@msareen/knowledge-hub-builder 0.1.8 → 0.2.0

package/AGENTS.md

@@ -73,8 +73,10 @@ One hard boundary governs every workflow and every future change to the tooling:
 
 - **`khb` converts bytes to text.** Hashing, caching, file plumbing, ledger-keeping, and
   *every* local extractor: PDF/DOCX/ODT/XLSX/PPTX libraries, tesseract OCR for scans and
-  images, whisper for audio and video. All of it deterministic, offline, and free of
-  charge. It **never contacts a model** — not directly, not by shelling out.
+  images, whisper.cpp (via `vno`) or whisper for audio and video, and the caption reader
+  that spares them the job whenever a `.vtt`/`.srt` sits beside the recording. All of it
+  deterministic, offline, and free of charge. It **never contacts a model** — not directly,
+  not by shelling out.
 - **The agent decides what the text means.** Splitting a document into concepts, labeling
   and linking them, curating `raw/` into the wiki, escalating a bad OCR to a vision read,
   and judging when a query has produced a new concept worth keeping.
@@ -136,7 +138,7 @@ From outside, pass `--hub <dir>` or set `$KHB_HUB`.
 |---|---|
 | `khb lint` | validate structure against `skills/lint/SKILL.md` |
 | `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` | regenerate `visualizer/graph.html` |
+| `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 |
 | `khb ingest <bundle>` | acquire + extract every source in `sources.yaml` → `raw/`; maintains `log.md`. Name the bundle — with none it lists the hub's bundles and stops, unless there is nothing to choose between (no bundles, or only `default`), where it uses `default` |
 | `khb export <bundle> [dest]` | standalone copy: bundle + common patterns, shareable alone |
@@ -164,8 +166,10 @@ There is no `khb catalog` command — cataloging is entirely a judgement pass.
 **Ingest** (`skills/ingest/SKILL.md`) is mechanical and flat: `khb ingest <bundle>` pulls
 every declared source into `raw/` as markdown with a provenance header, extracting
 everything it can locally — text, PDF, DOCX, ODT, XLSX, PPTX, images by OCR, audio and
-video by whisper. Sources behind an authenticated API (Confluence, ADO, git hosts) you pull
-yourself via MCP/CLI into the same `raw/` shape. Ingest never interprets content.
+video by whisper — or, where a recording has a `.vtt`/`.srt` beside it, from those captions,
+the pair acquired as a single source. Sources behind an authenticated API (Confluence, ADO,
+git hosts) you pull yourself via MCP/CLI into the same `raw/` shape. Ingest never interprets
+content.
 
 When the user has not named a bundle, **ask** which existing bundle owns the material or
 whether to start a new one, and for an existing bundle ask whether to re-ingest what its

package/README.md

@@ -88,6 +88,8 @@ Supported out of the box, with no system tools and no further installation:
 - PDF and DOCX
 - ODT, XLSX, and PPTX
 - OCR for images and scanned PDFs, applied automatically when a PDF has no text layer
+- subtitle files (`.vtt`, `.srt`) — and a video or audio file with one beside it is read
+  from the captions rather than transcribed, as one source rather than two
 
 OCR ships with KHB: `@hyzyla/pdfium`, `sharp`, and `tesseract.js` are ordinary dependencies,
 so installing KHB pulls them down whether or not you ever ingest a scan. That costs roughly
@@ -96,8 +98,14 @@ waiting for a setup step.
 
 One extractor is genuinely optional:
 
-- audio and video transcription needs a `whisper` or `faster-whisper` executable on `PATH`
-  (`pip install -U openai-whisper`)
+- audio and video transcription needs a transcriber on `PATH`. KHB prefers
+  [`vno`](https://www.npmjs.com/package/@msareen/voice-notes-organizer)
+  (`npm install -g @msareen/voice-notes-organizer`), which wraps whisper.cpp and installs
+  its own ffmpeg and model, and falls back to `whisper` / `faster-whisper`
+  (`pip install -U openai-whisper`). KHB checks `vno status` first: a vno that is installed
+  but not yet set up leaves recordings pending with `run: vno setup` and holds up nothing
+  else in the run. A recording that already has a `.vtt` or `.srt` beside
+  it needs neither — those captions are read instead
 
 Without it, KHB leaves a pending row in `log.md` and prints the required setup rather than
 failing the run.
@@ -241,7 +249,7 @@ Commands can be run directly or requested through the matching agent skill.
 | `khb init [dir] [--name N] [--description "…"]` | Create a hub |
 | `khb upgrade` | Refresh package-owned contracts and skills (also runs automatically on version drift) |
 | `khb new-bundle <name> ["scope"]` | Create and register a bundle |
-| `khb ingest [bundle] [--force]` | Acquire and extract declared sources |
+| `khb ingest [bundle] [--force] [--skip-ocr] [--skip-audio]` | Acquire and extract declared sources |
 | `khb lint` | Validate routing, bundle structure, and OKF metadata |
 | `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 |

package/SPEC.md

@@ -45,7 +45,8 @@ KHB's own contribution is the bundle-of-bundles layer over both — see §1.
    every concept traces back through a provenance header to the original file.
 6. **Extract to markdown, locally** — binary/opaque formats (PDF, DOCX, XLSX, images,
    audio) are converted to markdown so every bundle's knowledge is plain, greppable text.
-   Every extractor is local and deterministic: pure-JS libraries, tesseract WASM, whisper.
+   Every extractor is local and deterministic: pure-JS libraries, tesseract WASM,
+   whisper.cpp.
    Lossy routes (OCR, ASR) are marked `quality: low` rather than hidden.
 7. **Bun** is the scripting language for all tooling and third-party interfaces.
 
@@ -494,11 +495,23 @@ puts them on the CLI side of the §Division-of-labor line.
 | XLSX | `fflate` → one markdown table per sheet | bundled | high |
 | scanned PDF | `pdfium` + `tesseract.js` (WASM) | bundled, ~75 MB | low |
 | Images (png/jpg/webp/tif) | `tesseract.js` | bundled, ~75 MB | low |
-| Audio, video | `whisper` / `faster-whisper` | opt-in, pip | low |
+| Audio, video | `vno` (whisper.cpp), else `whisper` / `faster-whisper` | opt-in, npm or pip | low |
+| Captions (vtt/srt) | built-in reader | bundled | high |
+
+A recording that has a caption sidecar beside it — `talk.vtt`, `talk.en.vtt`, `talk.srt` —
+is read from the sidecar rather than transcribed, and the two are acquired as one source:
+one ledger row under the recording, no row and no `raw/` file for the sidecar. The pair's
+content hash covers both files, so correcting a caption re-ingests the recording. Where two
+sidecars disagree about language khb transcribes instead: choosing an audience is not a
+conversion decision, and §Division-of-labor puts choices on the agent's side of the line.
 
 The OCR stack is bundled rather than opt-in: an ingest that stops to ask for an install is
-worse than an install that carries WASM nobody uses. Transcription stays opt-in because it is
-a Python executable, not something a JS package manager can pull down.
+worse than an install that carries WASM nobody uses. Transcription stays opt-in because it
+is an external executable, not something khb's own dependency tree can carry: `vno`
+(@msareen/voice-notes-organizer) where `vno status` reports it ready, since whisper.cpp is
+faster than the Python whisper and hands back WebVTT the caption reader can anchor, else
+`whisper` / `faster-whisper`. A vno that is installed but not set up degrades to the
+fallback, or to pending rows, and never to a failed run.
 
 A missing dep degrades to a ledger row with an empty `raw` and a printed install
 hint — never to a failed run. `quality: low` output is a standing invitation for the catalog

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msareen/knowledge-hub-builder",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "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",

package/scripts/cli.ts

@@ -9,8 +9,8 @@ const COMMANDS: Record<string, { load: () => Promise<unknown>; usage: string; de
   "new-bundle": { load: () => import("./new-bundle"), usage: 'khb new-bundle <name> ["scope"]', desc: "scaffold a bundle + register it" },
   ingest: {
     load: () => import("./ingest/index"),
-    usage: "khb ingest <bundle> [--force]",
-    desc: "acquire + extract declared sources → raw/ (name required once the hub has a bundle other than 'default')",
+    usage: "khb ingest [bundle] [--force] [--skip-ocr] [--skip-audio]",
+    desc: "acquire + extract declared sources → raw/",
   },
   lint: { load: () => import("./lint"), usage: "khb lint", desc: "validate the hub against skills/lint/SKILL.md" },
   visualize: {
@@ -20,14 +20,22 @@ const COMMANDS: Record<string, { load: () => Promise<unknown>; usage: string; de
   },
   export: { load: () => import("./export"), usage: "khb export <bundle> [dest]", desc: "standalone copy of one bundle" },
   list: { load: () => import("./hubs"), usage: "khb list [--json]", desc: "every hub on this machine" },
-  go: { load: () => import("./hubs"), usage: "khb go [name|N] [--path]", desc: "open a hub with your agent (bare 'khb' picks one)" },
-  agent: { load: () => import("./hubs"), usage: "khb agent [name] [--command X]", desc: "which agent 'khb go' launches" },
+  go: {
+    load: () => import("./hubs"),
+    usage: "khb go [name|N] [--path] [--no-agent] [--agent X]",
+    desc: "open a hub with your agent (bare 'khb' picks one)",
+  },
+  agent: {
+    load: () => import("./hubs"),
+    usage: 'khb agent [name|none] [--command X] [--args "…"]',
+    desc: "which agent 'khb go' launches",
+  },
   update: {
     load: () => import("./hubs"),
-    usage: "khb update [new] [--path|-p] [--schema|-s] [--dry-run]",
-    desc: "repair a moved hub's paths and/or backfill sources.yaml to the current schema",
+    usage: "khb update [new-path] [--path|-p] [--schema|-s] [--from <old>] [--dry-run]",
+    desc: "repair a moved hub's paths, and/or backfill sources.yaml",
   },
-  forget: { load: () => import("./hubs"), usage: "khb forget <name>", desc: "drop a hub from the list (folder untouched)" },
+  forget: { load: () => import("./hubs"), usage: "khb forget <name|path>", desc: "drop a hub from the list (folder untouched)" },
 };
 
 /**
@@ -62,12 +70,23 @@ const cmd0 = argv.shift();
 const cmd = !cmd0 ? "go" : (ALIASES[cmd0] ?? cmd0);
 
 if (cmd === "help" || cmd === "--help" || cmd === "-h") {
-  const width = Math.max(...Object.values(COMMANDS).map((c) => c.usage.length));
+  // Descriptions align to the longest usage — but only among those that fit. One long
+  // entry should not push every other description off an 80-column terminal: past the
+  // cap, that entry gets its own line for the usage and an indented line for the
+  // description, instead of dragging the whole column wide.
+  const CAP = 60;
+  const usages = Object.values(COMMANDS).map((c) => c.usage.length);
+  const width = Math.max(...usages.filter((n) => n <= CAP));
   const printSection = (title: string, names: string[]) => {
     console.log(title);
     for (const name of names) {
       const c = COMMANDS[name];
-      console.log(`  ${c.usage.padEnd(width)}   ${c.desc}`);
+      if (c.usage.length > width) {
+        console.log(`  ${c.usage}`);
+        console.log(`  ${" ".repeat(width)}   ${c.desc}`);
+      } else {
+        console.log(`  ${c.usage.padEnd(width)}   ${c.desc}`);
+      }
     }
   };
 
@@ -89,7 +108,13 @@ if (cmd === "help" || cmd === "--help" || cmd === "-h") {
   );
   console.log();
 
-  console.log(`Global:  --hub <dir>   operate on that hub instead of searching upward from cwd`);
+  console.log(`Global:  --hub <dir>              operate on that hub instead of searching upward from cwd`);
+  console.log(`         help | --help | -h       this help          --version | -v   version`);
+  console.log(`Env:     KHB_HUB                  same as --hub`);
+  console.log(`         KHB_HOME                 where the hub list lives (default ~/.khb)`);
+  console.log(`         KHB_NO_AUTO_UPGRADE      don't refresh a hub's contract docs on version drift`);
+  console.log(`Exit:    0 on success, 1 on a usage error or a failure. An unknown option is an error;`);
+  console.log(`         a source khb cannot extract is not — it becomes a pending row in log.md.`);
   console.log(`Docs:    https://github.com/msareen/knowledge-hub-builder`);
   process.exit(0);
 }

package/scripts/export.ts

@@ -4,8 +4,13 @@
 import { cpSync, writeFileSync, mkdirSync, existsSync, readFileSync } from "node:fs";
 import { HUB, bundleDir, join } from "./lib/util";
 import { detail, totalElapsed } from "./lib/log";
+import { rejectUnknownFlags } from "./lib/args";
 
-const [name, destArg] = process.argv.slice(2);
+const argv = process.argv.slice(2);
+// Before reading positionals: an unrecognized flag would otherwise become the destination,
+// and `khb export mybundle --force` would export into a folder named `--force`.
+rejectUnknownFlags(argv, "khb export <bundle> [dest]");
+const [name, destArg] = argv;
 if (!name) { console.error("Usage: khb export <bundle> [dest]"); process.exit(1); }
 
 const src = bundleDir(name);

package/scripts/hubs.ts

@@ -29,24 +29,12 @@ import {
   touchHub,
   type HubEntry,
 } from "./lib/registry";
-import { takeFlag } from "./lib/args";
+import { takeFlag, takeOpt, rejectUnknownFlags } from "./lib/args";
 import { detail, section, totalElapsed } from "./lib/log";
 
 const cmd = process.env.KHB_SUBCOMMAND ?? "go";
 const argv = process.argv.slice(2);
 
-/** Take `--name value`, removing both. */
-function takeOpt(args: string[], name: string): string | undefined {
-  const i = args.indexOf(name);
-  if (i < 0) return undefined;
-  const v = args[i + 1];
-  if (v === undefined) {
-    console.error(`${name} needs a value`);
-    process.exit(1);
-  }
-  args.splice(i, 2);
-  return v;
-}
 
 const ago = (iso?: string): string => {
   if (!iso) return "";
@@ -352,6 +340,7 @@ async function wizard(): Promise<never> {
 
 if (cmd === "list") {
   const asJson = takeFlag(argv, "--json");
+  rejectUnknownFlags(argv, "khb list [--json]");
   const hubs = listHubs();
   if (asJson) {
     console.log(JSON.stringify({ config: CONFIG, ...loadConfig(), hubs }, null, 2));
@@ -527,6 +516,7 @@ if (cmd === "update") {
   const doSchema = takeFlag(argv, "--schema", "-s");
   const dryRun = takeFlag(argv, "--dry-run");
   const fromOpt = takeOpt(argv, "--from");
+  rejectUnknownFlags(argv, "khb update [new-path] [--path|-p] [--schema|-s] [--from <old>] [--dry-run]");
   const both = !doPath && !doSchema;
   const [dest] = argv;
 
@@ -561,6 +551,7 @@ if (cmd === "update") {
 // --------------------------------------------------------------------------- forget
 
 if (cmd === "forget") {
+  rejectUnknownFlags(argv, "khb forget <name|path>");
   const [what] = argv;
   if (!what) {
     console.error(`Usage: khb forget <name|path>`);
@@ -581,6 +572,7 @@ if (cmd === "forget") {
 if (cmd === "agent") {
   const command = takeOpt(argv, "--command");
   const argsOpt = takeOpt(argv, "--args");
+  rejectUnknownFlags(argv, 'khb agent [name|none] [--command X] [--args "…"]');
   const [name] = argv;
   const cfg = loadConfig();
 
@@ -622,6 +614,7 @@ if (cmd === "agent") {
 const wantPath = takeFlag(argv, "--path");
 const noAgent = takeFlag(argv, "--no-agent") || wantPath;
 const agentName = takeOpt(argv, "--agent");
+rejectUnknownFlags(argv, "khb go [name|N] [--path] [--no-agent] [--agent X]");
 const [what] = argv;
 
 // Named target: resolve through the registry, then fall back to any path that is a hub —

package/scripts/ingest/acquire.ts

@@ -9,13 +9,13 @@
 // what the text *says* is the catalog pass (skills/catalog/SKILL.md).
 import { readFileSync, existsSync } from "node:fs";
 import { basename } from "node:path";
-import { writeRaw, sha256File, rawNameFor, retargetRaw } from "../lib/util";
+import { writeRaw, sha256, sha256File, rawNameFor, retargetRaw, normPath } from "../lib/util";
 import { record, isFresh, identify, adopt, type Entry } from "../lib/ledger";
 import {
   extractCached, ocrCached, ocrImageCached, transcribeCached,
   extractedBody, extractedPath, type Extraction,
 } from "../lib/extract";
-import { kindOf, extOf, mdName } from "./exts";
+import { captionFor, kindOf, mediaFor, extOf, mdName } from "./exts";
 import { detectPasswordProtected, PROTECTABLE } from "./protect";
 import { item, note, outcome } from "../lib/log";
 
@@ -23,14 +23,22 @@ export type Options = {
   force: boolean;   // re-acquire even when the content hash is unchanged
   ocr: boolean;     // OCR scanned PDFs and images (default on; ~seconds/page)
   audio: boolean;   // transcribe audio/video (default on; ~minutes/file)
+  // Every path this source will visit, normalized. Only the caption/media pairing reads it
+  // — a sidecar may only be folded into a recording that is itself being acquired, or a
+  // `files:` source naming just the `.vtt` would acquire nothing at all.
+  scope?: ReadonlySet<string>;
 };
 
+/** Will this source reach that file? An unset scope has no opinion, so: yes. */
+const willVisit = (opts: Options, path: string) => !opts.scope || opts.scope.has(normPath(path));
+
 export type Counters = {
   copied: number;       // text files, taken verbatim
   extracted: number;    // converted this run
   fromCache: number;    // converted by an earlier run or another bundle
   ocrd: number;
   transcribed: number;
+  captioned: number;    // read from a caption sidecar — the whisper run it saved
   lowQuality: number;   // OCR/ASR output — worth re-reading from source during curation
   skipped: number;      // unchanged since last ingest
   moved: number;        // same bytes at a new path — row re-pointed, nothing re-extracted
@@ -41,7 +49,7 @@ export type Counters = {
 };
 
 export const newCounters = (): Counters => ({
-  copied: 0, extracted: 0, fromCache: 0, ocrd: 0, transcribed: 0,
+  copied: 0, extracted: 0, fromCache: 0, ocrd: 0, transcribed: 0, captioned: 0,
   lowQuality: 0, skipped: 0, moved: 0, pending: 0,
 });
 
@@ -67,7 +75,26 @@ export async function acquireFile(
   // real time, and a run that printed only successes left the slow file unnamed.
   item(at, path);
   const kind = kindOf(path);
-  const hash = await sha256File(path);
+
+  // A caption sidecar is not a source of its own: `talk.vtt` beside `talk.mp4` is that
+  // recording's words, and the recording's row claims them below. Acquiring it here as well
+  // would spend a second raw/ file, a second uncurated ledger row and eventually a second
+  // concept on the same sentences. A caption with no recording beside it — or one whose
+  // recording this source will not visit — is a source like any other and falls through.
+  if (kind === "caption") {
+    const media = mediaFor(path);
+    if (media && willVisit(opts, media)) {
+      outcome(`captions for ${basename(media)} — acquired with the recording`);
+      return;
+    }
+  }
+
+  // Identity of a captioned recording is the pair's, not the file's. Hashing the media
+  // alone would let a corrected transcript sit next to an "unchanged, skipped" row forever.
+  const captions = kind === "av" ? captionFor(path) : undefined;
+  const own = await sha256File(path);
+  const capHash = captions ? await sha256File(captions) : kind === "caption" ? own : undefined;
+  const hash = captions ? sha256(`${own}:${capHash}`) : own;
   if (kind === "skip") {
     pend(entries, path, hash, c, "no extractor for this format");
     return;
@@ -123,12 +150,16 @@ export async function acquireFile(
     return;
   }
 
-  const hit = existsSync(extractedPath(hash));
+  // The extraction cache is keyed on the bytes that actually get converted, which for a
+  // captioned recording is the sidecar — so the same captions beside a re-encoded copy of
+  // the video, or ingested alone into another bundle, hit the same entry.
+  const key = capHash ?? hash;
+  const hit = existsSync(extractedPath(key));
   let res: Extraction;
 
   if (kind === "doc") {
     note(hit ? `${ext.slice(1)} — reusing cached extraction` : `extracting ${ext.slice(1)} …`);
-    res = await extractCached(path, hash, ext);
+    res = await extractCached(path, key, ext);
     // Pages but no text layer: the file is fine, the reader was wrong. OCR is the remedy,
     // and running it here is what keeps ingest a single pass instead of a hunt afterwards.
     if (res.status === "needs-ocr") {
@@ -137,7 +168,7 @@ export async function acquireFile(
         return;
       }
       note(`no text layer, ${res.pages}p — scanned, running OCR (seconds per page)`);
-      res = await ocrCached(path, hash);
+      res = await ocrCached(path, key);
       if (res.status === "ok") c.ocrd++;
     }
   } else if (kind === "image") {
@@ -146,15 +177,22 @@ export async function acquireFile(
       return;
     }
     note(hit ? "image — reusing cached OCR" : "image — running OCR …");
-    res = await ocrImageCached(path, hash);
+    res = await ocrImageCached(path, key);
     if (res.status === "ok" && !hit) c.ocrd++;
+  } else if (kind === "caption" || captions) {
+    // Ahead of the --skip-audio check on purpose: that flag exists to skip minutes of CPU
+    // per file, and reading a sidecar costs none. A pair is acquired even on a fast run.
+    const src = captions ?? path;
+    note(hit ? "captions — reusing cached extraction" : `reading captions from ${basename(src)} …`);
+    res = await extractCached(src, key, extOf(src));
+    if (res.status === "ok" && captions) c.captioned++;
   } else {
     if (!opts.audio) {
       pend(entries, path, hash, c, "audio/video (--skip-audio)");
       return;
     }
-    note(hit ? "audio/video — reusing cached transcript" : "transcribing with whisper (minutes per file) …");
-    res = await transcribeCached(path, hash);
+    note(hit ? "audio/video — reusing cached transcript" : "no captions beside it — transcribing (minutes per file) …");
+    res = await transcribeCached(path, key);
     if (res.status === "ok" && !hit) c.transcribed++;
   }
 
@@ -165,14 +203,18 @@ export async function acquireFile(
 
   // Copy out of the hash-keyed cache rather than moving: raw/ stays derived and the cache
   // stays reusable by any other bundle that holds the same content.
-  const raw = writeRaw(rawDir, file, { source: path, sha256: hash.slice(0, 12), tool: res.tool, quality: res.quality }, extractedBody(res.path));
+  // Name the sidecar in the provenance header, not just in this run's output: the recording
+  // is the source, but which file the words were read from is what a curator needs to know
+  // when the transcript and the audio disagree.
+  const tool = captions ? `${res.tool} (sidecar: ${basename(captions)})` : res.tool;
+  const raw = writeRaw(rawDir, file, { source: path, sha256: hash.slice(0, 12), tool, quality: res.quality }, extractedBody(res.path));
   stamp(raw);
   if (hit) c.fromCache++;
-  else if (kind === "doc") c.extracted++;
+  else if (kind === "doc" || kind === "caption") c.extracted++;
   if (res.quality === "low") c.lowQuality++;
   // Name the tool and the quality on the line: `quality: low` is the flag that tells
   // curation to re-read the original, and burying it in the file made it easy to miss.
-  outcome(`${hit ? "cached" : "extracted"} → ${raw}  [${res.tool}, quality: ${res.quality}]`);
+  outcome(`${hit ? "cached" : "extracted"} → ${raw}  [${tool}, quality: ${res.quality}]`);
 }
 
 export function report(c: Counters) {
@@ -184,6 +226,7 @@ export function report(c: Counters) {
   line(c.fromCache, "reused from the extraction cache (inbox/extracted/)");
   line(c.ocrd, "read by OCR");
   line(c.transcribed, "transcribed");
+  line(c.captioned, "read from a caption sidecar (no transcription needed)");
   line(c.lowQuality, "marked `quality: low` — verify against the source when curating");
   line(c.pending, "not extracted (empty `raw` in log.md)");
 }

package/scripts/ingest/exts.ts

@@ -2,6 +2,10 @@
 //
 // The kind decides which extractor runs, and every kind here has one — ingest is a single
 // flat pass that converts everything it can, locally, with no agent turn in the middle.
+import { readdirSync } from "node:fs";
+import { dirname, basename, join } from "node:path";
+import { normPath } from "../lib/util";
+
 export const TEXT = [".md", ".txt", ".rst", ".adoc", ".html", ".csv", ".json", ".yaml", ".yml"];
 /** Born-digital documents: khb's own pure-JS libraries read these, no system install. */
 export const DOC = [".pdf", ".docx", ".odt", ".xlsx", ".pptx"];
@@ -9,6 +13,12 @@ export const DOC = [".pdf", ".docx", ".odt", ".xlsx", ".pptx"];
 export const IMAGE = [".png", ".jpg", ".jpeg", ".webp", ".bmp", ".tif", ".tiff", ".gif"];
 /** Audio and video: local whisper. Minutes of CPU per file, hence `--skip-audio`. */
 export const AV = [".mp3", ".wav", ".m4a", ".flac", ".ogg", ".mp4", ".mov", ".mkv", ".webm"];
+/**
+ * Subtitle sidecars: the words of a recording, already written down by someone who could
+ * hear it. Ordered by preference — the same captions often exist in both containers, and
+ * `.vtt` carries speaker names where `.srt` does not.
+ */
+export const CAPTION = [".vtt", ".srt"];
 
 export const extOf = (p: string) => {
   const i = p.lastIndexOf(".");
@@ -18,12 +28,83 @@ export const extOf = (p: string) => {
 /** raw/ files are always markdown — don't produce "budget.md.md". */
 export const mdName = (n: string) => (n.toLowerCase().endsWith(".md") ? n : n + ".md");
 
-export type Kind = "text" | "doc" | "image" | "av" | "skip";
+export type Kind = "text" | "doc" | "image" | "av" | "caption" | "skip";
 export function kindOf(path: string): Kind {
   const e = extOf(path);
   if (TEXT.includes(e)) return "text";
   if (DOC.includes(e)) return "doc";
   if (IMAGE.includes(e)) return "image";
   if (AV.includes(e)) return "av";
+  if (CAPTION.includes(e)) return "caption";
   return "skip";
 }
+
+// --- sidecar pairing -------------------------------------------------------------------
+//
+// `talk.vtt` next to `talk.mp4` is not a second source, it is that recording's transcript.
+// Pairing them is what lets ingest read the words instead of guessing at them with whisper,
+// for no CPU and at higher fidelity. Both directions of the pairing are decided here so the
+// two sides can never disagree about which file belongs to which.
+
+/** One readdir per directory per run — a folder walk asks about the same siblings a lot. */
+const listing = new Map<string, string[]>();
+function siblings(path: string): { dir: string; names: string[] } {
+  const dir = dirname(path) || ".";
+  let names = listing.get(dir);
+  if (!names) {
+    try {
+      names = readdirSync(dir);
+    } catch {
+      names = []; // unreadable directory: no sidecar, and the file itself will say why
+    }
+    listing.set(dir, names);
+  }
+  return { dir, names };
+}
+
+const stemOf = (name: string) => name.slice(0, name.length - extOf(name).length);
+
+/**
+ * A caption file's stem usually carries a language tag — `talk.en.vtt`, `talk.pt-BR.vtt`,
+ * which is what yt-dlp and every "download the subtitles" button writes — beside a plain
+ * `talk.mp4`. Strip one tag so the pair still matches.
+ */
+const untag = (stem: string) => stem.replace(/\.[a-z]{2,3}(?:-[A-Za-z]{2,4})?$/, "");
+
+/**
+ * The caption sidecar belonging to a media file, when there is one obvious candidate.
+ *
+ * Two languages on disk is a choice about audience, and khb does not make choices: it
+ * transcribes instead and leaves the sidecars for a human to point at. The same captions in
+ * two containers is not a choice — they are the same words — so CAPTION order settles it.
+ */
+export function captionFor(media: string): string | undefined {
+  if (kindOf(media) !== "av") return undefined;
+  const { dir, names } = siblings(media);
+  const stem = stemOf(basename(media));
+  const captions = names.filter((n) => kindOf(n) === "caption");
+  const exact = captions.filter((n) => stemOf(n) === stem);
+  const pool = exact.length ? exact : captions.filter((n) => untag(stemOf(n)) === stem);
+  if (!pool.length) return undefined;
+  if (!exact.length && new Set(pool.map(stemOf)).size > 1) return undefined; // several languages
+  const best = [...pool].sort((a, b) => CAPTION.indexOf(extOf(a)) - CAPTION.indexOf(extOf(b)))[0];
+  return join(dir, best);
+}
+
+/**
+ * The media file a caption sidecar belongs to, if any — deliberately defined in terms of
+ * `captionFor`, so a caption is only somebody's sidecar when that somebody would actually
+ * claim it. A caption with no recording beside it is a source in its own right.
+ */
+export function mediaFor(caption: string): string | undefined {
+  if (kindOf(caption) !== "caption") return undefined;
+  const { dir, names } = siblings(caption);
+  const stems = new Set([stemOf(basename(caption)), untag(stemOf(basename(caption)))]);
+  for (const n of names) {
+    if (kindOf(n) !== "av" || !stems.has(stemOf(n))) continue;
+    const media = join(dir, n);
+    const found = captionFor(media);
+    if (found && normPath(found) === normPath(caption)) return media;
+  }
+  return undefined;
+}

package/scripts/ingest/files.ts

@@ -1,7 +1,7 @@
 // Explicit file list → raw/files/. Same acquisition as a folder source, for the case where
 // the interesting files are scattered and naming them is easier than naming a root.
 import { existsSync } from "node:fs";
-import { basename } from "../lib/util";
+import { basename, normPath } from "../lib/util";
 import type { Entry } from "../lib/ledger";
 import { acquireFile, newCounters, report, type Options } from "./acquire";
 import { detail, item, outcome, pos } from "../lib/log";
@@ -21,6 +21,11 @@ export async function ingestFiles(
   const skippedCount = s.paths.length - paths.length;
   if (skippedCount) detail(`${skippedCount} excluded by 'exclude' rule(s), ${paths.length} remain`);
 
+  // What this source will visit, for the caption/media pairing: a `.vtt` is only folded
+  // into a recording that is itself on the list, so naming just the sidecar still acquires
+  // it on its own.
+  const scoped = { ...opts, scope: new Set(paths.map((p) => normPath(p))) };
+
   const c = newCounters();
   for (const [i, p] of paths.entries()) {
     const at = pos(i + 1, paths.length);
@@ -29,7 +34,7 @@ export async function ingestFiles(
       outcome("missing, skipped");
       continue;
     }
-    await acquireFile(at, p, basename(p), rawDir, bundleDir, entries, c, opts);
+    await acquireFile(at, p, basename(p), rawDir, bundleDir, entries, c, scoped);
   }
   report(c);
 }

package/scripts/ingest/folder.ts

@@ -2,7 +2,7 @@
 // owns the extraction decisions. Unchanged files (same content hash, raw/ copy still
 // present) are skipped.
 import { readdirSync, statSync, existsSync } from "node:fs";
-import { join } from "../lib/util";
+import { join, normPath } from "../lib/util";
 import type { Entry } from "../lib/ledger";
 import { acquireFile, newCounters, report, type Options } from "./acquire";
 import { detail, pos } from "../lib/log";
@@ -43,12 +43,17 @@ export async function ingestFolder(
   const skippedCount = all.length - files.length;
   if (skippedCount) detail(`${skippedCount} excluded by 'exclude' rule(s), ${files.length} remain`);
 
+  // What this walk will visit, for the caption/media pairing: a `.vtt` whose recording is
+  // excluded (or simply absent) is acquired on its own rather than folded into a row that
+  // would never appear.
+  const scoped = { ...opts, scope: new Set(files.map((p) => normPath(p))) };
+
   const c = newCounters();
   for (const [i, p] of files.entries()) {
     // Flatten the subtree into the filename so two `notes.md` in sibling folders don't
     // collide in raw/, and so the origin stays legible without opening the file.
     const rel = relOf(p).replaceAll("/", "__");
-    await acquireFile(pos(i + 1, files.length), p, rel, rawDir, bundleDir, entries, c, opts);
+    await acquireFile(pos(i + 1, files.length), p, rel, rawDir, bundleDir, entries, c, scoped);
   }
   report(c);
 }

package/scripts/ingest/index.ts

@@ -14,7 +14,7 @@ import { read, join, HUB } from "../lib/util";
 import { detail, section, totalElapsed } from "../lib/log";
 import { bundleForIngest, listBundles, DEFAULT_BUNDLE } from "../lib/scaffold";
 import { readLedger, writeLedger } from "../lib/ledger";
-import { takeFlag } from "../lib/args";
+import { takeFlag, rejectUnknownFlags } from "../lib/args";
 import { ingestFolder } from "./folder";
 import { ingestFiles } from "./files";
 import { ingestWeb } from "./web";
@@ -25,6 +25,7 @@ export type Source =
   | { type: "files"; paths: string[]; exclude?: string[] }
   | { type: "web"; urls: string[] };
 
+const USAGE = "khb ingest [bundle] [--force] [--skip-ocr] [--skip-audio]";
 const argv = process.argv.slice(2);
 const opts: Options = {
   force: takeFlag(argv, "--force"),
@@ -33,14 +34,10 @@ const opts: Options = {
   ocr: !takeFlag(argv, "--skip-ocr"),
   audio: !takeFlag(argv, "--skip-audio"),
 };
-const unknownFlag = argv.find((a) => a.startsWith("--"));
-if (unknownFlag) {
-  console.error(`Unknown ingest flag: ${unknownFlag}`);
-  process.exit(1);
-}
-const positional = argv.filter((a) => !a.startsWith("--"));
+rejectUnknownFlags(argv, USAGE);
+const positional = argv;
 if (positional.length > 1) {
-  console.error("Usage: khb ingest [bundle] [--force] [--skip-ocr] [--skip-audio]");
+  console.error(`Usage: ${USAGE}`);
   process.exit(1);
 }
 // No bundle named: which one owns the material is a human decision (AGENTS.md) and a CLI
@@ -52,7 +49,7 @@ if (!bundle) {
   const have = listBundles();
   const onlyLanding = have.length === 1 && have[0] === DEFAULT_BUNDLE;
   if (have.length && !onlyLanding) {
-    console.error("Usage: khb ingest [bundle] [--force] [--skip-ocr] [--skip-audio]");
+    console.error(`Usage: ${USAGE}`);
     console.error(`\nBundles in this hub: ${have.join(", ")}`);
     console.error(`Name the one that owns this material, or start a new one:`);
     console.error(`  khb new-bundle <name> "<scope>"`);

package/scripts/init.ts

@@ -10,7 +10,8 @@
 // drift before any hub command.
 import { resolve, basename } from "node:path";
 import { MARKER, markerIn } from "./lib/paths";
-import { upgradeHub, updateHint } from "./lib/upgrade";
+import { recordLocation, upgradeHub, updateHint } from "./lib/upgrade";
+import { takeOpt, rejectUnknownFlags } from "./lib/args";
 
 const upgrading = process.env.KHB_SUBCOMMAND === "upgrade";
 const argv = process.argv.slice(2);
@@ -18,23 +19,35 @@ const argv = process.argv.slice(2);
 // A hub describes itself in its own marker, and the machine-level registry reads those
 // two fields from there — so the label follows the hub when it is moved or cloned onto
 // another machine, instead of living only in one laptop's shortcut list.
-function takeOpt(name: string): string | undefined {
-  const i = argv.indexOf(name);
-  if (i < 0) return undefined;
-  const v = argv[i + 1];
-  if (v === undefined) {
-    console.error(`${name} needs a value`);
-    process.exit(1);
-  }
-  argv.splice(i, 2);
-  return v;
-}
-const nameOpt = takeOpt("--name");
-const descOpt = takeOpt("--description");
+// Both describe a hub being created, so `upgrade` must not consume them: left in argv they
+// are refused below like any other unknown option, instead of being silently swallowed by a
+// command whose help says it takes no flags at all.
+const nameOpt = upgrading ? undefined : takeOpt(argv, "--name");
+const descOpt = upgrading ? undefined : takeOpt(argv, "--description");
+rejectUnknownFlags(argv, upgrading ? "khb upgrade" : 'khb init [dir] [--name N] [--description "…"]');
 const [dirArg] = argv;
 
 if (upgrading) {
   const { HUB } = await import("./lib/util"); // resolves the hub, or exits with guidance
+
+  // cli.ts runs these two before every *other* in-hub command and skips `upgrade`, on the
+  // grounds that upgrade does the refresh itself. Neither of these is the refresh:
+  //
+  //   - unregistered, a hub you only ever upgrade never appears in `khb list` or `khb go`;
+  //   - unrecorded, a hub upgraded right after a move loses the move. `upgradeHub` stamps
+  //     the marker with wherever the hub is now, so the old path has to be read — and
+  //     appended to `movedFrom` — before that happens, or `khb update --path` is left with
+  //     nothing to repair from and the arguments it exists to avoid.
+  const { registerHub, touchHub } = await import("./lib/registry");
+  registerHub(HUB);
+  touchHub(HUB);
+  const { moved } = recordLocation(HUB);
+  if (moved) {
+    console.log(`This hub was at ${moved} and is now at ${HUB}.`);
+    console.log(`  absolute paths recorded inside it still name the old location.`);
+    console.log(`  repair them:  khb update --path           (--dry-run to preview)`);
+  }
+
   const { from, to, synced, pruned, renamed } = upgradeHub(HUB);
   console.log(`Upgraded ${HUB}: ${from ?? "?"} -> ${to}`);
   console.log(`  refreshed: ${synced.join(", ")}`);

package/scripts/lib/args.ts

@@ -10,3 +10,40 @@ export function takeFlag(args: string[], ...names: string[]): boolean {
   }
   return false;
 }
+
+/**
+ * Take `--name value`, removing both. Also accepts `--name=value`, since that is the form
+ * fingers produce when the docs show the spaced one.
+ */
+export function takeOpt(args: string[], name: string): string | undefined {
+  const eq = args.findIndex((a) => a.startsWith(`${name}=`));
+  if (eq >= 0) {
+    const [v] = args.splice(eq, 1);
+    return v.slice(name.length + 1);
+  }
+  const i = args.indexOf(name);
+  if (i < 0) return undefined;
+  const v = args[i + 1];
+  if (v === undefined) {
+    console.error(`${name} needs a value`);
+    process.exit(1);
+  }
+  args.splice(i, 2);
+  return v;
+}
+
+/**
+ * Refuse anything flag-shaped this command does not understand. Call it once every
+ * `takeFlag`/`takeOpt` has removed what it consumed, so whatever remains is positional.
+ *
+ * Silence is the wrong default here: an unrecognized flag left in the array becomes a
+ * positional argument, and `khb export mybundle --force` used to quietly export into a
+ * directory named `--force`. A typo should cost an error message, not a mystery folder.
+ */
+export function rejectUnknownFlags(args: string[], usage: string): void {
+  const bad = args.find((a) => a.length > 1 && a.startsWith("-"));
+  if (!bad) return;
+  console.error(`Unknown option: ${bad}`);
+  console.error(`Usage: ${usage}`);
+  process.exit(1);
+}

package/scripts/lib/extract.ts

@@ -77,8 +77,134 @@ function colIndex(ref: string): number {
   return n - 1;
 }
 
+// --- captions --------------------------------------------------------------------------
+//
+// WebVTT and SRT are the same document in two dialects: an optional cue index, a timecode
+// line, then the words. Everything but the words is scaffolding for a player, and reaches
+// curation as noise — a transcript diced into three-second lines, every one of them
+// preceded by a timestamp nobody will read.
+//
+// Two things are worth keeping. *When*, coarsely: a transcript nobody can point into is
+// hard to cite, so anything longer than a chapter gets a heading per interval, enough to
+// find the passage in the recording. And *who*, where the file says so: WebVTT's `<v Name>`
+// is the only speaker attribution that survives from the original, and it is exactly what a
+// meeting or an interview is read for.
+//
+// One thing is worth removing beyond the scaffolding. Auto-generated captions scroll: each
+// cue repeats the tail of the one before it so the viewer sees a stable two-line window.
+// Written down verbatim that doubles the transcript and reads as a stutter, so an
+// overlapping head is trimmed instead of appended twice.
+
+/** Seconds per `## h:mm:ss` heading, and the length below which a transcript gets none. */
+const CHAPTER = 300;
+
+/**
+ * Paragraph lengths, in characters. Captions have no paragraphs of their own — five minutes
+ * of speech arrives as one unbroken line — so they get made here: break at the first
+ * sentence end past SOFT, and give up and break anywhere past HARD, which is what
+ * auto-generated captions need, since they carry no punctuation to break on.
+ */
+const SOFT = 600;
+const HARD = 1600;
+
+/** "01:02:03.456" or "02:03.456" → seconds. */
+function cueSeconds(t: string): number {
+  const m = t.match(/(?:(\d+):)?(\d{1,2}):(\d{2})[.,](\d{1,3})/);
+  if (!m) return 0;
+  return Number(m[1] ?? 0) * 3600 + Number(m[2]) * 60 + Number(m[3]) + Number(m[4]) / 1000;
+}
+
+/** A closing `.`, `?` or `!`, with the quote or bracket that may follow it. */
+const SENTENCE_END = /[.!?]["')\]]?$/;
+
+function stamp(s: number): string {
+  const pad = (n: number) => String(Math.floor(n)).padStart(2, "0");
+  return `${Math.floor(s / 3600)}:${pad((s % 3600) / 60)}:${pad(s % 60)}`;
+}
+
+/** A cue's payload: its speaker, if the file names one, and its words minus the markup. */
+function cueText(lines: string[]): { speaker?: string; text: string } {
+  let speaker: string | undefined;
+  const text = lines
+    .join(" ")
+    // <v Roger Bingham> / <v.loud Esme> — the voice span names who is talking.
+    .replace(/<v[^\s>]*\s+([^>]*)>/g, (_, name: string) => {
+      speaker ??= name.trim();
+      return "";
+    })
+    // Everything else is presentation: <c> classes, </v>, and the inline <00:00:01.000>
+    // stamps that karaoke-style captions put between words.
+    .replace(/<[^>]*>/g, "")
+    .replace(/&nbsp;/g, " ");
+  return { speaker, text: unxml(text).replace(/\s+/g, " ").trim() };
+}
+
+/**
+ * Append `next` to `text`, dropping the head the two share. Only a whole-word overlap of
+ * some length counts: trimming on a coincidental few characters would splice two different
+ * words into one, which is worse than the repetition it avoids.
+ */
+function joinOverlap(text: string, next: string): string {
+  for (let k = Math.min(next.length, 400); k >= 4; k--) {
+    if (!text.endsWith(next.slice(0, k))) continue;
+    const before = text[text.length - k - 1];
+    const after = next[k];
+    if ((before !== undefined && before !== " ") || (after !== undefined && after !== " ")) continue;
+    const rest = next.slice(k).trim();
+    return rest ? `${text} ${rest}` : text;
+  }
+  return `${text} ${next}`;
+}
+
+/** WebVTT/SRT → prose. Pure text in, pure text out; no file access, so it is easy to test. */
+export function captionText(raw: string): string {
+  type Para = { at: number; speaker?: string; text: string };
+  const paras: Para[] = [];
+  let open: Para | undefined;
+
+  for (const block of raw.replace(/\r\n?/g, "\n").split(/\n{2,}/)) {
+    const lines = block.split("\n").map((l) => l.trim()).filter(Boolean);
+    // WEBVTT is the file signature; NOTE, STYLE and REGION blocks are metadata and CSS.
+    if (!lines.length || /^(WEBVTT|NOTE|STYLE|REGION)\b/.test(lines[0])) continue;
+    const timed = lines.findIndex((l) => l.includes("-->"));
+    if (timed === -1) continue; // no timecode: not a cue
+    const at = cueSeconds(lines[timed].split("-->")[0]);
+    const { speaker, text } = cueText(lines.slice(timed + 1));
+    if (!text) continue;
+    // A cue break means nothing — captions are cut to fit a screen, mid-sentence — so cues
+    // run together, and only a change of speaker or of chapter forces a new paragraph.
+    const newPara =
+      !open || open.speaker !== speaker || Math.floor(at / CHAPTER) !== Math.floor(open.at / CHAPTER);
+    if (newPara) paras.push((open = { at, speaker, text }));
+    else open.text = joinOverlap(open.text, text);
+    if (open.text.length >= (SENTENCE_END.test(open.text) ? SOFT : HARD)) open = undefined;
+  }
+
+  const out: string[] = [];
+  let chapter = -1;
+  let voice: string | undefined;
+  const long = paras.length > 0 && paras[paras.length - 1].at >= CHAPTER;
+  for (const p of paras) {
+    if (long && Math.floor(p.at / CHAPTER) !== chapter) {
+      chapter = Math.floor(p.at / CHAPTER);
+      voice = undefined; // name the speaker again under a new heading
+      out.push(`## ${stamp(chapter * CHAPTER)}`);
+    }
+    // Label a turn, not every paragraph of one: a monologue broken for length is still one
+    // person talking, and repeating their name down the page reads as a new speaker.
+    out.push(p.speaker && p.speaker !== voice ? `**${p.speaker}:** ${p.text}` : p.text);
+    voice = p.speaker;
+  }
+  return out.join("\n\n");
+}
+
 /** Built-in, pure-JS extractors. Loaded lazily so `khb init` never pays for them. */
 const LIBRARY: Record<string, (file: string) => Promise<LibResult>> = {
+  // Subtitle sidecars. Text already, but wrapped in cue indices and timecodes, so they get
+  // an extractor rather than a verbatim copy — and the extraction cache with it, since the
+  // same captions beside a re-encoded copy of a video are the same words.
+  ".vtt": async (file) => ({ text: captionText(readFileSync(file, "utf8")) }),
+  ".srt": async (file) => ({ text: captionText(readFileSync(file, "utf8")) }),
   ".pdf": async (file) => {
     const { extractText, getDocumentProxy } = await import("unpdf");
     const doc = await getDocumentProxy(new Uint8Array(readFileSync(file)));
@@ -334,48 +460,163 @@ export async function ocrImageCached(path: string, hash: string): Promise<Extrac
   }
 }
 
-/** Probe once per process: spawning `--help` per file would cost more than it saves. */
-let whisper: string | undefined;
-async function whisperBin(): Promise<string> {
-  if (whisper !== undefined) return whisper;
-  whisper = (await runCli(["whisper", "--help"])) ? "whisper"
-    : (await runCli(["faster-whisper", "--help"])) ? "faster-whisper"
-    : "";
-  if (!whisper) console.warn(`  whisper not on PATH — transcription skipped. Install:  pip install -U openai-whisper`);
-  return whisper;
+/**
+ * Is `vno` installed, and is it actually ready to run?
+ *
+ * `vno status` exists for exactly this: it reports and installs nothing, and exits non-zero
+ * when ffmpeg or whisper.cpp or a model is missing — so a vno that is installed but never
+ * set up is caught here rather than discovered one silent per-file failure at a time.
+ * `--json` turns the same answer into the blocker list that makes khb's message actionable.
+ *
+ * An older vno predating `status` would fail this check for the wrong reason, so a
+ * response that is not JSON at all falls back to the presence test it used to get. That
+ * costs a second spawn only on the rare path.
+ */
+type VnoState =
+  | { state: "ready" }
+  | { state: "unset-up"; blockers: string[] }  // installed, but ffmpeg/whisper.cpp/model missing
+  | { state: "absent" };
+
+async function vnoStatus(): Promise<VnoState> {
+  let out: string;
+  let code: number;
+  try {
+    const proc = Bun.spawn(["vno", "status", "--json"], { stdout: "pipe", stderr: "ignore", stdin: "ignore" });
+    out = await new Response(proc.stdout).text();
+    code = await proc.exited;
+  } catch {
+    return { state: "absent" }; // not on PATH — expected, and not worth a warning
+  }
+  if (code === 0) return { state: "ready" };
+  try {
+    const blockers = JSON.parse(out).blockers;
+    return { state: "unset-up", blockers: Array.isArray(blockers) ? blockers.map(String) : [] };
+  } catch {
+    return (await runCli(["vno", "--version"])) ? { state: "ready" } : { state: "absent" };
+  }
+}
+
+/**
+ * The local speech-to-text engine, probed once per process — spawning a status check per
+ * file would cost more than it saves.
+ *
+ * `vno` (@msareen/voice-notes-organizer) is preferred where it is set up. It is whisper.cpp
+ * under a wrapper, so it is markedly faster than the Python whisper on the same audio and
+ * uses whatever acceleration the machine has; it installs its own ffmpeg and model; and it
+ * emits WebVTT, which the caption reader above turns into a transcript with `## h:mm:ss`
+ * anchors instead of an undifferentiated wall of text. Same division of labor either way: a
+ * local binary doing a reproducible conversion, contacting no model.
+ *
+ * A vno that is installed but not set up is an amber gate, never a red one. Nothing about
+ * the run stops: whisper takes over if it is there, and if it is not, the recordings pend
+ * with an empty `raw` like every other unavailable extractor and the rest of the corpus is
+ * ingested regardless. All khb owes the user is an accurate reason and the one command that
+ * fixes it — running `vno setup` on their behalf would be khb installing software nobody
+ * asked it to install.
+ */
+type Engine = { bin: string; kind: "vno" | "whisper" };
+let engine: Engine | null | undefined;
+let vnoAmber: string | undefined; // set when vno is installed but not set up
+
+async function asrEngine(): Promise<Engine | null> {
+  if (engine !== undefined) return engine;
+
+  const vno = await vnoStatus();
+  if (vno.state === "unset-up") {
+    const missing = vno.blockers.length ? `: ${vno.blockers.join(", ")}` : "";
+    vnoAmber = `vno is installed but not set up${missing} — run:  vno setup`;
+  }
+
+  engine =
+    vno.state === "ready" ? { bin: "vno", kind: "vno" }
+    : (await runCli(["whisper", "--help"])) ? { bin: "whisper", kind: "whisper" }
+    : (await runCli(["faster-whisper", "--help"])) ? { bin: "faster-whisper", kind: "whisper" }
+    : null;
+
+  // Amber: say it once, then carry on with whatever else is available.
+  if (vnoAmber) console.warn(`  ${vnoAmber}${engine ? ` (using ${engine.bin} instead)` : ""}`);
+  if (!engine) {
+    console.warn(`  no transcriber ready — audio and video skipped, everything else proceeds. Install either:`);
+    if (!vnoAmber) console.warn(`    npm install -g @msareen/voice-notes-organizer   (whisper.cpp; installs its own deps)`);
+    console.warn(`    pip install -U openai-whisper`);
+  }
+  return engine;
+}
+
+/**
+ * `vno t <file> -o <out> --no-open` — the one-shot path: no picker, no model prompt, and no
+ * requirement that the file live in vno's own library. The model is left to the user's vno
+ * settings rather than pinned here, since those are also where their acceleration lives.
+ *
+ * stdin is closed deliberately. vno offers to install a missing ffmpeg or whisper.cpp, and
+ * checks `isTTY` before asking — so a closed stdin turns that offer into printed
+ * instructions rather than a prompt with nobody there to answer it.
+ */
+async function transcribeVno(path: string, dest: string, out: string): Promise<Extraction> {
+  const tool = "vno (whisper.cpp)";
+  const vtt = join(out, "transcript.vtt");
+  const proc = Bun.spawn(["vno", "t", path, "-o", vtt, "--no-open"], {
+    stdout: "ignore",
+    stderr: "ignore",
+    stdin: "ignore",
+  });
+  await proc.exited;
+  // vno reports a missing file or an unusable dependency on stdout and still exits 0, so
+  // the transcript existing is the only signal worth trusting here.
+  if (!existsSync(vtt)) return { status: "failed", reason: "vno produced no transcript" };
+  const text = captionText(readFileSync(vtt, "utf8"));
+  if (!text) return { status: "failed", reason: "empty transcript" };
+  return { status: "ok", path: writeCache(dest, path, tool, "low", text), tool, quality: "low" };
+}
+
+/** OpenAI whisper (or faster-whisper): plain text, written into a scratch --output_dir. */
+async function transcribeWhisper(
+  path: string,
+  dest: string,
+  out: string,
+  bin: string,
+  model: string,
+): Promise<Extraction> {
+  const tool = `${bin} (${model})`;
+  const proc = Bun.spawn([bin, path, "--model", model, "--output_format", "txt", "--output_dir", out], {
+    stdout: "ignore",
+    stderr: "ignore",
+    stdin: "ignore",
+  });
+  if ((await proc.exited) !== 0) return { status: "failed", reason: `${bin} exited non-zero` };
+  const txt = readdirSync(out).find((f) => f.endsWith(".txt"));
+  if (!txt) return { status: "failed", reason: `${bin} produced no transcript` };
+  const text = readFileSync(join(out, txt), "utf8").trim();
+  if (!text) return { status: "failed", reason: "empty transcript" };
+  return { status: "ok", path: writeCache(dest, path, tool, "low", text), tool, quality: "low" };
 }
 
 /**
- * Transcribe audio or video with a local whisper binary. Video needs no demux step —
- * whisper reads the audio track directly.
+ * Transcribe audio or video locally. Video needs no demux step — both engines read the
+ * audio track directly.
  *
  * Minutes of CPU per file, so this is the one extractor worth interrupting: `khb ingest
- * --skip-audio` leaves the rows pending and everything else proceeds. Still local and
- * still deterministic-enough to belong in khb rather than in an agent pass.
+ * --skip-audio` leaves the rows pending and everything else proceeds. A recording that
+ * arrived with captions beside it never gets here at all; ingest reads those instead.
  */
 export async function transcribeCached(path: string, hash: string, model = "base"): Promise<Extraction> {
   const dest = extractedPath(hash);
   if (existsSync(dest)) return cacheHit(dest);
 
-  const bin = await whisperBin();
-  if (!bin) return { status: "failed", reason: "whisper not installed" };
+  const eng = await asrEngine();
+  // The pending row carries the reason a person can act on: "not set up" and "not installed"
+  // have different fixes, and the ledger is where this is read back weeks later.
+  if (!eng) return { status: "failed", reason: vnoAmber ?? "no transcriber installed" };
+  note(`transcribing with ${eng.bin}`);
 
-  // whisper writes <name>.txt into --output_dir rather than to stdout; give it a scratch
-  // directory of its own so a stray sibling .txt never gets mistaken for the transcript.
+  // 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));
   mkdirSync(out, { recursive: true });
-  const tool = `${bin} (${model})`;
   try {
-    const proc = Bun.spawn([bin, path, "--model", model, "--output_format", "txt", "--output_dir", out], {
-      stdout: "ignore",
-      stderr: "ignore",
-    });
-    if ((await proc.exited) !== 0) return { status: "failed", reason: `${bin} exited non-zero` };
-    const txt = readdirSync(out).find((f) => f.endsWith(".txt"));
-    if (!txt) return { status: "failed", reason: `${bin} produced no transcript` };
-    const text = readFileSync(join(out, txt), "utf8").trim();
-    if (!text) return { status: "failed", reason: "empty transcript" };
-    return { status: "ok", path: writeCache(dest, path, tool, "low", text), tool, quality: "low" };
+    return eng.kind === "vno"
+      ? await transcribeVno(path, dest, out)
+      : await transcribeWhisper(path, dest, out, eng.bin, model);
   } catch (e) {
     return { status: "failed", reason: `transcription failed: ${e}` };
   } finally {

package/scripts/lib/util.ts

@@ -124,6 +124,13 @@ export function retargetRaw(bundleDir: string, rawRel: string, source: string):
   return true;
 }
 
+/**
+ * One spelling of a path, for comparing two of them. Absolute, and case-folded on Windows,
+ * where `D:\Corpus\Talk.mp4` and `d:/corpus/talk.mp4` are the same file.
+ */
+export const normPath = (p: string) =>
+  process.platform === "win32" ? resolve(p).toLowerCase() : resolve(p);
+
 export const sha256 = (buf: Buffer | string) => createHash("sha256").update(buf).digest("hex");
 
 /** Hash a file in chunks — corpora contain multi-GB binaries we must not slurp. */

package/scripts/lint.ts

@@ -4,6 +4,9 @@ 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";
+
+rejectUnknownFlags(process.argv.slice(2), "khb lint");
 
 /** OKF v0.1 concept frontmatter. Unknown keys are warned, not rejected — OKF is permissive,
  *  but a `titel:` typo silently loses the field, so it is worth one line of noise. */

package/scripts/new-bundle.ts

@@ -3,8 +3,11 @@
 import { existsSync } from "node:fs";
 import { BUNDLES, join } from "./lib/util";
 import { createBundle, VALID_NAME } from "./lib/scaffold";
+import { rejectUnknownFlags } from "./lib/args";
 
-const [name, scope = "TODO scope"] = process.argv.slice(2);
+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)");
   process.exit(1);

package/scripts/visualize.ts

@@ -7,19 +7,24 @@
 // process. `--port N` pins a specific port.
 import { buildGraphData, readConceptFile } from "./lib/graph";
 import { renderGraphPage } from "./lib/graph-page";
+import { takeFlag, takeOpt, rejectUnknownFlags } from "./lib/args";
 
+const USAGE = "khb visualize [--port N] [--no-open]";
 const argv = process.argv.slice(2);
 // port 0 asks the OS for any free port — no fixed default to collide with something else
-// already running on the machine. Both `--port N` and `--port=N` pin it, since the docs
-// have always shown the spaced form.
-const eqArg = argv.find((a) => a.startsWith("--port="));
-const spacedArg = argv[argv.indexOf("--port") + 1];
-const requestedPort = eqArg
-  ? Number(eqArg.slice("--port=".length))
-  : argv.includes("--port") && spacedArg
-    ? Number(spacedArg)
-    : 0;
-const noOpen = argv.includes("--no-open");
+// already running on the machine. `--port N` and `--port=N` both pin it.
+const portArg = takeOpt(argv, "--port");
+const noOpen = takeFlag(argv, "--no-open");
+rejectUnknownFlags(argv, USAGE);
+
+// A port that is not a port used to become NaN and silently serve on a random one, which
+// 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}`);
+  process.exit(1);
+}
 
 function summarize(data: ReturnType<typeof buildGraphData>) {
   const concepts = Object.values(data.bundleGraphs).reduce((n, g) => n + g.concepts.length, 0);

package/skills/ingest/SKILL.md

@@ -117,6 +117,7 @@ locally. Read the summary it prints — the counts are the state of the world:
 | `unchanged, skipped` | already acquired at this exact content hash |
 | `extracted` / `reused from the extraction cache` | converted now / converted by an earlier run or another bundle |
 | `read by OCR` / `transcribed` | lossy routes — see quality, below |
+| `read from a caption sidecar` | a recording whose words were read off its `.vtt`/`.srt` instead |
 | `marked quality: low` | verify these against the source when cataloging |
 | `not extracted` | got a ledger row with an empty `raw`; the per-file line says why |
 
@@ -150,21 +151,78 @@ curation, not transcription.
 | `.xlsx` | `fflate` → one markdown table per sheet | high |
 | `.pdf` (scanned, no text layer) | `pdfium` + `tesseract.js`, automatically | **low** |
 | `.png .jpg .webp .tif .gif` | `tesseract.js`, automatically | **low** |
-| `.mp3 .wav .m4a .mp4 .mov .mkv` | local `whisper` / `faster-whisper` | **low** |
+| `.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
 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`,
+or `talk.srt`) beside `talk.mp4` is that recording's words, already written down by someone
+who could hear it — so khb reads them instead of guessing at them with whisper. The pair
+gets one `log.md` row, under the recording; the sidecar earns no row and no `raw/` file of
+its own, and the recording's `extract_tool` names the file the text came from. It is both
+free and better than transcription, so it happens even under `--skip-audio`.
+
+Two things follow. The pair's identity is *both* files, so correcting a caption re-ingests
+the recording rather than leaving a stale row marked unchanged. And khb never picks between
+sidecars: `talk.en.vtt` next to `talk.fr.vtt` is a choice about audience, so it transcribes
+instead and leaves both files to be pointed at explicitly. A caption with no recording
+beside it — or one whose recording this source does not visit, because it is excluded or
+simply not listed — is an ordinary source and gets its own row. That is also the lever:
+excluding a sidecar does not unpair it, since `exclude` governs what earns a `raw/` file and
+a paired sidecar never earns one; exclude the *recording* to have its captions ingested
+alone.
+
+The caption reader drops what belongs to the player and keeps what belongs to the
+transcript: cue indices and timecodes go, `<v Name>` becomes a speaker label, the rolling
+repetition auto-generated captions leave behind is collapsed, and anything longer than five
+minutes gets a coarse `## h:mm:ss` heading per interval so a passage can be found in the
+source recording. Quality is `high` — the words are what the file says, not what an
+extractor guessed — but auto-generated captions are still ASR underneath, so treat a
+transcript that reads like a machine wrote it the way you would treat one.
+
 **OCR needs no setup.** `@hyzyla/pdfium`, `sharp` and `tesseract.js` are dependencies of khb
 itself, so a scanned PDF or a photographed page is read on the first run, in any hub, without
 asking the user to install anything.
 
-Transcription is the one route that can be absent: it wants a `whisper` or `faster-whisper`
-executable on `PATH`.
+Transcription is the one route that can be absent. It wants a transcriber on `PATH`, and
+takes the first of these it finds:
 
 ```
-pip install -U openai-whisper                # transcription (faster-whisper also works)
+npm install -g @msareen/voice-notes-organizer   # vno — whisper.cpp, preferred
+pip install -U openai-whisper                   # whisper (faster-whisper also works)
+```
+
+`vno` is preferred where both are set up: it is whisper.cpp rather than the Python
+whisper, so it is markedly faster on the same audio and uses whatever acceleration the
+machine has, it installs its own ffmpeg and model, and it emits WebVTT — which means a
+transcript with `## h:mm:ss` anchors instead of an undifferentiated wall of text. khb runs
+it as `vno t <file> -o <cache path> --no-open` with stdin closed, so nothing is written
+beside your recordings and vno's setup offers degrade to printed instructions instead of
+prompts.
+
+khb gates on `vno status` before using it, because installed and ready are different things
+— vno needs ffmpeg, whisper.cpp and a model, and reports on all three. **A vno that is not
+set up is an amber gate, never a red one.** The run does not stop and nothing else is
+affected: whisper takes over if you have it, and if you don't, the recordings pend with an
+empty `raw` exactly like any other unavailable extractor while the rest of the corpus is
+ingested normally. What you get is the reason and the fix, on the file's own line and again
+in `log.md`:
+
 ```
+[ 3/12] D:\corpus\standup.m4a
+        no captions beside it — transcribing (minutes per file) …
+  vno is installed but not set up: ffmpeg, whisper.cpp — run:  vno setup
+        pending — vno is installed but not set up: ffmpeg, whisper.cpp — run:  vno setup
+```
+
+Run `vno setup` yourself and re-run the ingest; the pending rows fill in. khb will not run
+it for you — installing software nobody asked it to install is not a conversion step.
+
+Either engine is a local binary doing a reproducible conversion, and its output is
+`quality: low` all the same: it is a machine's guess at audio, and the recording is still
+the thing to re-read when a passage looks wrong.
 
 When any extractor is unavailable khb says so once and records the affected files as pending
 rather than failing the run — a `log.md` row with an empty `raw`, waiting for the dependency.

package/templates/hub/gitignore

@@ -5,8 +5,9 @@ bundles/*/raw/
 .claude/settings.local.json
 
 # Extraction cache (inbox/extracted/<sha256>.md) — re-derivable from the sources.
-inbox/
+/inbox/
 
-# Generated
+# 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.
 visualizer/graph.html
-export/
+/export/