rvlib-shipkit 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # 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):
+
+- `manual()` generator backend — human-provided assets, any media: no
+  Generate button (POST /api/generate 400s; fill/add skip with a visible
+  line; generate-cat excludes them and an all-manual category 400s with an
+  upload pointer — its +N buttons are hidden in the SPA), the studio's
+  upload (button or drag-drop on the roll strip, POST /api/upload multipart,
+  ext-gated per media, seed-style `v<seed>` names — no same-ms overwrite) is
+  the only roll source. Upload itself works on EVERY kind (touched-up
+  images welcome). A manual asset with NO rolls is RED in the sidebar and
+  FAILs `shipkit assets check` with its curation brief; rolls-but-no-pick
+  WARNs. The asset's `prompt` is the brief.
+- `ship.dir` is now honored lib-side: with no via/fn hook, picking copies
+  the roll to `<dir>/<assetId>.<ext>` (zero-config ship); hooks still win
+  and read `dir` as data. Previously `dir` was inert without a repo hook.
+- `media: 'audio'` on kinds — rolls `v<n>.mp3|wav|ogg|m4a`, studio renders
+  players (roll strip, stage, grid card) instead of thumbnails; audio kinds
+  require `manual()` (generation backends are image-only today) and reject
+  geometry panels, both validated loud at defineKit. `isAudioRoll` exported.
+- barrel: `manual`, `mediaOf`, `MEDIA_EXTS`, `isAudioRoll` + types
+  `Media`/`ManualGen` exported.
+
 ## 0.5.0 — 2026-07-22
 
 New (wave 2 of the shipkit expansion — generation UX):
@@ -46,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.5.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,10 +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,18 +10,36 @@ 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
 }
 
 export type ComfyGen = { backend: 'comfy'; workflow?: string; bg?: string }
 export type CanvasGen = { backend: 'canvas'; draw: (ctx: unknown, asset: AssetSpec) => void | Promise<void> }
-export type GeneratorSpec = ComfyGen | CanvasGen
+/** Human-provided assets (any media): the studio's upload mints rolls, a
+ *  manual asset with no rolls is RED + FAILs `shipkit assets check`. The
+ *  asset's `prompt` is the curation brief. */
+export type ManualGen = { backend: 'manual' }
+/** 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'
+/** roll/upload extensions per media — ONE source for the workspace regex,
+ *  the upload route, and the SPA's player-vs-img decision */
+export const MEDIA_EXTS: Record<Media, string[]> = { image: ['webp', 'png'], audio: ['mp3', 'wav', 'ogg', 'm4a'] }
 
 export type GeometryPanelSpec = {
     panel: 'geometry'
@@ -81,10 +99,14 @@ export type Kind = {
     category: string
     assets: AssetSpec[]
     generate: GeneratorSpec
+    /** roll media (default 'image') — audio kinds render players, take no geometry */
+    media?: Media
     /** icon kinds get no geometry, thumbnails only */
     mode?: 'sprite' | 'icon'
     /** via = repo hook module path (default .rv-assets/ship.ts) · fn = a
-     *  built-in lib hook (e.g. identityKinds re-rendering the set) — never both */
+     *  built-in lib hook (e.g. identityKinds re-rendering the set) — never
+     *  both. With NO hook, `dir` alone is the zero-config ship: the picked
+     *  roll is copied to <dir>/<assetId>.<ext>; hooks read dir as data. */
     ship?: { dir?: string; via?: string; fn?: ShipFn }
     meta?: KindMeta
 }
@@ -109,6 +131,15 @@ export function validateKit(k: KitConfig): string[] {
         if (kindIds.has(kind.id)) errs.push(`duplicate kind id '${kind.id}'`)
         kindIds.add(kind.id)
         if (kind.generate?.backend === 'comfy' && k.comfy == null) errs.push(`kind '${kind.id}' uses the comfy backend but the kit has no comfy config`)
+        if (kind.media != null && !(kind.media in MEDIA_EXTS))
+            errs.push(`kind '${kind.id}': unknown media '${String(kind.media)}' (${Object.keys(MEDIA_EXTS).join('/')})`)
+        if (kind.media === 'audio' && kind.generate?.backend !== 'manual')
+            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 ?? []) {
@@ -127,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/roll-workspace.ts

@@ -15,7 +15,9 @@ export const PICK_INIT: PickState = { pick: null, alts: [], shippedAt: null }
 export type PromptOverlay = { prompt: string | null }
 export const PROMPT_INIT: PromptOverlay = { prompt: null }
 
-export const isRollFile = (f: string): boolean => /^v\d+\.(webp|png)$/.test(f)
+// extension list mirrors kit-config MEDIA_EXTS (audio added 0.6.0)
+export const isRollFile = (f: string): boolean => /^v\d+\.(webp|png|mp3|wav|ogg|m4a)$/.test(f)
+export const isAudioRoll = (f: string): boolean => /\.(mp3|wav|ogg|m4a)$/.test(f)
 
 export const assetDir = (workspace: string, assetId: string): string => join(workspace, 'studio', assetId)
 

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++
@@ -65,13 +74,17 @@ export const runAssetsTopUp = (root: string, io: AssetsIo, o: { mode: 'fill' | '
     guarded(io, async () => {
         const kit = await loadKit(root)
         const resolveComfy = comfyFor(root, kit)
-        // canvas AND comfy kinds top up (A30 — canvas kinds draw in-process)
-        const targets = allAssets(kit)
-            .filter((f) => o.categories.length === 0 || o.categories.includes(f.kind.category))
+        // canvas AND comfy kinds top up (A30 — canvas kinds draw in-process);
+        // manual kinds have nothing to generate — visible skip, never silence
+        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`)
+        // 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` : ''}`)
@@ -85,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
     })
 
@@ -133,10 +177,23 @@ 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')
+        let manualBad = 0
+        for (const f of manuals) {
+            const dir = assetDir(join(root, kit.workspace), f.asset.id)
+            const rolls = listRolls(dir)
+            if (rolls.length === 0) { io.print(`FAIL: manual asset '${f.asset.id}' has no file — upload in the studio (brief: ${f.asset.prompt.slice(0, 60)})`); manualBad++ }
+            else if ((await readPick(dir)).pick == null) io.print(`WARN manual asset '${f.asset.id}' has ${rolls.length} file(s), none picked`)
         }
+        bad += manualBad
+        if (manuals.length > 0 && manualBad === 0) io.print(`ok: ${manuals.length} manual asset(s) provided`)
         return bad > 0 ? 1 : 0
     })