@williamthorsen/kb 0.4.0 → 0.5.0

package/README.md

@@ -5,17 +5,15 @@ Provides knowledge-base discovery, registry loading, frontmatter parsing and wri
 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.4.0 (2026-08-07)
+## Release notes — v0.5.0 (2026-08-08)
 
 ### 🎉 Features
 
-- Add the .kb/taxonomy.yaml format with drift reporting and back-fill (#1210)
+- Register a new store with a description and keep the registry sorted (#1237)
 
-  Introduces `.kb/taxonomy.yaml`, in which a knowledge base declares the structure of its assertions. `kb check` now reports three kinds of drift between that declaration and the folders on disk: a folder that holds notes nothing declares, a declared area that holds no notes, and a declared area whose parent is undeclared. A knowledge base that already holds notes can adopt a declaration in one pass with the new `kb taxonomy init`, and `--merge` adds only what an existing declaration omits.
+  Adds a `--description` flag to `kb create`, so that a new knowledge base can be given a description as it is created. Alphabetical ordering of keys in `kb.yaml` is now enforced on every write.
 
-- Guide kb-add note placement with the store's declared taxonomy (#1223)
-
-  Improves classification of captured knowledge-base notes by aligning with the domains declared by the KB's taxonomy rather than looking to the directory structure. If a note is filed in a folder not covered by a domain, that folder is now added to the base's taxonomy. A domain added without confirmation is recorded as awaiting review.
+  Also fixes an issue where creating a knowledge base under an empty name could leave a stray registry entry. Across the CLI, a flag given an empty value is now refused.
 <!-- /section:release-notes -->
 
 ## Exports
@@ -206,9 +204,10 @@ The package ships a `kb` bin with four subcommands: `check`, `create`, `set-defa
 `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
+kb create                                 # scaffold the current directory, register under its name
+kb create --name coding                   # register under an explicit name
+kb create --description "Coding notes"    # describe the registry entry
+kb create --no-register                   # scaffold without writing the registry
 ```
 
 It creates these files and directories:
@@ -221,7 +220,7 @@ It creates these files and directories:
 
 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.
+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.
 
 `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.
 

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

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

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

@@ -1,11 +1,14 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { create } from "../../create/create.js";
+import { takeInlineValue, takeValue } from "../parse-flag-value.js";
 import { runSetDefault } from "./set-default.js";
 export const CREATE_HELP = `Usage: kb create [options]
 
 Scaffold a new knowledge base in the current directory and register it in the user-global kb.yaml registry.
 
+Registering leaves the registry's entries in alphabetical order, preserving its comments and formatting.
+
 When the registry has no default knowledge base, the new store becomes the default.
 If other knowledge bases are already registered, you are prompted to choose one (or set it later with "kb set-default").
 
@@ -15,9 +18,10 @@ Creates:
   content/, content/events/
 
 Options:
-  --name <name>   Registry name for the store. Defaults to the directory name.
-  --no-register   Scaffold without writing the kb.yaml registry entry.
-  -h, --help      Show this help.
+  --description <text>  Description for the registry entry; cannot be combined with --no-register.
+  --name <name>         Registry name for the store. Defaults to the directory name.
+  --no-register         Scaffold without writing the kb.yaml registry entry.
+  -h, --help            Show this help.
 
 Exit codes:
   0  store created
@@ -38,7 +42,12 @@ export async function runCreate(input) {
     const base = { targetDir: input.cwd, ...(options.name !== null && { name: options.name }) };
     const outcome = options.noRegister
         ? await create({ ...base, register: false })
-        : await create({ ...base, register: true, registryPath });
+        : await create({
+            ...base,
+            register: true,
+            registryPath,
+            ...(options.description !== null && { description: options.description }),
+        });
     if (!outcome.ok) {
         return { exitCode: 2, stdout: '', stderr: `kb create: ${outcome.message}\n` };
     }
@@ -57,6 +66,7 @@ export async function runCreate(input) {
     return { exitCode: 0, stdout: summary + selection.stdout, stderr: selection.stderr };
 }
 export function parseCreateArgs(argv) {
+    let description = null;
     let name = null;
     let noRegister = false;
     let help = false;
@@ -68,30 +78,34 @@ export function parseCreateArgs(argv) {
             help = true;
             continue;
         }
+        if (arg === '--description') {
+            description = takeValue(argv, index, '--description');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--description=')) {
+            description = takeInlineValue(arg, '--description=');
+            continue;
+        }
         if (arg === '--no-register') {
             noRegister = true;
             continue;
         }
         if (arg === '--name') {
-            const next = argv[index + 1] ?? null;
-            if (next === null || next.startsWith('--')) {
-                throw new Error('--name requires a value');
-            }
-            name = next;
+            name = takeValue(argv, index, '--name');
             index += 1;
             continue;
         }
         if (arg.startsWith('--name=')) {
-            const value = arg.slice('--name='.length);
-            if (value === '') {
-                throw new Error('--name requires a value');
-            }
-            name = value;
+            name = takeInlineValue(arg, '--name=');
             continue;
         }
         throw new Error(`unknown flag: ${arg}`);
     }
-    return { name, noRegister, help };
+    if (noRegister && description !== null) {
+        throw new Error('--description cannot be combined with --no-register');
+    }
+    return { description, name, noRegister, help };
 }
 const UNSET_DEFAULT_HINT = 'Multiple knowledge bases are registered and no default is set. Run `kb set-default` to choose one.\n';
 function buildUsageError(error) {
@@ -104,6 +118,9 @@ function formatCreated(created, registryPath) {
         lines.push(`  ${path}`);
     }
     lines.push(created.registered ? `Registered in ${registryPath}` : 'Not registered (--no-register).');
+    if (created.description !== undefined) {
+        lines.push(`Description: ${created.description}`);
+    }
     if (created.defaultKb === 'set') {
         lines.push('Set as the default knowledge base.');
     }

package/dist/esm/cli/parse-flag-value.js

@@ -7,7 +7,7 @@ export function takeInlineValue(arg, prefix) {
 }
 export function takeValue(argv, index, flag) {
     const next = argv[index + 1] ?? null;
-    if (next === null || next.startsWith('--')) {
+    if (next === null || next === '' || next.startsWith('--')) {
         throw new Error(`${flag} requires a value`);
     }
     return next;

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

@@ -2,6 +2,7 @@ export type DefaultKbOutcome = 'set' | 'unchanged' | 'needs-selection';
 export interface CreatedStore {
     name: string;
     storePath: string;
+    description?: string;
     registered: boolean;
     created: readonly string[];
     defaultKb?: DefaultKbOutcome;
@@ -14,6 +15,7 @@ export type CreateInput = {
 } | {
     register: true;
     registryPath: string;
+    description?: string;
 });
 export type CreateOutcome = {
     ok: true;

package/dist/esm/create/create.js

@@ -22,12 +22,13 @@ export async function create(input) {
         return { ok: false, reason: 'name-registered', message: nameRegisteredMessage(name, registryPath) };
     }
     const created = await scaffold(storePath);
-    const result = await registerStore({ registryPath, name, storePath });
+    const described = input.description !== undefined && { description: input.description };
+    const result = await registerStore({ registryPath, name, storePath, ...described });
     if (result.status === 'already-present') {
         return { ok: false, reason: 'name-registered', message: nameRegisteredMessage(name, registryPath) };
     }
     const defaultKb = await ensureDefaultKb({ registryPath, name, before });
-    return { ok: true, created: { name, storePath, registered: true, created, defaultKb } };
+    return { ok: true, created: { name, storePath, ...described, registered: true, created, defaultKb } };
 }
 async function ensureDefaultKb(input) {
     if (input.before.defaultKb !== undefined) {

package/dist/esm/discovery/register-store.js

@@ -1,5 +1,6 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { isMap, isScalar } from 'yaml';
 import { kbRegistryFileSchema } from "./kb-registry-schema.js";
 import { loadRegistryDocument } from "./registry-document.js";
 export async function registerStore(input) {
@@ -11,11 +12,12 @@ export async function registerStore(input) {
     if (doc.hasIn(['kbs', input.name])) {
         return { status: 'already-present' };
     }
-    const entry = { path: input.storePath };
-    if (input.description !== undefined) {
-        entry.description = input.description;
-    }
+    const entry = {
+        ...(input.description !== undefined && { description: input.description }),
+        path: input.storePath,
+    };
     doc.setIn(['kbs', input.name], entry);
+    sortRegistryEntries(doc);
     const result = kbRegistryFileSchema.safeParse(doc.toJS());
     if (!result.success) {
         throw new Error(`${input.registryPath}: cannot register "${input.name}" — ${result.error.issues[0]?.message ?? 'invalid entry'}`);
@@ -24,3 +26,20 @@ export async function registerStore(input) {
     await writeFile(input.registryPath, doc.toString(), 'utf8');
     return { status: 'added' };
 }
+function compareRegistryNames(left, right) {
+    const caseInsensitive = left.localeCompare(right, 'en', { sensitivity: 'base' });
+    return caseInsensitive === 0 ? left.localeCompare(right) : caseInsensitive;
+}
+function sortRegistryEntries(doc) {
+    const kbs = doc.getIn(['kbs'], true);
+    if (!isMap(kbs)) {
+        return;
+    }
+    kbs.items.sort((left, right) => compareRegistryNames(readName(left.key), readName(right.key)));
+}
+function readName(key) {
+    if (isScalar(key)) {
+        return String(key.value);
+    }
+    return typeof key === 'string' ? key : '';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/kb",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Knowledge-base foundation: discovery, config, frontmatter parsing, records, tags, and vault-integrity checks",
   "keywords": [
     "frontmatter",