@williamthorsen/nmr 1.0.0 → 2.0.0

package/.meta/changelog.json

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "2.0.0",
+    "date": "2026-11-10",
+    "sections": [
+      {
+        "title": "🪦 Removed",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Removes the `devBin` root-config field of `@williamthorsen/nmr`, which replaced the first token of a resolved command with a command that ran a bin from source. (#1269)",
+            "breaking": true,
+            "migration": "Replace each `devBin` entry by overriding the script that runs the bin in `rootScripts` or `workspaceScripts` with `node <path to the bin's source>`, and build an absolute path for a workspace script, because nmr no longer resolves relative paths from the monorepo root and a workspace script runs in each package's directory; a `package.json` script that runs the bin outranks the config, so change it in that `package.json`.",
+            "hash": "5a95865afe2560a4bb9e3f66448bd68f6a32c312",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "♻️ Refactoring",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Move the duplicated output-style resolver into nmr-core's cli entry (#1248)",
+            "body": "Replaces the duplicate `resolveStyles` modules in `release-kit` and `v11y-check` with one `resolveCliStyles` function, exported from `@williamthorsen/nmr-core/cli`. Each package still reads its own `RELEASE_KIT_OUTPUT_STYLE` or `V11Y_CHECK_OUTPUT_STYLE` variable and still reports a usage error for a value other than `auto`, `plain`, or `rich`.",
+            "hash": "c5f4ac68360ce550a7e53006a2a633b79f179f5f"
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "1.0.0",
     "date": "2026-11-08",

package/.readyup/kits/default.js

@@ -8733,11 +8733,6 @@ function readPackageScripts(packageDir) {
   }
 }
 
-// src/helpers/type-guards.ts
-function isStringRecord(value) {
-  return isRecord2(value) && Object.values(value).every((entry) => typeof entry === "string");
-}
-
 // src/verbosity.ts
 var COMMAND_VERBOSITIES = ["full", "quiet"];
 function formatVerbosityRejection(source, value) {
@@ -8752,7 +8747,7 @@ function isCommandVerbosity(value) {
 var CONFIG_TIERS = {
   root: {
     label: "a monorepo-root config",
-    honoredKeys: ["checkCache", "delegate", "devBin", "output", "rootScripts", "selfHostedRunner", "workspaceScripts"],
+    honoredKeys: ["checkCache", "delegate", "output", "rootScripts", "selfHostedRunner", "workspaceScripts"],
     elsewhere: "the package's own config"
   },
   workspace: {
@@ -8788,8 +8783,6 @@ function validateConfig(value, configPath, baseDir) {
   const checkCache = validateCheckCacheField(value, configPath);
   if (checkCache) config.checkCache = checkCache;
   if (value["delegate"] !== void 0) config.delegate = validateDelegateField(value["delegate"], configPath);
-  const devBin = validateStringRecordField(value, "devBin", configPath);
-  if (devBin) config.devBin = devBin;
   const output = validateOutputField(value, configPath);
   if (output) config.output = output;
   const workspaceScripts2 = validateScriptField(value, "workspaceScripts", configPath);
@@ -8960,15 +8953,6 @@ function validateScriptField(value, fieldName, configPath) {
   assertValidElements(scripts, fieldName, configPath);
   return scripts;
 }
-function validateStringRecordField(value, fieldName, configPath) {
-  if (!Object.hasOwn(value, fieldName) || value[fieldName] === void 0) {
-    return void 0;
-  }
-  if (!isStringRecord(value[fieldName])) {
-    throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string>`);
-  }
-  return value[fieldName];
-}
 
 // src/helpers/escapeControlCharacters.ts
 var NAMED_ESCAPES = /* @__PURE__ */ new Map([
@@ -9611,7 +9595,7 @@ function hasSupportedStrictLintVersion() {
   });
 }
 function getMinVersion() {
-  const pickedFields = { "version": "1.0.0" };
+  const pickedFields = { "version": "2.0.0" };
   if (typeof pickedFields["version"] !== "string") {
     throw new TypeError("nmr/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -32,7 +32,7 @@
           "checklist": "nmr",
           "checks": [
             "@williamthorsen/nmr in devDependencies",
-            "@williamthorsen/nmr >= 1.0.0",
+            "@williamthorsen/nmr >= 2.0.0",
             "pnpm-workspace.yaml exists",
             "catalogued dependencies use catalog:",
             "package.json has packageManager field",
@@ -86,7 +86,7 @@
           "path": "../../nmr-core/dist/esm/cache/cache-store.js"
         },
         {
-          "hash": "d2edf9e9",
+          "hash": "6ea2c3c0",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/cli.js"
         },
@@ -236,7 +236,7 @@
           "path": "lib/workspace-build.ts"
         },
         {
-          "hash": "2afa0f3c",
+          "hash": "6933f29e",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -254,12 +254,12 @@
           "path": "../src/config-check-cache.ts"
         },
         {
-          "hash": "378fb666",
+          "hash": "d25aef4f",
           "kind": "module",
           "path": "../src/config-validation.ts"
         },
         {
-          "hash": "8cb3c082",
+          "hash": "d345a285",
           "kind": "module",
           "path": "../src/config.ts"
         },
@@ -308,11 +308,6 @@
           "kind": "module",
           "path": "../src/helpers/reportClosing.ts"
         },
-        {
-          "hash": "3f8448c9",
-          "kind": "module",
-          "path": "../src/helpers/type-guards.ts"
-        },
         {
           "hash": "77f6bb50",
           "kind": "module",
@@ -324,7 +319,7 @@
           "path": "../src/resolve-scripts.ts"
         },
         {
-          "hash": "5112becc",
+          "hash": "0112952e",
           "kind": "module",
           "path": "../src/resolver.ts"
         },
@@ -364,7 +359,7 @@
       "readyupVersion": "0.45.0",
       "source": "kits/default.ts",
       "sourceHash": "9fd61bf4",
-      "targetHash": "5818d99b"
+      "targetHash": "7ddb0518"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## 2.0.0 — 2026-11-10
+
+### 🪦 Removed
+
+- 🚨 **Breaking:** Removes the `devBin` root-config field of `@williamthorsen/nmr`, which replaced the first token of a resolved command with a command that ran a bin from source. (#1269)
+
+### ♻️ Refactoring
+
+- Move the duplicated output-style resolver into nmr-core's cli entry (#1248)
+
+  Replaces the duplicate `resolveStyles` modules in `release-kit` and `v11y-check` with one `resolveCliStyles` function, exported from `@williamthorsen/nmr-core/cli`. Each package still reads its own `RELEASE_KIT_OUTPUT_STYLE` or `V11Y_CHECK_OUTPUT_STYLE` variable and still reports a usage error for a value other than `auto`, `plain`, or `rich`.
+
 ## 1.0.0 — 2026-11-08
 
 ### 🧪 Tests

package/README.md

@@ -4,7 +4,13 @@
 
 Context-aware script runner for pnpm monorepos. Includes an `nmr` (node-monorepo run) binary that provides centralized, consistent script execution across workspace packages and the monorepo root.
 
-<!-- section:release-notes --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v2.0.0 (2026-11-10)
+
+### 🪦 Removed
+
+- 🚨 **Breaking:** Removes the `devBin` root-config field of `@williamthorsen/nmr`, which replaced the first token of a resolved command with a command that ran a bin from source. (#1269)
+<!-- /section:release-notes -->
 
 ## Installation
 
@@ -141,7 +147,7 @@ export default defineConfig({
 });
 ```
 
-[Scripts and configuration](docs/scripts.md#configuration) lists every `defineConfig` field and covers package-level configuration and `devBin`.
+[Scripts and configuration](docs/scripts.md#configuration) lists every `defineConfig` field, covers package-level configuration, and shows how to run a workspace bin from source.
 
 ## What nmr reports
 
@@ -304,7 +310,7 @@ rdy list --from npm:@williamthorsen/nmr  # what nmr publishes
 
 ## Documentation
 
-- [Scripts and configuration](docs/scripts.md): Override tiers, script values, hooks, `defineConfig` fields, `devBin`, and the default commands
+- [Scripts and configuration](docs/scripts.md): Override tiers, script values, hooks, `defineConfig` fields, running a workspace bin from source, and the default commands
 - [What nmr reports](docs/reporting.md): Verdicts, `--json`, output style, and verbosity
 - [Check-result cache](docs/check-cache.md): What is skipped, what a hit requires, and replaying, reading, and bypassing recorded runs
 - [Machine lock](docs/machine-lock.md): Which commands wait for one another, where the lock lives, and bypassing it

package/dist/esm/check-cache-gate.d.ts

@@ -25,8 +25,6 @@ export declare function openGate(options: {
 }): TreeSnapshot | undefined;
 /**
  * Computes the key under which this invocation would be recorded, or `undefined` when the cache does not apply.
- * The cache does not apply to a `devBin` substitution: the substitute is built from a location that the tree id
- * does not describe, so a pass by it is not a pass by the command that the key names.
  */
 export declare function resolveCacheKey(options: {
     anchorDir: string;
@@ -36,7 +34,6 @@ export declare function resolveCacheKey(options: {
     monorepoRoot: string;
     snapshot: TreeSnapshot | undefined;
     stderr: Writable;
-    substitution: string | undefined;
 }): string | undefined;
 /**
  * Runs the resolved steps behind the check-result cache: skips them when a recorded pass covers this

package/dist/esm/check-cache-gate.js

@@ -33,14 +33,10 @@ export function openGate(options) {
     return snapshot.snapshot;
 }
 export function resolveCacheKey(options) {
-    const { env, snapshot, stderr, substitution } = options;
+    const { env, snapshot, stderr } = options;
     if (snapshot === undefined) {
         return undefined;
     }
-    if (substitution !== undefined) {
-        writeDebugNote(`gate disabled: devBin substituted \`${substitution}\``, env, stderr);
-        return undefined;
-    }
     const result = computeCacheKey({
         anchorDir: options.anchorDir,
         command: options.command,

package/dist/esm/commands/clean.js

@@ -8,7 +8,7 @@ import { findContainingPackageDir } from "../context.js";
 import { NMR_GLYPHS } from "../glyphs.js";
 import { reportClosing } from "../helpers/reportClosing.js";
 import { resolveChannel } from "../output-channel.js";
-import { applyDevBin, buildWorkspaceRegistry, resolveScript } from "../resolver.js";
+import { buildWorkspaceRegistry, resolveScript } from "../resolver.js";
 import { runCommand } from "../runner.js";
 import { renderChain } from "../steps.js";
 import { findMonorepoRoot, getWorkspacePackageDirs } from "../workspace.js";
@@ -67,13 +67,12 @@ async function sweepWorkspace(monorepoRoot, workspacePackageDirs, style) {
             cleanedCount++;
             continue;
         }
-        const command = applyDevBin(resolvedCommand, config.devBin, monorepoRoot);
-        const { exitCode } = await runCommand(command, packageDir, {
+        const { exitCode } = await runCommand(resolvedCommand, packageDir, {
             bin: NMR_CLEAN_BIN,
             channels: { stderr: resolveChannel(process.stderr, false), stdout: resolveChannel(process.stdout, false) },
         });
         if (exitCode !== 0) {
-            throw new UserError(`\`${command}\` failed in ${path.basename(packageDir)} with exit code ${exitCode}.`);
+            throw new UserError(`\`${resolvedCommand}\` failed in ${path.basename(packageDir)} with exit code ${exitCode}.`);
         }
         cleanedCount++;
     }

package/dist/esm/config-validation.js

@@ -1,12 +1,11 @@
 import { isRecord, UserError } from '@williamthorsen/nmr-core';
 import { assertResolvableCheckCacheCommands } from "./config-check-cache.js";
-import { isStringRecord } from "./helpers/type-guards.js";
 import { findUnexpressibleToken } from "./steps.js";
 import { formatVerbosityRejection, isCommandVerbosity } from "./verbosity.js";
 export const CONFIG_TIERS = {
     root: {
         label: 'a monorepo-root config',
-        honoredKeys: ['checkCache', 'delegate', 'devBin', 'output', 'rootScripts', 'selfHostedRunner', 'workspaceScripts'],
+        honoredKeys: ['checkCache', 'delegate', 'output', 'rootScripts', 'selfHostedRunner', 'workspaceScripts'],
         elsewhere: "the package's own config",
     },
     workspace: {
@@ -44,9 +43,6 @@ export function validateConfig(value, configPath, baseDir) {
         config.checkCache = checkCache;
     if (value['delegate'] !== undefined)
         config.delegate = validateDelegateField(value['delegate'], configPath);
-    const devBin = validateStringRecordField(value, 'devBin', configPath);
-    if (devBin)
-        config.devBin = devBin;
     const output = validateOutputField(value, configPath);
     if (output)
         config.output = output;
@@ -225,12 +221,3 @@ function validateScriptField(value, fieldName, configPath) {
     assertValidElements(scripts, fieldName, configPath);
     return scripts;
 }
-function validateStringRecordField(value, fieldName, configPath) {
-    if (!Object.hasOwn(value, fieldName) || value[fieldName] === undefined) {
-        return undefined;
-    }
-    if (!isStringRecord(value[fieldName])) {
-        throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string>`);
-    }
-    return value[fieldName];
-}

package/dist/esm/config.d.ts

@@ -6,7 +6,7 @@ import type { NmrConfig } from './types.js';
  */
 export declare function loadConfig(baseDir: string): Promise<NmrConfig>;
 /**
- * Loads the monorepo-root `.config/nmr.config.ts`, the tier that feeds script resolution and `devBin`.
+ * Loads the monorepo-root `.config/nmr.config.ts`, the tier that feeds script resolution.
  * Returns an empty config if the file doesn't exist.
  *
  * Throws on a recognized key that this tier does not honor. `build` governs one package's compile, which reads the

package/dist/esm/crossing-diagnostics.d.ts

@@ -24,7 +24,7 @@ export declare function assertNoSelfReference(options: {
  *
  * Ahead of the gate, so that a command that usually skips still reports its crossing. A `--log` reports
  * none, running nothing that could cross. Reads the resolved steps rather than the full chain: the line names
- * a declaration to edit, and a hook, a passthrough, and a `devBin` substitution are none.
+ * a declaration to edit, and neither a hook nor a passthrough is one.
  */
 export declare function reportNmrCrossing(options: {
     config: NmrConfig;

package/dist/esm/resolver.d.ts

@@ -1,18 +1,6 @@
 import { type ScriptRegistry, type ScriptValue } from './resolve-scripts.js';
 import { type Step } from './steps.js';
 import type { NmrConfig } from './types.js';
-/**
- * Replaces the first token of a command with a `devBin` substitute.
- * Relative paths in the replacement are resolved from `monorepoRoot`.
- */
-export declare function applyDevBin(command: string, devBin: Record<string, string> | undefined, monorepoRoot: string): string;
-/**
- * Applies a `devBin` substitution to each opaque step, leaving nmr's own compositions alone.
- *
- * A structural step names a command that nmr resolves for itself, so substituting its first token would replace
- * the `nmr` that runs the composite rather than the leaf tool that `devBin` documents replacing.
- */
-export declare function applyDevBinToSteps(steps: readonly Step[], devBin: Record<string, string> | undefined, monorepoRoot: string): readonly Step[];
 /**
  * Where a resolved script was read from.
  *

package/dist/esm/resolver.js

@@ -1,44 +1,9 @@
 import { readFileSync } from 'node:fs';
-import path from 'node:path';
 import { hasErrnoCode, isRecord } from '@williamthorsen/nmr-core';
 import { parsePackageJson, readScriptRecord, resolvePackageJsonPath } from "./helpers/package-json.js";
 import { getDefaultRootScripts, getDefaultWorkspaceScripts, } from "./resolve-scripts.js";
 import { composeNmrStep, readSelfReference } from "./steps.js";
 import { isMonorepoRoot } from "./workspace.js";
-export function applyDevBin(command, devBin, monorepoRoot) {
-    if (!devBin) {
-        return command;
-    }
-    const spaceIndex = command.indexOf(' ');
-    const firstToken = spaceIndex === -1 ? command : command.slice(0, spaceIndex);
-    const restOfCommand = spaceIndex === -1 ? '' : command.slice(spaceIndex);
-    const replacement = devBin[firstToken];
-    if (replacement === undefined) {
-        return command;
-    }
-    const resolvedReplacement = resolveReplacementPaths(replacement, monorepoRoot);
-    return resolvedReplacement + restOfCommand;
-}
-export function applyDevBinToSteps(steps, devBin, monorepoRoot) {
-    if (!devBin) {
-        return steps;
-    }
-    return steps.map((step) => step.kind === 'opaque' ? { kind: 'opaque', command: applyDevBin(step.command, devBin, monorepoRoot) } : step);
-}
-function resolveReplacementPaths(replacement, monorepoRoot) {
-    const tokens = replacement.split(' ');
-    return tokens
-        .map((token, index) => {
-        if (index === 0)
-            return token;
-        if (token.startsWith('-'))
-            return token;
-        if (!token.includes('/'))
-            return token;
-        return path.resolve(monorepoRoot, token);
-    })
-        .join(' ');
-}
 export function expandScript(script, isWorkspaceRoot) {
     if (typeof script === 'string') {
         return [{ kind: 'opaque', command: script }];

package/dist/esm/run-chain.d.ts

@@ -2,7 +2,7 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
 import type { TreeSnapshot } from './check-cache.js';
 import { type Invocation, type PhaseResult, type RunPlan } from './invocation.js';
 import type { ScriptRegistry } from './resolve-scripts.js';
-import { type ResolvedScript } from './resolver.js';
+import type { ResolvedScript } from './resolver.js';
 /**
  * Assembles the chain that a resolved script runs at this scope, the hooks wrapped around it included, and the key
  * under which a pass by that chain is recorded. Settles a no-op override and an argument that no step can take.

package/dist/esm/run-chain.js

@@ -9,7 +9,6 @@ import { quoteForShell } from "./helpers/quoteForShell.js";
 import { wrapWithHooks } from "./hooks.js";
 import { USAGE_EXIT_CODE } from "./invocation.js";
 import { reportVerdict } from "./presentation.js";
-import { applyDevBinToSteps } from "./resolver.js";
 import { dropRecursiveSteps, renderChain } from "./steps.js";
 export function assembleChain(options) {
     const { invocation, registry, resolvedScript, snapshot } = options;
@@ -21,9 +20,7 @@ export function assembleChain(options) {
         reportVerdict({ command, scope: invocation.scope, outcome: 'no-op', reason: noOpReason }, stdout, invocation.format, styles.stdout);
         return { settled: true, result: { exitCode: 0 } };
     }
-    const substitutedSteps = applyDevBinToSteps(runnableSteps, context.config.devBin, context.monorepoRoot);
-    const substitutedCommand = renderChain(substitutedSteps);
-    const bindResult = bindPassthrough(substitutedSteps, parsedArgs.passthrough, command);
+    const bindResult = bindPassthrough(runnableSteps, parsedArgs.passthrough, command);
     if (!bindResult.ok) {
         reportError(NMR_BIN, bindResult.error, stderr);
         return { settled: true, result: { exitCode: USAGE_EXIT_CODE } };
@@ -53,7 +50,6 @@ export function assembleChain(options) {
         monorepoRoot: context.monorepoRoot,
         snapshot,
         stderr,
-        substitution: substitutedCommand === resolvedCommand ? undefined : substitutedCommand,
     });
     return { settled: false, value: { commandString: fullCommand, key, ownSteps: mainSteps, steps: fullSteps } };
 }

package/dist/esm/types.d.ts

@@ -59,7 +59,6 @@ export interface NmrConfig {
      * config says. A delegation flag still sends a run elsewhere.
      */
     delegate?: false;
-    devBin?: Record<string, string>;
     output?: OutputConfig;
     workspaceScripts?: Record<string, ScriptValue>;
     rootScripts?: Record<string, ScriptValue>;

package/docs/check-cache.md

@@ -63,7 +63,6 @@ The gate never wrongly skips. When it cannot be sure, it does nothing and the co
 - When the monorepo root is not the git toplevel.
 - When a changed path cannot be read, contains a newline or bytes that are not UTF-8, or is neither a file nor a symlink (an untracked nested repository, for instance).
 - 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 tree id 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 cache did not apply.

package/docs/scripts.md

@@ -79,7 +79,7 @@ The line names the declaration to which it is an edit (the file, the field, and
 
 One kind of `package.json` entry is resolved in its own file: an entry whose whole value is `nmr <name>`, without flags, arguments, assignments, or a launcher, where `<name>` is a script in the same `package.json` that runs a command other than nmr and does not have a `:pre` or `:post` hook. Replace the entry's value with that command, and delete the script: `"build:pre": "nmr compile:ports"` beside `"compile:ports": "node scripts/compile-ports.ts"` becomes `"build:pre": "node scripts/compile-ports.ts"`. Keep the script when the registry also defines `<name>`, because the script then overrides nmr's own command. The script must come from the same file: Inlining a command that resolves from the registry would copy nmr's own command text into the package, where nmr's later changes do not reach it.
 
-nmr recognizes `nmr` in command position: at the start of a step, after an unquoted `&&`, `||`, `;`, `|`, or a newline, past any leading `NAME=value` assignments, and behind `npx`, `bunx`, or an `exec`, `dlx`, or `x` subcommand of `npm`, `pnpm`, `yarn`, or `bun`. This line reports a boundary rather than enforcing a rule: It covers a step that nmr runs as written, and only the reporting of the nested run is degraded. The line is also partial in three ways: a value-taking flag standing immediately before the program name hides it (`npx -p foo nmr`), a launcher outside that set goes unreported, and a `devBin` substitution that introduces `nmr` itself is not reported, the line being an edit to a declaration rather than to a substitution.
+nmr recognizes `nmr` in command position: at the start of a step, after an unquoted `&&`, `||`, `;`, `|`, or a newline, past any leading `NAME=value` assignments, and behind `npx`, `bunx`, or an `exec`, `dlx`, or `x` subcommand of `npm`, `pnpm`, `yarn`, or `bun`. This line reports a boundary rather than enforcing a rule: It covers a step that nmr runs as written, and only the reporting of the nested run is degraded. The line is also partial in two ways: a value-taking flag standing immediately before the program name hides it (`npx -p foo nmr`), and a launcher outside that set goes unreported.
 
 A [self-referential entry](#three-tier-override-system), in `package.json` or in `.config/nmr.config.ts`, is the shape that nmr cannot run as written, and it is rejected rather than reported. The same recognition finds it, so the same residuals apply: What goes unrecognized there re-enters nmr once, and the run then fails with an error naming the command and the directory that it re-entered.
 
@@ -125,7 +125,6 @@ A minimal `.config/nmr.config.ts` is in the [README](../README.md#configuration)
 | `delegate`         | `false`                                                                       | Keeps every check on the machine that has the tree, whatever `NMR_DELEGATE` or the [user config](delegate.md#the-user-config) says; a delegation flag still sends a run elsewhere (root config only)                                                                                                                                         |
 | `workspaceScripts` | `Record<string, ScriptValue>`                                                 | Scripts added or overridden in the workspace registry (tier 2)                                                                                                                                                                                                                                                                               |
 | `rootScripts`      | `Record<string, ScriptValue>`                                                 | Scripts added or overridden in the root registry (tier 2)                                                                                                                                                                                                                                                                                    |
-| `devBin`           | `Record<string, string>`                                                      | Map binary names to source-repo replacement commands                                                                                                                                                                                                                                                                                         |
 | `output`           | `{ commandVerbosity?: CommandVerbosity; extraAgentEnvVars?: string[] }`       | How loudly runs report command output; see [configuring](reporting.md#configuring)                                                                                                                                                                                                                                                           |
 | `selfHostedRunner` | `{ exempt: string }`                                                          | Why a qualifying repo keeps CI off the self-hosted runners; stops [nmr's readyup kit](../README.md#conformance-checks) from recommending `CI_RUNS_ON` (root config only). The reason is structural: a circular dependency, a platform or capacity the runners lack, or network reach. A missing tool is installed by a workflow step instead |
 
@@ -135,7 +134,7 @@ Each field belongs to exactly one tier, and nmr loads from a config only the fie
 
 ### Package-level configuration
 
-A package may have its own `.config/nmr.config.ts`, which `nmr-compile` reads from the package that 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 that nothing applied. The monorepo-root config has the mirror restriction: `build` there fails the same way, since only a package's own config affects the compile.
+A package may have its own `.config/nmr.config.ts`, which `nmr-compile` reads from the package that it is compiling. This tier honors `build` alone; declaring `workspaceScripts`, `rootScripts`, or any other root-config field 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 that nothing applied. The monorepo-root config has the mirror restriction: `build` there fails the same way, since only a package's own config affects the compile.
 
 ```ts
 // packages/my-package/.config/nmr.config.ts
@@ -150,23 +149,29 @@ export default defineConfig({
 
 > **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 does not produce a runtime import. `defineConfig` is unavailable at that moment, because it resolves through nmr's build output. Every other config, including every consumer's, imports nmr from an installed tarball that contains `dist`, and can use `defineConfig` freely.
 
-### `devBin`: source-repo binary substitution
+### Running a workspace bin from source
 
-During development of a CLI tool inside the monorepo, the published binary may not reflect the latest source changes. `devBin` maps a binary name to a replacement command that runs from source:
+A script that runs a bin built in this monorepo runs its build output, which can lag the source or be missing before the first build. To run the source instead, override the script whose value runs the bin, and call `node` on the bin's source file: Node runs TypeScript directly.
+
+A resolved script runs in the directory of its scope: A root script runs from the monorepo root, so a path relative to the root works there, and a workspace script runs in each package's directory, so the config builds an absolute path from `import.meta.dirname`, the config's own `.config` directory.
 
 ```ts
+// .config/nmr.config.ts
+import { defineConfig } from '@williamthorsen/nmr/config';
+
+const myCli = `${import.meta.dirname}/../packages/my-cli/src/cli.ts`;
+
 export default defineConfig({
-  devBin: {
-    'my-cli': 'tsx packages/my-cli/src/cli.ts',
+  rootScripts: {
+    'build:post': 'node packages/my-cli/src/cli.ts compile',
+  },
+  workspaceScripts: {
+    lint: `node "${myCli}" lint`,
   },
 });
 ```
 
-When nmr resolves a command whose first token matches a `devBin` key, it replaces that token with the mapped command. Arguments are preserved. Relative paths in the replacement are resolved from the monorepo root.
-
-For example, if a workspace script resolves to `my-cli --verbose`, nmr rewrites it to `tsx /absolute/path/to/packages/my-cli/src/cli.ts --verbose`.
-
-> **Note:** Path resolution uses a heuristic: Any non-flag token containing `/` is treated as a relative path. This works well for typical dev-tool commands but may incorrectly resolve URL-like values or glob patterns. Flags using `--flag=value` syntax are not resolved; use the spaced form `--flag value` for paths that need resolution.
+A package's own `package.json` script outranks the config (tier 3), so a package script that runs the bin is changed in that `package.json`.
 
 ## Default commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -80,7 +80,7 @@
     "!docs/*.v*.md"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.16.0",
+    "@williamthorsen/nmr-core": "0.16.1",
     "@williamthorsen/toolbelt.errors": "0.9.0",
     "@williamthorsen/toolbelt.filesystem": "0.10.0",
     "glob": "14.0.4",