wendkeep 0.58.1 → 0.59.0

package/docs/pt-BR/commands/maintenance-and-diagnostics.md

@@ -0,0 +1,77 @@
+# Manutenção e diagnóstico
+
+**PT-BR** · [English](../../en/commands/maintenance-and-diagnostics.md)
+
+## Objetivo
+
+Inspecionar a saúde do cofre e manter definições, tema e versão alinhados sem usar comandos de
+change como teste global.
+
+## Quando usar
+
+Use depois de instalar/atualizar, diante de warnings dos hooks ou antes de iniciar uma change.
+
+## Quando não usar
+
+Não use `wendkeep verify` quando nenhuma change estiver ativa. Ele prova tarefas de uma change;
+não substitui o doctor.
+
+## Pré-requisitos
+
+Execute na raiz do projeto ou informe `--project`/`--vault` explicitamente.
+
+## Sintaxe
+
+```bash
+npx wendkeep doctor [--vault <cofre>]
+npx wendkeep sync-defs [--check|--reseed] --vault <cofre> --project <raiz>
+npx wendkeep theme sync --vault <cofre>
+npx wendkeep --version
+npx wendkeep --help
+```
+
+## Opções e códigos de saída
+
+- `doctor` é read-only; exit `0` aceita warnings recuperáveis e exit não zero indica falha.
+- Em v2, `doctor`/`memory status --gate` correlacionam `last_memory_attempt` (mode, disposition,
+  event IDs e checkpoint) com outbox, ledger e SHARED; não inferem saúde só pela revision atual.
+- `revision: 0` após migração válida, sem attempt v2, é saudável. Attempt `degraded` cujos eventos
+  continuam duráveis na outbox/ledger é warning recuperável.
+- Attempt ambíguo, event ID perdido (ausente de ledger e outbox), estado `projected` apenas na
+  outbox ou checkpoint divergente são falhas bloqueantes.
+- `sync-defs --check` detecta drift sem gravar; `--reseed` restaura skills `wk-*` do pacote.
+- `theme sync` reaplica snippet CSS e grupos do grafo sem recriar o cofre.
+- `wendkeep --version` imprime a versão executada; `wendkeep --help` lista a interface pública.
+
+## Exemplos
+
+Checklist pós-atualização:
+
+```bash
+npx wendkeep --version
+npx wendkeep sync-defs --check --vault .MeuApp-vault --project .
+npx wendkeep doctor --vault .MeuApp-vault
+npx wendkeep memory status --gate --vault .MeuApp-vault
+```
+
+## Resultado esperado
+
+O doctor nomeia sessões, registry, links, notas, preços, derivadas e memória como saudáveis ou
+fornece um comando específico de diagnóstico/reparo. Na memória, ele distingue vazio inicial
+válido, replay pendente recuperável e lifecycle perdido/divergente. Nenhum reparo é aplicado
+implicitamente nem o conteúdo privado do erro do projector é reproduzido no relatório.
+
+## Erros comuns e diagnóstico
+
+- `no vault`: execute da raiz vinculada ou passe `--vault`.
+- `defs stale`: confirme a versão e rode `sync-defs --reseed`.
+- Vault legado: é warning não bloqueante; planeje `memory migrate --apply` separadamente.
+- `degraded` + outbox íntegra: warning; preserve a outbox e permita replay idempotente.
+- `ambiguous`, publicação perdida ou checkpoint divergente: bloqueante; preserve registry, ledger,
+  outbox e SHARED para correlacionar `last_memory_attempt` antes de reparar.
+- Bundle corrompido: preserve a evidência e use `memory status --gate` antes de `memory repair`.
+
+## Próximos passos
+
+Veja [instalação e primeiro uso](getting-started.md), [memória](memory.md) e
+[verificação de changes](verify.md).

package/docs/pt-BR/commands/memory-migration.md

@@ -0,0 +1,73 @@
+# Migração de memória legada para v2
+
+**PT-BR** · [English](../../en/commands/memory-migration.md)
+
+## Objetivo
+
+Converter um `SHARED_MEMORY.md` legado em bundle v2 auditável sem sobrescrever CORE nem promover
+relatos antigos silenciosamente.
+
+## Quando usar
+
+Use quando `memory status` retorna `legacy` e a equipe está pronta para curar o conteúdo convertido.
+
+## Quando não usar
+
+Não migre automaticamente durante `init`, `sync`, SessionStop ou como tentativa de silenciar um
+warning. Não aplique enquanto um backup/estado esperado não estiver claro.
+
+## Pré-requisitos
+
+- CORE válido e bytes legados preservados.
+- Vault sem corrupção v2 parcial.
+- Revisão humana dos candidates que serão criados.
+
+## Sintaxe
+
+```bash
+npx wendkeep memory status --gate --vault <cofre>
+npx wendkeep memory migrate --vault <cofre>
+npx wendkeep memory migrate --apply --vault <cofre>
+```
+
+## Opções e códigos de saída
+
+- Sem `--apply`, `wendkeep memory migrate` é dry-run e não grava.
+- `--apply` cria backup, converte conteúdo legado em candidates e publica bundle v2 válido.
+- Um bundle recém-migrado pode começar saudável em `revision: 0`: ainda não houve attempt v2 nem
+  evento elegível, portanto zero não significa estagnação.
+- Exit `0` indica prévia/aplicação consistente; exit diferente de zero preserva o estado original
+  e informa a falha.
+
+## Exemplos
+
+```bash
+npx wendkeep memory migrate --vault .MeuApp-vault
+# revise a prévia
+npx wendkeep memory migrate --apply --vault .MeuApp-vault
+npx wendkeep memory status --gate --vault .MeuApp-vault
+```
+
+## Resultado esperado
+
+O vault recebe ledger/projeção v2 coerentes, backup do SHARED legado e candidates para fatos sem
+evidência. CORE não é editado e conteúdo não verificado não vira estado ativo automaticamente.
+Após a migração, o próximo `UserPromptSubmit` recupera uma única activation se o registry legado
+estava fechado; o primeiro `Stop` cujo turno for comprovado publica uma vez e avança SHARED para
+revision 1. Repetir esse prompt ou Stop não duplica evento/revision.
+
+## Erros comuns e diagnóstico
+
+- Dry-run mostra vault já v2: não aplique novamente.
+- `revision: 0` imediatamente após apply válido: estado saudável; aguarde um prompt e Stop
+  elegíveis, não rode repair nem repita a migração.
+- Bundle v2 parcial/corrompido: use status e repair; migração não é ferramenta de corrupção.
+- Primeiro Stop pós-migração fica `ambiguous`: confirme que o `turn_id` pertence ao transcript e
+  que `UserPromptSubmit` abriu/avançou a activation de recuperação.
+- Candidates numerosos: curate gradualmente com `memory promote`/`memory reject`.
+- Warning legado após apply: confirme o vault efetivamente selecionado e o vínculo do projeto.
+
+## Próximos passos
+
+Volte para [memória e curadoria](memory.md) e execute
+[manutenção e diagnóstico](maintenance-and-diagnostics.md).

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

@@ -0,0 +1,99 @@
+# Memória compartilhada e curadoria
+
+**PT-BR** · [English](../../en/commands/memory.md)
+
+## Objetivo
+
+Inspecionar e curar CORE, SHARED, ledger, outbox, attempts e candidates sem confundir autoria
+canônica com estado operacional gerado.
+
+## Quando usar
+
+Use no CI, antes de verify/archive, diante de avisos do doctor ou para decidir candidates.
+
+## Quando não usar
+
+Não edite `SHARED_MEMORY.md` ou `MEMORY_EVENTS.jsonl` à mão. Não use repair em vault legado que
+apenas aguarda migração.
+
+## Pré-requisitos
+
+Informe o vault explicitamente em automações. Preserve backups e evidências antes de reparar.
+
+## Sintaxe
+
+```bash
+npx wendkeep memory status [--gate] --vault <cofre>
+npx wendkeep memory repair --vault <cofre>
+npx wendkeep memory reconcile <sessão-ambígua> --by-session <sessão-sucessora> --reason <motivo> [--apply] --vault <cofre>
+npx wendkeep memory promote <candidate> --vault <cofre>
+npx wendkeep memory reject <candidate> --vault <cofre>
+npx wendkeep validate-memory [caminho-do-CORE]
+npx wendkeep validate-memory --vault <cofre-v2>
+```
+
+## Opções e códigos de saída
+
+- `memory status` é read-only; `--gate` retorna exit `1` apenas para estado bloqueante.
+- O `Stop` grava os eventos na outbox antes de reconhecer `last_memory_attempt: enqueued`; depois o
+  projector roda fora do lock do registry. Retry do mesmo attempt reutiliza os event IDs congelados
+  e pode projetá-los no máximo uma vez.
+- Projector busy/falho persiste `degraded`, preserva a outbox e avisa que há replay. Um Stop/retry
+  seguinte reaproveita essa tentativa; não reconstrói o handoff com dados transitórios novos.
+- O outcome só atualiza `memory_status`/checkpoint se activation, epoch, turno e attempt ainda forem
+  exatamente os mesmos. Resultado stale/superseded não apaga nem sobrescreve checkpoint mais novo.
+- Vault legado válido gera warning e exit `0`. Em v2, o status correlaciona
+  `last_memory_attempt`, disposition, outbox, ledger, SHARED e checkpoint: attempt ambíguo,
+  publicação perdida ou checkpoint divergente bloqueiam; `degraded` com outbox íntegra é warning.
+- `memory repair` é exclusivamente estrutural: trabalha sob locks com owner PID/token, salva
+  `.bak`, retém eventos válidos e reprojeta. Quando reconhece um checkpoint pré-0.59 válido com
+  cursor causal, migra-o por CAS para a fronteira física e registra backup/auditoria; nunca
+  reclassifica attempts do registry nem aceita tuple que não seja rederivada integralmente.
+- `memory reconcile` é dry-run por padrão. `--apply` exige duas sessões nomeadas e motivo, faz CAS
+  do attempt exato, salva backup do registry e limita a mutação ao attempt ambíguo e à sucessora.
+  O replay é CORE-aware, usa cursor físico do ledger no checkpoint e não reescreve ledger, CORE ou
+  notas, nem consome a outbox. Repetir a mesma decisão aplicada é idempotente.
+- Toda rota de memória valida a topologia física de `.brain`, ledger, outbox, CORE, SHARED,
+  candidates, registry, notas, backups, temporários e sidecars antes de ler ou escrever. Junction,
+  symlink, reparse point ou hardlink falham fechados sem tocar bytes externos. Locks publicam owner
+  e lease atomicamente, não colhem PID vivo apenas por idade e só liberam a lease adquirida.
+- `promote`/`reject` acrescentam decisão auditável; nunca reescrevem o ledger no lugar.
+- `validate-memory <CORE.md>` valida cap de 25 linhas, seções e segredos.
+- `validate-memory --vault` exige bundle v2 completo; não é o gate correto para vault legado.
+
+## Exemplos
+
+```bash
+npx wendkeep memory status --gate --vault .MeuApp-vault
+npx wendkeep memory reconcile antiga --by-session atual --reason "entrega continuada" --vault .MeuApp-vault
+npx wendkeep memory reconcile antiga --by-session atual --reason "entrega continuada" --apply --vault .MeuApp-vault
+npx wendkeep validate-memory .MeuApp-vault/.brain/CORE.md
+npx wendkeep memory promote candidate-123 --vault .MeuApp-vault
+```
+
+## Resultado esperado
+
+O status imprime schema, revision, cursor, hash, eventos, outbox, candidates, conflitos e o estado
+causal do último attempt. CORE permanece canônico e curado à mão; SHARED permanece projeção
+operacional verificável. Depois de uma projeção bem-sucedida, o checkpoint do attempt pode ser um
+prefixo válido de uma projeção global que já avançou com eventos concorrentes.
+
+## Erros comuns e diagnóstico
+
+- `legacy`: siga o guia de migração; não é corrupção.
+- `revision: 0` logo após migração válida, sem attempt v2, é saudável; não rode repair só para
+  fabricar o primeiro evento.
+- `degraded` com todos os event IDs presentes no ledger ou na outbox íntegra é recuperável; deixe o
+  replay idempotente concluir. Event ID ausente nos dois lugares indica publicação perdida.
+- Attempt `ambiguous`, attempt `applied` sem event IDs, evento `projected` apenas na outbox ou
+  checkpoint divergente são bloqueantes: preserve os artefatos e investigue antes de repair. Se a
+  ambiguidade for comprovadamente substituída por uma sessão sucessora, revise o dry-run de
+  `memory reconcile` antes de autorizar `--apply`; o comando falha se o attempt ambíguo tiver IDs.
+- Candidate pendente comum: warning recuperável, exige decisão humana quando apropriado.
+- `event_cursor` ausente ou hash divergente em v2: preserve o bundle e avalie `memory repair`.
+- `validate-memory --vault` falha no legado: valide apenas CORE ou migre primeiro.
+
+## Próximos passos
+
+Leia [migração de memória](memory-migration.md), [manutenção](maintenance-and-diagnostics.md) e
+[verify](verify.md).

package/docs/pt-BR/commands/notes-and-knowledge.md

@@ -0,0 +1,69 @@
+# Notas derivadas e grafo de conhecimento
+
+**PT-BR** · [English](../../en/commands/notes-and-knowledge.md)
+
+## Objetivo
+
+Criar, reparar, numerar e navegar decisões, bugs e aprendizados mantendo proveniência e wikilinks.
+
+## Quando usar
+
+Use para registrar conhecimento durável ou reparar notas históricas diagnosticadas pelo doctor.
+
+## Quando não usar
+
+Não edite numeração e wikilinks em massa à mão. Não use `--apply` sem conferir a prévia.
+
+## Pré-requisitos
+
+Vault vinculado, sessão de origem identificável e backup antes de renumerações amplas.
+
+## Sintaxe
+
+```bash
+npx wendkeep dashboard [--force]
+npx wendkeep note new --type bug|learning "<título>"
+npx wendkeep note relink [--apply]
+npx wendkeep note repair-frontmatter [--apply]
+npx wendkeep note repair-sections [--apply]
+npx wendkeep renumber-decisions [--apply]
+npx wendkeep renumber-bugs [--apply]
+npx wendkeep renumber-learnings [--apply]
+npx wendkeep lesson add "<título>" "<lição>"
+```
+
+## Opções e códigos de saída
+
+- `note new` cria `BUG-NNNN` ou `APR-NNNN` no mês e aceita `--date`.
+- `note relink`, `repair-frontmatter`, `repair-sections` e `renumber-*` são dry-run por padrão;
+  `--apply` grava e `--json` facilita auditoria.
+- `dashboard --force` regenera Bases/MOC quando necessário.
+- `lesson add` aceita `--change <slug>` e `--vault` para ligar aprendizado local.
+- Exit `0` indica prévia/aplicação consistente; não zero deixa o reparo incompleto explícito.
+
+## Exemplos
+
+```bash
+npx wendkeep note new --type bug "refresh expira durante upload"
+npx wendkeep note relink --json
+npx wendkeep renumber-decisions --json
+# revise antes de repetir com --apply
+npx wendkeep dashboard --force
+```
+
+## Resultado esperado
+
+Notas derivadas vivem na pasta do mês, têm numeração global do tipo e backlink para a sessão. Os
+reparos preservam frontmatter válido e reescrevem wikilinks quando arquivos mudam.
+
+## Erros comuns e diagnóstico
+
+- Nota órfã sem fonte modal: `note relink` informa que não consegue inferir e não inventa vínculo.
+- Frontmatter empilhado: use repair sob o mesmo lock dos hooks.
+- Links cinza após renumber/archive: rode prévia de relink e confirme ambiguidades.
+- Título sensível: remova secrets/PII antes de persistir.
+
+## Próximos passos
+
+Veja [sessões e importação](sessions-and-import.md),
+[custos e observabilidade](costs-and-observability.md) e [manutenção](maintenance-and-diagnostics.md).

package/docs/pt-BR/commands/operating-profiles.md

@@ -0,0 +1,171 @@
+# Perfis de Operação e FLOW
+
+**PT-BR** · [English](../../en/commands/operating-profiles.md)
+
+## Objetivo
+
+Escolher quanta governança do Wend Runtime uma execução precisa sem desligar o **Keep Core**.
+O Keep Core permanece sempre ativo: Vault, sessão, identidade, CORE/SHARED, lessons, custos e
+integrações de persistência continuam funcionando em todos os perfis.
+
+## Quando usar
+
+Use `profile` para consultar ou selecionar explicitamente um Perfil de Operação. Use `FLOW` para
+manutenção local, reversível e com `spec_impact:none` que caiba num microcontrato Executar →
+Validar, sem change.
+
+## Quando não usar
+
+Não selecione `OFF` para tentar contornar uma política: ele entrega a execução ao harness nativo
+da LLM e só pode ser escolhido explicitamente. Não finalize em FLOW alterações de contrato
+público, segurança/auth, migração/schema, dependências, CI/release, specs ou dos próprios
+gates/policies do WendKeep; promova o trabalho para uma change.
+
+## Pré-requisitos
+
+- Projeto inicializado, com `.wendkeep.json` vinculado ao Vault correto.
+- Para override de sessão, uma sessão inequívoca no `SESSION_REGISTRY.json`.
+- Para FLOW, repositório Git, allowlist de paths, motivo e ao menos um sensor existente em
+  `wendkeep.sensors.json`.
+
+## Sintaxe
+
+```bash
+npx wendkeep profile status [--project <path>] [--vault <path>] [--session <id>] [--json]
+npx wendkeep profile use <perfil> [--project <path>] [--vault <path>] [--session <id>] [--json]
+npx wendkeep flow start <slug> --allow <path> [--allow <path>...] --sensor <id> [--sensor <id>...] --reason <texto> [--session <id>]
+npx wendkeep flow status [<id>]
+npx wendkeep flow show <id> [--session <id>]
+npx wendkeep flow finish <id> [--session <id>]
+npx wendkeep flow promote <id> [--change-slug <slug>] [--session <id>]
+```
+
+Todos os subcomandos FLOW também aceitam `--project <path>`, `--vault <path>` e `--json`.
+Quando informado, `--session` restringe inclusive consultas e mutações por ID à sessão dona do
+FLOW; um ID de outra sessão falha sem mutação.
+
+## Opções e códigos de saída
+
+| Perfil | Rota | Contrato |
+|---|---|---|
+| `OFF` | harness nativo da LLM | Wend Runtime desligado; Keep Core integral. |
+| `FLOW` | E → V | Microcontrato com baseline Git, allowlist, sensores e recibo, sem change. |
+| `GUIDE` | P → E → V | Change compacta; política reconhecida para evolução compatível. |
+| `GOVERN` | P → R → E → V | Loop a2 atual e fallback conservador. |
+| `ASSURE` | P → R → E → V → C | Governança acrescida de confirmação e handoff. |
+
+- A resolução segue override explícito da sessão → `harness.profile` do projeto → `GOVERN`.
+  Heurística, tamanho do diff, texto do prompt, variável de ambiente ou erro de leitura nunca
+  selecionam `OFF`.
+- `profile status` mostra perfil efetivo e origem; `--json` produz saída estruturada. Quando um
+  Vault explícito preserva a escolha apesar de binding corrompido, a saída inclui `binding_error`
+  e o diagnóstico também vai para stderr.
+- `profile use` valida nome e flags estritamente; opção singleton duplicada, incompleta ou com
+  valor iniciado por `--` falha antes de I/O. Sem `--session`, altera atomicamente o binding do
+  projeto; com `--session`, grava override, origem e timestamp sem trocar a identidade da sessão.
+- `.wendkeep.json` continua em `schemaVersion: 1`; o campo aditivo usa, por exemplo,
+  `"harness": { "profile": "GOVERN" }`. Binding legado sem o campo também resolve `GOVERN`.
+- Binding corrompido nunca equivale a `OFF`. Quando o payload ou a integração legada identifica
+  um Vault inequívoco, o Keep Core continua ativo sob `GOVERN` e o hook expõe um diagnóstico;
+  guards de mutação falham fechados até o binding ser reparado. Configuração local inválida,
+  marcador ausente ou identidade divergente nunca herdam silenciosamente o Vault pai/global.
+- `harness.flow.protectedRoots` aceita um array de raízes relativas ao projeto, sem globs ou
+  escapes `..`. Cada raiz amplia as superfícies protegidas do FLOW; qualquer alteração sob ela
+  exige `flow promote`.
+
+```json
+{
+  "harness": {
+    "profile": "FLOW",
+    "flow": {
+      "protectedRoots": ["src/internal-api", "infra/releases"]
+    }
+  }
+}
+```
+
+- `flow start` captura HEAD, estado Git preexistente, allowlist, sensores, motivo e sessão em
+  `.brain/runtime/flows/`; não cria `08-Mudanças`, ADR, verdict, spec ou `CURRENT_CHANGE.md`.
+- `flow finish` compara o diff real ao baseline Git e à allowlist, incluindo troca de commit em
+  submodule, metadata/config/flags ocultas do Git e superfícies protegidas ignoradas. O projectRoot
+  fica congelado e sensores rodam nesse cwd. Uma descoberta física limitada e no-follow mantém
+  visíveis aliases protegidos vazios ou ignorados, sem entrar em `.git`, no Vault efetivo ou em
+  caches locais; ambiguidade ou estouro de limite bloqueia. Ele rejeita
+  symlink/junction/reparse/hardlink no worktree e nos destinos do Vault, revalida antes/depois dos
+  sensores e recaptura o snapshot imediatamente antes do recibo, bloqueando qualquer sensor que
+  modifique o repositório. Recibo terminal e iteração
+  idempotente na sessão só contam como sucesso juntos;
+  uma projeção temporariamente ocupada retorna exit `1` e pode ser repetida com segurança.
+- `flow promote` cria uma change normal preservando sessão, motivo, paths, sensores e evidência.
+  Lock cross-process owner+lease por slug, reserva e estado durável `promoting` elegem um único
+  dono; contrato, reserva, attempts, recibo e origem permanecem semanticamente vinculados. O
+  perdedor permanece ativo e pode repetir com `--change-slug`. Retries retomam idempotentemente a
+  mesma promoção em vez de criar outra change. Não existe `--force` no FLOW.
+- Exit `0` indica consulta ou transição concluída; exit `1` indica política/sensor vermelho; exit
+  `2` indica perfil, sessão, flow ou argumentos inválidos, sem mutação parcial.
+
+## Exemplos
+
+Consultar o padrão efetivo e aplicar override somente à sessão atual:
+
+```bash
+npx wendkeep profile status
+npx wendkeep profile use OFF --session 019abc-session-id --json
+```
+
+Executar uma manutenção FLOW capturando o `flow_id` retornado por `start`:
+
+```powershell
+$flow = npx wendkeep flow start corrige-copy --allow README.md --sensor docs-bilingual --reason "Corrige texto sem alterar contrato" --json | ConvertFrom-Json
+$flowId = $flow.contract.flow_id
+npx wendkeep flow status $flowId
+```
+
+Se o trabalho permanecer local e dentro do microcontrato, finalize com o ID retornado:
+
+```powershell
+npx wendkeep flow finish $flowId
+```
+
+Se o escopo crescer antes do `finish`, promova em vez de finalizar:
+
+```powershell
+npx wendkeep flow promote $flowId
+```
+
+Se outra sessão já reivindicou o slug original, o FLOW continua ativo e pode ser promovido
+novamente com um destino explícito:
+
+```powershell
+npx wendkeep flow promote $flowId --change-slug outro-slug
+```
+
+## Resultado esperado
+
+Trocar o perfil não cria outra sessão nem interrompe o Vault. Em `OFF`, a memória e as lessons
+continuam injetadas e o Stop continua persistindo sessão/memória, mas router, skill gate,
+change context/warn/nag/guard e captura de plano ficam inativos. Um FLOW concluído deixa recibo
+durável e consultável; um FLOW promovido passa a seguir o lifecycle normal de change.
+
+## Erros comuns e diagnóstico
+
+- Perfil desconhecido: use exatamente `OFF`, `FLOW`, `GUIDE`, `GOVERN` ou `ASSURE`.
+- `OFF` apareceu sem escolha explícita: trate como erro; leitura ausente/inválida deve cair em
+  `GOVERN`.
+- Sessão ausente ou ambígua: confira `session list` e informe `--session <id>` sem tentar de novo
+  com um alvo diferente.
+- FLOW sem allowlist, motivo ou sensor: complete o microcontrato antes de editar.
+- Path fora do escopo, superfície protegida ou sensor vermelho: corrija/abandone o FLOW ou use
+  `flow promote`; não há bypass.
+- Sensor que alterou o repositório, allowlist atravessando symlink/junction ou superfície sensível
+  ignorada: restaure o estado e promova quando a mudança não for estritamente local. Sensores FLOW
+  devem ser somente leitura.
+- Projeção da sessão `missing`, `invalid-frontmatter` ou `busy`: restaure/desbloqueie a nota e
+  repita `flow finish` ou `flow promote`; o marcador idempotente impede duplicação.
+- Sujeira anterior apareceu no diff: ela deve coincidir com o fingerprint inicial e nunca pode ser
+  atribuída silenciosamente ao FLOW.
+
+## Próximos passos
+
+Leia [changes e verificação](changes-and-verification.md), o guia profundo de
+[verify](verify.md) e [sessões e importação](sessions-and-import.md).

package/docs/pt-BR/commands/retroactive-import.md

@@ -0,0 +1,67 @@
+# Importação retroativa segura
+
+**PT-BR** · [English](../../en/commands/retroactive-import.md)
+
+## Objetivo
+
+Importar sessões históricas de Claude e Codex com escopo controlado, identidade estável e revisão
+antes da escrita.
+
+## Quando usar
+
+Use ao instalar o WendKeep num projeto existente, recuperar uma faixa de datas ou reprocessar
+decisões sem importar o mundo inteiro.
+
+## Quando não usar
+
+Não use `--source all` sem dry-run em máquinas com muitos projetos, forks ou rollouts de subagents.
+Não trate transcript importado como evidência de implementação atual.
+
+## Pré-requisitos
+
+Confirme projeto, vault, provider, diretório fonte e janela temporal. Faça backup se o registry já
+contiver reparos manuais.
+
+## Sintaxe
+
+```bash
+npx wendkeep import --dry-run --json
+npx wendkeep import --source claude|codex|all [--since <data>] [--limit <n>]
+npx wendkeep import --from <claude-dir> --codex-from <codex-dir>
+npx wendkeep import --stamp-ids | --rescan-decisions
+```
+
+## Opções e códigos de saída
+
+- `--source` limita provider; `--since` e `--limit` limitam volume.
+- `--from`/`--codex-from` substituem diretórios descobertos.
+- `--dry-run` não grava e `--json` produz relatório auditável.
+- `--stamp-ids` preenche IDs em notas existentes; `--rescan-decisions` reaplica extração de prosa.
+- Exit `0` indica varredura/importação consistente; exit diferente de zero exige resolver fonte,
+  parsing ou identidade antes de repetir.
+
+## Exemplos
+
+```bash
+npx wendkeep import --source codex --since 2026-07-20 --limit 20 --dry-run --json
+# confira accepted/skipped/forks
+npx wendkeep import --source codex --since 2026-07-20 --limit 20
+```
+
+## Resultado esperado
+
+Sessões aceitas entram uma vez por `session_id`, com provider e transcript corretos. Duplicatas
+canônicas são ignoradas; forks/subagents preservam relação de origem em vez de copiar toda a
+história herdada como uma nova conversa independente.
+
+## Erros comuns e diagnóstico
+
+- Contaminação entre projetos: pare e confira cwd, binding e filtros antes de limpar qualquer nota.
+- Fork comum importado como sessão cheia: inspecione `forked_from_id` e payload de origem.
+- Nota sem `session_id`: use `--stamp-ids` somente após dry-run.
+- Decisões faltantes em nota já importada: prefira `--rescan-decisions` a duplicar a sessão.
+
+## Próximos passos
+
+Volte para [sessões e hooks](sessions-and-import.md), gere [custos](costs-and-observability.md) e
+revise [notas derivadas](notes-and-knowledge.md).

package/docs/pt-BR/commands/sessions-and-import.md

@@ -0,0 +1,89 @@
+# Sessões, hooks e importação
+
+**PT-BR** · [English](../../en/commands/sessions-and-import.md)
+
+## Objetivo
+
+Entender como os hooks capturam sessões ao vivo, como activation/turno preservam causalidade no
+registry e quando usar a importação retroativa. No perfil `OFF`, o Vault continua ativo: hooks de
+sessão, identidade, memória, custos e persistência pertencem ao Keep Core, não ao Wend Runtime.
+
+## Quando usar
+
+Use `session` para inspecionar/focar uma conversa e `import` para recuperar sessões anteriores à
+instalação ou fora do registry atual.
+
+## Quando não usar
+
+Não invoque hooks manualmente sem o envelope JSON esperado. Não use import amplo antes de uma
+prévia quando existirem forks/subagents possivelmente duplicados.
+
+## Pré-requisitos
+
+Hooks instalados para captura ao vivo; para import, acesso local aos diretórios de transcripts do
+Claude/Codex e um vault vinculado ao projeto correto.
+
+## Sintaxe
+
+```bash
+npx wendkeep hook <nome>
+npx wendkeep session list
+npx wendkeep session show <id>
+npx wendkeep session use <id>
+npx wendkeep import [opções]
+```
+
+## Opções e códigos de saída
+
+- `wendkeep hook <name>` lê o payload do agente em stdin; nomes válidos aparecem em `--help`.
+- `SessionStart` abre uma activation, isto é, um epoch que continua ativo por vários `Stop`; só um
+  novo `SessionStart` torna o epoch anterior superseded.
+- `UserPromptSubmit` avança o turno nativo da activation ativa. Se encontrar um registry legado
+  com o epoch fechado, abre exatamente uma activation de recuperação; repetir o mesmo prompt não
+  abre outra.
+- No Codex, `session_id`, o `turn_id` nativo e a ordem observada no transcript bastam para resolver
+  o turno. O payload do hook não precisa inventar `activation_id` nem `turn_sequence`.
+- `Stop` aceita somente o turno comprovado pelo transcript e pela activation ativa compatível.
+  Duplicatas são no-op; Stops stale/superseded não publicam memória nem sobrescrevem o checkpoint
+  de um epoch mais novo.
+- Ao compactar conversas em `## Iterações`, o hook escapa delimitadores de código cortados pelo
+  limite de tamanho; backticks inline ou fences nunca ficam abertos para engolir a linha seguinte.
+- `session list` lê `SESSION_REGISTRY`; `show` exibe uma sessão e `use` muda apenas o foco humano
+  em `CURRENT_SESSION.md`.
+- `import --source all|claude|codex`, `--since`, `--limit`, `--from` e `--codex-from` limitam escopo.
+- `--dry-run`/`--json` permitem auditar antes de gravar; `--stamp-ids` e `--rescan-decisions`
+  corrigem históricos específicos.
+- Exit `0` indica processamento consistente; exit não zero indica configuração, fonte ou escrita
+  inválida sem transformar isso em sucesso parcial silencioso.
+
+## Exemplos
+
+```bash
+npx wendkeep session list
+npx wendkeep session show 019abc-session-id
+npx wendkeep import --source codex --since 2026-07-01 --dry-run --json
+```
+
+## Resultado esperado
+
+Cada sessão canônica aponta para provider, transcript, arquivo de nota e custos correspondentes.
+O registry mantém um epoch de `SessionStart` por activation e o turno nativo mais recente; vários
+`Stop` podem confirmar turnos do mesmo epoch sem fechá-lo. Importações repetidas do mesmo
+`session_id` são deduplicadas; o foco humano não encerra nem altera a identidade dos hooks. Cada
+iteração automática permanece Markdown válido mesmo quando uma fala precisa ser truncada.
+
+## Erros comuns e diagnóstico
+
+- Sessão ausente: confira provider, path do transcript e registry antes de importar novamente.
+- `Stop ambiguous`: o `turn_id` não foi comprovado pelo transcript ou nenhuma activation ativa
+  compatível foi encontrada; o attempt fica observável, mas não publica memória.
+- Stop atrasado aparece como `stale_turn`/`superseded`: o epoch mais novo e seu checkpoint são
+  preservados; não force a reaplicação do payload antigo.
+- Duplicatas de forks: limite por fonte/data e revise `forked_from_id`/`source.subagent`.
+- Codex não captura: aprove os hooks e reinicie a sessão após `sync`.
+- Custo contaminado: valide `session_id → session_file → transcript_path → provider`.
+
+## Próximos passos
+
+Leia [Perfis de Operação](operating-profiles.md), [importação retroativa](retroactive-import.md),
+[custos e observabilidade](costs-and-observability.md) e [notas](notes-and-knowledge.md).