rvlib-shipkit 0.14.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,146 @@
 # Changelog
 
+## 0.17.0
+
+**Correction to 0.16.0.** Its notes and its `--frozen` flag description claimed some combination of flags made `shipkit ci` write nothing. None does: STATUS.md is refreshed on every run unless a caller passes `status: false`. If you wired `ci --no-fix --frozen` into CI expecting a read-only run, it leaves STATUS.md behind, and `--json` is the only output that writes nothing. 0.16.0 also flipped rule SK005 from warning to BLOCKING without saying so: a `link:` dependency that no longer resolves, or a declared dependency that is not installed, now fails the gate.
+
+- **`bump --all` takes a kind per unit.** Write `## Unreleased (minor)` on a unit's changelog heading and a batch release gives each unit the kind it actually needs, in ONE gate. A unit whose heading declares nothing refuses rather than being guessed into a version number. Passing a kind on the command line still applies it to the whole selection, and promoting strips the marker. `shipkit bump <unit>` with no kind works the same way.
+- **`notReleasable` can no longer cover a declared release unit.** An entry naming a container that holds one excused every future package under it while the rule reported green. The two lists state opposite intents, so overlap fails.
+- **A release gates fresh.** SK005 caches a clean pass for a day to rate-limit its registry call, but its blocking branches are local facts about whether the tree can import its own dependencies. Those are measured at release time now, not replayed.
+- **The bump rehearsal reads `git fetch`.** Offline or with an expired credential it could compare against stale remote refs and still report a clean merge. It warns and closes inconclusive instead.
+- New pre-commit gate **root-identity**: the name in the root `package.json` and `repo.config.ts`, index against HEAD, plus staged `.bak`/`.orig`/`.rej`. A fixture builder that escapes its temp dir overwrites those files and every other gate still passes, because a gutted repo lints fine. A deliberate rename passes with `SHIPKIT_ALLOW_IDENTITY_CHANGE=1`.
+- `.rv-private/` joins the SK004 gitignore policy. It holds the leak guard's own keyword file, which was committable in every repo until now.
+- `ci --frozen` exists as a flag, and no TUI panel writes STATUS.md any more, so opening the dashboard cannot overwrite a full gate's verdict with a tasks-only one.
+
+## 0.16.0
+
+Upgrading from 0.14.0 lands straight here: 0.15.0 was stamped and never
+published, so everything under the `## 0.15.0` heading below ships in this
+release too, its BREAKING lines included.
+
+Releasing becomes part of the toolkit. `shipkit ci` is the one gate, `shipkit
+bump` is the one release command, git hooks are owned by the binary instead of
+by hand-written shell, and a repo can now ship more than its own root.
+
+### One gate
+
+- `shipkit ci` repairs before it judges. A mechanical fix pass runs first
+  (formatter, canonical imports, the fixable repo-shape rules), then the task
+  DAG, then every check. `--no-fix` skips the repair pass. For a run that
+  writes nothing, add `--frozen`. Under CI the
+  fixers still run and the gate FAILS on any file they rewrote, so a green CI
+  cannot hide an unformatted commit. `--fix-rules` covers the structural rule
+  autofixes and `--no-fix-rules` leaves repo config alone.
+- **BREAKING: every check declares `blocking`.** `export const blocking = true`
+  means the failure is about this repo and stops you. `false` means the check
+  reports the WORLD (a credential nobody minted, a machine that is off), so it
+  prints as a warning and never blocks. A repo whose checks all probe the world
+  declares `checkDefaults: { blocking: false }` once instead of repeating it in
+  every file. A check that declares neither, in a repo with no default, now
+  fails the run: a check that silently does not block is the failure nobody
+  sees. A non-blocking failure is demoted where it is produced, so the printed
+  severity can never disagree with the exit code.
+- A repo's own rules (`repo.config.ts rules: []`) run in the same engine as the
+  built-in `SK###` rules, so a repo rule can BLOCK rather than only warn in a
+  health report. `shipkit rules` marks every rule BLOCKS or warns.
+- New `runCi` options: `frozen`, `failOnAdvisory`, `skipChecks`.
+- `shipkit check` writes STATUS.md as `shipkit check`, and only the full gate
+  says "clear to ship".
+
+### Release units
+
+- A repo is N releasable units. The ROOT unit is mandatory and never declared.
+  Sub-units are optional and declared in `repo.config.ts units: [{ dir }]`.
+  Each unit owns its own CHANGELOG, its own version, its own tag and its own
+  targets. Tag shapes stay per unit: `v{version}` for the root,
+  `{name}@{version}` for a sub-unit by default, overridable with `tag`.
+- **BREAKING: a sub-unit publishes to npm only when its entry declares
+  `npm: true`.** A package that merely forgot `private: true` is no longer a
+  publish target by inference. `npm: true` on a private package.json is a
+  resolution failure, not a silent skip.
+- `notReleasable: [dir]` declares a package that is deliberately not a release
+  unit. New rule SK010 fails on any package that is neither declared nor
+  excluded, so a forgotten package cannot hide. It asks git for the package
+  list, so gitignored trees never trip it.
+- Nothing is scanned into existence. Every surface that used to rediscover
+  packages on its own (drift probes, per-unit tests, per-unit typecheck, the
+  stranded-tag probe) reads the declared units.
+
+### The release path
+
+- `shipkit bump <major|minor|patch> [unit] [--all]` is the whole release from
+  one word. Run from a feature branch it merges into the release branch FIRST,
+  then computes every fact on the merged tree (next version, tag refusals,
+  per-unit test and typecheck), promotes the CHANGELOG `## Unreleased` section,
+  writes the version, runs the gate and every prepublish script, commits, tags,
+  pushes and publishes. Nothing is pushed until the sequence succeeds, so any
+  refusal before the version commit rolls the merge back and returns you to
+  your branch. A tag the remote already carries refuses before anything is
+  written. `--all` bumps every unit that has Unreleased notes, root last, in
+  one version commit. `--dry-run` rehearses the whole thing and writes nothing.
+- `shipkit release [unit]` publishes the version already in package.json,
+  reading its notes from the matching `## <version>` section. It resumes a
+  partial release by comparing the tag's COMMIT rather than its name, so a tag
+  name taken on the remote reads as a burnt version instead of "fully
+  released".
+- `shipkit releases` prints one row per unit: local version, npm version, tag
+  state, work landed since the tag, GitHub release state, then ONE next action
+  per unit. A version stamped without a release is called out: notes that stop
+  before the work did are how a package ships under someone else's changelog.
+  A unit that is in sync with npm and carries `## Unreleased` notes says so as
+  a note, so a release waiting on a decision is never invisible.
+- npm publishing lives here now. A publish runs the unit's own test suite and
+  typecheck, refuses a dirty unit directory, and reads the npm token from
+  `release.npmTokenCommand` into a throwaway userconfig, so the token never
+  reaches argv, a log, or a tracked `.npmrc`. A private unit skips npm and
+  still gets its tag, its push and its GitHub release.
+- The release path runs ONE gate. The separate health gate is gone and
+  `release.requireHealthy` works through `runCi` (non-blocking check failures
+  become fatal). The gate runs frozen, and the tree is re-checked for dirt
+  before anything publishes.
+
+### Commit gates, owned by the binary
+
+- `shipkit hooks install | list | pre-commit | commit-msg`. Built in: a leak
+  guard over a keyword file, and one commit-message predicate that rule SK009
+  also uses, replacing a copy kept in sync by hand. A repo adds its own gates
+  with `hooks: { preCommit: [{ id, cmd }] }` or `commitMsg`, and disables a
+  built-in by name. Hand-rolled hooks are invisible: a repo reports green while
+  its next commit is already doomed, and `shipkit hooks list` answers what
+  blocks a commit without anyone reading shell.
+
+### Discoverability and scaffolding
+
+- `shipkit commands [--json] [--out <file>] [--check]` prints every command the
+  binary registers, with every flag and a worked example. `--out` rewrites a
+  marked block inside a docs page and `--check` fails when that block is stale,
+  so a command added without a doc line cannot land.
+- `shipkit mv` renames code as well as md pages. A non-md path routes to the
+  ts-tools rename, which rewrites every path reference. Knowing WHICH rename
+  tool applies is exactly the doubt the toolkit exists to remove.
+- **BREAKING: a package.json script that only forwards to a shipkit verb is no
+  longer canon.** SK001 stops requiring `ci`, `check`, `contracts`, `tui`,
+  `mv`, `asks` and `assets:identity` scripts, and `shipkit init` no longer
+  scaffolds them. The verb is the vocabulary; an alias is one more name to keep
+  in sync. Only a body shipkit cannot express itself (`hub`, which needs watch
+  mode) stays a script.
+- SK001 asks for a `test` script only once the repo has test files. `bun test`
+  exits non-zero when it finds none, and a fixer must never manufacture a
+  failure.
+- SK007 (github visibility) blocks.
+
+## 0.15.0 — 2026-07-28
+
+- Hub: the `?needs=1` URL form is gone — the severity filter address is
+  `/?f=needs` · `/?f=red` only.
+- Assets (BREAKING): the exported `migrateCircle` is removed, and
+  `cleanRect` no longer reads the legacy rect `scale` key — session files
+  must carry `size` (a one-shot `"scale"` → `"size"` rename migrates old
+  files).
+- Comment cleanup across src (no behavior change).
+- check discovery: the self-cached heuristic recognizes `PageValidator`
+  (replacing the old subclass name) alongside `CheckSuite`.
+
 ## 0.14.0 — 2026-07-27
 
 New rule SK008 — the mandated reviewer agent type. A repo declares

package/README.md

@@ -1,9 +1,6 @@
 # rvlib-shipkit
 
-Repo toolkit for shipping: one config file gives a repo a commit gate
-(task DAG), release-contract fulfillness checks, a human ask queue,
-markdown-wiki tooling, and the asset atelier (generate, curate, and ship
-assets — favicon/logo/OG included).
+Repo toolkit for shipping: one config file gives a repo a commit gate (task DAG), release-contract fulfillness checks, a human ask queue, markdown-wiki tooling, and the asset atelier (generate, curate, and ship assets — favicon/logo/OG included).
 
 ```sh
 bun add -d rvlib-shipkit
@@ -22,8 +19,7 @@ export default defineRepo({
 })
 ```
 
-Health checks need no config at all: drop a `<name>.check.ts` file anywhere
-and `shipkit check` discovers and runs it (wire output + exit code).
+Health checks need no config at all: drop a `<name>.check.ts` file anywhere and `shipkit check` discovers and runs it (wire output + exit code).
 
 ## CLI
 
@@ -60,28 +56,16 @@ shipkit init      scaffold config + scripts, print the resolved floor
 shipkit start     ensure <root>/<name> + its CLAUDE.md include; prints the dir
 ```
 
-Output is a stable line protocol — `ok:` / `WARN` / `FAIL:` / `skip:` with
-indented `fix:` pointers — exit 0/1. Greppable by humans, parseable by
-agents, `--json` where structure helps.
+Output is a stable line protocol — `ok:` / `WARN` / `FAIL:` / `skip:` with indented `fix:` pointers — exit 0/1. Greppable by humans, parseable by agents, `--json` where structure helps.
 
 ## Release contracts
 
-A venue contract is data: required files, exact PNG dimensions (header-parsed,
-no image dependency), glob minimums, required markdown sections. Enforcement
-is both ways — a declared venue with an incomplete folder fails, and an
-undeclared venue whose signals fire (deploy scripts, folders) fails too.
-`exempt: { steam: "reason" }` skips visibly. Wire venue deploys as
-`deps: ['contracts']` and an incomplete folder physically blocks the upload.
+A venue contract is data: required files, exact PNG dimensions (header-parsed, no image dependency), glob minimums, required markdown sections. Enforcement is both ways — a declared venue with an incomplete folder fails, and an undeclared venue whose signals fire (deploy scripts, folders) fails too. `exempt: { steam: "reason" }` skips visibly. Wire venue deploys as `deps: ['contracts']` and an incomplete folder physically blocks the upload.
 
-Ship your own contracts via `contracts: { extra: [defineContract({...})] }`
-— see `rvlib-shipkit/contracts` for the rule vocabulary.
+Ship your own contracts via `contracts: { extra: [defineContract({...})] }` — see `rvlib-shipkit/contracts` for the rule vocabulary.
 
 ## Library use
 
-Everything the CLI does is importable: `runTasks`, `CheckSuite`,
-`evaluateContracts`, the asks queue, `scanMdGraph`/`lintMd`/`serveMdGraph`,
-and the assets surface (`defineKit`/`defineKind`, `identityKinds`,
-`studioRoutes`, `saveEndpoint` via `rvlib-shipkit/vite`).
-Ships TypeScript source; Bun ≥ 1.0.
+Everything the CLI does is importable: `runTasks`, `CheckSuite`, `evaluateContracts`, the asks queue, `scanMdGraph`/`lintMd`/`serveMdGraph`, and the assets surface (`defineKit`/`defineKind`, `identityKinds`, `studioRoutes`, `saveEndpoint` via `rvlib-shipkit/vite`). Ships TypeScript source. Bun ≥ 1.0.
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.14.0",
+    "version": "0.17.0",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
     "type": "module",

package/src/assets/kits/identity-kit.ts

@@ -37,7 +37,7 @@ export const OG_H = 630
 export const LOGO_SIZE = 1024
 
 /** the one next step when a comfy mark has no picked roll yet */
-export const NO_PICK_FIX = 'roll + pick in the studio: bun run assets → #identity-logo'
+export const NO_PICK_FIX = 'roll + pick in the studio: bun run hub → /assets/#identity-logo'
 
 export function identityKinds(brand: Brand): Kind[] {
     return [

package/src/assets/panels/geometry-rects.ts

@@ -20,11 +20,11 @@ export type GroundRect = {
 const r2 = (n: number): number => Math.round(n * 100) / 100
 const r3 = (n: number): number => Math.round(n * 1000) / 1000
 
-/** Normalize a possibly-legacy rect: fold `scale` into `size`, round
- *  (x/y/w/h 2dp, size 3dp, legs 2dp), ratio-lock h preserving center-y. */
+/** Normalize a rect: round (x/y/w/h 2dp, size 3dp, legs 2dp), ratio-lock h
+ *  preserving center-y. */
 export function cleanRect(raw: Record<string, unknown>, ratio: number): GroundRect {
     const num = (k: string, dflt: number): number => (typeof raw[k] === 'number' && Number.isFinite(raw[k]) ? (raw[k] as number) : dflt)
-    const size = typeof raw.size === 'number' ? (raw.size as number) : num('scale', 1) // legacy key folds in
+    const size = num('size', 1)
     const x = num('x', 0)
     const y = num('y', 0)
     const w = Math.max(1, num('w', 1))
@@ -68,17 +68,3 @@ export function defaultLegs(oval: GroundRect): LegRect[] {
         return { x: r2(cx + dx * u - lw / 2), y: r2(footY - lh), w: r2(lw), h: r2(lh) }
     })
 }
-
-/** Legacy circle → oval migration (run on session read). A circle is
- *  |h − w| ≤ 0.5. anchor: where the new oval's center-y comes from —
- *  'bottom' (characters/scenery: feet at circle bottom) or 'center'
- *  (buildings). artNormalized folds art-height units into oval-width units:
- *  size *= w / art. Non-circles pass through untouched. */
-export function migrateCircle(rect: GroundRect, opts: { ratio: number; anchor: 'bottom' | 'center'; artNormalized?: boolean }): GroundRect {
-    if (Math.abs(rect.h - rect.w) > 0.5) return rect
-    const cy = opts.anchor === 'bottom' ? rect.y + rect.h : rect.y + rect.h / 2
-    let size = rect.size
-    if (opts.artNormalized === true && rect.art != null && rect.art > 0) size = size * (rect.w / rect.art)
-    const h = rect.w * opts.ratio
-    return cleanRect({ ...rect, size, h, y: cy - h / 2 } as unknown as Record<string, unknown>, opts.ratio)
-}

package/src/assets/server/studio-server.ts

@@ -1,6 +1,6 @@
 // The studio HTTP server — roll variants, compare, pick, geometry metadata,
 // category grid data. 127.0.0.1 ONLY, forever. Watch-mode restarts drop the
-// in-memory queue — accepted tradeoff (his order 2026-07-23); `shipkit
+// in-memory queue — accepted tradeoff; `shipkit
 // assets fill` is the recovery path.
 //
 // ids/names are validated against the kit + the roll-file regex — no path

package/src/cli/cmd_Bump.ts

@@ -0,0 +1,61 @@
+// shipkit bump, version, changelog, gate, prepublish, commit, release, from
+// one word. Thin clipanion surface; logic in release/run-bump.ts.
+import { Command, Option } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { runBump, type BumpKind } from '../release/run-bump.ts'
+
+export class BumpCommand extends Command {
+    static override paths = [['bump']]
+
+    static override usage = Command.Usage({
+        category: 'Gate',
+        description: 'ship a version in one word: bumps a release unit (default the repo root), run from a feature branch it merges into the release branch first, then promotes the CHANGELOG Unreleased section, bumps package.json, runs the gate and every prepublish script, commits, tags, pushes, and cuts the release. Any failure before the version commit rolls the merge back and returns you to your branch.',
+        examples: [
+            ['a bugfix release of the repo itself', 'shipkit bump patch'],
+            ['a feature release', 'shipkit bump minor'],
+            ['a breaking release', 'shipkit bump major'],
+            ['one sub-unit (ids: shipkit releases)', 'shipkit bump minor rvlib-shipkit'],
+            ['a whole mixed batch in ONE gate, each unit at the kind its heading declares', 'shipkit bump --all'],
+            ['every unit that has Unreleased notes, all at the same kind', 'shipkit bump patch --all'],
+            ['one unit, kind from its own heading', 'shipkit bump rvlib-shipkit'],
+            ['rehearse the whole thing', 'shipkit bump minor --dry-run'],
+            ['bump and commit, release later', 'shipkit bump patch --no-release'],
+            ['from a feature branch, refuse rather than merge', 'shipkit bump patch --no-merge'],
+        ],
+    })
+
+    // both positionals are optional so `bump --all` can read each unit's own
+    // kind. The kinds are a closed set of three words, so a first positional
+    // that is not one of them is a unit id, never an ambiguity
+    kind = Option.String({ required: false })
+    unit = Option.String({ required: false })
+    dryRun = Option.Boolean('--dry-run', false, { description: 'rehearse: run every preflight, the gate and the prepublish scripts, then stop before any version is written. the gate can rewrite files, and the merge is probed rather than performed, so the release branch never moves' })
+    noRelease = Option.Boolean('--no-release', false, { description: 'stop after the version commit, do not tag or publish' })
+    noMerge = Option.Boolean('--no-merge', false, { description: 'refuse on a feature branch instead of merging it into the release branch' })
+    all = Option.Boolean('--all', false, { description: 'bump every unit whose changelog carries Unreleased notes, in declared order, root last. Given a kind it applies to ALL of them. Given none, each unit takes the kind from its own "## Unreleased (minor)" heading, and a unit whose heading is silent refuses' })
+
+    async execute(): Promise<number> {
+        const KINDS = ['major', 'minor', 'patch']
+        // `bump rvlib-shipkit` names a unit and leaves the kind to its heading
+        const kind = this.kind != null && KINDS.includes(this.kind) ? (this.kind as BumpKind) : null
+        const unit = kind == null && this.kind != null ? this.kind : this.unit
+        if (kind == null && this.kind != null && this.unit != null) {
+            this.context.stderr.write(`FAIL: bump takes major, minor or patch (got '${this.kind}')\n`)
+            return 1
+        }
+        try {
+            const config = await loadRepoConfig(process.cwd())
+            return await runBump(process.cwd(), config, kind, {
+                dryRun: this.dryRun,
+                noRelease: this.noRelease,
+                noMerge: this.noMerge,
+                unit,
+                all: this.all,
+                print: (l) => this.context.stdout.write(`${l}\n`),
+            })
+        } catch (e) {
+            this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+            return 1
+        }
+    }
+}

package/src/cli/cmd_Check.ts

@@ -6,11 +6,11 @@ import { runCheck } from '../core/run-check.ts'
 import { runFix } from '../rules/run-fix.ts'
 
 export class CheckCommand extends Command {
-    static override paths = [['check']]
+    static override paths = [['check'], ['doctor']]
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'periodic health: SK rules + every *.check.ts in the repo (auto-discovered, run as subprocesses), clean passes replay from a TTL cache; --fix applies rule autofixes',
+        description: 'the checks alone, without the build tasks. `shipkit ci` runs these too and is what you normally want. --fix applies rule autofixes',
         examples: [
             ['run (cached where valid)', 'shipkit check'],
             ['bust every cache layer', 'shipkit check --fresh'],

package/src/cli/cmd_Ci.ts

@@ -8,9 +8,11 @@ export class CiCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'commit gate: floor + contracts + repo tasks through the DAG runner',
+        description: 'THE command. Repairs what a machine can (formatter, imports, repo shape), runs every task, then every check. A check that declares blocking:false warns instead of failing. Run this instead of anything else.',
         examples: [
-            ['full gate', 'shipkit ci'],
+            ['full gate, mechanical fixes applied', 'shipkit ci'],
+            ['gate without the repair pass (checks can still write)', 'shipkit ci --no-fix'],
+            ['leave repo config files alone', 'shipkit ci --no-fix-rules'],
             ['stop at the first failure', 'shipkit ci --bail'],
             ['one task + its dep closure', 'shipkit ci --only typecheck'],
             ['include an opt-in task', 'shipkit ci --with up:itch'],
@@ -19,6 +21,9 @@ export class CiCommand extends Command {
 
     bail = Option.Boolean('--bail', false, { description: 'stop at the first failure' })
     json = Option.Boolean('--json', false, { description: 'machine-readable result instead of wire lines' })
+    fix = Option.Boolean('--fix', true, { description: 'repair the mechanical slots before gating. Default on. --no-fix skips the repair pass, checks can still write. Under CI the fixers still run but the gate FAILS on any file they rewrite' })
+    fixRules = Option.Boolean('--fix-rules', true, { description: 'apply the structural rule autofixes too. Default on. --no-fix-rules leaves repo config alone' })
+    frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for self-maintaining rules (SK005 never touches package.json). STATUS.md is still refreshed, so no combination of flags makes the run write nothing' })
     skip = Option.Array('--skip', [], { description: 'skip a task group (repeatable)' })
     withIds = Option.Array('--with', [], { description: 'include an opt-in task (repeatable)' })
     only = Option.Array('--only', [], { description: 'run only this task + its dep closure (repeatable)' })
@@ -28,6 +33,9 @@ export class CiCommand extends Command {
             return await runCi(process.cwd(), {
                 bail: this.bail,
                 json: this.json,
+                fix: this.fix,
+                fixRules: this.fixRules,
+                frozen: this.frozen,
                 skipGroups: this.skip,
                 withIds: this.withIds,
                 onlyIds: this.only,

package/src/cli/cmd_Commands.ts

@@ -0,0 +1,126 @@
+// the binary describing itself, in markdown. a hand-copied command list
+// drifts the moment a flag changes, and then teaches commands that do not
+// exist. rendering the live registry makes the doc a build artifact.
+import { Command, Option } from 'clipanion'
+
+export type CommandOption = { definition: string; description: string }
+export type CommandRow = {
+    path: string
+    category: string
+    description: string
+    usage: string
+    options: CommandOption[]
+    examples: [string, string][]
+}
+
+export type Definition = {
+    path: string
+    category?: string | null
+    description?: string | null
+    usage?: string | null
+    examples?: [string, string][] | null
+    options?: { definition?: string; description?: string | null }[] | null
+}
+
+// clipanion renders a value placeholder as `#0`, which nobody can type
+const clean = (s: string | null | undefined): string => (s ?? '').trim().replace(/\s+/g, ' ').replace(/ #\d+\b/g, ' <value>')
+
+/** rows from the live registry, builtins dropped, sorted by category then path.
+ *  clipanion splits what we need across two calls: the plain form carries the
+ *  examples, the detailed form carries the flags. Merge by path, or the page
+ *  ends up showing a command with no arguments, which is the state that sends
+ *  an agent to `--help` before it can act. */
+export function commandRows(plain: Definition[], detailed: Definition[] = []): CommandRow[] {
+    const flagsByPath = new Map(detailed.map((d) => [d.path, d.options ?? []]))
+    return plain
+        .filter((d) => !/^shipkit (--help|-h|--version|-v)$/.test(d.path))
+        .map((d) => ({
+            path: d.path.replace(/^shipkit /, ''),
+            category: clean(d.category) || 'Other',
+            // verbatim from the CLI so the doc cannot say something it does not
+            description: clean(d.description),
+            usage: clean(d.usage),
+            options: (flagsByPath.get(d.path) ?? [])
+                .map((o) => ({ definition: clean(o.definition), description: clean(o.description) }))
+                .filter((o) => o.definition !== ''),
+            examples: (d.examples ?? []).map(([label, cmd]) => [clean(label), clean(cmd)] as [string, string]),
+        }))
+        .sort((a, b) => a.category.localeCompare(b.category) || a.path.localeCompare(b.path))
+}
+
+/** the markdown block: per command, the real invocation with its arguments and
+ *  flags, then a worked example. A name and a sentence are not enough to act
+ *  on: an agent that cannot see the arguments either guesses them or runs
+ *  `--help` first, and both are the waste this page exists to remove. */
+export function renderMarkdown(rows: CommandRow[]): string {
+    const out: string[] = []
+    let cat = ''
+    for (const r of rows) {
+        if (r.category !== cat) { cat = r.category; out.push(`\n### ${cat}\n`) }
+        const sig = r.usage.replace(/^\$0/, 'shipkit').trim() || `shipkit ${r.path}`
+        const flags = r.options.map((o) => `[${o.definition}]`).join(' ')
+        // one line per bullet: a description on its own indented line reads as
+        // hard-wrapped prose to the house lint
+        out.push(`- \`${sig}${flags === '' ? '' : ` ${flags}`}\` — ${r.description}`)
+        for (const o of r.options) if (o.description !== '') out.push(`  - \`${o.definition}\` ${o.description}`)
+        for (const [label, cmd] of r.examples) out.push(`  - ${label}: \`${cmd}\``)
+    }
+    return out.join('\n').trim()
+}
+
+export const BEGIN = '<!-- shipkit:commands -->'
+export const END = '<!-- /shipkit:commands -->'
+
+/** replace the marked block in a host file. Returns null when the markers are
+ *  missing, so a renamed or hand-mangled host fails loud instead of silently
+ *  writing nothing. */
+export function spliceBlock(host: string, block: string): string | null {
+    const a = host.indexOf(BEGIN)
+    const b = host.indexOf(END)
+    if (a === -1 || b === -1 || b < a) return null
+    return `${host.slice(0, a + BEGIN.length)}\n\n${block}\n\n${host.slice(b)}`
+}
+
+export class CommandsCommand extends Command {
+    static override paths = [['commands']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'every command this binary registers, as markdown or json — the source a docs page is generated FROM, never hand-copied',
+        examples: [
+            ['markdown index', 'shipkit commands'],
+            ['machine-readable', 'shipkit commands --json'],
+            ['write into a docs page between the markers', 'shipkit commands --out wiki/build/shipkit-cli.md'],
+            ['fail if that page is stale (lint mode)', 'shipkit commands --out wiki/build/shipkit-cli.md --check'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'machine-readable [{path, category, description}]' })
+    out = Option.String('--out', { description: 'host file carrying the shipkit:commands markers. The block between them is rewritten' })
+    check = Option.Boolean('--check', false, { description: 'with --out: exit 1 if the block is stale, write nothing' })
+
+    async execute(): Promise<number> {
+        const rows = commandRows(
+            this.cli.definitions() as Definition[],
+            (this.cli.definitions as (o?: { detailed?: boolean }) => Definition[])({ detailed: true }),
+        )
+        if (this.out == null) {
+            this.context.stdout.write(this.json ? `${JSON.stringify(rows)}\n` : `${renderMarkdown(rows)}\n`)
+            return 0
+        }
+        const { existsSync, readFileSync, writeFileSync } = await import('fs')
+        if (!existsSync(this.out)) { this.context.stdout.write(`FAIL: ${this.out} does not exist\n`); return 1 }
+        const host = readFileSync(this.out, 'utf8')
+        const next = spliceBlock(host, renderMarkdown(rows))
+        if (next == null) { this.context.stdout.write(`FAIL: ${this.out} has no ${BEGIN} / ${END} markers\n`); return 1 }
+        if (next === host) { this.context.stdout.write(`ok: ${this.out} command index current (${rows.length} commands)\n`); return 0 }
+        if (this.check) {
+            this.context.stdout.write(`FAIL: ${this.out} command index is STALE — the binary registers commands the page does not list\n`)
+            this.context.stdout.write(`      fix: shipkit commands --out ${this.out}\n`)
+            return 1
+        }
+        writeFileSync(this.out, next)
+        this.context.stdout.write(`ok: ${this.out} command index rewritten (${rows.length} commands)\n`)
+        return 0
+    }
+}

package/src/cli/cmd_Hooks.ts

@@ -0,0 +1,66 @@
+// shipkit hooks, install the git hooks, run their gates, or list what
+// blocks a commit. Thin clipanion surface; logic in hooks/run-hooks.ts.
+import { Command, Option } from 'clipanion'
+import { installHooks, listGates, runCommitMsg, runPreCommit, type GateOutcome } from '../hooks/run-hooks.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+
+const report = (out: GateOutcome[], write: (s: string) => void): number => {
+    for (const g of out) for (const l of g.lines) write(`${l}\n`)
+    return out.every((g) => g.ok) ? 0 : 1
+}
+
+export class HooksInstallCommand extends Command {
+    static override paths = [['hooks', 'install']]
+    static override usage = Command.Usage({
+        category: 'Gate',
+        description: 'write hooks/pre-commit + hooks/commit-msg and point core.hooksPath at them (idempotent)',
+        examples: [['wire the hooks', 'shipkit hooks install']],
+    })
+
+    bin = Option.String('--bin', 'bunx rvlib-shipkit', { description: 'how the hook body invokes shipkit (in-repo consumers pass `bun <path to cli.ts>`)' })
+
+    async execute(): Promise<number> {
+        const r = installHooks(process.cwd(), this.bin)
+        for (const w of r.written) this.context.stdout.write(`ok: wrote ${w}\n`)
+        if (r.written.length === 0) this.context.stdout.write('ok: hook bodies already current\n')
+        this.context.stdout.write(`${r.note.startsWith('WARN') ? r.note : `ok: ${r.note}`}\n`)
+        return r.note.startsWith('WARN') ? 1 : 0
+    }
+}
+
+export class HooksPreCommitCommand extends Command {
+    static override paths = [['hooks', 'pre-commit']]
+    static override usage = Command.Usage({ category: 'Gate', description: 'run the pre-commit gate (called by the hook)' })
+
+    async execute(): Promise<number> {
+        const config = await loadRepoConfig(process.cwd())
+        return report(await runPreCommit(process.cwd(), config), (s) => this.context.stdout.write(s))
+    }
+}
+
+export class HooksCommitMsgCommand extends Command {
+    static override paths = [['hooks', 'commit-msg']]
+    static override usage = Command.Usage({ category: 'Gate', description: 'run the commit-message gate (called by the hook)' })
+
+    file = Option.String({ required: true })
+
+    async execute(): Promise<number> {
+        const config = await loadRepoConfig(process.cwd())
+        return report(await runCommitMsg(process.cwd(), config, this.file), (s) => this.context.stdout.write(s))
+    }
+}
+
+export class HooksListCommand extends Command {
+    static override paths = [['hooks', 'list']]
+    static override usage = Command.Usage({
+        category: 'Gate',
+        description: 'what blocks a commit in this repo, built-ins and repo-declared',
+        examples: [['list the gates', 'shipkit hooks list']],
+    })
+
+    async execute(): Promise<number> {
+        const config = await loadRepoConfig(process.cwd())
+        for (const l of listGates(config, process.cwd())) this.context.stdout.write(`${l}\n`)
+        return 0
+    }
+}

package/src/cli/cmd_Mv.ts

@@ -1,27 +1,50 @@
-// shipkit mv — md-page rename with repo-wide ref sweep. Thin clipanion
-// surface; logic in mv/mv-md.ts.
+// shipkit mv, ONE rename command for the whole repo. An md page routes to
+// mv/mv-md.ts (page + sibling asset dir + check.ts + every tracked ref);
+// anything else routes to rvlib-ts-tools' rename, which rewrites every path
+// reference in the code. Renaming used to mean knowing WHICH tool applied,
+// and knowing that is exactly the kind of doubt the toolkit exists to remove.
 import { Command, Option } from 'clipanion'
+import { fileURLToPath } from 'url'
 import { movePage } from '../mv/mv-md.ts'
+import { spawnWithTimeout } from '../core/spawn-timeout.ts'
 
 export class MvCommand extends Command {
     static override paths = [['mv']]
 
     static override usage = Command.Usage({
-        category: 'Wiki',
-        description: 'rename an md page + sibling dir + check.ts, sweeping every tracked ref; renames must be CHEAP',
+        category: 'Refactor',
+        description: 'rename anything and sweep every reference: an md page (plus its sibling dir and check.ts) or a code file or folder. Dry run by default. Renames must be CHEAP',
         examples: [
-            ['dry run (default): show what would change', 'shipkit mv docs/old-name.md docs/new-name.md'],
+            ['dry run, the default, shows what changes', 'shipkit mv docs/old-name.md docs/new-name.md'],
+            ['apply it', 'shipkit mv docs/old-name.md docs/new-name.md --write'],
             ['apply + one conventional commit', 'shipkit mv docs/old-name.md docs/new-name.md --commit'],
+            ['a code file, every import rewritten', 'shipkit mv src/old-mod.ts src/new-mod.ts --write'],
+            ['a whole folder', 'shipkit mv src/old-dir src/new-dir --write'],
         ],
     })
 
     oldPath = Option.String()
     newPath = Option.String()
     write = Option.Boolean('--write', false, { description: 'apply (default is a dry run)' })
-    commit = Option.Boolean('--commit', false, { description: 'apply + git commit (pre-commit hook is the gate)' })
+    commit = Option.Boolean('--commit', false, { description: 'apply + git commit, md pages only (the pre-commit gate still runs)' })
 
     async execute(): Promise<number> {
+        const write = this.write || this.commit
         try {
+            const isMd = this.oldPath.endsWith('.md') || this.newPath.endsWith('.md')
+            if (!isMd) {
+                if (this.commit) {
+                    this.context.stderr.write('FAIL: --commit is md-only for now — run with --write, then commit\n')
+                    return 1
+                }
+                let cli: string
+                try { cli = fileURLToPath(import.meta.resolve('rvlib-ts-tools/src/cli.ts')) }
+                catch { this.context.stderr.write('FAIL: rvlib-ts-tools is unresolvable — reinstall shipkit deps\n'); return 1 }
+                const r = await spawnWithTimeout(['bun', cli, 'rename', this.oldPath, this.newPath, ...(write ? ['--apply'] : [])], { cwd: process.cwd(), timeoutMs: 120_000 })
+                this.context.stdout.write(r.out)
+                if (!write && r.code === 0) this.context.stdout.write('note: dry run — pass --write to apply\n')
+                return r.code
+            }
             return movePage(process.cwd(), this.oldPath, this.newPath, {
                 print: (l) => this.context.stdout.write(`${l}\n`),
                 printErr: (l) => this.context.stderr.write(`${l}\n`),