wendkeep 0.46.2 → 0.48.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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.48.0] — 2026-07-23
+
+### Added
+
+- **`wendkeep note relink [--apply]` — backfill de proveniência das notas derivadas
+  órfãs.** BUG/APR legadas (criadas por versão antiga, sem `source:` de sessão) ficam ilhas
+  no grafo — num vault real: 13 de 15 BUG e 3 de 8 APR sem nenhum link de entrada nem de
+  saída. A origem não está registrada no órfão, mas os irmãos não-órfãos do mesmo tipo
+  carregam a sessão-fonte real. O comando liga cada órfão herdando a sessão **modal** (mais
+  comum) dos irmãos do mesmo tipo e mês, injetando `source:` + `related:` no frontmatter.
+  Dry-run por default; `--apply` escreve; idempotente; pula e reporta o órfão sem nenhum
+  irmão-fonte pra inferir (nunca chuta). Documentado em `derived-notes` (DRV-9).
+
+## [0.47.0] — 2026-07-23
+
+### Added
+
+- **Grafo do vault conectado: todo artefato de change linka o hub.** `change new` gera
+  `design.md` e `tarefas.md` com um backlink full-path pro `proposta.md` da própria change —
+  antes nasciam sem nenhum wikilink, ilhas no grafo do Obsidian (num vault real: 48 de 63
+  `.md` de `08-Mudanças` órfãos). O full-path (nunca basename, ambíguo entre changes) sobrevive
+  ao archive: o `rewriteChangeLinks` retargeta pro `_arquivo` junto com os demais links.
+- **Auto-heal do backlink em `spec.md`.** O delta de spec é escrito à mão, então `verify` e
+  `archive` passam a injetar o backlink pro proposta em cada `specs/<capability>/spec.md` que
+  estiver sem — idempotente. Nenhum artefato de change fica desconectado do plano↔sessão.
+- **`wendkeep change backlink [--apply]`** — backfill dos artefatos órfãos que já existem no
+  vault (changes open e arquivadas), apontando cada `design`/`tarefas`/`spec` pro proposta no
+  seu local atual. Dry-run por default; `--apply` escreve. Idempotente.
+- **`wendkeep theme sync`** — re-aplica o color system (snippet CSS + graph color groups) num
+  vault existente, sem re-`init`. Recupera o grafo que ficou cinza quando o Obsidian (dono do
+  `graph.json`) zera os `colorGroups`. O instalador virou módulo compartilhado com o `init`,
+  então os dois nunca divergem.
+- **Snippet define `--file-line-width`.** O CSS gerado passa a definir a largura de linha
+  legível (1400px, ajustável) sobre o `body` com `!important` — antes era edição manual em
+  cada vault. As capabilities `change-graph` e `vault-theme` documentam o contrato em `07-Specs`.
+
 ## [0.46.2] — 2026-07-19
 
 ### Fixed

package/README.md

@@ -70,7 +70,7 @@ npx wendkeep init
    - **`dotcontext`** — *legacy, not recommended, and hidden from the picker.* wendkeep's native a2 loop (`change` / `verify` / gate) already does its job, so installing it **duplicates the harness**. Reachable only via an explicit `--companions dotcontext` for anyone already invested (tune with `--dotcontext-mcp` / `--dotcontext-hooks`).
 
    Control with `--companions <csv>` or `--no-companions`. The Claude Code plugin layer (`extraKnownMarketplaces` + `enabledPlugins`) is wired as a bonus where the companion has one.
-6. Install a **color system** into the vault's `.obsidian/`: a CSS snippet that accents notes by type (session/decision/bug/learning, via the `cssclasses` the hooks emit) plus graph color groups by folder. Non-destructive merge into `appearance.json`/`graph.json`; skip with `--no-colors`.
+6. Install a **color system** into the vault's `.obsidian/`: a CSS snippet that accents notes by type (session/decision/bug/learning, via the `cssclasses` the hooks emit) plus graph color groups by folder. Non-destructive merge into `appearance.json`/`graph.json`; skip with `--no-colors`. Re-apply it any time on an existing vault with `wendkeep theme sync` — Obsidian owns `graph.json` and can drop the color groups (a grey graph); the re-sync restores them without a full re-`init`.
 7. Seed the **curated memory layer**: `.brain/CORE.md` (the hand-curated hot layer, with the 3 required sections) and `.brain/COMPACTION_PROTOCOL.md` (the protocol guide). The auto layers (`DIGEST.md`, `index.jsonl`) are generated by the hooks. Validate the curated layer with `wendkeep validate-memory` (cap 25 lines, 3 sections, no secrets/PII).
 8. Seed the **definitions + skills layer**: `.brain/agents/` + `.brain/skills/` (versioned source of truth), including the native process skills `wk-workflow` / `wk-tdd` / `wk-debugging` / `wk-brainstorming` / `wk-planning` / `wk-verify` (some ship templates — e.g. `wk-verify`'s `verdict-template.json` + reviewer prompt). `init` runs `wendkeep sync-defs` for you, delivering the skills to `.claude/skills/` and `.agents/skills/`, and the agent definitions (`.brain/agents/*.toml`) to `.codex/agents/`, plus a managed section in `AGENTS.md` that indexes the skills for Codex; `sync-defs --check` detects stale copies (re-run `sync-defs` after editing `.brain`).
 9. Seed the **change/spec lifecycle**: the `07-Specs/` + `08-Mudanças/` folders and a native `wendkeep.sensors.json` — a critical `memory-validation` sensor (`npx wendkeep validate-memory`) plus one for each of `typecheck` / `test` / `lint` / `build` found in your `package.json`. Add your own with `wendkeep sensors add`. Drives `wendkeep change` / `wendkeep verify` — see **Change lifecycle** below.
@@ -184,6 +184,8 @@ wendkeep note new --type learning "a regex without /g only ever returns the firs
 
 It prints the created path, numbers from the current max (recursive scan), files it in the month folder for today (`--date YYYY-MM-DD` to override), and links the active session in `source:` so the graph stays connected. Agents get this rule injected at SessionStart — they call the command instead of guessing a filename.
 
+**Reconnecting legacy notes.** Derived notes created by older versions carry no `source:` session and sit as islands in the graph. `wendkeep note relink` backfills them: each orphan inherits the modal source session of its type/month cohort (the session its non-orphan siblings already point to). Dry-run by default; `--apply` writes; notes with no sibling to infer from are skipped and reported.
+
 **Migrating an existing vault.** Notes created before `0.41.0` have date-prefixed names (`2026-07-16-bug-<slug>.md`) and may sit in legacy `DIA N` subfolders. One command per tree renumbers them chronologically, moves them up into the month folder, and rewrites every wikilink across the vault:
 
 ```bash
@@ -252,9 +254,13 @@ npx wendkeep change archive dark-mode          # gate: sensors + verdict + no op
 ```
 
 The archive promotes the delta into generated `07-Specs/ui.md`, mints an ADR, and the
-Obsidian graph now links *session ↔ change ↔ requirement ↔ decision*. A change that names
-no `[req:]` still runs `verify --deep`, but skips the `wk-verify` reading pass: the
-command writes a trivial verdict on its own and the sensor gate is the real proof.
+Obsidian graph now links *session ↔ change ↔ requirement ↔ decision*. Every generated
+artifact (`design`/`tarefas`) is born linking its change's `proposta` hub, and hand-authored
+`spec.md` deltas are auto-linked on `verify`/`archive` — no change artifact is a graph island.
+To backfill older changes that predate this, run `wendkeep change backlink --apply` (dry-run
+without `--apply`). A change that names no `[req:]` still runs `verify --deep`, but skips the
+`wk-verify` reading pass: the command writes a trivial verdict on its own and the sensor gate
+is the real proof.
 
 ## How it works
 

package/bin/wendkeep.mjs

@@ -44,8 +44,11 @@ Usage:
 
   wendkeep doctor [--vault P]  Run a vault health check.
   wendkeep change <sub>        Change lifecycle: new [--simple] | use | bind <slug> --session <id> | continue | list | show |
-                           status | done <id> | undone <id> | diff | archive [--force] | abandon.
+                           status | done <id> | undone <id> | diff | archive [--force] | abandon | relink | backlink.
                            archive exige verdict (rode verify --deep); abandon descarta sem ADR.
+                           backlink [--apply]: injeta o backlink pro proposta em design/tarefas/spec órfãos (open + _arquivo).
+  wendkeep theme sync          Re-aplica o color system (snippet CSS + graph color groups) num vault
+                           existente — recupera o grafo cinza sem re-init. --vault P.
   wendkeep session <sub>       Session registry: list | show <id> | use <id>.
   wendkeep spec <sub>          Specs: list | show | effective [--change] [--json] | migrate | rebase.
   wendkeep sensors <sub>       list | add <id> "<command>" [--severity --type --report].
@@ -74,6 +77,9 @@ Usage:
   wendkeep renumber-learnings   Same for 06-Aprendizados/06-Learnings with APR-<NNNN>-<slug>.
   wendkeep note new --type bug|learning "<título>"  Create a numbered derived note (BUG-/APR-NNNN)
                            in the month folder and print its vault path. --date YYYY-MM-DD · --vault P.
+  wendkeep note relink [--apply]  Backfill orphan derived notes (BUG/APR without a source session),
+                           linking each to the modal source session of its type/month cohort. Dry-run
+                           by default; --apply writes; skips notes with no sibling to infer from.
   wendkeep lesson add "t" "l"   Record a project-local lesson (injected at SessionStart).
   wendkeep validate-memory [path]  Validate .brain/CORE.md against the compaction
                            protocol (cap 25, 3 sections, no secrets/PII). Uses
@@ -175,6 +181,11 @@ async function main() {
       runSession(rest);
       break;
     }
+    case 'theme': {
+      const { runTheme } = await import('../src/theme.mjs');
+      runTheme(rest);
+      break;
+    }
     case 'verify': {
       const { runVerify } = await import('../src/verify.mjs');
       runVerify(rest);

package/hooks/change-core.mjs

@@ -2,10 +2,10 @@
 // Native change/spec lifecycle in the vault (Pilar B). Vault-facing lib consumed by
 // the `wendkeep change` CLI (src/change.mjs) and the brain-inject hook. No external deps.
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { ensureDir, wikilinkFromRel, monthFolderRelFromDateStr } from './obsidian-common.mjs';
 import { parseSpecsList, promoteSpecs, discoverSpecDeltas, tasksHashOf, captureSpecBaseline, REQ_ID_RE_SRC } from './spec-core.mjs';
-import { getLocale } from './locale.mjs';
+import { getLocale, LOCALES } from './locale.mjs';
 
 export const ARCHIVE_DIR = '_arquivo';
 const POINTER = '.brain/CURRENT_CHANGE.md';
@@ -39,12 +39,21 @@ specs: []
 
 ${en ? '## Why\n\n(reason for the change)\n\n## What changes\n\n(scope of the change)' : '## Por quê\n\n(motivo da mudança)\n\n## O que muda\n\n(escopo da mudança)'}
 `;
+  // Hub backlink: design/tarefas link the change's proposta so no generated artifact is a
+  // graph island. Full-path (never basename — proposta/design exist in every change) so the
+  // archive's rewriteChangeLinks retargets it to _arquivo when the change moves.
+  const changesFolder = (LOCALES[locale] || LOCALES['pt-BR']).folders.changes;
+  const hubLink = `> ${en ? 'Change:' : 'Mudança:'} [[${changesFolder}/${slug}/proposta]]`;
   const design = `# ${slug} — design
 
+${hubLink}
+
 ${en ? '## Approach\n\n(technical approach)' : '## Abordagem\n\n(abordagem técnica)'}
 `;
   const tarefas = `# ${slug} — ${en ? 'tasks' : 'tarefas'}
 
+${hubLink}
+
 - [ ] 1.1 ${en ? '(first task)' : '(primeira tarefa)'}
 `;
   const reqHeading = en ? 'Requirement' : 'Requisito';
@@ -419,6 +428,10 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
   let reqIds = [];
   try { reqIds = [...new Set(parseTasks(readFileSync(join(src, 'tarefas.md'), 'utf8')).flatMap((t) => t.reqs ?? []))]; } catch { /* sem tarefas */ }
 
+  // Backlink dos artefatos escritos à mão (spec.md) ANTES do move — o rewriteChangeLinks
+  // abaixo retargeta o wikilink pro _arquivo junto com os demais. Fail-quiet.
+  try { healSpecBacklinks(src, vaultBase); } catch { /* heal é bônus */ }
+
   ensureDir(join(vaultBase, chDir, ARCHIVE_DIR));
   try {
     renameSync(src, destAbs);
@@ -512,6 +525,96 @@ function rewriteChangeLinks(vaultBase, fromRel, toRel) {
   return touched;
 }
 
+// --- backlinks de artefato -> hub proposta (grafo conectado) -------------------
+// design/tarefas nascem linkando o hub (renderChangeScaffold); spec.md é escrito à mão,
+// então recebe o backlink por auto-heal (verify/archive) + backfill dos vaults existentes.
+function backlinkLabel(loc) {
+  return loc.id === 'en' ? 'Change:' : 'Mudança:';
+}
+
+// Injeta a linha de backlink logo abaixo do primeiro heading — mas NUNCA acima de um bloco
+// de frontmatter YAML: prepender antes do `---` quebra o frontmatter (Obsidian para de ler
+// cssclasses/tags). Ordem: preserva o frontmatter, depois cai abaixo do 1º heading do corpo,
+// senão no topo do corpo.
+function insertBacklink(content, backlinkLine) {
+  let head = '';
+  let body = content;
+  const fm = content.match(/^---\n[\s\S]*?\n---\n?/);
+  if (fm) { head = fm[0]; body = content.slice(fm[0].length); }
+  const h = body.match(/^\s*#[^\n]*\n/);
+  if (h) {
+    const rest = body.slice(h[0].length).replace(/^\n+/, '');
+    return `${head}${h[0]}\n${backlinkLine}\n\n${rest}`;
+  }
+  const rest = body.replace(/^\n+/, '');
+  return `${head}${backlinkLine}\n\n${rest}`;
+}
+
+// Auto-heal (0.47): garante o backlink pro proposta em cada specs/<cap>/spec.md do change.
+// Idempotente (pula quem já tem o link exato). Chamado no verify e no archive (antes do move,
+// pra o rewriteChangeLinks retargetar pro _arquivo). Retorna quantos arquivos healou.
+export function healSpecBacklinks(changeDir, vaultBase) {
+  const loc = getLocale(vaultBase);
+  const propRel = `${relative(vaultBase, changeDir).replaceAll('\\', '/')}/proposta`;
+  const link = `[[${propRel}]]`;
+  const line = `> ${backlinkLabel(loc)} ${link}`;
+  let caps = [];
+  try { caps = readdirSync(join(changeDir, 'specs'), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name); }
+  catch { return 0; }
+  let healed = 0;
+  for (const cap of caps) {
+    const p = join(changeDir, 'specs', cap, 'spec.md');
+    let c;
+    try { c = readFileSync(p, 'utf8'); } catch { continue; }
+    if (c.includes(link)) continue;
+    try { writeFileSync(p, insertBacklink(c, line), 'utf8'); healed += 1; } catch { /* readonly — segue */ }
+  }
+  return healed;
+}
+
+// Backfill (0.47): cura design/tarefas/spec órfãos em changes já existentes — open e _arquivo.
+// Aponta cada artefato pro proposta no seu local atual (arquivado usa o path do _arquivo).
+// Dry-run por default; `apply` escreve. Idempotente (pula quem já linka o proposta certo).
+export function backfillArtifactLinks(vaultBase, { apply = false } = {}) {
+  const loc = getLocale(vaultBase);
+  const chDir = loc.folders.changes;
+  const label = backlinkLabel(loc);
+  const base = join(vaultBase, chDir);
+  const dirs = [];
+  try {
+    for (const name of readdirSync(base)) {
+      if (name === ARCHIVE_DIR) continue;
+      const d = join(base, name);
+      if (existsSync(join(d, 'proposta.md'))) dirs.push(d);
+    }
+  } catch { /* sem changes */ }
+  try {
+    for (const name of readdirSync(join(base, ARCHIVE_DIR))) {
+      const d = join(base, ARCHIVE_DIR, name);
+      if (existsSync(join(d, 'proposta.md'))) dirs.push(d);
+    }
+  } catch { /* sem arquivo */ }
+
+  const changed = [];
+  for (const dir of dirs) {
+    const propRel = `${relative(vaultBase, dir).replaceAll('\\', '/')}/proposta`;
+    const link = `[[${propRel}]]`;
+    const line = `> ${label} ${link}`;
+    let caps = [];
+    try { caps = readdirSync(join(dir, 'specs'), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => join('specs', e.name, 'spec.md')); }
+    catch { /* sem specs */ }
+    for (const rel of ['design.md', 'tarefas.md', ...caps]) {
+      const p = join(dir, rel);
+      let c;
+      try { c = readFileSync(p, 'utf8'); } catch { continue; }
+      if (c.includes(link)) continue;
+      if (apply) { try { writeFileSync(p, insertBacklink(c, line), 'utf8'); } catch { continue; } }
+      changed.push(relative(vaultBase, p).replaceAll('\\', '/'));
+    }
+  }
+  return { applied: apply, scanned: dirs.length, changed };
+}
+
 // Cura retroativa (vaults pré-0.35): wikilinks para changes que já moveram sem reescrita.
 // Dry-run por default; match por slug no nome datado do archive (`<data>-<slug>[-abandonada]`);
 // ambíguo (mesmo slug arquivado 2×) é reportado e pulado — nunca chuta.

package/hooks/linked-notes.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs';
-import { basename, join } from 'path';
+import { basename, join, relative } from 'path';
 import {
   monthFolderRelFromDateStr,
   derivedContentKey,
@@ -63,6 +63,77 @@ function sessionYamlLinks(sessionRel) {
   ].join('\n');
 }
 
+// --- note relink: backfill de proveniência das notas derivadas órfãs (DRV-9) -----
+// Nota derivada legada (BUG/APR criada por wendkeep antigo) nasce sem `source:` de sessão —
+// ilha no grafo. A origem não está registrada nela, mas os irmãos NÃO-órfãos do mesmo tipo
+// carregam a sessão-fonte real: o órfão herda a sessão MODAL (mais comum) do seu (tipo, mês).
+
+// Extrai a sessão do primeiro `source: - [[...]]` do frontmatter (vazio se não houver).
+function sourceSessionOf(content) {
+  const m = content.match(/^source:\s*\n\s*-\s*"?\[\[([^\]"|]+)/m);
+  return m ? m[1].trim() : '';
+}
+
+// Injeta source+related antes do `---` de fechamento do frontmatter. Sem frontmatter, no-op.
+function insertSourceLinks(content, sessionRel) {
+  const m = content.match(/^(---\n[\s\S]*?\n)(---\n)/);
+  if (!m) return content;
+  return `${m[1]}${sessionYamlLinks(sessionRel)}\n${m[2]}${content.slice(m[0].length)}`;
+}
+
+function modalKey(counts) {
+  const entries = Object.entries(counts || {});
+  if (!entries.length) return '';
+  entries.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  return entries[0][0];
+}
+
+export function relinkDerivedNotes(vaultBase, { apply = false } = {}) {
+  const loc = getLocale(vaultBase);
+  const monthOf = (abs) => relative(vaultBase, abs).replaceAll('\\', '/').split('/').slice(0, 3).join('/');
+  const linked = [];
+  const skipped = [];
+  for (const [folderKey, prefix] of [['bugs', 'BUG'], ['learnings', 'APR']]) {
+    const root = join(vaultBase, loc.folders[folderKey]);
+    const files = [];
+    const walk = (dir) => {
+      let entries;
+      try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+      for (const e of entries) {
+        const p = join(dir, e.name);
+        if (e.isDirectory()) walk(p);
+        else if (e.name.endsWith('.md') && e.name.startsWith(`${prefix}-`)) files.push(p);
+      }
+    };
+    walk(root);
+    const byMonth = {};
+    const typeWide = {};
+    const orphans = [];
+    for (const p of files) {
+      let c;
+      try { c = readFileSync(p, 'utf8'); } catch { continue; }
+      const src = sourceSessionOf(c);
+      if (src) {
+        (byMonth[monthOf(p)] ??= {})[src] = ((byMonth[monthOf(p)] || {})[src] || 0) + 1;
+        typeWide[src] = (typeWide[src] || 0) + 1;
+      } else {
+        orphans.push({ p, c });
+      }
+    }
+    for (const o of orphans) {
+      const rel = relative(vaultBase, o.p).replaceAll('\\', '/');
+      const session = modalKey(byMonth[monthOf(o.p)]) || modalKey(typeWide);
+      if (!session) { skipped.push({ file: rel, reason: 'sem irmão com source para inferir' }); continue; }
+      if (apply) {
+        try { writeFileSync(o.p, insertSourceLinks(o.c, session), 'utf8'); }
+        catch { skipped.push({ file: rel, reason: 'escrita falhou' }); continue; }
+      }
+      linked.push({ file: rel, session: basename(session) });
+    }
+  }
+  return { applied: apply, linked, skipped };
+}
+
 function extractIssueRefs(tx) {
   const text = [
     assistantText(tx),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.46.2",
+  "version": "0.48.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": {

package/src/change.mjs

@@ -14,6 +14,7 @@ import {
   archiveChange,
   abandonChange,
   relinkChanges,
+  backfillArtifactLinks,
   scaffoldPlaceholders,
 } from '../hooks/change-core.mjs';
 import { evaluateGate, requiredSensors } from '../hooks/sensors-core.mjs';
@@ -308,6 +309,15 @@ export function runChange(argv) {
     process.exit(0);
   }
 
+  if (sub === 'backlink') {
+    const r = backfillArtifactLinks(vaultBase, { apply: rest.includes('--apply') });
+    if (rest.includes('--json')) { process.stdout.write(`${JSON.stringify(r, null, 2)}\n`); process.exit(0); }
+    process.stdout.write(`${r.changed.length} artefato(s) órfão(s) em ${r.scanned} change(s)${r.applied ? ' · reescritos' : ''}\n`);
+    for (const f of r.changed) process.stdout.write(`  ${f}\n`);
+    if (!r.applied && r.changed.length) process.stdout.write('\ndry-run — nada escrito. Rode com --apply para injetar os backlinks.\n');
+    process.exit(0);
+  }
+
   if (sub === 'abandon') {
     const slug = slugArg() || activeChange(vaultBase);
     if (!slug) { process.stderr.write('wendkeep change abandon: missing <slug> and no active change\n'); process.exit(2); }
@@ -317,6 +327,6 @@ export function runChange(argv) {
     process.exit(0);
   }
 
-  process.stderr.write(`wendkeep change: unknown subcommand "${sub}". Known: new, use, continue, list, show, status, done, undone, diff, archive, abandon, relink.\n`);
+  process.stderr.write(`wendkeep change: unknown subcommand "${sub}". Known: new, use, continue, list, show, status, done, undone, diff, archive, abandon, relink, backlink.\n`);
   process.exit(2);
 }

package/src/init.mjs

@@ -31,13 +31,7 @@ import {
 import { renderVaultReadme } from './vault-readme.mjs';
 import { seedVaultViews } from './vault-views.mjs';
 import { canInteractiveSelect, selectCompanionsInteractive } from './companion-select.mjs';
-import {
-  SNIPPET_NAME,
-  renderColorSnippetCss,
-  mergeAppearance,
-  graphColorGroups,
-  mergeGraphColorGroups,
-} from './vault-theme.mjs';
+import { syncVaultTheme } from './theme.mjs';
 import { renderCoreSkeleton, renderCompactionProtocol } from './validate-core.mjs';
 import { seedDefinitions, syncDefs } from './sync-defs.mjs';
 import { seedWkSkills } from './skills-seed.mjs';
@@ -261,33 +255,11 @@ function runCavemanInstaller(log) {
   }
 }
 
-// Install the vault color system into .obsidian: write wendkeep's CSS snippet,
-// 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).
+// Install the vault color system into .obsidian: write wendkeep's CSS snippet, enable it
+// (non-destructive), and add graph color groups. Shared installer lives in theme.mjs so
+// `init` and `theme sync` never drift. Unparseable user JSON is left untouched.
 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(loc), 'utf8');
-
-  let enabled = false;
-  const appPath = join(obsidianDir, 'appearance.json');
-  const appRead = readJsonSafe(appPath);
-  if (appRead.ok) {
-    writeJson(appPath, mergeAppearance(appRead.data || {}, SNIPPET_NAME));
-    enabled = true;
-  }
-
-  let groups = 0;
-  const graphPath = join(obsidianDir, 'graph.json');
-  const graphRead = readJsonSafe(graphPath);
-  if (graphRead.ok) {
-    const merged = mergeGraphColorGroups(graphRead.data || {}, graphColorGroups(loc));
-    writeJson(graphPath, merged);
-    groups = graphColorGroups(loc).length;
-  }
-  return `snippet ${SNIPPET_NAME}.css${enabled ? ' (enabled)' : ' (enable by hand: appearance.json unreadable)'} + ${groups} graph group(s)`;
+  return syncVaultTheme(vaultPath).summary;
 }
 
 // --- main -------------------------------------------------------------------

package/src/note.mjs

@@ -14,7 +14,7 @@ import {
   toVaultRelative,
 } from '../hooks/obsidian-common.mjs';
 import { getLocale } from '../hooks/locale.mjs';
-import { buildManualBugNote, buildManualLearningNote } from '../hooks/linked-notes.mjs';
+import { buildManualBugNote, buildManualLearningNote, relinkDerivedNotes } from '../hooks/linked-notes.mjs';
 
 const TYPES = {
   bug: { folderKey: 'bugs', prefix: 'BUG', build: buildManualBugNote },
@@ -30,8 +30,23 @@ function opt(argv, name) {
 
 export function runNote(argv) {
   const [sub, ...rest] = argv;
+
+  if (sub === 'relink') {
+    const vaultRaw = opt(rest, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
+    if (!vaultRaw) { process.stderr.write('wendkeep note relink: no vault (--vault or OBSIDIAN_VAULT_PATH).\n'); process.exit(2); }
+    const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);
+    if (!existsSync(vaultBase)) { process.stderr.write(`wendkeep note relink: vault not found: ${vaultBase}\n`); process.exit(2); }
+    const r = relinkDerivedNotes(vaultBase, { apply: rest.includes('--apply') });
+    if (rest.includes('--json')) { process.stdout.write(`${JSON.stringify(r, null, 2)}\n`); process.exit(0); }
+    process.stdout.write(`${r.linked.length} nota(s) derivada(s) órfã(s)${r.applied ? ' linkadas' : ' seriam linkadas'}\n`);
+    for (const l of r.linked) process.stdout.write(`  ${l.file} -> ${l.session}\n`);
+    for (const s of r.skipped) process.stdout.write(`  pulado: ${s.file} (${s.reason})\n`);
+    if (!r.applied && r.linked.length) process.stdout.write('\ndry-run — nada escrito. Rode com --apply para injetar os backlinks.\n');
+    process.exit(0);
+  }
+
   if (sub !== 'new') {
-    process.stderr.write('wendkeep note: subcomando desconhecido (use `note new --type bug|learning "<título>"`).\n');
+    process.stderr.write('wendkeep note: subcomando desconhecido (use `note new --type bug|learning "<título>"` ou `note relink [--apply]`).\n');
     process.exit(2);
   }
 

package/src/theme.mjs

@@ -0,0 +1,89 @@
+// `wendkeep theme sync` — re-apply the vault color system into .obsidian on an EXISTING
+// vault, idempotently: rewrite the CSS snippet, enable it (non-destructive), and (re)merge
+// the graph color groups. The installer is shared with `wendkeep init` so the two never drift.
+//
+// Why a re-sync exists: .obsidian/graph.json is owned by Obsidian, which can drop the
+// colorGroups wendkeep wrote (vault init'd by an older version, or Obsidian rewriting the
+// file). Without a re-apply path the only fix was a full re-init. This command restores the
+// graph colors without touching anything else.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { getLocale } from '../hooks/locale.mjs';
+import {
+  SNIPPET_NAME,
+  renderColorSnippetCss,
+  mergeAppearance,
+  graphColorGroups,
+  mergeGraphColorGroups,
+} from './vault-theme.mjs';
+
+// { ok, data }. ok=false means the file EXISTS but is unparseable — never clobber it.
+// Absent -> ok=true, data=null (we create it).
+function readJsonSafe(path) {
+  if (!existsSync(path)) return { ok: true, data: null };
+  try { return { ok: true, data: JSON.parse(readFileSync(path, 'utf8')) }; }
+  catch { return { ok: false, data: null }; }
+}
+
+function writeJson(path, obj) {
+  writeFileSync(path, `${JSON.stringify(obj, null, 2)}\n`, 'utf8');
+}
+
+// Pure-ish installer (does file I/O, no process exit). Returns a short summary + counts.
+// Consumed by both `wendkeep init` (installVaultColors) and `wendkeep theme sync`.
+export function syncVaultTheme(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(loc), 'utf8');
+
+  let enabled = false;
+  const appPath = join(obsidianDir, 'appearance.json');
+  const appRead = readJsonSafe(appPath);
+  if (appRead.ok) {
+    writeJson(appPath, mergeAppearance(appRead.data || {}, SNIPPET_NAME));
+    enabled = true;
+  }
+
+  let groups = 0;
+  const graphPath = join(obsidianDir, 'graph.json');
+  const graphRead = readJsonSafe(graphPath);
+  if (graphRead.ok) {
+    writeJson(graphPath, mergeGraphColorGroups(graphRead.data || {}, graphColorGroups(loc)));
+    groups = graphColorGroups(loc).length;
+  }
+  return {
+    enabled,
+    groups,
+    summary: `snippet ${SNIPPET_NAME}.css${enabled ? ' (enabled)' : ' (enable by hand: appearance.json unreadable)'} + ${groups} graph group(s)`,
+  };
+}
+
+function resolveVault(argv) {
+  let vault;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--vault') vault = argv[++i];
+    else if (a.startsWith('--vault=')) vault = a.slice(8);
+  }
+  const base = vault || process.env.OBSIDIAN_VAULT_PATH;
+  if (!base) {
+    process.stderr.write('wendkeep theme: no vault. Pass --vault <path> or set OBSIDIAN_VAULT_PATH.\n');
+    process.exit(2);
+  }
+  return isAbsolute(base) ? base : resolve(process.cwd(), base);
+}
+
+export function runTheme(argv) {
+  const [sub, ...rest] = argv;
+  if (sub !== 'sync') {
+    process.stderr.write(`wendkeep theme: unknown subcommand "${sub || ''}". Known: sync.\n`);
+    process.exit(2);
+  }
+  const vaultBase = resolveVault(rest);
+  const r = syncVaultTheme(vaultBase);
+  process.stdout.write(`theme sync: ${r.summary}\n`);
+  process.stdout.write('feche o Obsidian antes de rodar e reabra depois — ele é dono do graph.json e recarrega as cores na abertura.\n');
+  process.exit(0);
+}

package/src/vault-theme.mjs

@@ -8,6 +8,10 @@
 
 export const SNIPPET_NAME = 'wendkeep-colors';
 
+// Readable line width for note content — Obsidian's default (~700px) wastes wide monitors.
+// Ajuste aqui (1200px / 1400px / 100vw) para mudar em todos os vaults de uma vez.
+export const READABLE_LINE_WIDTH = '1400px';
+
 import { LOCALES } from '../hooks/locale.mjs';
 const PT = LOCALES['pt-BR'];
 
@@ -86,6 +90,13 @@ ${rootVars}
 .theme-dark { --us-line-tint: 44%; }
 .theme-light { --us-line-tint: 36%; }
 
+/* --- Readable line width: wider than Obsidian's ~700px default ------------ */
+/* !important porque o Obsidian declara --file-line-width com specificity alta; sem ele
+   a regra do body não vence e a linha volta pro ~700px. */
+body {
+  --file-line-width: ${READABLE_LINE_WIDTH} !important;
+}
+
 /* --- File explorer: accented folders ------------------------------------- */
 ${FX} {
   border-left: 3px solid transparent;

package/src/verify.mjs

@@ -3,7 +3,7 @@
 // the VAULT. Writes 08-Mudanças/<slug>/evidencia.json; exit 1 if a critical sensor is red.
 import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
-import { parseTasks, activeChange, appendFixTasks } from '../hooks/change-core.mjs';
+import { parseTasks, activeChange, appendFixTasks, healSpecBacklinks } from '../hooks/change-core.mjs';
 import { loadSensorsDetailed, findProjectRoot, requiredSensors, runSensors, evaluateGate } from '../hooks/sensors-core.mjs';
 import {
   buildEffectiveRequirementPackage,
@@ -41,6 +41,9 @@ export function runVerify(argv) {
   try { tarefas = readFileSync(join(changeDir, 'tarefas.md'), 'utf8'); }
   catch { process.stderr.write(`wendkeep verify: change not found: ${slug}\n`); process.exit(2); }
 
+  // Backlink dos specs escritos à mão pro hub proposta (grafo conectado). Idempotente, fail-quiet.
+  try { healSpecBacklinks(changeDir, vaultBase); } catch { /* heal é bônus */ }
+
   const ids = requiredSensors(parseTasks(tarefas));
   const loaded = loadSensorsDetailed(projectRoot);
   if (loaded.error) {