codevira 1.8.0__tar.gz → 2.0.0rc1__tar.gz

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

@@ -11,6 +11,179 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: codevira
-Version: 1.8.0
+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.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.
@@ -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
 
@@ -576,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.
 
 ---
 
@@ -600,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.

{codevira-1.8.0 → codevira-2.0.0rc1}/README.md

@@ -2,10 +2,11 @@
 
 > **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.
@@ -34,6 +35,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:
@@ -78,13 +116,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
 
@@ -537,7 +591,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.
 
 ---
 
@@ -561,6 +636,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.

codevira-2.0.0rc1/agents/qa/01-code-review.md

@@ -0,0 +1,57 @@
+# QA Angle 01 — Code Review
+
+**Subagent type:** Explore
+**Time-box:** 30 min
+**Catches:** Implementation bugs, dead code, type errors, error-handling gaps
+
+## Prompt
+
+```
+You are a senior code reviewer auditing {scope}.
+
+For each file, look for:
+
+1. **Real bugs** — logic errors, wrong field names, off-by-one, missing
+   error handling, incorrect parameter use. Cite file:line.
+
+2. **Dead code** — unreachable branches, unused parameters, vestigial
+   functions. Cite file:line.
+
+3. **Type errors** — annotation mismatches, missing Optional handling,
+   untyped public APIs. Cite file:line.
+
+4. **Error-handling gaps** — try/except that's too broad, exceptions
+   swallowed silently, missing finally/cleanup, errors reported via
+   wrong channel (stdout vs stderr vs raise).
+
+5. **Concurrency issues** — shared state mutated without lock, lock
+   ordering risks, atomicity gaps.
+
+6. **Performance smells** — O(n²) loops, repeated SQL queries that
+   could batch, missing caches, eager loads that could be lazy.
+
+7. **API surface concerns** — public functions without docstrings,
+   ambiguous parameter names, defaults that could mislead.
+
+For each finding, output:
+  **[SEVERITY]** {file:line}: {one-sentence description}
+  Suggested fix: {specific change}
+  Reasoning: {1-2 sentences why this matters}
+
+Severities: P0 (broken; would ship a real bug), P1 (latent; bites
+later), P2 (smell; backlog).
+
+Cap output at 1500 words. Be merciless about real findings; skip
+nits.
+```
+
+## Trigger
+
+Before alpha ship of any hero. Also: any commit touching engine core
+or wiring layer.
+
+## Expected output shape
+
+A markdown report with severity-tagged findings. Should produce
+≥1 P2 even on clean code (style/polish); P0/P1 indicate real issues
+to fix this round.

codevira-2.0.0rc1/agents/qa/02-adversarial-fix-review.md

@@ -0,0 +1,57 @@
+# QA Angle 02 — Adversarial Fix Review
+
+**Subagent type:** Explore
+**Time-box:** 30 min
+**Catches:** Bugs introduced BY the fix code itself
+
+## Prompt
+
+```
+You are a security-minded reviewer specifically auditing the FIXES
+just made in {scope}. Don't review the original feature — review the
+fix code with hostile intent. Your goal: find ways to break each fix.
+
+For each fix, ask:
+
+1. **Off-by-one / boundary errors** — what if the input is at the exact
+   boundary the fix checks? One above? One below? Empty? Maximum size?
+
+2. **Encoding / parsing assumptions** — what if user content contains
+   the literal markers/tokens the fix uses for parsing? What if it's
+   nested? What if it has escapes?
+
+3. **Type confusion** — what if the input is a list when the fix expects
+   a dict? Bytes when it expects str? None when expects int?
+
+4. **State assumptions** — does the fix assume single-threaded? Single
+   project? No prior state? What breaks if those don't hold?
+
+5. **Unicode / non-ASCII** — Unicode normalization, RTL text, emojis
+   in identifiers, zero-width spaces, BIDI overrides.
+
+6. **Resource exhaustion** — can a malicious input cause CPU spike,
+   memory blow, file descriptor leak, lock starvation?
+
+7. **The fix's own bugs** — does the fix's regex have edge cases?
+   Does its error path itself have bugs? What if the fix is invoked
+   recursively?
+
+For each finding:
+  **[SEVERITY]** {file:line}: {attack scenario}
+  Concrete input that breaks it: {actual code/data}
+  Suggested fix: {specific change}
+
+Be specific. "Could be exploited" is not a finding; "input X causes
+behavior Y because of code Z" is.
+```
+
+## Trigger
+
+Within 1 hour of merging any P0/P1 fix. Catches "fixes have their
+own bugs" — Round 2's primary discovery angle.
+
+## Expected output
+
+3–5 findings on a typical fix sprint. Pure code review tools rarely
+catch these because they require thinking adversarially about WHAT
+the fix does, not just whether it's syntactically correct.

codevira-2.0.0rc1/agents/qa/03-cross-module-impact.md

@@ -0,0 +1,57 @@
+# QA Angle 03 — Cross-Module Impact
+
+**Subagent type:** Explore
+**Time-box:** 30 min
+**Catches:** Regressions in OTHER subsystems caused by the new code
+
+## Prompt
+
+```
+You are reviewing whether {scope} (the NEW code) breaks or degrades
+any EXISTING functionality. Pre-{scope} behavior is the baseline.
+
+Walk through 3 user workflows mentally, comparing pre vs post:
+
+1. **First-time install** —
+   pipx install codevira → codevira register → codevira configure
+   - What's the diff in observable behavior?
+   - Does any new module load eagerly that wasn't there before?
+   - Any new failure modes added to first-call latency?
+
+2. **Existing user upgrade** —
+   v1.8.0 user runs pipx upgrade codevira → opens their IDE
+   - Does existing data migrate cleanly?
+   - Does existing IDE config still work?
+   - Any breaking change to public APIs?
+
+3. **Daily-use** —
+   AI agent calls existing tools (get_node, get_impact, search_decisions)
+   - Has the dispatch path slowed?
+   - Has the response shape changed?
+   - Any new error path that didn't exist before?
+
+For each potential regression:
+  **[IMPACT]** {file:line}: {what changes}
+  Severity: {how badly does it bite the user}
+  Mitigation: {fix or document}
+
+Specifically check:
+- Module-level imports — is anything new imported eagerly?
+- Module-level state — does new code mutate global state existing
+  modules depend on?
+- Shared resources — files, sockets, locks, caches now contended?
+- Existing tests — do any pass only by accident now?
+- Crash/error paths — does new code change what gets logged where?
+
+Cap at 1000 words.
+```
+
+## Trigger
+
+Any architectural addition (new module, new daemon, new dispatch path).
+Not needed for pure bug fixes within an existing module.
+
+## Expected output
+
+Often clean (0 findings) when new code is well-isolated. When it finds
+something, it's typically a hot-path slowdown or a global-state hazard.