@williamthorsen/kb 0.0.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2026 William Thorsen
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+The software is provided "as is" and the author disclaims all warranties with regard to this software including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, direct, indirect, or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.

package/README.md

@@ -1 +1,236 @@
-Placeholder for `@williamthorsen/kb` — awaiting first release.
+# @williamthorsen/kb
+
+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 -->
+## Release notes — v0.3.0 (2026-08-04)
+
+### 🎉 Features
+
+- Make codeassembly and kb CLI tools publishable (#1164)
+
+  The `codeassembly` CLI now installs from npm, and its `install` and `sync` commands deploy the rulebooks, skills, and subagents it ships into any consuming project. The knowledge-base library `@williamthorsen/kb` and the session-lifecycle event package `codeassembly-lifecycle` are published alongside it.
+<!-- /section:release-notes -->
+
+## Exports
+
+The package exposes ten subpath entries plus a root barrel:
+
+| Entry               | Description                                                                    |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `.`                 | The most-used types plus `buildVaultIndex`                                     |
+| `./check`           | `check`: config-driven enumeration composed with vault integrity and the lints |
+| `./config`          | `.kb/config.yaml` loading and the typed `KbLoaderError` the loaders throw      |
+| `./create`          | `create`: scaffold a new store and register it in `kb.yaml`                    |
+| `./discovery`       | KB root discovery and `kb.yaml` registry loading, merging, and writing         |
+| `./filesystem`      | Filesystem-existence helpers with an explicit absence policy                   |
+| `./frontmatter`     | Note parsing into typed frontmatter and writing it back to YAML                |
+| `./note-io`         | Type-blind note read/write as an ordered frontmatter field map                 |
+| `./records`         | The typed `assertion`/`event` record parsers and renderers                     |
+| `./tags`            | `.kb/tag-aliases.yaml` loading and tag canonicalization                        |
+| `./vault-integrity` | Type-blind `[[link]]` resolution and basename-uniqueness over a note set       |
+
+Every public function takes a single plain-object input so a future MCP wrapper can mechanically bind Zod-validated payloads.
+The library throws on errors; success/failure shaping is left to consumers.
+
+## Knowledge-base discovery
+
+`findKbRoot({ startDir })` walks ancestor directories looking for a `.kb/` folder and returns the first match (or `null` at the filesystem root).
+
+```ts
+import { findKbRoot } from '@williamthorsen/kb/discovery';
+
+const root = await findKbRoot({ startDir: process.cwd() });
+```
+
+## The `kb.yaml` registry
+
+A KB registry declares one or more knowledge bases. `loadKbRegistry` reads two optional registry files and merges them:
+
+- **user-global**: `~/.agents/kb.yaml`
+- **project-local**: `<projectDir>/.agents/kb.yaml`
+
+```yaml
+# .agents/kb.yaml
+default_kb: coding
+kbs:
+  coding:
+    path: ~/vaults/coding
+    description: Personal coding knowledge base
+    readonly: false
+  team:
+    path: ../shared/team-kb
+    description: Shared team knowledge base
+```
+
+The top-level `default_kb` key names the machine's default knowledge base: the single KB that searches and discovery-based writes fall back on when no store is named or discovered. `capture-event` writes there only when explicitly selected with `--store @default`, never by omission. It must name an entry under `kbs`; a value that matches none fails the load. Set, change, or clear it from the command line with `kb set-default`.
+
+Configuration keys, per KB entry under `kbs.<name>`:
+
+| Key           | Required | Meaning                                                                                                 |
+| ------------- | -------- | ------------------------------------------------------------------------------------------------------- |
+| `path`        | yes      | KB root directory; `~` expands to `$HOME`, relative paths resolve against the registry file's directory |
+| `description` | no       | Human-readable description                                                                              |
+| `readonly`    | no       | Marks the KB as read-only                                                                               |
+
+### Merge semantics
+
+`loadKbRegistry` merges the two registries by KB name:
+
+- Project entries **replace** user entries with the same name.
+- Project entries with a new name are **appended**.
+- When both files set `default_kb`, the **project** value wins; the resolved default is the named entry from the merged set.
+- Path existence is not checked at load time.
+
+```ts
+import { loadKbRegistry } from '@williamthorsen/kb/discovery';
+
+const config = await loadKbRegistry({ projectDir: process.cwd() });
+// config.entries: KbRegistryEntry[] with absolute, resolved paths
+```
+
+## The addressed-by/addresses relation
+
+`addressed-by`/`addresses` is an inverse-pair relation that threads a problem record to whatever was done about it: a fix, a mitigation, an improved guidance note. Both are optional, multi-valued list fields:
+
+- `addressed-by` (on the problem record, available on `assertion` and `event`) is the canonical, recall-facing field: a list of references to whatever addressed the problem. It is the only viable store when the responder is external, so its entries are heterogeneous: a KB wikilink or relative path, a commit SHA, a PR/issue ref, or a URL. The field's shape is validated as a list by the record parser, while its entries are free-form, like `sources`. It is set on events with `kb-update-events` and on assertions with `kb-edit`.
+- `addresses` (on a KB-note responder, available on `assertion`) is the optional inverse for the rare "what does this address?" query. It is **non-authoritative**: keeping it in sync would be an N-file write, so `kb-curate` deliberately does not police it.
+
+The relation is many-to-many (one response can address many problems, and one problem can accrue many responses) and is surfaced flat by recall, with no chain-walking. This is distinct from `supersedes`/`superseded-by`, which _deprecates_ a record through a policed 1:1 chain; an addressed problem is not deprecated. It remains a true observation whose recurrence is worth keeping.
+
+## Frontmatter parsing and writing
+
+`parseNote({ path })` (or `parseNoteContent({ content })`) parses a note into a `ParsedNote` carrying typed `Frontmatter`:
+The `title`, `recordType`, `created`, `updated`, and `tags` fields are strongly typed and any other fields are preserved in an `extra` map.
+`writeFrontmatter({ frontmatter, body })` renders it back to a note string with a fixed field order and flow-style tags; the round trip is idempotent.
+
+Date fields surface as strings, never JS `Date` objects. YAML parse errors are recorded in `ParsedNote.frontmatterRaw.parseError` rather than thrown;
+missing files (when a path is given) throw.
+
+## Tags
+
+`loadAliases({ kbRoot })` reads `.kb/tag-aliases.yaml` into an `AliasMap`, rejecting collisions and self-aliases at load time; an absent file yields an empty map.
+`canonicalize(tag, aliases)` resolves a tag to its canonical form; `findAliasFor(tag, aliases)` returns the canonical form only when the input is a known alias.
+
+## Vault integrity and lints
+
+`checkVaultIntegrity(notes)` runs whole-vault, type-blind checks over a `{ path, body, bodyStartLine }[]` note set: an unresolved `[[link]]` is an error (`wikilinks.unresolved`), and a basename shared by two or more notes is one vault-wide warning (`wikilinks.basename`). `buildVaultIndex(notes)` builds the basename → paths index the layer and curate's wikilink rewriter share.
+
+The type-blind per-note lints — `tagAliasFindings(note, aliases)` (`tag-alias`, warning) and `pathsFindings(note)` (`paths.user-home`, error) — catch what write-time record validation can't: alias-vocabulary drift and hardcoded `/Users/{name}/` paths in captured content.
+
+```ts
+import { checkVaultIntegrity } from '@williamthorsen/kb/vault-integrity';
+
+const findings = checkVaultIntegrity(notes);
+```
+
+## Checking a store
+
+`check({ kbRoot })` runs a store's full check in one call: it loads `.kb/config.yaml` and `.kb/tag-aliases.yaml`, enumerates the notes the config selects, and composes whole-vault integrity 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';
+
+const { notes, findings } = await check({ kbRoot });
+```
+
+A structural defect in either loaded file throws a `KbLoaderError` (see below). Any other error from enumeration or the checks propagates unchanged.
+
+### Which notes are checked: `.kb/config.yaml`
+
+`.kb/config.yaml` configures which notes a check enumerates. Both keys are optional; an absent file or an omitted key falls back to the default.
+
+```yaml
+# .kb/config.yaml
+targets:
+  - 'content/**/*.md'
+exclude:
+  - '**/node_modules/**'
+```
+
+| Key       | Default                  | Meaning                                                                      |
+| --------- | ------------------------ | ---------------------------------------------------------------------------- |
+| `targets` | `['content/**/*.md']`    | Glob patterns (store-root-relative) selecting which notes a check enumerates |
+| `exclude` | `['**/node_modules/**']` | Glob patterns excluded from enumeration even when a target matches           |
+
+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 `kb` command
+
+The package ships a `kb` bin with three subcommands: `create`, `set-default`, and `check`.
+
+### kb create
+
+`kb create` scaffolds a new knowledge base in the current directory and registers it in the user-global `~/.agents/kb.yaml`.
+
+```bash
+kb create                # scaffold the current directory, register under its name
+kb create --name coding  # register under an explicit name
+kb create --no-register  # scaffold without writing the registry
+```
+
+It creates these files and directories:
+
+| Path                          | Contents                                                                                                  |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `.kb/config.yaml`             | A fully-commented check config; the bundled defaults apply as-is                                          |
+| `.kb/tag-aliases.yaml`        | An empty `aliases: {}` map                                                                                |
+| `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 name defaults to the directory's base name; `--name` overrides it and `--no-register` scaffolds without writing the registry. The registry write preserves any existing comments in `kb.yaml`. `kb create` refuses to clobber: it exits 2 if the directory already contains a `.kb/` store, or if the chosen name is already registered.
+
+`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 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`.
+
+```bash
+kb set-default coding   # set default_kb to the registered KB "coding"
+kb set-default --none   # clear default_kb
+kb set-default          # list the registered KBs and choose interactively
+```
+
+With a name, it sets `default_kb` to that KB, exiting 2 if the name is not registered. With `--none`, it clears the pointer. With no arguments on an interactive terminal, it lists the registered KBs — marking the current default and offering a `(none)` option — and writes the choice; cancelling with an empty line leaves the registry unchanged. With no arguments on a non-interactive stdin, it exits 2 rather than hanging. Writes resolve against and target the user-global registry only, and preserve existing comments and formatting.
+
+### kb check
+
+`kb check` validates a store's notes and reports the findings. With no path arguments it checks every note; path arguments or `--vs` scope the run to a subset.
+
+```bash
+kb check                       # check every note in the nearest ancestor .kb/ store
+kb check --kb coding           # check the named store from the kb.yaml registry
+kb check --json                # emit a JSON report
+kb check content/assertions    # check only the notes under a directory
+kb check 'content/**/*.md'     # check only the notes a glob matches (quote it)
+kb check --vs=main             # check only the notes changed since a ref
+```
+
+`kb check` resolves the store from the nearest ancestor `.kb/` directory, or from a `--kb <name>` entry in the merged `kb.yaml` registry (project-local entries join the user-global registry). The default output groups findings by file; `--json` emits `{ store, summary, findings }`. The command is read-only and never writes to the store.
+
+**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.
+- **`--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.
+
+Exit codes:
+
+| Code | Meaning                                                                                                                     |
+| ---- | --------------------------------------------------------------------------------------------------------------------------- |
+| `0`  | No error-severity findings in the checked notes (warnings are allowed). A run that selects no notes also exits 0.           |
+| `1`  | One or more error-severity findings in the checked notes.                                                                   |
+| `2`  | A usage error, an unresolvable store or `--vs` ref, a path matching no note, or a malformed `config` or `tag-aliases` file. |
+
+## Error and exception model
+
+The checks **return** findings; they never throw. Loaders (`loadKbConfig`, `loadAliases`) **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. `loadKbRegistry` throws a plain `Error` on its own structural defects. I/O errors other than a missing optional file propagate.
+
+## MCP wrappability
+
+Every public function input is a plain object with primitive or `unknown`-typed fields, and no function takes a callback. A future `kb-mcp` server can bind Zod-validated request payloads directly onto these inputs without refactoring.

package/bin/kb.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { existsSync } from 'node:fs';
+
+// Thin wrapper so pnpm can symlink the bin at install time, before `dist/` exists.
+// The real entry point loads at runtime from the build output.
+// See packages/agents/README.md ("Bin wrapper pattern") for details.
+const entryPoint = new URL('../dist/esm/cli/index.js', import.meta.url);
+
+// Gate on the entry file itself: Node raises ERR_MODULE_NOT_FOUND for any unresolved
+// module in the graph, so keying the build-first message off the error code would also
+// fire when the build is present and one of its imports is missing.
+if (!existsSync(entryPoint)) {
+  process.stderr.write(
+    'kb: build output not found. In a source checkout, run `pnpm run bootstrap`; otherwise reinstall the package.\n',
+  );
+  process.exit(1);
+}
+
+try {
+  await import(entryPoint.href);
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`kb: failed to load: ${message}\n`);
+  process.exit(1);
+}

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

@@ -0,0 +1,11 @@
+import type { KbConfig } from '../config/config-schema.js';
+import type { Finding } from '../types.js';
+import { type EnumeratedNote } from './enumerate.js';
+export interface CheckResult {
+    config: KbConfig;
+    notes: readonly EnumeratedNote[];
+    findings: readonly Finding[];
+}
+export declare function check(input: {
+    kbRoot: string;
+}): Promise<CheckResult>;

package/dist/esm/check/check.js

@@ -0,0 +1,17 @@
+import { loadKbConfig } from "../config/load-config.js";
+import { resolveKbDir } from "../layout/index.js";
+import { pathsFindings } from "../lints/paths.js";
+import { tagAliasFindings } from "../lints/tag-alias.js";
+import { loadAliases } from "../tags/load-aliases.js";
+import { checkVaultIntegrity } from "../vault-integrity/check-vault-integrity.js";
+import { enumerateNotes } from "./enumerate.js";
+export async function check(input) {
+    const kbRoot = { path: input.kbRoot, kbDir: resolveKbDir(input.kbRoot) };
+    const [config, aliases] = await Promise.all([loadKbConfig({ kbRoot }), loadAliases({ kbRoot })]);
+    const notes = await enumerateNotes({ kbRoot: input.kbRoot, config });
+    const findings = [
+        ...checkVaultIntegrity(notes),
+        ...notes.flatMap((note) => [...tagAliasFindings(note, aliases), ...pathsFindings(note)]),
+    ];
+    return { config, notes, findings };
+}

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

@@ -0,0 +1,14 @@
+import type { KbConfig } from '../config/config-schema.js';
+export interface EnumeratedNote {
+    path: string;
+    relativePath: string;
+    fields: Record<string, unknown>;
+    body: string;
+    content: string;
+    bodyStartLine: number;
+    error?: string;
+}
+export declare function enumerateNotes(input: {
+    kbRoot: string;
+    config: KbConfig;
+}): Promise<EnumeratedNote[]>;

package/dist/esm/check/enumerate.js

@@ -0,0 +1,71 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import process from 'node:process';
+import { createNoteScopeMatcher } from "../config/note-scope.js";
+import { readNoteContent } from "../note-io/read-note.js";
+import { isGlobSegment } from "./glob-segments.js";
+export async function enumerateNotes(input) {
+    const { kbRoot, config } = input;
+    const matcher = createNoteScopeMatcher(config);
+    const topLevelDirs = leadingLiteralSegments(config.targets);
+    const notes = [];
+    await walk({ root: kbRoot, dir: kbRoot, matcher, topLevelDirs, out: notes });
+    return notes;
+}
+function leadingLiteralSegments(targets) {
+    const dirs = new Set();
+    for (const target of targets) {
+        const firstSegment = target.split('/', 1)[0] ?? '';
+        if (firstSegment === '' || isGlobSegment(firstSegment)) {
+            return null;
+        }
+        dirs.add(firstSegment);
+    }
+    return dirs;
+}
+async function walk(input) {
+    const { root, dir, matcher, topLevelDirs, out } = input;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`kb: warning: could not read directory ${dir}; skipping: ${message}\n`);
+        return;
+    }
+    const atRoot = dir === root;
+    for (const entry of entries) {
+        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))
+                continue;
+            if (matcher.isExcluded(relativePath))
+                continue;
+            await walk({ root, dir: absolutePath, matcher, topLevelDirs, out });
+            continue;
+        }
+        if (!entry.name.endsWith('.md'))
+            continue;
+        if (!matcher.isNote(relativePath))
+            continue;
+        try {
+            const content = await readFile(absolutePath, 'utf8');
+            const { fields, body, bodyStartLine, error: parseError } = readNoteContent(content);
+            out.push({
+                path: absolutePath,
+                relativePath,
+                fields,
+                body,
+                content,
+                bodyStartLine,
+                ...(parseError !== undefined && { error: parseError }),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`kb: warning: could not read note ${absolutePath}; skipping: ${message}\n`);
+        }
+    }
+}

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

@@ -0,0 +1,2 @@
+export declare function isGlobSegment(segment: string): boolean;
+export declare function leadingLiteralPrefix(pattern: string): string;

package/dist/esm/check/glob-segments.js

@@ -0,0 +1,12 @@
+export function isGlobSegment(segment) {
+    return /[*?[\]{}()!+@]/.test(segment);
+}
+export function leadingLiteralPrefix(pattern) {
+    const literal = [];
+    for (const segment of pattern.split('/')) {
+        if (isGlobSegment(segment))
+            break;
+        literal.push(segment);
+    }
+    return literal.join('/');
+}

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

@@ -0,0 +1,2 @@
+export { check, type CheckResult } from './check.js';
+export { type EnumeratedNote, enumerateNotes } from './enumerate.js';

package/dist/esm/check/index.js

@@ -0,0 +1,2 @@
+export { check } from "./check.js";
+export { enumerateNotes } from "./enumerate.js";

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

@@ -0,0 +1,20 @@
+export interface CommandOutput {
+    exitCode: 0 | 1 | 2;
+    stdout: string;
+    stderr: string;
+}
+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";
+export declare function runCheck(input: {
+    argv: readonly string[];
+    cwd: string;
+    home?: string;
+}): Promise<CommandOutput>;
+interface CheckOptions {
+    kb: string | null;
+    json: boolean;
+    help: boolean;
+    patterns: string[];
+    vs: string | null;
+}
+export declare function parseCheckArgs(argv: readonly string[]): CheckOptions;
+export {};

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

@@ -0,0 +1,179 @@
+import { check } from "../../check/check.js";
+import { isKbLoaderError } from "../../config/kb-loader-error.js";
+import { findKbRoot } from "../../discovery/find-kb-root.js";
+import { tryLoadKbRegistry } from "../../discovery/load-registry.js";
+import { formatHuman, formatJson, summarize } from "../format.js";
+import { resolveChangedPaths } from "../targeting/resolve-changed-paths.js";
+import { selectNotes } from "../targeting/select-notes.js";
+export const CHECK_HELP = `Usage: kb check [paths...] [options]
+
+Validate notes in a knowledge base against its tag aliases and cross-note
+link and path rules. With no path arguments, every note is checked.
+Cross-note rules always resolve against the whole vault.
+
+Targeting (mutually exclusive):
+  [paths...]    Check only the notes matching the given glob patterns, files,
+                or directories. Quote globs so kb expands them itself. A
+                directory checks every note beneath it. A path that matches no
+                note is a usage error unless it names a real non-note.
+  --vs <ref>    Check only the notes changed between the working tree and the
+                merge-base of <ref> and HEAD: follows renames, includes
+                uncommitted edits, excludes deletions.
+
+Options:
+  --kb <name>   Check the named store from the kb.yaml registry. Without it,
+                the nearest ancestor .kb/ directory is used.
+  --json        Emit a JSON report instead of human-readable output.
+  -h, --help    Show this help.
+
+Exit codes:
+  0  no error-severity findings in the checked notes (warnings allowed)
+  1  one or more error-severity findings in the checked notes
+  2  usage error, unresolvable store or --vs ref, a path matching no note, or
+     malformed config or aliases
+`;
+export async function runCheck(input) {
+    let options;
+    try {
+        options = parseCheckArgs(input.argv);
+    }
+    catch (error) {
+        return buildUsageError(error);
+    }
+    if (options.help) {
+        return { exitCode: 0, stdout: CHECK_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 check: ${resolved.message}\n` };
+    }
+    const store = resolved.store;
+    let result;
+    try {
+        result = await check({ kbRoot: store.path });
+    }
+    catch (error) {
+        if (isKbLoaderError(error)) {
+            return { exitCode: 2, stdout: '', stderr: `kb check: ${error.message}\n` };
+        }
+        throw error;
+    }
+    const selection = await resolveSelection({ options, store, result });
+    if (!selection.ok) {
+        return { exitCode: 2, stdout: '', stderr: `kb check: ${selection.message}\n` };
+    }
+    const summary = summarize(selection.findings, selection.notes.length);
+    const stdout = options.json
+        ? formatJson({ store, summary, findings: selection.findings })
+        : formatHuman({ summary, findings: selection.findings, targets: result.config.targets, scope: selection.scope });
+    return { exitCode: summary.errors > 0 ? 1 : 0, stdout, stderr: '' };
+}
+export function parseCheckArgs(argv) {
+    let kb = null;
+    let json = false;
+    let help = false;
+    let vs = null;
+    const patterns = [];
+    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 === '--json') {
+            json = true;
+            continue;
+        }
+        if (arg === '--kb') {
+            kb = takeValue(argv, index, '--kb');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--kb=')) {
+            kb = takeInlineValue(arg, '--kb=');
+            continue;
+        }
+        if (arg === '--vs') {
+            vs = takeValue(argv, index, '--vs');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--vs=')) {
+            vs = takeInlineValue(arg, '--vs=');
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            throw new Error(`unknown flag: ${arg}`);
+        }
+        patterns.push(arg);
+    }
+    if (vs !== null && patterns.length > 0) {
+        throw new Error('--vs cannot be combined with path arguments');
+    }
+    return { kb, json, help, patterns, vs };
+}
+function buildUsageError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { exitCode: 2, stdout: '', stderr: `kb check: ${message}\n${CHECK_HELP}` };
+}
+async function resolveSelection(input) {
+    const { options, store, result } = input;
+    if (options.vs === null && options.patterns.length === 0) {
+        return { ok: true, scope: 'vault', notes: result.notes, findings: result.findings };
+    }
+    let scope = 'patterns';
+    let patterns = options.patterns;
+    if (options.vs !== null) {
+        scope = 'vs';
+        const changed = resolveChangedPaths({ storeRoot: store.path, ref: options.vs });
+        if (!changed.ok) {
+            return { ok: false, message: changed.message };
+        }
+        patterns = changed.paths;
+    }
+    const selection = await selectNotes({ notes: result.notes, patterns, storeRoot: store.path });
+    if (selection.unmatched.length > 0) {
+        return { ok: false, message: `no notes matched: ${selection.unmatched.join(', ')}` };
+    }
+    const selectedPaths = new Set(selection.selected.map((entry) => entry.path));
+    const findings = result.findings.filter((finding) => selectedPaths.has(finding.path));
+    return { ok: true, scope, notes: selection.selected, findings };
+}
+async function resolveStore(input) {
+    if (input.explicitKb !== null) {
+        const { config } = await tryLoadKbRegistry({
+            projectDir: input.cwd,
+            ...(input.home !== undefined && { home: input.home }),
+        });
+        const match = config.entries.find((entry) => entry.name === input.explicitKb);
+        if (match === undefined) {
+            return { ok: false, message: `--kb "${input.explicitKb}" does not match any registered knowledge base` };
+        }
+        return { ok: true, store: { name: match.name, path: match.path } };
+    }
+    const discovered = await findKbRoot({ startDir: input.cwd });
+    if (discovered === null) {
+        return { ok: false, message: 'no .kb/ directory found in the current directory or any ancestor' };
+    }
+    return { ok: true, store: { name: null, path: discovered.path } };
+}
+function takeInlineValue(arg, prefix) {
+    const value = arg.slice(prefix.length);
+    if (value === '') {
+        throw new Error(`${prefix.replace(/=$/, '')} requires a value`);
+    }
+    return value;
+}
+function takeValue(argv, index, flag) {
+    const next = argv[index + 1] ?? null;
+    if (next === null || next.startsWith('--')) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return next;
+}

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

@@ -0,0 +1,16 @@
+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\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  --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";
+export declare function runCreate(input: {
+    argv: readonly string[];
+    cwd: string;
+    home?: string;
+    selectKb?: SelectKbPrompt;
+}): Promise<CommandOutput>;
+interface CreateOptions {
+    name: string | null;
+    noRegister: boolean;
+    help: boolean;
+}
+export declare function parseCreateArgs(argv: readonly string[]): CreateOptions;
+export {};