@msareen/knowledge-hub-builder 0.1.7 → 0.2.0

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/log.ts

@@ -51,3 +51,43 @@ export function note(msg: string) {
 export function outcome(msg: string) {
   console.log(`         ${msg} (${secs(Date.now() - itemStart)})`);
 }
+
+/**
+ * A running counter for a walk whose units are too fast and too many to deserve a line
+ * each — thousands of files checked in milliseconds, where `item()` per file would bury
+ * the result in its own progress.
+ *
+ * On a terminal it rewrites one line in place, on **stderr**: the transient text never
+ * lands in a redirected log or a pipe, so `khb … > out.txt` still gets clean output. With
+ * no terminal it degrades to a milestone line every `every` units, so a CI log or a
+ * captured run still shows the walk moving rather than appearing hung.
+ *
+ * Always call `done()`, including on the early-exit paths — it is what erases the line.
+ */
+export function ticker(label: string, total?: number, every = 500) {
+  const tty = process.stderr.isTTY;
+  const of = total ? `/${total}` : "";
+  let n = 0;
+  let lastPaint = 0;
+  let width = 0;
+  return {
+    tick(suffix = "") {
+      n++;
+      const text = `  ${label} ${n}${of}${suffix ? ` — ${suffix}` : ""}`;
+      if (tty) {
+        // Repaint at ~12fps, not per unit: the terminal is slower than the walk, and an
+        // unthrottled counter spends more time drawing than working.
+        const now = Date.now();
+        if (now - lastPaint < 80 && n !== total) return;
+        lastPaint = now;
+        width = Math.max(width, text.length);
+        process.stderr.write(`\r${text.padEnd(width)}`);
+      } else if (n % every === 0) {
+        console.log(text);
+      }
+    },
+    done() {
+      if (tty && width) process.stderr.write(`\r${" ".repeat(width)}\r`);
+    },
+  };
+}

package/scripts/lib/registry.ts

@@ -0,0 +1,306 @@
+// The machine-level registry: ~/.khb/hubs-config.json.
+//
+// A hub is self-contained and knows nothing about the machine it sits on — that is the
+// point of the marker file. But a person with hubs in three places has no way to find
+// them from a cold terminal, so khb keeps one small file per *machine* listing where the
+// hubs are and which agent to open them with. It holds no knowledge, only paths: delete
+// it and nothing is lost but the shortcuts.
+//
+// Package-side, like paths.ts — importing this must never require a hub to exist.
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, basename } from "node:path";
+import { markerIn } from "./paths";
+
+/** $KHB_HOME overrides the location — tests and portable installs need it moveable. */
+export const KHB_HOME = process.env.KHB_HOME ? resolve(process.env.KHB_HOME) : join(homedir(), ".khb");
+export const CONFIG = join(KHB_HOME, "hubs-config.json");
+
+/** How to start an agent in a hub folder. `args` is appended after the hub is cd'd into. */
+export type AgentSpec = { command: string; args?: string[] };
+
+export type HubEntry = {
+  name: string;
+  description: string;
+  path: string;
+  added: string;
+  lastUsed?: string;
+  /**
+   * The `created` stamp from the hub's own marker. Copied here purely as an identity
+   * fingerprint: after a hub is moved, its registry entry points at nothing, and matching
+   * this against the marker at the new location is how `khb update --path` knows which dead entry
+   * is the same hub rather than a different one that also went missing.
+   */
+  created?: string;
+};
+
+export type Config = {
+  version: 1;
+  /** Key into `agents`. Empty string means "never launch anything, just show the path". */
+  defaultAgent: string;
+  agents: Record<string, AgentSpec>;
+  hubs: HubEntry[];
+};
+
+/**
+ * Shipped defaults. Both are the plain binary name — resolved on PATH at launch time, so
+ * a machine without one installed simply fails at spawn with its own error rather than
+ * khb pretending to know where it lives.
+ */
+const DEFAULT_AGENTS: Record<string, AgentSpec> = {
+  claude: { command: "claude", args: [] },
+  codex: { command: "codex", args: [] },
+};
+
+const blank = (): Config => ({
+  version: 1,
+  defaultAgent: "claude",
+  agents: { ...DEFAULT_AGENTS },
+  hubs: [],
+});
+
+/**
+ * Read the registry, creating it on first run. Never throws on a damaged file: a
+ * corrupted shortcut list must not block `khb lint` in a hub that is perfectly fine, so
+ * unreadable JSON is reported once and treated as empty.
+ */
+export function loadConfig(): Config {
+  if (!existsSync(CONFIG)) {
+    const fresh = blank();
+    saveConfig(fresh);
+    return fresh;
+  }
+  try {
+    const raw = JSON.parse(readFileSync(CONFIG, "utf8")) as Partial<Config>;
+    return {
+      version: 1,
+      defaultAgent: raw.defaultAgent ?? "claude",
+      agents: { ...DEFAULT_AGENTS, ...(raw.agents ?? {}) },
+      hubs: Array.isArray(raw.hubs) ? raw.hubs.filter((h) => h && typeof h.path === "string") : [],
+    };
+  } catch {
+    console.error(`khb: could not read ${CONFIG} — ignoring it. Fix or delete the file.`);
+    return blank();
+  }
+}
+
+export function saveConfig(cfg: Config): void {
+  mkdirSync(KHB_HOME, { recursive: true });
+  writeFileSync(CONFIG, JSON.stringify(cfg, null, 2) + "\n");
+}
+
+/**
+ * The one true spelling of a path. `resolve` is not enough on Windows, where the same
+ * folder is reachable as `C:\Users\MANASV~1\…` and `C:\Users\Manasvi Sareen\…` with
+ * different casing again on top — three strings, one directory. Registering it under two
+ * of them would list one hub twice and defeat the move repair, so every path stored in or
+ * compared against the registry goes through here first.
+ *
+ * realpath also follows symlinks, which is the behaviour we want: a hub reached through a
+ * link is the same hub as the hub itself.
+ */
+export function canonical(p: string): string {
+  const abs = resolve(p);
+  try {
+    return realpathSync.native(abs);
+  } catch {
+    return abs; // path does not exist (a moved-away hub): the resolved form is the best we have
+  }
+}
+
+/** Case-insensitive on Windows, after canonicalizing — see `canonical`. */
+const samePath = (a: string, b: string) => {
+  const [x, y] = [canonical(a), canonical(b)];
+  return process.platform === "win32" ? x.toLowerCase() === y.toLowerCase() : x === y;
+};
+
+/** Whatever the hub's own marker says about itself. Unreadable marker → nothing known. */
+export function markerFields(hub: string): { name?: string; description?: string; created?: string } {
+  const marker = markerIn(hub);
+  if (!marker) return {};
+  try {
+    const j = JSON.parse(readFileSync(join(hub, marker), "utf8"));
+    const str = (v: unknown) => (typeof v === "string" && v.trim() ? v.trim() : undefined);
+    return { name: str(j.name), description: str(j.description), created: str(j.created) };
+  } catch {
+    return {}; // a hub with an unreadable marker still deserves a listing
+  }
+}
+
+/**
+ * A one-line description for a hub. Authored in the hub's own `khb.json` (`description`),
+ * so it travels with the hub and is not a second place to maintain the same sentence;
+ * with none, describe the hub by what is in it. Deliberately does not scrape
+ * `outer.index.md` — its opening line is template boilerplate identical in every hub.
+ */
+export function describeHub(hub: string): string {
+  const own = markerFields(hub).description;
+  if (own) return own;
+  const names = bundleNames(hub);
+  if (!names.length) return "no bundles yet";
+  const shown = names.slice(0, 4).join(", ");
+  return `${names.length} bundle${names.length === 1 ? "" : "s"}: ${shown}${names.length > 4 ? ", …" : ""}`;
+}
+
+export function bundleNames(hub: string): string[] {
+  try {
+    return readdirSync(join(hub, "bundles"), { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Unique registry name for a hub: what its marker calls itself, else the folder name,
+ * suffixed if two hubs on this machine want the same one.
+ */
+function uniqueName(cfg: Config, hub: string): string {
+  const base = markerFields(hub).name ?? basename(hub) ?? "hub";
+  if (!cfg.hubs.some((h) => h.name === base)) return base;
+  for (let i = 2; ; i++) if (!cfg.hubs.some((h) => h.name === `${base}-${i}`)) return `${base}-${i}`;
+}
+
+/**
+ * Record a hub in the registry, or refresh what is already recorded. Called whenever khb
+ * resolves a hub, so hubs created before the registry existed register themselves the
+ * first time any command runs in them — no migration step, no `khb register` to remember.
+ * A user-edited name is never overwritten; the description is, since it is derived.
+ */
+export function registerHub(hub: string, opts: { name?: string; description?: string } = {}): HubEntry {
+  const path = canonical(hub);
+  const cfg = loadConfig();
+  const own = markerFields(path);
+  let entry = cfg.hubs.find((h) => samePath(resolve(h.path), path));
+  if (entry) {
+    entry.path = path;
+    // Both fields are derived from the hub, so both re-derive: rename or re-describe a hub
+    // in its own khb.json and the listing follows on the next command run there.
+    if (opts.name ?? own.name) entry.name = opts.name ?? own.name!;
+    entry.description = opts.description ?? describeHub(path);
+    entry.created = own.created;
+  } else {
+    entry = {
+      name: opts.name ?? uniqueName(cfg, path),
+      description: opts.description ?? describeHub(path),
+      path,
+      added: new Date().toISOString(),
+      created: own.created,
+    };
+    cfg.hubs.push(entry);
+  }
+  saveConfig(cfg);
+  return entry;
+}
+
+/** Stamp a hub as most recently used, so the picker can order by recency. */
+export function touchHub(hub: string): void {
+  const path = canonical(hub);
+  const cfg = loadConfig();
+  const entry = cfg.hubs.find((h) => samePath(resolve(h.path), path));
+  if (!entry) return;
+  entry.lastUsed = new Date().toISOString();
+  saveConfig(cfg);
+}
+
+export function forgetHub(nameOrPath: string): HubEntry | undefined {
+  const cfg = loadConfig();
+  const i = cfg.hubs.findIndex(
+    (h) => h.name === nameOrPath || samePath(resolve(h.path), resolve(nameOrPath)),
+  );
+  if (i < 0) return undefined;
+  const [gone] = cfg.hubs.splice(i, 1);
+  saveConfig(cfg);
+  return gone;
+}
+
+/** A registered hub whose folder no longer holds a marker — moved, deleted, or unmounted. */
+export const isAlive = (h: HubEntry): boolean => existsSync(h.path) && !!markerIn(h.path);
+
+/**
+ * Dead entries that are plausibly `hub` under its former name, best evidence first:
+ * an identical `created` stamp is proof (it is minted once, at `khb init`), a matching
+ * registry name is a guess. Returning candidates rather than picking one is deliberate —
+ * `khb update --path` acts on proof and asks when it only has a guess.
+ */
+export function relocationCandidates(hub: string): { certain: HubEntry[]; likely: HubEntry[] } {
+  const path = canonical(hub);
+  const own = markerFields(path);
+  const dead = loadConfig().hubs.filter((h) => !isAlive(h) && !samePath(resolve(h.path), path));
+  const certain = own.created ? dead.filter((h) => h.created === own.created) : [];
+  const likely = dead.filter(
+    (h) => !certain.includes(h) && h.name === (own.name ?? basename(path)),
+  );
+  return { certain, likely };
+}
+
+/**
+ * Point a registry entry at where the hub now lives. If the new location was already
+ * registered separately — a `khb` command was run there before anyone repaired the move —
+ * the two entries are the same hub, so fold the older one's history into the survivor
+ * rather than leaving a duplicate behind.
+ */
+export function relocateHub(oldPath: string, newPath: string): HubEntry {
+  const from = canonical(oldPath);
+  const to = canonical(newPath);
+  const cfg = loadConfig();
+  const stale = cfg.hubs.find((h) => samePath(resolve(h.path), from));
+  const already = cfg.hubs.find((h) => samePath(resolve(h.path), to));
+
+  const survivor = stale ?? already ?? {
+    name: uniqueName(cfg, to),
+    description: describeHub(to),
+    path: to,
+    added: new Date().toISOString(),
+  };
+  if (stale && already && stale !== already) {
+    survivor.added = [stale.added, already.added].filter(Boolean).sort()[0];
+    survivor.lastUsed = [stale.lastUsed, already.lastUsed].filter(Boolean).sort().pop();
+    cfg.hubs.splice(cfg.hubs.indexOf(already), 1);
+  }
+  if (!cfg.hubs.includes(survivor)) cfg.hubs.push(survivor);
+
+  survivor.path = to;
+  const own = markerFields(to);
+  // A name the marker states is the hub's own and survives the move. A name that was only
+  // ever the old folder's would otherwise outlive the folder — re-derive it from the new
+  // location, so the listing does not go on calling a hub after a directory that is gone.
+  if (own.name) survivor.name = own.name;
+  else if (survivor.name === basename(from)) {
+    const taken = cfg.hubs.filter((h) => h !== survivor);
+    survivor.name = uniqueName({ ...cfg, hubs: taken }, to);
+  }
+  survivor.description = describeHub(to);
+  survivor.created = own.created;
+  saveConfig(cfg);
+  return survivor;
+}
+
+/** Registered hubs, live ones first, each group most-recently-used first. */
+export function listHubs(): HubEntry[] {
+  const recency = (h: HubEntry) => Date.parse(h.lastUsed ?? h.added) || 0;
+  return loadConfig().hubs.slice().sort((a, b) => {
+    if (isAlive(a) !== isAlive(b)) return isAlive(a) ? -1 : 1;
+    return recency(b) - recency(a);
+  });
+}
+
+/** Resolve `khb go <what>` — a registry name, a 1-based list position, or a path. */
+export function findHubEntry(what: string): HubEntry | undefined {
+  const hubs = listHubs();
+  const byName = hubs.find((h) => h.name === what);
+  if (byName) return byName;
+  const n = Number(what);
+  if (Number.isInteger(n) && n >= 1 && n <= hubs.length) return hubs[n - 1];
+  return hubs.find((h) => samePath(resolve(h.path), resolve(what)));
+}
+
+export function agentFor(cfg: Config, name?: string): { name: string; spec: AgentSpec } | undefined {
+  const key = name ?? cfg.defaultAgent;
+  if (!key) return undefined;
+  const spec = cfg.agents[key];
+  // An unknown name is still usable as a bare command — someone naming an agent khb has
+  // never heard of should get their agent, not a lecture about the config file.
+  return { name: key, spec: spec ?? { command: key, args: [] } };
+}