@msareen/knowledge-hub-builder 0.2.1 → 0.2.3

package/scripts/lib/upgrade.ts

@@ -32,16 +32,28 @@ export function hubVersion(hub: string): string | undefined {
   }
 }
 
-/** Copy every package-owned contract file into the hub, replacing what is there. */
+/**
+ * Copy every package-owned contract file into the hub, replacing what is there.
+ *
+ * A file is skipped when source and destination are the same path. That is not a corner
+ * case: the khb development repo is its own hub (see the `note` in this repo's `khb.json`),
+ * so `PKG` and `hub` are one directory there and every managed path resolves to itself.
+ * `cpSync` rejects that outright with EINVAL, which turned any version drift in the dev
+ * repo into a crash on *every* in-hub command — the working copy is already the source of
+ * truth, so the honest answer is that there is nothing to copy.
+ */
 export function syncManaged(hub: string): string[] {
   const done: string[] = [];
-  for (const f of MANAGED) {
-    const src = join(PKG, f);
+  const same = (left: string, right: string) =>
+    process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+  for (const managed of MANAGED) {
+    const src = join(PKG, managed);
     if (!existsSync(src)) continue;
-    const dest = join(hub, f);
+    const dest = join(hub, managed);
+    if (same(resolve(src), resolve(dest))) continue;
     mkdirSync(dirname(dest), { recursive: true });
     cpSync(src, dest, { recursive: true, force: true });
-    done.push(statSync(src).isDirectory() ? `${f}/` : f);
+    done.push(statSync(src).isDirectory() ? `${managed}/` : managed);
   }
   return done;
 }

package/scripts/lib/util.ts

@@ -25,7 +25,7 @@ function resolveHub(): string {
 
 export const HUB = resolveHub();
 export const BUNDLES = join(HUB, "bundles");
-export const INBOX = join(HUB, "inbox");
+export const INGEST_CACHE = join(HUB, ".ingest-cache");
 export { TEMPLATE, markerIn } from "./paths";
 
 export function listBundles(): string[] {

package/scripts/lint.ts

@@ -1,10 +1,12 @@
 // khb lint — enforce skills/lint/SKILL.md (structural rules + OKF v0.1 conformance) across the hub
 import { HUB, BUNDLES, listBundles, read, mdLinks, refTargets, join, existsSync } from "./lib/util";
+import { readLedger } from "./lib/ledger";
 import { detail, section, totalElapsed } from "./lib/log";
 import { readdirSync, statSync } from "node:fs";
 import { dirname, relative } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { rejectUnknownFlags } from "./lib/args";
+import { paint, paintErr } from "./lib/color";
 
 rejectUnknownFlags(process.argv.slice(2), "khb lint");
 
@@ -13,156 +15,262 @@ rejectUnknownFlags(process.argv.slice(2), "khb lint");
 const OKF_FIELDS = new Set(["type", "title", "description", "resource", "tags", "timestamp"]);
 
 /** Accepts a YAML-parsed Date (unquoted) or an ISO-8601 string (quoted). */
-const isTimestamp = (v: unknown) =>
-  v instanceof Date ? !isNaN(v.getTime()) : typeof v === "string" && !isNaN(Date.parse(v));
+const isTimestamp = (value: unknown) =>
+  value instanceof Date
+    ? !isNaN(value.getTime())
+    : typeof value === "string" && !isNaN(Date.parse(value));
 
 let errors = 0, warnings = 0;
-const err = (rule: string, msg: string) => { errors++; console.error(`ERROR ${rule}: ${msg}`); };
-const warn = (rule: string, msg: string) => { warnings++; console.warn(`warn  ${rule}: ${msg}`); };
+const err = (rule: string, msg: string) => { errors++; console.error(`${paintErr.bad("ERROR")} ${paintErr.name(rule)}: ${msg}`); };
+const warn = (rule: string, msg: string) => { warnings++; console.warn(`${paintErr.warn("warn ")} ${paintErr.name(rule)}: ${msg}`); };
+
+/**
+ * Drop everything that is markup *about* markdown rather than markdown: HTML comments, and
+ * every code span or fenced block.
+ *
+ * Code has to go before any link is extracted. A doc explaining the index form writes
+ * `` `* [Title](path.md) - description` `` as an example, and a link rule that cannot tell
+ * an example from a link reports it as a dead one — which in a project whose concept docs
+ * document its own conventions is a false positive on exactly the docs most worth writing.
+ * The same reasoning covers L6: a code sample *showing* a forbidden cross-bundle link is
+ * teaching the rule, not breaking it.
+ *
+ * One pattern handles spans and fences alike: a run of N backticks closes on the next run
+ * of exactly N, so ``` fences and the `` `…` `` form that quotes inner backticks both pair
+ * correctly. An unbalanced backtick simply fails to match and leaves the text alone.
+ */
+const stripNonProse = (markdown: string) =>
+  markdown.replace(/<!--[\s\S]*?-->/g, "").replace(/(`+)[\s\S]*?\1/g, "");
 
-const stripComments = (md: string) => md.replace(/<!--[\s\S]*?-->/g, "");
 const RESERVED = ["index.md", "log.md", "refs.md"]; // refs.md is KHB-reserved
 const bundles = listBundles();
 const outerIndex = read(join(HUB, "outer.index.md"));
 
 /** All files under dir (relative paths), skipping raw/. */
 function walk(dir: string, base = dir): string[] {
-  return readdirSync(dir).flatMap((f) => {
-    const p = join(dir, f);
-    if (statSync(p).isDirectory()) return f === "raw" ? [] : walk(p, base);
-    return [relative(base, p).replaceAll("\\", "/")];
+  return readdirSync(dir).flatMap((entry: string) => {
+    const path = join(dir, entry);
+    if (statSync(path).isDirectory()) return entry === "raw" ? [] : walk(path, base);
+    return [relative(base, path).replaceAll("\\", "/")];
   });
 }
 
-console.log(`khb lint → ${HUB}`);
+/**
+ * A markdown link target resolved to a path relative to the bundle root, or undefined when
+ * it names nothing in this bundle's files: an external URL, a `mailto:`, or a bare `#anchor`
+ * pointing inside the linking document itself.
+ *
+ * `/from/bundle/root.md` is the form AGENTS.md prefers; anything else is relative to the
+ * file doing the linking. A trailing `#section` names a place *within* the target, not a
+ * different file, so it is dropped before the path is resolved — without that, every
+ * `[text](concept.md#heading)` reads as a link to a file that does not exist.
+ */
+function resolveLink(bundleRoot: string, fromRelative: string, target: string): string | undefined {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("//")) return undefined;
+  const path = target.split("#")[0].split("?")[0].trim();
+  if (!path) return undefined;
+  const resolved = path.startsWith("/")
+    ? path.slice(1)
+    : relative(bundleRoot, join(bundleRoot, dirname(fromRelative), path)).replaceAll("\\", "/");
+  return resolved.replace(/\/$/, "");
+}
+
+console.log(`${paint.head("khb lint")} → ${paint.path(HUB)}`);
 detail(`${bundles.length} bundle(s): ${bundles.join(", ") || "none"}`);
 
-for (const [bi, b] of bundles.entries()) {
-  const dir = join(BUNDLES, b);
+for (const [bundleIndex, bundle] of bundles.entries()) {
+  const dir = join(BUNDLES, bundle);
   // Name the bundle before its findings: an unattributed "ERROR L4" in a fifty-bundle hub
   // sends you grepping, and a clean bundle should still show that it was actually checked.
-  section(`[${bi + 1}/${bundles.length}] ${b}`);
+  section(`[${bundleIndex + 1}/${bundles.length}] ${bundle}`);
 
   // L2 name
-  if (!/^[a-z0-9][a-z0-9-]*$/.test(b)) err("L2", `bad bundle name '${b}'`);
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(bundle)) err("L2", `bad bundle name '${bundle}'`);
 
   // L1 required files
-  for (const f of ["index.md", "refs.md", "sources.yaml"])
-    if (!existsSync(join(dir, f))) err("L1", `${b}: missing ${f}`);
+  for (const required of ["index.md", "refs.md", "sources.yaml"])
+    if (!existsSync(join(dir, required))) err("L1", `${bundle}: missing ${required}`);
 
   // L3 registered in outer index
-  if (!outerIndex.includes(`bundles/${b}/`)) err("L3", `${b}: not listed in outer.index.md`);
+  if (!outerIndex.includes(`bundles/${bundle}/`))
+    err("L3", `${bundle}: not listed in outer.index.md`);
 
   const files = existsSync(dir) ? walk(dir) : [];
-  const mdFiles = files.filter((f) => f.endsWith(".md"));
-  const concepts = mdFiles.filter((f) => !RESERVED.includes(f.split("/").pop()!));
-  const indexes = mdFiles.filter((f) => f.split("/").pop() === "index.md");
+  const mdFiles = files.filter((file) => file.endsWith(".md"));
+  const concepts = mdFiles.filter((file) => !RESERVED.includes(file.split("/").pop()!));
+  const indexes = mdFiles.filter((file) => file.split("/").pop() === "index.md");
   detail(`${concepts.length} concept doc(s), ${indexes.length} index file(s)`);
 
   // Collect all index link targets, resolved to bundle-relative paths
   const indexed = new Set<string>();
-  for (const idx of indexes) {
-    const md = stripComments(read(join(dir, idx)));
-    for (const l of mdLinks(md)) {
-      if (l.target.startsWith("http")) continue;
-      const resolved = l.target.startsWith("/")
-        ? l.target.slice(1)
-        : relative(dir, join(dir, dirname(idx), l.target)).replaceAll("\\", "/");
-      indexed.add(resolved.replace(/\/$/, ""));
+  for (const indexFile of indexes) {
+    const markdown = stripNonProse(read(join(dir, indexFile)));
+    for (const link of mdLinks(markdown)) {
+      const resolved = resolveLink(dir, indexFile, link.target);
+      if (resolved === undefined) continue;
+      indexed.add(resolved);
       // L4b index links resolve (warning — OKF tolerates not-yet-written knowledge)
       if (!existsSync(join(dir, resolved)))
-        warn("L4", `${b}: ${idx} links to missing ${resolved}`);
+        warn("L4", `${bundle}: ${indexFile} links to missing ${resolved}`);
     }
   }
 
   // L4a every concept is indexed somewhere
-  for (const c of concepts)
-    if (!indexed.has(c)) err("L4", `${b}: ${c} not listed in any index.md`);
+  for (const concept of concepts)
+    if (!indexed.has(concept)) err("L4", `${bundle}: ${concept} not listed in any index.md`);
 
-  for (const c of concepts) {
-    const body = read(join(dir, c));
+  for (const concept of concepts) {
+    const body = read(join(dir, concept));
 
     // L9 OKF conformance: frontmatter must parse and carry a usable field set.
     // Frontmatter is the machine-readable half of a concept — routing, filtering and any
     // future index generator read it — so a typo'd key is a silent data loss, not a style nit.
-    const fm = body.match(/^---\n([\s\S]*?)\n---/)?.[1];
-    if (fm === undefined) err("L9", `${b}: ${c} has no YAML frontmatter (OKF requires it)`);
+    const frontmatter = body.match(/^---\n([\s\S]*?)\n---/)?.[1];
+    if (frontmatter === undefined)
+      err("L9", `${bundle}: ${concept} has no YAML frontmatter (OKF requires it)`);
     else {
       let meta: Record<string, unknown> | undefined;
       try {
-        meta = (parseYaml(fm) ?? {}) as Record<string, unknown>;
-      } catch (e) {
-        err("L9", `${b}: ${c} frontmatter is not valid YAML — ${(e as Error).message.split("\n")[0]}`);
+        meta = (parseYaml(frontmatter) ?? {}) as Record<string, unknown>;
+      } catch (error) {
+        err(
+          "L9",
+          `${bundle}: ${concept} frontmatter is not valid YAML — ${(error as Error).message.split("\n")[0]}`,
+        );
       }
       if (meta) {
-        const str = (k: string) => (typeof meta![k] === "string" ? (meta![k] as string).trim() : "");
+        const str = (key: string) =>
+          typeof meta![key] === "string" ? (meta![key] as string).trim() : "";
         // type is the one OKF hard requirement; the rest degrade to warnings so an
         // in-progress hub still lints clean while its authors fill things in.
-        if (!str("type")) err("L9", `${b}: ${c} frontmatter missing required 'type'`);
-        for (const k of ["title", "description"])
-          if (!str(k)) warn("L9", `${b}: ${c} frontmatter missing '${k}'`);
+        if (!str("type")) err("L9", `${bundle}: ${concept} frontmatter missing required 'type'`);
+        for (const key of ["title", "description"])
+          if (!str(key)) warn("L9", `${bundle}: ${concept} frontmatter missing '${key}'`);
         if ("tags" in meta && !Array.isArray(meta.tags))
-          err("L9", `${b}: ${c} 'tags' must be a YAML list, not ${typeof meta.tags}`);
-        if (Array.isArray(meta.tags) && meta.tags.some((t) => typeof t !== "string"))
-          err("L9", `${b}: ${c} 'tags' must contain only strings`);
+          err("L9", `${bundle}: ${concept} 'tags' must be a YAML list, not ${typeof meta.tags}`);
+        if (Array.isArray(meta.tags) && meta.tags.some((tag) => typeof tag !== "string"))
+          err("L9", `${bundle}: ${concept} 'tags' must contain only strings`);
         if ("timestamp" in meta && !isTimestamp(meta.timestamp))
-          warn("L9", `${b}: ${c} 'timestamp' is not an ISO-8601 datetime`);
-        for (const k of Object.keys(meta))
-          if (!OKF_FIELDS.has(k)) warn("L9", `${b}: ${c} unknown frontmatter key '${k}'`);
+          warn("L9", `${bundle}: ${concept} 'timestamp' is not an ISO-8601 datetime`);
+        for (const key of Object.keys(meta))
+          if (!OKF_FIELDS.has(key)) warn("L9", `${bundle}: ${concept} unknown frontmatter key '${key}'`);
       }
     }
 
     // L6 no cross-bundle links from concept docs
-    for (const l of mdLinks(stripComments(body))) {
-      if (/(^|\/)bundles\//.test(l.target) || l.target.startsWith("../../"))
-        err("L6", `${b}: ${c} links into another bundle (${l.target}) — use refs.md`);
+    for (const link of mdLinks(stripNonProse(body))) {
+      if (/(^|\/)bundles\//.test(link.target) || link.target.startsWith("../../")) {
+        err("L6", `${bundle}: ${concept} links into another bundle (${link.target}) — use refs.md`);
+        continue;
+      }
+      // L11 in-bundle concept links resolve. Concepts link to each other as the bundle's
+      // actual structure — the catalog cross-link pass and the query skill's back-links to
+      // a synthesis's sources both live in these links, and a synthesis nobody can reach
+      // from its sources is a dead end. Only the index side of this was ever checked.
+      // A warning, like L4b and for the same reason: a link to a concept somebody intends
+      // to write next is not-yet-written knowledge, which OKF tolerates by design.
+      const resolved = resolveLink(dir, concept, link.target);
+      if (resolved !== undefined && !existsSync(join(dir, resolved)))
+        warn("L11", `${bundle}: ${concept} links to missing ${resolved}`);
     }
   }
 
   // L7 ref targets exist
   if (existsSync(join(dir, "refs.md"))) {
-    for (const t of refTargets(read(join(dir, "refs.md"))))
-      if (!bundles.includes(t)) err("L7", `${b}: refs.md targets missing bundle '${t}'`);
+    for (const target of refTargets(read(join(dir, "refs.md"))))
+      if (!bundles.includes(target)) err("L7", `${bundle}: refs.md targets missing bundle '${target}'`);
   }
 
-  // L8 raw provenance (warning)
+  // Enumerated once, bundle-relative (`raw/<type>/<file>.md`) — the spelling the ledger
+  // stores, so L10 can compare the two sides without renormalizing on every row.
   const rawDir = join(dir, "raw");
-  if (existsSync(rawDir)) {
-    const rawFiles = (readdirSync(rawDir, { recursive: true }) as string[]).filter((f) => f.endsWith(".md"));
+  const rawFiles = existsSync(rawDir)
+    ? (readdirSync(rawDir, { recursive: true }) as string[])
+        .filter((file) => file.endsWith(".md"))
+        .map((file) => `raw/${file.replaceAll("\\", "/")}`)
+    : [];
+
+  // L8 raw provenance (warning)
+  if (rawFiles.length) {
     detail(`${rawFiles.length} raw/ file(s) checked for provenance`);
-    for (const f of readdirSync(rawDir, { recursive: true }) as string[]) {
+    for (const rawFile of rawFiles) {
       try {
-        if (!f.endsWith(".md")) continue;
-        const head = read(join(rawDir, f));
-        const rfm = head.match(/^---\n([\s\S]*?)\n---/)?.[1];
-        if (rfm === undefined) { warn("L8", `${b}: raw/${f} missing provenance header`); continue; }
+        const head = read(join(dir, rawFile));
+        const provenance = head.match(/^---\n([\s\S]*?)\n---/)?.[1];
+        if (provenance === undefined) {
+          warn("L8", `${bundle}: ${rawFile} missing provenance header`);
+          continue;
+        }
         // `source` is the whole point of the header: it is how a bad extraction gets re-read.
-        if (!/^source:\s*\S/m.test(rfm)) warn("L8", `${b}: raw/${f} provenance missing 'source'`);
-        const q = rfm.match(/^quality:\s*(\S+)/m)?.[1];
-        if (q && q !== "high" && q !== "low")
-          warn("L8", `${b}: raw/${f} quality '${q}' is not high|low`);
+        if (!/^source:\s*\S/m.test(provenance))
+          warn("L8", `${bundle}: ${rawFile} provenance missing 'source'`);
+        const quality = provenance.match(/^quality:\s*(\S+)/m)?.[1];
+        if (quality && quality !== "high" && quality !== "low")
+          warn("L8", `${bundle}: ${rawFile} quality '${quality}' is not high|low`);
       } catch {}
     }
   }
+
+  // L10 ledger integrity. log.md is the durable record across both halves of the workflow,
+  // and its empty `curated` cells *are* the catalog backlog — but nothing has ever checked
+  // that its paths still name anything, so a concept renamed after cataloging leaves a row
+  // claiming work that can no longer be found, and neither side notices.
+  const ledger = readLedger(dir);
+  if (ledger.size) {
+    detail(`${ledger.size} log.md row(s) checked`);
+    const claimed = new Set<string>();
+    for (const row of ledger.values()) {
+      if (row.raw) {
+        claimed.add(row.raw);
+        // raw/ is gitignored and re-derivable, so a hub that was cloned rather than ingested
+        // legitimately has every row and no files at all. Only hold a row to its raw file
+        // once raw/ has actually been populated; an empty one is that ordinary state.
+        if (rawFiles.length && !existsSync(join(dir, row.raw)))
+          warn("L10", `${bundle}: log.md row '${row.source}' names missing ${row.raw}`);
+      }
+      // `declined` is the documented way to close a row without writing a concept
+      // (skills/catalog/SKILL.md §5); anything else is a path the row claims to have written.
+      // An error, unlike the link rules: there is no not-yet-written case here, since the
+      // column is only filled once the concept exists.
+      if (row.curated && row.curated !== "declined") {
+        const curatedPaths = row.curated.split(",").map((path) => path.trim()).filter(Boolean);
+        for (const curated of curatedPaths)
+          if (!existsSync(join(dir, curated)))
+            err("L10", `${bundle}: log.md row '${row.source}' claims missing concept ${curated}`);
+      }
+    }
+    // An extracted file no row names is invisible work: it is not offered as backlog, so it
+    // stays uncurated without ever appearing to be outstanding.
+    for (const rawFile of rawFiles)
+      if (!claimed.has(rawFile)) warn("L10", `${bundle}: ${rawFile} has no log.md row`);
+  } else if (rawFiles.length) {
+    warn("L10", `${bundle}: ${rawFiles.length} file(s) in raw/ but log.md records none of them`);
+  }
 }
 
 // L3 reverse: outer index entries exist
-for (const l of mdLinks(outerIndex)) {
-  const m = l.target.match(/^bundles\/([a-z0-9-]+)\//);
-  if (m && !bundles.includes(m[1])) err("L3", `outer.index.md lists missing bundle '${m[1]}'`);
+for (const link of mdLinks(outerIndex)) {
+  const match = link.target.match(/^bundles\/([a-z0-9-]+)\//);
+  if (match && !bundles.includes(match[1]))
+    err("L3", `outer.index.md lists missing bundle '${match[1]}'`);
 }
 
 // L5 index prose check (rough): paragraph-length prose in index files
-function proseCheck(name: string, md: string) {
-  for (const block of stripComments(md).split(/\n\s*\n/)) {
-    const t = block.trim();
-    if (!t || /^[#|\-*]/.test(t) || t.startsWith("---")) continue;
-    if (t.split(/\s+/).length > 30) warn("L5", `${name}: paragraph-length prose in an index file`);
+function proseCheck(name: string, markdown: string) {
+  for (const block of stripNonProse(markdown).split(/\n\s*\n/)) {
+    const text = block.trim();
+    if (!text || /^[#|\-*]/.test(text) || text.startsWith("---")) continue;
+    if (text.split(/\s+/).length > 30)
+      warn("L5", `${name}: paragraph-length prose in an index file`);
   }
 }
 proseCheck("outer.index.md", outerIndex);
-for (const b of bundles)
-  if (existsSync(join(BUNDLES, b, "index.md"))) proseCheck(`${b}/index.md`, read(join(BUNDLES, b, "index.md")));
+for (const bundle of bundles)
+  if (existsSync(join(BUNDLES, bundle, "index.md")))
+    proseCheck(`${bundle}/index.md`, read(join(BUNDLES, bundle, "index.md")));
 
-console.log(`\nlint: ${errors} error(s), ${warnings} warning(s) across ${bundles.length} bundle(s) in ${totalElapsed()}`);
-process.exit(errors ? 1 : 0);
+console.log(
+  `\n${paint.head("lint")}: ${errors ? paint.bad(`${errors} error(s)`) : paint.ok("0 errors")}, ` +
+    `${warnings ? paint.warn(`${warnings} warning(s)`) : paint.ok("0 warnings")} ` +
+    `across ${bundles.length} bundle(s) in ${totalElapsed()}`,
+);

package/scripts/new-bundle.ts

@@ -3,18 +3,23 @@
 import { existsSync } from "node:fs";
 import { BUNDLES, join } from "./lib/util";
 import { createBundle, VALID_NAME } from "./lib/scaffold";
+import { paint, paintErr } from "./lib/color";
 import { rejectUnknownFlags } from "./lib/args";
 
 const argv = process.argv.slice(2);
 rejectUnknownFlags(argv, 'khb new-bundle <name> ["scope"]');
 const [name, scope = "TODO scope"] = argv;
 if (!name || !VALID_NAME.test(name)) {
-  console.error("Usage: khb new-bundle <name> [scope]   (lowercase, digits, hyphens)");
+  console.error(
+    `Usage: ${paintErr.cmd("khb new-bundle <name> [scope]")}   ${paintErr.dim("(lowercase, digits, hyphens)")}`,
+  );
   process.exit(1);
 }
-if (existsSync(join(BUNDLES, name))) { console.error(`Bundle '${name}' already exists`); process.exit(1); }
+if (existsSync(join(BUNDLES, name))) { console.error(`${paintErr.bad("Bundle already exists:")} ${name}`); process.exit(1); }
 
 createBundle(name, scope);
 
-console.log(`Created bundles/${name}/ and registered it in outer.index.md`);
-console.log("Next: set its scope line in outer.index.md, add sources to sources.yaml, run: khb lint");
+console.log(`${paint.ok("Created")} ${paint.name(`bundles/${name}/`)} and registered it in outer.index.md`);
+console.log(
+  `Next: set its scope line in outer.index.md, add sources to sources.yaml, run: ${paint.cmd("khb lint")}`,
+);

package/scripts/visualize.ts

@@ -8,6 +8,7 @@
 import { buildGraphData, readConceptFile } from "./lib/graph";
 import { renderGraphPage } from "./lib/graph-page";
 import { takeFlag, takeOpt, rejectUnknownFlags } from "./lib/args";
+import { paint, paintErr } from "./lib/color";
 
 const USAGE = "khb visualize [--port N] [--no-open]";
 const argv = process.argv.slice(2);
@@ -21,8 +22,8 @@ rejectUnknownFlags(argv, USAGE);
 // looks like the flag working right up until nothing is listening where you expected.
 const requestedPort = portArg === undefined ? 0 : Number(portArg);
 if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) {
-  console.error(`--port must be a number between 0 and 65535, not: ${portArg}`);
-  console.error(`Usage: ${USAGE}`);
+  console.error(`${paintErr.bad("--port must be a number between 0 and 65535, not:")} ${portArg}`);
+  console.error(`Usage: ${paintErr.cmd(USAGE)}`);
   process.exit(1);
 }
 
@@ -76,7 +77,7 @@ try {
   server = Bun.serve({ port: requestedPort, fetch: fetchHandler });
 } catch (e) {
   if (requestedPort && (e as { code?: string }).code === "EADDRINUSE") {
-    console.warn(`Port ${requestedPort} is busy — picking a free one instead.`);
+    console.warn(paintErr.warn(`Port ${requestedPort} is busy — picking a free one instead.`));
     server = Bun.serve({ port: 0, fetch: fetchHandler });
   } else throw e;
 }
@@ -89,7 +90,7 @@ setInterval(() => {
 }, HEARTBEAT_INTERVAL_MS).unref();
 
 const url = `http://localhost:${server.port}`;
-console.log(`khb visualize → ${url}  (${summarize(data)})`);
+console.log(`${paint.head("khb visualize")} → ${paint.cmd(url)}  ${paint.dim(`(${summarize(data)})`)}`);
 
 // Open the default browser. If that fails the URL is already printed above, so a headless
 // or locked-down box just falls back to copy-paste rather than erroring out.
@@ -103,7 +104,7 @@ if (!noOpen) {
   try {
     Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore" }).unref();
   } catch {
-    console.warn("Could not launch a browser — open the URL above yourself.");
+    console.warn(paintErr.warn("Could not launch a browser — open the URL above yourself."));
   }
 }
-console.log(`The server exits on its own once you close the tab. Ctrl+C also works.`);
+console.log(paint.dim(`The server exits on its own once you close the tab. Ctrl+C also works.`));

package/skills/ingest/SKILL.md

@@ -154,7 +154,7 @@ curation, not transcription.
 | `.mp3 .wav .m4a .mp4 .mov .mkv` | local `vno` (whisper.cpp), else `whisper` / `faster-whisper` | **low** |
 | `.vtt .srt` | built-in caption reader | high |
 
-Extracted text is cached hub-wide by content hash at `inbox/extracted/<sha256>.md`, so the
+Extracted text is cached hub-wide by content hash at `.ingest-cache/extracted/<sha256>.md`, so the
 same file appearing in two bundles converts once.
 
 **A recording next to its captions is one source, not two.** `talk.vtt` (or `talk.en.vtt`,

package/skills/lint/SKILL.md

@@ -12,7 +12,7 @@ description: Validate KHB structure (routing integrity, bundle shape, OKF confor
    log it in `bundles/meta/notes/decisions.md`. No meta bundle means no decision log — do
    not create one to have somewhere to write.
 
-## The rules (L1–L9)
+## The rules (L1–L11)
 
 Enforced by `khb lint`. Combines KHB routing rules with
 OKF v0.1 conformance (see the OKF spec). Reserved filenames: `index.md`, `log.md`
@@ -33,7 +33,8 @@ is a **concept document**.
   `outer.index.md` exists on disk.
 - L4. Every concept doc is listed in at least one of the bundle's `index.md` files
   (error). Index links pointing at missing files are a warning only — OKF treats
-  broken links as not-yet-written knowledge.
+  broken links as not-yet-written knowledge. A `#section` suffix names a place inside
+  the target and is dropped before the path is checked.
 - L5. Index files contain routing only: headings, bullet/table link lines, one-line
   descriptions. Paragraph-length prose is a violation (warning).
 
@@ -42,6 +43,12 @@ is a **concept document**.
 - L6. No markdown link from a concept doc into another bundle's files. Cross-bundle
   pointers live in `refs.md` only.
 - L7. Every target bundle named in `refs.md` exists.
+- L11. Markdown links *within* a bundle resolve to a file that exists (warning). Concept
+  links are the bundle's real structure — the catalog cross-link pass and the back-links
+  the query skill writes from a synthesis to its sources are both made of them, and a
+  synthesis nobody can reach from its sources is a dead end. A warning rather than an
+  error, for L4's reason: a link to a concept somebody means to write next is
+  not-yet-written knowledge.
 
 ### Provenance
 
@@ -49,6 +56,21 @@ is a **concept document**.
   non-empty `source:`, and `quality:` — if set — reading exactly `high` or `low`.
   `source` is what makes a bad extraction recoverable, so a raw file without one is
   uncatalogable, not merely untidy.
+- L10. `log.md` still describes what is on disk. It is the durable record across ingest
+  and catalog, and its empty `curated` cells *are* the catalog backlog, so a row that has
+  come loose from its files misreports the work outstanding:
+  - a `curated` path names a file that exists (**error**). `declined` is the documented
+    way to close a row without a concept and is accepted as-is; anything else is a path
+    the row claims to have written, and unlike a link there is no not-yet-written case —
+    the column is filled only once the concept exists. Renaming a concept after
+    cataloging is what usually breaks it.
+  - a row's `raw` path names a file that exists (warning), checked **only** when `raw/`
+    has files in it. `raw/` is gitignored and re-derivable, so a hub that was cloned
+    rather than ingested has every row and no files at all — that is an ordinary state,
+    not a finding.
+  - every `.md` under `raw/` has a row (warning). An extracted file no row names is
+    invisible work: never offered as backlog, so it stays uncurated without ever looking
+    outstanding.
 
 ### OKF conformance
 

package/templates/hub/gitignore

@@ -4,8 +4,8 @@ bundles/*/raw/
 # Agent-specific machine-local permissions; shared skills remain tracked.
 .claude/settings.local.json
 
-# Extraction cache (inbox/extracted/<sha256>.md) — re-derivable from the sources.
-/inbox/
+# Extraction cache (.ingest-cache/extracted/<sha256>.md) — re-derivable from the sources.
+/.ingest-cache/
 
 # Generated. The leading slash matters: a bare `export/` also matches the `skills/export/`
 # these files ship with, and silently drops the export skill from the hub's own history.