@rarusoft/dendrite-wiki 0.1.0-alpha.0

package/src/doctor.ts

@@ -0,0 +1,260 @@
+/**
+ * `dendrite-wiki doctor` — project-health audit.
+ *
+ * Aggregates findings from every health-relevant subsystem into one ranked list with
+ * severities (`critical`, `warning`, `info`): missing required files, stale benchmark
+ * snapshots, accumulated wiki lint findings, contested or unsupported memories, missing
+ * telemetry config when sharing is opt-in, etc. The CLI prints a human report by default
+ * and a structured `--json` output for scripted health checks.
+ *
+ * The doctor exits 1 on any `critical` finding so it integrates cleanly with CI gates and
+ * pre-commit hooks. Most findings are advisory and live as `warning` so the doctor stays
+ * useful without becoming a nag.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { readBenchmarkHistory } from './benchmark.js';
+import { reviewProjectMemories, type ProjectMemoryReviewFinding } from '@rarusoft/dendrite-memory';
+import { lintWikiPages, listWikiPages, listWikiProposals } from './store.js';
+import { writeTelemetryStatusArtifact } from './telemetry.js';
+
+export type DoctorSeverity = 'critical' | 'warning' | 'info';
+
+export interface DoctorFinding {
+  severity: DoctorSeverity;
+  rule: string;
+  title: string;
+  detail: string;
+  fix?: string;
+}
+
+export interface DoctorReport {
+  generatedAt: string;
+  root: string;
+  findings: DoctorFinding[];
+  counts: {
+    critical: number;
+    warning: number;
+    info: number;
+  };
+  status: 'healthy' | 'warnings' | 'critical';
+}
+
+export async function runDoctor(options: { root?: string } = {}): Promise<DoctorReport> {
+  const root = path.resolve(options.root ?? process.cwd());
+  const findings: DoctorFinding[] = [];
+
+  // Critical filesystem checks first — if these fail, deeper checks may throw.
+  const wikiDirExists = await pathExists(path.join(root, 'docs', 'wiki'));
+  if (!wikiDirExists) {
+    findings.push({
+      severity: 'critical',
+      rule: 'no-wiki-directory',
+      title: 'Wiki directory is missing.',
+      detail: 'Dendrite expects markdown pages under docs/wiki/. The agent has nothing to read or update.',
+      fix: 'npx dendrite-wiki init'
+    });
+  }
+
+  const indexExists = await pathExists(path.join(root, 'docs', 'index.md'));
+  if (!indexExists) {
+    findings.push({
+      severity: 'critical',
+      rule: 'no-index-page',
+      title: 'docs/index.md is missing.',
+      detail: 'Agents are instructed to read docs/index.md first. Without it, orientation breaks.',
+      fix: 'npx dendrite-wiki init'
+    });
+  }
+
+  const mcpClientPaths = [
+    { client: 'Claude Code', file: '.mcp.json' },
+    { client: 'VS Code / Copilot', file: '.vscode/mcp.json' },
+    { client: 'Cursor', file: '.cursor/mcp.json' },
+    { client: 'Codex', file: '.codex/config.toml' },
+    { client: 'Continue', file: '.continue/mcpServers/dendrite-wiki-mcp.json' }
+  ];
+  const presentClients: string[] = [];
+  for (const entry of mcpClientPaths) {
+    if (await pathExists(path.join(root, entry.file))) {
+      presentClients.push(entry.client);
+    }
+  }
+  if (presentClients.length === 0) {
+    findings.push({
+      severity: 'critical',
+      rule: 'no-mcp-client-config',
+      title: 'No MCP client config files found.',
+      detail: 'No editor or agent client knows how to launch the MCP server. The agent cannot reach Dendrite.',
+      fix: 'npx dendrite-wiki init --profile claude  (or --profile cursor / copilot-vscode / codex / continue)'
+    });
+  } else {
+    findings.push({
+      severity: 'info',
+      rule: 'mcp-clients-configured',
+      title: `${presentClients.length} MCP client config${presentClients.length === 1 ? '' : 's'} present.`,
+      detail: `Configured: ${presentClients.join(', ')}.`
+    });
+  }
+
+  // If the basic skeleton is broken, skip deeper checks to avoid noisy errors.
+  const skeletonOk = wikiDirExists && indexExists;
+
+  if (skeletonOk) {
+    const [pages, lintFindings, proposals, memoryReview, history, telemetryStatus] = await Promise.all([
+      listWikiPages().catch(() => []),
+      lintWikiPages().catch(() => []),
+      listWikiProposals().catch(() => []),
+      reviewProjectMemories().catch(() => ({ findings: [] as ProjectMemoryReviewFinding[] })),
+      readBenchmarkHistory(root).catch(() => null),
+      writeTelemetryStatusArtifact(root).catch(() => null)
+    ]);
+
+    if (lintFindings.length > 0) {
+      findings.push({
+        severity: 'warning',
+        rule: 'lint-findings-present',
+        title: `${lintFindings.length} wiki lint finding${lintFindings.length === 1 ? '' : 's'}.`,
+        detail: 'The wiki has open hygiene issues (oversized guidance, stale claims, orphan pages, etc.). Review the maintenance inbox to triage.',
+        fix: 'Open docs/wiki/maintenance-inbox.md or run `npx dendrite-wiki benchmark:snapshot` to refresh state.'
+      });
+    }
+
+    if (proposals.length > 0) {
+      findings.push({
+        severity: 'warning',
+        rule: 'pending-proposals',
+        title: `${proposals.length} pending maintenance proposal${proposals.length === 1 ? '' : 's'}.`,
+        detail: 'Generated guidance cleanup proposals are waiting for review.',
+        fix: 'Open docs/wiki/maintenance-review.md in the browser, or call wiki_apply_proposal for low-risk items.'
+      });
+    }
+
+    const contradictionFindings = memoryReview.findings.filter((f) => f.kind === 'contradiction');
+    if (contradictionFindings.length > 0) {
+      findings.push({
+        severity: 'warning',
+        rule: 'memory-contradictions',
+        title: `${contradictionFindings.length} memory contradiction group${contradictionFindings.length === 1 ? '' : 's'} detected.`,
+        detail: 'Two or more memories disagree. The agent may be acting on inconsistent project truth.',
+        fix: 'Open the Maintenance Review board in the browser to inspect and resolve.'
+      });
+    }
+
+    if (history && history.snapshots.length > 0) {
+      const latest = history.latest && history.latest.timestamp ? history.latest : history.snapshots.at(-1);
+      if (latest && latest.timestamp) {
+        const ageDays = Math.floor((Date.now() - new Date(latest.timestamp).getTime()) / (1000 * 60 * 60 * 24));
+        if (ageDays > 14) {
+          findings.push({
+            severity: 'warning',
+            rule: 'stale-benchmark',
+            title: `Last benchmark snapshot is ${ageDays} days old.`,
+            detail: 'Benchmarks should be captured at session boundaries to detect drift. Stale snapshots make trend lines meaningless.',
+            fix: 'npx dendrite-wiki benchmark:snapshot --label session-end'
+          });
+        }
+      }
+    } else {
+      findings.push({
+        severity: 'warning',
+        rule: 'no-benchmark-history',
+        title: 'No benchmark snapshots have been captured.',
+        detail: 'Without baseline snapshots there is no way to measure whether Dendrite is helping the project over time.',
+        fix: 'npx dendrite-wiki benchmark:snapshot --label baseline'
+      });
+    }
+
+    const projectLogPath = path.join(root, 'docs', 'wiki', 'project-log.md');
+    if (await pathExists(projectLogPath)) {
+      const projectLogStat = await fs.stat(projectLogPath);
+      const logAgeDays = Math.floor((Date.now() - projectLogStat.mtime.getTime()) / (1000 * 60 * 60 * 24));
+      if (logAgeDays > 7) {
+        findings.push({
+          severity: 'warning',
+          rule: 'stale-project-log',
+          title: `project-log.md was last touched ${logAgeDays} days ago.`,
+          detail: 'No meaningful work has been logged in the past week. The project log is the chronological record agents read for context.',
+          fix: 'Append an entry via wiki_log when meaningful work happens.'
+        });
+      }
+    }
+
+    if (!(await pathExists(path.join(root, '.git')))) {
+      findings.push({
+        severity: 'warning',
+        rule: 'no-git-repository',
+        title: 'No .git/ directory found.',
+        detail: 'Dendrite assumes git for diff-based review. Without git, audit and rollback are weakened.',
+        fix: 'git init'
+      });
+    }
+
+    findings.push({
+      severity: 'info',
+      rule: 'project-stats',
+      title: `${pages.length} wiki page${pages.length === 1 ? '' : 's'} total.`,
+      detail: `${lintFindings.length} lint finding${lintFindings.length === 1 ? '' : 's'}, ${proposals.length} proposal${proposals.length === 1 ? '' : 's'}, ${memoryReview.findings.length} memory finding${memoryReview.findings.length === 1 ? '' : 's'}. Telemetry: ${telemetryStatus?.sharingMode ?? 'unknown'}.`
+    });
+  }
+
+  const counts = {
+    critical: findings.filter((f) => f.severity === 'critical').length,
+    warning: findings.filter((f) => f.severity === 'warning').length,
+    info: findings.filter((f) => f.severity === 'info').length
+  };
+  const status: DoctorReport['status'] = counts.critical > 0 ? 'critical' : counts.warning > 0 ? 'warnings' : 'healthy';
+
+  return {
+    generatedAt: new Date().toISOString(),
+    root,
+    findings,
+    counts,
+    status
+  };
+}
+
+export function formatDoctorReport(report: DoctorReport): string {
+  const lines: string[] = [];
+  const statusEmoji = report.status === 'healthy' ? 'OK' : report.status === 'warnings' ? 'WARN' : 'FAIL';
+  lines.push(`Dendrite Doctor — ${statusEmoji}`);
+  lines.push(`Project: ${report.root}`);
+  lines.push(`Critical: ${report.counts.critical}  Warnings: ${report.counts.warning}  Info: ${report.counts.info}`);
+  lines.push('');
+
+  const sections: Array<{ severity: DoctorSeverity; label: string }> = [
+    { severity: 'critical', label: 'CRITICAL' },
+    { severity: 'warning', label: 'WARNING' },
+    { severity: 'info', label: 'INFO' }
+  ];
+
+  for (const section of sections) {
+    const sectionFindings = report.findings.filter((f) => f.severity === section.severity);
+    if (sectionFindings.length === 0) continue;
+
+    lines.push(`[${section.label}]`);
+    for (const finding of sectionFindings) {
+      lines.push(`  ${finding.title}`);
+      lines.push(`    ${finding.detail}`);
+      if (finding.fix) {
+        lines.push(`    Fix: ${finding.fix}`);
+      }
+      lines.push('');
+    }
+  }
+
+  if (report.findings.length === 0) {
+    lines.push('No findings — Dendrite is healthy.');
+  }
+
+  return lines.join('\n');
+}
+
+async function pathExists(target: string): Promise<boolean> {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/generated-docs.ts

@@ -0,0 +1,316 @@
+/**
+ * The wiki refresh orchestrator — `npm run wiki:refresh` entry point.
+ *
+ * Rebuilds every deterministic derived view in the project: the catalog block in
+ * `docs/index.md`, `docs/wiki/maintenance-inbox.md` (and its JSON twin), the recent raw
+ * observation stream, the guidance-lifecycle table, the wiki search index (JSON +
+ * SQLite FTS5), and — since A5 of the API reference roadmap — the entire `docs/wiki/api/`
+ * tree via `refreshApiReference()` from `./api-reference.ts`.
+ *
+ * The order matters: API reference generation runs first so the page catalog and search
+ * index built later in the same call see the fresh generated pages. Every write goes
+ * through `writeIfChanged` so untouched files don't bump mtime, which keeps `npm run check`
+ * idempotent across repeated runs.
+ *
+ * This module deliberately does NOT write technical narrative pages like architecture.md.
+ * It only rebuilds derived views that map cleanly from primary data; humans own the prose.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { refreshApiReference } from './api-reference.js';
+import { reviewProjectMemories } from '@rarusoft/dendrite-memory';
+import {
+  buildWikiGraphSnapshot,
+  extractWikiClaims,
+  lintWikiPages,
+  listGuidanceLifecycle,
+  listWikiPages,
+  listWikiProposals,
+  readWikiPage,
+  searchWikiPages,
+  type WikiPageSummary
+} from './store.js';
+import { buildMaintenanceInboxPage, buildMaintenanceInboxSnapshot } from './maintenance-inbox.js';
+import { detectRawObservationClusters, readRawObservations } from '@rarusoft/dendrite-memory';
+import type { ExecutedMaintenanceAction } from './maintenance-actions.js';
+
+const indexPath = path.resolve(process.cwd(), 'docs', 'index.md');
+const maintenanceInboxPath = path.resolve(process.cwd(), 'docs', 'wiki', 'maintenance-inbox.md');
+const maintenanceInboxDataPath = path.resolve(process.cwd(), 'docs', 'public', 'maintenance-inbox.json');
+const observationStreamDataPath = path.resolve(process.cwd(), 'docs', 'public', 'raw-observations-recent.json');
+const observationStreamRecentSampleSize = 200;
+const guidanceLifecyclePath = path.resolve(process.cwd(), 'docs', 'wiki', 'guidance-lifecycle.md');
+const guidanceLifecycleDataPath = path.resolve(process.cwd(), 'docs', 'public', 'guidance-lifecycle.json');
+const maintenanceActionResultPath = path.resolve(process.cwd(), 'docs', 'public', 'maintenance-action-result.json');
+const wikiSearchIndexPath = path.resolve(process.cwd(), 'docs', 'public', 'wiki-search-index.json');
+const sqliteSearchIndexPath = path.resolve(process.cwd(), process.env.DENDRITE_WIKI_DATA_DIR ?? 'local-data', 'wiki-search.sqlite');
+const markerStart = '<!-- WIKI_CATALOG_START -->';
+const markerEnd = '<!-- WIKI_CATALOG_END -->';
+
+export interface MaintenanceActionArtifact {
+  ranAt: string;
+  refreshedPageCount: number;
+  audit: {
+    artifactPath: string;
+    changedPaths: string[];
+    projectLogEntry?: string;
+    undoPath: string;
+  };
+  execution: ExecutedMaintenanceAction;
+}
+
+export async function refreshGeneratedWikiDocs(): Promise<{ pageCount: number }> {
+  // Regenerate the API reference first so listWikiPages() and the lint pass below see the
+  // current set of generated pages. Projects without a `src/` directory get a harmless
+  // empty-result no-op (walkProjectSources returns []). Generation failures escalate so
+  // `npm run check` surfaces real breakage rather than silently shipping a stale catalog.
+  await refreshApiReference();
+
+  const [findings, proposals, memoryReview, observationClusters] = await Promise.all([
+    lintWikiPages(),
+    listWikiProposals(),
+    reviewProjectMemories(),
+    detectRawObservationClusters()
+  ]);
+  const index = await fs.readFile(indexPath, 'utf8');
+  const indexEol = detectEol(index);
+  const maintenanceInbox = await fs.readFile(maintenanceInboxPath, 'utf8').catch(() => '');
+  const maintenanceInboxEol = '\n';
+  const reviewPageExists = async (reviewPath: string) => {
+    try {
+      await fs.access(path.resolve(process.cwd(), reviewPath));
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const nextMaintenanceInbox = normalizeEol(
+    await buildMaintenanceInboxPage(findings, proposals, {
+      reviewPageExists,
+      memoryFindings: memoryReview.findings,
+      observationClusters
+    }),
+    maintenanceInboxEol
+  );
+  await writeIfChanged(maintenanceInboxPath, maintenanceInbox, nextMaintenanceInbox);
+
+  const maintenanceInboxData = await fs.readFile(maintenanceInboxDataPath, 'utf8').catch(() => '');
+  const nextMaintenanceInboxData = ensureTrailingEol(
+    JSON.stringify(
+      await buildMaintenanceInboxSnapshot(findings, proposals, {
+        reviewPageExists,
+        memoryFindings: memoryReview.findings,
+        observationClusters
+      }),
+      null,
+      2
+    ),
+    '\n'
+  );
+  await writeIfChanged(maintenanceInboxDataPath, maintenanceInboxData, nextMaintenanceInboxData);
+
+  const observationStreamData = await fs.readFile(observationStreamDataPath, 'utf8').catch(() => '');
+  const recentObservations = await readRawObservations({ limit: observationStreamRecentSampleSize });
+  const nextObservationStreamData = ensureTrailingEol(
+    JSON.stringify(
+      {
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        sampleSize: observationStreamRecentSampleSize,
+        observationCount: recentObservations.length,
+        clusterCount: observationClusters.length,
+        observations: recentObservations
+      },
+      null,
+      2
+    ),
+    '\n'
+  );
+  await writeIfChanged(observationStreamDataPath, observationStreamData, nextObservationStreamData);
+
+  const guidanceLifecycle = await listGuidanceLifecycle();
+  const currentGuidanceLifecycle = await fs.readFile(guidanceLifecyclePath, 'utf8').catch(() => '');
+  const nextGuidanceLifecycle = normalizeEol(buildGuidanceLifecyclePage(guidanceLifecycle), '\n');
+  await writeIfChanged(guidanceLifecyclePath, currentGuidanceLifecycle, nextGuidanceLifecycle);
+
+  const guidanceLifecycleData = await fs.readFile(guidanceLifecycleDataPath, 'utf8').catch(() => '');
+  const nextGuidanceLifecycleData = ensureTrailingEol(JSON.stringify({ guidance: guidanceLifecycle }, null, 2), '\n');
+  await writeIfChanged(guidanceLifecycleDataPath, guidanceLifecycleData, nextGuidanceLifecycleData);
+
+  const pages = await listWikiPages();
+
+  const searchIndexData = await fs.readFile(wikiSearchIndexPath, 'utf8').catch(() => '');
+  const nextSearchIndexData = ensureTrailingEol(
+    JSON.stringify(
+      {
+        graph: await buildWikiGraphSnapshot(),
+        sampleSearch: await searchWikiPages('project wiki')
+      },
+      null,
+      2
+    ),
+    '\n'
+  );
+  await writeIfChanged(wikiSearchIndexPath, searchIndexData, nextSearchIndexData);
+  await writeSqliteSearchIndex(sqliteSearchIndexPath, pages);
+
+  const catalog = normalizeEol(
+    [
+      markerStart,
+      '',
+      '| Page | Slug |',
+      '|---|---|',
+      ...pages.map((page) => `| [${page.title}](./wiki/${page.slug}.md) | \`${page.slug}\` |`),
+      '',
+      markerEnd
+    ].join('\n'),
+    indexEol
+  );
+
+  let nextIndex = index;
+  if (nextIndex.includes(markerStart) && nextIndex.includes(markerEnd)) {
+    nextIndex = nextIndex.replace(new RegExp(`${markerStart}[\\s\\S]*?${markerEnd}`), catalog);
+  } else {
+    nextIndex += `${indexEol}${indexEol}## Generated Catalog${indexEol}${indexEol}${catalog}${indexEol}`;
+  }
+
+  await writeIfChanged(indexPath, index, ensureTrailingEol(nextIndex, indexEol));
+  return { pageCount: pages.length };
+}
+
+function buildGuidanceLifecyclePage(guidance: Awaited<ReturnType<typeof listGuidanceLifecycle>>): string {
+  const statusCounts = [...new Map(guidance.map((item) => [item.status, guidance.filter((candidate) => candidate.status === item.status).length])).entries()]
+    .sort(([left], [right]) => left.localeCompare(right));
+
+  return [
+    '# Guidance Lifecycle',
+    '',
+    'This generated page shows active, dormant, superseded, and pending-review guidance files from the current project.',
+    '',
+    '## Status',
+    guidance.length > 0 ? `- Guidance files: ${guidance.length}` : '- Guidance files: none.',
+    statusCounts.length > 0
+      ? `- Status groups: ${statusCounts.map(([status, count]) => `\`${status}\` (${count})`).join(', ')}`
+      : '- Status groups: none.',
+    '',
+    '## Lifecycle Table',
+    guidance.length === 0
+      ? 'No guidance files found.'
+      : [
+          '| Path | Kind | Status | Review | Archive Target | Linked From | Reason |',
+          '|---|---|---|---|---|---|---|',
+          ...guidance.map((item) => `| ${escapeTableCell(item.path)} | \`${item.kind}\` | \`${item.status}\` | ${item.reviewStatus ?? 'none'} | ${escapeTableCell(item.archiveTarget ?? '')} | ${escapeTableCell(item.linkedFrom.join(', ') || 'none')} | ${escapeTableCell(item.reason)} |`)
+        ].join('\n'),
+    ''
+  ].join('\n');
+}
+
+function escapeTableCell(value: string): string {
+  return value.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+
+export async function writeLatestMaintenanceActionArtifact(artifact: MaintenanceActionArtifact): Promise<void> {
+  const currentContent = await fs.readFile(maintenanceActionResultPath, 'utf8').catch(() => '');
+  const nextContent = ensureTrailingEol(JSON.stringify(artifact, null, 2), '\n');
+  await writeIfChanged(maintenanceActionResultPath, currentContent, nextContent);
+}
+
+function detectEol(content: string): string {
+  return content.includes('\r\n') ? '\r\n' : '\n';
+}
+
+function normalizeEol(content: string, eol: string): string {
+  return content.replace(/\r?\n/g, eol);
+}
+
+function ensureTrailingEol(content: string, eol: string): string {
+  const withoutTrailingEol = content.replace(/(?:\r?\n)+$/g, '');
+  return `${withoutTrailingEol}${eol}`;
+}
+
+function extractSummaryParagraph(content: string): string {
+  const lines = content.split(/\r?\n/);
+  const h1Index = lines.findIndex((line) => /^#\s+\S+/.test(line));
+  const bodyLines = lines.slice(h1Index === -1 ? 0 : h1Index + 1);
+
+  for (const line of bodyLines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('|') || trimmed.startsWith('- ') || /^\d+\.\s/.test(trimmed)) {
+      continue;
+    }
+    return trimmed;
+  }
+
+  return '';
+}
+
+async function writeIfChanged(filePath: string, currentContent: string, nextContent: string): Promise<void> {
+  if (currentContent === nextContent) {
+    return;
+  }
+
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, nextContent, 'utf8');
+}
+
+async function writeSqliteSearchIndex(filePath: string, pages: WikiPageSummary[]): Promise<void> {
+  const sqliteModule = await loadNodeSqliteModule();
+  if (!sqliteModule) {
+    return;
+  }
+
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.rm(filePath, { force: true });
+
+  const database = new sqliteModule.DatabaseSync(filePath);
+  try {
+    database.exec([
+      'CREATE VIRTUAL TABLE pages_fts USING fts5(slug, title, path, summary, content);',
+      'CREATE VIRTUAL TABLE claims_fts USING fts5(page_slug, status, text, sources);',
+      'CREATE TABLE graph_edges(source_slug TEXT NOT NULL, target_slug TEXT NOT NULL);'
+    ].join('\n'));
+
+    const pageByPath = new Map(pages.map((page) => [page.path, page.slug]));
+    const insertPage = database.prepare('INSERT INTO pages_fts(slug, title, path, summary, content) VALUES (?, ?, ?, ?, ?)');
+    const insertClaim = database.prepare('INSERT INTO claims_fts(page_slug, status, text, sources) VALUES (?, ?, ?, ?)');
+    const insertEdge = database.prepare('INSERT INTO graph_edges(source_slug, target_slug) VALUES (?, ?)');
+
+    for (const page of pages) {
+      const content = await readWikiPage(page.slug);
+      insertPage.run(page.slug, page.title, page.path, extractSummaryParagraph(content) || page.title, content);
+
+      for (const claim of extractWikiClaims(page.slug, content, pageByPath)) {
+        insertClaim.run(claim.pageSlug, claim.status, claim.text, claim.sources.map((source) => source.slug).join(' '));
+        for (const source of claim.sources) {
+          insertEdge.run(page.slug, source.slug);
+        }
+      }
+    }
+  } finally {
+    database.close();
+  }
+}
+
+async function loadNodeSqliteModule(): Promise<
+  | {
+      DatabaseSync: new (filePath: string) => {
+        exec: (sql: string) => void;
+        prepare: (sql: string) => { run: (...values: unknown[]) => void };
+        close: () => void;
+      };
+    }
+  | undefined
+> {
+  const dynamicImport = new Function('specifier', 'return import(specifier)') as (specifier: string) => Promise<unknown>;
+  return dynamicImport('node:sqlite').catch(() => undefined) as Promise<
+    | {
+        DatabaseSync: new (filePath: string) => {
+          exec: (sql: string) => void;
+          prepare: (sql: string) => { run: (...values: unknown[]) => void };
+          close: () => void;
+        };
+      }
+    | undefined
+  >;
+}

package/src/i18n.ts

@@ -0,0 +1,106 @@
+// C7 slice 2: per-language modes for agent-facing strings.
+//
+// This is intentionally minimal: a single string-table per language code, resolved at call
+// time via the DENDRITE_LANG env var. The default is English. The framework is the
+// deliverable here; translations ship as forks or follow-up PRs once a real operator asks
+// for one.
+//
+// Storage rules stay English-only: memory bodies, wiki pages, claims, and project-log
+// entries are never translated by this module. Only operator-facing message text (cluster
+// templates, ritual reminders, hook output) is routed through the i18n table.
+//
+// Adding a new language:
+// 1. Pick an ISO 639-1 code (zh, ja, es, fr, de, etc.).
+// 2. Add an entry to the `translations` map below with the message keys you want to
+//    localize. Missing keys fall back to English automatically.
+// 3. Document the new code in docs/wiki/competitive-feature-roadmap.md (phase C7).
+
+export type DendriteLangCode = string;
+
+export type DendriteI18nKey =
+  | 'observation-cluster-template-header'
+  | 'observation-cluster-template-considerations'
+  | 'observation-cluster-template-options-edit-or-read'
+  | 'observation-cluster-template-options-default'
+  | 'observation-cluster-template-replace-instruction';
+
+export interface DendriteI18nMessageBundle {
+  // Each entry is a function from interpolation values to string so callers can pass in
+  // dynamic values (counts, paths) without forcing eager substitution at load time.
+  [key: string]: (values: Record<string, string | number>) => string;
+}
+
+const englishMessages: DendriteI18nMessageBundle = {
+  'observation-cluster-template-header': ({ kind, target, observationCount, distinctSessionCount, lastSeen }) =>
+    `Recurring activity detected: ${kind} on ${target} (${observationCount} observation${observationCount === 1 ? '' : 's'} across ${distinctSessionCount} session${distinctSessionCount === 1 ? '' : 's'}, last seen ${lastSeen}).`,
+  'observation-cluster-template-considerations': () =>
+    'Consider documenting why this {kindLabel} keeps coming up — for example:',
+  'observation-cluster-template-options-edit-or-read': () =>
+    [
+      '- a setup or onboarding gotcha future agents should know about',
+      '- a refactoring target that has accumulated repeated edits',
+      '- a frequently-broken integration or test',
+      '- a workflow pattern worth promoting to a scope-bound skill'
+    ].join('\n'),
+  'observation-cluster-template-options-default': () =>
+    [
+      '- a setup or onboarding gotcha future agents should know about',
+      '- a refactoring target that has accumulated repeated activity',
+      '- a frequently-broken integration or test',
+      '- a workflow pattern worth promoting to a scope-bound skill'
+    ].join('\n'),
+  'observation-cluster-template-replace-instruction': () =>
+    'Replace this template text with the actual lesson, then optionally promote to a skill via memory_promote_skill once the lesson has been recalled enough times.'
+};
+
+// Sample non-English bundle — Spanish — so the routing has a real second path to test.
+// Operators adding more languages should follow this exact shape.
+const spanishMessages: DendriteI18nMessageBundle = {
+  'observation-cluster-template-header': ({ kind, target, observationCount, distinctSessionCount, lastSeen }) =>
+    `Actividad recurrente detectada: ${kind} en ${target} (${observationCount} observación${observationCount === 1 ? '' : 'es'} en ${distinctSessionCount} sesión${distinctSessionCount === 1 ? '' : 'es'}, vista por última vez ${lastSeen}).`,
+  'observation-cluster-template-replace-instruction': () =>
+    'Reemplaza este texto plantilla con la lección real y luego promociónalo a una skill mediante memory_promote_skill una vez que la lección haya sido recordada suficientes veces.'
+};
+
+const translations: Record<string, DendriteI18nMessageBundle> = {
+  en: englishMessages,
+  es: spanishMessages
+};
+
+export function resolveDendriteLang(env: NodeJS.ProcessEnv = process.env): DendriteLangCode {
+  const raw = (env.DENDRITE_LANG ?? '').trim().toLowerCase();
+  if (!raw) {
+    return 'en';
+  }
+  // Accept full BCP-47 codes like en-US by stripping to the primary subtag.
+  return raw.split('-')[0];
+}
+
+export function translate(
+  key: DendriteI18nKey,
+  values: Record<string, string | number> = {},
+  options: { lang?: DendriteLangCode } = {}
+): string {
+  const lang = options.lang ?? resolveDendriteLang();
+  const bundle = translations[lang];
+  const fallback = translations.en;
+
+  const localized = bundle?.[key];
+  if (localized) {
+    return localized(values);
+  }
+
+  const fallbackEntry = fallback?.[key];
+  if (fallbackEntry) {
+    return fallbackEntry(values);
+  }
+
+  // Never throw on a missing key — agent-facing surfaces would prefer to render the key
+  // than fail. Operators can grep for any literal key in output to catch missing entries.
+  return key;
+}
+
+// Public helper used in tests + by anyone who wants to inspect available languages.
+export function listAvailableDendriteLangs(): DendriteLangCode[] {
+  return Object.keys(translations).sort();
+}