rvlib-shipkit 2.1.1 → 2.2.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 2.2.0
+
+- **The project CLI kit, `rvlib-shipkit/cli-kit`, and a project CLI from `sk start`.** A repo's own CLI is `runProjectCli({ name, root, families })`: the first word loads only its family, the bare listing prints one line per command (0.027 s on a fresh repo), and every run is logged to `.shipkit/logs/<cli>-calls.jsonl`. A command over code that exists is a row, `verbs([{ path, category, description, examples, run: { bun } | { cmd } | { tool, cold } }])`, never a second implementation. A row marked `essential` lands on the everyday page, and a row marked `film: 'still' | 'clip'` takes `--out` (resolved against the caller's cwd), a clip also `--seconds`, and fails when it exits 0 without writing `--out`. The kit adds `<cli> commands` (`--out` and `--essentials` write the agent pages, `--check` fails on a stale page or a row with no category, a long description or no example starting with its words, `--json` is the registry for other tools) and `<cli> calls`. `sk start` writes the skeleton on day one: `src/cli.ts`, `src/cli/cmd_Dev.ts` with a dev row and a commented shot row, both agent pages generated, the agent index loading the essentials page, package.json `cli` and a `bin` of the repo name. `sk start <name> --cli` writes it into a repo with history, and refuses one that already has a CLI. The scaffold tsconfig names `types: ["bun"]`, which TypeScript 7 needs for Bun's globals.
+- **`sk calls`: every sk run logged machine wide** (`~/.shipkit/logs/sk-calls.jsonl`, `SK_LOG=off` to stop), read back per command with the slowest runs, `--here` for one repo. It adds no measurable time to `sk --help`, and `sk start` now loads its scaffold only when it runs.
+- **`sk trailer`: a `.trailer` file in any repo becomes an mp4 and its contact strip.** The trailer language, its core words: a header (`trailer`, `size`, `fps`, `music`, `duck`, `fade-in`), shots with one film line each, titles, cuts, `from`, `push`, `frame`, `lift`, `shake`, `flash`, sections in bars with their tempo and meter, `mark`, `starts on`, and music, sfx and voice from files. Every error is at its file and line, all at once, and a file with one error never builds. A film line is `clip <video>`, `image <picture>`, `card`, `run "<command {out}>"`, or a film row of the repo's own CLI: `film <words>` runs `<cli> <words> --out <file>`, with `--seconds <n>` for a clip, the rows read from `<cli> commands --json` only when a line needs them. A take is filmed once into `.shipkit/cache/trailer/footage/<key>`, keyed on what films (the key formula of pkm-multi's trailer, verbatim), and stamped with the repo's world: a stale take is reported and filmed again only on `--refilm`. The stitch renders one piece per section, cached on its ffmpeg arguments and its inputs, so a title edit renders one section and a build with nothing changed takes about 0.6 s. Five title styles (`logo`, `big`, `caption`, `corner`, `line`) and the card wear the repo's brand: the palette of `.shipkit/identity/brand.ts`, its new optional `trailer` section for the face, the logo and each colour, and a house look for a repo with no brand. A `trailer({ sound })` unit in any `<name>.shipkit.ts` resolves sound ids that are not files. Verbs `sk trailer [file]`, `sk trailer check`, `sk trailer shot <name>` (its nine frames on one png).
+- **`sk trailer`: the vertical short from brand data, and `film url <route>`.** The header word `vertical [mark left|right] [outro card|none|<video>]` makes the cut a 9:16 short (1080x1920 unless `size` says otherwise, upright only) finished with the brand's `trailer.vertical` look: a lockup that pops in over every frame under the platforms' top tabs (a wordmark image, else the logo and the name, and a tag pill), a watermark in a bottom corner, an optional outro clip, and an end card whose image hops in, its lines with `*word*` in the accent. Each part takes its colours and face from the brand's look, each is `false` to leave it out, and a repo with no brand gets its logo and its folder name. The finish is cached on the pieces and the mix it reads: an unchanged build stays about 1 s, a title edit renders one section and the finish. `film url <route> [viewport WxH] [wait <time>] [still]` films a page of the repo's dev url (the `url` of its global process, `base <id>` when it has several, started through pm when down) through `shotUrl` and `clipUrl`, a portrait cut at a phone's width. Lifted from pkm-multi's `chi site vertical`; the footage key formula is unchanged.
+- **`sk shot <url>`: a png of any url through one warm browser for the whole machine, `--video <s>` a clip.** The `shot` global process (declared in the lib, `src/shot/shot.shipkit.ts`) starts on the first `sk shot` and never at login. It holds one headless chromium and one booted page, one request at a time. A still of the url the page already shows is a ready check plus chromium's fast capture: 33 to 52 ms in the service, 0.11 to 0.23 s for the whole command, measured on a running vite app. A page with `<meta name="shot-ready" content="wait">` is shot once it sets `content="ready"`, any other page `--wait` ms (300) after its load. `--video` films the page's largest canvas through its own WebCodecs H.264 encoder on its animation frames and muxes the stream into an mp4 with no second encode. It stays out of the way of other work: the browser runs at nice 10, the page is frozen 10 s after a request and loaded again before the next still, and the browser closes after 60 s idle. Code calls `shotUrl` and `clipUrl` from `src/shot/client.ts`. Playwright resolves from the repo that runs the service through `loadPlaywright`, now generic over the slice its caller types.
+- **`sk shot --video` films any web page, canvas or not.** A page that a canvas fills (half the viewport or more) still films that canvas through its WebCodecs encoder. Any other page, or any page with `--dom`, films as chromium paints it: CDP `Page.startScreencast` takes every painted frame, a frame holds on the clip's fixed grid until the next one paints (a still page fills its seconds from one frame), and ffmpeg encodes the jpegs to H.264 as they arrive. Measured on a 3 s animated page against Playwright's `recordVideo`: 90 of 90 distinct frames against 65 of 89, 3.29 s against 3.43 s from the start of filming to the closed file, and 1.8 s of CPU above an idle page against 2.7 s. A 3 s DOM clip takes 3.7 s for the whole command, the canvas path 3.6 s as before. A DOM clip is in css pixels whatever `--dpr`. `clipUrl` takes an optional `dom`, and a clip's request cap now adds its own seconds, so a `--long` clip past about 110 s no longer fails at the 120 s cap.
+- **Plans get a tracked home, `.shipkit/plans/`.** SK004 re-includes `!.shipkit/plans/` in a private repo's managed block, so a dated plan, an arc's board and its lane files survive a cleanup of the scratch, and a lost machine once committed. A repo declared `visibility: 'public'` gets no re-include, through the same filter that keeps its comfy drafts local. The next `sk ci` fix pass rewrites the block, and nothing else changes for anyone. The old root layout migration files the dated plans at the top of `tmp/` (`YYYYMMDD-HHMMSS-<slug>.md`) under `.shipkit/plans/` and moves the rest of the scratch under `.shipkit/tmp/` as before. A plan already in `.shipkit/tmp/` is not moved: the scratch holds other files, and only a human or an agent knows which one is a plan.
+- **`sk reflect` keeps only what the human typed.** A sub-agent hand-back (`<agent-message`) and a message from another Claude session (`<cross-session-message`, `Another Claude session sent a message`) are model output the harness parks in the queue, and the corpus counted them as queued prompts. They are dropped now, typed or queued. A real prompt that mentions `<agent-message` mid text stays.
+- **A red test check names the file that threw outside a test.** bun can count a throw inside a describe callback as `0 fail` beside `1 error`, and the check said `FAIL: 0 test(s) failed`, a red line that read green. It now says `FAIL: 1 error(s) outside any test (tests/light/galerie.test.ts threw error: unknown room: galerie), Ran 1 tests`, and adds the failed test count only when there is one. The record behind the hub keeps that error too: the error inside bun's banner block, a `ReferenceError:` or any named error class included.
+
 ## 2.1.1
 
 - **`--only a,b` takes a comma list** in `sk ci`, `sk cache-audit` and `sk fleet`, the same as repeating the flag.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "2.1.1",
+    "version": "2.2.0",
     "funding": "https://github.com/sponsors/rvion",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
@@ -16,6 +16,7 @@
     },
     "exports": {
         ".": "./src/shipkit.ts",
+        "./cli-kit": "./src/cli/kit/index.ts",
         "./contracts": "./src/contracts/contract-types.ts",
         "./vite": "./src/assets/vite.ts",
         "./src/*": "./src/*"

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

@@ -15,6 +15,7 @@ import { mkdirSync } from 'fs'
 import { dirname, join } from 'path'
 import sharp from 'sharp'
 import { defineKind, type CanvasGen, type ComfyGen, type Kind } from '../kit-config.ts'
+import { HOUSE_FAMILIES, type TrailerLookInput } from '../../trailer/look.ts'
 
 export type Brand = {
     name: string
@@ -29,6 +30,9 @@ export type Brand = {
     /** og layout hook — replaces the WHOLE default card (bg + mark left +
      *  name/tagline right); the hook owns compositing the mark if it wants one */
     drawOg?: (ctx: SKRSContext2D, brand: Brand, size: { w: number; h: number }) => void
+    /** the look every trailer of the repo wears (titles, card, face, logo);
+     *  each value left out is derived from the palette (trailer/look.ts) */
+    trailer?: TrailerLookInput
 }
 
 export const FAVICON_SIZE = 512
@@ -52,9 +56,9 @@ export function identityKinds(brand: Brand): Kind[] {
 }
 
 // named faces first: the generic sans-serif can resolve to a face with no
-// Latin-1 accents (macOS). Each family below carries them, and an absent one
-// is skipped (macOS, Windows, then the common Linux faces)
-const OG_FAMILIES = 'Helvetica, Arial, "DejaVu Sans", "Liberation Sans", "Noto Sans", sans-serif'
+// Latin-1 accents (macOS). Each family carries them, and an absent one is
+// skipped (macOS, Windows, then the common Linux faces)
+const OG_FAMILIES = HOUSE_FAMILIES
 export const ogFont = (px: number, bold = false): string => `${bold ? 'bold ' : ''}${px}px ${OG_FAMILIES}`
 
 // shrink px until text fits maxW (og cards must never clip the tagline)

package/src/assets/run-assets.ts

@@ -122,14 +122,28 @@ async function repoWebRoot(root: string): Promise<string> {
 
 export type IdentityRender = { written: string[] } | { blocked: string }
 
-export async function renderIdentityNow(root: string): Promise<IdentityRender> {
+/** the repo's brand, `.shipkit/identity/brand.ts`: null when the file is
+ *  absent, a string saying why when it does not default-export one */
+export async function loadBrand(root: string): Promise<Brand | null | string> {
     const brandPath = join(root, '.shipkit/identity/brand.ts')
-    if (!existsSync(brandPath)) return { blocked: 'no .shipkit/identity/brand.ts — create one exporting a Brand (name, palette, mark)' }
+    if (!existsSync(brandPath)) return null
     // cache-bust: bun caches dynamic imports for the process lifetime — a
     // long-running hub must re-render the EDITED brand, not the cached one
     const mod = (await import(`${brandPath}?v=${await brandHash(root)}`)) as { default?: Brand }
-    if (mod.default == null) return { blocked: '.shipkit/identity/brand.ts must default-export the Brand' }
-    const brand = mod.default
+    return mod.default ?? '.shipkit/identity/brand.ts must default-export the Brand'
+}
+
+/** the rendered logo of the identity set, repo relative, when it exists */
+export async function identityLogo(root: string): Promise<string | null> {
+    const web = await repoWebRoot(root)
+    const file = web === '.' ? 'logo.png' : `${web}/logo.png`
+    return existsSync(join(root, file)) ? file : null
+}
+
+export async function renderIdentityNow(root: string): Promise<IdentityRender> {
+    const brand = await loadBrand(root)
+    if (brand == null) return { blocked: 'no .shipkit/identity/brand.ts — create one exporting a Brand (name, palette, mark)' }
+    if (typeof brand === 'string') return { blocked: brand }
     let markFile: string | undefined
     if (brand.mark.backend === 'comfy') {
         // comfy marks render from the PICKED identity-logo roll — the kit

package/src/checks/SK004-gitignore-policy.check.ts

@@ -32,6 +32,10 @@ const CONTRIB = '# repo-contributed lines (repo.config.ts gitignore:)'
 
 const DRAFTS_BACK = '!.comfy-ts/drafts/'
 
+/** re-includes a private repo carries and a declared public one drops: a
+ *  draft names private loras, a plan or a board quotes the owner */
+const PRIVATE_ONLY: ReadonlySet<string> = new Set([DRAFTS_BACK, `!${LAYOUT.plans}/`])
+
 export const POLICY_LINES = [
     // everything shipkit keeps lives under .shipkit/ (core/layout.ts). Local
     // by default: the private notes, drafts, venue listings and caches, and the
@@ -45,12 +49,13 @@ export const POLICY_LINES = [
     // asks git about it: a negation below the block that exposed the keyword
     // list would otherwise pass as a venue override
     `${LAYOUT.private}/`,
-    // the scratch and the review files, spelled out for the same reason: a
-    // review narrates agent process, and a plan names what nobody published
+    // the scratch and the review files, spelled out for the same reason:
+    // nothing durable lives in the scratch, and a review narrates agent process
     `${LAYOUT.tmp}/`,
     `${LAYOUT.reviews}/`,
     // a root scratch stays out of git too: the fix pass moves it under
-    // .shipkit/, and until it runs, a plan there is still private
+    // .shipkit/, its dated plans into .shipkit/plans/, and until it runs
+    // nothing there is exposed
     `${LEGACY_TMP}/`,
     'CLAUDE.local.md',
     // atomicWrite lands every file via `.<name>.tmp-<pid>` next to its target,
@@ -74,9 +79,9 @@ export const POLICY_LINES = [
 ]
 
 /** the policy one repo carries. A declared public tree ships to strangers,
- *  so the drafts stay ignored there: a draft holds the prompts and values
- *  behind generated assets, authored state in a private repo */
-const policyLines = (config: RepoConfig): string[] => declaredPublic(config) ? POLICY_LINES.filter((l) => l !== DRAFTS_BACK) : POLICY_LINES
+ *  so its drafts and plans stay ignored there: authored state in a private
+ *  repo, private words in a public one */
+const policyLines = (config: RepoConfig): string[] => declaredPublic(config) ? POLICY_LINES.filter((l) => !PRIVATE_ONLY.has(l)) : POLICY_LINES
 
 const LEGACY = '# the old root layout, ignored until the fix pass moves it under .shipkit/'
 

package/src/checks/SK013-one-way-in-policy.check.ts

@@ -14,7 +14,7 @@
 // scaffold, so a policy written there would bind exactly one checkout.
 import { isAbsolute, join } from 'path'
 import { inferBin } from '../core/canonical-scripts.ts'
-import { denyRules, GIT_STASH_RULE, RAW_RUNNERS } from '../core/one-way-in-policy.ts'
+import { denyRules, GIT_STASH_RULES, LEGACY_STASH_RULE, RAW_RUNNERS } from '../core/one-way-in-policy.ts'
 import { rootPublishesNpm } from '../core/repo-facts.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { repoOff } from '../core/when.ts'
@@ -139,9 +139,12 @@ export const oneWayInPolicy = check({
             return
         }
         const have = new Set(s.permissions?.deny ?? [])
-        const missing = want.filter((r) => !have.has(r) && r !== GIT_STASH_RULE)
-        if (!have.has(GIT_STASH_RULE))
-            c.fail(`${SETTINGS_PATH}: no "${GIT_STASH_RULE}" deny row, so an agent can stash every other agent's uncommitted work in a shared tree`)
+        const missing = want.filter((r) => !have.has(r) && !GIT_STASH_RULES.includes(r))
+        const stashMissing = GIT_STASH_RULES.filter((r) => !have.has(r))
+        if (stashMissing.length > 0)
+            c.fail(`${SETTINGS_PATH}: ${stashMissing.length} stash deny row(s) missing (${stashMissing.slice(0, 2).join(', ')}${stashMissing.length > 2 ? ', …' : ''}), so an agent can stash every other agent's uncommitted work in a shared tree`)
+        if (have.has(LEGACY_STASH_RULE))
+            c.fail(`${SETTINGS_PATH}: the blanket "${LEGACY_STASH_RULE}" row also refuses the read only \`git stash list\` and \`git stash show\``)
         if (missing.length > 0)
             c.fail(`${SETTINGS_PATH}: ${missing.length} raw runner(s) still permitted (${missing.slice(0, 3).join(', ')}${missing.length > 3 ? ', …' : ''}) — those calls never reach shipkit, so nothing is cached and no run can be attached to`)
         const guard = guardHookCommand(s)
@@ -172,7 +175,7 @@ export const oneWayInPolicy = check({
         // replacement is named while the guard cannot run is the green that
         // measured nothing, one line under the WARN that says otherwise
         if (!c.failed)
-            c.ok(`${SETTINGS_PATH} closes ${want.length - 1}/${RAW_RUNNERS.length} raw runner(s) and refuses git stash${guardRuns ? ', with the replacement named' : ' (the guard that names the replacement is declared, not yet runnable)'}`)
+            c.ok(`${SETTINGS_PATH} closes ${want.length - GIT_STASH_RULES.length}/${RAW_RUNNERS.length} raw runner(s) and refuses git stash${guardRuns ? ', with the replacement named' : ' (the guard that names the replacement is declared, not yet runnable)'}`)
     },
     // MERGES, never rewrites: this file also carries the attribution silencer,
     // a repo's own allow list and its own hooks, and clobbering those to fix a
@@ -185,11 +188,13 @@ export const oneWayInPolicy = check({
         if (existing == null && c.exists(SETTINGS_PATH)) return { changed: false, summary: `${SETTINGS_PATH} is unparseable — repair it by hand first, a merge would destroy it` }
         const s: Settings = existing ?? {}
         const changes: string[] = []
-        const deny = s.permissions?.deny ?? []
+        const old = s.permissions?.deny ?? []
+        const deny = old.filter((r) => r !== LEGACY_STASH_RULE)
+        if (deny.length < old.length) changes.push(`the blanket ${LEGACY_STASH_RULE} row replaced by one row per stash write`)
         const added = want.filter((r) => !deny.includes(r))
-        if (added.length > 0) {
+        if (added.length > 0 || deny.length < old.length) {
             s.permissions = { ...s.permissions, deny: [...deny, ...added] }
-            changes.push(`${added.length} deny rule(s) added`)
+            if (added.length > 0) changes.push(`${added.length} deny rule(s) added`)
         }
         const wantGuard = await guardCommandFor(d)
         if (!hasGuardHook(s)) {

package/src/cli/cmd_Calls.ts

@@ -0,0 +1,53 @@
+// `<cli> calls`: the call log (cli/kit/calls.ts) read back. shipkit logs every
+// run machine wide, because one sk serves every repo; a project CLI logs under
+// its own root. One command class for both: only the log file differs.
+import { Command, Option } from 'clipanion'
+import { homedir } from 'os'
+import { callsFile, callsReport, envPrefix, renderCallsReport, sinceOf } from './kit/calls.ts'
+
+export class CallsCommand extends Command {
+    static override paths = [['calls']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'every sk run logged with its time: per command how often, how long, and the slowest runs',
+        details: 'reads ~/.shipkit/logs/sk-calls.jsonl, where every sk run writes a start line and an end line (time, cpu, memory, exit code). A run with no end line was killed or still runs. Runs another sk spawned are left out unless --nested. SK_LOG=off writes nothing; SK_AGENT names who ran it.',
+        examples: [
+            ['what agents waited on today', 'sk calls --since 1d'],
+            ['one command family', 'sk calls --cmd ci'],
+            ['only the runs started in this repo', 'sk calls --here'],
+            ['as json', 'sk calls --json'],
+        ],
+    })
+
+    since = Option.String('--since', { description: '30m, 2h, 3d or a date: only the runs that started after' })
+    cmd = Option.String('--cmd', { description: 'a command path prefix' })
+    top = Option.String('--top', '10', { description: 'how many slowest runs to list' })
+    nested = Option.Boolean('--nested', false, { description: 'keep the runs another run spawned' })
+    here = Option.Boolean('--here', false, { description: 'only the runs started inside the current folder' })
+    json = Option.Boolean('--json', false, { description: 'the report as json' })
+
+    /** the log this command reads */
+    logFile(): string {
+        return callsFile(homedir(), 'sk')
+    }
+
+    async execute(): Promise<number> {
+        const bin = this.cli.binaryName
+        const file = this.logFile()
+        const since = this.since == null ? undefined : sinceOf(this.since, Date.now())
+        if (since === null) { this.context.stderr.write(`FAIL: --since ${this.since}: 30m, 2h, 3d or a date\n`); return 2 }
+        const { existsSync, readFileSync } = await import('fs')
+        if (!existsSync(file)) { this.context.stdout.write(`no call yet: ${file}\n`); return 0 }
+        const r = callsReport(readFileSync(file, 'utf8'), {
+            since,
+            cmd: this.cmd,
+            top: Number(this.top),
+            nested: this.nested,
+            under: this.here ? process.cwd() : undefined,
+            self: process.env[`${envPrefix(bin)}_CALL`],
+        })
+        this.context.stdout.write(this.json ? `${JSON.stringify({ file, ...r })}\n` : renderCallsReport(bin, r, file))
+        return 0
+    }
+}

package/src/cli/cmd_Commands.ts

@@ -1,8 +1,11 @@
 // the binary describing itself, in markdown. a hand-copied command list
 // drifts the moment a flag changes, and then teaches commands that do not
-// exist. rendering the live registry makes the doc a build artifact.
+// exist. rendering the live registry makes the doc a build artifact. One
+// renderer for every binary: shipkit's own page and each project CLI's pages
+// (the kit in cli/kit/) come out of these functions.
 import { Command, Option } from 'clipanion'
 import { spliceMarkedBlock } from '../core/doc-block.ts'
+import { type Essential, type Film, marksOf, ROW_OF, runText } from './kit/verb.ts'
 
 export type CommandOption = { definition: string; description: string }
 export type CommandRow = {
@@ -12,6 +15,12 @@ export type CommandRow = {
     usage: string
     options: CommandOption[]
     examples: [string, string][]
+    /** a filmable command (cli/kit/verb.ts): takes --out, a clip also --seconds */
+    film?: Film
+    /** listed on the essentials page */
+    essential?: Essential
+    /** what a kit row runs */
+    runs?: string
 }
 
 export type Definition = {
@@ -30,68 +39,146 @@ export const DESCRIPTION_MAX = 100
 // clipanion renders a value placeholder as `#0`, which nobody can type
 const clean = (s: string | null | undefined): string => (s ?? '').trim().replace(/\s+/g, ' ').replace(/ #\d+\b/g, ' <value>')
 
+/** the names a binary answers to: shipkit is also `sk` */
+const namesOf = (bin: string): string[] => (bin === 'sk' || bin === 'shipkit' ? ['shipkit', 'sk'] : [bin])
+
+const stripName = (bin: string, path: string): string => {
+    for (const n of namesOf(bin)) if (path.startsWith(`${n} `)) return path.slice(n.length + 1)
+    return path
+}
+
 /** rows from the live registry, builtins dropped, sorted by category then path.
  *  clipanion splits what we need across two calls: the plain form carries the
  *  examples, the detailed form carries the flags. Merge by path, or the page
  *  ends up showing a command with no arguments, which is the state that sends
- *  an agent to `--help` before it can act. */
-export function commandRows(plain: Definition[], detailed: Definition[] = []): CommandRow[] {
+ *  an agent to `--help` before it can act. `classes` (the registered command
+ *  classes) add each command's marks: film, essential, what a row runs */
+export function commandRows(plain: Definition[], detailed: Definition[] = [], bin = 'sk', classes: readonly { paths?: string[][] }[] = []): CommandRow[] {
     const flagsByPath = new Map(detailed.map((d) => [d.path, d.options ?? []]))
+    const classByPath = new Map<string, object>()
+    for (const c of classes) for (const p of c.paths ?? []) classByPath.set(p.join(' '), c)
     return plain
-        .filter((d) => !/^(shipkit|sk) (--help|-h|--version|-v)$/.test(d.path))
-        .map((d) => ({
-            path: d.path.replace(/^(shipkit|sk) /, ''),
-            category: clean(d.category) || 'Other',
-            // verbatim from the CLI so the doc cannot say something it does not
-            description: clean(d.description),
-            usage: clean(d.usage),
-            options: (flagsByPath.get(d.path) ?? [])
-                .map((o) => ({ definition: clean(o.definition), description: clean(o.description) }))
-                .filter((o) => o.definition !== ''),
-            examples: (d.examples ?? []).map(([label, cmd]) => [clean(label), clean(cmd)] as [string, string]),
-        }))
+        .filter((d) => !/^(--help|-h|--version|-v)$/.test(stripName(bin, d.path)))
+        .map((d) => {
+            const path = stripName(bin, d.path)
+            const c = classByPath.get(path)
+            const row: CommandRow = {
+                path,
+                category: clean(d.category) || 'Other',
+                // verbatim from the CLI so the doc cannot say something it does not
+                description: clean(d.description),
+                usage: clean(d.usage),
+                options: (flagsByPath.get(d.path) ?? [])
+                    .map((o) => ({ definition: clean(o.definition), description: clean(o.description) }))
+                    .filter((o) => o.definition !== ''),
+                examples: (d.examples ?? []).map(([label, cmd]) => [clean(label), clean(cmd)] as [string, string]),
+            }
+            if (c != null) {
+                const m = marksOf(c)
+                if (m.film != null) row.film = m.film
+                if (m.essential != null) row.essential = m.essential
+                const v = ROW_OF.get(c)
+                if (v != null) row.runs = runText(v.run)
+            }
+            return row
+        })
         .sort((a, b) => a.category.localeCompare(b.category) || a.path.localeCompare(b.path))
 }
 
-/** the markdown block, loaded into every agent's context at start: per
- *  command its invocation with every flag, one line of description, then its
- *  examples. What a flag does and the long text are `sk <command> --help`. */
-export function renderMarkdown(rows: CommandRow[]): string {
+/** a command's invocation as an agent types it */
+const signature = (r: CommandRow, bin: string): string => r.usage.replace(/^\$0/, bin).trim() || `${bin} ${r.path}`
+
+/** the markdown block: per command its invocation with every flag, one line
+ *  of description, what a row runs, then its examples. What a flag does and
+ *  the long text are `<bin> <command> --help`. */
+export function renderMarkdown(rows: CommandRow[], bin = 'sk'): string {
     const out: string[] = []
     let cat = ''
     for (const r of rows) {
         if (r.category !== cat) { cat = r.category; out.push(`\n### ${cat}\n`) }
-        const sig = r.usage.replace(/^\$0/, 'sk').trim() || `sk ${r.path}`
         const flags = r.options.map((o) => `[${o.definition}]`).join(' ')
+        const sig = signature(r, bin)
         // one line per bullet: a description on its own indented line reads as
         // hard-wrapped prose to the house lint
-        out.push(`- \`${sig}${flags === '' ? '' : ` ${flags}`}\` — ${r.description}`)
+        out.push(`- \`${sig}${flags === '' ? '' : ` ${flags}`}\` — ${r.description}${r.runs != null ? ` → \`${r.runs}\`` : ''}${r.film != null ? ` (films a ${r.film})` : ''}`)
         for (const [label, cmd] of r.examples) out.push(`  - ${label}: \`${cmd}\``)
     }
     return out.join('\n').trim()
 }
 
 /** the eager form: one line per command, its positional arguments and its
- *  description. Flags and examples are `sk <command> --help`, so a page every
+ *  description. Flags and examples are `<bin> <command> --help`, so a page every
  *  session loads costs a line per command, not a screen */
-export function renderCompact(rows: CommandRow[]): string {
+export function renderCompact(rows: CommandRow[], bin = 'sk'): string {
     const out: string[] = []
     let cat = ''
     for (const r of rows) {
         if (r.category !== cat) { cat = r.category; out.push(`\n### ${cat}\n`) }
-        const sig = r.usage.replace(/^\$0/, 'sk').replace(/\s+\[(?:-|<\w+>)[^\]]*\]/g, '').trim() || `sk ${r.path}`
+        const sig = r.usage.replace(/^\$0/, bin).replace(/\s+\[(?:-|<\w+>)[^\]]*\]/g, '').trim() || `${bin} ${r.path}`
         out.push(`- \`${sig}\` — ${r.description}`)
     }
     return out.join('\n').trim()
 }
 
-export const BEGIN = '<!-- shipkit:commands -->'
-export const END = '<!-- /shipkit:commands -->'
+/** the page every session loads: per category its everyday commands, a few
+ *  examples, and how to list the rest. Generated whole */
+export function renderEssentials(rows: CommandRow[], bin: string, command: string): string {
+    const out = [`# ${bin}: the everyday commands`, '', `Generated by \`${command}\` from the commands marked \`essential\`. Every command: \`${bin}\`, \`${bin} <family>\`, \`${bin} <command> --help\`. \`${bin} <words>\` runs as \`bun run cli <words>\` from the repo root, and as \`${bin}\` anywhere once \`bun link\` ran there.`]
+    const first = (r: CommandRow): string => r.path.split(' ')[0]!
+    const quiet: string[] = []
+    for (const category of [...new Set(rows.map((r) => r.category))]) {
+        const all = rows.filter((r) => r.category === category)
+        const rest = [...new Set(all.map(first))]
+            .map((w) => [w, all.filter((r) => first(r) === w && r.essential == null).length] as const)
+            .filter(([, n]) => n > 0)
+            .map(([w, n]) => `\`${bin} ${w}${all.some((r) => r.path === w) ? ' --help' : ''}\` (${n} command${n === 1 ? '' : 's'})`)
+        const mine = all.filter((r) => r.essential != null)
+        if (mine.length === 0) { quiet.push(...rest); continue }
+        out.push('', `## ${category}${rest.length > 0 ? ` (more: ${rest.join(', ')})` : ''}`, '')
+        for (const r of mine) {
+            const e = r.essential!
+            out.push(`- \`${bin} ${r.path}${e.args != null ? ` ${e.args}` : ''}\`: ${r.description}`)
+            for (const [label, cmd] of r.examples.slice(0, e.examples ?? 0)) out.push(`  - \`${cmd}\`: ${label}`)
+        }
+    }
+    if (quiet.length > 0) out.push('', `## The other families: ${quiet.join(', ')}`)
+    return `${out.join('\n')}\n`
+}
+
+/** what a project CLI's registry must hold for its pages and its listing to
+ *  teach right: a category, a description under the cap, and an example that
+ *  starts with the command's own words. One line per breach */
+export function shapeProblems(rows: CommandRow[], bin: string): string[] {
+    const out: string[] = []
+    for (const r of rows) {
+        if (r.category === 'Other') out.push(`${bin} ${r.path}: no category`)
+        if (r.description === '') out.push(`${bin} ${r.path}: no description`)
+        else if (r.description.length > DESCRIPTION_MAX) out.push(`${bin} ${r.path}: description over ${DESCRIPTION_MAX} characters (the rest goes in details)`)
+        if (!r.examples.some(([, cmd]) => cmd === `${bin} ${r.path}` || cmd.startsWith(`${bin} ${r.path} `))) out.push(`${bin} ${r.path}: no example starting with \`${bin} ${r.path}\``)
+    }
+    return out
+}
+
+/** the markers a page carries around the generated block: shipkit keeps its
+ *  historical name, a project CLI uses its own */
+export const markersFor = (bin: string): [string, string] => {
+    const n = namesOf(bin).includes('shipkit') ? 'shipkit' : bin
+    return [`<!-- ${n}:commands -->`, `<!-- /${n}:commands -->`]
+}
+
+export const [BEGIN, END] = markersFor('sk')
 
 /** replace the marked block in a host file. Returns null when the markers are
  *  missing, so a renamed or hand-mangled host fails loud instead of silently
  *  writing nothing. */
-export const spliceBlock = (host: string, block: string): string | null => spliceMarkedBlock(host, block, BEGIN, END)
+export const spliceBlock = (host: string, block: string, bin = 'sk'): string | null => spliceMarkedBlock(host, block, ...markersFor(bin))
+
+/** the page a project CLI's `--out` creates when it is missing: a title, how
+ *  it is made, and the markers the block goes between */
+export const newCommandsPage = (bin: string, path: string): string => {
+    const [begin, end] = markersFor(bin)
+    return `# ${bin}: every command\n\nGenerated between the markers by \`${bin} commands --out ${path}\` from the registry. \`${bin}\` lists every command, \`${bin} <command> --help\` prints one.\n\n${begin}\n${end}\n`
+}
 
 export class CommandsCommand extends Command {
     static override paths = [['commands']]
@@ -109,33 +196,61 @@ export class CommandsCommand extends Command {
         ],
     })
 
-    json = Option.Boolean('--json', false, { description: 'machine-readable [{path, category, description}]' })
-    out = Option.String('--out', { description: 'host file carrying the shipkit:commands markers. The block between them is rewritten' })
-    check = Option.Boolean('--check', false, { description: 'with --out: exit 1 if the block is stale, write nothing' })
-    compact = Option.Boolean('--compact', false, { description: 'one line per command: no flags, no examples (they are `sk <command> --help`)' })
+    /** a project CLI holds its rows to shapeProblems (--out and --check fail on
+     *  a breach), and its --out creates a missing page */
+    static shapeRule = false
+
+    json = Option.Boolean('--json', false, { description: 'machine-readable rows, with film and essential where a command carries them' })
+    out = Option.String('--out', { description: 'host file carrying the <bin>:commands markers. The block between them is rewritten' })
+    check = Option.Boolean('--check', false, { description: 'with --out or --essentials: exit 1 if a page is stale, write nothing' })
+    compact = Option.Boolean('--compact', false, { description: 'one line per command: no flags, no examples (they are `<bin> <command> --help`)' })
+    essentials = Option.String('--essentials', { description: 'the everyday commands page, rewritten whole from the commands marked essential' })
 
     async execute(): Promise<number> {
+        const bin = this.cli.binaryName
+        const classes = (this.context as { classes?: { paths?: string[][] }[] }).classes ?? []
         const rows = commandRows(
             this.cli.definitions() as Definition[],
             (this.cli.definitions as (o?: { detailed?: boolean }) => Definition[])({ detailed: true }),
+            bin,
+            classes,
         )
-        if (this.out == null) {
-            this.context.stdout.write(this.json ? `${JSON.stringify(rows)}\n` : `${(this.compact ? renderCompact : renderMarkdown)(rows)}\n`)
+        const write = (s: string): void => void this.context.stdout.write(s)
+        if (this.out == null && this.essentials == null) {
+            write(this.json ? `${JSON.stringify(rows)}\n` : `${(this.compact ? renderCompact : renderMarkdown)(rows, bin)}\n`)
             return 0
         }
-        const { existsSync, readFileSync, writeFileSync } = await import('fs')
-        if (!existsSync(this.out)) { this.context.stdout.write(`FAIL: ${this.out} does not exist\n`); return 1 }
-        const host = readFileSync(this.out, 'utf8')
-        const next = spliceBlock(host, (this.compact ? renderCompact : renderMarkdown)(rows))
-        if (next == null) { this.context.stdout.write(`FAIL: ${this.out} has no ${BEGIN} / ${END} markers\n`); return 1 }
-        if (next === host) { this.context.stdout.write(`ok: ${this.out} command index current (${rows.length} commands)\n`); return 0 }
+        if ((this.constructor as typeof CommandsCommand).shapeRule) {
+            const bad = shapeProblems(rows, bin)
+            for (const b of bad) write(`FAIL: ${b}\n`)
+            if (bad.length > 0) { write('      fix: give the row a category, a short description and an example that starts with its words\n'); return 1 }
+        }
+        const { existsSync, mkdirSync, readFileSync, writeFileSync: writeRaw } = await import('fs')
+        const { dirname } = await import('path')
+        const writeFileSync = (path: string, text: string): void => { mkdirSync(dirname(path), { recursive: true }); writeRaw(path, text) }
+        let code = 0
+        if (this.essentials != null) {
+            const cmd = `${bin} commands${this.out != null ? ` --out ${this.out}` : ''} --essentials ${this.essentials}`
+            const text = renderEssentials(rows, bin, cmd)
+            if (existsSync(this.essentials) && readFileSync(this.essentials, 'utf8') === text) write(`ok: ${this.essentials} current\n`)
+            else if (this.check) { write(`FAIL: ${this.essentials} is STALE — the essential commands moved\n      fix: ${cmd}\n`); code = 1 }
+            else { writeFileSync(this.essentials, text); write(`ok: ${this.essentials} rewritten\n`) }
+        }
+        if (this.out == null) return code
+        const [begin, end] = markersFor(bin)
+        const project = (this.constructor as typeof CommandsCommand).shapeRule
+        if (!existsSync(this.out) && (!project || this.check)) { write(`FAIL: ${this.out} does not exist\n`); return 1 }
+        const host = existsSync(this.out) ? readFileSync(this.out, 'utf8') : newCommandsPage(bin, this.out)
+        const next = spliceBlock(host, (this.compact ? renderCompact : renderMarkdown)(rows, bin), bin)
+        if (next == null) { write(`FAIL: ${this.out} has no ${begin} / ${end} markers\n`); return 1 }
+        if (next === host) { write(`ok: ${this.out} command index current (${rows.length} commands)\n`); return code }
         if (this.check) {
-            this.context.stdout.write(`FAIL: ${this.out} command index is STALE — the binary registers commands the page does not list\n`)
-            this.context.stdout.write(`      fix: shipkit commands${this.compact ? ' --compact' : ''} --out ${this.out}\n`)
+            write(`FAIL: ${this.out} command index is STALE — the binary registers commands the page does not list\n`)
+            write(`      fix: ${bin === 'sk' ? 'shipkit' : bin} commands${this.compact ? ' --compact' : ''} --out ${this.out}\n`)
             return 1
         }
         writeFileSync(this.out, next)
-        this.context.stdout.write(`ok: ${this.out} command index rewritten (${rows.length} commands)\n`)
-        return 0
+        write(`ok: ${this.out} command index rewritten (${rows.length} commands)\n`)
+        return code
     }
 }

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
+        }
+    }
+}