@msareen/knowledge-hub-builder 0.2.1 → 0.2.3

package/AGENTS.md

@@ -137,13 +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, 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.
 
@@ -153,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

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

package/SPEC.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msareen/knowledge-hub-builder",
-  "version": "0.2.1",
+  "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",
@@ -35,6 +35,8 @@
   "scripts": {
     "khb": "bun scripts/cli.ts",
     "lint": "bun scripts/cli.ts lint",
+    "upgrade": "bun scripts/cli.ts upgrade",
+    "doctor": "bun scripts/cli.ts doctor",
     "visualize": "bun scripts/cli.ts visualize",
     "new-bundle": "bun scripts/cli.ts new-bundle",
     "export": "bun scripts/cli.ts export",

package/scripts/cli.ts

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