wendkeep 0.8.1 → 0.9.1

package/CHANGELOG.md

@@ -4,6 +4,33 @@ 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.1] — 2026-07-06
+
+Interactive install UX: language first.
+
+### Added
+- **`wendkeep init` asks the vault language first** on an interactive TTY (when `--locale`
+  isn't passed): `[1] Português  [2] English`. The answer drives the folders, scaffold and
+  skills — and the remaining prompts (vault path, companion selection) now render in the
+  chosen locale instead of always Portuguese. `--yes`, `--locale` and non-TTY are unchanged.
+
+## [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.
@@ -196,6 +223,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.1]: https://github.com/rogersialves/wendkeep/releases/tag/v0.9.1
+[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

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,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "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": {

package/src/companion-select.mjs

@@ -4,6 +4,7 @@
 import readline from 'node:readline';
 
 const HINT = 'Espaço marca/desmarca · ↑/↓ move · a=todos · n=nenhum · Enter confirma';
+const HEADER = 'Companions';
 
 export function initialCompanionMenu(companions) {
   return {
@@ -35,8 +36,8 @@ export function reduceCompanionMenu(state, action) {
   }
 }
 
-export function renderCompanionMenu(state) {
-  const lines = [`Companions — ${HINT}:`];
+export function renderCompanionMenu(state, { hint = HINT, header = HEADER } = {}) {
+  const lines = [`${header} — ${hint}:`];
   state.items.forEach((it, i) => {
     const cursor = i === state.cursor ? '>' : ' ';
     const box = it.checked ? '[x]' : '[ ]';
@@ -63,7 +64,7 @@ export function canInteractiveSelect(input = process.stdin, output = process.std
 
 // Run the raw-TTY checkbox menu; resolves with the selected ids. Caller must check
 // canInteractiveSelect() first (otherwise use the text fallback).
-export function selectCompanionsInteractive(companions, { input = process.stdin, output = process.stdout } = {}) {
+export function selectCompanionsInteractive(companions, { input = process.stdin, output = process.stdout, labels } = {}) {
   return new Promise((resolve) => {
     let state = initialCompanionMenu(companions);
     let drawnLines = 0;
@@ -77,7 +78,7 @@ export function selectCompanionsInteractive(companions, { input = process.stdin,
         readline.moveCursor(output, 0, -drawnLines);
         readline.clearScreenDown(output);
       }
-      const text = renderCompanionMenu(state);
+      const text = renderCompanionMenu(state, labels);
       output.write(`${text}\n`);
       drawnLines = text.split('\n').length;
     };

package/src/init.mjs

@@ -192,17 +192,55 @@ function installVaultColors(vaultPath) {
 
 // --- main -------------------------------------------------------------------
 
+// Interactive prompt strings by locale. The language question itself is bilingual (asked
+// before the locale is known); everything after follows the answer.
+const PROMPTS = {
+  'pt-BR': {
+    vault: (f) => `Caminho do vault Obsidian (Enter aceita o padrão, ou digite outro)\n  [${f}]\n> `,
+    companionsHeader: '\nCompanions (plugins/MCP opcionais — context-mode é a principal):',
+    companionsAsk: (def) => `Digite os ids separados por vírgula (Enter aceita [${def}], "none" p/ nenhum): `,
+    menu: { hint: 'Espaço marca/desmarca · ↑/↓ move · a=todos · n=nenhum · Enter confirma', header: 'Companions' },
+  },
+  en: {
+    vault: (f) => `Obsidian vault path (Enter for the default, or type another)\n  [${f}]\n> `,
+    companionsHeader: '\nCompanions (optional plugins/MCP — context-mode is the main one):',
+    companionsAsk: (def) => `Enter ids comma-separated (Enter for [${def}], "none" for none): `,
+    menu: { hint: 'Space toggles · ↑/↓ move · a=all · n=none · Enter confirms', header: 'Companions' },
+  },
+};
+
+export function promptStrings(localeId) {
+  return PROMPTS[localeId] || PROMPTS['pt-BR'];
+}
+
+// Map the language answer to a locale id. 2/en → en; 1/pt/empty/unknown → pt-BR.
+export function parseLocaleAnswer(ans) {
+  const a = String(ans || '').trim().toLowerCase();
+  if (a === '2' || a === 'en' || a === 'english') return 'en';
+  return 'pt-BR';
+}
+
 export async function runInit(argv) {
   const args = parseArgs(argv);
   const projectPath = resolve(args.project || process.cwd());
   const log = (s) => process.stdout.write(`${s}\n`);
 
+  // Language first (i18n): an interactive TTY without --locale is asked the vault language;
+  // folders, prompts and scaffold all follow the answer.
+  if (!args.locale && process.stdin.isTTY && !args.yes) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ans = await rl.question('Idioma do vault / Vault language:\n  [1] Português (pt-BR)   [2] English (en)\n> ');
+    rl.close();
+    args.locale = parseLocaleAnswer(ans);
+  }
+  const P = promptStrings(args.locale && LOCALES[args.locale] ? args.locale : DEFAULT_LOCALE);
+
   let vaultPath = args.vault;
   if (!vaultPath) {
     const fallback = join(projectPath, deriveVaultDirName(projectPath));
     if (process.stdin.isTTY && !args.yes) {
       const rl = createInterface({ input: process.stdin, output: process.stdout });
-      const ans = (await rl.question(`Obsidian vault path (Enter aceita o padrão, ou digite outro caminho)\n  [${fallback}]\n> `)).trim();
+      const ans = (await rl.question(P.vault(fallback))).trim();
       rl.close();
       vaultPath = ans || fallback;
     } else {
@@ -222,16 +260,14 @@ export async function runInit(argv) {
   } else if (process.stdin.isTTY && !args.yes) {
     if (canInteractiveSelect()) {
       log(''); // the checkbox menu renders its own header
-      companions = await selectCompanionsInteractive(COMPANIONS);
+      companions = await selectCompanionsInteractive(COMPANIONS, { labels: P.menu });
     } else {
       // Text fallback (no raw-mode TTY): list + comma input with clear instructions.
-      log('\nCompanions (plugins/MCP opcionais — context-mode é a principal):');
+      log(P.companionsHeader);
       for (const c of COMPANIONS) log(`  ${c.default ? '[x]' : '[ ]'} ${c.label}`);
       const def = resolveCompanions({}).join(',');
       const rl = createInterface({ input: process.stdin, output: process.stdout });
-      const ans = (await rl.question(
-        `Digite os ids separados por vírgula (Enter aceita [${def}], "none" p/ nenhum): `,
-      )).trim();
+      const ans = (await rl.question(P.companionsAsk(def))).trim();
       rl.close();
       companions = ans.toLowerCase() === 'none' ? [] : resolveCompanions({ companionsFlag: ans || def });
     }

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);
 }