wendkeep 0.64.0 → 0.65.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.65.0] — 2026-07-29
+
+### Added
+
+- **O workspace privado MCP passa a ter um kernel canônico de configuração.**
+  `packages/mcp/src/config.mjs` concentra a entrada do MCPVault, a seleção de servidores por
+  descritores e o merge imutável de `.mcp.json`, sem efeitos no import.
+- **O tarball instalado prova a composição MCP fora do checkout.** O teste executa `init` em um
+  consumidor temporário, confirma a preservação de configuração existente e rejeita exports
+  públicos prematuros como `wendkeep/mcp` e `@wendkeep/mcp`.
+
+### Changed
+
+- **Taxonomia e instalador agora delegam ao kernel MCP.** `src/taxonomy.mjs` fornece descritores
+  como dados e preserva a identidade dos exports históricos; `src/init.mjs` mantém a orquestração
+  do filesystem e o comportamento de reconciliação, inclusive `.mcp.json.new` para JSON inválido.
+- **A publicação continua unificada e compatível.** Não há servidor MCP nativo, subpath público ou
+  pacote npm separado nesta fase; comandos, flags, transporte MCPVault e arquivos existentes
+  preservam o comportamento anterior.
+
 ## [0.64.0] — 2026-07-28
 
 ### Added

package/README.en.md

@@ -16,14 +16,22 @@
 **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 `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;
+`integrations`, and `pi` — without fragmenting installation. The private `cli`, `harness`,
+`vault`, and `mcp` workspaces now canonically own the executable runtime, Operating Profiles/the
+sensor engine, safe binding/the Shared Project Memory v2 kernel, and the MCP configuration kernel,
+respectively. The root package exposes Harness and Vault through `wendkeep/harness` and
+`wendkeep/vault`; CLI and MCP remain private surfaces, reached only through the binaries and the
+configuration effects of `init`. Historical imports keep working through compatibility facades
+and no session data needs migration;
 see the [modular architecture](docs/en/architecture.md).
 
+In the **0.65 MCP Configuration Kernel** phase, `packages/mcp/src/config.mjs` becomes the
+canonical authority for the MCPVault entry, catalog-described server selection, and `.mcp.json`
+merging. `src/taxonomy.mjs` supplies descriptors while `src/init.mjs` retains only filesystem
+orchestration. Existing keys and servers remain preserved; invalid JSON stays byte-for-byte intact
+and the reconciled proposal is written to `.mcp.json.new`. The workspace remains private, with no
+public `wendkeep/mcp` subpath or separate npm package.
+
 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

package/README.md

@@ -16,14 +16,22 @@
 **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 `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;
+`integrations`, and `pi` — without fragmenting installation. The private `cli`, `harness`,
+`vault`, and `mcp` workspaces now canonically own the executable runtime, Operating Profiles/the
+sensor engine, safe binding/the Shared Project Memory v2 kernel, and the MCP configuration kernel,
+respectively. The root package exposes Harness and Vault through `wendkeep/harness` and
+`wendkeep/vault`; CLI and MCP remain private surfaces, reached only through the binaries and the
+configuration effects of `init`. Historical imports keep working through compatibility facades
+and no session data needs migration;
 see the [modular architecture](docs/en/architecture.md).
 
+In the **0.65 MCP Configuration Kernel** phase, `packages/mcp/src/config.mjs` becomes the
+canonical authority for the MCPVault entry, catalog-described server selection, and `.mcp.json`
+merging. `src/taxonomy.mjs` supplies descriptors while `src/init.mjs` retains only filesystem
+orchestration. Existing keys and servers remain preserved; invalid JSON stays byte-for-byte intact
+and the reconciled proposal is written to `.mcp.json.new`. The workspace remains private, with no
+public `wendkeep/mcp` subpath or separate npm package.
+
 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

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

@@ -73,6 +73,11 @@ pnpm exec wendkeep sync --yes
 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.
 
+When MCP is enabled, `init` preserves existing properties and servers in `.mcp.json` and adds
+`wendkeep-vault`. If the existing JSON is invalid, the original file remains byte-for-byte intact
+and the reconciled proposal is written to `.mcp.json.new`. Since version 0.65, this composition is
+owned by the private MCP kernel without changing commands, flags, or the public npm surface.
+
 ## Common errors and diagnosis
 
 - Wrong vault: inspect `.wendkeep.json` and run `wendkeep doctor --vault <path>`.

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

@@ -74,6 +74,11 @@ O projeto recebe `.wendkeep.json`, hooks gerenciados de Claude/Codex, definiçõ
 cofre inicializado. Arquivos preexistentes são mesclados ou preservados; o comando informa o
 cofre efetivamente selecionado.
 
+Quando MCP está habilitado, o `init` preserva propriedades e servidores existentes em `.mcp.json`
+e adiciona `wendkeep-vault`. Se o JSON existente for inválido, o arquivo original permanece byte
+a byte intacto e a proposta reconciliada é gravada em `.mcp.json.new`. Desde a versão 0.65, essa
+composição pertence ao kernel MCP privado, sem alterar comandos, flags ou a superfície npm pública.
+
 ## Erros comuns e diagnóstico
 
 - Cofre errado: confira `.wendkeep.json` e rode `wendkeep doctor --vault <path>`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.64.0",
+  "version": "0.65.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 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",
+    "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/mcp/src/config.mjs && node --check packages/mcp/src/index.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/mcp/package.json

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

package/packages/mcp/src/config.mjs

@@ -0,0 +1,33 @@
+export const MCP_SERVER_KEY = 'wendkeep-vault';
+
+export function mcpServerEntry(vaultPath) {
+  return {
+    type: 'stdio',
+    command: 'npx',
+    args: ['-y', '@bitbonsai/mcpvault@latest', vaultPath],
+  };
+}
+
+export function selectMcpServers(descriptors, skipIds = []) {
+  const skipSet = new Set(skipIds);
+  const servers = {};
+  for (const descriptor of descriptors || []) {
+    if (!descriptor || skipSet.has(descriptor.id)) continue;
+    if (typeof descriptor.key !== 'string' || !descriptor.key) continue;
+    if (!descriptor.entry || typeof descriptor.entry !== 'object') continue;
+    servers[descriptor.key] = descriptor.entry;
+  }
+  return servers;
+}
+
+export function mergeMcpConfig(existing, {
+  vaultPath,
+  withVault = true,
+  servers = {},
+} = {}) {
+  const config = existing && typeof existing === 'object' ? { ...existing } : {};
+  config.mcpServers = { ...(config.mcpServers || {}) };
+  if (withVault) config.mcpServers[MCP_SERVER_KEY] = mcpServerEntry(vaultPath);
+  Object.assign(config.mcpServers, servers);
+  return config;
+}

package/packages/mcp/src/index.mjs

@@ -0,0 +1 @@
+export * from './config.mjs';

package/src/init.mjs

@@ -6,13 +6,12 @@ import { spawnSync } from 'node:child_process';
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { basename, isAbsolute, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
+import { MCP_SERVER_KEY, mergeMcpConfig } from '../packages/mcp/src/index.mjs';
 import {
   VAULT_FOLDERS,
   SESSION_HOOKS,
   CHANGE_NUDGE_HOOKS,
   CHANGE_GATE_HOOKS,
-  MCP_SERVER_KEY,
-  mcpServerEntry,
   hookCommand,
   hookCommandLocal,
   hookCommandLocalLegacy,
@@ -245,11 +244,11 @@ export function mergeCodexHooks(existing, { force = false } = {}) {
 }
 
 export function mergeMcp(existing, { vaultPath, withVault = true, companions = [], skipMcp = [] }) {
-  const m = existing && typeof existing === 'object' ? { ...existing } : {};
-  m.mcpServers = { ...(m.mcpServers || {}) };
-  if (withVault) m.mcpServers[MCP_SERVER_KEY] = mcpServerEntry(vaultPath);
-  Object.assign(m.mcpServers, companionMcpPatch(companions, skipMcp));
-  return m;
+  return mergeMcpConfig(existing, {
+    vaultPath,
+    withVault,
+    servers: companionMcpPatch(companions, skipMcp),
+  });
 }
 
 // Run caveman's cross-agent installer (non-Claude skill coverage). Downloads the

package/src/taxonomy.mjs

@@ -1,3 +1,11 @@
+import {
+  MCP_SERVER_KEY,
+  mcpServerEntry,
+  selectMcpServers,
+} from '../packages/mcp/src/index.mjs';
+
+export { MCP_SERVER_KEY, mcpServerEntry };
+
 // Shared, data-only constants for the wendkeep installer and CLI.
 // Kept free of side effects so both bin/ and src/ can import it cheaply.
 
@@ -93,17 +101,6 @@ export const RUNNABLE_HOOKS = [
   'plan-capture',
 ];
 
-// The MCP server entry wendkeep wires into .mcp.json so the agent can read/write the
-// vault. Uses the published mcpvault server (no secrets).
-export function mcpServerEntry(vaultPath) {
-  return {
-    type: 'stdio',
-    command: 'npx',
-    args: ['-y', '@bitbonsai/mcpvault@latest', vaultPath],
-  };
-}
-export const MCP_SERVER_KEY = 'wendkeep-vault';
-
 // The three Claude Code session hooks, expressed as `wendkeep hook <name>` so the
 // installed package is the single source of truth (update with `npm update wendkeep`,
 // no re-copying). Returned as a spec the merge logic folds into settings.json.
@@ -281,14 +278,11 @@ export function companionSettingsPatch(ids) {
 // `skip` omits ids whose MCP is already configured elsewhere (e.g. dotcontext set
 // globally in ~/.claude.json — avoids a duplicate project-scoped server).
 export function companionMcpPatch(ids, skip = []) {
-  const skipSet = new Set(skip);
-  const servers = {};
-  for (const id of ids) {
-    if (skipSet.has(id)) continue;
-    const c = COMPANION_BY_ID[id];
-    if (c?.mcp) servers[c.mcp.key] = c.mcp.entry;
-  }
-  return servers;
+  const descriptors = ids.map((id) => {
+    const mcp = COMPANION_BY_ID[id]?.mcp;
+    return mcp ? { id, key: mcp.key, entry: mcp.entry } : { id };
+  });
+  return selectMcpServers(descriptors, skip);
 }
 
 // SessionStart hook specs wendkeep must author for companions that lack a native