@williamthorsen/nmr 0.39.0 → 0.40.0

package/README.md

@@ -2,53 +2,21 @@
 
 # @williamthorsen/nmr
 
-Context-aware script runner for pnpm monorepos. Ships an `nmr` (node-monorepo run) binary that provides centralized, consistent script execution across workspace packages and the monorepo root.
+Context-aware script runner for pnpm monorepos. Includes an `nmr` (node-monorepo run) binary that provides centralized, consistent script execution across workspace packages and the monorepo root.
 
 <!-- section:release-notes -->
-## Release notes — v0.39.0 (2026-09-22)
+## Release notes — v0.40.0 (2026-10-01)
 
 ### 🎉 Features
 
-- Report why a workspace selects no package, and no-op nmr's own -R steps (#841)
+- Makes `checkTestFileConventions` and the readyup kit's tier and placement checks skip untracked paths that git ignores, so that local build output such as a stale `.netlify/` directory no longer fails the check. (#898)
+- Excludes untracked paths that git ignores from collection in `defineVitestConfig` and `defineRootVitestConfig`, so that Vitest does not run a test file that the conventions check skips. (#898)
+- Rewords the `nmr --log` refusal for a run that the check-result cache does not cover to `the check-result cache does not apply here (NMR_DEBUG=1 reports why)`, and renames the matching `docs/check-cache.md` heading to "When the cache does not apply", which changes its anchor. (#923)
 
-  - Drops a `-R` step that nmr composed into a script where the workspace holds no package, so `typecheck` and the five `test` scripts run there instead of failing the run.
-  - Adds a no-op verdict for a command that the drop leaves with no step at all.
-  - Replaces the single refusal for a workspace that selects no package with one message per cause.
+### 🐛 Bug fixes
 
-  Migration: In a repo that declares a workspace package pattern and deliberately holds no package, delete the `.config/nmr.config.ts` entries added to work around the `-R` refusal, the `build: ':'` override included.
-
-- 🚨 **Breaking:** Prefix the booleans and reject unrecognized Vitest option keys (#849)
-
-  - Renames two boolean options of `defineVitestConfig` and `defineRootVitestConfig`, the factories that build a repo's Vitest config: `isolateGit` becomes `shouldIsolateGit`, and `resolveFromSource` becomes `shouldResolveFromSource`.
-  - Makes both factories reject an option key outside the recognized set, naming the offending keys and the recognized ones, rather than ignoring a misspelled or retired key and letting its option fall back to the default with nothing in the run reporting it.
-  - Adds a retired-key check that runs ahead of the unrecognized-key check, reporting the new name for a config that still sets `isolateGit` or `resolveFromSource`.
-
-  Migration: In each options object passed to `defineVitestConfig` or `defineRootVitestConfig`, rename `isolateGit` to `shouldIsolateGit` and `resolveFromSource` to `shouldResolveFromSource`, and correct any other key that the factory now rejects. `defineRootVitestConfig` recognizes `monorepoRoot` on the last layer alone, so a config that sets it on an earlier layer now throws where the old code ignored it.
-
-- 🚨 **Breaking:** End nmr's source value names with the kind of the value (#850)
-
-  - Renames two fields of `TestFileConventionsReport`, `misplaced` and `untiered`, to `misplacedFiles` and `untieredFiles`, and renames `TestFileConventionsOptions`'s `exclude` to `excludedBasenames`, in the `@williamthorsen/nmr/tests` entry point.
-  - Adds a guard to `checkTestFileConventions` and `reportTestFileConventions` that throws a `TypeError` naming `excludedBasenames` when a call still sets `exclude`.
-
-  Migration: Read `report.misplacedFiles` and `report.untieredFiles` in place of `report.misplaced` and `report.untiered`, and pass `excludedBasenames` in place of `exclude`. A call that still sets `exclude` throws rather than running with no exclusions, so the failure surfaces where Vitest loads the call site.
-
-- 🚨 **Breaking:** Hoist the pnpm-workspace resolver into nmr-core as a total API (#864)
-
-  - Adds a `./workspace` subpath export to `@williamthorsen/nmr-core`, whose `resolveWorkspace` returns a pnpm workspace's package directories, or the cause of an empty result, as a value rather than as a thrown error.
-  - Reports a `pnpm-workspace.yaml` that the YAML parser rejects under a cause of its own, `unreadable-manifest`, so `nmr -R build` names the syntax error and its remedy in place of failing with the parser's own error.
-  - Removes `diagnoseEmptyWorkspace` and `EmptyWorkspaceDiagnosis` from `@williamthorsen/nmr/workspace`, since `resolveWorkspace` reports the same cause in one call.
-
-  Migration: Replace each `diagnoseEmptyWorkspace` call with `resolveWorkspace`, which reports the cause on the empty result it already returns, and rename the `no-manifest` cause to `no-package`. `EmptyWorkspaceCause` also gains `unreadable-manifest`, so an exhaustive switch over it stops compiling until it handles the new member; every other export of `@williamthorsen/nmr/workspace` keeps its signature and its `UserError` throws.
-
-- 🚨 **Breaking:** Adopt the shared workspace resolver in release-kit, honoring exclusions (#865)
-
-  - 🚨 **Breaking:** Narrows `no-pattern` in `@williamthorsen/nmr-core`'s `EmptyWorkspaceCause`, moving an absent or empty `packages` list onto `no-packages-list` and a value that is not a list of strings onto `unreadable-packages`.
-  - Stops `release-kit` from tagging, publishing, and label-syncing a package that a `!` entry in `pnpm-workspace.yaml` excludes, which its previous `glob`-based resolution could not remove from the match.
-  - Replaces the release of the root package alone with a failure naming the condition that emptied the workspace, when `pnpm-workspace.yaml` does not hold valid YAML or declares a workspace that does not resolve to a package.
-  - Replaces the `no-pattern` remedy that `nmr` printed for a `pnpm-workspace.yaml` declaring no `packages` list, and for one declaring a `packages` value that is not a list of strings.
-  - Raises `engines.node` to `>=24.16.0` in `@williamthorsen/nmr-core` and `@williamthorsen/release-kit`, because Node 24.0 through 24.15 ignores the `followSymlinks` option that the workspace matcher passes to `globSync` and drops a symlinked package directory from the resolution without reporting it.
-
-  Migration: Add a `no-packages-list` arm and an `unreadable-packages` arm to any `switch` that covers `EmptyWorkspaceCause` exhaustively. `no-pattern` now names only a list that the resolver read in full and whose entries all failed to become a positive pattern, so move the handling of an absent `packages` key, an empty list, and a value that is not a list of strings out of the `no-pattern` arm into the two new ones. Route `no-packages-list` to single-package behavior rather than to a failure path: pnpm resolves such a manifest to the root package alone.
+- Rewords the messages printed by `nmr`, its bin wrappers, and its readyup kit, which used figures such as "sits under" and "holds", em-dashes, and "no" as a determiner, so that a diagnosis such as "-F/--filter did not match any workspace" states its condition directly. (#932)
+- Fixes the issue that the `nmr` rulebook recommended `-q` without stating that nmr reads its own flags only before the command name, which led agents to run `nmr ci -q` and fail when `nmr-fmt` rejected the flag. (#948)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -61,16 +29,16 @@ pnpm add -D @williamthorsen/nmr
 
 ### Making `nmr` resolvable
 
-nmr installs as a workspace bin, so the bare `nmr` command works only when your shell can find `<root>/node_modules/.bin/nmr`. Choose one:
+nmr installs as a workspace bin, so the bare `nmr` command works only when the shell can find `<root>/node_modules/.bin/nmr`. Choose one:
 
 - **[direnv](https://direnv.net/)** (recommended for contributors). Add `PATH_add node_modules/.bin` to the repo's `.envrc`, and bare `nmr` works from any subdirectory.
-- **`pnpm exec nmr <command>`**. Works with no setup: pnpm resolves the bin from the workspace root.
+- **`pnpm exec nmr <command>`**. Works without any setup: pnpm resolves the bin from the workspace root.
 
 > **Note:** Avoid `npx nmr`. Inside a git worktree, `npx` can resolve a different nmr binary from outside the working tree, so the command succeeds while running the wrong code.
 
 ## Quick start
 
-nmr works out of the box with no configuration. It ships with built-in scripts for common monorepo tasks.
+nmr works without any configuration. It includes built-in scripts for common monorepo tasks.
 
 From a package directory:
 
@@ -86,7 +54,7 @@ From the monorepo root:
 nmr test    # Run root tests + recursive workspace tests
 nmr build   # Build all packages
 nmr ci      # Build, then run the strict checks
-nmr prepush # Run everything the remote runs, before you push
+nmr prepush # Run everything the remote runs, before a push
 ```
 
 Target packages from anywhere:
@@ -96,19 +64,19 @@ nmr --filter core test # Test only the package whose manifest name is `core`
 nmr --recursive lint   # Lint all workspace packages
 ```
 
-`--recursive`, and a `--filter` that selects more than one package, give each package no terminal input. An interactive command such as `test:watch` needs a filter that selects a single package.
+`--recursive`, and a `--filter` that selects more than one package, do not give any package terminal input. An interactive command such as `test:watch` needs a filter that selects a single package.
 
-Position determines ownership: flags before the command name are nmr's own, and everything after the command name is forwarded untouched to the resolved command.
+Position determines ownership: Flags before the command name are nmr's own, and everything after the command name is forwarded untouched to the resolved command.
 
-`nmr --help` lists every flag and command, with the shell command each command resolves to. Per-package `package.json` files need no script entries.
+`nmr --help` lists every flag and command, with the shell command to which each command resolves. Per-package `package.json` files do not need any script entries.
 
-nmr detects where you are and selects the right scripts automatically — see [context-aware resolution](#context-aware-resolution) below.
+nmr detects the directory from which it is invoked and selects the right scripts automatically. See [context-aware resolution](#context-aware-resolution) below.
 
 ## Context-aware resolution
 
-nmr's key feature is that the same command runs different scripts depending on where you invoke it. It walks up from your current directory to find `pnpm-workspace.yaml`, then checks whether your CWD is inside a workspace package directory.
+nmr's key feature is that the same command runs different scripts depending on where it is invoked. It walks up from the current directory to find `pnpm-workspace.yaml`, then checks whether the current directory is inside a workspace package directory.
 
-| Where you run `nmr`               | Registry used     | Working directory | `nmr test` runs                                                      |
+| Where `nmr` is invoked            | Registry used     | Working directory | `nmr test` runs                                                      |
 | --------------------------------- | ----------------- | ----------------- | -------------------------------------------------------------------- |
 | Monorepo root                     | Root scripts      | Monorepo root     | `root:test`, then `-R test`                                          |
 | Inside a workspace package        | Workspace scripts | The package root  | `pnpm exec vitest --project unit --project tool` (that package only) |
@@ -126,21 +94,21 @@ nmr --workspace-root check
 Two consequences:
 
 - `nmr --workspace-root clean` sweeps every workspace package, as `nmr clean` does from the root.
-- Passthrough paths resolve against the working directory: from `packages/nmr/src/`, `nmr --workspace-root fmt pnpm-workspace.yaml` formats the file at the monorepo root.
+- Passthrough paths resolve against the working directory: From `packages/nmr/src/`, `nmr --workspace-root fmt pnpm-workspace.yaml` formats the file at the monorepo root.
 
 ## Three-tier override system
 
 Scripts resolve through three tiers. Higher tiers override lower ones:
 
-1. **Built-in defaults** — scripts shipped with this package
-2. **Repo-wide config** — additions and overrides in `.config/nmr.config.ts`
-3. **Per-package overrides** — scripts in a package's `package.json`
+1. **Built-in defaults**: Scripts included in this package
+2. **Repo-wide config**: Additions and overrides in `.config/nmr.config.ts`
+3. **Per-package overrides**: Scripts in a package's `package.json`
 
 [Scripts and configuration](docs/scripts.md#three-tier-override-system) shows a worked example, how to skip a script for one package, and what nmr does with a `package.json` entry that re-invokes its own command.
 
 ## Pre and post hooks
 
-Every `nmr X` invocation auto-wraps as the equivalent of `nmr X:pre && nmr X && nmr X:post`. Hooks are first-class scripts that resolve through the same three tiers as any other script (built-in defaults, then `.config/nmr.config.ts`, then per-package `package.json`). Wrapping is uniform: nested invocations from composite expansion get their own hook treatment. A failing hook ends the sequence, and its exit code propagates.
+Every `nmr X` invocation auto-wraps as the equivalent of `nmr X:pre && nmr X && nmr X:post`. Hooks are first-class scripts that resolve through the same three tiers as any other script (built-in defaults, then `.config/nmr.config.ts`, then per-package `package.json`). Wrapping is uniform: Nested invocations from composite expansion get their own hook treatment. A failing hook ends the sequence, and its exit code propagates.
 
 Extend `nmr build` with a pre-build step for every workspace package:
 
@@ -159,7 +127,7 @@ export default defineConfig({
 
 ## Configuration
 
-Create `.config/nmr.config.ts` in the monorepo root to add or override scripts. A package may carry one too, for [build settings of its own](docs/scripts.md#package-level-configuration):
+Create `.config/nmr.config.ts` in the monorepo root to add or override scripts. A package may have one too, for [build settings of its own](docs/scripts.md#package-level-configuration):
 
 ```ts
 import { defineConfig } from '@williamthorsen/nmr/config';
@@ -178,7 +146,7 @@ export default defineConfig({
 
 ## What nmr reports
 
-Every command nmr runs reports one line naming the scope it ran at, the command, the outcome, and the timing:
+Every command that nmr runs reports one line naming the scope at which it ran, the command, the outcome, and the timing:
 
 ```console
 ✅ nmr-core: test: passed in 12.4s
@@ -189,9 +157,9 @@ Every command nmr runs reports one line naming the scope it ran at, the command,
 
 **A pipe and a CI log get words rather than emoji.** The same four lines read `PASS`, `FAIL`, `SKIP`, and `NOOP` there, which `grep FAIL` finds. `--output-style` and `NMR_OUTPUT_STYLE` each force either style.
 
-**Verdicts print in every verbosity.** `-q` withholds the output of the commands nmr runs, never nmr's own words: a passing quiet run reports its verdicts and nothing else. A command that ran nothing reports the skip rather than exiting 0 in silence, which is what separates it from a command that passed: an override resolving to `""` or `":"`, and a fan-out step that a package-free workspace left nothing to do. An `NMR_RUN_IF_PRESENT` miss reports nothing, having no command to report on.
+**Verdicts print in every verbosity.** `nmr -q <command>` withholds the output of the commands that nmr runs, never nmr's own words: A passing quiet run reports its verdicts and nothing else. A command that ran nothing reports the skip rather than exiting 0 in silence, which separates it from a command that passed: an override resolving to `""` or `":"`, and a fan-out step that a package-free workspace left nothing to do. An `NMR_RUN_IF_PRESENT` miss reports nothing, because it does not have a command to report on.
 
-[What nmr reports](docs/reporting.md) covers how verdicts nest, the `--json` format, the output style, and where the verbosity of a run comes from.
+[What nmr reports](docs/reporting.md) covers how verdicts nest, the `--json` format, the output style, and what sets the verbosity of a run.
 
 ## Check-result cache
 
@@ -220,7 +188,7 @@ import { defineVitestConfig } from '@williamthorsen/nmr/vitest';
 export default defineVitestConfig();
 ```
 
-`@williamthorsen/nmr/tests` exports a check that fails a test run on a test file outside `__tests__` or one that names no tier. [Shared Vitest config](docs/vitest.md) covers the test tiers, that check, what the factory supplies, and customizing it by scope.
+`@williamthorsen/nmr/tests` exports a check that fails a test run on a test file outside `__tests__` or one that does not name a tier. [Shared Vitest config](docs/vitest.md) covers the test tiers, that check, what the factory supplies, and customizing it by scope.
 
 ### Shared Prettier config
 
@@ -241,7 +209,7 @@ export default definePrettierConfig();
 
 ### Workspace introspection
 
-Repo-wide tests and scripts often need to know where the monorepo root is, or which directories its workspace packages live in. The `@williamthorsen/nmr/workspace` subpath publishes the two pnpm-workspace lookups nmr uses internally:
+Repo-wide tests and scripts often need to know where the monorepo root is, or which directories its workspace packages live in. The `@williamthorsen/nmr/workspace` subpath publishes the two pnpm-workspace lookups that nmr uses internally:
 
 ```ts
 // __tests__/packages.test.ts
@@ -254,11 +222,11 @@ for (const packageDir of getWorkspacePackageDirs(monorepoRoot)) {
 }
 ```
 
-[Workspace introspection](docs/workspace.md) covers what each lookup returns and where it diverges from pnpm.
+[Workspace introspection](docs/workspace.md) covers what each lookup returns and the cases in which it diverges from pnpm.
 
 ## Agent guidance
 
-nmr ships the rules an agent needs in order to invoke it, as [CodeAssembly](https://github.com/williamthorsen/codeassembly) package content. Adopt it by naming the package in the consuming repo's `.agents/codeassembly.yaml`:
+nmr includes the rules that an agent needs in order to invoke it, as [CodeAssembly](https://github.com/williamthorsen/codeassembly) package content. Adopt it by naming the package in the consuming repo's `.agents/codeassembly.yaml`:
 
 ```yaml
 packages:
@@ -266,7 +234,7 @@ packages:
     - '@williamthorsen/nmr'
 ```
 
-Then add `codeassembly` as a devDependency and run `codeassembly sync`. The guidance is injected into the machine-local guidance file each harness loads at launch; nothing is copied into the repo or committed there. It resolves from the installed package, so upgrading nmr updates it with no second step.
+Then add `codeassembly` as a devDependency and run `codeassembly sync`. The guidance is injected into the machine-local guidance file that each harness loads at launch; nothing is copied into the repo or committed there. It resolves from the installed package, so upgrading nmr updates it without a second step.
 
 Wiring the sync to `postinstall` keeps it current without a hand-run command:
 
@@ -282,7 +250,7 @@ Wiring the sync to `postinstall` keeps it current without a hand-run command:
 
 ## Conformance checks
 
-nmr publishes a `readyup` kit that checks a consuming repo against the current release: the shared Vitest and Prettier configs, the workspace layout, the root script registry, the test-file conventions ([tier names](docs/vitest.md#test-tiers) and `__tests__` placement), that the repo's own suite gates them, that every `bin` target is a committed wrapper rather than build output that pnpm cannot link at install time, that `files` covers the output each wrapper loads, that no root install script runs `lefthook install` without `lefthook check-install`, and that no `package.json` in the tree declares a `pnpm` field, which pnpm 11 reads no key from. Those settings belong in `pnpm-workspace.yaml`, and `pnpx codemod run pnpm-v10-to-v11` moves them. The kit ships inside the package, so it checks against the nmr version installed rather than whatever a repository ref happens to point at, and a tier added or renamed in nmr reaches the repo on upgrade. A repo that declares the [conventions check](docs/vitest.md#gating-the-test-file-conventions) gates both conventions in its own test run, and the kit then leaves the test files to that check.
+nmr publishes a `readyup` kit that checks a consuming repo against the current release: the shared Vitest and Prettier configs, the workspace layout, the root script registry, the test-file conventions ([tier names](docs/vitest.md#test-tiers) and `__tests__` placement), that the repo's own suite gates them, that every `bin` target is a committed wrapper rather than build output that pnpm cannot link at install time, that `files` covers the output that each wrapper loads, that the root install scripts do not run `lefthook install` without `lefthook check-install`, and that the `package.json` files in the tree do not declare a `pnpm` field, from which pnpm 11 does not read any key. Those settings belong in `pnpm-workspace.yaml`, and `pnpx codemod run pnpm-v10-to-v11` moves them. The kit is included in the package, so it checks against the nmr version installed rather than whatever a repository ref happens to point at, and a tier added or renamed in nmr takes effect in the repo when it upgrades nmr. A repo that declares the [conventions check](docs/vitest.md#gating-the-test-file-conventions) gates both conventions in its own test run, and the kit then leaves the test files to that check.
 
 Add `readyup` as a devDependency, then name nmr in its config:
 
@@ -296,20 +264,20 @@ export default defineRdyConfig({
 ```
 
 ```bash
-rdy run --packages                       # every kit each listed package publishes
+rdy run --packages                       # every kit that each listed package publishes
 rdy run --from npm:@williamthorsen/nmr   # nmr's kit alone, without the config entry
 rdy list --from npm:@williamthorsen/nmr  # what nmr publishes
 ```
 
-`--packages` is the form that survives nmr publishing further kits. Both need `readyup` 0.23 or later, and `@williamthorsen/nmr` as a _direct_ devDependency: a strict pnpm layout links nothing else into the project, so a transitive copy is unreachable.
+`--packages` is the form that survives nmr publishing further kits. Both need `readyup` 0.23 or later, and `@williamthorsen/nmr` as a _direct_ devDependency: A strict pnpm layout links nothing else into the project, so a transitive copy is unreachable.
 
 ## Documentation
 
-- [Scripts and configuration](docs/scripts.md): override tiers, script values, hooks, `defineConfig` fields, `devBin`, and the default commands
-- [What nmr reports](docs/reporting.md): verdicts, `--json`, output style, and verbosity
-- [Check-result cache](docs/check-cache.md): what is skipped, what a hit requires, and replaying, reading, and bypassing recorded runs
+- [Scripts and configuration](docs/scripts.md): Override tiers, script values, hooks, `defineConfig` fields, `devBin`, and the default commands
+- [What nmr reports](docs/reporting.md): Verdicts, `--json`, output style, and verbosity
+- [Check-result cache](docs/check-cache.md): What is skipped, what a hit requires, and replaying, reading, and bypassing recorded runs
 - [Dependency upgrades](docs/upgrades.md): `nmr upgrade`, the upgrade policy, `report-catalog`, `report-overrides`, and `nmr-taze`
 - [Standalone utilities](docs/utilities.md): `nmr-clean`, `nmr-compile`, `nmr-fmt`, and `ensure-prepublish-hooks`
-- [Shared Vitest config](docs/vitest.md): test tiers, test selections, the conventions check, and customization
-- [Shared Prettier config](docs/prettier.md): what it formats and how to customize it
-- [Workspace introspection](docs/workspace.md): the two workspace lookups
+- [Shared Vitest config](docs/vitest.md): Test tiers, test selections, the conventions check, and customization
+- [Shared Prettier config](docs/prettier.md): What it formats and how to customize it
+- [Workspace introspection](docs/workspace.md): The two workspace lookups

package/agents/README.md

@@ -4,21 +4,21 @@ This directory is a CodeAssembly content root, declared by the `codeassembly.con
 
 ## The ambient cheatsheet
 
-`guidance/rulebooks/nmr.md` carries `delivery: ambient`, so its body is injected at launch in every consuming repo. Every line is paid for on every task, whether or not it is relevant. It is a cheatsheet, not a manual.
+`guidance/rulebooks/nmr.md` declares `delivery: ambient`, so its body is injected at launch in every consuming repo. Every line consumes launch tokens on every task, whether or not it is relevant. It is a cheatsheet, not a manual.
 
-A line earns a place in it only if both hold:
+A line belongs in it only if both hold:
 
-1. **It is absent from nmr's own output.** Bare `nmr` already prints the flags, every command, and the shell command each resolves to; failing checks already name their own fix. Repeating any of that costs launch tokens to say something the agent will be told anyway, at the moment it matters.
-2. **The obvious action goes wrong without it.** Guidance that prevents a silent mistake earns its place; guidance that prevents a mistake the next error message would diagnose does not.
+1. **It is absent from nmr's own output.** Bare `nmr` already prints the flags, every command, and the shell command to which each resolves; failing checks already name their own fix. Repeating any of that spends launch tokens to say something the agent will be told anyway, at the moment it matters.
+2. **The obvious action goes wrong without it.** Guidance that prevents a silent mistake belongs in it; guidance that prevents a mistake that the next error message would diagnose does not.
 
-Everything else belongs in the topic document under `packages/nmr/docs/` that covers it, reachable on demand at `node_modules/@williamthorsen/nmr/docs/`, with a pointer from the cheatsheet naming the topic and its document so an agent knows where to look. When adding a feature, document it there and extend that pointer rather than the cheatsheet.
+Everything else belongs in the topic document under `packages/nmr/docs/` that covers it, reachable on demand at `node_modules/@williamthorsen/nmr/docs/`, with a pointer from the cheatsheet naming the topic and its document so that an agent knows where to look. When adding a feature, document it there and extend that pointer rather than the cheatsheet.
 
 ## Constraints on rulebook bodies
 
-Rulebook bodies carry no links to other rulebooks. CodeAssembly's renderer rewrites link targets under `skills/` and `scripts/` and rejects everything else, so a cross-reference names the deployed `consult-<slug>` in prose and declares the edge under `dependencies:`.
+Rulebook bodies do not contain any links to other rulebooks. CodeAssembly's renderer rewrites link targets under `skills/` and `scripts/` and rejects everything else, so a cross-reference names the deployed `consult-<slug>` in prose and declares the edge under `dependencies:`.
 
-Anchor-only links are checked against the body they appear in, so a fragment naming a heading that lives in another document fails the run. Check `](#` before moving a section between bodies.
+Because anchor-only links are checked against the body in which they appear, a fragment naming a heading in another document fails the run. Check `](#` before moving a section between bodies.
 
 ## Publishing
 
-The directory is published because `files` in `packages/nmr/package.json` lists it. Dropping that entry fails nothing locally, because this repo resolves the guidance through a `workspace:*` self-link that `files` does not govern. `packaging.tool.test.ts` is what catches it.
+The directory is published because `files` in `packages/nmr/package.json` lists it. Dropping that entry fails nothing locally, because this repo resolves the guidance through a `workspace:*` self-link that `files` does not govern. `packaging.tool.test.ts` catches it.

package/agents/guidance/rulebooks/nmr.md

@@ -6,12 +6,12 @@ delivery: ambient
 
 # nmr: agent guidance
 
-- Use `nmr <command>`, not `pnpm run <command>`, for anything nmr provides. Run bare `nmr` to list every command and the shell command it resolves to; a wrong guess reports only `Unknown command`, with no list.
-- Scope follows cwd, and bare `nmr` lists both registries: from the repo root a command covers root files and every workspace; from inside a package, that package alone. `nmr -F <pkg> <command>` targets one package from anywhere; `nmr root:<command>` targets root files alone, which isolates a failure to root code.
-- Never `npx nmr`: inside a git worktree it can resolve a different nmr from outside the tree. Fall back to `pnpm exec nmr`.
+- Use `nmr <command>`, not `pnpm run <command>`, for anything nmr provides. Run bare `nmr` to list every command and the shell command to which it resolves; a wrong guess reports only `Unknown command`, without a list.
+- Scope follows cwd, and bare `nmr` lists both registries: From the repo root a command covers root files and every workspace; from inside a package, that package alone. `nmr -F <pkg> <command>` targets one package from anywhere; `nmr root:<command>` targets root files alone, which isolates a failure to root code.
+- Never `npx nmr`: Inside a git worktree it can resolve a different nmr from outside the tree. Fall back to `pnpm exec nmr`.
 - `nmr ci` runs what a code-quality workflow runs (build, then strict checks) and not the dependency audit, which belongs to a workflow of its own; `nmr prepush` runs the audit first, then `ci`, so a vulnerability stops the run before the long gate. Neither installs or binds a git hook.
-- A check that already passed on the current working tree skips, printing `SKIP <scope>: <command>: passed …` and, where the recalled run left one, `— replayed: <excerpt>` of what that run concluded. Any edit, addition, or deletion re-runs it, so read the replayed excerpt rather than paying for the answer again: never pass `--no-cache` to get a "real" run, which costs the command's full runtime to reach the same answer. Its one use is a file rather than an exit status -- a skipped command writes none, so a fresh `coverage/` needs `nmr --no-cache test:coverage`. A composite replays its constituents' excerpts, each attributed as `<scope>: <command>: <excerpt>` and cut at the line's ceiling where there are too many to fit. A skip carrying no excerpt is one whose run wrote to a terminal, or one whose constituents recorded none.
-- `nmr --log <command>` prints the whole run behind that excerpt -- up to 256 KiB, led by when it was recorded, how long it ran, and the command string that produced it -- so output you need in full is a recording to read rather than a run to pay for again. It runs nothing, and it is held to the tree rather than to the terminal: a recording a piped run made prints for a reader at one. A composite prints its constituents' excerpts, so the transcript of one of them is `nmr -F <pkg> --log <command>` or that constituent's own name. Nothing to show is said on one line and exits non-zero, naming which it is.
-- Every command nmr runs reports one line -- `PASS <scope>: <command>: passed in 12.4s`, `FAIL … failed in 1.2s (exit 1)`, `SKIP … passed 4m ago on this tree`, or `NOOP … skipped, the override is empty` -- and a composite reports alongside every command it expands into. Those are the words a pipe and a CI log get; a terminal gets ✅, ❌, ⏩, and ⚪ in their place, and `--output-style rich` or `NMR_OUTPUT_STYLE=rich` forces the emoji on any stream. The lines print in every verbosity, so `-q` is the low-noise way to run rather than a silent one: it withholds the output of the commands nmr runs and keeps nmr's own verdicts, which is how a pass, a cached skip, and a `""`/`":"` override stay distinguishable. Expect a run to be quiet already without the flag: nmr recognizes a known agent harness in the environment and takes quiet from that, as it does from `NMR_COMMAND_VERBOSITY` or the repo's `output.commandVerbosity`. A command whose output you need in full is one to run with `NMR_COMMAND_VERBOSITY=full`, which outranks both.
-- Every test file lives under a `__tests__` directory and names its isolation tier last: `<subject>[.<aspect>].<tier>.test.ts`, where any earlier segment is free-form documentation. A tier is the furthest thing the test reaches -- `tool` (a program the environment supplies), `localhost` (a service on this machine), `remote` (a machine that isn't this one), or `unit`, the residual claiming everything else. A file outside `__tests__`, or one whose tier segment is missing or misspelt, fails the test run in a repo that declares nmr's exported conventions check, which reports both. In a repo that has not, neither fails anything -- the first is collected by nothing and the second runs under `unit` -- and `rdy run --packages` reports both and warns that the check is missing.
-- The rest is in `node_modules/@williamthorsen/nmr/docs/`: `scripts.md` for pre/post hooks (every `nmr X` auto-wraps as `nmr X:pre && nmr X && nmr X:post`) and script overrides and their `""`/`":"` skip values; `upgrades.md` for `nmr upgrade` ceilings (report-only until `nmr upgrade --write`); `utilities.md` for the `nmr-compile` build (there is no repo-local build script); `vitest.md` for the test tiers' timeout budgets, the `tiers` seam that raises one, and which script reaches which tier; and `check-cache.md` for the check-result cache's key, the retention key a replayed excerpt is additionally held to, the retention ceiling `--log` prints within, its `checkCache` config, and every condition that disables it.
+- A check that already passed on the current working tree skips, printing `SKIP <scope>: <command>: passed …` and, when the recalled run left one, `— replayed: <excerpt>` of what that run concluded. Any edit, addition, or deletion re-runs it. Read the replayed excerpt rather than running the check again: Never pass `--no-cache` to get a "real" run, which takes the command's full runtime to reach the same answer. Its one use is a file rather than an exit status -- a skipped command writes none, so a fresh `coverage/` needs `nmr --no-cache test:coverage`. A composite replays its constituents' excerpts, each attributed as `<scope>: <command>: <excerpt>` and cut at the line's ceiling when there are too many to fit. A skip without an excerpt is one whose run wrote to a terminal, or one whose constituents recorded none.
+- `nmr --log <command>` prints the whole run behind that excerpt -- up to 256 KiB, led by when it was recorded, how long it ran, and the command string that produced it. Output that you need in full is a recording to read rather than a command to run again. It runs nothing, and it is held to the tree rather than to the terminal: A recording made by a piped run prints for a reader at one. A composite prints its constituents' excerpts, not their transcripts, so the transcript of one of them is `nmr -F <pkg> --log <command>` or that constituent's own name. When there is nothing to show, `--log` says so on one line, names which case it is, and exits non-zero.
+- Every command that nmr runs reports one line -- `PASS <scope>: <command>: passed in 12.4s`, `FAIL … failed in 1.2s (exit 1)`, `SKIP … passed 4m ago on this tree`, or `NOOP … skipped, the override is empty` -- and a composite reports alongside every command into which it expands. Those are the words that a pipe and a CI log get; a terminal gets ✅, ❌, ⏩, and ⚪ in their place, and `--output-style rich` or `NMR_OUTPUT_STYLE=rich` forces the emoji on any stream. The lines print in every verbosity, so `nmr -q <command>` is the low-noise way to run rather than a silent one: It withholds the output of the commands that nmr runs and keeps nmr's own verdicts, which is how a pass, a cached skip, and a `""`/`":"` override stay distinguishable. nmr reads its own flags only before the command name and passes everything after the name to the commands that run: `nmr ci -q` hands `-q` to `nmr-fmt`, which rejects it. Expect a run to be quiet already without the flag: nmr recognizes a known agent harness in the environment and takes quiet from that, as it does from `NMR_COMMAND_VERBOSITY` or the repo's `output.commandVerbosity`. A command whose output you need in full is one to run with `NMR_COMMAND_VERBOSITY=full`, which outranks both.
+- Every test file lives under a `__tests__` directory and names its isolation tier last: `<subject>[.<aspect>].<tier>.test.ts`, where any earlier segment is free-form documentation. A tier is the furthest thing that the test reaches -- `tool` (a program supplied by the environment), `localhost` (a service on this machine), `remote` (a machine that isn't this one), or `unit`, the residual claiming everything else. A file outside `__tests__`, or one whose tier segment is missing or misspelt, fails the test run in a repo that declares nmr's exported conventions check, which reports both. In a repo that has not, neither fails anything -- the first is collected by nothing and the second runs under `unit` -- and `rdy run --packages` reports both and warns that the check is missing.
+- The rest is in `node_modules/@williamthorsen/nmr/docs/`: `scripts.md` for pre/post hooks (every `nmr X` auto-wraps as `nmr X:pre && nmr X && nmr X:post`) and script overrides and their `""`/`":"` skip values; `upgrades.md` for `nmr upgrade` ceilings (report-only until `nmr upgrade --write`); `utilities.md` for the `nmr-compile` build (the repo does not define a build script of its own); `vitest.md` for the test tiers' timeout budgets, the `tiers` seam that raises one, and which script reaches which tier; and `check-cache.md` for the check-result cache's key, the retention key to which a replayed excerpt is additionally held, the retention ceiling within which `--log` prints, its `checkCache` config, and every condition that disables it.

package/bin/ensure-prepublish-hooks.js

@@ -3,7 +3,7 @@ try {
   await import('../dist/esm/cli-ensure-prepublish-hooks.js');
 } catch (error) {
   if (error.code === 'ERR_MODULE_NOT_FOUND') {
-    process.stderr.write('ensure-prepublish-hooks: build output not found — run `pnpm run bootstrap` first\n');
+    process.stderr.write('ensure-prepublish-hooks: build output not found; run `pnpm run bootstrap` first\n');
   } else {
     process.stderr.write(`ensure-prepublish-hooks: failed to load: ${error.message}\n`);
   }

package/bin/nmr-clean.js

@@ -3,7 +3,7 @@ try {
   await import('../dist/esm/cli-clean.js');
 } catch (error) {
   if (error.code === 'ERR_MODULE_NOT_FOUND') {
-    process.stderr.write('nmr-clean: build output not found — run `pnpm run bootstrap` first\n');
+    process.stderr.write('nmr-clean: build output not found; run `pnpm run bootstrap` first\n');
   } else {
     process.stderr.write(`nmr-clean: failed to load: ${error.message}\n`);
   }

package/bin/nmr-compile.js

@@ -3,7 +3,7 @@ try {
   await import('../dist/esm/cli-build.js');
 } catch (error) {
   if (error.code === 'ERR_MODULE_NOT_FOUND') {
-    process.stderr.write('nmr-compile: build output not found — run `pnpm run bootstrap` first\n');
+    process.stderr.write('nmr-compile: build output not found; run `pnpm run bootstrap` first\n');
   } else {
     process.stderr.write(`nmr-compile: failed to load: ${error.message}\n`);
   }

package/bin/nmr-fmt.js

@@ -3,7 +3,7 @@ try {
   await import('../dist/esm/cli-fmt.js');
 } catch (error) {
   if (error.code === 'ERR_MODULE_NOT_FOUND') {
-    process.stderr.write('nmr-fmt: build output not found — run `pnpm run bootstrap` first\n');
+    process.stderr.write('nmr-fmt: build output not found; run `pnpm run bootstrap` first\n');
   } else {
     process.stderr.write(`nmr-fmt: failed to load: ${error.message}\n`);
   }

package/bin/nmr-report-catalog.js

@@ -3,7 +3,7 @@ try {
   await import('../dist/esm/cli-report-catalog.js');
 } catch (error) {
   if (error.code === 'ERR_MODULE_NOT_FOUND') {
-    process.stderr.write('nmr-report-catalog: build output not found — run `pnpm run bootstrap` first\n');
+    process.stderr.write('nmr-report-catalog: build output not found; run `pnpm run bootstrap` first\n');
   } else {
     process.stderr.write(`nmr-report-catalog: failed to load: ${error.message}\n`);
   }

package/bin/nmr-report-overrides.js

@@ -3,7 +3,7 @@ try {
   await import('../dist/esm/cli-report-overrides.js');
 } catch (error) {
   if (error.code === 'ERR_MODULE_NOT_FOUND') {
-    process.stderr.write('nmr-report-overrides: build output not found — run `pnpm run bootstrap` first\n');
+    process.stderr.write('nmr-report-overrides: build output not found; run `pnpm run bootstrap` first\n');
   } else {
     process.stderr.write(`nmr-report-overrides: failed to load: ${error.message}\n`);
   }

package/bin/nmr-taze.js

@@ -3,7 +3,7 @@ try {
   await import('../dist/esm/cli-taze.js');
 } catch (error) {
   if (error.code === 'ERR_MODULE_NOT_FOUND') {
-    process.stderr.write('nmr-taze: build output not found — run `pnpm run bootstrap` first\n');
+    process.stderr.write('nmr-taze: build output not found; run `pnpm run bootstrap` first\n');
   } else {
     process.stderr.write(`nmr-taze: failed to load: ${error.message}\n`);
   }

package/bin/nmr.js

@@ -3,7 +3,7 @@ try {
   await import('../dist/esm/cli.js');
 } catch (error) {
   if (error.code === 'ERR_MODULE_NOT_FOUND') {
-    process.stderr.write('nmr: build output not found — run `pnpm run bootstrap` first\n');
+    process.stderr.write('nmr: build output not found; run `pnpm run bootstrap` first\n');
   } else {
     process.stderr.write(`nmr: failed to load: ${error.message}\n`);
   }

package/dist/esm/UserError.d.ts

@@ -1,8 +1,7 @@
 /**
  * A failure in what the user declared -- a config file, a `package.json` -- rather than a fault in nmr.
  *
- * The CLI boundary prints one of these as its message alone. A stack trace records where nmr noticed the
- * problem, which says nothing about the file the reader has to edit.
+ * The CLI boundary prints one of these as its message alone.
  */
 export declare class UserError extends Error {
     constructor(message: string);