rvlib-shipkit 2.3.0 → 2.5.0

package/src/review/store.ts

@@ -90,6 +90,8 @@ export interface ViewInput {
     after?: string
     /** a list of small images shown as a wrapping grid, each with its label; never the first view */
     gallery?: { file: string; label: string }[]
+    /** a line on this view alone: an option's description on a choice card */
+    note?: string
 }
 
 export interface AddInput {
@@ -123,6 +125,8 @@ export interface AddInput {
     light?: 'review'
     /** a draft card on a live shot: its image a live frame, no verdict until it is ready */
     wip?: { live: string }
+    /** every view is an option he picks one of */
+    choice?: boolean
     now?: Date
 }
 
@@ -228,12 +232,13 @@ function soundLength(file: string): number {
 /** the waveform a sound view shows, one size for every sound so a pair reads side by side */
 const WAVE_SIZE = { w: 1600, h: 240 }
 
-/** view `n`'s waveforms, drawn into `folder` beside their place and renamed */
+/** view `n`'s waveforms, drawn into `folder` beside their place and renamed: each column's peak on a square root scale,
+ *  so a voice's quiet syllables show; drawn white on transparent, the page fills it with its own colour (a mask) */
 async function writeWaves(v: Loaded, n: number, folder: string): Promise<void> {
     if (!v.audio) return
     const draw = async (from: string, name: string): Promise<void> => {
         const to = join(folder, `${prefix(n)}${name}.png`)
-        await ffmpeg(['-i', from, '-filter_complex', `showwavespic=s=${WAVE_SIZE.w}x${WAVE_SIZE.h}:split_channels=0:colors=0x8fb3ff`, '-frames:v', '1', '-f', 'image2', '-c:v', 'png', `${to}.tmp`])
+        await ffmpeg(['-i', from, '-filter_complex', `showwavespic=s=${WAVE_SIZE.w}x${WAVE_SIZE.h}:split_channels=0:scale=sqrt:filter=peak:colors=white`, '-frames:v', '1', '-f', 'image2', '-c:v', 'png', `${to}.tmp`])
         renameSync(`${to}.tmp`, to)
     }
     await draw(v.audio.from, 'wave')
@@ -245,10 +250,10 @@ const prefix = (n: number): string => (n > 0 ? `v${n}-` : '')
 /** the file name of tile `k` of gallery view `n` */
 const tileName = (n: number, k: number, path: string): string => `v${n}-g${k}${extname(path).toLowerCase()}`
 
-function viewOf(v: Loaded, n: number, marks: readonly ReviewMark[] = []): ReviewView {
+function viewOf(v: Loaded, n: number, marks: readonly ReviewMark[] = [], note?: string): ReviewView {
     if (v.tiles) return { label: v.label, gallery: v.tiles.map((t, k): GalleryTile => ({ file: tileName(n, k, t.path), label: t.label, size: t.size })) }
     const audio = v.audio ? { audio: { duration: v.audio.duration, wave: `${prefix(n)}wave.png`, ...(v.audio.before ? { waveBefore: `${prefix(n)}before-wave.png` } : {}) } } : {}
-    return { label: v.label, files: filesOf(v, n), size: v.size, ...clipOf(v, n), ...audio, ...(marks.length > 0 ? { marks: [...marks] } : {}) }
+    return { label: v.label, files: filesOf(v, n), size: v.size, ...clipOf(v, n), ...audio, ...(marks.length > 0 ? { marks: [...marks] } : {}), ...(note?.trim() ? { note: note.trim() } : {}) }
 }
 
 /** the file names of view `n` in the folder: `image.png` on the first, `v2-before.png` on a later one */
@@ -295,6 +300,8 @@ export async function addItem(dir: string, input: AddInput): Promise<Item> {
     if (given.length === 0) throw new Error('give --image, --video or --audio, or --before and --after, or --view "<label>" <image>')
     for (const [i, v] of given.entries()) if (i > 0 && !v.label.trim()) throw new Error('--view: every view after the first needs its label')
     if (given[0]?.gallery) throw new Error('a gallery is never the first view: give the card an --image (or a pair, or a clip) first')
+    if (input.choice && given.length < 2) throw new Error('--choice: a choice has two options or more, one --view each')
+    for (const v of given) if (v.note !== undefined && v.gallery) throw new Error(`--view "${v.label}": a note goes on an image, a clip or a sound, never a gallery`)
     const loaded = await Promise.all(given.map((v, i) => loadView(v, i === 0 ? 'the first view' : `--view "${v.label}"`)))
     if (input.supersedes !== undefined && !existsSync(join(dir, input.supersedes, 'item.json'))) throw new Error(`--supersedes ${input.supersedes}: no such card in ${dir}`)
     if (input.supersedes !== undefined && readItem(dir, input.supersedes)?.item.origin.by !== 'agent')
@@ -347,13 +354,14 @@ export async function addItem(dir: string, input: AddInput): Promise<Item> {
         what: input.what.trim(),
         ...(topic ? { topic } : {}),
         ...(input.commit ? { commit: input.commit } : {}),
-        views: loaded.map((v, n) => viewOf(v, n, input.marks?.[n])),
+        views: loaded.map((v, n) => viewOf(v, n, input.marks?.[n], given[n]?.note)),
         ...(input.supersedes ? { supersedes: input.supersedes } : {}),
         ...(answers.length > 0 ? { answers } : {}),
         ...(input.fresh && input.why ? { why: input.why.trim() } : {}),
         ...(input.supersedes && input.keeps?.trim() ? { keeps: input.keeps.trim() } : {}),
         ...(input.light ? { light: input.light } : {}),
         ...(input.wip ? { wip: { live: input.wip.live, frame: 1 } } : {}),
+        ...(input.choice ? { choice: true as const } : {}),
     }
     const problems = itemProblems(item)
     if (problems.length > 0) throw new Error(problems.join('; '))
@@ -383,6 +391,7 @@ export async function addView(dir: string, id: string, v: ViewInput, o: { marks?
     const x = readItem(dir, id)
     if (!x) throw new Error(`no card ${id}`)
     if (verdictOf(x)) throw new Error(`${id} has his answer already: a new version passes --supersedes ${id}`)
+    if (v.note !== undefined && v.gallery) throw new Error(`"${v.label}": a note goes on an image, a clip or a sound, never a gallery`)
     if (!v.label.trim()) throw new Error('add-view: the view needs its label')
     const loaded = await loadView(v, `the view "${v.label}"`)
     const n = x.item.views.length
@@ -391,7 +400,7 @@ export async function addView(dir: string, id: string, v: ViewInput, o: { marks?
     copyFiles(loaded, n, folder)
     await writePoster(loaded, n, folder)
     await writeWaves(loaded, n, folder)
-    const item: Item = { ...x.item, views: [...x.item.views, viewOf(loaded, n, o.marks)], ...(x.item.light || o.light ? { light: 'review' as const } : {}) }
+    const item: Item = { ...x.item, views: [...x.item.views, viewOf(loaded, n, o.marks, v.note)], ...(x.item.light || o.light ? { light: 'review' as const } : {}) }
     writeJson(join(folder, 'item.json'), item)
     return item
 }

package/src/review/unit.ts

@@ -11,10 +11,26 @@ export interface Fact {
     value: string
 }
 
-/** a link the hub opens */
+/** a link the hub opens. `host`: a page of the tool that frames the hub (pkm-multi's admin), its url relative to it:
+ *  in a frame it is posted to the host (`{ shipkit: 'open', url }`), alone it opens in a new tab */
 export interface Link {
     label: string
     url: string
+    host?: boolean
+}
+
+/** how a part's change reads: new, changed, gone or the same */
+export type PartTone = 'new' | 'changed' | 'gone' | 'same'
+
+/** one part of a subject the hub draws as a card of its own: a message of a post, a page of a script. `icon` an image
+ *  url (a data url carries a logo), `media` a repo relative file the hub serves beside the text, `badge` its change */
+export interface ViewPart {
+    label: string
+    detail?: string
+    icon?: string
+    badge?: { text: string; tone: PartTone }
+    media?: string
+    text: ViewText
 }
 
 /** a text the hub shows, or a change of one shown as a diff */
@@ -30,6 +46,8 @@ export interface KindDef<S extends Subject = Subject> extends SpecKind {
     /** a url the hub opens in a frame: the subject live */
     live?(x: ReviewItem): string | null
     text?(x: ReviewItem): ViewText | null
+    /** the subject in parts, each a card: a post's messages, with their logo, media and change */
+    parts?(x: ReviewItem): ViewPart[]
     /** the `sk review add` flags this kind reads, each with its help line: `--where <zone>:<x>,<y>` */
     flags?: Record<string, string>
     /** the subject (and its topic) a card of this kind gets from those flags, every flag as the list of its values;

package/src/scaffold/files/agent-index.md

@@ -18,8 +18,8 @@ Read the matching page before touching a surface:
 
 | read when touching… | page |
 |---|---|
-| any source file | `agent/coding.md` |
-| recent changes and why | `agent/changelog.md` |{{CLI_ROW}}
+| any source file | → agent/coding.md |
+| recent changes and why | → agent/changelog.md |{{CLI_ROW}}
 
 Grow this table: a subsystem, a service, a runbook each earn their own page,
 cross-linked from here.

package/src/scaffold/project-scaffold.ts

@@ -236,7 +236,7 @@ export function installedLib(root: string): { version?: string; exports?: Record
 /** the agent index lines that load the essentials page and list the full one */
 const cliIndexVars = (name: string, cli: boolean): { CLI_INCLUDE: string; CLI_ROW: string } => ({
     CLI_INCLUDE: cli ? `\n@${name}-essentials.md` : '',
-    CLI_ROW: cli ? `\n| every command of the project CLI | \`${cliPages(name).all}\` |` : '',
+    CLI_ROW: cli ? `\n| every command of the project CLI | → ${cliPages(name).all} |` : '',
 })
 
 /** an ADOPTED repo asking for the project CLI (`sk start <name> --cli`): the
@@ -257,7 +257,7 @@ export function adoptCli(root: string, opts: { name: string; print?: (line: stri
     addScripts(root, written, p, opts.name, false)
     const index = join(root, 'agent/index.md')
     const include = `@${opts.name}-essentials.md`
-    if (existsSync(index) && !readFileSync(index, 'utf8').split('\n').includes(include)) p(`next: in agent/index.md, load the everyday commands with the line ${include} and list \`${cliPages(opts.name).all}\` in its table`)
+    if (existsSync(index) && !readFileSync(index, 'utf8').split('\n').includes(include)) p(`next: in agent/index.md, load the everyday commands with the line ${include} and list → ${cliPages(opts.name).all} in its table`)
     const deps = { ...(pkg as { dependencies?: object }).dependencies, ...(pkg as { devDependencies?: object }).devDependencies }
     p(`ok: project CLI written: ${written.join(', ')} — run \`bun run cli\``)
     if (!('rvlib-shipkit' in deps)) p('next: bun add -d rvlib-shipkit   (the CLI imports rvlib-shipkit/cli-kit)')

package/src/serve/hub-app/activity-st.ts

@@ -10,6 +10,11 @@ import { clampCap, DEFAULT_CAP, DEFAULT_MINUTES, idleRow, WINDOW_MINUTES, type A
 export { ageShort, CAP_MAX, CAP_MIN, clampCap, DEFAULT_CAP, dirtWords, filesWords, upstreamWords, windowWords } from '../../home/activity-shape.ts'
 import type { HomeSt } from './home-st.ts'
 import { ownTrouble, reach } from './reach.ts'
+import type { PushResult } from '../../fleet/push-fleet.ts'
+
+/** the repos holding commits no remote has: ahead of their upstream, or on a branch with none */
+export const unpushedCount = (rows: Pick<ActivityRow, 'ahead' | 'upstream' | 'branch'>[]): number =>
+    rows.filter((r) => (r.ahead ?? 0) > 0 || (r.upstream == null && r.branch != null)).length
 
 export const ACTIVITY_POLL_MS = 60_000
 const MINUTES_KEY = 'home:activity:minutes'
@@ -38,6 +43,10 @@ function keep(key: string, n: number): void {
 export class ActivitySt {
     data: ActivityAnswer | null = null
     error = ''
+    /** the push button is running */
+    pushing = false
+    /** what the last push said, one line a repo that needed it */
+    pushed: PushResult[] | null = null
     minutes: number = keptMinutes()
     /** the most commits a repo shows before a click shows the rest */
     cap: number = clampCap(kept(CAP_KEY) ?? DEFAULT_CAP)
@@ -118,6 +127,28 @@ export class ActivitySt {
         this.st.select(name)
     }
 
+    /** repos holding commits no remote has */
+    get unpushed(): number {
+        return unpushedCount(this.data?.rows ?? [])
+    }
+
+    /** push every house repo that needs it, through the daemon (fleet/push-fleet.ts), then read git again */
+    async pushAll(): Promise<void> {
+        if (this.pushing) return
+        runInAction(() => { this.pushing = true; this.pushed = null })
+        try {
+            const r = await reach('/api/home/push-all', { method: 'POST', signal: AbortSignal.timeout(180_000) })
+            if (!r.ok) throw new Error(`${r.status} ${await r.text()}`)
+            const res = (await r.json()) as PushResult[]
+            runInAction(() => { this.pushed = res.filter((x) => x.action !== 'none'); this.error = '' })
+        } catch (e) {
+            runInAction(() => { this.error = ownTrouble(e, this.st.machine, (m) => `push every repo: ${m}`) })
+        } finally {
+            runInAction(() => { this.pushing = false })
+            void this.poll(true)
+        }
+    }
+
     /** the refresh button: a new git pass now, whatever the countdown says */
     refresh(): void {
         if (!this.loading) void this.poll(true)

package/src/serve/hub-app/activity-view.tsx

@@ -189,6 +189,12 @@ export const ActivityView = observer(({ app }: { app: HomeSt }) => {
                     <span className="acdim">commits</span>
                 </label>
                 <Next app={app} />
+                {st.unpushed > 0 || st.pushing ? (
+                    <button type="button" className="acpill acpush" disabled={st.pushing} onClick={() => void st.pushAll()}
+                        title="git push in every house repo with unpushed commits; never a force, a repo that fell behind waits for a pull (sk fleet push does the same)">
+                        {st.pushing ? 'pushing…' : `↑ push ${st.unpushed} unpushed`}
+                    </button>
+                ) : null}
                 {d == null ? <span className="acdim">reading every repo…</span> : (
                     <>
                         <span className="acpill">{busy.length} busy</span>
@@ -198,6 +204,9 @@ export const ActivityView = observer(({ app }: { app: HomeSt }) => {
                 )}
             </div>
             {st.error !== '' ? <div className="hnote">{st.error}</div> : null}
+            {st.pushed == null || st.pushed.length === 0 ? null : (
+                <div className="acpushed">{st.pushed.map((p) => <div key={p.name} className={p.ok ? 'ok' : p.action === 'skip' ? 'skip' : 'fail'}>{p.line}</div>)}</div>
+            )}
             {d != null && busy.length === 0 ? <div className="acdim">nothing committed or uncommitted in the last {windowWords(st.minutes)}</div> : null}
             {busy.length + idle.length === 0 ? null : (
                 <table className={`actable${st.stale ? ' stale' : ''}`}>

package/src/serve/hub-app/activity.css

@@ -72,3 +72,9 @@ button.acpill:disabled{cursor:default}
 .acfork .hico{width:13px;height:13px}
 .acgrp:hover .acfork{opacity:1}
 .acfork:hover{color:var(--accent)}
+.acpush{color:var(--ink);border-color:var(--accent)}
+/* what the last push said: a line a repo, pushed in the ok colour, skipped dim, failed red */
+.acpushed{margin:0 0 var(--s3);font:12px/1.5 ui-monospace,Menlo,monospace}
+.acpushed .ok{color:var(--ok)}
+.acpushed .skip{color:var(--dim)}
+.acpushed .fail{color:var(--red)}

package/src/serve/hub-app/admin-svc.ts

@@ -16,7 +16,7 @@ export class AdminSvc {
     /** the colours the preview keeps while a picker moves, so a drag draws a
      *  few icons, not one per frame; null follows the repo's colours */
     held: Identity | null = null
-    /** the repo has no png mark, or it would not draw: the app wears the default icon */
+    /** the repo has no mark, or it would not draw: the app wears the default icon */
     noIcon = false
     private rest: ReturnType<typeof setTimeout> | null = null
 

package/src/serve/hub-app/admin-view.tsx

@@ -27,7 +27,7 @@ const IdentityBox = observer(({ app }: { app: RepoSt }) => {
             <div className="adicon">
                 <img src={a.previewSrc} alt={`${name} app icon`} width={128} height={128} hidden={a.noIcon}
                     onLoad={() => a.previewLoaded()} onError={() => a.previewFailed()} />
-                {a.noIcon ? <span className="dim">no png mark (.shipkit/identity/icon.png, public/logo.png or public/favicon.png): its app wears the default icon</span> : null}
+                {a.noIcon ? <span className="dim">no mark (.shipkit/identity/icon.png or icon.svg, public/logo.png or public/favicon.png): its app wears the default icon</span> : null}
             </div>
             <div className="adtext">
                 <b>identity</b>

package/src/serve/hub-app/hash-route.ts

@@ -36,7 +36,7 @@ export type HashSel =
     /** the checks one owner ships: shipkit's, or the repo's own */
     | { t: 'checks'; from: CheckOwner }
     /** the review cards, `id` the open one, null for the first the list shows */
-    | { t: 'review'; id: string | null }
+    | { t: 'review'; id: string | null; q?: string }
     /** a trailer's cuts, played with their notes: a trailer folder and one of its cuts, null for the first; the note
      *  open on it, and the notes filter when it is not the page's default (all) */
     | { t: 'trailer'; trailer: string | null; cut: string | null; note?: string | null; filter?: 'open' | 'all' | null }
@@ -55,6 +55,8 @@ export type ParsedHash = {
     /** a trailer address only: the note open, the notes filter */
     note?: string
     filter?: 'open' | 'all'
+    /** a review address only: its view and list filters, as `view=1&subject=place` */
+    q?: string
 }
 
 const ITEM = 'item:'
@@ -91,7 +93,8 @@ export function hashFor(sel: HashSel | null): string | null {
         case 'git': return GIT
         case 'when': return WHEN
         case 'checks': return `${CHECKS}${sel.from}`
-        case 'review': return sel.id == null ? REVIEW : `${REVIEW}:${sel.id}`
+        // page:review:<id>?view=1&subject=place, the query only when it says something
+        case 'review': return `${sel.id == null ? REVIEW : `${REVIEW}:${sel.id}`}${sel.q ? `?${sel.q}` : ''}`
         case 'trailer': {
             // page:trailer:<trailer>/<cut>/<note>?filter=all, each part only when it says something
             const note = sel.trailer != null && sel.note ? `/${sel.cut ?? ''}/${sel.note}` : sel.cut == null ? '' : `/${sel.cut}`
@@ -111,7 +114,12 @@ export function parseHash(raw: string): ParsedHash {
     if (raw === PLAN) return { kind: 'plan', col: null, id: '', tools: null }
     if (raw === GIT) return { kind: 'git', col: null, id: '', tools: null }
     if (raw === WHEN) return { kind: 'when', col: null, id: '', tools: null }
-    if (raw === REVIEW || raw.startsWith(`${REVIEW}:`)) return { kind: 'review', col: null, id: raw.slice(REVIEW.length + 1), tools: null }
+    if (raw === REVIEW || raw.startsWith(`${REVIEW}:`) || raw.startsWith(`${REVIEW}?`)) {
+        const qi = raw.indexOf('?')
+        const path = qi === -1 ? raw : raw.slice(0, qi)
+        const q = qi === -1 ? '' : raw.slice(qi + 1)
+        return { kind: 'review', col: null, id: path.slice(REVIEW.length + 1), tools: null, ...(q ? { q } : {}) }
+    }
     // the trailer folder rides in `col`, its cut in `id`
     if (raw === TRAILER || raw.startsWith(`${TRAILER}:`) || raw.startsWith(`${TRAILER}?`)) {
         const qi = raw.indexOf('?')
@@ -173,7 +181,7 @@ export function selOf(p: ParsedHash): HashSel | null {
         case 'git': return { t: 'git' }
         case 'when': return { t: 'when' }
         case 'checks': return { t: 'checks', from: p.id as CheckOwner }
-        case 'review': return { t: 'review', id: p.id === '' ? null : p.id }
+        case 'review': return { t: 'review', id: p.id === '' ? null : p.id, ...(p.q ? { q: p.q } : {}) }
         case 'trailer': return { t: 'trailer', trailer: p.col, cut: p.id === '' ? null : p.id, ...(p.note ? { note: p.note } : {}), ...(p.filter ? { filter: p.filter } : {}) }
     }
 }

package/src/serve/hub-app/home-st.ts

@@ -159,9 +159,15 @@ export class HomeSt {
         return r
     }
 
+    /** the page is the embed page: one repo's page in another tool's frame (embed.ts) */
+    get embedded(): boolean {
+        return this.base !== undefined
+    }
+
     boot(): void {
         this.machine?.boot()
-        this.dock.boot()
+        // the embed page shows one repo's page alone: no dock, so no request for the house's runs
+        if (this.base === undefined) this.dock.boot()
         this.disposers.push(reaction(() => this.title, (t) => { document.title = t }, { fireImmediately: true }))
         // back, forward, a pasted link and a hand edited hash all arrive
         // here; fromUrl is idempotent, so the two events firing together

package/src/serve/hub-app/home-strip.tsx

@@ -256,7 +256,7 @@ const downCard = (m: MachineSt): Card[] => {
 
 /** what is wrong with the machine itself, one card each: the machine not
  *  answering, a crashed child of pm, a crashed global process (its switch
- *  starts it again), a failed poll. While pm is silent its last answer says
+ *  starts it again), a failed poll, the last good code running. While pm is silent its last answer says
  *  nothing here */
 const machineCards = (m: MachineSt): Card[] => {
     const pm = m.pmDown !== '' ? null : m.pm
@@ -265,6 +265,8 @@ const machineCards = (m: MachineSt): Card[] => {
         ...(pm?.children ?? []).filter((c) => c.status === 'crashed' || c.status === 'down').map((c): Card => ({ key: `child:${c.id}`, tone: 'red', head: `${c.id} ${STATUS_WORD[c.status]}`, body: c.note ?? c.tail.at(-1) ?? '' })),
         ...(pm?.resources ?? []).filter((r) => r.status === 'crashed').map((r): Card => ({ key: `res:${r.id}`, tone: 'red', head: 'crashed', body: <ResourceChip m={m} r={r} /> })),
         ...(m.error !== '' ? [{ key: 'poll', tone: 'red' as const, body: m.error }] : []),
+        // the tree fails to load and the machine runs its last good code (core/last-good.ts)
+        ...(m.data?.held != null ? [{ key: 'held', tone: 'warn' as const, head: 'last good code', body: m.data.held }] : []),
     ]
 }
 

package/src/serve/hub-app/hub.css

@@ -20,6 +20,8 @@
  --k1:#8ca8c7;--k2:#a892c9;--k3:#6fb0b8;--k4:#c792b4;--k5:#9198a1;--k6:#8f95cf;
  /* the review section's own hue: the one row of the tree meant to be seen first */
  --review:#e879d4;
+ /* a wiki page's refs (wikis-view.tsx): read on demand, loaded with the page */
+ --ref-lazy:#e8984a;--ref-eager:#6fa8f0;
  --wash:rgba(107,143,179,.15);--wash2:rgba(107,143,179,.11);--hair:rgba(107,143,179,.5);
  --errbg:#2a1a1a;--errline:#4a2c2c;--errink:#e3bebe;
  /* a running thing's wash, the green twin of errbg and errline */
@@ -39,6 +41,7 @@
  --ground:#e3ede6;--groundline:#c6d6cb;--tag:#eef2f6;
  --k1:#3f6690;--k2:#7055a3;--k3:#2b7c86;--k4:#a34e80;--k5:#5d646d;--k6:#4f56a8;
  --review:#c0279d;
+ --ref-lazy:#b8600c;--ref-eager:#1f5fc8;
  --wash:rgba(59,104,150,.12);--wash2:rgba(59,104,150,.08);--hair:rgba(59,104,150,.45);
  --errbg:#fbe9e8;--errline:#efc4c2;--errink:#8a2520;
  --okbg:#e6f3eb;--okline:#9ccdaf}
@@ -271,7 +274,8 @@ kbd{background:var(--panel2);border:1px solid var(--line);border-radius:4px;padd
  background:conic-gradient(var(--chk1) 90deg,var(--chk2) 0 180deg,var(--chk1) 0 270deg,var(--chk2) 0) 0/34px 34px}
 .stage img.roll{max-width:100%;max-height:100%;object-fit:contain;filter:drop-shadow(0 6px 20px var(--shadow));z-index:5;position:relative}
 .stage .ph,.stagewrap .ph{color:var(--dim)}
-.stagewrap{flex:1;min-height:0;overflow-y:auto;display:flex;align-items:flex-start;justify-content:center;padding:var(--s4)}
+/* every page card of a repo sits in this column, read from the left, never centred */
+.stagewrap{flex:1;min-height:0;overflow-y:auto;display:flex;align-items:flex-start;justify-content:flex-start;padding:var(--s4)}
 .stageaud{display:flex;flex-direction:column;align-items:center;gap:var(--s3);font-size:48px;padding:var(--s4)}
 .stageaud audio{width:min(480px,80vw)}
 
@@ -703,6 +707,39 @@ a.tok{color:var(--accent)}
 .gvframe{flex:1;min-height:0;position:relative;display:flex;border:1px solid var(--line);border-radius:3px;background:var(--bg)}
 .gvwait{position:absolute;inset:0;display:flex;align-items:center;justify-content:center;gap:var(--s2);font-size:12px;color:var(--dim)}
 .graphview iframe{position:relative;flex:1;min-height:0;width:100%;border:0;background:transparent}
+/* the graph and its preview panel (wikis-view.tsx) */
+.gvbody{flex:1;min-height:0}
+.gvbody .gvframe{height:100%}
+/* the wiki's search bar, its hits dropped under it over the graph */
+.wsearch{position:relative;flex:0 1 360px;min-width:160px;display:flex}
+.wsearch input{flex:1;min-width:0;height:22px;background:var(--bg);color:var(--ink);border:1px solid var(--line);border-radius:999px;padding:0 var(--s3);font:inherit;font-size:12px}
+.wsearch input:focus{outline:none;border-color:var(--accent)}
+.wslist{position:absolute;top:calc(100% + 4px);left:0;z-index:30;width:min(560px,80vw);max-height:60vh;overflow-y:auto;padding:var(--s1) 0;background:var(--panel);border:1px solid var(--line);border-radius:6px;box-shadow:0 6px 20px var(--shadow)}
+.wshit{padding:var(--s1) var(--s3);cursor:pointer}
+.wshit.on,.wshit:hover{background:var(--sel)}
+.wshead{display:flex;align-items:baseline;gap:var(--s2);min-width:0}
+.wshead b{flex:none;font-size:12.5px}
+.wspath{min-width:0;color:var(--dim);font:11px/1.4 ui-monospace,Menlo,monospace;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.wssnip{color:var(--dim);font-size:11.5px;line-height:1.4;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}
+.wsnone{padding:var(--s1) var(--s3);color:var(--dim);font-size:12px}
+/* the page open beside the graph */
+.wprev{height:100%;display:flex;flex-direction:column;min-width:0;background:var(--panel);border:1px solid var(--line);border-radius:3px}
+.wphead{flex:none;display:flex;align-items:center;gap:var(--s2);padding:var(--s2) var(--s3);border-bottom:1px solid var(--line);min-width:0}
+.wptitle{flex:0 1 auto;min-width:0;font-size:13px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.wphead .wspath{flex:1}
+.wpplace{flex:none}
+.wpplace button{padding:0 var(--s1)}
+.wpplace .hico{width:14px;height:14px}
+.wpbtn{flex:none;display:inline-flex;align-items:center;gap:var(--s1);height:22px;padding:0 var(--s2);border:1px solid var(--line);border-radius:999px;color:var(--dim);font-size:11.5px;text-decoration:none;background:transparent;cursor:pointer}
+.wpbtn:hover{color:var(--ink);border-color:var(--accent)}
+.wpbtn .hico{width:13px;height:13px}
+.wpclose{flex:none;padding:0 var(--s2);font-size:14px;line-height:1.2}
+/* the refs of a page: on demand (→, a link, a path) orange, loaded with it (@) blue and bold */
+.wpbody a[data-ref=lazy]{color:var(--ref-lazy)}
+.wpbody a[data-ref=lazy] code{color:var(--ref-lazy)}
+.wpbody a[data-ref=eager]{color:var(--ref-eager);font-weight:700}
+.wpbody{flex:1;min-height:0;overflow-y:auto;padding:var(--s2) var(--s4) var(--s4)}
+.wpbody a[data-wiki]{text-decoration:underline;text-decoration-style:dotted;text-underline-offset:2px;cursor:pointer}
 
 /* ── comfy item view (comfy-ts's own panel fills the stage) ── */
 .comfyview{flex:1;min-height:0;display:flex;flex-direction:column;gap:var(--s2);padding:var(--s3) var(--s4) var(--s4)}

package/src/serve/hub-app/icons.tsx

@@ -44,6 +44,12 @@ export const ICON = {
     sun: 'M10 6.5a3.5 3.5 0 1 0 .01 0M10 2v2M10 16v2M2 10h2M16 10h2M4.3 4.3l1.4 1.4M14.3 14.3l1.4 1.4M4.3 15.7l1.4-1.4M14.3 5.7l1.4-1.4',
     moon: 'M15.5 12.5A6.5 6.5 0 0 1 7.5 4.5a6.5 6.5 0 1 0 8 8z',
     auto: 'M10 3a7 7 0 1 0 .01 0M10 3v14M10 5.5h4M10 8.5h6M10 11.5h6M10 14.5h4',
+    // where the wiki preview sits: a frame with its panel's edge
+    paneLeft: 'M3 4h14v12H3zM8 4v12M4.5 7h2M4.5 9.5h2',
+    paneRight: 'M3 4h14v12H3zM12 4v12M13.5 7h2M13.5 9.5h2',
+    paneBottom: 'M3 4h14v12H3zM3 11h14M6 13.5h8',
+    copy: 'M7 7h9v10H7zM4 13V3h9',
+    editor: 'M13 3l4 3v8l-4 3-7-6 7-5zM3 7.5l3 2.5-3 2.5',
     // the project list's fold: a panel with its rail marked
     rail: 'M3 4h14v12H3zM7.5 4v12',
     // a process's own switches on the overview

package/src/serve/hub-app/layout-st.ts

@@ -16,10 +16,10 @@ export const LIST: Bounds = { key: 'hub:list-width', min: 140, max: 360, def: 20
 export const SIDEBAR: Bounds = { key: 'hub:sidebar-width', min: 150, max: 640, def: 330 }
 
 /** the rail's icon sizes, in px: the foot's button cycles them */
-export const RAIL_ICONS = { s: 18, m: 24, l: 32 } as const
+export const RAIL_ICONS = { s: 24, m: 32, l: 40 } as const
 export type RailIcon = keyof typeof RAIL_ICONS
 /** the rail is its icon and this much on each side */
-const RAIL_PAD = 13
+const RAIL_PAD = 6
 /** the project list folded: its icons only, a row's name in its hover card */
 export const railPx = (size: RailIcon): number => RAIL_ICONS[size] + 2 * RAIL_PAD
 const RAIL_KEY = 'hub:list-rail'

package/src/serve/hub-app/machine-st.ts

@@ -110,7 +110,7 @@ export class MachineSt {
      *  `shipkit global-processes` prints) */
     get processGroups(): ProcessGroup[] {
         const silent = { ...(this.down === '' ? {} : { [this.downWho]: this.down }), ...(this.pmDown === '' ? {} : { pm: this.pmDown }) }
-        return processGroups(this.pm, this.st.projects.list.map((p) => p.name), { daemonVersion: this.data?.version ?? null, silent })
+        return processGroups(this.pm, this.st.projects.list.map((p) => p.name), { daemonVersion: this.data?.version ?? null, daemonHeld: this.data?.held ?? null, silent })
     }
 
     resource(id: string): ResourceView | null {

package/src/serve/hub-app/md.ts

@@ -70,3 +70,35 @@ export const renderReadme = (src: string, fileUrl: (rel: string) => string): str
         },
         exclusiveFilter: (frame) => frame.tag === 'img' && (frame.attribs.src ?? '') === '',
     })
+
+/** a wiki page in the wikis page's preview: the card allowlist, and every ref
+ *  the server resolved (`links`, token → node, graph-pages.ts) as an anchor
+ *  that opens that page in place instead of a new tab, marked by its kind so
+ *  the sheet tells them apart: `@` loads with the page (eager), `→`, a link or
+ *  a path in a code span is read on demand (lazy, written `→ path` here
+ *  whatever the page wrote) */
+export const renderWikiPage = (src: string, links: Record<string, string>): string => {
+    const to = (t: string, eager = false): string | null => (links[t] == null ? null : `#wiki${eager ? '-eager' : ''}:${encodeURIComponent(links[t]!)}`)
+    // fences stay as written: a ref in a code block is an example, not a link
+    const linked = src.split(/(^```[\s\S]*?^```\s*$)/m).map((part, i) => i % 2 === 1 ? part : part
+        .replace(/\]\(([^)\s:]+\.md)\)/g, (m, t: string) => (to(t) == null ? m : `](${to(t)})`))
+        .replace(/→(\s*)([\w][\w./-]*\.md)\b/g, (m, sp: string, t: string) => (to(t) == null ? m : `→${sp}[${t}](${to(t)})`))
+        .replace(/(^|[\s(])@((?:\.{1,2}\/)*[\w][\w./-]*\.md)/gm, (m, pre: string, t: string) => (to(t, true) == null ? m : `${pre}[@${t}](${to(t, true)})`))
+        // a code span that is exactly a page's path: a lazy ref, its arrow added unless the page wrote one
+        .replace(/(→\s*)?(?<!\[)`([\w.][\w./-]*\.md)`/g, (m, arrow: string | undefined, t: string) => (to(t) == null ? m : `${arrow ?? '→ '}[\`${t}\`](${to(t)})`)),
+    ).join('')
+    return sanitizeHtml(marked.parse(linked) as string, {
+        allowedTags: [...CARD_TAGS, 'h5', 'h6', 'del'],
+        allowedAttributes: { a: ['href', 'target', 'rel', 'data-wiki', 'data-ref'] },
+        allowedSchemes: ['http', 'https'],
+        allowProtocolRelative: false,
+        transformTags: {
+            a: (tagName, attribs): sanitizeHtml.Tag => {
+                const href = attribs.href ?? ''
+                const ref = /^#wiki(-eager)?:(.*)$/.exec(href)
+                if (ref != null) return { tagName, attribs: { href, 'data-wiki': decodeURIComponent(ref[2]!), 'data-ref': ref[1] != null ? 'eager' : 'lazy' } }
+                return { tagName, attribs: { ...attribs, target: '_blank', rel: 'noreferrer' } }
+            },
+        },
+    })
+}

package/src/serve/hub-app/project-list.css

@@ -69,8 +69,8 @@
 .pgi.h5{--c:var(--k5)}
 .pgi.h6{--c:var(--k6)}
 /* the row says three things and no more (projects-svc faceOf) */
-/* closed in VS Code: the icon and the name dim, the badge does not */
-.pjrow.dim img,.pjrow.dim .pgi,.pjrow.dim .pjname{opacity:.5}
+/* closed in VS Code: the name dims, never the icon (the icon is how a repo is found, and the rail has no name) */
+.pjrow.dim .pjname{opacity:.5}
 /* ⌘1 to ⌘9 select the first nine rows (keys.ts): the hint sits at the row's end */
 .pjkey{flex:none;font:10px/1 ui-monospace,Menlo,monospace;color:var(--dim);opacity:.6;background:none;border:0;padding:0}
 .pjrow:hover .pjkey,.pjrow.cur .pjkey,.pjpl:hover .pjkey,.pjpl.cur .pjkey{opacity:1}
@@ -128,12 +128,14 @@
 .pjlist.rail .pjname,.pjlist.rail .pjkey,.pjlist.rail .pjstep,.pjlist.rail .pgsortl,.pjlist.rail .pjarow span,.pjlist.rail .pgerr{display:none}
 .pjlist.rail .pjrow,.pjlist.rail .pjpl,.pjlist.rail .pjarow{justify-content:center;padding:0}
 /* the rail's icon size (layout-st RAIL_ICONS, the foot's S M L button): the repo icons and the row under them grow */
-.pjlist.rail .pjrow{height:calc(var(--ri,18px) + 10px)}
-.pjlist.rail .pjrow img,.pjlist.rail .pjrow .pgi{width:var(--ri,18px);height:var(--ri,18px)}
-.pjlist.rail .pjrow .pgi{font-size:calc(var(--ri,18px) * .55)}
+.pjlist.rail .pjrow{height:calc(var(--ri,24px) + 6px)}
+.pjlist.rail .pjrow img,.pjlist.rail .pjrow .pgi{width:var(--ri,24px);height:var(--ri,24px);border-radius:6px}
+.pjlist.rail .pjrow .pgi{font-size:calc(var(--ri,24px) * .5)}
+/* the app icon is a rounded plate already (core/app-icon.ts) */
+.pjlist.rail .pjrow img.pjapp{border-radius:0}
 .pjsize{font:600 10px/1 ui-monospace,Menlo,monospace}
-.pjlist.rail .pga{position:absolute;top:var(--s0);left:50%;margin-left:var(--s1);min-width:14px;height:14px;padding:0 var(--s0);border-radius:7px;font-size:9px;line-height:14px}
-.pjlist.rail .pgd,.pjlist.rail .pgw{position:absolute;bottom:var(--s1);left:50%;margin-left:var(--s1)}
+.pjlist.rail .pga{position:absolute;top:0;right:calc(50% - var(--ri,24px) / 2 - 4px);min-width:14px;height:14px;padding:0 var(--s0);border-radius:7px;font-size:9px;line-height:14px}
+.pjlist.rail .pgd,.pjlist.rail .pgw{position:absolute;bottom:var(--s0);right:calc(50% - var(--ri,24px) / 2 - 2px)}
 .pjlist.rail .pjfoot{flex-direction:column;height:auto;padding:var(--s1) 0}
 .pjlist.rail .pjfoot button{justify-content:center;width:28px;padding:0}
 .pjlist.rail .pjarbtn span{display:none}

package/src/serve/hub-app/project-list.tsx

@@ -3,7 +3,7 @@
 // the shown repo's row marked in its identity colour. Its width is the
 // panel the page gives it (hub-app.tsx, react-resizable-panels). A row says
 // three things and no more (faceOf): the open asks as its one badge, a dim
-// icon while VS Code does not have the folder open, a thin edge breathing
+// name (never the icon) while VS Code does not have the folder open, a thin edge breathing
 // while Claude sessions run in it; on the home, a dot while its hub starts
 // or crashed and a mark while a global process it uses is off. Everything
 // else is the hover card, placed by floating-ui beside the row. A click
@@ -72,6 +72,7 @@ export const Row = observer(({ app, p, i }: { app: ListHost; p: Project; i: numb
     const warn = s.warnOf(p.name)
     // the shown repo's row is marked in its own colour
     const mark = cur ? (idVars(s.identityOf(p.name)) as CSSProperties) : undefined
+    // folded, the rail wears the repo's app icon: its mark on its identity plate
     return (
         <>
             <button ref={f.refs.setReference} className={cls} aria-label={p.name} style={mark} draggable
@@ -95,7 +96,9 @@ export const Row = observer(({ app, p, i }: { app: ListHost; p: Project; i: numb
                     },
                     onDragEnd: () => s.dragEnd(),
                 })}>
-                <Face p={p} px={ROW_ICON} />
+                {app.layout?.listRail === true && p.appIcon != null
+                    ? <img className="pjapp" src={p.appIcon} alt="" width={ROW_ICON} height={ROW_ICON} draggable={false} />
+                    : <Face p={p} px={ROW_ICON} />}
                 <span className="pjname">{p.name}</span>
                 {face.badge != null ? <b className="pga">{face.badge}</b> : null}
                 {face.busy ? <i className="pgs" /> : null}

package/src/serve/hub-app/projects-svc.ts

@@ -134,8 +134,9 @@ export function sortNames(list: Project[], mode: SortMode): string[] {
 export type HubDot = 'starting' | 'crashed' | null
 
 /** what the icon face shows, and nothing more: at most ONE badge (the open
- *  asks, the only fact that needs a human's hands), dim while VS Code does
- *  not have the folder open, and a pulsing edge while Claude sessions run */
+ *  asks, the only fact that needs a human's hands), a dim name while VS Code
+ *  does not have the folder open (the icon stays whole), and a pulsing edge
+ *  while Claude sessions run */
 export type Face = { badge: number | null; dim: boolean; busy: boolean }
 export const faceOf = (p: Project): Face => ({
     badge: p.asks > 0 ? p.asks : null,