wendkeep 0.1.0 → 0.2.1

package/README.md

@@ -35,12 +35,15 @@ npx wendkeep init
 
 `wendkeep init` is interactive and **idempotent**. It will:
 
-1. Create the vault folder taxonomy (default vault: `<project>/.wendkeep-vault`, override with `--vault`).
+1. Create the vault folder taxonomy and a templated `README.md` (default vault: `<project>/.<project-name>-vault`, e.g. `.MyApp-vault`; override with `--vault`).
 2. **Merge** the three session hooks and `OBSIDIAN_VAULT_PATH` into `.claude/settings.json` — without clobbering your existing settings (a `.bak` is saved; an unparseable file is left untouched and a `.new` is written for you to merge).
 3. Add the `wendkeep-vault` MCP server to `.mcp.json` (skip with `--no-mcp`).
+4. Offer to pin **companion** plugins/MCP (multi-choice; `context-mode` pre-checked). Each is wired through the most agent-agnostic path it supports — `context-mode` as an `.mcp.json` MCP server (any agent), `understand-anything` via a `understand-inject` SessionStart hook that injects its domain graph when generated, and the Claude Code plugin layer (`extraKnownMarketplaces` + `enabledPlugins`) as a bonus. Control with `--companions <csv>` or `--no-companions`. (`caveman` additionally runs its own cross-agent installer on non-Claude agents.)
 
 ```bash
-npx wendkeep init --vault "~/vaults/work" --project . --yes   # non-interactive
+npx wendkeep init --vault "~/vaults/work" --project . --yes   # non-interactive (companions: context-mode)
+npx wendkeep init --companions "context-mode,caveman" --yes
+npx wendkeep init --no-companions --yes
 ```
 
 Then open the vault in Obsidian, send a test prompt in your agent, and confirm a note appears under `02-Sessões/…`.

package/bin/wendkeep.mjs

@@ -26,9 +26,12 @@ const HELP = `wendkeep ${version()} — capture AI coding agent sessions into yo
 
 Usage:
   wendkeep init [options]      Set up wendkeep in a project (cross-platform).
-    --vault <path>         Obsidian vault folder (default: <project>/.wendkeep-vault).
+    --vault <path>         Obsidian vault folder (default: <project>/.<project-name>-vault).
     --project <path>       Project root to wire (default: current directory).
     --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 when interactive/--yes: context-mode).
+    --no-companions        Skip companion plugins/MCP entirely.
     --yes, -y              Non-interactive; accept defaults.
     --force                Overwrite existing wendkeep config blocks.
 

package/hooks/obsidian-common.mjs

@@ -30,8 +30,48 @@ export function writeHookOutput(payload = {}) {
   process.stdout.write(JSON.stringify(payload));
 }
 
+// Resolve the vault and report WHERE the path came from, so callers can react to
+// an unconfigured install instead of silently writing to the home fallback.
+//   env     -> OBSIDIAN_VAULT_PATH (set by `wendkeep init`)
+//   payload -> obsidian_vault_path from the hook's JSON input
+//   default -> DEFAULT_VAULT_BASE (~/wendkeep-vault) — a phantom vault nobody opened
+export function resolveVault(input = {}) {
+  if (process.env.OBSIDIAN_VAULT_PATH) {
+    return { base: process.env.OBSIDIAN_VAULT_PATH, source: 'env' };
+  }
+  if (input && input.obsidian_vault_path) {
+    return { base: input.obsidian_vault_path, source: 'payload' };
+  }
+  return { base: DEFAULT_VAULT_BASE, source: 'default' };
+}
+
 export function getVaultBase(input = {}) {
-  return process.env.OBSIDIAN_VAULT_PATH || input.obsidian_vault_path || DEFAULT_VAULT_BASE;
+  return resolveVault(input).base;
+}
+
+// Diagnostic logger. No-op unless WENDKEEP_DEBUG is set, so it never pollutes the
+// stdout hook contract during normal runs but makes fail-open paths debuggable.
+export function debugLog(...args) {
+  if (!process.env.WENDKEEP_DEBUG) return;
+  const text = args
+    .map((a) => (a && a.stack ? a.stack : String(a)))
+    .join(' ');
+  process.stderr.write(`[wendkeep] ${text}\n`);
+}
+
+// Warn loudly (stderr) when the vault resolved to the home fallback — i.e. neither
+// OBSIDIAN_VAULT_PATH nor a payload path was provided. Without this the hooks write
+// notes into ~/wendkeep-vault with zero signal that the install is misconfigured.
+// Returns the resolution source so callers can branch if they want.
+export function warnIfDefaultVault(input = {}) {
+  const { base, source } = resolveVault(input);
+  if (source === 'default') {
+    process.stderr.write(
+      `[wendkeep] WARNING: OBSIDIAN_VAULT_PATH não definido — gravando no fallback "${base}". ` +
+        'Rode `wendkeep init` ou defina OBSIDIAN_VAULT_PATH apontando ao seu vault Obsidian.\n',
+    );
+  }
+  return source;
 }
 
 // Detecta o agente real que está executando o hook. Claude Code expõe

package/hooks/session-ensure.mjs

@@ -9,6 +9,8 @@ import {
   formatLocalIso,
   formatTime,
   getVaultBase,
+  warnIfDefaultVault,
+  debugLog,
   readControl,
   readHookInput,
   readSessionRegistry,
@@ -298,6 +300,7 @@ function outputActiveContext({ relPath, startedAt, vaultBase, message }) {
 function main() {
   const input = readHookInput();
   const vaultBase = getVaultBase(input);
+  warnIfDefaultVault(input);
   const now = new Date();
   const sessionId = sessionIdFromInput(input);
 
@@ -318,7 +321,9 @@ function main() {
         return;
       }
     }
-  } catch {}
+  } catch (err) {
+    debugLog('session-ensure fast-path skipped:', err);
+  }
 
   const control = readControl(vaultBase);
 

package/hooks/session-start.mjs

@@ -10,6 +10,7 @@ import {
   formatLocalIso,
   formatTime,
   getVaultBase,
+  warnIfDefaultVault,
   providerMeta,
   readControl,
   readHookInput,
@@ -146,6 +147,7 @@ function buildAdditionalContext({ relPath, startedAt, vaultBase }) {
 function main() {
   const input = readHookInput();
   const vaultBase = getVaultBase(input);
+  warnIfDefaultVault(input);
   const now = new Date();
   const sessionId = input.session_id || input.sessionId || '';
   const control = readControl(vaultBase);

package/hooks/session-stop.mjs

@@ -14,6 +14,7 @@ import {
   formatLocalIso,
   getNextAdrNumber,
   getVaultBase,
+  warnIfDefaultVault,
   listMarkdownFiles,
   readControl,
   readHookInput,
@@ -997,6 +998,7 @@ function main() {
   }
 
   const vaultBase = getVaultBase(input);
+  warnIfDefaultVault(input);
   const control = readControl(vaultBase);
   const transcriptPath = input.transcript_path || input.transcriptPath || '';
 

package/hooks/understand-inject.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// understand-inject — SessionStart hook (agent-agnostic, run via `npx wendkeep hook
+// understand-inject`). If the Understand-Anything domain graph has been generated
+// (`.understand-anything/knowledge-graph.json` at the project root), inject a cheap
+// slice of it into the session; otherwise stay silent. Never breaks the session.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { readHookInput, writeHookOutput } from './obsidian-common.mjs';
+
+const DOMAIN_TYPES = new Set(['domain', 'flow', 'step']);
+
+// Build the injection text from the project's domain graph. Returns '' when the
+// graph is absent/unreadable/empty so the caller can stay silent (fail-quiet).
+// Reads only a bounded slice — the full knowledge-graph.json can be large.
+export function buildUnderstandInjection(projectRoot, { maxNodes = 30 } = {}) {
+  const graphPath = join(projectRoot, '.understand-anything', 'knowledge-graph.json');
+  let graph;
+  try {
+    graph = JSON.parse(readFileSync(graphPath, 'utf8'));
+  } catch {
+    return '';
+  }
+  const nodes = Array.isArray(graph?.nodes) ? graph.nodes : [];
+  if (!nodes.length) return '';
+
+  const domainNodes = nodes.filter((n) => DOMAIN_TYPES.has(n?.type));
+  const source = domainNodes.length ? domainNodes : nodes;
+  const picked = source.slice(0, maxNodes);
+
+  const lines = picked.map((n) => {
+    const title = n?.name || n?.title || n?.id || '(sem nome)';
+    const kind = n?.type ? `[${n.type}] ` : '';
+    const summary = String(n?.summary || n?.description || '')
+      .split('\n')[0]
+      .slice(0, 200);
+    return `- ${kind}${title}${summary ? ` — ${summary}` : ''}`;
+  });
+
+  const remaining = source.length - picked.length;
+  const more = remaining > 0
+    ? `*…+${remaining} nós. Grafo completo: .understand-anything/knowledge-graph.json*`
+    : '';
+
+  return [
+    '<understand_domain_graph>',
+    'Domain-graph do projeto (Understand-Anything) — mapa de domínios/fluxos:',
+    ...lines,
+    more,
+    '</understand_domain_graph>',
+  ]
+    .filter(Boolean)
+    .join('\n');
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    readHookInput(); // drain stdin (agent JSON); project root comes from cwd
+    const context = buildUnderstandInjection(process.cwd());
+    if (!context) {
+      writeHookOutput({});
+    } else {
+      writeHookOutput({
+        hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context },
+      });
+    }
+  } catch (error) {
+    process.stderr.write(`[understand-inject] falhou: ${error.message}\n`);
+    writeHookOutput({});
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Automatically capture AI coding agent sessions (Claude Code, Codex) as local Markdown in your Obsidian vault — turn-by-turn history, cost/token tracking, auto-extracted decisions/bugs/learnings, rendered in the graph. Local-first.",
   "type": "module",
   "bin": {
@@ -17,7 +17,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "check": "node --check bin/wendkeep.mjs && node --check src/init.mjs && node --check src/doctor.mjs"
+    "check": "node --check bin/wendkeep.mjs && node --check src/init.mjs && node --check src/doctor.mjs",
+    "test": "node --test"
   },
   "keywords": [
     "claude-code",

package/src/companion-select.mjs

@@ -0,0 +1,111 @@
+// Interactive companion checkbox selector for `wendkeep init`.
+// The state machine (initial/reduce/render/mapKey) is pure and tested; the raw-TTY
+// event loop is a thin shell over it, with a text fallback when raw mode is absent.
+import readline from 'node:readline';
+
+const HINT = 'Espaço marca/desmarca · ↑/↓ move · a=todos · n=nenhum · Enter confirma';
+
+export function initialCompanionMenu(companions) {
+  return {
+    items: companions.map((c) => ({ id: c.id, label: c.label, checked: !!c.default })),
+    cursor: 0,
+  };
+}
+
+export function reduceCompanionMenu(state, action) {
+  const n = state.items.length;
+  switch (action) {
+    case 'up':
+      return { ...state, cursor: (state.cursor - 1 + n) % n };
+    case 'down':
+      return { ...state, cursor: (state.cursor + 1) % n };
+    case 'space':
+      return {
+        ...state,
+        items: state.items.map((it, i) => (i === state.cursor ? { ...it, checked: !it.checked } : it)),
+      };
+    case 'all':
+      return { ...state, items: state.items.map((it) => ({ ...it, checked: true })) };
+    case 'none':
+      return { ...state, items: state.items.map((it) => ({ ...it, checked: false })) };
+    case 'enter':
+      return { ...state, done: true, selected: state.items.filter((it) => it.checked).map((it) => it.id) };
+    default:
+      return state;
+  }
+}
+
+export function renderCompanionMenu(state) {
+  const lines = [`Companions — ${HINT}:`];
+  state.items.forEach((it, i) => {
+    const cursor = i === state.cursor ? '>' : ' ';
+    const box = it.checked ? '[x]' : '[ ]';
+    lines.push(`${cursor} ${box} ${it.label}`);
+  });
+  return lines.join('\n');
+}
+
+export function mapKey(str, key = {}) {
+  const name = key.name;
+  if (name === 'up' || name === 'k') return 'up';
+  if (name === 'down' || name === 'j') return 'down';
+  if (name === 'space' || str === ' ') return 'space';
+  if (name === 'return' || name === 'enter') return 'enter';
+  if (str === 'a') return 'all';
+  if (str === 'n') return 'none';
+  return null;
+}
+
+// True when stdin/stdout can drive an interactive raw-mode menu.
+export function canInteractiveSelect(input = process.stdin, output = process.stdout) {
+  return !!(input && output && input.isTTY && output.isTTY && typeof input.setRawMode === 'function');
+}
+
+// Run the raw-TTY checkbox menu; resolves with the selected ids. Caller must check
+// canInteractiveSelect() first (otherwise use the text fallback).
+export function selectCompanionsInteractive(companions, { input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolve) => {
+    let state = initialCompanionMenu(companions);
+    let drawnLines = 0;
+
+    readline.emitKeypressEvents(input);
+    input.setRawMode(true);
+    input.resume();
+
+    const draw = () => {
+      if (drawnLines) {
+        readline.moveCursor(output, 0, -drawnLines);
+        readline.clearScreenDown(output);
+      }
+      const text = renderCompanionMenu(state);
+      output.write(`${text}\n`);
+      drawnLines = text.split('\n').length;
+    };
+
+    const cleanup = () => {
+      input.removeListener('keypress', onKey);
+      if (typeof input.setRawMode === 'function') input.setRawMode(false);
+      input.pause();
+    };
+
+    const onKey = (str, key = {}) => {
+      if (key.ctrl && key.name === 'c') {
+        cleanup();
+        output.write('\n');
+        process.exit(130);
+      }
+      const action = mapKey(str, key);
+      if (!action) return;
+      state = reduceCompanionMenu(state, action);
+      if (state.done) {
+        cleanup();
+        resolve(state.selected);
+        return;
+      }
+      draw();
+    };
+
+    input.on('keypress', onKey);
+    draw();
+  });
+}

package/src/init.mjs

@@ -2,8 +2,9 @@
 // Creates the vault taxonomy, NON-DESTRUCTIVELY merges the session hooks +
 // OBSIDIAN_VAULT_PATH into .claude/settings.json, and adds the mcpvault server to
 // .mcp.json. Idempotent: re-running only adds what is missing.
+import { spawnSync } from 'node:child_process';
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { isAbsolute, join, resolve } from 'node:path';
+import { basename, isAbsolute, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import {
   VAULT_FOLDERS,
@@ -11,7 +12,16 @@ import {
   MCP_SERVER_KEY,
   mcpServerEntry,
   hookCommand,
+  deriveVaultDirName,
+  COMPANIONS,
+  resolveCompanions,
+  companionSettingsPatch,
+  companionMcpPatch,
+  companionHookSpecs,
+  cavemanInstallerCommand,
 } from './taxonomy.mjs';
+import { renderVaultReadme } from './vault-readme.mjs';
+import { canInteractiveSelect, selectCompanionsInteractive } from './companion-select.mjs';
 
 function parseArgs(argv) {
   const args = { mcp: true, yes: false, force: false };
@@ -22,6 +32,9 @@ function parseArgs(argv) {
     else if (a === '--no-mcp') args.mcp = false;
     else if (a === '--yes' || a === '-y') args.yes = true;
     else if (a === '--force') args.force = true;
+    else if (a === '--no-companions') args.noCompanions = true;
+    else if (a === '--companions') args.companions = argv[++i];
+    else if (a.startsWith('--companions=')) args.companions = a.slice(13);
     else if (a.startsWith('--vault=')) args.vault = a.slice(8);
     else if (a.startsWith('--project=')) args.project = a.slice(10);
   }
@@ -57,11 +70,12 @@ function backup(path) {
 
 // --- merges -----------------------------------------------------------------
 
-function mergeSettings(existing, { vaultPath, withMcp, force }) {
+export function mergeSettings(existing, { vaultPath, withMcp, force, companions = [] }) {
   const s = existing && typeof existing === 'object' ? { ...existing } : {};
   s.hooks = { ...(s.hooks || {}) };
   let added = 0;
-  for (const h of SESSION_HOOKS) {
+  // wendkeep's own session hooks + any companion-authored hooks (e.g. understand-inject).
+  for (const h of [...SESSION_HOOKS, ...companionHookSpecs(companions)]) {
     const command = hookCommand(h.name);
     const groups = Array.isArray(s.hooks[h.event]) ? [...s.hooks[h.event]] : [];
     const present = groups.some((g) => (g.hooks || []).some((x) => x.command === command));
@@ -76,18 +90,31 @@ function mergeSettings(existing, { vaultPath, withMcp, force }) {
     added += 1;
   }
   s.env = { ...(s.env || {}), OBSIDIAN_VAULT_PATH: vaultPath };
-  if (withMcp) {
+
+  // Claude Code plugin layer for the selected companions (additive, non-clobbering).
+  const cp = companionSettingsPatch(companions);
+  if (Object.keys(cp.extraKnownMarketplaces).length) {
+    s.extraKnownMarketplaces = { ...(s.extraKnownMarketplaces || {}), ...cp.extraKnownMarketplaces };
+  }
+  if (Object.keys(cp.enabledPlugins).length) {
+    s.enabledPlugins = { ...(s.enabledPlugins || {}), ...cp.enabledPlugins };
+  }
+
+  const companionMcp = Object.keys(companionMcpPatch(companions));
+  if (withMcp || companionMcp.length) {
     const set = new Set(Array.isArray(s.enabledMcpjsonServers) ? s.enabledMcpjsonServers : []);
-    set.add(MCP_SERVER_KEY);
+    if (withMcp) set.add(MCP_SERVER_KEY);
+    for (const key of companionMcp) set.add(key);
     s.enabledMcpjsonServers = [...set];
   }
   return { settings: s, added };
 }
 
-function mergeMcp(existing, vaultPath) {
+export function mergeMcp(existing, { vaultPath, withVault = true, companions = [] }) {
   const m = existing && typeof existing === 'object' ? { ...existing } : {};
   m.mcpServers = { ...(m.mcpServers || {}) };
-  m.mcpServers[MCP_SERVER_KEY] = mcpServerEntry(vaultPath);
+  if (withVault) m.mcpServers[MCP_SERVER_KEY] = mcpServerEntry(vaultPath);
+  Object.assign(m.mcpServers, companionMcpPatch(companions));
   return m;
 }
 
@@ -100,10 +127,10 @@ export async function runInit(argv) {
 
   let vaultPath = args.vault;
   if (!vaultPath) {
-    const fallback = join(projectPath, '.wendkeep-vault');
+    const fallback = join(projectPath, deriveVaultDirName(projectPath));
     if (process.stdin.isTTY && !args.yes) {
       const rl = createInterface({ input: process.stdin, output: process.stdout });
-      const ans = (await rl.question(`Obsidian vault path [${fallback}]: `)).trim();
+      const ans = (await rl.question(`Obsidian vault path (Enter aceita o padrão, ou digite outro caminho)\n  [${fallback}]\n> `)).trim();
       rl.close();
       vaultPath = ans || fallback;
     } else {
@@ -112,10 +139,38 @@ export async function runInit(argv) {
   }
   vaultPath = isAbsolute(vaultPath) ? vaultPath : resolve(projectPath, vaultPath);
 
+  // Companion plugins/MCP selection. --no-companions wins; --companions <csv> is
+  // explicit; an interactive TTY gets a multi-choice prompt (context-mode pre-checked);
+  // otherwise the non-interactive default (context-mode only).
+  let companions;
+  if (args.noCompanions) {
+    companions = [];
+  } else if (args.companions !== undefined) {
+    companions = resolveCompanions({ companionsFlag: args.companions });
+  } else if (process.stdin.isTTY && !args.yes) {
+    log('\nCompanions (plugins/MCP opcionais — context-mode é a principal):');
+    if (canInteractiveSelect()) {
+      companions = await selectCompanionsInteractive(COMPANIONS);
+    } else {
+      // Text fallback (no raw-mode TTY): list + comma input with clear instructions.
+      for (const c of COMPANIONS) log(`  ${c.default ? '[x]' : '[ ]'} ${c.label}`);
+      const def = resolveCompanions({}).join(',');
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const ans = (await rl.question(
+        `Digite os ids separados por vírgula (Enter aceita [${def}], "none" p/ nenhum): `,
+      )).trim();
+      rl.close();
+      companions = ans.toLowerCase() === 'none' ? [] : resolveCompanions({ companionsFlag: ans || def });
+    }
+  } else {
+    companions = resolveCompanions({});
+  }
+
   log('\nwendkeep init');
-  log(`  project : ${projectPath}`);
-  log(`  vault   : ${vaultPath}`);
-  log(`  mcp     : ${args.mcp ? 'mcpvault (wendkeep-vault)' : 'skipped'}\n`);
+  log(`  project    : ${projectPath}`);
+  log(`  vault      : ${vaultPath}`);
+  log(`  mcp        : ${args.mcp ? 'mcpvault (wendkeep-vault)' : 'skipped'}`);
+  log(`  companions : ${companions.length ? companions.join(', ') : 'none'}\n`);
 
   // 1. Vault taxonomy ---------------------------------------------------------
   if (!existsSync(vaultPath)) mkdirSync(vaultPath, { recursive: true });
@@ -127,39 +182,66 @@ export async function runInit(argv) {
       created += 1;
     }
   }
-  log(`  [1/3] vault taxonomy: ${VAULT_FOLDERS.length} folders (${created} created)`);
+  // Generate a project-templated vault README (non-destructive: never clobber one).
+  const readmePath = join(vaultPath, 'README.md');
+  let readmeNote = '';
+  if (!existsSync(readmePath)) {
+    writeFileSync(readmePath, renderVaultReadme({ projectName: basename(projectPath), vaultPath, withMcp: args.mcp }), 'utf8');
+    readmeNote = ', README.md created';
+  }
+  log(`  [1/3] vault taxonomy: ${VAULT_FOLDERS.length} folders (${created} created)${readmeNote}`);
 
   // 2. .claude/settings.json --------------------------------------------------
   const settingsPath = join(projectPath, '.claude', 'settings.json');
   const settingsRead = readJsonSafe(settingsPath);
   if (!settingsRead.ok) {
     // Unparseable existing file — never clobber. Drop a .new for manual merge.
-    const fresh = mergeSettings(null, { vaultPath, withMcp: args.mcp, force: true }).settings;
+    const fresh = mergeSettings(null, { vaultPath, withMcp: args.mcp, force: true, companions }).settings;
     writeJson(`${settingsPath}.new`, fresh);
     log(`  [2/3] settings.json exists but is not valid JSON -> wrote ${settingsPath}.new (merge by hand)`);
   } else {
     const hadFile = settingsRead.data !== null;
-    const { settings, added } = mergeSettings(settingsRead.data, { vaultPath, withMcp: args.mcp, force: args.force });
+    const { settings, added } = mergeSettings(settingsRead.data, { vaultPath, withMcp: args.mcp, force: args.force, companions });
     if (hadFile) backup(settingsPath);
     writeJson(settingsPath, settings);
     log(`  [2/3] settings.json ${hadFile ? 'merged' : 'created'} (${added} hook(s) wired, OBSIDIAN_VAULT_PATH set${hadFile ? ', .bak saved' : ''})`);
   }
 
   // 3. .mcp.json --------------------------------------------------------------
-  if (args.mcp) {
+  // Written when mcpvault is wanted OR a selected companion ships an MCP server.
+  const companionMcp = companionMcpPatch(companions);
+  if (args.mcp || Object.keys(companionMcp).length) {
     const mcpPath = join(projectPath, '.mcp.json');
     const mcpRead = readJsonSafe(mcpPath);
+    const mcpOpts = { vaultPath, withVault: args.mcp, companions };
+    const names = [args.mcp && MCP_SERVER_KEY, ...Object.keys(companionMcp)].filter(Boolean).join(', ');
     if (!mcpRead.ok) {
-      writeJson(`${mcpPath}.new`, mergeMcp(null, vaultPath));
+      writeJson(`${mcpPath}.new`, mergeMcp(null, mcpOpts));
       log(`  [3/3] .mcp.json exists but is not valid JSON -> wrote ${mcpPath}.new (merge by hand)`);
     } else {
       const hadFile = mcpRead.data !== null;
       if (hadFile) backup(mcpPath);
-      writeJson(mcpPath, mergeMcp(mcpRead.data, vaultPath));
-      log(`  [3/3] .mcp.json ${hadFile ? 'merged' : 'created'} (wendkeep-vault server${hadFile ? ', .bak saved' : ''})`);
+      writeJson(mcpPath, mergeMcp(mcpRead.data, mcpOpts));
+      log(`  [3/3] .mcp.json ${hadFile ? 'merged' : 'created'} (${names}${hadFile ? ', .bak saved' : ''})`);
     }
   } else {
-    log('  [3/3] .mcp.json skipped (--no-mcp)');
+    log('  [3/3] .mcp.json skipped (--no-mcp, no MCP companions)');
+  }
+
+  // caveman has no MCP / agnostic-hook path: on non-Claude agents its skills come
+  // from its own cross-agent installer. Best-effort, fail-soft — the Claude Code
+  // plugin entry is already wired in settings.json regardless.
+  if (companions.includes('caveman')) {
+    const cmd = cavemanInstallerCommand();
+    log(`\n  caveman: running cross-agent installer (best-effort): ${cmd.command} ${cmd.args.join(' ')}`);
+    try {
+      const r = spawnSync(cmd.command, cmd.args, { stdio: 'inherit' });
+      if (r.status !== 0) {
+        log(`  [!] caveman installer exited ${r.status ?? '?'} — Claude Code plugin entry still wired; rerun manually if needed.`);
+      }
+    } catch (e) {
+      log(`  [!] caveman installer could not run (${e.code || e.message}) — Claude Code plugin entry still wired.`);
+    }
   }
 
   log('\nNext steps:');

package/src/taxonomy.mjs

@@ -35,6 +35,7 @@ export const HOOK_FILES = [
   'brain-reindex.mjs',
   'session-backfill.mjs',
   'vault-health.mjs',
+  'understand-inject.mjs',
 ];
 
 // Hook scripts that are safe to invoke directly via `wendkeep hook <name>`.
@@ -49,6 +50,7 @@ export const RUNNABLE_HOOKS = [
   'brain-recall',
   'brain-reindex',
   'vault-health',
+  'understand-inject',
 ];
 
 // The MCP server entry wendkeep wires into .mcp.json so the agent can read/write the
@@ -74,3 +76,134 @@ export const SESSION_HOOKS = [
 export function hookCommand(name) {
   return `npx wendkeep hook ${name}`;
 }
+
+// --- companion plugins / MCP --------------------------------------------------
+// Optional tools wendkeep init can pin alongside the vault. Each is wired through
+// the MOST agent-agnostic mechanism it supports; the Claude Code plugin entry
+// (extraKnownMarketplaces + enabledPlugins) is an additive bonus, never the base.
+//   - mcp:          .mcp.json server entry (works on any MCP-capable agent)
+//   - wendkeepHook: a wendkeep-authored hook (runs via `npx wendkeep hook`, any agent)
+//   - installer:    cross-agent install script (used on non-Claude agents)
+// marketplace/plugin shapes are verified against a real ~/.claude/settings.json.
+export const COMPANIONS = [
+  {
+    id: 'context-mode',
+    label: 'context-mode — otimizador de contexto + memória FTS5 (principal)',
+    default: true,
+    marketplace: { source: 'git', url: 'https://github.com/mksglu/context-mode.git' },
+    plugin: 'context-mode',
+    // Agent-agnostic: MCP server, self-updating via unpinned npx.
+    mcp: { key: 'context-mode', entry: { type: 'stdio', command: 'npx', args: ['-y', 'context-mode'] } },
+  },
+  {
+    id: 'understand-anything',
+    label: 'Understand-Anything — domain-graph do projeto',
+    default: false,
+    marketplace: { source: 'github', repo: 'Egonex-AI/Understand-Anything' },
+    plugin: 'understand-anything',
+    // No native SessionStart: wendkeep authors a conditional domain-graph injector.
+    wendkeepHook: 'understand-inject',
+  },
+  {
+    id: 'caveman',
+    label: 'caveman — modo compressão de tokens',
+    default: false,
+    marketplace: { source: 'git', url: 'https://github.com/JuliusBrussee/caveman.git' },
+    plugin: 'caveman',
+    // No MCP, no agnostic hook: on non-Claude agents, run its own installer.
+    installer: {
+      sh: 'https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh',
+      ps1: 'https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1',
+    },
+  },
+];
+
+const COMPANION_BY_ID = Object.fromEntries(COMPANIONS.map((c) => [c.id, c]));
+
+// Resolve the companion ids for the NON-interactive path (the interactive prompt
+// supplies its own selection). --no-companions wins; an explicit flag selects the
+// named ids (unknown dropped) in registry order; otherwise the defaults.
+export function resolveCompanions({ companionsFlag, noCompanions } = {}) {
+  if (noCompanions) return [];
+  let wanted;
+  if (typeof companionsFlag === 'string' && companionsFlag.trim()) {
+    const set = new Set(companionsFlag.split(',').map((s) => s.trim()).filter(Boolean));
+    wanted = (id) => set.has(id);
+  } else {
+    wanted = (id) => COMPANION_BY_ID[id]?.default === true;
+  }
+  return COMPANIONS.filter((c) => wanted(c.id)).map((c) => c.id);
+}
+
+// The settings.json fragment (Claude Code plugin layer) for the selected companions.
+export function companionSettingsPatch(ids) {
+  const extraKnownMarketplaces = {};
+  const enabledPlugins = {};
+  for (const id of ids) {
+    const c = COMPANION_BY_ID[id];
+    if (!c) continue;
+    extraKnownMarketplaces[c.id] = { source: c.marketplace };
+    enabledPlugins[`${c.plugin}@${c.id}`] = true;
+  }
+  return { extraKnownMarketplaces, enabledPlugins };
+}
+
+// The .mcp.json fragment (agent-agnostic layer) for MCP-capable companions only.
+export function companionMcpPatch(ids) {
+  const servers = {};
+  for (const id of ids) {
+    const c = COMPANION_BY_ID[id];
+    if (c?.mcp) servers[c.mcp.key] = c.mcp.entry;
+  }
+  return servers;
+}
+
+// SessionStart hook specs wendkeep must author for companions that lack a native
+// one (only Understand-Anything's domain-graph injector today). Same shape as
+// SESSION_HOOKS so the same merge logic wires them.
+export function companionHookSpecs(ids) {
+  const specs = [];
+  for (const id of ids) {
+    const c = COMPANION_BY_ID[id];
+    if (c?.wendkeepHook) {
+      specs.push({
+        event: 'SessionStart',
+        matcher: null,
+        name: c.wendkeepHook,
+        timeout: 15,
+        statusMessage: `wendkeep: ${c.id} domain graph`,
+      });
+    }
+  }
+  return specs;
+}
+
+// Build the platform-appropriate command to run caveman's own cross-agent installer
+// (used on non-Claude agents — caveman has no MCP/agnostic-hook path). Pure: returns
+// {command, args}; the caller decides whether to spawn it.
+export function cavemanInstallerCommand(platform = process.platform) {
+  const { sh, ps1 } = COMPANION_BY_ID.caveman.installer;
+  if (platform === 'win32') {
+    return { command: 'powershell', args: ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', `irm ${ps1} | iex`] };
+  }
+  return { command: 'bash', args: ['-c', `curl -fsSL ${sh} | bash`] };
+}
+
+// Derive the default vault folder name from the project folder: `.<project>-vault`.
+// Splits on both separators so it is correct regardless of host OS, sanitizes
+// filesystem-unsafe characters, preserves case, and falls back to a stable name
+// when the basename is empty (root paths). Pure + side-effect free.
+export function deriveVaultDirName(projectPath) {
+  const base = String(projectPath || '')
+    .replace(/[\\/]+$/, '')
+    .split(/[\\/]/)
+    .pop() || '';
+  const clean = base
+    .replace(/^[.\s]+/, '') // drop leading dots/space so we never get `..name`
+    .replace(/[<>:"/\\|?*-]/g, '-') // FS-unsafe chars -> dash
+    .replace(/\s+/g, '-') // whitespace -> dash
+    .replace(/-+/g, '-') // collapse dash runs
+    .replace(/^-+|-+$/g, '') // trim edge dashes
+    .replace(/\.+$/, ''); // trim trailing dots
+  return clean ? `.${clean}-vault` : '.wendkeep-vault';
+}

package/src/vault-readme.mjs

@@ -0,0 +1,73 @@
+// Renders a neutral, project-templated README for a freshly created wendkeep vault.
+// The structure table is derived from VAULT_FOLDERS so it can never drift from the
+// folders `wendkeep init` actually creates.
+import { VAULT_FOLDERS } from './taxonomy.mjs';
+
+const FOLDER_DESCRIPTIONS = {
+  '00-Inbox': 'Notas rápidas, captura sem classificação',
+  '01-Projeto': 'Arquitetura, padrões, memória do projeto',
+  '02-Sessões': 'Uma nota por sessão de trabalho com o agente IA',
+  '03-Linear': 'Espelho de issues/tarefas do seu tracker (Linear, Jira, GitHub Issues…)',
+  '04-Decisões': 'Architecture Decision Records (ADRs)',
+  '05-Bugs': 'Bugs resolvidos com causa raiz documentada',
+  '06-Aprendizados': 'Lições extraídas das sessões',
+  Templates: 'Templates para novas notas',
+  '.brain': 'Memória canônica: CORE.md (curado) + DIGEST.md (auto), injetada no SessionStart',
+};
+
+function structureTable() {
+  const rows = VAULT_FOLDERS.map((f) => {
+    const desc = FOLDER_DESCRIPTIONS[f] || 'Notas do projeto';
+    return `| \`${f}/\` | ${desc} |`;
+  });
+  return ['| Pasta | Conteúdo |', '| --- | --- |', ...rows].join('\n');
+}
+
+export function renderVaultReadme({ projectName, vaultPath, withMcp = true }) {
+  const name = projectName || 'projeto';
+  const mcpIntro = withMcp ? ', e lida/escrita pelo MCP server **MCPVault**' : '';
+
+  const access = [
+    `- **Obsidian:** abra esta pasta com "Open folder as vault" → \`${vaultPath}\``,
+  ];
+  if (withMcp) {
+    access.push(
+      '- **Agente (MCP):** o servidor `wendkeep-vault` (MCPVault) é apontado para este vault\n' +
+        '  pelo `wendkeep init` (em `.mcp.json`), dando ao agente leitura/escrita das notas.',
+    );
+  }
+  access.push(
+    '- **Hooks:** `settings.json` chama `npx wendkeep hook <name>`; o vault é localizado\n' +
+      '  via a env `OBSIDIAN_VAULT_PATH` (também gravada pelo `wendkeep init`).',
+  );
+
+  return `# Vault Obsidian — ${name}
+
+> Base de conhecimento de **${name}**, capturada automaticamente pelo wendkeep a
+> partir das sessões dos agentes de código IA (**Claude Code** e **Codex**) via
+> hooks de sessão${mcpIntro}.
+
+## Estrutura
+
+${structureTable()}
+
+## Acesso
+
+${access.join('\n')}
+
+## Regras
+
+1. Toda sessão de trabalho relevante gera nota em \`02-Sessões/\` (automático, pelos hooks).
+2. Decisões de arquitetura viram ADR em \`04-Decisões/\`.
+3. Bugs com causa raiz vão para \`05-Bugs/\`; lições para \`06-Aprendizados/\`.
+4. Memória canônica: \`.brain/CORE.md\` (curado) + \`.brain/DIGEST.md\` (auto) — injetados no SessionStart.
+5. Tags em frontmatter YAML, não inline.
+6. Wikilinks \`[[nota]]\` para conectar notas entre si.
+
+## Notas
+
+- **Idioma das pastas:** os nomes são PT-BR (limitação conhecida; i18n no roadmap do wendkeep).
+- **Versionamento:** as notas de sessão podem conter trechos de transcript — avalie
+  antes de commitar este vault em um repositório compartilhado.
+`;
+}