@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -1,5 +1,12 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
+const BARE = { arguments: '' }
+// `lane:pause` and `lane:resume` take the same target.
+const LANE_SIGNAL_EXAMPLES = [
+	{ arguments: '4198' },
+	{ arguments: '--all', note: 'every open lane' },
+]
+
 // The `lane:*` command registry, split out of `josh-commands-ai.ts` so that file stays under its line
 // limit. One script answers `lane:open` / `lane:close` / `lane:list` /
 // `lane:prune` / `lane:output` / `lane:dispatch` / `lane:await`, told apart by the verb below;
@@ -9,11 +16,19 @@ const LANE_SCRIPT = 'scripts/lane/lane-cli.ts'
 // has to read `.env` to see them — without this the two are documented and unreachable.
 const LANE_ARGUMENTS = { script: LANE_SCRIPT, tsx_arguments: OPTIONAL_ENV_FILE_FLAGS } as const
 const ISSUE_WITH_OPTIONS = '<issue> [options]'
+const ISSUE_OR_ALL = '<issue> | --all'
 const MEASURE_ARGUMENTS = {
 	script: 'scripts/lane/lane-measure-cli.ts',
 	tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 } as const
 
+const PAUSE_ARGUMENTS = {
+	script: 'scripts/lane/lane-pause-cli.ts',
+	tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+	category: 'AI tools',
+	reference: [ISSUE_OR_ALL, 'developer', ['processes']],
+} satisfies Partial<CommandEntry>
+
 /* eslint-disable @typescript-eslint/naming-convention */
 const LANE_COMMANDS: Record<string, CommandEntry> = {
 	'lane:open': {
@@ -22,6 +37,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: [ISSUE_WITH_OPTIONS, 'automation', ['files', 'git']],
 		default_script_arguments: ['open'],
+		usage: { examples: [{ arguments: '1490', note: 'prints the lane directory on stdout' }] },
 	},
 	'lane:close': {
 		...LANE_ARGUMENTS,
@@ -29,6 +45,10 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue>', 'automation', ['files', 'git']],
 		default_script_arguments: ['close'],
+		usage: {
+			examples: [{ arguments: '1490' }, { arguments: '--all' }],
+			flags: [{ names: ['--all'], description: 'closes every lane.' }],
+		},
 	},
 	'lane:list': {
 		...LANE_ARGUMENTS,
@@ -36,6 +56,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['', 'automation', ['none']],
 		default_script_arguments: ['list'],
+		usage: { examples: [BARE] },
 	},
 	'lane:prune': {
 		...LANE_ARGUMENTS,
@@ -44,6 +65,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['', 'automation', ['files', 'git']],
 		default_script_arguments: ['prune'],
+		usage: { examples: [BARE] },
 	},
 	'lane:output': {
 		...LANE_ARGUMENTS,
@@ -51,6 +73,12 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue> [path]', 'automation', ['files']],
 		default_script_arguments: ['output'],
+		usage: {
+			examples: [
+				{ arguments: '1713 /abs/path/to/agent-7.jsonl', note: 'record it; prints the path back' },
+				{ arguments: '1713', note: 'read it; prints the path, or `none`' },
+			],
+		},
 	},
 	'lane:dispatch': {
 		...LANE_ARGUMENTS,
@@ -58,6 +86,31 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue> <prompt>', 'automation', ['processes']],
 		default_script_arguments: ['dispatch'],
+		usage: {
+			examples: [
+				{
+					arguments: '1749',
+					note: "prints the child's pid; a refusal is an empty capture and exit 1",
+				},
+			],
+			flags: [
+				{
+					names: ['JOSH_{SCHEDULER,WORKER,REVIEWER}_MODEL'],
+					description:
+						'Claude Code role overrides; Anthropic defaults are respectively `claude-opus-5-5`, `claude-opus-5-5`, and `claude-opus-5-5`. Codex keeps its provider-specific model.',
+				},
+				{
+					names: ['JOSH_{SCHEDULER,WORKER,REVIEWER}_EFFORT'],
+					description:
+						'role effort overrides for either provider; defaults are `medium`, `medium`, and `medium`.',
+				},
+				{
+					names: ['JOSH_REVIEWER_VERIFICATION_{MODEL,EFFORT}'],
+					description:
+						'review round 2 and later (the verification pass); defaults are `claude-sonnet-5-5` / `high` on Anthropic and `high` on OpenAI, falling back to `JOSH_REVIEWER_*`.',
+				},
+			],
+		},
 	},
 	'lane:await': {
 		...LANE_ARGUMENTS,
@@ -66,13 +119,31 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue> [<issue>...] [--owner <pid>]', 'automation', ['files', 'processes']],
 		default_script_arguments: ['await'],
+		usage: {
+			examples: [
+				{ arguments: '1749 1750', note: 'block until either lane completes' },
+				{
+					arguments: '1749 1750 --owner "$PPID"',
+					note: 'reclaim the carry record for a resumed conversation first',
+				},
+			],
+		},
 	},
 	'lane:launch': {
-		script: 'scripts/lane/lane-launch-cli.ts',
+		script: 'scripts/lane/lane-launch-main.ts',
 		description:
 			'Collapse a backlogrun lane-start event into one call: open the lane, pop and re-install on the first, dispatch the child',
 		category: 'AI tools',
 		reference: ['<issue> [--stash <message>]', 'automation', ['files', 'git', 'processes']],
+		usage: {
+			examples: [
+				{ arguments: '1749', note: 'every lane after the first' },
+				{
+					arguments: '1749 --stash "backlogrun: josh latest before lanes"',
+					note: 'the first lane only',
+				},
+			],
+		},
 	},
 	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so the lane is found.
 	'lane:restart': {
@@ -82,15 +153,62 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 			'Stop a running lane child, stash its uncommitted work and re-dispatch its issue in a fresh session — not counted as an outage or a failure',
 		category: 'AI tools',
 		reference: ['<issue>', 'developer', ['files', 'git', 'processes', 'network']],
+		usage: {
+			examples: [{ arguments: '3769', note: "prints the fresh child's pid" }],
+		},
 	},
 	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so the lane is found.
 	'lane:withdraw': {
 		script: 'scripts/lane/lane-withdraw-cli.ts',
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		description:
-			'Stop a running lane child, stash its uncommitted work, close its issue as not planned and close the lane — booked withdrawn, not as an outage or a failure',
+			'Stop a running lane child, stash its uncommitted work and close the lane, leaving its issue open for the next run — booked withdrawn, not as an outage or a failure',
 		category: 'AI tools',
 		reference: ['<issue> --reason <text>', 'developer', ['files', 'git', 'processes', 'network']],
+		usage: {
+			examples: [{ arguments: '3769 --reason "folded into a broader issue"' }],
+		},
+	},
+	// `.env` is read for the Telegram settings the yield's hold release reaches (`run-hold-cli.ts`).
+	'lane:plan': {
+		script: 'scripts/lane/lane-plan-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Record the files a lane child plans to edit, and give the lane back when a running lane that planned earlier declares or plans one of them — naming the file and that issue',
+		category: 'AI tools',
+		reference: ['<issue> <path>... [--probe]', 'automation', ['files', 'network']],
+		usage: {
+			examples: [{ arguments: '4864 scripts/lane/lane-plan.ts scripts/backlog/backlog-next.ts' }],
+		},
+	},
+	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so `--all` finds the lanes.
+	'lane:pause': {
+		...PAUSE_ARGUMENTS,
+		description:
+			'Suspend a running lane child’s process tree (SIGSTOP) in place, leaving its work tree, branch and issue untouched, and record the pause in the lane’s state and the run’s event stream',
+		default_script_arguments: ['pause'],
+		usage: { examples: LANE_SIGNAL_EXAMPLES },
+	},
+	'lane:resume': {
+		...PAUSE_ARGUMENTS,
+		description: 'Let a paused lane child carry on from where it stopped (SIGCONT)',
+		default_script_arguments: ['resume'],
+		usage: { examples: LANE_SIGNAL_EXAMPLES },
+	},
+	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so `--all` finds the lanes.
+	'lane:adopt': {
+		script: 'scripts/lane/lane-adopt-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Give an open lane that lost its state record a record again, read from its process, work tree, unpushed commits, pull request and issue — its work untouched',
+		category: 'AI tools',
+		reference: [ISSUE_OR_ALL, 'developer', ['files', 'git', 'processes', 'network']],
+		usage: {
+			examples: [
+				{ arguments: '4744' },
+				{ arguments: '--all', note: 'every open lane with no record' },
+			],
+		},
 	},
 	// A live run's lane limit: `.env` is read so the bare form reports the
 	// `JOSH_LANE_LIMIT` a person set there when no override stands.
@@ -101,6 +219,13 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 			'Change a live backlogrun’s lane limit without stopping it, or print the limit, lanes in use and free lanes',
 		category: 'AI tools',
 		reference: ['[<limit>] [--reset]', 'developer', ['files']],
+		usage: {
+			examples: [
+				{ arguments: '8', note: "raise or lower the live run's limit to 8" },
+				{ arguments: '', note: 'print the limit, the lanes in use and the free lanes' },
+				{ arguments: '--reset', note: 'clear the override; JOSH_LANE_LIMIT applies again' },
+			],
+		},
 	},
 	// The lane-limit measurement: `.env` is read so `lane:stats` labels the row
 	// with the `JOSH_LANE_LIMIT` a person set there.
@@ -111,14 +236,73 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['[--every <seconds>]', 'maintainer', ['files']],
 		default_script_arguments: ['sample'],
+		usage: { examples: [{ arguments: '', note: 'one machine-load reading' }] },
 	},
 	'lane:stats': {
 		...MEASURE_ARGUMENTS,
 		description:
-			'Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, the wait after each ship stop reason under those, and the duration and reuse count of each gate check last',
+			"Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, the wait after each ship stop reason under those, the duration and reuse count of each gate check, and each check's core claim against the cores it used",
 		category: 'AI tools',
 		reference: ['--period <days> [--limit <lane-limit>]', 'maintainer', ['none']],
 		default_script_arguments: ['stats'],
+		usage: {
+			examples: [{ arguments: '--period 7', note: "a 7-day period's stage medians and maxima" }],
+		},
+	},
+	// One lane measurement as one number on the last line, for an Issue's measurement declaration
+	// (joshuafolkken/kit#4630).
+	'lane:value': {
+		...MEASURE_ARGUMENTS,
+		description:
+			'Print one lane measurement since an instant as a single number: cell (a lane:stats table cell, --table --row --column), lint-unmoved (median s of a lint:related that found nothing moved), metrics-stops (pre-detach metrics stops per lane), lint-core-wait (lint:related core-budget wait, min per lane), edit (median s of one Edit)',
+		category: 'AI tools',
+		reference: ['<metric> --since <instant>', 'maintainer', ['none']],
+		default_script_arguments: ['value'],
+		usage: {
+			examples: [
+				{
+					arguments: 'edit --since 2026-10-23T03:29Z',
+					note: 'the median Edit time since an instant',
+				},
+				{
+					arguments:
+						'cell --table "test:related scope" --row related --column "median (s)" --since 2026-10-23T03:29Z',
+					note: 'one lane:stats table cell since an instant',
+				},
+			],
+		},
+	},
+	'lane:net': {
+		...MEASURE_ARGUMENTS,
+		description:
+			"Print a lane's net minutes: its issue's first dispatch to its merge, less the waits its parks, outages, usage-limit stops and yields stood and the host's sleeps",
+		category: 'AI tools',
+		reference: ['<issue>', 'maintainer', ['none']],
+		default_script_arguments: ['net'],
+		usage: {
+			examples: [
+				{
+					arguments: '4695',
+					note: 'the net minutes a causing-lane line declares',
+				},
+			],
+		},
+	},
+	'lane:breakdown': {
+		script: 'scripts/lane/lane-breakdown-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			"Print a merged lane's net time by stage, longest first, the implementation split by its tool calls",
+		category: 'AI tools',
+		reference: ['<issue>', 'maintainer', ['none']],
+		usage: {
+			examples: [
+				{
+					arguments: '4970',
+					note: 'the breakdown the overrun investigation comments on the lane',
+				},
+			],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -7,29 +7,53 @@ import type { CommandEntry } from './josh-command-types'
 /* eslint-disable @typescript-eslint/naming-convention */
 const LINT_COMMANDS: Record<string, CommandEntry> = {
 	'issue:lint': {
-		script: 'scripts/issue/issue-lint-cli.ts',
+		script: 'scripts/issue/issue-lint-main.ts',
 		description: "Check an issue body file for the template's required headings",
 		category: 'AI tools',
 		reference: ['<path>', 'automation', ['files']],
-	},
-	'issue:backlinks': {
-		script: 'scripts/issue/issue-backlinks-cli.ts',
-		description: 'Classify an origin issue’s upstream backlinks: ok, missing, or wrong heading',
-		category: 'AI tools',
-		reference: ['<issue>', 'automation', ['network']],
+		usage: { examples: [{ arguments: '.josh/tmp/issue-body.md' }] },
 	},
 	'report:lint': {
 		script: 'scripts/report/report-lint-cli.ts',
-		description: 'Check a two-layer work summary on stdin against its mechanical format rules',
+		description:
+			"Check a two-layer work summary, or with --child-summary a lane child's summary, on stdin against its mechanical format rules",
+		category: 'AI tools',
+		reference: ['[--child-summary] (reads stdin)', 'automation', ['none']],
+		usage: {
+			examples: [{ arguments: '< summary.md' }, { arguments: '--child-summary < summary.md' }],
+		},
+	},
+	'review:lint': {
+		script: 'scripts/review/review-lint-cli.ts',
+		description:
+			"Check a review's markdown on stdin against the review rubric's output format, round 1 or with --round 2 the verification pass",
+		category: 'AI tools',
+		reference: ['[--round <1|2>] (reads stdin)', 'automation', ['none']],
+		usage: {
+			examples: [{ arguments: '< review.md' }, { arguments: '--round 2 < review.md' }],
+		},
+	},
+	'report:template': {
+		script: 'scripts/report/report-template-cli.ts',
+		description:
+			'Print the work summary or completion report skeleton in the session language: summary | done',
 		category: 'AI tools',
-		reference: ['(reads stdin)', 'automation', ['none']],
+		reference: ['summary|done [<path>...]', 'automation', ['files']],
+		usage: {
+			examples: [{ arguments: 'summary scripts/report/report-lint.ts' }, { arguments: 'done' }],
+		},
 	},
 	cases: {
 		script: 'scripts/cases/cases-cli.ts',
 		description:
-			'Read changed paths and print the I/O boundaries crossed and their mandatory abnormal cases: network | process | fs | none',
+			'Read changed paths and print the boundaries crossed and their mandatory abnormal cases: network | process | fs | time | state | env | none',
 		category: 'AI tools',
 		reference: ['<path...>', 'automation', ['files']],
+		usage: {
+			examples: [
+				{ arguments: 'scripts/a.ts scripts/b.ts', note: 'the boundaries these paths cross' },
+			],
+		},
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -1,5 +1,8 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
+const CHECK = '--check'
+const JSON_FLAG = '--json'
+
 /* eslint-disable @typescript-eslint/naming-convention */
 const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 	doctor: {
@@ -9,6 +12,21 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Maintenance',
 		reference: ['[--fix]', 'developer', ['files']],
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		usage: {
+			examples: [
+				{ arguments: '', note: 'diagnose only' },
+				{ arguments: '--fix', note: 'reclaim the global josh by removing a stale kit shim' },
+				{ arguments: '--ports', note: 'also print the per-repository port-seed table' },
+			],
+			flags: [
+				{
+					names: ['--fix'],
+					description:
+						'remove a shadowing binary **only if it is a kit shim** (its body references `@joshuafolkken/kit` or the removed `install-bin` script); any other binary is left and reported for manual review. Also the one-shot recovery for an old project that re-created the global shim.',
+				},
+				{ names: ['--ports'], description: 'additionally print the port-seed table (see below).' },
+			],
+		},
 	},
 	'ruleset:check': {
 		script: 'scripts/repo/ruleset-check-cli.ts',
@@ -16,30 +34,109 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 			"Check that the default branch requires every status check kit's workflows report (--apply adds the missing ones)",
 		category: 'Maintenance',
 		reference: ['[--apply]', 'maintainer', ['network']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'report only' },
+				{ arguments: '--apply', note: 'add the missing checks to the existing rule' },
+			],
+			flags: [
+				{
+					names: ['--apply'],
+					description:
+						"append the missing checks to the ruleset's required-checks rule (or to the branch protection's contexts). It never creates a ruleset: with none, create one under Settings → Rules → Rulesets, then rerun. Writing a repository setting needs admin access, so only this flag writes — `josh sync` and `josh doctor` never do.",
+				},
+			],
+		},
 	},
 	overrides: {
 		script: 'scripts/overrides/overrides-check.ts',
 		description: 'Check pnpm overrides for drift',
 		category: 'Maintenance',
 		reference: ['[--save]', 'developer', ['files']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'verify overrides unchanged' },
+				{ arguments: '--save', note: 'snapshot current merged overrides' },
+			],
+			flags: [
+				{
+					names: ['--save'],
+					description:
+						'write the current merged overrides to `.overrides-snapshot.json` (gitignored); later runs compare against it and exit non-zero on any add, removal, or change.',
+				},
+			],
+		},
 	},
 	audit: {
-		script: 'scripts/security/security-audit.ts',
+		script: 'scripts/security/security-audit-main.ts',
 		description: 'Run security audit',
 		category: 'Maintenance',
 		reference: ['', 'developer', ['processes']],
+		usage: { examples: [{ arguments: '' }] },
+	},
+	'lockfile:policy': {
+		script: 'tools/security/lockfile-policy.ts',
+		description:
+			"Verify the lockfile against pnpm's supply-chain policy (minimumReleaseAge) when it or the policy moved from the merge-base",
+		category: 'Maintenance',
+		reference: ['', 'automation', ['network']],
+		is_kit_only: true,
+		usage: {
+			examples: [{ arguments: '', note: 'verify when the lockfile or its policy moved' }],
+		},
+	},
+	'command:derive': {
+		script: 'tools/document/command-derive.ts',
+		description:
+			'Write every artifact the command map derives — usage spans, catalog, snapshot, docs/why.md counts — and print page bytes against their ceilings',
+		category: 'Maintenance',
+		reference: ['', 'maintainer', ['files']],
+		// Kit-only: the pages it writes are kit's own documentation, and the script lives under the
+		// undistributed `tools/`.
+		is_kit_only: true,
+		// The command-map snapshot runs through one single-file vitest run.
+		core_weight: 1,
+		usage: {
+			examples: [{ arguments: '', note: 'after adding, renaming or describing a command' }],
+		},
 	},
 	'audit:provision': {
-		script: 'scripts/security/security-audit-provision.ts',
+		script: 'scripts/security/security-audit-provision-main.ts',
 		description: 'Install the pinned osv-scanner when the audit cannot find one (no-op if present)',
 		category: 'Maintenance',
 		reference: ['', 'automation', ['files', 'network']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'no-op if a scanner is already present' },
+				{ arguments: '--force', note: 'ignore backoff, allow a longer download' },
+			],
+			flags: [
+				{
+					names: ['--force'],
+					description:
+						'ignore the 6-hour failure backoff and allow a longer download window; the command to run after fixing a network problem.',
+				},
+			],
+		},
 	},
 	'reconcile-templates': {
 		script: 'scripts/sync/reconcile-templates.ts',
 		description: 'Record template source hashes (--check to verify drift)',
 		category: 'Maintenance',
 		reference: ['', 'maintainer', ['files']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'regenerate copy templates + record tripwire hashes' },
+				{ arguments: CHECK, note: 'verify templates are in sync; non-zero on drift' },
+			],
+			flags: [
+				{
+					names: [CHECK],
+					description:
+						'verify only; exits non-zero on drift. A pre-commit hook runs this when a tracked source or copy template is staged.',
+				},
+			],
+		},
 	},
 	latest: {
 		shell: [
@@ -51,9 +148,10 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Maintenance',
 		reference: ['', 'developer', ['files', 'network', 'processes']],
 		argument_targets: ['latest:corepack', 'latest:update', 'audit'],
+		usage: { examples: [{ arguments: '', note: 'full update (update + audit + pnpm)' }] },
 	},
 	'latest:scope': {
-		script: 'scripts/version/latest-scope-cli.ts',
+		script: 'scripts/version/latest-scope-main.ts',
 		description:
 			'Say whether this run has to update dependencies, from when josh latest last finished (--record notes a run)',
 		category: 'Maintenance',
@@ -62,18 +160,42 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		// where the project keeps its settings — a variable that only works when exported from the
 		// shell is one a user follows the documentation for and gets the default from, silently.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		usage: {
+			examples: [
+				{ arguments: '', note: 'required or skip, the reason on stderr' },
+				{ arguments: '--record', note: 'note a finished josh latest run' },
+				{ arguments: JSON_FLAG, note: 'the verdict and the reason as JSON' },
+			],
+			flags: [
+				{
+					names: ['--record'],
+					description: 'write the completion record `josh latest` ends with.',
+				},
+				{ names: [JSON_FLAG], description: 'emit the verdict and its reason as JSON.' },
+			],
+		},
+	},
+	'latest:if-required': {
+		script: 'scripts/version/latest-if-required-cli.ts',
+		description: 'Run josh latest only when latest:scope answers required, stashing around it',
+		category: 'Maintenance',
+		reference: ['', 'automation', ['files', 'network', 'processes']],
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		usage: { examples: [{ arguments: '', note: 'stash, update, pop on required' }] },
 	},
 	'latest:guard': {
-		script: 'scripts/version/latest-lane-guard.ts',
+		script: 'scripts/version/latest-lane-guard-main.ts',
 		description: 'Refuse josh latest inside a lane (the update stamp is keyed to the project root)',
 		category: 'Maintenance',
 		reference: ['', 'automation', ['files']],
+		usage: { examples: [{ arguments: '', note: 'refuses inside a lane' }] },
 	},
 	'latest:corepack': {
 		script: 'scripts/version/latest-corepack.ts',
 		description: 'Update pnpm on the current major while preserving the integrity pin',
 		category: 'Maintenance',
 		reference: ['', 'developer', ['files', 'network']],
+		usage: { examples: [{ arguments: '', note: 'update pnpm only' }] },
 	},
 	'latest:update': {
 		script: 'scripts/version/latest-update.ts',
@@ -83,6 +205,7 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		// `JOSH_PLAYWRIGHT_BROWSERS` widens the browsers a Playwright bump installs, and a project
 		// keeps that setting in its `.env`.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		usage: { examples: [{ arguments: '', note: 'update dependencies only' }] },
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

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

@@ -0,0 +1,29 @@
+import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
+
+// `run:pause`, split out of `josh-commands-run.ts` so that file stays under its 300-code-line limit,
+// as `PROGRESS_COMMANDS` is. `RUN_COMMANDS` spreads this in after `run:release`, so the map keeps
+// the order the run reads them in.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const PAUSE_COMMANDS: Record<string, CommandEntry> = {
+	'run:pause': {
+		script: 'scripts/run/pause/run-pause-cli.ts',
+		description: 'Set a run aside while its prerequisite lands first',
+		category: 'AI tools',
+		// `run:release` underneath can send the stop confirmation.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		reference: ['<issue> --for <prerequisite>', 'automation', ['git', 'network', 'files']],
+		usage: {
+			examples: [{ arguments: '1091 --for 1102', note: 'pause 1091 until 1102 lands' }],
+			flags: [
+				{
+					names: ['--for <prerequisite>'],
+					description: 'the issue that has to land first; `<issue>` is recorded blocked by it.',
+				},
+			],
+		},
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { PAUSE_COMMANDS }