@joshuafolkken/kit 1.1471.0 → 1.1514.0

package/scripts/josh/josh-logic.ts

@@ -3,7 +3,6 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { resolve_local_bin, resolve_package_bin } from '#scripts/build/local-bin'
 import { core_budget } from '#scripts/gate/core-budget'
-import { ancestor_directories } from '#scripts/lib/ancestor-directories'
 import { package_version_schema } from '#scripts/lib/schemas'
 import { resolve_spawn_exit } from '#scripts/lib/spawn-exit'
 import { execaSync } from 'execa'
@@ -18,6 +17,7 @@ import {
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from './josh-composite-arguments'
 import { josh_in_process } from './josh-in-process'
 import { kit_only } from './kit-only'
+import { find_package_directory } from './package-directory'
 import { run_github_prerequisite } from './run-github-prerequisite'
 
 const COLUMN_WIDTH = 26
@@ -35,17 +35,6 @@ interface TsxRunner {
 	leading_arguments: ReadonlyArray<string>
 }
 
-// Resolve the kit package root by ascending to the nearest package.json. This works both
-// from the bundled dist/josh.js (one level under the root) and from the tsx source at
-// scripts/josh/ (two levels), so this file's depth no longer has to be hard-coded.
-function find_package_directory(start_directory: string): string {
-	return (
-		ancestor_directories.nearest(start_directory, (directory) =>
-			existsSync(path.join(directory, PACKAGE_JSON)),
-		) ?? start_directory
-	)
-}
-
 const PACKAGE_DIR = find_package_directory(path.dirname(fileURLToPath(import.meta.url)))
 
 function resolve_tsx_executable(): string {
@@ -287,6 +276,7 @@ function declared(value: number | (() => number) | undefined): number | undefine
 // without claiming a place. A command under a parent that already holds its cores claims nothing:
 // `core_budget.with_command_reservation` reads the mark that parent set.
 async function dispatch_entry(
+	command: string,
 	entry: CommandEntry,
 	subcommand_arguments: Array<string>,
 ): Promise<number> {
@@ -297,7 +287,7 @@ async function dispatch_entry(
 	return await core_budget.with_command_reservation(
 		weight,
 		async () => await run_entry(entry, subcommand_arguments),
-		{ memory_mb: declared(entry.memory_mb) },
+		{ memory_mb: declared(entry.memory_mb), command },
 	)
 }
 
@@ -314,7 +304,7 @@ async function run_command(
 	const early_exit = pre_dispatch_exit(resolved, entry, subcommand_arguments, is_consumer)
 	if (early_exit !== undefined) return early_exit
 
-	return await dispatch_entry(entry, subcommand_arguments)
+	return await dispatch_entry(resolved, entry, subcommand_arguments)
 }
 
 const josh_logic = {
@@ -330,10 +320,11 @@ export { ALIASES, COMMAND_MAP } from './josh-command-map'
 export { SPAWN_ERROR_EXIT_CODE } from '#scripts/lib/spawn-exit'
 export { composite_arguments, USAGE_ERROR_EXIT_CODE } from './josh-composite-arguments'
 export {
-	find_package_directory,
 	josh_logic,
 	resolve_alias,
 	resolve_tsx_executable,
 	resolve_tsx_runner,
 	UNKNOWN_COMMAND_EXIT_CODE,
 }
+
+export { find_package_directory } from './package-directory'

package/scripts/josh/josh-usage-automation.ts

@@ -0,0 +1,121 @@
+import type { CommandUsage } from './josh-command-types'
+
+// The usage of the commands `docs/josh-commands-automation.md` documents under "Development",
+// "Project" and "AI tools", keyed by command name. The page's usage blocks are generated from this
+// table and `josh help <command>` prints it, so an example or a flag is written once, here (#3939).
+const STAGED = '--staged'
+const JSON_FLAG = '--json'
+const BRANCH_DIFF = 'the branch diff'
+const STAGED_DIFF = 'the staged diff instead'
+const PR_NUMBER = '42'
+const DRY_RUN = '--dry-run'
+const SKIP_PUBLISH_WAIT = '--skip-publish-wait'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const AUTOMATION_USAGE: Readonly<Record<string, CommandUsage>> = {
+	'refactor:scan': { examples: [{ arguments: '' }] },
+	'time:density': {
+		examples: [{ arguments: '' }, { arguments: '--lanes 5', note: 'the five most recent lanes' }],
+		flags: [
+			{
+				names: ['--lanes <n>'],
+				description: 'average over a different count of recent qualifying lanes (default 10).',
+			},
+			{
+				names: ['--path <dir>'],
+				description:
+					"read another project's lane transcripts, as `josh time` does. Run it from the main checkout — a lane reads only its own transcript.",
+			},
+		],
+	},
+	'e2e:retry-check': { examples: [{ arguments: '' }] },
+	'sync:scope': {
+		examples: [
+			{ arguments: '', note: BRANCH_DIFF },
+			{ arguments: STAGED, note: STAGED_DIFF },
+			{ arguments: JSON_FLAG, note: '{"scope":"managed","reason":"..."}' },
+		],
+		flags: [
+			{ names: [STAGED], description: 'inspect the staged diff instead of the branch diff.' },
+			{ names: [JSON_FLAG], description: 'emit `{"scope","reason"}` as JSON.' },
+		],
+	},
+	'dogfood:commit': { examples: [{ arguments: '~/Development/kit-test-html-start' }] },
+	'fresh:run': {
+		examples: [
+			{ arguments: '--list', note: "kit's six patterns" },
+			{ arguments: 'kit-test-html-init', note: 'one pattern, the packed checkout' },
+			{
+				arguments: 'kit-test-html-start',
+				note: 'a GitHub pattern, the latest published version',
+			},
+			{ arguments: '--spec fresh/html-init.json', note: 'a scenario another toolkit wrote' },
+		],
+		flags: [
+			{ names: ['--list'], description: 'print the pattern names and run nothing.' },
+			{
+				names: ['--spec <file.json>'],
+				description:
+					'run the scenario in this file instead of a named pattern; the path is relative to the project root.',
+			},
+			{
+				names: ['--package-version <version>'],
+				description:
+					"the published version a `package_source: published` scenario installs. Default: the registry's latest version of the package the command is run from.",
+			},
+			{
+				names: ['--log-dir <dir>'],
+				description: 'where the log is written. Default: `.claude/tmp/fresh-machine`.',
+			},
+			{ names: ['--rebuild'], description: 'build the machine image without the layer cache.' },
+		],
+	},
+	'auth:setup': {
+		examples: [
+			{ arguments: '', note: 'sign in and save the token' },
+			{ arguments: '--check', note: 'ok: … saved on <date>, or missing: … and exit 1' },
+		],
+	},
+	'sonar:hotspots': { examples: [{ arguments: PR_NUMBER }] },
+	'sonar:new-code': { examples: [{ arguments: PR_NUMBER }] },
+	'ui:routes': {
+		examples: [
+			{ arguments: '', note: BRANCH_DIFF },
+			{ arguments: STAGED, note: STAGED_DIFF },
+		],
+	},
+	propagate: {
+		examples: [
+			{ arguments: '' },
+			{ arguments: DRY_RUN, note: 'report targets and steps, write nothing' },
+			{ arguments: SKIP_PUBLISH_WAIT, note: 'release already known to be published' },
+			{ arguments: '--target app-kit', note: 'carry the release into one consumer only' },
+		],
+		flags: [
+			{
+				names: [DRY_RUN],
+				description:
+					'report targets and steps without writing; skips the publish wait, opens no issues.',
+			},
+			{
+				names: [SKIP_PUBLISH_WAIT],
+				description: 'skip the registry poll for an already-published release.',
+			},
+			{
+				names: ['--target <repo>'],
+				description:
+					'process only that consumer (`app-kit` or `joshuafolkken/app-kit`); the rest are reported `skipped` and left untouched. An unknown, ambiguous or non-dependent name fails before the publish wait, writing nothing.',
+			},
+		],
+	},
+	'repo:party': {
+		examples: [
+			{ arguments: 'joshuafolkken/kit', note: '→ first-party (in the kit session)' },
+			{ arguments: 'sveltejs/kit', note: '→ third-party' },
+			{ arguments: '', note: "no argument: the session's own repository" },
+		],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { AUTOMATION_USAGE }

package/scripts/josh/josh-usage-backlog.ts

@@ -0,0 +1,180 @@
+import type { CommandUsage } from './josh-command-types'
+
+// The usage of the epic and backlog commands `docs/josh-commands-backlog.md` documents under "Epics
+// and backlog", keyed by command name. The page's usage blocks are generated from this table and
+// `josh help <command>` prints it, so an example or a flag is written once, here (#3938).
+const EXCLUDE = '--exclude <N>'
+const BUDGET = '--answer candidates --started "$started" --active "$active"'
+const REPO = '--repo <owner/repo>'
+const JUST_MERGED = 'skip the issue just merged'
+const EXCLUDE_1630 = '--exclude 1630'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const BACKLOG_USAGE: Readonly<Record<string, CommandUsage>> = {
+	epic: {
+		examples: [
+			{ arguments: '"Epic: split the parser work" 101 102 103' },
+			{ arguments: '"Epic: staged rollout" 101 102 --ordered' },
+			{ arguments: '"Epic: ..." 101 102 --rationale-file rationale.md' },
+			{ arguments: '--promote 858 101 102 103', note: 'turn an existing issue into an epic' },
+			{ arguments: '--add 893 894', note: 'track #894, declaring no order for it' },
+			{ arguments: '--add 893 894 --before 891', note: '#894 must finish before #891' },
+			{ arguments: '--add 893 894 --after 890', note: '#894 starts once #890 is done' },
+			{ arguments: '--add 893 894 --decision-file why.md', note: '…and record why, in one call' },
+			{
+				arguments: '--reconcile 2184',
+				note: 'rewrite the body to match the recorded blocked-by, and record any order the body declared',
+			},
+		],
+		flags: [
+			{
+				names: ['--ordered'],
+				description:
+					'argument order is the dependency order; writes the arrow chain, records the matching `blocked-by` relations, and adds a `### Declared order` entry under `## Decisions`.',
+			},
+			{
+				names: ['--rationale-file <path|->'],
+				description: 'split rationale prose (`-` reads stdin).',
+			},
+			{
+				names: ['--origin <owner/repo#N>'],
+				description: 'backlink when the split originated in another repository.',
+			},
+			{
+				names: ['--before <M>'],
+				description:
+					'with `--add`: insert before `#M`, re-pointing what `#M` was waiting on so the chain is never broken.',
+			},
+			{
+				names: ['--after <M>'],
+				description:
+					'with `--add`: start after `#M`; branches when `#M` already has a successor, extends when it is a tail.',
+			},
+			{
+				names: ['--order-before <M>', '--order-after <M>'],
+				description: 'with `--add`: move the task-list row only; write no `blocked-by` relation.',
+			},
+			{
+				names: ['--decision-file <path|->'],
+				description: 'with `--add`: record why the child was placed.',
+			},
+			{
+				names: ['--remove <E> <M> <N> [<N2> …]'],
+				description:
+					'delete a declared order from the body and the relations; each consecutive pair is one link.',
+			},
+		],
+	},
+	'epic:next': {
+		examples: [
+			{ arguments: '858' },
+			{ arguments: '858 --repo joshuafolkken/kit', note: 'just the next child for one repository' },
+			{ arguments: '858 --repo joshuafolkken/kit --lanes', note: 'one child per free lane there' },
+		],
+		flags: [
+			{
+				names: [REPO],
+				description:
+					'answer for one repository; stdout carries one token (an issue number, or `wait`/`stop`/`complete`), everything else on stderr.',
+			},
+			{
+				names: ['--lanes'],
+				description:
+					'print one issue number per free lane (requires `--repo`); `JOSH_LANE_LIMIT` sets the ceiling, default 4. Prints `triage` instead while any candidate carries neither `run:solo` nor `run:lane` (the triage gate in `josh backlog:next`).',
+			},
+		],
+	},
+	'epic:bundle': { examples: [{ arguments: '874' }] },
+	'epic:audit': { examples: [{ arguments: '858' }] },
+	'epic:check': { examples: [{ arguments: '700' }] },
+	'auto-ok:next': {
+		examples: [{ arguments: '' }, { arguments: '--exclude 906', note: JUST_MERGED }],
+		flags: [
+			{
+				names: [EXCLUDE],
+				description: 'drop issues from the answer; comma-separated, repeatable.',
+			},
+		],
+	},
+	'auto-ok:judge': {
+		examples: [
+			{ arguments: '', note: 'the issues that still owe a judgement' },
+			{ arguments: '--apply 912 --lane', note: 'opt it in, with its run label' },
+			{ arguments: '--decline 913 --reason "<why>"', note: 'record why it stays out' },
+		],
+		flags: [
+			{
+				names: ['--apply <N> --lane|--solo'],
+				description:
+					'checks the exclusions again against the labels as they stand, applies the run label and then `auto-ok`, and notes it on the progress board.',
+			},
+			{ names: ['--decline <N> --reason <text>'], description: 'applies nothing.' },
+		],
+	},
+	'backlog:next': {
+		examples: [{ arguments: '' }, { arguments: EXCLUDE_1630, note: JUST_MERGED }],
+		flags: [
+			{
+				names: [EXCLUDE],
+				description: 'drop issues from every bucket; comma-separated, repeatable.',
+			},
+		],
+	},
+	'backlog:plan': {
+		examples: [
+			{ arguments: '' },
+			{ arguments: EXCLUDE_1630, note: 'after #1630 merged' },
+			{ arguments: '--waves', note: 'the run order, wave by wave' },
+		],
+		flags: [
+			{ names: [EXCLUDE], description: 'same exclusion as `backlog:next`.' },
+			{
+				names: ['--waves'],
+				description:
+					'print the order the run takes, wave by wave, assuming each wave merges before the next. Read-only.',
+			},
+		],
+	},
+	'backlog:stalled': { examples: [{ arguments: '' }] },
+	'backlog:budget': {
+		examples: [
+			{ arguments: BUDGET },
+			{ arguments: '--answer exhausted --started "$started" --active "$active" --idle 60' },
+			{ arguments: `${BUDGET} --merged 3 --running 2 --max 5` },
+		],
+		flags: [
+			{
+				names: ['--answer <candidates|exhausted|blocked|parked|unreadable|untriaged>'],
+				description: "`backlog:next`'s answer, mapped.",
+			},
+			{
+				names: ['--started', '--active'],
+				description:
+					'when the invocation began / when it last had work (required unless the watch is off).',
+			},
+			{
+				names: ['--idle <minutes>'],
+				description:
+					'once nothing can proceed, keep polling this long, counted from `--active` (default 480, 8 hours; `--idle 0` turns the watch off).',
+			},
+			{
+				names: ['--max <count>'],
+				description:
+					'issues one invocation may take (default unlimited); `--merged` and `--running` count against it.',
+			},
+			{
+				names: ['--json'],
+				description: 'collapse verdict and reason into `{"budget": "<verdict>", "reason": "…"}`.',
+			},
+		],
+	},
+	'backlog:offer': {
+		examples: [{ arguments: '--started "$started" --active "$active" --running 2 --retries 1' }],
+	},
+	'backlog:drive': {
+		examples: [{ arguments: '--owner "$PPID" [--max <n>] [--idle <minutes>] [--only]' }],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { BACKLOG_USAGE }

package/scripts/josh/josh-usage-developer.ts

@@ -0,0 +1,230 @@
+import { ports } from '#ports'
+import type { CommandUsage } from './josh-command-types'
+
+// The usage of the commands `docs/josh-commands.md` documents, keyed by command name. The page's
+// usage blocks are generated from this table and `josh help <command>` prints it, so an example or a
+// flag is written once, here (#3932).
+// The unseeded ports are read from `ports/index.js`, their one definition (#818).
+const UNSEEDED: Readonly<Record<string, string | undefined>> = {}
+const NARROWED = { arguments: 'scripts/thing.ts', note: 'narrow by the given files instead' }
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const DEVELOPER_USAGE: Readonly<Record<string, CommandUsage>> = {
+	gate: {
+		examples: [
+			{ arguments: '' },
+			{ arguments: '--verbose', note: "every check's output, passing ones included" },
+			{ arguments: '--force', note: 're-run even on a tree already recorded green' },
+			{ arguments: '--no-unit', note: 'the static checks only (CI only)' },
+		],
+	},
+	lint: { examples: [{ arguments: '' }] },
+	'lint:related': { examples: [{ arguments: '' }, NARROWED] },
+	lines: {
+		examples: [{ arguments: 'scripts/hooks/format-edited-file.ts scripts/josh/josh-logic.ts' }],
+	},
+	bytes: {
+		examples: [
+			{ arguments: 'docs/josh-commands.md', note: 'one document' },
+			{ arguments: '', note: 'scan: every budgeted document near its ceiling' },
+		],
+	},
+	metrics: {
+		examples: [
+			{ arguments: '', note: "print the totals and check them against the merge-base's" },
+			{ arguments: '--accept --reason "<why>"', note: "record this branch's growth and why" },
+		],
+	},
+	format: { examples: [{ arguments: '' }] },
+	'cspell:dot': { examples: [{ arguments: '', note: 'includes dotfiles' }] },
+	behavior: { examples: [{ arguments: '' }] },
+	'exports:unused': { examples: [{ arguments: '' }] },
+	'test:unit': { examples: [{ arguments: '' }] },
+	'test:related': {
+		examples: [
+			{ arguments: '' },
+			NARROWED,
+			{ arguments: '--silent', note: 'flags are forwarded to vitest' },
+		],
+	},
+	'test:declared': {
+		examples: [
+			{ arguments: '' },
+			{ arguments: '--match', note: 'check Step 0 declarations on stdin' },
+			{ arguments: '--help', note: 'print usage, including the --match stdin form' },
+		],
+	},
+	'test:e2e': { examples: [{ arguments: '' }] },
+	test: { examples: [{ arguments: '' }] },
+	check: { examples: [{ arguments: '' }] },
+	port: {
+		examples: [
+			{
+				arguments: 'dev',
+				note: `${String(ports.resolve_development_port(UNSEEDED))} with no seed set`,
+			},
+			{
+				arguments: 'preview',
+				note: `${String(ports.resolve_preview_port(UNSEEDED))} with no seed set`,
+			},
+		],
+	},
+	profile: { examples: [{ arguments: '' }] },
+	init: {
+		examples: [
+			{
+				arguments: '',
+				note: 'create/merge config files, install and format (--no-install skips both, --dry-run only prints the plan)',
+			},
+		],
+	},
+	'registry:migrate': { examples: [{ arguments: '' }] },
+	sync: { examples: [{ arguments: '', note: 'overwrite managed files' }] },
+	uninstall: {
+		examples: [
+			{ arguments: '', note: 'show the plan, then ask' },
+			{ arguments: '--yes', note: 'remove without asking' },
+		],
+	},
+	adopt: {
+		examples: [
+			{ arguments: '' },
+			{ arguments: '--dry-run', note: 'report the steps without touching anything' },
+		],
+		flags: [{ names: ['--dry-run'], description: 'report the plan without writing.' }],
+	},
+	git: {
+		examples: [
+			{ arguments: '', note: 'interactive' },
+			{ arguments: '-y', note: 'unattended (no TTY required)' },
+			{ arguments: '-y "title"', note: 'set commit message prefix' },
+			{ arguments: '-y "<title> #<N>"', note: 'follow-up commit on the same branch' },
+			{
+				arguments: '-y --skip-commit --skip-push',
+				note: 'open the PR without committing/pushing',
+			},
+		],
+		flags: [
+			{
+				names: ['-y', '--yes'],
+				description: 'run non-interactively; works without a TTY (agent or CI shell).',
+			},
+			{
+				names: ['--skip-commit', '--skip-push'],
+				description: 'recover/open a PR without a new commit or push.',
+			},
+		],
+	},
+	pr: { examples: [{ arguments: '', note: 'open the PR for the current <N>-<slug> branch' }] },
+	'review:findings': { examples: [{ arguments: '' }] },
+	'main:sync': { examples: [{ arguments: '' }] },
+	'main:merge': { examples: [{ arguments: '' }] },
+	version: {
+		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.',
+			},
+		],
+	},
+	ranges: { examples: [{ arguments: '' }] },
+	doctor: {
+		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).' },
+		],
+	},
+	audit: { examples: [{ arguments: '' }] },
+	overrides: {
+		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.',
+			},
+		],
+	},
+	backlogrun: {
+		examples: [
+			{ arguments: '', note: 'start in Claude, then show the board' },
+			{ arguments: '3437 --only', note: 'the arguments go to backlogrun as typed' },
+			{ arguments: '--agent codex', note: 'start in Codex' },
+			{ arguments: '--stop', note: 'stop the run in this repository' },
+		],
+	},
+	'lane:limit': {
+		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' },
+		],
+	},
+	'lane:withdraw': {
+		examples: [{ arguments: '3769 --reason "folded into a broader issue"' }],
+	},
+	'test:red': { examples: [{ arguments: '', note: 'red, green, no-test or test-only' }] },
+	start: {
+		examples: [
+			{ arguments: '', note: 'asks for the profile and the repository' },
+			{
+				arguments: '--yes --github --profile basic',
+				note: 'unattended, including the GitHub repository',
+			},
+		],
+		flags: [
+			{ names: ['--profile basic|full'], description: 'the profile, without asking.' },
+			{ names: ['--yes'], description: 'take the defaults — not consent to write to GitHub.' },
+			{ names: ['--github'], description: 'create the GitHub repository and push `main`.' },
+			{ names: ['--public'], description: 'create the repository public instead of private.' },
+			{
+				names: ['--init-command "<command>"'],
+				description: 'run this setup command in place of `josh init`.',
+			},
+			{
+				names: ['--push-preflight-command "<command>"'],
+				description:
+					'a check run before the first step when the plan pushes; a failure stops the run before it writes anything.',
+			},
+			{ names: ['--dry-run'], description: 'print the plan and change nothing.' },
+		],
+	},
+	latest: { examples: [{ arguments: '', note: 'full update (update + audit + pnpm)' }] },
+	'latest:corepack': { examples: [{ arguments: '', note: 'update pnpm only' }] },
+	'latest:update': { examples: [{ arguments: '', note: 'update dependencies only' }] },
+	'lane:restart': {
+		examples: [{ arguments: '3769', note: "prints the fresh child's pid" }],
+	},
+	'rule:value': {
+		examples: [
+			{ arguments: '' },
+			{
+				arguments: '--refresh',
+				note: 'write the reading to the loop-head cache instead of stdout',
+			},
+		],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { DEVELOPER_USAGE }

package/scripts/josh/josh-usage-hooks.ts

@@ -0,0 +1,38 @@
+import type { CommandUsage } from './josh-command-types'
+
+// The usage of the Claude Code and Codex hook commands `docs/josh-commands-automation.md` documents
+// under "Development", keyed by command name. A hook is fed its payload as JSON on stdin, so each
+// example names the event that runs it rather than an argument. The page's usage blocks are generated
+// from this table and `josh help <command>` prints it, so an example is written once, here (#3981).
+const PRE_TOOL_USE = 'run by the PreToolUse hook, the pending tool call as JSON on stdin'
+const IN_PRETOOL_GUARD = 'run inside pretool:guard, not wired on its own'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const HOOK_USAGE: Readonly<Record<string, CommandUsage>> = {
+	'format:edited': {
+		examples: [
+			{ arguments: '', note: 'run by the PostToolUse hook, the tool call as JSON on stdin' },
+		],
+	},
+	'batch:guard': { examples: [{ arguments: '', note: IN_PRETOOL_GUARD }] },
+	'investigation:guard': { examples: [{ arguments: '', note: PRE_TOOL_USE }] },
+	'duplicate-read:guard': { examples: [{ arguments: '', note: IN_PRETOOL_GUARD }] },
+	'rule:guard': { examples: [{ arguments: '', note: PRE_TOOL_USE }] },
+	'rule:list': { examples: [{ arguments: '', note: 'print every trigger-delivered rule' }] },
+	'pretool:guard': { examples: [{ arguments: '', note: PRE_TOOL_USE }] },
+	'codex:hook-adapter': {
+		examples: [
+			{ arguments: 'pretool', note: 'a Codex PreToolUse payload on stdin' },
+			{ arguments: 'posttool', note: 'a Codex PostToolUse payload on stdin' },
+		],
+	},
+	'stop:guard': {
+		examples: [{ arguments: '', note: 'run by the Stop hook, the stop payload as JSON on stdin' }],
+	},
+	'session:lang': {
+		examples: [{ arguments: '', note: 'run by the UserPromptSubmit hook; `ja` prints nothing' }],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { HOOK_USAGE }