wendkeep 0.58.1 → 0.59.0

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

@@ -0,0 +1,173 @@
+# Operating profiles and FLOW
+
+**English** · [Português](../../pt-BR/commands/operating-profiles.md)
+
+## Purpose
+
+Choose how much Wend Runtime governance an execution needs without disabling **Keep Core**.
+Keep Core is always active: the Vault, session, identity, CORE/SHARED, lessons, costs, and
+persistence integrations continue working under every profile.
+
+## When to use
+
+Use `profile` to inspect or explicitly select an Operating Profile. Use `FLOW` for local,
+reversible `spec_impact:none` maintenance that fits an Execute → Validate microcontract without a
+change.
+
+## When not to use
+
+Do not select `OFF` to bypass policy: it hands execution to the LLM's native harness and can only
+be selected explicitly. Do not finish public-contract, security/auth, migration/schema,
+dependency, CI/release, spec, or WendKeep gate/policy changes in FLOW; promote the work to a
+change.
+
+## Prerequisites
+
+- An initialized project whose `.wendkeep.json` is bound to the correct Vault.
+- For a session override, one unambiguous session in `SESSION_REGISTRY.json`.
+- For FLOW, a Git repository, a path allowlist, a reason, and at least one existing sensor in
+  `wendkeep.sensors.json`.
+
+## Syntax
+
+```bash
+npx wendkeep profile status [--project <path>] [--vault <path>] [--session <id>] [--json]
+npx wendkeep profile use <profile> [--project <path>] [--vault <path>] [--session <id>] [--json]
+npx wendkeep flow start <slug> --allow <path> [--allow <path>...] --sensor <id> [--sensor <id>...] --reason <text> [--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>]
+```
+
+Every FLOW subcommand also accepts `--project <path>`, `--vault <path>`, and `--json`. When
+provided, `--session` scopes ID-based reads and mutations to the session that owns the FLOW; an
+ID from another session fails without mutation.
+
+## Options and exit codes
+
+| Profile | Route | Contract |
+|---|---|---|
+| `OFF` | LLM-native harness | Wend Runtime off; Keep Core intact. |
+| `FLOW` | E → V | Microcontract with Git baseline, allowlist, sensors, and receipt, without a change. |
+| `GUIDE` | P → E → V | Compact change; policy recognized for compatible evolution. |
+| `GOVERN` | P → R → E → V | Current a2 loop and conservative fallback. |
+| `ASSURE` | P → R → E → V → C | Governance plus confirmation and handoff. |
+
+- Resolution is explicit session override → project `harness.profile` → `GOVERN`. Heuristics,
+  diff size, prompt text, environment variables, or read failures never select `OFF`.
+- `profile status` prints the effective profile and source; `--json` emits structured output. When
+  an explicit Vault preserves the selection despite a corrupt binding, output includes
+  `binding_error` and the diagnostic is also written to stderr.
+- `profile use` validates names and flags strictly; a duplicate/incomplete singleton option or a
+  value beginning with `--` fails before I/O. Without `--session`, it atomically changes the
+  project binding; with `--session`, it records override, source, and timestamp without changing
+  session identity.
+- `.wendkeep.json` stays on `schemaVersion: 1`; the additive field is, for example,
+  `"harness": { "profile": "GOVERN" }`. A legacy binding without it also resolves to `GOVERN`.
+- 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
+  missing marker, or a mismatched identity never silently inherits a parent/global Vault.
+- `harness.flow.protectedRoots` accepts an array of project-relative roots, without globs or `..`
+  escapes. Each root extends FLOW's protected surfaces; any change below it requires
+  `flow promote`.
+
+```json
+{
+  "harness": {
+    "profile": "FLOW",
+    "flow": {
+      "protectedRoots": ["src/internal-api", "infra/releases"]
+    }
+  }
+}
+```
+
+- `flow start` captures HEAD, pre-existing Git state, allowlist, sensors, reason, and session under
+  `.brain/runtime/flows/`; it creates no `08-Mudanças`, ADR, verdict, spec, or
+  `CURRENT_CHANGE.md`.
+- `flow finish` compares the real diff with the Git baseline and allowlist, including submodule
+  changes, Git metadata/config/hidden flags, and ignored protected surfaces. The projectRoot is
+  frozen and sensors run in that cwd. A bounded, no-follow physical discovery keeps empty or
+  ignored protected aliases visible without entering `.git`, the effective Vault, or local caches;
+  ambiguity or a limit breach blocks. It rejects symlink/junction/reparse/hardlink paths in both
+  the worktree and Vault destinations, revalidates before/after sensors, and recaptures the snapshot
+  immediately before the receipt, blocking any sensor that mutates the repository. A terminal
+  receipt and idempotent
+  session iteration count as success only together; a temporarily
+  busy projection exits `1` and can be retried safely.
+- `flow promote` creates a normal change while preserving session, reason, paths, sensors, and
+  evidence. A cross-process owner+lease slug lock, reservation, and durable `promoting` state elect
+  one owner; contract, reservation, attempts, receipt, and origin remain semantically bound. The
+  loser remains active and can retry with `--change-slug`. Retries idempotently resume the same
+  promotion instead of creating another change.
+  No FLOW command accepts `--force`.
+- Exit `0` means a successful query or transition; exit `1` means a policy/red-sensor block; exit
+  `2` means invalid profile, session, flow, or arguments, with no partial mutation.
+
+## Examples
+
+Inspect the effective default and apply an override only to the current session:
+
+```bash
+npx wendkeep profile status
+npx wendkeep profile use OFF --session 019abc-session-id --json
+```
+
+Run FLOW maintenance while capturing the `flow_id` returned by `start`:
+
+```powershell
+$flow = npx wendkeep flow start fix-copy --allow README.md --sensor docs-bilingual --reason "Fix copy without changing the contract" --json | ConvertFrom-Json
+$flowId = $flow.contract.flow_id
+npx wendkeep flow status $flowId
+```
+
+If the work remains local and inside the microcontract, finish it with the returned ID:
+
+```powershell
+npx wendkeep flow finish $flowId
+```
+
+If the scope grows before `finish`, promote instead of finishing:
+
+```powershell
+npx wendkeep flow promote $flowId
+```
+
+If another session already claimed the original slug, the FLOW stays active and can be promoted
+again with an explicit destination:
+
+```powershell
+npx wendkeep flow promote $flowId --change-slug another-slug
+```
+
+## Expected result
+
+Changing profile neither creates a new session nor interrupts the Vault. In `OFF`, memory and
+lessons are still injected and Stop still persists the session/memory lifecycle, while the
+router, skill gate, change context/warn/nag/guard, and plan capture are inactive. A completed FLOW
+leaves a durable, inspectable receipt; a promoted FLOW enters the normal change lifecycle.
+
+## Common errors and diagnosis
+
+- Unknown profile: use exactly `OFF`, `FLOW`, `GUIDE`, `GOVERN`, or `ASSURE`.
+- `OFF` appeared without explicit selection: treat it as an error; missing/invalid reads must fall
+  back to `GOVERN`.
+- Missing or ambiguous session: inspect `session list` and pass `--session <id>` without retrying
+  against a different target.
+- FLOW without allowlist, reason, or sensor: complete the microcontract before editing.
+- Out-of-scope path, protected surface, or red sensor: fix/abandon the FLOW or use
+  `flow promote`; there is no bypass.
+- A sensor changed the repository, the allowlist crosses a symlink/junction, or a sensitive
+  ignored surface changed: restore the state and promote when the change is not strictly local.
+  FLOW sensors must be read-only.
+- Session projection is `missing`, `invalid-frontmatter`, or `busy`: restore/unlock the note and
+  retry `flow finish` or `flow promote`; the idempotent marker prevents duplication.
+- Pre-existing dirt appeared in the diff: it must match the initial fingerprint and must never be
+  silently attributed to the FLOW.
+
+## Next steps
+
+Read [changes and verification](changes-and-verification.md), the deep
+[verify guide](verify.md), and [sessions and import](sessions-and-import.md).

package/docs/en/commands/retroactive-import.md

@@ -0,0 +1,67 @@
+# Safe retroactive import
+
+**English** · [Português](../../pt-BR/commands/retroactive-import.md)
+
+## Purpose
+
+Import historical Claude and Codex sessions with bounded scope, stable identity, and review before
+writes.
+
+## When to use
+
+Use when installing WendKeep in an existing project, recovering a date range, or rescanning
+decisions without importing every transcript on the machine.
+
+## When not to use
+
+Do not use `--source all` without dry-run on machines with many projects, forks, or subagent
+rollouts. Do not treat imported conversation history as current implementation evidence.
+
+## Prerequisites
+
+Confirm project, vault, provider, source directory, and date window. Back up the registry if it
+already contains manual repairs.
+
+## Syntax
+
+```bash
+npx wendkeep import --dry-run --json
+npx wendkeep import --source claude|codex|all [--since <date>] [--limit <n>]
+npx wendkeep import --from <claude-dir> --codex-from <codex-dir>
+npx wendkeep import --stamp-ids | --rescan-decisions
+```
+
+## Options and exit codes
+
+- `--source` bounds provider; `--since` and `--limit` bound volume.
+- `--from`/`--codex-from` override discovered directories.
+- `--dry-run` performs zero writes; `--json` emits an auditable report.
+- `--stamp-ids` fills IDs in existing notes; `--rescan-decisions` reruns prose extraction.
+- Exit `0` means a consistent scan/import; non-zero requires fixing source, parsing, or identity
+  before retrying.
+
+## Examples
+
+```bash
+npx wendkeep import --source codex --since 2026-07-20 --limit 20 --dry-run --json
+# inspect accepted/skipped/forks
+npx wendkeep import --source codex --since 2026-07-20 --limit 20
+```
+
+## Expected result
+
+Accepted sessions enter once per `session_id` with matching provider/transcript. Canonical
+duplicates are skipped; forks/subagents retain origin relationships instead of copying inherited
+history into another full independent conversation.
+
+## Common errors and diagnosis
+
+- Cross-project contamination: stop and verify cwd, binding, and filters before cleaning notes.
+- Ordinary fork imported as full session: inspect `forked_from_id` and source payload.
+- Note without `session_id`: use `--stamp-ids` only after dry-run.
+- Missing decisions in an imported note: prefer `--rescan-decisions` over duplicating the session.
+
+## Next steps
+
+Return to [sessions and hooks](sessions-and-import.md), generate [costs](costs-and-observability.md),
+and review [derived notes](notes-and-knowledge.md).

package/docs/en/commands/sessions-and-import.md

@@ -0,0 +1,89 @@
+# Sessions, hooks, and import
+
+**English** · [Português](../../pt-BR/commands/sessions-and-import.md)
+
+## Purpose
+
+Understand how hooks capture live sessions, how activation/turn state preserves causality in the
+registry, and when to use retroactive import. Under `OFF`, the Vault remains active: session,
+identity, memory, cost, and persistence hooks belong to Keep Core, not Wend Runtime.
+
+## When to use
+
+Use `session` to inspect/focus a conversation and `import` to recover sessions from before setup or
+outside the current registry.
+
+## When not to use
+
+Do not invoke hooks manually without their expected JSON envelope. Do not run broad imports before
+a preview when forks/subagents may duplicate history.
+
+## Prerequisites
+
+Installed hooks for live capture; for imports, local access to Claude/Codex transcript directories
+and a vault bound to the correct project.
+
+## Syntax
+
+```bash
+npx wendkeep hook <name>
+npx wendkeep session list
+npx wendkeep session show <id>
+npx wendkeep session use <id>
+npx wendkeep import [options]
+```
+
+## Options and exit codes
+
+- `wendkeep hook <name>` reads the agent payload from stdin; valid names are listed by `--help`.
+- `SessionStart` opens an activation: an epoch that remains active across multiple `Stop` events;
+  only a new `SessionStart` supersedes the previous epoch.
+- `UserPromptSubmit` advances the active activation's native turn. If it finds a legacy registry
+  with a closed epoch, it opens exactly one recovery activation; replaying the same prompt does
+  not open another one.
+- On Codex, `session_id`, the native `turn_id`, and observed transcript order are enough to resolve
+  the turn. Hook payloads do not need invented `activation_id` or `turn_sequence` fields.
+- `Stop` accepts only a transcript-proven turn from the compatible active activation. Duplicates
+  are no-ops; stale/superseded Stops neither publish memory nor overwrite a newer epoch's
+  checkpoint.
+- When compacting conversations into `## Iterações`, the hook escapes code delimiters cut by the
+  size limit; inline backticks and fences never remain open and consume the following line.
+- `session list` reads `SESSION_REGISTRY`; `show` displays one session and `use` only changes human
+  focus in `CURRENT_SESSION.md`.
+- `import --source all|claude|codex`, `--since`, `--limit`, `--from`, and `--codex-from` bound scope.
+- `--dry-run`/`--json` support audit before writes; `--stamp-ids` and `--rescan-decisions` address
+  specific historical gaps.
+- Exit `0` means consistent processing; non-zero reports invalid source/config/write instead of
+  presenting silent partial success.
+
+## Examples
+
+```bash
+npx wendkeep session list
+npx wendkeep session show 019abc-session-id
+npx wendkeep import --source codex --since 2026-07-01 --dry-run --json
+```
+
+## Expected result
+
+Each canonical session points to the matching provider, transcript, note file, and costs. The
+registry keeps one `SessionStart` epoch per activation plus the latest native turn; multiple
+`Stop` events may acknowledge turns in that epoch without closing it. Repeated imports of the
+same `session_id` deduplicate; human focus does not close or re-identify live hooks. Every
+automatic iteration remains valid Markdown even when a message must be truncated.
+
+## Common errors and diagnosis
+
+- Missing session: verify provider, transcript path, and registry before importing again.
+- `Stop ambiguous`: the transcript did not prove the `turn_id`, or no compatible active activation
+  was found; the attempt remains observable but does not publish memory.
+- A late Stop reports `stale_turn`/`superseded`: the newer epoch and checkpoint are preserved; do
+  not force the old payload to apply.
+- Fork duplicates: bound source/date and inspect `forked_from_id`/`source.subagent`.
+- Codex does not capture: approve hooks and start a new session after `sync`.
+- Contaminated cost: validate `session_id → session_file → transcript_path → provider`.
+
+## Next steps
+
+Read [Operating profiles](operating-profiles.md), [retroactive import](retroactive-import.md),
+[costs and observability](costs-and-observability.md), and [notes](notes-and-knowledge.md).

package/docs/en/commands/verify.md

@@ -0,0 +1,92 @@
+# Verify and independent verification
+
+**English** · [Português](../../pt-BR/commands/verify.md)
+
+## Purpose
+
+Run the sensors required by a change's tasks, persist fresh evidence, and assemble the
+self-contained package consumed by the independent `wk-verify` pass.
+
+## When to use
+
+Run after implementing tasks and again whenever tasks, specs, or tests change.
+
+## When not to use
+
+Do not use it as a post-install health check or when no change exists. Run `wendkeep doctor` and
+`wendkeep memory status --gate` instead. In `FLOW`, validation and the receipt belong to
+`flow finish`; under `OFF`, `verify` remains available only when the user chooses to run the
+lifecycle manually.
+
+## Prerequisites
+
+- An open change selected through `CURRENT_CHANGE.md` or `--change <slug>`.
+- A placeholder-free `tarefas.md` with `[req:]` and one or more `[sensor:]` tags on checkbox lines;
+  every distinct sensor ID is required once, in declaration order.
+- Sensors declared in `wendkeep.sensors.json`.
+
+## Syntax
+
+```bash
+npx wendkeep verify [--change <slug>] [--project <root>] [--vault <vault>]
+npx wendkeep verify --deep [--change <slug>]
+npx wendkeep change use <slug>
+```
+
+## Options and exit codes
+
+- `--change <slug>` targets a change without changing the active pointer.
+- `change use <slug>` persists focus for following commands.
+- `--project <root>` selects the sensor cwd; `--vault` selects where proof is stored and is passed
+  to sensors as `OBSIDIAN_VAULT_PATH`, including `memory-health`.
+- **Exit 0:** all required sensors passed and evidence was written.
+- **Exit 1:** the gate ran, but at least one critical sensor was red or a mutant survived.
+- **Exit 2:** invalid usage/context, including `no change (--change or active)`, missing vault,
+  unknown change, or invalid `wendkeep.sensors.json`.
+
+`verify --deep` writes `verificacao.json`; it does not replace the reviewer. The `wk-verify` skill
+must be run by a different author and writes `verdict.json`.
+
+## Examples
+
+Active change:
+
+```bash
+npx wendkeep verify
+npx wendkeep verify --deep
+```
+
+Explicit change:
+
+```bash
+npx wendkeep verify --change tenant-login
+npx wendkeep verify --deep --change tenant-login
+```
+
+Project with no open change:
+
+```bash
+npx wendkeep doctor --vault .MyApp-vault
+npx wendkeep memory status --gate --vault .MyApp-vault
+```
+
+## Expected result
+
+`evidencia.json` contains sensor results and a seal binds proof to the current `tarefas.md` hash.
+Deep mode packages requirements, tasks, and evidence for read-only review; the verdict covers every
+`[req:]` before archive.
+
+## Common errors and diagnosis
+
+- `no change`: this is exit 2 and a valid idle state; create/use a change or skip verify.
+- Zero/missing sensors: inspect every same-line tag and `sensors list`; multiple tags on one task
+  are valid and all of them enter the gate.
+- Red gate: fix the cause and rerun; never choose `archive --force` on your own.
+- Missing/stale verdict: regenerate `--deep` and request a fresh independent pass.
+- Surviving mutants: strengthen the discriminating test; after three rounds, review manually.
+
+## Next steps
+
+Return to the [change lifecycle](changes-and-verification.md) for archive, review
+[Operating profiles](operating-profiles.md), or use [maintenance](maintenance-and-diagnostics.md)
+when no change exists.

package/docs/pt-BR/commands/changes-and-verification.md

@@ -0,0 +1,85 @@
+# Changes, specs, sensores e archive
+
+**PT-BR** · [English](../../en/commands/changes-and-verification.md)
+
+## Objetivo
+
+Conduzir uma mudança desde a intenção registrada até uma decisão arquivada, ligando requisitos,
+tarefas, sensores, evidência e verdict no grafo do cofre.
+
+## Quando usar
+
+Use para qualquer implementação não trivial ou correção que precise deixar prova auditável.
+
+## Quando não usar
+
+Não crie uma change para consultar saúde, importar sessões ou executar manutenção read-only.
+Para manutenção local elegível ao perfil `FLOW`, use o microcontrato descrito em
+[Perfis de Operação](operating-profiles.md); em `OFF`, o lifecycle permanece disponível, mas não
+é imposto pelo Wend Runtime.
+
+## Pré-requisitos
+
+Tenha o projeto inicializado, um vault saudável e `wendkeep.sensors.json` válido na raiz.
+
+## Sintaxe
+
+```bash
+npx wendkeep change new <slug>
+npx wendkeep change status [slug]
+npx wendkeep spec effective --change <slug>
+npx wendkeep sensors list
+npx wendkeep verify [--deep] [--change <slug>]
+npx wendkeep change archive <slug>
+```
+
+## Opções e códigos de saída
+
+- `wendkeep change new <slug> [--simple]` cria uma change; `--simple` só pula o design, não é nem
+  equivale a `FLOW` e preserva o lifecycle/ADR legado.
+- `change use`, `list`, `show`, `status`, `diff`, `done` e `undone` inspecionam ou atualizam o
+  trabalho sem arquivar.
+- `change continue <arquivada> <nova>` abre continuação sem herdar evidência antiga.
+- `change bind <slug> --session <id>` liga uma sessão existente.
+- `change relink [--apply]` e `change backlink [--apply]` reparam o grafo; dry-run é o padrão.
+- `change abandon <slug>` descarta sem ADR; `archive --force` exige decisão humana explícita.
+- `wendkeep spec list|show|effective|migrate|rebase` administra contratos vivos e deltas.
+- `wendkeep sensors list|add` administra provas executáveis.
+- Exit `0` indica comando concluído; os gates usam exit `1` para prova vermelha e exit `2` para
+  contexto/uso inválido.
+
+## Exemplos
+
+```bash
+npx wendkeep change new login-tenant
+npx wendkeep spec effective --change login-tenant
+npx wendkeep change done 1.1 --change login-tenant
+npx wendkeep verify --change login-tenant
+npx wendkeep verify --deep --change login-tenant
+npx wendkeep change archive login-tenant
+```
+
+Para adicionar um sensor:
+
+```bash
+npx wendkeep sensors add api-contracts "npm run test:contracts" --severity critical
+```
+
+## Resultado esperado
+
+A change arquivada move seu delta para o spec vivo, preserva proposta/design/tarefas/evidência e
+gera um ADR. O archive só passa com tarefas fechadas, sensores exigidos verdes e verdict atual.
+
+## Erros comuns e diagnóstico
+
+- `no change`: selecione com `change use <slug>` ou informe `--change`.
+- `spec_impact: pending`: defina `required` com delta ou `none` com justificativa real.
+- Sensor não executado: mantenha uma ou mais tags `[sensor:id]` na mesma linha do checkbox. Todos
+  os IDs distintos dessa linha são exigidos e executados uma vez, na ordem declarada.
+- Evidência stale: rode novamente `verify` e `verify --deep` depois de alterar tarefas/spec.
+- Rebase em conflito: resolva o delta ou use `--accept-current` apenas quando isso for a decisão.
+
+## Próximos passos
+
+Leia [Perfis de Operação](operating-profiles.md), o guia profundo de [verify](verify.md) e a
+referência de [manutenção e diagnóstico](maintenance-and-diagnostics.md).

package/docs/pt-BR/commands/costs-and-observability.md

@@ -0,0 +1,65 @@
+# Custos e observabilidade
+
+**PT-BR** · [English](../../en/commands/costs-and-observability.md)
+
+## Objetivo
+
+Medir sessões, prompts, modelos e custo de IA, além de reconstruir históricos a partir dos
+transcripts canônicos quando necessário.
+
+## Quando usar
+
+Use `stats` para visão rápida, `cost` para análise e `cost rebuild` quando notas antigas não têm
+custos confiáveis.
+
+## Quando não usar
+
+Não aplique rebuild antes de validar provider e transcript de cada sessão. Não compare custos de
+projetos com registries misturados.
+
+## Pré-requisitos
+
+Registry consistente, tabela de preços completa e acesso aos transcripts das sessões reconstruídas.
+
+## Sintaxe
+
+```bash
+npx wendkeep stats [--vault <cofre>] [--json]
+npx wendkeep cost [--since <data>] [--top [N]] [--trend day|week|month] [--write] [--json]
+npx wendkeep cost rebuild [--session <id|arquivo>] [--limit N] [--apply] [--json]
+```
+
+## Opções e códigos de saída
+
+- `wendkeep stats` gera uma linha compartilhável ou JSON.
+- `wendkeep cost` agrega total/modelo/dia; `--trend` inclui projeção e `--write` atualiza
+  `00-Custo.md`.
+- `wendkeep cost rebuild` é dry-run por padrão; `--apply` grava notas e
+  `.brain/COST_REBUILD.json`.
+- Exit `0` indica cálculo consistente; não zero indica registry, preço, transcript ou parsing
+  insuficiente.
+
+## Exemplos
+
+```bash
+npx wendkeep stats --vault .MeuApp-vault
+npx wendkeep cost --since 2026-07-01 --top 10 --trend week
+npx wendkeep cost rebuild --session 019abc --json
+```
+
+## Resultado esperado
+
+Totais preservam dimensões de input/output/cache/reasoning por modelo e período. Rebuild mostra a
+prévia antes de alterar notas e deixa um relatório reproduzível quando aplicado.
+
+## Erros comuns e diagnóstico
+
+- Modelo sem preço: atualize a tabela antes de aceitar o total.
+- Custos de provider errado: valide a cadeia de identidade da sessão.
+- Transcript ausente: não estime silenciosamente; mantenha a lacuna visível.
+- Total duplicado por subagent/fork: confirme relação pai/subagent e deduplicação do registry.
+
+## Próximos passos
+
+Veja [sessões e importação](sessions-and-import.md), [importação retroativa](retroactive-import.md)
+e [manutenção](maintenance-and-diagnostics.md).

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

@@ -0,0 +1,87 @@
+# Instalação e primeiro uso
+
+**PT-BR** · [English](../../en/commands/getting-started.md)
+
+## Objetivo
+
+Instalar o WendKeep, vincular o projeto ao cofre correto e ativar captura, memória e skills sem
+sobrescrever configurações existentes.
+
+## Quando usar
+
+Use `wendkeep init` na primeira instalação e `wendkeep sync` depois de atualizar o pacote.
+
+## Quando não usar
+
+Não rode `init --force` para tentar reparar memória ou uma configuração ilegível. Use primeiro
+`wendkeep doctor` e o comando de reparo indicado.
+
+## Pré-requisitos
+
+- Node.js 18 ou mais recente.
+- Projeto local e permissão de escrita no cofre.
+- Claude Code ou Codex; Obsidian é opcional para execução e recomendado para navegar no grafo.
+
+## Sintaxe
+
+```bash
+npm install --save-dev wendkeep
+npx wendkeep init [opções]
+npx wendkeep sync [--project <raiz>] [--vault <cofre>] [--profile <perfil>] [--yes]
+```
+
+## Opções e códigos de saída
+
+- `--vault <path>` escolhe o cofre; sem ele, o vínculo local `.wendkeep.json` prevalece.
+- `--project <path>` aponta a raiz do projeto.
+- `--profile <OFF|FLOW|GUIDE|GOVERN|ASSURE>` seleciona o Perfil de Operação; instalação nova usa
+  `GOVERN`, re-init/sync sem a flag preserva a escolha existente e `OFF` nunca é inferido.
+- `--no-mcp`, `--no-colors` e `--no-companions` desativam integrações opcionais.
+- `--companions <csv>` habilita companions explicitamente.
+- `--yes` aceita defaults não interativos; `--force` atualiza apenas blocos gerenciados.
+- Exit `0` indica instalação/sincronização concluída; exit diferente de zero identifica a etapa
+  que falhou. `sync` para em `init`, `sync-defs` ou `doctor`, sem esconder o erro.
+- `sync` não pré-resolve o Vault antes de `init`: um vínculo inválido falha fechado nessa primeira
+  etapa, e apenas um vínculo validado segue para `sync-defs` e `doctor`; nunca há fallback global.
+
+## Exemplos
+
+Primeira instalação no projeto atual:
+
+```bash
+npm install --save-dev wendkeep
+npx wendkeep init --profile GOVERN --no-companions
+```
+
+Atualização posterior:
+
+```bash
+npm install --save-dev wendkeep@latest
+npx wendkeep sync --yes
+```
+
+Com pnpm, informe uma versão concreta porque políticas de idade mínima podem manter `latest`
+atrasado silenciosamente:
+
+```bash
+pnpm add -D wendkeep@X.Y.Z --config.minimumReleaseAge=0
+pnpm exec wendkeep sync --yes
+```
+
+## Resultado esperado
+
+O projeto recebe `.wendkeep.json`, hooks gerenciados de Claude/Codex, definições de skills e um
+cofre inicializado. Arquivos preexistentes são mesclados ou preservados; o comando informa o
+cofre efetivamente selecionado.
+
+## Erros comuns e diagnóstico
+
+- Cofre errado: confira `.wendkeep.json` e rode `wendkeep doctor --vault <path>`.
+- Hooks do Codex não executam: aprove o aviso **Hooks need review** no próximo startup.
+- `defs stale`: rode `wendkeep sync-defs --reseed` e reinicie os agentes.
+- `sync` para no doctor: leia a seção que falhou; não repita com `--force` sem entender a causa.
+
+## Próximos passos
+
+Veja [manutenção e diagnóstico](maintenance-and-diagnostics.md),
+[sessões e importação](sessions-and-import.md) e [memória compartilhada](memory.md).