@msareen/knowledge-hub-builder 0.1.7 → 0.2.0

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

@@ -0,0 +1,37 @@
+// One rule for `exclude:` entries in sources.yaml, shared by folder and files sources. An
+// entry that starts with a drive letter or `/` is absolute and is checked against the file's
+// absolute path; anything else is relative and checked against the file's path relative to
+// its source root (or, for `files` sources, its basename). Within either case, an entry with
+// no glob metacharacter (* ? [) is a plain prefix — it matches the path itself or anything
+// under it — and an entry with one is a Bun.Glob pattern. Bun.Glob is a global, no import
+// needed.
+import { isAbsolute } from "node:path";
+
+const isGlobPattern = (p: string) => /[*?[]/.test(p);
+const posix = (p: string) => p.replaceAll("\\", "/");
+
+type Matcher = (path: string) => boolean;
+
+function makeMatcher(patterns: string[]): Matcher {
+  const plain: string[] = [];
+  const globs: Bun.Glob[] = [];
+  for (const raw of patterns) {
+    const p = posix(raw).replace(/\/+$/, ""); // trailing slash is cosmetic on a plain entry
+    if (isGlobPattern(p)) globs.push(new Bun.Glob(p));
+    else plain.push(p);
+  }
+  return (path: string) =>
+    plain.some((p) => path === p || path.startsWith(`${p}/`)) || globs.some((g) => g.match(path));
+}
+
+/**
+ * Build an excluder from `sources.yaml`'s `exclude:` list. The returned function takes a
+ * file's absolute path and its path relative to the source (or basename, for `files`
+ * sources) and reports whether either matched an exclude entry of the corresponding kind.
+ */
+export function makeExcluder(patterns: string[] | undefined): (absPath: string, relPath: string) => boolean {
+  if (!patterns?.length) return () => false;
+  const abs = makeMatcher(patterns.filter((p) => isAbsolute(p)).map(posix));
+  const rel = makeMatcher(patterns.filter((p) => !isAbsolute(p)));
+  return (absPath: string, relPath: string) => abs(posix(absPath)) || rel(relPath);
+}

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,10 +1,11 @@
 // 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";
+import { makeExcluder } from "./exclude";
 import type { Source } from "./index";
 
 export async function ingestFiles(
@@ -15,15 +16,25 @@ export async function ingestFiles(
   opts: Options,
 ) {
   detail(`${s.paths.length} file(s) declared`);
+  const excluded = makeExcluder(s.exclude);
+  const paths = s.paths.filter((p) => !excluded(p, basename(p)));
+  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 s.paths.entries()) {
-    const at = pos(i + 1, s.paths.length);
+  for (const [i, p] of paths.entries()) {
+    const at = pos(i + 1, paths.length);
     if (!existsSync(p)) {
       item(at, p);
       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,10 +2,11 @@
 // 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";
+import { makeExcluder } from "./exclude";
 import type { Source } from "./index";
 
 export async function ingestFolder(
@@ -30,15 +31,29 @@ export async function ingestFolder(
   // take a while to enumerate, and knowing the denominator is what makes "[ 3/57]" mean
   // anything to someone deciding whether to wait.
   detail(`scanning ${s.path} …`);
-  const files = walk(s.path);
-  detail(`${files.length} file(s) found`);
+  const all = walk(s.path);
+  detail(`${all.length} file(s) found`);
+
+  // relOf is posix-normalized so an 'exclude' entry like "drafts/" behaves the same whether
+  // the corpus was walked on Windows or POSIX; it's computed once and reused for both the
+  // exclude check and the flattened raw/ filename below.
+  const relOf = (p: string) => p.slice(s.path.length + 1).replaceAll("\\", "/");
+  const excluded = makeExcluder(s.exclude);
+  const files = all.filter((p) => !excluded(p, relOf(p)));
+  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 = p.slice(s.path.length + 1).replaceAll(/[\\/]/g, "__");
-    await acquireFile(pos(i + 1, files.length), p, rel, rawDir, bundleDir, entries, c, opts);
+    const rel = relOf(p).replaceAll("/", "__");
+    await acquireFile(pos(i + 1, files.length), p, rel, rawDir, bundleDir, entries, c, scoped);
   }
   report(c);
 }

package/scripts/ingest/index.ts

@@ -14,17 +14,18 @@ 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";
 import type { Options } from "./acquire";
 
 export type Source =
-  | { type: "folder"; path: string }
-  | { type: "files"; paths: string[] }
+  | { type: "folder"; path: string; exclude?: string[] }
+  | { 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>"`);
@@ -94,6 +91,14 @@ for (const [i, s] of sources.entries()) {
       process.exit(1);
     }
   }
+  if (
+    (s.type === "folder" || s.type === "files") &&
+    s.exclude !== undefined &&
+    (!Array.isArray(s.exclude) || s.exclude.some((v: unknown) => typeof v !== "string"))
+  ) {
+    console.error(`${bundle}: ${at}.exclude must be a list of strings`);
+    process.exit(1);
+  }
 }
 if (!sources.length) {
   console.log(`${bundle}: no sources configured.`);

package/scripts/init.ts

@@ -8,22 +8,54 @@
 //
 // The mechanism itself lives in lib/upgrade.ts, because cli.ts also runs it on version
 // drift before any hub command.
-import { cpSync, mkdirSync, existsSync } from "node:fs";
-import { join, resolve, basename } from "node:path";
-import { HUB_TEMPLATE, MARKER, markerIn } from "./lib/paths";
-import { upgradeHub, syncManaged, stamp } from "./lib/upgrade";
+import { resolve, basename } from "node:path";
+import { MARKER, markerIn } from "./lib/paths";
+import { recordLocation, upgradeHub, updateHint } from "./lib/upgrade";
+import { takeOpt, rejectUnknownFlags } from "./lib/args";
 
 const upgrading = process.env.KHB_SUBCOMMAND === "upgrade";
-const [dirArg] = process.argv.slice(2);
+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.
+// 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(", ")}`);
   if (renamed) console.log(`  renamed: ${renamed} -> ${MARKER}`);
   if (pruned.length) console.log(`  removed (no longer part of the contract): ${pruned.join(", ")}`);
   console.log(`Your bundles/ and outer.index.md were not touched. Next: khb lint`);
+  const hint = updateHint(HUB);
+  if (hint) console.log(hint);
 } else {
   const hub = resolve(dirArg ?? process.cwd());
 
@@ -33,14 +65,8 @@ if (upgrading) {
     process.exit(1);
   }
 
-  mkdirSync(join(hub, "bundles"), { recursive: true });
-  cpSync(join(HUB_TEMPLATE, "outer.index.md"), join(hub, "outer.index.md"));
-  // Dotfiles: shipped unprefixed so npm doesn't swallow them, renamed on the way in.
-  // Never clobber — `khb init` may be run inside a folder that is already a git repo.
-  for (const f of ["gitignore", "gitattributes"])
-    if (!existsSync(join(hub, `.${f}`))) cpSync(join(HUB_TEMPLATE, f), join(hub, `.${f}`));
-  const synced = syncManaged(hub);
-  stamp(hub);
+  const { createHub } = await import("./lib/create");
+  const { synced, entry } = createHub(hub, { name: nameOpt, description: descOpt });
 
   console.log(`Hub created: ${hub}`);
   console.log(`  khb.json, outer.index.md, bundles/, .gitignore, .gitattributes`);
@@ -50,4 +76,5 @@ if (upgrading) {
   console.log(`  git init                              # optional, but recommended`);
   console.log(`  khb new-bundle <name> "<scope>"       # your first bundle`);
   console.log(`\nThen open this folder with Claude or Codex — both load AGENTS.md and the workflow skills.`);
+  console.log(`Registered as "${entry.name}" — from any terminal, 'khb' comes back here and starts your agent.`);
 }

package/scripts/lib/args.ts

@@ -1,8 +1,49 @@
 // Tiny argv helpers shared by the scripts that take flags. Each `take*` removes what it
 // consumed from the array, so whatever is left is the positional arguments.
-export function takeFlag(args: string[], name: string): boolean {
+export function takeFlag(args: string[], ...names: string[]): boolean {
+  for (const name of names) {
+    const i = args.indexOf(name);
+    if (i >= 0) {
+      args.splice(i, 1);
+      return true;
+    }
+  }
+  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 false;
-  args.splice(i, 1);
-  return true;
+  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/create.ts

@@ -0,0 +1,39 @@
+// Creating a hub, as a function rather than a script.
+//
+// Two callers need it and must not diverge: `khb init`, and the first-run wizard a bare
+// `khb` opens when the machine has no hubs yet. A hub made by the wizard is the same hub
+// down to the byte — the wizard only asks the questions `init` takes as flags.
+import { cpSync, mkdirSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { HUB_TEMPLATE } from "./paths";
+import { syncManaged, stamp } from "./upgrade";
+import { registerHub, type HubEntry } from "./registry";
+
+export type CreatedHub = {
+  hub: string;
+  /** Package-owned contract files copied in, for the caller to report. */
+  synced: string[];
+  entry: HubEntry;
+};
+
+export function createHub(
+  dir: string,
+  opts: { name?: string; description?: string } = {},
+): CreatedHub {
+  const hub = resolve(dir);
+  mkdirSync(join(hub, "bundles"), { recursive: true });
+  cpSync(join(HUB_TEMPLATE, "outer.index.md"), join(hub, "outer.index.md"));
+  // Dotfiles: shipped unprefixed so npm doesn't swallow them, renamed on the way in.
+  // Never clobber — a hub may be created inside a folder that is already a git repo.
+  for (const f of ["gitignore", "gitattributes"])
+    if (!existsSync(join(hub, `.${f}`))) cpSync(join(HUB_TEMPLATE, f), join(hub, `.${f}`));
+  const synced = syncManaged(hub);
+  stamp(hub, undefined, {
+    ...(opts.name ? { name: opts.name } : {}),
+    ...(opts.description ? { description: opts.description } : {}),
+  });
+  // Put it on the machine's shortcut list straight away, so a bare `khb` from any
+  // terminal can find its way back here without the user remembering the path.
+  const entry = registerHub(hub);
+  return { hub, synced, entry };
+}