rvlib-shipkit 2.1.0 → 2.2.0

package/src/cli/cmd_GlobalProcesses.ts

@@ -172,6 +172,8 @@ export type SwitchDeps = {
 /** the longest a switch is followed: a bring-up polls its health for minutes */
 export const SWITCH_WAIT_MS = 10 * 60_000
 const SWITCH_POLL_MS = 1_000
+/** how long the state the switch left counts as pm not having acted yet */
+export const SWITCH_GRACE_MS = 30_000
 
 /** flip a global process through pm, then follow pm's state until its probe
  *  settles it: 0 once it is up (or down for stop), 1 otherwise. The launcher's
@@ -183,7 +185,8 @@ export async function switchProcess(id: string, act: SwitchAct, d: SwitchDeps, w
         return 1
     }
     const want = act === 'stop' ? 'down' : 'up'
-    const end = d.now() + waitMs
+    const start = d.now()
+    const end = start + waitMs
     let said = ''
     for (;;) {
         const v = await d.view(id)
@@ -195,7 +198,9 @@ export async function switchProcess(id: string, act: SwitchAct, d: SwitchDeps, w
             said = v.status
             d.log(`${id}: ${v.status}`)
         }
-        const moving = v.status === 'starting' || v.status === 'stopping' || v.want !== want
+        // the state it is leaving, read just after the switch, is pm not there yet
+        const leaving = v.status === (want === 'up' ? 'down' : 'up') && d.now() - start < SWITCH_GRACE_MS
+        const moving = v.status === 'starting' || v.status === 'stopping' || v.want !== want || leaving
         if (!moving) {
             if (v.status === want) return 0
             d.log(`FAIL ${id} is ${v.status}, not ${want}${v.note == null ? '' : `: ${v.note}`}`)

package/src/cli/cmd_Shot.ts

@@ -0,0 +1,63 @@
+// sk shot: a png of any url, or a clip with --video, through the machine's
+// one warm browser (shot/client.ts). A repo's own CLI wraps it with its setup
+// flags; the trailer's `url` film calls the same functions.
+import { relative } from 'path'
+import { Command, Option } from 'clipanion'
+import { clipUrl, shotUrl, type ShotResult } from '../shot/client.ts'
+import { askOf, isClip } from '../shot/shot-ask.ts'
+
+export const renderShot = (r: ShotResult, cwd: string): string[] => {
+    const phases = Object.entries(r.phases)
+        .map(([k, v]) => `${k} ${v}`)
+        .join(', ')
+    const out = relative(cwd, r.out)
+    const lines = [`ok ${out.startsWith('..') ? r.out : out} in ${r.ms} ms (${phases}; ${r.via}) ${r.note}`]
+    for (const e of r.errors.slice(0, 10)) lines.push(`WARN page ${e}`)
+    if (r.errors.length > 10) lines.push(`WARN page ${r.errors.length - 10} more errors`)
+    return lines
+}
+
+export class ShotCommand extends Command {
+    static override paths = [['shot']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'a png of any url through the warm browser, or an mp4 clip with --video',
+        details:
+            'one warm headless chromium for the whole machine (the `shot` global process, started when down). A still reuses the warm page when it already shows the url, so a warm shot answers in about 0.1 s. A page with `<meta name="shot-ready" content="wait">` is shot once it sets content="ready"; any other page --wait ms after its load. --video films a page that is a canvas through its WebCodecs encoder (H.264 muxed with no second encode), and any other page as chromium paints it (its screencast, encoded by ffmpeg as the frames arrive); --dom films the page even when a canvas fills it',
+        examples: [
+            ['a png of a running dev server', 'sk shot localhost:5173/'],
+            ['a phone screen, at the pixel ratio of a phone', 'sk shot :5173/play --viewport 390,844 --dpr 3 --out shots/phone.png'],
+            ['a 3 s clip', 'sk shot :4808/ --video 3 --out clips/walk.mp4'],
+            ['a clip of a whole web app page, canvas or not', 'sk shot :5173/settings --video 3 --dom'],
+        ],
+    })
+
+    url = Option.String({ required: true, name: 'url' })
+    viewport = Option.String('--viewport', { description: 'w,h in css pixels (default 1280,720)' })
+    dpr = Option.String('--dpr', { description: 'device pixel ratio (default 1)' })
+    out = Option.String('--out', { description: 'the file (default .shipkit/tmp/shots/<url>.png, or .mp4 with --video)' })
+    reload = Option.Boolean('--reload', false, { description: 'load the page again even when the warm page shows this url' })
+    wait = Option.String('--wait', { description: 'ms after load for a page with no ready mark (default 300)' })
+    video = Option.String('--video', { description: 'seconds of clip: an mp4 of the page (its canvas when a canvas fills it)' })
+    fps = Option.String('--fps', { description: 'clip frames per second (default 30)' })
+    long = Option.Boolean('--long', false, { description: 'allow a clip past 30 s' })
+    dom = Option.Boolean('--dom', false, { description: 'clip the page itself even when a canvas fills it' })
+    json = Option.Boolean('--json', false, { description: 'one json line: out, ms, phases, errors, note, via' })
+
+    async execute(): Promise<number> {
+        const cwd = process.cwd()
+        const err = (l: string) => this.context.stderr.write(`${l}\n`)
+        try {
+            const a = askOf({ url: this.url, viewport: this.viewport, dpr: this.dpr, out: this.out, reload: this.reload, wait: this.wait, video: this.video, fps: this.fps, long: this.long, dom: this.dom }, cwd)
+            const r = isClip(a) ? await clipUrl(a, err) : await shotUrl(a, err)
+            if (this.json) this.context.stdout.write(`${JSON.stringify(r)}\n`)
+            else for (const l of renderShot(r, cwd)) this.context.stdout.write(`${l}\n`)
+            return 0
+        } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e)
+            err(msg.startsWith('FAIL') ? msg : `FAIL shot: ${msg}`)
+            return 1
+        }
+    }
+}

package/src/cli/cmd_Start.ts

@@ -1,8 +1,7 @@
 // shipkit start — ensure <root>/<name> exists (+ a CLAUDE.md include),
 // printing the dir on stdout so a shell alias can cd there (a child process
-// can't cd its parent). Thin clipanion surface; logic in start-repo.ts.
+// can't cd its parent). Thin clipanion surface; logic in start-repo.ts, imported when it runs.
 import { Command, Option } from 'clipanion'
-import { startRepo } from '../start-repo.ts'
 
 export class StartCommand extends Command {
     static override paths = [['start']]
@@ -10,13 +9,14 @@ export class StartCommand extends Command {
     static override usage = Command.Usage({
         category: 'Setup',
         description: 'create or enter ~/dev/<name>, ready to work in: a private github repo and a push unless --no-github',
-        details: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in. On any dir with no commit history it writes the day-one shape (package.json + src/index.ts + lint/fmt/typecheck, tsconfig, .vscode tasks + settings, the verify skill, an agent/ wiki, .shipkit/reflections), installs the toolchain, wires shipkit (repo.config.ts via init), and runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Loose files ride in that first commit, and only a repo with real history is left as it is. Writes are create-only for files, additive for package.json scripts and .gitignore. CLAUDE.md is the two-line house template on its own (HOUSE_INCLUDE in src/start-repo.ts: the base wiki include, then `@./agent/index.md`, and --include overrides it), applied only on a machine where the house index exists, and the agent route lands last whenever the repo has agent/index.md. The house lines also opt the repo into the .claude/ policy files (a pre-approved shell allowlist + the attribution silencer), so a start with no house widens no agent permissions. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
+        details: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in. On any dir with no commit history it writes the day-one shape (package.json + src/index.ts + the project CLI on the kit (src/cli.ts, src/cli/cmd_Dev.ts, the cli script and a bin of the repo name) + lint/fmt/typecheck, tsconfig, .vscode tasks + settings, the verify skill, an agent/ wiki, .shipkit/reflections), installs the toolchain, wires shipkit (repo.config.ts via init), and runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Loose files ride in that first commit, and only a repo with real history is left as it is. Writes are create-only for files, additive for package.json scripts and .gitignore. CLAUDE.md is the two-line house template on its own (HOUSE_INCLUDE in src/start-repo.ts: the base wiki include, then `@./agent/index.md`, and --include overrides it), applied only on a machine where the house index exists, and the agent route lands last whenever the repo has agent/index.md. The house lines also opt the repo into the .claude/ policy files (a pre-approved shell allowlist + the attribution silencer), so a start with no house widens no agent permissions. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
         examples: [
             ['create or enter ~/dev/pong: dir, package.json, shipkit wiring, git, first commit, private github repo, push, the two-line CLAUDE.md', 'sk start pong'],
             ['another house: replace the include lines', "sk start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],
             ['adopt a pre-existing repo from anywhere', 'sk start my-old-project'],
             ['force the private github repo for a folder that was already there', 'sk start old-notes --github'],
             ['local git and the first commit, never touch github', 'sk start pong --no-github'],
+            ['give an existing repo its project CLI (a started repo has one)', 'sk start my-old-project --cli'],
         ],
     })
 
@@ -27,7 +27,11 @@ export class StartCommand extends Command {
     skip = Option.Array('--skip', { description: 'repo names shipkit never touches: no CLAUDE.md include, no wiring. Omitted: the house list (HOUSE_SKIP in src/start-repo.ts)' })
     github = Option.Boolean('--github', { description: 'ON by default when a repo is being STARTED (a dir this run created, or one with a package.json): it gets a PRIVATE github repo wired as origin, and the first commit is pushed to it. Pass --github to force it for a pre-existing folder, --no-github to keep everything local, the first commit included (SHIPKIT_NO_GITHUB=1 does it for every run)' })
 
+    withCli = Option.Boolean('--cli', false, { description: 'on a repo with history: write the project CLI skeleton (src/cli.ts on the kit, an example family, package.json cli and bin), refused when the repo already has a CLI. A started repo always gets it' })
+
     async execute(): Promise<number> {
-        return startRepo(this.name, { root: this.root, include: this.include, alsoOk: this.alsoOk, skip: this.skip, github: this.github })
+        // loaded here, so the scaffold and the git chain cost nothing to every other command
+        const { startRepo } = await import('../start-repo.ts')
+        return startRepo(this.name, { root: this.root, include: this.include, alsoOk: this.alsoOk, skip: this.skip, github: this.github, cli: this.withCli })
     }
 }

package/src/cli/cmd_Trailer.ts

@@ -0,0 +1,108 @@
+// sk trailer: a cut's .trailer file → its mp4, filming only the takes whose film line changed (trailer/build.ts).
+// Every module loads inside execute: the cli registers this file on every `sk` call
+import { Command, Option } from 'clipanion'
+
+const DETAILS = `the trailer language: shots with a film line each (clip <file>, image <file>, card, run "<cmd {out}>", url <route> through the shot service, or a film row of the project CLI), titles in the brand's look, cuts, sections in bars, music, sfx and voice; a \`vertical\` header finishes a short with the brand's lockup, watermark and end card. Outputs land in trailer/<trailer>/out/. Page: wiki build/trailer.md`
+
+/** --refilm alone: every stale take; --refilm a,b: those shots */
+const refilmOf = (v: string | boolean | undefined): 'stale' | ReadonlySet<string> | null => (v === undefined || v === false ? null : v === true ? 'stale' : new Set(v.split(',')))
+
+async function run(context: { stdout: NodeJS.WritableStream; stderr: NodeJS.WritableStream }, body: (say: (l: string) => void, root: string, cwd: string) => Promise<number>): Promise<number> {
+    const say = (l: string): void => void context.stdout.write(`${l}\n`)
+    const { Refused } = await import('../trailer/build.ts')
+    const { findRepoRoot } = await import('../ts/config.ts')
+    const cwd = process.cwd()
+    try {
+        return await body(say, findRepoRoot(cwd), cwd)
+    } catch (e) {
+        context.stderr.write(`FAIL: ${e instanceof Refused ? `trailer: ${e.message}` : e instanceof Error ? (e.stack ?? e.message) : String(e)}\n`)
+        return 1
+    }
+}
+
+export class TrailerCommand extends Command {
+    static override paths = [['trailer']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'build a cut from its .trailer: film what is missing, stitch, strip, montage',
+        details: DETAILS,
+        examples: [
+            ['the one cut under trailer/', 'sk trailer'],
+            ['one cut by its file', 'sk trailer trailer/launch/main.trailer'],
+            ['film again the takes of two shots', 'sk trailer --refilm intro,menu'],
+            ['encoded by x264 for a release', 'sk trailer --final'],
+        ],
+    })
+
+    file = Option.String({ required: false })
+    refilm = Option.String('--refilm', { tolerateBoolean: true, description: 'film again: every stale take, or the named shots (a,b)' })
+    final = Option.Boolean('--final', false, { description: 'encode with x264 for a release (default: the fast draft encoder)' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const b = await import('../trailer/build.ts')
+            const l = b.load(b.trailerFile(this.file, root, cwd), root)
+            if (!b.sayErrors(l, say, cwd)) return 1
+            await b.build(l, { refilm: refilmOf(this.refilm), final: this.final, say, cwd })
+            return 0
+        })
+    }
+}
+
+export class TrailerCheckCommand extends Command {
+    static override paths = [['trailer', 'check']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'parse and check a .trailer: every error at its line, the timeline, each take\'s state',
+        details: DETAILS,
+        examples: [
+            ['the one cut under trailer/', 'sk trailer check'],
+            ['one cut by its folder', 'sk trailer check trailer/launch'],
+        ],
+    })
+
+    file = Option.String({ required: false })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const t0 = performance.now()
+            const b = await import('../trailer/build.ts')
+            const l = b.load(b.trailerFile(this.file, root, cwd), root)
+            if (!b.sayErrors(l, say, cwd)) return 1
+            const { takesOf, worldStamp } = await import('../trailer/footage.ts')
+            for (const line of b.timeline(l, takesOf(l.t, root), worldStamp(root), cwd)) say(line)
+            say(`ok: checked in ${((performance.now() - t0) / 1000).toFixed(2)} s`)
+            return 0
+        })
+    }
+}
+
+export class TrailerShotCommand extends Command {
+    static override paths = [['trailer', 'shot']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'one shot alone with its titles, no sound, and its nine frames on one png',
+        details: DETAILS,
+        examples: [
+            ['a shot of the one cut', 'sk trailer shot intro'],
+            ['a shot of a named cut, its take filmed again', 'sk trailer shot intro trailer/launch --refilm intro'],
+        ],
+    })
+
+    name = Option.String({ required: true })
+    file = Option.String({ required: false })
+    refilm = Option.String('--refilm', { tolerateBoolean: true, description: 'film again: every stale take, or the named shots (a,b)' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const b = await import('../trailer/build.ts')
+            const l = b.load(b.trailerFile(this.file, root, cwd), root)
+            if (!b.sayErrors(l, say, cwd)) return 1
+            await b.previewShot(l, this.name, { refilm: refilmOf(this.refilm), final: false, say, cwd })
+            return 0
+        })
+    }
+}

package/src/cli/kit/builtins.ts

@@ -0,0 +1,40 @@
+// the commands every project CLI gets for free: its docs pages and its call
+// log. They are shipkit's own `commands` and `calls` classes, given the
+// project's name in their examples and the project's root for the log.
+import { Command } from 'clipanion'
+import { CallsCommand } from '../cmd_Calls.ts'
+import { CommandsCommand } from '../cmd_Commands.ts'
+import { callsFile } from './calls.ts'
+import type { CommandClass, KitContext } from './verb.ts'
+
+export function builtinCommands(bin: string): { docs: CommandClass[]; calls: CommandClass[] } {
+    class ProjectCommands extends CommandsCommand {
+        static override usage = Command.Usage({
+            category: 'Docs',
+            description: `every ${bin} command as markdown or json; --out writes the commands page`,
+            details: `the registry described by itself. --out rewrites the block between the ${bin}:commands markers, --essentials rewrites the everyday page whole, --check fails while a page lags the registry or a row lacks its category, description or example. --json is how another tool reads this registry.`,
+            examples: [
+                ['the markdown', `${bin} commands`],
+                ['as json, for another tool', `${bin} commands --json`],
+                ['write both agent pages', `${bin} commands --out agent/${bin}.md --essentials agent/${bin}-essentials.md`],
+                ['fail when a page is stale', `${bin} commands --out agent/${bin}.md --essentials agent/${bin}-essentials.md --check`],
+            ],
+        })
+        static override shapeRule = true
+    }
+    class ProjectCalls extends CallsCommand {
+        static override usage = Command.Usage({
+            category: 'Docs',
+            description: `every ${bin} run logged with its time: per command how often, how long, the slowest`,
+            details: `reads .shipkit/logs/${bin}-calls.jsonl under the repo root. A run with no end line was killed or still runs. ${bin.toUpperCase()}_LOG=off writes nothing.`,
+            examples: [
+                ['what agents waited on today', `${bin} calls --since 1d`],
+                ['one family', `${bin} calls --cmd <family>`],
+            ],
+        })
+        override logFile(): string {
+            return callsFile((this.context as unknown as KitContext).root, bin)
+        }
+    }
+    return { docs: [ProjectCommands as unknown as CommandClass], calls: [ProjectCalls as unknown as CommandClass] }
+}

package/src/cli/kit/calls.ts

@@ -0,0 +1,177 @@
+// every run of a CLI, logged: a start line at launch, an end line at any exit
+// with its time, CPU and memory, the same id on both. A start with no end was
+// killed or still runs. JSON lines, one append each, so runs at once never mix.
+// `<cli> calls` reads it back, so a speed pass starts from what agents waited on.
+// `<CLI>_LOG=off` writes nothing, and neither does a run under `bun test`. Past
+// 2 MB the log moves to `<file>.1` and starts again, so it never grows unbounded.
+import { appendFileSync, mkdirSync, renameSync, statSync } from 'fs'
+import { dirname, join } from 'path'
+import { LAYOUT } from '../../core/layout.ts'
+
+export type CallStart = {
+    id: string
+    at: string
+    argv: string[]
+    cwd: string
+    pid: number
+    /** `<CLI>_AGENT`, else null: who ran it */
+    agent: string | null
+    /** the run of the same CLI that spawned this one, null for a run of its own */
+    parent: string | null
+}
+
+export type CallEnd = {
+    id: string
+    /** the command's path, null when none matched (a listing, a typo) */
+    cmd: string | null
+    /** from the process start */
+    ms: number
+    /** building the registry: the import of the families the call needed */
+    loadMs: number
+    cpuMs: number
+    rssMb: number
+    code: number
+}
+
+/** where a CLI's calls go: `<root>/.shipkit/logs/<bin>-calls.jsonl` */
+export const callsFile = (root: string, bin: string): string => join(root, LAYOUT.logs, `${bin}-calls.jsonl`)
+
+/** the env prefix of a CLI: `my-tool` → `MY_TOOL` */
+export const envPrefix = (bin: string): string => bin.toUpperCase().replace(/[^A-Z0-9]/g, '_')
+
+/** past this size the log moves to `<file>.1` (replacing the older one) and starts again */
+export const CALLS_MAX_BYTES = 2 * 1024 * 1024
+
+/** a long argument (a pasted text) is cut, so a line stays one append */
+const ARG_MAX = 300
+
+/** logs this run's start, and its end on any exit. The caller names the
+ *  command and the registry load time once it knows them */
+export function logCall(file: string, bin: string, argv: readonly string[], env: NodeJS.ProcessEnv = process.env): { matched(cmd: string | null, loadMs: number): void } {
+    const pre = envPrefix(bin)
+    if (env[`${pre}_LOG`] === 'off' || env.NODE_ENV === 'test') return { matched: () => {} }
+    let warned = false
+    try { if (statSync(file).size > CALLS_MAX_BYTES) renameSync(file, `${file}.1`) } catch { /* no log yet */ }
+    const append = (line: object): void => {
+        try {
+            mkdirSync(dirname(file), { recursive: true })
+            appendFileSync(file, `${JSON.stringify(line)}\n`)
+        } catch (e) {
+            if (!warned) console.error(`WARN ${bin}: the call log could not be written (${file}): ${(e as Error).message}`)
+            warned = true
+        }
+    }
+    const id = `${Date.now().toString(36)}-${process.pid}`
+    const end: Pick<CallEnd, 'cmd' | 'loadMs'> = { cmd: null, loadMs: 0 }
+    const start: CallStart = {
+        id,
+        at: new Date().toISOString(),
+        argv: argv.map((a) => (a.length > ARG_MAX ? `${a.slice(0, ARG_MAX)}…` : a)),
+        cwd: process.cwd(),
+        pid: process.pid,
+        agent: env[`${pre}_AGENT`]?.trim() || null,
+        parent: env[`${pre}_CALL`] ?? null,
+    }
+    append(start)
+    env[`${pre}_CALL`] = id
+    process.on('exit', (code) => {
+        const cpu = process.cpuUsage()
+        append({ id, ...end, ms: Math.round(performance.now()), cpuMs: Math.round((cpu.user + cpu.system) / 1000), rssMb: Math.round(process.resourceUsage().maxRSS / 1024), code } satisfies CallEnd)
+    })
+    return { matched: (cmd, loadMs) => { end.cmd = cmd; end.loadMs = Math.round(loadMs) } }
+}
+
+export type CallsQuery = {
+    /** epoch ms: only the runs that started after */
+    since?: number
+    /** a command path prefix */
+    cmd?: string
+    /** a folder: only the runs started inside it */
+    under?: string
+    /** keep the runs another run of the same CLI spawned */
+    nested?: boolean
+    /** how many slowest runs to list */
+    top?: number
+    /** the id of the run asking, which has no end yet */
+    self?: string
+}
+
+export type CallsRow = { cmd: string; runs: number; noEnd: number; failed: number; p50: number; p95: number; max: number; totalS: number; loadP50: number; rssMax: number }
+export type CallsReport = { runs: number; rows: CallsRow[]; slowest: { ms: number; at: string; agent: string | null; argv: string }[] }
+
+/** `30m`, `2h`, `3d` or a date, as epoch ms; null when unreadable */
+export function sinceOf(s: string, now: number): number | null {
+    const m = /^(\d+)([mhd])$/.exec(s)
+    if (m) return now - Number(m[1]) * { m: 60e3, h: 3600e3, d: 86400e3 }[m[2] as 'm' | 'h' | 'd']
+    const t = Date.parse(s)
+    return Number.isNaN(t) ? null : t
+}
+
+const quantile = (xs: number[], p: number): number => {
+    if (xs.length === 0) return 0
+    const s = [...xs].sort((a, b) => a - b)
+    return s[Math.min(s.length - 1, Math.floor(p * s.length))] ?? 0
+}
+
+/** the call log read back: per command how often, how long, how heavy, and the slowest runs */
+export function callsReport(text: string, q: CallsQuery = {}): CallsReport {
+    const starts = new Map<string, CallStart>()
+    const ends = new Map<string, CallEnd>()
+    for (const line of text.split('\n')) {
+        if (line.trim() === '') continue
+        let r: CallStart | CallEnd
+        try { r = JSON.parse(line) as CallStart | CallEnd } catch { continue }
+        if ('at' in r) starts.set(r.id, r)
+        else ends.set(r.id, r)
+    }
+    type Run = { s: CallStart; e: CallEnd | null; cmd: string }
+    const runs: Run[] = []
+    for (const s of starts.values()) {
+        if (s.id === q.self || Date.parse(s.at) < (q.since ?? 0) || (q.nested !== true && s.parent != null)) continue
+        if (q.under != null && s.cwd !== q.under && !s.cwd.startsWith(`${q.under}/`)) continue
+        const e = ends.get(s.id) ?? null
+        const flag = s.argv.findIndex((a) => a.startsWith('-'))
+        const words = flag === -1 ? s.argv : s.argv.slice(0, flag)
+        const cmd = e?.cmd ?? (words.slice(0, 2).join(' ') || '(none)')
+        if (q.cmd != null && !cmd.startsWith(q.cmd)) continue
+        runs.push({ s, e, cmd })
+    }
+    const byCmd = new Map<string, Run[]>()
+    for (const r of runs) byCmd.set(r.cmd, [...(byCmd.get(r.cmd) ?? []), r])
+    const rows = [...byCmd].map(([cmd, rs]): CallsRow => {
+        const done = rs.flatMap((r) => (r.e ? [r.e] : []))
+        const ms = done.map((e) => e.ms)
+        return {
+            cmd,
+            runs: rs.length,
+            noEnd: rs.length - done.length,
+            failed: done.filter((e) => e.code !== 0).length,
+            p50: quantile(ms, 0.5),
+            p95: quantile(ms, 0.95),
+            max: Math.max(0, ...ms),
+            totalS: Math.round(ms.reduce((a, b) => a + b, 0) / 1000),
+            loadP50: quantile(done.map((e) => e.loadMs), 0.5),
+            rssMax: Math.max(0, ...done.map((e) => e.rssMb)),
+        }
+    })
+    rows.sort((a, b) => b.totalS - a.totalS || b.p95 - a.p95 || a.cmd.localeCompare(b.cmd))
+    const slowest = runs
+        .flatMap((r) => (r.e ? [{ ms: r.e.ms, at: r.s.at, agent: r.s.agent, argv: r.s.argv.join(' ') }] : []))
+        .sort((a, b) => b.ms - a.ms)
+        .slice(0, q.top ?? 10)
+    return { runs: runs.length, rows, slowest }
+}
+
+/** the report as a table, then the slowest runs */
+export function renderCallsReport(bin: string, r: CallsReport, file: string): string {
+    const head = ['command', 'runs', 'no end', 'failed', 'p50 ms', 'p95 ms', 'max ms', 'total s', 'load p50', 'rss max MB']
+    const table = [head, ...r.rows.map((x) => [x.cmd, x.runs, x.noEnd, x.failed, x.p50, x.p95, x.max, x.totalS, x.loadP50, x.rssMax].map(String))]
+    const widths = head.map((_, i) => Math.max(...table.map((t) => (t[i] ?? '').length)))
+    const out = [`${r.runs} runs · ${file}`, 'a run with no end line was killed or still runs; time is from the process start, load is building the registry', '']
+    for (const t of table) out.push(t.map((c, i) => (i === 0 ? c.padEnd(widths[i] ?? 0) : c.padStart(widths[i] ?? 0))).join('  '))
+    if (r.slowest.length > 0) {
+        out.push('', `the ${r.slowest.length} slowest runs`)
+        for (const s of r.slowest) out.push(`${String(s.ms).padStart(8)} ms  ${s.at.slice(0, 19)}  ${s.agent ?? '-'}  ${bin} ${s.argv}`)
+    }
+    return `${out.join('\n')}\n`
+}

package/src/cli/kit/families.ts

@@ -0,0 +1,67 @@
+// a project CLI is a table of families: the first word of a call loads the
+// family that owns it and nothing else, a word nobody owns (a listing, a typo)
+// loads them all. A family file exports `commands` and imports nothing heavy
+// at its top, so even the full load answers in milliseconds.
+import type { CommandClass } from './verb.ts'
+
+export type Family = {
+    /** the first words its commands start with */
+    roots: string[]
+    load: () => Promise<{ commands: CommandClass[] }>
+    /** its commands read the whole registry (the docs): every family loads with it */
+    all?: true
+}
+
+/** the families a call needs: the one owning its first word, else every one */
+export function familiesFor<F extends Family>(argv: readonly string[], families: readonly F[]): F[] {
+    const own = families.find((f) => f.roots.includes(argv[0] ?? ''))
+    return own != null && own.all !== true ? [own] : [...families]
+}
+
+/** the first words two families both claim: a call would load the wrong one */
+export function rootClashes(families: readonly Family[]): string[] {
+    const seen = new Set<string>()
+    const out = new Set<string>()
+    for (const f of families) for (const r of f.roots) (seen.has(r) ? out : seen).add(r)
+    return [...out]
+}
+
+/** what clipanion tells of a registered command */
+export type ListedDefinition = { path: string; category?: string | null; description?: string | null }
+
+const HELP_WORDS = ['--help', '-h', 'help']
+
+/** a definition's path without the binary name clipanion puts in front */
+export const stripBin = (bin: string, path: string): string => (path.startsWith(`${bin} `) ? path.slice(bin.length + 1) : path)
+
+/** the family word a call asks a listing of: '' for every command, a first
+ *  word for its family, null to run the call. A word that is itself a command runs */
+export function listingOf(bin: string, argv: readonly string[], defs: readonly ListedDefinition[]): string | null {
+    if (argv.length === 0 || (argv.length === 1 && HELP_WORDS.includes(argv[0]!))) return ''
+    if (argv.length > 2 || (argv.length === 2 && !HELP_WORDS.includes(argv[1]!))) return null
+    const word = argv[0]!
+    const paths = defs.map((d) => stripBin(bin, d.path))
+    if (paths.includes(word) || !paths.some((p) => p.startsWith(`${word} `))) return null
+    return word
+}
+
+/** every command of a family (all when ''), one line each, grouped by category */
+export function listing(bin: string, defs: readonly ListedDefinition[], word: string, label?: string): string {
+    const rows = defs
+        .map((d) => ({ path: stripBin(bin, d.path), category: (d.category ?? '').trim() || 'Other', description: (d.description ?? '').trim() }))
+        .filter((r) => !r.path.startsWith('-') && (word === '' || r.path === word || r.path.startsWith(`${word} `)))
+        .sort((a, b) => a.category.localeCompare(b.category) || a.path.localeCompare(b.path))
+    const width = Math.max(0, ...rows.map((r) => r.path.length)) + bin.length + 3
+    const out = word === '' && label != null ? [label, ''] : []
+    let category = ''
+    for (const r of rows) {
+        if (r.category !== category) {
+            if (category !== '') out.push('')
+            out.push(r.category)
+            category = r.category
+        }
+        out.push(`  ${`${bin} ${r.path}`.padEnd(width)}${r.description}`)
+    }
+    out.push('', `${bin} <command> --help: its usage, its examples and its flags`)
+    return `${out.join('\n')}\n`
+}

package/src/cli/kit/index.ts

@@ -0,0 +1,8 @@
+// the project CLI kit: what a repo's `src/cli.ts` and its family files import
+// (`rvlib-shipkit/cli-kit`). Command and Option come from here, so a project
+// needs no clipanion of its own and its classes match the kit's.
+export { Command, Option } from 'clipanion'
+export { type Family, familiesFor, listing, listingOf } from './families.ts'
+export { callsFile, logCall } from './calls.ts'
+export { type ProjectCliSpec, projectCli, runProjectCli } from './project-cli.ts'
+export { argvOf, type AskTool, type CommandClass, type Essential, type Film, filmCall, type KitContext, type Run, type Verb, verbs } from './verb.ts'

package/src/cli/kit/pages-check.ts

@@ -0,0 +1,36 @@
+// the body of a project CLI's pages check (the file `sk start` writes in
+// src/cli/): the CLI's `commands --check` says whether both agent pages match
+// the registry, and the repair writes them. The check file itself declares
+// where it runs, so the policy stays readable in the repo.
+import type { FixResult } from '../../check.ts'
+import type { CheckCtx } from '../../core/check-ctx.ts'
+
+/** the first FAIL line of a run, else what it printed on one line */
+const said = (out: string): string => {
+    const lines = out.trim().split('\n')
+    return lines.find((l) => l.startsWith('FAIL')) ?? lines.join('; ')
+}
+
+export function cliPagesCheck(name: string, entry = 'src/cli.ts'): {
+    description: string
+    inputs: string[]
+    run: (c: CheckCtx) => Promise<void>
+    repair: (c: CheckCtx) => Promise<FixResult>
+} {
+    const all = `agent/${name}.md`
+    const essentials = `agent/${name}-essentials.md`
+    const gen = ['bun', entry, 'commands', '--out', all, '--essentials', essentials]
+    return {
+        description: `the ${name} command pages match its registry`,
+        inputs: [entry, entry.replace(/\.ts$/, ''), all, essentials],
+        run: async (c) => {
+            const r = await c.exec([...gen, '--check'], { cwd: c.root, env: { [`${name.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_LOG`]: 'off' } })
+            if (r.code === 0) c.ok(said(r.out))
+            else c.fail(said(r.out), `${name} ${gen.slice(2).join(' ')}`)
+        },
+        repair: async (c) => {
+            const r = await c.exec(gen, { cwd: c.root })
+            return { changed: r.code === 0 && r.out.includes('rewritten'), summary: said(r.out) }
+        },
+    }
+}

package/src/cli/kit/project-cli.ts

@@ -0,0 +1,73 @@
+// a project's own CLI in one call: `runProjectCli({ name, root, families })`.
+// It loads only the family the first word needs, lists one line per command
+// when asked for a listing, logs every run, and adds `commands` (the agent
+// pages, generated) and `calls` (the log, read back). The bar: the bare
+// listing answers in well under a second.
+import { type BaseContext, Builtins, Cli } from 'clipanion'
+import { callsFile, logCall } from './calls.ts'
+import { type Family, familiesFor, listing, listingOf, rootClashes } from './families.ts'
+import type { AskTool, CommandClass, KitContext } from './verb.ts'
+
+export type ProjectCliSpec = {
+    /** the binary name: the listing, the examples, the log file and its env prefix use it */
+    name: string
+    /** the repo root: rows run from it, the call log lives under it */
+    root: string
+    families: Family[]
+    /** one line above the bare listing */
+    label?: string
+    version?: string
+    /** the warm path of `{ tool }` rows */
+    askTool?: AskTool
+}
+
+/** the kit's own families, after the project's */
+function kitFamilies(bin: string): Family[] {
+    const builtins = async () => (await import('./builtins.ts')).builtinCommands(bin)
+    return [
+        { roots: ['commands'], load: async () => ({ commands: (await builtins()).docs }), all: true },
+        { roots: ['calls'], load: async () => ({ commands: (await builtins()).calls }) },
+    ]
+}
+
+/** what the kit adds to clipanion's context */
+export type KitExtra = Omit<KitContext, keyof BaseContext>
+
+/** the cli with the families `argv` needs, and the context its commands run in */
+export async function projectCli(spec: ProjectCliSpec, argv: readonly string[], cwd = process.cwd()): Promise<{ cli: Cli<KitContext>; context: KitExtra }> {
+    const families = [...spec.families, ...kitFamilies(spec.name)]
+    const clash = rootClashes(families)
+    if (clash.length > 0) throw new Error(`${spec.name}: two families claim the first word ${clash.map((w) => `'${w}'`).join(', ')}, give each word one family`)
+    const cli = new Cli<KitContext>({ binaryLabel: spec.label ?? spec.name, binaryName: spec.name, binaryVersion: spec.version, enableCapture: true, enableColors: process.stdout.isTTY === true && (process.env.NO_COLOR ?? '') === '' })
+    cli.register(Builtins.HelpCommand)
+    if (spec.version != null) cli.register(Builtins.VersionCommand)
+    const need = familiesFor(argv, families)
+    const classes: CommandClass[] = []
+    for (const mod of await Promise.all(need.map((f) => f.load()))) for (const c of mod.commands) { cli.register(c); classes.push(c) }
+    return { cli, context: { root: spec.root, cwd, classes, askTool: spec.askTool } }
+}
+
+/** the path of the command a call runs, null when none matches */
+function commandOf(cli: Cli<KitContext>, argv: string[], context: KitExtra): string | null {
+    try {
+        const path = (cli.process(argv, context).constructor as { paths?: string[][] }).paths?.[0]?.join(' ') ?? null
+        return path?.startsWith('-') === true ? 'help' : path
+    } catch {
+        return null
+    }
+}
+
+const closedPipe = (e: unknown): boolean => e instanceof Error && 'code' in e && e.code === 'EPIPE'
+
+/** the whole entry of a project CLI: log, load, then list or run */
+export async function runProjectCli(spec: ProjectCliSpec, argv: string[] = process.argv.slice(2)): Promise<void> {
+    // a reader that closes early (`<cli> | head`) ends the run quietly
+    process.stdout.on('error', (e) => (closedPipe(e) ? process.exit(0) : undefined))
+    const call = logCall(callsFile(spec.root, spec.name), spec.name, argv)
+    const t0 = performance.now()
+    const { cli, context } = await projectCli(spec, argv)
+    call.matched(commandOf(cli, argv, context), performance.now() - t0)
+    const word = listingOf(spec.name, argv, cli.definitions())
+    if (word !== null) { process.stdout.write(listing(spec.name, cli.definitions(), word, spec.label)); return }
+    await cli.runExit(argv, context)
+}