wendkeep 0.63.0 → 0.64.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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.64.0] — 2026-07-28
+
+### Added
+
+- **O workspace privado CLI passa a ter runtime canônico em `packages/cli/src/index.mjs`.** Help,
+  versão, seleção de Vault, apresentação de erros e dispatch lazy agora pertencem à fronteira
+  `@wendkeep/cli`, com import sem autoexecução.
+- **O tarball instalado prova a CLI fora do checkout.** A distribuição inclui o runtime novo e
+  exercita os aliases `wendkeep` e `wk` em um consumidor temporário, mantendo o pacote raiz como
+  a única unidade npm.
+
+### Changed
+
+- **`bin/wendkeep.mjs` agora é uma fachada executável fina.** O arquivo preserva o shebang e
+  apenas invoca `runCli()`, enquanto comandos, flags, help antes do Vault, streams, mensagens e
+  códigos de saída mantêm o comportamento anterior.
+- **A CLI programática permanece privada durante a migração.** Não há export raiz
+  `wendkeep/cli`; as superfícies públicas continuam sendo os binários, `wendkeep/harness` e
+  `wendkeep/vault`.
+
 ## [0.63.0] — 2026-07-28
 
 ### Added

package/README.en.md

@@ -16,13 +16,19 @@
 **Persistent memory for AI coding agents, built on your Obsidian vault.** Every Claude Code **and Codex** session is captured turn by turn into local Markdown — `init` wires both (Codex asks you to approve its hooks once; `import` backfills past sessions either way) — with token/cost tracking and automatically extracted decisions, bugs, and learnings. That always-on plane is **Keep Core**. On top of it, **Wend Runtime** provides a native, zero-dependency lifecycle (spec → change → TDD → sensor-gated archive), selected through the `OFF`, `FLOW`, `GUIDE`, `GOVERN`, and `ASSURE` Operating Profiles. 100% local, open-core.
 
 The runtime is being separated into six physical boundaries — `cli`, `harness`, `vault`, `mcp`,
-`integrations`, and `pi` — without fragmenting installation. The private `harness` and `vault`
-workspaces now canonically own Operating Profiles/the sensor engine and safe binding/the Shared
-Project Memory v2 kernel, respectively. The root package exposes those surfaces through
-`wendkeep/harness` and `wendkeep/vault`; historical imports keep working through compatibility
+`integrations`, and `pi` — without fragmenting installation. The private `cli`, `harness`, and
+`vault` workspaces now canonically own the executable runtime, Operating Profiles/the sensor
+engine, and safe binding/the Shared Project Memory v2 kernel, respectively. The root package
+exposes Harness and Vault through `wendkeep/harness` and `wendkeep/vault`; CLI remains public only
+through the `wendkeep`/`wk` binaries. Historical imports keep working through compatibility
 facades and no session data needs migration;
 see the [modular architecture](docs/en/architecture.md).
 
+In the **0.64 CLI Runtime** phase, `packages/cli/src/index.mjs` owns help, version reporting, Vault
+selection, error presentation, and lazy dispatch. `bin/wendkeep.mjs` is reduced to the shebang and
+a `runCli()` invocation. The tarball remains a single artifact and proves both aliases in an
+isolated consumer; there is no public `wendkeep/cli` subpath in this phase.
+
 In the **0.63 Harness FLOW Store** phase, `packages/vault/src/locale.mjs` becomes the canonical
 source for Vault locale and taxonomy, while `packages/harness/src/flow-store.mjs` becomes the
 canonical durable FLOW store. The historical `hooks/locale.mjs` and

package/README.md

@@ -16,13 +16,19 @@
 **Persistent memory for AI coding agents, built on your Obsidian vault.** Every Claude Code **and Codex** session is captured turn by turn into local Markdown — `init` wires both (Codex asks you to approve its hooks once; `import` backfills past sessions either way) — with token/cost tracking and automatically extracted decisions, bugs, and learnings. That always-on plane is **Keep Core**. On top of it, **Wend Runtime** provides a native, zero-dependency lifecycle (spec → change → TDD → sensor-gated archive), selected through the `OFF`, `FLOW`, `GUIDE`, `GOVERN`, and `ASSURE` Operating Profiles. 100% local, open-core.
 
 The runtime is being separated into six physical boundaries — `cli`, `harness`, `vault`, `mcp`,
-`integrations`, and `pi` — without fragmenting installation. The private `harness` and `vault`
-workspaces now canonically own Operating Profiles/the sensor engine and safe binding/the Shared
-Project Memory v2 kernel, respectively. The root package exposes those surfaces through
-`wendkeep/harness` and `wendkeep/vault`; historical imports keep working through compatibility
+`integrations`, and `pi` — without fragmenting installation. The private `cli`, `harness`, and
+`vault` workspaces now canonically own the executable runtime, Operating Profiles/the sensor
+engine, and safe binding/the Shared Project Memory v2 kernel, respectively. The root package
+exposes Harness and Vault through `wendkeep/harness` and `wendkeep/vault`; CLI remains public only
+through the `wendkeep`/`wk` binaries. Historical imports keep working through compatibility
 facades and no session data needs migration;
 see the [modular architecture](docs/en/architecture.md).
 
+In the **0.64 CLI Runtime** phase, `packages/cli/src/index.mjs` owns help, version reporting, Vault
+selection, error presentation, and lazy dispatch. `bin/wendkeep.mjs` is reduced to the shebang and
+a `runCli()` invocation. The tarball remains a single artifact and proves both aliases in an
+isolated consumer; there is no public `wendkeep/cli` subpath in this phase.
+
 In the **0.63 Harness FLOW Store** phase, `packages/vault/src/locale.mjs` becomes the canonical
 source for Vault locale and taxonomy, while `packages/harness/src/flow-store.mjs` becomes the
 canonical durable FLOW store. The historical `hooks/locale.mjs` and

package/bin/wendkeep.mjs

@@ -1,346 +1,4 @@
 #!/usr/bin/env node
-// wendkeep CLI — single entrypoint.
-//   wendkeep init [--vault <path>] [--project <path>] [--no-mcp] [--yes] [--force]
-//   wendkeep hook <name>      (invoked by the agent's settings.json; pipes stdin/stdout)
-//   wendkeep doctor [--vault <path>]
-//   wendkeep --version | --help
-import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { RUNNABLE_HOOKS } from '../src/taxonomy.mjs';
+import { runCli } from '../packages/cli/src/index.mjs';
 
-const here = dirname(fileURLToPath(import.meta.url));
-const pkgRoot = join(here, '..');
-const hooksDir = join(pkgRoot, 'hooks');
-
-function version() {
-  try {
-    return JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')).version;
-  } catch {
-    return '0.0.0';
-  }
-}
-
-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.
-    --no-companions        Skip companion plugins/MCP entirely.
-    --no-colors            Skip the Obsidian color system (.obsidian snippet + graph groups).
-    --dotcontext-mcp <v>   dotcontext MCP placement: auto (default; skip project entry
-                           if already global), project, or none.
-    --dotcontext-hooks <v> dotcontext hooks: full (default), light (no PostToolUse), none.
-    --yes, -y              Non-interactive; accept defaults.
-    --force                Overwrite existing wendkeep config blocks.
-
-  wendkeep hook <name>         Run a session hook (used by settings.json). Reads the
-                           agent's JSON on stdin. Names: ${RUNNABLE_HOOKS.join(', ')}.
-
-  wendkeep sync [--project P]  Run init -> sync-defs -> doctor on the CURRENT project, in one
-                           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 · --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 |
-                           status | done <id> | undone <id> | diff | archive [--force] | abandon | relink | backlink.
-                           archive exige verdict (rode verify --deep); abandon descarta sem ADR.
-                           backlink [--apply]: injeta o backlink pro proposta em design/tarefas/spec órfãos (open + _arquivo).
-  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.
-                           --since <date> · --top [N] (priciest) · --trend [day|week|month]
-                           (+ run-rate projection) · --write (generate 00-Custo.md) · --json.
-  wendkeep cost rebuild        Recalculate historical parent + subagent costs from SESSION_REGISTRY.
-                           Dry-run by default · --apply writes notes + .brain/COST_REBUILD.json
-                           · --session <id|file> · --limit N · --json.
-  wendkeep stats [--vault P]   One shareable line: sessions · prompts · spend · span · models (--json).
-  wendkeep import [opts]       Backfill: import this project's past Claude + Codex sessions into
-                           the vault (deduped by session_id). --source all|claude|codex (default
-                           all) · --stamp-ids (backfill session_id in existing notes) ·
-                           --rescan-decisions (capture prose decisions from already-imported transcripts) ·
-                           --from <dir> · --codex-from <dir> · --since <date> · --limit N ·
-                           --dry-run · --json.
-  wendkeep verify [--deep] [--change s]  Run a change's task sensors + record evidence (the gate);
-                           --deep assembles the verification package for the wk-verify pass.
-  wendkeep dashboard [--force]  (Re)generate the vault's folder-filtered Bases + 00-Dashboard MOC.
-  wendkeep renumber-decisions   Renumber 04-Decisões to ADR-<NNNN>-<slug> in chronological order,
-                           renaming files + rewriting every wikilink. Preview by default; --apply to
-                           write. --vault P · --json.
-  wendkeep renumber-bugs        Renumber 05-Bugs to BUG-<NNNN>-<slug> chronologically, moving notes
-                           out of legacy "DIA N" subfolders into the month folder and rewriting
-                           wikilinks. Preview by default; --apply · --vault P · --json.
-  wendkeep renumber-learnings   Same for 06-Aprendizados/06-Learnings with APR-<NNNN>-<slug>.
-  wendkeep note new --type bug|learning "<título>"  Create a numbered derived note (BUG-/APR-NNNN)
-                           in the month folder and print its vault path. --date YYYY-MM-DD · --vault P.
-  wendkeep note relink [--apply]  Backfill orphan derived notes (BUG/APR without a source session),
-                           linking each to the modal source session of its type/month cohort. Dry-run
-                           by default; --apply writes; skips notes with no sibling to infer from.
-  wendkeep note repair-frontmatter [--apply]  Merge stacked frontmatter blocks in session notes
-                           (damage from pre-lock concurrent writes) into a single block: base keys
-                           from the original block, values from the newest. Dry-run by default;
-                           --apply writes under the same lock as the hooks · --json.
-  wendkeep note repair-sections [--apply]  Rebuild the derived sections (decisions/bugs/learnings)
-                           in session notes from the linked derived notes — the body used to lag
-                           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.
-  wendkeep sync-defs [opts]    Copy versioned defs from the vault's .brain into the
-                           project: .brain/agents/*.toml -> .codex/agents,
-                           .brain/skills/<name> -> .claude/skills + .agents/skills. --vault P --project P.
-                           --reseed re-semeia as skills wk-* com os seeds da versão instalada
-                           (sobrescreve edições manuais nas wk-*) antes de copiar.
-                           --check detecta drift sem modificar arquivos.
-  wendkeep --version           Print version.
-  wendkeep --help              Show this help.
-`;
-
-function runHook(name) {
-  if (!name) {
-    process.stderr.write('wendkeep hook: missing hook name\n');
-    process.exit(2);
-  }
-  if (!RUNNABLE_HOOKS.includes(name)) {
-    process.stderr.write(`wendkeep hook: unknown hook "${name}". Known: ${RUNNABLE_HOOKS.join(', ')}\n`);
-    process.exit(2);
-  }
-  const file = join(hooksDir, `${name}.mjs`);
-  if (!existsSync(file)) {
-    process.stderr.write(`wendkeep hook: hook file not found: ${file}\n`);
-    process.exit(2);
-  }
-  // Spawn exactly as the agent would run `node <hook>.mjs`: stdio inherited so the
-  // hook's stdin (agent JSON) and stdout (hookSpecificOutput) pass through untouched.
-  const r = spawnSync(process.execPath, [file], { stdio: 'inherit' });
-  process.exit(r.status ?? 0);
-}
-
-function optionValue(argv, name) {
-  const index = argv.indexOf(name);
-  if (index >= 0) return argv[index + 1] || '';
-  return argv.find((item) => item.startsWith(`${name}=`))?.slice(name.length + 1) || '';
-}
-
-async function preferProjectVault(argv) {
-  // Existing command modules still consume OBSIDIAN_VAULT_PATH internally. Populate it
-  // only inside this CLI process from the provider-neutral project binding, overriding
-  // any inherited machine-global value. An explicit --vault remains authoritative.
-  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 (error) {
-    // Backward-compatible manual CLI behavior: individual commands still explain
-    // --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;
-  }
-}
-
-async function main() {
-  const [cmd, ...rest] = process.argv.slice(2);
-  // Universal --help: any subcommand with --help/-h prints usage and never executes.
-  // 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'))) {
-    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);
-  }
-  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) {
-    case 'init': {
-      const { runInit } = await import('../src/init.mjs');
-      await runInit(rest);
-      break;
-    }
-    case 'hook':
-      runHook(rest[0]);
-      break;
-    case 'doctor': {
-      const { runDoctor } = await import('../src/doctor.mjs');
-      process.exit(runDoctor(rest));
-      break;
-    }
-    case 'sync': {
-      const { runSync } = await import('../src/sync.mjs');
-      process.exit(await runSync(rest));
-      break;
-    }
-    case 'validate-memory': {
-      if (rest.includes('--vault') || rest.some((item) => item.startsWith('--vault='))) {
-        const { runValidateMemoryBundle } = await import('../src/memory.mjs');
-        runValidateMemoryBundle(rest);
-      } else {
-        const { runValidateMemory } = await import('../src/validate-core.mjs');
-        runValidateMemory(rest);
-      }
-      break;
-    }
-    case 'memory': {
-      const { runMemory } = await import('../src/memory.mjs');
-      runMemory(rest);
-      break;
-    }
-    case 'sync-defs': {
-      const { runSyncDefs } = await import('../src/sync-defs.mjs');
-      process.exit(runSyncDefs(rest));
-      break;
-    }
-    case 'change': {
-      const { runChange } = await import('../src/change.mjs');
-      runChange(rest);
-      break;
-    }
-    case 'session': {
-      const { runSession } = await import('../src/session.mjs');
-      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);
-      break;
-    }
-    case 'verify': {
-      const { runVerify } = await import('../src/verify.mjs');
-      runVerify(rest);
-      break;
-    }
-    case 'lesson': {
-      const { runLesson } = await import('../src/lessons.mjs');
-      runLesson(rest);
-      break;
-    }
-    case 'spec': {
-      const { runSpec } = await import('../src/spec.mjs');
-      runSpec(rest);
-      break;
-    }
-    case 'sensors': {
-      const { runSensors } = await import('../src/sensors.mjs');
-      runSensors(rest);
-      break;
-    }
-    case 'cost': {
-      const { runCost } = await import('../src/cost.mjs');
-      runCost(rest);
-      break;
-    }
-    case 'stats': {
-      const { runStats } = await import('../src/stats.mjs');
-      runStats(rest);
-      break;
-    }
-    case 'import': {
-      const { runImportCli } = await import('../src/import.mjs');
-      runImportCli(rest);
-      break;
-    }
-    case 'dashboard': {
-      const { runDashboard } = await import('../src/vault-views.mjs');
-      runDashboard(rest);
-      break;
-    }
-    case 'renumber-decisions': {
-      const { runRenumberDecisions } = await import('../src/renumber.mjs');
-      runRenumberDecisions(rest);
-      break;
-    }
-    case 'renumber-bugs': {
-      const { runRenumberBugs } = await import('../src/renumber.mjs');
-      runRenumberBugs(rest);
-      break;
-    }
-    case 'renumber-learnings': {
-      const { runRenumberLearnings } = await import('../src/renumber.mjs');
-      runRenumberLearnings(rest);
-      break;
-    }
-    case 'note': {
-      const { runNote } = await import('../src/note.mjs');
-      runNote(rest);
-      break;
-    }
-    case '--version':
-    case '-v':
-      process.stdout.write(`${version()}\n`);
-      break;
-    case undefined:
-    case '--help':
-    case '-h':
-    case 'help':
-      process.stdout.write(HELP);
-      break;
-    default:
-      process.stderr.write(`wendkeep: unknown command "${cmd}"\n\n${HELP}`);
-      process.exit(2);
-  }
-}
-
-main().catch((err) => {
-  process.stderr.write(`wendkeep: ${err?.stack || err}\n`);
-  process.exit(1);
-});
+await runCli();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.63.0",
+  "version": "0.64.0",
   "description": "Vault-first persistent memory for AI coding agents, with an optional profile-aware governance runtime: OFF, FLOW, GUIDE, GOVERN, or ASSURE. Local-first and agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "workspaces": [
@@ -31,7 +31,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "check": "node --check bin/wendkeep.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/project-vault.mjs && node --check src/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.mjs && node --check hooks/operating-profile-runtime.mjs && node --check hooks/flow-core.mjs && node --check hooks/flow-protected-policy.mjs && node --check hooks/git-snapshot.mjs && node --check hooks/vault-path-safety.mjs && node --check hooks/vault-runtime-store.mjs && node --check packages/harness/src/index.mjs && node --check packages/harness/src/flow-store.mjs && node --check packages/harness/src/operating-profile.mjs && node --check packages/harness/src/sensors-core.mjs && node --check packages/vault/src/index.mjs && node --check packages/vault/src/project-vault.mjs && node --check packages/vault/src/vault-path-safety.mjs && node --check packages/vault/src/locale.mjs && node --check packages/vault/src/memory-schema.mjs && node --check packages/vault/src/memory-mode.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/vault/src/memory-store.mjs && node --check packages/vault/src/validate-core.mjs && node --check packages/vault/src/validate-memory.mjs",
+    "check": "node --check bin/wendkeep.mjs && node --check packages/cli/src/index.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/project-vault.mjs && node --check src/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.mjs && node --check hooks/operating-profile-runtime.mjs && node --check hooks/flow-core.mjs && node --check hooks/flow-protected-policy.mjs && node --check hooks/git-snapshot.mjs && node --check hooks/vault-path-safety.mjs && node --check hooks/vault-runtime-store.mjs && node --check packages/harness/src/index.mjs && node --check packages/harness/src/flow-store.mjs && node --check packages/harness/src/operating-profile.mjs && node --check packages/harness/src/sensors-core.mjs && node --check packages/vault/src/index.mjs && node --check packages/vault/src/project-vault.mjs && node --check packages/vault/src/vault-path-safety.mjs && node --check packages/vault/src/locale.mjs && node --check packages/vault/src/memory-schema.mjs && node --check packages/vault/src/memory-mode.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/vault/src/memory-store.mjs && node --check packages/vault/src/validate-core.mjs && node --check packages/vault/src/validate-memory.mjs",
     "test": "node --test",
     "release": "node scripts/release.mjs",
     "release:dry": "node scripts/release.mjs --dry-run",

package/packages/cli/package.json

@@ -1,5 +1,6 @@
 {
   "name": "@wendkeep/cli",
   "private": true,
-  "type": "module"
+  "type": "module",
+  "exports": "./src/index.mjs"
 }

package/packages/cli/src/index.mjs

@@ -0,0 +1,349 @@
+// wendkeep CLI — canonical private runtime.
+//   wendkeep init [--vault <path>] [--project <path>] [--no-mcp] [--yes] [--force]
+//   wendkeep hook <name>      (invoked by the agent's settings.json; pipes stdin/stdout)
+//   wendkeep doctor [--vault <path>]
+//   wendkeep --version | --help
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RUNNABLE_HOOKS } from '../../../src/taxonomy.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(here, '..', '..', '..');
+const hooksDir = join(pkgRoot, 'hooks');
+
+function version() {
+  try {
+    return JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+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.
+    --no-companions        Skip companion plugins/MCP entirely.
+    --no-colors            Skip the Obsidian color system (.obsidian snippet + graph groups).
+    --dotcontext-mcp <v>   dotcontext MCP placement: auto (default; skip project entry
+                           if already global), project, or none.
+    --dotcontext-hooks <v> dotcontext hooks: full (default), light (no PostToolUse), none.
+    --yes, -y              Non-interactive; accept defaults.
+    --force                Overwrite existing wendkeep config blocks.
+
+  wendkeep hook <name>         Run a session hook (used by settings.json). Reads the
+                           agent's JSON on stdin. Names: ${RUNNABLE_HOOKS.join(', ')}.
+
+  wendkeep sync [--project P]  Run init -> sync-defs -> doctor on the CURRENT project, in one
+                           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 · --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 |
+                           status | done <id> | undone <id> | diff | archive [--force] | abandon | relink | backlink.
+                           archive exige verdict (rode verify --deep); abandon descarta sem ADR.
+                           backlink [--apply]: injeta o backlink pro proposta em design/tarefas/spec órfãos (open + _arquivo).
+  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.
+                           --since <date> · --top [N] (priciest) · --trend [day|week|month]
+                           (+ run-rate projection) · --write (generate 00-Custo.md) · --json.
+  wendkeep cost rebuild        Recalculate historical parent + subagent costs from SESSION_REGISTRY.
+                           Dry-run by default · --apply writes notes + .brain/COST_REBUILD.json
+                           · --session <id|file> · --limit N · --json.
+  wendkeep stats [--vault P]   One shareable line: sessions · prompts · spend · span · models (--json).
+  wendkeep import [opts]       Backfill: import this project's past Claude + Codex sessions into
+                           the vault (deduped by session_id). --source all|claude|codex (default
+                           all) · --stamp-ids (backfill session_id in existing notes) ·
+                           --rescan-decisions (capture prose decisions from already-imported transcripts) ·
+                           --from <dir> · --codex-from <dir> · --since <date> · --limit N ·
+                           --dry-run · --json.
+  wendkeep verify [--deep] [--change s]  Run a change's task sensors + record evidence (the gate);
+                           --deep assembles the verification package for the wk-verify pass.
+  wendkeep dashboard [--force]  (Re)generate the vault's folder-filtered Bases + 00-Dashboard MOC.
+  wendkeep renumber-decisions   Renumber 04-Decisões to ADR-<NNNN>-<slug> in chronological order,
+                           renaming files + rewriting every wikilink. Preview by default; --apply to
+                           write. --vault P · --json.
+  wendkeep renumber-bugs        Renumber 05-Bugs to BUG-<NNNN>-<slug> chronologically, moving notes
+                           out of legacy "DIA N" subfolders into the month folder and rewriting
+                           wikilinks. Preview by default; --apply · --vault P · --json.
+  wendkeep renumber-learnings   Same for 06-Aprendizados/06-Learnings with APR-<NNNN>-<slug>.
+  wendkeep note new --type bug|learning "<título>"  Create a numbered derived note (BUG-/APR-NNNN)
+                           in the month folder and print its vault path. --date YYYY-MM-DD · --vault P.
+  wendkeep note relink [--apply]  Backfill orphan derived notes (BUG/APR without a source session),
+                           linking each to the modal source session of its type/month cohort. Dry-run
+                           by default; --apply writes; skips notes with no sibling to infer from.
+  wendkeep note repair-frontmatter [--apply]  Merge stacked frontmatter blocks in session notes
+                           (damage from pre-lock concurrent writes) into a single block: base keys
+                           from the original block, values from the newest. Dry-run by default;
+                           --apply writes under the same lock as the hooks · --json.
+  wendkeep note repair-sections [--apply]  Rebuild the derived sections (decisions/bugs/learnings)
+                           in session notes from the linked derived notes — the body used to lag
+                           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.
+  wendkeep sync-defs [opts]    Copy versioned defs from the vault's .brain into the
+                           project: .brain/agents/*.toml -> .codex/agents,
+                           .brain/skills/<name> -> .claude/skills + .agents/skills. --vault P --project P.
+                           --reseed re-semeia as skills wk-* com os seeds da versão instalada
+                           (sobrescreve edições manuais nas wk-*) antes de copiar.
+                           --check detecta drift sem modificar arquivos.
+  wendkeep --version           Print version.
+  wendkeep --help              Show this help.
+`;
+
+function runHook(name) {
+  if (!name) {
+    process.stderr.write('wendkeep hook: missing hook name\n');
+    process.exit(2);
+  }
+  if (!RUNNABLE_HOOKS.includes(name)) {
+    process.stderr.write(`wendkeep hook: unknown hook "${name}". Known: ${RUNNABLE_HOOKS.join(', ')}\n`);
+    process.exit(2);
+  }
+  const file = join(hooksDir, `${name}.mjs`);
+  if (!existsSync(file)) {
+    process.stderr.write(`wendkeep hook: hook file not found: ${file}\n`);
+    process.exit(2);
+  }
+  // Spawn exactly as the agent would run `node <hook>.mjs`: stdio inherited so the
+  // hook's stdin (agent JSON) and stdout (hookSpecificOutput) pass through untouched.
+  const r = spawnSync(process.execPath, [file], { stdio: 'inherit' });
+  process.exit(r.status ?? 0);
+}
+
+function optionValue(argv, name) {
+  const index = argv.indexOf(name);
+  if (index >= 0) return argv[index + 1] || '';
+  return argv.find((item) => item.startsWith(`${name}=`))?.slice(name.length + 1) || '';
+}
+
+async function preferProjectVault(argv) {
+  // Existing command modules still consume OBSIDIAN_VAULT_PATH internally. Populate it
+  // only inside this CLI process from the provider-neutral project binding, overriding
+  // any inherited machine-global value. An explicit --vault remains authoritative.
+  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 (error) {
+    // Backward-compatible manual CLI behavior: individual commands still explain
+    // --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;
+  }
+}
+
+async function main(argv) {
+  const [cmd, ...rest] = argv;
+  // Universal --help: any subcommand with --help/-h prints usage and never executes.
+  // 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'))) {
+    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);
+  }
+  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) {
+    case 'init': {
+      const { runInit } = await import('../../../src/init.mjs');
+      await runInit(rest);
+      break;
+    }
+    case 'hook':
+      runHook(rest[0]);
+      break;
+    case 'doctor': {
+      const { runDoctor } = await import('../../../src/doctor.mjs');
+      process.exit(runDoctor(rest));
+      break;
+    }
+    case 'sync': {
+      const { runSync } = await import('../../../src/sync.mjs');
+      process.exit(await runSync(rest));
+      break;
+    }
+    case 'validate-memory': {
+      if (rest.includes('--vault') || rest.some((item) => item.startsWith('--vault='))) {
+        const { runValidateMemoryBundle } = await import('../../../src/memory.mjs');
+        runValidateMemoryBundle(rest);
+      } else {
+        const { runValidateMemory } = await import('../../../src/validate-core.mjs');
+        runValidateMemory(rest);
+      }
+      break;
+    }
+    case 'memory': {
+      const { runMemory } = await import('../../../src/memory.mjs');
+      runMemory(rest);
+      break;
+    }
+    case 'sync-defs': {
+      const { runSyncDefs } = await import('../../../src/sync-defs.mjs');
+      process.exit(runSyncDefs(rest));
+      break;
+    }
+    case 'change': {
+      const { runChange } = await import('../../../src/change.mjs');
+      runChange(rest);
+      break;
+    }
+    case 'session': {
+      const { runSession } = await import('../../../src/session.mjs');
+      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);
+      break;
+    }
+    case 'verify': {
+      const { runVerify } = await import('../../../src/verify.mjs');
+      runVerify(rest);
+      break;
+    }
+    case 'lesson': {
+      const { runLesson } = await import('../../../src/lessons.mjs');
+      runLesson(rest);
+      break;
+    }
+    case 'spec': {
+      const { runSpec } = await import('../../../src/spec.mjs');
+      runSpec(rest);
+      break;
+    }
+    case 'sensors': {
+      const { runSensors } = await import('../../../src/sensors.mjs');
+      runSensors(rest);
+      break;
+    }
+    case 'cost': {
+      const { runCost } = await import('../../../src/cost.mjs');
+      runCost(rest);
+      break;
+    }
+    case 'stats': {
+      const { runStats } = await import('../../../src/stats.mjs');
+      runStats(rest);
+      break;
+    }
+    case 'import': {
+      const { runImportCli } = await import('../../../src/import.mjs');
+      runImportCli(rest);
+      break;
+    }
+    case 'dashboard': {
+      const { runDashboard } = await import('../../../src/vault-views.mjs');
+      runDashboard(rest);
+      break;
+    }
+    case 'renumber-decisions': {
+      const { runRenumberDecisions } = await import('../../../src/renumber.mjs');
+      runRenumberDecisions(rest);
+      break;
+    }
+    case 'renumber-bugs': {
+      const { runRenumberBugs } = await import('../../../src/renumber.mjs');
+      runRenumberBugs(rest);
+      break;
+    }
+    case 'renumber-learnings': {
+      const { runRenumberLearnings } = await import('../../../src/renumber.mjs');
+      runRenumberLearnings(rest);
+      break;
+    }
+    case 'note': {
+      const { runNote } = await import('../../../src/note.mjs');
+      runNote(rest);
+      break;
+    }
+    case '--version':
+    case '-v':
+      process.stdout.write(`${version()}\n`);
+      break;
+    case undefined:
+    case '--help':
+    case '-h':
+    case 'help':
+      process.stdout.write(HELP);
+      break;
+    default:
+      process.stderr.write(`wendkeep: unknown command "${cmd}"\n\n${HELP}`);
+      process.exit(2);
+  }
+}
+
+export async function runCli(argv = process.argv.slice(2)) {
+  try {
+    await main(argv);
+  } catch (err) {
+    process.stderr.write(`wendkeep: ${err?.stack || err}\n`);
+    process.exit(1);
+  }
+}