From b296f5f805a6bab54c0c8cd4a6e3f7a25a7f159e Mon Sep 17 00:00:00 2001
From: "Ricardo Q. Bazan" <raquirozbazan@gmail.com>
Date: Sun, 18 Oct 2026 12:44:43 -0500
Subject: [PATCH 1/3] docs: point the CLAUDE.md files at the development guide
 and fix their stale claims

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TzjvWWSt2KQNsVgAtswGTL
---
 CLAUDE.md             | 36 +++++++++---------------------------
 run-run/CLAUDE.md     | 19 +++++++------------
 run-run/cli/CLAUDE.md | 25 +++++++++++++------------
 3 files changed, 29 insertions(+), 51 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 38a9304..44b4b5b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,39 +4,21 @@ You are an agent maintaining this monorepo. The microkernel refactor that produc
 
 ## Layout
 
-```
-dx/
-├── shared/          # @variablelab/* — shared utilities (clibuddy, loggy)
-├── run-run/         # @rrlab/* — the rrlab product
-│   ├── cli/         # @rrlab/cli — the kernel
-│   ├── *-plugin/    # @rrlab/<tool>-plugin — the official plugins, one per wrapped tool
-│   └── *-config/    # @rrlab/<tool>-config — shared presets
-└── vland/           # @variablelab/vland CLI + the scaffolds it emits
-    ├── cli/         # @variablelab/vland — the `vland init` CLI
-    └── templates/   # scaffolds emitted by `vland init`
-```
+The folders and what each holds: [docs/development.md](docs/development.md#layout).
 
 This repo hosts **two npm orgs** intentionally: `@variablelab/*` (Variableland's utilities + the `vland` CLI) and `@rrlab/*` (the `rr` CLI product). Cross-pollination is fine — clibuddy and loggy are shared utilities both stacks depend on.
 
-Stack: pnpm workspaces, Turborepo, Changesets, `tsdown` for builds, vitest for tests, Biome for lint/format, TypeScript strict, Node 24 for development (pinned in `mise.toml`). Published packages declare `engines.node` as `>=22.18.0`, the first Node 22 that strips types by default, which `rr` needs to load `run-run.config.{ts,mts}`. CI runs the full check on both that floor (`mise.floor.toml`; run it locally with `MISE_ENV=floor`) and the `mise.toml` version. Bump the floor in `mise.floor.toml` and every `engines.node` together.
+Stack: pnpm workspaces, Turborepo, Changesets, `tsdown` for builds, vitest for tests, Biome for lint/format, TypeScript strict.
 
 ## Build & verify
 
-```bash
-pnpm --filter @rrlab/cli build     # build a single package
-pnpm --filter @rrlab/cli test      # test a single package
-pnpm test                          # all (turbo handles affected detection)
-pnpm rr check                      # dogfooded lint + format + tsc
-pnpm build && pnpm test && pnpm rr check    # full check
-```
+Setup, the Node floor, the everyday commands and CI are in [docs/development.md](docs/development.md).
 
 `pnpm rr check` must be green before any commit. If `pnpm rr lint --fix` or `pnpm rr format --fix` applies safe fixes, run them and re-verify.
 
 ## Working principles (non-negotiable)
 
-1. **Strict test discipline.** Every feature + bug fix lands with tests:
-   - Features: a happy-path test and at least one failure case (in `test/integration/` or `src/**/__tests__/`).
-   - Fixes: a regression test that would have caught the bug.
+1. **Strict test discipline.** Every feature and fix lands with the tests [docs/contributing.md](docs/contributing.md#pull-requests) asks for, in the folders [docs/development.md](docs/development.md#tasks) names.
    - Refactors with no behaviour change: existing tests must still pass; remove tests only when they were asserting implementation details that no longer exist.
    - If you can't write a meaningful test, the design is probably wrong — stop and report.
 
@@ -46,7 +28,7 @@ pnpm build && pnpm test && pnpm rr check    # full check
    - Pattern drift (e.g., one file uses `for...of`, the neighbour uses `.forEach()`) → align with the closer neighbour's pattern.
    - Don't go on cleanup spelunking expeditions for files unrelated to your task. Stay in the blast radius of what you're already touching.
 
-3. **Atomic commits**, imperative present-tense English: `add PluginRegistry`, `fix tsc cwd handling on monorepos`, `refactor edit-json idempotency`. Use Changesets (`pnpm changeset`) for any change to a publishable package.
+3. **Atomic commits** as [Conventional Commits](docs/contributing.md#pull-requests), such as `feat(cli): add PluginRegistry` or `fix(ts-plugin): handle tsc cwd on monorepos`. A change to what a package ships to npm needs a changeset (`pnpm changeset`). See [docs/contributing.md](docs/contributing.md#changesets) for the bump.
 
 4. **Never publish to npm.** No `pnpm publish`, no `changeset publish`, no `npm publish`. The human handles publication.
 
@@ -54,13 +36,12 @@ pnpm build && pnpm test && pnpm rr check    # full check
 
 ## Coding conventions
 
-- **Imports**: `#src/...` aliases inside a package; `@rrlab/...` / `@variablelab/...` across packages.
+- **Imports**: `#src/...` inside `@rrlab/cli` and `@variablelab/vland`, which map it in `imports`. Relative paths in the other packages. Package names (`@rrlab/...`, `@variablelab/...`) across packages.
 - **Exports**: named exports preferred; default exports only when the consumer needs them (e.g. plugin factories).
 - **Services**: classes ending in `Service`, dependencies via constructor. Only `logger` is a singleton.
-- **Commands**: factory functions named `create<Name>Command(ctx)` returning a configured commander `Command`. A command is a thin wrapper: it resolves its provider (throwing `MissingPluginError` with its `providers` list when absent) and delegates to exactly one action. See `decisions/015-command-action-service-layering.md`.
-- **Actions**: free functions in `src/actions/` taking a **single options object** named `<Name>ActionConfig` — never positional params. Dependencies (`ctx`, the resolved provider) sit at the top level; parsed flags/positional args nest under `options` / `args` (reuse the verb-option types from `src/types/tool.ts`). Actions import only `services`/`render`/`lib` — never the CLI framework.
+- **Commands and actions** (in `@rrlab/cli`): see "Commands are thin wrappers over actions" in [run-run/cli/CLAUDE.md](run-run/cli/CLAUDE.md#commands-are-thin-wrappers-over-actions) and [decisions/015](decisions/015-command-action-service-layering.md).
 - **Errors**: domain errors are classes — kernel-internal ones in `src/errors/` (e.g. `MissingPluginError`), SDK ones in `src/lib/plugin/errors.ts` (`MultipleProvidersError`). Each builds its user-facing message from structured constructor args. Do NOT set `this.name` — keep the plain `Error:` prefix, so output stays clean.
-- **Tests**: vitest. Unit tests in `src/**/__tests__/*.test.ts`. Integration tests in `test/integration/*.test.ts`. Inline snapshots for CLI output assertions.
+- **Tests**: vitest, in the folders [docs/development.md](docs/development.md#tasks) names. Inline snapshots for CLI output assertions.
 - **No `any`.** If TypeScript pushes you there, stop and report — it usually means a design problem.
 - **Match neighbours.** Before introducing a new pattern, scan 2-3 nearby files. If they use a different style, follow theirs.
 
@@ -72,6 +53,7 @@ pnpm build && pnpm test && pnpm rr check    # full check
 
 ## Going deeper
 
+- **[`docs/contributing.md`](docs/contributing.md)** — branches, commits, tests, changesets and releases.
 - **`run-run/CLAUDE.md`** — orientation for working on the `@rrlab/*` ecosystem (plugin contract, conventions for adding/modifying plugins).
 - **`run-run/cli/CLAUDE.md`** — kernel internals (commander patterns, context lifecycle, edit-json DSL, KDL spec emission).
 - **`decisions/`** — one file per architectural decision. Read before designing anything that touches plugin lifecycle, dependency model, or templating. Format / template in `decisions/README.md`.
diff --git a/run-run/CLAUDE.md b/run-run/CLAUDE.md
index d49c64f..fd313e6 100644
--- a/run-run/CLAUDE.md
+++ b/run-run/CLAUDE.md
@@ -1,6 +1,6 @@
 # CLAUDE.md — `run-run/` (the `@rrlab/*` ecosystem)
 
-Orientation for working on the `@rrlab/*` packages. Prerequisite reading: the repo-root `CLAUDE.md` (working principles, build commands, coding conventions).
+Orientation for working on the `@rrlab/*` packages. Prerequisite reading: the repo-root `CLAUDE.md` (working principles, coding conventions).
 
 ## Why `rr` exists — and how it's meant to be invoked
 
@@ -10,7 +10,7 @@ This means:
 
 - **Do not wrap `rr` in `package.json` scripts.** Aliases like `"lint": "rr lint"`, `"format": "rr format --fix"`, `"tscheck": "rr tsc"`, `"check": "rr check"` re-introduce the very indirection rr was created to remove (`pnpm lint` → `rr lint` → `biome check` is three layers for what should be one). The user types `rr lint`, not `pnpm lint`.
 - **The expected setup**: `node_modules/.bin` on `PATH` — typically via mise (`[env] _.path = ["{{config_root}}/node_modules/.bin"]`) — so `rr` is directly invokable from the project root without a package-manager hop. Templates ship a `mise.toml` that wires this for new projects.
-- **`package.json scripts` may still exist** — but only for things `rr` does NOT cover (`vitest run`, `tsx watch`, `node dist/...`, `vite dev`, `turbo run dev`, `changeset publish`). These are not single-command aliases; they're either different tools or multi-step compositions.
+- **`package.json scripts` may still exist** — but only for things `rr` does NOT cover (`tsx watch`, `node dist/...`, `vite dev`, `turbo run dev`, `changeset publish`). These are not single-command aliases; they're either different tools or multi-step compositions.
 - **Lifecycle / orchestration hooks MAY call `rr` directly.** lefthook git hooks, `prepublishOnly`, GitHub Actions workflows — those are triggered by other systems, not typed by the developer, so they don't fight the "one entry point" goal. A `pre-commit: rr jsc --fix-staged` lefthook job is exactly right.
 - **READMEs teach `rr <cmd>`, not `pnpm <cmd>`.** Mention the mise PATH note once; from then on every developer-facing instruction is `rr <cmd>`.
 
@@ -27,7 +27,7 @@ If you find yourself tempted to add a `pnpm <script>` that exists only to call `
 | `ts-plugin/` | `@rrlab/ts-plugin` | `tsc` (TypeScript). Has `install()` that scaffolds `tsconfig.json` from a preset. |
 | `tsdown-plugin/` | `@rrlab/tsdown-plugin` | `pack` (tsdown). |
 | `vitest-plugin/` | `@rrlab/vitest-plugin` | `test` (vitest), a streaming passthrough — see `decisions/016-vitest-passthrough-plugin.md`. |
-| `ts-config/` | `@rrlab/ts-config` | Shared tsconfig presets: `react`, `dom/app`, `dom/lib`, `no-dom/app`, `no-dom/lib`. |
+| `ts-config/` | `@rrlab/ts-config` | Shared tsconfig presets, listed in [its README](ts-config/README.md#presets). |
 | `biome-config/` | `@rrlab/biome-config` | Shared biome preset. |
 | `tsdown-config/` | `@rrlab/tsdown-config` | Shared tsdown configuration helpers. |
 
@@ -78,12 +78,7 @@ Every plugin's host-side tool (`@biomejs/biome`, `typescript`, etc.) is a `peerD
 
 ## Required reading order before changing anything in here
 
-1. The `decisions/` folder at the repo root. Five load-bearing decisions today:
-   - **001** all-peer dependencies.
-   - **002** no `bin` shims.
-   - **003** wire plugins via the registry (`ctx.plugins`) + drop of `future.oxc`.
-   - **004** templating strategy + edit-json DSL.
-   - **005** `@rrlab/tsdown-plugin` scaffolding + `@rrlab/tsdown-config` shape.
+1. The [`decisions/`](../decisions) folder at the repo root, one file per decision. Read the ones on the area you're changing.
 2. `run-run/cli/CLAUDE.md` if you're going to touch the kernel.
 3. The `*.test.ts` files of the area you're modifying. Tests are the executable spec for the existing behaviour.
 
@@ -108,7 +103,7 @@ Every official plugin exports `default = definePlugin({...})` — a plain `Plugi
 
 ### Templating: code-as-template + edit-json DSL
 
-The local config files plugins scaffold are **thin wrappers** pointing at the shared `@rrlab/*-config` package via `extends`. Two flavours of `FileOp`:
+The local config files plugins scaffold are **thin wrappers** pointing at the shared `@rrlab/*-config` package via `extends`. The `FileOp` kinds are the union in `run-run/cli/src/lib/plugin/types.ts`. Config scaffolding uses these:
 
 ```ts
 // new file: full content as a string (constructed in code, no template engine)
@@ -133,7 +128,7 @@ The local config files plugins scaffold are **thin wrappers** pointing at the sh
 
 Paths are JSON Pointer (RFC 6901). Ops are NOT strict RFC 6902 — see `decisions/004-templating-and-edit-json-dsl.md` for why.
 
-For TS modules (`eslint.config.ts` etc. if we ever add them), the escape hatch is `{ kind: "edit-text", path, edit: (src) => string }` — the plugin does AST surgery in-process via `magicast` (already a kernel dep) and returns the new text.
+For TS modules, such as the `tsdown.config.ts` that tsdown-plugin patches, the escape hatch is `{ kind: "edit-text", path, edit: (src) => string }`: the plugin parses the module with `magicast`, from its own `dependencies`, and returns the new text.
 
 ### Adding a new plugin (checklist)
 
@@ -145,7 +140,7 @@ For TS modules (`eslint.config.ts` etc. if we ever add them), the escape hatch i
 6. `src/__tests__/tool-versions.test.ts`: read this plugin's own `package.json` and assert that every `TOOL_VERSIONS[<name>].install` range fits within `peerDependencies[<name>]` (`semver.subset`). Copy the shape from any sibling plugin's test verbatim — duplication across plugins is cheaper than a kernel-level helper.
 7. `src/__tests__/install.test.ts`: cover install (default preset, declined, per-preset deps), uninstall (delete-vs-edit decision). Use `fs.mkdtemp` + a real tmp dir, not mocks.
 8. Add the alias to `run-run/cli/src/lib/plugin/directory.ts` `PLUGINS_DIRECTORY`, listing every capability it provides in that entry's `capabilities` array (so the `MissingPluginError` hint — derived via `providersOf(capability)` — suggests it).
-9. Add an integration test in `run-run/cli/test/integration/<capability>.test.ts` if the plugin provides a capability that doesn't yet have e2e coverage.
+9. Add an integration test in `run-run/cli/test/integration/<command>.test.ts` (such as `tsc.test.ts` for `typecheck`) if the plugin provides a capability that doesn't have one yet.
 10. If the plugin needs a shared config, create `run-run/<tool>-config/` alongside (mirror `ts-config` / `biome-config`).
 11. Update the dogfooded `run-run.config.mts` at the repo root if it makes sense (its `plugins` array is what we use today).
 12. Add the plugin's row to the "What's here" table above and to the "Plugins" table in `run-run/cli/README.md`. That README ships to npm, so the change needs a `@rrlab/cli` changeset. `plugin-docs.test.ts` fails until both rows exist.
diff --git a/run-run/cli/CLAUDE.md b/run-run/cli/CLAUDE.md
index d10147c..eb57ff6 100644
--- a/run-run/cli/CLAUDE.md
+++ b/run-run/cli/CLAUDE.md
@@ -14,7 +14,7 @@ bin                                    (bash dispatcher — entry point)
          │   └─ for each config.plugins: plugin.services(ctx) → registry.register(...)
          │
          └─ commands                   (src/program/commands/*.ts — thin wrappers, built on src/program/base.ts)
-             ├─ lint / format / jsc / tsc / pack
+             ├─ lint / format / jsc / tsc / test / pack
              │   ├─ ctx.plugins.getServiceOrThrow(capability)
              │   └─ delegate to one action (src/actions/*.ts)
              ├─ check                  (action calls jscAction + tscAction in-process)
@@ -28,9 +28,9 @@ bin                                    (bash dispatcher — entry point)
 
 ### Commands are thin wrappers over actions
 
-Each `create<Name>Command(ctx)` resolves its service inside its `.action(...)` via `ctx.plugins.getServiceOrThrow(capability)` (which raises `MissingPluginError` when absent), then delegates to exactly one free-function action in `src/actions/`. Actions never import commander — they take a single `<Name>ActionConfig` object and depend only on `services`/`render`/`lib`. See `decisions/015-command-action-service-layering.md`.
+Each `create<Name>Command(ctx)` resolves its service inside its `.action(...)` via `ctx.plugins.getServiceOrThrow(capability)` (which raises `MissingPluginError` when absent), then delegates to exactly one free-function action in `src/actions/`. Actions never import commander or `src/program/`. They take a single `<Name>ActionConfig` object: dependencies (`ctx`, the resolved service) at the top level, parsed flags and positional args under `options` and `args` (reuse the verb-option types from `src/types/tool.ts`). See `decisions/015-command-action-service-layering.md`.
 
-Commands are built with `createCommand(name)` from `src/program/base.ts` (a `Cmd extends Command` subclass), **not** commander's own `createCommand`. `Cmd` adds three chainable methods:
+Commands are built with `createCommand(name)` from `src/program/base.ts` (a `Cmd extends Command` subclass), **not** commander's own `createCommand`. `Cmd` adds these chainable methods:
 
 - `.addCapabilities([...capabilities])` — declares which `PluginCapability`s the command exercises.
 - `.addHelpTextAfter(ctx)` — appends the `See also:` / `Powered by:` block, both **auto-derived** from those capabilities (see below). No command hand-writes its cross-references anymore.
@@ -38,7 +38,7 @@ Commands are built with `createCommand(name)` from `src/program/base.ts` (a `Cmd
 
 ### The root is a `RunRunCmd` subclass
 
-`src/program/root.ts` defines `RunRunCmd extends Command`. It groups commands (`.commandsGroup("Code quality:")` etc.), registers `-v/--version` (plain version string), `--about` (credits) and `--usage` (KDL spec) as options with `option:*` listeners, and attaches the banner + installed/available plugins footer via `addHelpText`.
+`src/program/root.ts` defines `RunRunCmd extends Command`. It registers `-v/--version` (plain version string), `--about` (credits) and `--usage` (KDL spec) as options with `option:*` listeners, and attaches the banner + installed/available plugins footer via `addHelpText`. `createProgram` in `src/program/index.ts` groups the commands (`.commandsGroup("Code quality:")` etc.).
 
 ### `--usage` emits a stable KDL spec
 
@@ -46,7 +46,7 @@ Commands are built with `createCommand(name)` from `src/program/base.ts` (a `Cmd
 
 ## Context lifecycle
 
-`ContextService` (`src/services/context.ts`) builds — once per `rr <cmd>` invocation, memoised via `getContext()` — a fresh `ContextValue`:
+`createProgram` calls `ContextService.getContext()` (`src/services/context.ts`) once per `rr <cmd>` invocation. Each call builds a fresh `ContextValue`:
 
 ```ts
 type ContextValue = {
@@ -60,11 +60,11 @@ type ContextValue = {
 
 The registry is populated immediately: for each `plugin` in `config.plugins ?? []`, the kernel calls `plugin.services(pluginContext)` and registers what it returns. If `apiVersion` doesn't match `1`, it throws `PluginApiVersionError`. The populated `PluginRegistry` is then wrapped in a `PluginServices` facade and exposed as `ctx.plugins`.
 
-Commands that don't need plugin services (`clean`, `config`, `completion`) still get the full context; they just ignore `ctx.plugins`. Don't try to lazy-load it; the cost is small (a plugin's `services()` is meant to be cheap) and the simplicity is worth more than the savings.
+`clean` and `completion` take no context, and `config` reads it without resolving a service. The context is still built on every invocation that reaches Node (all but the `rr completion <shell>` fast path in `bin`). Don't try to lazy-load it; the cost is small (a plugin's `services()` is meant to be cheap) and the simplicity is worth more than the savings.
 
 ## ctx.plugins (the `PluginServices` facade)
 
-A `PluginCapability` is a key (`lint`, `format`, `jscheck`, `typecheck`, `pack`, `test`); a **service** is the impl that satisfies it (a `Linter & Doctor`, etc.). One plugin instance can back several capabilities with the same service object.
+A `PluginCapability` is a key of the `PluginServices` type in `src/lib/plugin/types.ts`. A **service** is the impl that satisfies it (a `Linter & Doctor`, etc.). One plugin instance can back several capabilities with the same service object.
 
 `src/services/plugin-services.ts` defines the `PluginServices` **class** — the only plugin-resolution surface commands and actions touch (`ctx.plugins`). It wraps `PluginRegistry` and exposes:
 
@@ -84,9 +84,10 @@ A `PluginCapability` is a key (`lint`, `format`, `jscheck`, `typecheck`, `pack`,
 Every plugin-backed command file follows the same shape:
 
 ```ts
+import type { ContextValue } from "#src/services/context.ts";
 import { createCommand } from "../base.ts";
 
-export function create<Name>Command(ctx: Context) {
+export function create<Name>Command(ctx: ContextValue) {
   return createCommand("<name>")
     .addCapabilities(["<kind>"])
     .summary("<summary>")
@@ -119,14 +120,14 @@ It renders via the `Lines` builder and returns `""` (nothing appended) when both
 
 ## File ops engine (`applyFileOp`)
 
-`src/services/file-ops.ts`. `applyFileOp` performs the filesystem work and returns a `FileOpOutcome` — it never writes to the terminal; the `plugins add/remove` actions map the outcome to clack log lines (`reportFileOp`), and `describeFileOp` renders a side-effect-free one-liner for the remove plan. Four `FileOp` kinds:
+`src/services/file-ops.ts`. `applyFileOp` performs the filesystem work and returns a `FileOpOutcome` — it never writes to the terminal; the `plugins add/remove` actions map the outcome to clack log lines (`reportFileOp`), and `describeFileOp` renders a side-effect-free one-liner for the remove plan. It handles every `FileOp` kind in `src/lib/plugin/types.ts`:
 
 - `create` — writes content; respects `overwrite` flag.
 - `edit-json` — reads, applies `JsonEdit[]` via `applyJsonEdits` (in `src/services/json-edit.ts`), writes back. Uses `comment-json` so user comments + key positions survive.
 - `edit-text` — reads, calls `op.edit(source)`, writes back. Escape hatch for TS modules etc.
 - `delete` — `fs.unlink`. Idempotent (skips if file doesn't exist).
 
-`applyJsonEdits` implements the 4 ops (`set`, `unset`, `include`, `exclude`) over JSON-Pointer paths. Tested in `src/services/__tests__/json-edit.test.ts`. The dedup in `include`/`exclude` uses `JSON.stringify` deep-equality — fine for the value shapes we use today (strings, plain objects).
+`applyJsonEdits` implements the `JsonEdit` ops in `src/lib/plugin/types.ts` over JSON-Pointer paths. Tested in `src/services/__tests__/json-edit.test.ts`. The dedup in `include`/`exclude` uses `JSON.stringify` deep-equality — fine for the value shapes we use today (strings, plain objects).
 
 ## `rr plugins` lifecycle (add / remove)
 
@@ -155,7 +156,7 @@ Both support `--dry-run` (print plan, no side effects) and `--yes` (skip prompts
 
 ## Tests
 
-- `src/**/__tests__/*.test.ts` — unit tests (no fs, no spawn).
+- `src/**/__tests__/*.test.ts` — unit tests: no spawn, and fs only in a temp dir.
 - `test/integration/*.test.ts` — spawn `rr` against a real fixture in `os.tmpdir()`. The fixture symlinks the workspace `node_modules` so the fixture's `run-run.config.mts` can import `@rrlab/*-plugin`.
 
 When the integration test asserts on the doctor or output of a plugin-backed command, configure the fixture's `run-run.config.mts` with `fixtures.config([...aliases])`. See `test/integration/check.test.ts` for the canonical multi-plugin shape (biome + ts).
@@ -163,7 +164,7 @@ When the integration test asserts on the doctor or output of a plugin-backed com
 ## What to keep an eye on
 
 - `dist/cli.usage.kdl` is regenerated by the `build:kdl` script. If a command's summary, description, or option set changes, `pnpm --filter @rrlab/cli build` should be run and the KDL diff inspected before committing.
-- `CLI.md` is generated from the KDL via `usage generate markdown` in CI (after a release tag). Locally, regenerate via `usage generate markdown --file dist/cli.usage.kdl --out-file CLI.md --replace-pre-with-code-fences` if you want to see the diff in dev.
+- `CLI.md` is generated: see [docs/development.md](../../docs/development.md#generated-files) to regenerate it locally.
 - `bin` is a bash dispatcher with a fast path for `rr completion <shell>` (skips Node startup). Keep it minimal — anything new goes in `src/`, not `bin`.
 
 ## Anti-patterns we already paid for

From 46342b2c5edeaf1e35afd93723c5cdcb0e3faccd Mon Sep 17 00:00:00 2001
From: "Ricardo Q. Bazan" <raquirozbazan@gmail.com>
Date: Sun, 18 Oct 2026 12:44:43 -0500
Subject: [PATCH 2/3] docs: fix stale commands, file names, versions and counts
 in the READMEs and guides

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TzjvWWSt2KQNsVgAtswGTL
---
 README.md                    |  2 +-
 docs/contributing.md         |  4 ++--
 docs/development.md          |  2 +-
 run-run/cli/README.md        | 12 ++++++------
 run-run/oxc-plugin/README.md |  4 ++--
 vland/cli/README.md          | 12 ++++++------
 6 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index e06b527..269d809 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@ The monorepo of run-run and vland.
 
 - [`run-run/`](run-run): run-run. The CLI is in `cli/`, a plugin per tool in `*-plugin/` and the presets in `*-config/`. The [run-run README](run-run/cli/README.md#plugins) lists the plugins.
 - [`vland/`](vland): vland. The CLI is in `cli/`, and the templates it starts a project from are in `templates/`.
-- [`shared/`](shared): `@variablelab/clibuddy` and `@variablelab/loggy`, internal to the two CLIs.
+- [`shared/`](shared): the internal packages the CLIs depend on.
 
 ## Contributing
 
diff --git a/docs/contributing.md b/docs/contributing.md
index 0f354a4..cf377fe 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -9,7 +9,7 @@ dx takes bug reports, fixes and small features for run-run, vland and their pack
 
 ## Pull requests
 
-1. Branch from `main` with a prefix: `feat/`, `fix/`, `docs/`, `chore/` or `test/`.
+1. Branch from `main` with a prefix: `feat/`, `fix/`, `docs/`, `ci/`, `chore/` or `test/`.
 2. Write commits as [Conventional Commits](https://www.conventionalcommits.org), such as `fix(oxc-plugin): stop installing a flaky oxlint-tsgolint`. The pull request title takes the same form, because it becomes the squash commit.
 3. A feature lands with a test of the happy path and at least one failure case, and a fix with a regression test.
 4. Run `pnpm rr check` and `pnpm test` before you push.
@@ -29,4 +29,4 @@ Nobody edits versions or `CHANGELOG.md` by hand, and nobody publishes from a clo
 
 When changesets land on `main`, the Release job opens or updates a "chore: update versions" pull request as `vland-bot`. A maintainer merges it, and the next run on `main` publishes each new version to npm, with npm trusted publishing, and tags it.
 
-A new tag of `@rrlab/cli` or `@variablelab/vland` regenerates the `CLI.md` of both CLIs in a "chore: regenerate CLI docs" pull request, which a maintainer merges too.
+A new tag of a CLI regenerates the `CLI.md` of every CLI in the cli docs workflow, in a "chore: regenerate CLI docs" pull request, which a maintainer merges too.
diff --git a/docs/development.md b/docs/development.md
index b42afb4..d36c852 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -6,7 +6,7 @@ How to work on dx in a clone. The [contributing guide](contributing.md) covers h
 
 - [`run-run/`](../run-run): run-run. `cli/` is `@rrlab/cli`, the kernel and the `rr` command. Each `*-plugin/` wraps one tool, and each `*-config/` is a preset that a plugin installs. [`run-run/CLAUDE.md`](../run-run/CLAUDE.md) covers the architecture: the plugin contract and how to add or change a plugin.
 - [`vland/`](../vland): vland. `cli/` is `@variablelab/vland`, and `templates/` holds the projects `vland init` starts from.
-- [`shared/`](../shared): `@variablelab/clibuddy` and `@variablelab/loggy`, the internal packages both CLIs depend on.
+- [`shared/`](../shared): `@variablelab/clibuddy` and `@variablelab/loggy`, the internal packages the CLIs depend on.
 - [`decisions/`](../decisions): the architecture decisions, one file each.
 - `docs/`: this guide and the [contributing guide](contributing.md).
 
diff --git a/run-run/cli/README.md b/run-run/cli/README.md
index 740e77a..917f719 100644
--- a/run-run/cli/README.md
+++ b/run-run/cli/README.md
@@ -18,10 +18,10 @@ It adds the `rr` command to your project. It needs Node 22.18 or later.
 
 ## Usage
 
-Run the help command:
+Print the commands and options:
 
 ```sh
-pnpm rr help
+pnpm rr --help
 ```
 
 > If you have `node_modules/.bin` on your `PATH` (e.g. via `mise` or `direnv` — see [Shell completion](#shell-completion)), you can drop the `pnpm` prefix and invoke `rr` directly.
@@ -49,12 +49,12 @@ rr plugins add biome
 
 This installs `@rrlab/biome-plugin` plus its peer tool and shared config, scaffolds `biome.json` if missing, and wires the plugin into `run-run.config.{ts,mts}`.
 
-To install from a specific dist-tag (e.g. a PR preview release published as `pr-<N>`, or a custom tag), append `@<spec>`:
+To install from a specific dist-tag (e.g. a [PR preview release](https://github.com/withvariablelab/dx/blob/main/docs/development.md#preview-releases) published as `pr-<number>`, or a custom tag), append `@<spec>`:
 
 ```sh
-rr plugins add biome@pr-226   # preview tag
-rr plugins add biome@next     # any dist-tag
-rr plugins add biome@^0.1.0   # explicit version range (sibling configs still use latest)
+rr plugins add biome@pr-<number>   # preview tag
+rr plugins add biome@<dist-tag>    # any dist-tag
+rr plugins add biome@^1.0.0        # explicit version range (sibling configs still use latest)
 ```
 
 When the spec is a dist-tag, `rr` resolves any `@rrlab/*-config` sibling at the same tag, falling back to `latest` if the registry doesn't have the sibling at that tag.
diff --git a/run-run/oxc-plugin/README.md b/run-run/oxc-plugin/README.md
index 1c06acd..a23edb3 100644
--- a/run-run/oxc-plugin/README.md
+++ b/run-run/oxc-plugin/README.md
@@ -8,7 +8,7 @@
 rr plugins add oxc
 ```
 
-`rr plugins add` installs `@rrlab/oxc-plugin` and adds `oxlint`, `oxfmt` and `oxlint-tsgolint` as dev dependencies. It writes no config file: oxlint and oxfmt run with their defaults, and a project that needs to change them adds its own `oxlintrc.json` or `.oxfmtrc`.
+`rr plugins add` installs `@rrlab/oxc-plugin` and adds `oxlint`, `oxfmt` and `oxlint-tsgolint` as dev dependencies. It writes no config file: oxlint and oxfmt run with their defaults, and a project that needs to change them adds its own `.oxlintrc.json` or `.oxfmtrc.json`.
 
 It needs `@rrlab/cli`, oxlint 1 or later and oxfmt 0.67 or later. The type check also needs `oxlint-tsgolint` 0.24 or later, an optional peer.
 
@@ -49,7 +49,7 @@ The `only` array is typed against the capabilities *this* plugin provides (`"lin
 rr plugins remove oxc
 ```
 
-It removes `oxlint`, `oxfmt` and `oxlint-tsgolint` from `package.json`, and drops `oxc()` from `run-run.config.{ts,mts}`. It leaves `oxlintrc.json` and `.oxfmtrc` alone, if you have them: they belong to you.
+It removes `oxlint`, `oxfmt` and `oxlint-tsgolint` from `package.json`, and drops `oxc()` from `run-run.config.{ts,mts}`. It leaves `.oxlintrc.json` and `.oxfmtrc.json` alone, if you have them: they belong to you.
 
 ## License
 
diff --git a/vland/cli/README.md b/vland/cli/README.md
index 32f0384..9fe7d40 100644
--- a/vland/cli/README.md
+++ b/vland/cli/README.md
@@ -34,13 +34,13 @@ The [CLI reference](https://github.com/withvariablelab/dx/blob/main/vland/cli/CL
 
 ### Templates
 
-| Template   | What you get                                                                              |
-| ---------- | ----------------------------------------------------------------------------------------- |
-| `library`  | A standalone TypeScript library with Vitest + Changesets release workflow.                |
-| `backend`  | An Elysia (`@elysiajs/node`) backend with evlog, Vitest, Dockerfile, CI shape.            |
-| `monorepo` | pnpm + Turbo workspace with an Elysia API, a Vite-React SPA, and a few internal packages. |
+| Template   | What you get                                                                                                       |
+| ---------- | ------------------------------------------------------------------------------------------------------------------ |
+| `library`  | A standalone TypeScript library with Vitest + Changesets release workflow.                                         |
+| `backend`  | An Elysia (`@elysiajs/node`) backend with evlog, Vitest, Dockerfile, CI shape.                                     |
+| `monorepo` | pnpm + Turbo workspace with an Elysia API, a Vite-React SPA, and `packages/types`, the zod schemas the apps share. |
 
-All templates target Node.js, pin Node.js and pnpm with [mise](https://mise.jdx.dev) (`mise.toml` and `mise.lock`), run their GitHub Actions on SHA-pinned actions checked by [zizmor](https://docs.zizmor.sh), and ship [`@rrlab/cli`](https://github.com/withvariablelab/dx/tree/main/run-run/cli) (`rr`) as the single entry point for lint, format, type-check, and build. The per-tool config files (`biome.json`, `tsconfig.json`, `tsdown.config.ts`) are not bundled: in your new project, run `rr plugins add` once per tool (`biome`, `ts`, `tsdown`) to opt in. The scaffolded README has the exact post-install setup.
+All templates target Node.js, pin Node.js and pnpm with [mise](https://mise.jdx.dev) (`mise.toml` and `mise.lock`), run their GitHub Actions on SHA-pinned actions checked by [zizmor](https://docs.zizmor.sh), and ship [`@rrlab/cli`](https://github.com/withvariablelab/dx/tree/main/run-run/cli) (`rr`) as the single entry point for lint, format, type-check, test and build. No plugin is configured: the scaffolded README lists the `rr plugins add` commands to run.
 
 ## Shell completion
 

From c16a8ab9469116f16ac9466f7e92e9f07c67425d Mon Sep 17 00:00:00 2001
From: "Ricardo Q. Bazan" <raquirozbazan@gmail.com>
Date: Sun, 18 Oct 2026 12:44:43 -0500
Subject: [PATCH 3/3] docs: write the package descriptions in the brand voice

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TzjvWWSt2KQNsVgAtswGTL
---
 .changeset/stale-texts.md          | 14 ++++++++++++++
 run-run/astro-plugin/package.json  |  2 +-
 run-run/biome-plugin/package.json  |  2 +-
 run-run/cli/package.json           |  2 +-
 run-run/oxc-plugin/package.json    |  2 +-
 run-run/ts-plugin/package.json     |  2 +-
 run-run/tsdown-plugin/package.json |  2 +-
 run-run/vitest-plugin/package.json |  2 +-
 shared/clibuddy/package.json       |  2 +-
 shared/loggy/package.json          |  2 +-
 vland/cli/package.json             |  2 +-
 11 files changed, 24 insertions(+), 10 deletions(-)
 create mode 100644 .changeset/stale-texts.md

diff --git a/.changeset/stale-texts.md b/.changeset/stale-texts.md
new file mode 100644
index 0000000..dca759a
--- /dev/null
+++ b/.changeset/stale-texts.md
@@ -0,0 +1,14 @@
+---
+"@rrlab/cli": patch
+"@rrlab/astro-plugin": patch
+"@rrlab/biome-plugin": patch
+"@rrlab/oxc-plugin": patch
+"@rrlab/ts-plugin": patch
+"@rrlab/tsdown-plugin": patch
+"@rrlab/vitest-plugin": patch
+"@variablelab/vland": patch
+"@variablelab/clibuddy": patch
+"@variablelab/loggy": patch
+---
+
+The npm description, and the README where it changed, say what the code does.
diff --git a/run-run/astro-plugin/package.json b/run-run/astro-plugin/package.json
index c8261e5..ed45e30 100644
--- a/run-run/astro-plugin/package.json
+++ b/run-run/astro-plugin/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@rrlab/astro-plugin",
   "version": "0.1.1",
-  "description": "Astro plugin for @rrlab/cli — provides the typecheck capability via astro check.",
+  "description": "run-run plugin for Astro: the typecheck capability, through astro check.",
   "homepage": "https://github.com/withvariablelab/dx/tree/main/run-run/astro-plugin#readme",
   "bugs": {
     "url": "https://github.com/withvariablelab/dx/issues"
diff --git a/run-run/biome-plugin/package.json b/run-run/biome-plugin/package.json
index b6b594f..1756574 100644
--- a/run-run/biome-plugin/package.json
+++ b/run-run/biome-plugin/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@rrlab/biome-plugin",
   "version": "1.2.1",
-  "description": "Biome plugin for @rrlab/cli — provides lint, format, and jsc capabilities.",
+  "description": "run-run plugin for Biome: the lint, format and jscheck capabilities.",
   "homepage": "https://github.com/withvariablelab/dx/tree/main/run-run/biome-plugin#readme",
   "bugs": {
     "url": "https://github.com/withvariablelab/dx/issues"
diff --git a/run-run/cli/package.json b/run-run/cli/package.json
index 2bf609f..d90cdb1 100644
--- a/run-run/cli/package.json
+++ b/run-run/cli/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@rrlab/cli",
   "version": "1.5.1",
-  "description": "The CLI toolbox to fullstack common scripts in Variable Land",
+  "description": "One way to run the scripts in a repo.",
   "homepage": "https://github.com/withvariablelab/dx/tree/main/run-run/cli#readme",
   "bugs": {
     "url": "https://github.com/withvariablelab/dx/issues"
diff --git a/run-run/oxc-plugin/package.json b/run-run/oxc-plugin/package.json
index 2c40240..5030b07 100644
--- a/run-run/oxc-plugin/package.json
+++ b/run-run/oxc-plugin/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@rrlab/oxc-plugin",
   "version": "1.2.1",
-  "description": "oxc plugin for @rrlab/cli — provides lint (oxlint) and format (oxfmt) capabilities.",
+  "description": "run-run plugin for oxc: the lint (oxlint), format (oxfmt) and typecheck (oxlint type-aware) capabilities.",
   "homepage": "https://github.com/withvariablelab/dx/tree/main/run-run/oxc-plugin#readme",
   "bugs": {
     "url": "https://github.com/withvariablelab/dx/issues"
diff --git a/run-run/ts-plugin/package.json b/run-run/ts-plugin/package.json
index fbbdaca..98ef9a0 100644
--- a/run-run/ts-plugin/package.json
+++ b/run-run/ts-plugin/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@rrlab/ts-plugin",
   "version": "1.2.1",
-  "description": "TypeScript plugin for @rrlab/cli — provides the tsc capability.",
+  "description": "run-run plugin for TypeScript: the typecheck capability, backed by tsc.",
   "homepage": "https://github.com/withvariablelab/dx/tree/main/run-run/ts-plugin#readme",
   "bugs": {
     "url": "https://github.com/withvariablelab/dx/issues"
diff --git a/run-run/tsdown-plugin/package.json b/run-run/tsdown-plugin/package.json
index 15945da..da9cd33 100644
--- a/run-run/tsdown-plugin/package.json
+++ b/run-run/tsdown-plugin/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@rrlab/tsdown-plugin",
   "version": "1.2.1",
-  "description": "tsdown plugin for @rrlab/cli — provides the pack capability for building TS libraries.",
+  "description": "run-run plugin for tsdown: the pack capability, a TypeScript build with tsdown.",
   "homepage": "https://github.com/withvariablelab/dx/tree/main/run-run/tsdown-plugin#readme",
   "bugs": {
     "url": "https://github.com/withvariablelab/dx/issues"
diff --git a/run-run/vitest-plugin/package.json b/run-run/vitest-plugin/package.json
index 85d6bb3..bbff2ee 100644
--- a/run-run/vitest-plugin/package.json
+++ b/run-run/vitest-plugin/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@rrlab/vitest-plugin",
   "version": "0.2.1",
-  "description": "vitest plugin for @rrlab/cli — provides the test capability as a passthrough to vitest.",
+  "description": "run-run plugin for Vitest: the test capability, a passthrough to vitest.",
   "homepage": "https://github.com/withvariablelab/dx/tree/main/run-run/vitest-plugin#readme",
   "bugs": {
     "url": "https://github.com/withvariablelab/dx/issues"
diff --git a/shared/clibuddy/package.json b/shared/clibuddy/package.json
index e919871..23f0bd2 100644
--- a/shared/clibuddy/package.json
+++ b/shared/clibuddy/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@variablelab/clibuddy",
   "version": "0.8.1",
-  "description": "A helper library to create CLIs in Variable Land",
+  "description": "The helpers that run-run and vland build their CLIs with.",
   "homepage": "https://github.com/withvariablelab/dx/tree/main/shared/clibuddy#readme",
   "bugs": {
     "url": "https://github.com/withvariablelab/dx/issues"
diff --git a/shared/loggy/package.json b/shared/loggy/package.json
index 4c53866..3af8c6d 100644
--- a/shared/loggy/package.json
+++ b/shared/loggy/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@variablelab/loggy",
   "version": "0.3.1",
-  "description": "Console wrapper to make logging fun again",
+  "description": "The logger of run-run and vland: messages through consola, debug output through debug.",
   "homepage": "https://github.com/withvariablelab/dx/tree/main/shared/loggy#readme",
   "bugs": {
     "url": "https://github.com/withvariablelab/dx/issues"
diff --git a/vland/cli/package.json b/vland/cli/package.json
index 25e4921..91b316e 100644
--- a/vland/cli/package.json
+++ b/vland/cli/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@variablelab/vland",
   "version": "0.4.1",
-  "description": "The CLI to init a new project in Variable Land",
+  "description": "Starts a project in Variable Land.",
   "homepage": "https://github.com/withvariablelab/dx/tree/main/vland/cli#readme",
   "bugs": {
     "url": "https://github.com/withvariablelab/dx/issues"