wendkeep 0.80.2 → 0.85.1

package/docs/en/commands/portable.md

@@ -0,0 +1,88 @@
+# Portable state
+
+**English** · [Português](../../pt-BR/commands/portable.md)
+
+## Purpose
+
+Publish the reviewable Vault subset and a compact `active-work` snapshot to
+`.wendkeep/portable/state.json` without turning private runtime into Git data. The command never
+runs `git add`, commit, or push.
+
+## When to use
+
+Use `portable export` before a PR that shares specs/decisions or before moving machines;
+`portable status`/`diff` to review drift; and `portable import` after creating and binding the Vault
+of a clean clone.
+
+## When not to use
+
+Do not use it as real-time remote sync, transcript backup, secret transport, or a replacement for
+`context switch`. Import restores a resume hint but never invents a session ID, active context, or
+lease.
+
+## Prerequisites
+
+- A Git project bound to its Vault through `.wendkeep.json`.
+- Valid `PROJECT.json`; a worktree registry when generating new identity.
+- Human review of the JSON before adding it to Git.
+
+## Syntax
+
+```bash
+npx --no-install wendkeep portable status [--project <root>] [--vault <vault>] [--input <file>] [--json]
+npx --no-install wendkeep portable export [--project <root>] [--vault <vault>] [--output <file>] [--json]
+npx --no-install wendkeep portable import [--project <root>] [--vault <vault>] [--input <file>] [--json]
+npx --no-install wendkeep portable diff [--project <root>] [--vault <vault>] [--input <file>] [--json]
+```
+
+## Options and exit codes
+
+- `--input`/`--output`: override the default `.wendkeep/portable/state.json` path.
+- `--project`/`--vault`: select the binding; `--json` emits structured results.
+- Exit `0`: valid status/export/import or equal diff. Exit `1`: different diff. Exit `2`: invalid
+  schema, project, integrity, path, or argument.
+- `status` returns `not_configured`, `current`, `diverged`, or `invalid`.
+
+## Examples
+
+```bash
+npx --no-install wendkeep portable export
+npx --no-install wendkeep portable diff
+git diff -- .wendkeep/portable/state.json
+git add -- .wendkeep/portable/state.json
+```
+
+`.gitattributes` fixes LF for `/.wendkeep/portable/*.json`. Projects may ignore this directory and
+retain the complete local Keep Core.
+
+## Expected result
+
+The inventory classifies `.brain/CORE.md`, ADRs, proposal/design/tasks, and `specs/` deltas as
+`authored`; `07-Specs`, evidence/verification/verdict, and archives as `derived`; registries, leases,
+locks, outboxes, and full receipts as `runtime`; transcripts, prompts/responses, tokens/costs,
+secrets, and environment as `secret`. Only authored data and `07-Specs` enter the bundle. Export
+normalizes LF, excludes symlinks/hardlinks, and removes Windows/POSIX absolute paths, known token
+shapes, and values of `Authorization`, `token`, `password`, `secret`, and `api_key`.
+
+Each `active-work` contains `project_id`, `repository_id`, `change_slug`, `task_id`, branch/SHAs,
+hashes, completed/next work, blockers, references, timestamp, and revision. It never contains
+`work_session_id`, `worktree_id`, local paths, or tokens. Import stores the private hint in
+`.brain/runtime/PORTABLE_ACTIVE_WORK.json`; export/import append metadata and hashes only to
+`.brain/runtime/PORTABLE_PROVENANCE.jsonl`.
+
+## Common errors and diagnosis
+
+- `WENDKEEP_PORTABLE_STALE`: incoming revision is older than local state.
+- `WENDKEEP_PORTABLE_CONFLICT`: the same revision carries a different hash.
+- `WENDKEEP_PORTABLE_PATH_UNSAFE`: traversal, non-allowlisted path, or symlink.
+- `WENDKEEP_PORTABLE_INTEGRITY`: content/hash was tampered with.
+
+All fail before the first write. `doctor` reports `[portable] diverged` and recommends diff/export;
+`not_configured` is a valid opt-out. Schemas: `schema/portable-state-v1.schema.json` and
+`schema/portable-active-work-v1.schema.json`.
+
+## Next steps
+
+Review the small human-readable diff, add only the confirmed snapshot, and open the PR. In the
+destination clone, run `init`, `portable import`, inspect `portable status`, and start a new causal
+session.

package/docs/en/commands/sync-protocol.md

@@ -0,0 +1,58 @@
+# Local-first sync protocol
+
+**English** · [Português](../../pt-BR/commands/sync-protocol.md)
+
+## Purpose
+
+Synchronize authored state and active work across machines without making the backend authoritative. The protocol uses revisions, compare-and-swap (CAS), causality, a durable outbox, expiring leases, and explicit conflicts; it never silently applies last-write-wins.
+
+## When to use
+
+Use `wendkeep sync push` and `pull` when one project must share its portable state across devices, branches, or worktrees. Sync is optional and creates runtime only after a write operation.
+
+## When not to use
+
+Do not use it as a private-data backup, transcript transport, or Git replacement. CORE, credentials, and local runtime are excluded. Private content may travel only inside an authenticated E2E envelope.
+
+## Prerequisites
+
+The project must be bound to a Vault and have `.wendkeep/portable/state.json`, generated by `wendkeep portable export`. Choose stable actor and device identities. Select a backend with `--remote` or `--url`; tokens are read only from the environment variable named by `--token-env`.
+
+## Syntax
+
+```text
+wendkeep sync status [--project <dir>] [--json]
+wendkeep sync push --actor <id> --device <id> (--remote <dir> | --url <url>)
+wendkeep sync pull (--remote <dir> | --url <url>) [--no-import]
+wendkeep sync conflicts [--json]
+wendkeep sync resolve --record <key> --select <event> --reason <text> --actor <id> --device <id> (--remote <dir> | --url <url>)
+```
+
+## Options and exit codes
+
+`--remote` uses the reference filesystem adapter; `--url` uses the replaceable HTTP adapter. `--token-env NAME` reads a secret without persisting it. `--no-import` downloads and validates without applying portable state. Exit `0` means converged, `1` an operational failure, and `2` invalid usage or a conflict requiring a human decision.
+
+## Examples
+
+```powershell
+wendkeep portable export --project .
+wendkeep sync push --project . --actor roger --device desktop --remote D:\wk-sync
+wendkeep sync pull --project . --remote D:\wk-sync
+wendkeep sync conflicts --project . --json
+```
+
+## Expected result
+
+Retries are idempotent. Out-of-order events wait for causal parents. Concurrent writes from one revision form an order-independent stable conflict set. Resolution creates a new event and an auditable decision; tombstones and lease history remain intact.
+
+`doctor`, the sanitized Observer snapshot, and the semantic MCP surface expose only health, counts, and candidate metadata; those queries never return authored payloads or local paths.
+
+## Common errors and diagnosis
+
+Use `wendkeep doctor` and `wendkeep sync status`. `WENDKEEP_SYNC_BACKEND_UNAVAILABLE` retains events in the outbox for retry. `WENDKEEP_SYNC_OUTBOX_CORRUPT` blocks sending until local review. Conflicts appear in `sync conflicts` and are never resolved automatically.
+
+Threat model: duplicate delivery, replay, and reordering are contained by hashes, idempotent IDs, revisions, and causal parents. Partitions retain the outbox. Client clocks do not choose a lease winner. A malicious backend can omit or retain events, but cannot forge content without breaking hashes or read private AES-256-GCM envelopes. Key and timestamp metadata may still leak; losing a private key is unrecoverable. Backend rollback is detectable through cursors and revisions, while availability remains the operator's responsibility.
+
+## Next steps
+
+Review conflicts with `wendkeep sync conflicts`, resolve them explicitly, and confirm state with `wendkeep portable diff`. See [Portable state](portable.md) and [Local Observer](observer.md).

package/docs/en/commands/tdd.md

@@ -0,0 +1,96 @@
+# Causal TDD attestation
+
+**English** · [Português](../../pt-BR/commands/tdd.md)
+
+## Purpose
+
+`wendkeep tdd` records auditable proof that a test bound to a task and requirement was observed
+RED and then GREEN in the same project, repository, worktree, work session, and change. It
+complements coverage, mutation, sensors, and review; it replaces none of them.
+
+## When to use
+
+Use before and after implementing testable behavior bound to a `[tdd]` task.
+
+## When not to use
+
+Do not use it for health checks, already-green tests, or environment failures. Use sensors/doctor
+for infrastructure and a human waiver only when the behavior is genuinely not testable.
+
+## Prerequisites
+
+An active change, causal active context, task with `[req:ID]`, project-relative test, and a
+deterministic command that can be repeated in RED and GREEN.
+
+## Syntax
+
+```bash
+wendkeep tdd red <task-id> --requirement <ID> --test <path> --command "<command>" --session <id>
+wendkeep tdd green <task-id> --command "<command>" --session <id>
+wendkeep tdd status <task-id> --session <id> [--json]
+wendkeep tdd waive <task-id> --requirement <ID> --reason "<reason>" --authority "<human>" --session <id>
+```
+
+`--test` is repeatable. Every path is project-relative. `--change <slug>`, `--project <root>`,
+`--vault <vault>`, and `--json` follow the other commands' conventions.
+
+## RED → GREEN contract
+
+- Valid RED is a behavioral failure. An already-green test, syntax/import error, missing module,
+  invalid configuration, or unknown command yields `invalid`.
+- GREEN must preserve the RED causal identity and branch, pass, and observe a production change
+  after RED. GREEN from another worktree, task, or requirement cannot close the cycle.
+- A changed test path is recorded in `review_flags`. A refactor or commit after GREEN makes proof
+  stale until `tdd green` runs again; the previous GREEN remains in `green_history`.
+- A waiver requires both a reason and explicit human authority. Silent waivers do not exist.
+
+The `08-Mudanças/<slug>/tdd-attestations.json` store retains SHA-256 digests, a sanitized tail
+bounded to 2,000 characters, and relative paths — never full output. The Evidence Envelope,
+`verificacao.json`, handoff, and Observer expose the attestation and its ID to reviewers.
+
+## Profile gate
+
+- `OFF` and `FLOW`: optional.
+- `GUIDE`: recommended for testable behavior.
+- `GOVERN`: required when a task carries `[tdd]`.
+- `ASSURE`: required for an executable task with a requirement or sensor, unless explicitly waived.
+
+Mark a task as follows:
+
+```markdown
+- [ ] 1.1 persists the preference [req:UI-1] [sensor:tests] [tdd]
+```
+
+Stale/invalid proof, a surviving mutant, or a missing GREEN/waiver produces
+`TASK_TDD_ATTESTATION_MISSING_OR_INVALID` in the Task Contract and blocks Execute → Verify.
+
+## Examples
+
+```bash
+wendkeep tdd red 1.1 --requirement UI-1 --test tests/ui.test.mjs --command "npm test" --session abc
+wendkeep tdd green 1.1 --command "npm test" --session abc
+wendkeep tdd status 1.1 --session abc --json
+```
+
+## Expected result
+
+A causal entry in `tdd-attestations.json`, referenced by the Task Contract and evidence surfaces,
+with an auditable current state and revalidation history.
+
+## Options and exit codes
+
+- `0`: the observed state is valid (`red-observed`, `green-observed`, or `waived`; green/waived status).
+- `1`: observation ran but is `invalid`, RED has not reached GREEN, or status is stale.
+- `2`: invalid usage, context, identity, store, or waiver authority.
+
+## Common errors and diagnosis
+
+- `TDD_RED_ALREADY_GREEN`: first write a discriminating test that fails.
+- `TDD_RED_INFRASTRUCTURE_FAILURE`: fix import, syntax, configuration, or command and repeat RED.
+- `TDD_GREEN_STALE_AFTER_REFACTOR`: repeat GREEN in the current checkout.
+- `TDD_IMPLEMENTATION_NOT_AFTER_RED`: proof observed no production diff after RED.
+
+## Next steps
+
+Run [verify](verify.md), request the independent pass, and continue the
+[change lifecycle](changes-and-verification.md).

package/docs/en/commands/verify.md

@@ -87,6 +87,11 @@ temporary in the same directory and an atomic rename. In deep mode, `verificacao
 `verdict.json` carry the same `evidenceEnvelopeId` and complete `evidenceBinding`; the independent
 reviewer must preserve both.
 
+The envelope carries `tdd_attestations`, and `verificacao.json` carries `tddAttestations`. Under GOVERN, a task marked
+`[tdd]` requires a current GREEN or explicit waiver; under ASSURE this applies to testable
+behavior. A later refactor/commit or a surviving mutant invalidates GREEN in the Task Contract.
+See [Causal TDD attestation](tdd.md).
+
 V1 evidence remains readable as `legacy-unbound`, never as equivalent authority. Run
 `wendkeep change status <slug>` to inspect `bound`, `stale`, or `context-mismatch`.
 

package/docs/pt-BR/commands/capabilities.md

@@ -0,0 +1,82 @@
+# Capacidades dos hosts
+
+[English](../../en/commands/capabilities.md)
+
+## Objetivo
+
+Mostrar a matriz versionada das 17 capacidades de lifecycle e efeitos que cada host realmente
+oferece como `native`, `adapted`, `polled`, `manual` ou `unavailable`.
+
+## Quando usar
+
+Use antes de depender de hooks de sessão, tool use, conclusão de tarefa, subagentes, transcript ou
+usage; e ao diagnosticar diferenças entre Claude Code, Codex, Pi e clientes MCP/CLI genéricos.
+
+## Quando não usar
+
+Não use a matriz como prova de que um evento manual ocorreu. Estado `manual` tem autoridade apenas
+`reported`; somente eventos native/adapted/polled podem ser `verified`.
+
+## Pré-requisitos
+
+Node.js 18+ e o pacote WendKeep instalado. O comando é puro e não requer Vault. A cobertura gravada
+na sessão usa o host detectado e pode receber a versão por `WENDKEEP_HOST_VERSION`.
+
+## Sintaxe
+
+```text
+wendkeep capabilities [--host <claude|codex|pi|generic-mcp>] [--host-version <v>] [--json]
+```
+
+Sem `--host`, o comando lista todos os manifests. Host desconhecido degrada explicitamente para
+`generic-mcp`; versão fora da faixa fica `HOST_VERSION_UNPROVEN`.
+
+## Opções e códigos de saída
+
+- `--host <id>` seleciona um host; ids desconhecidos não são promovidos silenciosamente.
+- `--host-version <v>` compara o major observado com o manifest.
+- `--json` emite o contrato `host-coverage-v1`.
+- exit `0`: matriz emitida; exit `2`: argumento inválido.
+
+`wendkeep.sensors.json` pode declarar `requires_host_capabilities` e waivers humanos explícitos em
+`host_capability_waivers`. `verify` sai `1` se uma capacidade requerida estiver manual/unavailable
+sem waiver com `authority: human`, `approved_by` e `reason`. ASSURE aplica a mesma regra ao handoff.
+
+## Exemplos
+
+```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": "confirmação manual"
+  }]
+}
+```
+
+## Resultado esperado
+
+A cobertura entra no registro da sessão, active context, handoff, envelope de evidência e resumo do
+Observer. Lacunas são injetadas no contexto no início, antes que o agente assuma paridade inexistente.
+Efeitos MCP vêm do manifest assinado: reads conhecidos pulam o mutation gate; writes/destructive
+continuam sujeitos aos gates; efeito desconhecido falha fechado.
+
+## Erros comuns e diagnóstico
+
+- `HOST_UNKNOWN`: use o fallback MCP/CLI ou publique um adapter isolado.
+- `HOST_VERSION_UNPROVEN`: atualize o manifest ou opere em modo degradado.
+- `HOST_CAPABILITY_UNAVAILABLE`: remova a dependência ou obtenha waiver humano explícito.
+- `HOST_ENVELOPE_UNKNOWN`: versão/evento não reconhecido nunca vira evidência verificada.
+- Tool com nome parecido não define efeito; confira o catálogo assinado com `wendkeep mcp inspect`.
+
+## Próximos passos
+
+Veja [MCP nativo](mcp.md), [sessões e importação](sessions-and-import.md),
+[changes e verificação](changes-and-verification.md) e [Observer](observer.md).

package/docs/pt-BR/commands/getting-started.md

@@ -86,8 +86,9 @@ cofre efetivamente selecionado.
 
 Quando MCP está habilitado, o `init` preserva propriedades e servidores existentes em `.mcp.json`
 e adiciona `wendkeep-vault`. Se o JSON existente for inválido, o arquivo original permanece byte
-a byte intacto e a proposta reconciliada é gravada em `.mcp.json.new`. Desde a versão 0.65, essa
-composição pertence ao kernel MCP privado, sem alterar comandos, flags ou a superfície npm pública.
+a byte intacto e a proposta reconciliada é gravada em `.mcp.json.new`. A entrada executa o servidor
+semântico instalado com `npx --no-install wendkeep mcp serve --vault <vault>`, sem download
+dinâmico `@latest`. Veja [MCP nativo](mcp.md) para tools, gates, limites e snippets de clientes.
 
 As regras puras que projetam os hooks de Claude/Codex e interpretam envelopes, transcripts, uso e
 identidade pertencem ao workspace privado `@wendkeep/integrations`. As fachadas históricas mantêm

package/docs/pt-BR/commands/mcp.md

@@ -0,0 +1,99 @@
+# MCP nativo
+
+[English](../../en/commands/mcp.md)
+
+## Objetivo
+
+Expor estado semântico local de projeto, contexto, memória, changes, tarefas, evidência e Observer
+sem leitura arbitrária do filesystem ou dependência dinâmica `@latest`.
+
+## Quando usar
+
+Use quando um cliente MCP precisar descobrir e consultar o WendKeep ou executar um write causal
+explicitamente autorizado por capability, active context e lease.
+
+## Quando não usar
+
+Não use para delivery, merge, push, tag, publicação, exclusão ou acesso genérico a arquivos. Essas
+operações ficam fora da superfície padrão e continuam nos fluxos CLI/ASSURE apropriados.
+
+## Pré-requisitos
+
+- pacote `wendkeep` instalado no projeto ou acessível pelo binário;
+- binding válido de projeto↔Vault;
+- Node.js 18+ para Core; Node.js 22.13+ somente para Observer SQL;
+- para writes: sessão causal, active context e autorização vigentes.
+
+## Sintaxe
+
+```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>
+```
+
+## Opções e códigos de saída
+
+- `--vault <path>` seleciona o Vault; é obrigatório em `config` e opcional em `serve`. Sem a
+  flag, o stdio inicia sem depender do checkout do processo e resolve o binding/auditoria de cada
+  chamada somente pelo `project_root` declarado; um projeto nunca reutiliza o auditor de outro.
+- `--timeout-ms <n>` aceita 1 a 120000; padrão 10000 por chamada.
+- `--client` aceita `generic`, `claude`, `codex` ou `cursor`.
+- Exit 0: transporte/configuração concluído; Exit 2: subcomando, cliente ou opção inválida.
+- Tool errors usam resultado MCP `isError` com `schema_version: 1`, código `MCP_*`, mensagem
+  sanitizada e `retryable`; não encerram o servidor.
+
+## Exemplos
+
+O `init` gera a entrada genérica reproduzível:
+
+```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` e
+`wendkeep_observer_query`.
+
+Writes: `wendkeep_memory_assert`, `wendkeep_checkpoint_create`, `wendkeep_context_select`,
+`wendkeep_task_claim`, `wendkeep_task_complete` e `wendkeep_handoff_publish`.
+
+## Resultado esperado
+
+O handshake e `tools/list` retornam JSON-RPC válido. Cada tool declara effect/capability e schemas
+versionados. Reads conhecidas não entram no mutation gate, mas mantêm binding explícito de
+projeto/worktree, paginação por cursor, budget padrão de 1 MiB, redaction, timeout e cancelamento.
+Observer aparece indisponível abaixo de Node 22.13 sem impedir Core no Node 18.
+
+Writes exigem `project_root`, `session_id`, `active_context_id`, `actor`, `reason`, capability exata
+e `lease.id`/`lease.expires_at`; o executor revalida a autorização causal e os gates da CLI. A
+auditoria local `.brain/runtime/MCP_AUDIT.jsonl` guarda somente tool, effect, capability, resultado,
+código e duração — nunca argumentos ou payload.
+
+## Erros comuns e diagnóstico
+
+- `MCP_TOOL_UNKNOWN`: tool/alias não consta no catálogo verificado; atualize o cliente ou pacote.
+- `MCP_CAPABILITY_REQUIRED` / `MCP_SCOPE_AUTH_REQUIRED`: capability ausente ou não autorizada.
+- `MCP_LEASE_EXPIRED`: obtenha autorização/lease nova; não altere timestamp manualmente.
+- `MCP_PROJECT_SCOPE_MISMATCH`: `project_root` e `worktree_root` pertencem a bindings diferentes.
+- `MCP_REQUEST_TOO_LARGE` / `MCP_RESPONSE_TOO_LARGE`: use `limit` e o cursor retornado.
+- `MCP_RUNTIME_UNSUPPORTED`: use Node 22.13+ para Observer; Core permanece disponível.
+
+## Próximos passos
+
+Rode `wendkeep mcp config --client <client> --vault <vault>`, instale o snippet no cliente e faça
+`initialize` → `tools/list` → uma read conhecida. Para identidade causal, veja [Contexto](context.md);
+para o backend SQL opcional, veja [Observer](observer.md).

package/docs/pt-BR/commands/portable.md

@@ -0,0 +1,87 @@
+# Estado portátil
+
+**PT-BR** · [English](../../en/commands/portable.md)
+
+## Objetivo
+
+Publicar em `.wendkeep/portable/state.json` a parte revisável do Vault e um snapshot compacto
+`active-work`, sem transformar runtime privado em dados de Git. O comando nunca executa `git add`,
+commit ou push.
+
+## Quando usar
+
+Use `portable export` antes de um PR que compartilhe specs/decisões ou antes de trocar de máquina;
+`portable status`/`diff` para revisar drift; e `portable import` depois de criar e vincular o Vault
+de um clone limpo.
+
+## Quando não usar
+
+Não use como sync remoto em tempo real, backup de transcritos, transporte de secrets ou substituto
+de `context switch`. O import restaura uma indicação de retomada, mas não inventa session ID, active
+context ou lease.
+
+## Pré-requisitos
+
+- Projeto Git vinculado ao Vault por `.wendkeep.json`.
+- `PROJECT.json` válido; worktree registry para gerar identidade nova.
+- Revisão humana do JSON antes de adicioná-lo ao Git.
+
+## Sintaxe
+
+```powershell
+npx --no-install wendkeep portable status [--project <raiz>] [--vault <cofre>] [--input <arquivo>] [--json]
+npx --no-install wendkeep portable export [--project <raiz>] [--vault <cofre>] [--output <arquivo>] [--json]
+npx --no-install wendkeep portable import [--project <raiz>] [--vault <cofre>] [--input <arquivo>] [--json]
+npx --no-install wendkeep portable diff [--project <raiz>] [--vault <cofre>] [--input <arquivo>] [--json]
+```
+
+## Opções e códigos de saída
+
+- `--input`/`--output`: substituem o path padrão `.wendkeep/portable/state.json`.
+- `--project`/`--vault`: selecionam o binding; `--json` emite resultado estruturado.
+- Exit `0`: status/export/import válido ou diff igual. Exit `1`: diff diferente. Exit `2`: schema,
+  project, integridade, path ou argumento inválido.
+- `status` retorna `not_configured`, `current`, `diverged` ou `invalid`.
+
+## Exemplos
+
+```powershell
+npx --no-install wendkeep portable export
+npx --no-install wendkeep portable diff
+git diff -- .wendkeep/portable/state.json
+git add -- .wendkeep/portable/state.json
+```
+
+O `.gitattributes` fixa LF para `/.wendkeep/portable/*.json`. Projetos podem ignorar essa pasta e
+continuar usando todo o Keep Core local.
+
+## Resultado esperado
+
+O inventário classifica `.brain/CORE.md`, ADRs, proposta/design/tarefas e deltas de `specs/` como
+`authored`; `07-Specs`, evidência/verificação/verdict e arquivo como `derived`; registries, leases,
+locks, outboxes e receipts completos como `runtime`; transcritos, prompts/respostas, tokens/custos,
+secrets e environment como `secret`. Só authored e `07-Specs` entram. O export normaliza LF,
+exclui symlink/hardlink e remove caminhos absolutos Windows/POSIX, tokens conhecidos e valores de
+`Authorization`, `token`, `password`, `secret` e `api_key`.
+
+Cada `active-work` contém `project_id`, `repository_id`, `change_slug`, `task_id`, branch/SHAs,
+hashes, tarefas concluídas/próximas, blockers, references, timestamp e revision. Nunca contém
+`work_session_id`, `worktree_id`, path local ou token. O import grava a dica privada em
+`.brain/runtime/PORTABLE_ACTIVE_WORK.json`; export/import registram somente metadados e hashes em
+`.brain/runtime/PORTABLE_PROVENANCE.jsonl`.
+
+## Erros comuns e diagnóstico
+
+- `WENDKEEP_PORTABLE_STALE`: revision recebida é inferior à local.
+- `WENDKEEP_PORTABLE_CONFLICT`: mesma revision tem hash diferente.
+- `WENDKEEP_PORTABLE_PATH_UNSAFE`: traversal, path fora da allowlist ou symlink.
+- `WENDKEEP_PORTABLE_INTEGRITY`: conteúdo/hash foi adulterado.
+
+Todos falham antes da primeira escrita. O `doctor` mostra `[portable] diverged` e recomenda diff/export;
+`not_configured` é opt-out válido. Schemas: `schema/portable-state-v1.schema.json` e
+`schema/portable-active-work-v1.schema.json`.
+
+## Próximos passos
+
+Revise o diff humano pequeno, adicione somente o snapshot confirmado e abra o PR. No clone destino,
+execute `init`, `portable import`, consulte `portable status` e inicie uma nova sessão causal.

package/docs/pt-BR/commands/sync-protocol.md

@@ -0,0 +1,58 @@
+# Protocolo local-first de sync
+
+**PT-BR** · [English](../../en/commands/sync-protocol.md)
+
+## Objetivo
+
+Sincronizar estado autorado e trabalho ativo entre máquinas sem transformar o backend em autoridade. O protocolo usa revisões, compare-and-swap (CAS), causalidade, outbox durável, leases expirantes e conflitos explícitos; não usa last-write-wins silencioso.
+
+## Quando usar
+
+Use `wendkeep sync push` e `pull` quando o mesmo projeto precisa compartilhar seu estado portátil entre dispositivos, branches ou worktrees. O sync é opcional e só cria runtime depois de uma operação de escrita.
+
+## Quando não usar
+
+Não use como backup de dados privados, transporte de transcripts ou substituto de Git. CORE, credenciais e runtime local não entram no protocolo. Conteúdo privado só pode ser enviado como envelope E2E autenticado.
+
+## Pré-requisitos
+
+O projeto deve estar vinculado a um Vault e possuir `.wendkeep/portable/state.json`, gerado por `wendkeep portable export`. Defina identidades estáveis de ator e dispositivo. Escolha um backend por `--remote` ou `--url`; tokens são lidos apenas da variável indicada por `--token-env`.
+
+## Sintaxe
+
+```text
+wendkeep sync status [--project <dir>] [--json]
+wendkeep sync push --actor <id> --device <id> (--remote <dir> | --url <url>)
+wendkeep sync pull (--remote <dir> | --url <url>) [--no-import]
+wendkeep sync conflicts [--json]
+wendkeep sync resolve --record <chave> --select <evento> --reason <texto> --actor <id> --device <id> (--remote <dir> | --url <url>)
+```
+
+## Opções e códigos de saída
+
+`--remote` usa o adaptador de referência em filesystem; `--url` usa HTTP substituível. `--token-env NOME` lê o segredo sem gravá-lo. `--no-import` baixa e valida sem aplicar ao estado portátil. O código `0` indica convergência, `1` falha operacional, `2` uso inválido ou conflito que exige decisão humana.
+
+## Exemplos
+
+```powershell
+wendkeep portable export --project .
+wendkeep sync push --project . --actor roger --device desktop --remote D:\wk-sync
+wendkeep sync pull --project . --remote D:\wk-sync
+wendkeep sync conflicts --project . --json
+```
+
+## Resultado esperado
+
+Reenvios são idempotentes. Eventos fora de ordem aguardam seus pais causais. Escritas concorrentes da mesma revisão formam um conjunto de conflito estável, independente da ordem de chegada. Uma resolução gera novo evento e decisão auditável; tombstones e histórico de lease são preservados.
+
+O `doctor`, o snapshot sanitizado do Observer e a superfície semântica MCP expõem apenas saúde, contagens e metadados de candidatos; payload autoral e caminhos locais não são retornados por essas consultas.
+
+## Erros comuns e diagnóstico
+
+Use `wendkeep doctor` e `wendkeep sync status`. `WENDKEEP_SYNC_BACKEND_UNAVAILABLE` mantém eventos no outbox para retry. `WENDKEEP_SYNC_OUTBOX_CORRUPT` bloqueia envio até revisão local. Conflitos aparecem em `sync conflicts` e nunca são resolvidos automaticamente.
+
+Modelo de ameaças: entrega duplicada, replay e reordenação são neutralizados por hashes, IDs idempotentes, revisões e pais causais. Partições mantêm o outbox. Relógios de clientes não decidem o vencedor de lease. Backend malicioso pode omitir ou reter eventos, mas não pode forjar conteúdo sem quebrar hashes nem ler envelopes privados AES-256-GCM. Metadados de chaves e horários ainda podem vazar; perda de chave privada é irrecuperável. Rollback do backend é detectável por cursor/revisão, mas disponibilidade continua sendo responsabilidade do operador.
+
+## Próximos passos
+
+Revise conflitos com `wendkeep sync conflicts`, resolva-os explicitamente e confirme o estado com `wendkeep portable diff`. Veja também [Estado portátil](portable.md) e [Observer local](observer.md).