@williamthorsen/kb 0.6.2 → 0.7.0

package/README.md

@@ -4,11 +4,38 @@ Foundation library for knowledge-base tooling.
 Provides knowledge-base discovery, registry loading, frontmatter parsing and writing, tag canonicalization, and type-blind vault-integrity checks.
 It underpins the knowledge-base skills — among them `kb-retrieve` (assertion recall) and `kb-retrieve-events` (event recall), `kb-add`, `kb-curate`, `capture-event`, and `kb-update-events` — and the planned `@williamthorsen/kb-mcp` server.
 
-<!-- section:release-notes --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v0.7.0 (2026-09-08)
+
+### 🎉 Features
+
+- 🚨 **Breaking:** Add kb scaffold to back-fill canonical files into an existing store (#1584)
+
+  - Adds the `kb scaffold` command, which writes the canonical files (`.kb/config.yaml` and `.kb/tag-aliases.yaml`) into a knowledge base. Files are created if missing, or replaced if `--force` is used.
+  - Narrows what `kb create` reports to the paths that it actually created.
+
+  Migration: import `renderAliasesSeed` and `renderConfigSeed` from `@williamthorsen/kb/scaffold` instead of `@williamthorsen/kb/create`.
+
+- Add canonical formatting configs so a store formats without a toolchain (#1586)
+
+  - Adds `.editorconfig` and `.prettierrc.yaml` to the canonical file set, so that `kb create` writes them into a new store and `kb scaffold` back-fills them into an existing one.
+  - Puts width, indentation, and line endings in `.editorconfig`, which editors read as well as Prettier.
+  - Sets `embeddedLanguageFormatting: off` in `.prettierrc.yaml`, which keeps Prettier from reflowing note frontmatter that the kb's note writer would flatten again.
+
+### 🐛 Bug fixes
+
+- Stop checking gitignored notes (#1587)
+
+  - Stops `kb check` from checking notes matching patterns in `.gitignore`. It now checks only those files that are tracked by git or new and not gitignored.
+  - Makes a link pointing at a gitignored note report `wikilinks.unresolved`, since such a link is broken for every clone but the author's.
+  - Fixes `kb check <path>` and `kb check --vs <ref>` for a note with an accented name, which on macOS matched nothing and could select unrelated files in its place.
+
+  Migration: Track a gitignored note that other notes link to, or remove the wikilinks pointing at it.
+<!-- /section:release-notes -->
 
 ## Exports
 
-The package exposes twelve subpath entries plus a root barrel:
+The package exposes thirteen subpath entries plus a root barrel:
 
 | Entry               | Description                                                                    |
 | ------------------- | ------------------------------------------------------------------------------ |
@@ -22,6 +49,7 @@ The package exposes twelve subpath entries plus a root barrel:
 | `./layout`          | The store's on-disk layout: every path inside a `.kb/` store derives from here |
 | `./note-io`         | Type-blind note read/write as an ordered frontmatter field map                 |
 | `./records`         | The typed `assertion`/`event` record parsers and renderers                     |
+| `./scaffold`        | The canonical set held by a store, and the idempotent writer over it           |
 | `./tags`            | `.kb/tag-aliases.yaml` loading and tag canonicalization                        |
 | `./taxonomy`        | `.kb/taxonomy.yaml` loading, comment-preserving declaration, and path mapping  |
 | `./vault-integrity` | Type-blind `[[link]]` resolution and basename-uniqueness over a note set       |
@@ -124,7 +152,7 @@ const findings = checkVaultIntegrity(notes);
 
 ## Checking a store
 
-`check({ kbRoot })` runs a store's full check in one call: it loads `.kb/config.yaml`, `.kb/tag-aliases.yaml`, and `.kb/taxonomy.yaml`, enumerates the notes the config selects, and composes whole-vault integrity and taxonomy drift with the `tag-alias` and `paths` lints. It performs no frontmatter validation — record types own that at write time. It returns **both** the enumerated notes and the findings, so a consumer can layer its own detectors over the same enumeration without walking the store twice.
+`check({ kbRoot })` runs a store's full check in one call: it loads `.kb/config.yaml`, `.kb/tag-aliases.yaml`, and `.kb/taxonomy.yaml`, enumerates the notes that the config selects (narrowed by [the git dimension](#the-git-dimension) inside a working tree), and composes whole-vault integrity and taxonomy drift with the `tag-alias` and `paths` lints. It performs no frontmatter validation — record types own that at write time. It returns **both** the enumerated notes and the findings, so a consumer can layer its own detectors over the same enumeration without walking the store twice.
 
 ```ts
 import { check } from '@williamthorsen/kb/check';
@@ -155,6 +183,12 @@ exclude:
 
 Matching uses dotfile-insensitive globbing, so dot-directories (`.kb`, `.git`, `.agents`) are skipped without naming them. The default targets the `content/`-scoped layout; a store with a different layout overrides `targets` to match. `loadKbConfig({ kbRoot })` returns the effective config and is exported from `@williamthorsen/kb/config`.
 
+#### The git dimension
+
+Where the store sits in a git working tree, `targets`/`exclude` is not the whole of note scope: what git accounts for narrows it further. A note is enumerated when git tracks it, or when git would track it, meaning no ignore rule covers it. A note that the repository ignores is therefore neither checked nor available as a wikilink target, so a link pointing at one reports `wikilinks.unresolved`. That is the correct reading: such a link is broken for every clone but the author's. This is what lets a store gitignore a scratch area (`local/`, `*.local.md`) and keep uncommitted notes there without the store's lints gating them.
+
+A store outside a git working tree, or a machine carrying no git, keeps the filesystem walk alone. Where git accounts for none of the notes that the walk found, which happens when a parent repository ignores the store's own directory, the run says so on stderr rather than reporting a clean bill over an empty note set.
+
 ### The declared structure: `.kb/taxonomy.yaml`
 
 `.kb/taxonomy.yaml` states where a store's assertions are meant to live. It is the source of truth for intended structure: folders on disk are derived from it, not the reverse. It governs `content/assertions/` only, since `content/events/` is flat and ULID-keyed.
@@ -187,7 +221,7 @@ A domain counts as used when any note lives at or beneath it, so a grouping doma
 
 ## The `kb` command
 
-The package ships a `kb` bin with four subcommands: `check`, `create`, `set-default`, and `taxonomy`.
+The package ships a `kb` bin with five subcommands: `check`, `create`, `scaffold`, `set-default`, and `taxonomy`.
 
 ### kb create
 
@@ -204,16 +238,34 @@ It creates these files and directories:
 
 | Path                          | Contents                                                                                                  |
 | ----------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `.editorconfig`               | Width, indentation, and line endings; see [Formatting a knowledge base](#formatting-a-knowledge-base)     |
 | `.kb/config.yaml`             | A fully-commented check config; the bundled defaults apply as-is                                          |
 | `.kb/tag-aliases.yaml`        | An empty `aliases: {}` map                                                                                |
+| `.prettierrc.yaml`            | The canonical formatting config; see [Formatting a knowledge base](#formatting-a-knowledge-base)          |
 | `content/`, `content/events/` | The note tree; `capture-event` writes events to `content/events/`, `kb-update-events` edits them in place |
 
-The config seed is serialized from the in-package `defaultKbConfig`, so a new store cannot drift from the bundled default.
+The check config is serialized from the in-package `defaultKbConfig` and the Prettier config from `canonicalPrettierConfig`, so a new store cannot drift from the bundled values.
 
-The name defaults to the directory's base name; `--name` overrides it and `--no-register` scaffolds without writing the registry. `--description` sets the new entry's description, and requires registration: combining it with `--no-register` is a usage error. The registry write preserves any existing comments in `kb.yaml` and leaves the `kbs:` entries alphabetically ordered, so a registry that has drifted out of order is tidied as stores are added. `kb create` refuses to clobber: it exits 2 if the directory already contains a `.kb/` store, or if the chosen name is already registered.
+The name defaults to the directory's base name; `--name` overrides it and `--no-register` scaffolds without writing the registry. `--description` sets the new entry's description, and requires registration: combining it with `--no-register` is a usage error. The registry write preserves any existing comments in `kb.yaml` and leaves the `kbs:` entries alphabetically ordered, so a registry that has drifted out of order is tidied as stores are added. `kb create` refuses to clobber: it exits 2 if the directory already contains a `.kb/` store, or if the chosen name is already registered. Use `kb scaffold` to add canonical files to a store that already exists.
 
 `kb create` also keeps a default knowledge base set. When the registry's top-level `default_kb` pointer is unset and the new store is the only registered KB, it becomes the default. When other KBs are already registered with no default, `kb create` prompts you to choose one on an interactive terminal — or, when stdin is not interactive, points you to `kb set-default`. An existing `default_kb` is never overwritten.
 
+### kb scaffold
+
+`kb scaffold` writes into an existing knowledge base any canonical file that it lacks, so a store created before a given file existed can acquire it.
+
+```bash
+kb scaffold                  # back-fill the nearest ancestor .kb/ store
+kb scaffold --kb coding      # back-fill the named store from the kb.yaml registry
+kb scaffold --force          # replace every canonical file with a fresh seed
+```
+
+The canonical set is the one that `kb create` writes, defined once and shared by both commands so neither can drift from the other. `.kb/taxonomy.yaml` is not part of it: `kb taxonomy init` derives that file's content from the notes a store already holds rather than writing a fixed template.
+
+An existing file is left untouched unless `--force` is given, which replaces it with a fresh seed and discards any edits. A directory has no content to replace, so `--force` governs files alone. The command reports each canonical path as `created`, `present`, or `replaced`.
+
+Store resolution matches `kb check`: the nearest ancestor `.kb/` directory, or a `--kb <name>` entry in the merged `kb.yaml` registry. Three grounds exit 2: no store resolves, the registry marks the resolved store `readonly`, or the resolved path holds no `.kb/`. The last keeps the command to back-filling a store rather than creating one, which is `kb create`'s job; a registry entry names a path without proving a store is there.
+
 ### kb set-default
 
 `kb set-default` sets, clears, or interactively chooses the user-global default knowledge base: the top-level `default_kb` pointer in `~/.agents/kb.yaml`.
@@ -243,7 +295,7 @@ kb check --vs=main             # check only the notes changed since a ref
 
 **Targeting.** Path arguments and `--vs` each scope the run to a subset of notes; they are mutually exclusive, and both compose with `--kb` and `--json`. Cross-note rules always resolve against the whole vault, so a targeted run never false-flags a link to an unselected note; only the report and the exit code narrow to the selection.
 
-- **`[paths...]`**: one or more glob patterns, files, or directories (store-root-relative). The command expands globs itself, so a quoted glob behaves the same as a shell-expanded one. A directory checks every note beneath it. A path that matches no note is a usage error, unless it names a real non-note (a README, a triage note, or an excluded file), which is skipped silently.
+- **`[paths...]`**: one or more glob patterns, files, or directories (store-root-relative). The command expands globs itself, so a quoted glob behaves the same as a shell-expanded one. A directory checks every note beneath it. A path that matches no note is a usage error, unless it names a real non-note (a README, a triage note, or a file that `exclude` or git rules out), which is skipped silently.
 - **`--vs <ref>`**: the notes changed between the working tree and the merge-base of `<ref>` and HEAD. The diff follows renames (checking the destination), includes uncommitted edits to tracked notes, and excludes deletions, so a `git mv`-heavy migration batch reports the notes it actually touched.
 
 Because the exit code reflects only the selected notes, a per-batch or pre-commit gate can pass while the rest of the vault still carries a migration backlog.
@@ -272,6 +324,67 @@ Every derived domain lands under `provisional:` with no description: the command
 
 Without `--merge`, a store that already declares a taxonomy is left untouched and the command exits 2.
 
+## Formatting a knowledge base
+
+A knowledge base is formatted by Prettier, invoked directly. kb owns the configuration and scaffolds it; it does not run the formatter and does not bundle one. A store therefore needs Prettier available on the machine and the two config files that `kb create` and `kb scaffold` write, and nothing else: no `package.json`, no lockfile, and no linter or TypeScript configuration.
+
+```bash
+prettier --write .   # format the store
+prettier --check .   # report drift without writing
+```
+
+Prettier 3 reads `.gitignore` and `.prettierignore` by default, so neither command needs a flag to skip what the repository ignores, and it loads a config file from a directory holding no `package.json`.
+
+### The two config files
+
+`.editorconfig` carries everything that more than one tool reads:
+
+```ini
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+max_line_length = 120
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+```
+
+Prettier reads this file, and so does every editor that supports EditorConfig, which is why the width and the indentation live here rather than in the Prettier config. `max_line_length` becomes Prettier's `printWidth` and `indent_size` its `tabWidth`, so a store that left them unset would format at Prettier's default width of 80 and would tell an editor nothing at all.
+
+The `[*.md]` exemption is the one entry that is not self-explanatory. Two trailing spaces are a hard line break in Markdown, and Prettier preserves them; an editor trimming trailing whitespace on save would destroy a break that the formatter deliberately keeps.
+
+`.prettierrc.yaml` carries the one setting that `.editorconfig` has no key for:
+
+```yaml
+embeddedLanguageFormatting: off
+```
+
+It is not stylistic, and the scaffolded file carries this reasoning in its own header so it travels with the store. `embeddedLanguageFormatting: off` leaves a note's YAML frontmatter unformatted. Formatted, a long `tags` or `addressed-by` list breaks across several lines, which `writeFrontmatter` puts back onto one the next time anything writes the note. Without this option the formatter and the note writer rewrite each other's output without end, and every note carrying a list past the print width churns on each pass.
+
+A store that must keep a file that it cannot format, such as a lockfile or a fixture whose defect is the point, names it in a `.prettierignore`. That file is the escape hatch and is not scaffolded, since a fresh store has nothing to put in it.
+
+### Migrating a store off a `package.json` toolchain
+
+A store that carries a `package.json` only to obtain Prettier can retire it.
+
+1. Install Prettier where the store is edited, if it is not already there: `pnpm add --global prettier`.
+2. Run `kb scaffold` in the store to write `.editorconfig` and `.prettierrc.yaml`. An `.editorconfig` the store already has is reported as `present` and left alone, so compare it against the canonical file above and reconcile the two by hand; `kb scaffold --force` replaces it outright.
+3. Delete `package.json`, the lockfile, `pnpm-workspace.yaml`, `.npmrc`, and any `eslint.config.*`, `tsconfig.json`, and dependency-upgrade config. Delete the superseded `.prettierrc.*` too; keep `.prettierignore` if it names anything still present.
+4. Check that `.editorconfig` still governs the width. Prettier reads it for every key the Prettier config leaves unset, so a store whose `max_line_length` disagrees with the canonical 120 formats to its own value, and two stores that disagree format differently.
+5. Repoint the pre-commit hook. A hook running `pnpm exec prettier --write {staged_files}` becomes `prettier --write {staged_files}`. Under lefthook, `stage_fixed: true` continues to apply. Note that lefthook was installed by `package.json`'s `prepare` script, so it now needs installing on the machine and enabling in the store with `lefthook install`.
+6. Repoint CI. A workflow calling `pnpm run check` needs a command that assumes no `package.json`: `prettier --check .`, plus `kb check` for the store's own rules.
+7. Format once: `prettier --write .`. Commit the result on its own, so the reformatting does not obscure later diffs.
+
+A store carrying its own note checker deserves one more step before it is retired: compare its rules against what `kb check` covers, and port anything missing. `kb check` validates wikilinks, tag aliases, hardcoded home paths, and taxonomy drift, and deliberately leaves frontmatter validity to the record types that own it at write time.
+
+A store with no `package.json` runs steps 1, 2, and 7, and skips 3 through 6: it has nothing to retire, only Prettier to install, the config to adopt, and a first format to run.
+
 ## Error and exception model
 
 The checks **return** findings; they never throw. Loaders (`loadKbConfig`, `loadAliases`, `loadTaxonomy`) **throw** a typed `KbLoaderError` on structural defects or malformed YAML, with the offending file path named in the message. `KbLoaderError` (exported from `@williamthorsen/kb/config`) carries a `kind: 'KbLoaderError'` discriminant — and an `isKbLoaderError` type guard — so a caller can distinguish a recoverable config or alias defect from any other throw. An underlying failure, such as a YAML parse error, is attached as the thrown error's `cause`. `loadKbRegistry` throws a plain `Error` on its own structural defects. I/O errors other than a missing optional file propagate.

package/dist/esm/check/check.d.ts

@@ -1,11 +1,35 @@
 import type { KbConfig } from '../config/config-schema.js';
 import type { Finding } from '../types.js';
 import { type EnumeratedNote } from './enumerate.js';
+/** The result of a check run: the effective config, every enumerated note, and every finding the checks produced. */
 export interface CheckResult {
+    /** The effective `KbConfig` the run used — loaded from `.kb/config.yaml`, or `defaultKbConfig` when absent. */
     config: KbConfig;
+    /** Every note that the store's `config.targets` and, inside a git working tree, its git scope admit, in walk order. */
     notes: readonly EnumeratedNote[];
+    /**
+     * Findings from whole-vault integrity (unresolved links, basename collisions), taxonomy drift, and the tag-alias and
+     * paths lints.
+     */
     findings: readonly Finding[];
 }
+/**
+ * Runs the store's config-driven check: load `.kb/config.yaml`, `.kb/tag-aliases.yaml`, and `.kb/taxonomy.yaml`,
+ * enumerate notes under the config's `targets`/`exclude`, and compose whole-vault integrity and taxonomy drift with
+ * the type-blind per-note lints across them. Frontmatter validity is owned by the record types at write time, so no
+ * frontmatter re-validation runs here.
+ *
+ * Inside a git working tree the enumeration narrows to what git accounts for, so a note the repository ignores is
+ * neither checked nor available as a wikilink target; see {@link enumerateNotes} for the rule.
+ *
+ * Returns the effective config alongside the enumerated notes and findings, so a consumer (e.g. `kb-curate`) can layer
+ * its own detectors over the same enumeration without walking the tree twice, and can read the resolved
+ * `targets`/`exclude` without re-loading `.kb/config.yaml`.
+ *
+ * A structural defect in any loaded file throws a `KbLoaderError` (the loaders' own contract); the caller decides how
+ * to surface it. Any other error from enumeration or the checks propagates unchanged — it is never relabeled as a
+ * config defect.
+ */
 export declare function check(input: {
     kbRoot: string;
 }): Promise<CheckResult>;

package/dist/esm/check/enumerate.d.ts

@@ -1,17 +1,54 @@
 import type { KbConfig } from '../config/config-schema.js';
+/**
+ * A note reduced to the fields the check pipeline and curate consume: its paths, its frontmatter field map, its body
+ * and body-start line (for file-absolute link lines), its full content (for the paths lint), and any parse error.
+ */
 export interface EnumeratedNote {
+    /** Absolute path the note was read from. */
     path: string;
+    /** The note's path relative to the KB root, slash-separated. */
     relativePath: string;
+    /** The frontmatter field map, empty when the block is absent or unparseable. */
     fields: Record<string, unknown>;
+    /** The note body (everything after the frontmatter block). */
     body: string;
+    /** The full original note content. */
     content: string;
+    /** 1-based file line where the body begins. */
     bodyStartLine: number;
+    /** Frontmatter parse or absence diagnostic, when the block was missing or could not be parsed. */
     error?: string;
 }
+/**
+ * Walks a KB root and returns the KB-root-relative path of every note {@link enumerateNotes} selects, opening none of
+ * them. Scope selection runs through the same matcher and the same pruning, so a caller that needs only the note set's
+ * shape — which folders hold notes, and how many — sees exactly what the check pipeline admits.
+ *
+ * A note whose content cannot be read still contributes its path here, where `enumerateNotes` drops it with a warning.
+ */
 export declare function enumerateNotePaths(input: {
     kbRoot: string;
     config: KbConfig;
 }): Promise<string[]>;
+/**
+ * Walks a KB root and parses every note whose KB-root-relative path matches a `config.targets` glob and no
+ * `config.exclude` glob into an {@link EnumeratedNote}.
+ *
+ * Matching uses `picomatch` with `dot:false`, so dot-prefixed directories (`.kb`, `.git`, `.agents`) are excluded
+ * implicitly without naming them in `exclude`. The walk prunes the tree to each target's leading literal segment
+ * (`content/**` descends only into `content/`); a target with no leading literal (e.g. `**\/*.md`) falls back to a
+ * full walk. Excludes are honored during descent so an excluded subtree is never entered.
+ *
+ * Where the store sits in a git working tree, scope narrows further to what git accounts for: tracked notes plus
+ * untracked ones that no ignore rule covers. A note that the repository ignores is therefore neither enumerated nor available
+ * as a wikilink target, so a link pointing at one resolves to nothing. A store outside a working tree, or a machine
+ * carrying no git, keeps the walk's own scope.
+ *
+ * Notes with malformed or absent frontmatter are kept — `readNoteContent` records the parse error in `error` and
+ * returns an empty field map rather than throwing, so they remain valid wikilink targets. A note that cannot be read,
+ * or a directory that cannot be listed, is skipped with a `kb:` stderr warning rather than aborting the walk. Each
+ * note's `path` is absolute; `relativePath` is the slash-separated path from the KB root.
+ */
 export declare function enumerateNotes(input: {
     kbRoot: string;
     config: KbConfig;

package/dist/esm/check/enumerate.js

@@ -3,6 +3,7 @@ import { join, relative, sep } from 'node:path';
 import process from 'node:process';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { createNoteScopeMatcher } from "../config/note-scope.js";
+import { listGitScope } from "../git/list-git-scope.js";
 import { readNoteContent } from "../note-io/read-note.js";
 import { isGlobSegment } from "./glob-segments.js";
 export async function enumerateNotePaths(input) {
@@ -36,8 +37,15 @@ async function collectNoteLocations(input) {
     const { kbRoot, config } = input;
     const matcher = createNoteScopeMatcher(config);
     const topLevelDirs = leadingLiteralSegments(config.targets);
-    const locations = [];
-    await walk({ root: kbRoot, dir: kbRoot, matcher, topLevelDirs, out: locations });
+    const candidates = [];
+    await walk({ root: kbRoot, dir: kbRoot, matcher, topLevelDirs, out: candidates });
+    const gitScope = listGitScope({ root: kbRoot });
+    if (gitScope === undefined)
+        return candidates;
+    const locations = candidates.filter((candidate) => gitScope.has(candidate.relativePath.normalize('NFC')));
+    if (candidates.length > 0 && locations.length === 0) {
+        process.stderr.write(`kb: warning: git ignores every note under ${kbRoot}, so nothing was checked\n`);
+    }
     return locations;
 }
 function leadingLiteralSegments(targets) {
@@ -45,7 +53,7 @@ function leadingLiteralSegments(targets) {
     for (const target of targets) {
         const firstSegment = target.split('/', 1)[0] ?? '';
         if (firstSegment === '' || isGlobSegment(firstSegment)) {
-            return null;
+            return undefined;
         }
         dirs.add(firstSegment);
     }
@@ -66,7 +74,7 @@ async function walk(input) {
         const absolutePath = join(dir, entry.name);
         const relativePath = relative(root, absolutePath).split(sep).join('/');
         if (entry.isDirectory()) {
-            if (atRoot && topLevelDirs !== null && !topLevelDirs.has(entry.name))
+            if (atRoot && topLevelDirs !== undefined && !topLevelDirs.has(entry.name))
                 continue;
             if (matcher.isExcluded(relativePath))
                 continue;

package/dist/esm/check/glob-segments.d.ts

@@ -1,2 +1,8 @@
+/** Reports whether a path segment contains a glob metacharacter, making it non-literal. */
 export declare function isGlobSegment(segment: string): boolean;
+/**
+ * Returns the leading run of literal (non-glob) segments of a slash-separated pattern, slash-joined. A pattern whose
+ * first segment is a glob yields the empty string; a fully literal pattern yields itself. Locates the deepest concrete
+ * path a glob is anchored to, e.g. `content/notes/**` yields `content/notes`.
+ */
 export declare function leadingLiteralPrefix(pattern: string): string;

package/dist/esm/cli/commands/check.d.ts

@@ -1,20 +1,42 @@
+/** The outcome of a command run: the exit code plus the streams to write. */
 export interface CommandOutput {
+    /** Process exit code: 0 clean, 1 error-severity findings, 2 usage/config error. */
     exitCode: 0 | 1 | 2;
     stdout: string;
     stderr: string;
 }
+/** Usage text for `kb check`. */
 export declare const CHECK_HELP = "Usage: kb check [paths...] [options]\n\nValidate notes in a knowledge base against its tag aliases and cross-note\nlink and path rules. With no path arguments, every note is checked.\nCross-note rules always resolve against the whole vault.\n\nTargeting (mutually exclusive):\n  [paths...]    Check only the notes matching the given glob patterns, files,\n                or directories. Quote globs so kb expands them itself. A\n                directory checks every note beneath it. A path that matches no\n                note is a usage error unless it names a real non-note.\n  --vs <ref>    Check only the notes changed between the working tree and the\n                merge-base of <ref> and HEAD: follows renames, includes\n                uncommitted edits, excludes deletions.\n\nOptions:\n  --kb <name>   Check the named store from the kb.yaml registry. Without it,\n                the nearest ancestor .kb/ directory is used.\n  --json        Emit a JSON report instead of human-readable output.\n  -h, --help    Show this help.\n\nExit codes:\n  0  no error-severity findings in the checked notes (warnings allowed)\n  1  one or more error-severity findings in the checked notes\n  2  usage error, unresolvable store or --vs ref, a path matching no note, or\n     malformed config or aliases\n";
+/**
+ * Runs `kb check`: parses options, resolves the store, runs the shared `check`, and formats the report.
+ *
+ * Store resolution composes the package's own exports inline — `findKbRoot` for the default ancestor-walk and
+ * `tryLoadKbRegistry` for an explicit `--kb <name>`. The lookup is read-only, so a store's registry `readonly` flag
+ * is ignored. A malformed `.kb/config.yaml`/`tag-aliases.yaml` surfaces as a `KbLoaderError` from `check`, which maps
+ * to exit 2; any other error from `check` propagates to the caller as a real crash.
+ */
 export declare function runCheck(input: {
     argv: readonly string[];
     cwd: string;
     home?: string;
 }): Promise<CommandOutput>;
+/** Parsed `kb check` options. */
 interface CheckOptions {
+    /** Explicit store name from `--kb`, or `null` for ancestor-walk discovery. */
     kb: string | null;
+    /** Whether `--json` was supplied. */
     json: boolean;
+    /** Whether `--help`/`-h` was supplied. */
     help: boolean;
+    /** Positional glob/path/directory arguments selecting which notes to check; empty for a whole-vault run. */
     patterns: string[];
+    /** The `--vs` ref to diff against, or `null` when not supplied. */
     vs: string | null;
 }
+/**
+ * Parses `kb check` options. `--kb` and `--vs` each accept both the space (`--kb x`) and equals (`--kb=x`) forms;
+ * non-flag arguments are collected as selection patterns. Unknown flags, a missing `--kb`/`--vs` value, or combining
+ * patterns with `--vs` throw with a usage-style message.
+ */
 export declare function parseCheckArgs(argv: readonly string[]): CheckOptions;
 export {};

package/dist/esm/cli/commands/create.d.ts

@@ -1,17 +1,35 @@
 import type { SelectKbPrompt } from '../select-kb-prompt.js';
 import type { CommandOutput } from './check.js';
-export declare const CREATE_HELP = "Usage: kb create [options]\n\nScaffold a new knowledge base in the current directory and register it in the user-global kb.yaml registry.\n\nRegistering leaves the registry's entries in alphabetical order, preserving its comments and formatting.\n\nWhen the registry has no default knowledge base, the new store becomes the default.\nIf other knowledge bases are already registered, you are prompted to choose one (or set it later with \"kb set-default\").\n\nCreates:\n  .kb/config.yaml        check configuration (commented; defaults apply)\n  .kb/tag-aliases.yaml   tag-alias map (empty)\n  content/, content/events/\n\nOptions:\n  --description <text>  Description for the registry entry; cannot be combined with --no-register.\n  --name <name>         Registry name for the store. Defaults to the directory name.\n  --no-register         Scaffold without writing the kb.yaml registry entry.\n  -h, --help            Show this help.\n\nExit codes:\n  0  store created\n  2  usage error, an existing .kb/ in the directory, or an already-registered name\n";
+/** Usage text for `kb create`. */
+export declare const CREATE_HELP = "Usage: kb create [options]\n\nScaffold a new knowledge base in the current directory and register it in the user-global kb.yaml registry.\n\nRegistering leaves the registry's entries in alphabetical order, preserving its comments and formatting.\n\nWhen the registry has no default knowledge base, the new store becomes the default.\nIf other knowledge bases are already registered, you are prompted to choose one (or set it later with \"kb set-default\").\n\nCreates:\n  .editorconfig          editor and formatter settings (width, indent, line endings)\n  .kb/config.yaml        check configuration (commented; defaults apply)\n  .kb/tag-aliases.yaml   tag-alias map (empty)\n  .prettierrc.yaml       formatting configuration (commented)\n  content/, content/events/\n\nOptions:\n  --description <text>  Description for the registry entry; cannot be combined with --no-register.\n  --name <name>         Registry name for the store. Defaults to the directory name.\n  --no-register         Scaffold without writing the kb.yaml registry entry.\n  -h, --help            Show this help.\n\nExit codes:\n  0  store created\n  2  usage error, an existing .kb/ in the directory, or an already-registered name\n";
+/**
+ * Runs `kb create`: parses options, scaffolds a store in `cwd`, and (unless `--no-register`) registers it in the
+ * user-global `~/.agents/kb.yaml`. After registering, it ensures a default knowledge base: the new store becomes the
+ * default when none is set and it is the only KB; when other KBs already exist with no default, it delegates to
+ * `kb set-default`'s picker (or, with no `selectKb` on a non-interactive stdin, points the user there). A precondition
+ * failure from `create` — an existing `.kb/` or an already-registered name — maps to exit 2; a genuine I/O error
+ * propagates to the caller.
+ */
 export declare function runCreate(input: {
     argv: readonly string[];
     cwd: string;
     home?: string;
     selectKb?: SelectKbPrompt;
 }): Promise<CommandOutput>;
+/** Parsed `kb create` options. */
 interface CreateOptions {
+    /** Description from `--description`, or `null` to write the entry without one. */
     description: string | null;
+    /** Explicit registry name from `--name`, or `null` to default to the directory name. */
     name: string | null;
+    /** Whether `--no-register` was supplied. */
     noRegister: boolean;
+    /** Whether `--help`/`-h` was supplied. */
     help: boolean;
 }
+/**
+ * Parses `kb create` options. Each value-taking flag accepts both the space form and the equals form. Unknown flags, a
+ * missing value, or a description supplied alongside `--no-register` throw with a usage-style message.
+ */
 export declare function parseCreateArgs(argv: readonly string[]): CreateOptions;
 export {};

package/dist/esm/cli/commands/create.js

@@ -14,8 +14,10 @@ When the registry has no default knowledge base, the new store becomes the defau
 If other knowledge bases are already registered, you are prompted to choose one (or set it later with "kb set-default").
 
 Creates:
+  .editorconfig          editor and formatter settings (width, indent, line endings)
   .kb/config.yaml        check configuration (commented; defaults apply)
   .kb/tag-aliases.yaml   tag-alias map (empty)
+  .prettierrc.yaml       formatting configuration (commented)
   content/, content/events/
 
 Options:

package/dist/esm/cli/commands/scaffold.d.ts

@@ -0,0 +1,30 @@
+import type { CommandOutput } from './check.js';
+/** Usage text for `kb scaffold`. */
+export declare const SCAFFOLD_HELP = "Usage: kb scaffold [options]\n\nWrite into an existing knowledge base any canonical file that it lacks, so a store\ncreated before a given file existed can acquire it. An existing file is left\nuntouched unless --force is given.\n\nWrites:\n  .editorconfig          editor and formatter settings (width, indent, line endings)\n  .kb/config.yaml        check configuration (commented; defaults apply)\n  .kb/tag-aliases.yaml   tag-alias map (empty)\n  .prettierrc.yaml       formatting configuration (commented)\n  content/, content/events/\n\n.kb/taxonomy.yaml is not part of this set: \"kb taxonomy init\" derives it from\nthe notes that the store already holds. Use \"kb create\" to make a new store.\n\nOptions:\n  --force       Replace an existing canonical file with a fresh seed. A\n                directory has no content to replace and is left as it is.\n  --kb <name>   Use the named store from the kb.yaml registry. Without it, the\n                nearest ancestor .kb/ directory is used.\n  -h, --help    Show this help.\n\nExit codes:\n  0  every canonical file is present, whether it was written or already there\n  2  usage error, unresolvable store, a store marked readonly in kb.yaml, or a\n     resolved path holding no .kb/\n";
+/**
+ * Runs `kb scaffold`: parses options, resolves the store, and writes the canonical files it lacks.
+ *
+ * Store resolution matches `kb check`. A store the registry marks `readonly` is refused, as `kb taxonomy init` does.
+ * A resolved path holding no `.kb/` is refused too: the command back-fills a store rather than creating one, and a
+ * registry entry names a path without proving a store is there.
+ */
+export declare function runScaffold(input: {
+    argv: readonly string[];
+    cwd: string;
+    home?: string;
+}): Promise<CommandOutput>;
+/** Parsed `kb scaffold` options. */
+interface ScaffoldOptions {
+    /** Whether `--force` was supplied. */
+    force: boolean;
+    /** Whether `--help`/`-h` was supplied. */
+    help: boolean;
+    /** Explicit store name from `--kb`, or `null` for ancestor-walk discovery. */
+    kb: string | null;
+}
+/**
+ * Parses `kb scaffold` options. `--kb` accepts both the space (`--kb x`) and equals (`--kb=x`) forms. An unknown flag,
+ * a positional argument, or a missing `--kb` value throws with a usage-style message.
+ */
+export declare function parseScaffoldArgs(argv: readonly string[]): ScaffoldOptions;
+export {};

package/dist/esm/cli/commands/scaffold.js

@@ -0,0 +1,108 @@
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { directoryExists } from "../../filesystem/exists.js";
+import { KB_DIR, resolveKbDir } from "../../layout/index.js";
+import { scaffold } from "../../scaffold/scaffold.js";
+import { takeInlineValue, takeValue } from "../parse-flag-value.js";
+import { resolveStore } from "../resolve-store.js";
+export const SCAFFOLD_HELP = `Usage: kb scaffold [options]
+
+Write into an existing knowledge base any canonical file that it lacks, so a store
+created before a given file existed can acquire it. An existing file is left
+untouched unless --force is given.
+
+Writes:
+  .editorconfig          editor and formatter settings (width, indent, line endings)
+  .kb/config.yaml        check configuration (commented; defaults apply)
+  .kb/tag-aliases.yaml   tag-alias map (empty)
+  .prettierrc.yaml       formatting configuration (commented)
+  content/, content/events/
+
+.kb/taxonomy.yaml is not part of this set: "kb taxonomy init" derives it from
+the notes that the store already holds. Use "kb create" to make a new store.
+
+Options:
+  --force       Replace an existing canonical file with a fresh seed. A
+                directory has no content to replace and is left as it is.
+  --kb <name>   Use the named store from the kb.yaml registry. Without it, the
+                nearest ancestor .kb/ directory is used.
+  -h, --help    Show this help.
+
+Exit codes:
+  0  every canonical file is present, whether it was written or already there
+  2  usage error, unresolvable store, a store marked readonly in kb.yaml, or a
+     resolved path holding no ${KB_DIR}/
+`;
+export async function runScaffold(input) {
+    let options;
+    try {
+        options = parseScaffoldArgs(input.argv);
+    }
+    catch (error) {
+        return { exitCode: 2, stdout: '', stderr: `kb scaffold: ${describeError(error)}\n${SCAFFOLD_HELP}` };
+    }
+    if (options.help) {
+        return { exitCode: 0, stdout: SCAFFOLD_HELP, stderr: '' };
+    }
+    const resolved = await resolveStore({
+        explicitKb: options.kb,
+        cwd: input.cwd,
+        ...(input.home !== undefined && { home: input.home }),
+    });
+    if (!resolved.ok) {
+        return { exitCode: 2, stdout: '', stderr: `kb scaffold: ${resolved.message}\n` };
+    }
+    const store = resolved.store;
+    const label = store.name ?? store.path;
+    if (resolved.readonly) {
+        return buildRefusal(`knowledge base "${label}" is marked readonly in kb.yaml; scaffold is refused`);
+    }
+    if (!(await directoryExists(resolveKbDir(store.path)))) {
+        return buildRefusal(`no ${KB_DIR}/ directory at ${store.path}; run "kb create" to make a store there`);
+    }
+    const entries = await scaffold({ storePath: store.path, force: options.force });
+    return { exitCode: 0, stdout: formatScaffolded(store, entries), stderr: '' };
+}
+export function parseScaffoldArgs(argv) {
+    let force = false;
+    let help = false;
+    let kb = null;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === undefined)
+            continue;
+        if (arg === '--help' || arg === '-h') {
+            help = true;
+            continue;
+        }
+        if (arg === '--force') {
+            force = true;
+            continue;
+        }
+        if (arg === '--kb') {
+            kb = takeValue(argv, index, '--kb');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--kb=')) {
+            kb = takeInlineValue(arg, '--kb=');
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            throw new Error(`unknown flag: ${arg}`);
+        }
+        throw new Error(`unexpected argument: ${arg}`);
+    }
+    return { force, help, kb };
+}
+const ACTION_WIDTH = 8;
+function buildRefusal(message) {
+    return { exitCode: 2, stdout: '', stderr: `kb scaffold: ${message}\n` };
+}
+function formatScaffolded(store, entries) {
+    const named = store.name === null ? '' : ` "${store.name}"`;
+    const lines = [`Scaffolded knowledge base${named} at ${store.path}`];
+    for (const entry of entries) {
+        lines.push(`  ${entry.action.padEnd(ACTION_WIDTH)} ${entry.path}`);
+    }
+    return `${lines.join('\n')}\n`;
+}

package/dist/esm/cli/commands/set-default.d.ts

@@ -1,15 +1,30 @@
 import type { SelectKbPrompt } from '../select-kb-prompt.js';
 import type { CommandOutput } from './check.js';
+/** Usage text for `kb set-default`. */
 export declare const SET_DEFAULT_HELP = "Usage: kb set-default [name] [options]\n\nSet, clear, or interactively choose the user-global default knowledge base \u2014\nthe top-level default_kb pointer in ~/.agents/kb.yaml.\n\n  kb set-default <name>   Set default_kb to the named registered KB.\n  kb set-default --none   Clear default_kb.\n  kb set-default          List the registered KBs and prompt for a choice\n                          (including a \"(none)\" option to clear).\n\nOptions:\n  --none        Clear the default knowledge base.\n  -h, --help    Show this help.\n\nExit codes:\n  0  default set or cleared, or the selection was cancelled\n  2  usage error, an unregistered name, no registered KBs, or no name supplied\n     when stdin is not interactive\n";
+/**
+ * Runs `kb set-default`: sets, clears, or interactively selects the user-global `default_kb`. Resolution reads the
+ * user-global registry only (no project overlay), so the chosen default resolves in every project context. The picker
+ * is injected via `selectKb`, keeping the dispatcher free of terminal I/O; its absence means stdin is non-interactive,
+ * making the no-argument form a usage error rather than a hang.
+ */
 export declare function runSetDefault(input: {
     argv: readonly string[];
     home?: string;
     selectKb?: SelectKbPrompt;
 }): Promise<CommandOutput>;
+/** Parsed `kb set-default` options. */
 interface SetDefaultOptions {
+    /** The positional KB name, or `null` when none was supplied (interactive form). */
     name: string | null;
+    /** Whether `--none` was supplied. */
     none: boolean;
+    /** Whether `--help`/`-h` was supplied. */
     help: boolean;
 }
+/**
+ * Parses `kb set-default` options. At most one positional name is accepted; `--none` clears. A name combined with
+ * `--none`, a second positional, or an unknown flag throws with a usage-style message.
+ */
 export declare function parseSetDefaultArgs(argv: readonly string[]): SetDefaultOptions;
 export {};