rvlib-shipkit 0.11.0 → 0.13.0

package/src/rules/SK007-github-visibility.ts

@@ -0,0 +1,63 @@
+// SK007 — github visibility tripwire (meta/contracts.md pre-public gate).
+// `repo.config.ts visibility: 'private' | 'public'` (absent = 'private')
+// states the INTENT; gh states the FACT; a mismatch in either direction is
+// red — public-while-declared-private is the leak case,
+// private-while-declared-public is a stale config lying to agents. The
+// TARGET repo is resolved explicitly from the remote url (preferring
+// `github`, then `origin`, then the first remote) and passed to gh — gh's
+// own base-repo resolution prefers `upstream`, which in a fork-shaped
+// checkout would confidently validate the WRONG repository. Flipping a
+// repo public stays a human act behind the pre-public audit; this rule is
+// the standing tripwire if it ever happens out of band. Clean passes cache
+// 7d, keyed on the declared value (a flip re-probes immediately); every
+// unverifiable path (no git, no remote, non-github remote, gh missing or
+// erroring, unreadable answer) is a loud skip — an UNKNOWN, never red,
+// never cached.
+import type { Rule } from './rule.ts'
+
+export const githubVisibility: Rule = {
+    id: 'SK007',
+    title: 'github visibility',
+    owner: 'meta/contracts.md',
+    ttl: '7d',
+    cacheKey: (env) => env.config.visibility ?? 'private',
+    lint: async (t, env) => {
+        const declared = env.config.visibility ?? 'private'
+        const skip = (why: string): void => void t.lines.push({ kind: 'skip', text: `github visibility unverified — ${why} (declared: ${declared})` })
+        const firstLine = (s: string): string => s.trim().split('\n').find((l) => l.trim() !== '')?.slice(0, 120) ?? ''
+
+        const remotes = await t.exec(['git', 'remote'], { cwd: env.root })
+        if (remotes.code !== 0) return skip(`git says: ${firstLine(remotes.out) || `exit ${remotes.code}`}`)
+        const names = remotes.out.trim().split('\n').filter((l) => l !== '')
+        if (names.length === 0) return skip('no git remote')
+        // his repos name it `github`, not `origin` (field catch 2026-07-26)
+        const pick = ['github', 'origin'].find((n) => names.includes(n)) ?? names[0]!
+        const url = await t.exec(['git', 'remote', 'get-url', pick], { cwd: env.root })
+        if (url.code !== 0) return skip(`git says: ${firstLine(url.out)}`)
+        const m = url.out.match(/github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\s*$/m)
+        if (m == null) return skip(`remote '${pick}' is not github (${firstLine(url.out)})`)
+        const target = m[1]!
+
+        const r = await t.exec(['gh', 'repo', 'view', target, '--json', 'isPrivate,nameWithOwner'], { cwd: env.root, timeoutMs: 30_000 })
+        if (r.code !== 0) return skip(`gh failed (${firstLine(r.out)})`)
+        // gh mixes stderr chatter (release notices, SSO warnings) into the
+        // captured output — carve the JSON object out before parsing, and an
+        // unreadable answer stays an UNKNOWN, never a FAIL
+        const start = r.out.indexOf('{')
+        const end = r.out.lastIndexOf('}')
+        let parsed: { isPrivate?: boolean; nameWithOwner?: string }
+        try {
+            if (start === -1 || end < start) throw new Error('no JSON object in output')
+            parsed = JSON.parse(r.out.slice(start, end + 1)) as typeof parsed
+        } catch {
+            return skip(`gh answer unreadable (${firstLine(r.out)})`)
+        }
+        const actual = parsed.isPrivate === true ? 'private' : 'public'
+        const who = parsed.nameWithOwner ?? target
+        if (actual === declared) t.ok(`github ${who} is ${actual} — matches repo.config visibility`)
+        else if (actual === 'public')
+            t.fail(`github ${who} is PUBLIC but repo.config declares '${declared}' — the leak case; make it private again or run the pre-public gate and declare visibility: 'public'`)
+        else
+            t.fail(`github ${who} is private but repo.config declares 'public' — stale config lying to agents; fix the declaration`)
+    },
+}

package/src/rules/rule-registry.ts

@@ -0,0 +1,32 @@
+// THE rule registry — single source of every SK rule. `shipkit check` runs
+// them, `shipkit rules` lists them, fix pointers and wiki pages name their
+// ids. A duplicate or malformed id throws at import time: every surface
+// that loads rules dies loud rather than run with an ambiguous registry.
+import type { Rule } from './rule.ts'
+import { packageJsonShape } from './SK001-package-json-shape.ts'
+import { contractsFulfillness } from './SK002-contracts-fulfillness.ts'
+import { claudeMdShape } from './SK003-claude-md-shape.ts'
+import { gitignorePolicy } from './SK004-gitignore-policy.ts'
+import { rvlibVersions } from './SK005-rvlib-versions.ts'
+import { npmPublishSafety } from './SK006-npm-publish-safety.ts'
+import { githubVisibility } from './SK007-github-visibility.ts'
+
+export const RULES: readonly Rule[] = [
+    packageJsonShape,
+    contractsFulfillness,
+    claudeMdShape,
+    gitignorePolicy,
+    rvlibVersions,
+    npmPublishSafety,
+    githubVisibility,
+]
+
+const seen = new Set<string>()
+for (const r of RULES) {
+    if (!/^SK\d{3}$/.test(r.id)) throw new Error(`rule-registry: bad id '${r.id}' — rules are SK### (3 digits, never reused)`)
+    if (seen.has(r.id)) throw new Error(`rule-registry: duplicate id ${r.id}`)
+    if (r.owner === '') throw new Error(`rule-registry: ${r.id} has no owner page`)
+    seen.add(r.id)
+}
+
+export const ruleById = (id: string): Rule | undefined => RULES.find((r) => r.id === id)

package/src/rules/rule.ts

@@ -0,0 +1,62 @@
+// Rule — one machine-enforced invariant with a stable id. One module per
+// rule (`src/rules/SK###-<slug>.ts`), registered in rule-registry.ts; ids
+// are never reused or renumbered. `shipkit check` runs every rule's lint;
+// a rule may also carry an idempotent fix() (the `check --fix` runner).
+// Every wire line a rule emits is tagged `[SK###]` so output is greppable
+// by rule and a fix pointer names the rule that can repair it.
+import type { CheckCtx } from '../core/check-ctx.ts'
+import type { Line } from '../core/wire.ts'
+import type { RepoConfig } from '../repo-config.ts'
+
+export type RuleEnv = { root: string; config: RepoConfig }
+
+export type FixResult = { changed: boolean; summary: string }
+
+export type Rule = {
+    /** stable `SK` + 3 digits — never reused, never renumbered (registry throws) */
+    id: string
+    /** check-suite display name — stable: the check name in STATUS.md, the TUI row, and the suite cache */
+    title: string
+    /** wiki page owning the invariant — the run-check framework appends `docsBase + owner`
+     *  as the fix: pointer whenever a failing/warning lint attached none */
+    owner: string
+    /** clean-pass cache duration (check-suite TTL, e.g. '24h') — for rules that
+     *  probe the network; skip/WARN/FAIL runs are never cached */
+    ttl?: string
+    /** cache-identity contribution for TTL'd rules whose verdict depends on
+     *  config — a changed key busts the cache instantly instead of replaying
+     *  a stale assertion for the TTL */
+    cacheKey?: (env: RuleEnv) => string
+    lint: (t: CheckCtx, env: RuleEnv) => void | Promise<void>
+    /** idempotent auto-repair; `check --fix` applies it then re-lints — never interactive */
+    fix?: (env: RuleEnv) => FixResult | Promise<FixResult>
+}
+
+// THE one way to run a rule's lint (check suite + the --fix runner): a
+// throwing lint still fails with its id, a failing/warning run always
+// carries at least one fix: pointer (the lint's own precise ones win, else
+// docsBase + the rule's owner page), and every line gets tagged.
+export async function runRuleLint(rule: Rule, t: CheckCtx, env: RuleEnv): Promise<void> {
+    try {
+        await rule.lint(t, env)
+    } catch (e) {
+        t.fail(`${rule.title} lint errored (${String(e).slice(0, 200)}) — network down, or a bug in this rule`)
+    }
+    if ((t.failed || t.warned) && !t.lines.some((l) => l.kind === 'fix-fail' || l.kind === 'fix-warn'))
+        t.lines.push({ kind: t.failed ? 'fix-fail' : 'fix-warn', text: `${env.config.docsBase ?? ''}${rule.owner}` })
+    t.lines = tagRuleLines(rule, t.lines)
+}
+
+// tag every severity line with the rule id; fix pointers of a fixable rule
+// advertise the autofix. Idempotent — already-tagged lines pass through
+// (cached suite replays re-enter here).
+export function tagRuleLines(rule: Rule, lines: Line[]): Line[] {
+    return lines.map((l) => {
+        if (l.kind === 'fix-warn' || l.kind === 'fix-fail')
+            return rule.fix == null || l.text.includes('--fix ')
+                ? l
+                : { ...l, text: `${l.text} · autofix: shipkit check --fix ${rule.id}` }
+        if (l.kind === 'note') return l
+        return l.text.startsWith(`[${rule.id}]`) ? l : { ...l, text: `[${rule.id}] ${l.text}` }
+    })
+}

package/src/rules/run-fix.ts

@@ -0,0 +1,57 @@
+// `shipkit check --fix [SK### …]` — apply rule autofixes, then re-lint and
+// show the real end state. Never runs under ci (the gate stays pure), never
+// caches (a fixer must see reality). No ids = every fixable rule; a
+// requested id that is unknown or unfixable fails loud instead of silently
+// narrowing.
+import { CheckCtx } from '../core/check-ctx.ts'
+import { formatLine } from '../core/wire.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+import { RULES, ruleById } from './rule-registry.ts'
+import { runRuleLint, type RuleEnv } from './rule.ts'
+
+export type FixOpts = {
+    ids?: string[]
+    print?: (line: string) => void
+}
+
+export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
+    const print = o.print ?? ((l: string) => console.log(l))
+    const config = await loadRepoConfig(root)
+    const env: RuleEnv = { root, config }
+    const color = process.stdout.isTTY && process.env.NO_COLOR == null
+
+    let targets = RULES.filter((r) => r.fix != null)
+    if (o.ids != null && o.ids.length > 0) {
+        for (const id of o.ids) {
+            const r = ruleById(id)
+            if (r == null) { print(`FAIL: unknown rule '${id}' — see: shipkit rules`); return 1 }
+            if (r.fix == null) { print(`FAIL: [${id}] has no autofix — fix by hand: ${config.docsBase ?? ''}${r.owner}`); return 1 }
+        }
+        const wanted = new Set(o.ids)
+        targets = targets.filter((r) => wanted.has(r.id))
+    }
+
+    let exit = 0
+    for (const rule of targets) {
+        const before = new CheckCtx(new Map())
+        await runRuleLint(rule, before, env)
+        if (!before.failed && !before.warned) {
+            print(`ok: [${rule.id}] already clean — nothing to fix`)
+            continue
+        }
+        const f = await rule.fix!(env)
+        // an unchanged fix is the DESIGNED outcome for judgment findings —
+        // a note, not a warning
+        print(f.changed ? `ok: [${rule.id}] fixed: ${f.summary}` : `[${rule.id}] fix changed nothing — ${f.summary}`)
+        const after = new CheckCtx(new Map())
+        await runRuleLint(rule, after, env)
+        // the fix already ran: advertising it again on surviving findings
+        // would send an agent in a loop
+        for (const l of after.lines) print(formatLine({ ...l, text: l.text.replace(/ · autofix: shipkit check --fix SK\d{3}$/, '') }, color))
+        if (after.failed) exit = 1
+    }
+    const unfixable = RULES.filter((r) => r.fix == null).length
+    if (unfixable > 0 && (o.ids == null || o.ids.length === 0))
+        print(`${unfixable} rule(s) have no autofix — run \`shipkit check\` for the full repo state`)
+    return exit
+}

package/src/serve/hub-app/col-card.tsx

@@ -0,0 +1,192 @@
+// Collection views: the per-collection card grid (ColGrid), the item card
+// (asks · creds · posts), the graph item view (GraphView — embeds the
+// /graph/* page itself), and the health/status card with the streaming
+// check runner. Every verb posts to /api/act/* and lands in a git-tracked
+// truth file; the truth chip names the file the item IS (on disagreement
+// the file wins).
+import { runInAction } from 'mobx'
+import { observer } from 'mobx-react-lite'
+import type { HubSt } from './hub-st.ts'
+import type { ColInstance } from './hub-types.ts'
+import { renderMd } from './md.ts'
+
+// creds carry no truth file — name/service/state parse out of the instance
+const credOf = (i: ColInstance): { name: string; service: string | null; missing: boolean } => ({
+    name: i.id.replace(/^cred:/, ''),
+    service: i.text.includes(' — ') ? i.text.split(' — ').slice(1).join(' — ') : null,
+    missing: i.severity != null,
+})
+
+const CredHead = ({ cred }: { cred: ReturnType<typeof credOf> }) => (
+    <>
+        <span className="credname">{cred.name}</span>
+        <span className={`stchip ${cred.missing ? 'miss' : 'ok'}`}>{cred.missing ? 'missing' : 'present'}</span>
+    </>
+)
+
+export const ColCard = observer(({ app, col, id }: { app: HubSt; col: string; id: string }) => {
+    const c = app.cols
+    const i = c.find(col, id)
+    if (i == null) return <div className="ph">item vanished — the truth file moved on</div>
+    const askFile = col === 'asks' ? id.replace(/^ask:/, '') : null
+    const postM = col === 'posts' ? id.match(/^post:([^/]+)\/(.+?):(pick|topost|invalid|posted|rejected)$/) : null
+    const postFile = (i.file ?? '').split('/').pop() ?? ''
+    if (col === 'creds') {
+        // no remark box, no generic dump — a cred has no truth file; the
+        // copy block + steps only matter while it is MISSING
+        const cred = credOf(i)
+        return (
+            <div className="colcard">
+                <div className="back" onClick={() => app.showCol(col)}>← {c.colTitle(col)}</div>
+                <h3>
+                    <span className={`cdot ${i.severity ?? ''}`} /> <CredHead cred={cred} />
+                    {i.artifact?.url != null ? <a className="mint" href={i.artifact.url} target="_blank" rel="noreferrer">mint ↗</a> : null}
+                </h3>
+                {cred.service != null ? <div className="creddesc">{cred.service}</div> : null}
+                {/* probe FAIL + fix: pointers ride the instance md — for an
+                    ask-covered cred (no verbs, no artifact) it is the ONLY detail */}
+                {i.md != null ? <div className="md" dangerouslySetInnerHTML={{ __html: renderMd(i.md) }} /> : null}
+                {cred.missing && i.artifact?.copy != null ? (
+                    <>
+                        <code>{i.artifact.copy}</code>
+                        <div className="row"><button onClick={() => void navigator.clipboard.writeText(i.artifact!.copy!)}>copy</button></div>
+                    </>
+                ) : null}
+                {cred.missing && i.artifact?.steps != null ? <div className="row"><div>{i.artifact.steps.map((s, n) => <span key={n}>{n + 1}. {s}<br /></span>)}</div></div> : null}
+            </div>
+        )
+    }
+    return (
+        <div className="colcard">
+            <div className="back" onClick={() => app.showCol(col)}>← {c.colTitle(col)}</div>
+            <h3>
+                <span className={`cdot ${i.severity ?? ''}`} /> {i.text}
+                {i.file != null ? <span className="truth">{i.file}</span> : null}
+            </h3>
+            {i.md != null ? <div className="md" dangerouslySetInnerHTML={{ __html: renderMd(i.md) }} /> : null}
+            {i.remarks != null && i.remarks.length > 0 ? <div className="rem">{i.remarks.join('\n')}</div> : null}
+            {i.artifact?.copy != null ? (
+                <>
+                    <code>{i.artifact.copy}</code>
+                    <div className="row"><button onClick={() => void navigator.clipboard.writeText(i.artifact!.copy!)}>copy</button></div>
+                </>
+            ) : null}
+            {i.artifact?.url != null ? <div className="row"><a href={i.artifact.url} target="_blank" rel="noreferrer">mint ↗</a></div> : null}
+            {i.artifact?.steps != null ? <div className="row"><div>{i.artifact.steps.map((s, n) => <span key={n}>{n + 1}. {s}<br /></span>)}</div></div> : null}
+            {postM?.[3] === 'pick' && i.candidates != null ? i.candidates.map((cd) => (
+                <div className="cand" key={cd.id}>
+                    <div className="row"><b>{cd.label}</b><button onClick={() => void c.postPick(postM[1]!, cd.id)}>pick</button></div>
+                    <div className="candhint">{cd.hint ?? ''}</div>
+                </div>
+            )) : null}
+            {postM?.[3] === 'topost' ? (
+                <div className="row">
+                    <input placeholder="posted URL = proof" value={c.proofDraft} onChange={(e) => runInAction(() => { c.proofDraft = e.target.value })} />
+                    <button onClick={() => void c.postPosted(postM[1]!, postFile)}>posted ✓</button>
+                </div>
+            ) : null}
+            {askFile != null && i.severity != null ? (
+                <div className="row">
+                    <input placeholder="proof URL (optional)" value={c.proofDraft} onChange={(e) => runInAction(() => { c.proofDraft = e.target.value })} />
+                    <button onClick={() => void c.askDone(askFile)}>done ✓</button>
+                </div>
+            ) : null}
+            {askFile != null || postM != null ? (
+                <div className="row">
+                    <input placeholder="remark → lands in the file, agents read it" value={c.remarkDraft}
+                        onChange={(e) => runInAction(() => { c.remarkDraft = e.target.value })} />
+                    <button className="ghost" onClick={() => void c.remark(askFile != null ? { kind: 'ask', file: askFile } : { kind: 'post', channel: postM![1], file: postFile })}>remark</button>
+                </div>
+            ) : null}
+            {c.actErr !== '' ? <div className="err">✗ {c.actErr}</div> : null}
+        </div>
+    )
+})
+
+// collection view — one card per visible instance, the stage-side twin of a
+// sidebar section (his rule 2026-07-23: every section gets both views)
+export const ColGrid = observer(({ app, id }: { app: HubSt; id: string }) => {
+    const c = app.cols
+    const col = c.sidebarCols.find((x) => x.id === id)
+    if (col == null) return <div className="stagewrap"><div className="ph">collection vanished — the truth moved on</div></div>
+    const items = c.visibleInstances(col)
+    return (
+        <div className="colgrid">
+            <div className="cghead">{col.title}<span className="cnt">{items.length}</span></div>
+            {items.length === 0 ? <div className="ph">{app.filter === 'red' ? 'no reds here' : app.filter === 'needs' ? 'nothing here needs you' : 'nothing here yet'}</div> : (
+                <div className="cgcards">
+                    {items.map((i) => {
+                        if (id === 'creds') {
+                            const cred = credOf(i)
+                            return (
+                                <div key={i.id} className="cgcard" onClick={() => c.select(col.id, i.id)}>
+                                    <div className="cgtop"><span className={`cdot ${i.severity ?? ''}`} /><CredHead cred={cred} /></div>
+                                    {cred.service != null ? <div className="creddesc">{cred.service}</div> : null}
+                                    {i.md != null ? <div className="md clamp" dangerouslySetInnerHTML={{ __html: renderMd(i.md) }} /> : null}
+                                    {i.artifact?.url != null ? (
+                                        <div className="credrow"><a className="mint" href={i.artifact.url} target="_blank" rel="noreferrer" onClick={(e) => e.stopPropagation()}>mint ↗</a></div>
+                                    ) : null}
+                                </div>
+                            )
+                        }
+                        return (
+                            <div key={i.id} className="cgcard" onClick={() => c.select(col.id, i.id)}>
+                                <div className="cgtop"><span className={`cdot ${i.severity ?? ''}`} /><b>{i.text}</b></div>
+                                {/* a link click opens its tab — it must not ALSO yank into the item view */}
+                                {i.md != null ? <div className="md clamp" onClick={(e) => { if ((e.target as HTMLElement).tagName === 'A') e.stopPropagation() }} dangerouslySetInnerHTML={{ __html: renderMd(i.md) }} /> : null}
+                                {i.file != null ? <span className="truth">{i.file}</span> : null}
+                                {i.remarks != null && i.remarks.length > 0 ? <div className="cgrem">{i.remarks[i.remarks.length - 1]}</div> : null}
+                            </div>
+                        )
+                    })}
+                </div>
+            )}
+        </div>
+    )
+})
+
+// graph item view — the graph ITSELF fills the stage (his order 2026-07-23:
+// "if I select a graph, I want to see it"), lint line as a slim header
+export const GraphView = observer(({ app, id }: { app: HubSt; id: string }) => {
+    const c = app.cols
+    const i = c.find('graphs', id)
+    if (i == null) return <div className="stagewrap"><div className="ph">graph vanished — the truth moved on</div></div>
+    if (i.href == null) return <div className="stagewrap"><div className="ph">this graph carries no page to embed</div></div>
+    return (
+        <div className="graphview">
+            <div className="gvhead">
+                <span className="back" onClick={() => app.showCol('graphs')}>← {c.colTitle('graphs')}</span>
+                <span className={`cdot ${i.severity ?? ''}`} />
+                <span className="gvtext">{i.text}</span>
+            </div>
+            <iframe src={i.href} title={i.text} />
+        </div>
+    )
+})
+
+const wireClass = (l: string): string => {
+    const t = l.trimStart()
+    if (t.startsWith('FAIL') || t.startsWith('✗')) return 'fail'
+    if (t.startsWith('WARN') || t.startsWith('⚠')) return 'warn'
+    if (t.startsWith('ok') || t.startsWith('✓')) return 'ok'
+    if (t.startsWith('skip') || t.startsWith('fix:') || t.startsWith('#')) return 'dim'
+    return ''
+}
+
+export const StatusCard = observer(({ app }: { app: HubSt }) => {
+    const h = app.health
+    return (
+        <div className="wrap">
+            <h1>{app.name}<small>STATUS.md</small></h1>
+            <div className="hbar">
+                <button disabled={h.running} onClick={() => void h.runCheck()}>run check</button>
+                <span className="note">{h.note !== '' ? h.note : <>shells <code>shipkit check</code>, wire lines stream in below</>}</span>
+            </div>
+            <pre>
+                {(h.statusMd ?? 'no STATUS.md yet — hit "run check" (or run: shipkit check)')
+                    .split('\n')
+                    .map((l, i) => <span key={i} className={wireClass(l)}>{l}{'\n'}</span>)}
+            </pre>
+        </div>
+    )
+})

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

@@ -0,0 +1,136 @@
+// Collections service — asks · creds · posts · health · graphs sections +
+// the act-in-place verbs. Every act hits a git-tracked truth file through
+// /api/act/*; errors come back as 400 text shown verbatim on the card.
+import { makeAutoObservable, runInAction } from 'mobx'
+import type { HubSt } from './hub-st.ts'
+import type { Col, ColInstance } from './hub-types.ts'
+
+export class ColsSvc {
+    cols: Col[] = []
+    actErr = ''
+    remarkDraft = ''
+    proofDraft = ''
+    /** user fold choices win; default = open when the section holds needs */
+    foldOverride = new Map<string, boolean>()
+    private timer: ReturnType<typeof setInterval> | null = null
+
+    constructor(private st: HubSt) {
+        makeAutoObservable<this, 'st' | 'timer'>(this, { st: false, timer: false })
+    }
+
+    start(): void {
+        void this.poll()
+        this.timer = setInterval(() => void this.poll(), 10_000)
+    }
+    dispose(): void {
+        if (this.timer != null) clearInterval(this.timer)
+    }
+
+    async poll(): Promise<void> {
+        try {
+            const r = await fetch('/api/collections.json')
+            if (!r.ok) throw new Error(await r.text())
+            const j = (await r.json()) as { collections: Col[] }
+            runInAction(() => { this.cols = j.collections })
+        } catch (e) {
+            runInAction(() => {
+                this.cols = [{ id: 'hub', title: 'hub', media: 'health', instances: [{ id: 'hub:collections-broken', text: `collections fetch broke: ${(e as Error).message}`, severity: 'red' }] }]
+            })
+        }
+    }
+
+    /** media instances render richer through the media sidebar — the
+     *  collection twin would be a duplicate surface (kept in `cols` so the
+     *  asset card can show its remarks) */
+    get sidebarCols(): Col[] {
+        return this.cols.filter((c) => c.id !== 'media')
+    }
+    mediaRemarks(assetId: string): string[] {
+        return this.cols.find((c) => c.id === 'media')?.instances.find((i) => i.id === `media:${assetId}`)?.remarks ?? []
+    }
+
+    needsItem = (i: ColInstance): boolean => i.severity != null
+    isOpen(c: Col): boolean {
+        // a live search must SHOW its matches — folds yield while it runs
+        if (this.st.query.trim() !== '') return true
+        return this.foldOverride.get(c.id) ?? c.instances.some(this.needsItem)
+    }
+    toggleFold(c: Col): void {
+        // folds yield to a live search — toggling then would do nothing
+        // visibly and snap shut when the query clears
+        if (this.st.query.trim() !== '') return
+        this.foldOverride.set(c.id, !this.isOpen(c))
+    }
+    openSection(c: Col): void {
+        this.foldOverride.set(c.id, true)
+    }
+    /** rail red dot — the section holds at least one red item */
+    hasRed(c: Col): boolean {
+        return c.instances.some((i) => i.severity === 'red')
+    }
+    get mediaHasRed(): boolean {
+        return this.cols.find((c) => c.id === 'media')?.instances.some((i) => i.severity === 'red') === true
+    }
+    visibleInstances(c: Col): ColInstance[] {
+        const f = this.st.filter
+        const base = f === 'all' ? c.instances
+            : c.instances.filter((i) => (f === 'red' ? i.severity === 'red' : this.needsItem(i)))
+        const q = this.st.query.trim().toLowerCase()
+        if (q === '') return base
+        return base.filter((i) => i.text.toLowerCase().includes(q) || (i.file ?? '').toLowerCase().includes(q))
+    }
+    get redCount(): number {
+        return this.cols.flatMap((c) => c.instances).filter((i) => i.severity === 'red').length
+    }
+    find(colId: string, id: string): ColInstance | null {
+        return this.cols.find((c) => c.id === colId)?.instances.find((i) => i.id === id) ?? null
+    }
+    colTitle(colId: string): string {
+        return this.cols.find((c) => c.id === colId)?.title ?? colId
+    }
+
+    select(colId: string, id: string): void {
+        this.st.sel = { t: 'item', col: colId, id }
+        this.actErr = ''
+        this.remarkDraft = ''
+        this.proofDraft = ''
+    }
+
+    private async act(path: string, body: Record<string, unknown>): Promise<boolean> {
+        this.actErr = ''
+        try {
+            const r = await fetch(`/api/act/${path}`, { method: 'POST', body: JSON.stringify(body) })
+            if (!r.ok) throw new Error(await r.text())
+            await this.poll()
+            return true
+        } catch (e) {
+            runInAction(() => { this.actErr = (e as Error).message })
+            return false
+        }
+    }
+
+    askDone(file: string): Promise<boolean> {
+        const url = this.proofDraft.trim()
+        return url !== '' ? this.act('ask-proof', { file, url }) : this.act('ask-done', { file })
+    }
+    postPick(channel: string, file: string): Promise<boolean> {
+        return this.act('post-pick', { channel, file })
+    }
+    async postPosted(channel: string, file: string): Promise<boolean> {
+        const url = this.proofDraft.trim()
+        if (url === '') {
+            this.actErr = 'paste the posted URL first — the proof is the point'
+            return false
+        }
+        const ok = await this.act('post-posted', { channel, file, url })
+        if (ok) runInAction(() => { this.proofDraft = '' })
+        return ok
+    }
+    async remark(body: Record<string, unknown>): Promise<void> {
+        const text = this.remarkDraft.trim()
+        if (text === '') return
+        // draft survives a failed send — his words are never erased
+        const ok = await this.act('remark', { ...body, text })
+        if (ok) runInAction(() => { this.remarkDraft = '' })
+    }
+}