codevira 1.8.0__tar.gz → 2.0.0__tar.gz

{codevira-1.8.0 → codevira-2.0.0}/CHANGELOG.md

@@ -11,6 +11,297 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Planned for v2.1
+
+See [ROADMAP.md](ROADMAP.md#-v21--honest-known-limitations-from-the-rc5-audit-2026-05-13).
+
+- **Multi-language `get_signature` / `get_code`** — wire tree-sitter (already
+  used for graph indexing) into these tools so non-Python projects stop
+  getting "Python-only by design".
+- **`record_decisions_batch` API** — compress 50× ~800 B per-call overhead
+  into one round-trip.
+- **CLI naming clarity** — pick a canonical hierarchy among `init` / `setup` /
+  `register` / `configure`; add a `codevira inspect` umbrella; deprecate one
+  of `--project-dir` (global) / `--project PATH` (per-subcommand) on a
+  v2.1 → v2.2 cycle.
+
+---
+
+## [2.0.0] — 2026-05-14 — First public 2.0 release
+
+The 2.0 release moves codevira from "memory layer for one developer in one IDE" to
+"active guardian for every AI coding tool you use, on every project, on your local
+machine." Five internal iterations (rc1..rc5 in dev tags) plus a same-day public
+release-candidate cycle (`2.0.0rc1`) of dogfood + audit + product-credibility
+work consolidate into 2.0.0. **Full changelog: [RELEASE_NOTES.md](RELEASE_NOTES.md).**
+
+### Added
+
+- **All 10 hero policies** — active guardian engine intercepts every AI tool
+  call (Edit, Write, prompt submit, session start) and routes through
+  registered policies (Decision Lock, Anti-Regression, Scope Contract,
+  Blast-Radius Veto, Cross-Session Consistency, Token Budget, Live Style
+  Enforcement, Decision Replay, Proactive Intent Inference, AI Promotion
+  Score).
+- **`codevira setup`** — one-prompt installer that detects every AI tool
+  on the machine (Claude Code, Cursor, Windsurf, Antigravity, OpenAI Codex,
+  GitHub Copilot, Continue.dev, Aider) and configures all of them at once.
+- **`codevira projects`** — canonical inventory with `tracked / ghost /
+  orphan / stale` classification (`--json` for scripting; `--ghosts-only`
+  pairs with `clean --ghosts`).
+- **`codevira hooks list / uninstall`** — admin commands for Claude Code
+  lifecycle hooks; surgical install + clean removal.
+- **`codevira clean --ghosts`** — surgical removal of incomplete project
+  data dirs without touching tracked projects.
+- **`codevira init --single-language`** — opt-out flag for the new
+  index-everything default.
+- **`codevira engine` subcommand** — internal hook dispatcher; surfaces in
+  `--help` so the lifecycle hooks can call it.
+- **4 new doctor checks** — `claude_mcp_visibility`, `codeindex_freshness`,
+  `semantic_search_health`, `ghost_projects` (total 14 per run).
+- **Per-project config opt-out for cross-session injection** —
+  `.codevira/config.yaml: project: { cross_session_mode: off }` disables
+  the per-prompt context block without touching env vars.
+
+### Changed
+
+- **`codevira init` default** — indexes every common source/config/docs
+  extension (~75 total: `.py`, `.ts`, `.go`, `.yaml`, `.toml`, `.md`,
+  `.html`, `.sql`, `.proto`, …) instead of narrowing to one language.
+- **`codevira agents` default** — renders nudge files for **detected** IDEs
+  only; `--ide=all` opt-in for the legacy "render for every supported IDE"
+  behavior.
+- **`codevira doctor`** — now genuinely read-only; snapshots the projects
+  dir at entry and removes any new dirs at exit.
+- **`search_codebase`** — graceful structural fallback (filename + symbol
+  substring) when the semantic index is unavailable, with the correct
+  `fix_command` instead of a misleading "reinstall codevira" hint.
+- **`get_node` / `get_impact` / `query_graph`** — three-case error
+  differentiation: "no graph DB" / "graph empty" / "file not in populated
+  graph", each with its own `fix_command`.
+- **`get_decision_confidence`** — exposes `decisions_in_db_total` and
+  `decisions_eligible_for_outcomes` plus a four-state interpretation so
+  users understand WHY their `total_decisions` may be zero. Outcome
+  tracker also classifies file-less decisions via mention-extraction.
+- **Playbooks** — project-scoped first
+  (`<data_dir>/playbooks/` or `<project>/.codevira/playbooks/`); bundled
+  Python defaults are skipped with a clear warning when project language
+  ≠ Python.
+- **`register_project`** uses `ON CONFLICT … COALESCE(excluded.git_remote,
+  projects.git_remote)` — subsequent registrations can't silently clear
+  the `git_remote` column.
+- **Auto-init self-heal** runs SYNCHRONOUSLY in the calling thread of every
+  CLI invocation — daemon thread death no longer leaves ghost data dirs.
+- **Default install** includes ChromaDB + sentence-transformers (no
+  `[search]` extra needed for semantic search).
+- **README "92% reduction" claim** qualified with honest scope, per-prompt
+  cost, and amortization curve.
+- **`register` deprecation** now names the removal version (v2.1).
+
+### Fixed
+
+- macOS Apple Silicon **fork-safety segfault on first `codevira index`**
+  (auto-applied at indexer import).
+- **Setup interactive prompt** silent-fail on unexpected input — replaced
+  with a shared `_prompts.confirm` helper that retries, flushes stdout,
+  and handles `KeyboardInterrupt` cleanly.
+- Three **`status --global` UI typos** that always rendered 0/0/0
+  regardless of actual `global.db` state.
+- Four **FK race conditions** in the watcher pipeline.
+- **Python `None` leaked into argparse choices** for `agents --ide` and
+  `budget` positional.
+- Several **silent argument clamps** in `replay --since`, `insights --since`,
+  and `insights --top` now print visible warnings.
+
+### Tests
+
+- 2395 / 2395 passing (deterministic).
+- ~1091 net new tests since v1.8.0 (mostly from the v2.0 hero policies +
+  audit-driven regression coverage).
+
+### Note on internal v1.8.1 + 2.0.0rc1
+
+A v1.8.1 production hotfix existed in dev tags but was never published to
+PyPI; its fixes are folded into 2.0.0. A `2.0.0rc1` was briefly published
+on PyPI (2026-05-14) as a same-day public release candidate; the code is
+identical to 2.0.0. Anyone who installed `codevira==2.0.0rc1` can
+`pipx install --upgrade codevira` to move to 2.0.0 final.
+
+---
+
+## [Original v1.9 plan, deferred]
+
+- **Interactive checkbox UI for `codevira configure`**. The current
+  prompt asks users to type comma-separated indices ("1,3,5") into a
+  numbered list — fine for 3–5 items, awkward for 15+. v1.9 will add
+  arrow-key navigation + space-to-toggle multi-select, matching the
+  UX of `npm create vite`, `gh repo create`, etc.
+
+  **Design (opt-in dependency):**
+  - Default install (`pip install codevira`) keeps the current numbered
+    prompt — zero new dependencies, zero new failure modes.
+  - `pip install codevira[ui]` pulls `questionary` (~3 MB). When
+    importable AND `sys.stdin.isatty()` AND `os.environ.get("TERM")
+    != "dumb"`, `prompt_multi_select` switches to the checkbox UI.
+  - `--dirs` and `--extensions` flags continue to work for both paths
+    (CI / scripts / non-interactive use).
+
+  **Why deferred from v1.8.1:** v1.8.1 is a pure crash hotfix; mixing
+  in a UX feature would slow the release and complicate testing. The
+  numbered prompt has shipped since v1.8.0 and works fine — this is
+  polish, not a fix.
+
+  **Implementation notes for whoever picks this up:**
+  - Site: `mcp_server/cli_configure.py:prompt_multi_select` (line ~176)
+  - Add `[ui]` extra in `pyproject.toml` with `questionary>=2.0`
+  - TTY detection already exists (`NonInteractiveError` raised on
+    `not sys.stdin.isatty()`); extend it to also branch on
+    questionary availability
+  - Test surface: split into two test classes — one mocks `input()`
+    (current behavior), one mocks `questionary.checkbox()`. Skip the
+    questionary tests when not installed.
+  - Accessibility: keep the numbered prompt for screen-reader users;
+    document `CODEVIRA_DISABLE_TUI=1` env var as the override.
+  - No schema changes, no public-API changes.
+
+### Other v1.9 candidates (no design yet)
+
+- Watcher restart circuit breaker (deferred from v1.8.1 — see "Out of
+  scope" below).
+- Refactor `_enable_wal_with_retry` into a shared `indexer/_sqlite_util.py`
+  (deferred from v1.8.1).
+- Watcher hot-reload of `config.yaml` on disk changes.
+- `crash_logger` size cap or rotation (currently grows unbounded).
+
+---
+
+## [1.8.1] — 2026-05-02 — Production Hotfix from Real-World Crash Logs
+
+Pure bug-fix release. No new features, no schema changes, no public-API
+changes. Motivated by a real production failure on the maintainer's
+machine: **43 crashes in 70 minutes** logged by `crash_logger` between
+07:37 and 08:47 on 2026-04-24, all under
+`WHERE: background watcher: incremental reindex`.
+
+Breakdown:
+- **41 × `InterruptedError` (EINTR, errno 4)** in
+  `_get_changed_files`'s rglob walk, all walking
+  `~/Library/Group Containers/...` (WhatsApp, Office, etc.) and
+  `~/Library/Containers/...` (TextEdit, mediaanalysisd, …).
+- **2 × `OperationalError("database is locked")`** in
+  `SQLiteGraph.add_symbol` and `remove_symbols_for_file`.
+
+Root cause: a rogue project data dir with
+`metadata.json.original_path = "/Users/sachin"` (the user's `$HOME`).
+`auto_detect_project` saw `Library`, `Downloads`, `Documents`, `go` as
+"subdirs", and the watcher then walked huge unrelated trees. v1.8.0's
+bootstrap (`cmd_configure`, `auto_init`) didn't refuse `$HOME`, and
+neither did `cmd_init`.
+
+### Fixed
+
+- **Refuse `$HOME` and system top-levels as a project root** (the
+  critical fix — eliminates 41 of the 43 production crashes by
+  preventing the rogue project from forming). New helper
+  `mcp_server.paths.is_invalid_project_root()` rejects `$HOME`, `/`,
+  `/Users`, `/home`, `/tmp`, `/private/tmp`, `/var`, `/private/var`,
+  `/etc`, `/opt` (plus the macOS-resolved `/private/etc` and
+  `/System/Volumes/Data/home` forms). Wired into TEN distinct sites
+  covering every state-creating path the codebase exposes:
+  - **CLI entry points (6):** `cmd_configure`, `cmd_init`, `cmd_index`,
+    `cmd_register`, `cmd_serve` (refuses both regular serve AND
+    `--install-service`; `--uninstall-service` is exempt so users can
+    always remove old launchd plists), `auto_init._run_background_init`.
+  - **MCP server entry points (2):** `mcp_server.server.main()` (stdio
+    transport) and `mcp_server.http_server.run_http_server()` (HTTP
+    transport). Both are reachable directly via `python -m`, not just
+    through the CLI.
+  - **Direct module entry (1):** `indexer.index_codebase.__main__`
+    (`python -m indexer.index_codebase --full | --watch | (default)`)
+    — this is a separate CLI surface from the `codevira` binary;
+    pre-revalidation it bypassed `cli.cmd_index`'s guard entirely.
+    `--status` is exempt (read-only, bails on missing graph.db).
+  - **Defense-in-depth (1):** `indexer.index_codebase.start_background_watcher`
+    refuses to start the watcher even if a programmatic caller bypasses
+    every entry-point guard above. Returns `None`; both `cmd_watch` and
+    `server.main` handle `None` correctly.
+
+  The `server.main()` and `run_http_server` guards are the most critical
+  — without them, a user upgrading from v1.8.0 *without* first running
+  `clean --orphans` would still hit the original crash mode: their
+  leftover rogue `config.yaml` would drive `start_background_watcher`
+  into walking `~/Library/Group Containers/...`, which is exactly where
+  the 41 production `InterruptedError` crashes came from. The
+  `start_background_watcher` defense-in-depth guard is a belt-and-braces
+  fallback — even if all entry-point guards regressed, the watcher
+  itself cannot start with an invalid project root.
+
+  `cmd_index`, `cmd_register`, `cmd_serve --install-service` close
+  defense-in-depth holes that pre-revalidation could have leaked state
+  on disk: silent dead-weight `mkdir` of
+  `~/.codevira/projects/<HOME_slug>/{graph,codeindex}/`, IDE configs
+  pinned to broken paths, and persistent launchd plists pointing at
+  `$HOME`. Pre-release revalidation across three rounds walked every
+  CLI sub-command, the stdio/HTTP server entry, the launchd
+  `--install-service` path, the `start_background_watcher` direct call
+  path, and the production-replay scenario (synthetic v1.8.0 leftover
+  rogue + `codevira` from `$HOME`). All paths refuse cleanly with zero
+  new crashes; legitimate projects untouched.
+
+  `auto_init` sets `_progress["status"] = "error"` so the MCP server
+  stops looping on retries.
+
+- **`SQLiteGraph` WAL with retry — port of the v1.8.0 GlobalDB fix**
+  (eliminates the 2 of 43 `database is locked` crashes). v1.8.0 fixed
+  the same race for `GlobalDB` after round 3 of binocular review;
+  `SQLiteGraph` was missed. `__init__` now opens with `timeout=30`,
+  enables WAL via the same retry loop pattern, and sets
+  `PRAGMA busy_timeout=30000` for subsequent writes.
+
+- **`_get_changed_files` and `cmd_full_rebuild` rglob loops tolerate
+  `OSError`** (defense-in-depth — even on legitimate projects,
+  transient `EINTR`, `PermissionError`, or "directory changed during
+  iteration" should not kill the whole reindex). Per-watch-dir scope
+  matches `watchdog.Observer`'s thread-per-watch model: the
+  microsecond-spaced parallel-thread crashes (3 within 6μs at
+  08:15:29 and 08:26:04 in the production log) confirm this is the
+  right granularity. `InterruptedError` is a subclass of `OSError`, so
+  the broader catch covers EINTR plus other transient walk failures.
+
+### Added
+
+- **`codevira clean --orphans`** — recovery path for users already hit
+  by the `$HOME`-bootstrap bug on v1.8.0. Walks
+  `~/.codevira/projects/*/metadata.json`; for each entry whose
+  `original_path` is rejected by `is_invalid_project_root()` OR no
+  longer exists on disk, removes the data dir and deletes the matching
+  row from `~/.codevira/global.db`. Reuses the existing `--dry-run`
+  and `-y/--yes` flags. Without this, affected users would need to
+  `rm -rf` and run raw sqlite by hand.
+
+- **Denylist macOS/Linux/cloud-sync user-data dirs in
+  `auto_detect_project`** (defense-in-depth). `_SKIP_DIRS` extended
+  with `Library`, `Downloads`, `Music`, `Movies`, `Pictures`,
+  `Desktop`, `Public`, `Applications`, `Videos`, `Templates`, plus
+  cloud-sync top-levels (`Dropbox`, `iCloud Drive`, `OneDrive`,
+  `Google Drive`, `Box`). Even if `is_invalid_project_root` somehow
+  misses (e.g. a user passes `--project-dir` to a `$HOME`-shaped
+  layout), these never show up in `watched_dirs`. A user who
+  legitimately has a project named e.g. `Library` can still pass
+  `codevira configure --dirs Library` to opt in.
+
+### Out of scope (deferred to v1.9)
+
+- **Watcher restart circuit breaker.** Crash log shows ~60s gaps
+  between EINTR crashes — no backoff. Adding a circuit breaker is real
+  design work; the rglob `OSError` tolerance closes the immediate
+  hole.
+- **Refactoring `_enable_wal_with_retry` to a shared util.** 25 lines
+  of duplication for one patch cycle is the right call; touching
+  `GlobalDB`'s tested-in-v1.8.0 code is higher risk.
+- **`crash_logger` size cap or rotation.** Log file is ~97KB now; will
+  grow unbounded over time. Out of scope for hotfix; flagged for v1.9.
+
 ---
 
 ## [1.8.0] — 2026-04-23 — Memory Sharpening + Config UX

{codevira-1.8.0/codevira.egg-info → codevira-2.0.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.2
 Name: codevira
-Version: 1.8.0
-Summary: Persistent adaptive memory for AI coding agents — MCP server with context graph, semantic search, adaptive learning, roadmap tracking, and cross-tool continuity.
+Version: 2.0.0
+Summary: Stop re-explaining your project to AI agents every session. Codevira gives Claude Code, Cursor, Windsurf, and Antigravity shared persistent memory of your codebase — locally, no signup, MIT-licensed. One install configures every AI tool.
 Author-email: Sachin Shelke <sachin.worldnet@gmail.com>
 License: MIT
 Project-URL: Homepage, https://github.com/sachinshelke/codevira
@@ -9,7 +9,7 @@ Project-URL: Repository, https://github.com/sachinshelke/codevira
 Project-URL: Issues, https://github.com/sachinshelke/codevira/issues
 Project-URL: Changelog, https://github.com/sachinshelke/codevira/blob/main/CHANGELOG.md
 Keywords: mcp,model-context-protocol,ai-agents,llm,developer-tools,claude,cursor,windsurf,code-intelligence,semantic-search,context-graph,chromadb,agentic,coding-assistant,knowledge-graph
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -41,15 +41,26 @@ Provides-Extra: all
 
 > **One memory layer for every AI coding tool you use.** Switch between Claude Code, Cursor, Windsurf, and Antigravity without losing context, decisions, or progress.
 
-[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![PyPI version](https://img.shields.io/pypi/v/codevira?color=orange)](https://pypi.org/project/codevira/)
+[![Python](https://img.shields.io/pypi/pyversions/codevira?color=blue)](https://pypi.org/project/codevira/)
+[![Downloads](https://static.pepy.tech/badge/codevira)](https://pepy.tech/project/codevira)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![MCP](https://img.shields.io/badge/protocol-MCP-purple)](https://modelcontextprotocol.io)
-[![Version](https://img.shields.io/badge/version-1.8.0-orange)](CHANGELOG.md)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)
 
 **Built for solo developers** working on local projects with AI agents. Codevira gives every AI tool you use access to the same persistent project memory — so you stop re-explaining your codebase every session, stop losing carefully-made decisions, and stop burning tokens on re-discovery.
 
-**Works with:** Claude Code · Claude Desktop · Cursor · Windsurf · Google Antigravity · any MCP-compatible AI tool
+**Works with:** Claude Code · Claude Desktop · Cursor · Windsurf · Google Antigravity · OpenAI Codex · GitHub Copilot · Continue.dev · Aider · any MCP-compatible AI tool
+
+---
+
+## What you get
+
+* 🧠 **One brain across every AI tool.** A decision you log in Claude Code shows up in Cursor. Style preferences learned in one session enforce in the next. No per-tool re-onboarding.
+* 🛡️ **Active guardrails, not passive notes.** Codevira intercepts every AI tool call (`Edit`, `Write`, prompt submit, session start). Decisions you mark `do_not_revert` block silent regressions. Out-of-scope edits get warned. The AI literally *cannot* undo your protected choices without surfacing the conflict to you first.
+* ⚡ **Zero-friction setup.** `pipx install codevira && codevira setup` — auto-detects every AI tool you have and configures all of them. No JSON to hand-edit, no per-IDE script, no team server to spin up.
+* 🔒 **Local-first, MIT-licensed.** Your decisions, code graph, and learned preferences live in `~/.codevira/` on your machine. No cloud, no account, no telemetry, no SaaS.
+* 📊 **Honest measurement.** `codevira insights` shows which past decisions held up vs got reverted across your real git history. `codevira budget` reports per-session AI token spend. You can audit what the memory layer is actually costing and earning.
 
 ---
 
@@ -73,13 +84,50 @@ Your AI agent reads the same 12 files every session before doing any actual work
 
 ---
 
+## What's new in v2.0
+
+> 30-second demo: **[docs/demo/codevira-demo.mp4](docs/demo/codevira-demo.mp4)**
+
+v2.0 ships **10 AI-guardian capabilities** that work together as a single engine intercepting every AI tool call (Edit, Write, prompt submit, session start). They turn the persistent memory layer from passive (the AI looks things up) into active (codevira protects you when the AI is about to do something inconsistent with your project's history).
+
+| # | Hero | What it does | Trigger |
+|---|---|---|---|
+| 4 | **Blast-Radius Veto** | Block edits to files with N+ callers without explicit acknowledgment | before Edit/Write |
+| 1 | **Decision Lock** | Refuse edits to files marked `do_not_revert` | before Edit/Write |
+| 2 | **Anti-Regression Memory** | Block edits that re-introduce previously-fixed bugs | before Edit/Write |
+| 3 | **Scope Contract Lock** *(off-by-default)* | Refuse edits to files outside what your prompt asked for | prompt → enforce on Edit |
+| 5 | **Cross-Session Consistency** | Inject related past decisions when you submit a prompt | prompt submit |
+| 9 | **Proactive Intent Inference** | Pre-fetch fixes/decisions/blast-radius for the AI's first turn | prompt submit |
+| 6 | **Token Budget Live View** | Track AI token spend per session; `codevira budget` shows breakdown | every tool call |
+| 7 | **Live Style Enforcement** | Warn on snake_case/camelCase/quote-style violations vs your project's preferences | after Edit/Write |
+| 10 | **AI Promotion Score** | Auto-score decisions by outcome history; `codevira insights` weekly digest | session start |
+| 8 | **Decision Replay** | Browse decision timeline as terminal / markdown / HTML; MCP resource for Claude Desktop; `codevira replay` CLI | on demand |
+
+All 10 work behind the scenes by default. No new vocabulary to learn.
+
+### v2.0 CLI surface
+
+```text
+codevira setup        # one-prompt setup; replaces `register`
+codevira doctor       # health check with ✓/⚠/✗ + exact fix commands
+codevira agents       # regen per-IDE nudge files (CLAUDE.md, AGENTS.md, etc.)
+codevira hooks install  # install Claude Code lifecycle hooks
+codevira budget       # token-spend per session  (Hero 6)
+codevira insights     # stable / reverted decisions  (Hero 10)
+codevira replay       # browse decision timeline  (Hero 8)
+```
+
+For the honest "vs Mem0 / claude-mem / MemPalace" comparison see **[docs/vs-other-memory-tools.md](docs/vs-other-memory-tools.md)**.
+
+---
+
 ## How It Works
 
 Codevira is a [Model Context Protocol](https://modelcontextprotocol.io) server that runs locally and gives any AI tool a structured, queryable memory of your codebase:
 
 | Capability | What it means for you |
 |---|---|
-| **Zero-config setup** | `pipx install codevira && codevira register` — that's it. No prompts, no JSON editing. Auto-detects language, source dirs, and IDE configs |
+| **Zero-config setup** | `pipx install codevira && codevira setup` — that's it. No prompts, no JSON editing. Auto-detects every installed AI tool and configures all of them |
 | **Cross-tool continuity** | One `get_session_context()` call brings any AI agent up to speed in ~800 tokens — works identically in Claude Code, Cursor, Windsurf, Antigravity |
 | **Decision protection** | `do_not_revert` flags + searchable decision log stop AI agents from undoing past architectural choices |
 | **Context graph** | Every source file has a node: role, rules, dependencies, stability, blast radius. AI calls `get_node(path)` instead of re-reading the file |
@@ -103,73 +151,148 @@ The agent always asks for what it needs, in the size it needs.
 
 ---
 
-## Quick Start
-
-### 1. Install
+## Quick Start — three commands
 
 ```bash
-# Recommended: global install via pipx (isolated, works everywhere)
+# 1. Install
 pipx install codevira
 
-# Alternative: pip install
-pip install codevira
-```
-
-Installs the full toolkit (23 AI-facing MCP tools + 12 admin/CLI tools) out of the box. Semantic search downloads a ~90MB embedding model on first use.
+# 2. Connect every AI tool you have (idempotent — safe to re-run)
+codevira setup
 
-### 2. Register with your AI tools
+# 3. (Optional) Verify the install
+codevira doctor
+```
 
-```bash
-codevira register
+That's it. Open any project in your AI tool — codevira auto-initializes on
+the first MCP tool call. No per-project `codevira init` needed.
+
+**Try it.** Ask your AI agent: *"Use `get_session_context` to brief me on this project."*
+You'll get a structured project state in one tool call instead of the AI
+re-reading docs.
+
+### What `codevira setup` actually does
+
+The one command above replaces what used to take 5+ steps in v1.x:
+
+* **Detects every installed AI tool** — Claude Code, Claude Desktop, Cursor,
+  Windsurf, Antigravity, Codex CLI, GitHub Copilot, Continue.dev, Aider.
+* **Injects MCP server config** into each tool's config file (per-IDE schema
+  handled automatically — no JSON to hand-edit).
+* **Writes per-IDE nudge files** so each AI tool knows codevira exists:
+  `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/codevira.mdc`, `.windsurfrules`,
+  `GEMINI.md`, `.github/copilot-instructions.md` — only for IDEs you actually
+  have installed.
+* **Installs Claude Code lifecycle hooks** (`SessionStart`, `PreToolUse`,
+  `PostToolUse`, `UserPromptSubmit`, `Stop`) — turns codevira from passive
+  memory into the **active guardian** that intercepts every AI tool call.
+
+Use `--dry-run` to preview without writing anything. Use `--ide=claude` to
+limit to one tool. Use `-y` to skip the confirmation prompt (handy in scripts).
+
+### Already on v1.x?
+
+`pipx install --upgrade codevira` then `codevira setup`. Three default
+behaviors changed (all opt-out-able for legacy compatibility) — see
+[MIGRATING.md](MIGRATING.md) for the full upgrade guide. No data loss; your
+existing `~/.codevira/global.db` migrates safely.
+
+### What `codevira doctor` reports
+
+14 health checks in one run, each with a concrete `fix_command` for any
+WARN or FAIL. Read-only — never modifies anything. Use it whenever
+something feels off.
+
+```text
+$ codevira doctor
+Codevira health check
+────────────────────────────────────────────────────────────
+✓  python_version         Python 3.13 (≥ 3.10 required)
+✓  codevira_data_dir      /Users/you/.codevira exists and is writable
+✓  graph_db               graph.db has all 4 expected tables
+✓  global_db              /Users/you/.codevira/global.db opens cleanly
+✓  detected_ides          5 AI tool(s) detected
+✓  claude_mcp_visibility  codevira visible to Claude Code (✓ Connected)
+✓  ghost_projects         12 project(s) tracked — none are ghost dirs
+... (and 7 more checks)
+────────────────────────────────────────────────────────────
+summary: 14 pass · 0 warn · 0 fail
 ```
 
-This one-time global command injects Codevira's MCP config into all detected AI tools — Claude Code, Cursor, Windsurf, Claude Desktop, and Google Antigravity. Run it from anywhere; no project directory needed.
+### Daily-use commands you'll actually run
 
-### 3. Start using
+| Command | What it does |
+|---|---|
+| `codevira setup` | Re-sync IDE configs (after installing a new AI tool, etc.) |
+| `codevira doctor` | Health check |
+| `codevira projects` | List every project codevira knows about on this machine |
+| `codevira projects --ghosts-only` | Find half-initialised project dirs |
+| `codevira clean --ghosts` | Remove ghost dirs (preserves real ones) |
+| `codevira insights` | Stable + reverted decisions across past sessions |
+| `codevira replay` | Decisions timeline (terminal / markdown / html output) |
+| `codevira budget` | Per-session token usage |
+| `codevira hooks list` | Show installed Claude Code lifecycle hooks |
+
+Run `codevira --help` for the full subcommand list.
 
-Open any project in your AI tool. On the first MCP tool call, Codevira **auto-initializes**:
-- Detects language, source directories, and file extensions from project markers
-- Creates the context graph and roadmap
-- Installs a `post-commit` git hook for automatic reindexing
+### Customizing what's indexed
 
-No explicit `codevira init` needed — everything happens on demand.
+By default codevira indexes every common source / config / docs extension
+(~75 total: `.py`, `.ts`, `.go`, `.yaml`, `.md`, `.html`, `.sql`, `.proto`,
+…). For most projects this is what you want. To narrow or widen:
 
-> **Note:** `codevira init` is still available for explicit per-project setup with custom settings.
+```bash
+# Interactive picker — shows discovered dirs + extensions with file counts
+codevira configure
 
-### 4. Verify
+# Non-interactive (CI / scripts)
+codevira configure --dirs src,packages,apps --extensions .py,.ts --no-reindex
 
-Ask your AI agent to call `get_roadmap()` — it should return your current phase and next action.
+# Restore legacy single-language behavior on init
+codevira init --single-language
+```
 
-> **Note:** Restart your AI tool after running `codevira register` to pick up the new MCP config.
+After changing watched directories, **restart your AI tool** — running
+watchers snapshot the dir set at boot.
 
-### Customizing what's indexed
+### Reducing per-prompt context overhead
 
-Codevira tries to auto-detect your project's source layout, but monorepo or non-standard layouts sometimes slip through — you'll notice when `codevira index --full` reports `0 chunks indexed` and prints a hint pointing you here.
+Codevira's Cross-Session Consistency policy injects ~1 KB of relevant prior
+decisions into each `UserPromptSubmit` event. To disable per-project:
 
-```bash
-cd your-project
-codevira configure
+```yaml
+# .codevira/config.yaml
+project:
+  cross_session_mode: off          # disable injection entirely
+  cross_session_max_inject: 2      # OR keep it but cap at 2 entries (default 5)
 ```
 
-Scans your project (gitignore-aware), shows discovered directories and extensions with file counts, and lets you pick which to watch via a numbered-list prompt. It writes your choices back to `.codevira/config.yaml` and offers to rebuild the index.
+Or system-wide via env: `export CODEVIRA_CROSS_SESSION_MODE=off`.
+
+### Uninstall
+
+See [Uninstall / Reset](#uninstall--reset) below for the full set of
+options (`--all`, `--dry-run`, `--orphans`, `--ghosts`, `--legacy`).
+Quick path:
 
-**Non-interactive** (useful in scripts or CI):
 ```bash
-codevira configure --dirs src,packages,apps --extensions .py,.ts,.tsx --no-reindex
+codevira clean              # remove ~/.codevira/, IDE configs, services
+codevira hooks uninstall    # remove Claude Code lifecycle hook scripts
+pipx uninstall codevira     # remove the binary
 ```
 
-After changing watched directories, **restart your AI tool** — running watchers snapshot the dir set at boot.
+---
 
-### Manual config (only if auto-inject didn't detect your tool)
+## Manual installation — only if `codevira setup` doesn't detect your tool
 
 Codevira supports two transports. Use the right one for your client:
 
 | Client | Transport | Config file |
 |--------|-----------|-------------|
 | Claude Desktop (app) | stdio | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Claude Code (CLI) | stdio or HTTP | `.claude/settings.json` |
-| Cursor | stdio | `.cursor/mcp.json` |
-| Windsurf | stdio | `.windsurf/mcp.json` |
+| Claude Code (CLI) | stdio | `~/.claude.json` (user scope — `mcpServers` section) |
+| Cursor | stdio | `~/.cursor/mcp.json` |
+| Windsurf | stdio | `~/.codeium/windsurf/mcp_config.json` |
 | Google Antigravity | stdio | `~/.gemini/antigravity/mcp_config.json` |
 
 **Stdio transport** — Claude Desktop, Cursor, Windsurf (`.claude/settings.json` / `.cursor/mcp.json` / `.windsurf/mcp.json`):
@@ -199,7 +322,7 @@ Codevira supports two transports. Use the right one for your client:
 
 > Tip: find the full binary path with `which codevira`
 
-**HTTP/HTTPS transport** — *Preview in v1.7, single-project only.* The HTTP server binds to one project at startup and cannot switch contexts per request. **Multi-project HTTPS is planned for v1.8.** For multi-project work today, use stdio via `codevira register` (above).
+**HTTP/HTTPS transport** — *Preview only.* The HTTP server binds to one project at startup and cannot switch contexts per request. Multi-project HTTPS is still on the roadmap (see [ROADMAP.md](ROADMAP.md)). For multi-project work today, use stdio via `codevira setup` (above) — `setup` is the v2.0 successor to the now-deprecated `codevira register`.
 
 First start the HTTP server in a terminal:
 ```bash
@@ -340,7 +463,7 @@ codevira clean --dry-run    # preview what would be removed
 ```mermaid
 flowchart LR
 
-A["pipx install codevira"] --> B["codevira register"]
+A["pipx install codevira"] --> B["codevira setup"]
 B --> C["Open project in\nClaude Code / Cursor /\nWindsurf / Antigravity"]
 C --> D["First MCP tool call\ntriggers auto-init"]
 D --> E["✓ Config written\n✓ Graph built\n✓ Roadmap created\n✓ Ready"]
@@ -576,7 +699,28 @@ The `search_codebase` tool will be hidden from your AI agent; all other tools wo
 
 Want to understand the full story behind why this was built, the design decisions, what didn't work, and how it compares to other tools in the ecosystem?
 
-Read the full write-up: [How We Cut AI Coding Agent Token Usage by 92%](docs/how-i-built-persistent-memory-for-ai-agents.md)
+Read the full write-up: [How We Built Persistent Memory for AI Coding Agents](docs/how-i-built-persistent-memory-for-ai-agents.md)
+
+### Honest token-cost positioning
+
+The "92% reduction" number was measured for **structural orientation queries**
+(reading a `get_node` summary vs. reading the full source file) on a Python codebase
+with well-populated graph nodes. It's **not** a per-session, per-prompt, or
+per-conversation savings number — and the gross savings always need to be
+weighed against codevira's own per-prompt context-injection cost
+(~1 KB on every `UserPromptSubmit` when relevant prior decisions exist) and
+one-time setup cost (recording the decisions in the first place).
+
+For short-to-medium sessions, expect rough neutrality on token cost. The real
+wins are over **weeks of work on the same project** (cross-session decision
+queries amortize the setup cost) and in **automation and cross-tool continuity**
+(decisions recorded in Claude Code are visible in Cursor / Windsurf / next
+session without you doing anything).
+
+To minimise the per-prompt overhead, set
+`project: { cross_session_mode: off }` in `.codevira/config.yaml`, or export
+`CODEVIRA_CROSS_SESSION_MODE=off` in your shell. The injection is opt-out, not
+on-by-default-with-no-escape.
 
 ---
 
@@ -600,6 +744,14 @@ Common questions about setup, usage, architecture, and troubleshooting — see [
 
 See what's built, what's next, and the long-term vision — see [ROADMAP.md](ROADMAP.md).
 
+## Star History
+
+If Codevira saves you tokens or sanity, a star helps other developers find it. Tracking growth keeps me focused on what's working.
+
+<a href="https://star-history.com/#sachinshelke/codevira&Date">
+  <img src="https://api.star-history.com/svg?repos=sachinshelke/codevira&type=Date" alt="Star History Chart" width="600"/>
+</a>
+
 ## License
 
 MIT — free to use, modify, and distribute.