wendkeep 0.80.1 → 0.85.0

package/CHANGELOG.md

@@ -4,6 +4,119 @@ 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.85.0] — 2026-08-25
+
+### Added
+
+- **Matriz versionada de capacidades dos hosts.** Claude Code, Codex, Pi e MCP/CLI genérico
+  declaram as mesmas 17 capacidades de lifecycle/efeitos como `native`, `adapted`, `polled`,
+  `manual` ou `unavailable`; `wendkeep capabilities` inspeciona a cobertura sem exigir Vault e
+  versões/hosts desconhecidos entram em modo degradado explícito.
+- **Pi adapter e efeitos MCP verificáveis.** O workspace Pi deixa de ser placeholder e normaliza
+  envelopes lifecycle sem importar adapters irmãos. Efeitos vêm do catálogo assinado, nunca do
+  nome da tool: reads conhecidos pulam o mutation gate, writes/destructive permanecem gated e
+  desconhecidos falham fechado.
+- **Cobertura causal persistida.** Gaps são injetados no início e acompanham session registry,
+  active context, handoff, Evidence Envelope e Observer; estados manuais continuam apenas
+  `reported`, sem promoção indevida a prova verificada.
+
+### Changed
+
+- **Gates de verify e ASSURE conscientes do host.** Projetos podem declarar
+  `requires_host_capabilities` no `wendkeep.sensors.json`; capacidades manuais/indisponíveis
+  bloqueiam `verify` e handoff ASSURE salvo waiver humano explícito com aprovador e motivo.
+- **Contrato e documentação pública bilíngue.** Novos schemas de manifest/cobertura, campos
+  opcionais de handoff/evidência, README e guias PT-BR/EN documentam fallback, versões, waivers,
+  códigos de saída e recovery.
+
+## [0.84.0] — 2026-08-25
+
+### Added
+
+- **Protocolo de sync local-first.** `wendkeep sync status/push/pull/conflicts/resolve` transporta
+  estado autoral portátil por revisões, CAS, pais causais, record keys com escopo de
+  projeto/branch/worktree, tombstones e conflitos explícitos, sem last-write-wins ou cloud
+  obrigatória.
+- **Operação offline e coordenação recuperável.** Outbox append-only, acknowledgements
+  idempotentes, replay fora de ordem, leases expirantes com histórico, adaptadores de referência
+  filesystem/HTTP e resolução auditável preservam autoria sob partição, retry e clocks
+  divergentes.
+- **Privacidade, diagnóstico e contrato público.** Envelopes opt-in AES-256-GCM com rotação de
+  chave, schemas v1, status no `doctor` e no Observer sanitizado, chaos tests e guias PT-BR/EN
+  documentam consistência, erros e threat model. O sync desabilitado não cria runtime nem altera
+  Keep Core.
+
+## [0.83.0] — 2026-08-25
+
+### Added
+
+- **Estado autoral portátil e `active-work`.** `wendkeep portable status/export/import/diff`
+  produz um snapshot determinístico e revisável de CORE, ADRs, specs e changes autorais, com uma
+  projeção compacta de retomada por active context sem session/worktree IDs, paths locais, tokens,
+  transcritos, locks, leases ou outboxes.
+- **Import fail-closed e provenance privado.** Schema, project, allowlist, hashes, limites,
+  traversal, symlinks/hardlinks e revision/hash são validados antes da primeira escrita; estado
+  stale ou conflitante nunca sobrescreve silenciosamente o local. Export/import registram somente
+  metadados e hashes em ledger privado, e o `doctor` diagnostica authored state divergente.
+- **Contrato público bilíngue.** Schemas `portable-state-v1`/`portable-active-work-v1`, README,
+  guias PT-BR/EN e política LF em `.gitattributes` documentam redaction, opt-out de Git, revisão em
+  PR e retomada segura em clone limpo.
+
+## [0.82.0] — 2026-08-25
+
+### Added
+
+- **MCP semântico nativo.** `wendkeep mcp serve` oferece tools bounded para projeto, contexto,
+  memória, changes, specs, tarefas, handoff, evidência e Observer por JSON-RPC/stdio, com schemas
+  versionados, paginação, budgets, timeout, cancelamento, redaction e compatibilidade Core com
+  Node 18; Observer SQL permanece capability separada em Node 22.13+.
+- **Effects, capabilities e writes causais.** Um catálogo versionado com integridade SHA-256
+  distingue read/write/destructive; reads conhecidas deixam de ser bloqueadas apenas pelo prefixo
+  MCP, enquanto desconhecidas e manifestos inválidos falham fechado. Writes exigem capability,
+  ator, sessão, active context, lease e motivo, revalidam o binding causal e reutilizam os gates da
+  CLI; delivery, merge, push, tag, publicação e exclusão ficam fora da superfície padrão.
+- **Auditoria e configuração multi-cliente.** O ledger local registra somente metadados de chamada,
+  nunca argumentos/payload; `wendkeep mcp config` gera configuração para Claude, Codex, Cursor e
+  clientes genéricos, e o tarball instalado prova o handshake e a consulta semântica.
+
+### Changed
+
+- **MCP principal reproduzível.** `init` substitui o servidor de Vault executado com `@latest` por
+  `npx --no-install wendkeep mcp serve --vault <vault>`, preservando o merge não destrutivo de
+  `.mcp.json`; README, arquitetura e guias PT-BR/EN documentam tools, gates, limites e recovery.
+- **Bootstrap stdio desacoplado do checkout.** `mcp serve` inicia sem exigir um Vault no cwd; quando
+  `--vault` não é informado, cada tool resolve e audita somente o binding do `project_root` declarado,
+  preservando isolamento multi-projeto e permitindo handshake empacotado em CI/editores.
+
+## [0.81.0] — 2026-08-24
+
+### Added
+
+- **Atestação TDD causal.** `wendkeep tdd red|green|status|waive` registra o ciclo RED → GREEN
+  ligado a projeto, repositório, worktree, work session, change, tarefa, requisito e paths de teste.
+  RED já verde ou causado por import/sintaxe/configuração fica `invalid`; GREEN exige sucessor
+  causal e diff de produção posterior, enquanto waiver exige motivo e autoridade humana explícita.
+- **Prova reviewable e portátil.** O store v1 conserva digests e cauda sanitizada limitada, preserva
+  histórico após refactor/revalidação e expõe IDs no Evidence Envelope, pacote deep, handoff e
+  Observer, sem persistir saída completa nem paths absolutos.
+
+### Changed
+
+- **Gate TDD por perfil.** Task Contracts exigem atestação atual para tarefas `[tdd]` em GOVERN e
+  para comportamento testável em ASSURE; mutante sobrevivente ou mudança pós-GREEN invalida a
+  prova. OFF/FLOW permanecem opcionais e GUIDE recomendado. Skill `wk-tdd`, schemas, README e
+  guias PT-BR/EN documentam o contrato e a recuperação.
+
+## [0.80.2] — 2026-08-24
+
+### Fixed
+
+- **Perfil persistente em worktrees vinculadas.** `profile use` e `profile status` agora leem e
+  escrevem o binding canônico da worktree principal quando o Vault é resolvido pelo registry Git
+  compartilhado, sem alterar o `.wendkeep.json` versionado da worktree vinculada. A identidade de
+  caminho também normaliza aliases Windows 8.3, impedindo que uma seleção humana `OFF` volte
+  imediatamente ao fallback `GOVERN`; README e guia de perfis foram atualizados em PT-BR/EN.
+
 ## [0.80.1] — 2026-08-24
 
 ### Fixed

package/README.en.md

@@ -39,12 +39,15 @@ sibling adapters with no dependency between them, and the direction remains
 remain equivalent; the private `@wendkeep/integrations` workspace stays inside the single
 published `wendkeep` package, with no public `wendkeep/integrations` subpath. Pi is the next phase.
 
-In the **0.65 MCP Configuration Kernel** phase, `packages/mcp/src/config.mjs` becomes the
-canonical authority for the MCPVault entry, catalog-described server selection, and `.mcp.json`
-merging. `src/taxonomy.mjs` supplies descriptors while `src/init.mjs` retains only filesystem
-orchestration. Existing keys and servers remain preserved; invalid JSON stays byte-for-byte intact
-and the reconciled proposal is written to `.mcp.json.new`. The workspace remains private, with no
-public `wendkeep/mcp` subpath or separate npm package.
+The **native MCP** workspace now serves semantic project, context, memory, change, spec, task,
+handoff, evidence, and Observer tools through `wendkeep mcp serve`. A versioned, verified catalog
+declares every effect/capability; known reads skip the mutation gate, while writes require a
+capability, session, active context, lease, and reason. Stable schemas, pagination, byte budgets,
+timeouts, cancellation, redaction, and payload-free local audit bound the surface. `init` preserves
+the `.mcp.json` merge while invoking the installed package through
+`npx --no-install wendkeep mcp serve`—with no dynamic `@latest` dependency or arbitrary filesystem
+access. Stdio may start outside a bound project; without `--vault`, each call resolves and audits
+only its declared `project_root`. The workspace remains private inside the single `wendkeep` package.
 
 In the **0.64 CLI Runtime** phase, `packages/cli/src/index.mjs` owns help, version reporting, Vault
 selection, error presentation, and lazy dispatch. `bin/wendkeep.mjs` is reduced to the shebang and
@@ -87,7 +90,7 @@ Decisions, dead ends, the reason you chose X over Y — gone next session. The p
 | **Recall** — injected back | Canonical `CORE` + operational `SHARED_MEMORY` enter on `startup`, `/clear`, and `/compact`; on every prompt, the local chunk index selects a few passages with source, authority, and validity under an explicit budget. |
 | **Cost** — what it all cost | Per‑model, cache‑aware token pricing per session — plus `cost --trend` with a run‑rate projection across the whole vault; research previews without a final rate remain unestimated. |
 | **Multi‑agent** — one vault, both agents | `init` wires the session hooks into `.claude/settings.json` *and* `.codex/hooks.json`, and every note is tagged with the agent that wrote it: Claude Code is detected from its environment, anything else is recorded as Codex. One shared graph, whichever agent you are in. |
-| **Local‑first** — no cloud, no account | Everything is plain Markdown on your disk. An optional MCP server (`@bitbonsai/mcpvault`) lets the agent read/write the vault. |
+| **Local‑first** — no cloud, no account | Everything is plain Markdown on your disk. The native MCP queries local semantic state and gates writes by capability/context/lease. |
 | **Local Observer** — many projects, one view | `wendkeep observer` keeps documents, FTS5 chunks, sessions, agents, tokens, costs, calls, and transcripts in SQLite. Identities and foreign keys are project-scoped; each event is atomic. Hooks publish only what changed; `observer reconcile --url` ignores the incremental cursor to regenerate the complete projection while preserving local/remote revision baselines. |
 
 During historical migration, the Observer preserves differences between frontmatter totals and the
@@ -117,7 +120,7 @@ npx wendkeep init
 2. Write a provider-neutral **`.wendkeep.json`** binding at the project root and a matching `.brain/PROJECT.json` marker in the vault, then merge the session hooks into **`.claude/settings.json`**. The binding is provider-neutral by design: any agent resolves the same vault from its session `cwd`, with no machine-global environment variable. Older registrations already in `.claude/settings.json` are adopted automatically.
 3. Wire the Codex hooks in **`.codex/hooks.json`** — twelve compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `evidence-context` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. For the Observer, `SessionStart` only drains the outbox, `Stop` enqueues the changed session, and `SubagentStop` enqueues only the affected transcript; full scanning is explicit through `observer reconcile`. When the host omits `work_session_id`, `session-start` and `session-ensure` derive it from the canonical `session_id`, preserving an explicit handoff and the already registered value first. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. A raw `git checkout/switch` branch transition is denied before it can strand the session; use `wendkeep context switch <branch> [--create]`, which moves Git and the causal scope together in the same worktree with an audited revision and rollback. If a divergence is already quarantined, `context status --session <id>` inventories sanitized `reserved`/`observed` candidates; `context recover --session <id> --select <reserved|observed> --revision <n> --reason <text>` requires an explicit choice, CAS, and current-checkout proof, failing closed before clearing the conflict if revalidation changes. `doctor` diagnoses orphaned active contexts, removed worktrees, and expired `request-stop` leases without writing; `context repair --key <key> --revision <n> --reason <text> --session <id>` revalidates under lock, closes only the ownerless/removed context or expires only its lease, while preserving the record and all historical memory. The change lifecycle uses `active_contexts`, identified by `repository_id` + `worktree_id` + `work_session_id`; two matching sessions fail with ambiguity instead of selecting silently, `CURRENT_CHANGE.md` is only a derived projection for one unambiguous context, and migration never invents a worktree or session identity. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
    Once `active_contexts` is initialized, `brain-inject` and `change-context` mark only the causal context's change as current; the backlog remains global, and an empty or ambiguous store never revives `CURRENT_CHANGE.md`.
-4. Add the **`wendkeep-vault`** MCP server to `.mcp.json` so the agent can read/write the vault. Skip with `--no-mcp` — e.g. when the agent already has a vault MCP. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
+4. Add the native semantic **`wendkeep-vault`** MCP server to `.mcp.json`. It offers bounded reads and capability-gated writes without arbitrary filesystem access or an `@latest` download. Skip with `--no-mcp`. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
 5. Offer to pin **companion** plugins/MCP (multi-choice; **none** pre-checked — wendkeep is a neutral harness and presumes no third-party plugin). Each is wired the most agent-agnostic way it supports:
    - **`context-mode`** — context optimizer + FTS5 memory, wired as a Claude Code plugin. It ships its own MCP server, so wendkeep deliberately adds no `.mcp.json` entry (registering both cold-started two servers at once). On non-Claude agents, add the MCP by hand: `npx -y context-mode`.
    - **`understand-anything`** — project domain graph, via a `understand-inject` SessionStart hook that injects the graph when generated.
@@ -161,6 +164,9 @@ paths are also supported. Hooks search upward from the agent's `cwd`, so nested
 the nearest binding. The vault carries the same identity in `.brain/PROJECT.json`; a mismatch
 is rejected before any session is written. If no binding exists, hooks fail closed and never
 create the historical `~/wendkeep-vault` fallback.
+In linked worktrees, `profile use` and `profile status` resolve the main worktree's canonical
+binding through the shared Git registry; the persistent selection applies project-wide without
+rewriting the current worktree's versioned `.wendkeep.json`.
 
 `OBSIDIAN_VAULT_PATH` remains only as legacy/manual CLI compatibility. It is not used to
 route automatic Codex or Claude hooks and a project-local binding overrides an inherited
@@ -241,6 +247,10 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Installation and updates** | `init`, `sync`, companions, and the first project↔vault binding | [Installation and first use](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/getting-started.md) |
 | **Managed worktrees** | `worktree create/list/status/open/finish/cleanup/remove/prune`, merge proof, preflight, crash-safe cleanup/common gate, and receipts | [Managed worktrees](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/worktrees.md) |
 | **Active context** | `active_contexts` by `repository_id`/`worktree_id`/`work_session_id`, causal transition, quarantine, and explicit recovery | [Active context](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/context.md) |
+| **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) |
+| **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) |
 | **Shared memory** | CORE, SHARED, status, validation, repair, and curation | [Memory](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory.md) |
@@ -251,6 +261,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **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),
+[causal TDD attestation](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/tdd.md),
 [legacy-memory migration](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory-migration.md), and
 [safe retroactive import](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/retroactive-import.md).
 
@@ -398,6 +409,12 @@ ambiguity. Use `--scope core` for Keep Core health, `--scope runtime` for govern
 `--strict` in CI/release; `wendkeep sync` validates Core only so work in progress does not become
 an installation failure.
 
+To resume a change in another clone without tracking transcripts, tokens, paths, leases, or outboxes,
+`wendkeep portable export` creates `.wendkeep/portable/state.json` with sanitized authored
+CORE/ADRs/specs/deltas and a compact `active-work` projection. `portable import` validates project,
+hashes, revisions, and paths before writing; stale or conflicting state never silently replaces local
+state. Git tracking is opt-in and the command never adds files automatically.
+
 ## Shared Project Memory v2
 
 Hot memory now separates human authorship, operational state, and evidence:
@@ -549,8 +566,8 @@ explore → propose → apply (TDD) → verify → archive
 ```
 
 - **Propose** — `wendkeep change new <slug>` scaffolds `08-Mudanças/<slug>/` (`proposta.md`, `design.md`, `tarefas.md`; `--simple` skips the design). `--guide` creates the compact GUIDE contract and omits automatic design/spec/ADR when `contract_impact:none`. It becomes the global *current* change. When the change declares `spec_impact: required`, you author the delta yourself at `specs/<capability>/spec.md` — there is no placeholder to delete. Multiple changes may remain open: `change list`/`status` and the hooks show every pending one, while commands without `--change` act on the current one alone. `change use <slug>` changes focus and `change continue <archived> <new>` creates an auditable continuation.
-- **Apply** — implement each `tarefas.md` task. Mark machine proof with one or more `[sensor:<id>]` tags on the same task: every distinct ID enters the gate once, in declaration order. Also mark satisfied requirements with one or more `[req:<ID>]` tags.
-- **Verify** — `wendkeep verify` runs declared sensors and writes an **Evidence Envelope v2** to `evidencia.json`, SHA-256-bound to project/repository/worktree/session, HEAD, index tree, normalized worktree digest, tasks, effective spec, and sensor configuration. Each sensor records a sanitized command, execution window, duration, exit code, output digest, and a sanitized tail bounded to 2,000 characters. If HEAD changes during the run, no new envelope is published. `change status` reports `bound`, `stale`, `context-mismatch`, or `legacy-unbound`; v1 evidence remains readable but cannot satisfy v2 authority. The public schema is [`schema/wendkeep.evidence-envelope-v2.schema.json`](schema/wendkeep.evidence-envelope-v2.schema.json). `verify --deep` binds both package and verdict to the current `envelope_id`.
+- **Apply** — implement each `tarefas.md` task. Mark machine proof with one or more `[sensor:<id>]` tags on the same task: every distinct ID enters the gate once, in declaration order. Also mark satisfied requirements with one or more `[req:<ID>]` tags. For causal TDD, add `[tdd]` and record `wendkeep tdd red|green`; the [TDD attestation guide](docs/en/commands/tdd.md) covers profiles, waivers, and exit codes.
+- **Verify** — `wendkeep verify` runs declared sensors and writes an **Evidence Envelope v2** to `evidencia.json`, SHA-256-bound to project/repository/worktree/session, HEAD, index tree, normalized worktree digest, tasks, effective spec, TDD attestations, and sensor configuration. Each sensor records a sanitized command, execution window, duration, exit code, output digest, and a sanitized tail bounded to 2,000 characters. If HEAD changes during the run, no new envelope is published. `change status` reports `bound`, `stale`, `context-mismatch`, or `legacy-unbound`; v1 evidence remains readable but cannot satisfy v2 authority. The public schema is [`schema/wendkeep.evidence-envelope-v2.schema.json`](schema/wendkeep.evidence-envelope-v2.schema.json). `verify --deep` binds the package, attestations, and verdict to the current `envelope_id`.
 - **Archive** — `wendkeep change archive <slug>` **gates** on the evidence (blocks unless every declared critical sensor is green), promotes each applicable spec delta (`ADDED`/`MODIFIED`/`REMOVED`) into the living `07-Specs/<capability>.md` and moves the change to `_arquivo/`. GOVERN/ASSURE mint an ADR in `04-Decisões/`; compact GUIDE with no contract impact does not mint one automatically.
 
 > The gate blocks unless the scaffold is filled, no task is open, evidence is fresh, and every declared requirement is covered. **`--force` waives exactly one of those — the open-task check — and is the human's call, never the agent's.** An unfilled scaffold, a red critical sensor, stale evidence, an orphan requirement or a missing verdict block regardless.
@@ -603,7 +620,7 @@ npx wendkeep change new dark-mode              # proposta/design/tarefas — cha
 Edit `tarefas.md` — tag proof and requirement per task:
 
 ```markdown
-- [ ] 1.1 toggle persists across sessions [req:UI-1] [sensor:tests]
+- [ ] 1.1 toggle persists across sessions [req:UI-1] [sensor:tests] [tdd]
 ```
 
 Declare the capability in `proposta.md` (`specs: [ui]`) and author its delta only in
@@ -615,6 +632,9 @@ npx wendkeep change list                       # same backlog, plus the archived
 npx wendkeep change status dark-mode           # one screen for one change: specs / tasks / sensors / verdict
 npx wendkeep spec effective --change dark-mode # living contract + this change's delta
 npx wendkeep change done 1.1                   # tick a task from the CLI
+npx wendkeep tdd red 1.1 --requirement UI-1 --test tests/ui.test.mjs --command "npm test"
+# implement; then observe GREEN in the same causal context
+npx wendkeep tdd green 1.1 --command "npm test"
 npx wendkeep verify                            # run the declared sensors -> evidencia.json
 npx wendkeep verify --deep                     # assemble the verification package
 # the wk-verify skill (fresh, read-only pass) writes verdict.json

package/README.md

@@ -39,12 +39,15 @@ sibling adapters with no dependency between them, and the direction remains
 remain equivalent; the private `@wendkeep/integrations` workspace stays inside the single
 published `wendkeep` package, with no public `wendkeep/integrations` subpath. Pi is the next phase.
 
-In the **0.65 MCP Configuration Kernel** phase, `packages/mcp/src/config.mjs` becomes the
-canonical authority for the MCPVault entry, catalog-described server selection, and `.mcp.json`
-merging. `src/taxonomy.mjs` supplies descriptors while `src/init.mjs` retains only filesystem
-orchestration. Existing keys and servers remain preserved; invalid JSON stays byte-for-byte intact
-and the reconciled proposal is written to `.mcp.json.new`. The workspace remains private, with no
-public `wendkeep/mcp` subpath or separate npm package.
+The **native MCP** workspace now serves semantic project, context, memory, change, spec, task,
+handoff, evidence, and Observer tools through `wendkeep mcp serve`. A versioned, verified catalog
+declares every effect/capability; known reads skip the mutation gate, while writes require a
+capability, session, active context, lease, and reason. Stable schemas, pagination, byte budgets,
+timeouts, cancellation, redaction, and payload-free local audit bound the surface. `init` preserves
+the `.mcp.json` merge while invoking the installed package through
+`npx --no-install wendkeep mcp serve`—with no dynamic `@latest` dependency or arbitrary filesystem
+access. Stdio may start outside a bound project; without `--vault`, each call resolves and audits
+only its declared `project_root`. The workspace remains private inside the single `wendkeep` package.
 
 In the **0.64 CLI Runtime** phase, `packages/cli/src/index.mjs` owns help, version reporting, Vault
 selection, error presentation, and lazy dispatch. `bin/wendkeep.mjs` is reduced to the shebang and
@@ -87,7 +90,7 @@ Decisions, dead ends, the reason you chose X over Y — gone next session. The p
 | **Recall** — injected back | Canonical `CORE` + operational `SHARED_MEMORY` enter on `startup`, `/clear`, and `/compact`; on every prompt, the local chunk index selects a few passages with source, authority, and validity under an explicit budget. |
 | **Cost** — what it all cost | Per‑model, cache‑aware token pricing per session — plus `cost --trend` with a run‑rate projection across the whole vault; research previews without a final rate remain unestimated. |
 | **Multi‑agent** — one vault, both agents | `init` wires the session hooks into `.claude/settings.json` *and* `.codex/hooks.json`, and every note is tagged with the agent that wrote it: Claude Code is detected from its environment, anything else is recorded as Codex. One shared graph, whichever agent you are in. |
-| **Local‑first** — no cloud, no account | Everything is plain Markdown on your disk. An optional MCP server (`@bitbonsai/mcpvault`) lets the agent read/write the vault. |
+| **Local‑first** — no cloud, no account | Everything is plain Markdown on your disk. The native MCP queries local semantic state and gates writes by capability/context/lease. |
 | **Local Observer** — many projects, one view | `wendkeep observer` keeps documents, FTS5 chunks, sessions, agents, tokens, costs, calls, and transcripts in SQLite. Identities and foreign keys are project-scoped; each event is atomic. Hooks publish only what changed; `observer reconcile --url` ignores the incremental cursor to regenerate the complete projection while preserving local/remote revision baselines. |
 
 During historical migration, the Observer preserves differences between frontmatter totals and the
@@ -117,7 +120,7 @@ npx wendkeep init
 2. Write a provider-neutral **`.wendkeep.json`** binding at the project root and a matching `.brain/PROJECT.json` marker in the vault, then merge the session hooks into **`.claude/settings.json`**. The binding is provider-neutral by design: any agent resolves the same vault from its session `cwd`, with no machine-global environment variable. Older registrations already in `.claude/settings.json` are adopted automatically.
 3. Wire the Codex hooks in **`.codex/hooks.json`** — twelve compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `evidence-context` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. For the Observer, `SessionStart` only drains the outbox, `Stop` enqueues the changed session, and `SubagentStop` enqueues only the affected transcript; full scanning is explicit through `observer reconcile`. When the host omits `work_session_id`, `session-start` and `session-ensure` derive it from the canonical `session_id`, preserving an explicit handoff and the already registered value first. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. A raw `git checkout/switch` branch transition is denied before it can strand the session; use `wendkeep context switch <branch> [--create]`, which moves Git and the causal scope together in the same worktree with an audited revision and rollback. If a divergence is already quarantined, `context status --session <id>` inventories sanitized `reserved`/`observed` candidates; `context recover --session <id> --select <reserved|observed> --revision <n> --reason <text>` requires an explicit choice, CAS, and current-checkout proof, failing closed before clearing the conflict if revalidation changes. `doctor` diagnoses orphaned active contexts, removed worktrees, and expired `request-stop` leases without writing; `context repair --key <key> --revision <n> --reason <text> --session <id>` revalidates under lock, closes only the ownerless/removed context or expires only its lease, while preserving the record and all historical memory. The change lifecycle uses `active_contexts`, identified by `repository_id` + `worktree_id` + `work_session_id`; two matching sessions fail with ambiguity instead of selecting silently, `CURRENT_CHANGE.md` is only a derived projection for one unambiguous context, and migration never invents a worktree or session identity. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
    Once `active_contexts` is initialized, `brain-inject` and `change-context` mark only the causal context's change as current; the backlog remains global, and an empty or ambiguous store never revives `CURRENT_CHANGE.md`.
-4. Add the **`wendkeep-vault`** MCP server to `.mcp.json` so the agent can read/write the vault. Skip with `--no-mcp` — e.g. when the agent already has a vault MCP. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
+4. Add the native semantic **`wendkeep-vault`** MCP server to `.mcp.json`. It offers bounded reads and capability-gated writes without arbitrary filesystem access or an `@latest` download. Skip with `--no-mcp`. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
 5. Offer to pin **companion** plugins/MCP (multi-choice; **none** pre-checked — wendkeep is a neutral harness and presumes no third-party plugin). Each is wired the most agent-agnostic way it supports:
    - **`context-mode`** — context optimizer + FTS5 memory, wired as a Claude Code plugin. It ships its own MCP server, so wendkeep deliberately adds no `.mcp.json` entry (registering both cold-started two servers at once). On non-Claude agents, add the MCP by hand: `npx -y context-mode`.
    - **`understand-anything`** — project domain graph, via a `understand-inject` SessionStart hook that injects the graph when generated.
@@ -161,6 +164,9 @@ paths are also supported. Hooks search upward from the agent's `cwd`, so nested
 the nearest binding. The vault carries the same identity in `.brain/PROJECT.json`; a mismatch
 is rejected before any session is written. If no binding exists, hooks fail closed and never
 create the historical `~/wendkeep-vault` fallback.
+In linked worktrees, `profile use` and `profile status` resolve the main worktree's canonical
+binding through the shared Git registry; the persistent selection applies project-wide without
+rewriting the current worktree's versioned `.wendkeep.json`.
 
 `OBSIDIAN_VAULT_PATH` remains only as legacy/manual CLI compatibility. It is not used to
 route automatic Codex or Claude hooks and a project-local binding overrides an inherited
@@ -241,6 +247,10 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Installation and updates** | `init`, `sync`, companions, and the first project↔vault binding | [Installation and first use](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/getting-started.md) |
 | **Managed worktrees** | `worktree create/list/status/open/finish/cleanup/remove/prune`, merge proof, preflight, crash-safe cleanup/common gate, and receipts | [Managed worktrees](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/worktrees.md) |
 | **Active context** | `active_contexts` by `repository_id`/`worktree_id`/`work_session_id`, causal transition, quarantine, and explicit recovery | [Active context](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/context.md) |
+| **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) |
+| **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) |
 | **Shared memory** | CORE, SHARED, status, validation, repair, and curation | [Memory](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory.md) |
@@ -251,6 +261,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **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),
+[causal TDD attestation](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/tdd.md),
 [legacy-memory migration](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory-migration.md), and
 [safe retroactive import](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/retroactive-import.md).
 
@@ -398,6 +409,12 @@ ambiguity. Use `--scope core` for Keep Core health, `--scope runtime` for govern
 `--strict` in CI/release; `wendkeep sync` validates Core only so work in progress does not become
 an installation failure.
 
+To resume a change in another clone without tracking transcripts, tokens, paths, leases, or outboxes,
+`wendkeep portable export` creates `.wendkeep/portable/state.json` with sanitized authored
+CORE/ADRs/specs/deltas and a compact `active-work` projection. `portable import` validates project,
+hashes, revisions, and paths before writing; stale or conflicting state never silently replaces local
+state. Git tracking is opt-in and the command never adds files automatically.
+
 ## Shared Project Memory v2
 
 Hot memory now separates human authorship, operational state, and evidence:
@@ -549,8 +566,8 @@ explore → propose → apply (TDD) → verify → archive
 ```
 
 - **Propose** — `wendkeep change new <slug>` scaffolds `08-Mudanças/<slug>/` (`proposta.md`, `design.md`, `tarefas.md`; `--simple` skips the design). `--guide` creates the compact GUIDE contract and omits automatic design/spec/ADR when `contract_impact:none`. It becomes the global *current* change. When the change declares `spec_impact: required`, you author the delta yourself at `specs/<capability>/spec.md` — there is no placeholder to delete. Multiple changes may remain open: `change list`/`status` and the hooks show every pending one, while commands without `--change` act on the current one alone. `change use <slug>` changes focus and `change continue <archived> <new>` creates an auditable continuation.
-- **Apply** — implement each `tarefas.md` task. Mark machine proof with one or more `[sensor:<id>]` tags on the same task: every distinct ID enters the gate once, in declaration order. Also mark satisfied requirements with one or more `[req:<ID>]` tags.
-- **Verify** — `wendkeep verify` runs declared sensors and writes an **Evidence Envelope v2** to `evidencia.json`, SHA-256-bound to project/repository/worktree/session, HEAD, index tree, normalized worktree digest, tasks, effective spec, and sensor configuration. Each sensor records a sanitized command, execution window, duration, exit code, output digest, and a sanitized tail bounded to 2,000 characters. If HEAD changes during the run, no new envelope is published. `change status` reports `bound`, `stale`, `context-mismatch`, or `legacy-unbound`; v1 evidence remains readable but cannot satisfy v2 authority. The public schema is [`schema/wendkeep.evidence-envelope-v2.schema.json`](schema/wendkeep.evidence-envelope-v2.schema.json). `verify --deep` binds both package and verdict to the current `envelope_id`.
+- **Apply** — implement each `tarefas.md` task. Mark machine proof with one or more `[sensor:<id>]` tags on the same task: every distinct ID enters the gate once, in declaration order. Also mark satisfied requirements with one or more `[req:<ID>]` tags. For causal TDD, add `[tdd]` and record `wendkeep tdd red|green`; the [TDD attestation guide](docs/en/commands/tdd.md) covers profiles, waivers, and exit codes.
+- **Verify** — `wendkeep verify` runs declared sensors and writes an **Evidence Envelope v2** to `evidencia.json`, SHA-256-bound to project/repository/worktree/session, HEAD, index tree, normalized worktree digest, tasks, effective spec, TDD attestations, and sensor configuration. Each sensor records a sanitized command, execution window, duration, exit code, output digest, and a sanitized tail bounded to 2,000 characters. If HEAD changes during the run, no new envelope is published. `change status` reports `bound`, `stale`, `context-mismatch`, or `legacy-unbound`; v1 evidence remains readable but cannot satisfy v2 authority. The public schema is [`schema/wendkeep.evidence-envelope-v2.schema.json`](schema/wendkeep.evidence-envelope-v2.schema.json). `verify --deep` binds the package, attestations, and verdict to the current `envelope_id`.
 - **Archive** — `wendkeep change archive <slug>` **gates** on the evidence (blocks unless every declared critical sensor is green), promotes each applicable spec delta (`ADDED`/`MODIFIED`/`REMOVED`) into the living `07-Specs/<capability>.md` and moves the change to `_arquivo/`. GOVERN/ASSURE mint an ADR in `04-Decisões/`; compact GUIDE with no contract impact does not mint one automatically.
 
 > The gate blocks unless the scaffold is filled, no task is open, evidence is fresh, and every declared requirement is covered. **`--force` waives exactly one of those — the open-task check — and is the human's call, never the agent's.** An unfilled scaffold, a red critical sensor, stale evidence, an orphan requirement or a missing verdict block regardless.
@@ -603,7 +620,7 @@ npx wendkeep change new dark-mode              # proposta/design/tarefas — cha
 Edit `tarefas.md` — tag proof and requirement per task:
 
 ```markdown
-- [ ] 1.1 toggle persists across sessions [req:UI-1] [sensor:tests]
+- [ ] 1.1 toggle persists across sessions [req:UI-1] [sensor:tests] [tdd]
 ```
 
 Declare the capability in `proposta.md` (`specs: [ui]`) and author its delta only in
@@ -615,6 +632,9 @@ npx wendkeep change list                       # same backlog, plus the archived
 npx wendkeep change status dark-mode           # one screen for one change: specs / tasks / sensors / verdict
 npx wendkeep spec effective --change dark-mode # living contract + this change's delta
 npx wendkeep change done 1.1                   # tick a task from the CLI
+npx wendkeep tdd red 1.1 --requirement UI-1 --test tests/ui.test.mjs --command "npm test"
+# implement; then observe GREEN in the same causal context
+npx wendkeep tdd green 1.1 --command "npm test"
 npx wendkeep verify                            # run the declared sensors -> evidencia.json
 npx wendkeep verify --deep                     # assemble the verification package
 # the wk-verify skill (fresh, read-only pass) writes verdict.json

package/docs/en/commands/capabilities.md

@@ -0,0 +1,82 @@
+# Host capabilities
+
+[Português (Brasil)](../../pt-BR/commands/capabilities.md)
+
+## Purpose
+
+Show the versioned matrix of the 17 lifecycle/effect capabilities each host actually provides as
+`native`, `adapted`, `polled`, `manual`, or `unavailable`.
+
+## When to use
+
+Use it before depending on session hooks, tool use, task completion, subagents, transcript, or
+usage; and when diagnosing differences across Claude Code, Codex, Pi, and generic MCP/CLI clients.
+
+## When not to use
+
+Do not treat the matrix as proof that a manual event happened. `manual` has `reported` authority;
+only native/adapted/polled events can be `verified`.
+
+## Prerequisites
+
+Node.js 18+ and WendKeep installed. The command is pure and needs no Vault. Session coverage uses
+the detected host and may receive its version through `WENDKEEP_HOST_VERSION`.
+
+## Syntax
+
+```text
+wendkeep capabilities [--host <claude|codex|pi|generic-mcp>] [--host-version <v>] [--json]
+```
+
+Without `--host`, all manifests are listed. An unknown host explicitly degrades to `generic-mcp`;
+an out-of-range version is marked `HOST_VERSION_UNPROVEN`.
+
+## Options and exit codes
+
+- `--host <id>` selects a host; unknown ids are never silently promoted.
+- `--host-version <v>` compares the observed major with the manifest.
+- `--json` emits the `host-coverage-v1` contract.
+- exit `0`: matrix emitted; exit `2`: invalid argument.
+
+`wendkeep.sensors.json` may declare `requires_host_capabilities` and explicit human waivers under
+`host_capability_waivers`. `verify` exits `1` when a required capability is manual/unavailable
+without `authority: human`, `approved_by`, and `reason`. ASSURE applies the same handoff rule.
+
+## Examples
+
+```powershell
+wendkeep capabilities --host codex --host-version 1.2.0
+wendkeep capabilities --host generic-mcp --json
+```
+
+```json
+{
+  "requires_host_capabilities": ["task.completed"],
+  "host_capability_waivers": [{
+    "capability": "task.completed",
+    "authority": "human",
+    "approved_by": "maintainer",
+    "reason": "manual confirmation"
+  }]
+}
+```
+
+## Expected result
+
+Coverage flows into the session registry, active context, handoff, evidence envelope, and Observer
+summary. Gaps are injected at session start before the agent assumes nonexistent parity. MCP effects
+come from the signed manifest: known reads skip the mutation gate; writes/destructive remain gated;
+an unknown effect fails closed.
+
+## Common errors and diagnosis
+
+- `HOST_UNKNOWN`: use MCP/CLI fallback or publish an isolated adapter.
+- `HOST_VERSION_UNPROVEN`: update the manifest or operate in degraded mode.
+- `HOST_CAPABILITY_UNAVAILABLE`: remove the dependency or obtain an explicit human waiver.
+- `HOST_ENVELOPE_UNKNOWN`: an unknown version/event never becomes verified evidence.
+- A suggestive tool name does not define its effect; inspect the signed catalog with `wendkeep mcp inspect`.
+
+## Next steps
+
+See [Native MCP](mcp.md), [sessions and import](sessions-and-import.md),
+[changes and verification](changes-and-verification.md), and [Observer](observer.md).

package/docs/en/commands/getting-started.md

@@ -86,7 +86,9 @@ initialized vault. Existing files are merged or preserved, and the selected vaul
 When MCP is enabled, `init` preserves existing properties and servers in `.mcp.json` and adds
 `wendkeep-vault`. If the existing JSON is invalid, the original file remains byte-for-byte intact
 and the reconciled proposal is written to `.mcp.json.new`. Since version 0.65, this composition is
-owned by the private MCP kernel without changing commands, flags, or the public npm surface.
+owned by the private MCP kernel. The entry runs the installed semantic server through
+`npx --no-install wendkeep mcp serve --vault <vault>`, with no dynamic `@latest` download. See
+[Native MCP](mcp.md) for tools, gates, limits, and client snippets.
 
 Pure rules that project Claude/Codex hooks and interpret envelopes, transcripts, usage, and
 identity belong to the private `@wendkeep/integrations` workspace. Historical facades retain

package/docs/en/commands/mcp.md

@@ -0,0 +1,99 @@
+# Native MCP
+
+[Português](../../pt-BR/commands/mcp.md)
+
+## Purpose
+
+Expose local semantic project, context, memory, change, task, evidence, and Observer state without
+arbitrary filesystem reads or a dynamic `@latest` dependency.
+
+## When to use
+
+Use it when an MCP client must discover and query WendKeep or execute a causal write explicitly
+authorized by capability, active context, and lease.
+
+## When not to use
+
+Do not use it for delivery, merge, push, tag, publication, deletion, or generic file access. Those
+operations remain outside the default surface and use the appropriate CLI/ASSURE workflows.
+
+## Prerequisites
+
+- `wendkeep` installed in the project or available through its binary;
+- a valid project↔Vault binding;
+- Node.js 18+ for Core; Node.js 22.13+ only for Observer SQL;
+- for writes: a current causal session, active context, and authorization.
+
+## Syntax
+
+```powershell
+wendkeep mcp serve --vault <vault>
+wendkeep mcp serve --vault <vault> --timeout-ms <n>
+wendkeep mcp config --client generic --vault <vault>
+wendkeep mcp config --client claude --vault <vault>
+wendkeep mcp config --client codex --vault <vault>
+wendkeep mcp config --client cursor --vault <vault>
+```
+
+## Options and exit codes
+
+- `--vault <path>` selects the Vault; it is required by `config` and optional for `serve`. Without
+  it, stdio starts independently of the process checkout and lazily resolves each call's binding
+  and audit ledger from the declared `project_root`; one project never reuses another's auditor.
+- `--timeout-ms <n>` accepts 1 through 120000; the per-call default is 10000.
+- `--client` accepts `generic`, `claude`, `codex`, or `cursor`.
+- Exit 0: transport/configuration completed; Exit 2: invalid subcommand, client, or option.
+- Tool errors use an MCP `isError` result with `schema_version: 1`, an `MCP_*` code, sanitized
+  message, and `retryable`; they do not terminate the server.
+
+## Examples
+
+`init` generates this reproducible generic entry:
+
+```json
+{
+  "mcpServers": {
+    "wendkeep-vault": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["--no-install", "wendkeep", "mcp", "serve", "--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`.
+
+Writes: `wendkeep_memory_assert`, `wendkeep_checkpoint_create`, `wendkeep_context_select`,
+`wendkeep_task_claim`, `wendkeep_task_complete`, and `wendkeep_handoff_publish`.
+
+## 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.
+
+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
+gates. The local `.brain/runtime/MCP_AUDIT.jsonl` audit stores only tool, effect, capability,
+outcome, code, and duration—never arguments or payloads.
+
+## Common errors and diagnosis
+
+- `MCP_TOOL_UNKNOWN`: the tool/alias is absent from the verified catalog; update client or package.
+- `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_RUNTIME_UNSUPPORTED`: use Node 22.13+ for Observer; Core remains available.
+
+## Next steps
+
+Run `wendkeep mcp config --client <client> --vault <vault>`, install the snippet in the client, and
+perform `initialize` → `tools/list` → a known read. See [Context](context.md) for causal identity and
+[Observer](observer.md) for the optional SQL backend.

package/docs/en/commands/operating-profiles.md

@@ -138,6 +138,10 @@ ownership to the native LLM harness.
   missing, ambiguous, or stale context fails closed without a partial mutation.
 - `.wendkeep.json` stays on `schemaVersion: 1`; the additive field is, for example,
   `"harness": { "profile": "GOVERN" }`. A legacy binding without it also resolves to `GOVERN`.
+- In a linked worktree, `profile use` and `profile status` use the main worktree's canonical
+  binding discovered through the shared Git registry. The selection is persisted once for the
+  project and the linked worktree's versioned `.wendkeep.json` remains unchanged, including on
+  Windows when long paths and 8.3 aliases identify the same Vault.
 - A corrupt binding never means `OFF`. When the payload or legacy integration identifies one
   unambiguous Vault, Keep Core remains active under `GOVERN` and the hook exposes a diagnostic;
   mutation guards fail closed until the binding is repaired. Invalid local configuration, a