@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/josh/josh-commands-run.ts

@@ -1,4 +1,11 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
+import { PAUSE_COMMANDS } from './josh-commands-pause'
+import { PROGRESS_COMMANDS } from './josh-commands-progress'
+
+const OWNER = '--owner <pid>'
+const OUTPUT = '--output <path>'
+const REPO_FLAG = { names: ['--repo <owner/name>'], description: 'a child in another repository.' }
+const ISSUE = { arguments: '<N>' }
 
 // The run-lifecycle registry (`run:hold` through `run:step`), split out of `josh-commands-ai.ts` so
 // that file stays under its 300-code-line limit, as `BACKLOG_COMMANDS` and `LANE_COMMANDS` are. It
@@ -6,7 +13,7 @@ import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types
 // order.
 
 // One script answers both `run:hold` and `run:release`; the flag below is what tells them apart.
-const RUN_HOLD_SCRIPT = 'scripts/run/hold/run-hold-cli.ts'
+const RUN_HOLD_SCRIPT = 'scripts/run/hold/run-hold-main.ts'
 
 /* eslint-disable @typescript-eslint/naming-convention */
 const RUN_COMMANDS: Record<string, CommandEntry> = {
@@ -14,20 +21,72 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 		script: RUN_HOLD_SCRIPT,
 		description: 'Claim this working tree for a run, or say which run already holds it',
 		category: 'AI tools',
-		reference: ['[<issue> [--fullrun | --halfrun-stop | --prrun-stop]]', 'automation', ['files']],
+		// A `--halfrun-stop` / `--human-review-stop` / `--prrun-stop` sends the stop confirmation.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		reference: [
+			'[<issue> [--fullrun | --halfrun-stop | --human-review-stop | --prrun-stop]] | --adopt <issue>',
+			'automation',
+			['files'],
+		],
+		usage: {
+			examples: [
+				{ arguments: '1091', note: 'claim for issue 1091' },
+				{ arguments: '1091 --fullrun', note: 'claim as `fullrun #1091` (what `run:entry` runs)' },
+				{ arguments: '--adopt 1091', note: "hand a `new` run's hold to the issue it filed" },
+			],
+			flags: [
+				{ names: ['--fullrun'], description: "marks the record as `fullrun #N`'s." },
+				{
+					names: ['--adopt <issue>'],
+					description:
+						"re-keys the unnumbered `new` run's record to the filed issue and applies `in-progress`; answers `none` (exit 1) when the tree holds no record.",
+				},
+				{
+					names: ['--halfrun-stop'],
+					description:
+						'marks a `halfrun` stop for `run:entry` to adopt, and sends its `confirmation` Telegram; answers `e2e-owed` (exit 1) until `test:e2e` answered green on this tree.',
+				},
+				{
+					names: ['--human-review-stop'],
+					description:
+						'marks a `needs-human-review` stop as a `halfrun` stop, and sends its `confirmation` Telegram naming the lane; answers `e2e-owed` (exit 1) until `test:e2e` answered green on this tree.',
+				},
+				{
+					names: ['--prrun-stop'],
+					description:
+						'marks a `prrun` stop with the commit its pull request is on, and sends its `confirmation` Telegram.',
+				},
+			],
+		},
 	},
 	'run:release': {
 		script: RUN_HOLD_SCRIPT,
 		description: "Release this working tree's run record",
 		category: 'AI tools',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		reference: ['[issue|--force]', 'automation', ['files']],
 		default_script_arguments: ['--release'],
+		usage: {
+			examples: [
+				{ arguments: '1091', note: "release this run's own record" },
+				{ arguments: '--force', note: 'clear a record left by a run that has ended' },
+			],
+			flags: [
+				{
+					names: ['--force'],
+					description:
+						"removes a record this run did not write, clearing another run's stale claim.",
+				},
+			],
+		},
 	},
+	...PAUSE_COMMANDS,
 	'run:tidy': {
-		script: 'scripts/run/tidy/run-tidy-cli.ts',
+		script: 'scripts/run/tidy/run-tidy-main.ts',
 		description: 'Close merged lanes and drop stashes whose issues are all merged',
 		category: 'AI tools',
 		reference: ['', 'automation', ['git', 'network', 'files']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	'run:carry': {
 		script: 'scripts/run/carry/run-carry-cli.ts',
@@ -37,15 +96,70 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Carry one invocation’s budget across its own session cuts',
 		category: 'AI tools',
 		reference: ['<operation> [arguments...]', 'automation', ['files']],
+		usage: {
+			examples: [
+				{ arguments: '--begin "backlogrun --max 5" --owner "$PPID"' },
+				{ arguments: '--json', note: 'read the record back in a resumed session' },
+				{ arguments: '--cut --owner "$PPID"', note: 'hand the record off before a cut' },
+				{
+					arguments:
+						'--retrospective --summary "0 filed; dropped #2240 already merged" --owner "$PPID"',
+					note: 'close the end-of-run retrospective',
+				},
+				{
+					arguments: '--resume "backlogrun --max 5" --owner "$PPID"',
+					note: 'adopt a record no cut handed off',
+				},
+				{
+					arguments: '--end --stopped "epic #2126: everything is blocked behind parked #2118"',
+					note: 'end + push',
+				},
+			],
+			flags: [
+				{
+					names: [OWNER],
+					description:
+						'the long-lived process spending the budget (`$PPID` under a loop); required by counts and `--begin` / `--resume`. A live PID stays `busy` if probes fail.',
+				},
+				{ names: ['--done <issue>'], description: "shrinks a named-issue run's `remaining` list." },
+				{
+					names: ['--merged <issue>'],
+					description:
+						'names the merged issue and counts it once against `merged_issues`, so a merge `run:merge` already recorded is not counted twice.',
+				},
+				{ names: ['--filed', '--cut'], description: 'increments, never totals.' },
+				{
+					names: ['--retrospective'],
+					description:
+						"marks the end-of-run retrospective run, once per invocation, and requires `--summary <text>` — the same close writes that result as one `retrospective` event on the run's event stream (best-effort), so a run that filed zero improvements reads apart from one whose retrospective never ran. Either flag without the other is refused.",
+				},
+				{
+					names: ['--stopped <reason>'],
+					description:
+						'rides on `--end`: the run stopped rather than finished, so one ⏸️ confirmation is pushed with the reason.',
+				},
+				{
+					names: ['--end'],
+					description:
+						'over a live record flushes pending ledger lines once (a failed flush goes to stderr and the record is still cleared); first collects each lane the run launched whose issue merged, exactly as `run:merge` would; keeps the run it removes as the last ended run — its invocation, start and end, one record overwritten by the next `--end` — so `run:board` can still draw a finished run.',
+				},
+			],
+		},
 	},
 	'run:add': {
 		script: 'scripts/run/add/run-add-cli.ts',
 		description: 'Add issues to a live backlogrun, ahead of the queue unless --no-priority',
 		category: 'AI tools',
 		reference: ['<issue...> [--no-priority]', 'automation', ['network', 'files']],
+		usage: {
+			examples: [
+				{ arguments: '101 102', note: 'ahead of the rest of the queue (`#N` works too)' },
+				{ arguments: '101 --no-priority', note: 'at the end of the queue' },
+			],
+		},
 	},
 	'run:wake': {
-		script: 'scripts/run/wake/run-wake-cli.ts',
+		script: 'scripts/run/wake/run-wake-main.ts',
 		// `.env` rather than the ambient environment:
 		// the failure warning needs the Telegram credentials, the same
 		// reasons `notify` and `followup` carry these flags.
@@ -53,48 +167,105 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Wake the next session of a cut backlogrun from outside the conversation',
 		category: 'AI tools',
 		reference: ['[options]', 'automation', ['processes', 'notifications']],
+		usage: {
+			examples: [
+				{ arguments: '--start', note: 'launch the detached supervisor' },
+				{ arguments: '--list', note: 'supervisor state, cut/wake counts, latest progress line' },
+				{ arguments: '--stop', note: 'stop the supervisor alone' },
+				{ arguments: '--loop --interval 30', note: 'run the loop body in the foreground' },
+			],
+		},
 	},
 	'run:cut': {
 		script: 'scripts/run/cut/run-cut-cli.ts',
 		description: 'Cut a lane child before the gate and resume a fresh process',
 		category: 'AI tools',
 		reference: ['[--resume] <issue> [--impl] [--handoff <path>]', 'automation', ['files']],
+		usage: {
+			examples: [
+				{ arguments: '1839', note: 'take the cut and hand it to a fresh process' },
+				{
+					arguments: '--impl 1839 --handoff .josh/tmp/handoff-1839.json',
+					note: 'cut mid-implementation, carrying the instruction',
+				},
+				{ arguments: '--resume 1839', note: "a fresh process's entry check" },
+				{ arguments: '--end', note: 'clear the record' },
+			],
+		},
+	},
+	'run:park': {
+		script: 'scripts/run/park/run-park-cli.ts',
+		description: 'Park a lane child for a decision, or clear the park',
+		category: 'AI tools',
+		reference: ['<issue> --body-file <path> | <issue> --clear', 'automation', ['files', 'network']],
+		usage: {
+			examples: [
+				{
+					arguments: '1839 --body-file .josh/tmp/park-1839.md',
+					note: 'comment, needs-decision and the local record',
+				},
+				{ arguments: '1839 --clear', note: 'remove needs-decision and the record' },
+			],
+		},
 	},
 	'run:liveness': {
 		script: 'scripts/run/run-liveness-cli.ts',
 		description: 'Say whether a delegated unit is still working, or stopped without reporting',
 		category: 'AI tools',
 		reference: ['<issue> --output <path> [options]', 'automation', ['processes']],
+		usage: {
+			examples: [
+				{ arguments: '1169 --output <path>' },
+				{ arguments: '1169 --output <path> --window 45 --gap 2 --repo joshuafolkken/app-kit' },
+			],
+			flags: [
+				{
+					names: [OUTPUT],
+					description:
+						'absolute, under the home or temp directory; a symlink is followed and size compared as well as mtime.',
+				},
+				{
+					names: ['--process alive | none'],
+					description:
+						"overrides the process trace, which the command otherwise reads itself: the child's own command line (`fullrun #<N>`) or its detached ship supervisor.",
+				},
+				{
+					names: ['--window <min>'],
+					description: 'silent window the file must be frozen for (default 30).',
+				},
+				{ names: ['--gap <sec>'], description: 'spacing between samples (default 5).' },
+				REPO_FLAG,
+			],
+		},
 	},
 	'run:ending': {
 		script: 'scripts/run/run-ending-cli.ts',
 		description: 'Classify how a dispatched lane child ended (merged, cut, abandoned, unreadable)',
 		category: 'AI tools',
 		reference: ['<issue> --output <path> [--repo <owner/repo>]', 'automation', ['network']],
+		usage: {
+			examples: [
+				{ arguments: '2118 --output <path>' },
+				{ arguments: '2118 --output <path> --repo joshuafolkken/app-kit' },
+			],
+			flags: [
+				{
+					names: [OUTPUT],
+					description:
+						"the child's transcript, absolute and under the home or temp directory (validated the same way `run:liveness --output` is).",
+				},
+				REPO_FLAG,
+			],
+		},
 	},
-	'run:progress': {
-		script: 'scripts/run/progress/run-progress-cli.ts',
-		description: 'Report an unattended run’s progress once it has gone quiet for an interval',
-		category: 'AI tools',
-		reference: [
-			'[--once | --wait] [--interval <minutes>] [--hours <hours>] [--repo <owner/repo>] [--output <path>] | --mark | --path',
-			'automation',
-			['files'],
-		],
-	},
-	'run:board': {
-		script: 'scripts/run/board/run-board-cli.ts',
-		// `--every` pushes its frame as a Telegram, so the credentials come from `.env` as for `run:carry`.
-		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
-		description: 'Draw a live board of the running backlogrun, redrawn every second',
-		category: 'AI tools',
-		reference: ['[--once | --chat | --every <minutes>]', 'automation', ['files', 'network']],
-	},
+	...PROGRESS_COMMANDS,
 	'run:prep': {
-		script: 'scripts/run/run-prep-cli.ts',
+		script: 'scripts/run/run-prep-main.ts',
 		description: 'Bundle a run’s pre-edit reads: body, comments, state, dependency scope',
 		category: 'AI tools',
 		reference: ['<issue>', 'automation', ['network']],
+		is_bundled: true,
+		usage: { examples: [ISSUE] },
 	},
 	// The entry sequence a lane opened on, folded into one call: claim the tree,
 	// read the budget, gather the issue reads and decide the pre-implementation step. `run:hold`,
@@ -107,18 +278,28 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 			'Open a run in one call: claim the tree, read the budget, bundle the reads, decide the pre-implementation step',
 		category: 'AI tools',
 		reference: ['<issue> [--to <command>]', 'automation', ['git', 'network', 'files']],
+		usage: {
+			examples: [
+				{ arguments: '<N>', note: 'a `fullrun`' },
+				{ arguments: '<N> --to halfrun', note: 'a run that goes as far as `halfrun`' },
+			],
+		},
 	},
 	'run:status': {
 		script: 'scripts/run/run-status-cli.ts',
 		description: 'Bundle a run’s read-only status: issue state, cost verdict, carry counters',
 		category: 'AI tools',
 		reference: ['<issue> [--repo <owner/repo>]', 'automation', ['network']],
+		usage: {
+			examples: [ISSUE, { arguments: '<N> --repo <owner/repo>', note: 'a cross-repo child' }],
+		},
 	},
 	'run:next': {
 		script: 'scripts/run/run-next-cli.ts',
 		description: 'Print the next step a fullrun takes, computed from the run’s state',
 		category: 'AI tools',
 		reference: ['<issue>', 'automation', ['network']],
+		usage: { examples: [ISSUE] },
 	},
 	'run:step': {
 		script: 'scripts/run/run-step-cli.ts',
@@ -126,6 +307,13 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 			'Print the run’s next single action, computed from the event stream, carry record and issue state',
 		category: 'AI tools',
 		reference: ['[<issue>]', 'automation', ['network', 'files']],
+		is_bundled: true,
+		usage: {
+			examples: [
+				{ arguments: '<N>', note: "the run's next action for issue <N>" },
+				{ arguments: '', note: "the `backlogrun` parent's next action" },
+			],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

package/scripts/josh/josh-commands-ship.ts

@@ -0,0 +1,169 @@
+import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
+
+const OUTPUT = '--output <path>'
+const OWNER = '--owner <pid>'
+const ISSUE_WITH_OPTIONS = '<issue> [options]'
+
+// The merge, review-launch, tail and ship commands, split out of `josh-commands-ai.ts` when each
+// command's usage moved onto its entry (#4185). `AI_COMMANDS` spreads this in at the same place, so the
+// map keeps its order.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const SHIP_COMMANDS: Record<string, CommandEntry> = {
+	'run:merge': {
+		script: 'scripts/run/merge/run-merge-main.ts',
+		description:
+			'Collapse a backlogrun merge event into one call: confirm the child, do the post-merge steps, offer the next child',
+		category: 'AI tools',
+		reference: [ISSUE_WITH_OPTIONS, 'automation', ['git', 'network']],
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		usage: {
+			examples: [
+				{
+					arguments: '<N> --epic <E> --repo <owner/repo> --owner "$PPID" --output <path>',
+					note: 'prints the next child number, or a verdict',
+				},
+				{ arguments: '<N> --owner "$PPID"', note: 'backlog offer (no epic)' },
+			],
+			flags: [
+				{
+					names: ['--epic <E>', '--repo <owner/repo>'],
+					description: "offer the epic's next children; omit both for the opted-in backlog.",
+				},
+				{
+					names: [OWNER],
+					description: "the parent's process, so the carry count respects the ownership guard.",
+				},
+				{
+					names: [OUTPUT],
+					description: 'the transcript the outage split reads; absent, it is off.',
+				},
+				{
+					names: ['--driver'],
+					description:
+						'the caller is `backlog:drive`, which has no context to cut and asks `backlog:offer` itself, so the merge is never handed back `over` and answers `deferred` in place of the next offer.',
+				},
+			],
+		},
+	},
+	'run:review': {
+		script: 'scripts/run/review/run-review-cli.ts',
+		description:
+			'Start the gate in the background and print the /code-review brief in one call so the two overlap (--join to join the gate and check its verdict)',
+		category: 'AI tools',
+		reference: ['[--join]', 'automation', ['processes', 'files']],
+		usage: {
+			examples: [
+				{
+					arguments: '',
+					note: 'detach the gate, print the brief; then launch the /code-review subagent',
+				},
+				{ arguments: '--join', note: 'after the review returns: join the gate, check its verdict' },
+			],
+		},
+	},
+	// The post-merge sequence a run closed on, folded into one call: commit the
+	// observation ledger, read the completion citations and decide the release scope. `observations:flush`,
+	// `issue:cite` and `release:scope` were three round trips re-billing the run's full context each.
+	'run:tail': {
+		script: 'scripts/run/run-tail-cli.ts',
+		description:
+			'Close a run in one call: return to the default branch, commit the observation ledger, read the citations, decide the release scope',
+		category: 'AI tools',
+		reference: ['[<issue> ...]', 'automation', ['git', 'network']],
+		usage: {
+			examples: [
+				{ arguments: '<N>', note: 'the closed issue' },
+				{ arguments: '<N> <follow-up-N>', note: 'and a follow-up filed this run' },
+			],
+		},
+	},
+	// The commit-to-report region a run ships a change on, folded into one call:
+	// the gate, the commit/push/PR (`git -y`), the CI-wait merge (`followup`) and the report bookkeeping
+	// (`run:tail`) were four round trips re-billing the run's full context each. It stops at the first
+	// failed step and names it, so the run reads only the step to fix.
+	ship: {
+		script: 'scripts/run/ship/run-ship-cli.ts',
+		// `.env` rather than the ambient environment: parking a lane child past the relaunch cap
+		// sends a Telegram warning, which needs the credentials.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Ship a change in one call: gate, commit/push/PR, the CI-wait merge and the report bookkeeping, stopping at the first failed step',
+		category: 'AI tools',
+		reference: [
+			'"<title> #<N>" [<follow-up-N> ...] [--cite <N>] [--review] [--detach] [--body-file <path>] [--notify-message <text> | --notify-message-file <path>] | --log <N>',
+			'automation',
+			['git', 'network'],
+		],
+		usage: {
+			examples: [
+				{ arguments: '"<title> #<N>" --body-file <evidence.md>' },
+				{ arguments: '"<title> #<N>" --review', note: 'both review rounds inside the ship' },
+				{ arguments: '--detach "<title> #<N>"', note: 'hand the ship to a supervisor' },
+				{ arguments: '--log <N>', note: "a detached ship's log" },
+			],
+			flags: [
+				{
+					names: ['--body-file <path>'],
+					description:
+						'the PR body carrying the live-execution evidence `followup` gates on; forwarded to `git -y` alone.',
+				},
+				{ names: ['--notify-message <text>'], description: 'forwarded to `followup` alone.' },
+				{
+					names: ['--review'],
+					description:
+						'runs review round 1 beside the gate, and round 2 after the commit when `review:round2` requires it; a High or an unfixed Medium stops the ship.',
+				},
+				{
+					names: ['--detach'],
+					description:
+						'hands the ship to a supervisor (implied in a lane child); a stop emits `ship-stop` (`--log <N>`). The preflight, type check, unused exports, cspell and guard tests run before the hand-off, the checks even after a preflight refusal, so one stop reports every failure; a stop returns to the same session.',
+				},
+			],
+		},
+	},
+	'run:event': {
+		script: 'scripts/run/event/run-event-cli.ts',
+		description:
+			'Append to, read or watch the run’s append-only event stream (--append <kind> <text> | --from|--follow <n> | --watch [<n>] | --last)',
+		category: 'AI tools',
+		reference: [
+			'--append <kind> <text> | --from|--follow <n> | --watch [<n>] | --last',
+			'automation',
+			['files'],
+		],
+		usage: {
+			examples: [
+				{ arguments: '--append <kind> <text>', note: 'append one event; prints its position' },
+				{ arguments: '--from <position>', note: 'every event after <position>, in order (JSON)' },
+				{
+					arguments: '--follow <position>',
+					note: 'new events, waiting for one; position on stderr',
+				},
+				{ arguments: '--watch [<position>]', note: 'every new event, rendered, until interrupted' },
+				{ arguments: '--last', note: 'the newest event alone' },
+			],
+		},
+	},
+	'run:report': {
+		script: 'scripts/run/run-report-cli.ts',
+		// `.env` rather than the ambient environment: `--handoff` sends the hand-off confirmation.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Generate the session-facing report for this invocation from the run’s event stream (merges, parks, cuts) with the release tail — the same text josh notify sends',
+		category: 'AI tools',
+		reference: ['[--handoff]', 'automation', ['files', 'network']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'print the report; the same text josh notify sends' },
+				{
+					arguments: '--handoff',
+					note: 'print the backlogrun hand-off report and send it as the confirmation',
+				},
+			],
+		},
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { SHIP_COMMANDS }

package/scripts/josh/josh-commands-split.ts

@@ -1,5 +1,8 @@
 import type { CommandEntry } from './josh-command-types'
 
+const MACHINE_READABLE = 'the verdict and the reason, machine-readable'
+const JSON_FLAG = '--json'
+
 // The `split:assess` command registry, split out of `josh-commands-ai.ts` so that file stays under its
 // 300-code-line limit, exactly as `LANE_COMMANDS` was for the same reason. It is spread into `AI_COMMANDS` so the command stays grouped with the other
 // decision oracles under the 'AI tools' category.
@@ -12,6 +15,12 @@ const SPLIT_COMMANDS: Record<string, CommandEntry> = {
 			'Measure the branch change size (tests excluded) and answer the split assessment size question: split | single',
 		category: 'AI tools',
 		reference: ['[--json]', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: '', note: '→ single' },
+				{ arguments: JSON_FLAG, note: MACHINE_READABLE },
+			],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

package/scripts/josh/josh-commands-versioning.ts

@@ -3,16 +3,33 @@ import type { CommandEntry } from './josh-command-types'
 /* eslint-disable @typescript-eslint/naming-convention */
 const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 	bump: {
-		script: 'scripts/version/bump-version.ts',
+		script: 'scripts/version/bump-version-main.ts',
 		description: 'Bump package version',
 		category: 'Versioning',
 		reference: ['[major|minor|patch]', 'maintainer', ['files']],
+		usage: { examples: [{ arguments: 'major' }, { arguments: 'minor' }, { arguments: 'patch' }] },
 	},
 	version: {
 		script: 'scripts/version/version-check.ts',
 		description: 'Show kit versions; --upgrade updates the global and project install',
 		category: 'Versioning',
 		reference: ['[--upgrade]', 'developer', ['files', 'network', 'processes']],
+		usage: {
+			examples: [
+				{ arguments: '' },
+				{
+					arguments: '--upgrade',
+					note: 'upgrade global + project to latest, then re-run fix-gh-packages',
+				},
+			],
+			flags: [
+				{
+					names: ['--upgrade'],
+					description:
+						'upgrade both the global install (`pnpm add -g`) and the project devDependency (`pnpm add -D` + `fix-gh-packages`); already-current or not-installed targets are skipped.',
+				},
+			],
+		},
 	},
 	// A `script` entry, not a shell one: script paths resolve against the kit package root, so this
 	// keeps working from a consumer repo where the file lives under node_modules. The registry
@@ -24,6 +41,7 @@ const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 			'Check that every published dependency range still resolves for a consumer and no peer range falls below an installed toolkit',
 		category: 'Versioning',
 		reference: ['', 'developer', ['network']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	// The one place that decides a version. A `script` entry for the same
 	// reason `ranges` is one: script paths resolve against the kit package root, so it keeps working
@@ -33,15 +51,39 @@ const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Release the merges main has taken since the version last changed',
 		category: 'Versioning',
 		reference: ['[--dry-run]', 'maintainer', ['git', 'network', 'release']],
+		usage: {
+			examples: [
+				{ arguments: '' },
+				{ arguments: '--dry-run', note: 'count and report, write nothing' },
+			],
+			flags: [
+				{
+					names: ['--dry-run'],
+					description:
+						'count and report only; writes nothing, fetches nothing, and creates no work tree.',
+				},
+				{
+					names: ['--help', '-h'],
+					description:
+						'print the usage line and exit 0 without fetching or releasing. Any other argument is refused with the usage line and a non-zero exit, before anything is fetched.',
+				},
+			],
+		},
 	},
 	// The read-only half of the one above. `release --dry-run` cannot
 	// answer this question: it refuses off the default branch and on a dirty tree, which is every
 	// position a run asks it from. A `script` entry for the same reason `release` is one.
 	'release:scope': {
-		script: 'scripts/release/release-scope-cli.ts',
+		script: 'scripts/release/release-scope-main.ts',
 		description: 'Say whether a release is owed, from the unreleased merges on main',
 		category: 'Versioning',
 		reference: ['[--json]', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: '', note: '→ required | skip | unknown' },
+				{ arguments: '--json', note: '{"scope":"…","reason":"…"} on one line' },
+			],
+		},
 	},
 	// Run by the release workflows, kit's and the one sync distributes, after a tag has published.
 	// Settings come from the environment, so the workflow decides them.
@@ -50,6 +92,11 @@ const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Create the GitHub Release for a published tag, with generated notes',
 		category: 'Versioning',
 		reference: ['', 'automation', ['network', 'release']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'run by CI with GH_TOKEN, RELEASE_TAG and GITHUB_REPOSITORY set' },
+			],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */