@msareen/knowledge-hub-builder 0.2.0 → 0.2.2

package/AGENTS.md

@@ -137,6 +137,7 @@ From outside, pass `--hub <dir>` or set `$KHB_HUB`.
 | Command | Purpose |
 |---|---|
 | `khb lint` | validate structure against `skills/lint/SKILL.md` |
+| `khb doctor` | read-only report on the hub: version, location, per-bundle concept/raw/backlog counts, transcriber, and the command that fixes each finding. Writes nothing, and does not duplicate `lint` |
 | `khb upgrade` | refresh this hub's package-owned contract docs — runs by itself whenever `khb.json`'s stamped version differs from the installed khb, so these docs always match the CLI |
 | `khb visualize [--port N] [--no-open]` | serve the live bundle graph in your browser; aliases `vis`, `viz` |
 | `khb new-bundle <name>` | scaffold + register a bundle |

package/README.md

@@ -251,26 +251,43 @@ Commands can be run directly or requested through the matching agent skill.
 | `khb new-bundle <name> ["scope"]` | Create and register a bundle |
 | `khb ingest [bundle] [--force] [--skip-ocr] [--skip-audio]` | Acquire and extract declared sources |
 | `khb lint` | Validate routing, bundle structure, and OKF metadata |
+| `khb doctor` | Read-only report: version, location, per-bundle counts, catalog backlog, transcriber |
 | `khb visualize [--port N] [--no-open]` (aliases: `vis`, `viz`) | Serve the live bundle graph on a random free port and open it in your default browser — pan/zoomable cross-bundle map, drill into a bundle for its folder-clustered concepts, rebuild-on-refresh, exits when you close the tab |
 | `khb export <bundle> [dest]` | Export one standalone bundle |
 
-Additional ingest flags:
+Run against a hub outside the current directory with `--hub <dir>` or `$KHB_HUB`.
 
-- `--skip-ocr`
-- `--skip-audio`
+### `khb doctor` — what state is this hub in?
 
-Run against a hub outside the current directory with `--hub <dir>` or `$KHB_HUB`.
+A single read-only report. It writes nothing and repairs nothing; each finding names the
+command that does.
+
+```text
+Hub            name, description, stamped version vs installed, location, registered
+Bundles        per bundle: concepts, raw/ files, log.md rows, catalog backlog, pending
+Extraction     which formats are bundled, and whether a transcriber is ready
+Findings       what needs attention, each with its fix
+```
+
+Every check existed already, spread across the margins of commands that each knew one of
+them — a move is announced by whatever you happen to run next, the `khb update` hint comes
+out of `khb upgrade`, the uncurated row count out of `khb ingest`, and the transcriber probe
+only ever spoke during a run that needed it. `doctor` asks for the whole picture without
+changing anything to get it.
+
+It is not a validator: `khb lint` still owns structure and OKF conformance, and `doctor`
+points at it rather than repeating a rule.
 
 ### Moving between hubs
 
-These four run **outside** any hub, from any terminal:
+These run **outside** any hub, from any terminal:
 
 | Command | Purpose |
 |---|---|
 | `khb` | Open a hub. One registered hub asks; several show a list and take a pick; none walks you through creating the first |
 | `khb list [--json]` | Every hub on this machine, with its description and path |
-| `khb go <name\|N> [--path]` | Open one by name or list position. `--path` prints just the path, for `cd "$(khb go --path work)"` |
-| `khb agent [name] [--command X] [--args "…"]` | Which agent `khb go` launches — `claude`, `codex`, anything on your PATH, or `none` to just print the path |
+| `khb go [name\|N] [--path] [--no-agent] [--agent X]` | Open one by name or list position. `--path` prints just the path, for `cd "$(khb go --path work)"`; `--no-agent` prints the path and the `cd` line without launching anything; `--agent X` launches `X` for this run only, leaving the configured default alone |
+| `khb agent [name\|none] [--command X] [--args "…"]` | Which agent `khb go` launches — `claude`, `codex`, anything on your PATH, or `none` to just print the path |
 | `khb update [new-path] [--path\|-p] [--schema\|-s] [--from <old>] [--dry-run]` | Repair the hub: path references after a move, and/or backfill `sources.yaml` to the current schema. No flag runs both |
 | `khb forget <name>` | Drop a hub from the list. The folder is untouched |
 
@@ -278,7 +295,8 @@ These four run **outside** any hub, from any terminal:
 cold terminal ends with an agent open on the right folder. No program can change its
 parent shell's directory, which is why the `cd` line is printed rather than performed.
 
-The list lives in `~/.khb/hubs-config.json` (`%USERPROFILE%\.khb` on Windows). It holds
+The list lives in `~/.khb/hubs-config.json` (`%USERPROFILE%\.khb` on Windows; `$KHB_HOME`
+overrides the directory, for a portable install or a test run). It holds
 paths and one launch command — no knowledge — and fills itself in: any khb command run
 inside a hub registers it, so hubs you already had show up without a migration step.
 Delete the file and the next command in each hub puts it back.
@@ -324,7 +342,7 @@ the same spelling of the new path; matches must end at a path boundary, so movin
 never touches a sibling `…/older`; and the new path is matched too and rewritten to itself,
 which is what makes overlapping moves safe — lifting a hub out of its parent, or pushing it
 down into a subdirectory of where it stood — and makes a second run a no-op.
-`.git/`, `node_modules/` and the `inbox/` cache are skipped, as are binaries.
+`.git/`, `node_modules/` and the `.ingest-cache/` cache are skipped, as are binaries.
 
 **`--schema`/`-s`** — a bundle's `sources.yaml` can predate a field khb's since learned about
 (e.g. `exclude:`), with no way to discover it short of reading the docs. This backfills
@@ -373,7 +391,7 @@ everything under `bundles/`.
 
 ## Privacy
 
-`raw/` and the extraction cache under `inbox/` are gitignored. `log.md` is committed and
+`raw/` and the extraction cache under `.ingest-cache/` are gitignored. `log.md` is committed and
 records source paths, which may be absolute. Ignore `log.md` before the first commit if
 those paths are sensitive.
 

package/SPEC.md

@@ -72,7 +72,7 @@ my-knowledge/                  # ~/OneDrive/my-knowledge, a private repo, a shar
 │       │   ├── index.md       #   (each may carry its own index)
 │       │   └── <concept>.md
 │       └── raw/               # ingested/extracted material, pre-curation (gitignored)
-├── inbox/extracted/           # hub-wide extraction cache, keyed by content hash (gitignored)
+├── .ingest-cache/extracted/   # hub-wide extraction cache, keyed by content hash (gitignored)
 │
 │   ── below: package-owned copies, refreshed by `khb upgrade`, never hand-edited ──
 ├── AGENTS.md                  # common contract; Codex discovers this directly
@@ -121,14 +121,21 @@ acting on them** — an agent can never read a protocol the CLI no longer implem
 │   ├── new-bundle.ts          # scaffold from .bundle_template, register in outer.index.md
 │   ├── export.ts              # bundle + common patterns → standalone shareable folder
 │   ├── lint.ts                # enforce skills/lint/SKILL.md across the hub
+│   ├── doctor.ts              # read-only state report; writes nothing, repairs nothing
 │   ├── visualize.ts           # serve the live bundle graph from indexes + refs
 │   ├── ingest/                # folder.ts / files.ts / web.ts → acquire.ts → bundle/raw
 │   └── lib/
+│       ├── args.ts            # argv helpers; what they consume they remove, leaving positionals
+│       ├── create.ts          # making a hub, shared by `khb init` and the first-run wizard
 │       ├── extract.ts         # every local extractor + the content-hash cache
+│       ├── graph.ts           # graph data for the visualizer — read-only, never writes
+│       ├── graph-page.ts      # the visualizer's browser UI, rendered from that data
 │       ├── ledger.ts          # log.md read/write
+│       ├── log.ts             # progress reporting: each unit announces itself before it runs
 │       ├── paths.ts           # package-side paths — importing it never needs a hub
 │       ├── registry.ts        # ~/.khb/hubs-config.json: where this machine's hubs are
 │       ├── relocate.ts        # khb update --path's path rewriter — pure text, no judgement
+│       ├── scaffold.ts        # bundle creation + lookup, shared by new-bundle and ingest
 │       ├── schema.ts          # khb update --schema: sources.yaml field diff/apply
 │       ├── upgrade.ts         # the refresh itself: `khb upgrade` and the drift check
 │       └── util.ts            # hub resolution + shared helpers
@@ -272,7 +279,7 @@ unattended:
   changes nothing. Only old and new naming *the same directory* is refused, there being no
   move to repair.
 
-`.git/`, `node_modules/` and the `inbox/` extraction cache are not walked; binary files and
+`.git/`, `node_modules/` and the `.ingest-cache/` extraction cache are not walked; binary files and
 anything over 8 MB are skipped. `--dry-run` reports the file-by-file hit count and writes
 nothing.
 
@@ -483,7 +490,7 @@ raw files, with one hard rule — subagents write concept docs, the orchestrator
 
 Extraction is deterministic, so `khb` owns all of it. Common formats use bundled pure-JS
 libraries with no system install; results are cached hub-wide by content hash
-(`inbox/extracted/<sha256>.md`) and reused across bundles. Nothing here contacts a model:
+(`.ingest-cache/extracted/<sha256>.md`) and reused across bundles. Nothing here contacts a model:
 tesseract and whisper are local binaries, expensive in CPU but reproducible, which is what
 puts them on the CLI side of the §Division-of-labor line.
 
@@ -526,6 +533,10 @@ drops, and rewrites the raw file with `extract_tool: claude-vision`.
 - every concept doc is listed in an index and carries OKF frontmatter (`type` required)
 - `refs.md` targets exist; no cross-bundle inline links from concept docs
 - index files contain links only (routing, not content)
+- intra-bundle links from a concept doc resolve to a file that exists (warning — OKF
+  tolerates a link to knowledge not yet written)
+- `log.md` agrees with the bundle: a `curated` value naming a missing concept is an error,
+  a `raw` value naming a missing file or a `raw/` file with no row is a warning
 
 ## 8. Visualizer
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msareen/knowledge-hub-builder",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Knowledge Hub Builder — a bundle-of-bundles knowledge base you build with an agent",
   "keywords": ["knowledge-base", "okf", "agent", "wiki", "bundles", "claude", "codex", "rag"],
   "license": "MIT",
@@ -35,6 +35,8 @@
   "scripts": {
     "khb": "bun scripts/cli.ts",
     "lint": "bun scripts/cli.ts lint",
+    "upgrade": "bun scripts/cli.ts upgrade",
+    "doctor": "bun scripts/cli.ts doctor",
     "visualize": "bun scripts/cli.ts visualize",
     "new-bundle": "bun scripts/cli.ts new-bundle",
     "export": "bun scripts/cli.ts export",

package/scripts/cli.ts

@@ -13,6 +13,7 @@ const COMMANDS: Record<string, { load: () => Promise<unknown>; usage: string; de
     desc: "acquire + extract declared sources → raw/",
   },
   lint: { load: () => import("./lint"), usage: "khb lint", desc: "validate the hub against skills/lint/SKILL.md" },
+  doctor: { load: () => import("./doctor"), usage: "khb doctor", desc: "read-only report on this hub's state" },
   visualize: {
     load: () => import("./visualize"),
     usage: "khb visualize [--port N] [--no-open]",

package/scripts/doctor.ts

@@ -0,0 +1,177 @@
+// khb doctor — one read-only report on the state of a hub.
+//
+// Every check here already existed, scattered across the preambles of commands that each
+// knew one of them: cli.ts announces a move and a version drift, `khb upgrade` prints the
+// `khb update` hint, `khb ingest` counts the uncurated rows on its way out, and the
+// transcriber probe only ever spoke during a run that needed it. So the answer to "what
+// state is this hub in?" was: run several commands that change things and read their
+// margins. This command asks nothing of the hub but to look at it.
+//
+// It writes nothing. That is the point, and it is also the boundary: `doctor` reports and
+// names the command that repairs, but never repairs. `khb lint` stays the structural
+// validator — doctor counts and points at it rather than duplicating a rule.
+import { HUB, BUNDLES, listBundles, read, join, existsSync } from "./lib/util";
+import { readLedger } from "./lib/ledger";
+import { staleLocations, hubVersion } from "./lib/upgrade";
+import { diffSourcesYamlAll } from "./lib/schema";
+import { transcriberStatus } from "./lib/extract";
+import { version, MARKER, markerIn } from "./lib/paths";
+import { listHubs, canonical } from "./lib/registry";
+import { section, detail, totalElapsed } from "./lib/log";
+import { rejectUnknownFlags } from "./lib/args";
+import { readdirSync, statSync } from "node:fs";
+import { relative } from "node:path";
+
+rejectUnknownFlags(process.argv.slice(2), "khb doctor");
+
+/** Findings are advisory: doctor's exit code reports whether it ran, not what it found. */
+const findings: string[] = [];
+const flag = (msg: string, fix?: string) => findings.push(fix ? `${msg}\n      fix: ${fix}` : msg);
+
+console.log(`khb doctor → ${HUB}`);
+
+// ---- Hub identity -----------------------------------------------------------------------
+const marker = (() => {
+  try {
+    return JSON.parse(read(join(HUB, markerIn(HUB) ?? MARKER))) as Record<string, unknown>;
+  } catch {
+    return {} as Record<string, unknown>;
+  }
+})();
+
+section("Hub");
+detail(`name          ${(marker.name as string) || "(unset — khb.json 'name')"}`);
+detail(`description   ${(marker.description as string) || "(unset — khb.json 'description')"}`);
+
+// Drift is normally self-healing: cli.ts refreshes a hub before any in-hub command, this one
+// included, so a mismatch here means the refresh was suppressed rather than that it is due.
+const stamped = hubVersion(HUB);
+const installed = version();
+detail(
+  `khb version   ${stamped ?? "unstamped"}` +
+    (stamped === installed ? ` (matches installed)` : ` — installed is ${installed}`),
+);
+if (stamped !== installed)
+  flag(
+    `hub is stamped ${stamped ?? "unstamped"} but khb is ${installed}; its contract docs may be a version behind.`,
+    process.env.KHB_NO_AUTO_UPGRADE ? "unset KHB_NO_AUTO_UPGRADE, or run: khb upgrade" : "khb upgrade",
+  );
+
+// ---- Location and registry --------------------------------------------------------------
+// A hub moved more than once before anyone repaired it carries every former home, and
+// `khb update --path` rewrites them all in one pass — so say how many there are rather than
+// showing the most recent and implying it is the only one.
+const stale = staleLocations(HUB);
+detail(
+  `location      ${
+    stale.length
+      ? `moved from ${stale[stale.length - 1]}${stale.length > 1 ? ` (+${stale.length - 1} earlier)` : ""}`
+      : "matches the marker"
+  }`,
+);
+if (stale.length)
+  flag(
+    `this hub has moved; absolute paths recorded inside it still name ${stale.length > 1 ? "former locations" : "its former location"}.`,
+    "khb update --path            (khb update --path --dry-run to preview)",
+  );
+
+const registered = listHubs().some((entry) => canonical(entry.path) === canonical(HUB));
+detail(`registered    ${registered ? "yes" : "no — 'khb list' and 'khb go' will not offer it"}`);
+
+// ---- sources.yaml schema ----------------------------------------------------------------
+const schemaDiffs = diffSourcesYamlAll(HUB);
+if (schemaDiffs.length) {
+  const fields = schemaDiffs.reduce((total, diff) => total + diff.changes.length, 0);
+  flag(
+    `${fields} sources.yaml field(s) across ${schemaDiffs.length} bundle(s) predate the current schema.`,
+    "khb update --schema          (khb update --schema --dry-run to preview)",
+  );
+}
+
+// ---- Bundles ----------------------------------------------------------------------------
+const RESERVED = ["index.md", "log.md", "refs.md"];
+
+/** Concept docs: every .md in the bundle outside raw/ that is not a reserved filename. */
+function conceptCount(dir: string): number {
+  const walk = (current: string): string[] =>
+    readdirSync(current).flatMap((entry: string) => {
+      const path = join(current, entry);
+      if (statSync(path).isDirectory()) return entry === "raw" ? [] : walk(path);
+      return [relative(dir, path).replaceAll("\\", "/")];
+    });
+  return walk(dir).filter(
+    (file) => file.endsWith(".md") && !RESERVED.includes(file.split("/").pop()!),
+  ).length;
+}
+
+const bundles = listBundles();
+section(`Bundles (${bundles.length})`);
+
+if (!bundles.length) {
+  detail("none yet — khb new-bundle <name> \"scope\"");
+} else {
+  const summaries = bundles.map((bundle) => {
+    const dir = join(BUNDLES, bundle);
+    const ledger = readLedger(dir);
+    const rawDir = join(dir, "raw");
+    const rawFiles = existsSync(rawDir)
+      ? (readdirSync(rawDir, { recursive: true }) as string[]).filter((file) => file.endsWith(".md"))
+          .length
+      : 0;
+    const rows = [...ledger.values()];
+    return {
+      bundle,
+      concepts: conceptCount(dir),
+      rawFiles,
+      rows: rows.length,
+      // The catalog backlog in the ledger's own terms — "in raw/ but not yet distilled into
+      // a concept doc" — so a row must have a raw file to be part of it. A row with neither
+      // is *pending*, a different state with a different fix, and counting it in both would
+      // overstate the work cataloging can actually pick up.
+      backlog: rows.filter((row) => row.raw && !row.curated).length,
+      pending: rows.filter((row) => !row.raw).length,
+    };
+  });
+
+  const nameWidth = Math.max(6, ...summaries.map((summary) => summary.bundle.length));
+  detail(`${"bundle".padEnd(nameWidth)}  concepts   raw/   rows   backlog   pending`);
+  for (const summary of summaries)
+    detail(
+      `${summary.bundle.padEnd(nameWidth)}  ${String(summary.concepts).padStart(8)}   ` +
+        `${String(summary.rawFiles).padStart(4)}   ${String(summary.rows).padStart(4)}   ` +
+        `${String(summary.backlog).padStart(7)}   ${String(summary.pending).padStart(7)}`,
+    );
+
+  const backlog = summaries.reduce((total, summary) => total + summary.backlog, 0);
+  const pending = summaries.reduce((total, summary) => total + summary.pending, 0);
+  if (backlog)
+    flag(
+      `${backlog} row(s) in raw/ but not yet cataloged, across ` +
+        `${summaries.filter((summary) => summary.backlog).length} bundle(s).`,
+      "ask an agent to catalog the bundle (skills/catalog/SKILL.md)",
+    );
+  // An empty `raw` is a source khb saw and could not convert — a missing extractor, a
+  // protected file, or a --skip flag. It is not a failed run, but it is work still owed.
+  if (pending)
+    flag(
+      `${pending} source(s) acquired but not extracted (empty 'raw' in log.md).`,
+      "khb ingest <bundle> — after installing whatever the row's reason names",
+    );
+}
+
+// ---- Extraction -------------------------------------------------------------------------
+section("Extraction");
+detail("bundled       text, PDF, DOCX, ODT, XLSX, PPTX, OCR (images + scanned PDFs), captions");
+const transcriber = await transcriberStatus();
+detail(`transcriber   ${transcriber.detail}`);
+if (!transcriber.ready)
+  flag(`no transcriber is ready, so audio and video will pend.`, transcriber.fix);
+
+// ---- Findings ---------------------------------------------------------------------------
+section(findings.length ? `Findings (${findings.length})` : "Findings");
+if (!findings.length) detail("none — nothing here needs attention.");
+else for (const finding of findings) detail(`- ${finding}`);
+
+section("Next");
+detail("khb lint      structural and OKF validation (doctor does not duplicate it)");
+console.log(`\ndoctor: ${findings.length} finding(s) across ${bundles.length} bundle(s) in ${totalElapsed()}`);

package/scripts/hubs.ts

@@ -461,7 +461,7 @@ function repairPaths(newPath: string, fromOpt: string | undefined, dryRun: boole
   detail(`scanning ${newPath} …`);
   const { scanned, hits, failed } = rewritePaths(newPath, froms, newPath, {
     dryRun,
-    onStart: (n) => detail(`${n} file(s) to check (skipping .git/, node_modules/, inbox/)`),
+    onStart: (n) => detail(`${n} file(s) to check (skipping .git/, node_modules/, .ingest-cache/)`),
   });
 
   const total = hits.reduce((n, h) => n + h.count, 0);

package/scripts/ingest/acquire.ts

@@ -223,7 +223,7 @@ export function report(c: Counters) {
   line(c.moved, "moved/renamed — existing raw file and catalog entry kept");
   line(c.copied, "text file(s) copied");
   line(c.extracted, "extracted");
-  line(c.fromCache, "reused from the extraction cache (inbox/extracted/)");
+  line(c.fromCache, "reused from the extraction cache (.ingest-cache/extracted/)");
   line(c.ocrd, "read by OCR");
   line(c.transcribed, "transcribed");
   line(c.captioned, "read from a caption sidecar (no transcription needed)");

package/scripts/init.ts

@@ -50,7 +50,14 @@ if (upgrading) {
 
   const { from, to, synced, pruned, renamed } = upgradeHub(HUB);
   console.log(`Upgraded ${HUB}: ${from ?? "?"} -> ${to}`);
-  console.log(`  refreshed: ${synced.join(", ")}`);
+  // An empty list is not an empty result: in the khb development repo the package *is* the
+  // hub, so every managed path is its own source and there is genuinely nothing to copy.
+  // Printing a bare "refreshed:" there reads as a failure rather than as the no-op it is.
+  console.log(
+    synced.length
+      ? `  refreshed: ${synced.join(", ")}`
+      : `  refreshed: nothing to copy — this hub is its own package`,
+  );
   if (renamed) console.log(`  renamed: ${renamed} -> ${MARKER}`);
   if (pruned.length) console.log(`  removed (no longer part of the contract): ${pruned.join(", ")}`);
   console.log(`Your bundles/ and outer.index.md were not touched. Next: khb lint`);

package/scripts/lib/extract.ts

@@ -1,4 +1,4 @@
-// Content-addressed extraction cache: inbox/extracted/<sha256>.md
+// Content-addressed extraction cache: .ingest-cache/extracted/<sha256>.md
 //
 // Binary formats have to be converted before anything can read them. That conversion is
 // expensive and deterministic per content hash, so it is cached hub-wide rather than
@@ -21,10 +21,10 @@
 // and named in the provenance header, so curation can escalate to a vision read of the
 // source instead of trusting garbled text.
 import { mkdirSync, writeFileSync, readFileSync, existsSync, rmSync, readdirSync } from "node:fs";
-import { INBOX, join, basename } from "./util";
+import { INGEST_CACHE, join, basename } from "./util";
 import { note } from "./log";
 
-export const EXTRACTED = join(INBOX, "extracted");
+export const EXTRACTED = join(INGEST_CACHE, "extracted");
 
 /** Below this many characters per page, a PDF is a picture of a document, not a document. */
 const SCANNED_CHARS_PER_PAGE = 20;
@@ -611,7 +611,7 @@ export async function transcribeCached(path: string, hash: string, model = "base
 
   // Both engines write files rather than to stdout; give each run a scratch directory of
   // its own so a stray sibling transcript is never mistaken for this one's.
-  const out = join(INBOX, "tmp", hash.slice(0, 12));
+  const out = join(INGEST_CACHE, "tmp", hash.slice(0, 12));
   mkdirSync(out, { recursive: true });
   try {
     return eng.kind === "vno"
@@ -623,3 +623,35 @@ export async function transcribeCached(path: string, hash: string, model = "base
     rmSync(out, { recursive: true, force: true });
   }
 }
+
+/**
+ * The transcriber situation as a fact to report, rather than as a step in a run.
+ *
+ * `asrEngine()` above is the ingest path: it caches its answer for the process and speaks
+ * up on stderr, both of which are right in the middle of a run and wrong for `khb doctor`,
+ * which prints its own report and must not warn on the side. Same probe order — vno, then
+ * whisper, then faster-whisper — so the two never disagree about what would actually run.
+ */
+export async function transcriberStatus(): Promise<{ ready: boolean; detail: string; fix?: string }> {
+  const vno = await vnoStatus();
+  if (vno.state === "ready") return { ready: true, detail: "vno (whisper.cpp)" };
+
+  const whisper =
+    (await runCli(["whisper", "--help"])) ? "whisper"
+    : (await runCli(["faster-whisper", "--help"])) ? "faster-whisper"
+    : "";
+
+  if (vno.state === "unset-up") {
+    const missing = vno.blockers.length ? `: ${vno.blockers.join(", ")}` : "";
+    // Amber, exactly as in a run: an unset-up vno with whisper behind it is not a problem.
+    return whisper
+      ? { ready: true, detail: `${whisper} — vno installed but not set up${missing}`, fix: "vno setup" }
+      : { ready: false, detail: `vno installed but not set up${missing}`, fix: "vno setup" };
+  }
+  if (whisper) return { ready: true, detail: whisper };
+  return {
+    ready: false,
+    detail: "none on PATH — audio and video pend as rows, everything else ingests",
+    fix: "npm install -g @msareen/voice-notes-organizer   (or: pip install -U openai-whisper)",
+  };
+}

package/scripts/lib/relocate.ts

@@ -10,7 +10,7 @@ import { join, relative } from "node:path";
 import { ticker } from "./log";
 
 /** Directories never walked: VCS internals, installed packages, regenerable caches. */
-const SKIP_DIRS = new Set([".git", "node_modules", "inbox"]);
+const SKIP_DIRS = new Set([".git", "node_modules", ".ingest-cache"]);
 
 /** A file bigger than this is a corpus artefact, not something holding a path reference. */
 const MAX_BYTES = 8 * 1024 * 1024;

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,5 +1,6 @@
 // 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";
@@ -13,156 +14,258 @@ 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 stripComments = (md: string) => md.replace(/<!--[\s\S]*?-->/g, "");
+/**
+ * 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 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("\\", "/")];
   });
 }
 
+/**
+ * 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(`khb lint → ${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);

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.