rvlib-shipkit 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 0.8.0 — 2026-07-22
+
+New:
+
+- `shipkit mv <old.md> <new.md>` in every repo: rename an md page + its
+  sibling asset dir + `<name>.check.ts`, sweeping every tracked file for
+  refs (full path, docs-root id, check filename, boundary-guarded so
+  lookalikes survive). Dry by default, `--write` applies, `--commit` adds
+  one conventional commit behind the repo's pre-commit gate. A repo
+  `mv:after` script (NOT `postmv`, bun npm-compat auto-runs post* names)
+  runs after the moves for repo-specific re-stamps. `movePage` exported.
+  `init` scaffolds the `mv` script; the package.json probe requires it.
+  Upgraders: re-run `shipkit init` (idempotent, only adds the gap).
+- the hub detects its own staleness: lib version read at boot vs on disk
+  per attention load. A mismatched running process shows a red line telling
+  you to restart the task (field bug: a morning process served old studio
+  code all day and a pick looked broken).
+
+## 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 +121,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.8.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,13 +177,14 @@ 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
+        // is the shopping list — build/game-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) {

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/cli/cmd_Mv.ts

@@ -0,0 +1,34 @@
+// shipkit mv — md-page rename with repo-wide ref sweep. Thin clipanion
+// surface; logic in mv/mv-md.ts.
+import { Command, Option } from 'clipanion'
+import { movePage } from '../mv/mv-md.ts'
+
+export class MvCommand extends Command {
+    static override paths = [['mv']]
+
+    static override usage = Command.Usage({
+        category: 'Wiki',
+        description: 'rename an md page + sibling dir + check.ts, sweeping every tracked ref; renames must be CHEAP',
+        examples: [
+            ['dry run (default): show what would change', 'shipkit mv docs/old-name.md docs/new-name.md'],
+            ['apply + one conventional commit', 'shipkit mv docs/old-name.md docs/new-name.md --commit'],
+        ],
+    })
+
+    oldPath = Option.String()
+    newPath = Option.String()
+    write = Option.Boolean('--write', false, { description: 'apply (default is a dry run)' })
+    commit = Option.Boolean('--commit', false, { description: 'apply + git commit (pre-commit hook is the gate)' })
+
+    async execute(): Promise<number> {
+        try {
+            return movePage(process.cwd(), this.oldPath, this.newPath, {
+                print: (l) => this.context.stdout.write(`${l}\n`),
+                printErr: (l) => this.context.stderr.write(`${l}\n`),
+            }, { write: this.write, commit: this.commit })
+        } catch (e) {
+            this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)
+            return 1
+        }
+    }
+}

package/src/cli.ts

@@ -10,6 +10,7 @@ import { CheckCommand } from './cli/cmd_Check.ts'
 import { CiCommand } from './cli/cmd_Ci.ts'
 import { ContractsCommand } from './cli/cmd_Contracts.ts'
 import { InitCommand } from './cli/cmd_Init.ts'
+import { MvCommand } from './cli/cmd_Mv.ts'
 import { ServeCommand } from './cli/cmd_Serve.ts'
 import { TuiCommand } from './cli/cmd_Tui.ts'
 import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
@@ -27,6 +28,7 @@ const cli = new Cli({
 cli.register(Builtins.HelpCommand)
 cli.register(Builtins.VersionCommand)
 cli.register(CiCommand)
+cli.register(MvCommand)
 cli.register(CheckCommand)
 cli.register(TuiCommand)
 cli.register(ServeCommand)