vouchdev · Copilot · Jun 21, 2026 · Jun 26, 2026 · Jun 21, 2026 · Jul 1, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,18 +6,33 @@ All notable changes to vouch are documented here. Format follows
 
 ## [Unreleased]
 
-## [1.2.2] — 2026-07-07
+### Added
+- `kb.triage_pending` — advisory triage scoring over the pending-review queue.
+  Scores each pending proposal on fit, citation quality, duplication risk, and
+  contradiction risk, then attaches a `_meta.vouch_triage` block
+  (`recommendation`, `score`, `signals`, `rationale`) to help a reviewer
+  prioritize a long `kb.list_pending`. Read-only and advisory only: it never
+  calls `kb.approve` / `kb.reject` and never moves a proposal out of pending —
+  a human still decides. Duplication and fit reuse the propose-time embedding
+  similarity path and degrade to a `difflib` heuristic when the `[embeddings]`
+  extra isn't installed. Opt-in via `triage.enabled: true` in `config.yaml`.
+  `vouch triage [proposal-id...]` mirrors it on the CLI with `--json` and
+  `--reverse` (#322).
+- mcp now serves a **minimal tool profile by default** (8 core tools)
+  instead of the full 58-method surface; widen with
+  `VOUCH_TOOL_PROFILE=standard|full` or `mcp.tool_profile` in
+  `config.yaml`. approve/reject and maintenance tools live in
+  `standard`/`full` — they stay human/cli actions, not agent defaults.
+  the jsonl and cli surfaces are unaffected; all 58 methods remain
+  reachable there.
+- per-prompt auto-recall: the claude-code adapter's `UserPromptSubmit`
+  hook (`vouch context-hook`) injects relevant kb context on every
+  prompt, so recall no longer depends on the agent remembering to ask.
 
-### Packaging
-- published to the mcp registry (`registry.modelcontextprotocol.io`, mirrored
-  at `github.com/mcp/vouchdev/vouch`) as `io.github.vouchdev/vouch`. a
-  `server.json` at the repo root carries the metadata; the pypi `vouch-kb`
-  package is the artifact, run over stdio via `uvx vouch-kb serve`.
-- `vouch-kb` console-script alias (alongside `vouch`) so `uvx vouch-kb serve`
-  resolves — the registry launches a package by its pypi identifier, which
-  otherwise wouldn't match the `vouch` script name.
-- README carries an `<!-- mcp-name: io.github.vouchdev/vouch -->` marker;
-  the registry verifies package ownership by matching it against `server.json`.
+### Changed
+- retrieval `auto`/`hybrid` now **fuses embedding + fts5** results via
+  reciprocal rank fusion instead of a waterfall (embedding-first,
+  fts5-fallback), with near-duplicate suppression over the fused list.
 
 ## [1.2.1] — 2026-07-06
 
@@ -111,6 +126,14 @@ All notable changes to vouch are documented here. Format follows
 ## [1.1.0] — 2026-07-03
 
 ### Added
+- `kb.diff` — `vouch diff <id-old> <id-new>` (0.1.0) now has full `kb.*`
+  parity: an MCP tool and a JSONL `kb.diff` handler alongside the existing
+  CLI, registered in `capabilities.METHODS` like every other read method.
+  `<id-new>` is now optional for a claim: omitting it resolves the diff
+  against `superseded_by`, with a clear error when the claim has no
+  successor (pages still require an explicit `new_id` — they have no
+  successor pointer). Read-only throughout; still no writes, proposals, or
+  audit events (#327).
 - auto-capture: claude code sessions are harvested via hooks and filed as a
   single pending session-summary proposal for human approval. a `PostToolUse`
   hook (`vouch capture observe`) appends compact tool-use observations to an
@@ -212,6 +235,12 @@ All notable changes to vouch are documented here. Format follows
   temporary copied home containing known Claude/Codex credential files, so agent
   writes stay in the throwaway dual-solve branches and host credential files are
   not modified.
+- dual-solve JSON, review-ui job, and choose responses now include
+  `changed_files` for each candidate and the kept branch, so desktop and browser
+  clients can show the resulting files without parsing unified diffs.
+- dual-solve JSON and review-ui job responses now include each engine's returned
+  output log plus a deterministic recommendation hint based on success and diff
+  scope, so clients can compare Claude and Codex results before choosing.
 - `vouch review-ui --allow-dual-solve` — a browser SPA that runs `dual-solve`
   on a github issue link, streams progress over the review-ui's websocket, shows
   both engines' diffs side by side, and lets you pick the winner. Off by default;
@@ -234,6 +263,7 @@ All notable changes to vouch are documented here. Format follows
   New `vouch schema list` and `vouch schema sync` commands inspect declared
   kinds and audit existing pages against them; `propose-page` gains `--kind`
   and repeatable `--meta key=value`.
+- `kb.capabilities` now reports a `host_compat` block mirroring the `openclaw.compat` constraints declared in `openclaw.plugin.json` (e.g. `pluginApi`), so non-OpenClaw clients can detect compat without parsing the manifest. A new test asserts the two stay in sync and fails CI on drift (#237).
 - `kb.synthesize` — answer-mode retrieval over the review-gated KB. Answers a
   query in prose from approved claims only, with an inline `[claim_id]`
   citation behind every sentence, an explicit `gaps` block listing query
@@ -266,13 +296,16 @@ All notable changes to vouch are documented here. Format follows
   KB under `eval/fixture-kb/`, and an `eval` workflow gating retrieval changes
   (#226).
 ### Fixed
+- `Claim.text`, `Entity.name`, and `Page.title` now reject empty / whitespace-only values at the model layer via `@field_validator`s, mirroring the `Claim.evidence` min-citation validator (#81/#82). The non-empty contract previously lived only in the `propose_*` helpers, so `store.put_*`, `store.update_*`, and bundle/sync import all silently accepted blank-content artifacts; enforcing on the model closes every write path at once (fixes #155).
 - `parse_since` (the `--since` parser behind `vouch metrics`/`vouch audit`) now raises a clean `MetricsError` for a duration too large to represent (e.g. `--since 1000000000000d`), instead of letting an uncaught `OverflowError` traceback escape — restoring the documented "clean error, not a traceback" contract.
 - `sync_apply` now loads the sync source exactly once and passes the same `_SyncSource` instance into `sync_check`, closing a TOCTOU window where a bundle replaced on disk between the two `_load_source` calls could cause the validation and write phases to operate on different snapshots. Also eliminates redundant directory walks (KB sources) and triple tarball opens (bundle sources). Fixes #217.
 - `vault_to_kb` now passes `slug_hint=page_id` to `propose_page` so vault edit proposals target the existing page id from frontmatter instead of a slugified copy of the title (fixes #219).
 - `vault_to_kb` skips mirror files whose page no longer exists in the KB, preventing ghost-page proposals that would fail on approve (fixes #219).
 - `vault_to_kb` skips filing a second proposal when a pending proposal already targets the same page id (with differing body), preventing duplicate proposals on repeated sync runs before approval (fixes #219).
 - `vault_to_kb` now warns when a user edits a claim stub instead of silently dropping the edit, directing the user to edit the citing page instead, and reports it via the dedicated `claim_stubs_edited` field on `VaultSyncResult` (fixes #219).
 - `approve()` now supports updating an existing page via `KBStore.update_page` when a PAGE proposal's id matches an existing artifact (the vault-edit flow), instead of raising `cannot approve: page already exists` for every vault edit (fixes #219).
+- `crystallize()` now updates an existing session summary page on retry instead of
+  failing with `page session-... already exists` after a partial approval run (#139).
 
 ### Fixed
 - `vouch serve` now fails fast with a clear `vouch init` hint when no `.vouch/` KB is present, instead of starting a server that immediately misbehaves (#95).

diff --git a/README.md b/README.md
@@ -61,7 +61,7 @@ vouch init
 vouch install-mcp claude-code
 ```
 
-`init` creates `.vouch/` with a starter config; `install-mcp` writes `.mcp.json` (the `kb.*` MCP tools), the `/vouch-*` slash commands, and three hooks — `PostToolUse` capture, `SessionEnd` rollup, `SessionStart` recall. Restart Claude Code so they load.
+`init` creates `.vouch/` with a starter config; `install-mcp` writes `.mcp.json` (the `kb.*` MCP tools — a lean default surface you can widen with `VOUCH_TOOL_PROFILE`), the `/vouch-*` slash commands, and four hooks — `PostToolUse` capture, `SessionEnd` rollup, `SessionStart` recall, and `UserPromptSubmit` per-prompt context injection. Restart Claude Code so they load.
 
 **2. Point `compile` at an LLM** — the only step that needs a model. In `.vouch/config.yaml`:
 
@@ -125,6 +125,8 @@ Detection is Claude Code's hook contract: whatever a `SessionStart` hook prints
 
 Only approved artifacts are ever emitted — archived, superseded, and still-pending items are excluded — and the digest is size-guarded (`recall.max_chars`) with an explicit truncation notice.
 
+Recall isn't only a session-start event anymore: a `UserPromptSubmit` hook runs `vouch context-hook` on *every* prompt, fusing the most relevant approved claims and pages for what you just asked and injecting them with zero tool calls — so the model sees relevant knowledge even when the agent doesn't think to look it up.
+
 How the approved pages actually get used from there: recall carries the *titles*, and the session pulls full content on demand through the `kb.*` MCP tools — `kb_search` matches page bodies, `kb_read_page` returns a page's markdown plus the claims it cites, and `kb_context` bundles the most relevant claims and pages for a stated task. To pull a topic in explicitly, use the `/vouch-recall <topic>` slash command, or just ask Claude to check the KB. One thing to know: pages still sitting in `vouch review` are invisible to all of this — the gate applies to retrieval too, so a compiled page only starts informing sessions once you approve it.
 
 **7. Commit the knowledge with the code.**

diff --git a/adapters/README.md b/adapters/README.md
@@ -10,7 +10,7 @@ file you need into your project and edit it.
 |---|---|---|
 | [claude-code/](claude-code/) | Anthropic's Claude Code CLI | `.mcp.json` snippet, `CLAUDE.md` excerpt |
 | [cursor/](cursor/) | Cursor IDE | `mcp.json` snippet |
-| [codex/](codex/) | OpenAI's Codex CLI | `config.toml` snippet |
+| [codex/](codex/) | OpenAI's Codex CLI | tiered install: `.codex/config.toml` merge, `AGENTS.md` excerpt, skills, capture hook |
 | [continue/](continue/) | Continue.dev | `config.json` snippet |
 | [openclaw/](openclaw/) | OpenClaw plugin host | `.openclaw/plugins.json`, `AGENTS.md` excerpt |
 | [generic-mcp/](generic-mcp/) | Any MCP-speaking host | annotated reference |

diff --git a/adapters/claude-code/.claude/settings.json b/adapters/claude-code/.claude/settings.json
@@ -43,6 +43,18 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "comment": "inject KB context relevant to THIS prompt (per-prompt auto-recall, 0 tool calls); never blocks the turn",
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "vouch context-hook || true"
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "*",

diff --git a/adapters/claude-code/README.md b/adapters/claude-code/README.md
@@ -112,3 +112,6 @@ To upgrade or check your extension version, see [Claude Code releases](https://g
   (`kb_supersede`, `kb_contradict`, …) without you asking each time,
   add: "When you find a stale claim, supersede it rather than
   proposing a contradicting one."
+- Only a core set of `kb_*` tools is visible by default (`mcp.tool_profile:
+  minimal` in `.vouch/config.yaml`, or the `VOUCH_TOOL_PROFILE` env var).
+  Set it to `standard` or `full` to expose lifecycle/admin tools.
diff --git a/adapters/codex/AGENTS.md.snippet b/adapters/codex/AGENTS.md.snippet
@@ -0,0 +1,31 @@
+# Vouch — knowledge base
+
+This repo uses **vouch** for durable agent knowledge. The KB lives in
+`.vouch/` and is reviewed in PRs like any other code.
+
+## How to remember things
+
+To preserve a fact, decision, or workflow across sessions:
+
+1. Register evidence: `kb_register_source` (or
+   `kb_register_source_from_path` for a file).
+2. Propose a claim that cites it: `kb_propose_claim`. Every claim
+   MUST cite at least one source or evidence id.
+3. For richer write-ups, propose pages: `kb_propose_page` with a
+   markdown body that references claims.
+
+You **cannot** write durable knowledge directly. Proposals land in
+`.vouch/proposed/` and require human approval via `vouch approve`.
+This is intentional.
+
+## How to read
+
+- `kb_search` for keyword search.
+- `kb_context` to fill a working set for a task ("what does this KB know
+  about X?").
+- `kb_read_*` for specific ids.
+
+## Identity
+
+Set `VOUCH_AGENT=codex` in your env (or the MCP entry's `env:` block) so the
+audit log can attribute writes to this host.
diff --git a/adapters/codex/README.md b/adapters/codex/README.md
@@ -1,13 +1,86 @@
 # Codex CLI adapter
 
-Wires `vouch serve` into [OpenAI's Codex CLI][codex] as an MCP server.
+Wires vouch into [OpenAI's Codex CLI][codex]: the MCP server, standing
+`AGENTS.md` instructions, the vouch guided flows as skills, and
+automatic session capture.
 
 [codex]: https://github.com/openai/codex
 
-## Setup
+## Install
 
-Codex reads MCP server config from `~/.codex/config.toml`. Add a
-`vouch` entry:
+```bash
+vouch install-mcp codex              # everything (T1–T4)
+vouch install-mcp codex --tier T1    # just the MCP wire
+```
+
+Everything lands in the *project*, never in `~/.codex` — the same
+scope rule every adapter follows. Codex loads project-local `.codex/`
+config for trusted projects, so trust the project when codex asks.
+
+What each tier adds (tiers stack):
+
+| Tier | File | What it does |
+|---|---|---|
+| T1 | `.codex/config.toml` | registers the `vouch` MCP server (`kb_search`, `kb_propose_claim`, …) with `VOUCH_AGENT=codex` for audit attribution |
+| T2 | `AGENTS.md` | fenced snippet with the standing rules: recall first, all writes via proposals, review stays human |
+| T3 | `.codex/skills/vouch-*/SKILL.md` | the nine vouch guided flows as project-local skills |
+| T4 | `.codex/hooks.json` | `Stop` hook that auto-captures each session into a pending, review-gated summary |
+
+The install is idempotent and merge-safe: an existing
+`.codex/config.toml` or `.codex/hooks.json` is deep-merged into (your
+entries always win on conflict), an existing `AGENTS.md` gets the
+snippet appended inside fence markers, and re-runs are a flat no-op.
+
+## Skills (T3)
+
+Codex discovers skills from `<project>/.codex/skills/` in trusted
+projects, so the flows (`vouch-recall`, `vouch-status`,
+`vouch-resolve-issue`, `vouch-propose-from-pr`, plus the company-brain
+set) surface in the session automatically — ask for one by name or let
+codex pick them up from context.
+
+Why skills and not custom prompts: codex loads custom prompts only
+from `~/.codex/prompts/` (user-global) and has deprecated them in
+favour of skills. A project-scoped `vouch install-mcp` never touches
+home-directory state, so skills are the surface vouch ships. If you
+prefer slash-style prompts anyway, copy the installed
+`.codex/skills/*/SKILL.md` bodies into `~/.codex/prompts/<name>.md`
+yourself.
+
+The skill bodies are identical to the claude-code slash commands
+(enforced by a sync test), so the flows behave the same on every host.
+
+## Automatic session capture (T4)
+
+`.codex/hooks.json` registers a `Stop` hook that runs `vouch capture
+ingest-codex --hook` when a turn completes. The handler reads the hook
+payload, resolves the session's rollout file, and rolls it into ONE
+pending session-summary proposal — the same review-gated summary a
+claude-code session produces. Because `Stop` fires per turn, re-ingest
+is idempotent: an unchanged session is a no-op, a session that grew
+refreshes its pending proposal in place, and a proposal you've already
+reviewed is never resurrected.
+
+Failure semantics match `capture observe`: the `--hook` mode exits 0
+no matter what, so a capture problem can never break your codex turn.
+Nothing is auto-approved — review with `vouch review`.
+
+Past sessions can be ingested by hand too:
+
+```bash
+vouch capture ingest-codex --latest        # newest rollout for this project
+vouch capture ingest-codex <rollout.jsonl> # a specific one
+```
+
+Why not codex's `notify` setting: codex honours `notify` only in
+user-global config (`~/.codex/config.toml`), which a project-scoped
+install never touches. If you prefer notify anyway, point it at a
+wrapper that calls `vouch capture ingest-codex --hook` yourself.
+
+## Manual fallback
+
+No installer, or a user-global setup on purpose? Add the entry to
+`~/.codex/config.toml` (or `<project>/.codex/config.toml`) by hand:
 
 ```toml
 [mcp_servers.vouch]
@@ -18,7 +91,8 @@ args = ["serve"]
 VOUCH_AGENT = "codex"
 ```
 
-Restart any running `codex` session.
+Restart any running `codex` session, then confirm with
+`codex mcp list`.
 
 ## Notes
 

diff --git a/adapters/codex/hooks.json b/adapters/codex/hooks.json
@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "vouch capture ingest-codex --hook",
+            "statusMessage": "vouch capture"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/adapters/codex/install.yaml b/adapters/codex/install.yaml
@@ -3,8 +3,49 @@
 # Codex reads `<project>/.codex/config.toml` (also `~/.codex/config.toml` for
 # user-global). We ship the project-local form so `vouch install-mcp codex`
 # doesn't touch home-directory state -- see issue #179 scope decision.
+#
+# `.codex/config.toml` is codex's *primary* config file (model, approval
+# policy, other MCP servers), so T1 deep-merges into an existing one instead
+# of skipping it -- see issue #384. Existing user values always win.
 host: codex
 pretty: OpenAI Codex CLI
+fence:
+  begin: "<!-- BEGIN vouch -->"
+  end: "<!-- END vouch -->"
 tiers:
   T1:
-    - { src: config.toml, dst: .codex/config.toml }
+    - { src: config.toml, dst: .codex/config.toml, toml_merge: true }
+  # T2 = AGENTS.md fenced snippet (codex reads AGENTS.md for project
+  # instructions the way cursor does -- see issue #385). Kept in lockstep
+  # with adapters/cursor/AGENTS.md.snippet modulo the host name.
+  T2:
+    - { src: AGENTS.md.snippet, dst: AGENTS.md, fenced_append: true }
+  # T3 = the vouch guided flows as codex *skills* under the project-local
+  # `.codex/skills/` -- see issue #386. Scope decision recorded here per
+  # that ticket: codex custom prompts load only from ~/.codex/prompts/
+  # (user-global) and are deprecated upstream in favour of skills, and the
+  # #179 rule forbids a project-scoped install from touching home-directory
+  # state, so prompts are out and project-local skills are in. The SKILL.md
+  # files are referenced from the openclaw mirror rather than duplicated;
+  # their bodies are sync-tested against the claude-code commands.
+  T3:
+    - { src: ../openclaw/skills/vouch-recall/SKILL.md, dst: .codex/skills/vouch-recall/SKILL.md }
+    - { src: ../openclaw/skills/vouch-status/SKILL.md, dst: .codex/skills/vouch-status/SKILL.md }
+    - { src: ../openclaw/skills/vouch-resolve-issue/SKILL.md, dst: .codex/skills/vouch-resolve-issue/SKILL.md }
+    - { src: ../openclaw/skills/vouch-propose-from-pr/SKILL.md, dst: .codex/skills/vouch-propose-from-pr/SKILL.md }
+    - { src: ../openclaw/skills/vouch-ask/SKILL.md, dst: .codex/skills/vouch-ask/SKILL.md }
+    - { src: ../openclaw/skills/vouch-remember/SKILL.md, dst: .codex/skills/vouch-remember/SKILL.md }
+    - { src: ../openclaw/skills/vouch-record/SKILL.md, dst: .codex/skills/vouch-record/SKILL.md }
+    - { src: ../openclaw/skills/vouch-followup/SKILL.md, dst: .codex/skills/vouch-followup/SKILL.md }
+    - { src: ../openclaw/skills/vouch-standup/SKILL.md, dst: .codex/skills/vouch-standup/SKILL.md }
+  # T4 = automatic session capture -- see issue #388. codex's hooks system
+  # fires Stop when a turn completes; the handler re-ingests the session's
+  # rollout idempotently (`vouch capture ingest-codex --hook` exits 0 even
+  # on failure, so capture can never break a codex turn), updating the
+  # session's single PENDING summary proposal as the session grows.
+  # hooks live in their own `.codex/hooks.json` file (project-local in
+  # trusted projects) and json_merge preserves any hooks the user already
+  # has. note: the legacy `notify` setting can't be used here -- codex only
+  # honours it in user-global config, which the #179 rule forbids touching.
+  T4:
+    - { src: hooks.json, dst: .codex/hooks.json, json_merge: true }