rvlib-shipkit 0.11.0 → 0.14.0

package/src/cli/cmd_Rules.ts

@@ -0,0 +1,32 @@
+// shipkit rules — render the SK rule registry. Agents read ids HERE (or
+// --json), never guess or mint one: the registry is the single source.
+import { Command, Option } from 'clipanion'
+import { RULES } from '../rules/rule-registry.ts'
+
+export class RulesCommand extends Command {
+    static override paths = [['rules']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'list every built-in SK rule: id, what it lints, owning doc, whether check --fix can repair it',
+        examples: [
+            ['list rules', 'shipkit rules'],
+            ['machine-readable', 'shipkit rules --json'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'machine-readable [{id, title, owner, fixable}]' })
+
+    async execute(): Promise<number> {
+        const rows = RULES.map((r) => ({ id: r.id, title: r.title, owner: r.owner, fixable: r.fix != null }))
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify(rows)}\n`)
+            return 0
+        }
+        // a catalog, not a health run — no wire prefixes (`ok:` would assert
+        // a passing check into anything that parses wire output)
+        for (const r of rows)
+            this.context.stdout.write(`${r.id}  ${r.title} — ${r.owner}${r.fixable ? ' · fixable' : ''}\n`)
+        return 0
+    }
+}

package/src/cli/cmd_Serve.ts

@@ -8,7 +8,7 @@ export class ServeCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Serve',
-        description: 'ONE hub server per repo: landing page linking the wiki/agent graphs, the assets studio, and live status',
+        description: 'ONE server, ONE page: media studio + asks + creds + posts + health + graphs, with drill-down graph pages',
         examples: [
             ['serve the repo toolbox', 'shipkit serve'],
             ['pin the port for this launch', 'shipkit serve --port 4804'],

package/src/cli.ts

@@ -5,13 +5,15 @@
 import { readFileSync } from 'fs'
 import { Builtins, Cli } from 'clipanion'
 import { AskNewCommand, AsksCheckCommand, AsksCommand } from './cli/cmd_Asks.ts'
-import { AssetsAddCommand, AssetsCheckCommand, AssetsFillCommand, AssetsGenCommand, AssetsIdentityCommand, AssetsServeCommand } from './cli/cmd_Assets.ts'
+import { AssetsAddCommand, AssetsCheckCommand, AssetsFillCommand, AssetsGenCommand, AssetsIdentityCommand } from './cli/cmd_Assets.ts'
 import { CheckCommand } from './cli/cmd_Check.ts'
 import { CiCommand } from './cli/cmd_Ci.ts'
 import { ContractsCommand } from './cli/cmd_Contracts.ts'
 import { InitCommand } from './cli/cmd_Init.ts'
 import { MvCommand } from './cli/cmd_Mv.ts'
 import { NeedsCommand } from './cli/cmd_Needs.ts'
+import { ReflectCommand } from './cli/cmd_Reflect.ts'
+import { RulesCommand } from './cli/cmd_Rules.ts'
 import { ServeCommand } from './cli/cmd_Serve.ts'
 import { StartCommand } from './cli/cmd_Start.ts'
 import { TuiCommand } from './cli/cmd_Tui.ts'
@@ -40,7 +42,6 @@ cli.register(AsksCheckCommand)
 cli.register(AskNewCommand)
 cli.register(WikiServeCommand)
 cli.register(WikiLintCommand)
-cli.register(AssetsServeCommand)
 cli.register(AssetsFillCommand)
 cli.register(AssetsAddCommand)
 cli.register(AssetsGenCommand)
@@ -49,5 +50,7 @@ cli.register(AssetsCheckCommand)
 cli.register(InitCommand)
 cli.register(StartCommand)
 cli.register(NeedsCommand)
+cli.register(ReflectCommand)
+cli.register(RulesCommand)
 
 cli.runExit(process.argv.slice(2))

package/src/collections/actions.ts

@@ -55,6 +55,25 @@ export function appendPostFeedback(root: string, channel: string, file: string,
     writeFileSync(p, /^## Feedback\s*$/m.test(md) ? `${md.trimEnd()}\n${line}\n` : `${md.trimEnd()}\n\n## Feedback\n${line}\n`)
 }
 
+/** his asset remark → `.rv-assets/notes.md` (git-tracked; the studio
+ *  workspace is gitignored, so notes live beside kit.ts) */
+export function appendAssetNote(root: string, assetId: string, text: string): void {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(assetId)) throw new Error('bad asset id')
+    const p = join(root, '.rv-assets', 'notes.md')
+    const line = `- ${today()} [${assetId}]: ${text.replace(/\n+/g, ' ').trim()}`
+    writeFileSync(p, existsSync(p) ? `${readFileSync(p, 'utf8').trimEnd()}\n${line}\n` : `# asset notes — his remarks, read by agents at boot\n\n${line}\n`)
+}
+
+/** his remark on an ask → appended to the ask file, dated, non-destructive.
+ *  Accepts exactly one optional `done/` prefix (archived asks stay
+ *  annotatable); any other slash or traversal is a bad path. */
+export function appendAskRemark(root: string, asksDir: string, file: string, text: string): void {
+    if (!/^(done\/)?[A-Za-z0-9][A-Za-z0-9._-]*$/.test(file) || file.includes('..')) throw new Error('bad path')
+    const p = join(root, asksDir, file)
+    if (!existsSync(p)) throw new Error(`no such ask: ${file}`)
+    writeFileSync(p, `${readFileSync(p, 'utf8').trimEnd()}\n- ${today()}: ${text.replace(/\n+/g, ' ').trim()}\n`)
+}
+
 export function askDone(root: string, asksDir: string, file: string): void {
     if (file.includes('/') || file.includes('..')) throw new Error('bad path')
     archiveAsk(join(root, asksDir), file)

package/src/collections/collection-types.ts

@@ -23,6 +23,19 @@ export type Instance = {
     verbs?: CurationVerb[]
     /** roll-strip analog: pickable variants (post drafts, rolls) */
     candidates?: { id: string; label: string; hint?: string }[]
+    /** TRUST: the git file this instance IS — shown on the tile; the file
+     *  always wins over the page */
+    file?: string
+    /** thumbnail URL for media tiles */
+    img?: string
+    /** his latest remarks from the item's own file — agents boot on these */
+    remarks?: string[]
+    /** the truth file's markdown BODY (frontmatter stripped) — clamped card
+     *  in the grid, full in the item view; capped server-side, never a dump */
+    md?: string
+    /** an open ask owns the action (dedup = acted-on once, never hidden):
+     *  the instance stays red HERE but verbs and pings live with the ask */
+    askOwned?: boolean
 }
 
 export type Collection = {

package/src/collections/graphs.ts

@@ -0,0 +1,34 @@
+// graphs collection — the mounted md graphs as CHECKED section entries:
+// each graph instance carries its lint state (orphans + dangling refs =
+// yellow with counts; clean = quiet). Custom wiki-graph providers (repos
+// with their own loader + their own lint) get a link-only instance — their
+// repo lint owns correctness, never double-judged here.
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { lintMd } from '../wiki/lint-md.ts'
+import type { Collection, Instance } from './collection-types.ts'
+
+export function graphsCollection(root: string, o: { customWiki: boolean; agentIndex?: string }): Collection {
+    return {
+        id: 'graphs',
+        title: 'graphs',
+        media: 'data',
+        list: async () => {
+            const out: Instance[] = []
+            const checked = (id: string, title: string, href: string, dir: string, index?: string): Instance => {
+                const r = lintMd({ root: dir, index })
+                const issues = r.orphans.length + r.dangling.length
+                return {
+                    id,
+                    text: issues === 0 ? title : `${title} — ${r.orphans.length} orphan(s), ${r.dangling.length} dangling ref(s)`,
+                    severity: issues === 0 ? undefined : 'yellow',
+                    href,
+                }
+            }
+            if (o.customWiki) out.push({ id: 'graph:wiki', text: 'wiki graph (repo-owned lint)', href: '/graph/wiki' })
+            else out.push(checked('graph:wiki', 'wiki graph', '/graph/wiki', root))
+            if (existsSync(join(root, 'agent'))) out.push(checked('graph:agent', 'agent graph', '/graph/agent', join(root, 'agent'), o.agentIndex))
+            return out
+        },
+    }
+}

package/src/collections/pings.ts

@@ -17,6 +17,9 @@ export type PingIo = {
     notifyCommand?: string
     /** additive desktop notification on macOS */
     osascript?: boolean
+    /** hub URL appended to the message — the OFF-MACHINE form
+     *  (serve.publicHost); a phone can't resolve localhost */
+    link?: string
 }
 
 const stateDir = (root: string): string | null => (existsSync(join(root, 'node_modules')) ? join(root, 'node_modules', '.cache', 'shipkit') : null)
@@ -46,6 +49,7 @@ export function pingTick(root: string, asksDir: string, needs: NeedItem[], io: P
     const fresh: NeedItem[] = []
     for (const n of needs) {
         if (n.severity !== 'red') continue
+        if (n.askOwned === true) continue // the covering ask's pinged: field already fired the once-ever ping
         if (n.collection === 'asks') {
             // ask file owns the once-ever marker (shared with agent pings)
             const file = n.id.replace(/^ask:/, '')
@@ -58,7 +62,7 @@ export function pingTick(root: string, asksDir: string, needs: NeedItem[], io: P
     savePinged(root, pinged)
     if (fresh.length === 0) return []
     const head = fresh.slice(0, 3).map((n) => n.text.slice(0, 80)).join(' · ')
-    const message = `${fresh.length} new item(s) need you: ${head}${fresh.length > 3 ? ' · …' : ''}`
+    const message = `${fresh.length} new item(s) need you: ${head}${fresh.length > 3 ? ' · …' : ''}${io.link != null ? ` → ${io.link}` : ''}`
     // item texts come from repo data — strip shell-active chars before the template substitution
     const safe = message.replace(/[`$\\'"]/g, '')
     if (io.notifyCommand != null) io.run(['sh', '-c', io.notifyCommand.replaceAll('{message}', safe)])

package/src/collections/posts.ts

@@ -66,13 +66,19 @@ export function socialPostsCollection(root: string): Collection {
                 bySlug.set(key, [...(bySlug.get(key) ?? []), p])
             }
             const out: Instance[] = []
+            const feedback = (v: PostFile): string[] | undefined => {
+                const lines = v.body.split('\n').filter((l) => /^- \d{4}-\d{2}-\d{2}: /.test(l))
+                return lines.length > 0 ? lines.slice(-3) : undefined
+            }
             for (const [key, variants] of bySlug) {
+                const fileOf = (v: PostFile): string => `.rv-social/${v.channel}/${v.file}`
                 const missing = variants.filter((v) => v.status == null)
                 if (missing.length > 0) {
                     out.push({
                         id: `post:${key}:invalid`,
                         text: `${key} — missing/invalid status: frontmatter (${missing.map((v) => v.file).join(', ')})`,
                         severity: 'red',
+                        file: fileOf(missing[0]!),
                     })
                     continue
                 }
@@ -85,6 +91,8 @@ export function socialPostsCollection(root: string): Collection {
                         artifact: { copy: postSection(picked.body) },
                         verbs: ['paste-proof', 'rate'],
                         candidates: [{ id: picked.file, label: picked.variant ?? 'post' }],
+                        file: fileOf(picked),
+                        remarks: feedback(picked),
                     })
                     continue
                 }
@@ -96,9 +104,20 @@ export function socialPostsCollection(root: string): Collection {
                         severity: 'yellow',
                         verbs: ['pick', 'rate'],
                         candidates: drafts.map((v) => ({ id: v.file, label: v.variant ?? 'draft', hint: postSection(v.body).slice(0, 200) })),
+                        file: fileOf(drafts[0]!),
+                        remarks: feedback(drafts[0]!),
                     })
+                    continue
                 }
-                // posted / rejected-only: quiet — history is training data, not attention
+                // posted / rejected history: VISIBLE (browse-all), never in needs
+                const posted = variants.find((v) => v.status === 'posted')
+                const shown = posted ?? variants[0]!
+                out.push({
+                    id: `post:${key}:${posted != null ? 'posted' : 'rejected'}`,
+                    text: `${key} — ${posted != null ? `posted${posted.posted != null ? ` (${posted.posted})` : ''}` : 'rejected'}`,
+                    file: fileOf(shown),
+                    remarks: feedback(shown),
+                })
             }
             return out
         },

package/src/collections/providers.ts

@@ -1,19 +1,24 @@
 // The built-in collection providers — each one REPLACED an attentionCollector
 // guard (the collector is gone; never reintroduce a parallel projection).
 // Behaviors preserved by name: per-source failure isolation (projectNeeds
-// guards per collection), cred-FAIL↔ask dedup, the identity self-heal
-// before surfacing, and the asks READ path never minting asks/ on a repo
-// without one. Dedup chain for one real-world action:
-// ask > cred-instance > health-line.
+// guards per collection), the identity self-heal before surfacing, and the
+// asks READ path never minting asks/ on a repo without one. Dedup doctrine
+// (his correction 2026-07-23): dedup = acted-on once, NEVER hidden — an
+// ask-covered missing cred still shows RED in secrets with a pointer to the
+// ask; verbs and pings stay with the ask. Each wire line of STATUS.md lives
+// in exactly ONE collection: cred probe lines in secrets, everything else
+// in repo health.
 import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import { isStale } from '../assets/gen/derived.ts'
-import { allAssets, type ResolvedKit } from '../assets/kit-config.ts'
+import { allAssets, mediaOf, type ResolvedKit } from '../assets/kit-config.ts'
 import { assetDir, listRolls, readPick } from '../assets/roll-workspace.ts'
 import { healIdentity } from '../assets/run-assets.ts'
-import { openAsks } from '../asks/asks-queue.ts'
+import { doneAsks, openAsks } from '../asks/asks-queue.ts'
 import { evaluateContracts } from '../contracts/contracts-engine.ts'
-import { activeContracts, contractsConfigFrom, type RepoConfig } from '../repo-config.ts'
+import { parseWireOutput } from '../core/wire.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import { activeContracts, contractsConfigFrom } from '../contracts/apply-contracts.ts'
 import type { Collection, Instance } from './collection-types.ts'
 import { socialPostsCollection } from './posts.ts'
 
@@ -26,50 +31,126 @@ const openAsksSafe = (root: string, c: RepoConfig): ReturnType<typeof openAsks>
 
 const CRED_LINE = /cred ([a-z0-9-]+\/[a-z0-9-]+\/[a-z0-9-]+) missing/
 
+/** STATUS.md's check output, regrouped: one item per ok/WARN/FAIL wire line
+ *  with its indented fix: pointers riding along. The writer's markdown
+ *  wrapper (comment, title, verdict, fences) parses as notes and drops out. */
+type WireItem = { kind: 'ok' | 'warn' | 'fail'; text: string; fixes: string[] }
+const statusWire = (root: string): WireItem[] => {
+    const p = join(root, 'STATUS.md')
+    if (!existsSync(p)) return []
+    const items: WireItem[] = []
+    for (const l of parseWireOutput(readFileSync(p, 'utf8'))) {
+        if (l.kind === 'ok' || l.kind === 'warn' || l.kind === 'fail') items.push({ kind: l.kind, text: l.text, fixes: [] })
+        else if ((l.kind === 'fix-warn' || l.kind === 'fix-fail') && items.length > 0) items[items.length - 1]!.fixes.push(l.text)
+    }
+    return items
+}
+
+/** wire lines re-rendered as a fenced block for an instance's md */
+const wireMd = (lines: string[]): string => `\`\`\`\n${lines.join('\n')}\n\`\`\``
+
 export function asksCollection(root: string, c: RepoConfig): Collection {
     return {
         id: 'asks',
-        title: 'asks — waiting on you',
+        title: 'asks',
         media: 'text',
-        list: async () =>
-            openAsksSafe(root, c).map((a) => ({
+        list: async () => {
+            const rel = c.asks?.dir ?? 'asks'
+            const open = openAsksSafe(root, c).map((a): Instance => ({
                 id: `ask:${a.file}`,
                 text: `${a.title}${a.kind !== '' ? ` (${a.kind})` : ''}`,
                 severity: 'red' as const,
                 verbs: ['done' as const, 'paste-proof' as const],
-            })),
+                file: `${rel}/${a.file}`,
+                md: askMd(join(root, rel, a.file)),
+                remarks: lastRemarks(join(root, rel, a.file)),
+            }))
+            // the done/ archive rides along QUIET (no severity) — past answers
+            // stay consultable and remarkable; newest first, after every open ask
+            const done = doneAsks(askDirOf(root, c)).map((a): Instance => ({
+                id: `ask:done/${a.file}`,
+                text: `${a.title}${a.kind !== '' ? ` (${a.kind})` : ''}`,
+                file: `${rel}/done/${a.file}`,
+                md: askMd(join(root, rel, 'done', a.file)),
+                remarks: lastRemarks(join(root, rel, 'done', a.file)),
+            }))
+            return [...open, ...done]
+        },
     }
 }
 
+// a card, not a document dump — the cut is loud (…) so a clamped card never
+// passes for the whole truth file
+const MD_CAP = 4000
+
+/** the ask file's markdown body: frontmatter stripped, trimmed, capped */
+const askMd = (path: string): string | undefined => {
+    if (!existsSync(path)) return undefined
+    const body = readFileSync(path, 'utf8').replace(/^---\n[\s\S]*?\n---\n?/, '').trim()
+    if (body === '') return undefined
+    // code-point slice — a UTF-16 cut can strand half a surrogate pair
+    return body.length > MD_CAP ? `${[...body].slice(0, MD_CAP).join('')}…` : body
+}
+
+/** his latest dated remark lines from a file's tail — the boot briefing */
+const lastRemarks = (path: string, max = 3): string[] | undefined => {
+    if (!existsSync(path)) return undefined
+    const lines = readFileSync(path, 'utf8').split('\n').filter((l) => /^- \d{4}-\d{2}-\d{2}: /.test(l))
+    return lines.length > 0 ? lines.slice(-max) : undefined
+}
+
 /** repo-declared secrets (repo.config `creds:`) + cred FAIL lines from
- *  STATUS.md — the tile carries the mint artifact as data. Skips any secret
- *  covered by an open ask (the ask wins: his hands, one surface). */
+ *  STATUS.md — the tile carries the mint artifact as data. EVERY declared
+ *  cred is listed. Missing + unclaimed = red with the set verb + artifact;
+ *  missing + ask-covered = STILL red (never hidden), no verbs — the text
+ *  points at the ask that owns the action. The probe FAIL line (+ its fix:
+ *  pointers) rides the instance's md, never a health line.
+ *  Declared-and-present creds show QUIET, the vault is consultable. */
 export function credsCollection(root: string, c: RepoConfig): Collection {
     return {
         id: 'creds',
-        title: 'missing secrets',
+        title: 'secrets',
         media: 'pointer',
         list: async () => {
-            const askText = openAsksSafe(root, c).map((a) => a.title.toLowerCase()).join(' ')
-            const covered = (name: string): boolean => askText.includes(name.split('/')[1] ?? name)
+            const rel = c.asks?.dir ?? 'asks'
+            const asks = openAsksSafe(root, c)
+            const coveringAsk = (name: string): { file: string } | undefined =>
+                asks.find((a) => a.title.toLowerCase().includes(name.split('/')[1] ?? name))
+            // only a FAIL probe proves missing — a WARN/narrative mention never reds
+            const probes = new Map<string, WireItem>()
+            for (const i of statusWire(root)) {
+                if (i.kind !== 'fail') continue
+                const name = i.text.match(CRED_LINE)?.[1]
+                if (name != null && !probes.has(name)) probes.set(name, i)
+            }
             const out: Instance[] = []
-            const seen = new Set<string>()
-            const statusPath = join(root, 'STATUS.md')
-            const statusCreds = existsSync(statusPath)
-                ? readFileSync(statusPath, 'utf8')
-                      .split('\n')
-                      .filter((l) => l.trimStart().startsWith('FAIL')) // only a FAIL probe proves missing — a WARN/narrative mention never reds
-                      .map((l) => l.match(CRED_LINE)?.[1])
-                      .filter((n): n is string => n != null)
-                : []
-            for (const name of statusCreds) {
-                if (seen.has(name) || covered(name)) continue
-                seen.add(name)
+            for (const [name, probe] of probes) {
                 const decl = (c.creds ?? []).find((d) => d.name === name)
-                out.push(credInstance(name, c.credsCommand, decl))
+                const md = wireMd([`FAIL: ${probe.text}`, ...probe.fixes.map((f) => `fix: ${f}`)])
+                const ask = coveringAsk(name)
+                if (ask != null)
+                    // dedup = acted-on once, never hidden: the ask keeps the
+                    // verbs and the ping; the cred still shows RED here
+                    out.push({
+                        id: `cred:${name}`,
+                        text: `${name} missing${decl?.service != null ? ` — ${decl.service}` : ''} — ask ${rel}/${ask.file} owns this`,
+                        severity: 'red',
+                        md,
+                        askOwned: true,
+                    })
+                else out.push({ ...credInstance(name, c.credsCommand, decl), md })
+            }
+            // every declared cred not proven missing is a quiet instance —
+            // present secrets carry no severity and no copy command (nothing
+            // to run), just the mint pointer when one is declared
+            for (const d of c.creds ?? []) {
+                if (probes.has(d.name)) continue
+                out.push({
+                    id: `cred:${d.name}`,
+                    text: `${d.name}${d.service != null ? ` — ${d.service}` : ''}`,
+                    artifact: d.mintUrl != null ? { url: d.mintUrl } : undefined,
+                })
             }
-            // declared-but-not-probed creds stay quiet: only a STATUS.md
-            // probe line proves "missing" — declaration alone never reds
             return out
         },
     }
@@ -85,9 +166,11 @@ const credInstance = (name: string, cmdTemplate: string | undefined, decl?: { se
     verbs: ['set'],
 })
 
-/** media kit instances — identity self-heals BEFORE surfacing; manual with
- *  nothing uploaded = red (provide); rolls with no pick = yellow (a default
- *  exists, taste pending — auto-pick-first is blessed); stale = yellow. */
+/** media kit instances — BROWSE-ALL: every kit asset is an instance (the
+ *  page shows everything that exists; healthy = no severity, dim tile).
+ *  Identity self-heals BEFORE surfacing; manual with nothing uploaded =
+ *  red (provide); rolls with no pick = yellow (a default exists, taste
+ *  pending — auto-pick-first is blessed); stale = yellow. */
 export function mediaKitCollection(root: string, kit: ResolvedKit | null, heal: typeof healIdentity = healIdentity): Collection {
     return {
         id: 'media',
@@ -97,29 +180,57 @@ export function mediaKitCollection(root: string, kit: ResolvedKit | null, heal:
             const idn = await heal(root)
             const out: Instance[] = []
             if (idn.state === 'blocked')
-                out.push({ id: 'media:identity', text: `identity — ${idn.detail ?? 'blocked'}`, severity: 'red', href: '/assets/#identity-logo', verbs: ['pick'] })
+                out.push({ id: 'media:identity', text: `identity — ${idn.detail ?? 'blocked'}`, severity: 'red', href: '/#identity-logo', verbs: ['pick'] })
             if (kit == null) return out
+            const notes = assetNotes(root)
             for (const f of allAssets(kit)) {
                 const dir = assetDir(join(root, kit.workspace), f.asset.id)
                 const rolls = listRolls(dir)
                 const manual = f.kind.generate.backend === 'manual'
-                const href = `/assets/#${f.asset.id}`
+                const base: Instance = {
+                    id: `media:${f.asset.id}`,
+                    text: f.asset.id,
+                    href: `/#${f.asset.id}`,
+                    // image kinds only — /api/thumb serves raw roll bytes, and
+                    // an mp3 inside an <img> is a broken glyph on every tile
+                    img: rolls.length > 0 && mediaOf(f.kind) === 'image' ? `/media/api/thumb?id=${encodeURIComponent(f.asset.id)}` : undefined,
+                    file: '.rv-assets/kit.ts',
+                    remarks: notes.get(f.asset.id),
+                }
                 if (manual && rolls.length === 0)
                     // the brief IS the paste-ready artifact ("I don't even
                     // know what to paste" — the tile hands him the prompt)
-                    out.push({ id: `media:${f.asset.id}`, text: `${f.asset.id} — manual, nothing uploaded`, severity: 'red', href, verbs: ['provide'], artifact: f.asset.prompt != null ? { copy: f.asset.prompt } : undefined })
+                    out.push({ ...base, text: `${f.asset.id} — manual, nothing uploaded`, severity: 'red', verbs: ['provide'], artifact: f.asset.prompt != null ? { copy: f.asset.prompt } : undefined })
                 else if (rolls.length > 0 && (await readPick(dir)).pick == null)
-                    out.push({ id: `media:${f.asset.id}`, text: `${f.asset.id} — ${rolls.length} roll(s), default in use, none picked`, severity: 'yellow', href, verbs: ['pick'] })
+                    out.push({ ...base, text: `${f.asset.id} — ${rolls.length} roll(s), default in use, none picked`, severity: 'yellow', verbs: ['pick'] })
                 else if (await isStale(kit, join(root, kit.workspace), f))
-                    out.push({ id: `media:${f.asset.id}`, text: `${f.asset.id} — stale (a parent was re-picked)`, severity: 'yellow', href, verbs: ['pick'] })
+                    out.push({ ...base, text: `${f.asset.id} — stale (a parent was re-picked)`, severity: 'yellow', verbs: ['pick'] })
+                else out.push(base) // healthy — visible, dim, never in needs
             }
             return out
         },
     }
 }
 
-/** repo health — NON-curatable feed items: failing checks (minus cred lines
- *  the creds provider owns), contract FAIL/WARN, hub process staleness. */
+/** `.rv-assets/notes.md` — his dated asset remarks, one git-tracked file:
+ *  `- YYYY-MM-DD [asset-id]: text` */
+const assetNotes = (root: string): Map<string, string[]> => {
+    const p = join(root, '.rv-assets', 'notes.md')
+    const map = new Map<string, string[]>()
+    if (!existsSync(p)) return map
+    for (const m of readFileSync(p, 'utf8').matchAll(/^- (\d{4}-\d{2}-\d{2}) \[([^\]]+)\]: (.+)$/gm)) {
+        const key = m[2]!
+        map.set(key, [...(map.get(key) ?? []).slice(-2), `- ${m[1]}: ${m[3]}`])
+    }
+    return map
+}
+
+/** repo health — NON-curatable feed items: EVERY wire line of STATUS.md's
+ *  check output (ok = quiet, WARN = yellow, FAIL = red; the passing lines
+ *  ARE listed — the page shows the whole check run), plus contract
+ *  FAIL/WARN and hub process staleness. fix: pointers ride the owning
+ *  instance's md as a code block. Cred probe FAIL lines (+ their fixes) are
+ *  routed to the secrets collection, never duplicated here. */
 export function repoHealthCollection(root: string, c: RepoConfig, o?: { bootVersion?: string; libVersion?: () => string }): Collection {
     return {
         id: 'health',
@@ -132,15 +243,17 @@ export function repoHealthCollection(root: string, c: RepoConfig, o?: { bootVers
                 if (now !== o.bootVersion)
                     out.push({ id: 'health:stale-hub', severity: 'red', text: `hub is running shipkit ${o.bootVersion} but ${now} is on disk (stale process, stale pages, old studio code). Restart the 🚀 shipkit task` })
             }
-            const statusPath = join(root, 'STATUS.md')
-            if (existsSync(statusPath))
-                for (const l of readFileSync(statusPath, 'utf8').split('\n'))
-                    if (l.trimStart().startsWith('FAIL') && !CRED_LINE.test(l)) {
-                        // the feed line carries severity already — a raw FAIL: marker would stack three signals
-                        const text = l.trim().replace(/^(FAIL|WARN):\s*/, '')
-                        // id = full text (never sliced: a shared 60-char prefix must not collide two items — pings dedup on ids)
-                        out.push({ id: `health:${text}`, severity: 'red', text, href: '/status' })
-                    }
+            for (const i of statusWire(root)) {
+                if (i.kind === 'fail' && CRED_LINE.test(i.text)) continue // secrets own the cred probe + its fix lines
+                // the feed line carries severity already — a raw FAIL:/WARN marker would stack the signal
+                // id = full text (never sliced: a shared 60-char prefix must not collide two items — pings dedup on ids)
+                out.push({
+                    id: `health:${i.text}`,
+                    text: i.text,
+                    severity: i.kind === 'fail' ? 'red' : i.kind === 'warn' ? 'yellow' : undefined,
+                    md: i.fixes.length > 0 ? wireMd(i.fixes.map((f) => `fix: ${f}`)) : undefined,
+                })
+            }
             const r = await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root))
             for (const l of r.lines) {
                 if (l.kind === 'fail') out.push({ id: `health:contract:${l.text}`, severity: 'red', text: l.text })

package/src/contracts/apply-contracts.ts

@@ -0,0 +1,47 @@
+// The ONE bridge from the contracts engine into wire output — every surface
+// that reports contract fulfillness (`shipkit check` via rule SK002, the ci
+// `contracts` task, `shipkit contracts`) goes through applyContractsResult,
+// so tags, the empty-repo sentence, and severity plumbing exist exactly
+// once. Kinds pass through raw so fix pointers and visible exempts survive
+// every printer.
+import { existsSync } from 'fs'
+import { join } from 'path'
+import type { CheckCtx } from '../core/check-ctx.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import { tagRuleLines, type Rule } from '../rules/rule.ts'
+import { allContracts } from './contract-manifests.ts'
+import type { ContractManifest } from './contract-types.ts'
+import type { ContractsConfig, ContractsResult } from './contracts-engine.ts'
+
+export function contractsConfigFrom(c: RepoConfig, root: string): ContractsConfig {
+    const venues = c.venues ?? []
+    const social = c.social ?? []
+    const declared = [
+        ...venues,
+        ...(social.length > 0 ? ['social'] : []),
+        ...(social.includes('discord') ? ['discord'] : []),
+    ]
+    return {
+        root,
+        declared,
+        social,
+        publicSurface: venues.length > 0 || existsSync(join(root, 'deploy.sh')),
+        exempt: c.contracts?.exempt,
+        docsBase: c.docsBase,
+    }
+}
+
+export function activeContracts(c: RepoConfig): ContractManifest[] {
+    return [...allContracts, ...(c.contracts?.extra ?? [])]
+}
+
+export function applyContractsResult(t: CheckCtx, r: ContractsResult, tag?: Rule): void {
+    const lines = tag != null ? tagRuleLines(tag, r.lines) : r.lines
+    for (const l of lines) t.lines.push(l)
+    if (r.exitCode === 1) t.failed = true
+    if (r.lines.some((l) => l.kind === 'warn')) t.warned = true
+    if (r.lines.length === 0) {
+        const text = 'no contracts apply (nothing declared, nothing detected)'
+        t.ok(tag != null ? `[${tag.id}] ${text}` : text)
+    }
+}

package/src/contracts/contract-types.ts

@@ -6,7 +6,10 @@
 
 export type RuleOpts = { warnOnly?: boolean }
 export type FileRule = RuleOpts & { kind: 'file'; path: string; nonEmpty: boolean }
-export type PngRule = RuleOpts & { kind: 'png'; path: string; width: number; height: number }
+/** `atLeast`: the venue's numbers are a MINIMUM at a fixed aspect ratio (itch
+ *  displays a 630x500 cover but accepts larger, and a 2x asset is better) —
+ *  without it an exact-size rule blocks the release over a better file */
+export type PngRule = RuleOpts & { kind: 'png'; path: string; width: number; height: number; atLeast?: boolean }
 export type GlobRule = RuleOpts & { kind: 'glob'; pattern: string; min: number; width?: number; height?: number }
 export type MdRule = RuleOpts & { kind: 'md'; path: string; mustContain: string[] }
 export type DirRule = RuleOpts & { kind: 'dir'; path: string }
@@ -41,7 +44,7 @@ export type ContractManifest = {
 }
 
 export const file = (path: string, p?: RuleOpts & { nonEmpty?: boolean }): FileRule => ({ kind: 'file', path, nonEmpty: p?.nonEmpty ?? true, warnOnly: p?.warnOnly })
-export const png = (path: string, width: number, height: number, p?: RuleOpts): PngRule => ({ kind: 'png', path, width, height, warnOnly: p?.warnOnly })
+export const png = (path: string, width: number, height: number, p?: RuleOpts & { atLeast?: boolean }): PngRule => ({ kind: 'png', path, width, height, atLeast: p?.atLeast, warnOnly: p?.warnOnly })
 export const glob = (pattern: string, p: RuleOpts & { min: number; width?: number; height?: number }): GlobRule => ({ kind: 'glob', pattern, min: p.min, width: p.width, height: p.height, warnOnly: p.warnOnly })
 export const md = (path: string, p?: RuleOpts & { mustContain?: string[] }): MdRule => ({ kind: 'md', path, mustContain: p?.mustContain ?? [], warnOnly: p?.warnOnly })
 export const dir = (path: string, p?: RuleOpts): DirRule => ({ kind: 'dir', path, warnOnly: p?.warnOnly })

package/src/contracts/contracts-engine.ts

@@ -57,11 +57,21 @@ async function checkRule(rule: ArtifactRule, env: ContractEnv): Promise<string[]
         }
         case 'png': {
             const p = abs(env.root, rule.path)
-            if (!existsSync(p)) { problems.push(`${rule.path} missing — need png ${rule.width}x${rule.height}`); break }
+            const need = rule.atLeast === true ? `>= ${rule.width}x${rule.height} at ${rule.width}:${rule.height}` : `${rule.width}x${rule.height}`
+            if (!existsSync(p)) { problems.push(`${rule.path} missing — need png ${need}`); break }
             const dims = pngDims(p)
             if (dims == null) problems.push(`${rule.path} is not a readable png`)
-            else if (dims.width !== rule.width || dims.height !== rule.height)
-                problems.push(`${rule.path} is ${dims.width}x${dims.height} — need ${rule.width}x${rule.height}`)
+            else if (rule.atLeast !== true) {
+                if (dims.width !== rule.width || dims.height !== rule.height) problems.push(`${rule.path} is ${dims.width}x${dims.height} — need ${need}`)
+            } else {
+                const want = rule.width / rule.height
+                // RELATIVE tolerance: an absolute one is 0.8% at 630:500 and
+                // 3% at a tall ratio, i.e. a different rule per venue
+                const ratioOff = Math.abs(dims.width / dims.height - want) / want > 0.01
+                const tooSmall = dims.width < rule.width || dims.height < rule.height
+                if (tooSmall || ratioOff)
+                    problems.push(`${rule.path} is ${dims.width}x${dims.height} — need ${need}${ratioOff ? ' (the ratio is off; a bigger asset at the same ratio is fine)' : ' (bigger is fine, smaller is not)'}`)
+            }
             break
         }
         case 'glob': {

package/src/contracts/manifests/discord.contract.ts

@@ -10,6 +10,6 @@ export default defineContract({
     detect: [dirExists('.rv-discord')],
     artifacts: [
         md('.rv-discord/server.md', { mustContain: ['invite'] }),
-        png('.rv-discord/icon.png', 512, 512),
+        png('.rv-discord/icon.png', 512, 512, { atLeast: true }),
     ],
 })