wendkeep 0.58.1 → 0.59.0

package/bin/wendkeep.mjs

@@ -22,12 +22,13 @@ function version() {
   }
 }
 
-const HELP = `wendkeep ${version()} — capture AI coding agent sessions into your Obsidian vault.
+const HELP = `wendkeep ${version()} — keep durable AI sessions in an Obsidian vault, with optional governance.
 
 Usage:
   wendkeep init [options]      Set up wendkeep in a project (cross-platform).
     --vault <path>         Obsidian vault folder (default: <project>/.<project-name>-vault).
     --project <path>       Project root to wire (default: current directory).
+    --profile <name>       Operating profile: OFF, FLOW, GUIDE, GOVERN (default), or ASSURE.
     --no-mcp               Do not add the mcpvault MCP server to .mcp.json.
     --companions <csv>     Companion plugins/MCP to pin: context-mode,caveman,understand-anything
                            (default: none — opt in explicitly). dotcontext is legacy — the native a2 loop replaces it.
@@ -46,7 +47,7 @@ Usage:
                            command — the three steps that repeat identically after every
                            package update. Stops at the first failing step. Install the
                            package first (npm i -D wendkeep@latest); a running process
-                           cannot replace itself. · --vault P · --yes.
+                           cannot replace itself. · --vault P · --profile <name> · --yes.
 
   wendkeep doctor [--vault P]  Run a vault health check.
   wendkeep change <sub>        Change lifecycle: new [--simple] | use | bind <slug> --session <id> | continue | list | show |
@@ -56,6 +57,11 @@ Usage:
   wendkeep theme sync          Re-aplica o color system (snippet CSS + graph color groups) num vault
                            existente — recupera o grafo cinza sem re-init. --vault P.
   wendkeep session <sub>       Session registry: list | show <id> | use <id>.
+  wendkeep profile <sub>       Operating profile: status | use <OFF|FLOW|GUIDE|GOVERN|ASSURE>.
+                           --session <id> sets an audited session override; otherwise changes
+                           the project default. The Vault/session/memory core is always active.
+  wendkeep flow <sub>          Low-ceremony E -> V contract: start | status | show | finish | promote.
+                           FLOW records scope, sensors and a receipt without creating a change.
   wendkeep spec <sub>          Specs: list | show | effective [--change] [--json] | migrate | rebase.
   wendkeep sensors <sub>       list | add <id> "<command>" [--severity --type --report].
   wendkeep cost [opts]         Aggregate AI-coding spend across the vault's sessions.
@@ -95,7 +101,9 @@ Usage:
                            behind the closing block. Dry-run by default · --apply · --json.
   wendkeep lesson add "t" "l"   Record a project-local lesson (injected at SessionStart).
   wendkeep memory <sub>          Shared memory v2: status | migrate [--apply] | repair |
+                           reconcile <session> --by-session <session> --reason <text> [--apply] |
                            promote <candidate> | reject <candidate>. --vault P.
+                           Reconcile is dry-run by default; the original attempt remains audited.
   wendkeep validate-memory [path]  Validate .brain/CORE.md against the compaction
                            protocol (cap 25, 3 sections, no secrets/PII).
                            --vault <path> validates the complete v2 bundle.
@@ -142,11 +150,25 @@ async function preferProjectVault(argv) {
   if (optionValue(argv, '--vault')) return;
   try {
     const { resolveProjectVault } = await import('../src/project-vault.mjs');
+    // A sensor may itself invoke WendKeep. `verify`/`flow finish` already selected the
+    // authoritative Vault explicitly, so preserve that choice across the child process
+    // instead of letting the sensor cwd's project binding redirect it.
+    const sensorVault = process.env.WENDKEEP_SENSOR_VAULT;
+    if (sensorVault) {
+      const selected = resolveProjectVault({
+        startDir: optionValue(argv, '--project') || process.cwd(),
+        explicitVault: sensorVault,
+      });
+      process.env.OBSIDIAN_VAULT_PATH = selected.base;
+      return;
+    }
     const resolved = resolveProjectVault({ startDir: optionValue(argv, '--project') || process.cwd() });
     process.env.OBSIDIAN_VAULT_PATH = resolved.base;
-  } catch {
+  } catch (error) {
     // Backward-compatible manual CLI behavior: individual commands still explain
-    // --vault / legacy env when no project binding exists. Hooks do not use this path.
+    // --vault / legacy env only when no project binding exists. A configured but
+    // corrupt/missing/mismatched binding must abort before dispatch to another Vault.
+    if (error?.code !== 'WENDKEEP_VAULT_UNCONFIGURED') throw error;
   }
 }
 
@@ -156,10 +178,26 @@ async function main() {
   // Intercepted BEFORE vault resolution so it works anywhere — help must never depend
   // on project state, and no command may treat --help as a runnable default.
   if (cmd && (rest.includes('--help') || rest.includes('-h'))) {
-    process.stdout.write(HELP);
+    if (cmd === 'flow') {
+      const { FLOW_HELP } = await import('../src/flow.mjs');
+      process.stdout.write(FLOW_HELP);
+    } else if (cmd === 'profile') {
+      const { PROFILE_HELP } = await import('../src/profile.mjs');
+      process.stdout.write(PROFILE_HELP);
+    } else {
+      process.stdout.write(HELP);
+    }
     process.exit(0);
   }
-  if (cmd && !['init', 'hook', '--version', '-v', '--help', '-h', 'help'].includes(cmd)) {
+  const validatesStandaloneCore = cmd === 'validate-memory'
+    && !rest.includes('--vault')
+    && !rest.some((item) => item.startsWith('--vault='));
+  if (cmd
+    && !validatesStandaloneCore
+    // `sync` starts with `init` and resolves the freshly bound Vault itself. Pre-resolving
+    // here would prevent that repair step from reporting a corrupt binding as its own
+    // first-stage failure (and could never make it as far as the guarded init).
+    && !['init', 'sync', 'hook', '--version', '-v', '--help', '-h', 'help'].includes(cmd)) {
     await preferProjectVault(rest);
   }
   switch (cmd) {
@@ -211,6 +249,16 @@ async function main() {
       runSession(rest);
       break;
     }
+    case 'profile': {
+      const { runProfile } = await import('../src/profile.mjs');
+      process.exit(runProfile(rest));
+      break;
+    }
+    case 'flow': {
+      const { runFlow } = await import('../src/flow.mjs');
+      process.exit(await runFlow(rest));
+      break;
+    }
     case 'theme': {
       const { runTheme } = await import('../src/theme.mjs');
       runTheme(rest);

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

@@ -0,0 +1,85 @@
+# 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.
+For local maintenance eligible for the `FLOW` profile, use the microcontract in
+[Operating profiles](operating-profiles.md); under `OFF`, the lifecycle remains available but is
+not imposed by Wend Runtime.
+
+## 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 a change; `--simple` only skips design, is not
+  `FLOW`, and preserves the legacy lifecycle/ADR contract.
+- `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 one or more `[sensor:id]` tags on the same checkbox line. Every
+  distinct ID on that line is required and runs once, in declaration order.
+- 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 [Operating profiles](operating-profiles.md), 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,86 @@
+# 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>] [--profile <profile>] [--yes]
+```
+
+## Options and exit codes
+
+- `--vault <path>` selects the vault; otherwise the local `.wendkeep.json` binding wins.
+- `--project <path>` selects the project root.
+- `--profile <OFF|FLOW|GUIDE|GOVERN|ASSURE>` selects the Operating Profile; new installs use
+  `GOVERN`, re-init/sync without the flag preserves the existing choice, and `OFF` is never inferred.
+- `--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.
+- `sync` does not pre-resolve the Vault before `init`: an invalid binding fails closed at that first
+  stage, and only a validated binding reaches `sync-defs` and `doctor`; no global fallback is used.
+
+## Examples
+
+First installation in the current project:
+
+```bash
+npm install --save-dev wendkeep
+npx wendkeep init --profile GOVERN --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@X.Y.Z --config.minimumReleaseAge=0
+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).

package/docs/en/commands/memory-migration.md

@@ -0,0 +1,73 @@
+# Legacy-to-v2 memory migration
+
+**English** · [Português](../../pt-BR/commands/memory-migration.md)
+
+## Purpose
+
+Convert a legacy `SHARED_MEMORY.md` into an auditable v2 bundle without overwriting CORE or
+silently promoting old reports.
+
+## When to use
+
+Use when `memory status` reports `legacy` and the team is ready to curate converted content.
+
+## When not to use
+
+Do not migrate automatically during `init`, `sync`, SessionStop, or merely to silence a warning.
+Do not apply until the backup and expected state are understood.
+
+## Prerequisites
+
+- Valid CORE and preserved legacy bytes.
+- No partially corrupt v2 bundle.
+- Human review of the candidates that will be created.
+
+## Syntax
+
+```bash
+npx wendkeep memory status --gate --vault <vault>
+npx wendkeep memory migrate --vault <vault>
+npx wendkeep memory migrate --apply --vault <vault>
+```
+
+## Options and exit codes
+
+- Without `--apply`, `wendkeep memory migrate` is a zero-write dry run.
+- `--apply` creates a backup, converts legacy content into candidates, and publishes valid v2.
+- A newly migrated bundle may start healthy at `revision: 0`: no v2 attempt or eligible event has
+  happened yet, so zero does not mean the lifecycle is stalled.
+- Exit `0` means a consistent preview/application; non-zero preserves original state and reports
+  the failure.
+
+## Examples
+
+```bash
+npx wendkeep memory migrate --vault .MyApp-vault
+# review the preview
+npx wendkeep memory migrate --apply --vault .MyApp-vault
+npx wendkeep memory status --gate --vault .MyApp-vault
+```
+
+## Expected result
+
+The vault receives a coherent v2 ledger/projection, a backup of legacy SHARED, and candidates for
+unsupported facts. CORE is untouched and unverified content is not activated automatically.
+After migration, the next `UserPromptSubmit` opens exactly one recovery activation when the
+legacy registry was closed; the first transcript-proven `Stop` publishes once and advances SHARED
+to revision 1. Replaying that prompt or Stop does not duplicate the event/revision.
+
+## Common errors and diagnosis
+
+- Dry run says already v2: do not apply again.
+- `revision: 0` immediately after a valid apply: this is healthy; wait for an eligible prompt and
+  Stop instead of repairing or repeating migration.
+- Partial/corrupt v2 bundle: use status and repair; migration is not a corruption tool.
+- First post-migration Stop is `ambiguous`: verify that its `turn_id` belongs to the transcript and
+  that `UserPromptSubmit` opened/advanced the recovery activation.
+- Many candidates: curate gradually with `memory promote`/`memory reject`.
+- Legacy warning remains after apply: verify the selected vault and project binding.
+
+## Next steps
+
+Return to [memory and curation](memory.md) and run
+[maintenance and diagnostics](maintenance-and-diagnostics.md).

package/docs/en/commands/memory.md

@@ -0,0 +1,102 @@
+# Shared memory and curation
+
+**English** · [Português](../../pt-BR/commands/memory.md)
+
+## Purpose
+
+Inspect and curate CORE, SHARED, ledger, outbox, attempts, and candidates without confusing
+canonical authorship with generated operational state.
+
+## When to use
+
+Use in CI, before verify/archive, after doctor warnings, or when deciding candidates.
+
+## When not to use
+
+Do not hand-edit `SHARED_MEMORY.md` or `MEMORY_EVENTS.jsonl`. Do not repair a healthy legacy vault
+that merely awaits migration.
+
+## Prerequisites
+
+Pass the vault explicitly in automation. Preserve backups and evidence before repair.
+
+## Syntax
+
+```bash
+npx wendkeep memory status [--gate] --vault <vault>
+npx wendkeep memory repair --vault <vault>
+npx wendkeep memory reconcile <ambiguous-session> --by-session <successor-session> --reason <reason> [--apply] --vault <vault>
+npx wendkeep memory promote <candidate> --vault <vault>
+npx wendkeep memory reject <candidate> --vault <vault>
+npx wendkeep validate-memory [CORE-path]
+npx wendkeep validate-memory --vault <v2-vault>
+```
+
+## Options and exit codes
+
+- `memory status` is read-only; `--gate` exits `1` only for blocking state.
+- `Stop` writes events to the outbox before acknowledging `last_memory_attempt: enqueued`, then the
+  projector runs outside the registry lock. Retrying the same attempt reuses its frozen event IDs
+  and can project them at most once.
+- A busy/failed projector persists `degraded`, preserves the outbox, and reports replay. A later
+  Stop/retry reuses that attempt instead of rebuilding its handoff from new transient data.
+- The outcome updates `memory_status`/checkpoint only while activation, epoch, turn, and attempt
+  still match exactly. A stale/superseded result cannot clear or overwrite a newer checkpoint.
+- A valid legacy vault warns and exits `0`. For v2, status correlates `last_memory_attempt`,
+  disposition, outbox, ledger, SHARED, and checkpoint: an ambiguous attempt, lost publication, or
+  mismatched checkpoint blocks; `degraded` with an intact outbox is a warning.
+- `memory repair` is structural only: it uses PID/token-owned locks, writes a `.bak`, retains
+  valid events, and reprojects state. When it recognizes a valid pre-0.59 checkpoint whose cursor
+  is causal, it CAS-migrates it to the physical boundary with backup/audit; it never reclassifies
+  registry attempts or accepts a tuple that cannot be fully re-derived.
+- `memory reconcile` is a dry run by default. `--apply` requires two named sessions plus a reason,
+  CAS-checks the exact attempt, backs up the registry, and limits mutation to the ambiguous attempt
+  and its successor. Replay is CORE-aware, checkpoints use the physical ledger cursor, and the
+  command neither rewrites ledger/CORE/notes nor consumes the outbox. Retrying the same applied
+  decision is idempotent.
+- Every memory path validates the physical topology of `.brain`, ledger, outbox, CORE, SHARED,
+  candidates, registry, notes, backups, temporary files, and sidecars before reading or writing.
+  Junctions, symlinks, reparse points, or hardlinks fail closed without touching external bytes.
+  Locks publish owner and lease atomically, never reap a live PID by age alone, and release only
+  the lease they acquired.
+- `promote`/`reject` append auditable decisions and never rewrite the ledger in place.
+- `validate-memory <CORE.md>` checks the 25-line cap, required sections, and secrets.
+- `validate-memory --vault` requires a complete v2 bundle and is not the legacy-vault gate.
+
+## Examples
+
+```bash
+npx wendkeep memory status --gate --vault .MyApp-vault
+npx wendkeep memory reconcile old --by-session current --reason "delivery continued" --vault .MyApp-vault
+npx wendkeep memory reconcile old --by-session current --reason "delivery continued" --apply --vault .MyApp-vault
+npx wendkeep validate-memory .MyApp-vault/.brain/CORE.md
+npx wendkeep memory promote candidate-123 --vault .MyApp-vault
+```
+
+## Expected result
+
+Status prints schema, revision, cursor, hash, events, outbox, candidates, conflicts, and the causal
+state of the last attempt. CORE stays hand-curated and canonical; SHARED stays a verifiable
+operational projection. After successful projection, an attempt checkpoint may be a valid prefix
+of a global projection that has already advanced with concurrent events.
+
+## Common errors and diagnosis
+
+- `legacy`: follow the migration guide; this is not corruption.
+- `revision: 0` immediately after a valid migration, with no v2 attempt, is healthy; do not run
+  repair merely to manufacture the first event.
+- `degraded` with every event ID present in either the ledger or an intact outbox is recoverable;
+  let idempotent replay finish. An event ID absent from both locations means lost publication.
+- An `ambiguous` attempt, an `applied` attempt without event IDs, a `projected` event found only in
+  the outbox, or a mismatched checkpoint is blocking: preserve the artifacts and investigate
+  before repair. If the ambiguity is demonstrably superseded by a successor session, inspect the
+  `memory reconcile` dry run before authorizing `--apply`; the command fails when the ambiguous
+  attempt already contains event IDs.
+- Ordinary pending candidate: recoverable warning, requiring human choice when appropriate.
+- Missing `event_cursor` or mismatched v2 hash: preserve the bundle and assess `memory repair`.
+- `validate-memory --vault` fails on legacy: validate CORE only or migrate first.
+
+## Next steps
+
+Read [memory migration](memory-migration.md), [maintenance](maintenance-and-diagnostics.md), and
+[verify](verify.md).

package/docs/en/commands/notes-and-knowledge.md

@@ -0,0 +1,70 @@
+# Derived notes and knowledge graph
+
+**English** · [Português](../../pt-BR/commands/notes-and-knowledge.md)
+
+## Purpose
+
+Create, repair, number, and navigate decisions, bugs, and learnings while preserving provenance
+and wikilinks.
+
+## When to use
+
+Use to record durable knowledge or repair historical notes diagnosed by doctor.
+
+## When not to use
+
+Do not hand-edit numbering or wikilinks in bulk. Do not use `--apply` before reviewing the preview.
+
+## Prerequisites
+
+A bound vault, identifiable source session, and backup before broad renumbering.
+
+## Syntax
+
+```bash
+npx wendkeep dashboard [--force]
+npx wendkeep note new --type bug|learning "<title>"
+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 "<title>" "<lesson>"
+```
+
+## Options and exit codes
+
+- `note new` creates a monthly `BUG-NNNN` or `APR-NNNN` and accepts `--date`.
+- `note relink`, `repair-frontmatter`, `repair-sections`, and `renumber-*` default to dry-run;
+  `--apply` writes and `--json` supports audit.
+- `dashboard --force` regenerates Bases/MOC when required.
+- `lesson add` accepts `--change <slug>` and `--vault` to bind local learning.
+- Exit `0` means a consistent preview/application; non-zero makes incomplete repair explicit.
+
+## Examples
+
+```bash
+npx wendkeep note new --type bug "refresh expires during upload"
+npx wendkeep note relink --json
+npx wendkeep renumber-decisions --json
+# review before repeating with --apply
+npx wendkeep dashboard --force
+```
+
+## Expected result
+
+Derived notes live in the month folder, use global per-type numbering, and link back to the source
+session. Repairs preserve valid frontmatter and rewrite wikilinks when files move.
+
+## Common errors and diagnosis
+
+- Orphan note without a modal source: `note relink` reports it and does not invent provenance.
+- Stacked frontmatter: repair under the same lock used by hooks.
+- Grey links after renumber/archive: preview relink and inspect ambiguities.
+- Sensitive title: remove secrets/PII before persistence.
+
+## Next steps
+
+See [sessions and import](sessions-and-import.md), [costs and observability](costs-and-observability.md),
+and [maintenance](maintenance-and-diagnostics.md).