@okf-harness/core 0.1.0

package/dist/index.js

@@ -0,0 +1,2717 @@
+// src/config/index.ts
+import { readFile } from "fs/promises";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+
+// src/paths/index.ts
+import { realpath } from "fs/promises";
+import path from "path";
+var PATH_OUTSIDE_WORKSPACE = "PATH_OUTSIDE_WORKSPACE";
+var WorkspacePathError = class extends Error {
+  constructor(message, workspaceRoot, input) {
+    super(message);
+    this.workspaceRoot = workspaceRoot;
+    this.input = input;
+    this.name = "WorkspacePathError";
+  }
+  workspaceRoot;
+  input;
+  code = PATH_OUTSIDE_WORKSPACE;
+};
+function toPosixPath(input) {
+  return input.replace(/\\/g, "/");
+}
+function toPosixRelativePath(from, to) {
+  return toPosixPath(path.relative(from, to));
+}
+async function safeResolveWorkspacePath(workspaceRoot, input) {
+  if (input.trim().length === 0) {
+    throw new WorkspacePathError("Workspace path input must not be empty.", workspaceRoot, input);
+  }
+  const resolvedWorkspaceRoot = await realpathOrResolve(workspaceRoot);
+  const candidate = path.isAbsolute(input) ? path.resolve(input) : path.resolve(resolvedWorkspaceRoot, input);
+  const resolvedCandidate = await realpathExistingPrefix(candidate);
+  if (!isPathInside(resolvedWorkspaceRoot, resolvedCandidate)) {
+    throw new WorkspacePathError(
+      `Path resolves outside workspace: ${input}`,
+      resolvedWorkspaceRoot,
+      input
+    );
+  }
+  return {
+    workspaceRoot: resolvedWorkspaceRoot,
+    absolutePath: resolvedCandidate,
+    relativePath: toPosixRelativePath(resolvedWorkspaceRoot, resolvedCandidate)
+  };
+}
+function isPathInside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative.length === 0 || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+async function realpathOrResolve(input) {
+  try {
+    return await realpath(input);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") {
+      return path.resolve(input);
+    }
+    throw error;
+  }
+}
+async function realpathExistingPrefix(candidate) {
+  const missingSegments = [];
+  let current = candidate;
+  while (true) {
+    try {
+      const existing = await realpath(current);
+      return path.join(existing, ...missingSegments.reverse());
+    } catch (error) {
+      if (errorCode(error) !== "ENOENT") {
+        throw error;
+      }
+      const parent = path.dirname(current);
+      if (parent === current) {
+        return path.resolve(candidate);
+      }
+      missingSegments.push(path.basename(current));
+      current = parent;
+    }
+  }
+}
+function errorCode(error) {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return void 0;
+  }
+  const code = error.code;
+  return typeof code === "string" ? code : void 0;
+}
+
+// src/config/index.ts
+var CONFIG_INVALID = "CONFIG_INVALID";
+var configRelativePathSchema = z.string().min(1).refine((value) => isSafeConfigRelativePath(value), {
+  message: "Path must be a non-empty workspace-relative POSIX path without traversal."
+});
+var workspaceConfigSchema = z.object({
+  version: z.union([z.literal(0.1), z.literal("0.1")]).transform(() => "0.1"),
+  workspace: z.object({
+    name: z.string().min(1),
+    created_at: z.string().min(1),
+    platform: z.literal("macos")
+  }).strict(),
+  okf: z.object({
+    bundle_root: configRelativePathSchema,
+    profile: z.string().min(1)
+  }).strict(),
+  agents: z.object({
+    tier1: z.object({
+      claude: z.boolean(),
+      codex: z.boolean()
+    }).strict(),
+    tier2: z.object({
+      pi: z.boolean(),
+      opencode: z.boolean()
+    }).strict()
+  }).strict(),
+  paths: z.object({
+    raw_inbox: configRelativePathSchema,
+    raw_sources: configRelativePathSchema,
+    wiki_root: configRelativePathSchema,
+    manifest: configRelativePathSchema
+  }).strict(),
+  safety: z.object({
+    raw_sources_immutable: z.boolean(),
+    require_git_checkpoint_before_agent_write: z.boolean(),
+    max_files_changed_per_ingest: z.number().int().positive()
+  }).strict()
+}).strict().refine((config) => config.okf.bundle_root === config.paths.wiki_root, {
+  path: ["paths", "wiki_root"],
+  message: "paths.wiki_root must match okf.bundle_root."
+});
+var WorkspaceConfigError = class extends Error {
+  constructor(issues) {
+    super(issues.map((issue) => issue.message).join("; "));
+    this.issues = issues;
+    this.name = "WorkspaceConfigError";
+  }
+  issues;
+  code = CONFIG_INVALID;
+};
+function parseWorkspaceConfig(source) {
+  let rawConfig;
+  try {
+    rawConfig = parseYaml(source);
+  } catch (error) {
+    return {
+      ok: false,
+      issues: [
+        {
+          code: CONFIG_INVALID,
+          path: "<yaml>",
+          message: error instanceof Error ? error.message : "Invalid YAML."
+        }
+      ]
+    };
+  }
+  const parsed = workspaceConfigSchema.safeParse(rawConfig);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      issues: parsed.error.issues.map((issue) => ({
+        code: CONFIG_INVALID,
+        path: issue.path.length > 0 ? issue.path.join(".") : "<root>",
+        message: issue.message
+      }))
+    };
+  }
+  return { ok: true, config: parsed.data };
+}
+async function readWorkspaceConfig(workspaceRoot) {
+  let configPath;
+  try {
+    configPath = (await safeResolveWorkspacePath(workspaceRoot, "okfh.config.yaml")).absolutePath;
+  } catch (error) {
+    return {
+      ok: false,
+      issues: [
+        {
+          code: CONFIG_INVALID,
+          path: "okfh.config.yaml",
+          message: error instanceof Error ? error.message : "Could not resolve workspace config path."
+        }
+      ]
+    };
+  }
+  try {
+    return parseWorkspaceConfig(await readFile(configPath, "utf8"));
+  } catch (error) {
+    return {
+      ok: false,
+      issues: [
+        {
+          code: CONFIG_INVALID,
+          path: "okfh.config.yaml",
+          message: error instanceof Error ? error.message : "Could not read workspace config."
+        }
+      ]
+    };
+  }
+}
+async function loadWorkspaceConfig(workspaceRoot) {
+  const result = await readWorkspaceConfig(workspaceRoot);
+  if (!result.ok) {
+    throw new WorkspaceConfigError(result.issues);
+  }
+  return result.config;
+}
+function isSafeConfigRelativePath(value) {
+  if (value.startsWith("/") || value.includes("\\")) {
+    return false;
+  }
+  const segments = value.split("/");
+  return segments.every((segment) => segment.length > 0 && segment !== "..");
+}
+
+// src/graph/index.ts
+import { mkdir, writeFile } from "fs/promises";
+import path4 from "path";
+
+// src/okf/concepts.ts
+import { readdir, readFile as readFile2 } from "fs/promises";
+import path2 from "path";
+
+// src/okf/frontmatter.ts
+import matter from "gray-matter";
+function parseMarkdownFrontmatter(markdown) {
+  if (!markdown.startsWith("---\n") && !markdown.startsWith("---\r\n")) {
+    return {
+      ok: false,
+      hasFrontmatter: false,
+      error: "missing",
+      message: "Markdown file is missing YAML frontmatter."
+    };
+  }
+  try {
+    const parsed = matter(markdown);
+    return {
+      ok: true,
+      hasFrontmatter: true,
+      data: parsed.data,
+      body: parsed.content,
+      raw: parsed.matter
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      hasFrontmatter: true,
+      error: "invalid",
+      message: error instanceof Error ? error.message : "Invalid YAML frontmatter."
+    };
+  }
+}
+
+// src/okf/concepts.ts
+var RESERVED_OKF_FILENAMES = /* @__PURE__ */ new Set(["index.md", "log.md"]);
+var SCAN_FAILED = "SCAN_FAILED";
+var ConceptScanError = class extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.details = details;
+    this.name = "ConceptScanError";
+  }
+  details;
+  code = SCAN_FAILED;
+};
+async function scanConcepts(workspaceRoot, config) {
+  let wikiRoot;
+  let markdownFiles;
+  try {
+    wikiRoot = await safeResolveWorkspacePath(workspaceRoot, config.okf.bundle_root);
+    const files = await scanMarkdownFiles(wikiRoot.absolutePath);
+    markdownFiles = await Promise.all(
+      files.map(async (absolutePath) => {
+        const bundlePath = toPosixRelativePath(wikiRoot.absolutePath, absolutePath);
+        const markdown = await readFile2(absolutePath, "utf8");
+        return {
+          absolutePath,
+          workspacePath: toPosixRelativePath(wikiRoot.workspaceRoot, absolutePath),
+          bundlePath,
+          conceptId: conceptIdFromPath(bundlePath),
+          isReserved: isReservedOkfFile(bundlePath),
+          markdown,
+          frontmatter: parseMarkdownFrontmatter(markdown)
+        };
+      })
+    );
+  } catch (error) {
+    throw new ConceptScanError(
+      error instanceof Error ? error.message : "Could not scan OKF wiki.",
+      {
+        wikiRoot: config.okf.bundle_root
+      }
+    );
+  }
+  const concepts = markdownFiles.flatMap((file) => {
+    if (file.isReserved || !file.frontmatter.ok) {
+      return [];
+    }
+    const conceptType = stringValue(file.frontmatter.data.type);
+    if (conceptType === void 0) {
+      return [];
+    }
+    const concept = {
+      id: file.conceptId,
+      absolutePath: file.absolutePath,
+      workspacePath: file.workspacePath,
+      bundlePath: file.bundlePath,
+      type: conceptType,
+      tags: stringArrayValue(file.frontmatter.data.tags),
+      frontmatter: file.frontmatter.data,
+      body: file.frontmatter.body
+    };
+    const title = stringValue(file.frontmatter.data.title);
+    if (title !== void 0) {
+      concept.title = title;
+    }
+    const description = stringValue(file.frontmatter.data.description);
+    if (description !== void 0) {
+      concept.description = description;
+    }
+    const timestamp = stringValue(file.frontmatter.data.timestamp);
+    if (timestamp !== void 0) {
+      concept.timestamp = timestamp;
+    }
+    return [concept];
+  });
+  return {
+    workspaceRoot: wikiRoot.workspaceRoot,
+    wikiRoot: wikiRoot.absolutePath,
+    files: markdownFiles.sort((left, right) => left.bundlePath.localeCompare(right.bundlePath)),
+    concepts: concepts.sort((left, right) => left.id.localeCompare(right.id))
+  };
+}
+function conceptIdFromPath(markdownPath) {
+  const normalized = toPosixPath(markdownPath);
+  if (!normalized.endsWith(".md")) {
+    throw new Error(`Concept path must end with .md: ${markdownPath}`);
+  }
+  const withoutWikiPrefix = normalized.startsWith("wiki/") ? normalized.slice("wiki/".length) : normalized;
+  return withoutWikiPrefix.slice(0, -".md".length);
+}
+function isReservedOkfFile(bundlePath) {
+  return RESERVED_OKF_FILENAMES.has(path2.posix.basename(toPosixPath(bundlePath)));
+}
+async function scanMarkdownFiles(root) {
+  const entries = await readdir(root, { withFileTypes: true });
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const absolutePath = path2.join(root, entry.name);
+      if (entry.isDirectory()) {
+        return scanMarkdownFiles(absolutePath);
+      }
+      if (entry.isFile() && entry.name.endsWith(".md")) {
+        return [absolutePath];
+      }
+      return [];
+    })
+  );
+  return nested.flat().sort((left, right) => left.localeCompare(right));
+}
+function stringValue(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function stringArrayValue(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+
+// src/okf/links.ts
+import path3 from "path";
+function parseMarkdownLinks(markdown) {
+  const links = [];
+  const lines = markdown.split(/\r?\n/);
+  lines.forEach((line, index) => {
+    for (const match of line.matchAll(/\[([^\]]+)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/g)) {
+      const raw = match[0];
+      const text = match[1];
+      const target = match[2];
+      if (raw === void 0 || text === void 0 || target === void 0) {
+        continue;
+      }
+      const link = {
+        text,
+        target,
+        raw,
+        line: index + 1
+      };
+      const title = match[3];
+      if (title !== void 0) {
+        link.title = title;
+      }
+      links.push(link);
+    }
+  });
+  return links;
+}
+function resolveOkfLinkTarget(target, fromBundlePath) {
+  if (target.startsWith("http://") || target.startsWith("https://") || target.startsWith("#")) {
+    return void 0;
+  }
+  const withoutFragment = target.split("#", 1)[0] ?? "";
+  if (withoutFragment.length === 0 || !withoutFragment.endsWith(".md")) {
+    return void 0;
+  }
+  if (withoutFragment.startsWith("/")) {
+    return conceptIdFromPath(withoutFragment.slice(1));
+  }
+  if (withoutFragment.startsWith("wiki/")) {
+    return conceptIdFromPath(withoutFragment);
+  }
+  const normalized = path3.posix.normalize(
+    path3.posix.join(path3.posix.dirname(fromBundlePath), withoutFragment)
+  );
+  if (normalized.startsWith("../")) {
+    return void 0;
+  }
+  return conceptIdFromPath(normalized);
+}
+
+// src/graph/index.ts
+var GRAPH_WRITE_FAILED = "GRAPH_WRITE_FAILED";
+var GraphWorkspaceError = class extends Error {
+  constructor(message, code, details = {}) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "GraphWorkspaceError";
+  }
+  code;
+  details;
+};
+async function buildWorkspaceGraph(options) {
+  const workspaceRoot = path4.resolve(options.workspaceRoot);
+  const config = await loadWorkspaceConfig(workspaceRoot);
+  const scanResult = await scanConcepts(workspaceRoot, config);
+  const nodes = scanResult.files.filter((file) => !file.isReserved).map(graphNodeFromFile);
+  const nodeIds = new Set(nodes.map((node) => node.id));
+  const { edges, missingTargets, issues } = graphEdgesFromFiles(
+    scanResult.files.filter((file) => !file.isReserved),
+    nodeIds
+  );
+  const backlinks = backlinksFromEdges(edges);
+  const backlinksPath = path4.join(workspaceRoot, ".okfh/backlinks.json");
+  const htmlPath = path4.join(workspaceRoot, ".okfh/reports/graph.html");
+  const data = {
+    generatedAt: (options.now ?? /* @__PURE__ */ new Date()).toISOString(),
+    workspaceRoot,
+    nodes,
+    edges,
+    backlinks,
+    issues,
+    missingTargets
+  };
+  try {
+    await mkdir(path4.dirname(backlinksPath), { recursive: true });
+    await mkdir(path4.dirname(htmlPath), { recursive: true });
+    await writeFile(backlinksPath, `${JSON.stringify(data, null, 2)}
+`, "utf8");
+    await writeFile(htmlPath, renderGraphHtml(data), "utf8");
+  } catch (error) {
+    throw new GraphWorkspaceError(
+      error instanceof Error ? error.message : "Could not write graph artifacts.",
+      GRAPH_WRITE_FAILED,
+      { backlinksPath, htmlPath }
+    );
+  }
+  return {
+    workspaceRoot,
+    report: {
+      backlinksPath,
+      htmlPath
+    },
+    stats: {
+      nodes: nodes.length,
+      conceptEdges: edges.filter((edge) => edge.kind === "link").length,
+      evidenceEdges: edges.filter((edge) => edge.kind === "citation").length,
+      missingTargets: missingTargets.length
+    },
+    issues,
+    missingTargets
+  };
+}
+function graphNodeFromFile(file) {
+  return {
+    id: file.conceptId,
+    path: file.workspacePath,
+    title: file.frontmatter.ok ? stringValue2(file.frontmatter.data.title) ?? firstHeading(file.markdown) ?? file.conceptId : firstHeading(file.markdown) ?? file.conceptId,
+    type: file.frontmatter.ok ? stringValue2(file.frontmatter.data.type) ?? "Unknown" : "Unknown",
+    tags: file.frontmatter.ok ? stringArrayValue2(file.frontmatter.data.tags) : []
+  };
+}
+function graphEdgesFromFiles(files, nodeIds) {
+  const edges = /* @__PURE__ */ new Map();
+  const missingTargets = [];
+  const issues = [];
+  for (const file of files) {
+    const body = file.frontmatter.ok ? file.frontmatter.body : stripFrontmatterFence(file.markdown);
+    const targets = [
+      ...parseMarkdownLinks(body).map((link) => ({ target: link.target, kind: "link" })),
+      ...bareReferenceTargets(body).map((target) => ({ target, kind: "citation" }))
+    ];
+    for (const target of targets) {
+      const conceptId = resolveOkfLinkTarget(target.target, file.bundlePath);
+      if (conceptId === void 0) {
+        continue;
+      }
+      if (!nodeIds.has(conceptId)) {
+        missingTargets.push({
+          from: file.conceptId,
+          target: target.target,
+          path: file.workspacePath
+        });
+        issues.push({
+          code: "MISSING_TARGET",
+          path: file.workspacePath,
+          message: `Graph link target does not exist: ${target.target}`
+        });
+        continue;
+      }
+      if (conceptId === file.conceptId) {
+        continue;
+      }
+      const edge = {
+        from: file.conceptId,
+        to: conceptId,
+        kind: target.kind
+      };
+      edges.set(`${edge.from}\0${edge.to}\0${edge.kind}`, edge);
+    }
+  }
+  return {
+    edges: [...edges.values()].sort(
+      (left, right) => left.from.localeCompare(right.from) || left.to.localeCompare(right.to) || left.kind.localeCompare(right.kind)
+    ),
+    missingTargets,
+    issues
+  };
+}
+function bareReferenceTargets(markdown) {
+  return [...markdown.matchAll(/(^|\s)(\/?(?:wiki\/)?references\/[^\s)]+\.md)\b/gm)].map((match) => match[2]).filter((target) => target !== void 0);
+}
+function backlinksFromEdges(edges) {
+  const backlinks = {};
+  for (const edge of edges) {
+    backlinks[edge.to] = [...backlinks[edge.to] ?? [], edge.from].sort();
+  }
+  return backlinks;
+}
+function renderGraphHtml(data) {
+  const safeJson = JSON.stringify({
+    nodes: data.nodes,
+    edges: data.edges,
+    issues: data.issues,
+    missingTargets: data.missingTargets
+  }).replace(/</g, "\\u003c");
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>OKF Harness Graph</title>
+<style>
+body { margin: 0; font: 14px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; color: #172026; background: #f7f8f5; }
+header { display: flex; gap: 12px; align-items: center; padding: 14px 18px; border-bottom: 1px solid #d8ddd2; background: #ffffff; }
+h1 { font-size: 16px; margin: 0; }
+input, select { font: inherit; padding: 6px 8px; border: 1px solid #bac3b4; border-radius: 6px; background: #fff; }
+main { display: grid; grid-template-columns: minmax(0, 1fr) 320px; min-height: calc(100vh - 58px); }
+svg { width: 100%; height: calc(100vh - 58px); background: #f7f8f5; }
+aside { border-left: 1px solid #d8ddd2; padding: 16px; background: #ffffff; overflow: auto; }
+.node { cursor: pointer; }
+.edge { stroke: #83907b; stroke-width: 1.4; opacity: .75; }
+.node circle { fill: #2f6f73; stroke: #fff; stroke-width: 2; }
+.node.reference circle { fill: #8b5e34; }
+.node text { paint-order: stroke; stroke: #f7f8f5; stroke-width: 4; fill: #172026; font-size: 12px; }
+.muted { color: #667064; }
+@media (max-width: 760px) { main { grid-template-columns: 1fr; } aside { border-left: 0; border-top: 1px solid #d8ddd2; } svg { height: 62vh; } }
+</style>
+</head>
+<body>
+<header>
+<h1>OKF Harness Graph</h1>
+<input id="search" type="search" placeholder="Search nodes" aria-label="Search nodes">
+<select id="type" aria-label="Filter by type"><option value="">All types</option></select>
+</header>
+<main>
+<svg id="graph" role="img" aria-label="OKF concept graph"></svg>
+<aside id="details"><p class="muted">Select a node to inspect links and metadata.</p></aside>
+</main>
+<script>
+const graph = ${safeJson};
+const svg = document.querySelector("#graph");
+const details = document.querySelector("#details");
+const search = document.querySelector("#search");
+const type = document.querySelector("#type");
+const types = [...new Set(graph.nodes.map((node) => node.type))].sort();
+for (const item of types) {
+  const option = document.createElement("option");
+  option.value = item;
+  option.textContent = item;
+  type.appendChild(option);
+}
+function visibleNodes() {
+  const q = search.value.trim().toLowerCase();
+  return graph.nodes.filter((node) => {
+    const matchesType = !type.value || node.type === type.value;
+    const haystack = [node.id, node.title, node.path, node.type].join(" ").toLowerCase();
+    return matchesType && (!q || haystack.includes(q));
+  });
+}
+function render() {
+  const nodes = visibleNodes();
+  const ids = new Set(nodes.map((node) => node.id));
+  const edges = graph.edges.filter((edge) => ids.has(edge.from) && ids.has(edge.to));
+  const width = svg.clientWidth || 900;
+  const height = svg.clientHeight || 620;
+  const radius = Math.max(120, Math.min(width, height) * 0.34);
+  const cx = width / 2;
+  const cy = height / 2;
+  const positioned = nodes.map((node, index) => {
+    const angle = nodes.length <= 1 ? 0 : (Math.PI * 2 * index) / nodes.length - Math.PI / 2;
+    return { ...node, x: cx + Math.cos(angle) * radius, y: cy + Math.sin(angle) * radius };
+  });
+  const byId = new Map(positioned.map((node) => [node.id, node]));
+  svg.replaceChildren();
+  for (const edge of edges) {
+    const from = byId.get(edge.from);
+    const to = byId.get(edge.to);
+    if (!from || !to) continue;
+    const line = document.createElementNS("http://www.w3.org/2000/svg", "line");
+    line.setAttribute("class", "edge");
+    line.setAttribute("x1", from.x);
+    line.setAttribute("y1", from.y);
+    line.setAttribute("x2", to.x);
+    line.setAttribute("y2", to.y);
+    svg.appendChild(line);
+  }
+  for (const node of positioned) {
+    const group = document.createElementNS("http://www.w3.org/2000/svg", "g");
+    group.setAttribute("class", "node " + node.type.toLowerCase());
+    group.addEventListener("click", () => showDetails(node));
+    const circle = document.createElementNS("http://www.w3.org/2000/svg", "circle");
+    circle.setAttribute("cx", node.x);
+    circle.setAttribute("cy", node.y);
+    circle.setAttribute("r", "18");
+    const label = document.createElementNS("http://www.w3.org/2000/svg", "text");
+    label.setAttribute("x", node.x + 24);
+    label.setAttribute("y", node.y + 4);
+    label.textContent = node.title;
+    group.append(circle, label);
+    svg.appendChild(group);
+  }
+}
+function showDetails(node) {
+  const outgoing = graph.edges.filter((edge) => edge.from === node.id);
+  const incoming = graph.edges.filter((edge) => edge.to === node.id);
+  details.innerHTML = [
+    "<h2>" + escapeHtml(node.title) + "</h2>",
+    "<p><strong>Path:</strong> " + escapeHtml(node.path) + "</p>",
+    "<p><strong>Type:</strong> " + escapeHtml(node.type) + "</p>",
+    "<p><strong>Tags:</strong> " + escapeHtml(node.tags.join(", ")) + "</p>",
+    "<h3>Outgoing</h3>",
+    listEdges(outgoing, "to"),
+    "<h3>Backlinks</h3>",
+    listEdges(incoming, "from")
+  ].join("");
+}
+function listEdges(edges, key) {
+  if (edges.length === 0) return '<p class="muted">None</p>';
+  return "<ul>" + edges.map((edge) => "<li>" + escapeHtml(edge[key]) + " <span class=\\"muted\\">" + edge.kind + "</span></li>").join("") + "</ul>";
+}
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#039;" }[char]));
+}
+search.addEventListener("input", render);
+type.addEventListener("change", render);
+addEventListener("resize", render);
+render();
+</script>
+</body>
+</html>
+`;
+}
+function firstHeading(markdown) {
+  return /^#\s+(.+?)\s*$/m.exec(markdown)?.[1];
+}
+function stripFrontmatterFence(markdown) {
+  if (!markdown.startsWith("---")) {
+    return markdown;
+  }
+  const end = markdown.indexOf("\n---", 3);
+  return end === -1 ? markdown : markdown.slice(end + "\n---".length);
+}
+function stringValue2(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function stringArrayValue2(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+
+// src/lint/index.ts
+import { createHash as createHash2 } from "crypto";
+import { readdir as readdir2, readFile as readFile4 } from "fs/promises";
+import path6 from "path";
+
+// src/source/index.ts
+import { createHash } from "crypto";
+import { access, appendFile, mkdir as mkdir2, readFile as readFile3, rm, stat, writeFile as writeFile2 } from "fs/promises";
+import path5 from "path";
+var MANIFEST_INVALID = "MANIFEST_INVALID";
+var SOURCE_REGISTRATION_FAILED = "SOURCE_REGISTRATION_FAILED";
+var SOURCE_INPUT_NOT_FOUND = "SOURCE_INPUT_NOT_FOUND";
+var SOURCE_INPUT_UNSUPPORTED = "SOURCE_INPUT_UNSUPPORTED";
+var SOURCE_NOT_REGISTERED = "SOURCE_NOT_REGISTERED";
+var SourceManagementError = class extends Error {
+  constructor(message, code, workspaceRoot) {
+    super(message);
+    this.code = code;
+    this.workspaceRoot = workspaceRoot;
+    this.name = "SourceManagementError";
+  }
+  code;
+  workspaceRoot;
+};
+async function addSource(options) {
+  const workspaceRoot = path5.resolve(options.workspaceRoot);
+  const config = await loadWorkspaceConfig(workspaceRoot);
+  const manifest = await readSourceManifest(workspaceRoot, config);
+  if (manifest.issues.length > 0) {
+    throw new SourceManagementError("Source manifest contains invalid rows.", MANIFEST_INVALID);
+  }
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const url = parseHttpUrl(options.input);
+  if (url !== void 0) {
+    return addUrlSource({
+      workspaceRoot,
+      config,
+      input: options.input,
+      url,
+      now,
+      options,
+      manifest
+    });
+  }
+  return addFileSource({ workspaceRoot, config, input: options.input, now, options, manifest });
+}
+async function listSources(options) {
+  const workspaceRoot = path5.resolve(options.workspaceRoot);
+  const config = await loadWorkspaceConfig(workspaceRoot);
+  const manifest = await readSourceManifest(workspaceRoot, config);
+  if (manifest.issues.length > 0) {
+    throw new SourceManagementError("Source manifest contains invalid rows.", MANIFEST_INVALID);
+  }
+  return {
+    workspaceRoot,
+    sources: manifest.entries
+  };
+}
+async function createIngestPlan(options) {
+  const workspaceRoot = path5.resolve(options.workspaceRoot);
+  const config = await loadWorkspaceConfig(workspaceRoot);
+  const manifest = await readSourceManifest(workspaceRoot, config);
+  if (manifest.issues.length > 0) {
+    throw new SourceManagementError("Source manifest contains invalid rows.", MANIFEST_INVALID);
+  }
+  const source = findRegisteredSource(manifest.entries, options.source);
+  if (source === void 0) {
+    throw new SourceManagementError(
+      `Source is not registered: ${options.source}`,
+      SOURCE_NOT_REGISTERED,
+      workspaceRoot
+    );
+  }
+  const scanResult = await scanConcepts(workspaceRoot, config);
+  const sourceTokens = tokenizeSourceMetadata(source);
+  const candidateConcepts = scanResult.concepts.filter((concept) => !concept.id.startsWith("references/")).map((concept) => {
+    const conceptTokens = tokenize([
+      concept.id,
+      concept.title ?? "",
+      concept.type,
+      concept.tags.join(" ")
+    ]);
+    const matches = [...sourceTokens].filter((token) => conceptTokens.has(token));
+    return {
+      concept,
+      matches
+    };
+  }).filter((candidate) => candidate.matches.length > 0).map(({ concept, matches }) => {
+    const candidate = {
+      id: concept.id,
+      path: concept.workspacePath,
+      type: concept.type,
+      score: matches.length,
+      reason: `metadata token match: ${matches.sort().join(", ")}`
+    };
+    if (concept.title !== void 0) {
+      candidate.title = concept.title;
+    }
+    return candidate;
+  }).sort((left, right) => right.score - left.score || left.id.localeCompare(right.id)).slice(0, 10);
+  const recommendedReferencePath = source.reference_concept ?? `wiki/references/${safeSlug(referenceTitle(source)) || source.id}.md`;
+  return {
+    workspaceRoot,
+    source,
+    recommendedReferencePath,
+    candidateConcepts,
+    checklist: [
+      `Read the full registered source at ${source.path} before writing wiki content.`,
+      `Create or update exactly one reference document at ${recommendedReferencePath}.`,
+      "Update only affected topic, entity, project, decision, or question concept documents.",
+      "Preserve uncertainty and contradictions; do not invent claims or citations.",
+      "Run okfh lint --workspace <workspace> --json after wiki edits."
+    ]
+  };
+}
+async function readSourceManifest(workspaceRootInput, config) {
+  const workspaceRoot = path5.resolve(workspaceRootInput);
+  const workspaceConfig = config ?? await loadWorkspaceConfig(workspaceRoot);
+  const manifestPath = path5.join(workspaceRoot, workspaceConfig.paths.manifest);
+  let source = "";
+  try {
+    source = await readFile3(manifestPath, "utf8");
+  } catch (error) {
+    if (errorCode2(error) !== "ENOENT") {
+      throw error;
+    }
+  }
+  const entries = [];
+  const issues = [];
+  const lines = source.split(/\r?\n/);
+  lines.forEach((line, index) => {
+    if (line.trim().length === 0) {
+      return;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch (error) {
+      issues.push({
+        code: MANIFEST_INVALID,
+        path: workspaceConfig.paths.manifest,
+        line: index + 1,
+        message: error instanceof Error ? error.message : "Invalid manifest JSON row."
+      });
+      return;
+    }
+    const entry = parseManifestEntry(parsed, workspaceConfig);
+    if (entry.ok) {
+      entries.push(entry.entry);
+      return;
+    }
+    issues.push({
+      code: MANIFEST_INVALID,
+      path: workspaceConfig.paths.manifest,
+      line: index + 1,
+      message: entry.message
+    });
+  });
+  return { entries, issues };
+}
+async function addFileSource(context) {
+  const sourcePath = path5.resolve(context.input);
+  let sourceStat;
+  try {
+    sourceStat = await stat(sourcePath);
+  } catch (error) {
+    if (errorCode2(error) === "ENOENT") {
+      throw new SourceManagementError(
+        `Source file does not exist: ${context.input}`,
+        SOURCE_INPUT_NOT_FOUND,
+        context.workspaceRoot
+      );
+    }
+    throw error;
+  }
+  if (!sourceStat.isFile()) {
+    throw new SourceManagementError(
+      "Source add supports ordinary files and URLs only.",
+      SOURCE_INPUT_UNSUPPORTED,
+      context.workspaceRoot
+    );
+  }
+  const contents = await readFile3(sourcePath);
+  const sha256 = sha256Hex(contents);
+  const existing = context.manifest.entries.find(
+    (entry2) => entry2.kind === "file" && entry2.sha256 === sha256
+  );
+  if (existing !== void 0) {
+    return {
+      workspaceRoot: context.workspaceRoot,
+      input: context.input,
+      action: "reused",
+      dryRun: context.options.dryRun === true,
+      source: existing
+    };
+  }
+  const original = path5.basename(sourcePath);
+  const rawPath = await nextRawSourcePath({
+    workspaceRoot: context.workspaceRoot,
+    config: context.config,
+    now: context.now,
+    original,
+    extension: path5.extname(original),
+    entries: context.manifest.entries
+  });
+  const entry = {
+    id: nextSourceId(context.manifest.entries, context.now),
+    kind: "file",
+    original,
+    path: rawPath,
+    sha256,
+    added_at: context.now.toISOString(),
+    status: "registered",
+    mime: mimeFromFilename(original),
+    title: titleFromFilename(original)
+  };
+  if (context.options.dryRun === true) {
+    return {
+      workspaceRoot: context.workspaceRoot,
+      input: context.input,
+      action: "planned",
+      dryRun: true,
+      source: entry
+    };
+  }
+  const absoluteRawPath = path5.join(context.workspaceRoot, entry.path);
+  await mkdir2(path5.dirname(absoluteRawPath), { recursive: true });
+  await writeFile2(absoluteRawPath, contents, { flag: "wx" });
+  try {
+    await appendManifestEntry(context.workspaceRoot, context.config, entry);
+  } catch (error) {
+    await rm(absoluteRawPath, { force: true });
+    throw new SourceManagementError(
+      error instanceof Error ? error.message : "Could not append source manifest entry.",
+      SOURCE_REGISTRATION_FAILED,
+      context.workspaceRoot
+    );
+  }
+  return {
+    workspaceRoot: context.workspaceRoot,
+    input: context.input,
+    action: "registered",
+    dryRun: false,
+    source: entry
+  };
+}
+async function addUrlSource(context) {
+  const original = context.url.href;
+  const existing = context.manifest.entries.find(
+    (entry2) => entry2.kind === "url" && entry2.original === original
+  );
+  if (existing !== void 0) {
+    return {
+      workspaceRoot: context.workspaceRoot,
+      input: context.input,
+      action: "reused",
+      dryRun: context.options.dryRun === true,
+      source: existing
+    };
+  }
+  const metadata = urlMetadataContents(original, context.now);
+  const rawPath = await nextRawSourcePath({
+    workspaceRoot: context.workspaceRoot,
+    config: context.config,
+    now: context.now,
+    original: urlSlugSource(context.url),
+    extension: ".url.md",
+    entries: context.manifest.entries
+  });
+  const entry = {
+    id: nextSourceId(context.manifest.entries, context.now),
+    kind: "url",
+    original,
+    path: rawPath,
+    sha256: sha256Hex(metadata),
+    added_at: context.now.toISOString(),
+    status: "registered",
+    mime: "text/markdown",
+    title: titleFromUrl(context.url)
+  };
+  if (context.options.dryRun === true) {
+    return {
+      workspaceRoot: context.workspaceRoot,
+      input: context.input,
+      action: "planned",
+      dryRun: true,
+      source: entry
+    };
+  }
+  const absoluteRawPath = path5.join(context.workspaceRoot, entry.path);
+  await mkdir2(path5.dirname(absoluteRawPath), { recursive: true });
+  await writeFile2(absoluteRawPath, metadata, { flag: "wx" });
+  try {
+    await appendManifestEntry(context.workspaceRoot, context.config, entry);
+  } catch (error) {
+    await rm(absoluteRawPath, { force: true });
+    throw new SourceManagementError(
+      error instanceof Error ? error.message : "Could not append source manifest entry.",
+      SOURCE_REGISTRATION_FAILED,
+      context.workspaceRoot
+    );
+  }
+  return {
+    workspaceRoot: context.workspaceRoot,
+    input: context.input,
+    action: "registered",
+    dryRun: false,
+    source: entry
+  };
+}
+async function appendManifestEntry(workspaceRoot, config, entry) {
+  const manifestPath = path5.join(workspaceRoot, config.paths.manifest);
+  await mkdir2(path5.dirname(manifestPath), { recursive: true });
+  await appendFile(manifestPath, `${JSON.stringify(entry)}
+`, "utf8");
+}
+async function nextRawSourcePath(options) {
+  const dateParts = sourceDateParts(options.now);
+  const directory = `${options.config.paths.raw_sources}/${dateParts.year}/${dateParts.month}`;
+  const extension = options.extension.length > 0 ? options.extension.toLowerCase() : "";
+  const stem = extension.length > 0 && options.original.toLowerCase().endsWith(extension) ? options.original.slice(0, -extension.length) : options.original;
+  const slug = safeSlug(stem) || "source";
+  const registeredPaths = new Set(options.entries.map((entry) => entry.path));
+  for (let suffix = 1; ; suffix += 1) {
+    const suffixText = suffix === 1 ? "" : `-${suffix}`;
+    const candidate = `${directory}/${slug}${suffixText}${extension}`;
+    if (registeredPaths.has(candidate)) {
+      continue;
+    }
+    if (!await pathExists(path5.join(options.workspaceRoot, candidate))) {
+      return candidate;
+    }
+  }
+}
+function parseManifestEntry(value, config) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { ok: false, message: "Manifest row must be a JSON object." };
+  }
+  const row = value;
+  const requiredStringFields = ["id", "kind", "original", "path", "sha256", "added_at", "status"];
+  for (const field of requiredStringFields) {
+    if (typeof row[field] !== "string" || row[field].trim().length === 0) {
+      return { ok: false, message: `Manifest row is missing a non-empty ${field} field.` };
+    }
+  }
+  if (row.kind !== "file" && row.kind !== "url") {
+    return { ok: false, message: "Manifest kind must be file or url." };
+  }
+  if (row.status !== "registered") {
+    return { ok: false, message: "Manifest status must be registered." };
+  }
+  if (!/^src_\d{8}_\d{4}$/.test(String(row.id))) {
+    return { ok: false, message: "Manifest source id must match src_YYYYMMDD_NNNN." };
+  }
+  if (!/^[a-f0-9]{64}$/.test(String(row.sha256))) {
+    return { ok: false, message: "Manifest sha256 must be a lowercase hex digest." };
+  }
+  if (!isSafeRawSourcePath(String(row.path), config)) {
+    return { ok: false, message: "Manifest path must be a safe raw source relative path." };
+  }
+  const entry = {
+    id: String(row.id),
+    kind: row.kind,
+    original: String(row.original),
+    path: toPosixPath(String(row.path)),
+    sha256: String(row.sha256),
+    added_at: String(row.added_at),
+    status: "registered"
+  };
+  for (const optional of ["mime", "title", "reference_concept", "notes"]) {
+    if (typeof row[optional] === "string" && row[optional].trim().length > 0) {
+      entry[optional] = String(row[optional]);
+    }
+  }
+  return { ok: true, entry };
+}
+function isSafeRawSourcePath(input, config) {
+  const rawPath = toPosixPath(input);
+  if (rawPath.startsWith("/") || rawPath.includes("\\") || rawPath.includes("\0")) {
+    return false;
+  }
+  const segments = rawPath.split("/");
+  if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+    return false;
+  }
+  return rawPath === config.paths.raw_sources || rawPath.startsWith(`${config.paths.raw_sources}/`);
+}
+function parseHttpUrl(input) {
+  try {
+    const url = new URL(input);
+    return url.protocol === "http:" || url.protocol === "https:" ? url : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function findRegisteredSource(entries, sourceInput) {
+  const normalizedInput = toPosixPath(sourceInput);
+  return entries.find(
+    (entry) => entry.id === sourceInput || entry.path === normalizedInput || path5.posix.basename(entry.path) === normalizedInput
+  );
+}
+function tokenizeSourceMetadata(source) {
+  return tokenize([source.id, source.original, source.path, source.title ?? ""]);
+}
+function tokenize(values) {
+  return new Set(
+    values.join(" ").normalize("NFKD").toLowerCase().replace(/[\u0300-\u036f]/g, "").split(/[^\p{Letter}\p{Number}]+/u).filter((token) => token.length >= 3 && !metadataStopWords.has(token))
+  );
+}
+function referenceTitle(source) {
+  if (source.title !== void 0) {
+    return source.title;
+  }
+  if (source.kind === "file") {
+    return titleFromFilename(source.original);
+  }
+  return titleFromUrl(new URL(source.original));
+}
+function sourceDateParts(now) {
+  const [date] = now.toISOString().split("T");
+  if (date === void 0) {
+    throw new Error("Could not derive source date.");
+  }
+  const [year, month] = date.split("-");
+  if (year === void 0 || month === void 0) {
+    throw new Error("Could not derive source date parts.");
+  }
+  return { year, month, date: date.replace(/-/g, "") };
+}
+var metadataStopWords = /* @__PURE__ */ new Set([
+  "raw",
+  "sources",
+  "source",
+  "http",
+  "https",
+  "www",
+  "com",
+  "org",
+  "net"
+]);
+function nextSourceId(entries, now) {
+  const { date } = sourceDateParts(now);
+  const maxSequence = entries.reduce((max, entry) => {
+    const match = new RegExp(`^src_${date}_(\\d{4})$`).exec(entry.id);
+    if (match?.[1] === void 0) {
+      return max;
+    }
+    return Math.max(max, Number(match[1]));
+  }, 0);
+  return `src_${date}_${String(maxSequence + 1).padStart(4, "0")}`;
+}
+function safeSlug(input) {
+  return input.normalize("NFKD").toLowerCase().replace(/[\u0300-\u036f]/g, "").replace(/[^\p{Letter}\p{Number}]+/gu, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-").slice(0, 80).replace(/-+$/g, "");
+}
+function titleFromFilename(filename) {
+  const extension = path5.extname(filename);
+  const stem = extension.length > 0 ? filename.slice(0, -extension.length) : filename;
+  return stem.trim().length > 0 ? stem : filename;
+}
+function urlSlugSource(url) {
+  const pathname = url.pathname.split("/").filter(Boolean).join("-");
+  return pathname.length > 0 ? `${url.hostname}-${pathname}` : url.hostname;
+}
+function titleFromUrl(url) {
+  const pathname = url.pathname.split("/").filter(Boolean).at(-1);
+  return pathname !== void 0 && pathname.length > 0 ? pathname : url.hostname;
+}
+function urlMetadataContents(url, now) {
+  return `# URL Source
+
+URL: ${url}
+Registered at: ${now.toISOString()}
+`;
+}
+function sha256Hex(contents) {
+  return createHash("sha256").update(contents).digest("hex");
+}
+function mimeFromFilename(filename) {
+  switch (path5.extname(filename).toLowerCase()) {
+    case ".md":
+    case ".markdown":
+      return "text/markdown";
+    case ".txt":
+      return "text/plain";
+    case ".pdf":
+      return "application/pdf";
+    case ".html":
+    case ".htm":
+      return "text/html";
+    case ".json":
+      return "application/json";
+    default:
+      return "application/octet-stream";
+  }
+}
+async function pathExists(input) {
+  try {
+    await access(input);
+    return true;
+  } catch (error) {
+    if (errorCode2(error) === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+function errorCode2(error) {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return void 0;
+  }
+  const code = error.code;
+  return typeof code === "string" ? code : void 0;
+}
+
+// src/lint/index.ts
+var OKF_MISSING_FRONTMATTER = "OKF_MISSING_FRONTMATTER";
+var OKF_INVALID_FRONTMATTER = "OKF_INVALID_FRONTMATTER";
+var OKF_MISSING_TYPE = "OKF_MISSING_TYPE";
+var RESERVED_FILE_HAS_CONCEPT_FRONTMATTER = "RESERVED_FILE_HAS_CONCEPT_FRONTMATTER";
+var LOG_INVALID_DATE_HEADING = "LOG_INVALID_DATE_HEADING";
+var SOURCE_HASH_DRIFT = "SOURCE_HASH_DRIFT";
+var SOURCE_MISSING = "SOURCE_MISSING";
+var REFERENCE_SOURCE_MISSING = "REFERENCE_SOURCE_MISSING";
+var BROKEN_LINK = "BROKEN_LINK";
+var MISSING_INDEX_ENTRY = "MISSING_INDEX_ENTRY";
+var MISSING_CITATIONS_SECTION = "MISSING_CITATIONS_SECTION";
+async function lintWorkspace(workspaceRoot) {
+  const configResult = await readWorkspaceConfig(workspaceRoot);
+  if (!configResult.ok) {
+    return {
+      ok: false,
+      issues: configResult.issues.map((issue) => ({
+        code: CONFIG_INVALID,
+        severity: "error",
+        message: issue.message,
+        path: issue.path
+      }))
+    };
+  }
+  try {
+    const scanResult = await scanConcepts(workspaceRoot, configResult.config);
+    const sourceManifest = await readSourceManifest(workspaceRoot, configResult.config);
+    const sourceIssues = sourceManifest.issues.length === 0 ? [
+      ...await lintRegisteredSources(workspaceRoot, sourceManifest.entries),
+      ...lintReferenceSourceIds(scanResult.files, sourceManifest.entries),
+      ...await lintUnregisteredRawSources(
+        workspaceRoot,
+        configResult.config.paths.raw_sources,
+        sourceManifest.entries
+      )
+    ] : [];
+    const issues = [
+      ...scanResult.files.flatMap((file) => lintMarkdownFile(file)),
+      ...lintWikiWarnings(scanResult.files),
+      ...sourceManifest.issues.map(
+        (issue) => ({
+          code: issue.code,
+          severity: "error",
+          path: issue.path,
+          line: issue.line,
+          message: issue.message
+        })
+      ),
+      ...sourceIssues
+    ];
+    return {
+      ok: issues.every((issue) => issue.severity !== "error"),
+      issues
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      issues: [
+        {
+          code: CONFIG_INVALID,
+          severity: "error",
+          path: configResult.config.okf.bundle_root,
+          message: error instanceof Error ? error.message : "Could not scan OKF wiki."
+        }
+      ]
+    };
+  }
+}
+function lintReferenceSourceIds(files, entries) {
+  const sourceIds = new Set(entries.map((entry) => entry.id));
+  return files.flatMap((file) => {
+    if (file.isReserved || !file.workspacePath.startsWith("wiki/references/")) {
+      return [];
+    }
+    if (!file.frontmatter.ok) {
+      return [];
+    }
+    const sourceId = frontmatterSourceId(file.frontmatter.data);
+    if (sourceId === void 0 || sourceIds.has(sourceId)) {
+      return [];
+    }
+    return [
+      {
+        code: REFERENCE_SOURCE_MISSING,
+        severity: "error",
+        path: file.workspacePath,
+        message: `Reference document points to an unregistered source id: ${sourceId}`
+      }
+    ];
+  });
+}
+async function lintUnregisteredRawSources(workspaceRoot, rawSourcesPath, entries) {
+  const rawRoot = path6.join(workspaceRoot, rawSourcesPath);
+  const registeredPaths = new Set(entries.map((entry) => entry.path));
+  const files = await scanRawSourceFiles(rawRoot);
+  return files.flatMap((filePath) => {
+    const workspacePath = path6.relative(workspaceRoot, filePath).split(path6.sep).join(path6.posix.sep);
+    if (registeredPaths.has(workspacePath) || isIgnoredRawSourceFile(workspacePath)) {
+      return [];
+    }
+    return [
+      {
+        code: "UNREGISTERED_RAW_SOURCE",
+        severity: "warning",
+        path: workspacePath,
+        message: `Raw source file is not registered in the manifest: ${workspacePath}`
+      }
+    ];
+  });
+}
+async function scanRawSourceFiles(root) {
+  let entries;
+  try {
+    entries = await readdir2(root, { withFileTypes: true });
+  } catch (error) {
+    if (errorCode3(error) === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const entryPath = path6.join(root, entry.name);
+      if (entry.isDirectory()) {
+        return scanRawSourceFiles(entryPath);
+      }
+      return entry.isFile() ? [entryPath] : [];
+    })
+  );
+  return nested.flat();
+}
+function isIgnoredRawSourceFile(workspacePath) {
+  return workspacePath === "raw/sources/README.md" || workspacePath.endsWith("/.gitkeep");
+}
+function frontmatterSourceId(frontmatter) {
+  const okfh = frontmatter.okfh;
+  if (typeof okfh !== "object" || okfh === null || Array.isArray(okfh)) {
+    return void 0;
+  }
+  const sourceId = okfh.source_id;
+  return typeof sourceId === "string" && sourceId.trim().length > 0 ? sourceId : void 0;
+}
+async function lintRegisteredSources(workspaceRoot, entries) {
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const absolutePath = path6.join(workspaceRoot, entry.path);
+      let contents;
+      try {
+        contents = await readFile4(absolutePath);
+      } catch (error) {
+        if (errorCode3(error) === "ENOENT") {
+          return [
+            {
+              code: SOURCE_MISSING,
+              severity: "error",
+              path: entry.path,
+              message: `Registered source is missing: ${entry.path}`
+            }
+          ];
+        }
+        throw error;
+      }
+      const actual = createHash2("sha256").update(contents).digest("hex");
+      if (actual === entry.sha256) {
+        return [];
+      }
+      return [
+        {
+          code: SOURCE_HASH_DRIFT,
+          severity: "error",
+          path: entry.path,
+          message: `Registered source hash changed: ${entry.path}`
+        }
+      ];
+    })
+  );
+  return nested.flat();
+}
+function lintMarkdownFile(file) {
+  const issues = [];
+  if (file.frontmatter.ok && file.isReserved && hasFrontmatterData(file)) {
+    issues.push({
+      code: RESERVED_FILE_HAS_CONCEPT_FRONTMATTER,
+      severity: "error",
+      path: file.workspacePath,
+      message: `${file.bundlePath} is reserved and must not define concept frontmatter.`
+    });
+  }
+  if (!file.frontmatter.ok && file.frontmatter.hasFrontmatter) {
+    issues.push({
+      code: OKF_INVALID_FRONTMATTER,
+      severity: "error",
+      path: file.workspacePath,
+      message: file.frontmatter.message
+    });
+  }
+  if (!file.isReserved) {
+    if (!file.frontmatter.ok && !file.frontmatter.hasFrontmatter) {
+      issues.push({
+        code: OKF_MISSING_FRONTMATTER,
+        severity: "error",
+        path: file.workspacePath,
+        message: `${file.bundlePath} is missing YAML frontmatter.`
+      });
+    }
+    if (file.frontmatter.ok && !hasNonEmptyType(file.frontmatter.data.type)) {
+      issues.push({
+        code: OKF_MISSING_TYPE,
+        severity: "error",
+        path: file.workspacePath,
+        message: `${file.bundlePath} is missing a non-empty type field.`
+      });
+    }
+  }
+  if (file.bundlePath.split("/").at(-1) === "log.md") {
+    issues.push(...lintLogDateHeadings(file));
+  }
+  return issues;
+}
+function lintWikiWarnings(files) {
+  const existingConceptIds = new Set(files.map((file) => file.conceptId));
+  const indexedConceptIds = indexMentionedConceptIds(files);
+  return [
+    ...lintBrokenLinks(files, existingConceptIds),
+    ...lintMissingIndexEntries(files, indexedConceptIds),
+    ...lintMissingCitationSections(files)
+  ];
+}
+function lintBrokenLinks(files, existingConceptIds) {
+  return files.flatMap(
+    (file) => parseMarkdownLinks(file.markdown).flatMap((link) => {
+      const conceptId = resolveOkfLinkTarget(link.target, file.bundlePath);
+      if (conceptId === void 0 || existingConceptIds.has(conceptId)) {
+        return [];
+      }
+      return [
+        {
+          code: BROKEN_LINK,
+          severity: "warning",
+          path: file.workspacePath,
+          line: link.line,
+          message: `Markdown link target does not exist: ${link.target}`
+        }
+      ];
+    })
+  );
+}
+function lintMissingIndexEntries(files, indexedConceptIds) {
+  return files.flatMap((file) => {
+    if (file.isReserved || indexedConceptIds.has(file.conceptId)) {
+      return [];
+    }
+    return [
+      {
+        code: MISSING_INDEX_ENTRY,
+        severity: "warning",
+        path: file.workspacePath,
+        message: `Concept is not linked from a root or directory index: ${file.workspacePath}`
+      }
+    ];
+  });
+}
+function lintMissingCitationSections(files) {
+  return files.flatMap((file) => {
+    if (file.isReserved || !file.frontmatter.ok) {
+      return [];
+    }
+    const type = stringValue3(file.frontmatter.data.type)?.toLocaleLowerCase();
+    if (type === void 0 || !(/* @__PURE__ */ new Set(["topic", "entity", "project", "decision"])).has(type) || hasOkfhSources(file.frontmatter.data) || /^#\s+Citations\s*$/im.test(file.frontmatter.body)) {
+      return [];
+    }
+    return [
+      {
+        code: MISSING_CITATIONS_SECTION,
+        severity: "warning",
+        path: file.workspacePath,
+        message: `${file.bundlePath} should include # Citations or okfh.sources.`
+      }
+    ];
+  });
+}
+function indexMentionedConceptIds(files) {
+  const indexed = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    if (path6.posix.basename(file.bundlePath) !== "index.md") {
+      continue;
+    }
+    for (const link of parseMarkdownLinks(file.markdown)) {
+      const conceptId = resolveOkfLinkTarget(link.target, file.bundlePath);
+      if (conceptId !== void 0) {
+        indexed.add(conceptId);
+      }
+    }
+  }
+  return indexed;
+}
+function lintLogDateHeadings(file) {
+  return file.markdown.split(/\r?\n/).flatMap((line, index) => {
+    const heading = /^(#{2,6})\s+(.+?)\s*$/.exec(line);
+    if (heading === null) {
+      return [];
+    }
+    const headingText = heading[2];
+    if (headingText === void 0) {
+      return [];
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(headingText)) {
+      return [];
+    }
+    return [
+      {
+        code: LOG_INVALID_DATE_HEADING,
+        severity: "error",
+        path: file.workspacePath,
+        line: index + 1,
+        message: `Log heading must be YYYY-MM-DD: ${headingText}`
+      }
+    ];
+  });
+}
+function hasFrontmatterData(file) {
+  return file.frontmatter.ok && Object.keys(file.frontmatter.data).length > 0;
+}
+function hasNonEmptyType(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function stringValue3(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function hasOkfhSources(frontmatter) {
+  const okfh = frontmatter.okfh;
+  if (typeof okfh !== "object" || okfh === null || Array.isArray(okfh)) {
+    return false;
+  }
+  const sources = okfh.sources;
+  return Array.isArray(sources) && sources.length > 0;
+}
+function errorCode3(error) {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return void 0;
+  }
+  const code = error.code;
+  return typeof code === "string" ? code : void 0;
+}
+
+// src/read/index.ts
+import { readFile as readFile5 } from "fs/promises";
+import path7 from "path";
+import { TextDecoder } from "util";
+var INVALID_TARGET = "INVALID_TARGET";
+var TARGET_NOT_FOUND = "TARGET_NOT_FOUND";
+var AMBIGUOUS_SECTION = "AMBIGUOUS_SECTION";
+var READ_LIMIT_EXCEEDED = "READ_LIMIT_EXCEEDED";
+var NON_MARKDOWN_TARGET = "NON_MARKDOWN_TARGET";
+var NON_UTF8_TARGET = "NON_UTF8_TARGET";
+var ReadWorkspaceError = class extends Error {
+  constructor(message, code, details = {}) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "ReadWorkspaceError";
+  }
+  code;
+  details;
+};
+var defaultReadPreviewChars = 12e3;
+var maxFullReadChars = 1e5;
+async function readWorkspaceDocument(options) {
+  const workspaceRoot = path7.resolve(options.workspaceRoot);
+  const config = await loadWorkspaceConfig(workspaceRoot);
+  const [scanResult, sourceManifest] = await Promise.all([
+    scanConcepts(workspaceRoot, config),
+    readSourceManifest(workspaceRoot, config)
+  ]);
+  const file = resolveReadTarget(scanResult.files, options.target);
+  await assertUtf8Target(file);
+  const sourceEntries = new Map(sourceManifest.entries.map((entry) => [entry.id, entry]));
+  const conceptIds = new Set(
+    scanResult.files.filter((item) => !item.isReserved).map((item) => item.conceptId)
+  );
+  const body = markdownBody(file);
+  const sections = parseSections(body);
+  const citationRange = findCitationsRange(sections, body);
+  const links = parseBodyLinks(file, body, conceptIds, citationRange);
+  const { citations, citationIssues } = parseCitations(
+    file,
+    body,
+    conceptIds,
+    sourceEntries,
+    citationRange
+  );
+  const source = file.frontmatter.ok && isReferenceDocument(file) ? sourceFromFrontmatter(file.frontmatter.data, sourceEntries) : void 0;
+  const result = {
+    workspaceRoot,
+    target: {
+      input: options.target,
+      conceptId: file.conceptId,
+      path: file.workspacePath,
+      bundlePath: file.bundlePath,
+      reserved: file.isReserved
+    },
+    frontmatter: renderFrontmatter(file),
+    metadata: renderMetadata(file),
+    outline: sections,
+    availableSections: sections,
+    links,
+    citations,
+    citationIssues,
+    content: selectContent(body, sections, options),
+    warnings: file.frontmatter.ok ? [] : [
+      {
+        code: "FRONTMATTER_DEGRADED",
+        path: file.workspacePath,
+        message: file.frontmatter.message
+      }
+    ]
+  };
+  if (source !== void 0) {
+    result.source = source;
+  }
+  if (file.bundlePath === "index.md") {
+    result.indexLinks = parseIndexLinks(file, body, conceptIds);
+  }
+  if (path7.posix.basename(file.bundlePath) === "log.md") {
+    result.logEntries = parseLogEntries(body);
+  }
+  return result;
+}
+async function assertUtf8Target(file) {
+  if (file.markdown.includes("\uFFFD") || file.frontmatter.ok && file.frontmatter.body.includes("\uFFFD")) {
+    throw new ReadWorkspaceError("Read target is not valid UTF-8 markdown.", NON_UTF8_TARGET, {
+      path: file.workspacePath
+    });
+  }
+  const bytes = await readFile5(file.absolutePath);
+  try {
+    new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new ReadWorkspaceError("Read target is not valid UTF-8 markdown.", NON_UTF8_TARGET, {
+      path: file.workspacePath
+    });
+  }
+}
+function resolveReadTarget(files, targetInput) {
+  const target = targetInput.trim();
+  if (target.length === 0 || target.includes("\\")) {
+    throw new ReadWorkspaceError("Read target must be a non-empty OKF path.", INVALID_TARGET);
+  }
+  if (/\.[^./]+$/.test(target) && !target.endsWith(".md")) {
+    throw new ReadWorkspaceError("Read target must be a markdown document.", NON_MARKDOWN_TARGET, {
+      target
+    });
+  }
+  const candidates = targetAliases(target);
+  const file = files.find(
+    (candidate) => candidates.some(
+      (alias) => candidate.conceptId === alias || candidate.workspacePath === alias || candidate.bundlePath === alias || `/${candidate.bundlePath}` === alias
+    )
+  );
+  if (file === void 0) {
+    throw new ReadWorkspaceError(
+      "No OKF concept document matched the read target.",
+      TARGET_NOT_FOUND,
+      {
+        target
+      }
+    );
+  }
+  return file;
+}
+function targetAliases(target) {
+  if (target === "index" || target === "wiki/index.md") {
+    return ["index", "wiki/index.md", "index.md", "/index.md"];
+  }
+  if (target === "log" || target === "wiki/log.md") {
+    return ["log", "wiki/log.md", "log.md", "/log.md"];
+  }
+  const withoutWiki = target.startsWith("wiki/") ? target.slice("wiki/".length) : target;
+  const withoutSlash = withoutWiki.startsWith("/") ? withoutWiki.slice(1) : withoutWiki;
+  const withExtension = withoutSlash.endsWith(".md") ? withoutSlash : `${withoutSlash}.md`;
+  const conceptId = withExtension.slice(0, -".md".length);
+  return [
+    target,
+    withoutSlash,
+    withExtension,
+    conceptId,
+    `wiki/${withExtension}`,
+    `/${withExtension}`
+  ];
+}
+function selectContent(body, sections, options) {
+  const contentLength = body.length;
+  if (options.full === true) {
+    if (contentLength > maxFullReadChars) {
+      throw new ReadWorkspaceError(
+        "Full read exceeds the current hard cap. Use section or range reads.",
+        READ_LIMIT_EXCEEDED,
+        { contentLength, maxFullReadChars }
+      );
+    }
+    return contentForRange(body, 0, body.length, "full");
+  }
+  if (options.sectionId !== void 0 || options.section !== void 0) {
+    const section = resolveSection(sections, options);
+    return contentForRange(body, section.startOffset, section.endOffset, "section");
+  }
+  if (options.offset !== void 0 || options.limit !== void 0) {
+    const startOffset = Math.max(0, Math.trunc(options.offset ?? 0));
+    const length = Math.max(0, Math.trunc(options.limit ?? defaultReadPreviewChars));
+    return contentForRange(body, startOffset, Math.min(body.length, startOffset + length), "range");
+  }
+  return contentForRange(body, 0, Math.min(body.length, defaultReadPreviewChars), "preview");
+}
+function resolveSection(sections, options) {
+  if (options.sectionId !== void 0) {
+    const section = sections.find((candidate) => candidate.sectionId === options.sectionId);
+    if (section === void 0) {
+      throw new ReadWorkspaceError(
+        "No section matched the requested section id.",
+        TARGET_NOT_FOUND,
+        {
+          sectionId: options.sectionId
+        }
+      );
+    }
+    return section;
+  }
+  const matches = sections.filter(
+    (section) => section.heading.toLocaleLowerCase() === options.section?.toLocaleLowerCase()
+  );
+  if (matches.length === 1) {
+    return matches[0];
+  }
+  if (matches.length > 1) {
+    throw new ReadWorkspaceError(
+      "Multiple sections matched the requested heading.",
+      AMBIGUOUS_SECTION,
+      {
+        section: options.section,
+        candidates: matches.map((section) => ({
+          sectionId: section.sectionId,
+          headingPath: section.headingPath
+        }))
+      }
+    );
+  }
+  throw new ReadWorkspaceError("No section matched the requested heading.", TARGET_NOT_FOUND, {
+    section: options.section
+  });
+}
+function contentForRange(body, startOffset, endOffset, mode) {
+  const text = body.slice(startOffset, endOffset);
+  return {
+    mode,
+    text,
+    startOffset,
+    endOffset,
+    contentLength: body.length,
+    returnedChars: text.length,
+    truncated: endOffset < body.length
+  };
+}
+function parseSections(body) {
+  const headings = [];
+  const slugCounts = /* @__PURE__ */ new Map();
+  const stack = [];
+  const headingPattern = /^(#{1,6})\s+(.+?)\s*$/gm;
+  let match = headingPattern.exec(body);
+  while (match !== null) {
+    const marker = match[1];
+    const heading = match[2];
+    if (marker === void 0 || heading === void 0) {
+      continue;
+    }
+    const level = marker.length;
+    while (stack.length > 0 && (stack.at(-1)?.level ?? 0) >= level) {
+      stack.pop();
+    }
+    stack.push({ level, heading });
+    const baseSlug = slugify(stack.map((item) => item.heading).join(" "));
+    const count = slugCounts.get(baseSlug) ?? 0;
+    slugCounts.set(baseSlug, count + 1);
+    const sectionId = count === 0 ? baseSlug : `${baseSlug}-${count + 1}`;
+    headings.push({
+      sectionId,
+      headingPath: stack.map((item) => item.heading),
+      heading,
+      level,
+      startOffset: match.index,
+      endOffset: body.length,
+      line: lineNumberAtOffset(body, match.index)
+    });
+    match = headingPattern.exec(body);
+  }
+  return headings.map((heading, index) => {
+    const next = headings.slice(index + 1).find((candidate) => candidate.level <= heading.level);
+    return {
+      sectionId: heading.sectionId,
+      headingPath: heading.headingPath,
+      heading: heading.heading,
+      level: heading.level,
+      startOffset: heading.startOffset,
+      endOffset: next?.startOffset ?? body.length
+    };
+  });
+}
+function parseBodyLinks(file, body, conceptIds, citationRange) {
+  return parseMarkdownLinks(body).filter((link) => !isLineInRange(link.line, citationRange)).flatMap((link) => {
+    const conceptId = resolveOkfLinkTarget(link.target, file.bundlePath);
+    if (conceptId === void 0) {
+      return [];
+    }
+    const readLink = {
+      text: link.text,
+      target: link.target,
+      exists: conceptIds.has(conceptId),
+      line: link.line
+    };
+    if (conceptId !== void 0) {
+      readLink.conceptId = conceptId;
+    }
+    return [readLink];
+  });
+}
+function parseCitations(file, body, conceptIds, sourceEntries, citationRange) {
+  if (citationRange === void 0) {
+    return { citations: [], citationIssues: [] };
+  }
+  const citationMarkdown = body.slice(citationRange.startOffset, citationRange.endOffset);
+  const links = parseMarkdownLinks(citationMarkdown);
+  const citations = [];
+  const citationIssues = [];
+  const linkedTargets = /* @__PURE__ */ new Set();
+  for (const link of links) {
+    linkedTargets.add(link.target);
+    const conceptId = resolveOkfLinkTarget(link.target, file.bundlePath);
+    const exists = conceptId !== void 0 && conceptIds.has(conceptId);
+    const citation = {
+      kind: "reference",
+      target: link.target,
+      exists,
+      line: citationRange.startLine + link.line - 1
+    };
+    if (conceptId !== void 0) {
+      citation.conceptId = conceptId;
+    }
+    citations.push(citation);
+    if (!exists) {
+      citationIssues.push({
+        code: "BROKEN_CITATION_REFERENCE",
+        line: citation.line,
+        message: `Citation reference does not resolve: ${link.target}`
+      });
+    }
+  }
+  const bareReferenceTargets2 = [
+    ...citationMarkdown.matchAll(/(^|\s)(\/?(?:wiki\/)?references\/[^\s)]+\.md)\b/gm)
+  ];
+  for (const match of bareReferenceTargets2) {
+    const target = match[2];
+    if (target === void 0 || linkedTargets.has(target)) {
+      continue;
+    }
+    const conceptId = resolveOkfLinkTarget(target, file.bundlePath);
+    const exists = conceptId !== void 0 && conceptIds.has(conceptId);
+    const citation = {
+      kind: "reference",
+      target,
+      exists,
+      line: citationRange.startLine + lineNumberAtOffset(citationMarkdown, match.index ?? 0) - 1
+    };
+    if (conceptId !== void 0) {
+      citation.conceptId = conceptId;
+    }
+    citations.push(citation);
+    if (!exists) {
+      citationIssues.push({
+        code: "BROKEN_CITATION_REFERENCE",
+        line: citation.line,
+        message: `Citation reference does not resolve: ${target}`
+      });
+    }
+  }
+  const citedSourceIds = [...citationMarkdown.matchAll(/\b(src_\d{8}_\d{4})\b/g)];
+  for (const match of citedSourceIds) {
+    const sourceId = match[1];
+    if (sourceId === void 0) {
+      continue;
+    }
+    const source = sourceEntries.get(sourceId);
+    const citation = {
+      kind: "source",
+      sourceId,
+      exists: source !== void 0,
+      line: citationRange.startLine + lineNumberAtOffset(citationMarkdown, match.index ?? 0) - 1
+    };
+    if (source !== void 0) {
+      citation.source = source;
+    }
+    citations.push(citation);
+    if (source === void 0) {
+      citationIssues.push({
+        code: "BROKEN_CITATION_SOURCE",
+        line: citation.line,
+        message: `Citation source id is not registered: ${sourceId}`
+      });
+    }
+  }
+  return { citations, citationIssues };
+}
+function findCitationsRange(sections, body) {
+  const section = sections.find(
+    (candidate) => candidate.level === 1 && candidate.heading.trim().toLocaleLowerCase() === "citations"
+  );
+  if (section === void 0) {
+    return void 0;
+  }
+  return {
+    startOffset: section.startOffset,
+    endOffset: section.endOffset,
+    startLine: lineNumberAtOffset(body, section.startOffset),
+    endLine: lineNumberAtOffset(body, section.endOffset)
+  };
+}
+function isLineInRange(line, range) {
+  return range !== void 0 && line >= range.startLine && line <= range.endLine;
+}
+function parseIndexLinks(file, body, conceptIds) {
+  return parseMarkdownLinks(body).map((link) => {
+    const conceptId = resolveOkfLinkTarget(link.target, file.bundlePath);
+    const indexLink = {
+      title: link.text,
+      target: link.target,
+      exists: conceptId !== void 0 && conceptIds.has(conceptId)
+    };
+    return conceptId === void 0 ? indexLink : { ...indexLink, conceptId };
+  });
+}
+function parseLogEntries(body) {
+  const lines = body.split(/\r?\n/);
+  const entries = [];
+  let currentDate;
+  lines.forEach((line, index) => {
+    const heading = /^##\s+(\d{4}-\d{2}-\d{2})\s*$/.exec(line);
+    if (heading?.[1] !== void 0) {
+      currentDate = heading[1];
+      return;
+    }
+    if (currentDate !== void 0 && line.trim().startsWith("- ")) {
+      entries.push({ date: currentDate, line: index + 1, text: line.trim().slice(2) });
+    }
+  });
+  return entries;
+}
+function renderFrontmatter(file) {
+  if (file.frontmatter.ok) {
+    return {
+      ok: true,
+      data: file.frontmatter.data
+    };
+  }
+  return {
+    ok: false,
+    error: file.frontmatter.error,
+    message: file.frontmatter.message
+  };
+}
+function renderMetadata(file) {
+  const title = file.frontmatter.ok ? stringValue4(file.frontmatter.data.title) ?? firstHeading2(file.markdown) ?? file.conceptId : firstHeading2(file.markdown) ?? file.conceptId;
+  const type = file.frontmatter.ok ? stringValue4(file.frontmatter.data.type) ?? "Reserved" : "Unknown";
+  const metadata = {
+    title,
+    type,
+    tags: file.frontmatter.ok ? stringArrayValue3(file.frontmatter.data.tags) : []
+  };
+  if (file.frontmatter.ok) {
+    const description = stringValue4(file.frontmatter.data.description);
+    const timestamp = stringValue4(file.frontmatter.data.timestamp);
+    if (description !== void 0) {
+      metadata.description = description;
+    }
+    if (timestamp !== void 0) {
+      metadata.timestamp = timestamp;
+    }
+  }
+  return metadata;
+}
+function sourceFromFrontmatter(frontmatter, sourceEntries) {
+  const okfh = frontmatter.okfh;
+  if (typeof okfh !== "object" || okfh === null || Array.isArray(okfh)) {
+    return void 0;
+  }
+  const sourceId = okfh.source_id;
+  return typeof sourceId === "string" ? sourceEntries.get(sourceId) : void 0;
+}
+function isReferenceDocument(file) {
+  return file.workspacePath.startsWith("wiki/references/");
+}
+function markdownBody(file) {
+  if (file.frontmatter.ok) {
+    return file.frontmatter.body;
+  }
+  return stripFrontmatterFence2(file.markdown);
+}
+function stripFrontmatterFence2(markdown) {
+  if (!markdown.startsWith("---")) {
+    return markdown;
+  }
+  const end = markdown.indexOf("\n---", 3);
+  return end === -1 ? markdown : markdown.slice(end + "\n---".length);
+}
+function firstHeading2(markdown) {
+  return /^#\s+(.+?)\s*$/m.exec(markdown)?.[1];
+}
+function lineNumberAtOffset(input, offset) {
+  return input.slice(0, offset).split(/\r?\n/).length;
+}
+function slugify(input) {
+  const slug = input.trim().toLocaleLowerCase().replace(/[^a-z0-9\u4e00-\u9fff]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug.length > 0 ? slug : "section";
+}
+function stringValue4(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function stringArrayValue3(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+
+// src/search/index.ts
+import { readFile as readFile6 } from "fs/promises";
+import path8 from "path";
+var defaultLimit = 10;
+var maxLimit = 50;
+var maxSearchBodyChars = 2e5;
+var stopWords = /* @__PURE__ */ new Set(["a", "an", "and", "are", "for", "in", "is", "of", "or", "the", "to"]);
+async function searchWorkspace(options) {
+  const workspaceRoot = path8.resolve(options.workspaceRoot);
+  const limit = clampLimit(options.limit);
+  const config = await loadWorkspaceConfig(workspaceRoot);
+  const scanResult = await scanConcepts(workspaceRoot, config);
+  const indexMentioned = await readRootIndexMentions(workspaceRoot, config.okf.bundle_root);
+  const parsedQuery = parseSearchQuery(options.query);
+  const warnings = [];
+  const scored = scanResult.files.filter((file) => !file.isReserved).map((file) => {
+    const card = cardFromMarkdownFile(file, indexMentioned.has(file.conceptId));
+    const body = markdownBody2(file);
+    if (!card.frontmatterOk) {
+      warnings.push({
+        code: "FRONTMATTER_DEGRADED",
+        path: file.workspacePath,
+        message: `Search used fallback metadata because frontmatter is invalid: ${file.workspacePath}`
+      });
+    }
+    if (body.length > maxSearchBodyChars) {
+      warnings.push({
+        code: "SEARCH_BODY_SKIPPED",
+        path: file.workspacePath,
+        message: `Search skipped body scoring for a large markdown file: ${file.workspacePath}`
+      });
+    }
+    return scoreCard(card, body, parsedQuery);
+  }).filter((candidate) => matchesFilters(candidate.card, parsedQuery.filters)).filter((candidate) => candidate.card.score > 0).sort(compareSearchCards).map((candidate) => candidate.card);
+  return {
+    workspaceRoot,
+    query: options.query,
+    filtersApplied: parsedQuery.filters,
+    limit,
+    totalMatches: scored.length,
+    truncated: scored.length > limit,
+    results: scored.slice(0, limit),
+    warnings
+  };
+}
+function cardFromMarkdownFile(file, indexMentioned) {
+  const title = file.frontmatter.ok ? stringValue5(file.frontmatter.data.title) ?? firstHeading3(file.markdown) ?? file.conceptId : firstHeading3(file.markdown) ?? file.conceptId;
+  const type = file.frontmatter.ok ? stringValue5(file.frontmatter.data.type) ?? "Unknown" : "Unknown";
+  const description = file.frontmatter.ok ? stringValue5(file.frontmatter.data.description) : void 0;
+  const card = {
+    conceptId: file.conceptId,
+    path: file.workspacePath,
+    title,
+    type,
+    tags: file.frontmatter.ok ? stringArrayValue4(file.frontmatter.data.tags) : [],
+    frontmatterOk: file.frontmatter.ok,
+    indexMentioned,
+    score: 0,
+    scoreBreakdown: [],
+    matchedFields: [],
+    bodyHitCount: 0
+  };
+  if (description !== void 0) {
+    card.description = description;
+  }
+  return card;
+}
+function scoreCard(card, body, query) {
+  const phrase = query.phrase.toLocaleLowerCase();
+  const title = card.title.toLocaleLowerCase();
+  const conceptId = card.conceptId.toLocaleLowerCase();
+  const pathValue = card.path.toLocaleLowerCase();
+  const typeValue = card.type.toLocaleLowerCase();
+  const description = (card.description ?? "").toLocaleLowerCase();
+  const tags = card.tags.map((tag) => tag.toLocaleLowerCase());
+  const matchedFields = /* @__PURE__ */ new Set();
+  const scoreBreakdown = [];
+  const addScore = (field, reason, score) => {
+    if (score <= 0) {
+      return;
+    }
+    matchedFields.add(field);
+    scoreBreakdown.push({ field, reason, score });
+  };
+  const exactIdentityMatch = phrase.length > 0 && (title === phrase || conceptId === phrase || pathValue === phrase);
+  if (exactIdentityMatch) {
+    addScore("identity", "exact title/id/path match", 100);
+  }
+  const titlePhraseMatch = phrase.length > 0 && title.includes(phrase);
+  if (titlePhraseMatch) {
+    addScore("title", "title phrase match", 60);
+  }
+  if (phrase.length > 0 && (conceptId.includes(phrase) || pathValue.includes(phrase))) {
+    addScore("path", "id/path phrase match", 50);
+  }
+  if (phrase.length > 0 && tags.includes(phrase)) {
+    addScore("tags", "exact tag match", 40);
+  }
+  if (query.filters.type !== void 0 && typeValue === query.filters.type.toLocaleLowerCase()) {
+    addScore("type", "type filter match", 25);
+  }
+  if (phrase.length > 0 && description.includes(phrase)) {
+    addScore("description", "description phrase match", 20);
+  }
+  addTokenScores("title", query.tokens, tokenize2(title), 12, 5, addScore);
+  addTokenScores("path", query.tokens, tokenize2(`${conceptId} ${pathValue}`), 10, 5, addScore);
+  addTokenScores("tags", query.tokens, tokenize2(tags.join(" ")), 8, 5, addScore);
+  addTokenScores("description", query.tokens, tokenize2(description), 4, 5, addScore);
+  const bodyForSearch = body.length > maxSearchBodyChars ? "" : body.toLocaleLowerCase();
+  const bodyPhraseHits = phrase.length > 0 ? countOccurrences(bodyForSearch, phrase) : 0;
+  card.bodyHitCount = Math.min(bodyPhraseHits, 5);
+  addScore("body", "body phrase hits", card.bodyHitCount * 4);
+  const bodyTokenMatches = [...query.tokens].filter((token) => tokenize2(bodyForSearch).has(token));
+  addScore("body", "body unique token hits", Math.min(bodyTokenMatches.length, 10) * 2);
+  card.score = scoreBreakdown.reduce((total, item) => total + item.score, 0);
+  card.scoreBreakdown = scoreBreakdown;
+  card.matchedFields = [...matchedFields].sort();
+  return { card, exactIdentityMatch, titlePhraseMatch };
+}
+function addTokenScores(field, queryTokens, fieldTokens, weight, cap, addScore) {
+  const matches = [...queryTokens].filter((token) => fieldTokens.has(token));
+  addScore(field, `${field} token hits`, Math.min(matches.length, cap) * weight);
+}
+function compareSearchCards(left, right) {
+  return right.card.score - left.card.score || Number(right.exactIdentityMatch) - Number(left.exactIdentityMatch) || Number(right.titlePhraseMatch) - Number(left.titlePhraseMatch) || left.card.conceptId.localeCompare(right.card.conceptId);
+}
+function parseSearchQuery(query) {
+  const filters = {};
+  const terms = [];
+  for (const rawPart of query.split(/\s+/)) {
+    const part = rawPart.trim();
+    if (part.length === 0) {
+      continue;
+    }
+    const filter = /^(type|tag|path):(.+)$/i.exec(part);
+    if (filter?.[1] !== void 0 && filter[2] !== void 0) {
+      filters[filter[1].toLocaleLowerCase()] = filter[2];
+      continue;
+    }
+    terms.push(part);
+  }
+  const phrase = terms.join(" ").trim();
+  return {
+    phrase,
+    tokens: tokenize2(phrase),
+    filters
+  };
+}
+function tokenize2(input) {
+  const tokens = /* @__PURE__ */ new Set();
+  for (const token of input.toLocaleLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+    if (token.length > 0 && !stopWords.has(token)) {
+      tokens.add(token);
+    }
+  }
+  const cjkChars = [...input].filter((char) => /\p{Script=Han}/u.test(char));
+  cjkChars.forEach((char) => {
+    tokens.add(char);
+  });
+  for (let index = 0; index < cjkChars.length - 1; index += 1) {
+    const first = cjkChars[index];
+    const second = cjkChars[index + 1];
+    if (first !== void 0 && second !== void 0) {
+      tokens.add(`${first}${second}`);
+    }
+  }
+  return tokens;
+}
+function matchesFilters(card, filters) {
+  if (filters.type !== void 0 && card.type.toLocaleLowerCase() !== filters.type.toLocaleLowerCase()) {
+    return false;
+  }
+  if (filters.tag !== void 0 && !card.tags.some((tag) => tag.toLocaleLowerCase() === filters.tag?.toLocaleLowerCase())) {
+    return false;
+  }
+  if (filters.path !== void 0 && !card.path.startsWith(normalizePathFilter(filters.path))) {
+    return false;
+  }
+  return true;
+}
+function normalizePathFilter(input) {
+  return input.startsWith("wiki/") ? input : `wiki/${input.replace(/^\/+/, "")}`;
+}
+function markdownBody2(file) {
+  if (file.frontmatter.ok) {
+    return file.frontmatter.body;
+  }
+  return stripFrontmatterFence3(file.markdown);
+}
+function stripFrontmatterFence3(markdown) {
+  if (!markdown.startsWith("---")) {
+    return markdown;
+  }
+  const end = markdown.indexOf("\n---", 3);
+  return end === -1 ? markdown : markdown.slice(end + "\n---".length);
+}
+function firstHeading3(markdown) {
+  const heading = /^#\s+(.+?)\s*$/m.exec(markdown);
+  return heading?.[1];
+}
+async function readRootIndexMentions(workspaceRoot, wikiRoot) {
+  const indexPath = path8.join(workspaceRoot, wikiRoot, "index.md");
+  try {
+    const indexMarkdown = await readFile6(indexPath, "utf8");
+    return new Set(
+      parseMarkdownLinks(indexMarkdown).map((link) => resolveOkfLinkTarget(link.target, "index.md")).filter((conceptId) => conceptId !== void 0)
+    );
+  } catch (error) {
+    if (errorCode4(error) === "ENOENT") {
+      return /* @__PURE__ */ new Set();
+    }
+    throw error;
+  }
+}
+function countOccurrences(input, needle) {
+  if (needle.length === 0) {
+    return 0;
+  }
+  let count = 0;
+  let index = 0;
+  while (true) {
+    const nextIndex = input.indexOf(needle, index);
+    if (nextIndex === -1) {
+      return count;
+    }
+    count += 1;
+    index = nextIndex + needle.length;
+  }
+}
+function clampLimit(limit) {
+  if (limit === void 0) {
+    return defaultLimit;
+  }
+  return Math.max(1, Math.min(maxLimit, Math.trunc(limit)));
+}
+function stringValue5(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function stringArrayValue4(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function errorCode4(error) {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return void 0;
+  }
+  const code = error.code;
+  return typeof code === "string" ? code : void 0;
+}
+
+// src/workspace/index.ts
+import { execFile } from "child_process";
+import { access as access2, mkdir as mkdir3, readdir as readdir3, stat as stat2, writeFile as writeFile3 } from "fs/promises";
+import path9 from "path";
+import { promisify } from "util";
+import { stringify as stringifyYaml } from "yaml";
+var WORKSPACE_NOT_FOUND = "WORKSPACE_NOT_FOUND";
+var WorkspaceResolutionError = class extends Error {
+  constructor(message, startDir) {
+    super(message);
+    this.startDir = startDir;
+    this.name = "WorkspaceResolutionError";
+  }
+  startDir;
+  code = WORKSPACE_NOT_FOUND;
+};
+var WorkspaceInitError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "WorkspaceInitError";
+  }
+  code;
+};
+var execFileAsync = promisify(execFile);
+async function initWorkspace(options) {
+  const workspaceRoot = path9.resolve(options.workspaceRoot);
+  const plan = options.now === void 0 ? createWorkspacePlan({ name: options.name }) : createWorkspacePlan({ name: options.name, now: options.now });
+  await assertWorkspaceCanBeInitialized(workspaceRoot);
+  if (options.dryRun === true) {
+    return {
+      workspaceRoot,
+      name: plan.name,
+      dryRun: true,
+      git: {
+        requested: options.git === true,
+        initialized: false
+      },
+      files: plan.files.map((file) => file.path),
+      directories: plan.directories,
+      lint: {
+        ok: true,
+        issues: []
+      },
+      warnings: plan.warnings
+    };
+  }
+  await mkdir3(workspaceRoot, { recursive: true });
+  await Promise.all(
+    plan.directories.map(
+      (directory) => mkdir3(path9.join(workspaceRoot, directory), { recursive: true })
+    )
+  );
+  await Promise.all(
+    plan.files.map((file) => writeTextFile(path9.join(workspaceRoot, file.path), file.contents))
+  );
+  const gitInitialized = options.git === true ? await initializeGit(workspaceRoot) : false;
+  const lint = await lintWorkspace(workspaceRoot);
+  return {
+    workspaceRoot,
+    name: plan.name,
+    dryRun: false,
+    git: {
+      requested: options.git === true,
+      initialized: gitInitialized
+    },
+    files: plan.files.map((file) => file.path),
+    directories: plan.directories,
+    lint,
+    warnings: plan.warnings
+  };
+}
+async function initializeGit(workspaceRoot) {
+  try {
+    await execFileAsync("git", ["init"], { cwd: workspaceRoot });
+    return true;
+  } catch (error) {
+    if (errorCode5(error) === "ENOENT") {
+      throw new WorkspaceInitError("git executable was not found.", "DEPENDENCY_MISSING");
+    }
+    throw error;
+  }
+}
+async function readWorkspaceStatus(workspaceRootInput) {
+  const workspaceRoot = path9.resolve(workspaceRootInput);
+  const configResult = await readWorkspaceConfig(workspaceRoot);
+  if (!configResult.ok) {
+    return {
+      workspaceRoot,
+      initialized: false,
+      wikiFiles: 0,
+      concepts: 0,
+      lint: {
+        ok: false,
+        issues: configResult.issues.map((issue) => ({
+          code: issue.code,
+          severity: "error",
+          message: issue.message,
+          path: issue.path
+        }))
+      },
+      warnings: []
+    };
+  }
+  const [scanResult, lint] = await Promise.all([
+    scanConcepts(workspaceRoot, configResult.config),
+    lintWorkspace(workspaceRoot)
+  ]);
+  return {
+    workspaceRoot,
+    initialized: true,
+    name: configResult.config.workspace.name,
+    wikiFiles: scanResult.files.length,
+    concepts: scanResult.concepts.length,
+    lint,
+    warnings: workspacePendingWarnings()
+  };
+}
+async function resolveWorkspaceRoot(options) {
+  if (options.workspaceRoot !== void 0 && options.workspaceRoot.trim().length > 0) {
+    return path9.resolve(options.workspaceRoot);
+  }
+  const startDir = path9.resolve(options.startDir ?? process.cwd());
+  const nearest = await findNearestWorkspaceRoot(startDir);
+  if (nearest === void 0) {
+    throw new WorkspaceResolutionError(
+      "Could not find okfh.config.yaml in the current directory or its parents.",
+      startDir
+    );
+  }
+  return nearest;
+}
+async function findNearestWorkspaceRoot(startDir) {
+  let current = startDir;
+  while (true) {
+    try {
+      await access2(path9.join(current, "okfh.config.yaml"));
+      return current;
+    } catch (error) {
+      if (errorCode5(error) !== "ENOENT") {
+        throw error;
+      }
+    }
+    const parent = path9.dirname(current);
+    if (parent === current) {
+      return void 0;
+    }
+    current = parent;
+  }
+}
+function workspacePendingWarnings() {
+  return [
+    {
+      code: "AGENT_PACK_PENDING",
+      message: "Claude and Codex skill rendering is not included in the base workspace plan."
+    }
+  ];
+}
+function createWorkspacePlan(options) {
+  const createdAt = (options.now ?? /* @__PURE__ */ new Date()).toISOString();
+  const logDate = createdAt.slice(0, "YYYY-MM-DD".length);
+  const config = createWorkspaceConfig(options.name, createdAt);
+  return {
+    name: options.name,
+    createdAt,
+    directories: workspaceDirectories(),
+    files: workspaceFiles(options.name, logDate, config),
+    warnings: workspacePendingWarnings()
+  };
+}
+function workspaceDirectories() {
+  return [
+    ".agents/skills",
+    ".claude/skills",
+    ".codex",
+    ".okfh/cache",
+    ".okfh/reports",
+    "raw/assets",
+    "raw/inbox",
+    "raw/sources",
+    "wiki/decisions",
+    "wiki/entities",
+    "wiki/projects",
+    "wiki/questions",
+    "wiki/references",
+    "wiki/topics"
+  ];
+}
+async function assertWorkspaceCanBeInitialized(workspaceRoot) {
+  try {
+    const workspaceStat = await stat2(workspaceRoot);
+    if (!workspaceStat.isDirectory()) {
+      throw new WorkspaceInitError(
+        "Workspace path exists and is not a directory.",
+        "INIT_NOT_DIRECTORY"
+      );
+    }
+    const entries = await readdir3(workspaceRoot);
+    if (entries.length > 0) {
+      throw new WorkspaceInitError("Workspace path exists and is not empty.", "INIT_NOT_EMPTY");
+    }
+  } catch (error) {
+    if (errorCode5(error) === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+}
+function createWorkspaceConfig(name, createdAt) {
+  return {
+    version: "0.1",
+    workspace: {
+      name,
+      created_at: createdAt,
+      platform: "macos"
+    },
+    okf: {
+      bundle_root: "wiki",
+      profile: "okf-harness-default"
+    },
+    agents: {
+      tier1: {
+        claude: true,
+        codex: true
+      },
+      tier2: {
+        pi: false,
+        opencode: false
+      }
+    },
+    paths: {
+      raw_inbox: "raw/inbox",
+      raw_sources: "raw/sources",
+      wiki_root: "wiki",
+      manifest: ".okfh/manifest.jsonl"
+    },
+    safety: {
+      raw_sources_immutable: true,
+      require_git_checkpoint_before_agent_write: true,
+      max_files_changed_per_ingest: 20
+    }
+  };
+}
+function workspaceFiles(name, logDate, config) {
+  return [
+    {
+      path: "README.md",
+      contents: `# ${name}
+
+This is an OKF Harness workspace.
+`
+    },
+    {
+      path: "AGENTS.md",
+      contents: "# OKF Harness workspace\n\nPlaceholder. Install agent guidance with okfh init or okfh agent.\n"
+    },
+    {
+      path: "CLAUDE.md",
+      contents: "@AGENTS.md\n"
+    },
+    {
+      path: ".agents/skills/.gitkeep",
+      contents: ""
+    },
+    {
+      path: ".claude/skills/.gitkeep",
+      contents: ""
+    },
+    {
+      path: ".codex/.gitkeep",
+      contents: ""
+    },
+    {
+      path: ".gitignore",
+      contents: "# OKF Harness generated caches\n.okfh/cache/\n.okfh/*.sqlite\n.okfh/backlinks.json\n.okfh/reports/graph.html\n.okfh/reports/*.tmp\n\n# OS\n.DS_Store\n\n# Secrets\n.env\n.env.*\n!.env.example\n"
+    },
+    {
+      path: ".okfh/cache/.gitkeep",
+      contents: ""
+    },
+    {
+      path: ".okfh/manifest.jsonl",
+      contents: ""
+    },
+    {
+      path: ".okfh/reports/.gitkeep",
+      contents: ""
+    },
+    {
+      path: "okfh.config.yaml",
+      contents: stringifyYaml(config)
+    },
+    {
+      path: "raw/assets/README.md",
+      contents: "# Assets\n\nStore local assets referenced by wiki pages here.\n"
+    },
+    {
+      path: "raw/inbox/README.md",
+      contents: "# Inbox\n\nDrop unregistered source material here before adding it to OKF Harness.\n"
+    },
+    {
+      path: "raw/sources/README.md",
+      contents: "# Sources\n\nRegistered raw sources live here and should not be edited in place.\n"
+    },
+    {
+      path: "wiki/index.md",
+      contents: `# ${name} Wiki
+
+## Concepts
+
+- [Topics](/topics/index.md)
+- [References](/references/index.md)
+`
+    },
+    {
+      path: "wiki/log.md",
+      contents: `# Log
+
+## ${logDate}
+
+- Initialized the OKF Harness workspace.
+`
+    },
+    ...workspaceIndexFiles([
+      "decisions",
+      "entities",
+      "projects",
+      "questions",
+      "references",
+      "topics"
+    ])
+  ].map((file) => ({
+    path: toPosixRelativePath(".", file.path),
+    contents: file.contents
+  }));
+}
+function workspaceIndexFiles(directories) {
+  return directories.map((directory) => ({
+    path: `wiki/${directory}/index.md`,
+    contents: `# ${titleCase(directory)}
+
+No entries yet.
+`
+  }));
+}
+async function writeTextFile(filePath, contents) {
+  await mkdir3(path9.dirname(filePath), { recursive: true });
+  await writeFile3(filePath, contents, "utf8");
+}
+function titleCase(input) {
+  return input.split("-").map((word) => `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`).join(" ");
+}
+function errorCode5(error) {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return void 0;
+  }
+  const code = error.code;
+  return typeof code === "string" ? code : void 0;
+}
+
+// src/index.ts
+var packageInfo = {
+  name: "@okf-harness/core",
+  role: "core"
+};
+export {
+  AMBIGUOUS_SECTION,
+  BROKEN_LINK,
+  CONFIG_INVALID,
+  ConceptScanError,
+  GRAPH_WRITE_FAILED,
+  GraphWorkspaceError,
+  INVALID_TARGET,
+  LOG_INVALID_DATE_HEADING,
+  MANIFEST_INVALID,
+  MISSING_CITATIONS_SECTION,
+  MISSING_INDEX_ENTRY,
+  NON_MARKDOWN_TARGET,
+  NON_UTF8_TARGET,
+  OKF_INVALID_FRONTMATTER,
+  OKF_MISSING_FRONTMATTER,
+  OKF_MISSING_TYPE,
+  PATH_OUTSIDE_WORKSPACE,
+  READ_LIMIT_EXCEEDED,
+  REFERENCE_SOURCE_MISSING,
+  RESERVED_FILE_HAS_CONCEPT_FRONTMATTER,
+  RESERVED_OKF_FILENAMES,
+  ReadWorkspaceError,
+  SCAN_FAILED,
+  SOURCE_HASH_DRIFT,
+  SOURCE_INPUT_NOT_FOUND,
+  SOURCE_INPUT_UNSUPPORTED,
+  SOURCE_MISSING,
+  SOURCE_NOT_REGISTERED,
+  SOURCE_REGISTRATION_FAILED,
+  SourceManagementError,
+  TARGET_NOT_FOUND,
+  WORKSPACE_NOT_FOUND,
+  WorkspaceConfigError,
+  WorkspaceInitError,
+  WorkspacePathError,
+  WorkspaceResolutionError,
+  addSource,
+  buildWorkspaceGraph,
+  conceptIdFromPath,
+  createIngestPlan,
+  createWorkspacePlan,
+  initWorkspace,
+  isReservedOkfFile,
+  lintWorkspace,
+  listSources,
+  loadWorkspaceConfig,
+  packageInfo,
+  parseMarkdownFrontmatter,
+  parseMarkdownLinks,
+  parseWorkspaceConfig,
+  readSourceManifest,
+  readWorkspaceConfig,
+  readWorkspaceDocument,
+  readWorkspaceStatus,
+  resolveOkfLinkTarget,
+  resolveWorkspaceRoot,
+  safeResolveWorkspacePath,
+  scanConcepts,
+  searchWorkspace,
+  toPosixPath,
+  toPosixRelativePath,
+  workspaceConfigSchema
+};