wendkeep 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ 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.9.0] — 2026-07-06
+
+Engineering debt: sensor editing + i18n coherence for auto-generated notes.
+
+### Added
+- **`wendkeep sensors add <id> "<command>"`** (`--severity` / `--type` / `--report` / `--name`
+  / `--description`) — append a sensor to `wendkeep.sensors.json` (creates the file with
+  `$schema` when absent, dedups by id) instead of hand-editing JSON.
+- **Locale-aware derived notes:** the auto-generated bug/decision/learning notes render their
+  headings + callout in the vault locale — an `en` vault no longer gets Portuguese headings.
+
+### Deferred (with reason)
+- `migrate-locale`: renaming a populated vault breaks every wikilink to the old folder names;
+  needs a backlink-repair pass — its own effort, not a patch.
+- Code-hash verdict freshness: a change carries no file manifest, so "the code" is undefined;
+  the existing `tarefas.md` hash already blocks task drift.
+
+## [0.8.1] — 2026-07-06
+
+Polish: i18n coherence + presentation.
+
+### Added
+- **Locale-aware process skills + vault docs:** an `en` vault now seeds the `wk-*` skills,
+  the vault README, the change template, and the specs README in English (previously
+  Portuguese regardless of locale). Completes the `--locale en` promise.
+- **`wendkeep.sensors.json` at the repo root** — the project gates itself with its own
+  test/check sensors (dogfooding the harness).
+
+### Changed
+- npm `description` now describes the harness + a2 loop (was capture-only).
+- CI: `actions/checkout` and `actions/setup-node` bumped to `v5` (v4 runner deprecation).
+- README: the i18n "known limitation" is resolved.
+
 ## [0.8.0] — 2026-07-05
 
 Reach: internationalization + agent-agnostic distribution.
@@ -180,6 +213,8 @@ Initial release — the capture engine, extracted from a system in daily product
 - `wendkeep init` (cross-platform installer) + optional `@bitbonsai/mcpvault` MCP server.
 
 <!-- Only v0.4.0+ is tagged in git (history starts here); older versions link to npm. -->
+[0.9.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.9.0
+[0.8.1]: https://github.com/rogersialves/wendkeep/releases/tag/v0.8.1
 [0.8.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.8.0
 [0.7.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.7.0
 [0.6.1]: https://github.com/rogersialves/wendkeep/releases/tag/v0.6.1

package/README.md

@@ -136,7 +136,7 @@ The agent's settings.json points each hook at `npx wendkeep hook …`. On `Stop`
 
 ## Known limitations (`v0.1`)
 
-- **Vault folder names and month labels are Portuguese** (`02-Sessões`, `04-Decisões`, …), hardcoded in the hooks. Internationalization is not done yet — the taxonomy `wendkeep init` creates matches what the hooks expect on purpose.
+- **Vault folder names default to Portuguese** (`02-Sessões`, `04-Decisões`, …). Pass `wendkeep init --locale en` for an English vault (`02-Sessions`, `04-Decisions`, English scaffold/skills). The locale is a vault property, locked at init; parsers are bilingual so mixed content never breaks.
 - **Search is keyword/frontmatter scoring**, not on‑device embeddings (that's on the roadmap).
 - **Transcript formats are agent‑internal** and can change between agent versions; parsing is isolated but may need updates.
 - Installer wires **Claude Code** settings + `.mcp.json`. Codex hooks run on the same scripts but are not auto‑wired yet.

package/bin/wendkeep.mjs

@@ -46,7 +46,7 @@ Usage:
   wendkeep change <sub>        Change lifecycle: new [--simple] | list | show | status |
                            done <id> | undone <id> | diff | archive [--force].
   wendkeep spec <sub>          Living specs: list | show <capability>.
-  wendkeep sensors list        Show the sensors from wendkeep.sensors.json.
+  wendkeep sensors <sub>       list | add <id> "<command>" [--severity --type --report].
   wendkeep verify [--change s] Run a change's task sensors + record evidence (the gate).
   wendkeep lesson add "t" "l"   Record a project-local lesson (injected at SessionStart).
   wendkeep validate-memory [path]  Validate .brain/CORE.md against the compaction

package/hooks/linked-notes.mjs

@@ -162,7 +162,28 @@ export function extractBugDetails(tx) {
   };
 }
 
-export function buildBugNoteContent(bug, issueRef, dateStr, sessionRel, provider = providerMeta(), contentKey = derivedContentKey(bug.rootCause)) {
+// Locale labels for the auto-generated derived notes (0.9.0). Output-only — the extraction
+// heuristics are untouched. Default pt-BR keeps existing behaviour for every legacy caller.
+const NOTE_LABELS = {
+  'pt-BR': {
+    autoTag: 'Auto-gerada', autoLine: (p) => `Nota criada automaticamente pelo hook Stop do ${p}.`, session: 'Sessão',
+    verify: '_Extraído da sessão — verificar._', complete: '_Extraído da sessão — complementar._',
+    bug: { symptom: 'Sintoma', rootCause: 'Causa raiz', fix: 'Correção', files: 'Arquivos alterados', evidence: 'Evidência', lessons: 'Lições aprendidas', noFix: '_Nenhuma correção explícita detectada._', seeSession: '_Ver sessão vinculada._', addEvidence: '_Adicionar evidência empírica._' },
+    dec: { context: 'Contexto', decision: 'Decisão', consequences: 'Consequências', alternatives: 'Alternativas consideradas', noAlt: '_Nenhuma alternativa registrada automaticamente._' },
+    learn: { title: 'Aprendizado', context: 'Contexto', learned: 'O que aprendemos', future: 'Como aplicar no futuro', futureHint: '_Registrar como este conhecimento pode ser reutilizado._' },
+  },
+  en: {
+    autoTag: 'Auto-generated', autoLine: (p) => `Note created automatically by the ${p} Stop hook.`, session: 'Session',
+    verify: '_Extracted from the session — verify._', complete: '_Extracted from the session — complete._',
+    bug: { symptom: 'Symptom', rootCause: 'Root cause', fix: 'Fix', files: 'Changed files', evidence: 'Evidence', lessons: 'Lessons learned', noFix: '_No explicit fix detected._', seeSession: '_See the linked session._', addEvidence: '_Add empirical evidence._' },
+    dec: { context: 'Context', decision: 'Decision', consequences: 'Consequences', alternatives: 'Alternatives considered', noAlt: '_No alternative recorded automatically._' },
+    learn: { title: 'Learning', context: 'Context', learned: 'What we learned', future: 'How to apply in future', futureHint: '_Record how this knowledge can be reused._' },
+  },
+};
+function noteLabels(localeId) { return NOTE_LABELS[localeId] || NOTE_LABELS['pt-BR']; }
+
+export function buildBugNoteContent(bug, issueRef, dateStr, sessionRel, provider = providerMeta(), contentKey = derivedContentKey(bug.rootCause), localeId = 'pt-BR') {
+  const L = noteLabels(localeId);
   const title = issueRef
     ? `${issueRef} - ${normalizeInline(bug.rootCause, 80)}`
     : normalizeInline(bug.rootCause, 80);
@@ -184,31 +205,31 @@ issue: ${yamlQuote(issueRef || '')}
 
 # Bug - ${title}
 
-> [!note] Auto-gerada
-> Nota criada automaticamente pelo hook Stop do ${provider.label}.
-> Sessão: ${wikilinkFromRel(sessionRel)}
+> [!note] ${L.autoTag}
+> ${L.autoLine(provider.label)}
+> ${L.session}: ${wikilinkFromRel(sessionRel)}
 
-## Sintoma
+## ${L.bug.symptom}
 
-${bug.symptom || '_Extraído da sessão — verificar._'}
+${bug.symptom || L.verify}
 
-## Causa raiz
+## ${L.bug.rootCause}
 
 ${bug.rootCause}
 
-## Correção
+## ${L.bug.fix}
 
-${markdownList(bug.fixes, '_Nenhuma correção explícita detectada._')}
+${markdownList(bug.fixes, L.bug.noFix)}
 
-## Arquivos alterados
+## ${L.bug.files}
 
-${markdownList(bug.changedFiles.map((file) => `\`${file}\``), '_Ver sessão vinculada._')}
+${markdownList(bug.changedFiles.map((file) => `\`${file}\``), L.bug.seeSession)}
 
-## Evidência
+## ${L.bug.evidence}
 
-${markdownList(bug.evidence, '_Adicionar evidência empírica._')}
+${markdownList(bug.evidence, L.bug.addEvidence)}
 
-## Lições aprendidas
+## ${L.bug.lessons}
 
 ${bug.lessons}
 `;
@@ -309,7 +330,8 @@ export function extractDecisionDetails(tx) {
   };
 }
 
-export function buildDecisionNoteContent(decision, adrNum, dateStr, sessionRel, provider = providerMeta(), contentKey = derivedContentKey(decision.title)) {
+export function buildDecisionNoteContent(decision, adrNum, dateStr, sessionRel, provider = providerMeta(), contentKey = derivedContentKey(decision.title), localeId = 'pt-BR') {
+  const L = noteLabels(localeId);
   const adrId = `ADR-${String(adrNum).padStart(3, '0')}`;
   return `---
 type: decision
@@ -327,25 +349,25 @@ superseded_by: ""
 
 # ${adrId} - ${decision.title}
 
-> [!note] Auto-gerada
-> Nota criada automaticamente pelo hook Stop do ${provider.label}.
-> Sessão: ${wikilinkFromRel(sessionRel)}
+> [!note] ${L.autoTag}
+> ${L.autoLine(provider.label)}
+> ${L.session}: ${wikilinkFromRel(sessionRel)}
 
-## Contexto
+## ${L.dec.context}
 
-${decision.context || '_Extraído da sessão — complementar._'}
+${decision.context || L.complete}
 
-## Decisão
+## ${L.dec.decision}
 
 ${decision.detail}
 
-## Consequências
+## ${L.dec.consequences}
 
 ${decision.consequences}
 
-## Alternativas consideradas
+## ${L.dec.alternatives}
 
-${markdownList(decision.alternatives, '_Nenhuma alternativa registrada automaticamente._')}
+${markdownList(decision.alternatives, L.dec.noAlt)}
 `;
 }
 
@@ -413,7 +435,8 @@ export function extractLearningDetails(tx, bugDetails) {
   return learnings.length ? learnings.slice(0, 5) : null;
 }
 
-export function buildLearningNoteContent(learning, dateStr, sessionRel, provider = providerMeta(), contentKey = derivedContentKey(learning.title)) {
+export function buildLearningNoteContent(learning, dateStr, sessionRel, provider = providerMeta(), contentKey = derivedContentKey(learning.title), localeId = 'pt-BR') {
+  const L = noteLabels(localeId);
   return `---
 type: learning
 date: ${dateStr}
@@ -427,23 +450,23 @@ tags:
 ${yamlTags(learning.tags.map((tag) => (tag === 'codex' ? provider.tag : tag)))}
 ---
 
-# Aprendizado - ${learning.title}
+# ${L.learn.title} - ${learning.title}
 
-> [!note] Auto-gerada
-> Nota criada automaticamente pelo hook Stop do ${provider.label}.
-> Sessão: ${wikilinkFromRel(sessionRel)}
+> [!note] ${L.autoTag}
+> ${L.autoLine(provider.label)}
+> ${L.session}: ${wikilinkFromRel(sessionRel)}
 
-## Contexto
+## ${L.learn.context}
 
-${learning.context || '_Extraído da sessão — complementar._'}
+${learning.context || L.complete}
 
-## O que aprendemos
+## ${L.learn.learned}
 
 ${learning.content}
 
-## Como aplicar no futuro
+## ${L.learn.future}
 
-_Registrar como este conhecimento pode ser reutilizado._
+${L.learn.futureHint}
 `;
 }
 
@@ -478,7 +501,8 @@ function alreadyHasKey(keys, candidate) {
 export function createLinkedNotes(vaultBase, dateStr, sessionRel, tx, options = {}) {
   const linked = { decisions: [], bugs: [], learnings: [] };
   const provider = providerMeta(options.provider);
-  const locF = getLocale(vaultBase).folders;
+  const loc = getLocale(vaultBase);
+  const locF = loc.folders;
   const bugsDir = join(vaultBase, monthFolderRelFromDateStr(locF.bugs, dateStr, vaultBase));
   const decisionsDir = join(vaultBase, monthFolderRelFromDateStr(locF.decisions, dateStr, vaultBase));
   const learningsDir = join(vaultBase, monthFolderRelFromDateStr(locF.learnings, dateStr, vaultBase));
@@ -497,7 +521,7 @@ export function createLinkedNotes(vaultBase, dateStr, sessionRel, tx, options =
       const causeSlug = slugify(bugDetails.rootCause.slice(0, 40), 'bug');
       const fileName = issueRef ? `${issueRef}-${causeSlug}.md` : `${dateStr}-bug-${causeSlug}.md`;
       const filePath = join(bugsDir, fileName);
-      if (!existsSync(filePath)) writeFileSync(filePath, buildBugNoteContent(bugDetails, issueRef, dateStr, sessionRel, provider, bugKey), 'utf-8');
+      if (!existsSync(filePath)) writeFileSync(filePath, buildBugNoteContent(bugDetails, issueRef, dateStr, sessionRel, provider, bugKey, loc.id), 'utf-8');
       linked.bugs.push(toVaultRelative(vaultBase, filePath));
       existingKeys.bugs.push(bugKey);
     }
@@ -513,7 +537,7 @@ export function createLinkedNotes(vaultBase, dateStr, sessionRel, tx, options =
       const filePath = join(decisionsDir, fileName);
       if (!existsSync(filePath)) {
         const adrNum = Number(fileName.match(/^ADR-(\d+)/i)?.[1]) || getNextAdrNumber(vaultBase);
-        writeFileSync(filePath, buildDecisionNoteContent(decisionDetails, adrNum, dateStr, sessionRel, provider, decisionKey), 'utf-8');
+        writeFileSync(filePath, buildDecisionNoteContent(decisionDetails, adrNum, dateStr, sessionRel, provider, decisionKey, loc.id), 'utf-8');
       }
       linked.decisions.push(toVaultRelative(vaultBase, filePath));
       existingKeys.decisions.push(decisionKey);
@@ -528,7 +552,7 @@ export function createLinkedNotes(vaultBase, dateStr, sessionRel, tx, options =
       const learningSlug = slugify(learning.title.slice(0, 40), 'aprendizado');
       const fileName = `${dateStr}-${learningSlug}.md`;
       const filePath = join(learningsDir, fileName);
-      if (!existsSync(filePath)) writeFileSync(filePath, buildLearningNoteContent(learning, dateStr, sessionRel, provider, learningKey), 'utf-8');
+      if (!existsSync(filePath)) writeFileSync(filePath, buildLearningNoteContent(learning, dateStr, sessionRel, provider, learningKey, loc.id), 'utf-8');
       linked.learnings.push(toVaultRelative(vaultBase, filePath));
       existingKeys.learnings.push(learningKey);
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wendkeep",
-  "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.",
+  "version": "0.9.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": {
     "wendkeep": "bin/wendkeep.mjs",

package/src/init.mjs

@@ -282,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
@@ -297,12 +297,21 @@ export async function runInit(argv) {
   // 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 en = loc.id === 'en';
   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');
+  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)) {

package/src/sensors.mjs

@@ -1,23 +1,55 @@
-// `wendkeep sensors list` — read-only view over wendkeep.sensors.json (0.7.0).
-import { resolve } from 'node:path';
+// `wendkeep sensors <list|add>` — view/edit wendkeep.sensors.json (0.7.0 / 0.9.0).
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { loadSensors } from '../hooks/sensors-core.mjs';
 
+const SCHEMA = 'https://raw.githubusercontent.com/rogersialves/wendkeep/main/schema/wendkeep.sensors.schema.json';
+
+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 resolveProject(rest) {
+  return resolve(opt(rest, '--project') || process.cwd());
+}
+
 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);
+
+  if (sub === 'list') {
+    const sensors = loadSensors(resolveProject(rest));
+    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);
   }
-  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`);
+
+  if (sub === 'add') {
+    const flags = new Set(['--severity', '--type', '--report', '--name', '--description', '--project']);
+    const positional = rest.filter((a, i) => !a.startsWith('--') && !flags.has(rest[i - 1]));
+    const [id, command] = positional;
+    if (!id || !command) { process.stderr.write('wendkeep sensors add: precisa <id> "<command>"\n'); process.exit(2); }
+    const projectRoot = resolveProject(rest);
+    const path = join(projectRoot, 'wendkeep.sensors.json');
+    let cfg = { $schema: SCHEMA, version: 1, source: 'manual', sensors: [] };
+    if (existsSync(path)) {
+      try { cfg = JSON.parse(readFileSync(path, 'utf8')); } catch { process.stderr.write('wendkeep sensors add: wendkeep.sensors.json inválido\n'); process.exit(2); }
+      if (!Array.isArray(cfg.sensors)) cfg.sensors = [];
+      if (!cfg.$schema) cfg.$schema = SCHEMA;
+    }
+    if (cfg.sensors.some((s) => s.id === id)) { process.stderr.write(`wendkeep sensors add: sensor "${id}" já existe\n`); process.exit(2); }
+    const severity = opt(rest, '--severity') === 'warning' ? 'warning' : 'critical';
+    const type = opt(rest, '--type') === 'mutation' ? 'mutation' : 'command';
+    const sensor = { id, name: opt(rest, '--name') || id, description: opt(rest, '--description') || command, severity, type, command };
+    if (type === 'mutation') sensor.report = opt(rest, '--report') || 'reports/mutation/mutation.json';
+    cfg.sensors.push(sensor);
+    writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`, 'utf8');
+    process.stdout.write(`sensor added: ${id} (${type} · ${severity})\n`);
+    process.exit(0);
   }
-  process.exit(0);
+
+  process.stderr.write(`wendkeep sensors: unknown subcommand "${sub}". Known: list, add.\n`);
+  process.exit(2);
 }

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/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.
 `;
 }