@williamthorsen/nmr 0.23.0 → 0.25.0

package/README.md

@@ -3,19 +3,20 @@
 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.
 
 <!-- section:release-notes -->
-## Release notes — v0.23.0 (2026-08-01)
+## Release notes — v0.25.0 (2026-08-03)
 
 ### 🎉 Features
 
-- 🚨 **Breaking:** Close the shared Vitest config's path gaps (#546)
+- Mark a cache hit's time saving with a speed-boost icon (#579)
 
-  Defines common patterns to determine which files are considered test files and which are subject to code coverage. Consumers that use `defineVitestConfig` benefit from these patterns if they follow naming and file-location conventions.
+  Time saved due to `nmr`'s cache feature now earns a rocket emoji in the terminal output.
+  Savings less than 1 second are no longer reported.
 
-### 🐛 Bug fixes
+- Publish nmr's readyup kit with a test-tier conformance check (#580)
 
-- Stop rewriting documented commands inside Markdown fences (#549)
+  `@williamthorsen/nmr` is now bundled with ReadyUp kits that check a repo's alignment with `nmr` requirements and recommendations.
 
-  Fixes an issue where `nmr fmt` silently rewrote shell commands documented in a repository's Markdown, leaving usage examples that no longer ran as written. Code fences inside Markdown are now left untouched in any language, withdrawing the fence formatting added in 0.22.0. Fence formatting can be reenabled on selected paths via the config.
+  `rdy run --from npm:@williamthorsen/nmr` checks the repo against the kits without prior configuration. Once the package is added to the ReadyUp config, `rdy run --packages` will run the `nmr` kits along with those of any other registered package. Requires `readyup` v0.23 or greater.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -50,9 +51,9 @@ nmr check # Typecheck, format check, lint check, and tests
 From the monorepo root:
 
 ```bash
-nmr test  # Run root tests + recursive workspace tests
-nmr build # Build all packages
-nmr ci    # Run build && check:strict && audit (full CI pipeline)
+nmr test    # Run root tests + recursive workspace tests
+nmr build   # Build all packages
+nmr prepush # Run everything the remote runs, before you push
 ```
 
 nmr detects where you are and selects the right scripts automatically — see [context-aware resolution](#context-aware-resolution) below.
@@ -61,11 +62,11 @@ nmr detects where you are and selects the right scripts automatically — see [c
 
 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.
 
-| Where you run `nmr`               | Registry used     | Working directory | `nmr test` runs                                                 |
-| --------------------------------- | ----------------- | ----------------- | --------------------------------------------------------------- |
-| Monorepo root                     | Root scripts      | Monorepo root     | Root tests + `pnpm --recursive exec nmr test`                   |
-| Inside a workspace package        | Workspace scripts | The package root  | `pnpm exec vitest --project '!integration'` (that package only) |
-| Anywhere, with `--workspace-root` | Root scripts      | Monorepo root     | Root tests + `pnpm --recursive exec nmr test`                   |
+| Where you run `nmr`               | Registry used     | Working directory | `nmr test` runs                                                      |
+| --------------------------------- | ----------------- | ----------------- | -------------------------------------------------------------------- |
+| Monorepo root                     | Root scripts      | Monorepo root     | Root tests + `pnpm --recursive exec nmr test`                        |
+| Inside a workspace package        | Workspace scripts | The package root  | `pnpm exec vitest --project unit --project tool` (that package only) |
+| Anywhere, with `--workspace-root` | Root scripts      | Monorepo root     | Root tests + `pnpm --recursive exec nmr test`                        |
 
 Relative paths in a script resolve against that working directory, not the invocation directory.
 
@@ -116,10 +117,10 @@ Passthrough arguments attach to the final step alone, because the expansion is a
 
 ## Configuration
 
-Create `.config/nmr.config.ts` in the monorepo root to add or override scripts:
+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](#package-level-configuration):
 
 ```ts
-import { defineConfig } from '@williamthorsen/nmr';
+import { defineConfig } from '@williamthorsen/nmr/config';
 
 export default defineConfig({
   workspaceScripts: {
@@ -133,14 +134,35 @@ export default defineConfig({
 
 ### `defineConfig` fields
 
-| Field              | Type                                 | Description                                                    |
-| ------------------ | ------------------------------------ | -------------------------------------------------------------- |
-| `workspaceScripts` | `Record<string, string \| string[]>` | Scripts added or overridden in the workspace registry (tier 2) |
-| `rootScripts`      | `Record<string, string \| string[]>` | Scripts added or overridden in the root registry (tier 2)      |
-| `devBin`           | `Record<string, string>`             | Map binary names to source-repo replacement commands           |
+| Field              | Type                                                                          | Description                                                           |
+| ------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `build`            | `{ extraIgnorePatterns?: string[] }`                                          | Patterns added to the build's ignore set (package config only)        |
+| `checkCache`       | `{ enabled?: boolean; extraCommands?: string[]; excludeCommands?: string[] }` | Which commands the [check-result cache](#check-result-cache) may skip |
+| `workspaceScripts` | `Record<string, string \| string[]>`                                          | Scripts added or overridden in the workspace registry (tier 2)        |
+| `rootScripts`      | `Record<string, string \| string[]>`                                          | Scripts added or overridden in the root registry (tier 2)             |
+| `devBin`           | `Record<string, string>`                                                      | Map binary names to source-repo replacement commands                  |
 
 All fields are optional. `workspaceScripts` and `rootScripts` values follow the same `string | string[]` convention described in [script values](#script-values).
 
+Each field belongs to exactly one tier, and a config loads only the fields its own tier honors: `build` in a package config, the other four in the monorepo-root config. Declaring a field at the wrong tier fails with a message naming it and where it goes, as does a key nmr does not recognize at all — a typo cannot degrade into a setting that silently applies nowhere.
+
+### Package-level configuration
+
+A package may carry its own `.config/nmr.config.ts`, which `nmr-compile` reads from the package it is compiling. This tier honors `build` alone; declaring `workspaceScripts`, `rootScripts`, or `devBin` there fails with a message naming them, rather than being quietly ignored — those belong in the monorepo-root config, and a package that appeared to set them would otherwise build on settings nothing applied. The monorepo-root config carries the mirror restriction: `build` there fails the same way, since only a package's own config reaches the compile.
+
+```ts
+// packages/my-package/.config/nmr.config.ts
+import { defineConfig } from '@williamthorsen/nmr/config';
+
+export default defineConfig({
+  build: { extraIgnorePatterns: ['**/fixtures/**'] },
+});
+```
+
+`extraIgnorePatterns` adds to the build's [default ignore set](#nmr-compile) rather than replacing it, so declaring a pattern cannot start a package shipping its own tests. The programmatic `buildPackage` option of the same name behaves identically; its bare `ignorePatterns` is the one that replaces.
+
+> **Building nmr from source:** a config file that has to load while nmr itself is being built — before its `dist` exists — must use the type-only form, `import type { NmrConfig } from '@williamthorsen/nmr/config'` with `satisfies NmrConfig`, which carries no runtime import. `defineConfig` resolves through nmr's build output and so is unavailable at that moment. Every other config, including every consumer's, installs nmr from a tarball that ships `dist` and can use `defineConfig` freely.
+
 ### `devBin` — source-repo binary substitution
 
 When developing a CLI tool inside the monorepo, the published binary may not reflect your latest source changes. `devBin` lets you map a binary name to a replacement command that runs from source:
@@ -175,7 +197,7 @@ Extend `nmr build` with a pre-build step for every workspace package:
 
 ```ts
 // .config/nmr.config.ts
-import { defineConfig } from '@williamthorsen/nmr';
+import { defineConfig } from '@williamthorsen/nmr/config';
 
 export default defineConfig({
   workspaceScripts: {
@@ -197,6 +219,114 @@ Attach a post-build step to one package:
 
 The second example calls the bin directly, which sidesteps the workspace-versus-root registry distinction.
 
+## Check-result cache
+
+A check that passed on a working tree passes again on the same working tree. nmr records that, and the next run of the same command on an unchanged tree exits 0 without doing the work:
+
+```console
+$ nmr ci
+# ... four minutes of build, typecheck, lint, and coverage ...
+
+$ nmr ci
+⏭️ ci: passed 2m ago on this tree (🚀 saved ~4m). Re-run with --no-cache.
+```
+
+Composite commands expand into child `nmr` processes, so one green `nmr ci` records a pass for every cacheable command in the chain, at every scope it ran at. A later `nmr check`, `nmr typecheck`, or `nmr -F core test` on the same tree skips too. The skip line is suppressed by `-q`.
+
+The cache is a working-tree cache, not a build cache: it answers "has this exact tree already passed this check?" and nothing else. It is also local to one checkout (the install fingerprint in its key is machine-specific), so it saves repeated work in a working copy rather than sharing results across machines or with CI.
+
+### What is cached
+
+Cacheable by default: `check`, `check:agent-files`, `check:strict`, `ci`, `fix:check`, `fmt:check`, `lint:check`, `lint:strict`, `test`, `test:coverage`, `test:tool`, `test:unit`, `typecheck`, and the `root:` variants `root:check`, `root:lint:check`, `root:lint:strict`, `root:test`, `root:test:tool`, `root:test:unit`, and `root:typecheck`.
+
+Everything else runs every time:
+
+| Command                         | Why it is never skipped                                                                                                                   |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `audit`, `prepush`              | Consult a vulnerability database that moves without the tree. `prepush`'s `ci` constituent still skips while its `audit` runs every time. |
+| `build`, `compile`              | Carry a cache of their own.                                                                                                               |
+| `fix`, `fmt`, `lint`, `upgrade` | Rewrite the tree they were asked about, so a recorded pass would describe a tree that no longer exists.                                   |
+| `test:all`                      | Reaches the `localhost` and `remote` tiers, which the environment supplies rather than the tree.                                          |
+
+### The exit-status-only contract
+
+**A cacheable name promises that its whole contribution is an exit status**, through its entire chain, `:pre` and `:post` hooks included. A hit skips that chain wholesale, so any file a cacheable command was relied on to produce is a file that will not appear.
+
+`test:coverage` is cacheable on exactly this reading: what it contributes is the pass, not the `coverage/` directory, which a skipped run leaves as whatever the last real run wrote. Read `coverage/` after a `test:coverage` that may have skipped, and it may be stale; `--no-cache` is how you insist on a fresh one.
+
+Overriding a cacheable name, in `package.json` or in `workspaceScripts`, inherits its cacheability. An override that writes something anyone depends on belongs in `excludeCommands`.
+
+### What the key is made of
+
+A hit requires all of these to match the run that recorded the pass:
+
+- **The working tree's content**, hashed from the commit's tree object folded with the current content of every path git reports as changed or untracked. Timestamps are not content, so a `touch` that rewrites no bytes leaves the hash alone.
+- **The command string that would run**, hooks and all, and the scope it would run in.
+- **nmr's version**, the **Node version**, and the **platform and architecture**.
+- **What pnpm has installed**, so an install, a prune, or a lockfile change forces a re-run.
+- **`TZ`, `LANG`, `LC_ALL`, and `NODE_OPTIONS`.** This set is fixed, so two machines that differ only in shell decoration still agree.
+
+A hit additionally requires the build output of every package nmr's own build covers to be present, and to have been built from this tree. Output is git-ignored, so neither its removal nor its replacement moves the hash: restoring a tree with `git stash` or `git checkout` restores none of the output that tree was built with. nmr compares each covered package's recorded build digest against the one on disk, so a `dist` compiled from another tree is a miss the following run repairs. A package that overrides `build` or `compile` emits on terms nmr does not know and is exempt.
+
+A pass is recorded only when the command exits 0, only when the tree still matches the one the run started against, only when every covered package's output is present, and never for a run that executed nothing (a `""`/`":"` skip override, or an `NMR_RUN_IF_PRESENT` miss).
+
+### Out of contract
+
+These change what a check concludes without moving the hash. Where one applies, exclude the affected command:
+
+- **Content filters.** `core.autocrlf` and `.gitattributes` filters mean the bytes on disk differ from the bytes git records; the hash follows what is on disk, but a checkout on another platform may not reproduce it.
+- **Symlinked inputs.** A symlink is hashed by the path it names, not by the content at the far end.
+- **Gitignored inputs.** Anything git does not report is invisible to the hash. The build-output probe is the one exception, and covers only nmr's own build.
+- **`passWithNoTests`.** A suite that collects no files exits 0, and that green is recorded like any other.
+
+Committing an already-checked tree also moves the hash, because the commit's tree object is the base of the fold; the next run does the work again. The reverse holds and is useful: a rebase or an amended message that preserves content leaves the hash alone, as does checking out a branch whose tree is identical.
+
+### When the gate stands aside
+
+The gate never wrongly skips. Where it cannot be sure, it does nothing and the command runs:
+
+- Outside a git repository, when git fails, or when there is no commit at `HEAD`.
+- When the repository declares or contains submodules, whose content the hash does not cover.
+- When the monorepo root is not the git toplevel.
+- When a changed path cannot be read, or is neither a file nor a symlink (an untracked nested repository, for instance).
+- When there is no pnpm install to fingerprint.
+- Under a `devBin` substitution, which runs a binary built from somewhere the hash does not describe.
+- For any invocation carrying arguments after the command name.
+
+`NMR_DEBUG=1` reports why a run did not skip and why the gate stood aside.
+
+### Bypassing and clearing
+
+Reach for these in order; the first is almost always the right one.
+
+| Step                                   | Effect                                                                    |
+| -------------------------------------- | ------------------------------------------------------------------------- |
+| `nmr --no-cache <command>`             | Runs the command, then records the fresh result. Reaches the whole chain. |
+| `NMR_NO_CACHE=1`                       | The same, for every nmr invocation in the shell.                          |
+| `rm -rf node_modules/.cache/nmr-check` | Forgets every recorded pass, leaving build output alone.                  |
+| `nmr clean`                            | Forgets every recorded pass and removes build output, at any scope.       |
+
+`--no-cache` belongs before the command name. After it, it is an argument to the command rather than a flag to nmr; nmr says so rather than letting the bypass silently not happen.
+
+### Reserved environment variables
+
+`NMR_TREE_SNAPSHOT` is nmr's own: it carries one observation of the tree from a top-level invocation down to the processes it spawns, so a chain hashes the tree once rather than at every link. nmr trusts an inherited value only while `HEAD` still stands where it did when the observation was taken, which bounds a process that outlives the run that spawned it. That bound does not extend to a tree edited without committing, so **a process that survives its run and later invokes nmr should clear `NMR_TREE_SNAPSHOT`** — a test suite that shells out to `nmr` is the case worth checking.
+
+### Configuring
+
+```ts
+export default defineConfig({
+  checkCache: {
+    // Names promising exit-status-only semantics through their whole chain.
+    extraCommands: ['verify:contracts'],
+    // Names that turned out to do more than report an exit status.
+    excludeCommands: ['test:coverage'],
+  },
+});
+```
+
+`extraCommands` extends the default set rather than replacing it, so naming one command cannot silently drop the rest; `excludeCommands` is applied afterwards, so a name in both is excluded. `enabled: false` turns the gate off entirely. The key is `checkCache`, in the monorepo-root config.
+
 ## Dependency upgrades
 
 `nmr upgrade` reports the dependency upgrades available to your repo. What it covers depends on where you run it:
@@ -245,58 +375,65 @@ These scripts are available out of the box. Repo-wide config (tier 2) and per-pa
 
 ### Workspace scripts
 
-| Command            | Runs                                                     |
-| ------------------ | -------------------------------------------------------- |
-| `build`            | `compile`                                                |
-| `check`            | `typecheck`, `fmt:check`, `lint:check`, `test`           |
-| `check:strict`     | `typecheck`, `fmt:check`, `lint:strict`, `test:coverage` |
-| `clean`            | `nmr-clean`                                              |
-| `compile`          | `nmr-compile`                                            |
-| `fix`              | `lint`, `fmt`                                            |
-| `fix:check`        | `fmt:check`, `lint:check`                                |
-| `fmt`              | `nmr-fmt --write`                                        |
-| `fmt:check`        | `nmr-fmt --check`                                        |
-| `lint`             | `eslint --fix .`                                         |
-| `lint:check`       | `eslint .`                                               |
-| `lint:strict`      | `strict-lint`                                            |
-| `test`             | `pnpm exec vitest --project '!integration'`              |
-| `test:all`         | `pnpm exec vitest`                                       |
-| `test:coverage`    | `pnpm exec vitest --project '!integration' --coverage`   |
-| `test:integration` | `pnpm exec vitest --project integration`                 |
-| `test:watch`       | `pnpm exec vitest --project '!integration' --watch`      |
-| `typecheck`        | `tsgo --noEmit`                                          |
-| `upgrade`          | `nmr-taze --include-locked`                              |
-| `view-coverage`    | `open coverage/index.html`                               |
+| Command         | Runs                                                        |
+| --------------- | ----------------------------------------------------------- |
+| `build`         | `compile`                                                   |
+| `check`         | `typecheck`, `fmt:check`, `lint:check`, `test`              |
+| `check:strict`  | `typecheck`, `fmt:check`, `lint:strict`, `test:coverage`    |
+| `clean`         | `nmr-clean`                                                 |
+| `compile`       | `nmr-compile`                                               |
+| `fix`           | `lint`, `fmt`                                               |
+| `fix:check`     | `fmt:check`, `lint:check`                                   |
+| `fmt`           | `nmr-fmt --write`                                           |
+| `fmt:check`     | `nmr-fmt --check`                                           |
+| `lint`          | `eslint --fix .`                                            |
+| `lint:check`    | `eslint .`                                                  |
+| `lint:strict`   | `strict-lint`                                               |
+| `test`          | `pnpm exec vitest --project unit --project tool`            |
+| `test:all`      | `pnpm exec vitest`                                          |
+| `test:coverage` | `pnpm exec vitest --project unit --project tool --coverage` |
+| `test:tool`     | `pnpm exec vitest --project tool`                           |
+| `test:unit`     | `pnpm exec vitest --project unit`                           |
+| `test:watch`    | `pnpm exec vitest --project unit --project tool --watch`    |
+| `typecheck`     | `tsgo --noEmit`                                             |
+| `upgrade`       | `nmr-taze --include-locked`                                 |
+| `view-coverage` | `open coverage/index.html`                                  |
 
 `fmt` and `fmt:check` select their files through git rather than by walking the directory, which is what makes a package-level run and a root-level run apply the same ignore rules — see [file selection](#file-selection).
 
 #### Test selections
 
-Every package resolves the same five test commands. Nothing is detected on disk: the commands select [Vitest projects](#shared-vitest-config), so a package separates its integration tests by naming them `*.int.test.ts`, not by carrying extra config files.
+Every package resolves the same six test commands. Nothing is detected on disk: the commands select [Vitest projects](#shared-vitest-config), so a package separates its tool-tier tests by naming them `*.tool.test.ts`, not by carrying extra config files.
 
-| To run                              | Command            |
-| ----------------------------------- | ------------------ |
-| Everything except integration tests | `test`             |
-| Integration tests alone             | `test:integration` |
-| Every project                       | `test:all`         |
+| To run                                        | Command     |
+| --------------------------------------------- | ----------- |
+| Everything that runs on a bare install        | `test`      |
+| The fastest tier alone                        | `test:unit` |
+| Tests reaching a program alone                | `test:tool` |
+| Every tier, including those needing a service | `test:all`  |
 
-`test` negates `integration` rather than naming the code-only projects, so a category added later joins the default run instead of being dropped from it.
+`test` names the tiers it runs rather than negating the ones it skips, so a tier added in a later release is opt-in rather than joining the default run on arrival. It covers `unit` and `tool`, the two that need nothing beyond a checkout and an install; `localhost` and `remote` are reached only through `test:all` or an explicit `--project`.
 
-`test:coverage` and `test:watch` are the same selection as `test` in a different mode. There are no `test:integration --coverage` equivalents because none are needed: everything after a command name is forwarded untouched, so `nmr test:integration --coverage` already works.
+`test:coverage` and `test:watch` are the same selection as `test` in a different mode. There are no `test:tool --coverage` equivalents because none are needed: everything after a command name is forwarded untouched, so `nmr test:tool --coverage` already works.
 
-To narrow to a single project, go through `test:all`: `nmr test:all --project app`. Narrowing through `test` does not work, because a second `--project` widens the filter rather than restricting it.
+To narrow to a single project, go through `test:all`: `nmr test:all --project remote`. Narrowing through `test` does not work, because a second `--project` widens the selection rather than restricting it.
 
-A run that collects no test files passes. That is what lets `nmr test:integration` fan out across a monorepo in which most packages have no integration tests, and it means a package with no tests at all needs no `"test": ""` override.
+A run that collects no test files passes. That is what lets `nmr test:tool` fan out across a monorepo in which most packages hold no tool-tier tests, and it means a package with no tests at all needs no `"test": ""` override.
 
 ### Root scripts
 
 #### Build and CI
 
-| Command | Runs                              |
-| ------- | --------------------------------- |
-| `build` | `pnpm --recursive exec nmr build` |
-| `ci`    | `build`, `check:strict`, `audit`  |
-| `clean` | `nmr-clean`                       |
+| Command   | Runs                              |
+| --------- | --------------------------------- |
+| `build`   | `pnpm --recursive exec nmr build` |
+| `ci`      | `build`, `check:strict`           |
+| `clean`   | `nmr-clean`                       |
+| `prepush` | `ci`, `audit`                     |
+
+`ci` is what a code-quality workflow runs; it leaves out the audit, which belongs in a workflow of its own. `prepush` is what a developer runs before pushing: both gates. It composes `ci` rather than restating its stages, so a stage added to `ci` joins the pre-push run too.
+
+Neither is bound to a git hook. `prepush` is named for when you run it, not for a hook nmr installs.
 
 #### Check and quality
 
@@ -314,15 +451,16 @@ A run that collects no test files passes. That is what lets `nmr test:integratio
 
 #### Test
 
-The same five names the workspace registry carries, so a command means the same thing from the monorepo root as from inside a package. Each fans out to root-level files and every workspace package.
+The same six names the workspace registry carries, so a command means the same thing from the monorepo root as from inside a package. Each fans out to root-level files and every workspace package.
 
-| Command            | Runs                                                                      |
-| ------------------ | ------------------------------------------------------------------------- |
-| `test`             | `nmr root:test && pnpm --recursive exec nmr test`                         |
-| `test:all`         | `nmr root:test:all && pnpm --recursive exec nmr test:all`                 |
-| `test:coverage`    | `nmr root:test && pnpm --recursive exec nmr test:coverage`                |
-| `test:integration` | `nmr root:test:integration && pnpm --recursive exec nmr test:integration` |
-| `test:watch`       | `vitest --project '!integration' --watch`                                 |
+| Command         | Runs                                                        |
+| --------------- | ----------------------------------------------------------- |
+| `test`          | `nmr root:test && pnpm --recursive exec nmr test`           |
+| `test:all`      | `nmr root:test:all && pnpm --recursive exec nmr test:all`   |
+| `test:coverage` | `nmr root:test && pnpm --recursive exec nmr test:coverage`  |
+| `test:tool`     | `nmr root:test:tool && pnpm --recursive exec nmr test:tool` |
+| `test:unit`     | `nmr root:test:unit && pnpm --recursive exec nmr test:unit` |
+| `test:watch`    | `vitest --project unit --project tool --watch`              |
 
 `test:coverage` chains `root:test` rather than a `root:test:coverage`, because the root config reports no coverage of its own; packages cover their own sources.
 
@@ -375,17 +513,18 @@ See [dependency upgrades](#dependency-upgrades) for the workflow and its configu
 
 These scripts operate on root-level code only (not workspace packages):
 
-| Command                 | Runs                                                               |
-| ----------------------- | ------------------------------------------------------------------ |
-| `root:check`            | `root:typecheck`, `fmt:check`, `root:lint:check`, `root:test`      |
-| `root:lint`             | `eslint --fix --ignore-pattern 'packages/**' .`                    |
-| `root:lint:check`       | `eslint --ignore-pattern 'packages/**' .`                          |
-| `root:lint:strict`      | `strict-lint --ignore-pattern 'packages/**' .`                     |
-| `root:test`             | `vitest --config ./vitest.root.config.ts --project '!integration'` |
-| `root:test:all`         | `vitest --config ./vitest.root.config.ts`                          |
-| `root:test:integration` | `vitest --config ./vitest.root.config.ts --project integration`    |
-| `root:typecheck`        | `tsgo --noEmit`                                                    |
-| `root:upgrade`          | `nmr-taze --include-locked`                                        |
+| Command            | Runs                                                                    |
+| ------------------ | ----------------------------------------------------------------------- |
+| `root:check`       | `root:typecheck`, `fmt:check`, `root:lint:check`, `root:test`           |
+| `root:lint`        | `eslint --fix --ignore-pattern 'packages/**' .`                         |
+| `root:lint:check`  | `eslint --ignore-pattern 'packages/**' .`                               |
+| `root:lint:strict` | `strict-lint --ignore-pattern 'packages/**' .`                          |
+| `root:test`        | `vitest --config ./vitest.root.config.ts --project unit --project tool` |
+| `root:test:all`    | `vitest --config ./vitest.root.config.ts`                               |
+| `root:test:tool`   | `vitest --config ./vitest.root.config.ts --project tool`                |
+| `root:test:unit`   | `vitest --config ./vitest.root.config.ts --project unit`                |
+| `root:typecheck`   | `tsgo --noEmit`                                                         |
+| `root:upgrade`     | `nmr-taze --include-locked`                                             |
 
 #### Utilities
 
@@ -404,14 +543,15 @@ nmr [flags] <command> [args...]
 
 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.
 
-| Flag                     | Description                                         | Default |
-| ------------------------ | --------------------------------------------------- | ------- |
-| `-F, --filter <pattern>` | Run command in matching packages                    | —       |
-| `-R, --recursive`        | Run command in all packages                         | —       |
-| `-w, --workspace-root`   | Use root scripts, running at the monorepo root      | —       |
-| `-q, --quiet`            | Suppress info messages; show full output on failure | —       |
-| `-?, --help`             | Show available commands                             | —       |
-| `-V, --version`          | Show version number                                 | —       |
+| Flag                     | Description                                             | Default |
+| ------------------------ | ------------------------------------------------------- | ------- |
+| `-F, --filter <pattern>` | Run command in matching packages                        | —       |
+| `-R, --recursive`        | Run command in all packages                             | —       |
+| `-w, --workspace-root`   | Use root scripts, running at the monorepo root          | —       |
+| `-q, --quiet`            | Suppress info messages; show full output on failure     | —       |
+| `--no-cache`             | Run even if this tree already passed; record the result | —       |
+| `-?, --help`             | Show available commands                                 | —       |
+| `-V, --version`          | Show version number                                     | —       |
 
 ### Examples
 
@@ -421,8 +561,9 @@ nmr test  # Run workspace test script
 nmr build # Compile to .js and .d.ts in one pass
 
 # From the monorepo root
-nmr test # Root tests + recursive workspace tests
-nmr ci   # build + check:strict + audit
+nmr test    # Root tests + recursive workspace tests
+nmr ci      # build + check:strict
+nmr prepush # ci + audit
 
 # Target specific packages
 nmr --filter core test # Test only the core package
@@ -488,6 +629,10 @@ nmr-clean
 
 Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` and `.d.ts` in one pass. Because the compiler parses each source file, every relative import form — static, re-export, dynamic `import()`, and bare side-effect — is rewritten from `.ts` to `.js` in both outputs, and `.ts` occurrences inside strings and comments are left intact. tsconfig `paths` aliases are resolved to runnable relative `.js` specifiers in both outputs, sourced from the package's tsconfig. An aliased import whose target resolves outside the package's `src/` and is not resolvable without the alias mapping fails the build with a diagnostic, rather than being emitted verbatim to produce output that fails at runtime. The build is skipped when no input has changed and the previous output is still on disk (a content-and-path hash is cached under `node_modules/.cache/nmr-compile/`, outside the published output). Deleting the output by any means — `nmr clean`, `rm -rf dist`, `git clean` — therefore forces a rebuild rather than a skip. This is the default `compile` script — run it from a package directory.
 
+**What it compiles.** Entry points are `src/**/*.ts` less the directories that hold test scaffolding rather than shipped code: `__fixtures__/`, `__mocks__/`, `__tests__/`, and `test-utils/`. Add to that list per package with [`build.extraIgnorePatterns`](#package-level-configuration). Ignoring a directory drops it as an _entry point_, not from the emit: the compiler still emits whatever the surviving entry points import, so a helper that production code uses is still compiled and its importer never emits a dangling specifier. This list is deliberately not the Vitest [coverage exclusions](#what-the-config-excludes) — helpers live in `test-utils/` precisely so they stay covered.
+
+**The build owns its output directory.** Every rebuild wipes `dist/esm` before emitting, so the directory holds exactly the current emit: a source that was deleted, or that a widened ignore set now covers, leaves nothing behind. Assets therefore belong outside the output directory, or in a `build:post` hook, which runs after the wipe and so composes correctly. Note that a bare `nmr compile` runs no hook, so assets a `build:post` step copies in are absent until a full `nmr build` restores them. An `outdir` that does not resolve inside the package is rejected rather than wiped.
+
 `typescript` is a peer dependency (`>=5.7.0 <7`); the consuming repo provides it. The floor is what `rewriteRelativeImportExtensions` requires; the ceiling is because TypeScript 7 ships no compiler API — its root export is a version constant, so `nmr-compile` cannot run on it. Relative imports in source must carry explicit `.ts` extensions for them to be rewritten.
 
 ```bash
@@ -535,6 +680,29 @@ ensure-prepublish-hooks
 | `--dry-run`           | Preview what `--fix` would do | —                 |
 | `--command <command>` | Custom hook command           | `"npm run build"` |
 
+## 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, and the [test-tier convention](#test-tiers). 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.
+
+Add `readyup` as a devDependency, then name nmr in its config:
+
+```ts
+// .config/readyup.config.ts
+import { defineRdyConfig } from 'readyup';
+
+export default defineRdyConfig({
+  packages: ['@williamthorsen/nmr'],
+});
+```
+
+```bash
+rdy run --packages                       # every kit 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.
+
 ## Consumer migration
 
 After installing, a consuming repo's root `package.json` scripts shrink to lifecycle hooks:
@@ -638,29 +806,42 @@ export default defineVitestConfig();
 
 `vitest` is a peer dependency (`>=4.0.0 <5`), declared optional — the consuming repo provides it, and repos that never import this subpath are unaffected.
 
-### Test categories
+### Test tiers
 
-The config declares three projects, named for what the tests cover:
+The config declares four projects, an ordered ladder named for the furthest thing a test reaches:
 
-| Project       | Matches                                | Covers                                   |
-| ------------- | -------------------------------------- | ---------------------------------------- |
-| `unit`        | every test file the others don't claim | source code                              |
-| `integration` | `*.int.test.{ts,tsx}`                  | behavior beyond source code              |
-| `app`         | `*.app.test.{ts,tsx}`                  | the app's own tooling, e.g. drift checks |
+| Project     | Matches                                | Reaches                                              |
+| ----------- | -------------------------------------- | ---------------------------------------------------- |
+| `unit`      | every test file the others don't claim | nothing outside the package's own dependency closure |
+| `tool`      | `*.tool.test.{ts,tsx}`                 | a program the environment must supply                |
+| `localhost` | `*.localhost.test.{ts,tsx}`            | a service running on this machine                    |
+| `remote`    | `*.remote.test.{ts,tsx}`               | a machine that isn't this one                        |
 
-All three match only under a `__tests__` directory. Select them at run time with `--project`, which accepts negation:
+All four match only under a `__tests__` directory. Select them at run time with `--project`, which unions when repeated and accepts negation:
 
 ```bash
-vitest --project '!integration' # everything except integration tests
-vitest --project integration    # integration tests alone
-vitest                          # every project
+vitest --project unit --project tool # everything that runs on a bare install
+vitest --project tool                # tests reaching a program, alone
+vitest                               # every project
 ```
 
-`unit` is defined by subtracting the other categories rather than by an allow-list of suffixes, so a file such as `parser.smoke.test.ts` runs under `unit` instead of being silently dropped.
+**A tier names what a test reaches, never how it invokes it.** A test driving a compiler through its JavaScript API is `tool`, exactly as one spawning the compiler binary is; whether a program ships as a library or an executable is an accident of packaging, not a property of the test. A package's `peerDependencies`, plus whatever binaries it spawns, are a good statement of where its `tool` boundary sits: a bundled dependency ships inside the package's own closure and is always present, so reaching one is `unit`.
+
+**A tier is not a statement about preconditions.** A `unit` test may still need something set up before it runs: a build, a generated fixture, a seeded file. What makes it `unit` is that it reaches nothing beyond the test process _while running_. The filesystem sits in `unit` for the same reason the tiers exist: they gate on what must be available, and the filesystem always is.
+
+**Every test file names its tier**, in the form `<subject>[.<aspect>].<tier>.test.ts`. Only the segment immediately before `.test.` selects a project, so an earlier one is free for documentation: `resolveConfig.packaged.unit.test.ts` reads as a companion to `resolveConfig.unit.test.ts` and still names `unit`.
+
+`unit` is defined by subtracting the tiers rather than by an allow-list of infixes, so a file such as `parser.smoke.test.ts` runs under `unit` instead of being silently dropped. That is a safety net, not a licence to omit the tier: a file whose tier segment is missing or misspelt runs under `unit` and reports success, so no test run distinguishes it from a conformant one. [nmr's readyup kit](#conformance-checks) reports those files, which is the only thing that does.
+
+`localhost` and `remote` have no test script of their own. They are declared anyway, so that a `*.remote.test.ts` file cannot fall into `unit` and run in the default gate unnoticed.
+
+Every tier above `unit` carries a 30-second `testTimeout` and `hookTimeout`, where `unit` keeps Vitest's defaults of 5 and 10 seconds. A tier test waits on something it doesn't control, and coverage instrumentation multiplies that wait, so the defaults turn a green suite flaky the moment `nmr test:coverage` collects it. Both budgets move together because a tier that scaffolds in `beforeAll` moves that wait out from under `testTimeout` entirely, where raising the test budget alone never reaches it. `unit` keeps the tight budgets, which is what makes a hung unit test fail fast.
+
+To raise a budget for one tier and no other, use the `tiers` seam below. The `project` seam merges over both budgets as well, but like every option passed through it the value reaches all four projects at once -- raising a tier's budget raises `unit`'s with it. To lift the ceiling for a single file rather than a whole tier, pass a timeout to the individual test or hook, which stays the narrower tool.
 
 ### Customizing by scope
 
-Vitest applies some options at the root of a `projects` config and others per project, and placing one at the wrong level is silent rather than loud. The factory therefore takes two separate override surfaces instead of one merged config:
+Vitest applies some options at the root of a `projects` config and others per project, and placing one at the wrong level is silent rather than loud. The factory therefore takes separate override surfaces instead of one merged config:
 
 ```ts
 export default defineVitestConfig({
@@ -668,16 +849,57 @@ export default defineVitestConfig({
   root: { resolve: { conditions: ['development'] } },
   // Applied to every project.
   project: { setupFiles: ['./vitest.setup.ts'] },
+  // Applied to one tier, after the `project` block above.
+  tiers: { tool: { testTimeout: 120_000 } },
 });
 ```
 
-`root` is typed to accept only the options that work at the root, so writing a per-project option there is a compile error rather than a setting that never runs. Both surfaces merge into the generated config rather than replacing it, so overriding one coverage field leaves the rest intact.
+`root` is typed to accept only the options that work at the root, so writing a per-project option there is a compile error rather than a setting that never runs. Every surface merges into the generated config rather than replacing it, so overriding one coverage field leaves the rest intact.
+
+`tiers` is keyed by tier name and reaches all four, `unit` included. A key naming no tier throws and names the valid ones: ignoring it would leave the suite green on the budget the key failed to change, which nothing in the run reports. A tier target sets whichever keys it names and no others, so raising `testTimeout` alone leaves that tier's `hookTimeout` at 30 seconds.
+
+Arrays concatenate rather than replace. `exclude` and `setupFiles` therefore add to what the config already declares, and no surface can narrow `include` or drop a default exclusion. Adding an `include` pattern through `project` widens all four projects at once, so a file matching it is collected by each and runs four times.
+
+`resolve.conditions` concatenates too, but layer order carries no meaning there: Vite consumes conditions as a set, and which one wins is decided by the key order of the consumed package's own `exports`. A later layer can add a condition and can never remove or outrank one an earlier layer contributed. `resolve.alias` is the one key that merges override-first, so a later alias takes precedence over an earlier one.
+
+### Sharing options across config files
+
+Vitest resolves one config per run, so a package that adds its own `vitest.config.ts` stops seeing the repo's root config entirely -- not the one setting it meant to change, all of them. Pass the shared settings as a layer instead:
+
+```ts
+// vitest.shared.ts
+import { fileURLToPath } from 'node:url';
+
+import type { VitestConfigOptions } from '@williamthorsen/nmr/vitest';
+
+export const shared: VitestConfigOptions = {
+  root: { resolve: { conditions: ['source'] } },
+  project: { setupFiles: [fileURLToPath(new URL('./vitest.setup.ts', import.meta.url))] },
+};
+```
+
+```ts
+// packages/web/vitest.config.ts
+import { defineVitestConfig } from '@williamthorsen/nmr/vitest';
 
-Arrays concatenate rather than replace. `exclude` and `setupFiles` therefore add to what the config already declares, and neither seam can narrow `include` or drop a default exclusion. Adding an `include` pattern through `project` widens all three projects at once, so a file matching it is collected by each and runs three times.
+import { shared } from '../../vitest.shared.ts';
+
+export default defineVitestConfig(shared, { project: { environment: 'jsdom' } });
+```
+
+Both factories fold any number of layers left to right: a later layer wins on a scalar, arrays concatenate in layer order, and an `undefined` layer is skipped, so `defineVitestConfig(shared, isCI ? ciLayer : undefined)` composes without a spread. `defineRootVitestConfig` takes the same layers, with `monorepoRoot` on the last one -- the config file's own, the only place `import.meta.dirname` names this repo.
+
+Order is the point where `setupFiles` is concerned, since a shared setup file establishes the environment the package's own then runs in. A later layer's `project` block likewise wins over an earlier layer's `tiers` target: the nearer config is the more deliberate.
+
+**A path in a shared layer must be absolute.** Vitest resolves `setupFiles` against each project's own root, not against the module that declared the path, so a bare `'./vitest.setup.ts'` in a shared module names a different file in every package that consumes it -- and a package that happens to own a file by that name loads the wrong one instead of failing. The co-located form stays correct in a config file that declares the path directly.
+
+**Do not merge two returned configs.** `mergeConfig(defineVitestConfig(), defineVitestConfig(mine))` looks like the idiomatic recovery and fails at startup: both sides declare the same four project names, which Vitest rejects with `Project name "unit" ... is not unique`. Layers merge the factory's inputs instead, which is why they yield four projects however many fold.
+
+A config file that omits the shared layer still loses those settings, silently -- Vitest's own resolution contract, not something the factory can intercept. Guard it with a test that fails when a package's suite goes missing, which also catches a shared `exclude` pattern swallowing one package's tests.
 
 ### What the config excludes
 
-Collection skips `**/node_modules/**`, `**/.git/**`, and `**/dist/**`. Coverage skips `**/__{fixtures,mocks,tests}__/**`, `**/index.ts`, `**/mock*.{ts,tsx}`, `**/*.d.ts`, and `**/*.types.ts`.
+Collection skips `**/node_modules/**`, `**/.git/**`, and `**/dist/**`. Coverage skips `**/__{fixtures,mocks,tests}__/**`, `**/index.ts`, and `**/*.d.ts`.
 
 Because both seams concatenate, a consumer can add an exclusion but never remove one. A pattern therefore earns its place in these lists only by preventing a _silent_ failure, one a consumer cannot self-diagnose. A visible failure, such as a stray file sitting at 0% in the coverage report, is left to the consumer's own `project` seam.
 
@@ -702,24 +924,31 @@ import { defineRootVitestConfig } from '@williamthorsen/nmr/vitest';
 export default defineRootVitestConfig({ monorepoRoot: import.meta.dirname });
 ```
 
-This variant reads `pnpm-workspace.yaml` and excludes every workspace package from all three projects, so a root run covers only root-level files. It reports no coverage of its own — packages cover their own sources.
+This variant reads `pnpm-workspace.yaml` and excludes every workspace package from all four projects, so a root run covers only root-level files. It reports no coverage of its own — packages cover their own sources.
 
 `monorepoRoot` is required, and because the config sits at the monorepo root, it is always `import.meta.dirname`. Stating the root rather than searching for it is what makes the exclusions describe this repo: a search from the working directory would resolve whichever monorepo the run started in, and every project is then pinned to that one. A directory holding no `pnpm-workspace.yaml` throws, naming the directory.
 
+### Migrating to the isolation tiers
+
+The projects were once named `unit`, `integration`, and `app`, for what a test _covered_ rather than what it _reached_. `integration` and `app` are gone.
+
+1. Rename every `*.int.test.ts`. A test that reaches a program the environment supplies becomes `*.tool.test.ts`; one that reaches nothing beyond the test process becomes `*.unit.test.ts`. Re-read each file rather than renaming in bulk -- the axis changed, so the old bucket does not map onto one new tier.
+2. Rename every `*.app.test.ts` onto the convention. `app` was never a tier, so keep it as the aspect segment and add the tier after it: `scaffold.app.test.ts` becomes `scaffold.app.unit.test.ts`.
+3. Replace `nmr test:integration` with `nmr test:tool`, and `nmr root:test:integration` with `nmr root:test:tool`, wherever a script or workflow names them.
+
+**A file left without a tier is a silent failure.** The residual `unit` claims it and it runs in the default gate -- green, with nothing reporting that the separation was lost. [nmr's readyup kit](#conformance-checks) reports every such file; a passing test run does not. Run it before treating the migration as done.
+
+`nmr test` also runs the `tool` tier, which the old `test` excluded. Those tests previously ran in no default selection at all: `check`, `check:strict`, and `ci` all inherited the exclusion, so a green pipeline said nothing about them. Expect `nmr test` to take longer and to surface failures that were never gated.
+
 ### Migrating from the config-file variants
 
-nmr once selected a package's test scripts by looking for a `vitest.integration.config.ts` on disk, which meant three config files per package that separated its integration tests. Those files are no longer consulted. **Migrate the config and the scripts together**: one without the other leaves the repo in one of the two states below.
+nmr once selected a package's test scripts by looking for a `vitest.integration.config.ts` on disk, which meant three config files per package that separated its integration tests. Those files are no longer consulted.
 
 1. Replace the repo's root `vitest.config.ts` with `defineVitestConfig()`, and its root-scoped config with `defineRootVitestConfig({ monorepoRoot: import.meta.dirname })`.
 2. Delete every `vitest.integration.config.ts` and `vitest.standalone.config.ts`, plus any per-package `vitest.config.ts` that only re-exports an ancestor. Vitest resolves config by walking up from the run root, so those are redundant.
-3. Rename integration tests to `*.int.test.ts` and tooling or drift tests to `*.app.test.ts`.
+3. Rename the tests onto the tiers, per the section above.
 4. Drop any hand-copied `test*` entries from `package.json`, which now shadow the defaults.
 
-Until step 1 is done, an upgraded nmr behaves as follows against a config that declares no projects:
-
-| Command                      | Result                                                                                                                                             |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `nmr test` / `test:coverage` | **Succeeds, and runs integration tests too.** The separation is lost with no error, because `--project '!integration'` matches nothing to exclude. |
-| `nmr test:integration`       | **Fails** with `No projects matched the filter "integration"`.                                                                                     |
+Until step 1 is done, every test command that names a tier fails against a config declaring no projects, with `Error: No projects matched the filter "unit", "tool".` at startup. `test:all` is the exception: it names no project, so it runs everything the config collects.
 
-The second is the reliable signal that migration is incomplete. The first is silent, so do not treat a green `nmr test` as evidence that the move succeeded.
+That is a change for the better. While `test` selected by negation, an unmigrated config produced a _green_ run, because `--project '!integration'` had nothing to exclude, so the separation was lost with no error anywhere. Positive selection turns the same state into a startup failure that names the missing projects.