@williamthorsen/nmr 0.25.0 → 0.26.0

package/.readyup/kits/default.js

@@ -40,8 +40,7 @@ var workspaceScripts = {
   "test:unit": "pnpm exec vitest --project unit",
   "test:watch": `pnpm exec vitest ${GATE_PROJECTS} --watch`,
   typecheck: "tsgo --noEmit",
-  // `--include-locked` is required rather than stylistic: a repo that pins exactly (pnpm's
-  // `savePrefix: ''`) has no dependency taze considers unlocked, so without it nothing is reported.
+  // Without `--include-locked`, nothing would be reported in a repo that pins exact version numbers.
   upgrade: "nmr-taze --include-locked",
   "view-coverage": "open coverage/index.html"
 };
@@ -51,21 +50,17 @@ var rootScripts = {
   "audit:prod": "pnpm exec v11y --prod",
   build: "pnpm --recursive exec nmr build",
   check: ["typecheck", "fmt:check", "lint:check", "test"],
-  "check:agent-files": "nmr-sync-agent-files --check",
-  "check:strict": ["typecheck", "fmt:check", "lint:strict", "test:coverage", "check:agent-files"],
-  // Excludes the audit, which has a workflow of its own.
+  "check:strict": ["typecheck", "fmt:check", "lint:strict", "test:coverage"],
+  // Excludes the audit, which in CI has a workflow of its own.
   ci: ["build", "check:strict"],
   clean: "nmr-clean",
   fix: ["lint", "fmt"],
   "fix:check": ["fmt:check", "lint:check"],
-  // Identical to the workspace entries: the bin scopes its own selection to the working directory, so
-  // neither registry needs the `sh -c '… "${@:-.}"' --` wrapper that gave the root form a default path.
   fmt: "nmr-fmt --write",
   "fmt:check": "nmr-fmt --check",
   lint: "nmr root:lint && pnpm --recursive exec nmr lint",
   "lint:check": "nmr root:lint:check && pnpm --recursive exec nmr lint:check",
   "lint:strict": "nmr root:lint:strict && pnpm --recursive exec nmr lint:strict",
-  // Everything the remote runs: the code-quality gate plus the audit workflow.
   prepush: ["ci", "audit"],
   "report-overrides": "nmr-report-overrides",
   "root:check": ["root:typecheck", "fmt:check", "root:lint:check", "root:test"],
@@ -78,23 +73,16 @@ var rootScripts = {
   "root:test:unit": "vitest --config ./vitest.root.config.ts --project unit",
   "root:typecheck": "tsgo --noEmit",
   "root:upgrade": "nmr-taze --include-locked",
-  "sync-agent-files": "nmr-sync-agent-files",
   test: "nmr root:test && pnpm --recursive exec nmr test",
   "test:all": "nmr root:test:all && pnpm --recursive exec nmr test:all",
-  // Chains `root:test`, not a `root:test:coverage`: the root config reports no coverage of its own.
   "test:coverage": "nmr root:test && pnpm --recursive exec nmr test:coverage",
   "test:tool": "nmr root:test:tool && pnpm --recursive exec nmr test:tool",
   "test:unit": "nmr root:test:unit && pnpm --recursive exec nmr test:unit",
-  // Omitting `--config` is deliberate: bare `vitest` at the monorepo root resolves the root `vitest.config.ts`,
-  // covering the whole tree in one process. A chain like the others would never advance past its first watcher.
+  // Bare `vitest` at the monorepo root resolves the root `vitest.config.ts`, covering the whole tree in one
+  // process; a chain like the others would never advance past its first watcher.
   "test:watch": `vitest ${GATE_PROJECTS} --watch`,
   typecheck: "nmr root:typecheck && pnpm --recursive exec nmr typecheck",
-  // A string rather than a composite because passthrough args attach to the chain's last command — as a
-  // composite, `nmr upgrade major` would hand `major` to the override report instead of the upgrade tool.
-  //
-  // Overrides print first, as context for the report that follows: a pinned transitive dependency is why
-  // an expected upgrade may be missing from it. taze handles pnpm workspaces natively, so this needs no
-  // `pnpm --recursive` fan-out: one process covers the root and every package.
+  // A string rather than a composite: Passthrough args attach to the chain's last command.
   upgrade: "nmr-report-overrides && nmr-taze --include-locked --recursive"
 };
 
@@ -375,7 +363,7 @@ function formatPaths(paths) {
 ${paths.map((path2) => `      ${path2}`).join("\n")}`;
 }
 function getMinVersion() {
-  const picked = { "version": "0.25.0" };
+  const picked = { "version": "0.26.0" };
   if (typeof picked.version !== "string") {
     throw new TypeError("nmr/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -10,7 +10,7 @@
       "readyupVersion": "0.23.0",
       "source": "kits/default.ts",
       "sourceHash": "f646e7fb",
-      "targetHash": "514c9b6f"
+      "targetHash": "56564046"
     }
   ]
 }

package/README.md

@@ -3,20 +3,21 @@
 Context-aware script runner for pnpm monorepos. Ships an `nmr` (node-monorepo run) binary that provides centralized, consistent script execution across workspace packages and the monorepo root.
 
 <!-- section:release-notes -->
-## Release notes — v0.25.0 (2026-08-03)
+## Release notes — v0.26.0 (2026-08-04)
 
 ### 🎉 Features
 
-- Mark a cache hit's time saving with a speed-boost icon (#579)
+- Publish each package's readyup kit from the package that owns it (#590)
 
-  Time saved due to `nmr`'s cache feature now earns a rocket emoji in the terminal output.
-  Savings less than 1 second are no longer reported.
+  ReadyUp checks for `@williamthorsen/nmr`, `@williamthorsen/release-kit`, and `v11y-check` are now run directly against these packages, guaranteeing a version-appropriate check, instead of against their host repo. The package must be installed as a direct dependency in the calling repo.
 
-- Publish nmr's readyup kit with a test-tier conformance check (#580)
+  The syntax is `rdy run --from npm:<package>`. `rdy run --packages` runs the kits contained in any packages listed in `.config/readyup.config.ts`. Requires `readyup` 0.23 or later.
 
-  `@williamthorsen/nmr` is now bundled with ReadyUp kits that check a repo's alignment with `nmr` requirements and recommendations.
+- Ship agent guidance as CodeAssembly package content (#591)
 
-  `rdy run --from npm:@williamthorsen/nmr` checks the repo against the kits without prior configuration. Once the package is added to the ReadyUp config, `rdy run --packages` will run the `nmr` kits along with those of any other registered package. Requires `readyup` v0.23 or greater.
+  A repo that consumes `@williamthorsen/nmr` can now adopt `nmr`'s agent guidance by naming the package in `.agents/codeassembly.yaml`. `codeassembly sync` then delivers that guidance to every agent harness. Guidance updates are thus delivered directly with each package, eliminating the need to keep a guidance file in sync. The `nmr sync-agent-files` command has been removed.
+
+  Migration guide: Delete `.agents/nmr/`, remove the `@nmr/AGENTS.md` include line, and remove all uses of `check:agent-files`.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -201,23 +202,23 @@ import { defineConfig } from '@williamthorsen/nmr/config';
 
 export default defineConfig({
   workspaceScripts: {
-    'build:pre': 'npx rdy compile',
+    'build:pre': 'node scripts/generate-manifest.ts',
   },
 });
 ```
 
-Attach a post-build step to one package:
+Attach a step to one package's hook:
 
 ```jsonc
-// packages/nmr/package.json
+// packages/my-package/package.json
 {
   "scripts": {
-    "build:post": "nmr-sync-agent-files",
+    "upgrade:post": "nmr-report-overrides",
   },
 }
 ```
 
-The second example calls the bin directly, which sidesteps the workspace-versus-root registry distinction.
+The second example calls the bin directly: `report-overrides` is a root-registry command, so `nmr report-overrides` from inside a package fails with `Unknown command`, while the bin runs from either scope.
 
 ## Check-result cache
 
@@ -237,7 +238,7 @@ The cache is a working-tree cache, not a build cache: it answers "has this exact
 
 ### What is cached
 
-Cacheable by default: `check`, `check:agent-files`, `check:strict`, `ci`, `fix:check`, `fmt:check`, `lint:check`, `lint:strict`, `test`, `test:coverage`, `test:tool`, `test:unit`, `typecheck`, and the `root:` variants `root:check`, `root:lint:check`, `root:lint:strict`, `root:test`, `root:test:tool`, `root:test:unit`, and `root:typecheck`.
+Cacheable by default: `check`, `check:strict`, `ci`, `fix:check`, `fmt:check`, `lint:check`, `lint:strict`, `test`, `test:coverage`, `test:tool`, `test:unit`, `typecheck`, and the `root:` variants `root:check`, `root:lint:check`, `root:lint:strict`, `root:test`, `root:test:tool`, `root:test:unit`, and `root:typecheck`.
 
 Everything else runs every time:
 
@@ -437,11 +438,10 @@ Neither is bound to a git hook. `prepush` is named for when you run it, not for
 
 #### Check and quality
 
-| Command             | Runs                                                                          |
-| ------------------- | ----------------------------------------------------------------------------- |
-| `check`             | `typecheck`, `fmt:check`, `lint:check`, `test`                                |
-| `check:agent-files` | `nmr-sync-agent-files --check`                                                |
-| `check:strict`      | `typecheck`, `fmt:check`, `lint:strict`, `test:coverage`, `check:agent-files` |
+| Command        | Runs                                                     |
+| -------------- | -------------------------------------------------------- |
+| `check`        | `typecheck`, `fmt:check`, `lint:check`, `test`           |
+| `check:strict` | `typecheck`, `fmt:check`, `lint:strict`, `test:coverage` |
 
 #### Fix
 
@@ -531,7 +531,6 @@ These scripts operate on root-level code only (not workspace packages):
 | Command            | Runs                   |
 | ------------------ | ---------------------- |
 | `report-overrides` | `nmr-report-overrides` |
-| `sync-agent-files` | `nmr-sync-agent-files` |
 
 ## CLI reference
 
@@ -585,35 +584,33 @@ Report any active `pnpm.overrides` in the root `package.json`, reminding develop
 nmr report-overrides
 ```
 
-### `sync-agent-files`
+## Agent guidance
 
-Sync the agent-facing guidance shipped with nmr into the consuming repo.
+nmr ships the rules an agent needs in order to invoke it, as [CodeAssembly](https://github.com/williamthorsen/codeassembly) package content. Adopt it by naming the package in the consuming repo's `.agents/codeassembly.yaml`:
 
-```bash
-nmr sync-agent-files         # write .agents/nmr/AGENTS.md, stamped with the installed nmr version
-nmr sync-agent-files --check # verify the stamp matches; exit 1 with a fix message if not
+```yaml
+packages:
+  use:
+    - '@williamthorsen/nmr'
 ```
 
-Run `nmr sync-agent-files` once after upgrading nmr. The generated file is committed to the consuming repo; do not edit it by hand.
-
-The default root `check:strict` composite includes `check:agent-files`, which runs `--check` automatically — so any CI pipeline already running `check:strict` catches drift without per-consumer wiring.
+Then add `codeassembly` as a devDependency and run `codeassembly sync`. The guidance is injected into the machine-local guidance file each harness loads at launch; nothing is copied into the repo or committed there. It resolves from the installed package, so upgrading nmr updates it with no second step.
 
-To expose the synced guidance to Claude Code sessions, add this include to the consuming repo's `.agents/PROJECT.md`:
+Wiring the sync to `postinstall` keeps it current without a hand-run command:
 
-```markdown
-@nmr/AGENTS.md
+```json
+{
+  "scripts": {
+    "postinstall": "codeassembly sync --warn-only"
+  }
+}
 ```
 
-#### What belongs in the synced file
-
-The synced file is injected at launch in every consuming repo, so every line is paid for on every task whether or not it is relevant. It is a cheatsheet, not a manual.
-
-A line earns a place in `AGENTS.md` only if both hold:
+`--warn-only` reports a sync failure and exits 0; without it, a failed sync aborts `pnpm install`.
 
-1. It is absent from nmr's own output. Bare `nmr` already prints the flags, every command, and the shell command each resolves to; failing checks already name their own fix. Repeating any of that costs launch tokens to say something the agent will be told anyway, at the moment it matters.
-2. The obvious action goes wrong without it. Guidance that prevents a silent mistake earns its place; guidance that prevents a mistake the next error message would diagnose does not.
+### Migrating from `sync-agent-files`
 
-Everything else belongs in this README, reachable on demand at `node_modules/@williamthorsen/nmr/README.md`, with a pointer from `AGENTS.md` naming the topic so an agent knows to look. When adding a feature, document it here and extend that pointer rather than the cheatsheet.
+The `nmr sync-agent-files` command, its `nmr-sync-agent-files` bin, and the `check:agent-files` script were removed in favor of the above. After upgrading, delete the generated `.agents/nmr/` directory and the `@nmr/AGENTS.md` line it was exposed through, drop `check:agent-files` from any `check:strict` override that enumerates it, and remove any direct call to the bin.
 
 ## Standalone utilities
 

package/agents/README.md

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

package/{AGENTS.md → agents/guidance/rulebooks/nmr.md}

@@ -1,8 +1,10 @@
 ---
-source: '@williamthorsen/nmr@0.0.0-source'
+slug: nmr
+description: Invocation rules for the nmr script runner in a pnpm monorepo.
+delivery: ambient
 ---
 
-# nmr: agent guidance (generated; do not edit)
+# nmr: agent guidance
 
 - Use `nmr <command>`, not `pnpm run <command>`, for anything nmr provides. Run bare `nmr` to list every command and the shell command it resolves to; a wrong guess reports only `Unknown command`, with no list.
 - Scope follows cwd, and bare `nmr` lists both registries: from the repo root a command covers root files and every workspace; from inside a package, that package alone. `nmr -F <pkg> <command>` targets one package from anywhere; `nmr root:<command>` targets root files alone, which isolates a failure to root code.

package/dist/esm/check-cache.js

@@ -18,7 +18,6 @@ export const CURRENT_RUNTIME = {
 export const DEBUG_ENV_VAR = 'NMR_DEBUG';
 export const DEFAULT_CACHEABLE_COMMANDS = [
     'check',
-    'check:agent-files',
     'check:strict',
     'ci',
     'fix:check',

package/dist/esm/default-scripts.js

@@ -28,8 +28,7 @@ export const rootScripts = {
     'audit:prod': 'pnpm exec v11y --prod',
     build: 'pnpm --recursive exec nmr build',
     check: ['typecheck', 'fmt:check', 'lint:check', 'test'],
-    'check:agent-files': 'nmr-sync-agent-files --check',
-    'check:strict': ['typecheck', 'fmt:check', 'lint:strict', 'test:coverage', 'check:agent-files'],
+    'check:strict': ['typecheck', 'fmt:check', 'lint:strict', 'test:coverage'],
     ci: ['build', 'check:strict'],
     clean: 'nmr-clean',
     fix: ['lint', 'fmt'],
@@ -51,7 +50,6 @@ export const rootScripts = {
     'root:test:unit': 'vitest --config ./vitest.root.config.ts --project unit',
     'root:typecheck': 'tsgo --noEmit',
     'root:upgrade': 'nmr-taze --include-locked',
-    'sync-agent-files': 'nmr-sync-agent-files',
     test: 'nmr root:test && pnpm --recursive exec nmr test',
     'test:all': 'nmr root:test:all && pnpm --recursive exec nmr test:all',
     'test:coverage': 'nmr root:test && pnpm --recursive exec nmr test:coverage',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -54,13 +54,12 @@
     "nmr-compile": "bin/nmr-compile.js",
     "nmr-fmt": "bin/nmr-fmt.js",
     "nmr-report-overrides": "bin/nmr-report-overrides.js",
-    "nmr-sync-agent-files": "bin/nmr-sync-agent-files.js",
     "nmr-taze": "bin/nmr-taze.js"
   },
   "files": [
     ".readyup/kits/*.js",
     ".readyup/manifest.json",
-    "AGENTS.md",
+    "agents",
     "bin",
     "dist"
   ],
@@ -96,7 +95,11 @@
   "publishConfig": {
     "access": "public"
   },
+  "codeassembly": {
+    "content": "agents"
+  },
   "scripts": {
-    "build:post": "nmr-sync-agent-files && rdy compile"
+    "build:post": "rdy compile",
+    "build:pre": "rdy verify"
   }
 }

package/bin/nmr-sync-agent-files.js

@@ -1,11 +0,0 @@
-#!/usr/bin/env node
-try {
-  await import('../dist/esm/cli-sync-agent-files.js');
-} catch (error) {
-  if (error.code === 'ERR_MODULE_NOT_FOUND') {
-    process.stderr.write('nmr-sync-agent-files: build output not found — run `pnpm run build` first\n');
-  } else {
-    process.stderr.write(`nmr-sync-agent-files: failed to load: ${error.message}\n`);
-  }
-  process.exit(1);
-}

package/dist/esm/cli-sync-agent-files.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/esm/cli-sync-agent-files.js

@@ -1,29 +0,0 @@
-import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
-import { check, sync } from "./commands/sync-agent-files.js";
-import { findMonorepoRoot } from "./workspace.js";
-const flagSchema = {
-    check: { long: '--check', type: 'boolean' },
-};
-const { flags } = parseArgsOrExit(process.argv.slice(2), flagSchema);
-try {
-    runCommand(flags.check);
-}
-catch (error) {
-    reportError(error instanceof Error ? error.message : String(error));
-    process.exit(1);
-}
-function runCommand(checkOnly) {
-    const monorepoRoot = findMonorepoRoot();
-    if (!checkOnly) {
-        const { path: destinationPath, packageSpecifier, changed } = sync(monorepoRoot);
-        console.info(changed ? `✓ Wrote ${destinationPath} (${packageSpecifier})` : `✓ ${destinationPath} already up to date`);
-        process.exit(0);
-    }
-    const result = check(monorepoRoot);
-    if (result.ok) {
-        console.info('✓ .agents/nmr/AGENTS.md is in sync');
-        process.exit(0);
-    }
-    process.stderr.write(`${result.reason}\n`);
-    process.exit(1);
-}

package/dist/esm/commands/sync-agent-files.d.ts

@@ -1,13 +0,0 @@
-export declare function check(destinationDir: string): CheckResult;
-export interface SyncResult {
-    path: string;
-    packageSpecifier: string;
-    changed: boolean;
-}
-export declare function sync(destinationDir: string): SyncResult;
-export type CheckResult = {
-    ok: true;
-} | {
-    ok: false;
-    reason: string;
-};

package/dist/esm/commands/sync-agent-files.js

@@ -1,58 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { readPackageVersion } from '@williamthorsen/nmr-core';
-const VERSION = readPackageVersion(import.meta.url);
-const PACKAGE_NAME = '@williamthorsen/nmr';
-const DESTINATION_RELATIVE_PATH = '.agents/nmr/AGENTS.md';
-const SOURCE_FILENAME = 'AGENTS.md';
-const FRONTMATTER_REGEX = /^---\n((?:.*\n)*?)---\n/;
-export function check(destinationDir) {
-    const destinationPath = getDestinationPath(destinationDir);
-    if (!existsSync(destinationPath)) {
-        return {
-            ok: false,
-            reason: `${DESTINATION_RELATIVE_PATH} is missing. Run \`nmr sync-agent-files\`.`,
-        };
-    }
-    const expectedBody = stripFrontmatter(readFileSync(getSourcePath(), 'utf8'));
-    const foundBody = stripFrontmatter(readFileSync(destinationPath, 'utf8'));
-    if (foundBody !== expectedBody) {
-        return {
-            ok: false,
-            reason: `${DESTINATION_RELATIVE_PATH} content is out of date. Run \`nmr sync-agent-files\`.`,
-        };
-    }
-    return { ok: true };
-}
-export function sync(destinationDir) {
-    const body = stripFrontmatter(readFileSync(getSourcePath(), 'utf8'));
-    const packageSpecifier = buildPackageSpecifier();
-    const destinationPath = getDestinationPath(destinationDir);
-    if (existsSync(destinationPath) && stripFrontmatter(readFileSync(destinationPath, 'utf8')) === body) {
-        return { path: destinationPath, packageSpecifier, changed: false };
-    }
-    const output = `---\nsource: '${packageSpecifier}'\n---\n${body}`;
-    mkdirSync(path.dirname(destinationPath), { recursive: true });
-    writeFileSync(destinationPath, output, 'utf8');
-    return { path: destinationPath, packageSpecifier, changed: true };
-}
-function buildPackageSpecifier() {
-    return `${PACKAGE_NAME}@${VERSION}`;
-}
-function getDestinationPath(destinationDir) {
-    return path.join(destinationDir, DESTINATION_RELATIVE_PATH);
-}
-function getSourcePath() {
-    let dir = path.dirname(fileURLToPath(import.meta.url));
-    while (dir !== path.dirname(dir)) {
-        const candidate = path.join(dir, SOURCE_FILENAME);
-        if (existsSync(candidate))
-            return candidate;
-        dir = path.dirname(dir);
-    }
-    throw new Error(`Could not locate ${SOURCE_FILENAME} in any parent of ${fileURLToPath(import.meta.url)}`);
-}
-function stripFrontmatter(content) {
-    return content.replace(FRONTMATTER_REGEX, '');
-}