neurain 0.1.0-alpha.0

package/src/core/recall_intel.mjs

@@ -0,0 +1,233 @@
+// Routed search intelligence for recall (W-A). A dependency-free, pure-JS port of
+// the vault's search-intel adapter: it reads per-area entity / domain / intent /
+// alias indexes registered in a search index registry (default
+// 00_system/neurain/search-index-registry.json) and exposes detection, routing,
+// and query-expansion primitives that the lexical ranker uses for the BM25 +
+// structural boosts. Every file is optional: a missing registry or a missing
+// area index contributes nothing and never throws, so a generic vault with no
+// routing data degrades to plain BM25 + structural boosts. Unlike the vault
+// original this holds no module-global cache; the loaded intel lives on the
+// lexical context object the caller builds, which keeps it testable.
+import fs from 'node:fs';
+import path from 'node:path';
+
+function readJsonSafe(absPath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(absPath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+export function normalizeText(value) {
+  return String(value ?? '').toLowerCase();
+}
+
+function normalizeRel(value) {
+  return String(value ?? '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+// Short-token rule (vault parity): 1-3 char alnum tokens match only on word
+// boundaries, so short codes (CR, IR, LP, DD) do not over-match inside longer
+// words; 4+ char tokens match as substrings.
+export function includesTermBoundary(normalizedText, term) {
+  const value = normalizeText(term).trim();
+  if (!value) return false;
+  if (/^[a-z0-9]{1,3}$/.test(value)) {
+    const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(^|[^a-z0-9])${escaped}($|[^a-z0-9])`).test(normalizedText);
+  }
+  return normalizedText.includes(value);
+}
+
+// Resolve an area-cwd-relative path to a real root-relative path by applying the
+// area's path_map and returning the first candidate that exists; falls back to
+// area_root/value. Mirrors the vault resolveRepoPath so boost paths land on the
+// same root-relative paths the corpus emits.
+function resolveAreaPath(root, value, areaRoot, pathMap) {
+  const normalized = normalizeRel(value);
+  if (!normalized) return '';
+  const candidates = [normalized];
+  for (const rule of pathMap || []) {
+    if (rule && rule.prefix && normalized.startsWith(rule.prefix)) {
+      candidates.push(rule.replace_with + normalized.slice(rule.prefix.length));
+    }
+  }
+  for (const candidate of candidates) {
+    const rel = `${areaRoot}/${candidate}`;
+    if (fs.existsSync(path.join(root, rel))) return rel;
+  }
+  return `${areaRoot}/${normalized}`;
+}
+
+// Domain-pack merge (vault parity): kaia routes are spread across pack files, so
+// skipping packs would silently weaken route_authority boosts.
+function loadDomainPacks(root, areaRoot, indexDir, packRegistryRel) {
+  if (!packRegistryRel) return [];
+  const registry = readJsonSafe(path.join(root, `${areaRoot}/${indexDir}/${packRegistryRel}`), null);
+  if (!registry || !Array.isArray(registry.pack_paths)) return [];
+  const packsDir = path.posix.dirname(`${indexDir}/${packRegistryRel}`);
+  const packs = [];
+  for (const rel of registry.pack_paths) {
+    const pack = readJsonSafe(path.join(root, `${areaRoot}/${packsDir}/${rel}`), null);
+    if (pack) packs.push(pack);
+  }
+  return packs;
+}
+
+// Search-only projection of a domain pack: keep the ranking fields, drop
+// answer/capture/flush fields (not used by search). Pack member entities are NOT
+// route keywords (that over-routes); aliases are the intended triggers.
+function packToRoute(pack, fallback = {}) {
+  const aliases = Array.isArray(pack.aliases) ? pack.aliases : [];
+  const keywords = [...new Set([...(fallback.keywords ?? []), ...aliases])];
+  return {
+    ...fallback,
+    id: pack.id,
+    label: pack.label ?? fallback.label,
+    ledger: pack.ledger || fallback.ledger || '',
+    keywords,
+    entity_ids: fallback.entity_ids ?? [],
+    source_priority: pack.source_priority ?? fallback.source_priority ?? [],
+    current_files: pack.current_files ?? fallback.current_files ?? [],
+  };
+}
+
+// Load and resolve the per-area routing intelligence into one snapshot. No
+// module cache: the caller owns the returned object.
+export function loadRecallIntel(root, recallCfg) {
+  const registryRel = recallCfg?.intel?.registry || '00_system/neurain/search-index-registry.json';
+  const registry = readJsonSafe(path.join(root, registryRel), { areas: {} });
+  const entities = [];
+  const routes = [];
+  const intents = [];
+  const aliases = [];
+  const relationshipPaths = [];
+
+  for (const [area, entry] of Object.entries(registry.areas || {})) {
+    if (!entry || !entry.area_root || !entry.index_dir) continue;
+    const base = `${entry.area_root}/${entry.index_dir}`;
+    const pm = entry.path_map || [];
+    const resolve = (value) => resolveAreaPath(root, value, entry.area_root, pm);
+
+    for (const e of readJsonSafe(path.join(root, `${base}/${entry.entities}`), [])) {
+      entities.push({
+        area,
+        id: e.id,
+        type: e.type,
+        canonical: e.canonical,
+        aliases: e.aliases || [],
+        source_docs: (e.source_docs || []).map(resolve),
+      });
+    }
+
+    const baseRoutes = readJsonSafe(path.join(root, `${base}/${entry.domain_routing}`), []);
+    const byId = new Map((Array.isArray(baseRoutes) ? baseRoutes : []).map((r) => [r.id, { ...r }]));
+    for (const pack of loadDomainPacks(root, entry.area_root, entry.index_dir, entry.domain_pack_registry)) {
+      byId.set(pack.id, { ...(byId.get(pack.id) ?? {}), ...packToRoute(pack, byId.get(pack.id) ?? {}) });
+    }
+    for (const r of byId.values()) {
+      const boostPaths = [
+        ...(r.boost_paths || []),
+        ...(r.source_priority || []),
+        ...(r.current_files || []),
+        ...(r.ledger ? [r.ledger] : []),
+      ].map(resolve);
+      routes.push({
+        area,
+        id: r.id,
+        label: r.label,
+        keywords: r.keywords || [],
+        entity_ids: r.entity_ids || [],
+        authority_weight: Number.isFinite(Number(r.authority_weight)) ? Number(r.authority_weight) : 50,
+        boost_paths: [...new Set(boostPaths)],
+      });
+    }
+
+    for (const i of readJsonSafe(path.join(root, `${base}/${entry.query_intents}`), [])) {
+      intents.push({ area, id: i.id, triggers: i.triggers || [], expansions: i.expansions || [], boost_paths: (i.boost_paths || []).map(resolve) });
+    }
+    for (const a of readJsonSafe(path.join(root, `${base}/${entry.semantic_aliases}`), [])) {
+      aliases.push({ area, id: a.id, label: a.label, triggers: a.triggers || [], expansions: a.expansions || [], boost_paths: (a.boost_paths || []).map(resolve) });
+    }
+    if (entry.relationships) relationshipPaths.push(resolve(`${entry.index_dir}/${entry.relationships}`));
+  }
+
+  return { entities, routes, intents, aliases, relationshipPaths };
+}
+
+const EMPTY_INTEL = { entities: [], routes: [], intents: [], aliases: [], relationshipPaths: [] };
+
+export function detectEntities(query, intel = EMPTY_INTEL) {
+  const q = normalizeText(query);
+  return intel.entities.filter((e) => (e.aliases || []).some((a) => includesTermBoundary(q, a)));
+}
+
+export function routeDomains(query, intel = EMPTY_INTEL) {
+  const q = normalizeText(query);
+  return intel.routes.filter((r) => (r.keywords || []).some((k) => includesTermBoundary(q, k)));
+}
+
+// Directly-mentioned entities PLUS entities sharing a relevant domain (a domain
+// is relevant if the query routes to it by keyword or it groups a detected
+// entity). The per-area domain entity_ids encode those relationships, so this
+// stays generic instead of hardcoding any one area's graph.
+export function relevantEntities(query, intel = EMPTY_INTEL) {
+  const direct = detectEntities(query, intel);
+  const directIds = new Set(direct.map((e) => e.id));
+  const byId = new Map(intel.entities.map((e) => [e.id, e]));
+  const relevantDomainIds = new Set(routeDomains(query, intel).map((r) => r.id));
+  for (const r of intel.routes) {
+    if ((r.entity_ids || []).some((id) => directIds.has(id))) relevantDomainIds.add(r.id);
+  }
+  const out = new Map(direct.map((e) => [e.id, e]));
+  for (const r of intel.routes) {
+    if (!relevantDomainIds.has(r.id)) continue;
+    for (const id of r.entity_ids || []) {
+      const e = byId.get(id);
+      if (e && !out.has(id)) out.set(id, e);
+    }
+  }
+  return [...out.values()];
+}
+
+export function expandIntelQuery(query, intel = EMPTY_INTEL) {
+  const q = normalizeText(query);
+  const out = [];
+  for (const i of intel.intents) if ((i.triggers || []).some((t) => includesTermBoundary(q, t))) out.push(...i.expansions);
+  for (const a of intel.aliases) if ((a.triggers || []).some((t) => includesTermBoundary(q, t))) out.push(...a.expansions);
+  return [...new Set(out)];
+}
+
+export function intelBoostPathsForQuery(query, intel = EMPTY_INTEL) {
+  const q = normalizeText(query);
+  const out = [];
+  for (const i of intel.intents) {
+    if ((i.triggers || []).some((t) => includesTermBoundary(q, t))) out.push(...(i.boost_paths || []));
+  }
+  for (const a of intel.aliases) {
+    if ((a.triggers || []).some((t) => includesTermBoundary(q, t))) out.push(...(a.boost_paths || []));
+  }
+  return [...new Set(out)];
+}
+
+// Vault-wide alias map (default 00_system/neurain/search-aliases.json): Korean /
+// nickname triggers that expand to English-canonical terms. Returned as a plain
+// map; expansion is applied by the lexical ranker.
+export function loadAliasMap(root, recallCfg) {
+  const aliasesRel = recallCfg?.intel?.aliases || '00_system/neurain/search-aliases.json';
+  const map = readJsonSafe(path.join(root, aliasesRel), { aliases: {} });
+  return map && typeof map.aliases === 'object' ? map.aliases : {};
+}
+
+export function expandAliases(aliasMap, queryLower) {
+  const out = [];
+  for (const [alias, expansions] of Object.entries(aliasMap || {})) {
+    if (queryLower.includes(String(alias).toLowerCase())) {
+      for (const expansion of expansions || []) {
+        for (const token of String(expansion).toLowerCase().split(/\s+/).filter(Boolean)) out.push(token);
+      }
+    }
+  }
+  return out;
+}

package/src/core/recall_lexical.mjs

@@ -0,0 +1,269 @@
+// Routed lexical ranker for recall (W-A). A faithful, engine-idiom port of the
+// vault's search-core scoring: substring-based BM25 over raw file text plus the
+// additive structural boosts (exact match, slug-in-path, phrase, heading), layer
+// boosts (wiki_core, session_handoff, area_index, queue/raw_inbox), and the
+// routing/memory boosts (entity authority, domain route authority, entity
+// overlap, relationship, fact-ledger fusion), then a per-layer diversity cap.
+// The BM25 constants and every boost weight are kept IDENTICAL to the vault
+// because the parity gate measures the formula, not the file layout; the
+// engine-style part is structural (pure functions over an explicit context, no
+// module globals, config-injected directory names, the shared corpus selector).
+//
+// Scores RAW file text, not the whitespace-normalized recall-doc bodies, because
+// headText/phrase/length all depend on the original line structure. Terms are
+// derived by whitespace split with punctuation retained (vault parity), NOT the
+// semantic tokenizer.
+import path from 'node:path';
+import { listRecallMarkdownFiles, reEsc } from './recall_corpus.mjs';
+import { readText } from './fs.mjs';
+import {
+  detectEntities,
+  expandAliases,
+  expandIntelQuery,
+  includesTermBoundary,
+  intelBoostPathsForQuery,
+  loadAliasMap,
+  loadRecallIntel,
+  relevantEntities,
+  routeDomains,
+} from './recall_intel.mjs';
+import { factsFor, loadFactIntel } from './recall_facts.mjs';
+
+const sourceIdPattern = /\braw-\d{8}-(?:\d{3}|dryrun)\b/i;
+// BM25 content weight relative to the additive structural boosts (vault parity).
+const BM25_WEIGHT = 4;
+const BM25_K1 = 1.5;
+const BM25_B = 0.75;
+
+function dirsFromConfig(recallCfg) {
+  const systemDir = recallCfg.system_dir || '00_system';
+  return {
+    areasDir: recallCfg.areas_dir || '10_areas',
+    wikiDir: recallCfg.wiki_dir || 'wiki',
+    systemDir,
+    hubsDir: recallCfg.hubs_dir || '20_hubs',
+    handoffDir: `${systemDir}/sessions/handoffs`,
+    rawInbox: `${recallCfg.raw_dir || 'raw'}/_inbox`,
+    queueRel: recallCfg.intel?.queue || '00_system/neurain/writeback-queue.jsonl',
+  };
+}
+
+// Precompiled layer classifier. Per-area buckets (area:<name>) so the diversity
+// cap applies within each area, letting several areas surface instead of one
+// crowding the rest out (vault parity).
+function makeLayerClassifier(dirs) {
+  const wikiCore = new RegExp(`^${reEsc(dirs.wikiDir)}/(concepts|source-summaries|entities|decisions)/`);
+  const areaIndex = new RegExp(`^${reEsc(dirs.areasDir)}/[^/]+/(?:_area|index|sources_map|log)\\.md$`);
+  const areaBucket = new RegExp(`^${reEsc(dirs.areasDir)}/([^/]+)/`);
+  return (rel) => {
+    if (rel === dirs.queueRel) return 'queue_metadata';
+    if (wikiCore.test(rel)) return 'wiki_core';
+    if (rel.startsWith(`${dirs.handoffDir}/`)) return 'session_handoff';
+    if (rel === `${dirs.systemDir}/area-registry.md`) return 'area_index';
+    if (areaIndex.test(rel)) return 'area_index';
+    if (rel.startsWith(`${dirs.rawInbox}/`)) return 'raw_inbox';
+    if (rel.startsWith(`${dirs.wikiDir}/`)) return 'wiki_other';
+    if (rel.startsWith(`${dirs.systemDir}/`)) return 'system';
+    const match = rel.match(areaBucket);
+    if (match) return `area:${match[1]}`;
+    return 'root';
+  };
+}
+
+function capLayerResults(items, limit, queryLooksLikeSourceId) {
+  if (!Number.isFinite(limit) || limit <= 0) return items;
+  const counts = new Map();
+  const capped = [];
+  for (const item of items) {
+    const count = counts.get(item.layer) || 0;
+    const sourceIdExempt = queryLooksLikeSourceId && ['queue_metadata', 'raw_inbox'].includes(item.layer);
+    if (item.exact_match || item.authoritative || sourceIdExempt || count < limit) {
+      capped.push(item);
+      counts.set(item.layer, count + 1);
+    }
+  }
+  return capped;
+}
+
+function headText(text) {
+  const parts = [];
+  const lines = String(text || '').split(/\r?\n/);
+  for (const line of lines.slice(0, 14)) {
+    const titleMatch = line.match(/^title:\s*(.+)$/i);
+    if (titleMatch) parts.push(titleMatch[1].replace(/['"]/g, ''));
+    if (/^#{1,2}\s+/.test(line)) {
+      parts.push(line.replace(/^#{1,2}\s+/, ''));
+      break;
+    }
+  }
+  return parts.join(' ').toLowerCase();
+}
+
+function slugish(value) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/['"]/g, '')
+    .replace(/[^a-z0-9가-힣]+/gi, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// Build the QUERY-INDEPENDENT lexical context once (corpus walk + raw reads +
+// intel/facts/alias snapshots + the held-aside queue doc), reused across many
+// queries. intel/facts/aliasMap can be injected (tests); otherwise loaded from
+// the registry, degrading to empty when files are absent.
+export function buildLexicalContext(root, { area = '', recallCfg, intel, facts, aliasMap } = {}) {
+  if (!recallCfg) throw new Error('buildLexicalContext requires recallCfg');
+  const dirs = dirsFromConfig(recallCfg);
+  const classify = makeLayerClassifier(dirs);
+  const files = listRecallMarkdownFiles(root, recallCfg, { area });
+  const baseDocs = files.map(({ rel, text }) => ({
+    text,
+    lower: text.toLowerCase(),
+    relPath: rel,
+    layer: classify(rel),
+    length: text.length,
+  }));
+  const queueText = readText(path.join(root, dirs.queueRel), '');
+  const queueDoc = {
+    text: queueText,
+    lower: queueText.toLowerCase(),
+    relPath: dirs.queueRel,
+    layer: 'queue_metadata',
+    length: queueText.length,
+  };
+  return {
+    root,
+    area,
+    recallCfg,
+    dirs,
+    baseDocs,
+    queueDoc,
+    intel: intel || loadRecallIntel(root, recallCfg),
+    facts: facts || loadFactIntel(root, recallCfg),
+    aliasMap: aliasMap || loadAliasMap(root, recallCfg),
+  };
+}
+
+// Run ONE query against a prebuilt lexical context. Returns
+// { query, top, results } where each result carries score, layer, signals,
+// matched_entities, exact_match, authoritative. Pure over ctx.
+export function lexicalSearchWithContext(ctx, query, { top = 10, maxPerLayer = 3, includeQueue: forceQueue = false } = {}) {
+  const queryLooksLikeSourceId = sourceIdPattern.test(String(query));
+  const includeQueue = Boolean(forceQueue) || queryLooksLikeSourceId || /\bqueue\b|writeback/i.test(String(query));
+
+  const terms = String(query).toLowerCase().split(/\s+/).filter(Boolean);
+  const aliasTerms = expandAliases(ctx.aliasMap, String(query).toLowerCase());
+  const intel = ctx.intel;
+  const queryEntities = detectEntities(query, intel);
+  const queryDomains = routeDomains(query, intel);
+  const relEntities = relevantEntities(query, intel);
+  const intelTerms = expandIntelQuery(query, intel)
+    .flatMap((s) => String(s).toLowerCase().split(/\s+/))
+    .filter(Boolean);
+  const entityBoostPaths = new Set(relEntities.flatMap((e) => e.source_docs));
+  const routeBoostWeights = new Map();
+  const addRouteBoost = (p, weight = 50) => routeBoostWeights.set(p, (routeBoostWeights.get(p) || 0) + weight);
+  for (const d of queryDomains) for (const p of d.boost_paths) addRouteBoost(p, d.authority_weight);
+  for (const p of intelBoostPathsForQuery(query, intel)) addRouteBoost(p, 50);
+  const intelBoostPaths = new Set([...entityBoostPaths, ...routeBoostWeights.keys()]);
+  const intelRelationshipPaths = new Set(intel.relationshipPaths);
+  const queryIsFollowup = /follow|owner|담당|누가|들고|액션|action|next|task|태스크|follow-up|후속/i.test(String(query));
+  const memBoostPaths = new Set(
+    queryEntities.length || queryDomains.length
+      ? factsFor(query, ctx.facts, { top: 40 }).flatMap((f) => [...(f.sources_resolved || []), f.file]).filter(Boolean)
+      : []
+  );
+  const searchTerms = [...new Set([...terms, ...aliasTerms, ...intelTerms])];
+
+  const docs = includeQueue ? [...ctx.baseDocs, ctx.queueDoc] : ctx.baseDocs;
+  const docCount = docs.length || 1;
+  const avgLength = docs.reduce((sum, doc) => sum + doc.length, 0) / docCount || 1;
+  const idf = {};
+  for (const term of searchTerms) {
+    const docFrequency = docs.reduce((count, doc) => count + (doc.lower.includes(term) ? 1 : 0), 0);
+    idf[term] = Math.log(1 + (docCount - docFrequency + 0.5) / (docFrequency + 0.5));
+  }
+
+  function scoreDoc(doc) {
+    const { lower, text, relPath, layer, length } = doc;
+    const lowerPath = relPath.toLowerCase();
+    const queryLower = String(query).toLowerCase();
+    const querySlug = slugish(queryLower);
+
+    let bm25 = 0;
+    for (const term of searchTerms) {
+      const tf = lower.split(term).length - 1;
+      if (tf === 0) continue;
+      const denom = tf + BM25_K1 * (1 - BM25_B + (BM25_B * length) / avgLength);
+      bm25 += (idf[term] || 0) * ((tf * (BM25_K1 + 1)) / denom);
+    }
+    let score = bm25 * BM25_WEIGHT;
+    const signals = {};
+    if (bm25 > 0) signals.bm25 = Math.round(bm25 * BM25_WEIGHT * 100) / 100;
+
+    if (lower.includes(queryLower)) { score += 5; signals.phrase = 5; }
+
+    const head = headText(text);
+    let headingBonus = 0;
+    for (const term of searchTerms) {
+      if (head.includes(term)) { score += 6; headingBonus += 6; }
+    }
+    if (headingBonus) signals.heading = headingBonus;
+
+    const aliasExact = aliasTerms.some(
+      (a) => lowerPath === a || lowerPath.endsWith(`/${a}.md`) || lower.includes(`title: ${a}`) || lower.includes(`# ${a}`)
+    );
+    const exactMatch =
+      aliasExact ||
+      (querySlug && lowerPath === querySlug) ||
+      (querySlug && lowerPath.endsWith(`/${querySlug}.md`)) ||
+      lower.includes(`title: ${queryLower}`) ||
+      lower.includes(`# ${queryLower}`);
+    if (querySlug && lowerPath.includes(querySlug)) { score += 25; signals.slug_path = 25; }
+    else if (aliasTerms.some((a) => lowerPath.includes(a))) { score += 25; signals.slug_path = 25; }
+    if (exactMatch) { score += 30; signals.exact_match = 30; }
+
+    const matched = score > 0;
+    if (matched && layer === 'wiki_core') { score += 18; signals.layer = 18; }
+    if (matched && layer === 'session_handoff') { score += 10; signals.layer = 10; }
+    if (matched && layer === 'area_index') { score += 6; signals.layer = 6; }
+    if (matched && layer === 'queue_metadata') { const b = queryLooksLikeSourceId ? 30 : 1; score += b; signals.layer = b; }
+    if (matched && layer === 'raw_inbox') { const b = queryLooksLikeSourceId ? 18 : 4; score += b; signals.layer = b; }
+    if (matched && entityBoostPaths.has(relPath)) { score += 15; signals.entity_authority = 15; }
+    if (matched && routeBoostWeights.has(relPath)) {
+      const b = routeBoostWeights.get(relPath);
+      score += b;
+      signals.route_authority = b;
+    }
+    if (matched && queryEntities.length) {
+      const overlap = queryEntities.reduce(
+        (n, e) => n + ((e.aliases || []).some((a) => includesTermBoundary(lower, a)) ? 1 : 0),
+        0
+      );
+      if (overlap) { score += overlap * 10; signals.entity_overlap = overlap * 10; }
+    }
+    if (matched && intelRelationshipPaths.has(relPath)) { const b = queryIsFollowup ? 42 : 16; score += b; signals.relationship = b; }
+    if (matched && memBoostPaths.has(relPath)) { score += 18; signals.memory_fusion = 18; }
+
+    const line = text.split(/\r?\n/).find((candidate) => searchTerms.some((term) => candidate.toLowerCase().includes(term)));
+    return {
+      path: relPath,
+      layer,
+      score: Math.round(score * 100) / 100,
+      exact_match: exactMatch,
+      matched_entities: relEntities.map((e) => e.canonical),
+      authoritative: intelBoostPaths.has(relPath) || memBoostPaths.has(relPath),
+      snippet: line ? line.trim().slice(0, 180) : '',
+      signals,
+    };
+  }
+
+  const ranked = docs
+    .map(scoreDoc)
+    .map((item) => (/^outputs?\//.test(item.path) ? { ...item, score: Math.round(item.score * 0.55 * 100) / 100 } : item))
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+
+  const results = capLayerResults(ranked, maxPerLayer, queryLooksLikeSourceId).slice(0, top);
+  return { query: String(query), top, results };
+}

package/src/core/recap.mjs

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { absPath, relPath, safeResolve, walkFiles } from './fs.mjs';
+import { lessonCandidates } from './lessons.mjs';
+import { redactedPreview } from './safety.mjs';
+
+export async function recapCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const recap = buildRecap(root, { area: args.area || '' });
+  if (args.json) return { json: true, payload: recap };
+  return {
+    text: [
+      '# Neurain recap',
+      '',
+      `- Root: ${root}`,
+      `- Sources checked: ${recap.sources_checked.length}`,
+      `- Lesson candidates: ${recap.lesson_candidate_count}`,
+      '',
+      '## Recent signals',
+      ...(recap.recent_signals.length ? recap.recent_signals.map((line) => `- ${line}`) : ['- none']),
+      '',
+      '## Open work hints',
+      ...(recap.open_work_hints.length ? recap.open_work_hints.map((line) => `- ${line}`) : ['- none']),
+    ].join('\n'),
+  };
+}
+
+export function buildRecap(root, { area = '' } = {}) {
+  const sources = recapSources(root, { area });
+  const recentSignals = [];
+  const openWorkHints = [];
+  for (const source of sources) {
+    const text = readTail(source.abs);
+    for (const line of text.split(/\r?\n/).map((item) => item.trim()).filter(Boolean).slice(-24)) {
+      const preview = redactedPreview(line, 180);
+      if (/(done|complete|pass|updated|added|merged|완료|통과|업데이트|병합)/i.test(line)) recentSignals.push(`${source.rel}: ${preview.text}`);
+      if (/(todo|pending|next|open|blocked|needs|남은|대기|필요)/i.test(line)) openWorkHints.push(`${source.rel}: ${preview.text}`);
+    }
+  }
+  const candidates = lessonCandidates(root, { limit: 5, area });
+  return {
+    ok: true,
+    command: 'recap',
+    root,
+    durable_write: false,
+    sources_checked: sources.map((source) => source.rel),
+    recent_signals: unique(recentSignals).slice(0, 8),
+    open_work_hints: unique(openWorkHints).slice(0, 8),
+    lesson_candidate_count: candidates.length,
+    lesson_candidate_ids: candidates.map((candidate) => candidate.id),
+  };
+}
+
+function recapSources(root, { area = '' } = {}) {
+  const fixed = ['log.md', 'wiki/log.md']
+    .map((rel) => ({ rel, abs: safeResolve(root, rel) }))
+    .filter((source) => fs.existsSync(source.abs));
+  const normalizedArea = String(area || '').replace(/^_+/, '').trim();
+  if (!normalizedArea) return fixed;
+  const areaPrefix = `10_areas/_${normalizedArea}/`;
+  const briefs = walkFiles(root, { includeRaw: false, maxFiles: 20000 })
+    .map((abs) => ({ abs, rel: relPath(root, abs) }))
+    .filter((source) => source.rel.startsWith(areaPrefix) && /(^|\/)current\/.+brief\.md$/i.test(source.rel));
+  return [...fixed, ...briefs].slice(0, 30);
+}
+
+function readTail(file) {
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    return text.split(/\r?\n/).slice(-80).join('\n');
+  } catch {
+    return '';
+  }
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}