rvlib-shipkit 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.7.0 — 2026-07-22
+
+New (the hub becomes THE dashboard; autonomy over nagging):
+
+- hub UI rebuilt as a **Bun-native React app** (Bun.serve + HTML import, no
+  vite, no build step; MobX store). The old template-string landing +
+  status pages are DELETED.
+- `/` IS the **attention dashboard**: failing checks (STATUS.md), open
+  asks, missing/unpicked/stale assets, contract gaps, planned posts — every
+  line links to its owning surface. Data via `/api/attention.json` +
+  `/api/status.json`; sources are failure-isolated (a broken collector
+  reports itself, never blanks the page).
+- a thin left **rail** (⚡🕸🤖🖼📊, active-tab marked, red dot when
+  anything red) on EVERY hub page — React pages natively, legacy pages
+  (graph pages, studio SPA) via server-side injection until they migrate.
+- **derived assets**: `from: ['parentId']` on an AssetSpec + the
+  `gemini({ model? })` backend (plain fetch, key from env GEMINI_API_KEY —
+  unset dies loud). The asset's prompt is the EDIT instruction; parents'
+  PICKED rolls feed generation as context images. Unknown refs, cycles and
+  non-gemini `from` die at defineKit. Each roll records its parent picks in
+  its meta sidecar.
+- **autonomy contract — machine-clearable red clears itself**: re-picking a
+  parent AUTO-enqueues every now-stale child (no button, no nag; spend
+  gated on the intentful pick). Identity self-heals the same way: brand.ts
+  content hash in `.rv-identity/brand.hash`; `assets check` and the
+  attention collector detect drift and RE-RENDER public/* themselves —
+  only a missing pick still reaches a human. The old
+  "WARN outputs missing — run identity" line is gone.
+- fill/add walk parents-first (topo) so derived children never generate
+  before their parents; a blocked derived asset FAILs naming the parent.
+- studio: stale = orange sidebar dot; `/api/state` gains
+  `derived`/`stale` per asset.
+
 ## 0.6.0 — 2026-07-22
 
 New (wave 3 of the shipkit expansion — media + manual assets):
@@ -70,7 +103,7 @@ New (wave 1 of the shipkit expansion — uniform repo setup):
 
 - fix: `react-dom` was missing from dependencies AND the CLI entry loaded
   the react/ink chain eagerly — every command crashed in a fresh consumer
-  repo without react-dom (found by the rabbits-vs-sheeps swap in the field,
+  repo without react-dom (found by a consumer-repo swap in the field,
   confirmed against the 0.3.0 tarball). tui now lazy-loads its body; deps
   carry react-dom. Proven by a fresh-repo install test (init → ci green in
   a react-less repo).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.6.0",
+    "version": "0.7.0",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
     "type": "module",
@@ -20,7 +20,8 @@
     },
     "devDependencies": {
         "@types/bun": "^1.3.14",
-        "@types/react": "^19.2.17"
+        "@types/react": "^19.2.17",
+        "@types/react-dom": "^19.2.3"
     },
     "dependencies": {
         "@napi-rs/canvas": "^1.0.2",

package/src/assets/gen/derived.ts

@@ -0,0 +1,83 @@
+// Derived assets — `from: ['parentId']` on an AssetSpec: the parents'
+// PICKED rolls feed generation as context images; each generated roll
+// records the parent picks in its meta sidecar; a parent re-pick flips
+// children to STALE. Shared by the studio queue and the fill/gen CLI.
+import { join } from 'path'
+import { findAsset, type FoundAsset, type KitConfig } from '../kit-config.ts'
+import { assetDir, listRolls, metaPath, readPick } from '../roll-workspace.ts'
+import { readJson, updateJson } from '../json-store.ts'
+import type { ContextImage } from './gemini-gen.ts'
+
+const MIME: Record<string, string> = { png: 'image/png', webp: 'image/webp' }
+
+export type ParentContext = { images: ContextImage[]; parents: Record<string, string> }
+
+export const parentIdsOf = (f: FoundAsset): string[] => f.asset.from ?? []
+
+/** Parents' picked rolls as base64 context — or the list of blockers
+ *  (unpicked/unknown parents), never a silent partial. */
+export async function resolveParentContext(kit: KitConfig, workspace: string, f: FoundAsset): Promise<ParentContext | { missing: string[] }> {
+    const missing: string[] = []
+    const images: ContextImage[] = []
+    const parents: Record<string, string> = {}
+    for (const id of parentIdsOf(f)) {
+        const parent = findAsset(kit, id)
+        if (parent == null) { missing.push(`${id} (not in kit)`); continue }
+        const dir = assetDir(workspace, id)
+        const pick = (await readPick(dir)).pick
+        if (pick == null) { missing.push(`${id} (no pick)`); continue }
+        const ext = pick.split('.').at(-1)!
+        const file = Bun.file(join(dir, pick))
+        if (!(await file.exists())) { missing.push(`${id} (picked roll ${pick} vanished)`); continue }
+        images.push({ mime: MIME[ext] ?? 'image/png', base64: Buffer.from(await file.arrayBuffer()).toString('base64') })
+        parents[id] = pick
+    }
+    if (missing.length > 0) return { missing }
+    return { images, parents }
+}
+
+/** Stamp the parent picks onto every roll of this seed (v<seed>.*) — called
+ *  after a successful derived generation. */
+export async function recordParents(destDir: string, seed: number, parents: Record<string, string>): Promise<void> {
+    if (Object.keys(parents).length === 0) return
+    for (const roll of listRolls(destDir).filter((r) => r.startsWith(`v${seed}.`) || r.startsWith(`v${seed}-`)))
+        await updateJson<{ parents?: Record<string, string> }>(metaPath(destDir, roll), {}, (m) => { m.parents = parents })
+}
+
+/** A derived asset is STALE when its PICKED roll's recorded parent picks
+ *  differ from the parents' CURRENT picks (or were never recorded). An
+ *  unpicked asset is never stale — it's just unpicked. */
+export async function isStale(kit: KitConfig, workspace: string, f: FoundAsset): Promise<boolean> {
+    const parentIds = parentIdsOf(f)
+    if (parentIds.length === 0) return false
+    const dir = assetDir(workspace, f.asset.id)
+    const pick = (await readPick(dir)).pick
+    if (pick == null) return false
+    const meta = await readJson<{ parents?: Record<string, string> }>(metaPath(dir, pick), {})
+    for (const id of parentIds) {
+        const current = (await readPick(assetDir(workspace, id))).pick
+        if (current == null) continue // parent lost its pick — child can't regen anyway; blocker surfaces at generate
+        if (meta.parents?.[id] !== current) return true
+    }
+    return false
+}
+
+/** Parents-first order for batch generation (fill/add, regen-stale).
+ *  Cycles are rejected at defineKit; a stray one here throws loud. */
+export function topoSort(assets: FoundAsset[]): FoundAsset[] {
+    const byId = new Map(assets.map((f) => [f.asset.id, f]))
+    const done = new Set<string>()
+    const visiting = new Set<string>()
+    const out: FoundAsset[] = []
+    const visit = (f: FoundAsset): void => {
+        if (done.has(f.asset.id)) return
+        if (visiting.has(f.asset.id)) throw new Error(`derived-asset cycle through '${f.asset.id}'`)
+        visiting.add(f.asset.id)
+        for (const id of parentIdsOf(f)) { const p = byId.get(id); if (p != null) visit(p) }
+        visiting.delete(f.asset.id)
+        done.add(f.asset.id)
+        out.push(f)
+    }
+    for (const f of assets) visit(f)
+    return out
+}

package/src/assets/gen/gemini-gen.ts

@@ -0,0 +1,77 @@
+// Gemini image backend — plain fetch, no SDK. THE backend for
+// edit-from-parent flows (context images = parents' picked rolls); comfy
+// stays for from-scratch art. Key from env (default GEMINI_API_KEY) — a
+// missing key dies loud at generation, never silently.
+import { mkdirSync } from 'fs'
+import { join } from 'path'
+
+export type GeminiModel = 'flash' | 'pro'
+export const GEMINI_MODELS: Record<GeminiModel, string> = {
+    flash: 'gemini-2.5-flash-image',
+    pro: 'gemini-3-pro-image-preview',
+}
+
+export type GeminiOpts = {
+    /** env var carrying the API key (default GEMINI_API_KEY) */
+    apiKeyEnv?: string
+    /** test seam / self-host — default the real Google endpoint */
+    host?: string
+}
+
+export type ContextImage = { mime: string; base64: string }
+
+const HOST = 'https://generativelanguage.googleapis.com'
+
+export function geminiKey(o: GeminiOpts): string {
+    const env = o.apiKeyEnv ?? 'GEMINI_API_KEY'
+    const key = process.env[env]
+    if (key == null || key === '')
+        throw new Error(`env ${env} unset — the gemini() backend needs it (mint: aistudio.google.com/apikey, export it in the repo's scripts)`)
+    return key
+}
+
+type GenerateContentResponse = {
+    candidates?: { content?: { parts?: { inlineData?: { mimeType?: string; data?: string }; text?: string }[] } }[]
+    error?: { message?: string }
+}
+
+/** One generation: prompt + context images → image roll(s) saved as
+ *  <destDir>/<name>.png (suffix -2… on multi-image). Returns saved paths. */
+export async function generateGemini(
+    o: GeminiOpts,
+    args: { prompt: string; model?: GeminiModel; destDir: string; name: string; context: ContextImage[] },
+): Promise<string[]> {
+    const key = geminiKey(o)
+    const model = GEMINI_MODELS[args.model ?? 'flash']
+    const res = await fetch(`${o.host ?? HOST}/v1beta/models/${model}:generateContent`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'x-goog-api-key': key },
+        body: JSON.stringify({
+            contents: [{ parts: [{ text: args.prompt }, ...args.context.map((c) => ({ inlineData: { mimeType: c.mime, data: c.base64 } }))] }],
+        }),
+    })
+    if (!res.ok) throw new Error(`gemini ${model} → ${res.status}: ${(await res.text()).slice(0, 200)}`)
+    const body = (await res.json()) as GenerateContentResponse
+    const parts = body.candidates?.[0]?.content?.parts ?? []
+    mkdirSync(args.destDir, { recursive: true })
+    const saved: string[] = []
+    for (const p of parts) {
+        if (p.inlineData?.data == null) continue
+        // roll names must satisfy the workspace regex (v<seed>.png|webp) or
+        // the studio never lists them — an invisible paid roll is the worst
+        // failure mode. Unexpected mimes die loud; extra images get their
+        // own seed-valid names instead of an unlistable -2 suffix.
+        const mime = p.inlineData.mimeType ?? 'image/png'
+        const ext = mime === 'image/webp' ? 'webp' : mime === 'image/png' ? 'png' : null
+        if (ext == null) throw new Error(`gemini returned mime '${mime}' — only png/webp land as rolls (got ${parts.length} part(s))`)
+        const name = saved.length === 0 ? args.name : `v${Math.floor(Math.random() * 2_000_000_000) + 1}`
+        const dest = join(args.destDir, `${name}.${ext}`)
+        await Bun.write(dest, Buffer.from(p.inlineData.data, 'base64'))
+        saved.push(dest)
+    }
+    if (saved.length === 0) {
+        const text = parts.find((p) => p.text != null)?.text?.slice(0, 160)
+        throw new Error(`gemini ${model} returned no image${text != null ? ` — model said: ${text}` : ''} (blocked prompt? wrong model?)`)
+    }
+    return saved
+}

package/src/assets/gen/generate-roll.ts

@@ -8,6 +8,8 @@ import { mkdirSync } from 'fs'
 import { join } from 'path'
 import type { FoundAsset } from '../kit-config.ts'
 import { generate, type OnProgress } from './comfy-gen.ts'
+import { recordParents, type ParentContext } from './derived.ts'
+import { generateGemini } from './gemini-gen.ts'
 import { loadWorkflows, workflowFor, type Workflow } from './workflow-loader.ts'
 
 /** roll canvas master size (square) — favicon/logo/sprites derive from it */
@@ -20,12 +22,21 @@ export type ComfyResolver = () => Promise<ComfyRuntime>
  *  v<seed>.<ext> (comfy). `resolveComfy` is only awaited for comfy backends. */
 export async function generateRoll(
     found: FoundAsset,
-    args: { prompt: string; seed: number; destDir: string; onProgress?: OnProgress },
+    args: { prompt: string; seed: number; destDir: string; onProgress?: OnProgress; context?: ParentContext },
     resolveComfy: ComfyResolver,
 ): Promise<void> {
     const gen = found.kind.generate
     if (gen.backend === 'manual')
         throw new Error(`'${found.asset.id}' is a manual asset — upload a file in the studio (button or drag-drop), nothing generates it`)
+    if (gen.backend === 'gemini') {
+        // derived assets NEED their parents' picked rolls — the caller
+        // resolves them (queue/CLI) so a blocker names the parent, loud
+        if ((found.asset.from?.length ?? 0) > 0 && args.context == null)
+            throw new Error(`'${found.asset.id}' derives from ${found.asset.from!.join(', ')} — parent context missing (are the parents picked?)`)
+        await generateGemini({}, { prompt: args.prompt, model: gen.model, destDir: args.destDir, name: `v${args.seed}`, context: args.context?.images ?? [] })
+        if (args.context != null) await recordParents(args.destDir, args.seed, args.context.parents)
+        return
+    }
     if (gen.backend === 'canvas') {
         const { createCanvas } = await import('@napi-rs/canvas')
         const c = createCanvas(CANVAS_SIZE, CANVAS_SIZE)

package/src/assets/kit-config.ts

@@ -10,9 +10,13 @@ import type { GroundRect } from './panels/geometry-rects.ts'
 
 export type AssetSpec = {
     id: string
-    /** FULL prompt text incl. style — the studio shows/edits exactly what generates */
+    /** FULL prompt text incl. style — the studio shows/edits exactly what
+     *  generates. On a DERIVED asset it is the EDIT instruction. */
     prompt: string
     label?: string
+    /** derived asset: parent asset ids whose PICKED rolls feed generation as
+     *  context images (gemini kinds only). Parent re-pick auto-regens. */
+    from?: string[]
     /** freeform data passed through to the ship hook */
     ship?: unknown
 }
@@ -23,10 +27,13 @@ export type CanvasGen = { backend: 'canvas'; draw: (ctx: unknown, asset: AssetSp
  *  manual asset with no rolls is RED + FAILs `shipkit assets check`. The
  *  asset's `prompt` is the curation brief. */
 export type ManualGen = { backend: 'manual' }
-export type GeneratorSpec = ComfyGen | CanvasGen | ManualGen
+/** Gemini image backend (edit-from-parent flows; comfy stays for from-scratch). */
+export type GeminiGen = { backend: 'gemini'; model?: 'flash' | 'pro' }
+export type GeneratorSpec = ComfyGen | CanvasGen | ManualGen | GeminiGen
 export const comfy = (p?: { workflow?: string; bg?: string }): ComfyGen => ({ backend: 'comfy', workflow: p?.workflow, bg: p?.bg })
 export const canvas = (draw: CanvasGen['draw']): CanvasGen => ({ backend: 'canvas', draw })
 export const manual = (): ManualGen => ({ backend: 'manual' })
+export const gemini = (p?: { model?: 'flash' | 'pro' }): GeminiGen => ({ backend: 'gemini', model: p?.model })
 
 export type Media = 'image' | 'audio'
 export const mediaOf = (kind: Kind): Media => kind.media ?? 'image'
@@ -130,6 +137,9 @@ export function validateKit(k: KitConfig): string[] {
             errs.push(`kind '${kind.id}': media 'audio' supports only the manual() backend today (generation backends are image-only)`)
         if (kind.media === 'audio' && (kind.meta?.panels ?? []).some((p) => p.panel === 'geometry'))
             errs.push(`kind '${kind.id}': audio kinds take no geometry panel`)
+        for (const a of kind.assets ?? [])
+            if ((a.from?.length ?? 0) > 0 && kind.generate?.backend !== 'gemini')
+                errs.push(`kind '${kind.id}': asset '${a.id}' derives (from:) but the backend is '${kind.generate?.backend}' — only gemini() takes context images`)
         if (kind.ship?.fn != null && kind.ship?.via != null) errs.push(`kind '${kind.id}': ship.fn and ship.via are two hooks for one pick — keep one`)
         if (!Array.isArray(kind.assets) || kind.assets.length === 0) errs.push(`kind '${kind.id}' has no assets — a silent no-op kind is a config mistake`)
         for (const a of kind.assets ?? []) {
@@ -148,6 +158,19 @@ export function validateKit(k: KitConfig): string[] {
                 errs.push(`kind '${kind.id}' panel '${p.id}': script must be repo-root-relative without '..' (got '${p.script}')`)
         }
     }
+    // derived-asset graph: every from-ref must exist, and the graph is a DAG
+    const fromOf = new Map<string, string[]>()
+    for (const kind of k.kinds ?? []) for (const a of kind.assets ?? []) fromOf.set(a.id, a.from ?? [])
+    for (const [id, refs] of fromOf) for (const r of refs) if (!fromOf.has(r)) errs.push(`asset '${id}' derives from unknown asset '${r}'`)
+    const state = new Map<string, 'visiting' | 'done'>()
+    const visit = (id: string, path: string[]): void => {
+        if (state.get(id) === 'done') return
+        if (state.get(id) === 'visiting') { errs.push(`derived-asset cycle: ${[...path, id].join(' → ')}`); return }
+        state.set(id, 'visiting')
+        for (const r of fromOf.get(id) ?? []) if (fromOf.has(r)) visit(r, [...path, id])
+        state.set(id, 'done')
+    }
+    for (const id of fromOf.keys()) visit(id, [])
     return errs
 }
 

package/src/assets/run-assets.ts

@@ -5,6 +5,7 @@ import { existsSync } from 'fs'
 import { join, relative } from 'path'
 import { randomSeed } from './gen/comfy-gen.ts'
 import { comfyResolver, generateRoll, type ComfyResolver } from './gen/generate-roll.ts'
+import { parentIdsOf, resolveParentContext, topoSort, type ParentContext } from './gen/derived.ts'
 import { loadWorkflows } from './gen/workflow-loader.ts'
 import { allAssets, findAsset, loadKit, type ResolvedKit } from './kit-config.ts'
 import { NO_PICK_FIX, renderIdentity, type Brand } from './kits/identity-kit.ts'
@@ -28,11 +29,19 @@ async function rollOnce(root: string, io: AssetsIo, kit: ResolvedKit, resolveCom
     if (f == null) die(`unknown asset '${assetId}'`)
     const dir = assetDir(join(root, kit.workspace), assetId)
     const prompt = (await readPromptOverlay(dir)).prompt ?? f!.asset.prompt
+    // derived assets need their parents' picks as context — a blocker names
+    // the parent and fails the whole asset, never a partial
+    let context: ParentContext | undefined
+    if (parentIdsOf(f!).length > 0) {
+        const r = await resolveParentContext(kit, join(root, kit.workspace), f!)
+        if ('missing' in r) { io.printErr(`FAIL: ${assetId} blocked — parents not ready: ${r.missing.join(', ')}`); return count }
+        context = r
+    }
     let failed = 0
     for (let i = 0; i < count; i++) {
         const seed = randomSeed()
         try {
-            await generateRoll(f!, { prompt, seed, destDir: dir }, resolveComfy)
+            await generateRoll(f!, { prompt, seed, destDir: dir, context }, resolveComfy)
             io.print(`ok: ${assetId} v${seed}`)
         } catch (e) {
             failed++
@@ -70,12 +79,12 @@ export const runAssetsTopUp = (root: string, io: AssetsIo, o: { mode: 'fill' | '
         const inScope = allAssets(kit).filter((f) => o.categories.length === 0 || o.categories.includes(f.kind.category))
         const manualCount = inScope.filter((f) => f.kind.generate.backend === 'manual').length
         if (manualCount > 0) io.print(`skip: ${manualCount} manual asset(s) — upload in the studio`)
-        const targets = inScope
-            .filter((f) => f.kind.generate.backend !== 'manual')
+        // topo (parents-first) replaced sparsest-first: derived children need
+        // their parents' rolls to exist before they can ever generate
+        const targets = topoSort(inScope.filter((f) => f.kind.generate.backend !== 'manual'))
             .map((f) => ({ f, have: listRolls(assetDir(join(root, kit.workspace), f.asset.id)).length }))
             .map((t) => ({ ...t, want: o.mode === 'add' ? o.n : Math.max(0, o.n - t.have) }))
             .filter((t) => t.want > 0)
-            .sort((a, b) => a.have - b.have) // sparsest first
         let failed = 0
         for (const t of targets) failed += await rollOnce(root, io, kit, resolveComfy, t.f.asset.id, t.want)
         io.print(`${o.mode}: ${targets.length} asset(s) topped up${failed > 0 ? ` — ${failed} roll(s) FAILED` : ''}`)
@@ -89,26 +98,57 @@ export const runAssetsGen = (root: string, io: AssetsIo, o: { assetId: string; n
         return failed > 0 ? 1 : 0
     })
 
+// ── identity: ONE render path + a brand.ts content hash so drift is
+// machine-detectable — and machine-CLEARED (auto re-render), never a nag.
+// Only a missing PICK still asks a human (taste).
+const brandHashPath = (root: string): string => join(root, '.rv-identity/brand.hash')
+const brandHash = async (root: string): Promise<string> =>
+    new Bun.CryptoHasher('sha256').update(await Bun.file(join(root, '.rv-identity/brand.ts')).text()).digest('hex').slice(0, 16)
+
+export type IdentityRender = { written: string[] } | { blocked: string }
+
+export async function renderIdentityNow(root: string): Promise<IdentityRender> {
+    const brandPath = join(root, '.rv-identity/brand.ts')
+    if (!existsSync(brandPath)) return { blocked: 'no .rv-identity/brand.ts — create one exporting a Brand (name, palette, mark)' }
+    // cache-bust: bun caches dynamic imports for the process lifetime — a
+    // long-running hub must re-render the EDITED brand, not the cached one
+    const mod = (await import(`${brandPath}?v=${await brandHash(root)}`)) as { default?: Brand }
+    if (mod.default == null) return { blocked: '.rv-identity/brand.ts must default-export the Brand' }
+    const brand = mod.default
+    let markFile: string | undefined
+    if (brand.mark.backend === 'comfy') {
+        // comfy marks render from the PICKED identity-logo roll — the kit
+        // owns the workspace where picks live
+        let kit: ResolvedKit
+        try { kit = await loadKit(root) } catch (e) { return { blocked: `comfy mark needs the kit's roll workspace — ${(e as Error).message}` } }
+        const dir = assetDir(join(root, kit.workspace), 'identity-logo')
+        const pick = await readPick(dir)
+        if (pick.pick == null) return { blocked: `brand '${brand.name}' uses a comfy mark and none is picked — ${NO_PICK_FIX}` }
+        markFile = join(dir, pick.pick)
+        if (!existsSync(markFile)) return { blocked: `picked roll ${pick.pick} vanished from ${dir} — re-pick in the studio` }
+    }
+    const written = await renderIdentity(brand, root, { markFile })
+    await Bun.write(brandHashPath(root), (await brandHash(root)) + '\n')
+    return { written }
+}
+
+/** brand.ts drifted since the last render → re-render NOW (autonomous).
+ *  Returns what happened; 'blocked' = only a human pick can clear it. */
+export async function healIdentity(root: string): Promise<{ state: 'fresh' | 'rendered' | 'blocked' | 'absent'; detail?: string }> {
+    if (!existsSync(join(root, '.rv-identity/brand.ts'))) return { state: 'absent' }
+    const outputsMissing = ['public/favicon.png', 'public/og.png', 'public/logo.png'].some((p) => !existsSync(join(root, p)))
+    const stored = existsSync(brandHashPath(root)) ? (await Bun.file(brandHashPath(root)).text()).trim() : null
+    if (!outputsMissing && stored === (await brandHash(root))) return { state: 'fresh' }
+    const r = await renderIdentityNow(root)
+    if ('blocked' in r) return { state: 'blocked', detail: r.blocked }
+    return { state: 'rendered', detail: r.written.join(', ') }
+}
+
 export const runAssetsIdentity = (root: string, io: AssetsIo): Promise<number> =>
     guarded(io, async () => {
-        const brandPath = join(root, '.rv-identity/brand.ts')
-        if (!existsSync(brandPath)) die('no .rv-identity/brand.ts — create one exporting a Brand (name, palette, mark)')
-        const mod = (await import(brandPath)) as { default?: Brand }
-        if (mod.default == null) die('.rv-identity/brand.ts must default-export the Brand')
-        const brand = mod.default!
-        let markFile: string | undefined
-        if (brand.mark.backend === 'comfy') {
-            // comfy marks render from the PICKED identity-logo roll — the kit
-            // owns the workspace where picks live
-            const kit = await loadKit(root).catch((e: Error) => die(`comfy mark needs the kit's roll workspace — ${e.message}`))
-            const dir = assetDir(join(root, kit.workspace), 'identity-logo')
-            const pick = await readPick(dir)
-            if (pick.pick == null) die(`brand '${brand.name}' uses a comfy mark and none is picked — ${NO_PICK_FIX}`)
-            markFile = join(dir, pick.pick!)
-            if (!existsSync(markFile)) die(`picked roll ${pick.pick} vanished from ${dir} — re-pick in the studio`)
-        }
-        const written = await renderIdentity(brand, root, { markFile })
-        for (const w of written) io.print(`ok: ${w}`)
+        const r = await renderIdentityNow(root)
+        if ('blocked' in r) die(r.blocked)
+        for (const w of (r as { written: string[] }).written) io.print(`ok: ${w}`)
         return 0
     })
 
@@ -137,11 +177,12 @@ export const runAssetsCheck = (root: string, io: AssetsIo): Promise<number> =>
             const up = await fetch(`${kit.comfy.host}/system_stats`, { signal: AbortSignal.timeout(3000) }).then((r) => r.ok).catch(() => false)
             io.print(up ? `ok: comfy backend reachable (${kit.comfy.host})` : `WARN comfy backend unreachable (${kit.comfy.host})${kit.comfy.heal != null ? ` — ${kit.comfy.heal}` : ''}`)
         }
-        if (existsSync(join(root, '.rv-identity/brand.ts'))) {
-            const outs = ['public/favicon.png', 'public/og.png', 'public/logo.png'].filter((p) => !existsSync(join(root, p)))
-            if (outs.length > 0) io.print(`WARN identity outputs missing: ${outs.join(', ')} — run: shipkit assets identity`)
-            else io.print('ok: identity outputs present')
-        }
+        // machine-clearable red clears itself: drifted/missing identity
+        // outputs re-render HERE; only a missing pick (taste) reaches a human
+        const idn = await healIdentity(root)
+        if (idn.state === 'fresh') io.print('ok: identity outputs present + brand.ts unchanged')
+        else if (idn.state === 'rendered') io.print(`ok: identity re-rendered (brand.ts changed) — ${idn.detail}`)
+        else if (idn.state === 'blocked') { io.print(`FAIL: identity blocked — ${idn.detail}`); bad++ }
         // manual assets: no rolls = nothing to ship = RED (the missing list
         // is the shopping list — build/audio doctrine); rolls-but-no-pick = WARN
         const manuals = allAssets(kit).filter((f) => f.kind.generate.backend === 'manual')

package/src/assets/server/studio-page.ts

@@ -49,6 +49,7 @@ select,input[type=number]{background:var(--bg);color:var(--ink);border:1px solid
 .vig.gen{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:8px;color:var(--dim);font-size:11px}
 .card .th .spin{position:absolute;top:8px;right:8px}
 .dot.miss{background:#e5484d;border-color:#e5484d}
+.dot.stale{background:#f5a524;border-color:#f5a524}
 .vig.aud{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:6px;font-size:20px}
 .vig.aud audio{width:100%;height:24px}
 .stageaud{display:flex;flex-direction:column;align-items:center;gap:14px;font-size:48px;padding:40px}
@@ -225,7 +226,7 @@ window.addEventListener('hashchange',restoreFromHash)
 function toggleFold(c){openCats.has(c)?openCats.delete(c):openCats.add(c);lastSideSig=null;renderSide(assets)}
 function renderSide(list){
  assets=list;$('#count').textContent=list.length
- const sig=JSON.stringify(list.map(a=>[a.id,a.rolls,a.picked]))+'|'+cur+'|'+catMode+'|'+[...openCats].join(',')+'|'+pending.join(',')
+ const sig=JSON.stringify(list.map(a=>[a.id,a.rolls,a.picked,a.stale]))+'|'+cur+'|'+catMode+'|'+[...openCats].join(',')+'|'+pending.join(',')
  if(sig===lastSideSig&&$('#list').innerHTML!=='')return; lastSideSig=sig
  const cats=[...new Set(list.map(a=>a.cat))]
  $('#list').innerHTML=cats.map(c=>{
@@ -236,7 +237,7 @@ function renderSide(list){
   if(!open)return head
   return head+list.filter(a=>a.cat===c).map(a=>
    '<div class="arow'+(a.id===cur?' sel':'')+'" data-id="'+esc(a.id)+'" onclick="selectAsset(\\''+jsq(a.id)+'\\')"><div class=lb><b>'+esc(a.label)+
-   '</b><span>'+a.rolls+' rolls</span></div>'+(pending.includes(a.id)?'<div class=spin></div>':'<div class="dot '+(a.picked?'done':(a.rolls?'some':(a.manual?'miss':'')))+'"'+(a.manual&&!a.rolls?' title="manual asset — nothing uploaded yet"':'')+'></div>')+'</div>').join('')
+   '</b><span>'+a.rolls+' rolls</span></div>'+(pending.includes(a.id)?'<div class=spin></div>':'<div class="dot '+(a.stale?'stale':(a.picked?'done':(a.rolls?'some':(a.manual?'miss':''))))+'"'+(a.manual&&!a.rolls?' title="manual asset — nothing uploaded yet"':'')+'></div>')+'</div>').join('')
  }).join('')
 }
 // ── per-asset info surface (W2-2): backend, workflow provenance, ship target,

package/src/assets/server/studio-server.ts

@@ -8,6 +8,7 @@ import { existsSync, mkdirSync, unlinkSync } from 'fs'
 import { join, relative } from 'path'
 import { findAsset, allAssets, mediaOf, missingPanelScripts, MEDIA_EXTS, type CustomPanelSpec, type FoundAsset, type GeometryPanelSpec, type ResolvedKit, type ShipFn } from '../kit-config.ts'
 import { interrupt, randomSeed, type OnProgress } from '../gen/comfy-gen.ts'
+import { isStale, parentIdsOf, resolveParentContext, type ParentContext } from '../gen/derived.ts'
 import { generateRoll, type ComfyRuntime } from '../gen/generate-roll.ts'
 import { loadWorkflows, type Workflow } from '../gen/workflow-loader.ts'
 import { alphaHeight, toPng } from '../image-ops.ts'
@@ -20,15 +21,16 @@ export type StudioDeps = {
     kit: ResolvedKit
     root: string
     page: () => string
-    /** test seam — defaults to the comfy engine */
-    generateOne?: (found: FoundAsset, prompt: string, seed: number, destDir: string, onProgress?: OnProgress) => Promise<void>
+    /** test seam — defaults to the real engines. `context` = a derived
+     *  asset's resolved parent picks (queue resolves it at run time) */
+    generateOne?: (found: FoundAsset, prompt: string, seed: number, destDir: string, onProgress?: OnProgress, context?: ParentContext) => Promise<void>
 }
 
 export type Studio = { server: ReturnType<typeof Bun.serve>; queue: StudioQueue; stop: () => void }
 
 // what the studio detail view shows about an asset's plumbing (W2-2)
 export type AssetInfo = {
-    backend: 'canvas' | 'comfy' | 'manual'
+    backend: 'canvas' | 'comfy' | 'manual' | 'gemini'
     /** canvas rolls have no seed input — every roll is identical */
     deterministic: boolean
     /** comfy only: resolved workflow id + its .rv-comfy path (note = why unresolved) */
@@ -100,15 +102,36 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
         if (kit.comfy == null || workflows == null) throw new Error('kit has no comfy config — only canvas kinds can generate')
         return { workflows, host: kit.comfy.host, heal: kit.comfy.heal }
     }
-    const generateOne = deps.generateOne ?? ((found, prompt, seed, destDir, onProgress) =>
-        generateRoll(found, { prompt, seed, destDir, onProgress }, resolveComfy))
+    const generateOne = deps.generateOne ?? ((found, prompt, seed, destDir, onProgress, context?: ParentContext) =>
+        generateRoll(found, { prompt, seed, destDir, onProgress, context }, resolveComfy))
 
     const queue = new StudioQueue(async (job, seed, onProgress) => {
         const found = findAsset(kit, job.assetId)
         if (found == null) throw new Error(`asset '${job.assetId}' not in the kit — job dropped`)
-        await generateOne(found, job.prompt, seed, dirOf(job.assetId), onProgress)
+        // derived assets: parents' picks resolved at RUN time (a pick made
+        // while the job queued is honored); a blocker names the parent
+        let context: ParentContext | undefined
+        if (parentIdsOf(found).length > 0) {
+            const r = await resolveParentContext(kit, workspace, found)
+            if ('missing' in r) throw new Error(`'${job.assetId}' blocked — parents not ready: ${r.missing.join(', ')}`)
+            context = r
+        }
+        await generateOne(found, job.prompt, seed, dirOf(job.assetId), onProgress, context)
     }, randomSeed)
 
+    // machine-clearable red clears itself: re-picking a PARENT auto-enqueues
+    // every now-stale child (1 roll each) — no button, no nag. Generation
+    // spend is gated on the intentful pick, never on passive page loads.
+    const regenStaleChildren = async (parentId: string): Promise<void> => {
+        for (const f of allAssets(kit)) {
+            if (!parentIdsOf(f).includes(parentId)) continue
+            if (!(await isStale(kit, workspace, f))) continue
+            if (queue.pendingIds().includes(f.asset.id)) continue // already queued — never double-spend
+            queue.enqueue([{ assetId: f.asset.id, prompt: await promptOf(f), count: 1 }])
+            console.log(`ok: ${f.asset.id} auto-regen queued (parent '${parentId}' re-picked)`)
+        }
+    }
+
     // ── session/live rect plumbing ─────────────────────────────────────────
     const rectPath = (id: string, roll: string): string => join(dirOf(id), `${roll}.rect.json`)
     const sessionRect = async (f: FoundAsset, roll: string): Promise<GroundRect> => {
@@ -207,6 +230,7 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
                     id: f.asset.id, cat: f.kind.category, label: f.asset.label ?? f.asset.id,
                     prompt: await promptOf(f), rolls: listRolls(dir).length, picked: pick.pick != null,
                     icon: f.kind.mode === 'icon', media: mediaOf(f.kind), manual: f.kind.generate.backend === 'manual',
+                    derived: parentIdsOf(f).length > 0, stale: await isStale(kit, workspace, f),
                 }
             }))
             return json({ ...queue.state, queued: queue.queuedCount, pending: queue.pendingIds(), errors: queue.errors.slice(-5), assets })
@@ -355,6 +379,7 @@ export async function studioRoutes(deps: StudioDeps): Promise<StudioRoutes> {
                     s.pick = name
                     s.shippedAt = res.shipped != null ? new Date().toISOString() : s.shippedAt
                 })
+                void regenStaleChildren(f.asset.id).catch((e: Error) => queue.pushError(`auto-regen after '${f.asset.id}' pick: ${e.message}`))
                 return json(res)
             } catch (e) {
                 queue.pushError(`ship ${String(b.id)}: ${(e as Error).message}`)

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, 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,76 @@ export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o
         agentGraph,
         studio,
         checkCmd: [process.execPath, cli, 'check'],
+        attention: attentionCollector(root, c, kit),
+    }
+}
+
+// ── 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('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
     }
 }
 

package/src/serve/serve-hub.ts

@@ -9,7 +9,11 @@ import { join } from 'path'
 import { graphHtml } from 'rvlib-shipkit/src/wiki/graph-page.ts'
 import type { MdGraph } from 'rvlib-shipkit/src/wiki/md-graph.ts'
 import type { StudioRoutes } from '../assets/server/studio-server.ts'
-import { landingPage, statusPage } from './hub-pages.ts'
+import { withRail, type AttentionSection } from './hub-pages.ts'
+// the hub UI is a Bun-native React app (HTML import, no vite, no build) —
+// build/webapp doctrine; legacy pages (graphs, studio SPA) keep the
+// server-injected rail until they migrate
+import hubIndex from './hub-app/index.html'
 
 export type HubGraph = { title: string; load: () => MdGraph }
 export type HubTool = { path: string; label: string; desc: string }
@@ -25,6 +29,9 @@ export type HubDeps = {
     studio: StudioRoutes | null
     /** argv shelling the check run streamed by /status/run (test seam) */
     checkCmd: string[]
+    /** the / dashboard's data — everything red, gathered per request
+     *  (checks · asks · assets · contracts · posts; run-serve builds it) */
+    attention: () => Promise<AttentionSection[]>
 }
 export type Hub = { server: ReturnType<typeof Bun.serve>; tools: HubTool[]; stop: () => void }
 
@@ -40,24 +47,33 @@ export function hubTools(d: Pick<HubDeps, 'wikiGraph' | 'agentGraph' | 'studio'>
 
 export function serveHub(d: HubDeps): Hub {
     const tools = hubTools(d)
-    const html = (s: string): Response => new Response(s, { headers: { 'content-type': 'text/html; charset=utf-8' } })
+    // every HTML page carries the rail — one keystroke between surfaces;
+    // the red dot self-fetches client-side (no collector on passive navs)
+    const shell = (s: string, active: string): Response =>
+        new Response(withRail(s, { tools, active }), { headers: { 'content-type': 'text/html; charset=utf-8' } })
     const server: ReturnType<typeof Bun.serve> = Bun.serve({
         hostname: '127.0.0.1',
         port: d.port,
+        // / (attention dashboard) and /status are the React app — one HTML
+        // bundle, view picked by pathname client-side
+        routes: { '/': hubIndex, '/status': hubIndex },
         async fetch(req): Promise<Response> {
             const path = new URL(req.url).pathname
-            if (path === '/') return html(landingPage({ name: d.name, port: server.port ?? d.port, tools }))
             // identity probe: lets a second launch tell "same repo, another
             // window" from "a DIFFERENT repo hashed onto my port"
             if (path === '/hub.json') return Response.json({ hub: 'shipkit', name: d.name, tools })
-            if (path === '/graph/wiki') return html(graphHtml(d.wikiGraph.load(), { title: d.wikiGraph.title }))
-            if (path === '/graph/wiki/graph.json') return Response.json(d.wikiGraph.load())
-            if (d.agentGraph != null && path === '/graph/agent') return html(graphHtml(d.agentGraph.load(), { title: d.agentGraph.title }))
-            if (d.agentGraph != null && path === '/graph/agent/graph.json') return Response.json(d.agentGraph.load())
-            if (path === '/status') {
+            if (path === '/api/attention.json') {
+                const sections = await d.attention().catch((e: Error) => [{ title: 'attention collector broke', tone: 'red' as const, lines: [{ text: e.message }] }])
+                return Response.json({ sections })
+            }
+            if (path === '/api/status.json') {
                 const p = join(d.root, 'STATUS.md')
-                return html(statusPage({ name: d.name, statusMd: existsSync(p) ? await Bun.file(p).text() : null }))
+                return Response.json({ statusMd: existsSync(p) ? await Bun.file(p).text() : null })
             }
+            if (path === '/graph/wiki') return shell(graphHtml(d.wikiGraph.load(), { title: d.wikiGraph.title }), path)
+            if (path === '/graph/wiki/graph.json') return Response.json(d.wikiGraph.load())
+            if (d.agentGraph != null && path === '/graph/agent') return shell(graphHtml(d.agentGraph.load(), { title: d.agentGraph.title }), path)
+            if (d.agentGraph != null && path === '/graph/agent/graph.json') return Response.json(d.agentGraph.load())
             if (path === '/status/run' && req.method === 'POST') {
                 // stream wire lines as the check emits them; sh merges stderr
                 // so FAIL lines reach the page, not just the terminal
@@ -68,6 +84,11 @@ export function serveHub(d: HubDeps): Hub {
                 // the studio page fetches RELATIVE urls — it must live under
                 // the slash-terminated prefix for them to resolve
                 if (path === '/assets') return new Response(null, { status: 307, headers: { location: '/assets/' } })
+                if (path === '/assets/' && req.method === 'GET') {
+                    // the SPA document gets the rail too; API routes untouched
+                    const res = await d.studio.handle(req, '/')
+                    return shell(await res.text(), '/assets/')
+                }
                 if (path.startsWith('/assets/')) return d.studio.handle(req, path.slice('/assets'.length))
             }
             return new Response('not found', { status: 404 })

package/src/shipkit.ts

@@ -6,7 +6,8 @@ export type { RepoConfig, ServeConfig, FloorResolution, FloorSource } from './re
 export { serveHub, hubTools } from './serve/serve-hub.ts'
 export type { Hub, HubDeps, HubGraph, HubTool } from './serve/serve-hub.ts'
 export { runServe, resolveHubDeps, defaultHubPort } from './serve/run-serve.ts'
-export { landingPage, statusPage } from './serve/hub-pages.ts'
+export { withRail, attentionRedCount } from './serve/hub-pages.ts'
+export type { AttentionSection, AttentionLine } from './serve/hub-pages.ts'
 export { discoverChecks } from './core/discover-checks.ts'
 export type { DiscoveredCheck } from './core/discover-checks.ts'
 export { runTasks, selectTasks } from './core/task-runner.ts'
@@ -33,8 +34,8 @@ export type { Ask, CreateOpts } from './asks/asks-queue.ts'
 // assets surface (folded in from the standalone atelier lib; that npm
 // package is frozen). A repo's .rv-assets/kit.ts imports defineKit and
 // declares its kinds; `shipkit assets …` derives the rest.
-export { defineKit, defineKind, comfy, canvas, manual, mediaOf, MEDIA_EXTS, geometryPanel, gridPanel, customPanel, validateKit, missingPanelScripts, loadKit, findAsset, allAssets, categoriesOf } from './assets/kit-config.ts'
-export type { KitConfig, ResolvedKit, Kind, KindMeta, Media, AssetSpec, GeneratorSpec, ComfyGen, CanvasGen, ManualGen, PanelSpec, GeometryPanelSpec, GridPanelSpec, CustomPanelSpec, FoundAsset, ShipContext, ShipFn } from './assets/kit-config.ts'
+export { defineKit, defineKind, comfy, canvas, manual, gemini, mediaOf, MEDIA_EXTS, geometryPanel, gridPanel, customPanel, validateKit, missingPanelScripts, loadKit, findAsset, allAssets, categoriesOf } from './assets/kit-config.ts'
+export type { KitConfig, ResolvedKit, Kind, KindMeta, Media, AssetSpec, GeneratorSpec, ComfyGen, CanvasGen, ManualGen, GeminiGen, PanelSpec, GeometryPanelSpec, GridPanelSpec, CustomPanelSpec, FoundAsset, ShipContext, ShipFn } from './assets/kit-config.ts'
 export { identityKinds, renderIdentity, renderIdentityFromMark, NO_PICK_FIX, FAVICON_SIZE, OG_W, OG_H, LOGO_SIZE } from './assets/kits/identity-kit.ts'
 export type { Brand } from './assets/kits/identity-kit.ts'
 export { serveStudio, studioRoutes } from './assets/server/studio-server.ts'