@orquentra/codebuddy 2.4.0 → 2.5.0

package/README.md

@@ -1,1119 +1,71 @@
 # CodeBuddy
 
-**A local-first project brain for AI coding agents.** CodeBuddy gives Claude
-Code and Codex durable memory *and* prepares the smallest useful slice of
-project context before every edit — so the agent works like a careful senior
-engineer instead of re-reading your whole repo on every turn.
+Local-first project context and memory for AI coding agents.
 
-It runs on your machine. Knowledge lives as readable Markdown under
-`.codebuddy/`. PostgreSQL + pgvector is only a search index, never the source of
-truth. Nothing is sent to a hosted CodeBuddy service — there isn't one.
+CodeBuddy helps agents find relevant code, understand project constraints, and
+remember decisions across sessions. It works through MCP with Claude Code,
+Codex, OpenCode, Hermes, and other compatible clients.
 
-- **npm:** `@orquentra/codebuddy` (v2.4.0)
-- **Surfaces:** CLI · MCP stdio server · TypeScript SDK · LangGraph helpers
+## Install
 
-`@orquentra/codebuddy` continues the project previously published as
-[`@ayushkumar320/codebuddy`](https://www.npmjs.com/package/@ayushkumar320/codebuddy).
-The original package remains available as the historical release archive, with
-its existing versions and download records. Future releases use the Orquentra
-package; npm tracks the two package names separately.
-
----
-
-## Table of contents
-
-- [The problem it solves](#the-problem-it-solves)
-- [How it works (mental model)](#how-it-works-mental-model)
-- [Install & setup](#install--setup)
-- [Feature tour (with examples)](#feature-tour-with-examples)
-  - [1. Durable Markdown memory](#1-durable-markdown-memory)
-  - [2. Plans](#2-plans)
-  - [3. Risk assessment](#3-risk-assessment)
-  - [4. Architecture map](#4-architecture-map)
-  - [5. Background indexing](#5-background-indexing)
-  - [6. Automatic context (bootstrap & before-edit)](#6-automatic-context-bootstrap--before-edit)
-  - [7. Automatic memory capture + review queue](#7-automatic-memory-capture--review-queue)
-  - [8. Measured token use](#8-measured-token-use)
-  - [9. Read-only suggestions](#9-read-only-suggestions)
-  - [10. Change readiness](#10-change-readiness)
-  - [11. Client workflow templates](#11-client-workflow-templates)
-  - [12. Fully automatic mode (hooks)](#12-fully-automatic-mode-hooks)
-- [How CodeBuddy saves tokens vs. a big knowledge graph](#how-codebuddy-saves-tokens-vs-a-big-knowledge-graph)
-- [MCP tools reference](#mcp-tools-reference)
-- [SDK usage](#sdk-usage)
-- [LangGraph](#langgraph)
-- [Working as a team](#working-as-a-team)
-- [Repo layout (for contributors)](#repo-layout-for-contributors)
-- [Troubleshooting](#troubleshooting)
-- [Privacy](#privacy)
-
----
-
-## The problem it solves
-
-When you code with an AI agent, two things quietly cost you money and quality:
-
-1. **The agent forgets.** Every session starts cold. You re-explain the same
-   decisions, the same "don't touch that file," the same past bug.
-2. **The agent over-reads.** To answer "fix the OAuth callback," it opens and
-   reads dozens of files — burning tokens on raw source it mostly doesn't need.
-
-CodeBuddy fixes both:
-
-- It **remembers** durable facts, decisions, and incidents as Markdown you can
-  read and commit.
-- It **prepares context** — a compact, bounded summary of the plan, risks, past
-  incidents, and only the relevant files — so the agent gets what it needs
-  without a repo dump.
-
----
-
-## How it works (mental model)
-
-```text
-                   .codebuddy/   (Markdown = source of truth, committable)
-                   ├── memory/facts, summaries, review     (what we know)
-                   ├── plans/                               (what we're doing)
-                   ├── policies.yaml                        (what needs care)
-                   └── cache/index.json                     (rebuildable index)
-                          │
-   ┌──────────────────────┼───────────────────────────────┐
-   │                      │                                │
- CLI (codebuddy …)   MCP server (codebuddy serve)      SDK / LangGraph
-   │                      │                                │
-   └── file-based tools ──┴── Postgres-backed tools ───────┘
-       (no DB needed)         (recall / embeddings)
-```
-
-A turn with an agent looks like this:
-
-```text
-turn starts
-  → context_bootstrap        # identity, active plan, policies, incidents, architecture
-  → context_before_edit      # for the files about to change: plan + risk + incidents + neighbours
-agent edits with compact context (not a repo dump)
-turn ends
-  → context_after_turn       # capture durable facts/decisions/incidents (confidence-gated)
-  → code_suggestions         # optional read-only quality findings
-```
-
-Two design rules run through everything:
-
-- **Bounded, deterministic, explainable.** Every tool output is capped, produced
-  the same way each run, and carries `explain[]` reasons. No black-box ranking.
-- **Local-first & no mandatory LLM.** The core context/index/suggestion
-  paths use zero LLM calls. Embeddings (Hugging Face) power semantic recall only.
-
----
-
-## Install & setup
-
-### Requirements
-
-- **Node 20+** (required)
-- **PostgreSQL 16 + pgvector** — only for semantic `recall`/embeddings. Every
-  new v2.0 feature works without it.
-- **Hugging Face token** — only for embeddings. Optional otherwise.
-- Optional: Docker (for the bundled Postgres), `@langchain/langgraph` peer dep.
-
-### Fastest path
-
-```bash
-npm install -g @orquentra/codebuddy
-cd ~/Projects/your-project
-codebuddy                         # first-run setup; offers to start Docker when needed
-codebuddy use your-project        # repeat setup for a named namespace
-codebuddy rules install --client claude   # teach the agent when to call the tools
-```
-
-For a zero-database setup that also enables PR reports:
-
-```bash
-npx @orquentra/codebuddy init --non-interactive --github-action
-```
-
-This creates the local `.codebuddy/` scaffold and an idempotent
-`.github/workflows/codebuddy.yml` workflow. Commit the workflow to start
-receiving a CodeBuddy report on every pull request.
-
-On the first run, `codebuddy` also asks whether to enable Graphify:
-
-- **Yes:** it installs/detects Graphify, builds `graphify-out/graph.json`,
-  registers its local MCP server in the project `.mcp.json`, and enables
-  Graphify architecture input for CodeBuddy.
-- **No:** it registers only CodeBuddy. The MCP context workflow is unchanged;
-  CodeBuddy uses its own local architecture index.
-
-In both cases it writes the CodeBuddy MCP entry without putting database
-credentials in `.mcp.json`, and adds managed instructions to `CLAUDE.md` and
-`AGENTS.md` so the agent knows to use `context_pack`. The Graphify MCP entry is
-added only when Graphify is enabled.
-
-Graphify runs locally. Its current installer is `uv tool install graphifyy`
-(with pipx/pip alternatives). Setup generates `graphify-out/graph.json` using
-Graphify's code-only extractor before registering the MCP server. Once the MCP
-server starts, CodeBuddy automatically indexes the existing repository, imports
-`.codebuddy/memory/` into the database, refreshes Graphify after code changes,
-and queues embeddings in the background. No manual refresh command is needed.
-The explicit command remains available for diagnostics:
-
-```bash
-codebuddy graphify index
-```
-
-`codebuddy serve` also checks an enabled Graphify configuration and prepares a
-missing or invalid graph automatically. Graph output is staged and validated
-before replacement, so a valid existing graph is preserved if extraction fails.
-
-### How CodeBuddy helps, in plain English
-
-CodeBuddy is a small context and memory layer between your repository and your
-coding agent. You describe a task once, and CodeBuddy prepares the useful
-project information before Claude or Codex starts editing:
-
-1. It finds the files, functions, tests, rules, previous incidents, and related
-   architecture that matter to the task.
-2. It sends a compact, token-budgeted `context_pack` instead of making the
-   agent repeatedly read the whole repository.
-3. The agent makes the change with more relevant evidence and less guessing.
-4. CodeBuddy can record durable decisions and change outcomes for future tasks.
-5. Pull requests can receive a readiness report covering risk, tests, plan drift,
-   and architecture impact.
-
-The practical result is less repeated reading, lower context cost, fewer
-irrelevant edits, and a project that becomes easier for new agents to
-understand over time. Graphify is optional: it adds a richer local map of how
-the codebase connects, while CodeBuddy's own MCP context workflow works either
-way.
-
-### No-database path (try the context engine in 30 seconds)
-
-Everything except semantic recall is file-based, so you can skip Postgres:
+Requires Node.js 20 or later.
 
 ```bash
 npm install -g @orquentra/codebuddy
-cd ~/Projects/your-project
-codebuddy init --non-interactive  # just creates the .codebuddy/ scaffold
-codebuddy index
-codebuddy suggest --git
-```
-
-### Bring-your-own vs. bundled Postgres
-
-The normal setup flow checks the default local Postgres URL first. If it is not
-reachable, CodeBuddy offers to start Docker Desktop and its bundled pgvector
-database automatically. Choose `No` if you want to configure Postgres yourself.
-Use `codebuddy use --no-docker` to skip that offer in scripts or controlled
-environments.
-
-```bash
-# Manual control is still available:
-codebuddy postgres up
-codebuddy doctor                  # DB, pgvector, scaffold, model health
-
-# Or your own database — the URL must include real user:password
-export DATABASE_URL="postgres://user:pass@host:5432/db"
-codebuddy migrate
+cd your-project
+codebuddy
 ```
 
-> If `codebuddy doctor` says `password authentication failed for user "<you>"`,
-> your `DATABASE_URL` has no credentials and Postgres fell back to your OS
-> username. Set the URL as above. This does **not** affect the file-based tools.
+The setup wizard configures the project and agent integration. Project context
+works without a database; semantic memory recall optionally uses PostgreSQL
+with pgvector and a local Hugging Face embedding model (no token needed).
 
----
+## What it does
 
-## Feature tour (with examples)
+- **Task context:** relevant files, symbols, code excerpts, nearby dependencies,
+  and covering tests within a token budget.
+- **Project memory:** decisions, rules, and handoffs stored as readable Markdown,
+  recalled on every prompt by hybrid lexical + vector search
+  ([how it works](docs/semantic-memory.md)).
+- **Change guidance:** plans, policies, incident history, and risk signals.
+- **Optional retrieval:** zvec semantic search, Graphify architecture maps, and
+  a bring-your-own LLM layer.
 
-### 1. Durable Markdown memory
-
-Facts and summaries are written as Markdown under `.codebuddy/memory/`. They
-survive database loss and are diffable in git.
+## See what it does
 
 ```bash
-codebuddy list-facts
-codebuddy inspect your-project
-codebuddy export your-project > backup.json
-codebuddy stats
+codebuddy dashboard
 ```
 
-Through MCP an agent calls `remember` / `recall` / `share` / `forget`. Facts can
-be tagged as **incidents** (with `paths` and `severity`) so CodeBuddy can warn
-when a future change touches a file that broke before.
-
-### 2. Plans
-
-A plan is a durable Markdown work-order: title, brief, files to touch, tests to
-add, risks, out-of-scope. At most one plan is "active" per namespace.
-
-```bash
-codebuddy plan new "Add OAuth login flow"   # opens $EDITOR
-codebuddy plan list
-codebuddy plan approve pln_abc123
-codebuddy plan start pln_abc123
-codebuddy plan complete pln_abc123 --commit <sha>
-```
+This opens a live local page showing:
+- every prompt and the memories recalled for it;
+- MCP tool calls with their latency;
+- the tokens delivered to your agent.
 
-### 3. Risk assessment
+It updates as you work, and the traces never leave your machine.
 
-Deterministic, evidence-backed risk scoring from incident memory, project
-policy, and recent git churn — no LLM.
+## Try it without a database
 
 ```bash
-codebuddy risk assess --git
-codebuddy risk assess --paths src/auth/oauth.ts,src/api/login.ts
-codebuddy risk assess --plan pln_abc123 --explain
-```
-
-Policy lives in `.codebuddy/policies.yaml`:
-
-```yaml
-rules:
-  - id: auth-sensitive
-    pattern: "src/auth/**"
-    message: "Auth changes need careful review."
-    weight: 70
+codebuddy init --non-interactive
+codebuddy context preview "fix the login flow"
 ```
 
-### 4. Architecture map
-
-A lightweight import graph, scanned on demand.
+Agents use `context_pack` to request task evidence and `context_after_turn` to
+capture useful knowledge. Request `evidence: "source"` when a short excerpt
+needs more detail. Inspect missing or truncated evidence before editing.
 
-```bash
-codebuddy map build
-codebuddy map deps src/cli/index.ts          # what this file imports
-codebuddy map dependents src/core/codebuddy.ts   # what imports this file (blast radius)
-```
+## Documentation
 
-### 5. Background indexing
+- [Full guide and examples](https://github.com/Orquentra-Inc/CodeBuddy/blob/348bb7c/README.md)
+- [Token budgets](https://github.com/Orquentra-Inc/CodeBuddy/blob/main/docs/token-budgets.md)
+- [Optional LLM setup](https://github.com/Orquentra-Inc/CodeBuddy/blob/main/docs/llm-byok.md)
+- [Source and issues](https://github.com/Orquentra-Inc/CodeBuddy)
 
-Builds a content-hash + one-line summary for every file, cached at
-`.codebuddy/cache/index.json` (gitignored, rebuildable). Incremental: unchanged
-files are skipped. Respects `.gitignore`.
-
-```bash
-codebuddy index          # e.g. "128 indexed (+128 ~0 =0 -0) in 40ms"
-codebuddy index          # again → "=128" (all unchanged)
-codebuddy watch          # optional foreground watcher; MCP serve watches automatically
-```
-
-The index also records a per-file **symbol table** (functions, classes, class
-methods as `Class.method`, types), so context can send a file's public API
-instead of its whole body. Before-edit context ranks the whole table by the task
-before keeping 12 signatures, and returns the best match per top file as a
-`spans[]` entry (line range, `source`, zvec `rank`, a short excerpt) read from
-current source:
-
-```bash
-codebuddy symbols src/service.ts
-# export function getUser  L3-5
-# ...
-# 5 symbol(s)
-```
-
-### 6. Automatic context (bootstrap & before-edit)
-
-The heart of v2.0. Preview exactly what the agent would receive:
-
-```bash
-codebuddy context bootstrap
-# project + active plan + policy + incident hotspots + architecture summary + token stats
-
-codebuddy context preview "fix the OAuth callback" --paths src/auth/oauth.ts
-# target files + relevant plan + matching policy + incidents + risk + import neighbours
-
-codebuddy context explain --git
-# the same, plus WHY each piece was included and per-stage token accounting
-```
-
-Over MCP these are `context_bootstrap` and `context_before_edit`.
-
-For Claude and Codex, the simplest integration is the single-call
-`context_pack` tool:
-
-```text
-context_pack({
-  "task": "fix the OAuth callback",
-  "tokenBudget": 4000
-})
-```
-
-It automatically ranks files from the local index when paths are omitted, then
-returns bounded symbols, policies, risks, incidents, architecture neighbours,
-and relevant team facts. The agent does not need to manually chain recall,
-risk, map, and context tools. The response includes token accounting and whether
-safety evidence was omitted when the budget is tight. See the
-[token budget contract](docs/token-budgets.md) for the exact counted surfaces,
-final response accounting, and overflow behavior.
-
-**Optional semantic retrieval (zvec-grep).** When paths are omitted, files are
-found by keyword ranking over the local index. For conceptually phrased tasks
-you can add [zvec-grep](https://github.com/zvec-ai/zvec-grep) (`zg`, 0.2.x) as a
-local semantic candidate source. It is off by default and needs no network or
-hosted service:
-
-```bash
-npm install -g @zvec/zvec-grep
-codebuddy zvec index      # explicit; local/potion-code-16m-v2, seconds on a mid-size repo
-codebuddy zvec enable     # or CODEBUDDY_ZVEC=1, or "zvec": { "enabled": true } in config
-codebuddy zvec status     # enabled / version / index ready / zg server / reason
-echo ".zvec-grep/" >> .gitignore
-zg server on              # optional: halves query latency; CodeBuddy never starts it
-```
-
-CodeBuddy then runs `zg query --vector --mode auto` (oversampling chunks so one
-file's many chunks can't crowd out the rest), keeps only hits that still exist in
-the working tree (tests only if the task is about tests; never
-`.codebuddy/cache/`), drops vector hits whose current source shares fewer than two
-task words (unless they pass the keyword floor below), and fuses the rest with the
-keyword ranking (equal-weight RRF; weighting vectors 0.5–0.75 or 1.5 scored worse
-on the benchmark). Hit line ranges are kept
-and re-checked against current source to pick symbol spans. A task naming a code
-identifier (`withSessionLock`, `HookStagingStore.claim`) skips vectors and routes
-straight to the declaring files (`retrieval: exact-symbol routing`). It never builds
-a zvec index for you: a missing binary, unsupported version, unready index,
-timeout or failure falls back to keyword ranking, and `explain` says which
-happened (`retrieval: …`). The version/readiness check is cached for 10 minutes
-in `.codebuddy/cache/zvec-ready.json`; a failed check is cached for 30 seconds
-(dropped as soon as `.zvec-grep/` changes), and the explain line then says
-`cached check from Ns ago`. Hits only choose candidate files and
-spans; risks, policies and incidents still come from CodeBuddy's own evidence,
-and facts are ranked lexically (no semantic fact ranker is wired by default).
-
-**Optional small model (bring your own key).** With a free Groq or OpenRouter key,
-CodeBuddy can write one-line summaries of your files (so a reworded task still finds
-the right file) and rerank the candidates once per prompt with a short deadline. It's
-off by default, the key stays in your environment, and any failure falls back to the
-deterministic ranking. See [docs/llm-byok.md](docs/llm-byok.md) for setup and exactly
-what is sent.
-
-```bash
-export GROQ_API_KEY=gsk_...
-codebuddy llm enable && codebuddy llm summarize
-```
-
-**Evidence floor and abstention.** A task-discovered file needs a keyword score
-of 1.5 (two distinct task words in its path, summary or symbols, or one in its
-file name), or, for a vector hit, two task words in its current source. Weaker
-candidates are dropped (`abstention: N weak keyword candidate(s) … dropped`), and
-when no *source* file reaches the floor the task gets no targets at all rather
-than unrelated code (`abstention: no source file reached the evidence floor …`);
-docs and config alone never justify sending code. The thresholds were calibrated
-on the `tune` split of `evals/task-savings.json` only. Explicit `paths`, plans and
-exact identifiers are unaffected.
-
-**Multi-file expansion.** When the task asks for a path through several files
-(`trace`, `follow`, `through`, `across`, `between`, `from … to`), up to two import
-neighbours of the top three targets that share a task word are ranked with the
-import edge credited as one more word, so a workflow's partner files survive the
-floor and the target cap without displacing stronger evidence (`expansion: …`).
-
-Benchmark on this repo (`npm run eval:retrieval`, 12 tasks, `zg` index built with
-`codebuddy zvec index`):
-
-| | top-5 hits | MRR | context | cold | warm |
-|---|---|---|---|---|---|
-| keyword only | 6/12 | 0.39 | ~1.7k tokens | ~130ms | ~20ms |
-| + zvec-grep (direct) | 9/12 | 0.51 | ~2.1k tokens | ~810ms | ~425ms |
-
-The evidence floor cut keyword context from ~2.5k and fused from ~2.3k tokens per
-task at unchanged hits; a running `zg server` roughly halves warm latency.
-
-### 7. Automatic memory capture + review queue
-
-After a turn, `context_after_turn` (MCP) turns a summary into classified
-candidates and **gates** them:
-
-- **Auto-saved** as durable Markdown: confident facts, decisions, incidents.
-- **Queued for review:** temporary notes, low-confidence items, anything
-  sensitive (secrets/keys/tokens are **never** auto-saved).
-- **Dropped:** chatter.
-
-Curate the queue from the CLI:
-
-```bash
-codebuddy memory review                 # list pending candidates (⚠ marks sensitive)
-codebuddy memory review show <id>
-codebuddy memory review approve <id>    # promote to a durable fact
-codebuddy memory review reject <id>
-```
-
-Bias by design: **prefer a missed memory over a false durable fact.**
-
-### 8. Measured token use
-
-CodeBuddy does not print estimated savings. The token numbers it reports are the
-size of its own payload (`tokens.returnedEstimate` against `tokens.budget`) and
-what agent CLIs bill in A/B studies.
-
-The three-arm study (`npm run eval:agent-ab`, results in
-[`evals/agent-ab-repos.jsonl`](evals/agent-ab-repos.jsonl)) ran 14 bug-fix tasks
-across semver, pygments, click, chi and commander, 3 runs per arm, with
-`claude -p` on Claude Opus 5.5 and CodeBuddy 2.3.0:
-
-| Arm | Cost | Tokens | Agent turns | Tasks passed |
-|---|---|---|---|---|
-| no CodeBuddy | $13.77 | 16.56M | 532 | 42/42 |
-| `lean` | $12.79 (−7.1%) | 14.45M (−12.7%) | 480 | 42/42 |
-
-Lean was cheaper on 11 of the 14 tasks; per task, tokens ranged from −43% to
-+16%. The saving comes from fewer agent steps, each of which re-sends the
-conversation, more than from reading fewer bytes.
-
-For development, `npm run eval:savings` measures `context_pack` itself on
-[`evals/task-savings.json`](evals/task-savings.json) (27 cases: identifiers,
-paraphrases, multi-file, negative queries; TypeScript + Python; `tune` vs
-`holdout` splits) by calling the real MCP tool:
-
-- **compression** — a recount that tokenizes (cl100k) only files whose
-  signatures actually reached the payload, against those files' raw source;
-- **transmission** — observed MCP result tokens on the first turn and on an
-  acknowledged repeat turn. Reported next to it, each labelled separately:
-  the **framing** count tokenizes the whole SDK tool result (`context_pack`
-  returns the payload both as `content[].text` and as `structuredContent`, so a
-  client that forwards both pays roughly twice); the **JSON-RPC envelope** is
-  the serialized request and response message captured from the transport; the
-  **tool list** is the `tools/list` schema (and its serialized response) a
-  client loads once per session. System-prompt framing is client-specific and
-  not observable from the server, so it is reported as not measured;
-- **net task tokens** — first turn + raw reads of expected files the payload
-  only names + **function-body reads** (the lines of each declaration the task
-  edits, per the dataset's `symbols`, that neither a listed signature nor a span
-  excerpt shows), against an oracle that reads exactly the expected files. Not
-  clamped: losses show as negative.
-
-Quality is deterministic (no LLM): evidence sufficiency (every expected file's
-signatures present and every expected identifier in the payload), abstention
-on negative queries, and the false durable memory rate of `context_after_turn`.
-Each case reports its retrieval status (`disabled`/`vector`/`fallback`); fused
-quality only counts `vector` cases, so a zvec fallback never passes as semantic
-evidence. Fused mode never touches your repository's zg index: with `zg` 0.2.x
-installed, each dataset repository is copied to a temp directory and indexed
-there first (a few seconds).
-
-Scenarios run alongside (dataset `scenarios`, no Postgres or `zg` needed):
-
-- **stale index** — index a copy, then edit a signature, delete a file and
-  rename a file without reindexing: each case must report only current
-  symbols/paths and flag the refresh in its `index:` explain line;
-- **provider outage** — fused mode against a stub `zg` that is missing, crashes
-  or hangs: every case must report `fallback` (or exact-symbol routing), keep the
-  keyword-only targets, and never yield vector-quality evidence;
-- **long session** — twelve acknowledged `context_pack` turns in one session
-  that switch between tasks and come back (A, B, A …), with `full: true` at turn
-  6 (a compacted client), against the same tasks as independent first turns.
-  The `full` turn must match a fresh session section for section, and every
-  omitted section must have been delivered earlier since the last `full`;
-- **agent harness** — four fixture tasks
-  ([`evals/fixtures/agent-tasks`](evals/fixtures/agent-tasks)), each with a real
-  check that fails until the task is done. The default, deterministic
-  `simulated` agent picks its target only from the payload (files whose listed
-  signatures declare the symbol to change, then the other targets in rank
-  order), reads what the payload does not show, applies the task's scripted
-  edit, and runs the check; a failed edit is reverted and the next candidate is
-  a retry. Retries, incorrect edits (files outside the expected set), passes and
-  tokens are recorded, so a worse payload shows up as a worse outcome.
-
-```bash
-npm run eval:savings                    # per-case table + summary
-npm run eval:savings -- --json          # machine-readable report (incl. scenarios)
-npm run eval:savings -- --check         # exit 1 on regression vs evals/task-savings.baseline.json
-npm run eval:savings -- --check --mode keyword   # what CI runs
-npm run eval:savings -- --check --mode fused     # fused gate on zg-indexed temp copies
-npm run eval:savings -- --check --gate-latency   # also gate p95 latency (same machine only)
-npm run eval:savings -- --write-baseline
-npm run eval:savings -- --mode keyword --agent-cmd "claude -p --output-format json"
-npm run eval:savings -- --mode keyword --agent-cmd "codex exec" --agent-context none
-```
-
-With the #45 evidence floor (keyword mode) abstention is 1.0 and first turns are
-~1,401 tokens per task; tool schema is 1,261 tokens with `CODEBUDDY_TOOL_PROFILE=core`
-(see [docs/audits](docs/audits/README.md#experiments)). The detailed figures below
-predate that change; `evals/task-savings.baseline.json` holds the current baseline.
-
-`--agent-cmd` switches the harness to `agent` mode: it runs a real agent CLI in
-a temp copy per task (the prompt is passed as the last argument, with the
-`context_pack` payload unless `--agent-context none`), re-prompts with the check
-output on failure, and records files edited, retries, the check result and the
-tokens the CLI reports (`usage` JSON or `tokens used: N`; `null` when it reports
-none, never estimated). It spends model tokens, so it is opt-in and never runs
-in CI; `--check` never compares it with the simulated baseline.
-
-The committed baseline was measured on this repo. Keyword mode: evidence
-sufficiency 0.667, abstention 0.667, ~1,898 first-turn and ~467 repeat-turn
-tokens per task, latency p50 ~25 ms / p95 ~29 ms. Fused mode (zg 0.2.2,
-`local/potion-code-16m-v2`, temp copies): 23 `vector` + 4 exact-symbol cases,
-0 fallback, vector-case sufficiency 0.75 (0.792 over all cases), ~1,788
-first-turn tokens, p50 ~433 ms / p95 ~604 ms. Net modeled task tokens across
-the 27 cases are **−15,128** keyword / −9,307 fused, of which function-body
-reads are 5,156 / 6,124 and whole-file reads 7,432 / 3,604: for small
-single-file tasks an agent reading the right file directly is cheaper. Framing,
-separately: the SDK result is ~3,973 tokens per first turn, the serialized
-JSON-RPC response ~3,987 and the request ~56 (net −71,158 and −73,042 if a
-client keeps them); the tool list is 3,419 tokens of schema (3,437 serialized,
-290 for `context_pack` alone) once per session. Scenarios: stale index 3/3
-correct, outage 15/15 safe (12 `fallback`, 3 exact-symbol, 0 `vector`), long
-session 21,418 vs 32,638 tokens for the same twelve tasks fetched
-independently, agent harness 4/4 passed with 0 retries and 0 incorrect edits at
-1,965 tokens (an oracle that reads only the edited files: 434). Without a ready
-index, fused mode re-probed `zg` on every call (~206 ms); the failed probe is now
-cached for 30 s (10 calls: 2,071 ms → 212 ms).
-
-`--check` fails if sufficiency or abstention drops, false memory rises, tokens
-(payload, framing, envelope, function-body reads, tool list or session) grow
-more than 10%, a stale-index case claims stale evidence or fewer are correct, an
-outage case reports `vector` or loses keyword context, the session's acks,
-`full` resend or omissions break, or the simulated harness passes fewer tasks or
-needs more retries or incorrect edits. The fused baseline is only enforced when
-fused mode ran with `zg` 0.2.x; without it the check reports `skip` instead of
-failing, so CI stays green without `zg`. Token counts are deterministic up to a
-random `deliveryId` and the absolute repo root echoed in the payload (a few
-tokens), so the gate is stable across machines; latency is not, so p95 only
-warns unless `--gate-latency` is passed. CI runs `--check --mode keyword`.
-
-### 9. Read-only suggestions
-
-Evidence-backed, severity-ranked findings — a careful reviewer, not a noisy
-linter. It **never edits code.**
-
-```bash
-codebuddy suggest --git
-codebuddy suggest --paths src/auth/oauth.ts
-# [med ] Review high-risk change to src/auth/oauth.ts
-#   ↳ risk_score: score 70 (policy)
-# [low ] No test found for src/auth/oauth.ts
-# [low ] Stale policy rule "gone" → legacy/** does not exist
-```
-
-Categories: risk · plan divergence · architecture blast radius · incident
-history · missing tests · stale policies. Over MCP: `code_suggestions`.
-
-### 10. Change readiness
-
-Turn the existing signals into one evidence-backed change report. It combines
-the current diff, active plan, risk, architecture dependents, incident history,
-and test coverage into a single readiness decision.
-
-```bash
-codebuddy change
-codebuddy change --paths src/auth/oauth.ts --no-git
-codebuddy change --json       # stable output for CI or another agent
-# [review ] change report
-#   highest risk: 70
-#   verification: 1 test file(s) changed; 0 code file(s) without a discovered test
-
-codebuddy change verify     # detects and runs npm/pnpm/yarn/bun test
-codebuddy change verify --command "npm run test:unit" --timeout 300000
-
-codebuddy eval             # run the committed readiness evaluation cases
-```
-
-The status is `ready`, `review`, `blocked`, or `no_changes`. The command is
-read-only and is designed to run before a commit or as an agent checkpoint.
-`change verify` returns a non-zero exit code when tests fail, time out, or no
-test command can be found, and supports `--json` for CI integration.
-
-The evaluation dataset lives under `evals/` and is intentionally small,
-readable, and versioned. Extend it when changing risk thresholds or adding a
-new signal so product claims remain reproducible.
-
-Record the outcome of a real change so future reports learn from the project:
-
-```bash
-codebuddy learn outcome --outcome safe \
-  --paths src/auth/oauth.ts \
-  --summary "OAuth callback change passed review and regression tests."
-
-codebuddy learn outcome --outcome regression \
-  --paths src/auth/oauth.ts \
-  --severity high \
-  --summary "Dropped callback state caused a production login failure."
-```
-
-Outcomes are stored as reviewable Markdown under `.codebuddy/memory/`. A
-regression becomes path-specific incident memory and raises the next change's
-risk score for that area.
-
-If a repository already uses Graphify, CodeBuddy can consume its local graph
-without taking a Graphify dependency:
-
-```bash
-codebuddy change --graphify graphify-out/graph.json
-codebuddy change verify --graphify graphify-out/graph.json
-```
-
-The imported relationships enrich architecture dependents while CodeBuddy
-keeps its own policy, plan, verification, and team-memory signals layered on
-top.
-
-### 11. Client workflow templates
-
-Teach Claude/Codex *when* to call each tool. Install writes an idempotent
-managed block into `CLAUDE.md` / `AGENTS.md` between clear markers — re-running
-updates it in place and never touches your other content.
-
-```bash
-codebuddy rules show --client claude       # preview the exact text
-codebuddy rules install --client claude    # → managed block in CLAUDE.md
-codebuddy rules install --client codex     # → managed block in AGENTS.md
-```
-
-See [docs/degraded-mode.md](docs/degraded-mode.md) for how the tools fail soft
-(a tool missing, Postgres down, empty retrieval).
-
-#### Client adapters and automation modes
-
-Each client gets one explicit mode — who drives retrieval and capture:
-
-| Mode | Rules block | Hooks | Who calls `context_pack` / `context_after_turn` |
-| --- | --- | --- | --- |
-| `agent` | agent-driven | removed | the model, as the rules instruct |
-| `hooks` | hook-driven | installed | the hooks; the rules tell the model **not** to repeat them |
-| `mcp-only` | removed | removed | nobody automatically — tools are just available |
-| `lean` | removed | lean hook | nobody — no MCP server; the hook injects up to 3 ranked file pointers (claude, opencode, hermes) |
-
-```bash
-codebuddy clients list                          # surfaces, lifecycle coverage, mode in this repo
-codebuddy clients install claude --mode hooks   # CLAUDE.md + .claude/settings.json + .mcp.json
-codebuddy clients install opencode --mode hooks # AGENTS.md + .opencode/plugins/codebuddy.js + opencode.json
-codebuddy clients install hermes --mode hooks --global # + .hermes/plugins/codebuddy/ + ~/.hermes/config.yaml
-codebuddy clients install claude --mode lean    # lean hook only + index build; no rules block, no MCP
-codebuddy clients uninstall opencode            # removes only CodeBuddy's entries
-codebuddy clients verify [client]               # installed vs verified host version, no-model conformance checks
-codebuddy clients cost                          # measured per-turn token cost per client and mode
-```
-
-| Client | Rules | MCP config | Lifecycle hooks | Verified host |
-| --- | --- | --- | --- | --- |
-| Claude Code | `CLAUDE.md` | `.mcp.json` | prompt, edit, turn-end, compaction | 2.1.287 |
-| Codex | `AGENTS.md` | global `~/.codex/config.toml` (`--global`) | missing | 0.163.0 |
-| OpenCode | `AGENTS.md` | `opencode.json` or `opencode.jsonc` (`mcp`, local) | prompt, edit, turn-end, compaction (plugin) | 1.18.32 |
-| Freebuff | `AGENTS.md` | `.agents/mcp.json` | missing: no hook config, SDK `run_file_change_hooks` is a no-op | source `f9ae64dd` |
-| Hermes Agent | `AGENTS.md` | global `~/.hermes/config.yaml` (`--global`) | prompt, edit, turn-end, compaction (plugin) | 0.17.0 |
-
-Global MCP configs are only written with `--global` (install and uninstall),
-and only CodeBuddy's `codebuddy-<namespace>` entry is touched. Codex reuses the
-`codebuddy codex install` writer. Hermes gets a line-scoped edit of
-`mcp_servers` (`HERMES_HOME` is honoured): every other line and comment stays
-byte-for-byte, and a file whose shape can't be edited safely (flow map,
-invalid YAML) is left alone with a manual step.
-
-`clients verify` runs `<host> --version` and, where the host is installed,
-`claude mcp get`, `opencode debug config`, `codex mcp list --json` and
-`hermes mcp list`, plus the Hermes plugin gates. It never calls a model and
-reports a missing host or a failing command instead of failing.
-
-`hook-driven` is only offered where CodeBuddy wires every lifecycle event, so a
-turn is never half-automated. Clients sharing `AGENTS.md` share one managed
-block. `codebuddy rules install` without `--mode` and `codebuddy use` follow the
-installed hooks, and `hooks install|uninstall` switch an existing block, so the
-two paths never both retrieve and capture. `clients list` warns if they do.
-While OpenCode hooks are installed the shared `AGENTS.md` block stays
-hook-driven; it tells agents without hooks to use the agent-driven flow.
-
-The OpenCode plugin forwards `chat.message` (context appended to the prompt as a
-synthetic text part), `tool.execute.after` for `edit`/`write`/`apply_patch`/`patch`,
-`session.idle` and `session.compacted` to the same `codebuddy hooks` runtime.
-It never overwrites a `codebuddy.js` it did not write. A commented
-`opencode.json(c)` is never rewritten: install prints the entry to add by hand.
-
-The Hermes plugin (`.hermes/plugins/codebuddy/`, Python) forwards `pre_llm_call`
-(the block is returned as `{"context": ...}`), `post_tool_call` for
-`write_file`/`patch` (paths and V4A headers only, never file content) and
-`terminal` exit codes, `post_llm_call` (capture summary) and `on_session_end`
-(capture) to the same runtime. Hermes adds plugin context to the current turn
-only and never stores it, so the bridge asks for the full block every turn and
-resets the session ledger with it. That reset also covers compaction, which
-has no plugin hook. Hermes loads project plugins only with
-`HERMES_ENABLE_PROJECT_PLUGINS=1` and `codebuddy` listed under `plugins.enabled`
-in `~/.hermes/config.yaml`. `hermes plugins enable` rejects project plugins,
-so add that entry by hand. `clients verify hermes` checks both.
-
-Per-turn CodeBuddy cost, measured by `codebuddy clients cost` on this repo
-(cl100k tokens). "1st" is the first prompt of a session; "later" is a later
-prompt with nothing changed:
-
-| Client | Mode | Rules | MCP `tools/list` | Hook block 1st / later | Turn 1st / later |
-| --- | --- | --- | --- | --- | --- |
-| Claude Code | agent | 696 | 3419 | 0 / 0 | 4115 / 4115 |
-| Claude Code | hooks | 660 | 3419 | 162 / 141 | 4241 / 4220 |
-| Codex, OpenCode, Freebuff, Hermes | agent | 703 | 3419 | 0 / 0 | 4122 / 4122 |
-| OpenCode | hooks | 667 | 3419 | 162 / 141 | 4248 / 4227 |
-| Hermes Agent | hooks | 667 | 3419 | 162 / 162 | 4248 / 4248 |
-
-The rules block, the `tools/list` payload and the hook block are measured.
-The hook block depends on the repo's memory and is capped at 1,800 characters.
-In agent mode, the cost of the tool results depends on which tools the model
-calls (see `npm run eval:savings`).
-
-How each host frames these costs:
-
-- **Claude Code.** Adds the hook output to the prompt with its own wrapper,
-  and may defer MCP schemas behind tool search. Neither is measured here.
-- **OpenCode.** Appends the block unchanged as a synthetic text part that
-  stays in history.
-- **Hermes.** Appends the block to the user message with `\n\n` (checked in
-  the source), and resends it every turn. `hermes prompt-size --json`,
-  measured on 0.17.0, shows the `AGENTS.md` context section at 3,070 bytes for
-  a 2,960-byte file: 110 bytes of framing on every turn. It doesn't count MCP
-  tools.
-- **Freebuff.** Sends `AGENTS.md` as a fenced block under a fixed header,
-  according to the source.
-
-### 12. Fully automatic mode (hooks)
-
-Templates *ask* the agent to call the tools. **Hooks guarantee it** — CodeBuddy
-wires into Claude Code's lifecycle so recall and capture fire deterministically,
-whether or not the model remembers to.
-
-```bash
-codebuddy hooks install --client claude    # → .claude/settings.json (idempotent)
-codebuddy hooks install --client opencode  # → .opencode/plugins/codebuddy.js
-codebuddy hooks status --client claude
-codebuddy hooks uninstall --client claude  # removes only CodeBuddy's hooks
-```
-
-- `UserPromptSubmit` → inject compact project context into every prompt (**recall**)
-- `PostToolUse(Edit|Write|MultiEdit)` → record the changed files
-- `Stop` → capture durable memory from the real change set + transcript (**capture**),
-  and write a worklog handoff including the test/lint/typecheck/build commands run
-  that turn and whether they passed
-- `SessionStart(compact|clear)` → forget which context was already sent, so the
-  next prompt resends it in full (re-run `codebuddy hooks install` to add this to
-  an existing install)
-- `PreToolUse(Read|Grep)` → **tool guard**: a Read of a file over 1,000 lines or 80 KB
-  with no `offset`/`limit` is answered with an outline (symbols or headings with line
-  ranges) and a hint to read a range or Grep; a content Grep without `head_limit`
-  gets `head_limit: 100`. It never grants permission, and any ranged Read passes.
-  Lean mode installs it too. `CODEBUDDY_TOOL_GUARD=0` turns it off.
-
-Installing hooks switches an existing managed rules block to hook-driven mode
-(and uninstalling switches it back), so the model is not also told to call
-`context_pack` / `context_after_turn`. The injected block names its `session`;
-MCP calls that pass it as `sessionId` share the hook ledger, so a compaction
-reset makes both paths resend in full.
-
-Set this up once and you never call `remember`/`recall` — it happens on its own.
-Hooks are fail-soft (a hook never breaks a turn) and capture still runs through
-the same confidence + sensitivity gating. Restart Claude Code after installing.
-
----
-
-## How CodeBuddy saves tokens vs. a big knowledge graph
-
-A popular alternative is to build a **whole-repo knowledge graph** (GraphRAG
-style): parse every file into nodes and edges, cluster them, and retrieve
-subgraphs to answer questions. That's great for *exploration* ("how does X
-connect to Y across the codebase?"). It is expensive for *day-to-day editing*.
-
-The difference in one line: **a graph models the entire repo; CodeBuddy models
-just the change in front of you.**
-
-| | Whole-repo knowledge graph | CodeBuddy context engine |
-|---|---|---|
-| Unit | thousands of nodes + edges | a few file "capsules" + the active plan/risk |
-| What the LLM sees | a retrieved subgraph (size varies, can be large) | a **bounded, budgeted** payload with `explain[]` |
-| Scope | the whole project | target files + their direct import neighbours |
-| Build cost | LLM extraction over every file (tokens $$) | deterministic hashes + summaries (no LLM) |
-| Freshness | re-extract on change (often another LLM pass) | incremental hash diff, milliseconds |
-| Measurability | hard to say what a query "cost" | every payload reports its size against its budget; savings are measured in billed A/B runs |
-
-Concretely, for a change touching `src/auth/oauth.ts`:
-
-- **Graph approach:** to be safe, retrieval pulls the auth community — many
-  nodes, their neighbours, and descriptions — and drops a large subgraph into
-  context. The token cost scales with how big and connected that region is.
-- **CodeBuddy:** sends the file's one-line summary + exported symbols, its direct
-  import neighbours, the matching policy rule, any past incident, and the active
-  plan — then **packs it into a token budget, keeping the highest-value evidence
-  first.** If it doesn't fit, low-value context is dropped (and reported), never
-  the risk finding.
-
-Why it saves tokens: a file capsule such as
-`"ts • 42 lines • exports login, verify"` points the agent at the right file, so
-it spends fewer steps searching. Every step re-sends the conversation, so fewer
-steps is where the saving comes from; see
-[measured token use](#8-measured-token-use).
-
-The honest caveats:
-
-- These are **complementary tools.** Use a knowledge graph to *understand* an
-  unfamiliar codebase; use CodeBuddy to *edit* one efficiently and safely.
-- Savings depend on the task: in the A/B study they ranged from −43% to +16%
-  tokens per task.
-- CodeBuddy does **not** try to answer arbitrary cross-repo questions; that's
-  what the graph is for.
-
----
-
-## MCP tools reference
-
-CodeBuddy ships tools over stdio (`codebuddy serve`). HTTP transport is deferred.
-
-| Tool | Input | Output |
-|---|---|---|
-| `remember` | `{ sessionId?, content, type?, idempotencyKey?, agentId? }` | `{ id, sessionId, deduplicated }` |
-| `remember_batch` | `{ items: [...] }` | `{ items: [...] }` |
-| `recall` | `{ sessionId, query, budget?, callerModel?, conflictMode? }` | `{ system, messages, stats }` |
-| `list_facts` | `{ subject?, limit?, cursor? }` | `{ facts[], nextCursor? }` |
-| `list_namespaces` | `{}` | `{ namespaces[] }` |
-| `forget` | `{ id }` | `{ ok, entityType }` |
-| `share` | `{ to_namespace, factIds, mode?, to_project_root?, agentId? }` | `{ shared }` |
-| `unshare` | `{ to_namespace, factIds, agentId? }` | `{ revoked }` |
-| `plan_current` | `{}` | `{ plan, policy }` |
-| `plan_create` / `plan_amend` / `plan_status` | plan fields | `{ plan }` |
-| `risk_assess` | `{ planId?, paths?, useGit?, limit? }` | `{ items, stats }` |
-| `map_query` / `map_neighbours` | graph query | edges / `{ modules, edges }` |
-| `context_bootstrap` | `{ sessionId?, ack?, full? }` | `{ project, plan, policy, policyRules, incidents, facts, handoffs, architecture, tokens, delivery? }` |
-| `context_before_edit` | `{ task?, paths?, planId?, useGit?, tokenBudget?, sessionId?, ack?, full? }` | `{ targetPaths, plan, policyRules, incidents, facts, handoffs, risks, neighbours, symbols, diffs, tokens, delivery? }` |
-| `context_pack` | `{ task, paths?, planId?, useGit?, tokenBudget?, sessionId?, ack?, full? }` | same as `context_before_edit` |
-| `context_after_turn` | `{ summary, changedFiles?, planId?, taskType?, agentId?, sessionId?, verification?, commitSha? }` | `{ saved, queuedForReview, ignored, reasons, extractor, worklogId }` |
-| `code_suggestions` | `{ paths?, planId?, useGit?, limit? }` | `{ suggestions, stats }` |
-| `health` | `{}` | `{ database: { available, state, error?, retryInMs? }, tools: { profile, file, database } }` |
-
-**Tool profiles.** Every tool definition costs schema tokens in each session
-(3,419 tokens for all 21). Set `CODEBUDDY_TOOL_PROFILE=core` in the MCP server's
-environment to list only the automatic context workflow — `context_pack`,
-`context_bootstrap`, `context_before_edit`, `context_after_turn`,
-`code_suggestions` and `health` — for 1,261 tokens. `full` (the default) lists
-everything; any other value fails at startup. In a client's MCP config:
-
-```json
-{ "mcpServers": { "codebuddy": { "command": "codebuddy", "args": ["serve"],
-  "env": { "CODEBUDDY_TOOL_PROFILE": "core" } } } }
-```
-
-(Codex: `CODEBUDDY_TOOL_PROFILE = "core"` under `[mcp_servers."<name>".env]`.)
-Use `full` when the agent should call `recall`, `remember`, plans or map tools
-directly; hooks and the CLI are unaffected.
-
-If PostgreSQL is unreachable the server still starts: file-based tools work and
-the database tools return `{ degraded: true, tool, database, fallback }` with
-`isError` until a later call reconnects (see [docs/degraded-mode.md](docs/degraded-mode.md)).
-
-**Session-aware delivery (contract v1).** The three context tools accept an
-optional `sessionId`. The response then carries `delivery: { version, sessionId,
-deliveryId, ack, unchanged, avoidedTokens, note }`. Pass that `deliveryId` as
-`ack` on your next call; sections you acknowledged and that have not changed
-(`plan`, `policyRules`, `incidents`, `facts`, `handoffs`, `architecture`,
-`symbols`, `neighbours`) are then omitted and named in `delivery.unchanged`.
-Target paths, risks and diffs are always sent. The last 8 acknowledged
-versions of each section are remembered, so switching back to an earlier task
-in the same session does not resend what you already hold. Nothing counts as
-seen until it is acknowledged, acknowledged sections are resent after 30
-minutes, and `full: true` resends everything and forgets every earlier
-acknowledgement. Without `sessionId` the payload is complete and
-unchanged from earlier versions.
-
-**Cross-chat handoffs.** Turns captured via `context_after_turn` or the Stop
-hook that changed files, saved memory or report verification write a bounded
-Markdown entry to `.codebuddy/worklog/`. Context tools return relevant entries
-as `handoffs` with freshness (`changedSince`, `missing`). Inspect them with
-`codebuddy worklog list|show|latest`.
-
-Wire it into a client with `codebuddy use`, or a project `.mcp.json` (see
-[CLAUDE_CODEX.md](CLAUDE_CODEX.md)).
-
----
-
-## SDK usage
-
-`createRuntime` wires the Postgres repository, initializes `CodeBuddy`, and
-returns a `close()` hook that drains the worker and closes the client.
-
-```ts
-import { createRuntime } from "codebuddy";
-
-const runtime = await createRuntime({
-  postgresUrl: process.env.DATABASE_URL!,
-  provider: { type: "huggingface", apiKey: process.env.HF_TOKEN },
-  namespace: "research-agent",
-  tokenBudget: 8000,
-});
-
-await runtime.memory.remember({
-  sessionId: "sess_123",
-  content: "Use layer caching for the Docker build.",
-  type: "fact",
-});
-
-const context = await runtime.memory.recall({
-  sessionId: "sess_123",
-  query: "What do we know about deployment?",
-  budget: 6000,
-});
-
-await runtime.close();
-```
-
-Notes: `remember` defaults to `type: "interaction"`; repeated writes with the
-same idempotency key or content return `deduplicated: true`; embeddings are
-prepared asynchronously and recall falls back to recency plus lexical matches
-over durable facts while vectors are pending or the provider is unavailable.
-
----
-
-## LangGraph
-
-```ts
-import { CodeBuddyNode, CodeBuddyCheckpointer } from "codebuddy/langgraph";
-
-const graph = new StateGraph(State)
-  .addNode("recall", new CodeBuddyNode({ memory, mode: "recall", cacheTtlSeconds: 30 }))
-  .addNode("agent", agentNode)
-  .addNode("remember", new CodeBuddyNode({ memory, mode: "remember" }))
-  .compile({ checkpointer: new CodeBuddyCheckpointer({ namespace: "research-agent" }) });
-```
-
-Recall caching defaults to 30s, keyed by `(namespace, sessionId, query)`.
-`CodeBuddyCheckpointer` keeps checkpoints and pending writes in process memory.
-It preserves parent history and separates LangGraph checkpoint namespaces, but
-state is lost when the process exits. Use a durable LangGraph checkpointer when
-resume across restarts is required.
-
----
-
-## Working as a team
-
-CodeBuddy is built so teammates share project knowledge without sharing secrets.
-
-`codebuddy use` / `codebuddy init` create this scaffold:
-
-```text
-.codebuddy/
-├── .gitignore          # keeps config, cache, locks, and review queue out of git
-├── config.json         # LOCAL ONLY — never commit (your DB URL + token)
-├── policies.yaml        # commit: shared "handle with care" rules
-├── memory/
-│   ├── facts/          # commit: reviewable Markdown facts
-│   ├── summaries/      # commit: reviewable summaries
-│   └── review/         # local: un-approved candidates
-├── plans/              # commit: shared work plans
-└── cache/index.json    # local: rebuildable index
-```
-
-- **Commit** `memory/facts`, `memory/summaries`, `plans/*.md`, and
-  `policies.yaml` to share memory, plans, and policy with the team.
-- **Never commit** `config.json` — each teammate runs `codebuddy use` locally
-  with their own token and database.
-- One namespace per project (`codebuddy use my-project`); use the `share` tool to
-  explicitly hand facts between namespaces.
-- If project memory is private, add `.codebuddy/memory/` to the repo `.gitignore`.
-
-New collaborator quickstart:
-
-```bash
-git clone <repo> && cd <repo>
-npm install -g @orquentra/codebuddy
-codebuddy use <project>      # local DB + migrations + client wiring
-codebuddy index
-codebuddy rules install --client claude
-codebuddy context bootstrap  # sanity-check what the agent will see
-```
-
----
-
-## Repo layout (for contributors)
-
-```text
-src/
-├── core/            config, Markdown stores, plan lifecycle, runtime
-├── db/              Drizzle schema, migrations, client
-├── mcp/             stdio server + tool registration (Zod schemas)
-├── risk/            evidence-backed risk assessor + signals (no LLM)
-├── map/             import-graph architecture map
-├── context/         [04.2] context bootstrap + before-edit engine
-├── indexer/         [04.3] scan, summaries, incremental index, watch
-├── memory-extract/  [04.4] auto-capture, sensitivity scan, review queue
-├── savings/         [04.5] token estimator and budget-aware packer
-├── suggest/         [04.6] read-only suggestion engine
-├── templates/       [04.7] client workflow templates + safe install
-├── planner/ providers/ langgraph/
-└── cli/             commander CLI (commands/*)
-```
-
-Dev workflow (see [CLAUDE.md](CLAUDE.md) for agent-oriented notes):
-
-```bash
-npm run typecheck     # tsc --noEmit (strict)
-npm run lint          # biome check .  (npx biome check --write . to fix)
-npm test              # vitest (one integration test skips without Postgres)
-npm run build         # tsup → dist/
-```
-
----
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| `password authentication failed` | `DATABASE_URL` needs `user:password`; use the bundled DB URL or `codebuddy use`. File tools are unaffected. |
-| `namespace ... differs from folder default` | Run `codebuddy use <name>` or set `CODEBUDDY_NAMESPACE`. |
-| `model ... unknown` in doctor | No HF token / model check skipped — informational, not a failure. |
-| Facts/vectors are empty after setup | Restart the MCP server once; startup imports existing Markdown memory and the embedding worker then processes pending vectors. Check `codebuddy doctor` for provider/database errors. |
-| Client doesn't show CodeBuddy tools | Confirm MCP registration (`codebuddy claude list` / `codebuddy codex list`) and restart the client. |
-| `plan list` errors on this repo | Its `.codebuddy/plans/` holds hand-written docs, not generated plans — test plan/context features in a clean scaffold. |
-
-`codebuddy doctor` reports DB connectivity, pgvector, vector/index health, model
-reachability, recent usage, and config permissions.
-
----
-
-## Privacy
-
-- Facts, summaries, and plans are plaintext Markdown — inspect before committing.
-- Conversations, telemetry, and indexes live in PostgreSQL. Reference shares are also
-  recorded in the source fact's `sharedWith` front matter; snapshots are fact files in
-  the target project.
-- `context_after_turn` never auto-saves sensitive content (keys, tokens,
-  credentials, emails); such items are flagged and queued for review.
-- For private memory, add `.codebuddy/memory/` to `.gitignore`.
-- The optional BYOK small model (`codebuddy llm enable`) sends file paths, signatures,
-  short summaries and your task text to the provider you choose; see
-  [docs/llm-byok.md](docs/llm-byok.md). It's off unless you enable it with your own key.
-- Encryption at rest is the deployment owner's responsibility.
+Previously published as
+[`@ayushkumar320/codebuddy`](https://www.npmjs.com/package/@ayushkumar320/codebuddy),
+which retains the historical releases and download records.
 
 ## License
 
-MIT © Agentic Office — see [LICENSE](LICENSE).
-
-**Project docs:** start at the [docs index](docs/README.md).
-[current-version.md](docs/current-version.md) (what ships today + how automatic
-it really is) · [roadmap.md](docs/roadmap.md) (what's left to build) ·
-[improvements.md](docs/improvements.md) (quality/robustness backlog) ·
-[live-test-checklist.md](docs/live-test-checklist.md) (pre-release verification) ·
-[migration-2.0.md](docs/migration-2.0.md) · [degraded-mode.md](docs/degraded-mode.md) ·
-[CLAUDE_CODEX.md](CLAUDE_CODEX.md).
-
-### Context quality and delivery cost
-
-Workflow installs now select `CODEBUDDY_TOOL_PROFILE=core`; set it to `full` in
-that client's server environment when direct memory, plan or map tools are needed.
-Manually configured servers are unaffected until reinstalled; reinstalling a workflow selects core again.
-
-For clients that forward both MCP text and structured output to the model,
-`CODEBUDDY_RESPONSE_FORMAT=text` sends the same complete JSON once as text.
-The default `both` preserves existing structured consumers. Verify your host's
-rendering before selecting text mode. This changes delivery representation, not
-which evidence is selected or the compact-JSON budget contract.
-
-Prefer sufficient task evidence over the smallest possible payload. Reuse context
-already delivered; read missing bodies before editing, and narrow the request or
-increase its budget when safety evidence is omitted. Lean remains optional.
-
-### Requesting deeper task evidence
-
-`context_pack` and `context_before_edit` accept `evidence: "source"` when the
-initial short excerpt omits behavior you need to inspect. Pass the known paths
-and task. Source mode returns up to 40 lines / 1,800 characters per selected span
-with a global 5,400-character excerpt ceiling; the existing final token budget
-still applies. Truncated excerpts remain labelled. The default is `overview`.
-
-Task packs use compatible semantic fact scores when the MCP server's database is
-already ready, with a 350 ms deadline and lexical fallback. File-only operation
-and hook processes remain available without a database. Facts are filtered through
-the current Markdown eligibility rules before any semantic scores are applied.
-
-Graphs generated with `codebuddy graphify index` now include a source-hash
-snapshot beside the graph. Source hashes are captured before extraction; changed
-endpoints are excluded even if timestamps are restored. Regenerate older graphs
-to enable this check; unstamped legacy graphs retain the timestamp fallback.
+MIT. Copyright © 2026 Orquentra Inc.