rvlib-shipkit 1.3.0 → 1.5.0

package/src/checks/SK022-machine-runs-the-pin.check.ts

@@ -1,4 +1,4 @@
-// SK022 machine runs the pin (build/shipkit.md): on a machine with a house
+// SK022 machine runs the pin (build/shipkit/home.md): on a machine with a house
 // every shipkit runs the house copy, whatever a repo installed, so a repo's
 // rvlib-shipkit pin is a minimum. It warns when the repo asks for a version
 // newer than the one this process runs: a rule or an api that pin relies on
@@ -24,11 +24,13 @@ export const machineRunsThePin = check({
     blocking: false,
     title: 'machine runs the pin',
     description: 'the shipkit this machine runs is at least the version this repo pins',
-    owner: 'build/shipkit.md',
+    owner: 'build/shipkit/home.md',
+    runs: { onPreCommit: false, onCi: false, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
     // the pin, the install (gitignored) and the version this machine runs,
     // which is no file of the repo
-    inputs: ['package.json'],
-    cacheKey: (env) => `${LIB_VERSION}|installed=${fileStamp(join(env.root, 'node_modules', NAME, 'package.json'))}`,
+    cache: { by: 'files', inputs: ['package.json'], key: (env) => `${LIB_VERSION}|installed=${fileStamp(join(env.root, 'node_modules', NAME, 'package.json'))}` },
+    fix: 'none',
+    applies: 'always',
     run: (c) => {
         const pkg = c.json<Pkg>('package.json')
         const spec = pkg?.devDependencies?.[NAME] ?? pkg?.dependencies?.[NAME]

package/src/checks/SK024-identity-colors.check.ts

@@ -18,9 +18,11 @@ export const identityColors = check({
     title: 'identity colors',
     description: 'repo.config.ts declares identity colours: colorLight and colorDark, two hex',
     owner: 'build/shipkit/built-in-checks.md',
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: 'moved', onClock: false },
     // the config, and the installed lib that says whether it knows the key
-    inputs: [CONFIG_FILE],
-    cacheKey: (env) => `installed=${fileStamp(join(env.root, INSTALLED_CONFIG_SRC))}`,
+    cache: { by: 'files', inputs: [CONFIG_FILE], key: (env) => `installed=${fileStamp(join(env.root, INSTALLED_CONFIG_SRC))}` },
+    fix: 'manual',
+    applies: 'always',
     run: (c) => {
         const text = c.read(CONFIG_FILE)
         if (text == null) return c.note(`no ${CONFIG_FILE}`)
@@ -32,7 +34,7 @@ export const identityColors = check({
         if (why != null) return c.warn(`${CONFIG_FILE}: ${why}`, FIX)
         c.ok(`identity ${id!.colorLight} on light, ${id!.colorDark} on dark`)
     },
-    fix: async (c) => {
+    repair: async (c) => {
         const text = c.read(CONFIG_FILE)
         if (text == null) return { changed: false, summary: `no ${CONFIG_FILE}` }
         const have = identityOfText(text)

package/src/checks/SK025-release-drift.check.ts

@@ -41,11 +41,10 @@ export const releaseDrift = check({
     title: 'release drift',
     description: 'every unit this repo releases matches npm and its push remote',
     owner: 'build/shipkit/built-in-checks.md',
-    when: 'health',
-    ttl: '20h',
-    every: (last) => (last?.status === 'pass' ? ['20h', '28h'] : '4h'),
-    planOff: (env) => (releasedUnits(env.root, env.config).length === 0 ? 'this repo releases nothing' : null),
-    cacheKey: (env) => releasedUnits(env.root, env.config).map((u) => `${u.id}@${u.version}`).join(','),
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: false, onClock: { every: (last) => (last?.status === 'pass' ? ['20h', '28h'] : '4h'), inactive: 'wait' } },
+    cache: { by: 'ttl', span: '20h', key: (env) => releasedUnits(env.root, env.config).map((u) => `${u.id}@${u.version}`).join(',') },
+    fix: 'none',
+    applies: (env) => (releasedUnits(env.root, env.config).length === 0 ? 'this repo releases nothing' : null),
     run: async (c) => {
         const ids = new Set(releasedUnits(c.root, c.config).map((u) => u.id))
         if (ids.size === 0) return void c.lines.push({ kind: 'skip', text: 'this repo releases nothing: no npm root, no release config, no units' })

package/src/checks/SK026-asks-autoclose.check.ts

@@ -14,11 +14,11 @@ export const asksAutoclose = check({
     title: 'asks auto close',
     description: 'no open ask whose own probe passes stays in the queue',
     owner: 'build/shipkit/built-in-checks.md',
-    when: 'health',
-    never: "runs each open ask's own probe, a shell command that reads the world",
-    every: ['20h', '28h'],
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: false, onClock: { every: ['20h', '28h'], inactive: 'wait' } },
+    cache: { by: 'never', why: "runs each open ask's own probe, a shell command that reads the world" },
+    fix: 'none',
     // it only probes an ask that carries one, and archives one marked done
-    planOff: (env) => {
+    applies: (env) => {
         const dir = join(env.root, env.config.asks?.dir ?? LAYOUT.asks)
         if (!existsSync(dir)) return 'no asks queue'
         return listAsks(dir).some((a) => a.check != null || a.status === 'done') ? null : 'no open ask carries a probe'

package/src/checks/SK027-agent-wiki-links.check.ts

@@ -1,10 +1,10 @@
 // SK027 agent wiki links (build/shipkit/built-in-checks.md): a repo's agent/
 // IS an md wiki (entry index.md, the CLAUDE.md include), so an orphan page or
-// a dangling ref there fails. A cross wiki pointer (into a house wiki) is
-// backticked, never a bare → or @, which reads as an agent local link and
-// dangles. A repo without agent/index.md skips.
-import { existsSync } from 'fs'
-import { join } from 'path'
+// a dangling ref there fails. A link that leaves agent/ but stays in the repo
+// is checked on disk; a pointer out of the repo (a house wiki) is backticked,
+// never a bare → or @. A repo without agent/index.md skips.
+import { existsSync, readFileSync } from 'fs'
+import { basename, join } from 'path'
 import { check } from '../check.ts'
 import { lintMd } from '../wiki/lint-md.ts'
 
@@ -14,15 +14,40 @@ export const agentWikiLinks = check({
     title: 'agent wiki links',
     description: 'every agent/ page is linked from somewhere, and every agent/ link resolves',
     owner: 'meta/agent-folder.md',
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
     // the md lint walks agent/ on disk rather than through `c`: agent/ is all it reads
-    inputs: ['agent'],
+    cache: { by: 'files', inputs: ['agent'], key: null },
+    fix: 'none',
+    applies: 'always',
     run: (c) => {
         if (!existsSync(join(c.root, 'agent/index.md'))) return void c.lines.push({ kind: 'skip', text: 'no agent/ wiki in this repo' })
-        const lint = lintMd({ root: join(c.root, 'agent'), index: 'index.md' })
-        for (const f of lint.orphans) c.fail(`agent/${f}: orphan, unreachable from agent/index.md: link it from a page or delete it`)
-        for (const d of lint.dangling) c.fail(`agent/${d.from}: dangling ref → ${d.token}, target not found (backtick a cross wiki ref; fix or delete the pointer)`)
+        const lint = lintMd({ root: join(c.root, 'agent'), index: 'index.md', boundary: c.root })
+        const linked = lint.pages.filter((p) => !lint.orphans.includes(p))
+        for (const f of lint.orphans) {
+            const by = namingPage(c.root, f, linked)
+            const where = by != null ? `${by}, which already names it (turn that mention into the link)` : 'agent/index.md or the page of its topic'
+            c.fail(`agent/${f}: orphan, unreachable from agent/index.md: add a markdown link to it from ${where}; delete it only if the page is dead`)
+        }
+        for (const d of lint.dangling) c.fail(`agent/${d.from}: dangling ref → ${d.token}, target not found on disk: fix the path or delete the pointer (a pointer out of this repo, into a house wiki or another repo, goes in backticks)`)
         if (!c.failed) c.ok('agent/ has no orphans and no dangling refs')
     },
 })
 
+/** the linked page whose text already names an orphan (its path, its file
+ *  name, or a glob its file name matches), the one to turn into a link */
+function namingPage(root: string, orphan: string, pages: string[]): string | null {
+    const name = basename(orphan)
+    const stem = name.replace(/\.md$/, '')
+    for (const p of pages) {
+        const text = readFileSync(join(root, 'agent', p), 'utf8')
+        if (text.includes(orphan) || text.includes(name) || text.includes(`${stem}.`) || text.includes(`${stem} `)) return `agent/${p}`
+        for (const m of text.matchAll(/[\w.-]*\*[\w.*-]*/g)) {
+            const g = m[0]
+            if (g.replace(/[*.]/g, '').length < 3) continue
+            if (new Bun.Glob(g).match(name) || new Bun.Glob(`${g}.md`).match(name)) return `agent/${p}`
+        }
+    }
+    return null
+}
+
 export default agentWikiLinks

package/src/checks/SK028-readme.check.ts

@@ -52,21 +52,29 @@ const REQUIREMENTS: Requirement[] = [
             const why = found.map((f) => (f as { bad: string }).bad)
             return {
                 warn: `${README}: screenshot: ${why.length === 0 ? 'no image at all' : `no image resolves (${why.join(', ')})`}`,
-                fix: 'add a screenshot to README.md: ![what it looks like](docs/screenshot.png), a file in the repo, or an https url',
+                fix: `add a screenshot to README.md: ![what it looks like](docs/screenshot.png), a file in the repo, or an https url; ${OFF}`,
             }
         },
     },
 ]
 
+/** the other way out, for a repo that cannot show one: the rule off, with the
+ *  reason `defineRepo` requires (core/when.ts) */
+const OFF = `or, when this repo cannot show one, turn the rule off with the reason: off: { SK028: '<why this repo shows no screenshot>' } in repo.config.ts, inside its shipkit gate block`
+
 export const readme = check({
     id: 'SK028',
     blocking: false,
     title: 'readme',
     description: 'README.md exists and shows at least one screenshot',
     owner: 'build/shipkit/built-in-checks.md',
+    runs: { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'reads' },
+    fix: 'none',
+    applies: 'always',
     run: (c) => {
         const md = c.read(README)
-        if (md == null) return c.warn(`${README}: exists: no ${README} at the repo root`, 'write README.md: what the repo is, and a screenshot of it')
+        if (md == null) return c.warn(`${README}: exists: no ${README} at the repo root`, `write README.md: what the repo is, and a screenshot of it; ${OFF}`)
         c.ok(`${README} exists`)
         for (const r of REQUIREMENTS) {
             const f = r.test(c, md)

package/src/checks/SK029-explicit-check-files.check.ts

@@ -0,0 +1,95 @@
+// SK029 explicit check files (build/shipkit/runs.md owns the declaration):
+// every check file of the repo declares runs, cache, fix and applies, with
+// no retired key. A file that does not does not load, and discovery shows
+// it as one failing row. The repair ports it with the values the retired
+// keys resolved to (core/port-check-file.ts), so the check keeps running
+// where it ran, and the ci fix pass applies it before the gate reads the
+// files: a repo carried across by its first `shipkit ci`. The same holds for
+// the config: a retired `when` (only its `off:<why>` entries still load) and
+// `ruleExempt` become `off` entries in the managed block.
+import { join } from 'path'
+import { check, type FixResult } from '../check.ts'
+import { unportedCheckFiles } from '../core/port-check-files.ts'
+import type { PortRun } from '../core/port-check-cli.ts'
+import type { ConfigPlan, ConfigRewrite } from '../core/config-rewrite.ts'
+import type { RepoConfig } from '../repo-config.ts'
+
+/** the write half, run as its own process: it walks import closures on disk */
+const PORT_CLI = join(import.meta.dir, '../core/port-check-cli.ts')
+/** the config half, run as its own process: it loads repo.config.ts */
+const CONFIG_REWRITE = join(import.meta.dir, '../core/config-rewrite.ts')
+
+/** the retired config keys this repo still carries, and the `off` entries
+ *  they become. defineRepo already refused every `when` word but `off:<why>` */
+export function retiredOff(c: RepoConfig): { keys: string[]; off: Record<string, string> } {
+    const off: Record<string, string> = {}
+    for (const [id, raw] of Object.entries(c.when ?? {})) off[id] = raw.trim().replace(/^off:?/, '').trim()
+    for (const [id, why] of Object.entries(c.ruleExempt ?? {})) off[id] ??= why
+    const keys = [...(c.when != null ? ['when'] : []), ...(c.ruleExempt != null ? ['ruleExempt'] : [])]
+    return { keys, off }
+}
+
+export const explicitCheckFiles = check({
+    id: 'SK029',
+    title: 'explicit check files',
+    description: 'every check file declares runs, cache, fix and applies, and the config says only off',
+    owner: 'build/shipkit/runs.md',
+    blocking: true,
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    // the listing of check files and their sources, read through `c`
+    cache: { by: 'reads' },
+    // the port is mechanical: every value it writes is what the retired keys
+    // resolved to, so the fix pass applies it without asking
+    fix: 'ci',
+    applies: 'always',
+    run: (c) => {
+        const files = unportedCheckFiles(c)
+        const cfg = retiredOff(c.config)
+        if (files.length === 0 && cfg.keys.length === 0) return c.ok('every check file declares runs, cache, fix and applies, and the config says only off')
+        for (const f of files) c.fail(`${f.rel} still declares the retired shape (${f.keys.join(', ')}), so it does not load`)
+        if (cfg.keys.length > 0) c.fail(`repo.config.ts still carries ${cfg.keys.join(' and ')}: a repo only turns a check off, as off: { <id>: '<why>' }`)
+        c.fail(`${files.length + (cfg.keys.length > 0 ? 1 : 0)} file(s) to port`, 'shipkit check --fix SK029 ports each one with the values it ran on, and `shipkit ci` does it in its fix pass')
+    },
+    repair: async (c): Promise<FixResult> => {
+        const files = unportedCheckFiles(c)
+        const cfg = retiredOff(c.config)
+        if (files.length === 0 && cfg.keys.length === 0) return { changed: false, summary: 'every check file is explicit already, and the config says only off' }
+        const did: string[] = []
+        const hand: string[] = []
+        if (files.length > 0) {
+            const r = await c.exec([process.execPath, PORT_CLI, c.root, ...files.map((f) => f.rel)], { cwd: c.root, timeoutMs: 60_000 })
+            try {
+                const run = JSON.parse(r.out.trim().split('\n').at(-1) ?? '') as PortRun
+                if (run.did.length > 0) did.push(`ported ${run.did.join('; ')}`)
+                hand.push(...run.hand)
+            } catch {
+                hand.push(`the port did not answer (exit ${r.code}: ${r.out.trim().slice(0, 160)}): port ${files.map((f) => f.rel).join(', ')} by hand (build/shipkit/runs.md)`)
+            }
+        }
+        if (cfg.keys.length > 0) {
+            // `when` sits inside the managed block, so it goes first and the
+            // block describes the config again before the entries land
+            const plan: ConfigPlan = {
+                off: cfg.off,
+                drop: [
+                    ...(c.config.when != null ? [{ key: 'when', why: 'its off entries are `off` now', phase: 'first' as const }] : []),
+                    ...(c.config.ruleExempt != null ? [{ key: 'ruleExempt', why: 'its exemptions are `off` now', phase: 'afterOff' as const }] : []),
+                ],
+                name: c.config.name,
+            }
+            const r = await c.exec([process.execPath, CONFIG_REWRITE, c.root, JSON.stringify(plan)], { cwd: c.root, timeoutMs: 60_000 })
+            try {
+                const out = JSON.parse(r.out.trim().split('\n').at(-1) ?? '') as ConfigRewrite
+                did.push(...out.did)
+                hand.push(...out.hand)
+                if (out.restored != null) hand.push(`repo.config.ts was left as it was: ${out.restored}`)
+            } catch {
+                hand.push(`the repo.config.ts rewrite did not answer (exit ${r.code}): write off: ${JSON.stringify(cfg.off)} by hand and drop ${cfg.keys.join(', ')}`)
+            }
+        }
+        const summary = [did.length > 0 ? did.join('; ') : 'nothing ported', ...(hand.length > 0 ? [`${hand.length} by hand: ${hand.join(' | ')}`] : [])].join('. ')
+        return { changed: did.length > 0, summary }
+    },
+})
+
+export default explicitCheckFiles

package/src/cli/cmd_Asks.ts

@@ -15,7 +15,7 @@ export class AsksCommand extends Command {
     static override usage = Command.Usage({
         category: 'Asks',
         description: 'list open asks — the per-repo human action queue',
-        examples: [['list open asks', 'shipkit asks']],
+        examples: [['list open asks', 'sk asks']],
     })
 
     async execute(): Promise<number> {
@@ -37,7 +37,7 @@ export class AsksCheckCommand extends Command {
     static override usage = Command.Usage({
         category: 'Asks',
         description: 'probe every open ask and archive the ones whose check now passes',
-        examples: [['probe + auto-close', 'shipkit asks check']],
+        examples: [['probe + auto-close', 'sk asks check']],
     })
 
     async execute(): Promise<number> {
@@ -59,9 +59,9 @@ export class AskNewCommand extends Command {
         category: 'Asks',
         description: 'create a new ask file in the queue',
         examples: [
-            ['minimal', 'shipkit ask "rotate the API token"'],
-            ['with a reason', 'shipkit ask "buy the domain" --why "landing page is blocked on it"'],
-            ['with metadata', 'shipkit ask "buy the domain" --kind action --blocks deploy --check "dig +short example.com"'],
+            ['minimal', 'sk ask "rotate the API token"'],
+            ['with a reason', 'sk ask "buy the domain" --why "landing page is blocked on it"'],
+            ['with metadata', 'sk ask "buy the domain" --kind action --blocks deploy --check "dig +short example.com"'],
         ],
     })
 

package/src/cli/cmd_Assets.ts

@@ -19,8 +19,8 @@ export class AssetsFillCommand extends Command {
         category: 'Assets',
         description: 'top rolls up to N per asset (canvas or comfy), sparsest-first',
         examples: [
-            ['every asset up to 8 rolls', 'shipkit assets fill 8'],
-            ['only two categories', 'shipkit assets fill 8 icons sprites'],
+            ['every asset up to 8 rolls', 'sk assets fill 8'],
+            ['only two categories', 'sk assets fill 8 icons sprites'],
         ],
     })
 
@@ -43,7 +43,7 @@ export class AssetsAddCommand extends Command {
     static override usage = Command.Usage({
         category: 'Assets',
         description: 'N more rolls per asset (canvas or comfy), regardless of what it has',
-        examples: [['3 fresh rolls everywhere', 'shipkit assets add 3']],
+        examples: [['3 fresh rolls everywhere', 'sk assets add 3']],
     })
 
     n = Option.String({ required: true })
@@ -66,8 +66,8 @@ export class AssetsGenCommand extends Command {
         category: 'Assets',
         description: 'one-shot rolls for a single asset (canvas or comfy)',
         examples: [
-            ['one roll', 'shipkit assets gen hero'],
-            ['five rolls', 'shipkit assets gen hero --n 5'],
+            ['one roll', 'sk assets gen hero'],
+            ['five rolls', 'sk assets gen hero --n 5'],
         ],
     })
 
@@ -86,7 +86,7 @@ export class AssetsIdentityCommand extends Command {
     static override usage = Command.Usage({
         category: 'Assets',
         description: 'render favicon/logo/OG from .shipkit/identity/brand.ts into public/',
-        examples: [['regenerate the identity outputs', 'shipkit assets identity']],
+        examples: [['regenerate the identity outputs', 'sk assets identity']],
     })
 
     async execute(): Promise<number> {
@@ -100,7 +100,7 @@ export class AssetsCheckCommand extends Command {
     static override usage = Command.Usage({
         category: 'Assets',
         description: 'kit loads, kinds valid, cflow workflows load, drafts present, identity outputs present',
-        examples: [['health-check the asset pipeline', 'shipkit assets check']],
+        examples: [['health-check the asset pipeline', 'sk assets check']],
     })
 
     async execute(): Promise<number> {

package/src/cli/cmd_Bump.ts

@@ -9,18 +9,19 @@ export class BumpCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'ship a version in one word: bumps a unit (default the repo root), run from a feature branch it merges into the release branch first, then promotes the CHANGELOG Unreleased section, bumps package.json, runs the gate and every prepublish script, commits, tags, pushes, and cuts the release. Any failure before the version commit rolls the merge back and returns you to your branch.',
+        description: 'ship a version: merge, changelog, bump, gate, tag, push, release',
+        details: 'ship a version in one word: bumps a unit (default the repo root), run from a feature branch it merges into the release branch first, then promotes the CHANGELOG Unreleased section, bumps package.json, runs the gate and every prepublish script, commits, tags, pushes, and cuts the release. Any failure before the version commit rolls the merge back and returns you to your branch.',
         examples: [
-            ['a bugfix release of the repo itself', 'shipkit bump patch'],
-            ['a feature release', 'shipkit bump minor'],
-            ['a breaking release', 'shipkit bump major'],
-            ['one sub-unit (ids: shipkit releases)', 'shipkit bump minor rvlib-shipkit'],
-            ['a whole mixed batch in ONE gate, each unit at the kind its heading declares', 'shipkit bump --all'],
-            ['every unit carrying Unreleased notes, all at the same kind', 'shipkit bump patch --all'],
-            ['one unit, kind from its own heading', 'shipkit bump rvlib-shipkit'],
-            ['rehearse the whole thing', 'shipkit bump minor --dry-run'],
-            ['bump and commit, release later', 'shipkit bump patch --no-release'],
-            ['from a feature branch, refuse rather than merge', 'shipkit bump patch --no-merge'],
+            ['a bugfix release of the repo itself', 'sk bump patch'],
+            ['a feature release', 'sk bump minor'],
+            ['a breaking release', 'sk bump major'],
+            ['one sub-unit (ids: shipkit releases)', 'sk bump minor rvlib-shipkit'],
+            ['a whole mixed batch in ONE gate, each unit at the kind its heading declares', 'sk bump --all'],
+            ['every unit carrying Unreleased notes, all at the same kind', 'sk bump patch --all'],
+            ['one unit, kind from its own heading', 'sk bump rvlib-shipkit'],
+            ['rehearse the whole thing', 'sk bump minor --dry-run'],
+            ['bump and commit, release later', 'sk bump patch --no-release'],
+            ['from a feature branch, refuse rather than merge', 'sk bump patch --no-merge'],
         ],
     })
 

package/src/cli/cmd_Check.ts

@@ -14,14 +14,15 @@ export class CheckCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'every check except the build steps. `shipkit ci` runs these too and is what you normally want. --fix applies check autofixes',
+        description: 'every check except the build steps: the slower health surface',
+        details: 'every check except the build steps. `shipkit ci` runs these too and is what you normally want. --fix applies check autofixes',
         examples: [
-            ['run (cached where valid)', 'shipkit check'],
-            ['bust every cache layer', 'shipkit check --fresh'],
-            ['apply every rule autofix, re-lint', 'shipkit check --fix'],
-            ['fix one rule', 'shipkit check --fix SK004'],
-            ['report-only: self-maintaining rules never write', 'shipkit check --frozen'],
-            ['machine-readable', 'shipkit check --json'],
+            ['run (cached where valid)', 'sk check'],
+            ['bust every cache layer', 'sk check --fresh'],
+            ['apply every rule autofix, re-lint', 'sk check --fix'],
+            ['fix one rule', 'sk check --fix SK004'],
+            ['report-only: self-maintaining rules never write', 'sk check --frozen'],
+            ['machine-readable', 'sk check --json'],
         ],
     })
 

package/src/cli/cmd_Checks.ts

@@ -21,13 +21,14 @@ export class ChecksCommand extends Command {
     // widened so the hidden alias below can drop it: no usage, no help entry
     static override usage: Usage | undefined = Command.Usage({
         category: 'Health',
-        description: 'every gate check on one table: where it comes from, whether it blocks or only warns, whether the gate runs it or only `shipkit check`, and how it caches. Reports, never gates',
+        description: 'every gate check on one table: source, blocking or warning, cache',
+        details: 'every gate check on one table: where it comes from, whether it blocks or only warns, whether the gate runs it or only `shipkit check`, and how it caches. Reports, never gates',
         examples: [
-            ['the whole inventory', 'shipkit checks'],
-            ['the big markdown table, written to a file', 'shipkit checks --out STATUS.full.md'],
-            ['only the ones the gate never runs', 'shipkit checks --proactive'],
-            ['everything that repairs itself, with its owner', 'shipkit checks --fixable'],
-            ['machine-readable', 'shipkit checks --json'],
+            ['the whole inventory', 'sk checks'],
+            ['the big markdown table, written to a file', 'sk checks --out STATUS.full.md'],
+            ['only the ones the gate never runs', 'sk checks --proactive'],
+            ['everything that repairs itself, with its owner', 'sk checks --fixable'],
+            ['machine-readable', 'sk checks --json'],
         ],
     })
 

package/src/cli/cmd_Ci.ts

@@ -13,18 +13,19 @@ export class CiCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'THE command. Repairs what a machine can (formatter, imports, repo shape), then runs every check the gate asks for, through one DAG. A check that declares blocking:false warns instead of failing. Run this instead of anything else.',
+        description: 'THE gate: repairs what a machine can, then runs every check. Run this, not the parts',
+        details: 'THE command. Repairs what a machine can (formatter, imports, repo shape), then runs every check the gate asks for, through one DAG. A check that declares blocking:false warns instead of failing. Run this instead of anything else.',
         examples: [
-            ['full gate, mechanical fixes applied', 'shipkit ci'],
-            ['gate without the repair pass (checks can still write)', 'shipkit ci --no-fix'],
-            ['leave repo config files alone', 'shipkit ci --no-fix-rules'],
-            ['stop at the first failure', 'shipkit ci --bail'],
-            ['one check + its dep closure', 'shipkit ci --only typecheck'],
-            ['every check declaring one group', 'shipkit ci --only wiki'],
-            ['run everything, take nothing from the cache', 'shipkit ci --fresh'],
-            ['include an opt in check', 'shipkit ci --with up:itch'],
-            ['in the background, read it back with shipkit status', 'shipkit ci --detach'],
-            ['every line, the ones nobody acts on included', 'shipkit ci --verbose'],
+            ['full gate, mechanical fixes applied', 'sk ci'],
+            ['gate without the repair pass (checks can still write)', 'sk ci --no-fix'],
+            ['leave repo config files alone', 'sk ci --no-fix-rules'],
+            ['stop at the first failure', 'sk ci --bail'],
+            ['one check + its dep closure', 'sk ci --only typecheck'],
+            ['every check declaring one group', 'sk ci --only wiki'],
+            ['run everything, take nothing from the cache', 'sk ci --fresh'],
+            ['include an opt in check', 'sk ci --with up:itch'],
+            ['in the background, read it back with shipkit status', 'sk ci --detach'],
+            ['every line, the ones nobody acts on included', 'sk ci --verbose'],
         ],
     })
 

package/src/cli/cmd_Commands.ts

@@ -23,6 +23,10 @@ export type Definition = {
     options?: { definition?: string; description?: string | null }[] | null
 }
 
+/** the longest description the index shows: one short line. The rest goes in
+ *  the command's `details`, which --help prints */
+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>')
 
@@ -34,9 +38,9 @@ const clean = (s: string | null | undefined): string => (s ?? '').trim().replace
 export function commandRows(plain: Definition[], detailed: Definition[] = []): CommandRow[] {
     const flagsByPath = new Map(detailed.map((d) => [d.path, d.options ?? []]))
     return plain
-        .filter((d) => !/^shipkit (--help|-h|--version|-v)$/.test(d.path))
+        .filter((d) => !/^(shipkit|sk) (--help|-h|--version|-v)$/.test(d.path))
         .map((d) => ({
-            path: d.path.replace(/^shipkit /, ''),
+            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),
@@ -49,21 +53,19 @@ export function commandRows(plain: Definition[], detailed: Definition[] = []): C
         .sort((a, b) => a.category.localeCompare(b.category) || a.path.localeCompare(b.path))
 }
 
-/** the markdown block: per command, the real invocation with its arguments and
- *  flags, then a worked example. A name and a sentence are not enough to act
- *  on: an agent that cannot see the arguments either guesses them or runs
- *  `--help` first, and both are the waste this page exists to remove. */
+/** 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 {
     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/, 'shipkit').trim() || `shipkit ${r.path}`
+        const sig = r.usage.replace(/^\$0/, 'sk').trim() || `sk ${r.path}`
         const flags = r.options.map((o) => `[${o.definition}]`).join(' ')
         // 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}`)
-        for (const o of r.options) if (o.description !== '') out.push(`  - \`${o.definition}\` ${o.description}`)
         for (const [label, cmd] of r.examples) out.push(`  - ${label}: \`${cmd}\``)
     }
     return out.join('\n').trim()
@@ -82,12 +84,13 @@ export class CommandsCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'every command this binary registers, as markdown or json — the source a docs page is generated FROM, never hand-copied',
+        description: 'every command this binary registers, as markdown or json',
+        details: 'every command this binary registers, as markdown or json — the source a docs page is generated FROM, never hand-copied',
         examples: [
-            ['markdown index', 'shipkit commands'],
-            ['machine-readable', 'shipkit commands --json'],
-            ['write into a docs page between the markers', 'shipkit commands --out wiki/build/shipkit-cli.md'],
-            ['fail if that page is stale (lint mode)', 'shipkit commands --out wiki/build/shipkit-cli.md --check'],
+            ['markdown index', 'sk commands'],
+            ['machine-readable', 'sk commands --json'],
+            ['write into a docs page between the markers', 'sk commands --out wiki/build/shipkit-cli.md'],
+            ['fail if that page is stale (lint mode)', 'sk commands --out wiki/build/shipkit-cli.md --check'],
         ],
     })
 

package/src/cli/cmd_ConfigKeys.ts

@@ -19,13 +19,14 @@ export class ConfigKeysCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'every repo.config.ts key and every check field with its doc, read from the types — the source a config reference page is generated FROM',
+        description: 'every repo.config.ts key and check field with its doc, from the types',
+        details: 'every repo.config.ts key and every check field with its doc, read from the types — the source a config reference page is generated FROM',
         examples: [
-            ['markdown reference', 'shipkit config-keys'],
-            ['machine-readable', 'shipkit config-keys --json'],
-            ['write into a docs page between the markers', 'shipkit config-keys --out wiki/build/shipkit/config-keys.md'],
-            ['fail if that page is stale (lint mode)', 'shipkit config-keys --out wiki/build/shipkit/config-keys.md --check'],
-            ['name the keys carrying no doc comment', 'shipkit config-keys --undocumented'],
+            ['markdown reference', 'sk config-keys'],
+            ['machine-readable', 'sk config-keys --json'],
+            ['write into a docs page between the markers', 'sk config-keys --out wiki/build/shipkit/config-keys.md'],
+            ['fail if that page is stale (lint mode)', 'sk config-keys --out wiki/build/shipkit/config-keys.md --check'],
+            ['name the keys carrying no doc comment', 'sk config-keys --undocumented'],
         ],
     })
 

package/src/cli/cmd_Contracts.ts

@@ -10,9 +10,9 @@ export class ContractsCommand extends Command {
         category: 'Gate',
         description: 'release-contract fulfillness, fast and filesystem-only — deploy checks dep on it',
         examples: [
-            ['all applicable contracts', 'shipkit contracts'],
-            ['one venue', 'shipkit contracts --venue itch'],
-            ['machine-readable', 'shipkit contracts --json'],
+            ['all applicable contracts', 'sk contracts'],
+            ['one venue', 'sk contracts --venue itch'],
+            ['machine-readable', 'sk contracts --json'],
         ],
     })
 

package/src/cli/cmd_CrossRepoActivity.ts

@@ -60,7 +60,10 @@ export function renderActivity(a: ActivityAnswer, cap: number): string[] {
     for (const r of [...busy, ...quiet]) {
         const branch = r.branch ?? (r.detached == null ? '' : `detached ${r.detached}`)
         out.push(`${r.name}  ${dot(r)}  ${branch}  (${upstreamWords(r)})`)
-        if (r.status != null && r.status.reds.length > 0) out.push(`    failing: ${r.status.reds.map((id) => (r.status!.since[id] == null ? id : `${id} (${ageShort(r.status!.since[id]!, a.now)})`)).join(', ')}`)
+        for (const c of r.failing ?? []) {
+            out.push(`    ${c.status === 'fail' ? '✗' : '!'} ${c.id}${c.at == null ? '' : ` (${ageShort(c.at, a.now)})`}`)
+            for (const l of c.lines) out.push(`        ${l}`)
+        }
         if (r.error != null) out.push(`    git failed: ${r.error}`)
         const dirt = r.error == null ? dirtWords(r) : ''
         if (dirt !== '') {
@@ -82,12 +85,13 @@ export class CrossRepoActivityCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Home',
-        description: 'the activity page in the console: every house repo (archived ones left out), its checks, branch, upstream, uncommitted work and commits in a window. The same computation the page reads, local git only, no daemon needed',
+        description: 'the activity page as text: every house repo, its git state and recent commits',
+        details: 'the activity page in the console: every house repo (archived ones left out), its checks, branch, upstream, uncommitted work and commits in a window. The same computation the page reads, local git only, no daemon needed',
         examples: [
-            ['the last 30 minutes, 3 commits per repo, as the page opens', 'shipkit cross-repo-activity'],
-            ['the same, by the page name', 'shipkit activity'],
-            ['the last 3 hours, up to 10 commits per repo', 'shipkit cross-repo-activity --max-age 3h --max-commit 10'],
-            ['the route\'s exact payload', 'shipkit cross-repo-activity --max-age 30m --json'],
+            ['the last 30 minutes, 3 commits per repo, as the page opens', 'sk cross-repo-activity'],
+            ['the same, by the page name', 'sk activity'],
+            ['the last 3 hours, up to 10 commits per repo', 'sk cross-repo-activity --max-age 3h --max-commit 10'],
+            ['the route\'s exact payload', 'sk cross-repo-activity --max-age 30m --json'],
         ],
     })