@orquentra/codebuddy 0.0.0-stage → 2.4.0

package/README.md

@@ -1,3 +1,1119 @@
-# Temporary Holding Version
+# CodeBuddy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**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.
+
+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.
+
+- **npm:** `@orquentra/codebuddy` (v2.4.0)
+- **Surfaces:** CLI · MCP stdio server · TypeScript SDK · LangGraph helpers
+
+`@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:
+
+```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
+```
+
+> 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.
+
+---
+
+## Feature tour (with examples)
+
+### 1. Durable Markdown memory
+
+Facts and summaries are written as Markdown under `.codebuddy/memory/`. They
+survive database loss and are diffable in git.
+
+```bash
+codebuddy list-facts
+codebuddy inspect your-project
+codebuddy export your-project > backup.json
+codebuddy stats
+```
+
+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>
+```
+
+### 3. Risk assessment
+
+Deterministic, evidence-backed risk scoring from incident memory, project
+policy, and recent git churn — no LLM.
+
+```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
+```
+
+### 4. Architecture map
+
+A lightweight import graph, scanned on demand.
+
+```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)
+```
+
+### 5. Background indexing
+
+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.
+
+## 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.