wendkeep 0.6.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "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": {
@@ -11,6 +11,7 @@
     "bin",
     "src",
     "hooks",
+    "schema",
     "README.md",
     "CHANGELOG.md"
   ],

package/schema/wendkeep.sensors.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/rogersialves/wendkeep/main/schema/wendkeep.sensors.schema.json",
+  "title": "wendkeep.sensors.json",
+  "description": "Native sensor config for the wendkeep harness (harness contract v1.1).",
+  "type": "object",
+  "required": ["version", "sensors"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "source": { "type": "string" },
+    "sensors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "command"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "severity": { "enum": ["critical", "warning"], "default": "critical" },
+          "type": { "enum": ["command", "mutation"], "default": "command" },
+          "command": { "type": "string", "minLength": 1 },
+          "report": {
+            "type": "string",
+            "description": "type: mutation only — path (project-relative) to the mutation-testing-elements report."
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/src/change.mjs

@@ -6,11 +6,13 @@ import {
   activeChange,
   listChanges,
   parseTasks,
+  setTaskDone,
   archiveChange,
 } from '../hooks/change-core.mjs';
 import { evaluateGate, requiredSensors } from '../hooks/sensors-core.mjs';
-import { evaluateVerdict, tasksHashOf } from '../hooks/spec-core.mjs';
+import { evaluateVerdict, tasksHashOf, parseSpecsList, parseDelta, parseRequirements, applyDelta } from '../hooks/spec-core.mjs';
 import { getNextAdrNumber, readControl } from '../hooks/obsidian-common.mjs';
+import { getLocale } from '../hooks/locale.mjs';
 
 function resolveVault(argv) {
   let vault;
@@ -27,6 +29,13 @@ function resolveVault(argv) {
   return isAbsolute(base) ? base : resolve(process.cwd(), base);
 }
 
+function opt(argv, name) {
+  const i = argv.indexOf(name);
+  if (i >= 0) return argv[i + 1];
+  const eq = argv.find((a) => a.startsWith(`${name}=`));
+  return eq ? eq.slice(name.length + 1) : undefined;
+}
+
 function today() {
   const d = new Date();
   return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
@@ -35,7 +44,8 @@ function today() {
 export function runChange(argv) {
   const [sub, ...rest] = argv;
   const vaultBase = resolveVault(rest);
-  const slugArg = () => rest.find((a) => !a.startsWith('-'));
+  const VALUE_FLAGS = new Set(['--vault', '--change', '--project']);
+  const slugArg = () => rest.find((a, i) => !a.startsWith('-') && !VALUE_FLAGS.has(rest[i - 1]));
 
   if (sub === 'new') {
     const slug = slugArg();
@@ -60,7 +70,7 @@ export function runChange(argv) {
     const slug = slugArg();
     if (!slug) { process.stderr.write('wendkeep change show: missing <slug>\n'); process.exit(2); }
     let md;
-    try { md = readFileSync(join(vaultBase, '08-Mudanças', slug, 'tarefas.md'), 'utf8'); }
+    try { md = readFileSync(join(vaultBase, getLocale(vaultBase).folders.changes, slug, 'tarefas.md'), 'utf8'); }
     catch { process.stderr.write(`wendkeep change show: not found: ${slug}\n`); process.exit(2); }
     const tasks = parseTasks(md);
     const open = tasks.filter((t) => !t.done).length;
@@ -69,6 +79,76 @@ export function runChange(argv) {
     process.exit(0);
   }
 
+  if (sub === 'status') {
+    const slug = slugArg() || activeChange(vaultBase);
+    if (!slug) { process.stderr.write('wendkeep change status: no change (arg or active)\n'); process.exit(2); }
+    const dir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
+    let tarefasMd;
+    try { tarefasMd = readFileSync(join(dir, 'tarefas.md'), 'utf8'); }
+    catch { process.stderr.write(`wendkeep change status: not found: ${slug}\n`); process.exit(2); }
+    const tasks = parseTasks(tarefasMd);
+    const done = tasks.filter((t) => t.done).length;
+    process.stdout.write(`change: ${slug}${slug === activeChange(vaultBase) ? ' (ativa)' : ''}\n`);
+    let specs = [];
+    try { specs = parseSpecsList(readFileSync(join(dir, 'proposta.md'), 'utf8')); } catch { /* sem proposta */ }
+    process.stdout.write(`specs: ${specs.join(', ') || '(nenhuma)'}\n`);
+    process.stdout.write(`tarefas: ${done} done / ${tasks.length - done} open\n`);
+    for (const t of tasks) {
+      process.stdout.write(`  [${t.done ? 'x' : ' '}] ${t.id} ${t.text}${t.req ? ` [req:${t.req}]` : ''}${t.sensor ? ` [sensor:${t.sensor}]` : ''}\n`);
+    }
+    let evidence = null;
+    try { evidence = JSON.parse(readFileSync(join(dir, 'evidencia.json'), 'utf8')); } catch { /* sem evidência */ }
+    if (evidence) for (const e of evidence) process.stdout.write(`  ${e.status === 'green' ? '✓' : '✗'} ${e.id} (${e.severity || 'critical'})\n`);
+    else process.stdout.write('evidencia: ausente\n');
+    const reqIds = [...new Set(tasks.map((t) => t.req).filter(Boolean))];
+    let verdict = null;
+    try { verdict = JSON.parse(readFileSync(join(dir, 'verdict.json'), 'utf8')); } catch { /* sem verdict */ }
+    if (!reqIds.length) process.stdout.write('verdict: não exigido (sem [req:])\n');
+    else if (!verdict) process.stdout.write('verdict: ausente — rode `wendkeep verify --deep` + wk-verify\n');
+    else {
+      const v = evaluateVerdict(verdict, reqIds, { tasksHash: tasksHashOf(tarefasMd) });
+      process.stdout.write(`verdict: ${v.ok ? 'ok' : v.stale ? 'stale — re-verifique' : `incompleto: falta ${v.missing.join(', ')}`}\n`);
+    }
+    try { process.stdout.write(`mutation-round: ${readFileSync(join(dir, '.mutation-round'), 'utf8').trim()}/3\n`); } catch { /* sem rodadas */ }
+    process.exit(0);
+  }
+
+  if (sub === 'done' || sub === 'undone') {
+    const taskId = slugArg();
+    if (!taskId) { process.stderr.write(`wendkeep change ${sub}: missing <taskId>\n`); process.exit(2); }
+    const slug = opt(rest, '--change') || activeChange(vaultBase);
+    if (!slug) { process.stderr.write(`wendkeep change ${sub}: no active change\n`); process.exit(2); }
+    const dir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
+    let ok = false;
+    try { ok = setTaskDone(dir, taskId, sub === 'done'); } catch { /* sem tarefas.md */ }
+    if (!ok) { process.stderr.write(`wendkeep change ${sub}: task não encontrada: ${taskId}\n`); process.exit(2); }
+    process.stdout.write(`task ${taskId}: ${sub === 'done' ? '[x]' : '[ ]'}\n`);
+    process.exit(0);
+  }
+
+  if (sub === 'diff') {
+    const slug = slugArg() || activeChange(vaultBase);
+    if (!slug) { process.stderr.write('wendkeep change diff: no change (arg or active)\n'); process.exit(2); }
+    const dir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
+    let specs = [];
+    try { specs = parseSpecsList(readFileSync(join(dir, 'proposta.md'), 'utf8')); }
+    catch { process.stderr.write(`wendkeep change diff: not found: ${slug}\n`); process.exit(2); }
+    if (!specs.length) { process.stdout.write('diff: sem specs declaradas na proposta\n'); process.exit(0); }
+    for (const cap of specs) {
+      let delta;
+      try { delta = parseDelta(readFileSync(join(dir, 'specs', cap, 'spec.md'), 'utf8')); }
+      catch { process.stdout.write(`! sem delta para ${cap}\n`); continue; }
+      process.stdout.write(`spec: ${cap}\n`);
+      for (const r of delta.added) process.stdout.write(`  + ${r.id || r.name} (ADDED)\n`);
+      for (const r of delta.modified) process.stdout.write(`  ~ ${r.id || r.name} (MODIFIED)\n`);
+      for (const k of delta.removed) process.stdout.write(`  - ${k} (REMOVED)\n`);
+      let living = [];
+      try { living = parseRequirements(readFileSync(join(vaultBase, getLocale(vaultBase).folders.specs, `${cap}.md`), 'utf8')); } catch { /* nova capability */ }
+      for (const w of applyDelta(living, delta).warnings) process.stdout.write(`  ! ${w}\n`);
+    }
+    process.exit(0);
+  }
+
   if (sub === 'archive') {
     const slug = slugArg() || activeChange(vaultBase);
     if (!slug) { process.stderr.write('wendkeep change archive: missing <slug> and no active change\n'); process.exit(2); }
@@ -109,6 +189,6 @@ export function runChange(argv) {
     process.exit(0);
   }
 
-  process.stderr.write(`wendkeep change: unknown subcommand "${sub}". Known: new, list, show, archive.\n`);
+  process.stderr.write(`wendkeep change: unknown subcommand "${sub}". Known: new, list, show, status, done, undone, diff, archive.\n`);
   process.exit(2);
 }

package/src/dotcontext-seed.mjs

@@ -37,7 +37,7 @@ export function renderSensorsJson(scripts = {}) {
       });
     }
   }
-  return `${JSON.stringify({ version: 1, source: 'manual', sensors }, null, 2)}\n`;
+  return `${JSON.stringify({ $schema: 'https://raw.githubusercontent.com/rogersialves/wendkeep/main/schema/wendkeep.sensors.schema.json', version: 1, source: 'manual', sensors }, null, 2)}\n`;
 }
 
 function readProjectScripts(projectPath) {

package/src/init.mjs

@@ -33,6 +33,7 @@ import {
 import { renderCoreSkeleton, renderCompactionProtocol } from './validate-core.mjs';
 import { seedDefinitions, syncDefs } from './sync-defs.mjs';
 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';
 
 function parseArgs(argv) {
@@ -40,6 +41,8 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--vault') args.vault = argv[++i];
+    else if (a === '--locale') args.locale = argv[++i];
+    else if (a.startsWith('--locale=')) args.locale = a.slice(9);
     else if (a === '--project') args.project = argv[++i];
     else if (a === '--no-mcp') args.mcp = false;
     else if (a === '--yes' || a === '-y') args.yes = true;
@@ -162,10 +165,11 @@ function runCavemanInstaller(log) {
 // enable it (non-destructive), and add graph color groups. Returns a short note.
 // Unparseable user JSON is left untouched (we only merge into valid/absent files).
 function installVaultColors(vaultPath) {
+  const loc = getLocale(vaultPath);
   const obsidianDir = join(vaultPath, '.obsidian');
   const snippetsDir = join(obsidianDir, 'snippets');
   mkdirSync(snippetsDir, { recursive: true });
-  writeFileSync(join(snippetsDir, `${SNIPPET_NAME}.css`), renderColorSnippetCss(), 'utf8');
+  writeFileSync(join(snippetsDir, `${SNIPPET_NAME}.css`), renderColorSnippetCss(loc), 'utf8');
 
   let enabled = false;
   const appPath = join(obsidianDir, 'appearance.json');
@@ -179,9 +183,9 @@ function installVaultColors(vaultPath) {
   const graphPath = join(obsidianDir, 'graph.json');
   const graphRead = readJsonSafe(graphPath);
   if (graphRead.ok) {
-    const merged = mergeGraphColorGroups(graphRead.data || {}, graphColorGroups());
+    const merged = mergeGraphColorGroups(graphRead.data || {}, graphColorGroups(loc));
     writeJson(graphPath, merged);
-    groups = graphColorGroups().length;
+    groups = graphColorGroups(loc).length;
   }
   return `snippet ${SNIPPET_NAME}.css${enabled ? ' (enabled)' : ' (enable by hand: appearance.json unreadable)'} + ${groups} graph group(s)`;
 }
@@ -253,9 +257,21 @@ export async function runInit(argv) {
   }
 
   // 1. Vault taxonomy ---------------------------------------------------------
+  // Locale (0.8.0): a vault property, locked at init. Written BEFORE folder creation so
+  // the folder names follow it. Invalid/absent = pt-BR (backward compat).
   if (!existsSync(vaultPath)) mkdirSync(vaultPath, { recursive: true });
+  const localeId = args.locale && LOCALES[args.locale] ? args.locale : DEFAULT_LOCALE;
+  if (args.locale && !LOCALES[args.locale]) {
+    log(`  ! locale desconhecido "${args.locale}" — usando ${DEFAULT_LOCALE} (opções: ${Object.keys(LOCALES).join(', ')})`);
+  }
+  mkdirSync(join(vaultPath, '.brain'), { recursive: true });
+  const configPath = join(vaultPath, '.brain', 'config.json');
+  if (!existsSync(configPath)) writeFileSync(configPath, `${JSON.stringify({ locale: localeId }, null, 2)}\n`, 'utf8');
+  clearLocaleCache();
+  const loc = getLocale(vaultPath);
+  const folders = vaultFolders(loc);
   let created = 0;
-  for (const f of VAULT_FOLDERS) {
+  for (const f of folders) {
     const p = join(vaultPath, f);
     if (!existsSync(p)) {
       mkdirSync(p, { recursive: true });
@@ -275,7 +291,7 @@ export async function runInit(argv) {
   const brainDir = join(vaultPath, '.brain');
   mkdirSync(brainDir, { recursive: true });
   const corePath = join(brainDir, 'CORE.md');
-  if (!existsSync(corePath)) writeFileSync(corePath, renderCoreSkeleton(), 'utf8');
+  if (!existsSync(corePath)) writeFileSync(corePath, renderCoreSkeleton(loc.id), 'utf8');
   const protoPath = join(brainDir, 'COMPACTION_PROTOCOL.md');
   if (!existsSync(protoPath)) writeFileSync(protoPath, renderCompactionProtocol(), 'utf8');
   // Seed the definitions layer (.brain/agents + .brain/skills): versioned source of
@@ -283,8 +299,8 @@ export async function runInit(argv) {
   seedDefinitions(brainDir);
   seedWkSkills(brainDir); // Pilar A: native process skills (wk-workflow/tdd/debugging/...).
   // Seed the change/spec layer starters (Pilar B) — non-destructive.
-  const specsReadme = join(vaultPath, '07-Specs', 'README.md');
-  if (!existsSync(specsReadme)) writeFileSync(specsReadme, '# Specs — contrato vivo\n\nCapacidades do projeto (requisitos/cenários). Changes em `08-Mudanças/` promovem deltas aqui no `wendkeep change archive`.\n', 'utf8');
+  const specsReadme = join(vaultPath, loc.folders.specs, 'README.md');
+  if (!existsSync(specsReadme)) writeFileSync(specsReadme, `# Specs — contrato vivo\n\nCapacidades do projeto (requisitos/cenários). Changes em \`${loc.folders.changes}/\` promovem deltas aqui no \`wendkeep change archive\`.\n`, 'utf8');
   const changeTpl = join(vaultPath, 'Templates', 'Change.md');
   if (!existsSync(changeTpl)) writeFileSync(changeTpl, '---\ntype: change\nstatus: active\ncssclasses:\n  - topic-change\n---\n\n# <slug>\n\n## Por quê\n\n## O que muda\n', 'utf8');
   // Seed the native sensor config (Pilar C) at project root — non-destructive.
@@ -294,7 +310,7 @@ export async function runInit(argv) {
     try { scripts = JSON.parse(readFileSync(join(projectPath, 'package.json'), 'utf8')).scripts || {}; } catch { /* no package.json */ }
     writeFileSync(sensorsFile, renderSensorsJson(scripts), 'utf8');
   }
-  log(`  [1/4] vault taxonomy: ${VAULT_FOLDERS.length} folders (${created} created)${readmeNote}, .brain + change/spec + sensors seeded`);
+  log(`  [1/4] vault taxonomy: ${folders.length} folders (${created} created, locale ${loc.id})${readmeNote}, .brain + change/spec + sensors seeded`);
   // Deliver the seeded defs (agents + wk process skills) to the project so they're
   // usable immediately — no separate `wendkeep sync-defs` step needed.
   const synced = syncDefs(vaultPath, projectPath);

package/src/sensors.mjs

@@ -0,0 +1,23 @@
+// `wendkeep sensors list` — read-only view over wendkeep.sensors.json (0.7.0).
+import { resolve } from 'node:path';
+import { loadSensors } from '../hooks/sensors-core.mjs';
+
+export function runSensors(argv) {
+  const [sub, ...rest] = argv;
+  if (sub !== 'list') {
+    process.stderr.write(`wendkeep sensors: unknown subcommand "${sub}". Known: list.\n`);
+    process.exit(2);
+  }
+  let project;
+  for (let i = 0; i < rest.length; i += 1) {
+    if (rest[i] === '--project') project = rest[++i];
+    else if (rest[i].startsWith('--project=')) project = rest[i].slice(10);
+  }
+  const projectRoot = resolve(project || process.cwd());
+  const sensors = loadSensors(projectRoot);
+  if (!sensors.length) { process.stdout.write('sensors: (nenhum — crie wendkeep.sensors.json na raiz)\n'); process.exit(0); }
+  for (const s of sensors) {
+    process.stdout.write(`${s.id}: ${s.type || 'command'} · ${s.severity || 'critical'} · ${s.command}\n`);
+  }
+  process.exit(0);
+}

package/src/spec.mjs

@@ -0,0 +1,54 @@
+// `wendkeep spec <sub>` — read-only views over the living specs in 07-Specs (0.7.0).
+import { readFileSync, readdirSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { parseRequirements } from '../hooks/spec-core.mjs';
+import { getLocale } from '../hooks/locale.mjs';
+
+function resolveVault(argv) {
+  let vault;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--vault') vault = argv[++i];
+    else if (a.startsWith('--vault=')) vault = a.slice(8);
+  }
+  const base = vault || process.env.OBSIDIAN_VAULT_PATH;
+  if (!base) {
+    process.stderr.write('wendkeep spec: no vault. Pass --vault <path> or set OBSIDIAN_VAULT_PATH.\n');
+    process.exit(2);
+  }
+  return isAbsolute(base) ? base : resolve(process.cwd(), base);
+}
+
+export function runSpec(argv) {
+  const [sub, ...rest] = argv;
+  const vaultBase = resolveVault(rest);
+  const specsDir = join(vaultBase, getLocale(vaultBase).folders.specs);
+
+  if (sub === 'list') {
+    let files = [];
+    try { files = readdirSync(specsDir).filter((f) => f.endsWith('.md') && f !== 'README.md'); } catch { /* sem specs */ }
+    if (!files.length) { process.stdout.write('specs: (nenhuma)\n'); process.exit(0); }
+    for (const f of files) {
+      const md = readFileSync(join(specsDir, f), 'utf8');
+      const n = parseRequirements(md).length;
+      const upd = md.match(/> Atualizado por .* em (\d{4}-\d{2}-\d{2})/);
+      process.stdout.write(`${f.replace(/\.md$/, '')}: ${n} requisito(s)${upd ? ` (atualizado ${upd[1]})` : ''}\n`);
+    }
+    process.exit(0);
+  }
+
+  if (sub === 'show') {
+    const cap = rest.find((a, i) => !a.startsWith('-') && rest[i - 1] !== '--vault');
+    if (!cap) { process.stderr.write('wendkeep spec show: missing <capability>\n'); process.exit(2); }
+    let md;
+    try { md = readFileSync(join(specsDir, `${cap}.md`), 'utf8'); }
+    catch { process.stderr.write(`wendkeep spec show: not found: ${cap}\n`); process.exit(2); }
+    const reqs = parseRequirements(md);
+    process.stdout.write(`${cap}: ${reqs.length} requisito(s)\n`);
+    for (const r of reqs) process.stdout.write(`  ${r.id ? `${r.id} — ` : ''}${r.name}\n`);
+    process.exit(0);
+  }
+
+  process.stderr.write(`wendkeep spec: unknown subcommand "${sub}". Known: list, show.\n`);
+  process.exit(2);
+}

package/src/sync-defs.mjs

@@ -5,11 +5,67 @@
 //   .brain/skills/<name>/ -> <project>/.claude/skills/   (skill format)
 // .brain is the source of truth; re-run sync after editing. Copy (not symlink) for
 // cross-platform robustness.
-import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 
+// Managed AGENTS.md section (0.8.0): the agent-agnostic distribution channel. Codex, Amp,
+// Cursor, Zed et al. read AGENTS.md — one file covers them all. Only the content between
+// the markers is ours; user content around it is never touched.
+const AG_START = '<!-- wendkeep:skills:start -->';
+const AG_END = '<!-- wendkeep:skills:end -->';
+
+function skillInventory(skillsSrc) {
+  const out = [];
+  let names = [];
+  try { names = readdirSync(skillsSrc); } catch { return out; }
+  for (const name of names) {
+    try {
+      if (!statSync(join(skillsSrc, name)).isDirectory()) continue;
+      const md = readFileSync(join(skillsSrc, name, 'SKILL.md'), 'utf8');
+      const desc = (md.match(/^description:\s*(.+)$/m) || [])[1] || '';
+      out.push({ name, description: desc.trim() });
+    } catch { /* skill sem SKILL.md */ }
+  }
+  return out;
+}
+
+function renderAgentsSection(skills) {
+  const list = skills.map((s) => `- **${s.name}** — ${s.description}`).join('\n');
+  return `${AG_START}
+## wendkeep — process skills & loop
+
+This project uses the [wendkeep](https://github.com/rogersialves/wendkeep) harness. Work
+through its change loop: \`wendkeep change new <slug>\` → implement tasks test-first
+(tag proof \`[sensor:id]\` and requirement \`[req:ID]\`) → \`wendkeep verify\` →
+\`wendkeep verify --deep\` + an independent read-only verification pass writing
+\`verdict.json\` → \`wendkeep change archive\` (gated). Inspect with \`wendkeep change
+status\` / \`spec list\` / \`sensors list\`.
+
+Process skills (full text in \`.claude/skills/\` and the vault's \`.brain/skills/\`):
+${list}
+${AG_END}`;
+}
+
+function upsertAgentsMd(projectPath, skillsSrc) {
+  const skills = skillInventory(skillsSrc);
+  if (!skills.length) return false;
+  const path = join(projectPath, 'AGENTS.md');
+  const section = renderAgentsSection(skills);
+  let content = '';
+  try { content = readFileSync(path, 'utf8'); } catch { /* novo */ }
+  if (content.includes(AG_START) && content.includes(AG_END)) {
+    const start = content.indexOf(AG_START);
+    const end = content.indexOf(AG_END) + AG_END.length;
+    content = content.slice(0, start) + section + content.slice(end);
+  } else {
+    content = content ? `${content.trimEnd()}\n\n${section}\n` : `${section}\n`;
+  }
+  writeFileSync(path, content, 'utf8');
+  return true;
+}
+
 export function syncDefs(vaultBase, projectPath) {
-  const out = { agents: [], skills: [] };
+  const out = { agents: [], skills: [], agentsMd: false };
 
   const agentsSrc = join(vaultBase, '.brain', 'agents');
   if (existsSync(agentsSrc)) {
@@ -34,6 +90,9 @@ export function syncDefs(vaultBase, projectPath) {
     }
   }
 
+  // Agent-agnostic channel: the managed AGENTS.md section (docs/17).
+  out.agentsMd = upsertAgentsMd(projectPath, skillsSrc);
+
   return out;
 }
 

package/src/taxonomy.mjs

@@ -25,6 +25,7 @@ export const VAULT_FOLDERS = [
 // entrypoints + price table). Mirrors the list the old setup-vault.ps1 copied.
 export const HOOK_FILES = [
   'obsidian-common.mjs',
+  'locale.mjs',
   'session-start.mjs',
   'session-ensure.mjs',
   'session-stop.mjs',

package/src/validate-core.mjs

@@ -11,11 +11,20 @@ import { isAbsolute, join, resolve } from 'node:path';
 const HARD_LIMIT = 25;
 const SOFT_LIMIT = 22;
 
-const REQUIRED_SECTIONS = [
-  { label: 'Preferências do Usuário', regex: /^##\s+Prefer[êe]ncias\s+do\s+Usu[áa]rio\s*$/im },
-  { label: 'Padrões Ativos', regex: /^##\s+Padr[õo]es\s+Ativos\s*$/im },
-  { label: 'Pendências Abertas', regex: /^##\s+Pend[êe]ncias\s+Abertas\s*$/im },
-];
+// Bilingual (0.8.0): a CORE is valid when it carries the COMPLETE section set of either
+// locale — pt-BR or en. Mixed/partial sets fail (the 3 sections are one contract).
+const SECTION_SETS = {
+  'pt-BR': [
+    { label: 'Preferências do Usuário', regex: /^##\s+Prefer[êe]ncias\s+do\s+Usu[áa]rio\s*$/im },
+    { label: 'Padrões Ativos', regex: /^##\s+Padr[õo]es\s+Ativos\s*$/im },
+    { label: 'Pendências Abertas', regex: /^##\s+Pend[êe]ncias\s+Abertas\s*$/im },
+  ],
+  en: [
+    { label: 'User Preferences', regex: /^##\s+User\s+Preferences\s*$/im },
+    { label: 'Active Patterns', regex: /^##\s+Active\s+Patterns\s*$/im },
+    { label: 'Open Items', regex: /^##\s+Open\s+Items\s*$/im },
+  ],
+};
 
 // Secret patterns reject only "real" values (length floor); abstract mentions like
 // `sk_*` / `whsec_*` (trailing asterisk) are allowed.
@@ -41,9 +50,10 @@ export function validateCore(content) {
   if (lineCount > HARD_LIMIT) {
     errors.push(`Tamanho ${lineCount} > ${HARD_LIMIT} linhas (hard limit). Curar: remover itens resolvidos (detalhe vive no vault/git).`);
   }
-  for (const { label, regex } of REQUIRED_SECTIONS) {
-    if (!regex.test(text)) errors.push(`Seção obrigatória ausente: ## ${label}`);
-  }
+  // Pick the locale set that matches best; require it to be complete.
+  const missingBySet = Object.values(SECTION_SETS).map((set) => set.filter(({ regex }) => !regex.test(text)));
+  const best = missingBySet.reduce((a, b) => (b.length < a.length ? b : a));
+  for (const { label } of best) errors.push(`Seção obrigatória ausente: ## ${label}`);
   for (const { name, regex } of SECRET_PATTERNS) {
     const m = text.match(regex);
     if (m) errors.push(`Possível ${name} detectado: "${m[0].slice(0, 30)}..." — substituir por [REDACTED_SECRET].`);
@@ -61,7 +71,22 @@ export function validateCore(content) {
 
 // The seeded CORE.md (must pass validateCore). Bootstraps the 3 sections so the
 // curated hot layer exists with the right shape from day one.
-export function renderCoreSkeleton() {
+export function renderCoreSkeleton(localeId = 'pt-BR') {
+  if (localeId === 'en') {
+    return `# CORE — curated memory core (.brain)
+
+> RULE #1 — the project's canonical memory. Hand-curated, 25-line cap (validate: \`wendkeep validate-memory\`). Volatile facts live in DIGEST.md (auto). Depth: /brain-recall <topic>.
+
+## User Preferences
+- (durable preferences: language, style, conventions)
+
+## Active Patterns
+- (active patterns/architecture another agent must know)
+
+## Open Items
+- (open items/decisions — remove when resolved)
+`;
+  }
   return `# CORE — núcleo curado da memória (.brain)
 
 > REGRA #1 — memória canônica do projeto. Curado à mão, cap 25 linhas (valide: \`wendkeep validate-memory\`). Volátil vive no DIGEST.md (auto). Profundidade: /brain-recall <tópico>.

package/src/vault-theme.mjs

@@ -8,6 +8,9 @@
 
 export const SNIPPET_NAME = 'wendkeep-colors';
 
+import { LOCALES } from '../hooks/locale.mjs';
+const PT = LOCALES['pt-BR'];
+
 // Base palette (hex + "r, g, b" for rgba()).
 const PALETTE = {
   blue: { hex: '#2f80ed', rgb: '47, 128, 237' },
@@ -20,42 +23,49 @@ const PALETTE = {
   slate: { hex: '#64748b', rgb: '100, 116, 139' },
 };
 
-// File-explorer folder -> palette key (mirrors VAULT_FOLDERS in taxonomy.mjs).
-const FOLDER_PALETTE = [
-  ['00-Inbox', 'amber'],
-  ['01-Projeto', 'indigo'],
-  ['02-Sessões', 'blue'],
-  ['03-Linear', 'teal'],
-  ['04-Decisões', 'violet'],
-  ['05-Bugs', 'red'],
-  ['06-Aprendizados', 'green'],
-  ['07-Specs', 'teal'],
-  ['08-Mudanças', 'amber'],
-  ['Templates', 'slate'],
-];
-
-// Note cssclass -> palette key; `folder` is reused for the graph color groups.
-export const NOTE_COLORS = {
-  session: { cssClass: 'topic-session', folder: '02-Sessões', palette: 'blue' },
-  decision: { cssClass: 'topic-decision', folder: '04-Decisões', palette: 'violet' },
-  bug: { cssClass: 'topic-bug', folder: '05-Bugs', palette: 'red' },
-  learning: { cssClass: 'topic-learning', folder: '06-Aprendizados', palette: 'green' },
-  spec: { cssClass: 'topic-spec', folder: '07-Specs', palette: 'teal' },
-  change: { cssClass: 'topic-change', folder: '08-Mudanças', palette: 'amber' },
+// File-explorer folder KEY -> palette key; folder names resolve via the vault locale.
+const PALETTE_BY_KEY = {
+  inbox: 'amber',
+  project: 'indigo',
+  sessions: 'blue',
+  linear: 'teal',
+  decisions: 'violet',
+  bugs: 'red',
+  learnings: 'green',
+  specs: 'teal',
+  changes: 'amber',
+};
+function folderPalette(loc) {
+  return [...Object.entries(PALETTE_BY_KEY).map(([k, p]) => [loc.folders[k], p]), ['Templates', 'slate']];
+}
+
+// Note cssclass -> palette + locale folder key; `folder` resolves per locale.
+const NOTE_TYPES = {
+  session: { cssClass: 'topic-session', folderKey: 'sessions', palette: 'blue' },
+  decision: { cssClass: 'topic-decision', folderKey: 'decisions', palette: 'violet' },
+  bug: { cssClass: 'topic-bug', folderKey: 'bugs', palette: 'red' },
+  learning: { cssClass: 'topic-learning', folderKey: 'learnings', palette: 'green' },
+  spec: { cssClass: 'topic-spec', folderKey: 'specs', palette: 'teal' },
+  change: { cssClass: 'topic-change', folderKey: 'changes', palette: 'amber' },
 };
+// Legacy pt-shaped export (folder names resolved at pt-BR) kept for compat.
+export const NOTE_COLORS = Object.fromEntries(
+  Object.entries(NOTE_TYPES).map(([k, v]) => [k, { cssClass: v.cssClass, folder: PT.folders[v.folderKey], palette: v.palette }]),
+);
 
-// cssclasses that get the note-accent treatment (the four note types + a home note).
-const TOPIC_CLASSES = [...Object.values(NOTE_COLORS).map((n) => n.cssClass), 'vault-home'];
+// cssclasses that get the note-accent treatment (the note types + a home note).
+const TOPIC_CLASSES = [...Object.values(NOTE_TYPES).map((n) => n.cssClass), 'vault-home'];
 const NOTE_ACCENTS = [
-  ...Object.values(NOTE_COLORS).map((n) => ({ cssClass: n.cssClass, palette: n.palette })),
+  ...Object.values(NOTE_TYPES).map((n) => ({ cssClass: n.cssClass, palette: n.palette })),
   { cssClass: 'vault-home', palette: 'indigo' },
 ];
 
 const FX = '.workspace-leaf-content[data-type="file-explorer"] .nav-folder-title';
-const folderSel = FOLDER_PALETTE.map(([f]) => `[data-path^="${f}"]`).join(',\n  ');
 const topicReading = TOPIC_CLASSES.map((c) => `.${c}`).join(', ');
 
-export function renderColorSnippetCss() {
+export function renderColorSnippetCss(loc = PT) {
+  const FOLDER_PALETTE = folderPalette(loc);
+  const folderSel = FOLDER_PALETTE.map(([f]) => `[data-path^="${f}"]`).join(',\n  ');
   const rootVars = Object.entries(PALETTE)
     .map(([k, v]) => `  --us-${k}: ${v.hex};\n  --us-${k}-rgb: ${v.rgb};`)
     .join('\n');
@@ -181,9 +191,9 @@ export function mergeAppearance(existing, snippetName = SNIPPET_NAME) {
 }
 
 // Graph color groups: one per note folder, colored from the palette.
-export function graphColorGroups() {
-  return Object.values(NOTE_COLORS).map((v) => ({
-    query: `path:"${v.folder}"`,
+export function graphColorGroups(loc = PT) {
+  return Object.values(NOTE_TYPES).map((v) => ({
+    query: `path:"${loc.folders[v.folderKey]}"`,
     color: { a: 1, rgb: parseInt(PALETTE[v.palette].hex.slice(1), 16) },
   }));
 }

package/src/verify.mjs

@@ -7,6 +7,7 @@ import { parseTasks, activeChange, appendFixTasks } from '../hooks/change-core.m
 import { loadSensors, requiredSensors, runSensors, evaluateGate } from '../hooks/sensors-core.mjs';
 import { tasksHashOf } from '../hooks/spec-core.mjs';
 import { addLesson } from '../hooks/lessons-core.mjs';
+import { getLocale } from '../hooks/locale.mjs';
 
 function today() {
   const d = new Date();
@@ -28,7 +29,7 @@ export function runVerify(argv) {
   const slug = opt(argv, '--change') || activeChange(vaultBase);
   if (!slug) { process.stderr.write('wendkeep verify: no change (--change or active).\n'); process.exit(2); }
 
-  const changeDir = join(vaultBase, '08-Mudanças', slug);
+  const changeDir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
   let tarefas = '';
   try { tarefas = readFileSync(join(changeDir, 'tarefas.md'), 'utf8'); }
   catch { process.stderr.write(`wendkeep verify: change not found: ${slug}\n`); process.exit(2); }