rvlib-shipkit 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.5.0
+
+- **A review card hands itself to any agent session.** A small copy icon on the card's header (or C) copies one block: its title and state, its repo, `cd <repo> && sk review show <id>`, its link here and on the phone when the repo has a public host; a toast says what was copied. `sk review show <id> --paste` prints the same block.
+- **The overall comment box sits under the card's header**, after the verdicts, on every card and in every layout.
+- **Push every unpushed repo: `sk fleet push` and a button on the activity page.** Each house repo with commits its remote lacks gets a plain `git push`, never a force; a branch with no upstream goes `-u` to its one remote; a branch that is also behind, a gone upstream or a detached head is skipped with the reason. `--dry` plans only.
+
+- **A new repo's agent/index.md routes with `→`.** The scaffold's table rows, the project CLI's row and its `next:` hint write `→ agent/<page>.md`, the wiki's form for a page to open, instead of a backticked path.
+
 ## 2.3.0
 
 - **A sound is a review view.** `sk review add --audio <sound>`, a sound in `--view`, `add-view <id> "<label>" --audio <sound>`, or a before and after of two sounds: the store keeps the sound and draws its waveform (`wave.png`, `before-wave.png`), and the hub shows each waveform over a player, one row a side. A sound takes reactions and words, never a rectangle; a pair is never a sound and an image.
@@ -15,8 +23,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.5.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",
@@ -36,7 +36,7 @@
     },
     "dependencies": {
         "@floating-ui/react": "^0.27.20",
-        "@napi-rs/canvas": "^1.0.2",
+        "@napi-rs/canvas": "^1.1.0",
         "clipanion": "^4.0.0-rc.4",
         "comfy-ts": "^2.9.0",
         "ink": "^7.1.1",

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

@@ -5,6 +5,7 @@
 // (the kit in cli/kit/) come out of these functions.
 import { Command, Option } from 'clipanion'
 import { spliceMarkedBlock } from '../core/doc-block.ts'
+import { FAMILY_PAGES } from './family-pages.ts'
 import { type Essential, type Film, marksOf, ROW_OF, runText } from './kit/verb.ts'
 
 export type CommandOption = { definition: string; description: string }
@@ -20,6 +21,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 +84,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)
@@ -113,12 +118,13 @@ export function renderMarkdown(rows: CommandRow[], bin = 'sk'): string {
 
 /** the eager form: one line per command, its positional arguments and its
  *  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[], bin = 'sk'): string {
+ *  session loads costs a line per command, not a screen. `pages` puts each
+ *  family's owner page in its heading: `### Trailer → build/trailer.md` */
+export function renderCompact(rows: CommandRow[], bin = 'sk', pages: Readonly<Record<string, string>> | null = null): string {
     const out: string[] = []
     let cat = ''
     for (const r of rows) {
-        if (r.category !== cat) { cat = r.category; out.push(`\n### ${cat}\n`) }
+        if (r.category !== cat) { cat = r.category; out.push(`\n### ${cat}${pages?.[cat] != null ? ` → ${pages[cat]}` : ''}\n`) }
         const sig = r.usage.replace(/^\$0/, bin).replace(/\s+\[(?:-|<\w+>)[^\]]*\]/g, '').trim() || `${bin} ${r.path}`
         out.push(`- \`${sig}\` — ${r.description}`)
     }
@@ -150,6 +156,15 @@ export function renderEssentials(rows: CommandRow[], bin: string, command: strin
     return `${out.join('\n')}\n`
 }
 
+/** a family with no owner page, and a page for a family no command has: one line each */
+export function familyProblems(rows: CommandRow[], pages: Readonly<Record<string, string>>): string[] {
+    const families = new Set(rows.map((r) => r.category))
+    return [
+        ...[...families].filter((f) => pages[f] == null).map((f) => `family ${f}: no owner page in src/cli/family-pages.ts`),
+        ...Object.keys(pages).filter((f) => !families.has(f)).map((f) => `family ${f}: src/cli/family-pages.ts names a page for a family no command has`),
+    ]
+}
+
 /** 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 */
@@ -205,6 +220,9 @@ export class CommandsCommand extends Command {
      *  a breach), and its --out creates a missing page */
     static shapeRule = false
 
+    /** each family's owner page, named in the compact page's headings; a project CLI has none */
+    static familyPages: Readonly<Record<string, string>> | null = FAMILY_PAGES
+
     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' })
@@ -221,10 +239,17 @@ export class CommandsCommand extends Command {
             classes,
         )
         const write = (s: string): void => void this.context.stdout.write(s)
+        const pages = (this.constructor as typeof CommandsCommand).familyPages
+        const render = (): string => (this.compact ? renderCompact(rows, bin, pages) : renderMarkdown(rows, bin))
         if (this.out == null && this.essentials == null) {
-            write(this.json ? `${JSON.stringify(rows)}\n` : `${(this.compact ? renderCompact : renderMarkdown)(rows, bin)}\n`)
+            write(this.json ? `${JSON.stringify(rows)}\n` : `${render()}\n`)
             return 0
         }
+        if (this.out != null && this.compact && pages != null) {
+            const bad = familyProblems(rows, pages)
+            for (const b of bad) write(`FAIL: ${b}\n`)
+            if (bad.length > 0) { write('      fix: one row per family in src/cli/family-pages.ts, the wiki page that owns it\n'); return 1 }
+        }
         if ((this.constructor as typeof CommandsCommand).shapeRule) {
             const bad = shapeProblems(rows, bin)
             for (const b of bad) write(`FAIL: ${b}\n`)
@@ -246,7 +271,7 @@ export class CommandsCommand extends Command {
         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)
+        const next = spliceBlock(host, render(), 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) {

package/src/cli/cmd_FleetPush.ts

@@ -0,0 +1,47 @@
+// shipkit fleet push — every house repo that holds commits its remote does
+// not, pushed: a plain git push, never a force (fleet/push-fleet.ts, the same
+// path as the activity page's push button). A repo that fell behind waits for
+// a pull, and says so.
+import { Command, Option } from 'clipanion'
+import { homedir } from 'os'
+import { gitRoot } from '../core/git-root.ts'
+import { pushFleet } from '../fleet/push-fleet.ts'
+import { houseRepos } from '../serve/project-gutter.ts'
+import { listFlag } from './list-flag.ts'
+
+export class FleetPushCommand extends Command {
+    static override paths = [['fleet', 'push']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'push every house repo with unpushed commits: a plain git push, never a force',
+        examples: [
+            ['push what is unpushed, everywhere', 'sk fleet push'],
+            ['what would go out', 'sk fleet push --dry'],
+            ['some repos only', 'sk fleet push --only my-app --only other'],
+        ],
+    })
+
+    dry = Option.Boolean('--dry', false, { description: 'plan only: say what would be pushed and what is skipped, push nothing' })
+    only = Option.Array('--only', { description: 'limit to these repo names (repeatable)' })
+    all = Option.Boolean('--all', false, { description: 'also print the repos that have nothing to push' })
+
+    async execute(): Promise<number> {
+        const root = gitRoot(process.cwd())?.top ?? process.cwd()
+        let repos = houseRepos(root, homedir()).repos.map((r) => ({ name: r.name, path: r.path }))
+        const only = listFlag(this.only)
+        if (only.length > 0) repos = repos.filter((r) => only.includes(r.name))
+        const w = (l: string) => this.context.stdout.write(`${l}\n`)
+        if (repos.length === 0) {
+            w(`skip: no house repo found from ${root}`)
+            return 0
+        }
+        const res = await pushFleet(repos, { dry: this.dry })
+        for (const r of res) if (this.all || r.action !== 'none') w(r.line)
+        const pushed = res.filter((r) => r.ok && (r.action === 'push' || r.action === 'push-upstream')).length
+        const failed = res.filter((r) => !r.ok && r.action !== 'skip').length
+        const skipped = res.filter((r) => r.action === 'skip').length
+        w(`${failed > 0 ? 'FAIL' : 'ok'}: ${repos.length} repos, ${this.dry ? `${res.filter((r) => r.action === 'push' || r.action === 'push-upstream').length} would push` : `${pushed} pushed`}, ${skipped} skipped${failed > 0 ? `, ${failed} failed` : ''}`)
+        return failed > 0 ? 1 : 0
+    }
+}

package/src/cli/cmd_GlobalProcesses.ts

@@ -28,7 +28,7 @@ export type GlobalProcessesAnswer = {
 export type GlobalProcessesDeps = {
     pm: () => Promise<PmAnswer | null>
     /** the daemon's identity, for its version; null when it does not answer */
-    daemon?: () => Promise<{ version: string } | null>
+    daemon?: () => Promise<{ version: string; held?: string | null } | null>
     /** the declared units, read like pm reads them; null when no house is found */
     declared: () => Promise<Pick<PmConfig, 'processes' | 'errors'> | null>
     /** the project list's order */
@@ -43,18 +43,18 @@ const localPorts = () => ({ pm: pmPort(), daemon: daemonPort(), web: homePort()
  *  pm does not answer */
 export async function globalProcessesAnswer(d: GlobalProcessesDeps): Promise<GlobalProcessesAnswer> {
     const [pm, daemon] = await Promise.all([d.pm(), d.daemon?.() ?? null])
-    const core = { daemonVersion: daemon?.version ?? null, ports: localPorts() }
+    const core = { daemonVersion: daemon?.version ?? null, daemonHeld: daemon?.held ?? null, ports: localPorts() }
     if (pm != null) return { pm: { pid: pm.pid, version: pm.version }, now: d.now, groups: processGroups(pm, d.order, core), errors: pm.unitErrors, house: true }
     const c = await d.declared()
     return { pm: null, now: d.now, groups: [coreGroup(null, core), ...groupRows((c?.processes ?? []).map(declaredRow), d.order)], errors: c?.errors ?? [], house: c != null }
 }
 
 /** the daemon's identity at /hub.json, or null */
-export async function askDaemon(url = daemonUrl()): Promise<{ version: string } | null> {
+export async function askDaemon(url = daemonUrl()): Promise<{ version: string; held: string | null } | null> {
     try {
         const r = await fetch(`${url}/hub.json`, { signal: AbortSignal.timeout(3_000) })
-        const j = r.ok ? ((await r.json()) as { hub?: string; version?: string }) : null
-        return j?.hub === 'shipkit-home' && typeof j.version === 'string' ? { version: j.version } : null
+        const j = r.ok ? ((await r.json()) as { hub?: string; version?: string; held?: string | null }) : null
+        return j?.hub === 'shipkit-home' && typeof j.version === 'string' ? { version: j.version, held: j.held ?? null } : null
     } catch {
         return null
     }

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`)
@@ -320,8 +345,14 @@ export class ReviewLsCommand extends Command {
 
 export class ReviewShowCommand extends Command {
     static override paths = [['review', 'show']]
-    static override usage = Command.Usage({ category: 'Review', description: 'one item and its thread: the verdict, rectangles, reactions, the whole conversation', details: `${DETAILS}\n\nTakes an item id or a player report's ref (live#3).` })
+    static override usage = Command.Usage({
+        category: 'Review',
+        description: 'one item and its thread: the verdict, rectangles, reactions, the whole conversation',
+        details: `${DETAILS}\n\nTakes an item id or a player report's ref (live#3). --paste prints the short block that hands the card to another agent session (the hub's copy button gives the same).`,
+        examples: [['hand a card to another session', 'sk review show <id> --paste']],
+    })
     id = Option.String()
+    paste = Option.Boolean('--paste', false, { description: 'the block another agent session acts on: title, repo, this command, the links' })
 
     async execute(): Promise<number> {
         return run(this.context, async (h) => {
@@ -332,6 +363,15 @@ export class ReviewShowCommand extends Command {
             const all = readAllCached(h.dir)
             const x = all.items.find((y) => y.item.id === id)
             if (!x) throw new Error(`no item ${this.id}`)
+            if (this.paste) {
+                const { dirname } = await import('node:path')
+                const { pasteHosts, cardUrl } = await import('../review/paste.ts')
+                const { pasteBlock, STATUS_LABEL } = await import('../review/model.ts')
+                const { statusOf } = await import('../review/threads.ts')
+                const w = await pasteHosts(dirname(dirname(h.dir)))
+                h.out(pasteBlock(x.item, STATUS_LABEL[statusOf(x, all.items)], { root: w.root, open: cardUrl(w.open, x.item.id), phone: w.phone ? cardUrl(w.phone, x.item.id) : null }))
+                return 0
+            }
             const t = threadOfItem(x.item.id, threadsOf(all.items))
             h.out(t && (t.head.item.id === x.item.id || t.answers.length > 0) ? threadDetail(t, h.dir, true, h.say) : detail(x, h.dir, true, false, h.say))
             return 0
@@ -380,10 +420,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')