@msareen/knowledge-hub-builder 0.2.2 → 0.2.3

package/AGENTS.md

@@ -137,14 +137,14 @@ From outside, pass `--hub <dir>` or set `$KHB_HUB`.
 | Command | Purpose |
 |---|---|
 | `khb lint` | validate structure against `skills/lint/SKILL.md` |
-| `khb doctor` | read-only report on the hub: version, location, per-bundle concept/raw/backlog counts, transcriber, and the command that fixes each finding. Writes nothing, and does not duplicate `lint` |
+| `khb doctor` | read-only report on the hub: version, location, per-bundle concept/raw/backlog counts, transcriber, the machine config's schema findings, and the command that fixes each finding. Writes nothing, and does not duplicate `lint` |
 | `khb upgrade` | refresh this hub's package-owned contract docs — runs by itself whenever `khb.json`'s stamped version differs from the installed khb, so these docs always match the CLI |
 | `khb visualize [--port N] [--no-open]` | serve the live bundle graph in your browser; aliases `vis`, `viz` |
 | `khb new-bundle <name>` | scaffold + register a bundle |
 | `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 |
 
-These five work **outside** any hub, against a per-machine shortcut list at
+These six work **outside** any hub, against a per-machine shortcut list at
 `~/.khb/hubs-config.json` (`%USERPROFILE%\.khb` on Windows). They hold no knowledge — only
 paths — and fill themselves in as hubs are used, so they need no maintenance.
 
@@ -154,7 +154,8 @@ paths — and fill themselves in as hubs are used, so they need no maintenance.
 | `khb go [name\|N]` | open a hub — prints its path, then launches your agent there. Bare `khb` is this: one hub asks, several offer a list, none walks the user through creating the first. `--path` prints only the path |
 | `khb agent [name]` | which agent `khb go` launches — `claude`, `codex`, a custom `--command`, or `none` |
 | `khb update [new-path]` | repair the hub: `--path`/`-p` repoints the list and rewrites every old-path reference after a move (needs no arguments — the move is detected and announced by any khb command run there); `--schema`/`-s` backfills a bundle's `sources.yaml` to the current schema (e.g. a newly added `exclude:` field). No flag runs both. `--dry-run` first. Unrelated to `khb upgrade`, which only touches package-owned contract docs, never bundle content |
-| `khb forget <name>` | drop a shortcut; the hub folder is untouched |
+| `khb forget <name> [more…]` | drop one or more shortcuts; the hub folders are untouched. Every target is resolved before any is removed, so list positions (`khb forget 1 2`) mean what they meant when you typed them. With no name it points at `khb list` |
+| `khb config [view\|edit\|check\|fix\|path]` | the machine config itself: `view` prints it, `edit` opens it in the OS default editor, `check` validates it against the schema, `fix` repairs what can be repaired mechanically (`--dry-run`, `--prune` to drop dead shortcuts), `path` prints just the location. `khb doctor` reports the same findings but never writes |
 
 A hub's `name` and `description` in that list come from its own `khb.json`, so they travel
 with it. Set them at creation with `khb init --name --description`, or edit the marker's

package/README.md

@@ -257,6 +257,11 @@ Commands can be run directly or requested through the matching agent skill.
 
 Run against a hub outside the current directory with `--hub <dir>` or `$KHB_HUB`.
 
+Output is colour-coded when the stream is a terminal — headings, the commands you can
+type next, paths, and the difference between an error, a warning and a clean result.
+`NO_COLOR=1` turns it off, `FORCE_COLOR=1` keeps it through a pipe, and a redirected
+stdout is plain text either way.
+
 ### `khb doctor` — what state is this hub in?
 
 A single read-only report. It writes nothing and repairs nothing; each finding names the
@@ -264,6 +269,7 @@ command that does.
 
 ```text
 Hub            name, description, stamped version vs installed, location, registered
+Machine config where it is, the agent it names, how many hubs, schema findings
 Bundles        per bundle: concepts, raw/ files, log.md rows, catalog backlog, pending
 Extraction     which formats are bundled, and whether a transcriber is ready
 Findings       what needs attention, each with its fix
@@ -289,7 +295,8 @@ These run **outside** any hub, from any terminal:
 | `khb go [name\|N] [--path] [--no-agent] [--agent X]` | Open one by name or list position. `--path` prints just the path, for `cd "$(khb go --path work)"`; `--no-agent` prints the path and the `cd` line without launching anything; `--agent X` launches `X` for this run only, leaving the configured default alone |
 | `khb agent [name\|none] [--command X] [--args "…"]` | Which agent `khb go` launches — `claude`, `codex`, anything on your PATH, or `none` to just print the path |
 | `khb update [new-path] [--path\|-p] [--schema\|-s] [--from <old>] [--dry-run]` | Repair the hub: path references after a move, and/or backfill `sources.yaml` to the current schema. No flag runs both |
-| `khb forget <name>` | Drop a hub from the list. The folder is untouched |
+| `khb forget <name> [more…]` | Drop one or more hubs from the list. The folders are untouched. With no name it points you at `khb list` for the names |
+| `khb config [view\|edit\|check\|fix\|path]` | The config file itself — see below |
 
 `khb go` prints the hub's path and then starts your agent there, so a bare `khb` from a
 cold terminal ends with an agent open on the right folder. No program can change its
@@ -305,6 +312,39 @@ A hub's name and description come from its own `khb.json`, so they travel with t
 rather than living in one machine's list. Set them with `khb init --name --description`,
 or edit those two keys in the marker later.
 
+### `khb config` — the file itself
+
+The list is plain JSON and always has been editable by hand. These five reach it without
+hunting for the path, and say something when a hand edit has gone wrong:
+
+```bash
+khb config              # or 'view' — the path, the file, and a findings count
+khb config edit         # open it in whatever this machine opens .json with
+khb config check        # validate it against the schema
+khb config fix          # repair what can be repaired mechanically
+khb config fix --dry-run --prune   # preview; --prune also drops dead shortcuts
+khb config path         # just the path, for cat "$(khb config path)"
+```
+
+The reason `check` exists: `loadConfig` is forgiving on purpose — it ignores keys it does
+not know and treats an unparseable file as an empty one, so a damaged registry never
+blocks `khb lint` in a hub that is fine. The cost is silence. A `defaultagent` typo does
+nothing at all, a pasted duplicate makes `khb forget` look broken, and a stray comma
+loses you every shortcut with no message anywhere. `check` names each of those, `fix`
+repairs the mechanical ones — canonicalizing paths, merging duplicate entries, dropping
+keys the schema does not define, re-deriving a name or description that has drifted from
+the hub's own `khb.json` — and leaves anything needing a decision to you, with the
+command that settles it.
+
+`khb doctor` runs the same checks and prints the same fixes, so a hub health check covers
+the machine config too. Doctor never writes; `khb config fix` is the half that does.
+
+Two things `fix` will not do on its own: drop a shortcut whose folder has gone (that is
+`--prune`, or `khb forget` — a missing path can be an unplugged drive, and a moved hub
+wants `khb update --path`, not forgetting), and rename a hub. A name is re-derived from
+each hub's own `khb.json` every time a command runs there, so renaming the entry would
+be undone on the next command — the rename belongs in the marker.
+
 ### `khb update` — repairing a hub
 
 Two independent repairs, run together or apart:

package/SPEC.md

@@ -123,9 +123,12 @@ acting on them** — an agent can never read a protocol the CLI no longer implem
 │   ├── lint.ts                # enforce skills/lint/SKILL.md across the hub
 │   ├── doctor.ts              # read-only state report; writes nothing, repairs nothing
 │   ├── visualize.ts           # serve the live bundle graph from indexes + refs
+│   ├── config.ts              # khb config: view / edit / check / fix the machine config
 │   ├── ingest/                # folder.ts / files.ts / web.ts → acquire.ts → bundle/raw
 │   └── lib/
 │       ├── args.ts            # argv helpers; what they consume they remove, leaving positionals
+│       ├── color.ts           # semantic terminal colour; one palette per stream
+│       ├── config-check.ts    # the machine config's schema: findings + the repairs for them
 │       ├── create.ts          # making a hub, shared by `khb init` and the first-run wizard
 │       ├── extract.ts         # every local extractor + the content-hash cache
 │       ├── graph.ts           # graph data for the visualizer — read-only, never writes
@@ -187,8 +190,9 @@ Three properties define it:
   Delete it and nothing is lost — the next command run inside each hub puts it back.
 - **It fills itself in.** Every khb command that resolves a hub registers it, so hubs made
   before the registry existed appear the first time anything is run in them. There is no
-  migration and no `register` command to remember. `khb forget <name>` drops a shortcut and
-  never touches the folder.
+  migration and no `register` command to remember. `khb forget <name> [more…]` drops one or more
+  shortcuts and never touches the folders. Every target is resolved before any is removed,
+  so list positions still mean what they meant when the command was typed.
 - **The hub is the authority on its own identity.** `name` and `description` are read out
   of the hub's `khb.json` (`khb init --name --description`, or edit the file), so a hub
   moved to another machine or cloned by a colleague describes itself the same way there.
@@ -196,9 +200,9 @@ Three properties define it:
   the bundles inside. `khb upgrade` merges rather than replaces the marker, so keys khb
   does not own survive an upgrade.
 
-The commands over it are `khb list`, `khb go`, `khb agent`, `khb update` and `khb forget` —
-the only ones that run **outside** a hub, and therefore the only ones that skip hub
-resolution and the version drift check. A bare `khb` is `khb go`: one hub asks to open it,
+The commands over it are `khb list`, `khb go`, `khb agent`, `khb update`, `khb forget` and
+`khb config` — the only ones that run **outside** a hub, and therefore the only ones that
+skip hub resolution and the version drift check. A bare `khb` is `khb go`: one hub asks to open it,
 several show the list and take a pick, none prints the help.
 
 `khb go` ends by launching your configured agent with the hub as its working directory.
@@ -206,6 +210,18 @@ No process can change its parent shell's directory, so `khb go` prints the `cd`
 the human and passes the path to the agent as cwd — `khb go --path <name>` prints only the
 path, for `cd "$(khb go --path work)"`. `khb agent none` turns the launch off entirely.
 
+**The file is hand-editable, so it is also checked.** `loadConfig` is deliberately
+forgiving — unknown keys ignored, a file that will not parse treated as empty — which is
+right at load time and wrong as the only feedback anyone gets: a typo'd `defaultagent`
+silently does nothing, and broken JSON silently costs you every shortcut. So the schema
+is stated once, in `lib/config-check.ts`, as findings with repairs attached. `khb config
+check` lists them, `khb config fix` applies the mechanical ones, and `khb doctor` reports
+them without writing. A finding carries a repair only when the fix loses nothing:
+canonicalizing a path, merging a duplicate entry, re-deriving a stale name from the hub's
+own marker. Anything needing a human decision — which of two same-named hubs to rename,
+whether a missing folder was deleted or is on an unplugged drive — is reported with the
+command to run and left alone.
+
 Every path stored in or compared against the registry is canonicalized first (`realpath`,
 case-folded on Windows). One directory has several true names — `C:\Users\MANASV~1\…` and
 `C:\Users\Manasvi Sareen\…` are the same folder, as is anything reached through a symlink —

package/package.json

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

@@ -2,6 +2,7 @@
 // khb — the CLI. Subcommands are loaded lazily: `init` must run before a hub exists,
 // so nothing that resolves a hub may be imported at module scope.
 import { version, findHub, markerIn, MARKER } from "./lib/paths";
+import { paint, paintErr } from "./lib/color";
 
 const COMMANDS: Record<string, { load: () => Promise<unknown>; usage: string; desc: string }> = {
   init: { load: () => import("./init"), usage: 'khb init [dir] [--name N] [--description "…"]', desc: "create a hub here (or in dir)" },
@@ -36,14 +37,23 @@ const COMMANDS: Record<string, { load: () => Promise<unknown>; usage: string; de
     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|path>", desc: "drop a hub from the list (folder untouched)" },
+  forget: {
+    load: () => import("./hubs"),
+    usage: "khb forget <name|path> [more…]",
+    desc: "drop one or more hubs from the list (folders untouched)",
+  },
+  config: {
+    load: () => import("./config"),
+    usage: "khb config [view|edit|check|fix|path]",
+    desc: "the machine config: show it, open it, validate it, repair it",
+  },
 };
 
 /**
  * Commands that work *outside* a hub, against ~/.khb/hubs-config.json. They must not
  * resolve or upgrade a hub — their whole job is running before you are in one.
  */
-const REGISTRY_COMMANDS = new Set(["list", "go", "agent", "forget", "update"]);
+const REGISTRY_COMMANDS = new Set(["list", "go", "agent", "forget", "update", "config"]);
 
 // Short forms that just resolve to a canonical command above — kept out of COMMANDS
 // itself so help text lists each command once. `-v` is taken by --version, so
@@ -79,19 +89,20 @@ if (cmd === "help" || cmd === "--help" || cmd === "-h") {
   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);
+    console.log(paint.head(title));
     for (const name of names) {
-      const c = COMMANDS[name];
-      if (c.usage.length > width) {
-        console.log(`  ${c.usage}`);
-        console.log(`  ${" ".repeat(width)}   ${c.desc}`);
+      const entry = COMMANDS[name];
+      // Pad before painting: escape sequences have width in the string and none on screen.
+      if (entry.usage.length > width) {
+        console.log(`  ${paint.cmd(entry.usage)}`);
+        console.log(`  ${" ".repeat(width)}   ${entry.desc}`);
       } else {
-        console.log(`  ${c.usage.padEnd(width)}   ${c.desc}`);
+        console.log(`  ${paint.cmd(entry.usage.padEnd(width))}   ${entry.desc}`);
       }
     }
   };
 
-  console.log(`khb ${version()} — Knowledge Hub Builder`);
+  console.log(`${paint.head(`khb ${version()}`)} — Knowledge Hub Builder`);
   console.log();
   console.log(`khb is the supporting tool: it handles deterministic extraction, file plumbing,`);
   console.log(`validation, and export. Your AI agent — Claude, Codex, Gemini, or another`);
@@ -109,14 +120,16 @@ 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(`         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`);
+  const label = (text: string) => paint.head(text.padEnd(9));
+  console.log(`${label("Global:")}${paint.cmd("--hub <dir>")}              operate on that hub instead of searching upward from cwd`);
+  console.log(`${" ".repeat(9)}${paint.cmd("help | --help | -h")}       this help          ${paint.cmd("--version | -v")}   version`);
+  console.log(`${label("Env:")}${paint.cmd("KHB_HUB")}                  same as --hub`);
+  console.log(`${" ".repeat(9)}${paint.cmd("KHB_HOME")}                 where the hub list lives (default ~/.khb)`);
+  console.log(`${" ".repeat(9)}${paint.cmd("KHB_NO_AUTO_UPGRADE")}      don't refresh a hub's contract docs on version drift`);
+  console.log(`${label("Colour:")}on when stdout is a terminal — ${paint.cmd("NO_COLOR")} turns it off, ${paint.cmd("FORCE_COLOR")} forces it on`);
+  console.log(`${label("Exit:")}0 on success, 1 on a usage error or a failure. An unknown option is an error;`);
+  console.log(`${" ".repeat(9)}a source khb cannot extract is not — it becomes a pending row in log.md.`);
+  console.log(`${label("Docs:")}${paint.path("https://github.com/msareen/knowledge-hub-builder")}`);
   process.exit(0);
 }
 
@@ -127,8 +140,8 @@ if (cmd === "--version" || cmd === "-v") {
 
 const entry = COMMANDS[cmd];
 if (!entry) {
-  console.error(`Unknown command: ${cmd}`);
-  console.error(`Try: khb help`);
+  console.error(`${paintErr.bad("Unknown command:")} ${cmd}`);
+  console.error(`Try: ${paintErr.cmd("khb help")}`);
   process.exit(1);
 }
 
@@ -154,9 +167,13 @@ if (cmd !== "init" && cmd !== "upgrade" && !REGISTRY_COMMANDS.has(cmd)) {
     const { recordLocation } = await import("./lib/upgrade");
     const { moved } = recordLocation(hub);
     if (moved) {
-      console.error(`khb: this hub was at ${moved} and is now at ${hub}.`);
-      console.error(`khb:   absolute paths recorded inside it still name the old location.`);
-      console.error(`khb:   repair them:  khb update --path           (--dry-run to preview)`);
+      console.error(
+        `${paintErr.warn("khb:")} this hub was at ${paintErr.path(moved)} and is now at ${paintErr.path(hub)}.`,
+      );
+      console.error(`${paintErr.warn("khb:")}   absolute paths recorded inside it still name the old location.`);
+      console.error(
+        `${paintErr.warn("khb:")}   repair them:  ${paintErr.cmd("khb update --path")}           (--dry-run to preview)`,
+      );
     }
   }
   if (hub && !process.env.KHB_NO_AUTO_UPGRADE) {
@@ -166,10 +183,13 @@ if (cmd !== "init" && cmd !== "upgrade" && !REGISTRY_COMMANDS.has(cmd)) {
       const { from, to, pruned, renamed } = upgradeHub(hub);
       // stderr, so a command's own output stays pipeable.
       console.error(
-        `khb: hub was built by ${from ?? "an unknown version"}, khb is ${to} — refreshed its contract docs.`,
+        `${paintErr.warn("khb:")} hub was built by ${from ?? "an unknown version"}, khb is ${to} — refreshed its contract docs.`,
       );
-      if (renamed) console.error(`khb:   renamed ${renamed} -> khb.json`);
-      if (pruned.length) console.error(`khb:   removed (no longer part of the contract): ${pruned.join(", ")}`);
+      if (renamed) console.error(`${paintErr.warn("khb:")}   renamed ${renamed} -> khb.json`);
+      if (pruned.length)
+        console.error(
+          `${paintErr.warn("khb:")}   removed (no longer part of the contract): ${pruned.join(", ")}`,
+        );
       const hint = updateHint(hub);
       if (hint) console.error(hint);
     }

package/scripts/config.ts

@@ -0,0 +1,229 @@
+// khb config — view, edit, check and repair the machine-level config.
+//
+// ~/.khb/hubs-config.json is the only khb file that is neither knowledge nor package-owned:
+// it is this machine's shortcut list plus the agent `khb go` launches. It has always been
+// hand-editable — the README says where it lives and what is in it — but nothing pointed at
+// it from the CLI, and nothing ever told you when a hand edit had gone wrong. `loadConfig`
+// is forgiving by design (unknown keys ignored, unparseable file treated as empty), so a
+// typo costs you your hub list with no message at all.
+//
+// So: `view` and `edit` to reach it without hunting for the path, `check` to say what is
+// wrong, `fix` to repair what can be repaired mechanically. The rules live once, in
+// lib/config-check.ts, and `khb doctor` reads the same checker — doctor reports and never
+// writes, this is where the writing happens.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { checkConfig, pruneDead, type Finding } from "./lib/config-check";
+import { CONFIG, KHB_HOME, loadConfig, saveConfig } from "./lib/registry";
+import { takeFlag, rejectUnknownFlags } from "./lib/args";
+import { detail, section, totalElapsed } from "./lib/log";
+import { paint, paintErr } from "./lib/color";
+
+const USAGE = "khb config [view|edit|check|fix|path] [--json] [--dry-run] [--prune]";
+const argv = process.argv.slice(2);
+
+const asJson = takeFlag(argv, "--json");
+const dryRun = takeFlag(argv, "--dry-run");
+const prune = takeFlag(argv, "--prune");
+rejectUnknownFlags(argv, USAGE);
+
+// Bare `khb config` shows the file. A command whose default action is read-only is the
+// right default for the one file whose corruption costs you every shortcut you have.
+const action = argv[0] ?? "view";
+if (argv.length > 1) {
+  console.error(`${paintErr.bad("Too many arguments:")} ${argv.slice(1).join(" ")}`);
+  console.error(`Usage: ${paintErr.cmd(USAGE)}`);
+  process.exit(1);
+}
+
+/** Ensure the file exists before anyone is told to look at it — first run has none. */
+function ensureExists(): void {
+  if (!existsSync(CONFIG)) saveConfig(loadConfig());
+}
+
+function printFinding(finding: Finding): void {
+  const tag = finding.level === "error" ? paint.bad("ERROR") : paint.warn("warn ");
+  console.log(`  ${tag} ${finding.what}`);
+  console.log(`        ${paint.dim(finding.repair ? "fix (automatic):" : "fix:")} ${paint.cmd(finding.fix)}`);
+}
+
+/** The closing line every action shares: how many findings stand, and what clears them. */
+function summarize(findings: Finding[]): void {
+  const errors = findings.filter((finding) => finding.level === "error").length;
+  const repairable = findings.filter((finding) => finding.repair).length;
+  if (!findings.length) {
+    console.log(`\n${paint.ok("no problems found")} in ${totalElapsed()}`);
+    return;
+  }
+  console.log(
+    `\n${paint.head("config")}: ${errors ? paint.bad(`${errors} error(s)`) : paint.ok("0 errors")}, ` +
+      `${paint.warn(`${findings.length - errors} warning(s)`)} in ${totalElapsed()}`,
+  );
+  if (repairable)
+    console.log(`${repairable} of them can be repaired for you:  ${paint.cmd("khb config fix")}`);
+}
+
+// ------------------------------------------------------------------------------- path
+
+if (action === "path") {
+  // Deliberately bare, so `cat "$(khb config path)"` works. Nothing else on stdout.
+  console.log(CONFIG);
+  process.exit(0);
+}
+
+// ------------------------------------------------------------------------------- view
+
+if (action === "view") {
+  ensureExists();
+  const text = readFileSync(CONFIG, "utf8");
+  if (asJson) {
+    // The file itself, verbatim — pipeable into jq. No header, no findings.
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+    process.exit(0);
+  }
+  console.log(`${paint.head("khb config")} → ${paint.path(CONFIG)}\n`);
+  process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+
+  const { findings } = checkConfig({ probeAgent: false });
+  if (findings.length) {
+    console.log(
+      `\n${paint.warn(`${findings.length} finding(s)`)} — see them in full:  ${paint.cmd("khb config check")}`,
+    );
+  }
+  console.log(paint.dim(`Edit it:  khb config edit        Repair it:  khb config fix`));
+  process.exit(0);
+}
+
+// ------------------------------------------------------------------------------- edit
+
+if (action === "edit") {
+  ensureExists();
+  console.log(`${paint.head("khb config")} → ${paint.path(CONFIG)}`);
+
+  // The OS association, the same way `khb visualize` opens a browser: whatever this machine
+  // already opens a .json with is the editor the person has actually chosen. $EDITOR is not
+  // consulted — a terminal editor launched detached would draw over this session.
+  const command =
+    process.platform === "win32"
+      ? ["cmd", "/c", "start", "", CONFIG] // the empty string is start's window-title argument
+      : process.platform === "darwin"
+        ? ["open", CONFIG]
+        : ["xdg-open", CONFIG];
+
+  const launched = spawnSync(command[0], command.slice(1), { stdio: "ignore" });
+  if (launched.error || (launched.status ?? 0) !== 0) {
+    console.error(`\n${paintErr.warn("Could not open an editor")} — open the path above yourself.`);
+    process.exit(1);
+  }
+
+  console.log(`  ${paint.dim("opened in your default editor for .json")}`);
+  // The editor is detached, so khb cannot wait for the save and validate it. Say what to run
+  // instead — a config that stops parsing is silently treated as empty, which is exactly the
+  // failure someone editing by hand is most likely to cause and least likely to notice.
+  console.log(`\nWhen you have saved it:  ${paint.cmd("khb config check")}`);
+  console.log(paint.dim(`An unparseable file is ignored in full — khb would act as if you had no hubs.`));
+  process.exit(0);
+}
+
+// ------------------------------------------------------------------------------ check
+
+if (action === "check") {
+  console.log(`${paint.head("khb config check")} → ${paint.path(CONFIG)}`);
+  const report = checkConfig();
+  if (!report.exists) {
+    detail(`no config yet — it is written the first time khb registers a hub`);
+    process.exit(0);
+  }
+  section(report.findings.length ? `Findings (${report.findings.length})` : "Findings");
+  if (!report.findings.length) detail(paint.ok("none — nothing here needs attention."));
+  else for (const finding of report.findings) printFinding(finding);
+  summarize(report.findings);
+  // Exit 0 with findings, like `khb lint` and `khb doctor`: the exit code says the command
+  // ran, not that the thing it inspected is perfect.
+  process.exit(0);
+}
+
+// -------------------------------------------------------------------------------- fix
+
+if (action === "fix") {
+  console.log(`${paint.head("khb config fix")}${dryRun ? paint.dim(" (dry run)") : ""} → ${paint.path(CONFIG)}`);
+  const first = checkConfig();
+  if (!first.exists) {
+    detail(`no config yet — nothing to repair`);
+    process.exit(0);
+  }
+  if (!first.readable) {
+    // Every repair works on the parsed config, and there is none. Rewriting from the
+    // normalized (empty) view would silently delete every shortcut in the file.
+    section("Findings");
+    for (const finding of first.findings) printFinding(finding);
+    console.log(`\n${paintErr.bad("Nothing can be repaired while the file does not parse.")}`);
+    console.log(`Fix the JSON by hand:  ${paint.cmd("khb config edit")}`);
+    process.exit(1);
+  }
+
+  section("Repairs");
+  const applied: string[] = [];
+  // One repair per pass, re-checking in between. Repairs interact — canonicalizing a path
+  // changes the key a later repair looks its entry up by, and merging a duplicate shifts
+  // every index after it — so the honest way to apply a set of them is to apply one and
+  // ask again. It converges: each pass either clears a finding or stops.
+  let previous = "";
+  for (let pass = 0; pass < 100; pass++) {
+    const { findings } = checkConfig({ probeAgent: false });
+    const next = findings.find((finding) => finding.repair);
+    if (!next) break;
+    if (next.what === previous) {
+      // The repair ran and the finding came back: report it rather than loop.
+      console.log(`  ${paint.warn("could not repair:")} ${next.what}`);
+      break;
+    }
+    previous = next.what;
+    if (dryRun) {
+      // Nothing is written, so re-checking would return the same finding forever. Show the
+      // whole repairable set in one go instead of walking it.
+      for (const finding of findings.filter((each) => each.repair))
+        console.log(`  ${paint.dim("would fix:")} ${finding.what}`);
+      break;
+    }
+    const cfg = loadConfig();
+    next.repair!(cfg);
+    saveConfig(cfg);
+    applied.push(next.what);
+    console.log(`  ${paint.ok("fixed:")} ${next.what}`);
+  }
+
+  if (prune) {
+    const cfg = loadConfig();
+    const dead = pruneDead(cfg);
+    if (!dead.length) detail(`--prune: no dead shortcuts to drop`);
+    else if (dryRun)
+      for (const entry of dead)
+        console.log(`  ${paint.dim("would drop:")} ${entry.name} (${entry.path})`);
+    else {
+      saveConfig(cfg);
+      for (const entry of dead)
+        console.log(`  ${paint.ok("dropped:")} ${entry.name} ${paint.path(`(${entry.path})`)}`);
+      console.log(paint.dim(`  the folders themselves are untouched`));
+    }
+  }
+
+  if (!applied.length && !dryRun) detail(`nothing to repair automatically`);
+
+  // What is left is what needed a person. Say so explicitly rather than reporting success
+  // on a config that still has problems in it.
+  const after = checkConfig();
+  const manual = after.findings.filter((finding) => !finding.repair);
+  if (manual.length) {
+    section(`Left for you (${manual.length})`);
+    for (const finding of manual) printFinding(finding);
+  }
+  summarize(after.findings);
+  if (dryRun) console.log(`Re-run without ${paint.cmd("--dry-run")} to apply.`);
+  process.exit(0);
+}
+
+console.error(`${paintErr.bad("Unknown action:")} ${action}`);
+console.error(`Usage: ${paintErr.cmd(USAGE)}`);
+console.error(`The config lives at ${paintErr.path(CONFIG)} (${paintErr.dim(`$KHB_HOME is ${KHB_HOME}`)})`);
+process.exit(1);

package/scripts/doctor.ts

@@ -16,9 +16,11 @@ import { staleLocations, hubVersion } from "./lib/upgrade";
 import { diffSourcesYamlAll } from "./lib/schema";
 import { transcriberStatus } from "./lib/extract";
 import { version, MARKER, markerIn } from "./lib/paths";
-import { listHubs, canonical } from "./lib/registry";
+import { listHubs, canonical, loadConfig, agentFor, isAlive } from "./lib/registry";
+import { checkConfig } from "./lib/config-check";
 import { section, detail, totalElapsed } from "./lib/log";
 import { rejectUnknownFlags } from "./lib/args";
+import { paint } from "./lib/color";
 import { readdirSync, statSync } from "node:fs";
 import { relative } from "node:path";
 
@@ -26,9 +28,10 @@ rejectUnknownFlags(process.argv.slice(2), "khb doctor");
 
 /** Findings are advisory: doctor's exit code reports whether it ran, not what it found. */
 const findings: string[] = [];
-const flag = (msg: string, fix?: string) => findings.push(fix ? `${msg}\n      fix: ${fix}` : msg);
+const flag = (msg: string, fix?: string) =>
+  findings.push(fix ? `${msg}\n      ${paint.dim("fix:")} ${paint.cmd(fix)}` : msg);
 
-console.log(`khb doctor → ${HUB}`);
+console.log(`${paint.head("khb doctor")} → ${paint.path(HUB)}`);
 
 // ---- Hub identity -----------------------------------------------------------------------
 const marker = (() => {
@@ -78,6 +81,29 @@ if (stale.length)
 const registered = listHubs().some((entry) => canonical(entry.path) === canonical(HUB));
 detail(`registered    ${registered ? "yes" : "no — 'khb list' and 'khb go' will not offer it"}`);
 
+// ---- Machine config ---------------------------------------------------------------------
+// Not about this hub — about the file that lists every hub on the machine and names the
+// agent `khb go` launches. It belongs in doctor because it fails the same way a hub does:
+// quietly. `loadConfig` ignores what it cannot read, so a hand edit that broke the JSON
+// costs you every shortcut with no message anywhere. The rules live in lib/config-check.ts;
+// doctor reports them and `khb config fix` is the half that writes.
+section("Machine config");
+const configReport = checkConfig();
+detail(`file          ${configReport.path}`);
+if (!configReport.exists) detail(`state         not written yet — created the first time khb registers a hub`);
+else {
+  const machineConfig = loadConfig();
+  const agent = agentFor(machineConfig);
+  detail(`agent         ${agent ? `${agent.name} (${agent.spec.command})` : "none — khb go prints the path"}`);
+  const hubs = listHubs();
+  const missing = hubs.filter((entry) => !isAlive(entry)).length;
+  detail(`hubs          ${hubs.length} registered${missing ? `, ${missing} missing` : ""}`);
+  detail(
+    `schema        ${configReport.findings.length ? `${configReport.findings.length} finding(s)` : "clean"}`,
+  );
+}
+for (const finding of configReport.findings) flag(`config: ${finding.what}`, finding.fix);
+
 // ---- sources.yaml schema ----------------------------------------------------------------
 const schemaDiffs = diffSourcesYamlAll(HUB);
 if (schemaDiffs.length) {
@@ -108,7 +134,7 @@ const bundles = listBundles();
 section(`Bundles (${bundles.length})`);
 
 if (!bundles.length) {
-  detail("none yet — khb new-bundle <name> \"scope\"");
+  detail(`none yet — ${paint.cmd('khb new-bundle <name> "scope"')}`);
 } else {
   const summaries = bundles.map((bundle) => {
     const dir = join(BUNDLES, bundle);
@@ -169,9 +195,12 @@ if (!transcriber.ready)
 
 // ---- Findings ---------------------------------------------------------------------------
 section(findings.length ? `Findings (${findings.length})` : "Findings");
-if (!findings.length) detail("none — nothing here needs attention.");
-else for (const finding of findings) detail(`- ${finding}`);
+if (!findings.length) detail(paint.ok("none — nothing here needs attention."));
+else for (const finding of findings) detail(`${paint.warn("-")} ${finding}`);
 
 section("Next");
-detail("khb lint      structural and OKF validation (doctor does not duplicate it)");
-console.log(`\ndoctor: ${findings.length} finding(s) across ${bundles.length} bundle(s) in ${totalElapsed()}`);
+detail(`${paint.cmd("khb lint")}      structural and OKF validation (doctor does not duplicate it)`);
+console.log(
+  `\n${paint.head("doctor")}: ${findings.length ? paint.warn(`${findings.length} finding(s)`) : paint.ok("no findings")} ` +
+    `across ${bundles.length} bundle(s) in ${totalElapsed()}`,
+);

package/scripts/export.ts

@@ -5,19 +5,20 @@ import { cpSync, writeFileSync, mkdirSync, existsSync, readFileSync } from "node
 import { HUB, bundleDir, join } from "./lib/util";
 import { detail, totalElapsed } from "./lib/log";
 import { rejectUnknownFlags } from "./lib/args";
+import { paint, paintErr } from "./lib/color";
 
 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); }
+if (!name) { console.error(`Usage: ${paintErr.cmd("khb export <bundle> [dest]")}`); process.exit(1); }
 
 const src = bundleDir(name);
 const dest = destArg ?? join(HUB, "export", name);
-if (existsSync(dest)) { console.error(`Destination exists: ${dest}`); process.exit(1); }
+if (existsSync(dest)) { console.error(`${paintErr.bad("Destination exists:")} ${paintErr.path(dest)}`); process.exit(1); }
 
-console.log(`khb export → ${name}`);
+console.log(`${paint.head("khb export")} → ${paint.name(name)}`);
 detail(`from: ${src}`);
 detail(`to:   ${dest}`);
 
@@ -44,4 +45,7 @@ writeFileSync(join(dest, "outer.index.md"),
 writeFileSync(join(dest, "README.md"),
   `# ${name} (exported KHB bundle)\n\nExported: ${new Date().toISOString()}\nOrigin: KHB bundle-of-bundles repo.\n\nStandalone unit: start at AGENTS.md → outer.index.md → bundle/index.md.\nWorkflow protocols (query, ingest, lint, …) live in skills/<name>/SKILL.md and are discoverable by Claude and Codex.\nNote: refs.md entries pointing at other bundles will not resolve here.\n`);
 
-console.log(`\nExported to ${dest} in ${totalElapsed()} (bundle + agent contracts, skills, single-bundle router)`);
+console.log(
+  `\n${paint.ok("Exported to")} ${paint.path(dest)} in ${totalElapsed()} ` +
+    paint.dim("(bundle + agent contracts, skills, single-bundle router)"),
+);