feat: agent tool adapter, demo command, README overhaul

[Jacobcdsmith]

• Add src/kairos/tool.py — importable KAIROS tool adapter with inline source links (file://#L,C + vscode://file/)
• Add kairos demo command — cross-platform walkthrough, no bash required
• Add [all] install extra — one pip install for CLI + TUI + dev
• Restructure README with ASCII logo, compact quick-start, demo section
• Add :tutorial TUI command
• Bump to v0.1.1

These are additive enhancements on the existing v0.1.0 substrate. All existing services unchanged. README restructured for clarity. New agent tool adapter uses existing services through their typed API.

What does this change?

Checklist

• ruff format --check src tests passes
• ruff check src tests passes
• pyright passes with zero errors
• pytest passes, and I added/updated tests for the behavior change
• I did not add a dependency on model inference, remote services, or anything in the
  non-goals list
• I updated docs/cli.md and/or docs/architecture.md if this changes command behavior, schema, or provenance guarantees

How was this tested?

Summary by CodeRabbit

• New Features

  • Added an interactive setup wizard via kairos init --interactive.
  • Added the kairos demo walkthrough and consolidated kairos[all] installation option.
  • Added agent-tool integrations with structured results and clickable source links.
  • Added TUI tutorials, ingest commands, fuzzy search, tabs, and first-run guidance.

• Bug Fixes

  • Improved source-link handling and corrected workspace name display.

• Documentation

  • Reorganized the README and added release and session documentation.

• Style

  • Refreshed TUI visuals, status indicators, navigation, and evidence presentation.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cec82e72-7746-416f-b1fe-4f1befbc2e7e

📥 Commits

Reviewing files that changed from the base of the PR and between 63ad83f and 75ca324.

📒 Files selected for processing (24)

• CHANGELOG.md
• README.md
• docs/session-2026-07-20.md
• pyproject.toml
• src/kairos/cli/commands/demo.py
• src/kairos/cli/commands/init.py
• src/kairos/cli/main.py
• src/kairos/tool.py
• src/kairos/tui/app.py
• src/kairos/tui/commands.py
• src/kairos/tui/controller.py
• src/kairos/tui/screens/fuzzy_finder.py
• src/kairos/tui/screens/help.py
• src/kairos/tui/screens/main.py
• src/kairos/tui/screens/tutorial.py
• src/kairos/tui/styles/kairos.tcss
• src/kairos/tui/widgets/command_line.py
• src/kairos/tui/widgets/evidence_pane.py
• src/kairos/tui/widgets/explorer_pane.py
• src/kairos/tui/widgets/header_line.py
• src/kairos/tui/widgets/status_line.py
• src/kairos/tui/widgets/tab_bar.py
• src/kairos/tui/widgets/workspace_pane.py
• tests/tui/test_app.py

---

📝 Walkthrough

Walkthrough

The release adds an agent tool adapter with provenance links, a kairos demo command, interactive initialization, new TUI tutorial and fuzzy-finder workflows, refreshed TUI rendering and styling, consolidated installation extras, and updated release documentation.

Changes

KAIROS 0.1.1 feature release

Layer / File(s)	Summary
Agent adapter and service workflow src/kairos/tool.py	Adds structured agent-facing functions for initialization, ingestion, search, trace, source access, artifacts, coherence wells, and status reporting with provenance links.
CLI demo and interactive initialization src/kairos/cli/commands/demo.py, src/kairos/cli/commands/init.py, src/kairos/cli/main.py	Adds the fixture-based kairos demo walkthrough, registers it with Typer, and adds guided interactive workspace setup.
TUI commands, overlays, and startup flow src/kairos/tui/app.py, src/kairos/tui/controller.py, src/kairos/tui/commands.py, src/kairos/tui/screens/*	Adds ingest and tutorial commands, first-run ingestion and tutorial display, the tutorial overlay, and Ctrl+P artifact navigation.
TUI layout, rendering, and visual identity src/kairos/tui/screens/main.py, src/kairos/tui/widgets/*, src/kairos/tui/styles/kairos.tcss, tests/tui/test_app.py	Adds tab navigation and updates pane output, status indicators, glyph-based labels, overlay styling, and matching UI assertions.
Release metadata and documentation pyproject.toml, CHANGELOG.md, README.md, docs/session-2026-07-20.md	Bumps the version, adds the [all] extra, and documents the release features and revised setup flows.

Estimated code review effort: 5 (Critical) | ~90 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Operator
  participant KAIROS_CLI
  participant KAIROS_services
  participant Temporary_workspace
  Operator->>KAIROS_CLI: run kairos demo
  KAIROS_CLI->>Temporary_workspace: create workspace
  KAIROS_CLI->>KAIROS_services: initialize and ingest fixtures
  KAIROS_services-->>KAIROS_CLI: artifacts and diagnostics
  KAIROS_CLI->>KAIROS_services: search, show, trace, well, doctor
  KAIROS_services-->>KAIROS_CLI: walkthrough results
  KAIROS_CLI->>Temporary_workspace: remove workspace

Loading

Possibly related PRs

• Jacobcdsmith/kairos#1: Both PRs substantially revise the README hero, quick-start content, and TUI setup flow.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/readme-refresh

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}