@williamthorsen/kb 0.6.2 → 0.8.0

package/README.md

@@ -1,14 +1,40 @@
+<!-- readme-type: library -->
+
 # @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 --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v0.8.0 (2026-09-13)
+
+### 🎉 Features
+
+- Resolve wikilinks from a private store into a shared one (#1617)
+
+  - Adds the store-qualified wikilink `[[store:Note title]]`, whose prefix names an entry in the merged `kb.yaml` registry, so that `kb check` resolves the link against that store rather than reporting `wikilinks.unresolved`.
+  - Adds `visibility` to `.kb/config.yaml`, taking `shared` or `private` and defaulting to `private`, which sets the permitted direction: a link may point at a store as shareable as its own or more so.
+  - Adds three findings for a qualified link that does not resolve, `wikilinks.unknown-store` and `wikilinks.disallowed-store` as errors and `wikilinks.store-unavailable` as a warning, so that a correct link into a store that this machine has not cloned is reported as unverifiable rather than broken.
+
+- Add a second-person rule to the writing preferences (#1634)
+
+  - Bans the use of the 2nd person in user- and developer-facing documentation prose.
+  - Adds `second-person` to the rule names that `revise-prose` and `prose-reviser` accept, alongside `plain-speech`, so a sweep repairs a site or records a rejection under it though no detector reports its sites.
+  - Moves the rulebook's `version` to `3`, so that a bound repository re-sweeps and re-adjudicates the rejections recorded under the old version.
+
+### 🪦 Removed
+
+- 🚨 **Breaking:** Remove the wikilink-parse primitives from the vault-integrity subpath (#1680)
+
+  - Removes `countNewlines`, `extractTarget`, `hasNonMarkdownExtension`, `maskFencedCode`, `maskInlineCode`, and `WIKILINK` from `@williamthorsen/kb/vault-integrity`.
+
+  Migration: Call `scanWikilinks` to find the wikilinks in a note body and their targets, in place of a scan assembled from the removed primitives.
+<!-- /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                                                                    |
 | ------------------- | ------------------------------------------------------------------------------ |
@@ -18,16 +44,14 @@ The package exposes twelve subpath entries plus a root barrel:
 | `./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                |
+| `./frontmatter`     | Note parsing into typed frontmatter                                            |
 | `./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       |
-
-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.
+| `./vault-integrity` | Type-blind `[[link]]` scanning, resolution, and basename-uniqueness checks     |
 
 ## Knowledge-base discovery
 
@@ -69,6 +93,8 @@ Configuration keys, per KB entry under `kbs.<name>`:
 | `description` | no       | Human-readable description                                                                              |
 | `readonly`    | no       | Marks the KB as read-only                                                                               |
 
+An entry's name is also what a [store-qualified wikilink](#linking-into-another-store) names: `[[coding:Note title]]` resolves against the KB registered as `coding`.
+
 ### Merge semantics
 
 `loadKbRegistry` merges the two registries by KB name:
@@ -98,23 +124,24 @@ The relation is many-to-many (one response can address many problems, and one pr
 
 `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.
 
+Writing is type-blind and lives in `@williamthorsen/kb/note-io`. `readNote(path)` (or `readNoteContent(content)`) splits a note into an insertion-ordered frontmatter field map and a body, and `writeNote(path, fields, body)` (or `renderNote(fields, body)`) renders them back, with string lists in flow style. A note written this way reads back to the same fields and body.
+
 ## 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
+## Vault integrity
 
 `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.
+A second argument, `{ foreignStores, sourceVisibility }`, resolves [store-qualified links](#linking-into-another-store) against the stores they name; supplied none, the layer treats every target as store-local, which is what `buildVaultIndex`'s other consumers get.
 
-`taxonomyFindings({ notes, taxonomy, config, taxonomyPath })` reports where a store's assertion folders and its declared taxonomy disagree (see [`.kb/taxonomy.yaml`](#the-declared-structure-kbtaxonomyyaml)). Its findings carry `scope: 'vault'`: they describe the store rather than any one note, so a consumer that narrows a report to selected notes must keep them rather than filter them out by path.
+`scanWikilinks(body)` yields each link in a note body, with its store qualifier and target separated, and is the single definition of what counts as a link. `lookupKey(target)` reduces a target to the key that `VaultIndex` uses. The subpath exports `checkVaultIntegrity`, `buildVaultIndex`, `scanWikilinks`, and `lookupKey`, and not the parse primitives from which they are built: A consumer that detects or rewrites links calls `scanWikilinks`.
 
 ```ts
 import { checkVaultIntegrity } from '@williamthorsen/kb/vault-integrity';
@@ -124,7 +151,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 (inside a git working tree, the enumeration drops [ignored notes](#ignored-notes)), 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';
@@ -132,13 +159,15 @@ import { check } from '@williamthorsen/kb/check';
 const { notes, findings } = await check({ kbRoot });
 ```
 
+No subpath exports the lints, so `check`, and the `kb check` command built on it, is the only way to run them. Two type-blind per-note lints catch what write-time record validation can't: `tag-alias` (warning) reports alias-vocabulary drift, and `paths.user-home` (error) reports a hardcoded `/Users/{name}/` path in captured content. The `taxonomy.*` rules, all warnings, report where a store's assertion folders and its declared taxonomy disagree (see [`.kb/taxonomy.yaml`](#the-declared-structure-kbtaxonomyyaml)). Their findings carry `scope: 'vault'`: they describe the store rather than any one note, so a consumer that narrows a report to selected notes must keep them rather than filter them out by path.
+
 A structural defect in any loaded file throws a `KbLoaderError` (see below). Any other error from enumeration or the checks propagates unchanged.
 
 `enumerateNotes({ kbRoot, config })` performs the enumeration on its own, and `enumerateNotePaths({ kbRoot, config })` returns the same note set as store-root-relative paths without opening a single note. Both are exported from `@williamthorsen/kb/check`; the paths-only variant serves a caller that needs the note set's shape rather than its content.
 
 ### 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.
+`.kb/config.yaml` configures which notes a check enumerates and how widely the store is published. Every key is optional; an absent file or an omitted key falls back to the default.
 
 ```yaml
 # .kb/config.yaml
@@ -146,15 +175,45 @@ targets:
   - 'content/**/*.md'
 exclude:
   - '**/node_modules/**'
+visibility: private
 ```
 
-| 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           |
+| 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           |
+| `visibility` | `private`                | `shared` or `private`; decides which stores may link into this one           |
+
+`visibility` belongs here rather than in the registry entry because it is intrinsic to the store: one store cloned on two machines has one visibility, where a per-machine declaration could let the two disagree silently. It governs [linking into another store](#linking-into-another-store).
 
 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`.
 
+#### Ignored notes
+
+Where the store sits in a git working tree, the repository's ignore rules narrow the selection further. A note is enumerated when git tracks it, or when 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 the repository ignores every note 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.
+
+### Linking into another store
+
+A wikilink names a store by qualifying its target: `[[fde:Note title]]` resolves `Note title` in the store registered as `fde`, where a bare `[[Note title]]` stays inside the store being checked. A qualifier is recognized only when the text before the first colon is non-empty and carries no whitespace and no `/`, so a title that happens to contain a colon resolves whole.
+
+Direction is decided by `visibility`: a link may point at a store as shareable as its own or more so, never at a less shareable one. A private note may therefore link to the share-safe assertion its detail was stripped from, while the reverse is refused, because a note's title tends to be its claim and a link into a private store discloses that claim through the link itself.
+
+Only the stores that a run's own links name are consulted, and each is enumerated under its own `targets`/`exclude` and its own repository's ignore rules, reading note paths alone. A run whose links qualify no store reads no registry.
+
+| Rule                            | Severity | Reported when                                                                       |
+| ------------------------------- | -------- | ----------------------------------------------------------------------------------- |
+| `wikilinks.disallowed-store`    | error    | The named store is less shareable than the one being checked                        |
+| `wikilinks.registry-unloadable` | error    | A run with qualified links could not load `kb.yaml`; vault-scoped, reported once    |
+| `wikilinks.store-unavailable`   | warning  | The named store is registered but could not be read here, so the link is unverified |
+| `wikilinks.unknown-store`       | error    | No `kb.yaml` entry declares the named store                                         |
+| `wikilinks.unresolved`          | error    | The named store carries no note of that basename                                    |
+
+`wikilinks.store-unavailable` is a warning rather than an error because a store absent from this machine leaves its links unverifiable rather than broken: a correct link should not fail a check run on a machine that has not cloned the target.
+
+A run that reports `wikilinks.registry-unloadable` reports nothing per link. No store was looked up, so whether one is registered is undetermined, and naming each link would send the reader to fix a registration that may already be correct.
+
 ### 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 +246,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,15 +263,33 @@ 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. 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 for one on an interactive terminal, and points to `kb set-default` where stdin is not interactive. 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 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 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.
 
-`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.
+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
 
@@ -241,9 +318,9 @@ 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.
+**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 store, and a store-qualified link against the whole store it names, 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,10 +349,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.
 
-## Error and exception model
+## Formatting a knowledge base
 
-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.
+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
+```
 
-## MCP wrappability
+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.
 
-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.
+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 `renderNote` 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,45 @@
 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 selected by the store's `config.targets` and, inside a git working tree, not ignored by the repository,
+     * 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 also drops the notes that the repository ignores, so such a note is
+ * neither checked nor available as a wikilink target; see {@link enumerateNotes} for the rule.
+ *
+ * A `[[store:Target]]` link resolves against the store its prefix names rather than this one. Those stores are looked
+ * up in the merged `kb.yaml` registry, which is read from `~/.agents/kb.yaml` and from `cwd`'s project-local registry;
+ * `cwd` defaults to the store root, so a caller that supplies none still resolves against the user-global registry.
+ * Only the stores this store's own links name are consulted.
+ *
+ * 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;
+    cwd?: string;
+    home?: string;
 }): Promise<CheckResult>;

package/dist/esm/check/check.js

@@ -1,5 +1,6 @@
 import { join } from 'node:path';
 import { loadKbConfig } from "../config/load-config.js";
+import { tryLoadKbRegistry } from "../discovery/load-registry.js";
 import { resolveKbDir, TAXONOMY_FILE } from "../layout/index.js";
 import { pathsFindings } from "../lints/paths.js";
 import { tagAliasFindings } from "../lints/tag-alias.js";
@@ -8,6 +9,7 @@ import { loadAliases } from "../tags/load-aliases.js";
 import { loadTaxonomy } from "../taxonomy/load-taxonomy.js";
 import { checkVaultIntegrity } from "../vault-integrity/check-vault-integrity.js";
 import { enumerateNotes } from "./enumerate.js";
+import { collectStorePrefixes, resolveForeignStores } from "./resolve-foreign-stores.js";
 export async function check(input) {
     const kbRoot = { path: input.kbRoot, kbDir: resolveKbDir(input.kbRoot) };
     const [config, aliases, taxonomy] = await Promise.all([
@@ -16,10 +18,48 @@ export async function check(input) {
         loadTaxonomy({ kbRoot }),
     ]);
     const notes = await enumerateNotes({ kbRoot: input.kbRoot, config });
+    const qualified = await resolveQualifiedStores({
+        notes,
+        projectDir: input.cwd ?? input.kbRoot,
+        sourceVisibility: config.visibility,
+        ...(input.home !== undefined && { home: input.home }),
+    });
     const findings = [
-        ...checkVaultIntegrity(notes),
+        ...registryFindings(qualified.registryError),
+        ...checkVaultIntegrity(notes, { foreignStores: qualified.foreignStores, sourceVisibility: config.visibility }),
         ...taxonomyFindings({ notes, taxonomy, config, taxonomyPath: join(input.kbRoot, TAXONOMY_FILE) }),
         ...notes.flatMap((note) => [...tagAliasFindings(note, aliases), ...pathsFindings(note)]),
     ];
     return { config, notes, findings };
 }
+function registryFindings(error) {
+    if (error === undefined)
+        return [];
+    return [
+        {
+            path: KB_REGISTRY_LABEL,
+            scope: 'vault',
+            rule: 'wikilinks.registry-unloadable',
+            severity: 'error',
+            message: `no store-qualified link can resolve: ${error}`,
+        },
+    ];
+}
+async function resolveQualifiedStores(input) {
+    const prefixes = collectStorePrefixes(input.notes);
+    if (prefixes.size === 0)
+        return { foreignStores: new Map() };
+    const registry = await tryLoadKbRegistry({
+        projectDir: input.projectDir,
+        ...(input.home !== undefined && { home: input.home }),
+    });
+    if (registry.error !== undefined)
+        return { foreignStores: new Map(), registryError: registry.error };
+    const foreignStores = await resolveForeignStores({
+        prefixes,
+        registry: registry.config,
+        sourceVisibility: input.sourceVisibility,
+    });
+    return { foreignStores };
+}
+const KB_REGISTRY_LABEL = 'kb.yaml';

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.
+ *
+ * If the store sits in a git working tree, the enumeration keeps only the notes that git tracks and the untracked
+ * notes 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 what the walk alone found.
+ *
+ * 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/check/resolve-foreign-stores.d.ts

@@ -0,0 +1,24 @@
+import { type StoreVisibility } from '../config/config-schema.js';
+import type { KbRegistry } from '../types.js';
+import type { ForeignStore } from '../vault-integrity/check-vault-integrity.js';
+/**
+ * Collects the distinct store names that a note set's wikilinks qualify, so a check run consults only the stores its
+ * own links reach. It reads {@link scanWikilinks}, the same walk that later evaluates the links, so a store-shaped
+ * prefix inside a code sample pulls in no store and the two cannot disagree on what counts as a qualified link.
+ */
+export declare function collectStorePrefixes(notes: readonly {
+    body: string;
+}[]): Set<string>;
+/**
+ * Resolves each store name a run's links qualify against the merged registry, reading only note paths and each store's
+ * own `.kb/config.yaml`: a foreign store is enumerated under its own `targets`/`exclude` and its own repository's
+ * ignore rules, as it would be under its own check run, and no foreign note is opened.
+ *
+ * A store that cannot be read — absent from this machine, or carrying a config file that will not load — resolves
+ * `unavailable` rather than throwing, so one unrelated store cannot fail the run.
+ */
+export declare function resolveForeignStores(input: {
+    prefixes: Iterable<string>;
+    registry: KbRegistry;
+    sourceVisibility: StoreVisibility;
+}): Promise<Map<string, ForeignStore>>;

package/dist/esm/check/resolve-foreign-stores.js

@@ -0,0 +1,50 @@
+import { stat } from 'node:fs/promises';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { isAtLeastAsShareable } from "../config/config-schema.js";
+import { loadKbConfig } from "../config/load-config.js";
+import { resolveKbDir } from "../layout/index.js";
+import { buildVaultIndex } from "../vault-integrity/build-vault-index.js";
+import { scanWikilinks } from "../vault-integrity/wikilink-parse.js";
+import { enumerateNotePaths } from "./enumerate.js";
+export function collectStorePrefixes(notes) {
+    const prefixes = new Set();
+    for (const note of notes) {
+        for (const { store } of scanWikilinks(note.body)) {
+            if (store !== undefined)
+                prefixes.add(store);
+        }
+    }
+    return prefixes;
+}
+export async function resolveForeignStores(input) {
+    const resolved = new Map();
+    for (const prefix of input.prefixes) {
+        resolved.set(prefix, await resolveOne(prefix, input.registry, input.sourceVisibility));
+    }
+    return resolved;
+}
+async function resolveOne(prefix, registry, sourceVisibility) {
+    const entry = registry.entries.find((candidate) => candidate.name === prefix);
+    if (entry === undefined)
+        return { status: 'unknown' };
+    try {
+        const stats = await stat(entry.path);
+        if (!stats.isDirectory())
+            return { status: 'unavailable', reason: `${entry.path} is not a directory` };
+    }
+    catch (error) {
+        return { status: 'unavailable', reason: `${entry.path} could not be read: ${describeError(error)}` };
+    }
+    let config;
+    try {
+        config = await loadKbConfig({ kbRoot: { path: entry.path, kbDir: resolveKbDir(entry.path) } });
+    }
+    catch (error) {
+        return { status: 'unavailable', reason: describeError(error) };
+    }
+    if (!isAtLeastAsShareable({ source: sourceVisibility, target: config.visibility })) {
+        return { status: 'disallowed', visibility: config.visibility };
+    }
+    const paths = await enumerateNotePaths({ kbRoot: entry.path, config });
+    return { status: 'resolved', index: buildVaultIndex(paths.map((path) => ({ path }))) };
+}