wendkeep 0.7.0 → 0.8.1

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 });
@@ -266,7 +282,7 @@ export async function runInit(argv) {
   const readmePath = join(vaultPath, 'README.md');
   let readmeNote = '';
   if (!existsSync(readmePath)) {
-    writeFileSync(readmePath, renderVaultReadme({ projectName: basename(projectPath), vaultPath, withMcp: args.mcp }), 'utf8');
+    writeFileSync(readmePath, renderVaultReadme({ projectName: basename(projectPath), vaultPath, withMcp: args.mcp, locale: loc.id }), 'utf8');
     readmeNote = ', README.md created';
   }
   // Seed the curated memory layer (CORE.md) + the compaction-protocol doc. The
@@ -275,18 +291,27 @@ 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
   // truth for custom agents/skills. `wendkeep sync-defs` copies them to the agent dirs.
   seedDefinitions(brainDir);
-  seedWkSkills(brainDir); // Pilar A: native process skills (wk-workflow/tdd/debugging/...).
+  seedWkSkills(brainDir, loc.id); // Pilar A: native process skills, in the vault locale.
   // 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 en = loc.id === 'en';
+  const specsReadme = join(vaultPath, loc.folders.specs, 'README.md');
+  if (!existsSync(specsReadme)) {
+    writeFileSync(specsReadme, en
+      ? `# Specs — living contract\n\nThe project's capabilities (requirements/scenarios). Changes in \`${loc.folders.changes}/\` promote deltas here on \`wendkeep change archive\`.\n`
+      : `# 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');
+  if (!existsSync(changeTpl)) {
+    writeFileSync(changeTpl, en
+      ? '---\ntype: change\nstatus: active\ncssclasses:\n  - topic-change\n---\n\n# <slug>\n\n## Why\n\n## What changes\n'
+      : '---\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.
   const sensorsFile = join(projectPath, 'wendkeep.sensors.json');
   if (!existsSync(sensorsFile)) {
@@ -294,7 +319,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/skills-seed.mjs

@@ -203,7 +203,135 @@ nunca tivesse visto a implementação. Contexto fresco, read-only.
 - O gate do \`archive\` **exige** \`verdict.json\` com \`ok\` cobrindo todo \`[req:]\`. Sem isso, não arquiva.
 `;
 
-export const WK_SKILLS = [
+const WORKFLOW_EN = `# The a2 loop — wendkeep's work cycle
+
+Use it when starting any non-trivial change. The loop keeps memory (vault) and proof
+(sensors) together, wikilinked in the Obsidian graph.
+
+## Steps
+
+1. **Explore** — understand the problem before proposing.
+2. **Propose** — \`wendkeep change new <slug>\` scaffolds \`08-Changes/<slug>/\`
+   (proposta/design/tarefas + a \`specs/\` delta). The change becomes *active* and is
+   injected at the next SessionStart.
+3. **Apply** — implement each task in tarefas.md with **wk-tdd** (red test first). Tag tasks:
+   \`[sensor:<id>]\` (automated proof) and \`[req:<ID>]\` (the spec requirement it satisfies).
+4. **Verify** — \`wendkeep verify\` runs the sensors; then \`wendkeep verify --deep\` builds
+   the verification package.
+5. **Verify deep** — the **wk-verify** skill (fresh, author≠verifier) writes \`verdict.json\`.
+   A trivial change (no \`[req:]\`) gets an auto verdict.
+6. **Archive** — \`wendkeep change archive <slug>\`. The gate needs green sensors AND a
+   verdict AND no open tasks. It promotes the delta into \`07-Specs\` and mints an ADR.
+
+## Rules
+- One active change at a time. Finish (archive) before starting another.
+- No \`[sensor:]\` on a task = no automated gate for it. No \`[req:]\` = no independent verdict.
+- The graph links session ↔ change ↔ requirement ↔ decision. That is the point.
+`;
+
+const TDD_EN = `# TDD — Red, Green, Refactor (tests that discriminate)
+
+Never write production code without a red test asking for it — and never write a test that
+would pass under the wrong implementation.
+
+## The cycle
+1. **Red** — the smallest test that fails for the missing behaviour.
+2. **See it fail** for the right reason (not an import/typo).
+3. **Green** — the minimal code to pass.
+4. **Refactor** with the greens protecting you.
+
+## Derive from the spec, not the code
+Write assertions from the requirement's acceptance criteria (\`07-Specs\`), not by reading the
+implementation. Reading the code to write the test = it only confirms what the code already does.
+
+## Non-shallow litmus
+Reject an assertion that would pass under a wrong implementation. Assert a **value or persisted
+state**, never "the mock was called". "Tested later" is rejected.
+
+## Adequacy (necessary and sufficient)
+Every acceptance criterion has an assertion with \`file:line\` evidence; every test traces to a
+requirement (\`[req:ID]\`); covers what the spec asks, nothing more.
+
+## Learn the project
+Sample 5–10 existing tests for style/location/framework/depth (treat that depth as a floor).
+Read \`AGENTS.md\` / \`.cursor/rules\` / CI configs for declared standards.
+`;
+
+const DEBUGGING_EN = `# Systematic debugging
+
+Use it when something fails or behaves wrong. One hypothesis at a time — no shotgun changes.
+
+1. **Reproduce** — a minimal deterministic case. Without it you can't know you fixed anything.
+2. **One hypothesis** — the most likely cause, specific enough to test.
+3. **Isolate** — confirm or kill the hypothesis BEFORE fixing (bisect, log, comment half). Prove
+   where it is, not where you think it is.
+4. **Fix the root**, not the symptom.
+5. **Verify** — the repro is gone AND the suite stays green. No regression.
+
+Changed several things and it "worked"? You don't know what fixed it — revert, isolate one
+variable. Read the whole error + stack — the decisive line is usually there.
+`;
+
+const BRAINSTORMING_EN = `# Brainstorming — idea into design
+
+Use it when the idea is still vague. Turn it into an approved design BEFORE writing code.
+
+1. **Explore context** — files, docs, relevant history.
+2. **One question at a time** — purpose, constraints, success criteria. Prefer multiple choice.
+3. **Propose 2–3 approaches** with trade-offs and your recommendation.
+4. **Present the design in sections**, confirm each.
+
+## Closure gate — no dangling ambiguity
+Resolve every gray area: decide with the user, or log a **signed-off assumption** ("assuming X
+because Y — correct me if wrong"). A declined gray area is recorded, not silently dropped.
+
+## Out-of-scope table
+List explicitly what the change does **not** do. Undeclared scope becomes creep.
+
+## Hard gate
+No code / scaffold / implementation action until a design is presented and approved. Then go to
+**wk-planning**.
+`;
+
+const PLANNING_EN = `# Planning — design into a task plan
+
+Use it after an approved design. Produce a plan an engineer with no project context can execute.
+
+## Before tasks
+Map the files: what to create/modify and each one's responsibility. Files that change together
+live together; one file, one responsibility.
+
+## Bite-sized tasks (TDD)
+Each task ends in an independently testable deliverable. Each step is a 2–5 min action:
+write the failing test (show code) → run and see it fail (exact command + expected) → minimal
+implementation (show code) → run and see it pass → checkpoint: suite green.
+
+## Rules
+- Exact file paths, always. Real code in each step — no "TODO", "handle errors appropriately",
+  "similar to Task N". DRY, YAGNI. Consistent names/signatures across tasks.
+`;
+
+const VERIFY_EN = `# Independent verification — the fresh pass
+
+Use it in the *verify deep* step, after \`wendkeep verify --deep\`. You are the **verifier**, not
+the author — even if you wrote the code, enter as if you'd never seen it. Fresh context, read-only.
+
+## What to do
+1. Read the package \`08-Changes/<slug>/verificacao.json\` (requirements, tasks, evidence).
+2. **Re-derive coverage from \`07-Specs\`** — for each \`[req:ID]\`, check the requirement's behaviour
+   is covered by a test that discriminates (wouldn't pass under a wrong impl). \`file:line\` evidence.
+3. Spec-anchored outcome check: does the observable result match the acceptance criterion?
+4. Write \`08-Changes/<slug>/verdict.json\`:
+   \`{ "slug": "...", "ok": true, "coverage": [{ "req": "GATE-1", "covered": true, "evidence": "file:line" }], "tasksHash": "<copy from the package>", "notes": [] }\`.
+
+## Rules
+- **Author ≠ verifier.** On Claude, spawn a read-only sub-agent for real isolation.
+- \`ok: false\` if any requirement lacks discriminating coverage. A gap is red, not "almost".
+- Don't fix here — a gap becomes a fix task; re-verify after.
+- The archive gate **requires** a fresh \`verdict.json\` (matching \`tasksHash\`) covering every \`[req:]\`.
+`;
+
+const WK_SKILLS_PT = [
   skill('wk-workflow', 'Use ao começar qualquer mudança não-trivial — orquestra o loop a2 (explore, propose, apply, verify, archive) nos comandos wendkeep.', WORKFLOW),
   skill('wk-tdd', 'Use ao implementar qualquer comportamento — Red/Green/Refactor com testes que discriminam (derivados do spec, litmus não-raso, adequação).', TDD),
   skill('wk-debugging', 'Use quando algo falha ou quebra — depuração sistemática por hipótese antes de corrigir.', DEBUGGING),
@@ -212,10 +340,25 @@ export const WK_SKILLS = [
   skill('wk-verify', 'Use no verify deep — passe independente read-only (autor≠verificador) que re-deriva a cobertura do spec e grava verdict.json.', VERIFY),
 ];
 
+const WK_SKILLS_EN = [
+  skill('wk-workflow', 'Use when starting any non-trivial change — orchestrates the a2 loop (explore, propose, apply, verify, archive) over the wendkeep commands.', WORKFLOW_EN),
+  skill('wk-tdd', 'Use when implementing any behaviour — Red/Green/Refactor with tests that discriminate (spec-derived, non-shallow litmus, adequacy).', TDD_EN),
+  skill('wk-debugging', 'Use when something fails or breaks — systematic hypothesis-driven debugging before fixing.', DEBUGGING_EN),
+  skill('wk-brainstorming', 'Use when the idea is still vague — turns it into an approved design, with a closure gate and out-of-scope table, before code.', BRAINSTORMING_EN),
+  skill('wk-planning', 'Use after an approved design — decomposes it into a bite-sized TDD task plan.', PLANNING_EN),
+  skill('wk-verify', 'Use in verify deep — an independent read-only pass (author≠verifier) that re-derives spec coverage and writes verdict.json.', VERIFY_EN),
+];
+
+// Skill set for a locale. WK_SKILLS stays the pt-BR set for back-compat.
+export function wkSkills(localeId = 'pt-BR') {
+  return localeId === 'en' ? WK_SKILLS_EN : WK_SKILLS_PT;
+}
+export const WK_SKILLS = WK_SKILLS_PT;
+
 // Seed each skill into <brainDir>/skills/<name>/SKILL.md if absent (non-destructive).
-export function seedWkSkills(brainDir) {
+export function seedWkSkills(brainDir, localeId = 'pt-BR') {
   const created = [];
-  for (const s of WK_SKILLS) {
+  for (const s of wkSkills(localeId)) {
     const dir = join(brainDir, 'skills', s.name);
     mkdirSync(dir, { recursive: true });
     const f = join(dir, 'SKILL.md');

package/src/spec.mjs

@@ -2,6 +2,7 @@
 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;
@@ -21,7 +22,7 @@ function resolveVault(argv) {
 export function runSpec(argv) {
   const [sub, ...rest] = argv;
   const vaultBase = resolveVault(rest);
-  const specsDir = join(vaultBase, '07-Specs');
+  const specsDir = join(vaultBase, getLocale(vaultBase).folders.specs);
 
   if (sub === 'list') {
     let files = [];

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-readme.mjs

@@ -1,46 +1,90 @@
 // 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',
+// Locale-aware (0.8.1): the structure table + prose follow the vault locale; folder names
+// come from the locale so they can never drift from what `wendkeep init` creates.
+import { LOCALES, vaultFolders } from '../hooks/locale.mjs';
+
+// Folder descriptions keyed by locale folder KEY (not literal name), per locale.
+const DESC = {
+  'pt-BR': {
+    inbox: 'Notas rápidas, captura sem classificação',
+    project: 'Arquitetura, padrões, memória do projeto',
+    sessions: 'Uma nota por sessão de trabalho com o agente IA',
+    linear: 'Espelho de issues/tarefas do seu tracker (Linear, Jira, GitHub Issues…)',
+    decisions: 'Architecture Decision Records (ADRs)',
+    bugs: 'Bugs resolvidos com causa raiz documentada',
+    learnings: 'Lições extraídas das sessões',
+    specs: 'Contrato vivo: capacidades do projeto (requisitos)',
+    changes: 'Mudanças em andamento (proposta/design/tarefas/spec-delta)',
+    Templates: 'Templates para novas notas',
+    '.brain': 'Memória canônica: CORE.md (curado) + DIGEST.md (auto), injetada no SessionStart',
+  },
+  en: {
+    inbox: 'Quick notes, unclassified capture',
+    project: 'Architecture, patterns, project memory',
+    sessions: 'One note per AI-agent work session',
+    linear: 'Mirror of issues/tasks from your tracker (Linear, Jira, GitHub Issues…)',
+    decisions: 'Architecture Decision Records (ADRs)',
+    bugs: 'Fixed bugs with documented root cause',
+    learnings: 'Lessons extracted from sessions',
+    specs: 'Living contract: the project capabilities (requirements)',
+    changes: 'Changes in flight (proposal/design/tasks/spec-delta)',
+    Templates: 'Templates for new notes',
+    '.brain': 'Canonical memory: CORE.md (curated) + DIGEST.md (auto), injected at 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');
+// folder literal -> key, for description lookup.
+function keyForFolder(loc, folder) {
+  const entry = Object.entries(loc.folders).find(([, name]) => name === folder);
+  return entry ? entry[0] : folder; // Templates / .brain fall through as themselves
 }
 
-export function renderVaultReadme({ projectName, vaultPath, withMcp = true }) {
-  const name = projectName || 'projeto';
-  const mcpIntro = withMcp ? ', e lida/escrita pelo MCP server **MCPVault**' : '';
+export function renderVaultReadme({ projectName, vaultPath, withMcp = true, locale = 'pt-BR' }) {
+  const loc = LOCALES[locale] || LOCALES['pt-BR'];
+  const en = loc.id === 'en';
+  const desc = DESC[loc.id] || DESC['pt-BR'];
+  const name = projectName || (en ? 'project' : 'projeto');
+
+  const rows = vaultFolders(loc).map((f) => `| \`${f}/\` | ${desc[keyForFolder(loc, f)] || (en ? 'Project notes' : 'Notas do projeto')} |`);
+  const table = [en ? '| Folder | Contents |' : '| Pasta | Conteúdo |', '| --- | --- |', ...rows].join('\n');
+
+  if (en) {
+    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`).');
+    return `# Obsidian vault — ${name}
+
+> Knowledge base of **${name}**, captured automatically by wendkeep from AI coding-agent
+> sessions (**Claude Code**, **Codex**) via session hooks${mcpIntro}.
+
+## Structure
+
+${table}
+
+## Access
 
-  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.join('\n')}
+
+## Rules
+
+1. Every relevant work session produces a note in \`${loc.folders.sessions}/\` (automatic, via hooks).
+2. Architecture decisions become ADRs in \`${loc.folders.decisions}/\`.
+3. Bugs with a root cause go to \`${loc.folders.bugs}/\`; lessons to \`${loc.folders.learnings}/\`.
+4. Canonical memory: \`.brain/CORE.md\` (curated) + \`.brain/DIGEST.md\` (auto) — injected at SessionStart.
+5. Tags in YAML frontmatter, not inline. Wikilinks \`[[note]]\` to connect notes.
+
+## Notes
+
+- **Locale:** this vault is \`en\` (folder names in English). Set at \`wendkeep init --locale\`; a vault is never renamed after.
+- **Versioning:** session notes may contain transcript excerpts — review before committing this vault to a shared repo.
+`;
   }
-  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`).',
-  );
 
+  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`).');
   return `# Vault Obsidian — ${name}
 
 > Base de conhecimento de **${name}**, capturada automaticamente pelo wendkeep a
@@ -49,7 +93,7 @@ export function renderVaultReadme({ projectName, vaultPath, withMcp = true }) {
 
 ## Estrutura
 
-${structureTable()}
+${table}
 
 ## Acesso
 
@@ -57,17 +101,15 @@ ${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/\`.
+1. Toda sessão de trabalho relevante gera nota em \`${loc.folders.sessions}/\` (automático, pelos hooks).
+2. Decisões de arquitetura viram ADR em \`${loc.folders.decisions}/\`.
+3. Bugs com causa raiz vão para \`${loc.folders.bugs}/\`; lições para \`${loc.folders.learnings}/\`.
 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.
+5. Tags em frontmatter YAML, não inline. Wikilinks \`[[nota]]\` para conectar notas.
 
 ## 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.
+- **Locale:** este vault é \`pt-BR\` (nomes de pasta em português). Definido em \`wendkeep init --locale\`; o vault nunca é renomeado depois.
+- **Versionamento:** as notas de sessão podem conter trechos de transcript — avalie antes de commitar este vault em um repositório compartilhado.
 `;
 }