@staix/vault-mem 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-11-02
+
+- Add library-only spec discovery, repository/worktree identity checks, typed id-based graphs and bounded directional slices (#91 T2). `SpecIndex` reuses the vault scan/metadata/hash/BM25 engine with a separate `spec-` cache per canonical worktree; vault cache names remain unchanged. Spec searches exclude shared-cache rows absent from the instance snapshot or replaced since its scan, and discovery errors name the relative file. Filesystem normalization/case aliases are accepted with root-identity and physical-containment checks, skipped listed paths have diagnostics, and error advice preserves the original cause and names `.gitignore` for discovery bounds. No CLI/MCP read surface or spec content write tools are added.
+
+- Register local git roots separately with `specs add|list|remove`; removal previews and unregisters only. Spec root diagnostics distinguish a missing git executable, timeout, git refusal and non-root path, and support repository names containing backslashes. Spec sources default to `write: none` and `pii: deny`, share IDs and the atomic registry lock with vaults, and get root diagnostics in `doctor`. Config writes use format 2 only when `specs` is present; vault-only settings and output stay compatible. Spec graph/read/validation tools and spec content writes are not part of this increment (#91 T1).
+
+- MCP argument errors name the first failing path and reason without echoing values; unknown tools have a separate diagnostic. `vmem_create` accepts top-level `created` and checks a real YYYY-MM-DD calendar date. Writer/log CLI errors name rejected options, writer arity errors show the expected form, and per-command `--help`/`-h` prints usage (#94).
+
+- V05 refuses newly introduced Topics placement or content problems while retaining existing problems as warnings. `frontmatter --set topics` updates only the body Topics wiki-list items in the same atomic write, preserving fenced blocks, H3/prose and line endings; an unchanged topics value leaves the body unchanged. All create paths, including org `promote` and `vmem_create` with a custom body, now refuse a note whose Topics is not the final H2 or does not match its frontmatter topics. Existing vaults must run `vmem tidy <vault> --all` once after upgrading to the validating writer, previewing and then confirming its fingerprint; `doctor` reports pending migration counts and unparsable paths without writing, using only the planning pass, and reports thrown or returned planning failures as per-vault diagnostics (#92).
+
+- Releases publish a GitHub release next to the npm package, with the validated tarball and manifest attached and the CHANGELOG section as notes (#89).
+
+## [0.3.1] - 2026-11-01
+
+- `sync` and `doctor` refuse a git URL rewrite (`insteadOf`/`pushInsteadOf`) only when its prefix matches the configured remote or one of origin's configured or effective URLs, explicit `pushurl` included, and name that rule (#86). An unrelated rule, such as a global `https://github.com/` to SSH rewrite with an SSH vault remote, no longer blocks sync.
+
 ## [0.3.0] - 2026-11-01
 
 - A vault whose PII policy has members this build does not know (from a newer-format config) fails closed: note writes, `check`, tidy, `promote-from-amem`, `promote`, move and delete and log appends on it are refused with `PII_POLICY` instead of screening with an incomplete policy. Reads and `vaults pii` show still work.
@@ -61,7 +77,7 @@
 
 - Add vault registration, bounded configuration, home resolution, diagnostics and explicit unregister confirmation.
 - Add lossless frontmatter, local wiki-link resolution and incremental SQLite FTS indexing.
-- Add validated atomic note mutations, preview fingerprints and append-only attributed vault events.
+- Add validated atomic note mutations, preview fingerprints and append-only attributed vault events. Existing vaults must run `vmem tidy <vault> --all` once after upgrading, previewing first and then confirming its fingerprint.
 - Add bounded CLI/MCP providers, reversible host setup and agent-mem promotion with provenance.
 - Add indexed lint, deterministic graph reports, bounded neighborhoods and synthetic reference-parity checks.
 - Reuse unchanged parsed notes and link analysis during write validation, refresh derived links only for affected sources, and recheck the staging snapshot by direct content comparison instead of rehashing.

package/README.md

@@ -25,13 +25,13 @@ Home precedence: `VMEM_HOME` (the pointer is not consulted), else a `home` point
 {"vaults":[{"id":"personal","path":"/absolute/vault","kind":"personal","write":"mcp"}],"denyPaths":[],"piiPatterns":[]}
 ```
 
-Configuration is limited to 64 KiB both on read and after serialization (a change whose pretty-printed result exceeds the limit is refused and the file is unchanged), rejects unknown keys, and is updated under an exclusive lock using a flushed temporary file and atomic rename. An optional top-level `version` (positive integer, absent means 1) names the config format; this build writes format 1 and never adds `version` itself, so 0.2.4 and older keep reading what it writes. A config whose `version` is newer than this build's format is read tolerantly: unknown keys at the top level, in vaults and in PII policies are kept and written back unchanged by registry commands, while the keys this build knows are still validated. A PII policy with members this build does not know cannot be enforced, so it fails closed: every write on that vault (note writes and `check`, two-step previews and confirms, tidy, `promote-from-amem`, `promote` and log appends) is refused with `PII_POLICY`, naming the members, until the newer vmem that wrote the policy does the write. Reads and `vaults pii` show are unaffected. `vaults pii --set` refuses to replace a policy that carries such members, since the replacement would drop them; change it with the newer vmem. Versions that add a key bump the format. Errors name the config file or vault id and path but never echo config or note contents.
+Configuration is limited to 64 KiB both on read and after serialization (a change whose pretty-printed result exceeds the limit is refused and the file is unchanged), rejects unknown keys, and is updated under an exclusive lock using a flushed temporary file and atomic rename. An optional top-level `version` (positive integer, absent means 1) names the config format; this build supports format 2 and adds `version: 2` when `specs` is present. Vault-only configurations retain their existing version field (or its absence), so 0.2.4 and older keep reading those configurations. A config whose `version` is newer than this build's format is read tolerantly: unknown keys at the top level, in vaults and in PII policies are kept and written back unchanged by registry commands, while the keys this build knows are still validated. A PII policy with members this build does not know cannot be enforced, so it fails closed: every write on that vault (note writes and `check`, two-step previews and confirms, tidy, `promote-from-amem`, `promote` and log appends) is refused with `PII_POLICY`, naming the members, until the newer vmem that wrote the policy does the write. Reads and `vaults pii` show are unaffected. `vaults pii --set` refuses to replace a policy that carries such members, since the replacement would drop them; change it with the newer vmem. Versions that add a key bump the format. Errors name the config file or vault id and path but never echo config or note contents.
 
 Durability: the temporary file is fsynced before the rename and the home directory is fsynced after it. On Linux this makes the new config durable once the command returns. On macOS directory fsync succeeds but does not flush the drive cache (no `F_FULLFSYNC`), so a power loss right after a change can revert to the previous complete config, never to a partial one. Windows is not a supported platform for durability claims; the rename stays atomic.
 
 Crash recovery: the lock file records the writer's pid, host and start time. Nothing is cleaned up automatically. `vmem recover` previews the state; `vmem recover --confirm` removes the lock only when it names this host and a pid that no longer runs, and then removes leftover `.config-<uuid>.tmp` files. A live lock, a lock from another host, or an unreadable (older-format) lock is never removed and the command exits 1; confirm no writer runs, then delete `config.lock` by hand. No other file in the home or any vault is touched. If cleanup fails after an operation (for example the lock cannot be removed), the original error is kept and the cleanup failure, including a retained lock, is appended to it.
 
-Vault fields: `id`, absolute `path` (must contain a real `notes/` directory), `kind` (`personal|org`), `write` (`mcp|cli|none`), optional `pii` (the `allow|deny` shorthand or a policy object, see PII policy below; default `allow` for personal and `deny` for org, and `status`/`vaults list` always report the effective shorthand and `piiPolicy` matrix, including for unhealthy entries), optional `remote` (any nonempty string such as an `https://` or `git@host:path` URL) and optional `registry` (absolute path). For healthy vaults, `doctor` checks locally that the vault is a git repository root with an origin whose fetch and push URLs all match `remote` (URL rewrites are refused), and that `registry` passes the same deny-path, size and project-id validation as log appends. Results appear under each vault's `checks.remote` and `checks.registry`; a failed check exits 1. These checks use no network and do not test reachability. `status` is unchanged. Policy fields are stored for later note-writing stages, not enforced by the read commands. Writer commands enforce write/channel policy and configured deny/PII screening.
+Vault fields: `id`, absolute `path` (must contain a real `notes/` directory), `kind` (`personal|org`), `write` (`mcp|cli|none`), optional `pii` (the `allow|deny` shorthand or a policy object, see PII policy below; default `allow` for personal and `deny` for org, and `status`/`vaults list` always report the effective shorthand and `piiPolicy` matrix, including for unhealthy entries), optional `remote` (any nonempty string such as an `https://` or `git@host:path` URL) and optional `registry` (absolute path). For healthy vaults, `doctor` checks locally that the vault is a git repository root with an origin whose fetch and push URLs all match `remote` (URL rewrites are refused), and that `registry` passes the same deny-path, size and project-id validation as log appends. Results appear under each vault's `checks.remote` and `checks.registry`. Doctor also runs the tidy planning pass for writable vaults and reports pending counts and unparsable paths, without per-note writer validation or writes. Planning failures appear as `checks.tidy`; a failed check exits 1. Actual tidy previews validate planned notes and identify skipped notes. These checks use no network and do not test reachability. `status` is unchanged. Policy fields are stored for later note-writing stages, not enforced by the read commands. Writer commands enforce write/channel policy and configured deny/PII screening.
 
 The only runtime dependency is the exact first-party pin `@staix/agent-mem@0.17.0`; it is not loaded by registry commands. Public library exports cover configuration, home resolution, registry operations, frontmatter, link resolution and the derived index. No console bin or UI contract is advertised before its implementation.
 
@@ -117,11 +117,11 @@ vmem tidy personal --connections
 vmem tidy personal --all --json                 # migration sanitize preview (see Migration tidy)
 ```
 
-Syntax follows indexed reads: the vault id comes first. `new` supports `--title`, `--source`, `--confidence`, `--status`, `--extra JSON` and `--body file|-`; omitted body gets an H1/Relevant Notes/Topics skeleton. Patch accepts nonempty old/new strings up to 8192 bytes and requires exactly one occurrence (including overlapping occurrences). Append uses an existing section or inserts it before Topics; it refuses targeting or introducing a Topics H2. `frontmatter` supports `--set JSON`, `--unset key,key` and `--expected-sha`; append also supports `--expected-sha`. Link relations are `supports`, `contradicts`, `extends`, `applies-to`, `context-for`; links are bidirectional unless `--one-way`. Supersede sets `status`/`superseded_by` on the old note and adds a reverse link in the next note. Report permits plain paths below `reports/` or `ops/`, is schema-exempt and still screened. Inputs are bounded to 256 KiB, follow no file symlinks and accept stdin with `-`.
+Syntax follows indexed reads: the vault id comes first. `new` supports `--title`, `--source`, `--confidence`, `--status`, `--extra JSON` and `--body file|-`; omitted body gets an H1/Relevant Notes/Topics skeleton. Patch accepts nonempty old/new strings up to 8192 bytes and requires exactly one occurrence (including overlapping occurrences). Append uses an existing section or inserts it before Topics; it refuses targeting or introducing a Topics H2. `frontmatter` supports `--set JSON`, `--unset key,key` and `--expected-sha`; changing `topics` also replaces only the body Topics wiki-list items in the same write, preserving other content and line endings; setting an equal topics value leaves the body unchanged; append also supports `--expected-sha`. Link relations are `supports`, `contradicts`, `extends`, `applies-to`, `context-for`; links are bidirectional unless `--one-way`. Supersede sets `status`/`superseded_by` on the old note and adds a reverse link in the next note. Report permits plain paths below `reports/` or `ops/`, is schema-exempt and still screened. Inputs are bounded to 256 KiB, follow no file symlinks and accept stdin with `-`.
 
 `--dry-run` plans and validates any writer without creating locks, temporary files, directories or caches. `check` always takes this path, even without `--dry-run`. Move, delete and tidy first return a preview with planned path/hash changes and a fingerprint; confirmation requires that fingerprint. It covers canonical operation input, the canonical vault path/identity and policy, expected SHAs, every scanned note and all touched files, so even a new inbound reference after preview forces another preview. Move rewrites visible wiki/heading/block/embed targets and wiki references in frontmatter across the vault, preserving explicit `|label` text, anchors and code. Alias-only links resolve to no note and are left as written. The move source may be an existing note with a legacy file name (lint L13, for example a dot in the stem); the destination must be a valid stem. Tidy folds Connections sections into Relevant Notes. Delete refuses when it would newly break inbound links or MOC topics; fix those references first.
 
-Validation returns named issues with severity and no matched secret text: V01 schema/enums/description; V02 existing MOC topics; V03 newly unresolved links; V04 flat ASCII note paths (maximum 200 bytes) and safe report paths; V05 final Topics placement/content (warning), with explicit append-to-Topics refusal; V06 pinned agent-mem secret regex parity and denied sources/input/snapshot paths; V07 email/phone/configured PII patterns when denied; V08 create duplicates (stem/NFKC H1); V09 256 KiB prospective note size / 16 MiB report size, exact patch and expected-SHA/drift; V10 supersession target integrity. Unchanged pre-existing broken links warn, including after a move. `possibleDuplicates` lists candidate paths for warnings from a disposable in-memory FTS5 query of title terms, with BM25 <= -0.000001, up to three paths; no disk cache is written for that check. `LOCKED`, `IO`, `ROLLBACK`, `INDEX` and `CLEANUP` identify operational failures. CLI returns exit 1 when `ok` is false.
+Validation returns named issues with severity and no matched secret text: V01 schema/enums/description; V02 existing MOC topics; V03 newly unresolved links; V04 flat ASCII note paths (maximum 200 bytes) and safe report paths; V05 final Topics placement/content (error when the write introduces a placement or content problem the note did not already have, or on create; warning when every problem was already present), with explicit append-to-Topics refusal; V06 pinned agent-mem secret regex parity and denied sources/input/snapshot paths; V07 email/phone/configured PII patterns when denied; V08 create duplicates (stem/NFKC H1); V09 256 KiB prospective note size / 16 MiB report size, exact patch and expected-SHA/drift; V10 supersession target integrity. Unchanged pre-existing broken links warn, including after a move. `possibleDuplicates` lists candidate paths for warnings from a disposable in-memory FTS5 query of title terms, with BM25 <= -0.000001, up to three paths; no disk cache is written for that check. `LOCKED`, `IO`, `ROLLBACK`, `INDEX` and `CLEANUP` identify operational failures. CLI returns exit 1 when `ok` is false.
 
 A successful receipt reports `applied`, planned path/hash/byte changes, issues and `indexUpdated`. Unrelated malformed legacy YAML is skipped by duplicate hints and by writer index refresh, with a V01 warning naming the unchanged note; normal read/rebuild commands retain strict parsing. Move/tidy still require parseable inputs and name the offending path on refusal. Reads allocate each note's stat size plus one growth-probe byte, capped at the 2 MiB read limit plus one. A failed index refresh rolls back the file changes. Rollback first verifies each file still equals this operation's committed result; external edits are preserved. Failed/refused rollback retains the original backup and reports its relative recovery path. All files are staged before replacement and backups permit rollback of caught multi-file failures. Each individual rename is atomic; a machine/process crash between multiple renames can leave a partially completed batch. The retained lock and `.vmem-<uuid>.tmp` files require inspection and manual recovery after confirming the writer stopped. They are never automatically removed by registry recovery. Uncoordinated editors do not honor the lock; the pipeline rechecks SHAs before replacement, but this does not provide a filesystem transaction against concurrent external edits. Existing notes may be read up to the index's 2 MiB limit; prospective notes are limited to 256 KiB; report operations under `reports/` and `ops/` allow up to 16 MiB for both prospective content and existing-file reads (including staging and rollback rechecks), with at most 10000 flat notes per mutation snapshot. File/directory fsync has the platform guarantees described above. Successful changed mutations now append an event as described below; log failure is reported separately from note success.
 
@@ -306,7 +306,7 @@ Runtime changes intentionally make `release:verify` report stale historical rele
 
 # Migration tidy
 
-`vmem tidy <vault> [--connections --escapes --enums --keys --sources --topics --secrets --log | --all] [--map <file>] [--json] [--confirm --fingerprint SHA]` sanitizes debt from older, unvalidated writers. It is meant for the one-time V2 cutover and later imports.
+`vmem tidy <vault> [--connections --escapes --enums --keys --sources --topics --secrets --log | --all] [--map <file>] [--json] [--confirm --fingerprint SHA]` sanitizes debt from older, unvalidated writers. Existing vaults must run `vmem tidy <vault> --all` once after upgrading to the validating writer, previewing first and then confirming the returned fingerprint. `vmem doctor` reports pending migration planning counts and unparsable paths for writable vaults; it writes nothing. Doctor does not run the per-note writer validation, so its planning counts may include notes the actual tidy preview will skip. Tidy also handles later imports.
 
 - **Two steps.** Without `--confirm` it prints per-rule `counts`, a per-note change list (`key: old -> new`, dropped keys with their values, sections added) and `reported` items that were left unchanged; nothing is written. With `--confirm` the fingerprint must match: it covers the rules, the map file, and the before/after sha of every touched file (and of the log). Each note is then written through `applyWrite` (atomic per note, under the vault lock) and one `LINT` event is appended, for example `tidy: escapes 1, enums 13, keys 78, ...`.
 - **Never blocked by one note.** A sanitized note that the writer would still refuse (for example an unknown key) is left unchanged, listed under `skipped` and `reported`, and the rest of the run proceeds. Counts and the `LINT` event cover only notes that are written.
@@ -326,3 +326,21 @@ Runtime changes intentionally make `release:verify` report stale historical rele
 | `--log` | replace secret-looking substrings in existing log lines with `[redacted]`, and PII values that the vault policy denies on the `log` surface (allow-list entries excepted), under the log lock (refused with V06 when `denyPaths` covers the log). A line that fails the lint L09 structure check loses a trailing seconds field when that makes it valid, and is otherwise kept verbatim behind `# legacy: ` (readers skip `#` lines); no time, zone or TYPE is guessed. Other lines are kept byte for byte. Git history is not rewritten: rotate exposed credentials |
 
 `--map <file>` overrides defaults with strict JSON `{"enums": {"confidence|status|type": {"from": "to"}}, "keys": {"key": "drop" | "keep" | {"rename": "key"}}}` (at most 64 KiB and 1000 entries). For `tidy`, `--log` selects the log rule; tidy always writes its own `LINT` event.
+
+# Spec source registry
+
+Register a local repository as a separate spec source:
+
+```sh
+vmem specs add project-specs /absolute/repository --write none --pii deny
+vmem specs list --json
+vmem doctor --json
+vmem specs remove project-specs
+vmem specs remove project-specs --confirm
+```
+
+The config `specs` array holds `id`, canonical git working-tree root `path`, `write` (`mcp|cli|none`, default `none`) and `pii` (`allow|deny`, default `deny`). IDs are unique across vaults and spec sources. A spec source does not need a `notes/` directory. Registration and removal reuse the vault registry lock and atomic config write. Removal previews first, then `--confirm` unregisters only; repository files remain in place.
+
+Config writes containing `specs` use format 2; a config without `specs` keeps its existing serialization and version field. `status` lists spec entries under a separate `specs` key, and `doctor` checks that every registered path is still its canonical git working-tree root. An unavailable or changed root makes doctor exit 1 with a per-source issue. Existing vault entries and `vaults list` keep their output shape.
+
+The registry and a library-only read engine are implemented. `resolveSpecWorktree` checks the registered git common directory; `discoverSpecs` discovers nested Markdown specs in memory; `SpecIndex` reuses the vault scanner and BM25 with a separate `spec-` cache prefix per canonical worktree. Call `scan()` to refresh a `SpecIndex`; its `snapshot()` uses the last completed scan and `search()` admits only shared-cache rows matching that snapshot's paths and hashes. Call `scan()` again to see documents another index instance inserted or replaced. `buildSpecGraph` resolves typed links by frontmatter id, and `specSlice` returns bounded subtree/ancestor/neighbor slices (depth 0..3, at most 500 nodes). Discovery uses Git's tracked/untracked non-ignored Markdown list, reports skipped symlinks/missing/nonregular paths, accepts NFC/NFD and filesystem case aliases, and keeps the first duplicate id in NFC path order with a diagnostic. Root device/inode identity and per-file physical containment remain checked while accepting these spelling aliases. Unknown type/status strings remain readable. To exclude large or vendored untracked Markdown, add it to `.gitignore`; already-tracked ignored files must also be untracked with `git rm --cached`. Discovery/indexing is bounded to 10000 Markdown inputs, 2 MiB each and 64 MiB total; graphs allow 10000 inputs and 100000 unique edges. Graph results omit raw note sources. Spec validation, freshness, path filters, MCP tools and CLI graph/search commands are not yet implemented. Spec create/update/delete tools remain deferred; `write` stores a policy for later capabilities. Commands do not edit repository content or run git commit, branch or push.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/vault-mem",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Validated Obsidian-compatible knowledge vaults for agents and people",
   "license": "MIT",
   "type": "module",

package/src/cli.ts

@@ -1,3 +1,4 @@
+import { tidyVault, TIDY_RULES } from "./tidy.ts";
 import { originCheck } from "./sync.ts";
 import { registryIds } from "./vault-log.ts";
 import { runAnalysisCommand } from "./analysis-commands.ts";
@@ -11,7 +12,7 @@ import { VMEM_TOOL_NAMES } from "./mcp-vault.ts";
 import { CONFIG_VERSION } from "./config.ts";
 import { runSetup, type SetupMode } from "./setup.ts";
 import { resolveHome } from "./home.ts";
-import { addVault, effectivePii, loadRegistry, recoverRegistry, registryStatus, removeVault, setVaultPii } from "./registry.ts";
+import { addVault, addSpec, removeSpec, specStatus, effectivePii, loadRegistry, recoverRegistry, registryStatus, removeVault, setVaultPii } from "./registry.ts";
 import { piiPolicy } from "./pii.ts";
 function parse(args: string[], allowed: string[], values: string[]) {
   const flags: Record<string, string | boolean> = {}, positional: string[] = [];
@@ -27,8 +28,17 @@ function parse(args: string[], allowed: string[], values: string[]) {
   }
   return { flags, positional };
 }
+function commandHelp(args: string[]): string | undefined {
+  if (!["--help", "-h"].includes(args.at(-1) ?? "")) return undefined;
+  const name = args.slice(0, -1).join(" ");
+  if (!name) return undefined;
+  const commands = COMMANDS.filter(command => command.name === name || command.name.startsWith(name + " "));
+  return commands.length ? commands.map(command => `Usage: vmem ${command.usage}`).join("\n") : undefined;
+}
 export function run(args: string[], env: NodeJS.ProcessEnv = process.env): { text: string; code: number } {
   if (!args.length || (args.length === 1 && ["--help", "-h", "help"].includes(args[0]!))) return { text: help(), code: 0 };
+  const usage = commandHelp(args);
+  if (usage) return { text: usage, code: 0 };
   if (args.length === 1 && args[0] === "--version") return { text: version, code: 0 };
   if (args[0] === "manifest") {
     const { flags, positional } = parse(args.slice(1), ["--json"], []);
@@ -52,18 +62,19 @@ export function run(args: string[], env: NodeJS.ProcessEnv = process.env): { tex
   if (args[0] === "log") return runLogCommand(args.slice(1), resolveHome(env).home, env);
   if (isWriteCommand(args[0]!)) return runWriteCommand(args[0]!, args.slice(1), resolveHome(env).home, env);
   if (isReadCommand(args[0]!)) return runReadCommand(args[0]!, args.slice(1), resolveHome(env).home);
-  const command = args[0] === "vaults" ? `vaults ${args[1] ?? ""}` : args[0];
-  const tail = args.slice(args[0] === "vaults" ? 2 : 1);
-  const options = command === "vaults add" ? ["--kind", "--write", "--pii", "--remote", "--registry"] : command === "vaults pii" ? ["--set"] : [];
-  const { flags, positional } = parse(tail, ["--json", ...options, ...(command === "vaults remove" || command === "vaults pii" || command === "recover" ? ["--confirm"] : [])], options);
+  const group = args[0] === "vaults" || args[0] === "specs";
+  const command = group ? `${args[0]} ${args[1] ?? ""}` : args[0];
+  const tail = args.slice(group ? 2 : 1);
+  const options = command === "vaults add" ? ["--kind", "--write", "--pii", "--remote", "--registry"] : command === "vaults pii" ? ["--set"] : command === "specs add" ? ["--write", "--pii"] : [];
+  const { flags, positional } = parse(tail, ["--json", ...options, ...(command === "vaults remove" || command === "specs remove" || command === "vaults pii" || command === "recover" ? ["--confirm"] : [])], options);
   const home = resolveHome(env);
   let result: unknown, code = 0;
   switch (command) {
     case "status": case "doctor": {
       if (positional.length) throw new Error(`${command}: unexpected arguments`);
-      const config = command === "doctor" ? loadRegistry(home.home) : undefined;
+      const config = loadRegistry(home.home);
       const vaults = registryStatus(home.home).map(vault => {
-        if (command !== "doctor" || !vault.healthy || (!vault.remote && !vault.registry)) return vault;
+        if (command !== "doctor" || !vault.healthy) return { ...vault, checks: undefined };
         const checks: Record<string, { ok: boolean; issue?: string }> = {};
         if (vault.remote) {
           try {
@@ -72,13 +83,26 @@ export function run(args: string[], env: NodeJS.ProcessEnv = process.env): { tex
           } catch (error) { checks.remote = { ok: false, issue: error instanceof Error ? error.message : "git failed" }; }
         }
         if (vault.registry) {
-          try { registryIds(vault.registry, config!.denyPaths); checks.registry = { ok: true }; }
+          try { registryIds(vault.registry, config.denyPaths); checks.registry = { ok: true }; }
           catch (error) { checks.registry = { ok: false, issue: error instanceof Error ? error.message : "cannot read project registry" }; }
         }
-        return { ...vault, checks };
+        let preview: ReturnType<typeof tidyVault> | undefined;
+        try {
+          if (vault.write !== "none") preview = tidyVault(home.home, { vault: vault.id, rules: [...TIDY_RULES] }, { env, validate: false });
+        } catch (error) { checks.tidy = { ok: false, issue: error instanceof Error ? error.message : "cannot preview migration tidy" }; }
+        if (preview && !preview.ok) {
+          const failures = preview.issues.filter(issue => issue.code !== "POLICY" && issue.code !== "PII_POLICY");
+          if (failures.length) checks.tidy = { ok: false, issue: failures.map(issue => `${issue.code}: ${issue.message}`).join("; ") };
+        }
+        const unparsable = preview?.reported.filter(item => item.message.startsWith("unparsable note skipped")).map(item => item.path) ?? [];
+        const tidy = preview?.ok && (preview.notes.length || unparsable.length || Object.values(preview.counts).some(count => count > 0))
+          ? { pending: preview.counts, notes: preview.notes.length, unparsable, hint: `Run vmem tidy ${vault.id} --all, then confirm its preview fingerprint to apply the migration.` }
+          : undefined;
+        return { ...vault, checks: Object.keys(checks).length ? checks : undefined, ...(tidy ? { tidy } : {}) };
       });
-      const healthy = vaults.every(v => v.healthy && (!("checks" in v) || Object.values(v.checks).every(check => check.ok)));
-      result = { ...home, version, stage: "foundation", healthy, vaults };
+      const sources = command === "doctor" && config.specs !== undefined ? specStatus(home.home, env) : undefined;
+      const healthy = vaults.every(v => v.healthy && (!v.checks || Object.values(v.checks).every(check => check.ok))) && (!sources || sources.every(source => source.healthy));
+      result = { ...home, version, stage: "foundation", healthy, vaults, ...(config.specs !== undefined ? { specs: sources ?? config.specs } : {}) };
       if (command === "doctor" && !healthy) code = 1;
       break;
     }
@@ -87,6 +111,21 @@ export function run(args: string[], env: NodeJS.ProcessEnv = process.env): { tex
       result = recoverRegistry(home.home, flags["--confirm"] === true);
       if ((result as { blocked?: string }).blocked) code = 1;
       break;
+    case "specs list":
+      if (positional.length) throw new Error("specs list: unexpected targets; use vmem specs list [--json]");
+      result = loadRegistry(home.home).specs ?? [];
+      break;
+    case "specs add": {
+      if (positional.length !== 2) throw new Error("specs add: requires id and absolute repository root; use vmem specs add <id> <absolute-path> [--write mcp|cli|none] [--pii allow|deny]");
+      const value: Record<string, unknown> = { id: positional[0], path: positional[1] };
+      for (const option of options) if (flags[option] !== undefined) value[option.slice(2)] = flags[option];
+      result = { applied: true, spec: addSpec(home.home, value, env) };
+      break;
+    }
+    case "specs remove":
+      if (positional.length !== 1) throw new Error("specs remove: requires one id; use vmem specs list, then vmem specs remove <id> [--confirm]");
+      result = removeSpec(home.home, positional[0]!, flags["--confirm"] === true);
+      break;
     case "vaults list":
       if (positional.length) throw new Error("vaults list: unexpected arguments");
       result = loadRegistry(home.home).vaults.map(v => ({ ...v, pii: effectivePii(v), piiPolicy: piiPolicy(v) }));
@@ -129,6 +168,8 @@ export async function runMcp(env: NodeJS.ProcessEnv = process.env): Promise<void
 }
 /** Async commands. Only `promote-from-amem` and `skills mine` load the agent-mem seam, and only when they run. */
 export async function runAsync(args: string[], env: NodeJS.ProcessEnv = process.env, io: { stdinIsTTY?: boolean } = {}): Promise<{ text: string; code: number }> {
+  const usage = commandHelp(args);
+  if (usage) return { text: usage, code: 0 };
   if (args[0] === "skills") {
     const { runSkillsCommand } = await import("./skills-mine.ts");
     return runSkillsCommand(args.slice(1), resolveHome(env).home, env);

package/src/commands-table.ts

@@ -14,6 +14,9 @@ export const COMMANDS = [
   { name: "vaults add", usage: "vaults add <id> <absolute-path> --kind personal|org --write mcp|cli|none [--pii allow|deny] [--remote URL] [--registry PATH] [--json]", mutates: true },
   { name: "vaults remove", usage: "vaults remove <id> [--confirm] [--json]", mutates: "confirm" },
   { name: "vaults pii", usage: "vaults pii <id> [--set allow|deny|JSON] [--confirm] [--json]", mutates: "confirm" },
+  { name: "specs list", usage: "specs list [--json]", mutates: false },
+  { name: "specs add", usage: "specs add <id> <absolute-path> [--write mcp|cli|none] [--pii allow|deny] [--json]", mutates: true },
+  { name: "specs remove", usage: "specs remove <id> [--confirm] [--json]", mutates: "confirm" },
   { name: "new", usage: "new <vault> <stem> --type TYPE --domain DOMAIN --topics a,b --description TEXT [--title TEXT] [--source TEXT|JSON] [--confidence TEXT] [--status TEXT] [--body file|-] [--extra JSON] [--dry-run] [--json]", mutates: true },
   { name: "patch", usage: "patch <vault> <note> --old TEXT --new TEXT [--expected-sha SHA] [--dry-run] [--json]", mutates: true },
   { name: "append", usage: "append <vault> <note> --section SECTION --markdown TEXT [--expected-sha SHA] [--dry-run] [--json]", mutates: true },
@@ -69,7 +72,7 @@ export function completionScript(shell: string): string {
       const cond = d.path.length === 1 ? `__fish_seen_subcommand_from ${d.path[0]}` : `__fish_seen_subcommand_from ${d.path[1]}`;
       for (const flag of Object.keys(d.options)) lines.push(`complete -c vmem -n ${quote(cond)} -l ${flag.slice(2)}`);
     }
-    for (const parent of ["vaults", "log", "graph", "skills"]) lines.push(`complete -c vmem -n '__fish_seen_subcommand_from ${parent}' -a ${quote(defs.filter(d => d.path[0] === parent).map(d => d.path[1]).join(" "))}`);
+    for (const parent of ["vaults", "specs", "log", "graph", "skills"]) lines.push(`complete -c vmem -n '__fish_seen_subcommand_from ${parent}' -a ${quote(defs.filter(d => d.path[0] === parent).map(d => d.path[1]).join(" "))}`);
     return lines.join("\n") + "\n";
   }
   const cases = defs.map(d => `    ${quote(d.path.join(" "))}) words=${quote(Object.keys(d.options).join(" "))} ;;`);
@@ -78,7 +81,7 @@ export function completionScript(shell: string): string {
   cur="\${COMP_WORDS[COMP_CWORD]}"
   if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W ${quote(top.join(" "))} -- "$cur")); return; fi
   key="\${COMP_WORDS[1]}"
-  case "$key" in graph) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'build neighbors' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; skills) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'mine' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; vaults|log) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W "$( [ "$key" = vaults ] && echo 'list add remove' || echo 'tail grep append')" -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; esac
+  case "$key" in graph) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'build neighbors' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; skills) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'mine' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; specs) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'list add remove' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; vaults|log) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W "$( [ "$key" = vaults ] && echo 'list add remove' || echo 'tail grep append')" -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; esac
   case "$key" in
 ${cases.join("\n")}
     *) words='' ;;

package/src/config.ts

@@ -23,10 +23,11 @@ export interface PiiSpec { email?: PiiCell; phone?: PiiCell; custom?: PiiCell; p
  * The config format this build writes. A build that adds a key bumps it. A config whose `version` is newer
  * than this build is read tolerantly: unknown keys are kept as they are and written back unchanged, so an
  * older vmem can share a config with a newer one. At or below this version unknown keys stay errors (typos).
- * An absent `version` means 1, and this build never adds one, so 0.2.4 and older keep reading what it writes.
+ * An absent `version` means 1. Registry writes add format 2 only when `specs` is present; vault-only configs keep their existing version field.
  */
-export const CONFIG_VERSION = 1;
-export interface VmemConfig { version?: number; home?: string; vaults: VaultSpec[]; denyPaths?: string[]; piiPatterns?: string[] }
+export const CONFIG_VERSION = 2;
+export interface SpecSourceSpec { id: string; path: string; write: "mcp" | "cli" | "none"; pii: "allow" | "deny" }
+export interface VmemConfig { version?: number; home?: string; vaults: VaultSpec[]; specs?: SpecSourceSpec[]; denyPaths?: string[]; piiPatterns?: string[] }
 const controls = /[\x00-\x1f\x7f]/;
 function object(value: unknown, keys: string[], label: string, tolerant = false): Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label}: expected object`);
@@ -125,25 +126,44 @@ export function parseVault(value: unknown, tolerant = false): VaultSpec {
   if (v.registry !== undefined) result.registry = absolute(v.registry, "vault.registry");
   return result;
 }
+/** Spec sources have their own registry shape; they are not vaults. */
+export function parseSpec(value: unknown, tolerant = false): SpecSourceSpec {
+  try {
+    const keys = ["id", "path", "write", "pii"], raw = object(value, keys, "spec source", tolerant);
+    const id = string(raw.id, "spec source.id");
+    if (!/^[a-z][a-z0-9-]{0,31}$/.test(id)) throw new Error("spec source.id: expected a lowercase letter followed by at most 31 lowercase letters, digits or hyphens");
+    const write = raw.write === undefined ? "none" : raw.write, pii = raw.pii === undefined ? "deny" : raw.pii;
+    if (write !== "mcp" && write !== "cli" && write !== "none") throw new Error("spec source.write: expected mcp, cli or none");
+    if (pii !== "allow" && pii !== "deny") throw new Error("spec source.pii: expected allow or deny");
+    return { ...unknown(raw, keys, tolerant), id, path: absolute(raw.path, "spec source.path"), write, pii };
+  } catch (error) {
+    throw new Error(`${error instanceof Error ? error.message : "invalid spec source"}; use vmem specs add <id> <absolute-path> with --write mcp|cli|none and --pii allow|deny`);
+  }
+}
 export function parseConfig(value: unknown): VmemConfig {
-  const keys = ["version", "home", "vaults", "denyPaths", "piiPatterns"];
+  const keys = ["version", "home", "vaults", "specs", "denyPaths", "piiPatterns"];
   const version = (value as Record<string, unknown> | null)?.version;
   if (version !== undefined && (!Number.isSafeInteger(version) || (version as number) < 1)) throw new Error("config.version: expected a positive integer");
   const tolerant = newerFormat(value), raw = object(value, keys, "config", tolerant);
   const stamp = version === undefined ? {} : { version: version as number };
   if (raw.home !== undefined) {
-    if (["vaults", "denyPaths", "piiPatterns"].some(key => raw[key] !== undefined)) throw new Error("config: home pointer must not contain vaults or policy");
+    if (["vaults", "specs", "denyPaths", "piiPatterns"].some(key => raw[key] !== undefined)) throw new Error("config: home pointer must not contain vaults, specs or policy; put source entries in the pointed-to home config");
     return { ...unknown(raw, keys, tolerant), ...stamp, home: absolute(raw.home, "config.home"), vaults: [] };
   }
-  if (!Array.isArray(raw.vaults)) throw new Error("config.vaults: expected array");
-  const vaults = raw.vaults.map(item => parseVault(item, tolerant));
+  const vaultInput = raw.vaults === undefined && raw.specs !== undefined ? [] : raw.vaults;
+  if (!Array.isArray(vaultInput)) throw new Error("config.vaults: expected array");
+  const vaults = vaultInput.map(item => parseVault(item, tolerant));
+  if (raw.specs !== undefined && !Array.isArray(raw.specs)) throw new Error("config.specs: expected an array; list spec source entries in specs");
+  const specs = (raw.specs as unknown[] | undefined)?.map(item => parseSpec(item, tolerant));
+  if (specs && new Set([...vaults, ...specs].map(source => source.id)).size !== vaults.length + specs.length) throw new Error("config: duplicate source id across vaults/specs; give each registered source a unique id");
+  if (specs && new Set(specs.map(source => source.path)).size !== specs.length) throw new Error("config: duplicate spec source path; keep only one entry for each repository root");
   if (new Set(vaults.map(v => v.id)).size !== vaults.length) throw new Error("config: duplicate vault id");
   if (new Set(vaults.map(v => v.path)).size !== vaults.length) throw new Error("config: duplicate vault path");
   const denyPaths = strings(raw.denyPaths, "denyPaths"), piiPatterns = strings(raw.piiPatterns, "piiPatterns");
   for (const pattern of piiPatterns ?? []) {
     try { new RegExp(pattern); } catch { throw new Error("piiPatterns: invalid regular expression"); }
   }
-  return { ...unknown(raw, keys, tolerant), ...stamp, vaults, ...(denyPaths ? { denyPaths } : {}), ...(piiPatterns ? { piiPatterns } : {}) };
+  return { ...unknown(raw, keys, tolerant), ...stamp, vaults, ...(specs !== undefined ? { specs } : {}), ...(denyPaths ? { denyPaths } : {}), ...(piiPatterns ? { piiPatterns } : {}) };
 }
 /** Bounded descriptor read: reject links, devices and oversized/growing files. */
 export function readConfig(home: string): VmemConfig {

package/src/index.ts

@@ -1,7 +1,7 @@
 export { resolveHome } from "./home.ts";
-export { parseConfig, parseVault, readConfig, CONFIG_FILE, MAX_CONFIG_BYTES } from "./config.ts";
-export type { VaultSpec, VmemConfig } from "./config.ts";
-export { addVault, removeVault, loadRegistry, registryStatus, recoverRegistry, effectivePii, syncDirectory, LOCK_FILE } from "./registry.ts";
+export { parseConfig, parseVault, parseSpec, readConfig, CONFIG_FILE, MAX_CONFIG_BYTES } from "./config.ts";
+export type { VaultSpec, SpecSourceSpec, VmemConfig } from "./config.ts";
+export { addVault, removeVault, addSpec, removeSpec, specStatus, loadRegistry, registryStatus, recoverRegistry, effectivePii, syncDirectory, LOCK_FILE } from "./registry.ts";
 export type { RecoveryReport, LockOwner } from "./registry.ts";
 export { parseFrontmatter, emitFrontmatter } from "./frontmatter.ts";
 export type { FrontmatterDocument } from "./frontmatter.ts";
@@ -42,3 +42,8 @@ export { normalizeSource, sourceReferences } from "./source.ts";
 export type { SourceValue, SourceReference } from "./source.ts";
 export { tidyVault, parseTidyMap, TIDY_RULES } from "./tidy.ts";
 export type { TidyRequest, TidyResult, TidyRule, TidyMap } from "./tidy.ts";
+
+export { resolveSpecWorktree, discoverSpecs, SpecIndex } from "./spec-source.ts";
+export type { SpecDocument, SpecDiagnostic, SpecSnapshot, SpecSourceOptions, SpecIndexOptions, SpecSearchResult } from "./spec-source.ts";
+export { buildSpecGraph, specSlice, SPEC_EDGE_KINDS, MAX_SPEC_INPUTS, MAX_SPEC_EDGES } from "./spec-graph.ts";
+export type { SpecNode, SpecEdge, SpecEdgeKind, SpecGraph, SpecSliceOptions, SpecSlice } from "./spec-graph.ts";

package/src/log-commands.ts

@@ -8,7 +8,7 @@ export function runLogCommand(args: string[], home: string, env: NodeJS.ProcessE
   for (let i = 1; i < args.length; i++) {
     const word = args[i]!;
     if (!word.startsWith("--")) { positional.push(word); continue; }
-    if (Object.hasOwn(flags, word) || (word !== "--json" && !values.includes(word))) throw new Error("log: unknown or repeated option");
+    if (Object.hasOwn(flags, word) || (word !== "--json" && !values.includes(word))) throw new Error(`log ${command}: unknown or repeated option: ${word}`);
     if (word === "--json") flags[word] = true;
     else {
       const value = args[++i]; if (value === undefined || value.startsWith("--")) throw new Error("log: option value required");

package/src/mcp-vault.ts

@@ -44,7 +44,7 @@ export function vaultTools(ids: readonly string[], orgIds: readonly string[] = [
     tool("vmem_mocs", "MOC notes with incoming link counts.", object({ vault })),
     tool("vmem_check", "Validate a prospective note text without writing.", object({ vault, path: string(200), text: string(262144, 0) }, ["text"])),
     tool("vmem_log_tail", "Read the newest vault log lines, optionally filtered.", object({ vault, n: integer(1, 200), type: { type: "string", enum: LOG_TYPES }, grep: string(256) })),
-    tool("vmem_create", "Create a validated note. Requires a vault with write=mcp.", object({ vault, stem: string(200), type: string(64), domain: string(64), topics: { type: "array", maxItems: 32, items: string(200) }, description: string(1000), title: string(300), body: string(65536, 0), source: { type: ["string", "array"], minLength: 1, maxLength: 512, minItems: 1, maxItems: 32, items: string(512) }, confidence: string(32), status: string(32), extra: { type: "object", maxProperties: 32, additionalProperties: scalar }, log: logEvent }, ["stem", "type", "domain", "description"]), "write"),
+    tool("vmem_create", "Create a validated note. Requires a vault with write=mcp.", object({ vault, stem: string(200), type: string(64), domain: string(64), topics: { type: "array", maxItems: 32, items: string(200) }, description: string(1000), title: string(300), body: string(65536, 0), source: { type: ["string", "array"], minLength: 1, maxLength: 512, minItems: 1, maxItems: 32, items: string(512) }, confidence: string(32), status: string(32), created: string(32, 0), extra: { type: "object", maxProperties: 32, additionalProperties: scalar }, log: logEvent }, ["stem", "type", "domain", "description"]), "write"),
     tool("vmem_patch", "Replace one exact string in a note.", object({ vault, path: note, oldString: string(8192), newString: string(8192, 0), expectedSha: sha }, ["path", "oldString", "newString"]), "write"),
     tool("vmem_append", "Append markdown to a section of a note.", object({ vault, path: note, section: string(120), markdown: string(16384), expectedSha: sha }, ["path", "section", "markdown"]), "write"),
     tool("vmem_set_frontmatter", "Set or unset frontmatter keys of a note.", object({ vault, path: note, set: { type: "object", maxProperties: 32, additionalProperties: scalar }, unset: { type: "array", maxItems: 32, items: string(64) }, expectedSha: sha }, ["path"]), "write"),
@@ -140,8 +140,12 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
     vmem_check: args => write(args, { op: "check", path: notePath(str(args.path) ?? "checked-note"), text: str(args.text)! }),
     vmem_log_tail: args => readLog(home, { vault: pick(args).id, limit: (args.n as number | undefined) ?? 50, ...(str(args.type) ? { type: str(args.type) } : {}), ...(str(args.grep) ? { grep: str(args.grep) } : {}) }),
     vmem_create: args => {
+      if (args.created !== undefined) {
+        const created = str(args.created), time = typeof created === "string" && /^\d{4}-\d{2}-\d{2}$/.test(created) ? Date.parse(created + "T00:00:00Z") : NaN;
+        if (!Number.isFinite(time) || new Date(time).toISOString().slice(0, 10) !== created) return refusal("V01", "created: expected YYYY-MM-DD");
+      }
       const frontmatter: Record<string, unknown> = { ...(args.extra as Record<string, unknown> | undefined ?? {}) };
-      for (const key of ["type", "domain", "description", "title", "source", "confidence", "status"]) if (str(args[key]) !== undefined) frontmatter[key] = args[key];
+      for (const key of ["type", "domain", "description", "title", "source", "confidence", "status", "created"]) if (str(args[key]) !== undefined) frontmatter[key] = args[key];
       if (Array.isArray(args.source)) frontmatter.source = args.source as string[];
       if (Array.isArray(args.topics)) frontmatter.topics = (args.topics as string[]).map(v => v.startsWith("[[") ? v : `[[${v}]]`);
       return write(args, { op: "create", path: str(args.stem)!, frontmatter, ...(str(args.body) !== undefined ? { body: str(args.body) } : {}) });

package/src/mcp.ts

@@ -9,31 +9,54 @@ export interface McpServerOptions { tools: readonly McpTool[]; handlers: Record<
 const protocols = ["2025-06-18", "2025-03-26", "2024-11-05"];
 const plain = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
 
-/** Runtime validation for the small schema vocabulary the tools use. Unknown keywords never widen acceptance. */
-export function validArguments(value: unknown, raw: unknown): boolean {
+/** First schema failure only; paths and schema limits are reported, never argument values. */
+export function argumentError(value: unknown, raw: unknown, path = ""): string | undefined {
+  const at = path || "arguments", fail = (reason: string) => `${at}: ${reason}`;
+  if (!plain(raw)) return fail("invalid schema");
   const s = raw as Record<string, any>, type = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
   const types: unknown[] = Array.isArray(s.type) ? s.type : [s.type];
-  if (!types.includes(type) && !(type === "number" && Number.isSafeInteger(value) && types.includes("integer"))) return false;
-  if (type === "number" && !types.includes("number") && !Number.isSafeInteger(value)) return false;
-  if (s.enum && !s.enum.includes(value)) return false;
-  if (typeof value === "string" && (value.length < (s.minLength ?? 0) || value.length > (s.maxLength ?? FRAME_BYTES) || value.includes("\0"))) return false;
-  if (typeof value === "number" && (!Number.isFinite(value) || value < (s.minimum ?? -Infinity) || value > (s.maximum ?? Infinity))) return false;
-  if (Array.isArray(value)) {
-    if (value.length < (s.minItems ?? 0) || value.length > (s.maxItems ?? 64) || !plain(s.items)) return false;
-    return value.every(item => validArguments(item, s.items));
+  if (!types.includes(type) && !(type === "number" && Number.isSafeInteger(value) && types.includes("integer"))) return fail(`expected ${types.join(" or ")}`);
+  if (type === "number" && !types.includes("number") && !Number.isSafeInteger(value)) return fail("expected safe integer");
+  if (s.enum && !s.enum.includes(value)) return fail("not an allowed value");
+  if (typeof value === "string") {
+    if (value.length < (s.minLength ?? 0)) return fail(`shorter than ${s.minLength}`);
+    if (value.length > (s.maxLength ?? FRAME_BYTES)) return fail(`longer than ${s.maxLength ?? FRAME_BYTES}`);
+    if (value.includes("\0")) return fail("NUL is not allowed");
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return fail("expected finite number");
+    if (value < (s.minimum ?? -Infinity)) return fail(`less than ${s.minimum}`);
+    if (value > (s.maximum ?? Infinity)) return fail(`greater than ${s.maximum}`);
   }
-  if (plain(value)) {
+  if (Array.isArray(value)) {
+    if (value.length < (s.minItems ?? 0)) return fail(`fewer than ${s.minItems} items`);
+    if (value.length > (s.maxItems ?? 64)) return fail(`more than ${s.maxItems ?? 64} items`);
+    if (!plain(s.items)) return fail("invalid item schema");
+    for (let i = 0; i < value.length; i++) {
+      const error = argumentError(value[i], s.items, `${path}[${i}]`);
+      if (error) return error;
+    }
+  } else if (plain(value)) {
     const keys = Object.keys(value);
-    if (keys.length < (s.minProperties ?? 0) || keys.length > (s.maxProperties ?? 64)) return false;
-    if ((s.required ?? []).some((key: string) => !Object.hasOwn(value, key))) return false;
+    if (keys.length < (s.minProperties ?? 0)) return fail(`fewer than ${s.minProperties} properties`);
+    if (keys.length > (s.maxProperties ?? 64)) return fail(`more than ${s.maxProperties ?? 64} properties`);
+    for (const key of s.required ?? []) if (!Object.hasOwn(value, key)) return `${path ? path + "." : ""}${key}: required`;
     for (const key of keys) {
-      if (["__proto__", "prototype", "constructor"].includes(key) || key.length > 200) return false;
-      if (Object.hasOwn(s.properties ?? {}, key)) { if (!validArguments(value[key], s.properties[key])) return false; }
-      else if (s.additionalProperties === false || !plain(s.additionalProperties) || !validArguments(value[key], s.additionalProperties)) return false;
+      if (key.length > 200) return fail("property name longer than 200");
+      const child = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? (path ? `${path}.${key}` : key) : `${path || "$"}[${JSON.stringify(key)}]`;
+      if (["__proto__", "prototype", "constructor"].includes(key)) return `${child}: forbidden property name`;
+      let schema;
+      if (Object.hasOwn(s.properties ?? {}, key)) schema = s.properties[key];
+      else if (s.additionalProperties === false || !plain(s.additionalProperties)) return `${path ? path + ": " : ""}unknown argument: ${key}`;
+      else schema = s.additionalProperties;
+      const error = argumentError(value[key], schema, child);
+      if (error) return error;
     }
-  } else if (type === "object") return false;
-  return true;
+  } else if (type === "object") return fail("expected plain object");
+  return undefined;
 }
+/** Boolean compatibility API for the same closed, bounded schema vocabulary. */
+export function validArguments(value: unknown, raw: unknown): boolean { return argumentError(value, raw) === undefined; }
 
 /** Serve until input ends. stdout carries protocol messages only; nothing else is written to `output`. */
 export async function serveMcp(options: McpServerOptions): Promise<void> {
@@ -70,7 +93,9 @@ export async function serveMcp(options: McpServerOptions): Promise<void> {
     if (!plain(params) || Object.keys(params).some(k => !["name", "arguments", "_meta"].includes(k)) || typeof params.name !== "string") { await error(id, -32602, "Invalid tool call"); return; }
     const definition = options.tools.find(t => t.name === params.name), args = params.arguments ?? {};
     const handler = definition && options.handlers[definition.name];
-    if (!definition || !handler || !validArguments(args, definition.inputSchema)) { await error(id, -32602, "Invalid tool name or arguments"); return; }
+    if (!definition || !handler) { await error(id, -32602, `unknown tool: ${params.name.slice(0, 200)}`); return; }
+    const invalid = argumentError(args, definition.inputSchema);
+    if (invalid) { await error(id, -32602, invalid); return; }
     let result: unknown;
     try {
       const text = JSON.stringify(await handler(args as Record<string, unknown>));

package/src/org-promote.ts

@@ -8,7 +8,7 @@ import { normalizeTarget, proseLines } from "./links.ts";
 import { loadRegistry } from "./registry.ts";
 import { VaultIndex } from "./vault-index.ts";
 import { applyWrite } from "./writer.ts";
-import { notePath } from "./write-operations.ts";
+import { notePath, replaceTopicsSection } from "./write-operations.ts";
 import { screenContent } from "./write-validation.ts";
 import { appendLog, logBinding } from "./vault-log.ts";
 import type { WriteIssue, WriteReceipt } from "./write-types.ts";
@@ -97,19 +97,6 @@ function screenDroppedLinks(home: string, source: VaultSpec, all: VaultSpec[], d
   // Counts and categories only: the linked names are exactly what must not be echoed.
   return [...found].map(([category, count]) => issue("SCREEN", `${category}: ${count} body link${count === 1 ? "" : "s"} point at notes that are never promoted; remove those links from the source note first`));
 }
-/** Replace the last prose `## Topics` section (never one inside a fence) with the given topics; append one if absent. */
-export function replaceTopicsSection(body: string, topics: string[]): string {
-  const prose = proseLines(body), raw = body.split("\n");
-  let start = -1;
-  for (let i = prose.length - 1; i >= 0; i--) if (/^ {0,3}##[ \t]+Topics[ \t]*#*[ \t]*$/.test(prose[i]!)) { start = i; break; }
-  const section = ["## Topics", "", ...topics.map(topic => `- ${topic}`), ""];
-  if (start < 0) return `${body.replace(/\n*$/, "")}\n\n${section.join("\n")}`;
-  // The section ends at the next prose heading of level 1 or 2.
-  let end = raw.length;
-  for (let i = start + 1; i < prose.length; i++) if (/^ {0,3}#{1,2}[ \t]/.test(prose[i]!)) { end = i; break; }
-  const tail = raw.slice(end);
-  return [...raw.slice(0, start), ...section, ...(tail.length ? tail : [])].join("\n").replace(/\n*$/, "\n");
-}
 /** Replace visible wiki links whose target does not resolve in the target vault with their plain text. */
 export function dropUnresolvedLinks(body: string, resolves: (target: string) => boolean): { body: string; dropped: string[] } {
   const prose = proseLines(body), raw = body.split("\n"), dropped: string[] = [];