neurain 0.1.0-alpha.0 → 0.1.0-alpha.1

package/docs/release-checklist.en.md

@@ -2,7 +2,40 @@
 
 Use this checklist before publishing an alpha release.
 
-## Local Checks
+## Automated Release (preferred)
+
+Releases are automated. You only decide WHEN to ship:
+
+```bash
+npm version prerelease --preid=alpha   # 0.1.0-alpha.0 -> 0.1.0-alpha.1 (commits + tags)
+git push origin main --follow-tags     # push the commit AND the new tag
+```
+
+The tag push triggers `.github/workflows/release.yml`, which runs the full
+readiness gate and then `npm publish --tag alpha` via npm Trusted Publishing
+(OIDC) — no stored token, no interactive 2FA. Every push (untagged) is gated by
+`.github/workflows/test.yml` (tests + fast readiness + `npm publish --dry-run`).
+
+One-time setup: on npmjs.com, the package -> Settings -> Trusted Publisher ->
+GitHub Actions, with this repo's owner/name and workflow `release.yml`.
+
+## Versioning policy
+
+- Pre-1.0 alpha: increment with `npm version prerelease --preid=alpha`
+  (`-alpha.0 -> -alpha.1 -> ...`). Publish ALWAYS with `--tag alpha`; never move
+  the `latest` dist-tag to a prerelease. Only a deliberate stable (>= the first
+  non-prerelease) should ever hold `latest`.
+
+## Rollback / yank
+
+- A published version cannot be overwritten and cannot be unpublished after 72h.
+  To pull a bad alpha: `npm deprecate neurain@<bad> "broken, use <good>"` and ship
+  a fixed `-alpha.<next>`.
+- To roll the consuming vault back to a prior engine: point `NEURAIN_ENGINE_BIN`
+  at the previous tag's checkout (or pin the previous npm version), or set
+  `NEURAIN_LEGACY=1` to fall back to the vault's preserved implementations.
+
+## Local Checks (manual fallback)
 
 ```bash
 npm ci

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neurain",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "description": "Local-first Neurain Knowledge OS CLI and MCP connector.",
   "type": "module",
   "license": "Apache-2.0",

package/src/cli.mjs

@@ -31,6 +31,20 @@ import { queueArchiveCommand } from './core/queue_archive.mjs';
 import { captureCommand } from './core/capture_durable.mjs';
 import { completeCommand } from './core/complete.mjs';
 import { linkCheckCommand } from './core/link_check.mjs';
+import { sessionLintCommand } from './core/session_lint.mjs';
+import { labelCommand } from './core/label.mjs';
+import { orphansCommand } from './core/orphans.mjs';
+import { hubsCommand } from './core/hubs.mjs';
+import { areaIndexCommand } from './core/area_index.mjs';
+import { lintCommand } from './core/lint.mjs';
+import { sessionPulseCommand } from './core/session_pulse.mjs';
+import { syncCommand } from './core/sync.mjs';
+import { healthCommand } from './core/health.mjs';
+import { memoryCommand } from './core/memory.mjs';
+import { retentionCommand } from './core/retention.mjs';
+import { freezeCommand } from './core/freeze.mjs';
+import { memoryWriteCommand } from './core/memory_write_cli.mjs';
+import { backupCommand } from './core/backup.mjs';
 import { schedulerCommand } from './core/scheduler.mjs';
 import { searchCommand } from './core/search.mjs';
 import { watchCommand } from './core/watch.mjs';
@@ -83,6 +97,20 @@ export async function runCli(argv) {
   if (command === 'capture') return render(await captureCommand(args));
   if (command === 'complete') return render(await completeCommand(args));
   if (command === 'link-check') return render(await linkCheckCommand(args));
+  if (command === 'session-lint') return render(await sessionLintCommand(args));
+  if (command === 'label') return render(await labelCommand(args));
+  if (command === 'orphans') return render(await orphansCommand(args));
+  if (command === 'hubs') return render(await hubsCommand(args));
+  if (command === 'area-index') return render(await areaIndexCommand(args));
+  if (command === 'lint') return render(await lintCommand(args));
+  if (command === 'session-pulse') return render(await sessionPulseCommand(args));
+  if (command === 'sync') return render(await syncCommand(args));
+  if (command === 'health') return render(await healthCommand(args));
+  if (command === 'memory') return render(await memoryCommand(args));
+  if (command === 'retention') return render(await retentionCommand(args));
+  if (command === 'freeze') return render(await freezeCommand(args));
+  if (command === 'memory-write') return render(await memoryWriteCommand(args));
+  if (command === 'backup') return render(await backupCommand(args));
   if (command === 'capabilities') return render(await capabilitiesCommand(args));
   if (command === 'recap') return render(await recapCommand(args));
   if (command === 'watch') return render(await watchCommand(args));
@@ -203,6 +231,20 @@ Usage:
   neurain capture <folder> [--text "..." | <text> | --file rel] [--session-id id] [--type memo] [--title t] [--area name] [--sensitivity s] [--intent i] [--allow-secret] [--dry-run] [--json]
   neurain complete <folder> --source-id id --compiled-to "a.md,b.md" [--status compiled] [--completed-at ts] [--dry-run] [--json]
   neurain link-check <folder> [--scope .] [--top 20] [--include-raw] [--include-archive] [--include-output] [--json]
+  neurain session-lint <folder> [--stale-days 7] [--now ms] [--json]
+  neurain label <folder> [--check | --apply] [--area name | --all] [--glob substr] [--limit N] [--json]
+  neurain orphans <folder> [--area name] [--fix] [--json]
+  neurain hubs <folder> [--check | --apply] [--area name] [--json]
+  neurain area-index <folder> [--build area | --refresh area | --register-curated area [--sensitivity private] | --detect [--fix] [--restamp-curated]] [--force] [--dry-run] [--json]
+  neurain lint <folder> [--json]
+  neurain session-pulse <folder> --session-id id --summary "..." [--focus t] [--next t] [--max-notes 8] [--no-area-brief] [--queue ...] [--now ts] [--dry-run] [--allow-secret] [--json]
+  neurain sync <folder> --session-id id [--summary "..."] [--level light|standard|full] [--no-pulse] [--no-area-brief] [--queue ...] [--now ts] [--dry-run] [--json]
+  neurain health <folder> [--fix] [--now ts] [--json]
+  neurain memory <folder> [--facts q | --tasks q | --conflicts | --verify | --stats] [--area name] [--top 10] [--json]
+  neurain retention <folder> [--area name] [--stale-days 120] [--write] [--now ms] [--json]
+  neurain freeze <folder> <acquire|release|status> [--owner name] [--json]
+  neurain memory-write <folder> --area name --file ledger.md --op add-fact|add-task|set-status|append-event [--fields json] [--changes json] [--event json] [--fact-id id] [--id id] [--apply] [--json]
+  neurain backup <folder> --target <dir> [--label name] | --verify <name> | --restore <name> [--to <dir>] | --drill <name> [--target <dir>] | --list [--json]
   neurain recap <folder> [--area name] [--json]
   neurain watch <folder> [--area name] [--since-minutes 1440] [--top 10] [--poll-once] [--json]
   neurain review <folder> [--area name] [--since-minutes 1440] [--top 10] [--json]
@@ -249,7 +291,16 @@ Alpha principles:
   - Source-digest and plan-receipt are W-B writers that touch only their own non-canonical artifacts: source-digest writes the rebuildable source-digest manifest (dry by default, --write to update) and plan-receipt writes an optional receipt under output/receipts/. Every durable write goes through an atomic temp+fsync+rename plus a cross-process lock, and the manifest's path sensitivity is decided by the label resolver, never hardcoded area names.
   - Stage is the secret gate: content lands in .neurain-staging (excluded from every walk), is scanned fail-closed for high-confidence secret shapes, mnemonics, context-aware hex keys, and high-entropy tokens, and is promoted to its canonical target by an atomic rename ONLY if clean; a hit holds the content in staging, leaves the target untouched, and exits 2. Queue-archive moves terminal queue rows into an append-only archive under one lock (archive appended before the hot-queue rewrite, so a crash never loses a row).
   - Capture and complete are the durable pipeline writers. They write raw markdown (capture, routed through the stage secret gate), the _inbox envelope, the writeback queue (capture appends, complete rewrites - both under a lock), and a wiki/log line, but they NEVER write session-state, handoff, or area-brief files: those stay W-D-owned, returned as an unapplied session_state_delta whose pending_count is advisory (the future vault shuttle recomputes at apply time). Capture is text-only in this increment; file capture and overlap/numeric enrichment are the documented flip gate.
-  - Link-check (W-C) is a read-only graph validator: it resolves every markdown link and wikilink against the vault and reports unresolved targets by file and area, writing nothing. Area buckets use the configured structural dirs, not hardcoded area names.
+  - Link-check and session-lint (W-C) are read-only validators that write nothing. Link-check resolves every markdown link and wikilink against the vault and reports unresolved targets by file and area. Session-lint validates the session layer: required paths, session-state vs handoff consistency, pending-count drift vs the queue, handoff frontmatter, and queue rows referencing known sessions. Both use the configured structural dirs, not hardcoded area names.
+  - Label (W-C) is the label-system CLI: --check (default, read-only) proposes the managed label block (type/areas/entities/domains/sensitivity/tags) per knowledge file and reports private leaks; --apply writes it additively and idempotently, atomic per file, refusing symlinks. The label brain (label_intel) hard-codes nothing vault-specific — vocabulary comes from each area's entity dictionary and tuning from an optional label-config.json. A private/published file never gets entity/domain tags.
+  - Backup (W-E) is the local snapshot + EXACT restore + restore-drill: the manifest records files (sha256+size) and dirs, symlinks/special files are refused, and restore reconstructs the target byte-exactly (and proves it) via stage-verify-rename-aside-reverify, so a no-git vault still has a verifiable rollback. The macOS/iCloud encrypted external backup stays vault-side.
+  - Memory-write (W-E) is the registry-driven fact/task ledger writer: schemas, ID templates, mandatory/dash columns and paths come from memory-write-registry.json, so every area is handled by the same code. It appends rows or edits a fact's lifecycle columns while keeping every other row byte-identical, under an O_EXCL lock with a sha256 compare-and-swap (concurrent modification aborts) + fsync. Default dry-run; a live write needs the area's write_enabled:true, a realpath inside area_root, a fail-closed secret scan, and the freeze lock not held.
+  - Memory and retention (W-E, read-only) query the per-area fact/task ledgers via a config-driven reader that maps heterogeneous table schemas by column name. Memory does status-aware fact/task lookup, conflicts, and verify; retention flags active facts for human review (contradicted / unverified / stale / low-confidence / missing-metadata) and never deletes (optional --write emits a report). Neither touches the ledgers.
+  - Health (W-D) composes doctor + lint into one verdict and reconciles session-state drift: pending_count's source of truth is the writeback queue and last_pulse's is the handoff frontmatter, so a session can drift. Read-only without --fix; with --fix it repairs drift via the locked session-state path and runs the W-C maintenance fixers (orphans, label, area-index) before a final lint.
+  - Session-pulse (W-D) is the session working-memory writer: it pulses one durable note into the handoff, optionally the area brief and a queue row, then advances session-state. Hardened per cross-review: markdown is written first and the authoritative session-state.json last (a crash leaves the markdown ahead but state recoverable), every write is atomic, the area brief is rendered + labelled in memory and written once, and the note is secret-scanned fail-closed. session-state writes are this wave's (W-D) responsibility; W-B's capture/complete only returned a delta for it to apply.
+  - Lint (W-C) is a read-only STRUCTURAL aggregator: it composes the ported validators (link-check, session-lint, advisory orphans) into one health verdict. It deliberately does NOT re-implement the vault's documentation-governance checks (master version, clipper templates, instruction lengths, progressive disclosure) — those stay vault-side.
+  - Area-index (W-C) generates a per-area search index from the area's own signals (wiki/entities pages, frontmatter entity_candidates, area-tagged raw envelopes, salience-gated content terms), registers it, detects staleness via a file signature, and refreshes drifted generated indexes. Curated indexes are never auto-overwritten; --detect is read-only, writes happen only with --build/--refresh/--register-curated/--detect --fix.
+  - Orphans and hubs (W-C) are the graph connection layer. Orphans reports knowledge files with no inbound and no outbound wikilink, classified (structural / has-entities / no-entities); --fix adds one additive per-area graph-backlog page (source files untouched). Hubs generates per-entity hub pages linking member notes (dry-run by default, --apply writes and prunes only its own hub_generated pages); private areas and private files are excluded, member files are never modified.
   - Live-cases scaffold creates a redacted E23 reviewed-case pack scaffold with hash-only source refs. It does not claim human evidence and stores no raw source text or absolute paths.
   - Onboard is a read-only first-run guide for non-developers. It explains the next command without creating files or calling a model.
   - Answer eval checks faithfulness, citation accuracy, conflict surfacing, abstention, private boundaries, and stale-source handling without model calls or writes.

package/src/core/area_index.mjs

@@ -0,0 +1,281 @@
+// `area-index` command (W-C). Per-area search-index automation: generates a
+// starter entity/domain index from an area's own high-confidence signals
+// (wiki/entities pages, frontmatter entity_candidates, area-tagged raw envelopes,
+// and salience-gated content terms), registers it, detects staleness via a file
+// signature, and refreshes drifted generated indexes. Curated indexes are never
+// auto-overwritten. Faithful, root-injected port of the vault neurain-area-index;
+// writes go through the engine atomic primitive. Self-contained, config-driven,
+// no vault identifiers.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { absPath, readText, relPath, timestamp, walkFiles } from './fs.mjs';
+import { vaultConfig } from './config.mjs';
+import { readJsonSafe } from './vault_state.mjs';
+import { atomicWriteJson } from './durable.mjs';
+
+const STOPLIST = new Set([
+  'the', 'and', 'for', 'with', 'this', 'that', 'from', 'into', 'over', 'current', 'status', 'index', 'area', 'note', 'notes',
+  'overview', 'summary', 'guide', 'report', 'readme', 'draft', 'final', 'update', 'system', 'data', 'file', 'files',
+  '그리고', '하지만', '현재', '관련', '내용', '정리', '요약', '개요', '문서', '항목', '경우', '대한', '위한',
+]);
+
+function parseFrontmatter(text) {
+  const m = String(text || '').match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return {};
+  const fm = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const mm = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+    if (!mm) continue;
+    let val = mm[2].trim();
+    if (val.startsWith('[') && val.endsWith(']')) val = val.slice(1, -1).split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    else val = val.replace(/^["']|["']$/g, '');
+    fm[mm[1]] = val;
+  }
+  return fm;
+}
+
+function toList(v) {
+  if (!v) return [];
+  return (Array.isArray(v) ? v : String(v).replace(/^\[|\]$/g, '').split(',')).map((s) => String(s).trim()).filter(Boolean);
+}
+function slug(v) {
+  return String(v || '').toLowerCase().replace(/[^a-z0-9가-힣]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 50) || 'x';
+}
+
+function mdFiles(root, relDir) {
+  return walkFiles(path.join(root, relDir), { includeRaw: true, maxFiles: 200000 })
+    .filter((abs) => abs.endsWith('.md'))
+    .map((abs) => relPath(root, abs));
+}
+
+function areaFiles(ctx, area) {
+  return mdFiles(ctx.root, `${ctx.areasDir}/${area}`)
+    .filter((rel) => !/(^|\/)(search-index|_trash|_archive)\//.test(rel))
+    .filter((rel) => !/(^|\/)current\/[^/]*-area-brief\.md$/.test(rel)); // rolling brief excluded from the signature
+}
+
+function signatureOf(ctx, relFiles) {
+  const parts = relFiles
+    .map((rel) => { try { const st = fs.statSync(path.join(ctx.root, rel)); return `${rel}|${Math.round(st.mtimeMs)}|${st.size}`; } catch { return ''; } })
+    .filter(Boolean)
+    .sort();
+  return crypto.createHash('sha256').update(parts.join('\n')).digest('hex');
+}
+
+function stripMarkup(text) {
+  return String(text || '')
+    .replace(/^---\n[\s\S]*?\n---/, ' ')
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`[^`]*`/g, ' ')
+    .replace(/!?\[[^\]]*\]\([^)]*\)/g, ' ')
+    .replace(/https?:\/\/\S+/g, ' ')
+    .replace(/[#>*_~|]/g, ' ');
+}
+
+function contentCandidates(ctx, relFiles) {
+  const freq = new Map();
+  const bump = (term, rel) => {
+    const key = String(term || '').trim().replace(/\s+/g, ' ').replace(/^(the|a|an)\s+/i, '');
+    if (key.length < 2 || key.length > 40) return;
+    const low = key.toLowerCase();
+    if (STOPLIST.has(low)) return;
+    const c = freq.get(low) || { term: key, count: 0, docs: new Set() };
+    c.count += 1; c.docs.add(rel); freq.set(low, c);
+  };
+  for (const rel of relFiles) {
+    const text = stripMarkup(readText(path.join(ctx.root, rel), ''));
+    for (const m of text.matchAll(/\b[A-Z][A-Z0-9]{1,7}\b/g)) bump(m[0], rel);
+    for (const m of text.matchAll(/\b[A-Z][a-z0-9]+(?:\s+[A-Z][a-z0-9]+){0,3}\b/g)) bump(m[0], rel);
+    for (const m of text.matchAll(/[가-힣぀-ヿ一-鿿]{2,12}/g)) bump(m[0], rel);
+  }
+  return [...freq.values()].filter((c) => c.docs.size >= 2 || c.count >= 3).sort((a, b) => b.count - a.count).slice(0, 60);
+}
+
+function highConfidenceEntities(ctx, area, relFiles) {
+  const byCanonical = new Map();
+  const add = (canonical, type, confidence, evidence) => {
+    const key = String(canonical || '').trim();
+    if (!key || key.length < 2 || STOPLIST.has(key.toLowerCase())) return;
+    const cur = byCanonical.get(key.toLowerCase()) || { canonical: key, type: type || 'entity', aliases: new Set([key]), confidence, evidence: new Set(), count: 0 };
+    cur.count += 1;
+    if (evidence) cur.evidence.add(evidence);
+    if (confidence === 'high') cur.confidence = 'high';
+    byCanonical.set(key.toLowerCase(), cur);
+  };
+
+  for (const rel of mdFiles(ctx.root, `${ctx.wikiDir}/entities`)) {
+    const text = readText(path.join(ctx.root, rel), '');
+    const fm = parseFrontmatter(text);
+    const areas = Array.isArray(fm.areas) ? fm.areas : String(fm.areas || '').split(',').map((s) => s.trim());
+    if (areas.includes(area)) add(fm.title || path.basename(rel, '.md'), 'entity', 'high', rel);
+  }
+  for (const rel of relFiles) {
+    const fm = parseFrontmatter(readText(path.join(ctx.root, rel), ''));
+    for (const c of toList(fm.entity_candidates)) add(c, 'entity', 'medium', rel);
+  }
+  const inboxAbs = path.join(ctx.root, ctx.rawInbox);
+  for (const file of (fs.existsSync(inboxAbs) ? fs.readdirSync(inboxAbs) : [])) {
+    if (!file.endsWith('.json')) continue;
+    const env = readJsonSafe(path.join(inboxAbs, file), null);
+    if (env && toList(env.area_candidates).includes(area)) {
+      for (const c of toList(env.entity_candidates)) add(c, 'entity', 'medium', `${ctx.rawInbox}/${file}`);
+    }
+  }
+  for (const c of contentCandidates(ctx, relFiles)) {
+    const low = c.term.toLowerCase();
+    const cur = byCanonical.get(low) || { canonical: c.term, type: 'term', aliases: new Set([c.term]), confidence: 'medium', evidence: new Set(), count: 0 };
+    cur.count += Math.max(2, c.docs.size);
+    for (const d of c.docs) cur.evidence.add(d);
+    byCanonical.set(low, cur);
+  }
+
+  return [...byCanonical.values()]
+    .filter((e) => e.confidence === 'high' || e.count >= 2)
+    .map((e) => ({ id: `entity:${area}:${slug(e.canonical)}`, type: e.type, canonical: e.canonical, aliases: [...e.aliases], confidence: e.confidence, evidence_docs: [...e.evidence].slice(0, 5) }));
+}
+
+function keywordsFromFolder(name) {
+  return name.replace(/^\d+[_-]?\d*[_-]?/, '').split(/[_\-\s]+/).map((s) => s.trim()).filter((s) => s.length >= 3 && !STOPLIST.has(s.toLowerCase()) && !/^\d+$/.test(s));
+}
+function domainsFromFolders(ctx, area) {
+  const dir = path.join(ctx.root, ctx.areasDir, area);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !/^(search-index|_trash|_archive|node_modules)/.test(d.name) && !d.name.startsWith('.'))
+    .map((d) => ({ id: `domain:${area}:${slug(d.name)}`, label: d.name, keywords: keywordsFromFolder(d.name), boost_paths: [`${ctx.areasDir}/${area}/${d.name}`] }))
+    .filter((d) => d.keywords.length);
+}
+
+function loadRegistry(ctx) {
+  return readJsonSafe(path.join(ctx.root, ctx.registryPath), { areas: {} }) || { areas: {} };
+}
+function saveRegistry(ctx, reg) {
+  atomicWriteJson(path.join(ctx.root, ctx.registryPath), reg);
+}
+
+function buildArea(ctx, area, { force = false } = {}) {
+  const reg = loadRegistry(ctx);
+  const existing = reg.areas?.[area];
+  if (existing?.curated) return { ok: false, area, error: 'curated index, refusing to overwrite (use the curated source)' };
+  if (existing && !force) return { ok: false, area, error: 'already registered; pass --force to rebuild a generated index' };
+
+  const relFiles = areaFiles(ctx, area);
+  const entities = highConfidenceEntities(ctx, area, relFiles);
+  const domains = domainsFromFolders(ctx, area);
+  const sig = signatureOf(ctx, relFiles);
+  const dir = `${ctx.areasDir}/${area}/search-index`;
+
+  if (!ctx.dryRun) {
+    atomicWriteJson(path.join(ctx.root, `${dir}/entities.json`), entities);
+    atomicWriteJson(path.join(ctx.root, `${dir}/domain-routing.json`), domains);
+    atomicWriteJson(path.join(ctx.root, `${dir}/meta.json`), {
+      area, generated: true, generated_at: timestamp(), signature: sig, candidate_count: entities.length, scanned_files: relFiles.length,
+      note: 'Auto-generated starter index. confidence high|medium only. Curate for precision; set "curated": true in the registry to stop auto-refresh.',
+    });
+    reg.areas = reg.areas || {};
+    const previous = reg.areas[area] || {};
+    reg.areas[area] = { ...previous, area_root: `${ctx.areasDir}/${area}`, index_dir: 'search-index', entities: 'entities.json', domain_routing: 'domain-routing.json', generated: true, signature: sig, path_map: previous.path_map || [] };
+    saveRegistry(ctx, reg);
+  }
+  return { ok: true, area, entities: entities.length, domains: domains.length, scanned: relFiles.length, signature: sig.slice(0, 12), dry_run: ctx.dryRun };
+}
+
+function registerCurated(ctx, area, { sensitivity } = {}) {
+  const dir = `${ctx.areasDir}/${area}/search-index`;
+  const entPath = path.join(ctx.root, `${dir}/entities.json`);
+  const domPath = path.join(ctx.root, `${dir}/domain-routing.json`);
+  if (!fs.existsSync(entPath) || !fs.existsSync(domPath)) return { ok: false, area, error: `curated source missing: write ${dir}/entities.json and ${dir}/domain-routing.json first` };
+  const entities = readJsonSafe(entPath, []);
+  const domains = readJsonSafe(domPath, []);
+  const relFiles = areaFiles(ctx, area);
+  const sig = signatureOf(ctx, relFiles);
+  if (!ctx.dryRun) {
+    atomicWriteJson(path.join(ctx.root, `${dir}/meta.json`), {
+      area, curated: true, generated: false, ...(sensitivity ? { sensitivity } : {}), curated_at: timestamp(), signature: sig,
+      entity_count: entities.length, domain_count: domains.length, scanned_files: relFiles.length,
+      note: 'Hand-curated entity/domain index. Do not auto-refresh; update curation when staleness is flagged.',
+    });
+    const reg = loadRegistry(ctx);
+    reg.areas = reg.areas || {};
+    const previous = reg.areas[area] || {};
+    reg.areas[area] = { ...previous, area_root: `${ctx.areasDir}/${area}`, index_dir: 'search-index', entities: 'entities.json', domain_routing: 'domain-routing.json', curated: true, ...(sensitivity ? { sensitivity } : {}), signature: sig, path_map: previous.path_map || [] };
+    saveRegistry(ctx, reg);
+  }
+  return { ok: true, area, mode: 'register-curated', entities: entities.length, domains: domains.length, scanned: relFiles.length, signature: sig.slice(0, 12), sensitivity: sensitivity || null, dry_run: ctx.dryRun };
+}
+
+function detect(ctx) {
+  const reg = loadRegistry(ctx);
+  const areasAbs = path.join(ctx.root, ctx.areasDir);
+  let present = [];
+  try {
+    present = fs.readdirSync(areasAbs, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && !d.name.startsWith('.')).map((d) => d.name)
+      .filter((a) => fs.existsSync(path.join(ctx.root, `${ctx.areasDir}/${a}/_area.md`)));
+  } catch { present = []; }
+  const missing = []; const stale_curated = []; const stale_generated = [];
+  for (const area of present) {
+    const entry = reg.areas?.[area];
+    if (!entry) { missing.push(area); continue; }
+    if (!entry.signature) continue;
+    if (entry.signature === signatureOf(ctx, areaFiles(ctx, area))) continue;
+    if (entry.curated) stale_curated.push(area); else stale_generated.push(area);
+  }
+  return { missing, stale_curated, stale_generated };
+}
+
+function refresh(ctx, area) {
+  const reg = loadRegistry(ctx);
+  const entry = reg.areas?.[area];
+  if (!entry) return { ok: false, area, error: 'not registered; use --build' };
+  if (entry.curated) return { ok: false, area, error: 'curated index, refusing to refresh' };
+  return buildArea(ctx, area, { force: true });
+}
+
+function autoTidy(ctx, restampCurated) {
+  const { missing, stale_curated, stale_generated } = detect(ctx);
+  const reg = loadRegistry(ctx);
+  const built = []; const refreshed = []; const restamped_curated = [];
+  for (const area of missing) if (buildArea(ctx, area, {}).ok) built.push(area);
+  for (const area of stale_generated) if (refresh(ctx, area).ok) refreshed.push(area);
+  if (restampCurated) {
+    for (const area of stale_curated) {
+      const sensitivity = reg.areas?.[area]?.sensitivity || null;
+      if (registerCurated(ctx, area, { sensitivity }).ok) restamped_curated.push(area);
+    }
+  }
+  const restamped = new Set(restamped_curated);
+  return { built, refreshed, restamped_curated, needs_recuration: stale_curated.filter((a) => !restamped.has(a)) };
+}
+
+export async function areaIndexCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const vaultCfg = vaultConfig(root);
+  const ctx = {
+    root,
+    registryPath: vaultCfg.search_index_registry,
+    areasDir: vaultCfg.areas_dir,
+    wikiDir: vaultCfg.wiki_dir,
+    rawInbox: vaultCfg.raw_inbox_dir,
+    dryRun: Boolean(args['dry-run']),
+  };
+
+  let result;
+  let durable = false;
+  if (args.detect && args.fix) { const t = autoTidy(ctx, Boolean(args['restamp-curated'])); result = { ok: true, mode: 'detect-fix', ...t }; durable = !ctx.dryRun && (t.built.length + t.refreshed.length + t.restamped_curated.length > 0); }
+  else if (args.detect) { result = { ok: true, mode: 'detect', ...detect(ctx) }; }
+  else if (args['register-curated']) { result = registerCurated(ctx, String(args['register-curated']), { sensitivity: args.sensitivity ? String(args.sensitivity) : null }); durable = !ctx.dryRun && result.ok !== false; }
+  else if (args.refresh) { result = { mode: 'refresh', ...refresh(ctx, String(args.refresh)) }; durable = !ctx.dryRun && result.ok !== false; }
+  else if (args.build) { result = { mode: 'build', ...buildArea(ctx, String(args.build), { force: Boolean(args.force) }) }; durable = !ctx.dryRun && result.ok !== false; }
+  else {
+    process.exitCode = 1;
+    const payload = { ok: false, command: 'area-index', durable_write: false, error: 'Use --build <area> | --register-curated <area> [--sensitivity private] | --detect [--fix] [--restamp-curated] | --refresh <area>' };
+    return args.json ? { json: true, payload } : { text: payload.error };
+  }
+
+  const payload = { command: 'area-index', durable_write: durable, ...result };
+  if (payload.ok === false) process.exitCode = 1;
+  if (args.json) return { json: true, payload };
+  return { text: JSON.stringify(payload, null, 2) };
+}

package/src/core/backup.mjs

@@ -0,0 +1,171 @@
+// `backup` command (W-E). Local snapshot + EXACT restore + restore-drill. In a
+// no-git vault this is the only rollback, so restore reconstructs the target
+// EXACTLY (every backed-up file byte-identical AND no extra files) and proves it.
+// The manifest records files (sha256+size) and dirs; symlinks/special files are
+// REFUSED (never silently dropped). Restore is atomic-ish: stage into a sibling
+// temp, verify, rename the live tree aside, move the staged tree in, re-verify,
+// drop the aside. Faithful, root-injected port of the vault neurain-backup. (The
+// macOS/iCloud external-encrypted-backup tool stays vault-side.)
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { absPath } from './fs.mjs';
+import { vaultConfig } from './config.mjs';
+
+const sha256File = (abs) => crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
+const stamp = () => new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
+
+function walkTree(absRoot) {
+  const files = []; const dirs = [];
+  (function rec(absDir) {
+    for (const e of fs.readdirSync(absDir, { withFileTypes: true })) {
+      if (e.name === '.DS_Store') continue;
+      const abs = path.join(absDir, e.name);
+      const rel = path.relative(absRoot, abs).split(path.sep).join('/');
+      if (e.isSymbolicLink()) throw new Error(`symlink not supported in backup target: ${rel}`);
+      if (e.isDirectory()) { dirs.push(rel); rec(abs); }
+      else if (e.isFile()) files.push({ rel, sha256: sha256File(abs), size: fs.statSync(abs).size });
+      else throw new Error(`unsupported entry (not a regular file or dir): ${rel}`);
+    }
+  })(absRoot);
+  files.sort((a, b) => a.rel.localeCompare(b.rel));
+  dirs.sort();
+  return { files, dirs };
+}
+function copyTree(srcRoot, dstRoot, manifest) {
+  fs.mkdirSync(dstRoot, { recursive: true });
+  for (const d of manifest.dirs || []) fs.mkdirSync(path.join(dstRoot, d), { recursive: true });
+  for (const f of manifest.files) {
+    const dst = path.join(dstRoot, f.rel);
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    fs.copyFileSync(path.join(srcRoot, f.rel), dst);
+  }
+}
+function compareExact(rootAbs, manifest) {
+  const missing = []; const mismatched = []; const extra = [];
+  const expected = new Set(manifest.files.map((f) => f.rel));
+  for (const f of manifest.files) {
+    const abs = path.join(rootAbs, f.rel);
+    if (!fs.existsSync(abs)) missing.push(f.rel);
+    else if (sha256File(abs) !== f.sha256) mismatched.push(f.rel);
+  }
+  let actual;
+  try { actual = walkTree(rootAbs); } catch (e) { return { missing, mismatched, extra: [`<walk error: ${e.message}>`] }; }
+  for (const f of actual.files) if (!expected.has(f.rel)) extra.push(f.rel);
+  const expectedDirs = new Set(manifest.dirs || []);
+  for (const d of manifest.dirs || []) { const abs = path.join(rootAbs, d); if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) missing.push(`${d}/`); }
+  for (const d of actual.dirs) if (!expectedDirs.has(d)) extra.push(`${d}/`);
+  return { missing, mismatched, extra };
+}
+const isExact = (c) => c.missing.length === 0 && c.mismatched.length === 0 && c.extra.length === 0;
+function assertSafeRel(rel, kind) {
+  if (typeof rel !== 'string' || rel === '' || path.isAbsolute(rel)) throw new Error(`unsafe manifest ${kind}: ${JSON.stringify(rel)}`);
+  const norm = path.normalize(rel).split(path.sep).join('/');
+  if (norm === '..' || norm.startsWith('../') || norm.includes('/../') || norm !== rel) throw new Error(`unsafe/non-normalized manifest ${kind}: ${rel}`);
+}
+function loadManifest(backupRoot, name) {
+  const m = JSON.parse(fs.readFileSync(path.join(backupRoot, name, 'manifest.json'), 'utf8'));
+  for (const f of m.files || []) assertSafeRel(f.rel, 'file');
+  for (const d of m.dirs || []) assertSafeRel(d, 'dir');
+  return m;
+}
+function realTargetUnderRoot(root, toAbs) {
+  const rootReal = fs.realpathSync(root);
+  const abs = path.resolve(toAbs);
+  let real;
+  try { real = fs.realpathSync(abs); } catch {
+    let parent = path.dirname(abs); let realParent;
+    try { realParent = fs.realpathSync(parent); } catch { realParent = parent; }
+    real = path.join(realParent, path.basename(abs));
+  }
+  if (real !== rootReal && !real.startsWith(rootReal + path.sep)) throw new Error(`restore target escapes the vault (symlink ancestor?): ${toAbs}`);
+  return real;
+}
+
+function doBackup(root, backupRoot, targetRel, label) {
+  const targetAbs = path.join(root, targetRel);
+  if (!fs.existsSync(targetAbs) || !fs.statSync(targetAbs).isDirectory()) throw new Error(`target must be an existing directory: ${targetRel}`);
+  const tree = walkTree(targetAbs);
+  const name = `${stamp()}${label ? `_${label}` : ''}`;
+  const dataAbs = path.join(backupRoot, name, 'data');
+  const manifest = { name, target: targetRel, created: new Date().toISOString(), dirs: tree.dirs, files: tree.files };
+  copyTree(targetAbs, dataAbs, manifest);
+  fs.writeFileSync(path.join(backupRoot, name, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+  const cmp = compareExact(dataAbs, manifest);
+  return { name, file_count: tree.files.length, dir_count: tree.dirs.length, verified: isExact(cmp), cmp };
+}
+function restore(root, backupRoot, name, toRel) {
+  const m = loadManifest(backupRoot, name);
+  const dataAbs = path.join(backupRoot, name, 'data');
+  if (!isExact(compareExact(dataAbs, m))) throw new Error(`backup ${name} failed its own integrity check; refusing to restore`);
+  const toAbs = path.join(root, toRel || m.target);
+  realTargetUnderRoot(root, toAbs);
+  if (fs.existsSync(toAbs) && !fs.statSync(toAbs).isDirectory()) throw new Error(`restore target exists and is not a directory: ${toRel || m.target}`);
+  const tmp = `${toAbs}.restore-tmp-${process.pid}`;
+  fs.rmSync(tmp, { recursive: true, force: true });
+  copyTree(dataAbs, tmp, m);
+  if (!isExact(compareExact(tmp, m))) { fs.rmSync(tmp, { recursive: true, force: true }); throw new Error('staged restore tree did not match the manifest; aborting'); }
+  const aside = `${toAbs}.replaced-${stamp()}`;
+  if (fs.existsSync(toAbs)) fs.renameSync(toAbs, aside);
+  try { fs.renameSync(tmp, toAbs); } catch (e) { if (fs.existsSync(aside)) fs.renameSync(aside, toAbs); fs.rmSync(tmp, { recursive: true, force: true }); throw e; }
+  const final = compareExact(toAbs, m);
+  const ok = isExact(final);
+  if (ok && fs.existsSync(aside)) fs.rmSync(aside, { recursive: true, force: true });
+  return { name, to: toRel || m.target, ok, final, aside_kept: ok ? null : aside };
+}
+function drill(root, backupRoot, name, targetRel) {
+  const m = loadManifest(backupRoot, name);
+  const dataAbs = path.join(backupRoot, name, 'data');
+  const backupIntegrity = compareExact(dataAbs, m);
+  const targetAbs = path.join(root, targetRel || m.target);
+  const liveBefore = walkTree(targetAbs);
+  const scratch = `${targetAbs}.drill-${process.pid}`;
+  fs.rmSync(scratch, { recursive: true, force: true });
+  copyTree(dataAbs, scratch, m);
+  const vsManifest = compareExact(scratch, m);
+  const vsLive = compareExact(scratch, { dirs: liveBefore.dirs, files: liveBefore.files });
+  fs.rmSync(scratch, { recursive: true, force: true });
+  const liveUnchanged = JSON.stringify(liveBefore) === JSON.stringify(walkTree(targetAbs));
+  return { name, target: targetRel || m.target, backupIntegrity, vsManifest, vsLive, liveUnchanged };
+}
+
+export async function backupCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const vaultCfg = vaultConfig(root);
+  const backupRoot = path.join(root, vaultCfg.archive_dir, '_backups');
+
+  let payload;
+  try {
+    if (args.list) {
+      const names = fs.existsSync(backupRoot) ? fs.readdirSync(backupRoot).filter((n) => fs.existsSync(path.join(backupRoot, n, 'manifest.json'))) : [];
+      payload = { ok: true, command: 'backup', durable_write: false, op: 'list', backups: names.map((n) => { const m = loadManifest(backupRoot, n); return { name: n, target: m.target, files: m.files.length, dirs: m.dirs.length, created: m.created }; }) };
+    } else if (args.verify) {
+      const m = loadManifest(backupRoot, String(args.verify));
+      const c = compareExact(path.join(backupRoot, String(args.verify), 'data'), m);
+      payload = { ok: isExact(c), command: 'backup', durable_write: false, op: 'verify', name: String(args.verify), files: m.files.length, missing: c.missing.length, changed: c.mismatched.length, extra: c.extra.length };
+      if (!payload.ok) process.exitCode = 1;
+    } else if (args.drill) {
+      const r = drill(root, backupRoot, String(args.drill), args.target);
+      const ok = isExact(r.backupIntegrity) && isExact(r.vsManifest) && isExact(r.vsLive) && r.liveUnchanged;
+      payload = { ok, command: 'backup', durable_write: false, op: 'drill', name: r.name, target: r.target, backup_integrity: isExact(r.backupIntegrity), restored_eq_manifest: isExact(r.vsManifest), restored_eq_live: isExact(r.vsLive), live_unchanged: r.liveUnchanged };
+      if (!ok) process.exitCode = 1;
+    } else if (args.restore) {
+      const r = restore(root, backupRoot, String(args.restore), args.to);
+      payload = { ok: r.ok, command: 'backup', durable_write: true, op: 'restore', name: r.name, to: r.to, exact: r.ok, aside_kept: r.aside_kept };
+      if (!r.ok) process.exitCode = 1;
+    } else if (args.target) {
+      const r = doBackup(root, backupRoot, String(args.target), args.label);
+      payload = { ok: r.verified, command: 'backup', durable_write: true, op: 'snapshot', name: r.name, file_count: r.file_count, dir_count: r.dir_count, verified: r.verified };
+      if (!r.verified) process.exitCode = 1;
+    } else {
+      process.exitCode = 1;
+      payload = { ok: false, command: 'backup', durable_write: false, error: 'usage: --target <dir> [--label] | --verify <name> | --restore <name> [--to <dir>] | --drill <name> [--target <dir>] | --list' };
+    }
+  } catch (e) {
+    process.exitCode = 1;
+    payload = { ok: false, command: 'backup', durable_write: false, error: e.message };
+  }
+
+  if (args.json) return { json: true, payload };
+  return { text: payload.error ? `# Neurain Backup\n\n- ${payload.error}` : `# Neurain Backup\n\n- Op: ${payload.op}\n- OK: ${payload.ok ? 'yes' : 'no'}${payload.name ? `\n- Name: ${payload.name}` : ''}` };
+}