rvlib-shipkit 0.6.0 → 0.8.0

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

@@ -5,7 +5,7 @@ import { defineContract, dirExists, md, png } from 'rvlib-shipkit/src/contracts/
 export default defineContract({
     venue: 'discord',
     dir: '.rv-discord',
-    owner: 'distribute/social.md',
+    owner: 'distribute/post-publicly.md',
     appliesTo: 'declared',
     detect: [dirExists('.rv-discord')],
     artifacts: [

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

@@ -6,7 +6,7 @@ import { defineContract, file, glob, png } from 'rvlib-shipkit/src/contracts/con
 export default defineContract({
     venue: 'identity',
     dir: '.rv-identity',
-    owner: 'build/assets.md',
+    owner: 'build/generate-assets.md',
     appliesTo: 'always',
     gate: 'public-surface',
     detect: [],

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

@@ -5,7 +5,7 @@ import { custom, defineContract, dirExists } from 'rvlib-shipkit/src/contracts/c
 export default defineContract({
     venue: 'social',
     dir: '.rv-social',
-    owner: 'distribute/social.md',
+    owner: 'distribute/post-publicly.md',
     appliesTo: 'declared',
     detect: [dirExists('.rv-social')],
     artifacts: [

package/src/core/package-json-check.ts

@@ -68,6 +68,7 @@ export async function evaluatePackageJson(t: CheckCtx, root: string, c: RepoConf
         { name: 'contracts', why: 'shipkit repo' },
         { name: 'tui', why: 'shipkit repo' },
         { name: 'hub', why: 'shipkit repo' },
+        { name: 'mv', why: 'shipkit repo' },
     ]
     if (existsSync(join(root, '.rv-assets/kit.ts'))) required.push({ name: 'assets', why: '.rv-assets/kit.ts exists' })
     if (existsSync(join(root, '.rv-identity/brand.ts'))) required.push({ name: 'assets:identity', why: '.rv-identity/brand.ts exists' })

package/src/init-repo.ts

@@ -42,7 +42,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     let added = 0
     // canonical script NAME → shipkit command (hub runs `shipkit serve`) —
     // vocabulary owned by meta/rv-conventions/package-json.md
-    const CANONICAL = { ci: 'ci', check: 'check', contracts: 'contracts', tui: 'tui', hub: 'serve' } as const
+    const CANONICAL = { ci: 'ci', check: 'check', contracts: 'contracts', tui: 'tui', hub: 'serve', mv: 'mv' } as const
     for (const [k, cmd] of Object.entries(CANONICAL)) {
         const v = run(cmd)
         if (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }

package/src/mv/mv-md.ts

@@ -0,0 +1,90 @@
+// shipkit mv — rename an md page the AGILE way: one command moves the .md,
+// its sibling asset dir and <name>.check.ts, then sweeps EVERY tracked text
+// file for refs (full path, docs-root-relative id, check filename). Dry by
+// default; --write applies; --commit adds one conventional commit (the
+// repo's pre-commit hook is the gate). If package.json has a `mv:after`
+// script it runs after the moves (repo-specific re-stamps). TS module moves
+// are a different concern (a TS-aware renamer owns import graphs).
+import { execSync } from 'child_process'
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { basename, dirname, join } from 'path'
+
+export type MvIo = { print: (l: string) => void; printErr: (l: string) => void }
+export type MvOpts = { write?: boolean; commit?: boolean }
+
+const sh = (cmd: string, cwd: string): string => execSync(cmd, { cwd }).toString()
+
+export function movePage(root: string, oldRel: string, newRel: string, io: MvIo, o: MvOpts = {}): number {
+    const die = (m: string): number => { io.printErr(`FAIL: ${m}`); return 1 }
+    if (!oldRel.endsWith('.md') || !newRel.endsWith('.md')) return die('both paths must be .md (TS moves are not this tool\'s job)')
+    if (!existsSync(join(root, oldRel))) return die(`${oldRel} does not exist`)
+    if (existsSync(join(root, newRel))) return die(`${newRel} already exists`)
+    if (dirname(oldRel) !== dirname(newRel)) return die('cross-directory moves not supported yet, same dir only')
+
+    const write = o.write === true || o.commit === true
+    const oldName = basename(oldRel, '.md')
+    const newName = basename(newRel, '.md')
+    const oldBase = oldRel.slice(0, -3) // full path sans .md — the sibling dir
+    const newBase = newRel.slice(0, -3)
+    // docs-root-relative id: refs inside a wiki usually omit the top dir
+    // (`build/state`, not `wiki/build/state`) — sweep both forms
+    const tail = (p: string): string | null => { const seg = p.split('/'); return seg.length >= 3 ? seg.slice(1).join('/') : null }
+    const oldId = tail(oldBase)
+    const newId = tail(newBase)
+
+    // longest-first so `wiki/x/state.md` beats `x/state` beats bare tokens
+    const pairs: [string, string][] = [
+        [`${oldBase}.md`, `${newBase}.md`],
+        ...(oldId != null ? [[`${oldId}.md`, `${newId}.md`] as [string, string]] : []),
+        // probe file is named after its page; DIR-qualified so another
+        // page's same-named check.ts in a different dir never gets rewritten
+        [`${oldBase}/${oldName}.check.ts`, `${newBase}/${newName}.check.ts`],
+        ...(oldId != null ? [[`${oldId}/${oldName}.check.ts`, `${newId}/${newName}.check.ts`] as [string, string]] : []),
+        [`${oldBase}/`, `${newBase}/`],
+        ...(oldId != null ? [[`${oldId}/`, `${newId}/`] as [string, string]] : []),
+        [oldBase, newBase],
+        ...(oldId != null ? [[oldId, newId!] as [string, string]] : []),
+    ]
+    const bound = (t: string): RegExp =>
+        new RegExp('(?<![\\w-])' + t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + (/[/.]$/.test(t) || t.endsWith('.ts') ? '' : '(?![\\w-])'), 'g')
+
+    const tracked = sh('git ls-files', root).split('\n').filter(Boolean)
+        .filter((f) => !/\.(png|jpe?g|gif|webp|ico|woff2?|ttf|zip|gz|lockb|lock)$/i.test(f))
+    let touched = 0
+    for (const f of tracked) {
+        const p = join(root, f)
+        if (!existsSync(p)) continue
+        const before = readFileSync(p, 'utf8')
+        let after = before
+        for (const [oldTok, newTok] of pairs) after = after.replace(bound(oldTok), newTok)
+        if (after !== before) {
+            io.print(`  ${f}`)
+            if (write) writeFileSync(p, after)
+            touched++
+        }
+    }
+    io.print(`${write ? 'renamed' : 'DRY RUN'}: ${oldBase} → ${newBase}, refs in ${touched} file(s)`)
+    if (!write) { io.print('re-run with --write (or --commit) to apply'); return 0 }
+
+    // moves AFTER the sweep (the sweep rewrote files at their old paths)
+    sh(`git mv ${JSON.stringify(oldRel)} ${JSON.stringify(newRel)}`, root)
+    if (existsSync(join(root, oldBase))) {
+        sh(`git mv ${JSON.stringify(oldBase)} ${JSON.stringify(newBase)}`, root)
+        const oldCheck = join(newBase, `${oldName}.check.ts`)
+        if (existsSync(join(root, oldCheck))) sh(`git mv ${JSON.stringify(oldCheck)} ${JSON.stringify(join(newBase, `${newName}.check.ts`))}`, root)
+    }
+
+    // repo-specific re-stamps (e.g. wiki depth frontmatter) — loud on failure
+    const pkg = existsSync(join(root, 'package.json')) ? (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { scripts?: Record<string, string> }) : {}
+    if (pkg.scripts?.['mv:after'] != null) {
+        try { execSync('bun run mv:after', { cwd: root, stdio: 'inherit' }) } catch { return die('mv:after failed, fix before committing') }
+    }
+    if (o.commit === true) {
+        sh('git add -A', root)
+        try {
+            execSync(`git commit -m ${JSON.stringify(`docs: rename ${oldBase} → ${newBase}`)}`, { cwd: root, stdio: 'inherit' })
+        } catch { return die('commit failed (pre-commit gate?). The rename is applied, fix and commit yourself') }
+    }
+    io.print(`ok: ${oldBase} → ${newBase}${o.commit === true ? ' (committed)' : ''}`)
+    return 0
+}

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

@@ -0,0 +1,156 @@
+// The hub's React app (Bun.serve HTML import — no vite, no build step).
+// Two views routed by pathname: / = attention dashboard (everything red),
+// /status = STATUS.md + streamed check runs. The rail lists every mounted
+// tool (from /hub.json) — legacy pages (graphs, studio) get the same rail
+// injected server-side until they migrate.
+import { makeAutoObservable, runInAction } from 'mobx'
+import { observer } from 'mobx-react-lite'
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+
+type HubTool = { path: string; label: string; desc: string }
+type AttentionLine = { text: string; href?: string }
+type AttentionSection = { title: string; tone: 'red' | 'warn'; lines: AttentionLine[]; href?: string }
+
+const RAIL_ICONS: Record<string, string> = { '/': '⚡', '/graph/wiki': '🕸', '/graph/agent': '🤖', '/assets/': '🖼', '/status': '📊' }
+
+class HubStore {
+    name = ''
+    tools: HubTool[] = []
+    sections: AttentionSection[] | null = null
+    statusMd: string | null = null
+    running = false
+    note = ''
+    error: string | null = null
+
+    constructor() {
+        makeAutoObservable(this)
+    }
+
+    get redCount(): number {
+        return (this.sections ?? []).filter((s) => s.tone === 'red').reduce((n, s) => n + s.lines.length, 0)
+    }
+
+    async load(): Promise<void> {
+        try {
+            const hub = (await (await fetch('/hub.json')).json()) as { name: string; tools: HubTool[] }
+            const att = (await (await fetch('/api/attention.json')).json()) as { sections: AttentionSection[] }
+            runInAction(() => {
+                this.name = hub.name
+                this.tools = hub.tools
+                this.sections = att.sections
+            })
+            if (location.pathname === '/status') {
+                const s = (await (await fetch('/api/status.json')).json()) as { statusMd: string | null }
+                runInAction(() => { this.statusMd = s.statusMd })
+            }
+        } catch (e) {
+            runInAction(() => { this.error = (e as Error).message })
+        }
+    }
+
+    async runCheck(): Promise<void> {
+        this.running = true
+        this.note = 'running…'
+        let text = ''
+        try {
+            const r = await fetch('/status/run', { method: 'POST' })
+            const rd = r.body!.getReader()
+            const dec = new TextDecoder()
+            for (;;) {
+                const { done, value } = await rd.read()
+                if (done) break
+                text += dec.decode(value, { stream: true })
+                runInAction(() => { this.statusMd = text })
+            }
+            runInAction(() => { this.note = 'done — STATUS.md refreshed on disk' })
+            void this.load() // red counts moved — refresh the dashboard data
+        } catch (e) {
+            runInAction(() => {
+                this.statusMd = `${text}\nFAIL stream broke: ${(e as Error).message}`
+                this.note = 'stream broke'
+            })
+        }
+        runInAction(() => { this.running = false })
+    }
+}
+
+const store = new HubStore()
+void store.load()
+
+const Rail = observer(() => {
+    const items = [{ path: '/', label: 'attention', desc: 'everything red' }, ...store.tools.filter((t) => t.path !== '/')]
+    return (
+        <nav className="skrail">
+            {items.map((t) => {
+                const on = location.pathname === t.path || (t.path !== '/' && location.pathname.startsWith(t.path))
+                return (
+                    <a key={t.path} className={on ? 'on' : ''} href={t.path} title={`${t.label} — ${t.desc}`}>
+                        {RAIL_ICONS[t.path] ?? '·'}
+                        {t.path === '/' && store.redCount > 0 ? <i /> : null}
+                    </a>
+                )
+            })}
+        </nav>
+    )
+})
+
+const Attention = observer(() => {
+    const live = (store.sections ?? []).filter((s) => s.lines.length > 0)
+    return (
+        <div className="wrap">
+            <div className="crumb">shipkit hub · attention</div>
+            <h1>{store.name}<small>everything that needs you, one page</small></h1>
+            {store.sections == null ? <div className="sub">loading…</div>
+                : live.length === 0 ? <div className="clear">✅ all clear — nothing needs you</div>
+                : live.map((s) => (
+                    <section key={s.title} className={s.tone}>
+                        <h2>{s.href != null ? <a href={s.href}>{s.title}</a> : s.title}<em>{s.lines.length}</em></h2>
+                        {s.lines.map((l, i) => (
+                            <div key={i} className="line">{l.href != null ? <a href={l.href}>{l.text}</a> : l.text}</div>
+                        ))}
+                    </section>
+                ))}
+            <div className="sub">refreshes on reload · checks refresh via <a href="/status">status → run check</a></div>
+        </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 ''
+}
+
+const Status = observer(() => (
+    <div className="wrap">
+        <div className="crumb">shipkit hub · status</div>
+        <h1>{store.name}<small>STATUS.md</small></h1>
+        <div className="bar">
+            <button disabled={store.running} onClick={() => void store.runCheck()}>run check</button>
+            <span className="note">{store.note !== '' ? store.note : <>shells <code>shipkit check</code>, wire lines stream in below</>}</span>
+        </div>
+        <pre>
+            {(store.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>
+))
+
+const App = observer(() => (
+    <div className="app">
+        <Rail />
+        {store.error != null ? <div className="wrap err">hub api unreachable: {store.error}</div>
+            : location.pathname === '/status' ? <Status /> : <Attention />}
+    </div>
+))
+
+createRoot(document.getElementById('root')!).render(
+    <StrictMode>
+        <App />
+    </StrictMode>,
+)

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

@@ -0,0 +1,41 @@
+/* house palette — matches the studio/graph family. Plain CSS on purpose:
+   a published lib must not impose bunfig plugins (tailwind) on consumers. */
+:root{--bg:#141210;--panel:#1e1a15;--panel2:#262019;--line:#332b22;--ink:#f3ebe0;--dim:#a89a88;
+ --accent:#e88c28;--gold:#ffcf5c;--teal:#58c0b0;--red:#e05252}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.6 system-ui,sans-serif;min-height:100vh}
+.app{display:flex;min-height:100vh}
+.wrap{max-width:900px;margin:0 auto;padding:34px 26px;flex:1}
+h1{font-size:20px;margin:0}
+h1 small{color:var(--dim);font-weight:400;font-size:13px;margin-left:10px}
+.crumb{font-size:12px;letter-spacing:.14em;text-transform:uppercase;color:var(--accent);margin-bottom:6px}
+
+.skrail{position:sticky;top:0;align-self:flex-start;height:100vh;width:46px;display:flex;flex-direction:column;
+ align-items:center;padding-top:10px;gap:4px;background:#17140f;border-right:1px solid var(--line);flex:none}
+.skrail a{display:flex;align-items:center;justify-content:center;width:36px;height:36px;border-radius:9px;
+ font-size:17px;text-decoration:none;border-left:2px solid transparent;filter:grayscale(35%);opacity:.75;position:relative}
+.skrail a:hover{background:var(--panel2);filter:none;opacity:1}
+.skrail a.on{background:var(--panel2);border-left-color:var(--accent);filter:none;opacity:1}
+.skrail a i{position:absolute;top:4px;right:4px;width:8px;height:8px;border-radius:50%;background:var(--red)}
+
+.clear{margin-top:30px;font-size:17px;color:var(--teal)}
+section{background:var(--panel);border:1px solid var(--line);border-left:3px solid var(--gold);border-radius:12px;
+ padding:14px 18px;margin-top:16px}
+section.red{border-left-color:var(--red)}
+h2{font-size:14px;margin:0 0 8px;display:flex;align-items:center;gap:8px}
+h2 a{color:var(--ink);text-decoration:none}h2 a:hover{color:var(--gold)}
+h2 em{font-style:normal;font-size:12px;color:var(--dim);background:var(--panel2);border-radius:8px;padding:1px 8px}
+.line{font:12.5px/1.7 ui-monospace,Menlo,monospace;color:var(--dim);white-space:pre-wrap}
+.line a{color:var(--dim);text-decoration:underline dotted}.line a:hover{color:var(--gold)}
+section.red .line{color:#e8a0a0}
+.sub{margin-top:10px;font-size:12px;color:var(--dim)}
+.sub a{color:var(--dim)}
+
+.bar{display:flex;align-items:center;gap:12px;margin:18px 0 12px}
+button{background:var(--accent);color:#1a1206;border:0;border-radius:9px;padding:8px 14px;font-weight:650;cursor:pointer}
+button:disabled{opacity:.45;cursor:default}
+.note{font-size:12px;color:var(--dim)}
+pre{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:16px;overflow-x:auto;
+ font:12.5px/1.55 ui-monospace,Menlo,monospace;white-space:pre-wrap}
+.ok{color:var(--teal)}.warn{color:var(--gold)}.fail{color:var(--red)}.dim{color:var(--dim)}
+.err{margin-top:26px;color:var(--red)}

package/src/serve/hub-app/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>shipkit hub</title>
+  <link rel="stylesheet" href="./hub.css" />
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="./hub-app.tsx"></script>
+</body>
+</html>

package/src/serve/hub-pages.ts

@@ -1,84 +1,45 @@
-// The hub's two no-build pages (served by serve-hub.ts): the landing page
-// whose links ARE the toolbox, and the /status page (STATUS.md + a
-// "run check" button streaming wire lines). Same style family as the
-// studio: one template string, vanilla JS, no build step, no CDN.
+// Shared hub-page plumbing. The hub UI itself is the Bun-native React app
+// in hub-app/ (HTML import, served by serve-hub.ts — build/webapp
+// doctrine). This module keeps what the LEGACY pages (graph pages, studio
+// SPA) still need until they migrate: the server-injected rail, and the
+// attention section types the collector + React app share.
 import type { HubTool } from './serve-hub.ts'
 
-const esc = (s: string): string => s.replace(/&/g, '&amp;').replace(/</g, '&lt;')
+const esc = (s: string): string => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;')
 
-const SHELL = `
-:root{--bg:#141210;--panel:#1e1a15;--panel2:#262019;--line:#332b22;--ink:#f3ebe0;--dim:#a89a88;
- --accent:#e88c28;--gold:#ffcf5c;--teal:#58c0b0;--red:#e05252}
-*{box-sizing:border-box}
-body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.6 system-ui,sans-serif;min-height:100vh}
-.wrap{max-width:860px;margin:0 auto;padding:40px 24px}
-h1{font-size:20px;margin:0}
-h1 small{color:var(--dim);font-weight:400;font-size:13px;margin-left:10px}
-.crumb{font-size:12px;letter-spacing:.14em;text-transform:uppercase;color:var(--accent);margin-bottom:6px}
-.crumb a{color:var(--accent);text-decoration:none}.crumb a:hover{color:var(--gold)}
-`
+// ── the rail: thin fixed tab bar, injected into legacy hub-served pages ───
+const RAIL_ICONS: Record<string, string> = { '/': '⚡', '/graph/wiki': '🕸', '/graph/agent': '🤖', '/assets/': '🖼', '/status': '📊' }
 
-export function landingPage(o: { name: string; port: number; tools: HubTool[] }): string {
-    const cards = o.tools
-        .map((t) => `<a class=card href="${esc(t.path)}"><b>${esc(t.label)}</b><span>${esc(t.desc)}</span><code>${esc(t.path)}</code></a>`)
-        .join('\n')
-    return `<!doctype html><html><head><meta charset=utf-8>
-<meta name=viewport content="width=device-width,initial-scale=1"><title>${esc(o.name)} · shipkit</title>
-<style>${SHELL}
-.cards{display:grid;grid-template-columns:repeat(auto-fill,minmax(240px,1fr));gap:14px;margin-top:26px}
-.card{display:flex;flex-direction:column;gap:6px;background:var(--panel);border:1px solid var(--line);border-radius:12px;
- padding:16px;text-decoration:none;color:var(--ink)}
-.card:hover{border-color:var(--accent);background:var(--panel2)}
-.card b{font-size:15px}.card span{font-size:13px;color:var(--dim)}
-.card code{font:11px ui-monospace,Menlo,monospace;color:var(--teal)}
-</style></head><body><div class=wrap>
-<div class=crumb>shipkit hub</div>
-<h1>${esc(o.name)}<small>http://localhost:${o.port}</small></h1>
-<div class=cards>
-${cards}
-</div>
-</div></body></html>`
-}
+const RAIL_CSS = `
+.skrail{position:fixed;left:0;top:0;bottom:0;width:46px;z-index:9999;display:flex;flex-direction:column;
+ align-items:center;padding-top:10px;gap:4px;background:#17140f;border-right:1px solid #332b22}
+.skrail a{display:flex;align-items:center;justify-content:center;width:36px;height:36px;border-radius:9px;
+ font-size:17px;text-decoration:none;border-left:2px solid transparent;filter:grayscale(35%);opacity:.75;position:relative}
+.skrail a:hover{background:#262019;filter:none;opacity:1}
+.skrail a.on{background:#262019;border-left-color:#e88c28;filter:none;opacity:1}
+.skrail a i{position:absolute;top:4px;right:4px;width:8px;height:8px;border-radius:50%;background:#e05252}
+body{padding-left:46px}`
 
-export function statusPage(o: { name: string; statusMd: string | null }): string {
-    const body = o.statusMd ?? 'no STATUS.md yet — hit "run check" (or run: shipkit check)'
-    return `<!doctype html><html><head><meta charset=utf-8>
-<meta name=viewport content="width=device-width,initial-scale=1"><title>${esc(o.name)} · status</title>
-<style>${SHELL}
-.bar{display:flex;align-items:center;gap:12px;margin:18px 0 12px}
-button{background:var(--accent);color:#1a1206;border:0;border-radius:9px;padding:8px 14px;font-weight:650;cursor:pointer}
-button:disabled{opacity:.45;cursor:default}
-#note{font-size:12px;color:var(--dim)}
-pre{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:16px;overflow-x:auto;
- font:12.5px/1.55 ui-monospace,Menlo,monospace;white-space:pre-wrap}
-.ok{color:var(--teal)}.warn{color:var(--gold)}.fail{color:var(--red)}.dim{color:var(--dim)}
-</style></head><body><div class=wrap>
-<div class=crumb><a href="/">shipkit hub</a> / status</div>
-<h1>${esc(o.name)}<small>STATUS.md</small></h1>
-<div class=bar><button id=run>run check</button><span id=note>shells <code>shipkit check</code>, wire lines stream in below</span></div>
-<pre id=out></pre>
-<script>
-const out=document.getElementById('out'),btn=document.getElementById('run'),note=document.getElementById('note')
-// wire-line coloring: ok/WARN/FAIL/skip prefixes → the house palette
-const esc=s=>s.replace(/&/g,'&amp;').replace(/</g,'&lt;')
-const cls=l=>{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 ''}
-const paint=text=>{out.innerHTML=text.split('\\n').map(l=>'<span class="'+cls(l)+'">'+esc(l)+'</span>').join('\\n')}
-paint(${JSON.stringify(body).replaceAll('<', '\\u003c')})
-btn.onclick=async()=>{
- btn.disabled=true;note.textContent='running…';let text=''
- try{
-  const r=await fetch('status/run',{method:'POST'})
-  const rd=r.body.getReader(),dec=new TextDecoder()
-  for(;;){const{done,value}=await rd.read();if(done)break;text+=dec.decode(value,{stream:true});paint(text)}
-  note.textContent='done — STATUS.md refreshed on disk'
- }catch(e){text+='\\nFAIL stream broke: '+e;paint(text);note.textContent='stream broke'}
- btn.disabled=false
-}
-</script>
-</div></body></html>`
+/** Inject the rail into a legacy hub-served HTML document (post-<body>,
+ *  fixed position — the page needs no layout knowledge). The React app
+ *  renders its own identical rail from /hub.json. */
+export function withRail(html: string, o: { tools: HubTool[]; active: string }): string {
+    const items = [{ path: '/', label: 'attention', desc: 'everything red' }, ...o.tools.filter((t) => t.path !== '/')]
+        .map((t) => {
+            const on = o.active === t.path || (t.path !== '/' && o.active.startsWith(t.path))
+            const dot = t.path === '/' ? '<i id=skdot style="display:none"></i>' : ''
+            return `<a class="${on ? 'on' : ''}" href="${esc(t.path)}" title="${esc(t.label)} — ${esc(t.desc)}">${RAIL_ICONS[t.path] ?? '·'}${dot}</a>`
+        })
+        .join('')
+    // the red dot fetches client-side: a passive page nav must never run the
+    // attention collector server-side (cost + heal side-effects)
+    const dotScript = `<script>fetch('/api/attention.json').then(r=>r.json()).then(j=>{const n=(j.sections||[]).filter(s=>s.tone==='red').reduce((a,s)=>a+s.lines.length,0);if(n>0)document.getElementById('skdot').style.display=''}).catch(()=>{})</script>`
+    return html.replace(/<body([^>]*)>/, `<body$1><style>${RAIL_CSS}</style><nav class=skrail>${items}</nav>${dotScript}`)
 }
+
+// ── attention data shapes (collector in run-serve, rendering in hub-app) ──
+export type AttentionLine = { text: string; href?: string }
+export type AttentionSection = { title: string; tone: 'red' | 'warn'; lines: AttentionLine[]; href?: string }
+
+export const attentionRedCount = (sections: AttentionSection[]): number =>
+    sections.filter((s) => s.tone === 'red').reduce((n, s) => n + s.lines.length, 0)

package/src/serve/run-serve.ts

@@ -5,14 +5,20 @@
 // kit.ts loads. Port: --port > serve.port > a deterministic house-range
 // default (4800-4979, hashed from the repo name — stable across launches;
 // pin serve.port when two repos collide).
-import { existsSync } from 'fs'
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'
 import { fileURLToPath } from 'url'
-import { loadKit } from '../assets/kit-config.ts'
+import { loadKit, allAssets, type ResolvedKit } from '../assets/kit-config.ts'
+import { isStale } from '../assets/gen/derived.ts'
+import { assetDir, listRolls, readPick } from '../assets/roll-workspace.ts'
+import { healIdentity } from '../assets/run-assets.ts'
 import { page as studioPage } from '../assets/server/studio-page.ts'
 import { studioRoutes, type StudioRoutes } from '../assets/server/studio-server.ts'
-import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
+import { openAsks } from '../asks/asks-queue.ts'
+import { evaluateContracts } from '../contracts/contracts-engine.ts'
+import { activeContracts, contractsConfigFrom, loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { scanMdGraph } from '../wiki/scan-md.ts'
+import type { AttentionSection } from './hub-pages.ts'
 import { serveHub, type HubDeps } from './serve-hub.ts'
 
 export type ServeIo = { print: (l: string) => void; printErr: (l: string) => void }
@@ -32,12 +38,15 @@ export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o
         ? { title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }) }
         : null
     let studio: StudioRoutes | null = null
+    let kit: ResolvedKit | null = null
     if (existsSync(join(root, '.rv-assets/kit.ts'))) {
         // a broken kit must not take the graphs and status down with it —
         // WARN + mount everything else
         try {
-            studio = await studioRoutes({ kit: await loadKit(root), root, page: studioPage })
+            kit = await loadKit(root)
+            studio = await studioRoutes({ kit, root, page: studioPage })
         } catch (e) {
+            kit = null
             io.print(`WARN assets studio not mounted: ${(e as Error).message}`)
         }
     }
@@ -50,6 +59,90 @@ export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o
         agentGraph,
         studio,
         checkCmd: [process.execPath, cli, 'check'],
+        attention: attentionCollector(root, c, kit),
+    }
+}
+
+// the hub must KNOW when it is outdated (field bug 2026-07-22: a morning
+// process served stale code all day, picks looked broken): version read at
+// boot vs on disk per attention load; mismatch = red line telling him to
+// restart the task
+const libVersion = (): string => {
+    try { return (JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8')) as { version?: string }).version ?? '?' } catch { return '?' }
+}
+const BOOT_VERSION = libVersion()
+
+// ── the / dashboard's data: everything red, one collector per source, each
+//    failure-isolated (a broken source reports itself, never blanks the page)
+export function attentionCollector(root: string, c: RepoConfig, kit: ResolvedKit | null): () => Promise<AttentionSection[]> {
+    const guard = async (title: string, tone: 'red' | 'warn', body: () => Promise<AttentionSection['lines']>): Promise<AttentionSection> => {
+        try { return { title, tone, lines: await body() } } catch (e) { return { title, tone: 'red', lines: [{ text: `collector broke: ${(e as Error).message}` }] } }
+    }
+    return async () => {
+        const sections = await Promise.all([
+            guard('hub process', 'red', async () => {
+                const now = libVersion()
+                if (now === BOOT_VERSION) return []
+                return [{ text: `hub is running shipkit ${BOOT_VERSION} but ${now} is on disk (stale process, stale pages, old studio code). Restart the 🚀 shipkit task` }]
+            }),
+            guard('failing checks', 'red', async () => {
+                const p = join(root, 'STATUS.md')
+                if (!existsSync(p)) return []
+                // a cred FAIL whose ask already sits in the asks section is
+                // ONE action shown twice — the ask (his hands) wins
+                const askDir = join(root, c.asks?.dir ?? 'asks')
+                const askText = existsSync(askDir) ? openAsks(askDir).map((a) => a.title.toLowerCase()).join(' ') : ''
+                return (await Bun.file(p).text()).split('\n')
+                    .filter((l) => l.trimStart().startsWith('FAIL'))
+                    .filter((l) => {
+                        const cred = l.match(/cred rv\/([a-z0-9-]+)\/[a-z0-9-]+ missing/)?.[1]
+                        return cred == null || !askText.includes(cred)
+                    })
+                    .map((text) => ({ text, href: '/status' }))
+            }),
+            guard('asks — waiting on you', 'red', async () => {
+                const dir = join(root, c.asks?.dir ?? 'asks')
+                if (!existsSync(dir)) return [] // read path must not mint an asks/ dir
+                return openAsks(dir).map((a) => ({ text: `${a.title}${a.kind !== '' ? ` (${a.kind})` : ''}` }))
+            }),
+            guard('assets', 'red', async () => {
+                // self-heal first: identity re-renders itself on brand.ts
+                // drift; only pick-blocked (taste) surfaces below
+                const idn = await healIdentity(root)
+                const lines: AttentionSection['lines'] = []
+                if (idn.state === 'blocked') lines.push({ text: `identity — ${idn.detail ?? 'blocked'}`, href: '/assets/#identity-logo' })
+                if (kit == null) return lines
+                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'
+                    if (manual && rolls.length === 0) lines.push({ text: `${f.asset.id} — manual, nothing uploaded`, href: `/assets/#${f.asset.id}` })
+                    else if (rolls.length > 0 && (await readPick(dir)).pick == null) lines.push({ text: `${f.asset.id} — ${rolls.length} roll(s), none picked`, href: `/assets/#${f.asset.id}` })
+                    else if (await isStale(kit, join(root, kit.workspace), f)) lines.push({ text: `${f.asset.id} — stale (a parent was re-picked)`, href: `/assets/#${f.asset.id}` })
+                }
+                return lines
+            }),
+            guard('contracts', 'red', async () => {
+                const r = await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root))
+                return r.lines.filter((l) => l.kind === 'fail').map((l) => ({ text: l.text }))
+            }),
+            guard('contract warnings', 'warn', async () => {
+                const r = await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root))
+                return r.lines.filter((l) => l.kind === 'warn').map((l) => ({ text: l.text }))
+            }),
+            guard('posts to write', 'warn', async () => {
+                const social = join(root, '.rv-social')
+                if (!existsSync(social)) return []
+                const lines: AttentionSection['lines'] = []
+                for (const ch of readdirSync(social)) {
+                    const d = join(social, ch)
+                    if (!statSync(d).isDirectory()) continue
+                    for (const f of readdirSync(d).filter((x) => x.endsWith('.md'))) lines.push({ text: `${ch}/${f}` })
+                }
+                return lines
+            }),
+        ])
+        return sections
     }
 }