wendkeep 0.58.0 → 0.58.3

package/CHANGELOG.md

@@ -4,6 +4,67 @@ 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.58.3] — 2026-07-26
+
+### Fixed
+
+- **O primeiro `SessionStop` elegível após a migração legacy → v2 volta a publicar o handoff.**
+  A activation passa a representar um epoch com múltiplos Stops, e `UserPromptSubmit` recupera
+  uma única activation ausente sob lock. Identidade nativa de sessão/turno e a ordem física do
+  transcript impedem que Stops duplicados, atrasados ou de uma activation anterior publiquem de
+  novo ou sobrescrevam checkpoints mais recentes.
+- **A publicação de memória ficou durável e observável de ponta a ponta.** O evento é enfileirado
+  antes de registrar `enqueued`, a projeção ocorre fora do lock e retries reutilizam a tentativa
+  congelada. Falhas preservam a outbox como `degraded`, enquanto retornos ambíguos deixam evidência
+  diagnóstica em vez de encerrar silenciosamente.
+- **`wendkeep doctor` agora detecta memória v2 realmente estagnada sem acusar uma migração nova.**
+  O diagnóstico correlaciona tentativa, ledger, outbox, revisão e checkpoint; revision 0 logo após
+  uma migração válida continua saudável, mas perda causal, ambiguidade e divergência bloqueiam.
+
+### Changed
+
+- **Os guias bilíngues de memória, sessões, migração e diagnóstico descrevem o lifecycle real.**
+  A documentação cobre epochs multi-Stop, recuperação única, retries idempotentes, estados
+  `enqueued|projected|degraded|ambiguous` e como interpretar revision 0.
+
+### Security
+
+- **Fixtures persistíveis de lifecycle são integralmente sintéticas.** Um gate de privacidade
+  verifica arquivos rastreados e novos e reporta somente arquivo, linha e categoria, evitando que
+  caminhos ou identificadores locais entrem em testes, commits e artefatos.
+
+## [0.58.2] — 2026-07-26
+
+### Added
+
+- **Referência completa dos comandos agora é bilíngue e orientada por tarefa.** Sete guias por
+  domínio e três guias profundos cobrem instalação, changes, verificação, memória, sessões,
+  importação, notas, custos e manutenção em PT-BR e inglês, com sintaxe, exits, exemplos,
+  resultados esperados e diagnóstico.
+- **Paridade documental virou gate automatizado.** O novo sensor `docs-bilingual` bloqueia pares
+  ausentes, comandos públicos sem cobertura, links quebrados, estrutura divergente, drift da regra
+  local e guias ausentes no tarball.
+
+### Changed
+
+- **Os READMEs agora apresentam as funcionalidades por grupos.** A referência extensa deu lugar a
+  um mapa navegável que leva ao guia correto no GitHub e no npm. O fluxo de `verify` deixa explícito
+  que exit 2 por ausência de change é contexto ocioso, não falha de saúde do projeto.
+
+## [0.58.1] — 2026-07-26
+
+### Fixed
+
+- **Vaults com `SHARED_MEMORY.md` legado voltam a atualizar sem bloquear o doctor.** `init` e
+  `sync` ainda preservam todos os bytes existentes e podem criar os sidecars v2 ausentes,
+  mas sidecars vazios não ativam a memória v2. `memory status --gate` reporta o estado
+  `legacy` como aviso não bloqueante e `brain-inject` mantém CORE+DIGEST durante a janela de
+  compatibilidade.
+- **`SessionStop` não migra memória implicitamente.** Enquanto o vault permanecer legado, o
+  Stop não grava outbox, ledger, candidates nem reescreve SHARED. A transição acontece somente
+  com `wendkeep memory migrate --apply`; conteúdo com assinatura/evidência v2 corrompida continua
+  visível e bloqueante, sem fallback silencioso.
+
 ## [0.58.0] — 2026-07-26
 
 ### Added

package/README.en.md

@@ -156,41 +156,23 @@ stop reporting `defs stale` without a single skill having been updated. If you h
 `wk-*`, that edit is overwritten; your own customisation belongs in a skill of your own,
 which the reseed never touches.
 
-## Commands
+## Features by group
 
-| Command | What it does |
-|---|---|
-| `wendkeep init` | Set up wendkeep in a project (vault taxonomy + settings + MCP + skills). |
-| `wendkeep sync [--project P]` | **One-command update**: runs `init` → `sync-defs` → `doctor` on the current project, stopping at the first failing step. Install the package first (a running process cannot replace itself). `--vault P` · `--yes` to skip the companions picker. |
-| `wendkeep hook <name>` | Run a session hook; invoked by `settings.json` (reads agent JSON on stdin). |
-| `wendkeep change <sub>` | Change lifecycle: `new <slug> [--simple]` / `use <slug>` (switch focus) / `continue <archived> <new> [--simple]` / `bind <slug> --session <id>` / `list` (global backlog) / `show <slug>` / `status [slug]` / `done <id> [--change slug]` / `undone <id> [--change slug]` / `relink [--apply] [--json]` (repair change wikilinks; preview by default) / `diff [slug]` / `archive [slug] [--force]` / `abandon [slug]` (drop it, no ADR) / `backlink [--apply]` (inject the proposal backlink into orphan design/tasks/spec files). `diff`, `archive` and `abandon` fall back to the active change when you omit the slug; bare `status` lists every open one. |
-| `wendkeep verify [--deep] [--change s]` | Run the change's task sensors; `--deep` assembles the independent-verification package. `--change` targets a change other than the active one; `--project <root>` runs it from outside the root. |
-| `wendkeep spec <sub>` | `list` / `show <capability>` generated contracts; `effective [--change <slug>] [--json]` (living contract + delta; defaults to the active change); `migrate`; `rebase [--accept-current]` (stops on conflicts unless you accept the living spec's side). |
-| `wendkeep sensors <sub>` | `list` / `add <id> "<command>"` with `--severity` / `--type` / `--report` / `--name` / `--description` / `--project` — view/edit `wendkeep.sensors.json` (JSON Schema shipped). |
-| `wendkeep cost [opts]` | Aggregate AI-coding spend across the vault's sessions — total, by model, by day. `--since <date>` / `--top [N]` (priciest) / `--trend [day\|week\|month]` (+ run-rate projection) / `--write` (generate `00-Custo.md`) / `--json`. |
-| `wendkeep cost rebuild [opts]` | Recalculate historical parent + subagent costs from `SESSION_REGISTRY`. Dry-run by default; `--apply` updates the notes and writes `.brain/COST_REBUILD.json`. Also `--session <id\|file>` / `--limit n` / `--json`. |
-| `wendkeep stats [--vault P]` | One shareable line: sessions · prompts · spend · span · models (`--json`). |
-| `wendkeep import [opts]` | **Retroactive memory** — backfill past **Claude + Codex** sessions into the vault (deduped by `session_id`). `--source all\|claude\|codex` / `--stamp-ids` / `--rescan-decisions` / `--from <dir>` / `--codex-from <dir>` / `--since d` / `--limit n` / `--dry-run` / `--json`. |
-| `wendkeep session list\|show\|use` | List the multi-session registry, show one conversation, or move only the human focus in `CURRENT_SESSION.md`. |
-| `wendkeep dashboard [--force]` | (Re)generate the vault's folder-filtered Bases + the `00-Dashboard` MOC. |
-| `wendkeep note new --type bug\|learning "<title>"` | Create a **numbered** derived note (`BUG-`/`APR-NNNN`) in the month folder and print its vault path. `--date YYYY-MM-DD`. |
-| `wendkeep note relink [--apply]` | Backfill provenance on orphan derived notes (BUG/APR with no source session), inheriting the modal session of their type/month cohort. Preview by default. |
-| `wendkeep note repair-frontmatter [--apply]` | Merge stacked frontmatter blocks in a session note — damage from the concurrent writes of pre-0.50 versions. Base keys from the original block, values from the newest; preview by default · `--json`. |
-| `wendkeep note repair-sections [--apply]` | Rebuild the `## Decisions/Bugs/Learnings generated in this session` sections from the linked derived notes — the body used to lag behind the closing block. Preview by default · `--json`. |
-| `wendkeep renumber-decisions` | Renumber `04-Decisões` to `ADR-NNNN-<slug>` chronologically, move notes out of legacy `DIA N` subfolders into the month folder, and rewrite wikilinks. Preview by default; `--apply` / `--json`. |
-| `wendkeep renumber-bugs` | Same for `05-Bugs` → `BUG-NNNN-<slug>`. |
-| `wendkeep renumber-learnings` | Same for `06-Aprendizados`/`06-Learnings` → `APR-NNNN-<slug>`. |
-| `wendkeep lesson add "t" "l"` | Record a project-local lesson (injected at the next SessionStart). `--change <slug>` ties the lesson to a change; `--vault P`. |
-| `wendkeep sync-defs` | Copy `.brain/agents\|skills` into `.codex/agents`, `.claude/skills`, `.agents/skills`; `--check` detects drift, `--reseed` refreshes the `wk-*` skills from the installed version's seeds. |
-| `wendkeep memory status [--gate] --vault P` | Inspect the v2 bundle without mutating it. `--gate` exits 1 only for a blocking state; warnings keep exit code 0. |
-| `wendkeep memory migrate [--apply] --vault P` | Convert a legacy `SHARED_MEMORY.md`. Dry-run by default; `--apply` creates a backup, turns legacy content into candidates, and publishes a valid v2 projection without editing CORE. |
-| `wendkeep memory repair --vault P` | Repair a partial/corrupt ledger under lock, preserving the original bytes in a `.bak`, retaining valid events, and re-projecting state. |
-| `wendkeep memory promote <candidate> --vault P` | Promote a candidate by ID by appending an auditable event; never edits the ledger in place. |
-| `wendkeep memory reject <candidate> --vault P` | Reject a candidate by ID by appending the decision to the audit history. |
-| `wendkeep validate-memory [path]` | Compatibility mode: validate `.brain/CORE.md` only (cap 25, 3 sections, no secrets/PII). Use `--vault <path>` to validate CORE + ledger + SHARED as a v2 bundle. |
-| `wendkeep theme sync [--vault P]` | Re-apply the colour system (CSS snippet + graph groups) to an existing vault — recovers a grey graph without re-running `init`. |
-| `wendkeep doctor [--vault P]` | Read-only vault health check. Beyond sessions/registry, links, notes, prices, and derived sections, it checks the v2 bundle and points to `memory status --gate` or `memory repair`; doctor never projects or repairs by itself. |
-| `wendkeep --version` / `--help` | Version / usage. |
+The README is the map; the guides provide syntax, options, exit codes, examples, and diagnosis.
+
+| Group | Use it for | Detailed guide |
+|---|---|---|
+| **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) |
+| **Changes and verification** | `change`, specs, sensors, TDD, evidence, 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) |
+| **Sessions and import** | hooks, registry, session focus, and Claude/Codex backfill | [Sessions and import](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/sessions-and-import.md) |
+| **Notes and knowledge** | BUG/APR/ADR, repairs, renumbering, lessons, and dashboard | [Notes and knowledge](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/notes-and-knowledge.md) |
+| **Costs and observability** | stats, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
+| **Maintenance and diagnostics** | doctor, definition drift, theme, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.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),
+[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).
 
 ## Shared Project Memory v2
 
@@ -198,11 +180,17 @@ Hot memory now separates human authorship, operational state, and evidence:
 
 - **`CORE.md` is canonical.** It is the short, hand-curated nucleus for durable preferences, active patterns, and open issues; no projector may infer or overwrite it.
 - **`SHARED_MEMORY.md` is generated operational state.** The `Stop` hook turns the session handoff into sanitized events; the projector deterministically reduces the ledger and publishes a verifiable revision, cursor, and hash. Facts are `verified` only with local evidence; unsupported reports remain `reported`, and disagreements become candidates for human judgment.
-- **`MEMORY_EVENTS.jsonl` is the append-only authority.** Producers publish to the outbox with exclusive creation, then the projector serializes append + projection under a lock. Repeating an identical `event_id`/payload is a no-op; reusing the ID with different bytes is observable corruption.
+- **`MEMORY_EVENTS.jsonl` is the append-only authority.** `Stop` makes events durable in the outbox before acknowledging the attempt; the projector runs outside the registry lock and retries reuse the same IDs. Repeating an identical `event_id`/payload is a no-op; reusing the ID with different bytes is observable corruption.
 - **`MEMORY_CANDIDATES.jsonl` is the curation queue.** Conflicts and legacy content are never silently promoted. `promote` and `reject` record the decision as a new event.
 
 Artifacts stay under `.brain/` only. Sanitization strips secrets, tokens, local paths, transcripts, and harness payloads both before persistence and before injection. Events carry a `project_id`, and one vault never accepts another project's events.
 
+Lifecycle in brief: each `SessionStart` opens an epoch that spans multiple `Stop` events;
+`UserPromptSubmit` advances the native turn and recovers exactly one closed legacy activation.
+Codex uses `session_id`/`turn_id` plus transcript order, with no artificial causal fields. See
+[sessions and hooks](docs/en/commands/sessions-and-import.md) and
+[memory](docs/en/commands/memory.md).
+
 ### Injection and budgets
 
 `brain-inject` delivers the same revision/hash on `startup`, `/clear`, and `/compact` `SessionStart` events, always placing CORE and SHARED before change context. The full envelope is capped at 24 KiB; CORE reserves up to 4 KiB, SHARED up to 6 KiB, and each line is capped at 320 characters. Under pressure, lessons are removed first, then non-current changes. CORE and SHARED are never prefix-sliced: a missing, invalid, or over-budget layer becomes a visible, repairable `<wk_memory_error>`.
@@ -217,7 +205,11 @@ wendkeep memory migrate --apply --vault .MyApp-vault  # backup + candidates + v2
 
 ### Health and recovery
 
-Use `wendkeep memory status --gate --vault <vault>` in CI and before `verify`/`archive`. The critical `memory-health` sensor blocks ledger/outbox/bundle corruption, revision/cursor/hash lag, and active conflicts. A valid pending outbox or ordinary candidate is recoverable and remains a warning rather than blocking.
+Use `wendkeep memory status --gate --vault <vault>` in CI and before `verify`/`archive`. Revision 0
+immediately after valid migration is healthy. The gate correlates `last_memory_attempt`, outbox,
+ledger, SHARED, and checkpoint: `degraded` with a durable outbox is a warning; an ambiguous attempt,
+lost publication, or mismatched checkpoint blocks. See [migration](docs/en/commands/memory-migration.md)
+and [diagnostics](docs/en/commands/maintenance-and-diagnostics.md).
 
 If status blocks, preserve the evidence and run `wendkeep memory repair --vault <vault>` to save a backup of the corrupt ledger, retain valid lines, and re-project. Then run `status --gate` again. Conflicts require explicit curation with `memory promote <id>` or `memory reject <id>`; doctor only diagnoses.
 

package/README.md

@@ -156,41 +156,23 @@ stop reporting `defs stale` without a single skill having been updated. If you h
 `wk-*`, that edit is overwritten; your own customisation belongs in a skill of your own,
 which the reseed never touches.
 
-## Commands
+## Features by group
 
-| Command | What it does |
-|---|---|
-| `wendkeep init` | Set up wendkeep in a project (vault taxonomy + settings + MCP + skills). |
-| `wendkeep sync [--project P]` | **One-command update**: runs `init` → `sync-defs` → `doctor` on the current project, stopping at the first failing step. Install the package first (a running process cannot replace itself). `--vault P` · `--yes` to skip the companions picker. |
-| `wendkeep hook <name>` | Run a session hook; invoked by `settings.json` (reads agent JSON on stdin). |
-| `wendkeep change <sub>` | Change lifecycle: `new <slug> [--simple]` / `use <slug>` (switch focus) / `continue <archived> <new> [--simple]` / `bind <slug> --session <id>` / `list` (global backlog) / `show <slug>` / `status [slug]` / `done <id> [--change slug]` / `undone <id> [--change slug]` / `relink [--apply] [--json]` (repair change wikilinks; preview by default) / `diff [slug]` / `archive [slug] [--force]` / `abandon [slug]` (drop it, no ADR) / `backlink [--apply]` (inject the proposal backlink into orphan design/tasks/spec files). `diff`, `archive` and `abandon` fall back to the active change when you omit the slug; bare `status` lists every open one. |
-| `wendkeep verify [--deep] [--change s]` | Run the change's task sensors; `--deep` assembles the independent-verification package. `--change` targets a change other than the active one; `--project <root>` runs it from outside the root. |
-| `wendkeep spec <sub>` | `list` / `show <capability>` generated contracts; `effective [--change <slug>] [--json]` (living contract + delta; defaults to the active change); `migrate`; `rebase [--accept-current]` (stops on conflicts unless you accept the living spec's side). |
-| `wendkeep sensors <sub>` | `list` / `add <id> "<command>"` with `--severity` / `--type` / `--report` / `--name` / `--description` / `--project` — view/edit `wendkeep.sensors.json` (JSON Schema shipped). |
-| `wendkeep cost [opts]` | Aggregate AI-coding spend across the vault's sessions — total, by model, by day. `--since <date>` / `--top [N]` (priciest) / `--trend [day\|week\|month]` (+ run-rate projection) / `--write` (generate `00-Custo.md`) / `--json`. |
-| `wendkeep cost rebuild [opts]` | Recalculate historical parent + subagent costs from `SESSION_REGISTRY`. Dry-run by default; `--apply` updates the notes and writes `.brain/COST_REBUILD.json`. Also `--session <id\|file>` / `--limit n` / `--json`. |
-| `wendkeep stats [--vault P]` | One shareable line: sessions · prompts · spend · span · models (`--json`). |
-| `wendkeep import [opts]` | **Retroactive memory** — backfill past **Claude + Codex** sessions into the vault (deduped by `session_id`). `--source all\|claude\|codex` / `--stamp-ids` / `--rescan-decisions` / `--from <dir>` / `--codex-from <dir>` / `--since d` / `--limit n` / `--dry-run` / `--json`. |
-| `wendkeep session list\|show\|use` | List the multi-session registry, show one conversation, or move only the human focus in `CURRENT_SESSION.md`. |
-| `wendkeep dashboard [--force]` | (Re)generate the vault's folder-filtered Bases + the `00-Dashboard` MOC. |
-| `wendkeep note new --type bug\|learning "<title>"` | Create a **numbered** derived note (`BUG-`/`APR-NNNN`) in the month folder and print its vault path. `--date YYYY-MM-DD`. |
-| `wendkeep note relink [--apply]` | Backfill provenance on orphan derived notes (BUG/APR with no source session), inheriting the modal session of their type/month cohort. Preview by default. |
-| `wendkeep note repair-frontmatter [--apply]` | Merge stacked frontmatter blocks in a session note — damage from the concurrent writes of pre-0.50 versions. Base keys from the original block, values from the newest; preview by default · `--json`. |
-| `wendkeep note repair-sections [--apply]` | Rebuild the `## Decisions/Bugs/Learnings generated in this session` sections from the linked derived notes — the body used to lag behind the closing block. Preview by default · `--json`. |
-| `wendkeep renumber-decisions` | Renumber `04-Decisões` to `ADR-NNNN-<slug>` chronologically, move notes out of legacy `DIA N` subfolders into the month folder, and rewrite wikilinks. Preview by default; `--apply` / `--json`. |
-| `wendkeep renumber-bugs` | Same for `05-Bugs` → `BUG-NNNN-<slug>`. |
-| `wendkeep renumber-learnings` | Same for `06-Aprendizados`/`06-Learnings` → `APR-NNNN-<slug>`. |
-| `wendkeep lesson add "t" "l"` | Record a project-local lesson (injected at the next SessionStart). `--change <slug>` ties the lesson to a change; `--vault P`. |
-| `wendkeep sync-defs` | Copy `.brain/agents\|skills` into `.codex/agents`, `.claude/skills`, `.agents/skills`; `--check` detects drift, `--reseed` refreshes the `wk-*` skills from the installed version's seeds. |
-| `wendkeep memory status [--gate] --vault P` | Inspect the v2 bundle without mutating it. `--gate` exits 1 only for a blocking state; warnings keep exit code 0. |
-| `wendkeep memory migrate [--apply] --vault P` | Convert a legacy `SHARED_MEMORY.md`. Dry-run by default; `--apply` creates a backup, turns legacy content into candidates, and publishes a valid v2 projection without editing CORE. |
-| `wendkeep memory repair --vault P` | Repair a partial/corrupt ledger under lock, preserving the original bytes in a `.bak`, retaining valid events, and re-projecting state. |
-| `wendkeep memory promote <candidate> --vault P` | Promote a candidate by ID by appending an auditable event; never edits the ledger in place. |
-| `wendkeep memory reject <candidate> --vault P` | Reject a candidate by ID by appending the decision to the audit history. |
-| `wendkeep validate-memory [path]` | Compatibility mode: validate `.brain/CORE.md` only (cap 25, 3 sections, no secrets/PII). Use `--vault <path>` to validate CORE + ledger + SHARED as a v2 bundle. |
-| `wendkeep theme sync [--vault P]` | Re-apply the colour system (CSS snippet + graph groups) to an existing vault — recovers a grey graph without re-running `init`. |
-| `wendkeep doctor [--vault P]` | Read-only vault health check. Beyond sessions/registry, links, notes, prices, and derived sections, it checks the v2 bundle and points to `memory status --gate` or `memory repair`; doctor never projects or repairs by itself. |
-| `wendkeep --version` / `--help` | Version / usage. |
+The README is the map; the guides provide syntax, options, exit codes, examples, and diagnosis.
+
+| Group | Use it for | Detailed guide |
+|---|---|---|
+| **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) |
+| **Changes and verification** | `change`, specs, sensors, TDD, evidence, 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) |
+| **Sessions and import** | hooks, registry, session focus, and Claude/Codex backfill | [Sessions and import](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/sessions-and-import.md) |
+| **Notes and knowledge** | BUG/APR/ADR, repairs, renumbering, lessons, and dashboard | [Notes and knowledge](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/notes-and-knowledge.md) |
+| **Costs and observability** | stats, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
+| **Maintenance and diagnostics** | doctor, definition drift, theme, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.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),
+[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).
 
 ## Shared Project Memory v2
 
@@ -198,11 +180,17 @@ Hot memory now separates human authorship, operational state, and evidence:
 
 - **`CORE.md` is canonical.** It is the short, hand-curated nucleus for durable preferences, active patterns, and open issues; no projector may infer or overwrite it.
 - **`SHARED_MEMORY.md` is generated operational state.** The `Stop` hook turns the session handoff into sanitized events; the projector deterministically reduces the ledger and publishes a verifiable revision, cursor, and hash. Facts are `verified` only with local evidence; unsupported reports remain `reported`, and disagreements become candidates for human judgment.
-- **`MEMORY_EVENTS.jsonl` is the append-only authority.** Producers publish to the outbox with exclusive creation, then the projector serializes append + projection under a lock. Repeating an identical `event_id`/payload is a no-op; reusing the ID with different bytes is observable corruption.
+- **`MEMORY_EVENTS.jsonl` is the append-only authority.** `Stop` makes events durable in the outbox before acknowledging the attempt; the projector runs outside the registry lock and retries reuse the same IDs. Repeating an identical `event_id`/payload is a no-op; reusing the ID with different bytes is observable corruption.
 - **`MEMORY_CANDIDATES.jsonl` is the curation queue.** Conflicts and legacy content are never silently promoted. `promote` and `reject` record the decision as a new event.
 
 Artifacts stay under `.brain/` only. Sanitization strips secrets, tokens, local paths, transcripts, and harness payloads both before persistence and before injection. Events carry a `project_id`, and one vault never accepts another project's events.
 
+Lifecycle in brief: each `SessionStart` opens an epoch that spans multiple `Stop` events;
+`UserPromptSubmit` advances the native turn and recovers exactly one closed legacy activation.
+Codex uses `session_id`/`turn_id` plus transcript order, with no artificial causal fields. See
+[sessions and hooks](docs/en/commands/sessions-and-import.md) and
+[memory](docs/en/commands/memory.md).
+
 ### Injection and budgets
 
 `brain-inject` delivers the same revision/hash on `startup`, `/clear`, and `/compact` `SessionStart` events, always placing CORE and SHARED before change context. The full envelope is capped at 24 KiB; CORE reserves up to 4 KiB, SHARED up to 6 KiB, and each line is capped at 320 characters. Under pressure, lessons are removed first, then non-current changes. CORE and SHARED are never prefix-sliced: a missing, invalid, or over-budget layer becomes a visible, repairable `<wk_memory_error>`.
@@ -217,7 +205,11 @@ wendkeep memory migrate --apply --vault .MyApp-vault  # backup + candidates + v2
 
 ### Health and recovery
 
-Use `wendkeep memory status --gate --vault <vault>` in CI and before `verify`/`archive`. The critical `memory-health` sensor blocks ledger/outbox/bundle corruption, revision/cursor/hash lag, and active conflicts. A valid pending outbox or ordinary candidate is recoverable and remains a warning rather than blocking.
+Use `wendkeep memory status --gate --vault <vault>` in CI and before `verify`/`archive`. Revision 0
+immediately after valid migration is healthy. The gate correlates `last_memory_attempt`, outbox,
+ledger, SHARED, and checkpoint: `degraded` with a durable outbox is a warning; an ambiguous attempt,
+lost publication, or mismatched checkpoint blocks. See [migration](docs/en/commands/memory-migration.md)
+and [diagnostics](docs/en/commands/maintenance-and-diagnostics.md).
 
 If status blocks, preserve the evidence and run `wendkeep memory repair --vault <vault>` to save a backup of the corrupt ledger, retain valid lines, and re-project. Then run `status --gate` again. Conflicts require explicit curation with `memory promote <id>` or `memory reject <id>`; doctor only diagnoses.
 

package/docs/en/commands/changes-and-verification.md

@@ -0,0 +1,79 @@
+# Changes, specs, sensors, and archive
+
+**English** · [Português](../../pt-BR/commands/changes-and-verification.md)
+
+## Purpose
+
+Carry a change from recorded intent to an archived decision, linking requirements, tasks,
+sensors, evidence, and verdict in the vault graph.
+
+## When to use
+
+Use for any non-trivial implementation or fix that must leave auditable proof.
+
+## When not to use
+
+Do not create a change merely to inspect health, import sessions, or run read-only maintenance.
+
+## Prerequisites
+
+Initialize the project, keep the vault healthy, and provide a valid `wendkeep.sensors.json`.
+
+## Syntax
+
+```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>
+```
+
+## Options and exit codes
+
+- `wendkeep change new <slug> [--simple]` creates proposal, design, tasks, and active pointer.
+- `change use`, `list`, `show`, `status`, `diff`, `done`, and `undone` inspect or update work
+  without archiving it.
+- `change continue <archived> <new>` starts follow-up work without inheriting stale proof.
+- `change bind <slug> --session <id>` attaches an existing session.
+- `change relink [--apply]` and `change backlink [--apply]` repair graph links; preview is default.
+- `change abandon <slug>` drops work without an ADR; `archive --force` needs explicit human choice.
+- `wendkeep spec list|show|effective|migrate|rebase` manages living contracts and deltas.
+- `wendkeep sensors list|add` manages executable proof.
+- Exit `0` means completion; gates use exit `1` for red proof and exit `2` for invalid
+  context/usage.
+
+## Examples
+
+```bash
+npx wendkeep change new tenant-login
+npx wendkeep spec effective --change tenant-login
+npx wendkeep change done 1.1 --change tenant-login
+npx wendkeep verify --change tenant-login
+npx wendkeep verify --deep --change tenant-login
+npx wendkeep change archive tenant-login
+```
+
+Add a sensor:
+
+```bash
+npx wendkeep sensors add api-contracts "npm run test:contracts" --severity critical
+```
+
+## Expected result
+
+An archived change promotes its delta into the living spec, preserves proposal/design/tasks/proof,
+and mints an ADR. Archive passes only with closed tasks, green required sensors, and a fresh verdict.
+
+## Common errors and diagnosis
+
+- `no change`: select one with `change use <slug>` or pass `--change`.
+- `spec_impact: pending`: choose `required` with a delta or `none` with a real reason.
+- Sensor not executed: keep `[sensor:id]` on the same checkbox line as the task.
+- Stale evidence: rerun `verify` and `verify --deep` after task/spec edits.
+- Rebase conflict: resolve the delta or use `--accept-current` only when that is the decision.
+
+## Next steps
+
+Read the deep [verify guide](verify.md) and [maintenance and diagnostics](maintenance-and-diagnostics.md).

package/docs/en/commands/costs-and-observability.md

@@ -0,0 +1,65 @@
+# Costs and observability
+
+**English** · [Português](../../pt-BR/commands/costs-and-observability.md)
+
+## Purpose
+
+Measure sessions, prompts, models, and AI spend, and rebuild historical costs from canonical
+transcripts when required.
+
+## When to use
+
+Use `stats` for a quick view, `cost` for analysis, and `cost rebuild` when older notes lack
+trustworthy costs.
+
+## When not to use
+
+Do not apply rebuild before validating each session's provider and transcript. Do not compare
+projects whose registries are mixed.
+
+## Prerequisites
+
+A consistent registry, complete price table, and transcript access for rebuilt sessions.
+
+## Syntax
+
+```bash
+npx wendkeep stats [--vault <vault>] [--json]
+npx wendkeep cost [--since <date>] [--top [N]] [--trend day|week|month] [--write] [--json]
+npx wendkeep cost rebuild [--session <id|file>] [--limit N] [--apply] [--json]
+```
+
+## Options and exit codes
+
+- `wendkeep stats` emits one shareable line or JSON.
+- `wendkeep cost` aggregates total/model/day; `--trend` adds projection and `--write` refreshes
+  `00-Custo.md`.
+- `wendkeep cost rebuild` is dry-run by default; `--apply` writes notes and
+  `.brain/COST_REBUILD.json`.
+- Exit `0` means a consistent calculation; non-zero reports insufficient registry, price,
+  transcript, or parsing state.
+
+## Examples
+
+```bash
+npx wendkeep stats --vault .MyApp-vault
+npx wendkeep cost --since 2026-07-01 --top 10 --trend week
+npx wendkeep cost rebuild --session 019abc --json
+```
+
+## Expected result
+
+Totals retain input/output/cache/reasoning dimensions by model and period. Rebuild shows a preview
+before changing notes and leaves a reproducible report when applied.
+
+## Common errors and diagnosis
+
+- Model without a price: update the table before accepting totals.
+- Wrong-provider costs: validate the session identity chain.
+- Missing transcript: do not estimate silently; keep the gap visible.
+- Duplicated parent/subagent/fork totals: verify registry relationships and deduplication.
+
+## Next steps
+
+See [sessions and import](sessions-and-import.md), [retroactive import](retroactive-import.md), and
+[maintenance](maintenance-and-diagnostics.md).

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

@@ -0,0 +1,82 @@
+# Installation and first use
+
+**English** · [Português](../../pt-BR/commands/getting-started.md)
+
+## Purpose
+
+Install WendKeep, bind the project to the correct vault, and enable capture, memory, and skills
+without overwriting existing configuration.
+
+## When to use
+
+Use `wendkeep init` for the first installation and `wendkeep sync` after updating the package.
+
+## When not to use
+
+Do not run `init --force` as a generic repair for memory or unreadable configuration. Run
+`wendkeep doctor` first and follow the repair command it reports.
+
+## Prerequisites
+
+- Node.js 18 or newer.
+- A local project and write access to the vault.
+- Claude Code or Codex; Obsidian is optional at runtime and recommended for graph navigation.
+
+## Syntax
+
+```bash
+npm install --save-dev wendkeep
+npx wendkeep init [options]
+npx wendkeep sync [--project <root>] [--vault <vault>] [--yes]
+```
+
+## Options and exit codes
+
+- `--vault <path>` selects the vault; otherwise the local `.wendkeep.json` binding wins.
+- `--project <path>` selects the project root.
+- `--no-mcp`, `--no-colors`, and `--no-companions` disable optional integrations.
+- `--companions <csv>` explicitly enables companion integrations.
+- `--yes` accepts non-interactive defaults; `--force` refreshes managed blocks only.
+- Exit `0` means setup/sync completed. Any other exit identifies the failed stage. `sync` stops at
+  `init`, `sync-defs`, or `doctor` instead of hiding the error.
+
+## Examples
+
+First installation in the current project:
+
+```bash
+npm install --save-dev wendkeep
+npx wendkeep init --no-companions
+```
+
+Later update:
+
+```bash
+npm install --save-dev wendkeep@latest
+npx wendkeep sync --yes
+```
+
+With pnpm, pin a concrete version because minimum-release-age policies may keep `latest` silently
+behind:
+
+```bash
+pnpm add -D wendkeep@0.58.2
+pnpm exec wendkeep sync --yes
+```
+
+## Expected result
+
+The project receives `.wendkeep.json`, managed Claude/Codex hooks, skill definitions, and an
+initialized vault. Existing files are merged or preserved, and the selected vault is printed.
+
+## Common errors and diagnosis
+
+- Wrong vault: inspect `.wendkeep.json` and run `wendkeep doctor --vault <path>`.
+- Codex hooks do not run: approve **Hooks need review** on the next startup.
+- `defs stale`: run `wendkeep sync-defs --reseed`, then restart the agents.
+- `sync` stops at doctor: read the failing section; do not retry with `--force` blindly.
+
+## Next steps
+
+Continue with [maintenance and diagnostics](maintenance-and-diagnostics.md),
+[sessions and import](sessions-and-import.md), and [shared memory](memory.md).

package/docs/en/commands/maintenance-and-diagnostics.md

@@ -0,0 +1,77 @@
+# Maintenance and diagnostics
+
+**English** · [Português](../../pt-BR/commands/maintenance-and-diagnostics.md)
+
+## Purpose
+
+Inspect vault health and keep definitions, theme, and package version aligned without treating
+change commands as global checks.
+
+## When to use
+
+Use after install/update, when hooks emit warnings, or before starting a change.
+
+## When not to use
+
+Do not run `wendkeep verify` when no change is active. It proves a change's tasks; it is not a
+replacement for doctor.
+
+## Prerequisites
+
+Run from the project root or provide `--project` and `--vault` explicitly.
+
+## Syntax
+
+```bash
+npx wendkeep doctor [--vault <vault>]
+npx wendkeep sync-defs [--check|--reseed] --vault <vault> --project <root>
+npx wendkeep theme sync --vault <vault>
+npx wendkeep --version
+npx wendkeep --help
+```
+
+## Options and exit codes
+
+- `doctor` is read-only; exit `0` accepts recoverable warnings, while non-zero means failure.
+- In v2, `doctor`/`memory status --gate` correlate `last_memory_attempt` (mode, disposition, event
+  IDs, and checkpoint) with outbox, ledger, and SHARED; they do not infer health from revision alone.
+- `revision: 0` after a valid migration, with no v2 attempt, is healthy. A `degraded` attempt whose
+  events remain durable in the outbox/ledger is a recoverable warning.
+- An ambiguous attempt, a lost event ID (absent from ledger and outbox), `projected` state found
+  only in the outbox, or a mismatched checkpoint is blocking.
+- `sync-defs --check` detects drift without writes; `--reseed` restores packaged `wk-*` skills.
+- `theme sync` reapplies the CSS snippet and graph groups without recreating the vault.
+- `wendkeep --version` prints the running version; `wendkeep --help` lists the public interface.
+
+## Examples
+
+Post-update checklist:
+
+```bash
+npx wendkeep --version
+npx wendkeep sync-defs --check --vault .MyApp-vault --project .
+npx wendkeep doctor --vault .MyApp-vault
+npx wendkeep memory status --gate --vault .MyApp-vault
+```
+
+## Expected result
+
+Doctor names sessions, registry, links, notes, prices, derived sections, and memory as healthy or
+provides a specific diagnostic/repair command. For memory, it distinguishes a valid initial empty
+state, recoverable pending replay, and lost/divergent lifecycle state. It never repairs implicitly
+or echoes private projector-error content into its report.
+
+## Common errors and diagnosis
+
+- `no vault`: run from the bound root or pass `--vault`.
+- `defs stale`: confirm the version and run `sync-defs --reseed`.
+- Legacy vault: this is a non-blocking warning; plan `memory migrate --apply` separately.
+- `degraded` plus an intact outbox: warning; preserve the outbox and allow idempotent replay.
+- `ambiguous`, lost publication, or a mismatched checkpoint: blocking; preserve registry, ledger,
+  outbox, and SHARED so `last_memory_attempt` can be correlated before repair.
+- Corrupt bundle: preserve evidence and run `memory status --gate` before `memory repair`.
+
+## Next steps
+
+See [installation and first use](getting-started.md), [memory](memory.md), and
+[change verification](verify.md).