@williamthorsen/nmr 0.38.0 → 0.40.0

package/dist/esm/workspace.js

@@ -1,76 +1,18 @@
-import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
-import { parse } from 'yaml';
-import { readStringValues } from "./helpers/readStringValues.js";
-import { isObject } from "./helpers/type-guards.js";
-import { resolvePackageDirs } from "./helpers/workspace-patterns.js";
+import { findMonorepoRoot as findMonorepoRootOrNothing, resolveWorkspace } from '@williamthorsen/nmr-core/workspace';
 import { UserError } from "./UserError.js";
-const PACKAGE_MANIFEST = 'package.json';
 const WORKSPACE_MANIFEST = 'pnpm-workspace.yaml';
-export function isMonorepoRoot(dir) {
-    return existsSync(path.join(dir, WORKSPACE_MANIFEST));
-}
+export { isMonorepoRoot, readWorkspaceOverrides, readWorkspacePackageNames, resolveWorkspace, } from '@williamthorsen/nmr-core/workspace';
 export function findMonorepoRoot(startDir) {
-    let dir = path.resolve(startDir ?? process.cwd());
-    for (;;) {
-        if (isMonorepoRoot(dir)) {
-            return dir;
-        }
-        const parent = path.dirname(dir);
-        if (parent === dir) {
-            throw new UserError(`Could not find monorepo root: no ${WORKSPACE_MANIFEST} found in any parent directory`);
-        }
-        dir = parent;
+    const monorepoRoot = findMonorepoRootOrNothing(startDir);
+    if (monorepoRoot === undefined) {
+        throw new UserError(`Could not find monorepo root: no ${WORKSPACE_MANIFEST} found in any parent directory`);
     }
+    return monorepoRoot;
 }
 export function getWorkspacePackageDirs(monorepoRoot) {
-    const workspaceFile = path.join(monorepoRoot, WORKSPACE_MANIFEST);
-    if (!existsSync(workspaceFile)) {
+    const resolution = resolveWorkspace(monorepoRoot);
+    if (resolution.kind === 'not-a-workspace') {
         throw new UserError(`Not a monorepo root: no ${WORKSPACE_MANIFEST} in ${monorepoRoot}`);
     }
-    const content = readFileSync(workspaceFile, 'utf8');
-    const parsed = parse(content);
-    const packages = getPackagesFromParsedYaml(parsed);
-    if (!packages) {
-        return [];
-    }
-    return resolvePackageDirs(monorepoRoot, packages);
-}
-export function readWorkspaceOverrides(monorepoRoot) {
-    const workspaceFile = path.join(monorepoRoot, WORKSPACE_MANIFEST);
-    if (!existsSync(workspaceFile)) {
-        return undefined;
-    }
-    const parsed = parse(readFileSync(workspaceFile, 'utf8'));
-    if (!isObject(parsed)) {
-        return undefined;
-    }
-    const overrides = parsed['overrides'];
-    return isObject(overrides) ? readStringValues(overrides) : undefined;
-}
-export function readWorkspacePackageNames(packageDirs) {
-    const names = [];
-    for (const dir of packageDirs) {
-        let parsed;
-        try {
-            parsed = JSON.parse(readFileSync(path.join(dir, PACKAGE_MANIFEST), 'utf8'));
-        }
-        catch {
-            continue;
-        }
-        if (isObject(parsed) && typeof parsed['name'] === 'string') {
-            names.push(parsed['name']);
-        }
-    }
-    return names;
-}
-function getPackagesFromParsedYaml(parsed) {
-    if (!isObject(parsed))
-        return undefined;
-    const packages = parsed['packages'];
-    if (!Array.isArray(packages))
-        return undefined;
-    if (!packages.every((p) => typeof p === 'string'))
-        return undefined;
-    return packages;
+    return resolution.kind === 'packages' ? resolution.packageDirs : [];
 }

package/docs/check-cache.md

@@ -4,9 +4,9 @@ How nmr skips a check that already passed on the same working tree, what decides
 
 The [README](../README.md#check-result-cache) shows a skip in action.
 
-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 is [reported](reporting.md#what-nmr-reports) in every verbosity.
+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 at which it ran. A later `nmr check`, `nmr typecheck`, or `nmr -F core test` on the same tree skips too. The skip is [reported](reporting.md#what-nmr-reports) in every verbosity.
 
-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.
+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
 
@@ -14,18 +14,18 @@ Cacheable by default: `check`, `check:strict`, `ci`, `fix:check`, `fmt:check`, `
 
 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.                                          |
+| Command                         | Why it is never skipped                                                                                                                              |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `audit`, `prepush`              | Consult a vulnerability database that changes independently of the tree. `prepush`'s `ci` constituent still skips while its `audit` runs every time. |
+| `build`, `compile`              | Have a cache of their own.                                                                                                                           |
+| `fix`, `fmt`, `lint`, `upgrade` | Rewrite the tree that 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.
+**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 that a cacheable command was relied on to produce 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.
+`test:coverage` is cacheable on exactly this reading: It contributes the pass, not the `coverage/` directory, which a skipped run leaves as whatever the last real run wrote. After a `test:coverage` that may have skipped, `coverage/` may be stale; `--no-cache` forces 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`.
 
@@ -33,44 +33,44 @@ Overriding a cacheable name, in `package.json` or in `workspaceScripts`, inherit
 
 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.
+- **The working tree's content**, hashed from the commit's tree object folded with the current content of every path that git reports as changed or untracked. Timestamps are not content, so a `touch` that does not rewrite any bytes leaves the hash alone.
+- **The command string that would run**, hooks and all, and the scope in which it would run.
 - **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.
+- **What pnpm has installed.** 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 other environment variables 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 hit additionally requires the build output of every package that nmr's own build covers to be present, and to have been built from this tree. Because output is git-ignored, neither its removal nor its replacement changes the hash: Restoring a tree with `git stash` or `git checkout` does not restore any of the output with which that tree was built. nmr compares each covered package's recorded build digest against the one on disk, and treats a `dist` compiled from another tree as a miss that the following run repairs. A package that overrides `build` or `compile` emits on terms that 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 unchanged since the run started, and never for a run that executed nothing (a `""`/`":"` skip override, or an `NMR_RUN_IF_PRESENT` miss). Output that moves mid-run leaves no answer to which output the pass was earned over, whether another process rebuilt it or the chain built it itself: `nmr ci` is the one default command whose chain does, and it records nothing on a run whose build did work. The `nmr check:strict` inside that chain still records, because its own window opens after the build.
+A pass is recorded only when the command exits 0, only when the tree still matches the one against which the run started, only when every covered package's output is present and unchanged since the run started, and never for a run that executed nothing (a `""`/`":"` skip override, or an `NMR_RUN_IF_PRESENT` miss). When output changes mid-run, whether another process rebuilt it or the chain built it itself, nmr cannot tell over which output the pass was earned: `nmr ci` is the one default command whose chain builds its own output, and it does not record a pass on a run whose build did work. The `nmr check:strict` inside that chain still records a pass, because it starts after the build.
 
 ## Out of contract
 
-These change what a check concludes without moving the hash. Where one applies, exclude the affected command:
+These change what a check concludes without changing the hash. When 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.
+- **Content filters.** `core.autocrlf` and `.gitattributes` filters mean the bytes on disk differ from the bytes that 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 that it names, not by the content of its target.
 - **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.
+- **`passWithNoTests`.** A suite that does not collect any files exits 0, and that pass 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.
+Committing an already-checked tree also changes 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
+## When the cache does not apply
 
-The gate never wrongly skips. Where it cannot be sure, it does nothing and the command runs:
+The gate never wrongly skips. When 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`.
+- Outside a git repository, when git fails, or when `HEAD` does not resolve to a commit.
 - 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.
+- When the repository does not have a pnpm install to fingerprint.
+- Under a `devBin` substitution, which runs a binary built from a location that the hash does not describe.
 - For any invocation carrying arguments after the command name, and for every step below it: the arguments narrow what runs, and a step served from a recorded pass is a step that did not.
 
-`NMR_DEBUG=1` reports why a run did not skip and why the gate stood aside.
+`NMR_DEBUG=1` reports why a run did not skip and why the cache did not apply.
 
 ## Replaying a skipped run's output
 
-A skip reports an excerpt of the run it recalls, marked as a recording rather than as this run's output:
+A skip reports an excerpt of the run that it recalls, marked as a recording rather than as this run's output:
 
 ```console
 $ nmr test
@@ -80,11 +80,11 @@ $ nmr test
 ⏩ nmr: test: passed 2m ago on this tree, saved ~12s — replayed: Test Files 6 passed (6) Tests 41 passed (41)
 ```
 
-The excerpt is the last blank-line-delimited block of what the command wrote, which is the closing statement a tool separates from its progress output. It is flattened onto one line, with escape sequences stripped, table rules dropped, and a redrawn progress line reduced to what a reader was left looking at. Nothing is parsed and no figure is computed: nmr replays bytes it recorded. A block wider than a few kilobytes is cut and marked with `…`, so a command whose closing statement is one long line cannot carry its whole output into the cache.
+The excerpt is the last blank-line-delimited block of what the command wrote, which is the closing statement that a tool separates from its progress output. It is flattened onto one line, with escape sequences stripped, table rules dropped, and a redrawn progress line reduced to what a reader was left looking at. nmr does not parse anything or compute any figure: It replays bytes that it recorded. A block wider than a few kilobytes is cut and marked with `…`, so a command whose closing statement is one long line cannot put its whole output in the cache.
 
-The excerpt and the whole transcript it is drawn from are written by the same operation that records the pass, so a pass declined because the tree moved or build output changed leaves neither behind, and `nmr clean` clears both along with the passes they belong to.
+The operation that records the pass also writes the excerpt and the whole transcript from which it is drawn. A pass that nmr declines to record because the tree or the build output changed leaves neither behind, and `nmr clean` clears both along with the passes to which they belong.
 
-**Capture happens at the command, and only where nmr can see its output.** A command whose stdout or stderr is a terminal writes where nmr never reads, so an interactive run retains nothing and its progress display is untouched; a piped or redirected run, and any run under `-q`, retains both streams. A composite hands its descriptors to the child `nmr` processes below it and captures nothing of its own, and a `:pre` or `:post` hook contributes nothing to the command it wraps: an excerpt is the command's own output or none.
+**nmr captures output at the command, and only when it can see that output.** A command whose stdout or stderr is a terminal writes to a stream that nmr never reads, so an interactive run retains nothing and its progress display is untouched; a piped or redirected run, and any run under `-q`, retains both streams. A composite passes its file descriptors to the child `nmr` processes below it and captures nothing of its own, and a `:pre` or `:post` hook contributes nothing to the command that it wraps: An excerpt is the command's own output or none.
 
 **A composite replays its constituents' excerpts.** Capturing nothing of its own, a composite assembles what its constituents recorded, each line attributed to the scope and command that produced it:
 
@@ -93,19 +93,19 @@ $ nmr check
 ⏩ nmr-core: check: passed 3m ago on this tree, saved ~48s — replayed: nmr-core: fmt:check: All matched files use Prettier code style!; nmr-core: test: Test Files 6 passed (6) Tests 41 passed (41)
 ```
 
-The assembly is flat: a constituent that is itself a composite contributes its own leaves' lines, so a skipped `ci` replays a package's `test` rather than one opaque `check:strict` line. A delegate expands into the scopes it fans out to, and a constituent that recorded no excerpt is absent rather than inferred: `typecheck` and `lint:check` print nothing on success and contribute nothing above, and a command outside the [cacheable set](#what-is-cached) records nothing at all, so `ci` replays what `check:strict` earned and nothing for `build`.
+The assembly is flat: A constituent that is itself a composite contributes its own leaves' lines, so a skipped `ci` replays a package's `test` rather than one opaque `check:strict` line. A delegate expands into the scopes to which it fans out, and a constituent that did not record an excerpt is absent rather than inferred: `typecheck` and `lint:check` print nothing on success and contribute nothing above, and a command outside the [cacheable set](#what-is-cached) records nothing at all. `ci` replays what `check:strict` earned and nothing for `build`.
 
-It is assembled when the composite records its pass rather than when it skips, so every excerpt in it was certified during that one run, on that one tree. `NMR_RUN_ID` is what makes that provable; see [reserved environment variables](#reserved-environment-variables).
+Every excerpt in the assembly was certified during a single run, on a single tree, because nmr assembles it when the composite records its pass rather than when it skips. `NMR_RUN_ID` makes that provable; see [reserved environment variables](#reserved-environment-variables).
 
 **A skip certifies what it replays.** Recalling a pass proves the excerpt describes this tree, and a matching retention key proves it describes this presentation environment, so a skip restamps the recalled entry with the run replaying it. A constituent already warm when a composite ran therefore still contributes its line: `nmr check` after `nmr test` replays the test summary. The restamp touches nothing else -- the instant and the duration belong to the run that earned the pass.
 
-**A replay is held to more than the pass is.** Retention carries its own key: the [pass key](#what-the-key-is-made-of) folded with the channel each output stream ran on and with `CI`, `COLUMNS`, `FORCE_COLOR`, `NO_COLOR`, and `TERM`. `NMR_OUTPUT_STYLE` is in neither key, so a rich run and a plain one share a recorded pass and replay each other's excerpts as recorded. A recording made under a different one is recalled as a pass all the same; its excerpt is simply not replayed, and the verdict prints alone, as it does for a pass that retained nothing.
+**A replay is held to more than the pass is.** Retention has its own key: the [pass key](#what-the-key-is-made-of) folded with the channel on which each output stream ran and with `CI`, `COLUMNS`, `FORCE_COLOR`, `NO_COLOR`, and `TERM`. `NMR_OUTPUT_STYLE` is in neither key, so a rich run and a plain one share a recorded pass and replay each other's excerpts as recorded. A recording made under a different one is recalled as a pass all the same; its excerpt is simply not replayed, and the verdict prints alone, as it does for a pass that retained nothing.
 
-The whole line, excerpt included, is held to the same [512-byte ceiling](reporting.md#what-nmr-reports) every verdict is, so one write still carries it whole under concurrent fan-out. An assembly wide enough to overrun it is cut and marked with `…` rather than spread over several lines.
+Because the whole line, excerpt included, is held to the same [512-byte ceiling](reporting.md#what-nmr-reports) as every verdict, one write still emits it whole under concurrent fan-out. An assembly wide enough to overrun it is cut and marked with `…` rather than spread over several lines.
 
 ## Reading a retained run
 
-The excerpt is a line; the run behind it is kept whole. `nmr --log <command>` prints it, led by a header dating what follows:
+The excerpt is a line; nmr also keeps the run's whole transcript. `nmr --log <command>` prints that transcript after a header that dates it:
 
 ```console
 $ nmr --log test
@@ -118,43 +118,43 @@ $ pnpm exec vitest --project unit --project tool
       Tests  41 passed (41)
 ```
 
-The header is what presents the body as a recording rather than as this invocation's output. The command string is the whole chain, hooks included, so it names what earned the pass and not merely what was typed. A flag rather than a subcommand, since `log` would collide with the script registry.
+The header presents the body as a recording rather than as this invocation's output. The command string is the whole chain, hooks included, so it names what earned the pass and not merely what was typed. A flag rather than a subcommand, since `log` would collide with the script registry.
 
-**Reading a recording runs nothing.** No hook runs, no verdict prints, and nothing is recorded or restamped. `--no-cache` governs running rather than reading and is ignored.
+**Reading a recording runs nothing.** nmr does not run any hook or print any verdict, and it does not record or restamp anything. `--no-cache` governs running rather than reading and is ignored.
 
-**A recording is held to the tree, not to the terminal.** `--log` prints exactly what a skip would have recalled: the [pass key](#what-the-key-is-made-of) has to match. The [retention key](#replaying-a-skipped-runs-output) is not consulted, so a recording made under a different terminal width, or through a pipe, still prints -- a reader at a terminal being shown what a piped run wrote is the case the flag exists for.
+**A recording is held to the tree, not to the terminal.** `--log` prints exactly what a skip would have recalled: The [pass key](#what-the-key-is-made-of) has to match. `--log` does not consult the [retention key](#replaying-a-skipped-runs-output), so a recording made under a different terminal width, or through a pipe, still prints -- the flag exists to show a reader at a terminal what a piped run wrote.
 
-**A composite prints its assembly.** Retaining nothing of its own, a composite prints the excerpts its constituents recorded, one attributed line each. The transcript of any one of them is that constituent's own `--log` to print.
+**A composite prints its assembly.** Retaining nothing of its own, a composite prints the excerpts that its constituents recorded, one attributed line each. To print the transcript of any one of them, run `--log` for that constituent.
 
-**Nothing to show is said rather than left blank.** A refusal names which it is -- the command is outside the [cacheable set](#what-is-cached), the gate is [standing aside](#when-the-gate-stands-aside), nothing has recorded a pass, the last pass was recorded under something this run does not share, or the pass retained no output, having printed none or written to a terminal -- and exits non-zero, so a caller can tell an empty `stdout` from a recording. A mismatch names the ingredient that moved, the tree or the chain or a version, so a reader whose `git status` is clean is not sent looking there.
+**When nmr has nothing to show, it says so rather than printing a blank.** A refusal names which case applies -- the command is outside the [cacheable set](#what-is-cached), the [cache does not apply](#when-the-cache-does-not-apply), nothing has recorded a pass, the last pass was recorded under something this run does not share, or the pass did not retain any output, having printed none or written to a terminal -- and nmr exits non-zero, so that a caller can tell an empty `stdout` from a recording. A mismatch names the ingredient that changed, whether the tree, the chain, or a version, to keep a reader whose `git status` is clean from looking there.
 
 ```console
 $ nmr --log test
-🟠 nmr: test: no recording; the last pass was 3m ago, on a tree this is not
+🟠 nmr: test: no recording; the last pass was 3m ago, on a tree that this is not
 ```
 
-**`--log` reaches the scopes `-F` and `-R` select.** The flag rides the delegate, so each scope prints its own recording. There a scope with nothing to show reports its gap and exits 0: partial coverage is a survey's normal shape, and failing on the first gap would hide every scope that had something. A selection of no scope at all is the other case and fails, as it does for a run: there is no survey to be partial.
+**`--log` applies to the scopes that `-F` and `-R` select.** nmr passes the flag to the delegate. Each scope prints its own recording. There a scope with nothing to show reports its gap and exits 0: Partial coverage is normal for a survey, and failing on the first gap would hide every scope that had something to show. A selection that does not include any scope is the other case and fails, as it does for a run: An empty selection is not a partial survey.
 
-**Retention has a ceiling of 256 KiB per recorded pass**, distinct from the 512 bytes a verdict line is held to. A transcript overrunning it keeps 128 KiB from each end, because a run's opening and its closing statement each carry what the other does not, and the drop is marked with a line naming the bytes it stands for rather than being cut silently.
+**Retention has a ceiling of 256 KiB per recorded pass**, distinct from the 512 bytes to which a verdict line is held. nmr keeps 128 KiB from each end of a transcript that overruns it, because a run's opening and its closing statement each contain what the other does not, and it marks the drop with a line that names the dropped bytes, rather than cutting silently.
 
 ## Bypassing and clearing
 
-Reach for these in order; the first is almost always the right one.
+Try 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.       |
+| Step                                   | Effect                                                                       |
+| -------------------------------------- | ---------------------------------------------------------------------------- |
+| `nmr --no-cache <command>`             | Runs the command, then records the fresh result. Applies to 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.
+`--no-cache` belongs before the command name. After it, it is an argument to the command rather than a flag to nmr; nmr reports this rather than silently ignoring the bypass.
 
 ## 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.
+`NMR_TREE_SNAPSHOT` is nmr's own: It passes one observation of the tree from a top-level invocation down to the processes that it spawns, so a chain hashes the tree once rather than at every link. nmr trusts an inherited value only while `HEAD` still points to the same commit as when the observation was taken, which bounds a process that outlives the run that spawned it. Because that bound does not extend to a tree edited without committing, **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.
 
-`NMR_RUN_ID` is nmr's own too: it carries one run's identity from a top-level invocation down to the processes it spawns, so the excerpts recorded at every scope during one run are recognizable as that run's, and a composite can assemble from them. Where `NMR_TREE_SNAPSHOT` is bounded by `HEAD`, this is bounded by the tree hash each entry records, so a process that outlives its run and carries the identity into a later one contributes nothing to that run's assemblies.
+`NMR_RUN_ID` is nmr's own too: It passes one run's identity from a top-level invocation down to the processes that it spawns, so that the excerpts recorded at every scope during one run are recognizable as that run's, and a composite can assemble from them. Whereas `NMR_TREE_SNAPSHOT` is bounded by `HEAD`, this one is bounded by the tree hash that each entry records. A process that outlives its run and carries the identity into a later one contributes nothing to that run's assemblies.
 
 ## Configuring
 
@@ -169,8 +169,8 @@ export default defineConfig({
 });
 ```
 
-`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.
+`extraCommands` extends the default set rather than replacing it, so naming one command cannot silently drop the rest. nmr applies `excludeCommands` afterwards and excludes a name that appears in both. `enabled: false` turns the gate off entirely. The key is `checkCache`, in the monorepo-root config.
 
-**A name in either list must resolve to a command**, whether through nmr's defaults, the repo config's script records, or a package's own `package.json` scripts. Both lists are read by name alone, so a misspelt entry would otherwise be inert: the command it meant to name would go on running, indistinguishable from one that cannot be cached at all. A name that resolves nowhere fails config load, naming the closest command where there is one. A hook name is rejected too, since a hook is never gated on its own -- it runs as part of the chain of the command it wraps, and is skipped or run with it.
+**A name in either list must resolve to a command**, whether through nmr's defaults, the repo config's script records, or a package's own `package.json` scripts. Both lists are read by name alone, so a misspelt entry would otherwise be inert: The command that it meant to name would go on running, indistinguishable from one that cannot be cached at all. A name that resolves nowhere fails config load, naming the closest command if one exists. A hook name is rejected too, since a hook is never gated on its own -- it runs as part of the chain of the command that it wraps, and is skipped or run with it.
 
-The test is resolvability rather than membership of the cacheable set, so an `excludeCommands` entry keeps standing after a release moves its name out of the defaults.
+Because the test is resolvability rather than membership of the cacheable set, an `excludeCommands` entry stays valid after a release moves its name out of the defaults.

package/docs/prettier.md

@@ -2,23 +2,23 @@
 
 The Prettier config that `@williamthorsen/nmr/prettier` publishes: what it formats, how it scopes the shell plugin, and how to customize and adopt it.
 
-`prettier` is a peer dependency (`>=3.9.5 <4`), declared optional — the consuming repo provides it. The shell and Dockerfile plugin is a dependency of nmr rather than a peer, so its version is pinned centrally and two repos cannot format the same script differently.
+`prettier` is a peer dependency (`>=3.9.5 <4`), declared optional; the consuming repo provides it. The shell and Dockerfile plugin is a dependency of nmr rather than a peer, so its version is pinned centrally and two repos cannot format the same script differently.
 
 ## What it formats
 
-Beyond everything Prettier already handles, this config formats `.sh`, `.bash`, `.zsh`, and the other extensions and dotfile names of the Shell language, plus `Dockerfile` and `Containerfile`. `nmr fmt` therefore covers shell scripts with no extra script, glob, or workflow entry.
+Beyond everything Prettier already handles, this config formats `.sh`, `.bash`, `.zsh`, and the other extensions and dotfile names of the Shell language, plus `Dockerfile` and `Containerfile`. `nmr fmt` therefore covers shell scripts without an extra script, glob, or workflow entry.
 
-Shell output matches `shfmt` run with no flags: `binaryNextLine`, `spaceRedirects`, and `switchCaseIndent` are pinned to shfmt's CLI defaults, which the underlying plugin inverts. A repo whose scripts shfmt already formatted sees no diff on adoption.
+Shell output matches `shfmt` run without flags: `binaryNextLine`, `spaceRedirects`, and `switchCaseIndent` are pinned to shfmt's CLI defaults, which the underlying plugin inverts. Adoption does not produce any diff in a repo whose scripts shfmt already formatted.
 
-Code fences inside Markdown are left alone, in every language rather than shell alone. Registering the shell plugin also routes a fence tagged `bash` to shfmt, where a documented command's angle-bracket placeholders are valid redirections: `cmd --type <type> --harness claude` is reprinted as `cmd --type claude <type >--harness`, which still runs but no longer does what it documents. It cannot be narrowed back to shell, because Prettier matches a fence tag against the same `extensions` its file inference reads, so the `.bash` routing a script also claims the tag `bash`.
+Code fences inside Markdown are left alone, in every language rather than shell alone. Registering the shell plugin also sends a fence tagged `bash` to shfmt, which reads a documented command's angle-bracket placeholders as valid redirections: `cmd --type <type> --harness claude` is reprinted as `cmd --type claude <type >--harness`, which still runs but no longer does what it documents. It cannot be narrowed back to shell, because Prettier matches a fence tag against the same `extensions` that its file inference reads, so the `.bash` extension that sends a script to the shell parser also matches the tag `bash`.
 
 ## Language scoping
 
-`prettier-plugin-sh` routes 20 further file types to the same shell parser, among them `.gitignore`, `.env`, `.csh`, `.nu`, `.properties`, `.ics`, `.vcf`, `CODEOWNERS`, and `hosts`. Since `nmr fmt` hands git's whole file list to Prettier, registering the plugin as shipped would make every one of them formattable — and the shell parser either fails on them or silently rewrites them. A `.gitignore` pattern such as `a(b)c` fails to parse, and an unquoted `&` in a `.env` or `.properties` value is split across two lines.
+`prettier-plugin-sh` assigns 20 further file types to the same shell parser, among them `.gitignore`, `.env`, `.csh`, `.nu`, `.properties`, `.ics`, `.vcf`, `CODEOWNERS`, and `hosts`. Since `nmr fmt` passes git's whole file list to Prettier, registering the plugin unmodified would make every one of them formattable, and the shell parser either fails on them or silently rewrites them. A `.gitignore` pattern such as `a(b)c` fails to parse, and an unquoted `&` in a `.env` or `.properties` value is split across two lines.
 
-This config registers a narrowed plugin, so Prettier infers a parser for the Shell and Dockerfile languages alone. `.flaskenv`, `gradlew`, and `mvnw` are dropped from Shell as well: the first holds dotenv content the plugin misfiles as shell, and the other two are vendored wrappers their generators would overwrite.
+This config registers a narrowed plugin, so Prettier infers a parser for the Shell and Dockerfile languages alone. `.flaskenv`, `gradlew`, and `mvnw` are dropped from Shell as well: The first contains dotenv content that the plugin misidentifies as shell, and the other two are vendored wrappers that their generators would overwrite.
 
-The parsers themselves stay registered, so a repo that wants a dropped language back assigns it explicitly:
+The parsers themselves stay registered. A repo that wants a dropped language back assigns it explicitly:
 
 ```js
 export default definePrettierConfig({
@@ -38,10 +38,10 @@ export default definePrettierConfig({
 });
 ```
 
-`additionalPlugins` and `additionalOverrides` append to what the config declares, so a later override wins over nmr's own and no seam can drop shell support. Passing `plugins` or `overrides` throws, and both are typed `never` — replacement is inexpressible rather than merely discouraged, because a silently ignored key would produce no diff to notice.
+`additionalPlugins` and `additionalOverrides` append to what the config declares, so a later override wins over nmr's own, and a repo cannot use either option to drop shell support. Passing `plugins` or `overrides` throws, and both are typed `never`: Replacement is inexpressible rather than merely discouraged, because a silently ignored key would not produce any diff to notice.
 
 ## Adoption caveats
 
-- **Indentation follows `.editorconfig`**, as it did under shfmt: Prettier maps `indent_style` and `indent_size` to `useTabs` and `tabWidth`, and the plugin honours both. With no `.editorconfig`, the two disagree — shfmt indents shell with tabs, Prettier with two spaces. Add `indent_style = tab` under `[*.sh]` to keep tabs.
-- **Markdown fences stop being tidied.** The carve-out that protects documented shell commands costs the `ts`, `json`, and `yaml` fences their formatting too. Fences already formatted stay as they are, so nothing churns on adoption; new ones are simply left as written. A repo whose docs hold no shell can take them back for the Markdown paths it actually uses: `additionalOverrides: [{ files: ['*.md'], options: { embeddedLanguageFormatting: 'auto' } }]` restores `.md` alone, and the carve-out still covers every other path Prettier reads as Markdown.
+- **Indentation follows `.editorconfig`**, as it did under shfmt: Prettier maps `indent_style` and `indent_size` to `useTabs` and `tabWidth`, and the plugin honours both. Without an `.editorconfig`, the two disagree: shfmt indents shell with tabs, Prettier with two spaces. Add `indent_style = tab` under `[*.sh]` to keep tabs.
+- **Markdown fences stop being tidied.** The carve-out that protects documented shell commands leaves the `ts`, `json`, and `yaml` fences unformatted too. Fences already formatted stay as they are, so adoption does not change them; new ones are simply left as written. A repo whose docs do not contain any shell can restore fence formatting for the Markdown paths that it actually uses: `additionalOverrides: [{ files: ['*.md'], options: { embeddedLanguageFormatting: 'auto' } }]` restores `.md` alone, and the carve-out still covers every other path that Prettier reads as Markdown.
 - **Adopting the house options reformats the repo.** `singleQuote`, `trailingComma`, and the rest apply on the first run; review that diff separately from the shell one.

package/docs/reporting.md

@@ -1,22 +1,26 @@
 # What nmr reports
 
-How nmr reports each command it runs, in prose or as JSON, and how loudly it relays the output of those commands.
+How nmr reports each command that it runs, in prose or as JSON, and how loudly it relays the output of those commands.
 
 The verdict line and its four outcomes are shown in the [README](../README.md#what-nmr-reports).
 
-A recalled pass also carries an excerpt of the run it recalls, where that run left one; see [Replaying a skipped run's output](check-cache.md#replaying-a-skipped-runs-output).
+A recalled pass also includes an excerpt of the run that it recalls, if that run left one; see [Replaying a skipped run's output](check-cache.md#replaying-a-skipped-runs-output).
 
-The scope is the directory the command's registry belongs to: a package's own directory, or the monorepo root. Durations and ages truncate and carry at most two units, so a check that passed 90 seconds ago reports `1m 30s ago` and never `2m ago`.
+The scope is the directory to which the command's registry belongs: a package's own directory, or the monorepo root. Durations and ages truncate and show at most two units, so a check that passed 119.9 seconds ago reports `1m 59s ago` and never `2m ago`.
 
-Verdicts nest. A composite reports, and so does every command it expands into; a `:pre` or `:post` hook reports nothing of its own, since the command it wraps already reports for the chain, though a hook that delegates to a named command reports under that name. A `-R` or `-F` invocation reports nothing either, every scope it fans out to reporting instead. A cold repo-wide `nmr ci` in this package's own monorepo spends 26 lines on a run that prints roughly 250.
+Verdicts nest. A composite reports, and so does every command into which it expands; a `:pre` or `:post` hook reports nothing of its own, since the command that it wraps already reports for the chain, though a hook that delegates to a named command reports under that name. A `-R` or `-F` invocation reports nothing either; every scope to which it fans out reports instead. A cold repo-wide `nmr ci` in this package's own monorepo uses 26 verdict lines to report a run that prints roughly 250.
 
-**A fan-out that selects no scope fails.** A `-F` pattern matches a package's manifest `name` rather than its directory name, so a plausible directory name selects nothing, and pnpm exits 0 over an empty selection as it does over a passing one. nmr asks pnpm what the pattern selects and refuses the invocation where the answer is nothing, naming the pattern and, where the pattern carries a name, the names it could have named. A pattern of another form states the rule its own shape answers to: a directory (`./dir`, `/dir`, `{dir}`), an exclusion (`!`), or a changed-since selector (`[<ref>]`), none of which a workspace name repairs. A pattern pnpm rejects rather than resolves, such as a bad git ref in a `[since]` selector, is left to pnpm to report. `-R` is refused on the same ground where the workspace declares no package at all, which is its only empty selection.
+**A fan-out that does not select any scope fails.** A `-F` pattern matches a package's manifest `name` rather than its directory name, so a plausible directory name selects nothing, and pnpm exits 0 over an empty selection as it does over a passing one. nmr asks pnpm what the pattern selects and refuses the invocation when the answer is nothing, naming the pattern and, when the pattern contains a name, the names that it could have named. For a pattern of another form, the refusal states the rule to which that form answers: a directory (`./dir`, `/dir`, `{dir}`), an exclusion (`!`), or a changed-since selector (`[<ref>]`), none of which a workspace name repairs. A pattern that pnpm rejects rather than resolves, such as a bad git ref in a `[since]` selector, is left to pnpm to report. A `-R` typed on the invocation is refused on the same ground when the workspace does not declare any package at all, which is its only empty selection. That condition takes precedence over the pattern rules above: When the workspace does not contain any package, a `-F` pattern could not have matched one, so the refusal reports the workspace rather than the shape of the pattern.
 
-A verdict is one write of at most 512 bytes, the smallest `PIPE_BUF` POSIX permits, so packages running concurrently under `pnpm --recursive` cannot interleave within a line. A line longer than that is cut and marked with `…`; nothing nmr reports today comes near it.
+**nmr reports a workspace that does not contain any package as one of four conditions.** `pnpm-workspace.yaml` may lack a positive pattern, declare patterns that do not match any directory containing a `package.json`, declare `!` exclusions that remove every directory matched by the positive patterns, or not contain valid YAML at all. Each refusal names its own condition and states a remedy, and each quotes the `packages` list that the manifest declares, apart from the last, whose manifest nmr could not read. The second is the likeliest, because nmr [counts a directory as a package](workspace.md) only if it contains `package.json` and recognizes neither `package.yaml` nor `package.json5`.
+
+**A `-R` that nmr composed into a script is not a fan-out that the caller asked for.** In a workspace that does not contain any package, such a step -- in nmr's own default script or in a repo override alike -- is dropped from the chain, the steps beside it run, and the dropped step reports nothing of its own, as the rule above gives a `-R` invocation whose scopes report instead. When the drop leaves the command without any step at all, as it does the root `build`, the command reports a no-op naming the workspace. A repo that does not contain any workspace package therefore runs the default root commands without any entry in `.config/nmr.config.ts`.
+
+A verdict is one write of at most 512 bytes, the smallest `PIPE_BUF` that POSIX permits, so packages running concurrently under `pnpm --recursive` cannot interleave within a line. A line longer than that is cut and marked with `…`; nothing nmr reports today comes near it.
 
 ## Reporting for a machine
 
-`--json` renders each verdict as a JSON object instead of a line of prose — one object per line, newline-delimited, with no enclosing array and no separators between them. A consumer parses each line as it arrives, and a run cut off partway still leaves every line it already emitted parseable, which an enclosing array would not.
+`--json` renders each verdict as a JSON object instead of a line of prose: one object per line, newline-delimited, without an enclosing array or separators between them. A consumer parses each line as it arrives, and a run cut off partway still leaves every line that it already emitted parseable, which an enclosing array would not.
 
 ```console
 $ nmr --json check
@@ -25,80 +29,80 @@ $ nmr --json check
 {"command":"check","scope":"nmr-core","outcome":"passed","durationMs":31204}
 ```
 
-Every object carries `command`, `scope`, and `outcome`, and then what that outcome carries and no other does:
+Every object contains `command`, `scope`, and `outcome`, and then the fields that only that outcome includes:
 
-| `outcome`  | Also carries                                                                                                             |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `passed`   | `durationMs`                                                                                                             |
-| `failed`   | `durationMs`, `exitCode`                                                                                                 |
-| `recalled` | `ageMs`, `savedMs`, and `replay` where the skip has excerpts to [replay](check-cache.md#replaying-a-skipped-runs-output) |
-| `no-op`    | `reason`, either `empty-override` or `noop-override`                                                                     |
+| `outcome`  | Also contains                                                                                                           |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `passed`   | `durationMs`                                                                                                            |
+| `failed`   | `durationMs`, `exitCode`                                                                                                |
+| `recalled` | `ageMs`, `savedMs`, and `replay` when the skip has excerpts to [replay](check-cache.md#replaying-a-skipped-runs-output) |
+| `no-op`    | `reason`, one of `empty-override`, `empty-workspace`, or `noop-override`                                                |
 
-Both renderings are produced from one record, so neither reports what the other does not. Where the prose line makes a presentation decision the record does not — a saving too small to be worth a clause, say — the object carries the fact and leaves the decision to whoever reads it.
+Both renderings are produced from one record, so neither reports what the other does not. When the prose line makes a presentation decision that the record does not (a saving too small to be worth a clause, for example), the object contains the fact and leaves the decision to whoever reads it.
 
-**An object is one write of at most 512 bytes**, the [same ceiling](#what-nmr-reports) a prose line is held to, so packages running concurrently under `pnpm --recursive` cannot interleave within one. Cuts land inside the record's text rather than across its structure, so the line still parses, and a record that overruns is fitted by rungs — each shedding what a reader can better spare than the one below it:
+**An object is one write of at most 512 bytes**, the [same ceiling](#what-nmr-reports) to which a prose line is held. Packages running concurrently under `pnpm --recursive` cannot interleave within one. Because nmr cuts inside the record's text rather than across its structure, the line still parses. nmr fits a record that overruns by rungs, each dropping what a reader can spare more easily than what the rung below it drops:
 
-1. **The excerpts are shortened toward one another**, so an assembly's constituents come down together rather than the first ones being emptied to leave the last whole. No excerpt is cut below `…`, which keeps a cut one distinguishable from a run that recorded nothing.
-2. **The excerpts go**, leaving the `scope` and `command` that name each constituent. An entry carrying no `excerpt` key is one whose text did not fit.
+1. **The excerpts are shortened toward one another**, so an assembly's constituents shrink together rather than the first ones being emptied to leave the last whole. nmr does not cut any excerpt below `…`, which keeps a cut one distinguishable from a run that recorded nothing.
+2. **The excerpts go**, leaving the `scope` and `command` that name each constituent. An entry without an `excerpt` key is one whose text did not fit.
 3. **The trailing constituents go**, as the prose line drops its own tail, and the `replay` array itself once none fit.
-4. **The `scope` and `command` are cut**, each marked. This is the last resort and the reason for it is the ceiling itself: a line that overruns can be split across a pipe and corrupt the records of every scope sharing it, where a marked cut costs only its own.
+4. **The `scope` and `command` are cut**, each marked. This is the last resort and the reason for it is the ceiling itself: A line that overruns can be split across a pipe and corrupt the records of every scope sharing it, whereas a marked cut damages only its own.
 
-A package-scoped `check` carries four constituents and fits uncut. A four-package root `check` assembles twelve — `typecheck` and `test` each fan out to every package, and a nested composite's list is spliced in flat — which is more than the ceiling can name: it reaches rung 3, keeping eight and dropping the trailing four. Rung 4 needs a scope and command running to hundreds of bytes between them.
+A package-scoped `check` has four constituents and fits uncut. A four-package root `check` assembles twelve (`typecheck` and `test` each fan out to every package, and a nested composite's list is spliced in flat), which is more than the ceiling can name: It reaches rung 3, keeping eight and dropping the trailing four. Rung 4 needs a scope and command running to hundreds of bytes between them.
 
-**The mode implies quiet.** The commands' own output is withheld, so stdout carries the objects alone — no prose verdict, and no override notice. `NMR_COMMAND_VERBOSITY=full` does not opt back out. A failure still surrenders the failing command's output, on stderr, as under any quiet run. Both modes leave a command on the same channels, so a machine-readable run and a quiet one share a [retention key](check-cache.md#replaying-a-skipped-runs-output): each replays what the other recorded.
+**The mode implies quiet.** The commands' own output is withheld, so stdout contains the objects alone, without a prose verdict or an override notice. `NMR_COMMAND_VERBOSITY=full` does not opt back out. On a failure, nmr still prints the failing command's output on stderr, as under any quiet run. Because both modes leave a command on the same channels, a machine-readable run and a quiet one share a [retention key](check-cache.md#replaying-a-skipped-runs-output): Each replays what the other recorded.
 
-The format is nmr's own reporting and not a mode the commands it runs are told about, so it is out of the [pass key](check-cache.md#what-the-key-is-made-of) and the retention key alike. Selecting it neither invalidates a recorded pass nor costs a replay.
+Because the format is nmr's own reporting, and nmr does not tell the commands that it runs about it, the format is out of the [pass key](check-cache.md#what-the-key-is-made-of) and the retention key alike. Selecting it neither invalidates a recorded pass nor prevents a replay.
 
-`--log`, `--help`, and `--version` are unaffected: none of them reports a verdict, and what `--log` prints is a tool's own transcript, which has no rendering as a record.
+`--log`, `--help`, and `--version` are unaffected: None of them reports a verdict, and what `--log` prints is a tool's own transcript, which cannot be rendered as a record.
 
 ## Reserved environment variables
 
-`NMR_COMMAND_VERBOSITY` is nmr's own, and carries how loudly a run reports the output of the commands it runs. Its values are `full` and `quiet`; any other non-empty value is reported and exits 1, rather than falling back to a mode nobody chose, and an empty value reads as unset. Each process in a chain suppresses the output of the command it runs rather than of everything below it, so a failure still surrenders the failing command's output. It governs those commands' output alone: nmr's [verdicts](#what-nmr-reports) print in every verbosity, and the override notice is the one message a quiet run withholds.
+`NMR_COMMAND_VERBOSITY` is nmr's own, and sets how loudly a run reports the output of the commands that it runs. Its values are `full` and `quiet`; nmr reports any other non-empty value and exits 1, rather than falling back to a mode that nobody chose, and an empty value reads as unset. Each process in a chain suppresses the output of the command that it runs rather than of everything below it, so the failing command's output still prints on a failure. It governs those commands' output alone: nmr's [verdicts](#what-nmr-reports) print in every verbosity, and the override notice is the one message that a quiet run withholds.
 
-`-q` sets it for the run and outranks an inherited value. Both values are spelled out so either direction is expressible: export `NMR_COMMAND_VERBOSITY=quiet` for a quiet shell, and set `full` on one invocation to opt back out.
+`nmr -q <command>` sets it for the run and outranks an inherited value. Both values are spelled out so that either direction is expressible: Export `NMR_COMMAND_VERBOSITY=quiet` for a quiet shell, and set `full` on one invocation to opt back out.
 
-`NMR_OUTPUT_STYLE` is nmr's own as well, and carries the style every marker nmr prints is rendered in; see [output style](#output-style) below.
+`NMR_OUTPUT_STYLE` is nmr's own as well, and sets the style in which nmr renders every marker that it prints; see [output style](#output-style) below.
 
-`NMR_REPORT_FORMAT` is nmr's own as well, and carries how nmr renders its own verdicts. Its values are `text` and `json`; any other non-empty value is reported and exits 1, and an empty value reads as unset. `--json` sets it for the run and outranks an inherited value, and both values are spelled out so either direction is expressible: export `NMR_REPORT_FORMAT=json` for a shell whose consumer parses, and set `text` on one invocation to opt back out. Two sources, then, where a verbosity has four: no repo-level default and no harness detection, since detection would hand every agent JSON in place of the prose the [shipped guidance](../README.md#agent-guidance) teaches. See [reporting for a machine](#reporting-for-a-machine) for what the objects carry.
+`NMR_REPORT_FORMAT` is nmr's own as well, and sets how nmr renders its own verdicts. Its values are `text` and `json`; nmr reports any other non-empty value and exits 1, and an empty value reads as unset. `--json` sets it for the run and outranks an inherited value, and both values are spelled out so that either direction is expressible: Export `NMR_REPORT_FORMAT=json` for a shell whose consumer parses, and set `text` on one invocation to opt back out. The format has two sources, then, whereas a verbosity has four: It does not have a repo-level default or harness detection, because detection would hand every agent JSON in place of the prose that the [bundled guidance](../README.md#agent-guidance) teaches. See [reporting for a machine](#reporting-for-a-machine) for what the objects contain.
 
 ### Output style
 
-`--output-style <auto|plain|rich>` sets the style for one invocation, and `NMR_OUTPUT_STYLE` sets it for a shell: `rich` marks each verdict with an emoji, such as ✅ or ❌, and `plain` prints a word in its place, such as `PASS` or `FAIL`, which a reader of a log can search for. `auto`, the default, defers to detection. Any other value is a usage error that exits with code 1, whichever source named it. The flag outranks the variable, and both name `auto` as well as a style, so a shell exporting one style is overridable on one invocation in either direction.
+`--output-style <auto|plain|rich>` sets the style for one invocation, and `NMR_OUTPUT_STYLE` sets it for a shell: `rich` marks each verdict with an emoji, such as ✅ or ❌, and `plain` prints a word in its place, such as `PASS` or `FAIL`, which a reader of a log can search for. `auto`, the default, defers to detection. Any other value is a usage error, and nmr exits with code 1, whichever source named it. The flag outranks the variable, and both accept `auto` as well as a style, so a shell exporting one style is overridable on one invocation in either direction.
 
-Detection decides stdout and stderr separately. A stream is plain when `CI` is set to anything other than an empty string or `false`, when the stream is not a terminal, or when `TERM` is `linux`; otherwise it is rich. `--json` output carries no marker in either style.
+Detection decides stdout and stderr separately. A stream is plain when `CI` is set to anything other than an empty string or `false`, when the stream is not a terminal, or when `TERM` is `linux`; otherwise it is rich. `--json` output does not contain a marker in either style.
 
-**The flag belongs to `nmr`.** A standalone bin -- `nmr-clean`, `nmr-compile`, `nmr-report-catalog`, `nmr-report-overrides`, `nmr-ensure-prepublish-hooks` -- takes the variable alone, and passing it the flag gets that bin's unknown-option error. `nmr <command>` exports the style it resolved, so a bin run through nmr renders as nmr does.
+**The flag belongs to `nmr`.** A standalone bin -- `nmr-clean`, `nmr-compile`, `nmr-report-catalog`, `nmr-report-overrides`, `nmr-ensure-prepublish-hooks` -- takes the variable alone, and passing it the flag produces that bin's unknown-option error. `nmr <command>` exports the style that it resolved, so a bin run through nmr renders as nmr does.
 
-**A nested run follows the one that spawned it.** The resolved style, never `auto`, travels down as `NMR_OUTPUT_STYLE`, so a child whose own stdout is a pipe still renders rich where the parent resolved rich. The style exported is the one stdout resolved to, which is where the verdicts and nearly every other line go; a parent at a terminal whose stderr alone is redirected therefore hands its children `rich`.
+**A nested run follows the one that spawned it.** Because nmr passes the resolved style, never `auto`, down as `NMR_OUTPUT_STYLE`, a child whose own stdout is a pipe still renders rich when the parent resolved rich. The exported style is the one to which stdout resolved, and stdout receives the verdicts and nearly every other line; a parent at a terminal whose stderr alone is redirected therefore hands its children `rich`.
 
-The style is out of the [pass key](check-cache.md#what-the-key-is-made-of) and the [retention key](check-cache.md#replaying-a-skipped-runs-output) alike, as the verbosity is: it changes how a run renders and never what a command concludes. Selecting it neither invalidates a recorded pass nor costs a replay, and an excerpt recorded rich replays as recorded in a plain run.
+The style is out of the [pass key](check-cache.md#what-the-key-is-made-of) and the [retention key](check-cache.md#replaying-a-skipped-runs-output) alike, as the verbosity is: It changes how a run renders and never what a command concludes. Selecting it neither invalidates a recorded pass nor prevents a replay, and an excerpt recorded rich replays as recorded in a plain run.
 
 ### Where a verbosity comes from
 
-Four sources, in precedence order. Each is read once, at the top of a chain: the resolved value travels down as `NMR_COMMAND_VERBOSITY`, so a nested process reads a decision already made rather than making its own.
+Four sources, in precedence order. Each is read once, at the top of a chain: nmr passes the resolved value down as `NMR_COMMAND_VERBOSITY`, so a nested process reads a decision already made rather than making its own.
 
-| Source                                                | Set it when                                                |
-| ----------------------------------------------------- | ---------------------------------------------------------- |
-| `-q`                                                  | One invocation should be quiet.                            |
-| `NMR_COMMAND_VERBOSITY`                               | A shell, or a harness that launches one, should be quiet.  |
-| `output.commandVerbosity` in the monorepo-root config | A repo should be quiet for everyone working in it.         |
-| An agent harness nmr recognizes in the environment    | Nothing above applies and an agent is running the command. |
+| Source                                                  | Set it when                                                |
+| ------------------------------------------------------- | ---------------------------------------------------------- |
+| `nmr -q <command>`                                      | One invocation should be quiet.                            |
+| `NMR_COMMAND_VERBOSITY`                                 | A shell, or a harness that launches one, should be quiet.  |
+| `output.commandVerbosity` in the monorepo-root config   | A repo should be quiet for everyone working in it.         |
+| An agent harness that nmr recognizes in the environment | Nothing above applies and an agent is running the command. |
 
-Falling off the bottom leaves the run `full`, which is what an unrecognized harness gets: detection adds quiet where it fires and changes nothing where it does not.
+Below the last source, a run is `full`, which is what an unrecognized harness gets: Detection adds quiet when it fires and changes nothing when it does not.
 
-Detection reads a set of environment-variable names and fires on any one of them holding a non-empty value. The shipped set is `CLAUDECODE`, `ROVODEV_CLI`, and `ROVO_CLI`. **Treat that set as perishable.** The names belong to ecosystems nmr does not control and that rename, and a rename fails silently here, since the symptom is a return to loud output rather than an error. `output.extraAgentEnvVars` is how a repo adds a name — a harness nmr has never heard of, or one whose marker was renamed after the installed version shipped — without waiting for a release. A repo that wants no detection at all configures `output.commandVerbosity: 'full'`, which outranks it.
+Detection reads a set of environment-variable names and fires on any one of them holding a non-empty value. The bundled set is `CLAUDECODE`, `ROVODEV_CLI`, and `ROVO_CLI`. **Expect that set to change.** The names belong to ecosystems that nmr does not control and that rename them, and a rename fails silently here, since the symptom is a return to loud output rather than an error. A repo adds a name with `output.extraAgentEnvVars` (for a harness unknown to nmr, or one whose marker was renamed after the installed version was released) without waiting for a release. A repo that does not want any detection at all configures `output.commandVerbosity: 'full'`, which outranks it.
 
 ## Configuring
 
 ```ts
 export default defineConfig({
   output: {
-    // The verbosity a run takes when neither `-q` nor the environment named one.
+    // The verbosity that a run takes when neither `-q` nor the environment named one.
     commandVerbosity: 'quiet',
-    // Markers of a harness the shipped set does not name, added to it rather than replacing it.
+    // Markers of a harness that the bundled set does not name, added to it rather than replacing it.
     extraAgentEnvVars: ['MY_HARNESS'],
   },
 });
 ```
 
-`output` is a monorepo-root key, and both of its fields feed the [verbosity ladder](#where-a-verbosity-comes-from).
+`output` is a monorepo-root key, and both of its fields are inputs to the [verbosity ladder](#where-a-verbosity-comes-from).