wendkeep 0.85.1 → 0.87.0

package/.githooks/commit-msg

@@ -0,0 +1,16 @@
+#!/bin/sh
+set -eu
+
+CLI=${WENDKEEP_COMMIT_CLI:-}
+if [ -z "$CLI" ]; then
+  if [ -f "./node_modules/wendkeep/bin/wendkeep.mjs" ]; then
+    CLI=./node_modules/wendkeep/bin/wendkeep.mjs
+  elif [ -f "./bin/wendkeep.mjs" ]; then
+    CLI=./bin/wendkeep.mjs
+  else
+    echo "WENDKEEP_COMMIT_CLI_MISSING: install wendkeep or run wendkeep doctor" >&2
+    exit 2
+  fi
+fi
+
+exec node "$CLI" commit validate --message-file "$1" --consume-context

package/.githooks/prepare-commit-msg

@@ -0,0 +1,16 @@
+#!/bin/sh
+set -eu
+
+CLI=${WENDKEEP_COMMIT_CLI:-}
+if [ -z "$CLI" ]; then
+  if [ -f "./node_modules/wendkeep/bin/wendkeep.mjs" ]; then
+    CLI=./node_modules/wendkeep/bin/wendkeep.mjs
+  elif [ -f "./bin/wendkeep.mjs" ]; then
+    CLI=./bin/wendkeep.mjs
+  else
+    echo "WENDKEEP_COMMIT_CLI_MISSING: install wendkeep or run wendkeep doctor" >&2
+    exit 2
+  fi
+fi
+
+exec node "$CLI" commit prepare --message-file "$1" --source "${2:-}" --commit "${3:-}"

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.87.0] — 2026-08-29
+
+### Added
+
+- **Política universal de commits baseada em evidências.** O novo pacote `wendkeep/commit`, a CLI,
+  os hooks Git e o gate de intervalo produzem e validam mensagens determinísticas a partir de
+  autoridade, tarefas, spec, escopo e sensores rederiváveis no checkout exato do commit.
+
+### Security
+
+- **Prova remota limitada ao que o CI consegue rederivar.** Evidências causais locais permanecem
+  não publicadas; alegações remotas indisponíveis, provas circulares, sensores divergentes,
+  adulterações de escopo e caminhos privados falham de modo fechado antes da persistência.
+
+## [0.86.0] — 2026-08-28
+
+### Added
+
+- **Memory ledger bounded para Vaults longos.** Snapshots determinísticos, replay apenas do tail,
+  segmentos imutáveis com manifest encadeado e rotação/compactação transacional preservam a
+  autoridade append-only, com dry-run, journal, receipt, recovery e benchmarks sintéticos de
+  100 mil eventos.
+- **Recall incremental, paginado e indexado.** Estado por documento/chunk, cursor vinculado ao
+  índice/consulta/filtros/`as_of`, budgets UTF-8 exatos, sidecar lexical bounded e SQLite FTS5
+  opcional evitam scans integrais sem transformar artefatos derivados em autoridade; o MCP expõe
+  a mesma leitura paginada e bounded.
+- **Contrato opcional de embeddings locais.** `wendkeep/vault` exporta manifest versionado,
+  integrity-bound e in-process para reranquear somente um prefixo de candidatos; fica desligado
+  por padrão, proíbe rede/retenção, limita batch/bytes, preserva proveniência e degrada para a
+  ordem lexical sem incluir modelo, provider ou vector database no Core.
+
+### Changed
+
+- **Saúde de escala no `doctor` e Observer.** Snapshots operacionais publicam somente contagens,
+  bytes, atualidade, backend e estados sanitizados de memória/recall, sem rebuild, leitura do
+  corpus ou vazamento de termos e paths.
+- **Fechamento coordenado da issue #82.** A PR agregadora #124 reconcilia os slices #111–#123,
+  mantém documentação PT-BR/EN e tarball em paridade e alinha package/lock/CHANGELOG para a
+  entrega minor única.
+
 ## [0.85.1] — 2026-08-25
 
 ### Fixed

package/README.en.md

@@ -151,6 +151,7 @@ npx wendkeep init --no-companions --no-mcp --yes              # zero companions,
 | `--no-mcp` | Skip **wendkeep's own** vault MCP (`wendkeep-vault`). Companion MCPs still follow `--companions`. |
 | `--no-colors` | Skip the Obsidian color system (`.obsidian` snippet + graph groups). |
 | `--vscode-worktree-tasks` | Create a local, Git-excluded `.vscode/tasks.json` for creating/listing/opening/finishing worktrees; never overwrites an existing file. Also accepted by `sync`. |
+| `--git-commit-hooks` | Opt in to copying commit hooks into `.githooks/` and setting local `core.hooksPath`; custom hooks are preserved without `--force`. |
 | `--yes`, `-y` | Non-interactive; accept defaults (skips the language / vault / companion prompts). |
 | `--force` | Overwrite existing wendkeep config blocks. |
 
@@ -250,6 +251,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Portable state** | `portable status/export/import/diff`, authored/runtime boundary, redaction, and the `active-work` snapshot | [Portable state](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/portable.md) |
 | **Local-first sync** | `sync status/push/pull/conflicts/resolve`, revision/CAS, outbox, leases, and explicit conflicts | [Sync protocol](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/sync-protocol.md) |
 | **Native MCP** | semantic tools, effects/capabilities, stdio, schemas, pagination, budgets, audit, and client configuration | [Native MCP](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/mcp.md) |
+| **Evidence recall and embeddings** | cursor/byte budgets, bounded lexical/FTS sidecars, and an optional local plugin contract that is off by default | [Optional embedding plugin](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/evidence-embeddings.md) |
 | **Host capabilities** | versioned lifecycle/effect matrix, degraded mode, human waivers, and evidence/Observer coverage | [Host capabilities](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/capabilities.md) |
 | **Operating profiles** | `profile`, `flow`, always-on Keep Core, and Wend Runtime governance | [Operating profiles](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/operating-profiles.md) |
 | **Changes and verification** | `change`, specs, sensors, TDD, evidence, Task Contracts, and archive | [Changes and verification](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/changes-and-verification.md) |
@@ -258,6 +260,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Notes and knowledge** | BUG/APR/ADR, repairs, renumbering, lessons, and dashboard | [Notes and knowledge](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/notes-and-knowledge.md) |
 | **Costs and observability** | safe dry-run, tri-state, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
 | **Maintenance and diagnostics** | doctor, frontier/manifest freshness, drift, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
+| **Evidence-based commits** | `wendkeep commit`, tasks derived from contracts, tests only from canonical execution bound to the exact SHA, opt-in Git hooks, privacy, and remote range gate | [Commits](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/commit.md) |
 | **Local Observer** | `observer serve`, registration, incremental publication, `reconcile`, outbox, and multi-project index | [Local Observer](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer.md) |
 
 Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/verify.md),
@@ -665,7 +668,7 @@ The archive **gate** blocks unless: the change scaffold is filled (G0), no task
 ## Notes & roadmap
 
 - **Vault folder names default to Portuguese** (`02-Sessões`, `04-Decisões`, …). Pass `wendkeep init --locale en` for an English vault (`02-Sessions`, `04-Decisions`, English scaffold/skills). The locale is a vault property, locked at init; parsers are bilingual so mixed content never breaks.
-- **Search is keyword/frontmatter scoring**, not on‑device embeddings (that's on the roadmap).
+- **Default recall remains local lexical/FTS.** Embeddings require an explicitly supplied trusted local plugin with forbidden network access, budgets, and lexical fallback; Core ships no model or provider.
 - **Transcript formats are agent‑internal** and can change between agent versions; parsing is isolated but may need updates.
 - Installer wires **both agents**: `.claude/settings.json` + `.mcp.json` for Claude Code, `.codex/hooks.json` for Codex. **Eight Codex hooks are compatible**; `change-guard` validates the project lease in `PreToolUse` and denies mutations outside it. The four hooks without an equivalent remain Claude-only: `change-warn`, `plan-capture`, `decision-capture`, and `task-log`.
 - **Codex hooks start untrusted.** They are enumerated but not executed until you approve the “Hooks need review” prompt; `init` cannot pre‑approve them (`--dangerously-bypass-hook-trust` is per‑invocation and stores no trusted hash). Trust is keyed to the hook's identity, so hand‑written wendkeep Codex hooks predating `0.46.0` — which ran at the 600s default because they used `timeout` instead of `timeoutSec` — cost one re‑review after `init` corrects the key. Expected, not a regression. `import --source codex` still backfills past Codex sessions either way.

package/README.md

@@ -151,6 +151,7 @@ npx wendkeep init --no-companions --no-mcp --yes              # zero companions,
 | `--no-mcp` | Skip **wendkeep's own** vault MCP (`wendkeep-vault`). Companion MCPs still follow `--companions`. |
 | `--no-colors` | Skip the Obsidian color system (`.obsidian` snippet + graph groups). |
 | `--vscode-worktree-tasks` | Create a local, Git-excluded `.vscode/tasks.json` for creating/listing/opening/finishing worktrees; never overwrites an existing file. Also accepted by `sync`. |
+| `--git-commit-hooks` | Opt in to copying commit hooks into `.githooks/` and setting local `core.hooksPath`; custom hooks are preserved without `--force`. |
 | `--yes`, `-y` | Non-interactive; accept defaults (skips the language / vault / companion prompts). |
 | `--force` | Overwrite existing wendkeep config blocks. |
 
@@ -250,6 +251,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Portable state** | `portable status/export/import/diff`, authored/runtime boundary, redaction, and the `active-work` snapshot | [Portable state](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/portable.md) |
 | **Local-first sync** | `sync status/push/pull/conflicts/resolve`, revision/CAS, outbox, leases, and explicit conflicts | [Sync protocol](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/sync-protocol.md) |
 | **Native MCP** | semantic tools, effects/capabilities, stdio, schemas, pagination, budgets, audit, and client configuration | [Native MCP](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/mcp.md) |
+| **Evidence recall and embeddings** | cursor/byte budgets, bounded lexical/FTS sidecars, and an optional local plugin contract that is off by default | [Optional embedding plugin](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/evidence-embeddings.md) |
 | **Host capabilities** | versioned lifecycle/effect matrix, degraded mode, human waivers, and evidence/Observer coverage | [Host capabilities](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/capabilities.md) |
 | **Operating profiles** | `profile`, `flow`, always-on Keep Core, and Wend Runtime governance | [Operating profiles](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/operating-profiles.md) |
 | **Changes and verification** | `change`, specs, sensors, TDD, evidence, Task Contracts, and archive | [Changes and verification](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/changes-and-verification.md) |
@@ -258,6 +260,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Notes and knowledge** | BUG/APR/ADR, repairs, renumbering, lessons, and dashboard | [Notes and knowledge](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/notes-and-knowledge.md) |
 | **Costs and observability** | safe dry-run, tri-state, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
 | **Maintenance and diagnostics** | doctor, frontier/manifest freshness, drift, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
+| **Evidence-based commits** | `wendkeep commit`, tasks derived from contracts, tests only from canonical execution bound to the exact SHA, opt-in Git hooks, privacy, and remote range gate | [Commits](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/commit.md) |
 | **Local Observer** | `observer serve`, registration, incremental publication, `reconcile`, outbox, and multi-project index | [Local Observer](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer.md) |
 
 Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/verify.md),
@@ -665,7 +668,7 @@ The archive **gate** blocks unless: the change scaffold is filled (G0), no task
 ## Notes & roadmap
 
 - **Vault folder names default to Portuguese** (`02-Sessões`, `04-Decisões`, …). Pass `wendkeep init --locale en` for an English vault (`02-Sessions`, `04-Decisions`, English scaffold/skills). The locale is a vault property, locked at init; parsers are bilingual so mixed content never breaks.
-- **Search is keyword/frontmatter scoring**, not on‑device embeddings (that's on the roadmap).
+- **Default recall remains local lexical/FTS.** Embeddings require an explicitly supplied trusted local plugin with forbidden network access, budgets, and lexical fallback; Core ships no model or provider.
 - **Transcript formats are agent‑internal** and can change between agent versions; parsing is isolated but may need updates.
 - Installer wires **both agents**: `.claude/settings.json` + `.mcp.json` for Claude Code, `.codex/hooks.json` for Codex. **Eight Codex hooks are compatible**; `change-guard` validates the project lease in `PreToolUse` and denies mutations outside it. The four hooks without an equivalent remain Claude-only: `change-warn`, `plan-capture`, `decision-capture`, and `task-log`.
 - **Codex hooks start untrusted.** They are enumerated but not executed until you approve the “Hooks need review” prompt; `init` cannot pre‑approve them (`--dangerously-bypass-hook-trust` is per‑invocation and stores no trusted hash). Trust is keyed to the hook's identity, so hand‑written wendkeep Codex hooks predating `0.46.0` — which ran at the 600s default because they used `timeout` instead of `timeoutSec` — cost one re‑review after `init` corrects the key. Expected, not a regression. `import --source codex` still backfills past Codex sessions either way.

package/docs/en/commands/commit.md

@@ -0,0 +1,159 @@
+# Evidence-based commits
+
+**English** · [Português](../../pt-BR/commands/commit.md)
+
+## Purpose
+
+Produce the same auditable message from Codex, Claude Code, or another Git client using typed input,
+public references, and a staged-index summary only. The deterministic kernel does not read the
+Vault, `.brain`, session registries, or the network.
+
+## When to use
+
+Use before `feat`, `fix`, `refactor`, or `perf` implementation commits that must record causal
+authority, tasks, tests, scope, and verifiable evidence consistently across harnesses.
+
+## When not to use
+
+Do not use it to invent proof, publish private content, rewrite history, or automate pushes.
+`docs`, `test`, and `chore` commits need no context only when every changed file is objectively
+documentation/test material. Product changes require the governed body regardless of type.
+
+## Prerequisites
+
+Run inside a Git repository with WendKeep installed locally and the selected product files already
+present in the staged index.
+
+## Syntax
+
+```bash
+npx --no-install wendkeep commit context --input <json|-> [--json]
+npx --no-install wendkeep commit context --clear [--json]
+npx --no-install wendkeep commit render --input <json|->
+npx --no-install wendkeep commit prepare --message-file <path> [--source <source>]
+npx --no-install wendkeep commit validate --message-file <path> [--json]
+```
+
+## Options and exit codes
+
+- Exit `0`: context written/cleared or message valid.
+- Exit `1`: invalid governed message.
+- Exit `2`: invalid argument, JSON, Git state, privacy boundary, or stale context.
+- `--consume-context` is reserved for the `commit-msg` wrapper and removes context after validation.
+
+## Opt-in installation
+
+The default `init` does not enable Git hooks. To copy the portable wrappers and set
+`core.hooksPath=.githooks` for this repository only:
+
+```bash
+npx --no-install wendkeep init --git-commit-hooks --yes
+```
+
+Custom hooks are never overwritten silently. When `init` finds a conflict it preserves the file.
+Review it and rerun with `--force` only when replacement is intended; the previous file is retained
+as `.bak`.
+A custom `core.hooksPath` is also a conflict and remains untouched without `--force`.
+
+## Examples
+
+### Prepare a commit
+
+Create JSON matching `schema/commit-message-v1.schema.json`. Declare authority and evidence
+references, but do not provide `tasks`, `tests`, `fresh`, or `verified`. Runtime derives tasks from
+completed canonical Task Contracts. Tests come only from `[sensor:<id>]` sensors executed by the
+collector; `[phase:verify]` alone is never a result. Sensors
+declared in an Envelope must exactly match the canonical reexecution in IDs, configuration,
+command, severity, and result; only that reexecution emits a `Tests` line. The remote gate
+re-executes each sensor in the checkout for that exact commit SHA. Every
+published reference gets a re-derived SHA-256 digest. ADR/design validate artifact ID and path;
+tasks containing `[req:]` require a versioned, sanitized `spec` reference that defines every
+requirement. Evidence Envelope, Verdict, receipt, and TDD attestation may participate in local
+validation, but are omitted from remote Evidence: worktree/session/branch IDs are not published,
+and self-contained consistency is not promoted to proof. A message claiming them as
+`fresh`/`verified` is rejected with `WENDKEEP_COMMIT_REMOTE_PROOF_UNAVAILABLE`. The fixed trailers
+`Remote-Proof-Scope: git,authority,tasks,spec,sensors` and `Local-Causal-Proof: unpublished` make
+that boundary explicit. Range re-derives authority/artifacts, task/spec, Git `Scope`, and
+config/sensors from the SHA, and only canonical reexecution emits `Tests`. `Co-Authored-By` is
+omitted until a trusted identity registry can resolve it.
+
+The normal authority is the causal ADR:
+
+```json
+{ "authority": { "kind": "adr", "adr": "ADR-1234", "ref": "docs/ADR-1234.md", "issue": "#123" } }
+```
+
+Only when no causal change/ADR exists may the native harness declare the fallback below. `issue`
+must be `#NNN` and `design` must be versioned in the same commit under
+`docs/superpowers/specs/` or `plans/`:
+
+```json
+{
+  "authority": {
+    "kind": "native",
+    "issue": "#40",
+    "design": "docs/superpowers/specs/approved-design.md"
+  }
+}
+```
+
+Runtime observes effective profile `OFF`, no causal context/change/lease or ADR, and the issue in the
+design. This mode emits unique `Authority: native-no-causal-change`, `Issue`, and `Design` trailers. Free text, unversioned
+design, stale/unverified proof, or a missing body/tests fail closed.
+
+```bash
+git add <product-files>
+npx --no-install wendkeep commit context --input commit-input.json
+git commit -m "feat(scope): draft"
+```
+
+`commit context` calculates the staged diff SHA-256 and stores the sanitized context at
+`.git/wendkeep-commit-input.json`, outside the working tree. `prepare-commit-msg` replaces the draft
+with the canonical message; `commit-msg` validates it and consumes the context. If the index changes,
+the context becomes stale and must be recreated.
+`commit-msg` rereads context, compares the complete message and staged hash/files, and consumes
+context only after success. Merge, squash, and amend clear incompatible context so it cannot leak
+to the next commit. `--message-file` stays inside the repository or Git directory.
+
+Other commands:
+
+```bash
+npx --no-install wendkeep commit render --input commit-input.json
+npx --no-install wendkeep commit validate --message-file .git/COMMIT_EDITMSG
+npx --no-install wendkeep commit context --clear
+```
+
+Objectively trivial commits remain unchanged. Implementation
+commits (`feat`, `fix`, `refactor`, and `perf`) require a Conventional Commit subject with an ADR or
+the restricted native fallback above, Capability, Evidence, Tasks, Tests, and Scope sections, the
+staged hash, and a `WendKeep-Commit: v1` trailer. Amend, merge, and squash never receive duplicate or
+invented proof.
+
+## Privacy and fail-closed behavior
+
+- Embedded absolute paths, any configured/default Vault, `.brain`, session registries, PII, and secrets are rejected
+  before persistence.
+- `reported`, `legacy-unbound`, `stale`, and `unproven` evidence cannot be presented as proof.
+- Context holds sanitized references and diff metadata, never private Vault content.
+- `--no-verify` is not accepted: CI validates every new commit, including merges and novel resolutions.
+
+## Expected result
+
+A deterministic, self-contained message with no private material, the hash of the committed index,
+and coherent causal trailers.
+
+## Common errors and diagnosis
+
+`wendkeep doctor` reports `[commit-hooks] healthy`, `disabled`, `missing`, or `drift` and remains
+read-only. After review, recover missing or divergent files with:
+
+```bash
+npx --no-install wendkeep init --git-commit-hooks --force --yes
+```
+
+When abandoning a commit, remove only its transient context with
+`wendkeep commit context --clear`. No command rewrites history or pushes automatically.
+
+## Next steps
+
+Review the generated message, commit it, and let the PR range gate detect any local bypass.

package/docs/en/commands/evidence-embeddings.md

@@ -0,0 +1,243 @@
+# Optional evidence embedding plugin
+
+[Português](../../pt-BR/commands/evidence-embeddings.md)
+
+## Purpose
+
+Define a programmatic boundary for local semantic reranking without adding a model, ML runtime,
+vector database, HTTP client, or provider dependency to WendKeep Core.
+
+This surface is **not a CLI command**. It is exported by `wendkeep/vault` for local plugins that are
+explicitly supplied by the application's composition root.
+
+## When to use
+
+Use this API when a trusted composition root needs to rerank a small candidate set already filtered
+by lexical/FTS recall while keeping the model and adapter outside Core.
+
+Embeddings are disabled by default.
+
+```js
+const result = await rerankEvidenceCandidatesWithEmbedding(rows, query);
+// result.metrics.status === 'disabled'
+```
+
+Core does not:
+
+- discover plugins in `node_modules`;
+- execute `import()` from Vault configuration;
+- download models;
+- open network connections;
+- persist vectors;
+- hand the full corpus to a plugin.
+
+A plugin receives data only when the caller supplies the plugin object and sets `enabled: true`.
+
+## When not to use
+
+Do not use the plugin as an authoritative index, a scope-expansion mechanism, a code autoloader, or
+a replacement for lexical filters/recall. Do not use a remote provider either: the contract requires
+local in-process execution with no network and no retention.
+
+### Authority contract
+
+Authority remains ordered as follows:
+
+```text
+Vault Markdown/JSONL → incremental index → lexical/FTS candidates → optional reranking
+```
+
+The plugin operates only on a bounded prefix of already-filtered candidates. It cannot:
+
+- make its index or cache authoritative;
+- silently broaden project, session, change, or logical-path scope;
+- hide `authority`, `validity`, or provenance;
+- remove unprocessed candidates—they remain at the end in their original order;
+- mutate the source objects returned by Core.
+
+## Prerequisites
+
+- a reviewed local plugin explicitly loaded by the application;
+- a model/configuration pinned by SHA-256 fingerprint;
+- explicit batch and byte budgets;
+- candidates already filtered by lexical/FTS recall.
+
+### Versioned manifest
+
+Use `buildEvidenceEmbeddingManifest()` to create the manifest and
+`createEvidenceEmbeddingPlugin()` to bind it to the `embed` function.
+
+Required fields:
+
+| Field | Rule |
+|---|---|
+| `schema_version` | `1` |
+| `protocol_version` | `1` |
+| `plugin_id` | stable local identifier |
+| `plugin_version` | adapter version |
+| `model_id` | model identifier |
+| `model_revision` | immutable revision used by the adapter |
+| `model_fingerprint` | `sha256:<64 hex>` for the effective model/configuration |
+| `dimensions` | 1 through 65536 |
+| `locality` | exactly `local` |
+| `transport` | exactly `in-process` |
+| `network` | exactly `forbidden` |
+| `retention` | exactly `none` |
+| `max_batch_size` | 1 through 512 documents |
+| `max_input_bytes` | 1 through 4 MiB |
+| `integrity` | hash of the canonical manifest payload |
+
+The manifest is declarative. Core cannot sandbox arbitrary JavaScript, so install only trusted local
+plugins and review their code. WendKeep prevents automatic loading and validates the contract before
+handing over any evidence, but it does not turn third-party code into trusted code.
+
+## Syntax
+
+```text
+buildEvidenceEmbeddingManifest(options)
+createEvidenceEmbeddingPlugin({ manifest, embed })
+verifyEvidenceEmbeddingPlugin(plugin)
+rerankEvidenceCandidatesWithEmbedding(rows, query, options)
+```
+
+## Examples
+
+```js
+import {
+  buildEvidenceEmbeddingManifest,
+  createEvidenceEmbeddingPlugin,
+  rerankEvidenceCandidatesWithEmbedding,
+} from 'wendkeep/vault';
+
+const manifest = buildEvidenceEmbeddingManifest({
+  plugin_id: 'local.my-embedding',
+  plugin_version: '1.0.0',
+  model_id: 'local.my-model',
+  model_revision: '2026.08.27',
+  model_fingerprint: 'sha256:<model-and-configuration-hash>',
+  dimensions: 384,
+  max_batch_size: 64,
+  max_input_bytes: 262144,
+});
+
+const plugin = createEvidenceEmbeddingPlugin({
+  manifest,
+  async embed(request, { signal }) {
+    // Local adapter: no network access and no text retention.
+    // Return exactly one query vector and one vector for every document.id.
+    return {
+      schema_version: 1,
+      model_fingerprint: manifest.model_fingerprint,
+      query_vector: await localModel.embed(request.query.text, { signal }),
+      document_vectors: await Promise.all(request.documents.map(async (document) => ({
+        id: document.id,
+        vector: await localModel.embed(document.text, { signal }),
+      }))),
+    };
+  },
+});
+
+const reranked = await rerankEvidenceCandidatesWithEmbedding(rows, query, {
+  enabled: true,
+  plugin,
+  maxCandidates: 64,
+  maxInputBytes: 262144,
+});
+```
+
+The request contains only:
+
+```json
+{
+  "schema_version": 1,
+  "model_fingerprint": "sha256:...",
+  "query": { "text": "..." },
+  "documents": [
+    { "id": "<chunk_id>", "text": "<title + heading + content>" }
+  ]
+}
+```
+
+`logical_path` is not sent to the plugin. Full provenance remains on the source objects and returns
+with the reranked order.
+
+## Expected result
+
+The response is fail-closed and may contain only:
+
+```json
+{
+  "schema_version": 1,
+  "model_fingerprint": "sha256:...",
+  "query_vector": [0.1, 0.2],
+  "document_vectors": [
+    { "id": "<chunk_id>", "vector": [0.3, 0.4] }
+  ]
+}
+```
+
+Core rejects:
+
+- dimensions that differ from the manifest;
+- `NaN`, infinity, or zero-norm vectors;
+- a divergent model fingerprint;
+- missing, duplicate, or unknown documents;
+- extra envelope fields;
+- a vector count that differs from the document count.
+
+The canonical adapter uses cosine similarity. Ties preserve the original order.
+
+## Options and exit codes
+
+The effective limit is always the lower value between caller and plugin manifest.
+
+- `maxCandidates`: default 128; maximum 512;
+- `maxInputBytes`: default 256 KiB; maximum 4 MiB;
+- documents that do not fit remain after the reranked prefix;
+- Core never sends a partial document;
+- a query or first document that cannot fit produces
+  `EVIDENCE_EMBEDDING_BUDGET_EXCEEDED`.
+
+With `required: false`—the default—a contract, budget, response, or execution failure returns the
+original lexical order and `metrics.status: "fallback"`. With `required: true`, the typed error is
+propagated.
+
+Main codes:
+
+- `EVIDENCE_EMBEDDING_PLUGIN_INVALID`;
+- `EVIDENCE_EMBEDDING_BUDGET_EXCEEDED`;
+- `EVIDENCE_EMBEDDING_RESPONSE_INVALID`;
+- `EVIDENCE_EMBEDDING_EXECUTION_FAILED`.
+
+## Safe operation
+
+1. Keep `enabled: false` until the plugin and model hash are verified.
+2. Run `verifyEvidenceEmbeddingPlugin(plugin)` before registering the adapter.
+3. Pin `plugin_version`, `model_revision`, and `model_fingerprint`; do not use mutable aliases such
+   as `latest`.
+4. Start with small budgets and compare the result against lexical/FTS recall.
+5. Record metrics only—IDs, counts, bytes, and timings—never query, text, or vectors.
+6. Treat a fingerprint change as a new generation of any plugin-owned cache.
+
+## Common errors and diagnosis
+
+When `metrics.status` is `fallback`:
+
+1. disable the plugin; lexical/FTS recall remains the safe route;
+2. validate the manifest and inspect `metrics.reason`;
+3. confirm dimensions, fingerprint, and vector count;
+4. discard only plugin-owned caches and rebuild them from `EVIDENCE_INDEX.jsonl` authority;
+5. never delete or edit `EVIDENCE_INDEX.jsonl`, Markdown, or Core sidecars to repair an embedding
+   provider;
+6. re-enable with `required: false` and promote to `required: true` only in an environment that
+   genuinely requires the provider.
+
+## Next steps
+
+This contract does not install a model or automatically add embeddings to MCP, doctor, or Observer.
+It defines the safe, testable boundary for a future sibling adapter. Core remains complete and
+functional without any plugin.
+
+Use the [Native MCP](mcp.md) guide for the existing paged/lexical surface and the
+[maintenance and diagnostics](maintenance-and-diagnostics.md) guide to inspect derived-artifact
+health without rebuilding it.

package/docs/en/commands/mcp.md

@@ -63,20 +63,71 @@ wendkeep mcp config --client cursor --vault <vault>
 ```
 
 Reads: `wendkeep_project_status`, `wendkeep_context_status`, `wendkeep_memory_recall`,
-`wendkeep_memory_conflicts`, `wendkeep_change_list`, `wendkeep_change_show`,
-`wendkeep_change_status`, `wendkeep_spec_effective`, `wendkeep_task_show`,
-`wendkeep_task_evaluate`, `wendkeep_handoff_current`, `wendkeep_evidence_latest`, and
-`wendkeep_observer_query`.
+`wendkeep_evidence_recall`, `wendkeep_memory_conflicts`, `wendkeep_change_list`,
+`wendkeep_change_show`, `wendkeep_change_status`, `wendkeep_spec_effective`,
+`wendkeep_task_show`, `wendkeep_task_evaluate`, `wendkeep_handoff_current`,
+`wendkeep_evidence_latest`, and `wendkeep_observer_query`.
 
 Writes: `wendkeep_memory_assert`, `wendkeep_checkpoint_create`, `wendkeep_context_select`,
 `wendkeep_task_claim`, `wendkeep_task_complete`, and `wendkeep_handoff_publish`.
 
+## Paged indexed evidence recall
+
+`wendkeep_evidence_recall` is the bounded surface for retrieving Vault evidence. It selects
+candidates through the persistent lexical sidecar or optional SQLite/FTS5, reranks them with the
+canonical scorer, and returns a compact page. `wendkeep_memory_recall` remains available as the
+legacy API and does not silently inherit the new contract.
+
+Main input:
+
+- `project_root` and `query` are required;
+- `limit` accepts 1 through 100 results per page;
+- `cursor` is opaque and is valid only for the same query, filters, and logical index;
+- `max_bytes` accepts 2 through 524288 and exactly bounds the serialized JSON in `results`; the
+  default is 64 KiB;
+- `candidate_limit` accepts 1 through 4096 candidates;
+- `posting_budget` accepts 1 through 1048576 visited postings;
+- `backend` accepts `auto`, `sqlite`, or `lexical`;
+- `filters` supports exact matches for `authority`, `validity`, `entity_type`, `project_id`,
+  `change_slug`, `session_id`, `work_session_id`, and `logical_path`, plus
+  `logical_path_prefix`. Each filter may be a string or a string list.
+
+Example call:
+
+```json
+{
+  "name": "wendkeep_evidence_recall",
+  "arguments": {
+    "project_root": "<project>",
+    "query": "authentication contract",
+    "limit": 5,
+    "max_bytes": 65536,
+    "candidate_limit": 512,
+    "posting_budget": 65536,
+    "backend": "auto",
+    "filters": {
+      "authority": "verified",
+      "validity": "active",
+      "logical_path_prefix": "04-Decisions/"
+    }
+  }
+}
+```
+
+The response contains `results`, `next_cursor`, `has_more`, `as_of`, and page counts/bytes. Each
+result omits `content`, reports `content_bytes`, retains a bounded `excerpt`, and replaces
+`logical_path` with `logical_ref`, a Vault-relative reference—never an absolute path. The
+`candidates` block exposes backend, count, postings, rebuild, and fallback metadata. When the
+candidate budget did not cover every possible match, `complete_candidate_set` is `false`; this
+prevents a consumer from treating a truncated selection as exhaustive.
+
 ## Expected result
 
 The handshake and `tools/list` return valid JSON-RPC. Every tool declares a versioned
 effect/capability and schemas. Known reads skip the mutation gate while retaining explicit
-project/worktree binding, cursor pagination, a 1 MiB default budget, redaction, timeout, and
-cancellation. Observer is declared unavailable below Node 22.13 without blocking Core on Node 18.
+project/worktree binding, cursor pagination, budgets, redaction, timeout, and cancellation.
+Observer is declared unavailable below Node 22.13 without blocking Core on Node 18. Indexed recall
+also works on Node 18 through the lexical fallback; SQLite/FTS5 remains optional.
 
 Writes require `project_root`, `session_id`, `active_context_id`, `actor`, `reason`, the exact
 capability, and `lease.id`/`lease.expires_at`; the executor revalidates causal authorization and CLI
@@ -89,8 +140,17 @@ outcome, code, and duration—never arguments or payloads.
 - `MCP_CAPABILITY_REQUIRED` / `MCP_SCOPE_AUTH_REQUIRED`: capability missing or unauthorized.
 - `MCP_LEASE_EXPIRED`: obtain a new authorization/lease; do not hand-edit its timestamp.
 - `MCP_PROJECT_SCOPE_MISMATCH`: `project_root` and `worktree_root` use different bindings.
-- `MCP_REQUEST_TOO_LARGE` / `MCP_RESPONSE_TOO_LARGE`: use `limit` and the returned cursor.
+- `MCP_REQUEST_TOO_LARGE` / `MCP_RESPONSE_TOO_LARGE`: reduce budgets and continue with the cursor.
 - `MCP_RUNTIME_UNSUPPORTED`: use Node 22.13+ for Observer; Core remains available.
+- `MCP_EVIDENCE_QUERY_REQUIRED`: provide a non-empty query.
+- `MCP_EVIDENCE_CURSOR_INVALID`: the cursor was altered, became stale, or was reused with a
+  different query/filter set.
+- `MCP_EVIDENCE_BUDGET_TOO_SMALL`: even the next result's minimum metadata cannot fit
+  `max_bytes`.
+- `MCP_EVIDENCE_BACKEND_UNAVAILABLE`: SQLite was required but FTS5 is unavailable; use `auto` or
+  `lexical`.
+- `MCP_EVIDENCE_ARTIFACT_UNSAFE`: a derived artifact violated the Vault's physical boundary.
+- `MCP_EVIDENCE_RECALL_INVALID`: a filter, backend, or limit is outside the contract.
 
 ## Next steps