rvlib-shipkit 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -15,8 +15,17 @@
 - **`sk time` shows turn count, what makes agents slow when no command is.** Every call costs a model turn before it. The summary gives, for the main sessions and for the sub-agents, the model time before each call, the share of single read calls and the share sent in parallel. The sub-agent lines lead with a verdict (turn count or command speed, with a fix line when reads pile up one per turn), then their work split (model, tools, their own waits), run length p50 and p90, and calls per run. The `turns` view lists the runs that worked longest with their turns, read and parallel shares and model per turn, then the read shapes by the model time of the turns that issued them. A read is Read, Grep, Glob, or a Bash command of a read shape whose every part reads (a redirect to a file, `sed -i`, `find -delete` or `-exec`, `tee`, or a second command that writes or runs makes it not one), judged when a call is indexed and again when the rules change (`src/agent-time/turns.ts`). A call is parallel when it starts while the previous call still runs, within 2 s of its start. The model stretch before a call comes from the same sweep that cuts the wall. pkm-multi, every recorded session: sub-agents worked 905.4h, model 67%, 7.7 s of model before each of 283,821 calls, 51% single reads, 2.3% in parallel.
 - **A message relayed into a sub-agent ends its park.** The harness writes "The coordinator sent a message while you were working" (or the user, or another session) into a sub-agent as an `isMeta` user entry with no peer origin, which the transcript reader dropped, so a sub-agent that handed back and sat for hours until someone wrote to it counted those hours as model: 352h of pkm-multi's sub-agent time. It is now a `message` event that counts as a prompt (idle past 30 minutes). The index version moves to 6, so every file is read again once.
 
-## Unreleased (patch)
-
+## 2.4.0
+
+- **The wiki preview opens on the index, beside the graph on the left, right or bottom.** A switch of three icons in the preview's head places it, kept per browser; buttons open the page in VS Code and copy its path. Refs read by kind: on demand (`→`, a link, a path in a code span, written `→ path` whichever the page used) in orange, loaded with the page (`@`) in blue and bold. A page that names `agent/spec.md` opens the agent/ graph's `spec.md`.
+- **The wikis page searches and previews.** A search bar over the graph finds every page by title and full text (`/graph/<id>/search`), a dropdown the arrows walk; enter, or a click on a ball, opens the page in a resizable panel on the right (`/graph/<id>/page`), whose refs open their page and focus its ball. The graph follows the hub's theme. `serve.wikiGraph.dir` names the folder a custom wiki's node ids are relative to (default the repo root).
+- **A choice card.** `sk review add --choice --view "voice A" a.flac --note "low" --view "voice B" b.flac`: every view is an option he scores (1 to 5 stars) and picks one of. His pick is an approval carrying `pick`; `inbox` and `watch` print `picked [voice B]` and each score. An approval with reactions or a pick is no longer counted as a plain one by `inbox`.
+- **Options as thin rows.** A choice, and any card of two clips or sounds or more, shows its views one below the other: ▶, the label, a strip that scrubs it, the time, then stars and « pick » (a choice) or OK, fix, no (a group), ✎ a word, ⤢ the full view. Keys 1 to 9 play a row, ⇧1 to ⇧5 score it, P picks it. « rows | full » switches back to every view stacked.
+- **One clip or sound plays at a time on the whole page.** Any audio or video that starts pauses the one playing (the review page, the trailer page, the atelier's rolls). A card's first clip loops alone; the others wait on their first frame.
+- **The card's header reads.** The title, then one line: the list's own pill, the lane, when it was sent or answered, the commit, an id to copy. No subject row, no id row, no banner. `top` is one column from the top: the header and the verdicts, the views, then the answer. A link to a card on a phone opens the card.
+- **An svg mark is a repo's icon.** `.shipkit/identity/icon.svg` comes right after `icon.png` for the project list's icon and for the app icon, which draws it on the identity plate like a png.
+- **The hub's pages read from the left.** Every page card of a repo (admin, checks, tests, plan, git, when, processes, status, readme) and a review card's pictures start at the left of their pane instead of floating centred; a guard keeps it.
+- **The rail draws bigger icons: each repo's app icon.** The sizes are 24, 32 and 40px (S, M, L) with 6px a side, the rail 36, 44 or 52px; the ask badge sits on the icon's top right corner. Folded, a row wears the repo's app icon, its mark on the identity plate the admin page previews, cropped to the plate (`appIcon` on `/api/projects.json`, `appIconPngs(…, 'plate')`, drawn once per mark and colours); a repo with no png mark keeps its plain icon. A repo closed in VS Code dims its name, never its icon.
 - **The rail's icons come in three sizes.** Folded, the list's foot shows an S, M or L button: 18, 24 or 32px icons, the rail 44, 50 or 58px wide to fit, kept per browser (`hub:rail-icon`). M is the default.
 - **The project list folds to an icon rail.** ⌘B, the fold button at the list's foot, or a drag of its separator below the list's min folds it to 44px of icons: the names, the ⌘ hints and the step hint hide, a badge rides its icon's corner, the hover card still names the row. A drag out or ⌘B again unfolds it to its kept width; the fold is kept per browser (`hub:list-rail`). The dock moves to ⌘⇧B.
 - **⌘; opens the insights**, its filter focused, so a package name is one key and a word away.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "2.3.0",
+    "version": "2.4.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",

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

@@ -16,6 +16,7 @@ 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'
+import type { TrailerSoundInput } from '../../trailer/sound/brand.ts'
 
 export type Brand = {
     name: string
@@ -31,8 +32,10 @@ export type Brand = {
      *  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
+     *  each value left out is derived from the palette (trailer/look.ts);
+     *  its sound section (`comfy`, `elevenKey`, `voice`, `voices`) makes the
+     *  voice, sfx and music lines (trailer/sound/brand.ts) */
+    trailer?: TrailerLookInput & TrailerSoundInput
 }
 
 export const FAVICON_SIZE = 512

package/src/cli/cmd_Commands.ts

@@ -20,6 +20,8 @@ export type CommandRow = {
     /** a filmable command's take version and length (build/trailer.md, Film lines) */
     version?: number | string
     length?: 'own'
+    words?: Record<string, unknown>
+    stamp?: string[]
     /** listed on the essentials page */
     essential?: Essential
     /** what a kit row runs */
@@ -81,6 +83,8 @@ export function commandRows(plain: Definition[], detailed: Definition[] = [], bi
                 if (m.film != null) row.film = m.film
                 if (m.version != null) row.version = m.version
                 if (m.length != null) row.length = m.length
+                if (m.words != null) row.words = m.words
+                if (m.stamp != null) row.stamp = m.stamp
                 if (m.essential != null) row.essential = m.essential
                 const v = ROW_OF.get(c)
                 if (v != null) row.runs = runText(v.run)

package/src/cli/cmd_Review.ts

@@ -83,7 +83,7 @@ function tileOf(arg: string): { file: string; label: string } {
 
 type ViewInput = import('../review/store.ts').ViewInput
 
-/** `--view "<label>" a.png [b.png]` and `--gallery "<label>" a.png b.png …` out of the args */
+/** `--view "<label>" a.png [b.png] [--note "<text>"]` and `--gallery "<label>" a.png b.png …` out of the args */
 function takeViews(args: readonly string[]): { views: ViewInput[]; rest: string[] } {
     const views: ViewInput[] = []
     const rest: string[] = []
@@ -100,6 +100,13 @@ function takeViews(args: readonly string[]): { views: ViewInput[]; rest: string[
         if (a === '--gallery') views.push({ label, gallery: files.map(tileOf) })
         else views.push(files.length === 1 ? { label, image: files[0] } : { label, before: files[0], after: files[1] })
         i += 1 + files.length
+        if (args[i + 1] === '--note') {
+            const note = args[i + 2]
+            if (note === undefined || note.startsWith('--')) throw new Error(`--view "${label}" … --note "<text>": a line on that view`)
+            const v = views[views.length - 1]
+            if (v) v.note = note
+            i += 2
+        }
     }
     return { views, rest }
 }
@@ -139,7 +146,8 @@ const ADD_FLAGS = `flags:
   --audio <sound.wav>                 a sound: a waveform and a player (wav, mp3, flac, ogg, opus, m4a)
   --before <a.png> --after <b.png>    a before and after: two images, two clips of one size, or two sounds
   --label "<label>"                   the first view's label
-  --view "<label>" <a.png> [<b.png>]  another view of the same subject (repeat it)
+  --view "<label>" <a.png> [<b.png>]  another view of the same subject (repeat it); --note "<text>" right after it: a line on that view
+  --choice                            every view is an option he scores and picks one of (two --view or more)
   --gallery "<label>" <a.png> …       a grid of small images; "<tile label>=<c.png>" names a tile (repeat it)
   --topic <topic>                     what part of the project it is about (sk review topics)
   --subject <kind>                    what is judged (default shot; the repo's unit names its kinds)
@@ -150,6 +158,19 @@ const ADD_FLAGS = `flags:
   --keeps "<what stays>"              with --supersedes on an approved look: what of it stays
   --new --why "<reason>"              a new card beside an active one of the same subject`
 
+/** the help of add or add-view, then the flags this repo's review unit adds (any kind's, then each kind's under
+ *  `--subject <kind>`); a repo with no unit, or one that does not load, says so on one line */
+async function helpWithUnit(context: Ctx, usage: string, kinds: boolean): Promise<number> {
+    context.stdout.write(usage)
+    await run(context, (h) => {
+        const lines = Object.entries(h.unit?.flags ?? {}).map(([k, d]) => `  --${k} ${d}`)
+        if (kinds) for (const [name, k] of Object.entries(h.unit?.kinds ?? {})) for (const [f, d] of Object.entries(k.flags ?? {})) lines.push(`  --${f} ${d} (with --subject ${name})`)
+        h.out(lines.length > 0 ? `\nthis repo's review unit adds:\n${lines.join('\n')}` : "\nthis repo's review unit adds no flags")
+        return 0
+    })
+    return 0
+}
+
 export class ReviewAddCommand extends Command {
     static override paths = [['review', 'add']]
     static override usage = Command.Usage({
@@ -160,14 +181,14 @@ export class ReviewAddCommand extends Command {
             ['one image', 'sk review add --title "the new menu" --what "the menu, bigger" --image shots/menu.png'],
             ['a before and after', 'sk review add --title "lamps lit" --what "..." --before a.png --after b.png'],
             ['a second version after his answer', 'sk review add --title "lamps lit" --what "..." --image c.png --supersedes <id>'],
+            ['a pick among three voices', 'sk review add --choice --title "the narrator" --what "..." --view "voice 0" a.flac --note "low, breathy" --view "voice 1" b.flac --view "voice 2" c.flac'],
         ],
     })
     args = Option.Proxy()
 
     async execute(): Promise<number> {
         if (this.args.some(isHelp)) {
-            this.context.stdout.write(this.cli.usage(ReviewAddCommand, { detailed: true }))
-            return 0
+            return helpWithUnit(this.context, this.cli.usage(ReviewAddCommand, { detailed: true }), true)
         }
         return run(this.context, async (h) => {
             const { addItem } = await import('../review/store.ts')
@@ -176,7 +197,7 @@ export class ReviewAddCommand extends Command {
             const kindName = rest[rest.indexOf('--subject') + 1]
             const kind = rest.includes('--subject') && kindName ? h.unit?.kinds?.[kindName] : undefined
             const own = [...Object.keys(kind?.flags ?? {}), ...Object.keys(h.unit?.flags ?? {})]
-            const f = flagsOf(rest, ['title', 'what', 'image', 'video', 'audio', 'before', 'after', 'label', 'topic', 'subject', 'commit', 'lane', 'supersedes', 'keeps', 'why', 'live'], ['answers', ...own], ['new', 'wip'])
+            const f = flagsOf(rest, ['title', 'what', 'image', 'video', 'audio', 'before', 'after', 'label', 'topic', 'subject', 'commit', 'lane', 'supersedes', 'keeps', 'why', 'live'], ['answers', ...own], ['new', 'wip', 'choice'])
             if (f.positionals.length > 0) throw new Error(`unexpected ${f.positionals.join(' ')}`)
             const o = f.one
             const repoFlags = Object.fromEntries(own.flatMap((k) => (f.many[k] ? [[k, f.many[k]]] : [])))
@@ -209,6 +230,7 @@ export class ReviewAddCommand extends Command {
                 ...(o.why ? { why: o.why } : {}),
                 ...(answers.length > 0 ? { answers } : {}),
                 ...(f.on.has('new') ? { fresh: true } : {}),
+                ...(f.on.has('choice') ? { choice: true } : {}),
                 ...(o.live !== undefined ? { image: wipViews[0]?.image ?? '', views: wipViews.slice(1), wip: { live: o.live } } : { views }),
             }
             if (h.unit?.add) input = await h.unit.add(input, repoFlags)
@@ -225,27 +247,29 @@ export class ReviewAddViewCommand extends Command {
     static override usage = Command.Usage({
         category: 'Review',
         description: 'another angle on a card he has not answered yet: an image, a pair, a clip or a gallery',
-        details: `${DETAILS}\n\nsk review add-view <id> "<label>" <a.png> [<b.png>] | --video <clip.mp4> | --gallery <a.png> <b.png> …`,
+        details: `${DETAILS}\n\nsk review add-view <id> "<label>" <a.png> [<b.png>] | --video <clip.mp4> | --audio <sound.wav> | --gallery <a.png> <b.png> … [--note "<a line on that view>"]`,
         examples: [['a view from above', 'sk review add-view <id> "from above" top.png']],
     })
     args = Option.Proxy()
 
     async execute(): Promise<number> {
         if (this.args.some(isHelp)) {
-            this.context.stdout.write(this.cli.usage(ReviewAddViewCommand, { detailed: true }))
-            return 0
+            return helpWithUnit(this.context, this.cli.usage(ReviewAddViewCommand, { detailed: true }), false)
         }
         return run(this.context, async (h) => {
             const { addView } = await import('../review/store.ts')
             const own = Object.keys(h.unit?.flags ?? {})
             const repoFlags: Record<string, string[]> = {}
             const args: string[] = []
+            let note: string | undefined
             for (let i = 0; i < this.args.length; i++) {
                 const a = this.args[i] ?? ''
                 const name = a.startsWith('--') ? a.slice(2) : ''
                 if (own.includes(name)) (repoFlags[name] ??= []).push(this.args[++i] ?? '')
+                else if (name === 'note') note = this.args[++i]
                 else args.push(a)
             }
+            if (this.args.includes('--note') && (note === undefined || note.startsWith('--'))) throw new Error('--note "<text>": a line on that view')
             const [id, label, ...rest] = args
             if (!id || !label) throw new Error('add-view <id> "<label>" <media>')
             const v: ViewInput =
@@ -262,6 +286,7 @@ export class ReviewAddViewCommand extends Command {
                           : (() => {
                                 throw new Error('add-view <id> "<label>" <a.png> [<b.png>] | --video <clip> | --gallery <a.png> …')
                             })()
+            if (note !== undefined) v.note = note
             const extra = h.unit?.addView ? await h.unit.addView(v, repoFlags) : {}
             const item = await addView(h.dir, id, v, extra)
             h.out(`${id}: view ${item.views.length} "${label}" added`)
@@ -380,10 +405,11 @@ export class ReviewInboxCommand extends Command {
             const followed = followedIds(all.items)
             // what he or a player raised and nobody closed is the agents' move, read or not
             const open = all.items.filter((x) => of(x) && x.item.origin.by !== 'agent' && moveOf(stateOf(x, followed.has(x.item.id)).state) === 'agents' && !news.includes(x))
-            // a plain approval (no comment, no rectangle, no reply) asks for no work: counted on one line unless --all
+            // a plain approval (no comment, no rectangle, no reaction, no pick, no reply) asks for no work: counted on one
+            // line unless --all
             const plain = (x: (typeof news)[number]): boolean => {
                 const v = verdictOf(x)
-                return v?.status === 'approved' && !v.seen && !v.comment && v.rects.length === 0 && unreadBy(x, 'agent').length === 0
+                return v?.status === 'approved' && !v.seen && !v.comment && v.rects.length === 0 && !v.reactions && v.pick === undefined && unreadBy(x, 'agent').length === 0
             }
             const shown = [...(this.all ? news : news.filter((x) => !plain(x))), ...open]
             if (shown.length === 0 && news.length === 0) h.out('review: no unseen feedback or reply')

package/src/cli/cmd_Sound.ts

@@ -0,0 +1,209 @@
+// sk sound: the house sound generators, one verb each, for a trailer as much as a game. Each writes --out and says its
+// measures; a trailer's `voice`, `sfx` and `music` words run them through its sound cache (trailer/sound/). Every
+// module loads inside execute: the cli registers this file on every `sk` call
+import { Command, Option } from 'clipanion'
+
+const PAGE = 'Page: wiki build/trailer.md, Sound'
+
+async function run(context: { stdout: NodeJS.WritableStream; stderr: NodeJS.WritableStream }, body: (say: (l: string) => void, root: string, cwd: string) => Promise<void>): Promise<number> {
+    const say = (l: string): void => void context.stdout.write(`${l}\n`)
+    const { findRepoRoot } = await import('../ts/config.ts')
+    const cwd = process.cwd()
+    try {
+        await body(say, findRepoRoot(cwd), cwd)
+        return 0
+    } catch (e) {
+        context.stderr.write(`FAIL sound: ${e instanceof Error ? e.message : String(e)}\n`)
+        return 1
+    }
+}
+
+/** the brand's sound section, when the repo has a brand */
+async function brandSound(root: string): Promise<import('../trailer/sound/brand.ts').TrailerSoundInput | undefined> {
+    const { loadBrand } = await import('../assets/run-assets.ts')
+    const b = await loadBrand(root)
+    if (typeof b === 'string') throw new Error(b)
+    return b?.trailer
+}
+
+const COMFY = 'the comfy-ts module folder (default: the brand\'s trailer.comfy)'
+
+/** --out, which every making verb needs */
+function outOf(out: string | undefined): string {
+    if (out === undefined) throw new Error('--out <file>: the file it writes')
+    return out
+}
+
+const num = (name: string, v: string | undefined, fallback: number): number => {
+    if (v === undefined) return fallback
+    const n = Number(v)
+    if (!Number.isFinite(n)) throw new Error(`${name} takes a number, got ${v}`)
+    return n
+}
+
+export class SoundVoiceCommand extends Command {
+    static override paths = [['sound', 'voice']]
+    static override usage = Command.Usage({
+        category: 'Sound',
+        description: 'one spoken line in a voice: ElevenLabs, or comfy-ts cloning a clip or a designed voice',
+        details: `no voice flag: the brand's trailer.voice (--by <name>: one of its trailer.voices), else the house narrator. ElevenLabs is paid: it says the characters spent and left. The line is trimmed at both ends and set at -16 LUFS. ${PAGE}`,
+        examples: [
+            ['the brand\'s voice', 'sk sound voice "The storm is coming." --out lines/storm.wav'],
+            ['an ElevenLabs voice, its second take', 'sk sound voice "[whispers] Hey." --eleven pNInz6obpgDQGcFmaJgB --seed 2 --out hey.wav'],
+            ['a clip cloned, free', 'sk sound voice "Ahoy." --clone voices/sailor.flac --out ahoy.wav'],
+            ['a voice designed from words, free', 'sk sound voice "Ahoy." --design "an old sailor, gravelly and warm" --out ahoy.wav'],
+        ],
+    })
+    text = Option.String({ required: true, name: 'line' })
+    by = Option.String('--by', { description: 'one of the brand\'s trailer.voices' })
+    eleven = Option.String('--eleven', { description: 'an ElevenLabs voice id (paid)' })
+    model = Option.String('--model', { description: 'the ElevenLabs model (default eleven_v3)' })
+    stability = Option.String('--stability')
+    similarity = Option.String('--similarity')
+    speed = Option.String('--speed')
+    clone = Option.String('--clone', { description: 'a clean 5 to 10 s clip to clone, repo relative' })
+    transcript = Option.String('--transcript', { description: 'what the clip says (default: <clip>.txt)' })
+    design = Option.String('--design', { description: 'a voice designed from its description' })
+    designLine = Option.String('--design-line', { description: 'what the designed voice\'s reference reads' })
+    designSeed = Option.String('--design-seed')
+    engine = Option.String('--engine', { description: 'comfy-ts engine: chatterbox, qwen3, fishs2, cosyvoice3, omnivoice' })
+    language = Option.String('--language', { description: 'en, fr… (ElevenLabs) or English, French… (comfy-ts)' })
+    comfy = Option.String('--comfy', { description: COMFY })
+    seed = Option.String('--seed', { description: 'the take (default 1)' })
+    out = Option.String('--out', { description: 'the file it writes (required)' })
+
+    execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const [{ resolve }, { genVoice }, { voiceOf }] = await Promise.all([import('node:path'), import('../trailer/sound/gen.ts'), import('../trailer/sound/brand.ts')])
+            const brand = await brandSound(root)
+            const given = [this.eleven, this.clone, this.design].filter((x) => x !== undefined).length
+            if (given > 1) throw new Error('one voice: --eleven, --clone or --design')
+            const n = (k: string, v: string | undefined): number | undefined => (v === undefined ? undefined : num(k, v, 0))
+            const lang = this.language !== undefined ? { language: this.language } : {}
+            const eng = this.engine !== undefined ? { engine: this.engine } : {}
+            let voice
+            if (this.eleven !== undefined) voice = { eleven: this.eleven, ...(this.model ? { model: this.model } : {}), ...strip({ stability: n('--stability', this.stability), similarity: n('--similarity', this.similarity), speed: n('--speed', this.speed) }), ...lang }
+            else if (this.clone !== undefined) voice = { clone: this.clone, ...(this.transcript !== undefined ? { transcript: this.transcript } : {}), ...eng, ...lang }
+            else if (this.design !== undefined) voice = { design: this.design, ...(this.designLine !== undefined ? { line: this.designLine } : {}), ...strip({ seed: n('--design-seed', this.designSeed) }), ...eng, ...lang }
+            else voice = voiceOf(brand, this.by)
+            await genVoice({ root, text: this.text, voice, seed: num('--seed', this.seed, 1), comfy: this.comfy ?? brand?.comfy, elevenKey: brand?.elevenKey, out: resolve(cwd, outOf(this.out)), say })
+        })
+    }
+}
+
+const strip = <T extends Record<string, unknown>>(o: T): Partial<T> => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as Partial<T>
+
+export class SoundSfxCommand extends Command {
+    static override paths = [['sound', 'sfx']]
+    static override usage = Command.Usage({
+        category: 'Sound',
+        description: 'a sound effect from a prompt: comfy-ts stable-audio, trimmed, its peak at -3 dBFS',
+        details: `its silence before is cut, its tail cut where it falls 45 dB under its peak with a 30 ms fade; --hit keeps its first hit alone. The GPU box must be up: sk gp start comfyui. ${PAGE}`,
+        examples: [
+            ['a clash cut to its first hit', 'sk sound sfx "a sword clash, metal on metal" --hit --out sfx/clash.wav'],
+            ['four seconds of rain, another take', 'sk sound sfx "rain on a tin roof" --seconds 4 --seed 2 --out sfx/rain.wav'],
+        ],
+    })
+    prompt = Option.String({ required: true, name: 'prompt' })
+    seconds = Option.String('--seconds', { description: 'seconds made (default 2)' })
+    seed = Option.String('--seed', { description: 'the take (default 1)' })
+    hit = Option.Boolean('--hit', false, { description: 'its first hit alone' })
+    comfy = Option.String('--comfy', { description: COMFY })
+    out = Option.String('--out', { description: 'the file it writes (required)' })
+
+    execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const [{ resolve }, { genSfx }] = await Promise.all([import('node:path'), import('../trailer/sound/gen.ts')])
+            const comfy = this.comfy ?? (await brandSound(root))?.comfy
+            await genSfx({ prompt: this.prompt, seconds: num('--seconds', this.seconds, 2), seed: num('--seed', this.seed, 1), hit: this.hit, comfy, out: resolve(cwd, outOf(this.out)), say })
+        })
+    }
+}
+
+export class SoundMusicCommand extends Command {
+    static override paths = [['sound', 'music']]
+    static override usage = Command.Usage({
+        category: 'Sound',
+        description: 'a music bed or a song from a prompt: comfy-ts stable-audio or ace-step, -16 LUFS',
+        details: `stable-audio plays an instrumental bed (up to 300 s); ace-step reads the prompt's first line as its style caption and sings the lines after it ([Verse], [Chorus]), else plays instrumental. The GPU box must be up: sk gp start comfyui. ${PAGE}`,
+        examples: [
+            ['a 30 s bed', 'sk sound music "warm lofi piano bed, slow, soft" --seconds 30 --out music/bed.wav'],
+            ['a sung theme, its third take', 'sk sound music "an epic orchestral theme, brass and choir" --engine ace-step --seed 3 --out music/theme.wav'],
+        ],
+    })
+    prompt = Option.String({ required: true, name: 'prompt' })
+    engine = Option.String('--engine', { description: 'stable-audio (default) or ace-step' })
+    seconds = Option.String('--seconds', { description: 'seconds made (default 30)' })
+    seed = Option.String('--seed', { description: 'the take (default 1)' })
+    comfy = Option.String('--comfy', { description: COMFY })
+    out = Option.String('--out', { description: 'the file it writes (required)' })
+
+    execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const [{ resolve }, { genMusic }] = await Promise.all([import('node:path'), import('../trailer/sound/gen.ts')])
+            const engine = this.engine ?? 'stable-audio'
+            if (engine !== 'stable-audio' && engine !== 'ace-step') throw new Error(`--engine ${engine}: stable-audio or ace-step`)
+            const comfy = this.comfy ?? (await brandSound(root))?.comfy
+            await genMusic({ prompt: this.prompt.replaceAll('\\n', '\n'), engine, seconds: num('--seconds', this.seconds, 30), seed: num('--seed', this.seed, 1), comfy, out: resolve(cwd, outOf(this.out)), say })
+        })
+    }
+}
+
+export class SoundMidiCommand extends Command {
+    static override paths = [['sound', 'midi']]
+    static override usage = Command.Usage({
+        category: 'Sound',
+        description: 'a MIDI file through the soundfont: FluidSynth, its own room on, -16 LUFS',
+        details: `the machine's fluidsynth and ~/.local/share/soundfonts/GeneralUser-GS.sf2 (SK_SOUNDFONT names another). ${PAGE}`,
+        examples: [['a .mid as a wav', 'sk sound midi theme.mid --out music/theme.wav']],
+    })
+    file = Option.String({ required: true, name: 'file.mid' })
+    out = Option.String('--out', { description: 'the file it writes (required)' })
+
+    execute(): Promise<number> {
+        return run(this.context, async (say, _root, cwd) => {
+            const [{ resolve }, { genMidi }] = await Promise.all([import('node:path'), import('../trailer/sound/gen.ts')])
+            await genMidi({ file: resolve(cwd, this.file), out: resolve(cwd, outOf(this.out)), say })
+        })
+    }
+}
+
+export class SoundMeasureCommand extends Command {
+    static override paths = [['sound', 'measure']]
+    static override usage = Command.Usage({
+        category: 'Sound',
+        description: 'a sound as numbers and a picture: length, peak, loudness, onsets, the waveform png',
+        details: `nobody hears a build: read these before you report a sound. The png lands at <file>.png. ${PAGE}`,
+        examples: [['a made sfx', 'sk sound measure sfx/clash.wav']],
+    })
+    file = Option.String({ required: true, name: 'file' })
+
+    execute(): Promise<number> {
+        return run(this.context, async (say, _root, cwd) => {
+            const [{ resolve }, { measure, measureLine, waveformPng }] = await Promise.all([import('node:path'), import('../trailer/sound/audio.ts')])
+            const f = resolve(cwd, this.file)
+            say(`${this.file}: ${measureLine(await measure(f))}`)
+            await waveformPng(f, `${f}.png`)
+            say(`ok: ${f}.png`)
+        })
+    }
+}
+
+export class SoundGmCommand extends Command {
+    static override paths = [['sound', 'gm']]
+    static override usage = Command.Usage({
+        category: 'Sound',
+        description: 'the General MIDI programs, drums and kits a score\'s gm: instruments take',
+        details: `a score track plays one through the soundfont: track piano gm:acoustic-grand, drums k=gm:kick, or gm('strings', { vol, pan, reverb }) in its code. ${PAGE}`,
+        examples: [['every name', 'sk sound gm']],
+    })
+
+    execute(): Promise<number> {
+        return run(this.context, async (say) => {
+            const { gmTable } = await import('../trailer/score/gm.ts')
+            for (const l of gmTable()) say(l)
+        })
+    }
+}
+
+export const SOUND_COMMANDS = [SoundVoiceCommand, SoundSfxCommand, SoundMusicCommand, SoundMidiCommand, SoundMeasureCommand, SoundGmCommand]

package/src/cli/cmd_Trailer.ts

@@ -32,17 +32,19 @@ export class TrailerCommand extends Command {
             ['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'],
+            ['the music variant b on the same picture', 'sk trailer --variant b'],
         ],
     })
 
     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)' })
+    variant = Option.String('--variant', { description: 'a music variant the cut names (music … variant <name>): out/<name>-<variant>.mp4' })
 
     async execute(): Promise<number> {
         return run(this.context, async (say, root, cwd) => {
             const b = await import('../trailer/build.ts')
-            const l = await b.load(b.trailerFile(this.file, root, cwd), root)
+            const l = await b.load(b.trailerFile(this.file, root, cwd), root, this.variant !== undefined ? { variant: this.variant } : {})
             if (!b.sayErrors(l, say, cwd)) return 1
             await b.build(l, { refilm: refilmOf(this.refilm), final: this.final, say, cwd })
             return 0
@@ -64,14 +66,17 @@ export class TrailerCheckCommand extends Command {
     })
 
     file = Option.String({ required: false })
+    variant = Option.String('--variant', { description: 'a music variant the cut names' })
 
     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 = await b.load(b.trailerFile(this.file, root, cwd), root)
+            const l = await b.load(b.trailerFile(this.file, root, cwd), root, this.variant !== undefined ? { variant: this.variant } : {})
             if (!b.sayErrors(l, say, cwd)) return 1
             for (const line of b.timeline(l, b.takesOfLoaded(l), await b.worldOf(l), cwd)) say(line)
+            for (const line of await b.soundLines(l)) say(`  ${line}`)
+            for (const line of await b.fontLines(l)) say(`  ${line}`)
             say(`ok: checked in ${((performance.now() - t0) / 1000).toFixed(2)} s`)
             return 0
         })

package/src/cli/kit/verb.ts

@@ -65,6 +65,10 @@ export type Verb = {
     version?: number | string
     /** with film: `own`, a clip that films as long as it plays (no `--seconds`) */
     length?: 'own'
+    /** with film: the words it takes and their types (trailer/words.ts), each checked at its line of a .trailer */
+    words?: Record<string, unknown>
+    /** with film: the paths its takes film, their world */
+    stamp?: string[]
 }
 
 /** the argv a row runs */
@@ -126,6 +130,8 @@ export function verbs(rows: Verb[]): CommandClass[] {
             static film = v.film
             static filmVersion = v.version
             static filmLength = v.length
+            static filmWords = v.words
+            static filmStamp = v.stamp
             args = Option.Proxy()
             async execute(): Promise<number> {
                 const { root, cwd } = this.context
@@ -154,14 +160,16 @@ export function verbs(rows: Verb[]): CommandClass[] {
 
 /** the marks a command class carries: set by `verbs()` from its row, or
  *  declared as statics on a hand written class */
-export function marksOf(c: object): { essential?: Essential; film?: Film; version?: number | string; length?: 'own' } {
-    const o = c as { essential?: unknown; film?: unknown; filmVersion?: unknown; filmLength?: unknown }
-    const out: { essential?: Essential; film?: Film; version?: number | string; length?: 'own' } = {}
+export function marksOf(c: object): { essential?: Essential; film?: Film; version?: number | string; length?: 'own'; words?: Record<string, unknown>; stamp?: string[] } {
+    const o = c as { essential?: unknown; film?: unknown; filmVersion?: unknown; filmLength?: unknown; filmWords?: unknown; filmStamp?: unknown }
+    const out: { essential?: Essential; film?: Film; version?: number | string; length?: 'own'; words?: Record<string, unknown>; stamp?: string[] } = {}
     if (typeof o.essential === 'object' && o.essential !== null) out.essential = o.essential as Essential
     if (o.film === 'still' || o.film === 'clip') {
         out.film = o.film
         if (typeof o.filmVersion === 'number' || typeof o.filmVersion === 'string') out.version = o.filmVersion
         if (o.filmLength === 'own') out.length = 'own'
+        if (typeof o.filmWords === 'object' && o.filmWords !== null) out.words = o.filmWords as Record<string, unknown>
+        if (Array.isArray(o.filmStamp)) out.stamp = o.filmStamp.map(String)
     }
     return out
 }

package/src/cli.ts

@@ -41,6 +41,7 @@ import { ShotCommand } from './cli/cmd_Shot.ts'
 import { StatusCommand } from './cli/cmd_Status.ts'
 import { StartCommand } from './cli/cmd_Start.ts'
 import { TRAILER_COMMANDS } from './cli/cmd_Trailer.ts'
+import { SOUND_COMMANDS } from './cli/cmd_Sound.ts'
 import { REVIEW_COMMANDS } from './cli/cmd_Review.ts'
 import { TuiCommand } from './cli/cmd_Tui.ts'
 import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
@@ -73,6 +74,7 @@ export function buildCli(): Cli {
     cli.register(CheckCommand)
     cli.register(TuiCommand)
     for (const c of TRAILER_COMMANDS) cli.register(c)
+    for (const c of SOUND_COMMANDS) cli.register(c)
     for (const c of REVIEW_COMMANDS) cli.register(c)
     cli.register(ServeCommand)
     cli.register(PmCommand)

package/src/core/app-icon.ts

@@ -10,8 +10,9 @@ import { identityOfName, identityOfText, type Identity } from './identity-color.
 import { configName, CONFIG_FILE } from './identity.ts'
 import { LAYOUT } from './layout.ts'
 
-/** the mark an app wears: the repo's own, largest first. Rasters only */
-export const APP_ICON_FILES = [`${LAYOUT.identity}/icon.png`, 'public/logo.png', 'public/favicon.png']
+/** the mark an app wears: the repo's own, largest first; an svg mark is drawn
+ *  as an image too (the canvas decodes it) */
+export const APP_ICON_FILES = [`${LAYOUT.identity}/icon.png`, `${LAYOUT.identity}/icon.svg`, 'public/logo.png', 'public/favicon.png']
 
 export function appIconOf(root: string): string | null {
     for (const f of APP_ICON_FILES) if (existsSync(join(root, f))) return join(root, f)
@@ -133,15 +134,18 @@ export async function drawAppIcon(bytes: Uint8Array, id: Identity): Promise<{ ca
     return { canvas: out, plate: colour }
 }
 
-/** the icon as pngs, one per size asked, drawn once */
-export async function appIconPngs(bytes: Uint8Array, id: Identity, sizes: number[] = [ICON_PX]): Promise<Buffer[]> {
+/** the icon as pngs, one per size asked, drawn once. `plate` crops the macOS
+ *  grid's margin away, the rounded plate edge to edge (the hub's rail) */
+export async function appIconPngs(bytes: Uint8Array, id: Identity, sizes: number[] = [ICON_PX], crop: 'canvas' | 'plate' = 'canvas'): Promise<Buffer[]> {
     const { canvas } = await drawAppIcon(bytes, id)
+    const o = crop === 'plate' ? (ICON_PX - PLATE) / 2 : 0
+    const side = crop === 'plate' ? PLATE : ICON_PX
     return sizes.map((px) => {
-        if (px === ICON_PX) return canvas.toBuffer('image/png')
+        if (px === ICON_PX && crop === 'canvas') return canvas.toBuffer('image/png')
         const small = createCanvas(px, px)
         const ctx = small.getContext('2d')
         ctx.imageSmoothingQuality = 'high'
-        ctx.drawImage(canvas, 0, 0, px, px)
+        ctx.drawImage(canvas, o, o, side, side, 0, 0, px, px)
         return small.toBuffer('image/png')
     })
 }

package/src/repo-config.ts

@@ -57,6 +57,9 @@ export type ServeConfig = {
          *  one failed, green when all passed. Default: the built-in md lint
          *  (orphans and dangling refs) over the repo root */
         lint?: string[]
+        /** the folder its node ids are relative to, where the wikis page reads
+         *  a page to search and preview (default: the repo root) */
+        dir?: string
     }
     /** agent/ graph entrypoint (default: index.md AND README.md) */
     agentIndex?: string

package/src/review/format.ts

@@ -19,7 +19,13 @@ const atText = (t: number | undefined): string => (t === undefined ? '' : ` at $
 
 /** each reaction to one view or tile: its place by label, its status, its comment */
 const reactionTexts = (x: ReviewItem): string[] =>
-    (verdictOf(x)?.reactions ?? []).map((q) => `${placeText(q, x.item.views)}${q.status ? ` ${q.status}` : ''}${q.comment ? `: ${flat(q.comment)}` : ''}`)
+    (verdictOf(x)?.reactions ?? []).map((q) => `${placeText(q, x.item.views)}${q.status ? ` ${q.status}` : ''}${q.stars ? ` ★${q.stars}` : ''}${q.comment ? `: ${flat(q.comment)}` : ''}`)
+
+/** the view he picked on a choice card, `picked [voice 1]`; null when he picked none */
+const pickText = (x: ReviewItem): string | null => {
+    const p = verdictOf(x)?.pick
+    return p === undefined ? null : `picked ${placeText({ view: p }, x.item.views)}`
+}
 
 /** one line per feedback, for a monitor: the status, the overall comment, each view's reaction, then each rectangle's comment */
 export function line(x: ReviewItem): string {
@@ -28,7 +34,8 @@ export function line(x: ReviewItem): string {
     const views = x.item.views
     const many = views.length > 1
     const rects = f.rects.map((q, i) => `#${i + 1}${many ? ` ${placeText(q, views)}` : ''}${q.side ? ` ${q.side}` : ''}${atText(q.t)} ${flat(q.comment) || '(no comment)'}`)
-    const parts = [...reactionTexts(x), ...rects]
+    const pick = pickText(x)
+    const parts = [...(pick ? [pick] : []), ...reactionTexts(x), ...rects]
     return `${x.item.id} ${f.status} "${x.item.title}": ${flat(f.comment) || '(no overall comment)'}${parts.length ? ` | ${parts.join(' | ')}` : ''}`
 }
 
@@ -131,7 +138,8 @@ export function detail(x: ReviewItem, dir: string, full = false, followed = fals
         ].join('\n')
     }
     if (!f) return [`${r.id}  NO VERDICT YET`, head, ...sub, ...replies].join('\n')
-    const out = [`${r.id}  ${f.status.toUpperCase()}  ${f.at}`, head, ...sub, `  comment: ${f.comment || '(none)'}`]
+    const pick = pickText(x)
+    const out = [`${r.id}  ${f.status.toUpperCase()}  ${f.at}`, head, ...sub, ...(pick ? [`  ${pick}`] : []), `  comment: ${f.comment || '(none)'}`]
     for (const t of reactionTexts(x)) out.push(`  view ${t}`)
     const px = (v: number, of: number): number => Math.round(v * of)
     const views = r.views