llm-wiki-kit 0.1.0

package/src/install.js

@@ -0,0 +1,164 @@
+import { chmod } from 'fs/promises';
+import { join, resolve } from 'path';
+import { CLAUDE_EVENTS, CODEX_EVENTS, KIT_NAME } from './constants.js';
+import { backupFile, ensureDir, exists, homeDir, readJson, safeSymlink, writeJson } from './fs-utils.js';
+import { inspectProjectState } from './project-state.js';
+import { bootstrapProject } from './project.js';
+import { binPath, detectInstallSource, packageRoot, runtimeVersion } from './version.js';
+
+function shellQuote(value) {
+  return `"${String(value).replace(/(["\\$`])/g, '\\$1')}"`;
+}
+
+export function hookCommand(provider, eventName) {
+  return `${shellQuote(process.execPath)} ${shellQuote(binPath)} hook ${provider} ${eventName}`;
+}
+
+function addHook(hooks, eventName, command, options = {}) {
+  hooks[eventName] = Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
+  const already = JSON.stringify(hooks[eventName]).includes(command);
+  if (already) return false;
+  const entry = {
+    hooks: [
+      {
+        type: 'command',
+        command,
+        timeout: options.timeout || 30,
+      },
+    ],
+  };
+  if (options.matcher) entry.matcher = options.matcher;
+  hooks[eventName].push(entry);
+  return true;
+}
+
+function removeKitHooks(hooks) {
+  let changed = false;
+  for (const [eventName, entries] of Object.entries(hooks || {})) {
+    if (!Array.isArray(entries)) continue;
+    const next = entries.filter((entry) => {
+      const serialized = JSON.stringify(entry);
+      return !serialized.includes(KIT_NAME) && !serialized.includes(binPath);
+    });
+    if (next.length !== entries.length) {
+      hooks[eventName] = next;
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+export async function install(options = {}) {
+  const workspace = resolve(options.workspace || process.cwd());
+  await chmod(binPath, 0o755).catch(() => {});
+  const localBin = join(homeDir(), '.local', 'bin');
+  await ensureDir(localBin);
+  const localBinPath = join(localBin, 'llm-wiki');
+  if (await exists(localBinPath)) {
+    await backupFile(localBinPath, 'local-bin-llm-wiki');
+  }
+  await safeSymlink(binPath, localBinPath);
+  await bootstrapProject(workspace, { profile: options.profile || 'standard', recordState: true });
+
+  const codexHooksPath = join(homeDir(), '.codex', 'hooks.json');
+  const claudeSettingsPath = join(homeDir(), '.claude', 'settings.json');
+  const changed = [];
+
+  if (options.codex !== false) {
+    const codex = (await readJson(codexHooksPath, null)) || {};
+    codex.hooks = codex.hooks || {};
+    let codexChanged = false;
+    if (options.replaceHooks && removeKitHooks(codex.hooks)) {
+      codexChanged = true;
+      changed.push('codex:replaced');
+    }
+    for (const eventName of CODEX_EVENTS) {
+      const matcher = eventName === 'SessionStart' ? 'startup|resume|clear' : undefined;
+      if (addHook(codex.hooks, eventName, hookCommand('codex', eventName), { matcher })) {
+        codexChanged = true;
+        changed.push(`codex:${eventName}`);
+      }
+    }
+    if (codexChanged) {
+      await backupFile(codexHooksPath, 'codex-hooks.json');
+      await writeJson(codexHooksPath, codex);
+    }
+  }
+
+  if (options.claude !== false) {
+    const claude = (await readJson(claudeSettingsPath, null)) || {};
+    claude.hooks = claude.hooks || {};
+    let claudeChanged = false;
+    if (options.replaceHooks && removeKitHooks(claude.hooks)) {
+      claudeChanged = true;
+      changed.push('claude:replaced');
+    }
+    for (const eventName of CLAUDE_EVENTS) {
+      const matcher = eventName === 'SessionStart' ? 'startup|resume|clear' : undefined;
+      if (addHook(claude.hooks, eventName, hookCommand('claude', eventName), { matcher })) {
+        claudeChanged = true;
+        changed.push(`claude:${eventName}`);
+      }
+    }
+    if (claudeChanged) {
+      await backupFile(claudeSettingsPath, 'claude-settings.json');
+      await writeJson(claudeSettingsPath, claude);
+    }
+  }
+
+  return {
+    workspace,
+    runtimeVersion: runtimeVersion(),
+    binPath,
+    localBin: join(localBin, 'llm-wiki'),
+    changed,
+  };
+}
+
+export async function uninstall(options = {}) {
+  const codexHooksPath = join(homeDir(), '.codex', 'hooks.json');
+  const claudeSettingsPath = join(homeDir(), '.claude', 'settings.json');
+  const changed = [];
+
+  if (options.codex !== false && await exists(codexHooksPath)) {
+    const codex = await readJson(codexHooksPath, {});
+    if (removeKitHooks(codex.hooks || {})) {
+      await backupFile(codexHooksPath, 'codex-hooks-before-uninstall.json');
+      await writeJson(codexHooksPath, codex);
+      changed.push('codex');
+    }
+  }
+
+  if (options.claude !== false && await exists(claudeSettingsPath)) {
+    const claude = await readJson(claudeSettingsPath, {});
+    if (removeKitHooks(claude.hooks || {})) {
+      await backupFile(claudeSettingsPath, 'claude-settings-before-uninstall.json');
+      await writeJson(claudeSettingsPath, claude);
+      changed.push('claude');
+    }
+  }
+
+  return { changed };
+}
+
+export async function status(options = {}) {
+  const workspace = resolve(options.workspace || process.cwd());
+  const codexHooksPath = join(homeDir(), '.codex', 'hooks.json');
+  const claudeSettingsPath = join(homeDir(), '.claude', 'settings.json');
+  const codex = await readJson(codexHooksPath, {});
+  const claude = await readJson(claudeSettingsPath, {});
+  const codexInstalled = JSON.stringify(codex.hooks || {}).includes(binPath);
+  const claudeInstalled = JSON.stringify(claude.hooks || {}).includes(binPath);
+  return {
+    runtimeVersion: runtimeVersion(),
+    packageRoot,
+    installSource: detectInstallSource(),
+    binPath,
+    codexInstalled,
+    claudeInstalled,
+    hooksCurrent: codexInstalled && claudeInstalled,
+    codexHooksPath,
+    claudeSettingsPath,
+    project: await inspectProjectState(workspace),
+  };
+}

package/src/migrate.js

@@ -0,0 +1,57 @@
+import { basename, dirname, join } from 'path';
+import { copyFile } from 'fs/promises';
+import { ensureDir, exists, listMarkdownFiles, readText } from './fs-utils.js';
+import { appendWikiLog, bootstrapProject } from './project.js';
+
+async function isGeneratedKitAgents(path) {
+  if (!(await exists(path))) return false;
+  return (await readText(path)).includes('Generated by llm-wiki-kit');
+}
+
+async function isLegacyProceduresDir(path) {
+  if (!(await exists(path))) return false;
+  return (
+    await exists(join(path, 'autosave-hooks.md')) ||
+    await exists(join(path, 'record-live-qa.md')) ||
+    !(await exists(join(path, 'security.md')))
+  );
+}
+
+export async function migrate(projectRoot) {
+  const sources = [
+    { from: join(projectRoot, 'omx_wiki'), to: join(projectRoot, 'llm-wiki', 'wiki', 'context'), legacy: true },
+    { from: join(projectRoot, 'llm-wiki', 'sources'), to: join(projectRoot, 'llm-wiki', 'wiki', 'sources'), legacy: true },
+    { from: join(projectRoot, 'llm-wiki', 'templates'), to: join(projectRoot, 'llm-wiki', 'wiki', 'context'), legacy: true },
+    { from: join(projectRoot, 'llm-wiki', 'procedures'), to: join(projectRoot, 'llm-wiki', 'wiki', 'context'), legacy: await isLegacyProceduresDir(join(projectRoot, 'llm-wiki', 'procedures')) },
+  ];
+  const legacySources = [];
+  for (const source of sources) {
+    if (source.legacy && await exists(source.from)) legacySources.push(source);
+  }
+  const legacyFiles = [
+    { from: join(projectRoot, 'llm-wiki', 'index.md'), to: join(projectRoot, 'llm-wiki', 'wiki', 'context', 'legacy-llm-wiki-index.md'), legacy: await exists(join(projectRoot, 'llm-wiki', 'index.md')) },
+    { from: join(projectRoot, 'llm-wiki', 'log.md'), to: join(projectRoot, 'llm-wiki', 'wiki', 'context', 'legacy-llm-wiki-log.md'), legacy: await exists(join(projectRoot, 'llm-wiki', 'log.md')) },
+    { from: join(projectRoot, 'llm-wiki', 'AGENTS.md'), to: join(projectRoot, 'llm-wiki', 'wiki', 'context', 'legacy-llm-wiki-agents.md'), legacy: await exists(join(projectRoot, 'llm-wiki', 'AGENTS.md')) && !(await isGeneratedKitAgents(join(projectRoot, 'llm-wiki', 'AGENTS.md'))) },
+  ].filter((item) => item.legacy);
+
+  await bootstrapProject(projectRoot);
+  const copied = [];
+  for (const source of legacySources) {
+    const files = await listMarkdownFiles(source.from, 500);
+    await ensureDir(source.to);
+    for (const file of files) {
+      const dest = join(source.to, basename(file));
+      if (file === dest || await exists(dest)) continue;
+      await copyFile(file, dest);
+      copied.push(dest);
+    }
+  }
+  for (const item of legacyFiles) {
+    if (!(await exists(item.from)) || await exists(item.to)) continue;
+    await ensureDir(dirname(item.to));
+    await copyFile(item.from, item.to);
+    copied.push(item.to);
+  }
+  await appendWikiLog(projectRoot, `migration copy-only completed: ${copied.length} files`);
+  return { copied };
+}

package/src/project-state.js

@@ -0,0 +1,231 @@
+import { dirname, join, relative } from 'path';
+import { backupFile, ensureDir, exists, readJson, readText, sha256, writeJson, writeText } from './fs-utils.js';
+import { runtimeVersion } from './version.js';
+import { llmWikiAgents, procedure, rootAgentsPolicy } from './templates.js';
+
+export const PROJECT_STATE_SCHEMA_VERSION = 1;
+export const PROJECT_STATE_FILE = '.kit-state.json';
+
+const PROCEDURE_NAMES = ['ingest.md', 'query.md', 'lint.md', 'security.md'];
+const ROOT_POLICY_START = '<!-- llm-wiki-kit:start -->';
+const ROOT_POLICY_END = '<!-- llm-wiki-kit:end -->';
+
+function statePath(projectRoot) {
+  return join(projectRoot, 'llm-wiki', PROJECT_STATE_FILE);
+}
+
+function templateDescriptors() {
+  return [
+    {
+      id: 'root-agents-policy',
+      path: 'AGENTS.md',
+      content: rootAgentsPolicy(),
+      mode: 'marker',
+    },
+    {
+      id: 'llm-wiki-agents',
+      path: join('llm-wiki', 'AGENTS.md'),
+      content: llmWikiAgents(),
+      mode: 'generated-file',
+      marker: 'Generated by llm-wiki-kit',
+    },
+    ...PROCEDURE_NAMES.map((name) => ({
+      id: `procedure-${name.replace(/\.md$/, '')}`,
+      path: join('llm-wiki', 'procedures', name),
+      content: procedure(name),
+      mode: 'generated-file',
+    })),
+  ];
+}
+
+function emptyState() {
+  return {
+    schemaVersion: PROJECT_STATE_SCHEMA_VERSION,
+    lastRuntimeVersionApplied: null,
+    managedTemplates: {},
+    lastUpdatedAt: null,
+  };
+}
+
+function templateHash(content) {
+  return sha256(content);
+}
+
+function normalizeState(raw) {
+  return {
+    ...emptyState(),
+    ...(raw || {}),
+    managedTemplates: {
+      ...((raw && raw.managedTemplates) || {}),
+    },
+  };
+}
+
+export async function readProjectState(projectRoot) {
+  return normalizeState(await readJson(statePath(projectRoot), null));
+}
+
+export async function writeProjectState(projectRoot, state) {
+  const next = normalizeState(state);
+  next.schemaVersion = PROJECT_STATE_SCHEMA_VERSION;
+  next.lastUpdatedAt = new Date().toISOString();
+  await writeJson(statePath(projectRoot), next);
+  return next;
+}
+
+function replaceMarkedBlock(current, replacement) {
+  const start = current.indexOf(ROOT_POLICY_START);
+  const end = current.indexOf(ROOT_POLICY_END);
+  if (start === -1 || end === -1 || end < start) return null;
+  const afterEnd = end + ROOT_POLICY_END.length;
+  return `${current.slice(0, start)}${replacement.trimStart().trimEnd()}${current.slice(afterEnd)}`;
+}
+
+function hasGeneratedMarker(text, descriptor) {
+  return descriptor.marker ? text.includes(descriptor.marker) : false;
+}
+
+function isRecordedManaged(state, descriptor, currentText) {
+  const recorded = state.managedTemplates?.[descriptor.id];
+  if (!recorded) return false;
+  if (descriptor.mode === 'marker') return true;
+  return !recorded.hash || recorded.hash === templateHash(currentText);
+}
+
+function isKnownGeneratedContent(text, descriptor) {
+  if (descriptor.mode === 'marker') return replaceMarkedBlock(text, descriptor.content) !== null;
+  return templateHash(text) === templateHash(descriptor.content) || hasGeneratedMarker(text, descriptor);
+}
+
+function canPatchDescriptor(state, descriptor, currentText) {
+  if (descriptor.mode === 'marker') return replaceMarkedBlock(currentText, descriptor.content) !== null;
+  return isRecordedManaged(state, descriptor, currentText) || isKnownGeneratedContent(currentText, descriptor);
+}
+
+function desiredTextForDescriptor(descriptor, currentText) {
+  if (descriptor.mode === 'marker') return replaceMarkedBlock(currentText, descriptor.content);
+  return descriptor.content;
+}
+
+export async function inspectProjectState(projectRoot) {
+  const state = await readProjectState(projectRoot);
+  const runtime = runtimeVersion();
+  const files = [];
+
+  for (const descriptor of templateDescriptors()) {
+    const absolutePath = join(projectRoot, descriptor.path);
+    const fileExists = await exists(absolutePath);
+    const currentText = fileExists ? await readText(absolutePath) : '';
+    const desiredText = fileExists ? desiredTextForDescriptor(descriptor, currentText) : descriptor.content;
+    const desiredHash = templateHash(desiredText || descriptor.content);
+    const currentHash = fileExists ? templateHash(currentText) : null;
+    const recorded = state.managedTemplates[descriptor.id] || null;
+    const patchable = fileExists ? canPatchDescriptor(state, descriptor, currentText) : false;
+    const current = fileExists && desiredText !== null && currentHash === templateHash(desiredText);
+
+    files.push({
+      id: descriptor.id,
+      path: descriptor.path,
+      exists: fileExists,
+      patchable,
+      current,
+      currentHash,
+      desiredHash,
+      recordedHash: recorded?.hash || null,
+      recordedVersion: recorded?.version || null,
+    });
+  }
+
+  return {
+    statePath: statePath(projectRoot),
+    stateExists: await exists(statePath(projectRoot)),
+    schemaVersion: state.schemaVersion,
+    lastRuntimeVersionApplied: state.lastRuntimeVersionApplied,
+    runtimeUpToDateWithProject: state.lastRuntimeVersionApplied === runtime,
+    managedFilesCurrent: files.every((file) => file.current || !file.patchable),
+    managedFiles: files,
+  };
+}
+
+export async function recordManagedTemplates(projectRoot) {
+  const state = await readProjectState(projectRoot);
+  const runtime = runtimeVersion();
+
+  for (const descriptor of templateDescriptors()) {
+    const absolutePath = join(projectRoot, descriptor.path);
+    if (!(await exists(absolutePath))) continue;
+    const currentText = await readText(absolutePath);
+    if (!canPatchDescriptor(state, descriptor, currentText)) continue;
+    state.managedTemplates[descriptor.id] = {
+      path: descriptor.path,
+      version: runtime,
+      hash: templateHash(currentText),
+    };
+  }
+
+  state.lastRuntimeVersionApplied = runtime;
+  return writeProjectState(projectRoot, state);
+}
+
+export async function applyProjectTemplateUpdate(projectRoot, options = {}) {
+  const state = await readProjectState(projectRoot);
+  const runtime = runtimeVersion();
+  const changed = [];
+  const skipped = [];
+  const unchanged = [];
+
+  for (const descriptor of templateDescriptors()) {
+    const absolutePath = join(projectRoot, descriptor.path);
+    if (!(await exists(absolutePath))) {
+      skipped.push({ id: descriptor.id, path: descriptor.path, reason: 'missing' });
+      continue;
+    }
+
+    const currentText = await readText(absolutePath);
+    if (!canPatchDescriptor(state, descriptor, currentText)) {
+      skipped.push({ id: descriptor.id, path: descriptor.path, reason: 'not-managed' });
+      continue;
+    }
+
+    const desiredText = desiredTextForDescriptor(descriptor, currentText);
+    if (desiredText === null) {
+      skipped.push({ id: descriptor.id, path: descriptor.path, reason: 'missing-marker' });
+      continue;
+    }
+
+    if (currentText === desiredText) {
+      unchanged.push({ id: descriptor.id, path: descriptor.path });
+      state.managedTemplates[descriptor.id] = {
+        path: descriptor.path,
+        version: runtime,
+        hash: templateHash(currentText),
+      };
+      continue;
+    }
+
+    if (!options.dryRun) {
+      await backupFile(absolutePath, relative(projectRoot, absolutePath));
+      await ensureDir(dirname(absolutePath));
+      await writeText(absolutePath, desiredText, 'utf8');
+    }
+
+    changed.push({ id: descriptor.id, path: descriptor.path });
+    state.managedTemplates[descriptor.id] = {
+      path: descriptor.path,
+      version: runtime,
+      hash: templateHash(desiredText),
+    };
+  }
+
+  state.lastRuntimeVersionApplied = runtime;
+  if (!options.dryRun) await writeProjectState(projectRoot, state);
+
+  return {
+    workspace: projectRoot,
+    runtimeVersion: runtime,
+    changed,
+    skipped,
+    unchanged,
+    dryRun: Boolean(options.dryRun),
+  };
+}

package/src/project.js

@@ -0,0 +1,204 @@
+import { join, relative } from 'path';
+import {
+  appendText,
+  ensureDir,
+  exists,
+  listMarkdownFiles,
+  readText,
+  timeKst,
+  todayKst,
+  writeTextIfMissing,
+} from './fs-utils.js';
+import { LLM_WIKI_DIRS } from './constants.js';
+import { redactText, summarizeForStorage } from './redaction.js';
+import { gitignore, indexPage, llmWikiAgents, logPage, procedure, rootAgentsPolicy } from './templates.js';
+import { recordManagedTemplates } from './project-state.js';
+
+export async function bootstrapProject(projectRoot, options = {}) {
+  if (process.env.LLM_WIKI_KIT_DISABLE_BOOTSTRAP === '1') return { created: false };
+  const base = join(projectRoot, 'llm-wiki');
+  for (const dir of LLM_WIKI_DIRS) {
+    await ensureDir(join(base, dir));
+  }
+
+  const created = [];
+  const maybeCreate = async (path, content) => {
+    if (await writeTextIfMissing(path, content)) created.push(relative(projectRoot, path));
+  };
+
+  await maybeCreate(join(base, 'AGENTS.md'), llmWikiAgents());
+  await maybeCreate(join(base, 'wiki', 'index.md'), indexPage());
+  await maybeCreate(join(base, 'wiki', 'log.md'), logPage());
+  await maybeCreate(join(base, '.gitignore'), gitignore());
+  for (const name of ['ingest.md', 'query.md', 'lint.md', 'security.md']) {
+    await maybeCreate(join(base, 'procedures', name), procedure(name));
+  }
+
+  const rootAgents = join(projectRoot, 'AGENTS.md');
+  if (await exists(rootAgents)) {
+    const current = await readText(rootAgents);
+    if (!current.includes('<!-- llm-wiki-kit:start -->')) {
+      await appendText(rootAgents, rootAgentsPolicy());
+      created.push('AGENTS.md#llm-wiki-kit-policy');
+    }
+  } else {
+    await maybeCreate(rootAgents, `# Repository Instructions\n${rootAgentsPolicy()}`);
+  }
+
+  const claudeMd = join(projectRoot, 'CLAUDE.md');
+  if (!(await exists(claudeMd))) {
+    await maybeCreate(claudeMd, '@AGENTS.md\n');
+  }
+
+  if (created.length > 0) {
+    await appendWikiLog(projectRoot, `bootstrap: created ${created.join(', ')}`);
+  }
+  if (created.length > 0 || options.recordState === true) {
+    await recordManagedTemplates(projectRoot);
+  }
+  return { created: created.length > 0, files: created };
+}
+
+export async function appendWikiLog(projectRoot, message) {
+  const line = `\n## ${todayKst()} ${timeKst()} KST\n\n- ${summarizeForStorage(message, 1000)}\n`;
+  await appendText(join(projectRoot, 'llm-wiki', 'wiki', 'log.md'), line);
+}
+
+export async function appendSessionEnvelope(projectRoot, eventName, payload) {
+  const day = todayKst();
+  const path = join(projectRoot, 'llm-wiki', 'raw', 'sessions', `${day}-events.jsonl`);
+  const safePayload = {
+    timestamp: new Date().toISOString(),
+    event: eventName,
+    provider: payload.__provider,
+    cwd: payload.cwd,
+    session_id: payload.session_id || payload.sessionId || payload.conversation_id || undefined,
+    transcript_path: payload.transcript_path ? '[REDACTED_PATH_PRESENT]' : undefined,
+  };
+  await appendText(path, `${JSON.stringify(safePayload)}\n`);
+}
+
+export function slugify(value, fallback = 'note') {
+  const ascii = String(value || '')
+    .normalize('NFKD')
+    .replace(/[^\p{Letter}\p{Number}]+/gu, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase()
+    .slice(0, 80);
+  return ascii || fallback;
+}
+
+export async function appendLiveQa(projectRoot, entry) {
+  const day = todayKst();
+  const path = join(projectRoot, 'llm-wiki', 'outputs', 'questions', `${day}-live-qa.md`);
+  const block = [
+    `\n## ${timeKst()} KST - ${entry.topic || 'session turn'}`,
+    '',
+    '### Question',
+    entry.question || '(not captured)',
+    '',
+    '### Work',
+    entry.work || '(not captured)',
+    '',
+    '### Result',
+    entry.result || '(not captured)',
+    '',
+    '### Changed files',
+    entry.changedFiles || '(not captured)',
+    '',
+    '### Verification',
+    entry.verification || '(not captured)',
+    '',
+    '### Follow-up',
+    entry.followUp || '(none captured)',
+    '',
+  ].join('\n');
+  await appendText(path, redactText(block, 12000));
+}
+
+export async function writeQueryPage(projectRoot, entry) {
+  if (!entry.question || entry.question.length < 8) return null;
+  const day = todayKst();
+  const slug = slugify(entry.question, 'query');
+  const path = join(projectRoot, 'llm-wiki', 'wiki', 'queries', `${day}-${slug}.md`);
+  if (await exists(path)) return path;
+  const content = `---\ntitle: "${entry.topic || slug}"\ntype: "query"\nsource_ids: []\nstatus: "draft"\nlast_updated: "${day}"\nconfidence: "medium"\n---\n\n# ${entry.topic || entry.question.slice(0, 80)}\n\n## Question\n${entry.question}\n\n## Answer Summary\n${entry.result || '(not captured)'}\n\n## Work Notes\n${entry.work || '(not captured)'}\n\n## Verification\n${entry.verification || '(not captured)'}\n\n## Related Pages\n- [[index]]\n\n## Change Log\n- ${day}: Captured automatically by llm-wiki-kit hook.\n`;
+  await writeTextIfMissing(path, redactText(content, 12000));
+  return path;
+}
+
+export async function writeDecisionPage(projectRoot, entry) {
+  const text = `${entry.question || ''}\n${entry.result || ''}`;
+  if (!/(decision|decided|결정|선택|채택|확정)/i.test(text)) return null;
+  const day = todayKst();
+  const slug = slugify(entry.topic || entry.question || 'decision', 'decision');
+  const path = join(projectRoot, 'llm-wiki', 'wiki', 'decisions', `${day}-${slug}.md`);
+  if (await exists(path)) return path;
+  const content = `---\ntitle: "${entry.topic || slug}"\ntype: "decision"\nsource_ids: []\nstatus: "draft"\nlast_updated: "${day}"\nconfidence: "medium"\n---\n\n# ${entry.topic || 'Decision'}\n\n## Decision\n${entry.result || '(captured from assistant response; review needed)'}\n\n## Context\n${entry.question || '(not captured)'}\n\n## Evidence\n${entry.work || '(not captured)'}\n\n## Verification\n${entry.verification || '(not captured)'}\n\n## Open Questions\n${entry.followUp || '(none captured)'}\n\n## Change Log\n- ${day}: Captured automatically by llm-wiki-kit hook.\n`;
+  await writeTextIfMissing(path, redactText(content, 12000));
+  return path;
+}
+
+export async function appendContextNote(projectRoot, eventName, text) {
+  const day = todayKst();
+  const path = join(projectRoot, 'llm-wiki', 'wiki', 'context', `${day}-session-context.md`);
+  const block = `\n## ${timeKst()} KST - ${eventName}\n\n${summarizeForStorage(text || '(no context)', 4000)}\n`;
+  await appendText(path, block);
+}
+
+function tokenize(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[^\p{Letter}\p{Number}]+/gu, ' ')
+    .split(/\s+/)
+    .filter((token) => token.length >= 2)
+    .slice(0, 80);
+}
+
+export async function searchWiki(projectRoot, query, limit = 5) {
+  const wikiRoot = join(projectRoot, 'llm-wiki', 'wiki');
+  const files = await listMarkdownFiles(wikiRoot, 400);
+  const terms = tokenize(query);
+  if (terms.length === 0) return [];
+  const scored = [];
+  for (const file of files) {
+    const raw = await readText(file);
+    const content = raw.slice(0, 50000);
+    const lower = content.toLowerCase();
+    let score = 0;
+    for (const term of terms) {
+      if (lower.includes(term)) score += term.length > 3 ? 2 : 1;
+    }
+    if (score > 0) {
+      const rel = relative(join(projectRoot, 'llm-wiki'), file);
+      scored.push({
+        score,
+        path: rel,
+        snippet: content.replace(/\s+/g, ' ').slice(0, 350),
+      });
+    }
+  }
+  return scored.sort((a, b) => b.score - a.score).slice(0, limit);
+}
+
+export async function buildContextBrief(projectRoot, eventName, query = '') {
+  const index = await readText(join(projectRoot, 'llm-wiki', 'wiki', 'index.md'));
+  const log = await readText(join(projectRoot, 'llm-wiki', 'wiki', 'log.md'));
+  const hits = query ? await searchWiki(projectRoot, query, 5) : [];
+  const parts = [
+    'LLM Wiki context from llm-wiki-kit:',
+    '- Treat chat memory as temporary; update project Markdown when knowledge should persist.',
+    '- Preserve raw/wiki separation. Do not store secrets, tokens, .env contents, private keys, or personal/customer identifiers.',
+    '- Prefer updating existing wiki pages over creating duplicate pages.',
+    '',
+    'Index excerpt:',
+    index.slice(0, 1200).trim(),
+  ];
+  if (hits.length > 0) {
+    parts.push('', 'Relevant wiki pages:', ...hits.map((hit) => `- ${hit.path}: ${hit.snippet}`));
+  }
+  if (eventName === 'SessionStart') {
+    parts.push('', 'Recent log excerpt:', log.slice(-1000).trim());
+  }
+  return parts.join('\n').trim();
+}