neurain 0.1.0-alpha.0

package/src/core/answer_eval.mjs

@@ -0,0 +1,450 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { absPath, isTextFile, relPath, safeResolve, sha256, walkFiles } from './fs.mjs';
+import { injectionLike, secretLike } from './safety.mjs';
+
+const DEFAULT_SUPPORTED = 50;
+const DEFAULT_CONFLICT = 20;
+const DEFAULT_PRIVATE = 20;
+const DEFAULT_STALE = 20;
+const DEFAULT_NO_ANSWER = 10;
+
+export async function answerCommand(args) {
+  const [subcommand, ...rest] = args._;
+  const root = absPath(rest[0] || args.root || process.cwd());
+  if (!subcommand || subcommand === 'eval') return renderAnswerEval(root, args);
+  throw new Error('Unknown answer command. Use "answer eval".');
+}
+
+export async function evaluateAnswerQuality(root, {
+  caseFile = '',
+  supportedCases = DEFAULT_SUPPORTED,
+  conflictCases = DEFAULT_CONFLICT,
+  privateCases = DEFAULT_PRIVATE,
+  staleCases = DEFAULT_STALE,
+  noAnswerCases = DEFAULT_NO_ANSWER,
+  minCases = 50,
+} = {}) {
+  const before = snapshotAnswerEvalWriteSurface(root);
+  const cases = caseFile
+    ? loadCaseFile(root, caseFile)
+    : buildSyntheticCases({
+      supportedCases,
+      conflictCases,
+      privateCases,
+      staleCases,
+      noAnswerCases,
+    });
+  const results = cases.map(evaluateCase);
+  const after = snapshotAnswerEvalWriteSurface(root);
+  const evaluated = results.length;
+  const supportedResults = results.filter((item) => item.type === 'supported');
+  const citationResults = results.filter((item) => !item.abstention_expected);
+  const conflictResults = results.filter((item) => item.type === 'conflict');
+  const abstentionResults = results.filter((item) => item.type === 'no_answer');
+  const privateResults = results.filter((item) => item.type === 'private_boundary');
+  const staleResults = results.filter((item) => item.type === 'stale');
+
+  const faithfulnessRate = rate(supportedResults, 'faithful');
+  const citationAccuracy = rate(citationResults, 'citation_accurate');
+  const conflictSurfacingRate = rate(conflictResults, 'conflict_surfaced');
+  const abstentionCorrectness = rate(abstentionResults, 'abstention_correct');
+  const privateBoundaryRate = rate(privateResults, 'private_boundary_kept');
+  const staleHandlingRate = rate(staleResults, 'stale_handled');
+  const targetRootUntouched = stableJson(before) === stableJson(after);
+  const unsupported = results.filter((item) => !item.pass).slice(0, 20);
+  const ok = evaluated >= Number(minCases || 50)
+    && faithfulnessRate >= 0.95
+    && citationAccuracy >= 0.95
+    && conflictSurfacingRate >= 0.9
+    && abstentionCorrectness >= 0.9
+    && privateBoundaryRate >= 0.95
+    && staleHandlingRate >= 0.9
+    && targetRootUntouched;
+
+  return {
+    ok,
+    command: 'answer eval',
+    root,
+    durable_write: false,
+    model_calls: false,
+    external_tool_calls: false,
+    eval_type: caseFile ? 'answer_quality_cases' : 'answer_quality_fixture',
+    metric_scope: caseFile ? 'source_grounded_answer_quality_cases' : 'synthetic_answer_quality_policy_regression',
+    answer_quality_evaluated: true,
+    reviewed_answer_quality_evaluated: Boolean(caseFile),
+    retrieval_only_eval: false,
+    case_file: caseFile || null,
+    evaluated_cases: evaluated,
+    min_cases: Number(minCases || 50),
+    case_breakdown: countBy(results, 'type'),
+    faithfulness_rate: roundRate(faithfulnessRate),
+    citation_accuracy: roundRate(citationAccuracy),
+    conflict_surfacing_rate: roundRate(conflictSurfacingRate),
+    abstention_correctness: roundRate(abstentionCorrectness),
+    private_boundary_rate: roundRate(privateBoundaryRate),
+    stale_handling_rate: roundRate(staleHandlingRate),
+    target_root_untouched: targetRootUntouched,
+    source_grounded_truth_gates: {
+      faithfulness_min: 0.95,
+      citation_accuracy_min: 0.95,
+      conflict_surfacing_min: 0.9,
+      abstention_correctness_min: 0.9,
+      private_boundary_min: 0.95,
+      stale_handling_min: 0.9,
+    },
+    unsupported_cases: unsupported,
+    cases: results,
+    missing_evidence: ok
+      ? null
+      : evaluated < Number(minCases || 50)
+      ? `Need at least ${Number(minCases || 50)} answer-quality case(s).`
+      : !targetRootUntouched
+      ? 'Answer eval changed the target root write surface.'
+      : 'One or more answer-quality gates did not pass.',
+  };
+}
+
+function renderAnswerEval(root, args) {
+  const fixtureSize = Number(args['fixture-size'] || 0);
+  const counts = fixtureSize > 0
+    ? scaledCounts(fixtureSize)
+    : {
+      supportedCases: Number(args['supported-cases'] || DEFAULT_SUPPORTED),
+      conflictCases: Number(args['conflict-cases'] || DEFAULT_CONFLICT),
+      privateCases: Number(args['private-cases'] || DEFAULT_PRIVATE),
+      staleCases: Number(args['stale-cases'] || DEFAULT_STALE),
+      noAnswerCases: Number(args['no-answer-cases'] || DEFAULT_NO_ANSWER),
+    };
+  return evaluateAnswerQuality(root, {
+    caseFile: args['case-file'] || '',
+    minCases: Number(args['min-cases'] || 50),
+    ...counts,
+  }).then((payload) => args.json ? { json: true, payload } : {
+    text: [
+      '# Neurain answer eval',
+      '',
+      `- OK: ${payload.ok ? 'yes' : 'no'}`,
+      `- Type: ${payload.eval_type}`,
+      `- Cases: ${payload.evaluated_cases}`,
+      `- Faithfulness: ${payload.faithfulness_rate}`,
+      `- Citation accuracy: ${payload.citation_accuracy}`,
+      `- Conflict surfacing: ${payload.conflict_surfacing_rate}`,
+      `- Abstention correctness: ${payload.abstention_correctness}`,
+      `- Private boundary: ${payload.private_boundary_rate}`,
+      `- Stale handling: ${payload.stale_handling_rate}`,
+      payload.missing_evidence ? `- Missing evidence: ${payload.missing_evidence}` : '',
+    ].filter(Boolean).join('\n'),
+  });
+}
+
+function evaluateCase(testCase) {
+  const answer = normalizeAnswer(testCase.answer || {});
+  const sources = Array.isArray(testCase.sources) ? testCase.sources : [];
+  const publicSources = sources.filter((source) => !source.private);
+  const privateSources = sources.filter((source) => source.private);
+  const citations = answer.citations;
+  const checks = {
+    faithful: true,
+    citation_accurate: true,
+    conflict_surfaced: testCase.type !== 'conflict',
+    abstention_correct: testCase.type !== 'no_answer',
+    private_boundary_kept: testCase.type !== 'private_boundary',
+    stale_handled: testCase.type !== 'stale',
+  };
+
+  for (const claim of testCase.claims || []) {
+    const claimText = String(claim.text || '').trim();
+    const terms = termsForClaim(claim);
+    const citedIds = claim.citations || citations.map((item) => item.source_id);
+    const citedSources = citedIds.map((id) => sources.find((source) => source.id === id)).filter(Boolean);
+    const supported = citedSources.some((source) => sourceSupportsTerms(source, terms));
+    const answerMentionsClaim = claimText ? includesNormalized(answer.text, claimText) : terms.every((term) => includesNormalized(answer.text, term));
+    if (!supported || !answerMentionsClaim) checks.faithful = false;
+  }
+
+  for (const citation of citations) {
+    const source = sources.find((item) => item.id === citation.source_id);
+    if (!source) {
+      checks.citation_accurate = false;
+      continue;
+    }
+    const terms = termsForCitation(citation, testCase);
+    if (terms.length && !sourceSupportsTerms(source, terms)) checks.citation_accurate = false;
+  }
+
+  if (testCase.type === 'conflict') {
+    const conflictTerms = (testCase.conflict_terms || []).map((term) => String(term || '').toLowerCase());
+    const citesBothSides = new Set(citations.map((item) => item.source_id)).size >= 2;
+    checks.conflict_surfaced = Boolean(answer.conflict_surface && citesBothSides && conflictTerms.every((term) => includesNormalized(answer.text, term)));
+  }
+
+  if (testCase.type === 'no_answer') {
+    checks.abstention_correct = Boolean(answer.abstained && citations.length === 0 && /not enough evidence|insufficient evidence|모르|근거가 부족/i.test(answer.text));
+  }
+
+  if (testCase.type === 'private_boundary') {
+    const privateIds = new Set(privateSources.map((source) => source.id));
+    const privateMarkers = privateSources.flatMap((source) => source.private_markers || termsFromText(source.text));
+    const citesPrivate = citations.some((citation) => privateIds.has(citation.source_id));
+    const leaksPrivate = privateMarkers.some((marker) => marker.length >= 6 && includesNormalized(answer.text, marker));
+    checks.private_boundary_kept = !citesPrivate && !leaksPrivate && publicSources.length >= 1;
+  }
+
+  if (testCase.type === 'stale') {
+    const currentId = testCase.current_source_id;
+    const staleId = testCase.stale_source_id;
+    checks.stale_handled = Boolean(
+      currentId
+      && citations.some((citation) => citation.source_id === currentId)
+      && !citations.some((citation) => citation.source_id === staleId)
+      && termsForClaim(testCase.claims?.[0] || {}).every((term) => includesNormalized(answer.text, term))
+    );
+  }
+
+  const unsafeAnswer = Boolean(secretLike(answer.text) || injectionLike(answer.text));
+  const pass = Object.values(checks).every(Boolean) && !unsafeAnswer;
+  return {
+    id: String(testCase.id || ''),
+    type: String(testCase.type || 'supported'),
+    pass,
+    ...checks,
+    unsafe_answer: unsafeAnswer,
+    citation_count: citations.length,
+    abstention_expected: testCase.type === 'no_answer',
+  };
+}
+
+function loadCaseFile(root, caseFile) {
+  const abs = path.isAbsolute(caseFile) ? caseFile : safeResolve(root, caseFile);
+  if (!fs.existsSync(abs)) throw new Error(`Answer eval case file does not exist: ${caseFile}`);
+  if (!isTextFile(abs)) throw new Error(`Answer eval case file must be a text JSON file: ${caseFile}`);
+  const parsed = JSON.parse(fs.readFileSync(abs, 'utf8'));
+  const cases = Array.isArray(parsed) ? parsed : parsed.cases;
+  if (!Array.isArray(cases)) throw new Error('Answer eval case file must contain an array or { "cases": [] }.');
+  return cases;
+}
+
+function buildSyntheticCases({
+  supportedCases,
+  conflictCases,
+  privateCases,
+  staleCases,
+  noAnswerCases,
+}) {
+  const cases = [];
+  for (let i = 0; i < boundedCount(supportedCases, DEFAULT_SUPPORTED); i += 1) {
+    const serial = pad(i + 1);
+    cases.push({
+      id: `supported-${serial}`,
+      type: 'supported',
+      question: `What is the supported answer marker ${serial}?`,
+      sources: [{ id: 's1', text: `Supported answer marker answer${serial} is sourcegrounded${serial}.` }],
+      claims: [{ text: `answer${serial}`, support_terms: [`answer${serial}`, `sourcegrounded${serial}`], citations: ['s1'] }],
+      answer: {
+        text: `The supported answer is answer${serial} because sourcegrounded${serial} is present.`,
+        citations: [{ source_id: 's1', support_terms: [`answer${serial}`, `sourcegrounded${serial}`] }],
+      },
+    });
+  }
+  for (let i = 0; i < boundedCount(conflictCases, DEFAULT_CONFLICT); i += 1) {
+    const serial = pad(i + 1);
+    cases.push({
+      id: `conflict-${serial}`,
+      type: 'conflict',
+      question: `Which value is correct for conflict marker ${serial}?`,
+      sources: [
+        { id: 'a', text: `Conflict marker conflict${serial} says value alpha${serial}.` },
+        { id: 'b', text: `Conflict marker conflict${serial} says value beta${serial}.` },
+      ],
+      claims: [],
+      conflict_terms: [`alpha${serial}`, `beta${serial}`],
+      answer: {
+        text: `The sources conflict: one says alpha${serial}, another says beta${serial}.`,
+        conflict_surface: true,
+        citations: [
+          { source_id: 'a', support_terms: [`alpha${serial}`] },
+          { source_id: 'b', support_terms: [`beta${serial}`] },
+        ],
+      },
+    });
+  }
+  for (let i = 0; i < boundedCount(privateCases, DEFAULT_PRIVATE); i += 1) {
+    const serial = pad(i + 1);
+    cases.push({
+      id: `private-${serial}`,
+      type: 'private_boundary',
+      question: `What can be answered publicly for private marker ${serial}?`,
+      sources: [
+        { id: 'pub', text: `Public marker publicsafe${serial} can be cited safely.` },
+        { id: 'priv', text: `Private marker privatesecret${serial} must not appear.`, private: true, private_markers: [`privatesecret${serial}`] },
+      ],
+      claims: [{ text: `publicsafe${serial}`, support_terms: [`publicsafe${serial}`], citations: ['pub'] }],
+      answer: {
+        text: `The public source supports publicsafe${serial}.`,
+        citations: [{ source_id: 'pub', support_terms: [`publicsafe${serial}`] }],
+      },
+    });
+  }
+  for (let i = 0; i < boundedCount(staleCases, DEFAULT_STALE); i += 1) {
+    const serial = pad(i + 1);
+    cases.push({
+      id: `stale-${serial}`,
+      type: 'stale',
+      question: `Which status is current for stale marker ${serial}?`,
+      sources: [
+        { id: 'old', text: `Old source says stale${serial} status is retired${serial}.` },
+        { id: 'current', text: `Current source says stale${serial} status is active${serial}.` },
+      ],
+      current_source_id: 'current',
+      stale_source_id: 'old',
+      claims: [{ text: `active${serial}`, support_terms: [`stale${serial}`, `active${serial}`], citations: ['current'] }],
+      answer: {
+        text: `The current status is active${serial} for stale${serial}.`,
+        citations: [{ source_id: 'current', support_terms: [`stale${serial}`, `active${serial}`] }],
+      },
+    });
+  }
+  for (let i = 0; i < boundedCount(noAnswerCases, DEFAULT_NO_ANSWER); i += 1) {
+    const serial = pad(i + 1);
+    cases.push({
+      id: `no-answer-${serial}`,
+      type: 'no_answer',
+      question: `What is missing marker ${serial}?`,
+      sources: [{ id: 's1', text: `This source discusses nearby topic nearby${serial}, but not the requested missing marker.` }],
+      claims: [],
+      answer: {
+        text: 'Not enough evidence in the provided sources.',
+        abstained: true,
+        citations: [],
+      },
+    });
+  }
+  return cases;
+}
+
+function scaledCounts(total) {
+  const count = Math.max(10, Math.min(Number(total || 120), 500));
+  const supportedCases = Math.max(1, Math.round(count * 0.42));
+  const conflictCases = Math.max(1, Math.round(count * 0.17));
+  const privateCases = Math.max(1, Math.round(count * 0.17));
+  const staleCases = Math.max(1, Math.round(count * 0.17));
+  const used = supportedCases + conflictCases + privateCases + staleCases;
+  return {
+    supportedCases,
+    conflictCases,
+    privateCases,
+    staleCases,
+    noAnswerCases: Math.max(1, count - used),
+  };
+}
+
+function normalizeAnswer(answer) {
+  return {
+    text: String(answer.text || ''),
+    citations: Array.isArray(answer.citations) ? answer.citations.map((citation) => ({
+      source_id: String(citation.source_id || ''),
+      claim: String(citation.claim || ''),
+      support_terms: Array.isArray(citation.support_terms) ? citation.support_terms.map(String) : [],
+    })) : [],
+    conflict_surface: Boolean(answer.conflict_surface),
+    abstained: Boolean(answer.abstained),
+  };
+}
+
+function termsForClaim(claim) {
+  if (!claim) return [];
+  if (Array.isArray(claim.support_terms) && claim.support_terms.length) return claim.support_terms.map(String);
+  return termsFromText(claim.text || '');
+}
+
+function termsForCitation(citation, testCase) {
+  if (Array.isArray(citation.support_terms) && citation.support_terms.length) return citation.support_terms.map(String);
+  const claim = (testCase.claims || []).find((item) => (item.citations || []).includes(citation.source_id));
+  return termsForClaim(claim);
+}
+
+function termsFromText(text) {
+  return String(text || '').toLowerCase().match(/[a-z0-9_-]{4,}/g) || [];
+}
+
+function sourceSupportsTerms(source, terms) {
+  return terms.every((term) => includesNormalized(source.text || '', term));
+}
+
+function includesNormalized(text, term) {
+  return String(text || '').toLowerCase().includes(String(term || '').toLowerCase());
+}
+
+function rate(items, key) {
+  if (!items.length) return 1;
+  return items.filter((item) => item[key] === true).length / items.length;
+}
+
+function roundRate(value) {
+  return Number(value.toFixed(3));
+}
+
+function countBy(items, key) {
+  const out = {};
+  for (const item of items) out[item[key]] = (out[item[key]] || 0) + 1;
+  return out;
+}
+
+function boundedCount(value, fallback) {
+  const parsed = Number(value);
+  return Math.max(0, Math.min(Number.isFinite(parsed) ? parsed : fallback, 500));
+}
+
+function pad(value) {
+  return String(value).padStart(3, '0');
+}
+
+function stableJson(value) {
+  return JSON.stringify(value, Object.keys(flattenKeys(value)).sort());
+}
+
+function flattenKeys(value, out = {}) {
+  if (value && typeof value === 'object') {
+    for (const key of Object.keys(value)) {
+      out[key] = true;
+      flattenKeys(value[key], out);
+    }
+  }
+  return out;
+}
+
+function snapshotAnswerEvalWriteSurface(root) {
+  const rels = [
+    '00_system/neurain/events.ndjson',
+    '00_system/neurain/recall.sqlite',
+    '00_system/neurain/recall.sqlite-wal',
+    '00_system/neurain/recall.sqlite-shm',
+    '00_system/evals',
+    'output/receipts',
+  ];
+  const out = {};
+  for (const rel of rels) {
+    let abs;
+    try {
+      abs = safeResolve(root, rel);
+    } catch {
+      out[rel] = { exists: false, hash: 'invalid-root' };
+      continue;
+    }
+    if (!fs.existsSync(abs)) {
+      out[rel] = { exists: false, hash: '' };
+      continue;
+    }
+    const stat = fs.statSync(abs);
+    if (stat.isDirectory()) {
+      const files = walkFiles(abs, { includeRaw: false, maxFiles: 10000 })
+        .map((file) => `${relPath(abs, file)}:${sha256(fs.readFileSync(file))}`)
+        .sort();
+      out[rel] = { exists: true, type: 'directory', hash: sha256(files.join('\n')) };
+    } else {
+      out[rel] = { exists: true, type: 'file', hash: sha256(fs.readFileSync(abs)) };
+    }
+  }
+  return out;
+}

package/src/core/capabilities.mjs

@@ -0,0 +1,217 @@
+const capabilityCards = [
+  {
+    id: 'status-doctor',
+    title: 'Check local vault state',
+    phase: 'core',
+    commands: ['neurain doctor <folder>', 'neurain mcp tool neurain_status'],
+    summary: 'Read required files, backup note, lesson registry state, and host connection guidance.',
+    tags: ['status', 'doctor', 'health', 'startup'],
+  },
+  {
+    id: 'folder-adoption-scan',
+    title: 'Scan an existing work folder safely',
+    phase: 'core',
+    commands: ['neurain adopt <folder> --dry-run', 'neurain mcp tool neurain_adopt_scan'],
+    summary: 'Detect generated files, secrets, symlinks, large files, and recommend in-place, hybrid, or copy mode before any write.',
+    tags: ['adopt', 'folder', 'scan', 'safety'],
+  },
+  {
+    id: 'event-journal',
+    title: 'Record and verify local workflow events',
+    phase: 'self-improve-90-e2-phase-1',
+    commands: ['neurain journal list <folder>', 'neurain journal add <folder> --type test --summary "..." --confirm "1건 저장 진행"', 'neurain mcp tool neurain_journal_list'],
+    summary: 'Append-only local event substrate for wrap, review, test, correction, rollback, and sync signals. Writes require confirmation; MCP is read-only.',
+    tags: ['journal', 'event', 'receipt', 'watch', 'review-worker'],
+  },
+  {
+    id: 'watch-report',
+    title: 'Observe local signals without writing',
+    phase: 'self-improve-90-e3-phase-2',
+    commands: ['neurain watch <folder> --poll-once', 'neurain mcp tool neurain_watch_report'],
+    summary: 'Read recent local file signals, journal events, recap hints, and lesson candidates as a review-worker input. It emits reports only.',
+    tags: ['watch', 'background-review', 'review-worker', 'event', 'automation'],
+  },
+  {
+    id: 'review-worker',
+    title: 'Review local signals into improvement proposals',
+    phase: 'self-improve-90-e4-phase-3',
+    commands: ['neurain review <folder> --json', 'neurain mcp tool neurain_review_worker'],
+    summary: 'Convert watch reports, event journal entries, and lesson candidates into a deterministic manual review report. It performs no model calls and no writes.',
+    tags: ['review', 'background-review', 'lesson', 'candidate', 'automation', 'runtime'],
+  },
+  {
+    id: 'scheduler-tick',
+    title: 'Decide when local review should run',
+    phase: 'self-improve-90-e8-phase-3b',
+    commands: ['neurain scheduler tick <folder> --json', 'neurain mcp tool neurain_scheduler_tick'],
+    summary: 'Run a read-only one-shot scheduler tick that inspects watch signals and includes a review worker report only when thresholds are met.',
+    tags: ['scheduler', 'background-review', 'automation', 'watch', 'review-worker', 'runtime'],
+  },
+  {
+    id: 'scheduler-eval',
+    title: 'Measure background review trigger quality',
+    phase: 'self-improve-90-e20-scheduler-trigger-eval',
+    commands: ['neurain scheduler eval <folder> --fixture-size 100 --json', 'neurain mcp tool neurain_scheduler_eval'],
+    summary: 'Validate scheduler trigger precision, recall, no-recursion, private-boundary handling, and target-root non-write before claiming background automation quality.',
+    tags: ['scheduler', 'eval', 'background-review', 'automation', 'precision', 'recall', 'runtime'],
+  },
+  {
+    id: 'scheduler-monitor',
+    title: 'Monitor local review needs in the foreground',
+    phase: 'self-improve-90-e9-foreground-monitor',
+    commands: ['neurain scheduler monitor <folder> --interval-seconds 60 --max-ticks 3 --json'],
+    summary: 'Run a user-started bounded foreground monitor that repeats read-only scheduler ticks without installing background jobs or writing durable knowledge.',
+    tags: ['scheduler', 'monitor', 'automation', 'watch', 'review-worker', 'runtime'],
+  },
+  {
+    id: 'continuous-daemon',
+    title: 'Keep local review checks running while the user works',
+    phase: 'self-improve-90-e11-continuous-daemon',
+    commands: ['neurain daemon run <folder> --interval-seconds 300', 'neurain daemon status <folder>', 'neurain daemon stop <folder>'],
+    summary: 'Run a user-started foreground daemon loop that repeats scheduler ticks and writes only operational state. It never writes wiki, promotes lessons, calls models, or exposes MCP tools.',
+    tags: ['daemon', 'scheduler', 'monitor', 'automation', 'watch', 'review-worker', 'runtime'],
+  },
+  {
+    id: 'lifecycle-lineage',
+    title: 'Track host lifecycle and session lineage',
+    phase: 'self-improve-90-e10-lifecycle-lineage',
+    commands: ['neurain lifecycle emit <folder> --host codex --event turn_end --session-id session --confirm "1건 저장 진행"', 'neurain lifecycle report <folder> --json', 'neurain mcp tool neurain_lifecycle_report'],
+    summary: 'Record append-only host boundary events and report turn completion, compaction, resume, and review-due lineage without Neurain pretending to own the host model loop.',
+    tags: ['lifecycle', 'lineage', 'session', 'automation', 'runtime', 'agent-loop'],
+  },
+  {
+    id: 'claude-lifecycle-hooks',
+    title: 'Preview Claude Code lifecycle hook automation',
+    phase: 'self-improve-90-e12-claude-lifecycle-hooks',
+    commands: ['neurain connect claude <folder> --lifecycle-hooks --dry-run', 'neurain lifecycle hook <folder> --host claude --confirm "1건 저장 진행"'],
+    summary: 'Preview Claude Code command hooks that map SessionStart, UserPromptSubmit, Stop, and SessionEnd into Neurain lifecycle receipts without storing prompt bodies or transcript paths.',
+    tags: ['lifecycle', 'hooks', 'claude', 'automation', 'session', 'agent-loop'],
+  },
+  {
+    id: 'lesson-curator',
+    title: 'Manage lesson lifecycle safely',
+    phase: 'self-improve-90-e5-phase-4',
+    commands: ['neurain curator status <folder>', 'neurain curator run <folder> --dry-run', 'neurain mcp tool neurain_curator_status'],
+    summary: 'Preview and apply active, stale, and archived lifecycle changes with snapshot receipts, rollback, pinned protection, and no deletion.',
+    tags: ['curator', 'lesson', 'lifecycle', 'snapshot', 'rollback', 'runtime'],
+  },
+  {
+    id: 'recall-db',
+    title: 'Build and search local recall index',
+    phase: 'self-improve-90-e6-phase-5',
+    commands: ['neurain recall status <folder>', 'neurain recall rebuild <folder>', 'neurain recall search <folder> <query>', 'neurain mcp tool neurain_recall_search'],
+    summary: 'Use an optional rebuildable SQLite FTS5 cache for cross-session recall while keeping markdown, events, and receipts as canonical truth.',
+    tags: ['recall', 'sqlite', 'fts5', 'session', 'search', 'runtime'],
+  },
+  {
+    id: 'lesson-list',
+    title: 'Read active lessons',
+    phase: 'runtime-v0.3',
+    commands: ['neurain lessons list <folder>', 'neurain mcp tool neurain_lessons_list'],
+    summary: 'Load cover-level lessons first so agents can avoid repeated mistakes without loading bulky bodies.',
+    tags: ['lesson', 'memory', 'runtime', 'startup'],
+  },
+  {
+    id: 'lesson-candidates',
+    title: 'Preview lesson candidates',
+    phase: 'runtime-v0.3',
+    commands: ['neurain lessons candidates <folder>', 'neurain mcp tool neurain_lessons_candidates'],
+    summary: 'Inspect logs and current context for recurring corrections. Produces preview candidates only, not durable lessons.',
+    tags: ['lesson', 'candidate', 'wrap', 'curator'],
+  },
+  {
+    id: 'wrap-dry-run',
+    title: 'End-of-work self-improvement preview',
+    phase: 'runtime-v0.3',
+    commands: ['neurain wrap <folder> --dry-run'],
+    summary: 'Combines doctor, recap, lesson candidate preview, and capability hints so the next session starts better.',
+    tags: ['wrap', 'recap', 'lesson', 'self-improvement'],
+  },
+  {
+    id: 'session-recap',
+    title: 'Create deterministic session recap',
+    phase: 'runtime-v0.3',
+    commands: ['neurain recap <folder>'],
+    summary: 'Summarizes recent logs and area briefs without calling a model or writing durable knowledge.',
+    tags: ['recap', 'session', 'handoff', 'compression'],
+  },
+  {
+    id: 'first-run-onboarding',
+    title: 'Show first-run onboarding',
+    phase: 'e24-onboarding',
+    commands: ['neurain onboard <folder> --lang ko', 'neurain onboard <folder> --host gemini --json'],
+    summary: 'Read-only non-developer guide that explains whether to initialize, scan, connect, or preview wrap next.',
+    tags: ['onboarding', 'first-run', 'non-developer', 'read-only'],
+  },
+  {
+    id: 'host-connect',
+    title: 'Connect Codex, Claude Code, Gemini CLI, or Runtime',
+    phase: 'core',
+    commands: ['neurain connect codex <folder> --dry-run', 'neurain connect claude <folder> --dry-run', 'neurain connect gemini <folder> --dry-run', 'neurain connect runtime <folder> --dry-run'],
+    summary: 'Print host-specific MCP setup commands. Dry-run mode changes no host configuration.',
+    tags: ['mcp', 'codex', 'claude', 'gemini', 'runtime', 'connect'],
+  },
+  {
+    id: 'adoption-rollback',
+    title: 'Rollback adoption adapter writes',
+    phase: 'core',
+    commands: ['neurain adopt --rollback <receipt> --root <folder>'],
+    summary: 'Remove only files listed in the adoption receipt and refuse changed files.',
+    tags: ['rollback', 'receipt', 'safety'],
+  },
+];
+
+export function listCapabilities({ query = '', limit = 20 } = {}) {
+  const needle = String(query || '').trim().toLowerCase();
+  const ranked = capabilityCards
+    .map((card) => ({ ...card, score: scoreCard(card, needle) }))
+    .filter((card) => !needle || card.score > 0)
+    .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+    .slice(0, Number(limit || 20))
+    .map(({ score, ...card }) => ({
+      ...card,
+      reason: needle ? reasonFor(card, needle, score) : 'listed as part of the Neurain alpha capability contract',
+    }));
+  return ranked;
+}
+
+export async function capabilitiesCommand(args) {
+  const query = args.query || args._.join(' ');
+  const capabilities = listCapabilities({ query, limit: Number(args.top || 20) });
+  const payload = {
+    ok: true,
+    command: 'capabilities',
+    query: query || null,
+    count: capabilities.length,
+    capabilities,
+  };
+  if (args.json) return { json: true, payload };
+  return {
+    text: [
+      '# Neurain capabilities',
+      '',
+      query ? `Query: ${query}` : 'Query: all',
+      '',
+      ...capabilities.map((card) => [
+        `## ${card.id}`,
+        `- Title: ${card.title}`,
+        `- Phase: ${card.phase}`,
+        `- Use: ${card.commands[0]}`,
+        `- Why: ${card.reason}`,
+      ].join('\n')),
+    ].join('\n'),
+  };
+}
+
+function scoreCard(card, needle) {
+  if (!needle) return 1;
+  const words = needle.split(/\s+/).filter(Boolean);
+  const haystack = `${card.id} ${card.title} ${card.summary} ${card.tags.join(' ')} ${card.commands.join(' ')}`.toLowerCase();
+  return words.reduce((score, word) => score + (haystack.includes(word) ? 1 : 0), 0);
+}
+
+function reasonFor(card, needle, score) {
+  return score > 0
+    ? `matched "${needle}" against ${card.tags.join(', ')}`
+    : `available capability ${card.id}`;
+}