wendkeep 0.38.2 → 0.39.0

package/CHANGELOG.md

@@ -4,6 +4,46 @@ 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.39.0] — 2026-07-13
+
+### Added
+
+- Configuração provider-neutral `.wendkeep.json`, descoberta do diretório da sessão para os
+  pais, permitindo que Codex e Claude Code resolvam o mesmo vault sem variável global do
+  Windows. Caminhos relativos ao projeto e caminhos absolutos são suportados.
+- Identidade estável `projectId`, espelhada em `.brain/PROJECT.json`; vínculos que apontem
+  para o vault de outro projeto são rejeitados antes de qualquer gravação.
+- `doctor` informa caminho e origem do vínculo efetivo. Comandos CLI executados dentro do
+  projeto também descobrem o vault local, mantendo `--vault` como override explícito.
+
+### Changed
+
+- `wendkeep init` cria o vínculo projeto→vault de forma idempotente e adota instalações
+  antigas registradas em `.claude/settings.json`, sem mover ou dividir o histórico.
+- Um vínculo local sempre vence um `OBSIDIAN_VAULT_PATH` herdado pelo processo. A variável
+  permanece apenas para compatibilidade de comandos manuais legados.
+
+### Fixed
+
+- Hooks do Codex deixam de gravar sessões no vault doméstico `~/wendkeep-vault` quando o
+  processo não recebe o ambiente privado do Claude Code. Sem vínculo local ou payload
+  explícito, o hook agora falha de modo seguro, emite diagnóstico e não cria arquivos.
+- Projetos simultâneos deixam de compartilhar acidentalmente sessões, mudanças e grafo por
+  causa de uma variável global de usuário apontando para um único vault.
+
+### Migration
+
+- Após atualizar, execute uma vez `wendkeep init --project . --vault <vault> --yes`, depois
+  `wendkeep sync-defs --project . --reseed` e `wendkeep doctor --project .`; reinicie Codex e
+  Claude Code para recarregar os artefatos gerados.
+
+## [0.38.3] — 2026-07-12
+
+### Fixed
+
+- Sessões do Codex Desktop voltam a ser criadas quando `SessionStart` ou o primeiro `UserPromptSubmit` não fornecem `transcript_path`: o resolvedor usa o UUID canônico de `CODEX_THREAD_ID` e associa o rollout à mesma entrada assim que o transcript materializa.
+- A barreira cross-provider permanece fail-closed: quando `CODEX_THREAD_ID` e `session_meta.payload.session_id` estão presentes, divergência entre eles adia a escrita em vez de contaminar outra sessão.
+
 ## [0.38.2] — 2026-07-12
 
 ### Fixed

package/README.md

@@ -60,7 +60,7 @@ npx wendkeep init
 `wendkeep init` is interactive and **idempotent**. It will:
 
 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).
+2. Write a provider-neutral **`.wendkeep.json`** binding at the project root and a matching `.brain/PROJECT.json` marker in the vault. Codex and Claude Code discover the same vault from their session `cwd`; no machine-global environment variable is required. Existing `.claude/settings.json` registrations are adopted automatically.
 3. Add the **`wendkeep-vault`** MCP server to `.mcp.json` so the agent can read/write the vault. Skip with `--no-mcp` — e.g. when the agent already has a vault MCP. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
 4. Offer to pin **companion** plugins/MCP (multi-choice; only `context-mode` pre-checked). Each is wired the most agent-agnostic way it supports:
    - **`context-mode`** — context optimizer + FTS5 memory, as a `.mcp.json` MCP server (any agent). The recommended default.
@@ -96,15 +96,32 @@ npx wendkeep init --no-companions --no-mcp --yes              # zero companions,
 
 Then open the vault in Obsidian, send a test prompt in your agent, and confirm a note appears under `02-Sessões/…` (or `02-Sessions/…` for an `en` vault).
 
+### Project isolation
+
+Each project owns a `.wendkeep.json` containing a stable `projectId` and its vault path.
+Relative paths (for example `.NutriGymBrain`) are resolved from the project root; absolute
+paths are also supported. Hooks search upward from the agent's `cwd`, so nested packages use
+the nearest binding. The vault carries the same identity in `.brain/PROJECT.json`; a mismatch
+is rejected before any session is written. If no binding exists, hooks fail closed and never
+create the historical `~/wendkeep-vault` fallback.
+
+`OBSIDIAN_VAULT_PATH` remains only as legacy/manual CLI compatibility. It is not used to
+route automatic Codex or Claude hooks and a project-local binding overrides an inherited
+machine value.
+
 ## Updating
 
-Because the hooks live inside the installed package (settings.json calls `npx wendkeep hook <name>`), upgrading is just:
+Because the hooks live inside the installed package, upgrade the package and re-run the
+idempotent init. The init step creates/migrates the provider-neutral project binding:
 
 ```bash
-npm update wendkeep
+npm install --save-dev wendkeep@latest
+npx --no-install wendkeep init --project . --vault <your-vault> --yes
+npx --no-install wendkeep sync-defs --project . --reseed
+npx --no-install wendkeep doctor --project .
 ```
 
-No re‑copying, no snapshot to re‑sync — the package is the single source of truth.
+Restart Codex and Claude Code after reseeding their generated skills.
 
 ## Commands
 

package/README.pt-BR.md

@@ -58,7 +58,7 @@ npx wendkeep init
 O `wendkeep init` é interativo e **idempotente**. Ele:
 
 1. Cria a taxonomia de pastas do cofre e um `README.md` templado (cofre padrão: `<projeto>/.<nome-do-projeto>-vault`, ex.: `.MeuApp-vault`; sobrescreva com `--vault`).
-2. **Mescla** os três hooks de sessão e o `OBSIDIAN_VAULT_PATH` no `.claude/settings.json` — sem atropelar suas configs (salva um `.bak`; arquivo ilegível fica intocado e um `.new` é escrito pra você mesclar).
+2. Grava um vínculo provider-neutral **`.wendkeep.json`** na raiz do projeto e o marcador correspondente `.brain/PROJECT.json` no cofre. Codex e Claude Code descobrem o mesmo vault pelo `cwd` da sessão, sem variável global do Windows. Registros antigos em `.claude/settings.json` são adotados automaticamente.
 3. Adiciona o servidor MCP **`wendkeep-vault`** ao `.mcp.json` pro agente ler/escrever o cofre. Pule com `--no-mcp` — ex.: quando o agente já tem um MCP de cofre. (`--no-mcp` pula *só o MCP do próprio wendkeep*; os MCPs de companion seguem `--companions`.)
 4. Oferece fixar plugins/MCP **companion** (múltipla escolha; **nenhum** pré-marcado). Cada um é wirado do jeito mais agnóstico que suporta:
    - **`context-mode`** — otimizador de contexto + memória FTS5, como servidor MCP no `.mcp.json` (qualquer agente).
@@ -94,15 +94,31 @@ npx wendkeep init --no-companions --no-mcp --yes              # zero companions,
 
 Depois abra o cofre no Obsidian, mande um prompt de teste no seu agente e confirme que uma nota aparece em `02-Sessões/…` (ou `02-Sessions/…` num cofre `en`).
 
+### Isolamento por projeto
+
+Cada projeto possui um `.wendkeep.json` com `projectId` estável e caminho do vault. Caminhos
+relativos, como `.NutriGymBrain`, partem da raiz do projeto; caminhos absolutos também são
+aceitos. Os hooks procuram o vínculo mais próximo subindo a partir do `cwd`. O vault guarda a
+mesma identidade em `.brain/PROJECT.json`, e uma divergência bloqueia a escrita. Sem vínculo,
+os hooks falham de modo seguro e nunca criam o antigo fallback `~/wendkeep-vault`.
+
+`OBSIDIAN_VAULT_PATH` permanece somente como compatibilidade legada para comandos manuais.
+Ele não roteia hooks automáticos do Codex ou Claude, e o vínculo local prevalece sobre uma
+variável herdada da máquina.
+
 ## Atualizar
 
-Como os hooks vivem dentro do pacote instalado (o settings.json chama `npx wendkeep hook <name>`), atualizar é só:
+Como os hooks vivem dentro do pacote instalado, atualize e rode novamente o `init`
+idempotente. Essa etapa cria ou migra o vínculo provider-neutral:
 
 ```bash
-npm update wendkeep
+npm install --save-dev wendkeep@latest
+npx --no-install wendkeep init --project . --vault <seu-vault> --yes
+npx --no-install wendkeep sync-defs --project . --reseed
+npx --no-install wendkeep doctor --project .
 ```
 
-Sem recopiar, sem snapshot pra re‑sincronizar — o pacote é a única fonte da verdade.
+Reinicie Codex e Claude Code depois de resemear as skills geradas.
 
 ## Comandos
 

package/bin/wendkeep.mjs

@@ -102,8 +102,32 @@ function runHook(name) {
   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');
+    const resolved = resolveProjectVault({ startDir: optionValue(argv, '--project') || process.cwd() });
+    process.env.OBSIDIAN_VAULT_PATH = resolved.base;
+  } catch {
+    // Backward-compatible manual CLI behavior: individual commands still explain
+    // --vault / legacy env when no project binding exists. Hooks do not use this path.
+  }
+}
+
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
+  if (cmd && !['init', 'hook', '--version', '-v', '--help', '-h', 'help'].includes(cmd)) {
+    await preferProjectVault(rest);
+  }
   switch (cmd) {
     case 'init': {
       const { runInit } = await import('../src/init.mjs');

package/hooks/obsidian-common.mjs

@@ -2,9 +2,10 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'fs';
 import { basename, dirname, join, relative } from 'path';
 import { getLocale } from './locale.mjs';
+import { resolveProjectVault } from '../src/project-vault.mjs';
 
-// Neutral fallback only. The vault is normally resolved from the
-// OBSIDIAN_VAULT_PATH env var (set by `wendkeep init`) via getVaultBase() below.
+// Deprecated export kept for consumers that imported it before 0.39.0. Automatic
+// hooks never use this fallback: an unbound project fails closed.
 export const DEFAULT_VAULT_BASE = join(
   process.env.USERPROFILE || process.env.HOME || process.cwd(),
   'wendkeep-vault',
@@ -31,19 +32,12 @@ 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
+// Resolve from explicit hook payload or the nearest project-local binding. A legacy
+// `.claude/settings.json` registration is accepted as a migration bridge so Codex can
+// discover projects initialized by older WendKeep versions. Global process env and the
+// historical home fallback are intentionally excluded to prevent cross-project writes.
 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' };
+  return resolveProjectVault({ input });
 }
 
 export function getVaultBase(input = {}) {
@@ -60,16 +54,15 @@ export function debugLog(...args) {
   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.
+// Migration warning for projects that are still discovered through Claude's local
+// settings. Missing bindings throw before this point and are handled by each hook's
+// fail-closed top-level catch.
 export function warnIfDefaultVault(input = {}) {
   const { base, source } = resolveVault(input);
-  if (source === 'default') {
+  if (source === 'legacy-project-settings') {
     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',
+      `[wendkeep] Configuração legada do vault detectada em .claude/settings.json ("${base}"). `
+        + 'Rode `wendkeep init --yes` para criar .wendkeep.json; Codex e Claude continuarão no mesmo vault.\n',
     );
   }
   return source;

package/hooks/session-identity.mjs

@@ -39,10 +39,41 @@ function compatible(provider, transcriptProvider) {
     || (provider === 'claude' && transcriptProvider === 'anthropic');
 }
 
+function canonicalUuid(value = '') {
+  const id = String(value || '').trim().toLowerCase();
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(id) ? id : '';
+}
+
 export function resolveSessionIdentity(vaultBase, input = {}, provider = detectProvider()) {
   const transcriptPath = input.transcript_path || input.transcriptPath || '';
   const inspected = inspectTranscriptIdentity(transcriptPath);
   const hookId = input.session_id || input.sessionId || '';
+  const codexThreadId = canonicalUuid(input.codex_thread_id || input.codexThreadId || process.env.CODEX_THREAD_ID || '');
+
+  // Codex Desktop exposes the stable canonical conversation through
+  // CODEX_THREAD_ID even when SessionStart/UserPromptSubmit omit transcript_path.
+  // This is safer than the hook session_id (which may rotate on resume). Once the
+  // rollout materializes, require both canonical sources to agree.
+  const transcriptConversationId = canonicalUuid(inspected.canonicalConversationId);
+  if (provider === 'codex' && transcriptConversationId && codexThreadId
+    && transcriptConversationId !== codexThreadId) {
+    return {
+      state: 'deferred', provider, transcriptPath,
+      diagnostics: [`CODEX_THREAD_ID diverge do session_id do transcript (${codexThreadId} != ${transcriptConversationId})`],
+    };
+  }
+  if (provider === 'codex' && !inspected.canonicalConversationId && codexThreadId) {
+    return {
+      state: 'resolved',
+      provider,
+      canonicalConversationId: codexThreadId,
+      hookSessionId: hookId,
+      transcriptPath,
+      transcriptId: transcriptPath ? basename(transcriptPath, '.jsonl') : codexThreadId,
+      parentConversationId: '',
+      diagnostics: [],
+    };
+  }
 
   // Claude: input.session_id já é o id canônico e estável da conversa — idêntico
   // ao sessionId que cada linha do transcript grava. Numa sessão nova o arquivo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.38.2",
+  "version": "0.39.0",
   "description": "A persistent-memory harness for AI coding agents on your Obsidian vault: turn-by-turn session capture plus a native, zero-dependency spec→change→verify→archive loop (sensor-gated, independent verdict, mutation discrimination). Local-first, agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
     "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 && node --check src/project-vault.mjs",
     "test": "node --test",
     "release": "node scripts/release.mjs",
     "release:dry": "node scripts/release.mjs --dry-run"
@@ -46,6 +46,6 @@
     "url": "https://github.com/rogersialves/wendkeep/issues"
   },
   "devDependencies": {
-    "wendkeep": "^0.38.1"
+    "wendkeep": "^0.38.3"
   }
 }

package/src/doctor.mjs

@@ -2,10 +2,11 @@
 // harness integrity check (hooks/harness-doctor.mjs). Exits 1 on any error.
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { checkHarness } from '../hooks/harness-doctor.mjs';
 import { checkSyncDefs } from './sync-defs.mjs';
+import { resolveProjectVault } from './project-vault.mjs';
 
 export function runDoctor(argv) {
   const here = dirname(fileURLToPath(import.meta.url));
@@ -23,19 +24,28 @@ export function runDoctor(argv) {
     else passthrough.push(a);
   }
 
-  const env = { ...process.env };
-  if (vault) env.OBSIDIAN_VAULT_PATH = isAbsolute(vault) ? vault : resolve(process.cwd(), vault);
-  if (!env.OBSIDIAN_VAULT_PATH) {
-    process.stderr.write('wendkeep doctor: no vault. Pass --vault <path> or set OBSIDIAN_VAULT_PATH.\n');
+  const projectRoot = resolve(project || process.cwd());
+  let resolution;
+  try {
+    resolution = resolveProjectVault({
+      startDir: projectRoot,
+      explicitVault: vault || '',
+      validateIdentity: !vault,
+    });
+  } catch (error) {
+    process.stderr.write(`wendkeep doctor: ${error.message}\n`);
     process.exit(2);
   }
-  const vaultBase = env.OBSIDIAN_VAULT_PATH;
-  const projectRoot = resolve(project || process.cwd());
+  const vaultBase = resolution.base;
+  process.stdout.write(`[vault] ${resolution.source}: ${vaultBase} (project: ${projectRoot})\n`);
+  if (resolution.source === 'legacy-project-settings') {
+    process.stdout.write('  ! migração pendente: rode `wendkeep init --project . --vault "<vault>" --yes` para criar .wendkeep.json\n');
+  }
 
   // 1. Session/vault integrity (existing check).
   let healthStatus = 0;
   if (existsSync(hookFile)) {
-    const r = spawnSync(process.execPath, [hookFile, ...passthrough], { stdio: 'inherit', env });
+    const r = spawnSync(process.execPath, [hookFile, ...passthrough, '--vault', vaultBase], { stdio: 'inherit' });
     healthStatus = r.status ?? 0;
   }
 

package/src/init.mjs

@@ -1,6 +1,6 @@
 // `wendkeep init` — cross-platform replacement for setup-vault.ps1.
-// Creates the vault taxonomy, NON-DESTRUCTIVELY merges the session hooks +
-// OBSIDIAN_VAULT_PATH into .claude/settings.json, and adds the mcpvault server to
+// Creates the vault taxonomy + provider-neutral project binding, NON-DESTRUCTIVELY
+// merges the session hooks 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, readdirSync, writeFileSync } from 'node:fs';
@@ -41,6 +41,7 @@ import { seedWkSkills } from './skills-seed.mjs';
 import { LOCALES, DEFAULT_LOCALE, getLocale, clearLocaleCache, vaultFolders } from '../hooks/locale.mjs';
 import { seedDotcontext, globalHasDotcontext, resolveDotcontextSkipMcp, renderSensorsJson } from './dotcontext-seed.mjs';
 import { adoptSpecsState, SPECS_STATE_FILE } from '../hooks/spec-core.mjs';
+import { bindProjectVault, readProjectBinding } from './project-vault.mjs';
 
 function parseArgs(argv) {
   const args = { mcp: true, yes: false, force: false };
@@ -281,7 +282,7 @@ const MESSAGES = {
     readmeCreated: ', README.md criado', viewsNote: (n) => `, ${n} view(s) + dashboard`,
     defs: (s, a) => `        defs entregues: ${s} skill(s) -> .claude/skills + .agents/skills, ${a} agent(s) -> .codex/agents`,
     settingsBadJson: (p) => `  [2/4] settings.json existe mas não é JSON válido -> escrevi ${p}.new (mescle à mão)`,
-    settings: (verb, added, bak) => `  [2/4] settings.json ${verb} (${added} hook(s) wirados, OBSIDIAN_VAULT_PATH setado${bak})`,
+    settings: (verb, added, bak) => `  [2/4] settings.json ${verb} (${added} hook(s) wirados; .wendkeep.json é o vínculo compartilhado${bak})`,
     mcpBadJson: (p) => `  [3/4] .mcp.json existe mas não é JSON válido -> escrevi ${p}.new (mescle à mão)`,
     mcp: (verb, names, bak) => `  [3/4] .mcp.json ${verb} (${names}${bak})`,
     mcpSkipped: '  [3/4] .mcp.json ignorado (--no-mcp, sem companions MCP)',
@@ -306,7 +307,7 @@ const MESSAGES = {
     readmeCreated: ', README.md created', viewsNote: (n) => `, ${n} view(s) + dashboard`,
     defs: (s, a) => `        defs delivered: ${s} skill(s) -> .claude/skills + .agents/skills, ${a} agent(s) -> .codex/agents`,
     settingsBadJson: (p) => `  [2/4] settings.json exists but is not valid JSON -> wrote ${p}.new (merge by hand)`,
-    settings: (verb, added, bak) => `  [2/4] settings.json ${verb} (${added} hook(s) wired, OBSIDIAN_VAULT_PATH set${bak})`,
+    settings: (verb, added, bak) => `  [2/4] settings.json ${verb} (${added} hook(s) wired; .wendkeep.json is the shared binding${bak})`,
     mcpBadJson: (p) => `  [3/4] .mcp.json exists but is not valid JSON -> wrote ${p}.new (merge by hand)`,
     mcp: (verb, names, bak) => `  [3/4] .mcp.json ${verb} (${names}${bak})`,
     mcpSkipped: '  [3/4] .mcp.json skipped (--no-mcp, no MCP companions)',
@@ -334,9 +335,14 @@ export function parseLocaleAnswer(ans) {
   return 'pt-BR';
 }
 
-// The vault path this project was set up with — read from .claude/settings.json's
-// OBSIDIAN_VAULT_PATH (written by a prior init). Empty when the project isn't configured yet.
+// The vault path this project was set up with. New installs use the provider-neutral
+// `.wendkeep.json`; `.claude/settings.json` remains a local migration bridge for projects
+// initialized before 0.39.0.
 export function detectRegisteredVault(projectPath) {
+  try {
+    const binding = readProjectBinding(projectPath);
+    if (binding?.base) return binding.base;
+  } catch { /* init will surface/repair through an explicit --vault */ }
   try {
     const s = JSON.parse(readFileSync(join(projectPath, '.claude', 'settings.json'), 'utf8'));
     const v = s && s.env && s.env.OBSIDIAN_VAULT_PATH;
@@ -357,8 +363,8 @@ export async function runInit(argv) {
   const projectPath = resolve(args.project || process.cwd());
   const log = (s) => process.stdout.write(`${s}\n`);
 
-  // Recognize an already-configured project: the vault is registered in the project's
-  // settings.json (OBSIDIAN_VAULT_PATH) and its locale is locked in the vault's config.json.
+  // Recognize an already-configured project through `.wendkeep.json`, or through the
+  // project-local Claude setting during migration. Locale remains locked in vault config.
   // On re-run (e.g. after `npm i -D wendkeep@latest`) we reuse both and SKIP the language + vault
   // prompts — asking again risks a divergent vault from a mistyped name. `--vault` / `--locale`
   // override; the vault question is a once-per-project thing.
@@ -393,6 +399,10 @@ export async function runInit(argv) {
   }
   vaultPath = isAbsolute(vaultPath) ? vaultPath : resolve(projectPath, vaultPath);
 
+  // Persist the provider-neutral binding before any hook/config delivery. This also
+  // claims the vault identity and rejects accidental cross-project graph contamination.
+  bindProjectVault({ projectRoot: 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).

package/src/project-vault.mjs

@@ -0,0 +1,221 @@
+import { randomUUID } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, isAbsolute, join, parse, relative, resolve } from 'node:path';
+
+export const PROJECT_CONFIG_FILE = '.wendkeep.json';
+export const PROJECT_MARKER_REL = '.brain/PROJECT.json';
+export const PROJECT_CONFIG_SCHEMA = 1;
+
+function json(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); }
+  catch (error) {
+    const wrapped = new Error(`Configuração WendKeep inválida em "${path}": ${error.message}`);
+    wrapped.code = 'WENDKEEP_VAULT_CONFIG_INVALID';
+    throw wrapped;
+  }
+}
+
+function atomicJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const content = `${JSON.stringify(value, null, 2)}\n`;
+  if (existsSync(path) && readFileSync(path, 'utf8') === content) return false;
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temp, content, 'utf8');
+  renameSync(temp, path);
+  return true;
+}
+
+function startDirectory(value) {
+  const candidate = resolve(String(value || process.cwd()));
+  try { return statSync(candidate).isFile() ? dirname(candidate) : candidate; }
+  catch { return candidate; }
+}
+
+function walkParents(start) {
+  const result = [];
+  let current = startDirectory(start);
+  const root = parse(current).root;
+  while (true) {
+    result.push(current);
+    if (current === root) break;
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return result;
+}
+
+function inputStart(input = {}, fallback = '') {
+  return input.cwd
+    || input.project_dir
+    || input.projectDir
+    || input.workspace?.cwd
+    || process.env.CLAUDE_PROJECT_DIR
+    || fallback
+    || process.cwd();
+}
+
+function vaultFromConfig(projectRoot, config) {
+  if (!config || config.schemaVersion !== PROJECT_CONFIG_SCHEMA || !config.projectId || !config.vault) {
+    const error = new Error(
+      `Configuração incompleta em "${join(projectRoot, PROJECT_CONFIG_FILE)}". `
+      + 'Rode `wendkeep init --project <path> --vault <path>`.',
+    );
+    error.code = 'WENDKEEP_VAULT_CONFIG_INVALID';
+    throw error;
+  }
+  return isAbsolute(config.vault) ? resolve(config.vault) : resolve(projectRoot, config.vault);
+}
+
+export function readProjectBinding(projectRoot) {
+  const root = resolve(projectRoot);
+  const path = join(root, PROJECT_CONFIG_FILE);
+  if (!existsSync(path)) return null;
+  const config = json(path);
+  return { config, configPath: path, projectRoot: root, base: vaultFromConfig(root, config) };
+}
+
+export function findProjectBinding(start) {
+  for (const projectRoot of walkParents(start)) {
+    const found = readProjectBinding(projectRoot);
+    if (found) return found;
+  }
+  return null;
+}
+
+export function findLegacyProjectVault(start) {
+  for (const projectRoot of walkParents(start)) {
+    const settingsPath = join(projectRoot, '.claude', 'settings.json');
+    if (!existsSync(settingsPath)) continue;
+    try {
+      const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+      const raw = settings?.env?.OBSIDIAN_VAULT_PATH;
+      if (typeof raw === 'string' && raw.trim()) {
+        return {
+          base: isAbsolute(raw) ? resolve(raw) : resolve(projectRoot, raw),
+          projectRoot,
+          source: 'legacy-project-settings',
+          configPath: settingsPath,
+          projectId: '',
+        };
+      }
+    } catch { /* init/doctor explicam JSON inválido; descoberta segue procurando */ }
+  }
+  return null;
+}
+
+export function readVaultMarker(vaultPath) {
+  const markerPath = join(resolve(vaultPath), ...PROJECT_MARKER_REL.split('/'));
+  if (!existsSync(markerPath)) return null;
+  return { marker: json(markerPath), markerPath };
+}
+
+function validateMarker(result) {
+  const found = readVaultMarker(result.base);
+  if (!found) {
+    const error = new Error(
+      `O vault "${result.base}" ainda não possui ${PROJECT_MARKER_REL}. `
+      + `Rode \`wendkeep init --project "${result.projectRoot}" --vault "${result.base}" --yes\`.`,
+    );
+    error.code = 'WENDKEEP_VAULT_MARKER_MISSING';
+    throw error;
+  }
+  if (found.marker?.projectId !== result.projectId) {
+    const error = new Error(
+      `Vault de outro projeto: configuração "${result.projectId}" aponta para marcador `
+      + `"${found.marker?.projectId || 'ausente'}" em "${found.markerPath}".`,
+    );
+    error.code = 'WENDKEEP_VAULT_PROJECT_MISMATCH';
+    throw error;
+  }
+}
+
+export function resolveProjectVault({
+  input = {},
+  startDir = '',
+  explicitVault = '',
+  allowLegacySettings = true,
+  validateIdentity = true,
+} = {}) {
+  const start = inputStart(input, startDir);
+  const explicit = explicitVault || input?.obsidian_vault_path;
+  if (explicit) {
+    return {
+      base: isAbsolute(explicit) ? resolve(explicit) : resolve(startDirectory(start), explicit),
+      source: explicitVault ? 'explicit' : 'payload',
+      projectRoot: startDirectory(start),
+      projectId: '',
+      configPath: '',
+    };
+  }
+
+  const binding = findProjectBinding(start);
+  if (binding) {
+    const result = {
+      base: binding.base,
+      source: 'project-config',
+      projectRoot: binding.projectRoot,
+      projectId: binding.config.projectId,
+      configPath: binding.configPath,
+    };
+    if (validateIdentity) validateMarker(result);
+    return result;
+  }
+
+  if (allowLegacySettings) {
+    const legacy = findLegacyProjectVault(start);
+    if (legacy) return legacy;
+  }
+
+  const error = new Error(
+    `Nenhum vault WendKeep vinculado ao projeto em "${startDirectory(start)}". `
+    + `Crie ${PROJECT_CONFIG_FILE} com \`wendkeep init --project "${startDirectory(start)}" --vault <path> --yes\`.`,
+  );
+  error.code = 'WENDKEEP_VAULT_UNCONFIGURED';
+  throw error;
+}
+
+function portableVaultPath(projectRoot, vaultPath) {
+  const rel = relative(projectRoot, vaultPath);
+  if (rel && !rel.startsWith('..') && !isAbsolute(rel)) return rel.replaceAll('\\', '/');
+  return vaultPath;
+}
+
+export function bindProjectVault({ projectRoot, vaultPath }) {
+  const root = resolve(projectRoot);
+  const base = isAbsolute(vaultPath) ? resolve(vaultPath) : resolve(root, vaultPath);
+  const existing = readProjectBinding(root);
+  const existingMarker = readVaultMarker(base);
+  const projectId = existing?.config?.projectId || existingMarker?.marker?.projectId || randomUUID();
+
+  if (existingMarker?.marker?.projectId && existingMarker.marker.projectId !== projectId) {
+    const error = new Error(
+      `Não é seguro vincular "${root}" ao vault de outro projeto: `
+      + `esperado "${projectId}", encontrado "${existingMarker.marker.projectId}".`,
+    );
+    error.code = 'WENDKEEP_VAULT_PROJECT_MISMATCH';
+    throw error;
+  }
+
+  mkdirSync(join(base, '.brain'), { recursive: true });
+  const config = {
+    schemaVersion: PROJECT_CONFIG_SCHEMA,
+    projectId,
+    vault: portableVaultPath(root, base),
+  };
+  const marker = {
+    schemaVersion: PROJECT_CONFIG_SCHEMA,
+    projectId,
+    projectName: basename(root),
+  };
+  atomicJson(join(base, ...PROJECT_MARKER_REL.split('/')), marker);
+  atomicJson(join(root, PROJECT_CONFIG_FILE), config);
+  return { base, projectRoot: root, projectId, config, marker };
+}

package/src/vault-readme.mjs

@@ -52,7 +52,7 @@ export function renderVaultReadme({ projectName, vaultPath, withMcp = true, loca
     const mcpIntro = withMcp ? ', and read/written by the **MCPVault** MCP server' : '';
     const access = [`- **Obsidian:** open this folder with "Open folder as vault" → \`${vaultPath}\``];
     if (withMcp) access.push('- **Agent (MCP):** the `wendkeep-vault` server (MCPVault) points at this vault (set in `.mcp.json`), giving the agent read/write on the notes.');
-    access.push('- **Hooks:** `settings.json` calls `npx wendkeep hook <name>`; the vault is located via `OBSIDIAN_VAULT_PATH` (also written by `wendkeep init`).');
+    access.push('- **Hooks:** Codex and Claude Code call `npx wendkeep hook <name>`; the vault is discovered from the project-local `.wendkeep.json` binding and checked against `.brain/PROJECT.json`.');
     return `# Obsidian vault — ${name}
 
 > Knowledge base of **${name}**, captured automatically by wendkeep from AI coding-agent
@@ -84,7 +84,7 @@ ${access.join('\n')}
   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 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 via a env `OBSIDIAN_VAULT_PATH` (também gravada pelo `wendkeep init`).');
+  access.push('- **Hooks:** Codex e Claude Code chamam `npx wendkeep hook <name>`; o vault é descoberto pelo vínculo local `.wendkeep.json` e validado contra `.brain/PROJECT.json`.');
   return `# Vault Obsidian — ${name}
 
 > Base de conhecimento de **${name}**, capturada automaticamente pelo wendkeep a