codevira 1.7.1__tar.gz → 2.0.0rc1__tar.gz

{codevira-1.7.1 → codevira-2.0.0rc1}/CHANGELOG.md

@@ -11,6 +11,400 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Planned for v1.9
+
+- **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
+
+Three internal improvements that make the memory we already capture **sharper**,
+without making it heavier. Zero new MCP tools. Zero new tables. The public API
+shape changes only one thing: `get_session_context()` gains a `focus_source`
+field (~10 tokens, additive, backwards-compatible).
+
+The problem this release solves:
+- `get_session_context()` returned the 3 newest decisions by timestamp —
+  regardless of whether they had anything to do with the current task.
+- `search_decisions()` ordered purely by recency — a `file_path` match
+  was no better than a match buried in an unrelated session summary.
+- `log_session()` inserted every decision unconditionally — a day of
+  iterative agent work logged the same intent 5+ times.
+
+### Fixed
+
+- **MCP `serverInfo.version` reported the MCP library version, not codevira's**
+  (pre-existing bug, surfaced during v1.8 install verification on Python
+  3.13). `Server("codevira")` was constructed without a `version=` argument,
+  so the framework defaulted to its own pip-package version (e.g. `1.27.0`)
+  in the JSON-RPC `initialize` handshake response. Clients use this field
+  for telemetry and version gating, so the wrong value misled them.
+  One-line fix: `Server("codevira", version=__version__)`.
+- **`get_session_context()` read the wrong dict key** (pre-existing bug).
+  `list_open_changesets()` returns `{"open_changesets": [...], ...}`, but
+  `get_session_context` looked for `"changesets"`. The `open_changesets`
+  field in the session-context response was **always empty** in production.
+  Tests didn't catch it because mocks used the same wrong key.
+
+- **`GlobalDB` concurrent-open race condition** (pre-existing bug — latent
+  since v1.6's centralized storage introduced shared `~/.codevira/global.db`).
+  `PRAGMA journal_mode=WAL` requires an exclusive lock and — unlike normal
+  SQL — does NOT honour `sqlite3`'s `busy_timeout`. When multiple processes
+  or threads opened the same fresh database concurrently (e.g. several
+  projects' first-ever `codevira register` running in parallel, or the
+  `global_sync` background export racing the MCP server thread), one or
+  more would raise `OperationalError('database is locked')` and silently
+  fail to register. The test `test_concurrent_access_from_threads` was
+  flaky at 60% failure rate, hinting at the real issue. Fixed with WAL-
+  enable retry loop + short-circuit when WAL is already active. Stability
+  verified at 20/20 passes across 20 test runs.
+
+### Changed
+
+- **Focus-weighted `recent_decisions` in `get_session_context()`**. Instead
+  of chronological "newest 3", decisions are now ranked by what the agent
+  is currently focused on:
+  1. Open changeset with `files_pending` → focus = first file path of the
+     most-recently-created changeset.
+  2. Strong `current_phase.next_action` signal → focus = extracted keywords
+     (rejects short or stop-list-only actions like "continue work").
+  3. Otherwise → chronological fallback (unchanged behaviour).
+  If focus returns fewer than 3, the list pads with `get_recent_decisions()`.
+  New response field `focus_source` (`"open_changeset:<id>"`, `"next_action"`,
+  or `null`) lets the agent see *why* it got these decisions.
+
+- **Smarter `search_decisions()` ranking**. SQL now adds `file_path` to both
+  the WHERE clause and a CASE-based ORDER BY:
+  `file_path match (0) > decision text (1) > context (2) > summary-only (3)`,
+  then newest first within each tier. Searching for `"src/auth.py"` now
+  surfaces file-path matches even when the decision text doesn't mention
+  the path.
+
+- **Decision dedup on write**. `log_session()` now skips a new decision
+  if it has a `file_path` and its token-set overlaps ≥ 80% with any of
+  the 5 most recent decisions for that same file. The session row is
+  always created; only redundant *decisions* are dropped. Short
+  decisions (< 3 tokens) and decisions without `file_path` are always
+  inserted.
+
+### Added
+
+- `focus_source` field on `get_session_context()` response (≈10 tokens).
+- `mcp_server.tools.learning._infer_focus()` — pure helper, module-private.
+- `indexer.sqlite_graph._is_duplicate()` — pure token-overlap helper,
+  module-private, independently testable.
+- **`codevira configure`** — new CLI subcommand. Scans your project
+  (gitignore-aware via existing `discover_source_files()`), shows discovered
+  directories and file extensions with counts, lets you pick via a numbered-
+  list prompt, writes the choices back to `.codevira/config.yaml`, and offers
+  to rebuild the index. Non-interactive:
+  `codevira configure --dirs src,lib --extensions .py,.ts --no-reindex`.
+  Solves the AgentStore-style "0 chunks indexed" case where
+  `auto_detect_project()` mis-guesses a monorepo layout.
+  When `config.yaml` is missing (normal state after `codevira register` but
+  before the first MCP tool call), `configure` auto-bootstraps it in full
+  parity with `auto_init`'s first-init path: writes `metadata.json` (rename-
+  resilient lookup via `git_remote`) and registers the project in
+  `~/.codevira/global.db` for cross-project intelligence. Missing these on
+  earlier drafts would have left the project invisible to rename-resilient
+  path lookup and absent from global memory until the first session log.
+- **Zero-chunks safety hint at index time.** When `codevira index --full` or
+  `codevira index` (incremental, project-wide) matches no files against your
+  `watched_dirs` + `file_extensions`, the indexer now prints a one-line
+  remedy pointing at `codevira configure`. Output goes to **stderr** (not
+  stdout) so the hint never leaks into the MCP JSON-RPC wire when
+  `start_background_full_index` runs during auto_init inside the MCP server
+  process. Also logged at WARNING level so background invocations
+  (auto-init, launchd watcher) leave a trace regardless of terminal
+  capture. Does NOT fire for caller-scoped incremental runs (e.g. the
+  `refresh_index` MCP tool targeting a specific file) — zero matches there
+  is the caller's choice, not a misconfiguration.
+- `codevira register` success banner now nudges toward `codevira configure`.
+
+### Internal
+
+- 87 new tests:
+  - 34 for v1.8 memory sharpening (focus inference priority rules, ranking
+    tier ordering, dedup threshold behaviour, session-row-always-created
+    invariant, NULL file_path fallback, session_id filtering + new ranking SQL)
+  - 43 for `codevira configure` (scan_project with centralized-mode
+    decoupling + skip_dirs honoring, multi-select prompt incl. non-TTY
+    fallback + Ctrl+C clean-abort, config writer preserve/dedupe/idempotency,
+    orchestrator edge cases incl. bootstrap on missing config, dry-run disk
+    safety, corrupt-YAML handling, empty-extensions safety, PermissionError
+    friendly wrapper, `--dirs`/`--extensions` normalization)
+  - 10 for the zero-chunks hint (unit tests of the helper proving it writes
+    to stderr not stdout + integration tests proving it fires ONLY for full
+    or project-wide-incremental scans, not caller-scoped or normal "no files
+    changed")
+- Full test suite: **1,398 passing, 0 deterministic failures** (up from
+  1,306 at v1.7.1 → +92). The two "pre-existing watchdog failures" that
+  haunted earlier drafts of this CHANGELOG turned out to be an environment
+  issue in a single dev machine (system Python 3.9 without `watchdog`);
+  the pipx-installed v1.8.0 environment has all required deps. The one
+  pre-existing flaky test (`test_concurrent_access_from_threads`) is now
+  fixed by the `GlobalDB` WAL-enable retry loop described above.
+
+### Verified environments
+
+- **macOS (APFS)** + Python 3.9 system + Python 3.11 pipx: full regression
+  passes; all interactive + non-interactive flows manually verified on three
+  real projects (AgentStore, UDAP, ToolsConnector).
+- **Cross-process + thread concurrency**: stress-tested (12 threads × 20
+  writes, 8 subprocesses × 25 writes, 100 concurrent-read/write cycles) —
+  0 errors, 0 data loss.
+
+### Unverified environments / known gaps (candidates for v1.8.1 or v1.9)
+
+- **Windows**: `os.replace` atomicity weakens when the destination is open
+  by another process. If a Windows user has Claude Code reading
+  `config.yaml` at the moment `codevira configure` writes it, the write
+  may fail with `PermissionError`. Pre-existing risk; v1.8 does not fix
+  and does not regress. Windows smoke-testing is a v1.9 scope item.
+- **Network filesystems (NFS, SMB)**: atomic-replace guarantees are weaker
+  on network FS. Unlikely in solo-dev environments (codevira's target);
+  possible in enterprise setups.
+- **Python 3.10, 3.12**: The APIs `codevira configure` uses are stable
+  across 3.10+. Syntax-verified against 3.10+. **Python 3.13.7
+  empirically verified** during v1.8 install validation (full pipx
+  install + MCP handshake working). 3.10 and 3.12 are syntax-verified
+  only. CI on all Python versions is a v1.8.x task.
+- **Case-insensitive filesystem slugs**: On macOS APFS (default), paths
+  differing only in case (`~/Documents` vs `~/documents`) produce
+  different slugs for the same physical directory, creating split state.
+  Pre-existing since v1.5 — fixing requires a migration step for existing
+  users and is scoped to v1.9.
+- **Interactive TTY automated coverage**: The interactive prompt flow is
+  tested via mocked stdin + `sys.stdin.isatty`. A real terminal session
+  was manually verified during development; automated TTY testing (via
+  pexpect or similar) is a v1.8.x nice-to-have.
+- **MCP client post-upgrade reload**: `codevira register` writes config;
+  each MCP client (Claude Code, Cursor, Windsurf, Antigravity, Claude
+  Desktop) needs to reload to see changes. Verified for Claude Code.
+  Other clients may have edge cases that surface post-release.
+
+### Known test flake (NOT v1.8; pre-existing)
+
+- `test_chunk_error_continues_to_next_file` fails ~3/10 times in the full
+  suite on Python 3.9 (system) due to a chromadb+pydantic version
+  incompatibility raising `TypeError` during `import chromadb`, which
+  `_check_search_deps()` doesn't catch (it only catches `ImportError`).
+  **Not introduced by v1.8 and not touched by v1.8 code paths** — verified
+  by measuring the same 3/10 flake rate on clean v1.7.1. v1.8 deliberately
+  does not widen the exception catch because it would silently mask real
+  dep issues; a proper fix belongs in a targeted follow-up PR with its own
+  test coverage. Does not affect production users — the condition requires
+  a specific dev environment (Py 3.9 + mismatched chromadb/pydantic).
+- Regression guards added by the binocular review pass:
+  - `test_centralized_mode_data_dir_and_project_root_decoupled` — catches
+    the production bug where `data_dir.parent` was used where
+    `get_project_root()` was required (centralized mode v1.6+).
+  - `test_bootstraps_config_when_missing` — catches the workflow where
+    `codevira register` was run but config.yaml hasn't been written yet
+    (auto_init hadn't fired because no MCP tool call had happened).
+  - `test_bootstrap_respects_dry_run` — catches bootstrap writing disk
+    during `--dry-run`.
+  - `test_fires_on_stderr_when_not_quiet` — catches zero-chunks hint
+    leaking to stdout, which would corrupt the MCP JSON-RPC wire in stdio
+    mode.
+  - `test_empty_extensions_non_interactive_errors_exit_2` — catches
+    `--extensions ""` being silently accepted, which would write an empty
+    `file_extensions: []` and re-create the zero-chunks bug.
+  - `test_ctrl_c_in_prompt_returns_exit_0` — catches KeyboardInterrupt
+    propagating a traceback to the user.
+  - `test_permission_error_on_write_exits_1` — catches PermissionError /
+    OSError propagating a traceback when config.yaml isn't writable.
+  - `test_honors_user_skip_dirs_from_config` — catches scan_project
+    ignoring the user's explicit skip_dirs in config.yaml.
+
+### Known limitations
+
+- A running file-watcher or live MCP server session won't pick up config
+  changes until it restarts (the watcher snapshots `watched_dirs` at boot).
+  Restart your AI tool after `codevira configure` to apply changes.
+- `yaml.safe_dump` doesn't preserve comments in `config.yaml`. First-time
+  configs are auto-generated and have no comments; users who hand-edited
+  may see formatting normalized after `codevira configure` rewrites the file.
+
+### Unchanged (intentionally)
+
+- No new MCP tools. No new tables. No schema migration.
+- `search_decisions()` method signature unchanged.
+- `log_session()` method signature unchanged.
+- `get_session_context()` keys are additive — no removals.
+- `auto_init.py`, `detect.py`, `gitignore.py`, and `metadata.json` writer
+  untouched; `codevira configure` reuses all existing detection machinery.
+
 ---
 
 ## [1.7.1] — 2026-04-22 — Search Timeout Fix & Version Display

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: codevira
-Version: 1.7.1
+Version: 2.0.0rc1
 Summary: Persistent adaptive memory for AI coding agents — MCP server with context graph, semantic search, adaptive learning, roadmap tracking, and cross-tool continuity.
 Author-email: Sachin Shelke <sachin.worldnet@gmail.com>
 License: MIT
@@ -41,10 +41,11 @@ 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.7.1-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.
@@ -73,6 +74,43 @@ 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:
@@ -117,13 +155,29 @@ 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. Register with your AI tools
+### 2. Set up every AI tool you have
 
 ```bash
-codevira register
+codevira setup
 ```
 
-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.
+This one-prompt v2.0 command:
+- Detects every AI tool installed on your machine (Claude Code, Cursor, Windsurf, Antigravity, Codex CLI, GitHub Copilot, Claude Desktop, Continue, Aider, Roo Code, Cline)
+- Writes per-IDE nudge files so each tool knows codevira exists (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/codevira.mdc`, `.windsurfrules`, `GEMINI.md`, `.github/copilot-instructions.md`)
+- Installs Claude Code lifecycle hooks (SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop) — turns codevira from passive memory into the **AI guardian** described above
+- Injects MCP server config into each detected tool
+
+Idempotent — re-run any time to re-sync. Use `--dry-run` to preview, `--ide=claude` to limit to one tool.
+
+> **Migrating from v1.x?** If you've been using `codevira register`, switch to `codevira setup` — register only injects MCP server config; setup ALSO writes the nudge files + lifecycle hooks that power the v2.0 hero capabilities.
+
+### 2.5 Verify the install (optional but recommended)
+
+```bash
+codevira doctor
+```
+
+Runs 9 health checks, prints `✓` / `⚠` / `✗` per check, and shows the **exact command** to fix anything that's not green. Read-only — never modifies anything.
 
 ### 3. Start using
 
@@ -142,6 +196,24 @@ Ask your AI agent to call `get_roadmap()` — it should return your current phas
 
 > **Note:** Restart your AI tool after running `codevira register` to pick up the new MCP config.
 
+### Customizing what's indexed
+
+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.
+
+```bash
+cd your-project
+codevira configure
+```
+
+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.
+
+**Non-interactive** (useful in scripts or CI):
+```bash
+codevira configure --dirs src,packages,apps --extensions .py,.ts,.tsx --no-reindex
+```
+
+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)
 
 Codevira supports two transports. Use the right one for your client:
@@ -558,7 +630,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.
 
 ---
 
@@ -570,6 +663,8 @@ Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the full
 **Requesting a feature?** [Open a feature request](https://github.com/sachinshelke/codevira/issues/new?template=feature_request.md)
 **Found a security issue?** Read [SECURITY.md](SECURITY.md) — please don't use public issues for vulnerabilities.
 
+**Testing a release candidate locally?** See [docs/local-pypi-https.md](docs/local-pypi-https.md) for setting up a Docker-based HTTPS PyPI registry that mirrors the real PyPI install flow without touching public PyPI.
+
 ---
 
 ## FAQ
@@ -580,6 +675,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.