codebase-intel 0.2.0__tar.gz → 0.3.0__tar.gz

codebase_intel-0.3.0/.codebase-intel/intent-journal/journal.jsonl

@@ -0,0 +1,6 @@
+{"actor": "cli", "entry_id": "c75235b94d883dc3", "op": "add_node", "payload": {"anchors": [{"content_hash": null, "file_path": "/home/phoenix/Documents/playground/codebase-intel/src/codebase_intel/intentgraph/journal.py", "line_range": null, "symbol_name": null}, {"content_hash": null, "file_path": "/home/phoenix/Documents/playground/codebase-intel/src/codebase_intel/intentgraph/store.py", "line_range": null, "symbol_name": null}], "author": "human", "confidence": 1.0, "created_at": "2026-07-17T17:57:17.836420Z", "decision_id": null, "level": 3, "metadata": {}, "node_id": "4dad4394663a3ee1", "session": null, "source": "capture", "status": "active", "supersede_reason": null, "superseded_by": null, "tags": ["architecture"], "title": "Journal-first intent storage", "trust": "confirmed", "updated_at": "2026-07-17T17:57:17.836424Z", "why": "SQLite index is derived and rebuildable; the JSONL journal committed to git is the source of truth — crash-safety, portability, merge-friendliness"}, "ts": "2026-07-17T17:57:17.836528Z"}
+{"actor": "cli", "entry_id": "c9bf75e21d4b0f5d", "op": "add_node", "payload": {"anchors": [{"content_hash": null, "file_path": "/home/phoenix/Documents/playground/codebase-intel/src/codebase_intel/intentgraph/gate.py", "line_range": null, "symbol_name": null}], "author": "human", "confidence": 1.0, "created_at": "2026-07-17T17:57:18.329111Z", "decision_id": null, "level": 3, "metadata": {}, "node_id": "6c89907cccd0d567", "session": null, "source": "capture", "status": "active", "supersede_reason": null, "superseded_by": null, "tags": ["capture"], "title": "Soft pre-commit gate by default", "trust": "confirmed", "updated_at": "2026-07-17T17:57:18.329116Z", "why": "A hard gate that blocks hotfixes gets uninstalled; soft mode warns and leaves a missing-why backlog node, hard mode is per-repo opt-in"}, "ts": "2026-07-17T17:57:18.329248Z"}
+{"actor": "cli", "entry_id": "19e25c83c221c1c2", "op": "add_node", "payload": {"anchors": [{"content_hash": null, "file_path": "/home/phoenix/Documents/playground/codebase-intel/src/codebase_intel/intentgraph/models.py", "line_range": null, "symbol_name": null}], "author": "human", "confidence": 1.0, "created_at": "2026-07-17T17:57:18.799017Z", "decision_id": null, "level": 3, "metadata": {}, "node_id": "bf8c7774b6ad86ef", "session": null, "source": "capture", "status": "active", "supersede_reason": null, "superseded_by": null, "tags": ["trust"], "title": "Trust tiers surfaced everywhere", "trust": "confirmed", "updated_at": "2026-07-17T17:57:18.799022Z", "why": "A hallucinated why is worse than none — mined/derived/asserted/confirmed tiers appear in every rendered answer so agents can weigh belief"}, "ts": "2026-07-17T17:57:18.799121Z"}
+{"actor": "honesty", "entry_id": "4345f164f5d49491", "op": "update_node", "payload": {"changes": {"anchors": [{"content_hash": "3c48a38271e70ea5", "file_path": "/home/phoenix/Documents/playground/codebase-intel/src/codebase_intel/intentgraph/journal.py", "line_range": null, "symbol_name": null}, {"content_hash": "4973465f9237c937", "file_path": "/home/phoenix/Documents/playground/codebase-intel/src/codebase_intel/intentgraph/store.py", "line_range": null, "symbol_name": null}]}, "node_id": "4dad4394663a3ee1"}, "ts": "2026-07-17T18:01:40.723012Z"}
+{"actor": "honesty", "entry_id": "7ed94ef9d40e7393", "op": "update_node", "payload": {"changes": {"anchors": [{"content_hash": "8358c0e41997c035", "file_path": "/home/phoenix/Documents/playground/codebase-intel/src/codebase_intel/intentgraph/gate.py", "line_range": null, "symbol_name": null}]}, "node_id": "6c89907cccd0d567"}, "ts": "2026-07-17T18:01:40.728759Z"}
+{"actor": "honesty", "entry_id": "92aad8529d3af2af", "op": "update_node", "payload": {"changes": {"anchors": [{"content_hash": "5b9e6e9b15bf8b83", "file_path": "/home/phoenix/Documents/playground/codebase-intel/src/codebase_intel/intentgraph/models.py", "line_range": null, "symbol_name": null}]}, "node_id": "bf8c7774b6ad86ef"}, "ts": "2026-07-17T18:01:40.732727Z"}

codebase_intel-0.3.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project runtime data (generated by codebase-intel itself)
+.codebase-intel/graph.db
+.codebase-intel/graph.db-wal
+.codebase-intel/graph.db-shm
+# Intent graph: the SQLite index is derived and rebuildable — the journal (JSONL) IS committed
+.codebase-intel/intent-graph.db
+.codebase-intel/intent-graph.db-wal
+.codebase-intel/intent-graph.db-shm
+# Analytics/benchmark/eval history — local telemetry, not project state
+.codebase-intel/analytics.db
+.codebase-intel/analytics.db-wal
+.codebase-intel/analytics.db-shm
+.codebase-intel/feedback.db
+.codebase-intel/feedback.db-wal
+.codebase-intel/feedback.db-shm
+
+# Environment
+.env
+.env.*

codebase_intel-0.3.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.3.0] — 2026-10-23
+
+### Added
+
+- **Intent graph (v2).** A multi-level "why" layer. `.codebase-intel/intent-journal/*.jsonl` is the
+  committed source of truth, and `intent-graph.db` is a rebuildable, git-ignored index. Nodes
+  carry trust tiers (`mined` → `derived` → `asserted` → `confirmed`) and four abstraction levels.
+- MCP tools: `bootstrap`, `check_precedent`, `record_why`, `get_intent`. The server now exposes 16 tools.
+- CLI: `why`, `intent-gate`, `install-hooks`, `intent-check`, `intent-confirm`, `intent-render`,
+  `intent-migrate`, `intent-rebuild`, `intent-eval`.
+- Pre-commit intent gate that warns (or blocks, with `intentgraph.gate_hard`) on structural
+  changes with no recorded why.
+- Anchor repair and re-anchoring when code moves; divergence, conflict and coverage reporting.
+- Human projection of the intent graph as HTML or Mermaid.
+- Safe, re-runnable migration of v1 decision records into the intent graph.
+- Eval harness (`intent-eval`) measuring token cost and retrieval correctness against the v1
+  baseline. Self-hosted results and caveats are in `docs/EVAL-RESULTS.md`.
+- Agent skill at `skills/codebase-intel/SKILL.md` that tells agents when to call the intent tools.
+
+### Changed
+
+- The package version now comes from `codebase_intel.__version__`, and `get_status` reports
+  it. Before this, three version strings had drifted apart: `0.1.0`, `0.2.0` and `0.2.0`.
+- Project URLs in the package metadata now point to the actual GitHub repository.
+
+### Fixed
+
+- Removed all pre-existing ruff and mypy errors in the v1 modules.
+
+## [0.2.0] — 2026-04-09
+
+### Added
+
+- Global workspace manager: one MCP server for every registered project (`serve --auto`).
+- Intent tracking (`set_intent`, `check_intent`, `list_intents`) with machine-verifiable
+  acceptance criteria.
+- Cross-repo awareness across 14 web frameworks in 10 languages.
+- Feedback loop and efficiency reporting.
+
+## [0.1.0]
+
+- Initial release: code graph, decision journal, quality contracts, drift detection, MCP server, CLI.
+
+[0.3.0]: https://github.com/a-mutharasu/codebase-intel/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/a-mutharasu/codebase-intel/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/a-mutharasu/codebase-intel/releases/tag/v0.1.0

{codebase_intel-0.2.0 → codebase_intel-0.3.0}/CLAUDE.md

@@ -56,6 +56,9 @@ src/codebase_intel/
 ├── contracts/     # models.py, parser.py, evaluator.py, registry.py
 ├── orchestrator/  # assembler.py, budget.py, scorer.py, conflict.py
 ├── drift/         # detector.py, reporter.py
+├── intentgraph/   # v2 core: models, journal (JSONL truth), store (SQLite index),
+│                  #   capture, classifier, gate, traversal, bootstrap, anchors,
+│                  #   render, migrate — the multi-level intent graph
 ├── workspace/     # manager.py, registry.py — global multi-project workspace
 ├── crossrepo/     # models.py, scanner.py, registry.py — cross-service deps
 ├── analytics/     # tracker.py, benchmark.py, feedback.py
@@ -64,6 +67,9 @@ src/codebase_intel/
 └── cli/           # main.py
 ```
 
+Outside `src/`: `skills/codebase-intel/SKILL.md` is the agent skill (portable frontmatter only:
+name, description, license, compatibility). `CHANGELOG.md` records releases.
+
 ## Key Commands
 - `ruff check src/ tests/` — Lint
 - `ruff format src/ tests/` — Format
@@ -81,7 +87,23 @@ src/codebase_intel/
 - Content hashing via xxhash for change detection
 - ISO 8601 for all timestamps, UTC timezone
 
+## Intent Graph (v2)
+- Journal-first: `.codebase-intel/intent-journal/*.jsonl` is committed source of truth;
+  `intent-graph.db` is a derived, rebuildable index (git-ignored)
+- Trust tiers: mined → derived → asserted (agent) → confirmed (human) — surfaced in every render
+- MCP tools: record_why, check_precedent, bootstrap, get_intent
+- CLI: why, intent-gate, install-hooks, intent-check, intent-confirm, intent-render,
+  intent-migrate, intent-rebuild, intent-eval
+- Degradation ladder everywhere: intent graph → code graph → raw files, never hard-fail
+- Eval harness (T-006): `codebase-intel intent-eval <repo...>` — token AND correctness
+  A/B (accuracy@1/@3, naive-vs-citation token reduction) vs the v1 baseline. See
+  docs/EVAL-RESULTS.md for methodology and this repo's self-hosted numbers.
+- See docs/V2-PLAN.md (requirements/design) and docs/TASK-LEDGER.md (state)
+
 ## Current Focus
-- Initial architecture build-out with comprehensive edge case handling
-- Core module implementation
-- MCP server interface design
+- v0.3.0 release prep (intent graph + agent skill) on `chore/release-0.3.0`; version is
+  single-sourced from `codebase_intel.__version__` via `[tool.hatch.version]`
+  (release = GitHub Release → `publish.yml` → PyPI)
+- v2 intent graph: Phases 0–5 + eval harness shipped (see TASK-LEDGER)
+- Next: eval harness needs 2–3 external production repos for a broader A/B (T-006
+  remains open for that), team layer depth, pre-existing coverage debt (T-008)

{codebase_intel-0.2.0 → codebase_intel-0.3.0}/CONTRIBUTING.md

@@ -5,7 +5,7 @@ Thanks for wanting to help. Here's how to get started.
 ## Setup
 
 ```bash
-git clone https://github.com/MutharasuArchunan13/codebase-intel.git
+git clone https://github.com/a-mutharasu/codebase-intel.git
 cd codebase-intel
 uv sync --dev          # or: pip install -e ".[dev]"
 ```

codebase_intel-0.3.0/HANDOFF.md

@@ -0,0 +1,104 @@
+# Handoff — codebase-intel v2 (Intent Graph)
+
+Last updated: 2026-07-18 · Branch: `main` · For the next session (human or agent)
+## Read this first
+
+1. This file (5 min) — orientation and where things stand
+2. `docs/V2-PLAN.md` — the requirements analysis and phased plan this work follows
+3. `docs/TASK-LEDGER.md` — the authoritative, up-to-date task state (source of truth,
+   supersedes anything below if they disagree)
+
+## What this is
+
+`codebase-intel` v1 gives AI agents structured code-graph context, a decision journal,
+and quality contracts. v2 (this work) adds an **intent graph**: a multi-level "why" layer
+captured at decision time, so agents traverse recorded reasoning instead of re-reading
+files and re-deciding things that were already decided. See `docs/V2-PLAN.md` for the
+full functional/non-functional requirements and the resilience design.
+
+## State right now
+
+All of v2 Phases 0–5 are built, tested, and merged to `main`. Plus a chore pass that
+eliminated all pre-existing v1 ruff/mypy debt. Concretely:
+
+| Phase | What | Status |
+|---|---|---|
+| 0 | Intent graph foundation — journal-first store (JSONL truth + rebuildable SQLite index), trust tiers, v1→v2 migration | done |
+| 1 | Capture loop — `record_why`, `check_precedent`, pre-commit gate, significance classifier | done |
+| 2 | Traversal + session bootstrap with a mandatory degradation ladder | done |
+| 3 | Honesty machinery — anchor repair/re-anchoring, staleness, conflicts, coverage | done |
+| 5 | Human projection (Mermaid/HTML render) + review promotion (asserted→confirmed) | done |
+| 4 (T-006) | Eval harness — token AND correctness A/B | **blocked**, see below |
+| — (T-008) | v1 lint/type/coverage debt | ruff+mypy done; coverage gate still open |
+
+913 tests passing, `ruff check`/`ruff format --check`/`mypy src/` all clean on `main`.
+
+### What's genuinely unfinished
+
+- **T-006 (eval harness) is blocked, not done.** The harness itself
+  (`analytics/eval.py`, CLI `codebase-intel intent-eval`) is code-complete and verified
+  end-to-end — it ran against this repo and produced real numbers
+  (`docs/EVAL-RESULTS.md`: 100% accuracy@1/@3, 99% token reduction, n=3 cases, self-hosted
+  only). The task's actual bar ("real repos," plural, vs v1 baseline) needs 2+ external
+  production repos. The CLI already accepts multiple paths
+  (`codebase-intel intent-eval repo-a repo-b repo-c`) — no more code is needed, just repos
+  to point it at. **This is the most concrete unblock a human can hand over.**
+- **T-008 (v1 coverage debt) is in-progress.** `ruff` (222→0) and `mypy` (33→0) errors are
+  fully fixed. The `pytest` 90% coverage gate still fails (~45% project-wide) because large
+  v1 modules have zero dedicated unit tests: `mcp/server.py` (~5%), `graph/query.py` (0%),
+  `intent/*.py` (0%), `crossrepo/*.py` (0%), `decisions/miner.py` (0%). This is a
+  substantially larger effort (writing tests for existing untested v1 code) than the
+  lint/type fixes were — treat it as its own project, not a quick follow-on. Until it's
+  addressed, run tests with `pytest --no-cov` or expect the coverage gate to fail even
+  though every test passes.
+
+## How to verify the repo is healthy
+
+```bash
+uv sync --extra dev
+uv run ruff check src/ tests/          # should be clean
+uv run ruff format --check src/ tests/ # should be clean
+uv run mypy src/                        # should be clean
+uv run pytest --no-cov -q               # 913 passed
+```
+
+## How to explore what v2 built
+
+```bash
+codebase-intel why "<title>" "<reason>" -f <file>   # record a why
+codebase-intel intent-gate                          # pre-commit gate (also installable: install-hooks)
+codebase-intel intent-check                         # anchor validation/repair report
+codebase-intel intent-render -f html -o out.html     # human-readable graph
+codebase-intel intent-eval <repo...>                 # token+correctness eval (T-006)
+```
+
+Or via MCP tools: `record_why`, `check_precedent`, `bootstrap`, `get_intent`.
+
+This repo dogfoods its own intent graph — `.codebase-intel/intent-journal/journal.jsonl`
+is committed and has real entries from this session's own work (see git history on that
+path). `docs/intent-graph.html` is a static render of it.
+
+## Working conventions this session used (carry these forward)
+
+- One feature branch per phase (`feature/v2-phaseN-...`), squash of work, merge
+  `--ff-only` to `main` after full verification (ruff + mypy + full test suite).
+- `docs/TASK-LEDGER.md` is updated at claim-time (status → in-progress, owner, touched)
+  and at completion (status → done/blocked, a dated Decisions entry explaining what
+  passed/what didn't and why) — read it before trusting any status claim here, this file
+  is a snapshot and will go stale.
+- Commits in this session were made **without** a Co-Authored-By trailer, per explicit
+  user instruction — continue that unless told otherwise.
+- Don't mark a ledger task `done` if its literal Verify bar isn't met — T-006 is the
+  example: the harness works, but "done" would overclaim a multi-repo A/B that hasn't
+  happened yet. `blocked` was used instead, with what's built vs what's missing spelled
+  out.
+
+## Suggested next steps (not mandated — use judgment)
+
+1. If you have other repos handy: `codebase-intel init` in them, capture a few real
+   `why`s, then `codebase-intel intent-eval` across all of them for T-006's real bar.
+2. Otherwise: pick up T-008's coverage debt, module by module (mcp/server.py and
+   graph/query.py are the biggest zero-coverage gaps).
+3. Team-layer depth (multi-user review queues, ownership UI, access control) was
+   deliberately deferred in Phase 5 — `capture.promote()` + owner metadata is the seed if
+   that becomes a priority.

{codebase_intel-0.2.0 → codebase_intel-0.3.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Mutharasu
+Copyright (c) 2026 Mutharasu A
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{codebase_intel-0.2.0 → codebase_intel-0.3.0}/PKG-INFO

@@ -1,10 +1,10 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: codebase-intel
-Version: 0.2.0
+Version: 0.3.0
 Summary: Your AI agent writes code — but does it know WHY your code exists? Decision provenance, quality contracts, and AI anti-pattern detection for coding agents.
-Project-URL: Homepage, https://github.com/mutharasu/codebase-intel
-Project-URL: Repository, https://github.com/mutharasu/codebase-intel
-Project-URL: Issues, https://github.com/mutharasu/codebase-intel/issues
+Project-URL: Homepage, https://github.com/a-mutharasu/codebase-intel
+Project-URL: Repository, https://github.com/a-mutharasu/codebase-intel
+Project-URL: Issues, https://github.com/a-mutharasu/codebase-intel/issues
 Author: Mutharasu
 License-Expression: MIT
 License-File: LICENSE
@@ -40,6 +40,7 @@ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
 Provides-Extra: eval
 Requires-Dist: matplotlib>=3.7; extra == 'eval'
 Description-Content-Type: text/markdown
@@ -51,11 +52,12 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  <a href="https://github.com/MutharasuArchunan13/codebase-intel/stargazers"><img src="https://img.shields.io/github/stars/MutharasuArchunan13/codebase-intel?style=flat-square" alt="Stars"></a>
+  <a href="https://github.com/a-mutharasu/codebase-intel/stargazers"><img src="https://img.shields.io/github/stars/a-mutharasu/codebase-intel?style=flat-square" alt="Stars"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green.svg?style=flat-square" alt="MIT"></a>
   <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg?style=flat-square" alt="Python 3.11+"></a>
   <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-purple.svg?style=flat-square" alt="MCP"></a>
   <a href="#19-languages"><img src="https://img.shields.io/badge/languages-19-orange.svg?style=flat-square" alt="19 Languages"></a>
+  <a href="https://pypi.org/project/codebase-intel/"><img src="https://img.shields.io/pypi/v/codebase-intel?style=flat-square" alt="PyPI"></a>
 </p>
 
 ---
@@ -135,7 +137,12 @@ Code → Graph → Agent        Code → Graph ───────────
 ## Quick Start
 
 ```bash
-pip install codebase-intel
+# Install globally (no venv needed)
+uvx codebase-intel --help          # ephemeral, like npx
+# or
+pipx install codebase-intel        # persistent global install
+# or
+pip install codebase-intel         # traditional
 
 # Initialize on your project
 cd your-project
@@ -147,6 +154,9 @@ codebase-intel status
 # Mine decisions from git history
 codebase-intel mine --save
 
+# Auto-detect code patterns and generate quality contracts
+codebase-intel detect-patterns --save
+
 # Run benchmarks (see the before/after)
 codebase-intel benchmark
 
@@ -154,8 +164,9 @@ codebase-intel benchmark
 codebase-intel dashboard
 ```
 
-### Connect to Claude Code
+### Connect to Claude Code / any MCP client
 
+**Single project:**
 ```json
 {
   "mcpServers": {
@@ -167,6 +178,27 @@ codebase-intel dashboard
 }
 ```
 
+**Multiple projects (global mode):**
+```bash
+# Register repos once from anywhere
+codebase-intel register ~/projects/user-service
+codebase-intel register /opt/services/payment-api
+codebase-intel register /var/repos/notification-service
+```
+
+```json
+{
+  "mcpServers": {
+    "codebase-intel": {
+      "command": "uvx",
+      "args": ["codebase-intel", "serve", "--auto"]
+    }
+  }
+}
+```
+
+In `--auto` mode, the MCP server automatically routes each request to the correct project based on file paths in the request. No manual switching — works like `npx @playwright/mcp`.
+
 Now your agent automatically gets relevant context, decisions, and contracts before writing code.
 
 ---
@@ -263,17 +295,41 @@ Full tree-sitter parsing via [tree-sitter-language-pack](https://github.com/nico
 ## CLI Commands
 
 ```bash
+# Core
 codebase-intel init [path]              # Initialize — build graph, create configs
 codebase-intel analyze [--incremental]  # Rebuild or update the code graph
 codebase-intel mine [--save]            # Mine git history for decision candidates
+codebase-intel detect-patterns [--save] # Auto-detect code patterns → quality contracts
 codebase-intel drift                    # Run drift detection
 codebase-intel benchmark                # Measure token efficiency (before/after)
 codebase-intel dashboard                # Live efficiency tracking over time
-codebase-intel serve                    # Start MCP server
+codebase-intel serve [path]             # Start MCP server (single project)
 codebase-intel status                   # Component health check
+codebase-intel intent [--verify]        # Track and verify delivery goals
+
+# Global workspace (multi-project)
+codebase-intel register <path>          # Register a project globally
+codebase-intel unregister <id>          # Remove from global registry
+codebase-intel projects                 # List all registered projects
+codebase-intel serve --auto             # Start MCP server for ALL registered projects
+
+# Cross-repo (microservices)
+codebase-intel crossrepo <paths...>     # Scan repos for cross-service dependencies
+codebase-intel crossrepo --all          # Scan all registered projects
+
+# Intent graph (v0.3)
+codebase-intel why "<title>" "<reason>" -f <file>   # Record a why (confirmed trust)
+codebase-intel install-hooks            # Install the pre-commit intent gate
+codebase-intel intent-gate              # Run the gate manually
+codebase-intel intent-check             # Repair moved anchors, flag drift, report coverage
+codebase-intel intent-confirm <node-id> # Promote an agent-asserted why to confirmed
+codebase-intel intent-render -f html -o intent.html  # Human view (html | mermaid)
+codebase-intel intent-migrate           # Import v1 decisions into the intent graph
+codebase-intel intent-rebuild           # Rebuild the SQLite index from the journal
+codebase-intel intent-eval [repos...]   # Token + correctness A/B vs the v1 baseline
 ```
 
-## MCP Tools (7 tools)
+## MCP Tools (16 tools)
 
 | Tool | What it does |
 |---|---|
@@ -284,6 +340,15 @@ codebase-intel status                   # Component health check
 | `check_drift` | Verify context freshness before trusting old decisions. |
 | `impact_analysis` | "What breaks if I change this file?" |
 | `get_status` | Health check — graph stats, decision count, contract count. |
+| `record_feedback` | Record if AI output was accepted/rejected — powers the learning loop. |
+| `get_efficiency_report` | Live token savings, acceptance rate, before/after proof. |
+| `set_intent` | Capture what the user wants with machine-verifiable acceptance criteria. |
+| `check_intent` | Verify if acceptance criteria are actually met before marking done. |
+| `list_intents` | Show all tracked intents with completion status. |
+| `bootstrap` | **Call first in a session.** System orientation + task-relevant whys, packed into a token budget. |
+| `check_precedent` | Was this already decided — or decided and reversed? Call before structural choices. |
+| `record_why` | Record why a structural decision was made, at the moment it's made. |
+| `get_intent` | Traverse the intent graph by node, file, or abstraction level; no args = coverage stats. |
 
 ---
 
@@ -303,10 +368,89 @@ cp community-contracts/fastapi.yaml .codebase-intel/contracts/
 
 ---
 
+## New in v0.3.0 — the Intent Graph
+
+v0.2 could tell an agent *what* decisions exist. v0.3 captures **why** at the moment a decision is made, and lets agents traverse that reasoning instead of re-reading files and re-deciding things that were already decided.
+
+- **Journal-first.** `.codebase-intel/intent-journal/*.jsonl` is the committed source of truth; `intent-graph.db` is a derived, git-ignored index you can always rebuild (`intent-rebuild`).
+- **Four abstraction levels** — system topology → service/module → component/flow → function/decision — linked with parent/child and `supersedes` edges.
+- **Trust tiers, surfaced everywhere:** `mined` (from git) → `derived` → `asserted` (by an agent) → `confirmed` (by a human, via `intent-confirm`). Agents see which whys a human has actually vouched for.
+- **Capture loop.** Agents call `record_why` when they make a structural choice and `check_precedent` before they make one. A pre-commit gate (`install-hooks`) warns — or blocks, with `gate_hard` — on structural changes that have no recorded why.
+- **Session bootstrap.** `bootstrap(task)` returns top-level orientation plus the relevant whys within a token budget, with a degradation ladder: intent graph → code graph → raw files. It never hard-fails.
+- **Anchor honesty.** `intent-check` re-anchors whys when code moves, flags whys whose code diverged, and reports conflicts and coverage.
+- **Human projection.** `intent-render` produces an HTML or Mermaid view of the same graph for review.
+- **v1 migration.** `intent-migrate` imports existing decision records. It's safe to re-run.
+- **Eval harness.** `intent-eval` measures token cost *and* retrieval correctness against the v1 baseline. First self-hosted result: accuracy@1 100%, ~99% fewer tokens than a naive file read — on **n=3** cases from this repo only. See [docs/EVAL-RESULTS.md](docs/EVAL-RESULTS.md) for methodology and caveats; external-repo numbers are still to come.
+
+```bash
+pip install -U codebase-intel
+codebase-intel intent-migrate      # bring v1 decisions along
+codebase-intel install-hooks       # start capturing whys at commit time
+```
+
+An agent skill that tells Claude Code (and other agents) when to call these tools ships in [`skills/codebase-intel/SKILL.md`](skills/codebase-intel/SKILL.md).
+Install it for Claude Code with:
+
+```bash
+mkdir -p ~/.claude/skills/codebase-intel
+curl -fsSL https://raw.githubusercontent.com/a-mutharasu/codebase-intel/main/skills/codebase-intel/SKILL.md \
+  -o ~/.claude/skills/codebase-intel/SKILL.md
+```
+
+## New in v0.2.0
+
+### Global Workspace — One server, all your projects
+
+No more running a separate MCP server per project. Register your repos once, serve them all:
+
+```bash
+codebase-intel register ~/projects/user-service
+codebase-intel register /opt/services/payment-api
+codebase-intel serve --auto
+```
+
+The server auto-routes each request to the correct project based on file paths. LRU cache keeps the 5 most recently used projects loaded — older ones are evicted and reloaded on demand.
+
+### Intent Tracking — "Did you actually build what was requested?"
+
+AI agents say "done" when the code compiles. But did they actually deliver what was asked? Intent tracking captures goals with **machine-verifiable** acceptance criteria:
+
+```bash
+# Agent sets intent at task start (via MCP tool set_intent)
+# Agent works on the task...
+# Before marking done, agent calls check_intent
+# System runs automated checks: file_exists, function_exists, grep_match, test_passes...
+# Returns: 18/21 criteria met — 3 gaps identified
+```
+
+11 verification types: `file_exists`, `file_contains`, `function_exists`, `wired`, `cli_works`, `mcp_tool_exists`, `grep_match`, `grep_no_match`, `test_passes`, `custom`, `manual`.
+
+### Cross-Repo Awareness — Microservice dependency mapping
+
+Scans 14 web frameworks across 10 languages to find exposed endpoints and outbound HTTP calls. Maps which service depends on which endpoint:
+
+```bash
+codebase-intel crossrepo --all --impact user-service
+
+# Output:
+# CRITICAL: 3 services depend on /api/v1/users/{id}
+# → payment-service calls this endpoint [CRITICAL] at src/clients/user.py:42
+# → notification-service calls this endpoint at lib/api/users.ts:18
+```
+
+Supported: FastAPI, Express, Flask, Django, Spring Boot, Gin, Actix, Rails, Phoenix, Laravel, ASP.NET, Ktor, Vapor, Echo.
+
+### Feedback Loop — Learn from acceptance/rejection
+
+Records whether AI-generated code was accepted, modified, or rejected. Over time, identifies which context patterns lead to better output and which rejection reasons are most common.
+
 ## Architecture
 
 ```
-AI Agent (any) ──→ MCP Server (7 tools)
+AI Agent (any) ──→ MCP Server (16 tools)
+                        │
+                  Workspace Manager ←── Global Registry (~/.codebase-intel/)
+                  (multi-project routing, LRU cache)
                         │
                   Context Orchestrator
                   (token budgeting, priority, conflicts)
@@ -318,8 +462,13 @@ AI Agent (any) ──→ MCP Server (7 tools)
                     Drift Detector
                     (staleness, rot, orphans)
                           │
-                    Analytics Tracker
-                    (live efficiency metrics)
+               ┌──────────┼──────────┐
+         Analytics    Feedback    Intent
+         Tracker      Loop       Tracker
+               └──────────┼──────────┘
+                          │
+                   Cross-Repo Scanner
+                   (14 frameworks, 10 languages)
 ```
 
 ---
@@ -350,7 +499,7 @@ Areas with the most impact:
 4. **Benchmarks** — Run against your repos, share results
 
 ```bash
-git clone https://github.com/MutharasuArchunan13/codebase-intel.git
+git clone https://github.com/a-mutharasu/codebase-intel.git
 cd codebase-intel
 pip install -e ".[dev]"
 pytest