rvlib-shipkit 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 0.11.0 — 2026-07-23
+
+The needs feed: the hub's `/` now answers "what needs a human right now,
+artifact in hand".
+
+New:
+
+- Collection model (`src/collections/`): every curatable surface projects
+  through one interface — media kinds, asks, missing declared secrets
+  (mint artifact + `credsCommand` store template as config data), repo
+  health, social posts. `projectNeeds` is failure-isolated per collection.
+- `shipkit needs [--json]`: the feed as a CLI — red/yellow by collection,
+  REPORT-ONLY (exit 0 always; `check`/`ci` stay the gates).
+- Hub `/` = the needs feed: act-in-place tiles (copy buttons for briefs/
+  commands/post text, mint links, done + proof-URL inputs, draft pick
+  buttons), reds-only toggle, `/api/needs.json` + `/api/act/*` (every
+  mutation hits a git-tracked truth file).
+- RED-only pings while the hub serves: one batched notification per tick
+  of NEW red items (`notifyCommand` template + macOS notification).
+  Once-ever per item: cache file for non-ask items, the ask file's own
+  `pinged:` field for asks. Yellow never pings.
+- Social posts contract v2: slug-only files, variants (`<slug>.a.md`) as
+  drafts-as-rolls (pick flips siblings to rejected, files kept),
+  frontmatter kind/tone/status/posted/rating, `## Angle` / `## Post` /
+  `## Feedback` sections — the copy button pastes ONLY `## Post`;
+  feedback appends are non-destructive.
+- Missing manual media tiles carry their brief as the copy artifact.
+
+Breaking (0.10.x consumers):
+
+- `/api/attention.json` → `/api/needs.json` (NeedItem[] — flat, severity
+  red|yellow); `attentionRedCount`/`AttentionSection`/`AttentionLine`
+  exports removed (use `redCount`/`NeedItem`/`Instance`). Unpicked-roll
+  and stale assets are now YELLOW (taste pending — a default ships), no
+  longer red.
+- `.rv-social` post files: `status:` frontmatter is required (missing =
+  a red feed item); v1 vocab maps idea→draft, ready→picked, link→posted.
+
+## 0.10.0 — 2026-07-22
+
+New:
+
+- `shipkit start`: `--include` is now repeatable — every given line is
+  ensured in CLAUDE.md, in order, inserted after any leading include lines
+  already present (never double-added; `--also-ok` satisfies the first
+  include).
+
+Fixed:
+
+- md graph scanner: a backticked/arrow token carrying the scan root's own
+  dir name (`agent/architecture.md` while scanning `agent/`) now resolves —
+  routing tables written repo-root-relative finally produce edges.
+
 ## 0.9.0 — 2026-07-22
 
 New:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.9.0",
+    "version": "0.11.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",

package/src/asks/asks-queue.ts

@@ -99,6 +99,40 @@ ${whyBlock}**Answer**: _(fill in / check off, or just do it — the check probe
     return file
 }
 
+/** flip an ask to done and archive it (the hub's "done" verb) */
+export function archiveAsk(dir: string, file: string): void {
+    const p = join(dir, file)
+    if (!existsSync(p)) throw new Error(`no such ask: ${file}`)
+    const md = readFileSync(p, 'utf8').replace(/^status:.*$/m, `status: done\nclosed: ${new Date().toISOString().slice(0, 10)}`)
+    writeFileSync(p, md)
+    const done = join(dir, 'done')
+    mkdirSync(done, { recursive: true })
+    renameSync(p, join(done, file))
+}
+
+/** record the completion proof (human-loop: URL back = done), then archive */
+export function proofAsk(dir: string, file: string, url: string): void {
+    const p = join(dir, file)
+    if (!existsSync(p)) throw new Error(`no such ask: ${file}`)
+    writeFileSync(p, `${readFileSync(p, 'utf8').trimEnd()}\n\n**Proof**: ${url}\n`)
+    archiveAsk(dir, file)
+}
+
+/** once-ever ping marker, shared with every ping path (notify doctrine):
+ *  returns false when the ask was already pinged — never double-fire */
+export function markPinged(dir: string, file: string): boolean {
+    const p = join(dir, file)
+    if (!existsSync(p)) return false
+    const md = readFileSync(p, 'utf8')
+    if (/^pinged:/m.test(md)) return false
+    const line = `pinged: ${new Date().toISOString().slice(0, 10)}`
+    const withMark = md.replace(/^status:(.*)$/m, `status:$1\n${line}`)
+    // a hand-edited ask without status: still gets a durable marker — a
+    // no-op write here would re-fire the ping every tick forever
+    writeFileSync(p, withMark !== md ? withMark : `${line}\n${md}`)
+    return true
+}
+
 export function renderAsksTable(dir: string, print: (line: string) => void = console.log, opts?: { emptyText?: string }): number {
     const open = openAsks(dir)
     if (open.length === 0) { print(opts?.emptyText ?? 'no open asks — all caught up 🎉'); return 0 }

package/src/cli/cmd_Needs.ts

@@ -0,0 +1,47 @@
+// shipkit needs — the needs feed as a CLI: everything blocked on a human,
+// red/yellow, grouped by collection. REPORT-ONLY: exit 0 always — `check`
+// and `ci` stay the gates. Thin clipanion surface; logic in collections/.
+import { Command, Option } from 'clipanion'
+import { loadKit } from '../assets/kit-config.ts'
+import { projectNeeds } from '../collections/collection-types.ts'
+import { buildCollections } from '../collections/providers.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+
+export class NeedsCommand extends Command {
+    static override paths = [['needs']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'everything blocked on a human, red/yellow by collection — report-only, exit 0 always (check/ci are the gates)',
+        examples: [
+            ['what needs me', 'shipkit needs'],
+            ['machine-readable (agents, drills, cross-repo rollups)', 'shipkit needs --json'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'emit NeedItem[] JSON' })
+
+    async execute(): Promise<number> {
+        const root = process.cwd()
+        const c = await loadRepoConfig(root)
+        const kit = await loadKit(root).catch(() => null)
+        const needs = await projectNeeds(buildCollections(root, c, kit))
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify(needs, null, 2)}\n`)
+            return 0
+        }
+        if (needs.length === 0) {
+            this.context.stdout.write('ok: nothing needs you\n')
+            return 0
+        }
+        for (const n of needs) {
+            const line = `${n.severity === 'red' ? 'red:   ' : 'yellow:'} [${n.collection}] ${n.text}`
+            this.context.stdout.write(`${line}\n`)
+            if (n.artifact?.copy != null) this.context.stdout.write(`        paste: ${n.artifact.copy}\n`)
+            if (n.artifact?.url != null) this.context.stdout.write(`        mint:  ${n.artifact.url}\n`)
+        }
+        const reds = needs.filter((n) => n.severity === 'red').length
+        this.context.stdout.write(`${reds} red · ${needs.length - reds} yellow\n`)
+        return 0
+    }
+}

package/src/cli/cmd_Start.ts

@@ -12,14 +12,14 @@ export class StartCommand extends Command {
         description: 'ensure <root>/<name> exists, optionally with a CLAUDE.md include line; prints the dir on stdout so a shell alias can cd there',
         examples: [
             ['start (or enter) a repo', 'shipkit start pong'],
-            ['seed CLAUDE.md line 1', "shipkit start pong --include '@~/wiki/index.md'"],
+            ['seed CLAUDE.md includes', "shipkit start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],
         ],
     })
 
     name = Option.String()
     root = Option.String('--root', { description: 'parent dir for repos (default ~/dev)' })
-    include = Option.String('--include', { description: 'line CLAUDE.md must start with; omitted = only ensure the dir' })
-    alsoOk = Option.Array('--also-ok', { description: 'alternative lines that already count as wired — never double-add' })
+    include = Option.Array('--include', { description: 'line CLAUDE.md must carry, repeatable, order kept; omitted = only ensure the dir' })
+    alsoOk = Option.Array('--also-ok', { description: 'alternative lines satisfying the first --include — never double-add' })
     skip = Option.Array('--skip', { description: 'repo names that never get the include' })
 
     async execute(): Promise<number> {

package/src/cli.ts

@@ -11,6 +11,7 @@ import { CiCommand } from './cli/cmd_Ci.ts'
 import { ContractsCommand } from './cli/cmd_Contracts.ts'
 import { InitCommand } from './cli/cmd_Init.ts'
 import { MvCommand } from './cli/cmd_Mv.ts'
+import { NeedsCommand } from './cli/cmd_Needs.ts'
 import { ServeCommand } from './cli/cmd_Serve.ts'
 import { StartCommand } from './cli/cmd_Start.ts'
 import { TuiCommand } from './cli/cmd_Tui.ts'
@@ -47,5 +48,6 @@ cli.register(AssetsIdentityCommand)
 cli.register(AssetsCheckCommand)
 cli.register(InitCommand)
 cli.register(StartCommand)
+cli.register(NeedsCommand)
 
 cli.runExit(process.argv.slice(2))

package/src/collections/actions.ts

@@ -0,0 +1,66 @@
+// Act-in-place verbs behind the hub feed — every mutation targets a
+// git-tracked truth file (studio pick-flow precedent: the hub writes, the
+// repo's diff shows it; Feedback appends are append-only, never destructive).
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { archiveAsk, proofAsk } from '../asks/asks-queue.ts'
+import { parsePostFile } from './posts.ts'
+
+const today = (): string => new Date().toISOString().slice(0, 10)
+
+const postPath = (root: string, channel: string, file: string): string => {
+    if (channel.includes('/') || channel.includes('..') || file.includes('/') || file.includes('..')) throw new Error('bad path')
+    const p = join(root, '.rv-social', channel, file)
+    if (!existsSync(p)) throw new Error(`no such post: ${channel}/${file}`)
+    return p
+}
+
+const setStatus = (p: string, status: string): void => {
+    const md = readFileSync(p, 'utf8')
+    if (!/^status:/m.test(md)) throw new Error('post has no status: frontmatter')
+    writeFileSync(p, md.replace(/^status:.*$/m, `status: ${status}`))
+}
+
+/** pick one draft variant: it flips to picked, sibling drafts to rejected
+ *  (files KEPT — rejections are training data for the next generation) */
+export function pickPostVariant(root: string, channel: string, file: string): void {
+    const p = postPath(root, channel, file)
+    const dir = join(root, '.rv-social', channel)
+    const slug = parsePostFile(dir, channel, file).slug
+    setStatus(p, 'picked')
+    for (const f of readdirSync(dir).filter((x) => x.endsWith('.md') && x !== file)) {
+        const sib = parsePostFile(dir, channel, f)
+        if (sib.slug === slug && sib.status === 'draft') setStatus(join(dir, f), 'rejected')
+    }
+}
+
+/** the posted-URL proof: status → posted, `posted:` frontmatter carries the URL */
+export function markPosted(root: string, channel: string, file: string, url: string, rating?: number): void {
+    const p = postPath(root, channel, file)
+    setStatus(p, 'posted')
+    const md = readFileSync(p, 'utf8')
+    const withUrl = /^posted:/m.test(md) ? md.replace(/^posted:.*$/m, `posted: ${url}`) : md.replace(/^status:.*$/m, (s) => `${s}\nposted: ${url}`)
+    const withRating = rating != null
+        ? (/^rating:/m.test(withUrl) ? withUrl.replace(/^rating:.*$/m, `rating: ${rating}`) : withUrl.replace(/^posted:.*$/m, (s) => `${s}\nrating: ${rating}`))
+        : withUrl
+    writeFileSync(p, withRating)
+}
+
+/** append a dated remark under ## Feedback (created if absent) — NEVER
+ *  destructive; future generations re-read these before drafting */
+export function appendPostFeedback(root: string, channel: string, file: string, text: string): void {
+    const p = postPath(root, channel, file)
+    const md = readFileSync(p, 'utf8')
+    const line = `- ${today()}: ${text.replace(/\n+/g, ' ').trim()}`
+    writeFileSync(p, /^## Feedback\s*$/m.test(md) ? `${md.trimEnd()}\n${line}\n` : `${md.trimEnd()}\n\n## Feedback\n${line}\n`)
+}
+
+export function askDone(root: string, asksDir: string, file: string): void {
+    if (file.includes('/') || file.includes('..')) throw new Error('bad path')
+    archiveAsk(join(root, asksDir), file)
+}
+
+export function askProof(root: string, asksDir: string, file: string, url: string): void {
+    if (file.includes('/') || file.includes('..')) throw new Error('bad path')
+    proofAsk(join(root, asksDir), file, url)
+}

package/src/collections/collection-types.ts

@@ -0,0 +1,52 @@
+// The collection model: every curatable surface (media kinds, asks, creds,
+// repo health, posts) projects through ONE interface into the hub's needs
+// feed, the studio browse, and `shipkit needs`. Truth files never move to
+// fit the UI — a Collection only READS its source. Severity: yellow = a
+// default is in use, taste pending; red = missing with no inventable
+// default, or a paste-from-elsewhere. Doctrine page: build/collections in
+// the docs wiki this lib ships beside.
+
+export type NeedSeverity = 'red' | 'yellow'
+
+export type CurationVerb = 'pick' | 'approve' | 'rate' | 'provide' | 'paste-proof' | 'set' | 'done' | 'archive'
+
+export type Instance = {
+    id: string
+    /** one-line human text — the feed line */
+    text: string
+    /** absent = healthy, nothing needed */
+    severity?: NeedSeverity
+    /** deep link (studio anchor, /status, external editor) */
+    href?: string
+    /** paste-ready artifact: exact command/text to copy + optional steps */
+    artifact?: { copy?: string; url?: string; steps?: string[] }
+    verbs?: CurationVerb[]
+    /** roll-strip analog: pickable variants (post drafts, rolls) */
+    candidates?: { id: string; label: string; hint?: string }[]
+}
+
+export type Collection = {
+    id: string
+    title: string
+    media: 'image' | 'audio' | 'text' | 'data' | 'pointer' | 'health'
+    /** wire tone when any needing instance is only yellow */
+    list: () => Promise<Instance[]>
+}
+
+export type NeedItem = Instance & { collection: string }
+
+/** the flat needs projection — failure-isolated per collection: a broken
+ *  source reports itself as ONE red item, never blanks the feed */
+export async function projectNeeds(collections: Collection[]): Promise<NeedItem[]> {
+    const out: NeedItem[] = []
+    for (const c of collections) {
+        try {
+            for (const i of await c.list()) if (i.severity != null) out.push({ ...i, collection: c.id })
+        } catch (e) {
+            out.push({ collection: c.id, id: `${c.id}:broken`, text: `collector broke: ${(e as Error).message}`, severity: 'red' })
+        }
+    }
+    return out
+}
+
+export const redCount = (needs: NeedItem[]): number => needs.filter((n) => n.severity === 'red').length

package/src/collections/pings.ts

@@ -0,0 +1,68 @@
+// RED-item pings — one batched notification per burst of NEW red needs.
+// Yellow (taste debt) NEVER pings: that would be progress spam. Stateful by
+// design: last-pinged ids persist in node_modules/.cache/shipkit (always
+// gitignored territory); a repo without node_modules gets NO pings rather
+// than re-fired backlogs (no persistence = no dedup = stay silent). For
+// ask-backed items the marker is the ask file's own `pinged:` field — the
+// SAME once-ever guarantee every other ping path uses.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { markPinged } from '../asks/asks-queue.ts'
+import type { NeedItem } from './collection-types.ts'
+
+export type PingIo = {
+    /** run a notify command — injectable for tests */
+    run: (cmd: string[]) => void
+    /** repo.config notifyCommand template, `{message}` substituted */
+    notifyCommand?: string
+    /** additive desktop notification on macOS */
+    osascript?: boolean
+}
+
+const stateDir = (root: string): string | null => (existsSync(join(root, 'node_modules')) ? join(root, 'node_modules', '.cache', 'shipkit') : null)
+
+const loadPinged = (root: string): Set<string> | null => {
+    const dir = stateDir(root)
+    if (dir == null) return null
+    try {
+        return new Set(JSON.parse(readFileSync(join(dir, 'pinged.json'), 'utf8')) as string[])
+    } catch {
+        return new Set()
+    }
+}
+
+const savePinged = (root: string, ids: Set<string>): void => {
+    const dir = stateDir(root)
+    if (dir == null) return
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(join(dir, 'pinged.json'), JSON.stringify([...ids].sort()))
+}
+
+/** one tick: ping ONCE for the batch of never-pinged red items, mark them.
+ *  Returns the pinged ids (empty = silence). */
+export function pingTick(root: string, asksDir: string, needs: NeedItem[], io: PingIo): string[] {
+    const pinged = loadPinged(root)
+    if (pinged == null) return [] // no persistence, no pings — never re-fire a backlog
+    const fresh: NeedItem[] = []
+    for (const n of needs) {
+        if (n.severity !== 'red') continue
+        if (n.collection === 'asks') {
+            // ask file owns the once-ever marker (shared with agent pings)
+            const file = n.id.replace(/^ask:/, '')
+            if (markPinged(join(root, asksDir), file)) fresh.push(n)
+        } else if (!pinged.has(n.id)) {
+            pinged.add(n.id)
+            fresh.push(n)
+        }
+    }
+    savePinged(root, pinged)
+    if (fresh.length === 0) return []
+    const head = fresh.slice(0, 3).map((n) => n.text.slice(0, 80)).join(' · ')
+    const message = `${fresh.length} new item(s) need you: ${head}${fresh.length > 3 ? ' · …' : ''}`
+    // item texts come from repo data — strip shell-active chars before the template substitution
+    const safe = message.replace(/[`$\\'"]/g, '')
+    if (io.notifyCommand != null) io.run(['sh', '-c', io.notifyCommand.replaceAll('{message}', safe)])
+    if (io.osascript !== false && process.platform === 'darwin')
+        io.run(['osascript', '-e', `display notification ${JSON.stringify(message)} with title "shipkit needs"`])
+    return fresh.map((n) => n.id)
+}

package/src/collections/posts.ts

@@ -0,0 +1,106 @@
+// social-posts collection — projects `.rv-social/<channel>/` post files
+// (contract v2) into the needs feed. Status-aware: rejected/posted history
+// stays on disk as training data and never floods the feed. Drafts-as-rolls:
+// variants are sibling files `<slug>.a.md`, `<slug>.b.md`; picking one flips
+// it to picked and the others to rejected (files KEPT). Severities:
+//   any file missing `status:` → red (metadata with no inventable default)
+//   drafts awaiting a pick     → yellow (his taste)
+//   picked but not posted      → red (paste-from-elsewhere: post + URL proof)
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+import type { Collection, Instance } from './collection-types.ts'
+
+export type PostFile = {
+    channel: string
+    file: string
+    slug: string
+    variant: string | null
+    status: 'draft' | 'picked' | 'posted' | 'rejected' | null
+    kind: string | null
+    posted: string | null
+    body: string
+}
+
+const fm = (md: string, key: string): string | null => md.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))?.[1]?.trim() ?? null
+
+/** the paste-ready text: the `## Post` section body (Angle/Feedback never leak into the paste) */
+export const postSection = (md: string): string => md.match(/^## Post\s*\n([\s\S]*?)(?=^## |\s*$(?![\s\S]))/m)?.[1]?.trim() ?? ''
+
+export function parsePostFile(dir: string, channel: string, file: string): PostFile {
+    const md = readFileSync(join(dir, file), 'utf8')
+    const m = file.match(/^(.*?)(?:\.([a-z]))?\.md$/)
+    const status = fm(md, 'status')
+    return {
+        channel,
+        file,
+        slug: m?.[1] ?? file,
+        variant: m?.[2] ?? null,
+        status: status === 'draft' || status === 'picked' || status === 'posted' || status === 'rejected' ? status : null,
+        kind: fm(md, 'kind'),
+        posted: fm(md, 'posted'),
+        body: md,
+    }
+}
+
+export function listPosts(root: string): PostFile[] {
+    const social = join(root, '.rv-social')
+    if (!existsSync(social)) return []
+    const out: PostFile[] = []
+    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')).sort()) out.push(parsePostFile(d, ch, f))
+    }
+    return out
+}
+
+export function socialPostsCollection(root: string): Collection {
+    return {
+        id: 'posts',
+        title: 'posts',
+        media: 'text',
+        list: async () => {
+            const bySlug = new Map<string, PostFile[]>()
+            for (const p of listPosts(root)) {
+                const key = `${p.channel}/${p.slug}`
+                bySlug.set(key, [...(bySlug.get(key) ?? []), p])
+            }
+            const out: Instance[] = []
+            for (const [key, variants] of bySlug) {
+                const missing = variants.filter((v) => v.status == null)
+                if (missing.length > 0) {
+                    out.push({
+                        id: `post:${key}:invalid`,
+                        text: `${key} — missing/invalid status: frontmatter (${missing.map((v) => v.file).join(', ')})`,
+                        severity: 'red',
+                    })
+                    continue
+                }
+                const picked = variants.find((v) => v.status === 'picked')
+                if (picked != null) {
+                    out.push({
+                        id: `post:${key}:topost`,
+                        text: `${key} — picked, waiting to be POSTED (copy → post → paste the URL)`,
+                        severity: 'red',
+                        artifact: { copy: postSection(picked.body) },
+                        verbs: ['paste-proof', 'rate'],
+                        candidates: [{ id: picked.file, label: picked.variant ?? 'post' }],
+                    })
+                    continue
+                }
+                const drafts = variants.filter((v) => v.status === 'draft')
+                if (drafts.length > 0) {
+                    out.push({
+                        id: `post:${key}:pick`,
+                        text: `${key} — ${drafts.length} draft(s), pick one`,
+                        severity: 'yellow',
+                        verbs: ['pick', 'rate'],
+                        candidates: drafts.map((v) => ({ id: v.file, label: v.variant ?? 'draft', hint: postSection(v.body).slice(0, 200) })),
+                    })
+                }
+                // posted / rejected-only: quiet — history is training data, not attention
+            }
+            return out
+        },
+    }
+}

package/src/collections/providers.ts

@@ -0,0 +1,162 @@
+// The built-in collection providers — each one REPLACED an attentionCollector
+// guard (the collector is gone; never reintroduce a parallel projection).
+// Behaviors preserved by name: per-source failure isolation (projectNeeds
+// guards per collection), cred-FAIL↔ask dedup, the identity self-heal
+// before surfacing, and the asks READ path never minting asks/ on a repo
+// without one. Dedup chain for one real-world action:
+// ask > cred-instance > health-line.
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { isStale } from '../assets/gen/derived.ts'
+import { allAssets, type ResolvedKit } from '../assets/kit-config.ts'
+import { assetDir, listRolls, readPick } from '../assets/roll-workspace.ts'
+import { healIdentity } from '../assets/run-assets.ts'
+import { openAsks } from '../asks/asks-queue.ts'
+import { evaluateContracts } from '../contracts/contracts-engine.ts'
+import { activeContracts, contractsConfigFrom, type RepoConfig } from '../repo-config.ts'
+import type { Collection, Instance } from './collection-types.ts'
+import { socialPostsCollection } from './posts.ts'
+
+const askDirOf = (root: string, c: RepoConfig): string => join(root, c.asks?.dir ?? 'asks')
+// read path must not mint an asks/ dir (listAsks mkdirs on read)
+const openAsksSafe = (root: string, c: RepoConfig): ReturnType<typeof openAsks> => {
+    const dir = askDirOf(root, c)
+    return existsSync(dir) ? openAsks(dir) : []
+}
+
+const CRED_LINE = /cred ([a-z0-9-]+\/[a-z0-9-]+\/[a-z0-9-]+) missing/
+
+export function asksCollection(root: string, c: RepoConfig): Collection {
+    return {
+        id: 'asks',
+        title: 'asks — waiting on you',
+        media: 'text',
+        list: async () =>
+            openAsksSafe(root, c).map((a) => ({
+                id: `ask:${a.file}`,
+                text: `${a.title}${a.kind !== '' ? ` (${a.kind})` : ''}`,
+                severity: 'red' as const,
+                verbs: ['done' as const, 'paste-proof' as const],
+            })),
+    }
+}
+
+/** repo-declared secrets (repo.config `creds:`) + cred FAIL lines from
+ *  STATUS.md — the tile carries the mint artifact as data. Skips any secret
+ *  covered by an open ask (the ask wins: his hands, one surface). */
+export function credsCollection(root: string, c: RepoConfig): Collection {
+    return {
+        id: 'creds',
+        title: 'missing secrets',
+        media: 'pointer',
+        list: async () => {
+            const askText = openAsksSafe(root, c).map((a) => a.title.toLowerCase()).join(' ')
+            const covered = (name: string): boolean => askText.includes(name.split('/')[1] ?? name)
+            const out: Instance[] = []
+            const seen = new Set<string>()
+            const statusPath = join(root, 'STATUS.md')
+            const statusCreds = existsSync(statusPath)
+                ? readFileSync(statusPath, 'utf8')
+                      .split('\n')
+                      .filter((l) => l.trimStart().startsWith('FAIL')) // only a FAIL probe proves missing — a WARN/narrative mention never reds
+                      .map((l) => l.match(CRED_LINE)?.[1])
+                      .filter((n): n is string => n != null)
+                : []
+            for (const name of statusCreds) {
+                if (seen.has(name) || covered(name)) continue
+                seen.add(name)
+                const decl = (c.creds ?? []).find((d) => d.name === name)
+                out.push(credInstance(name, c.credsCommand, decl))
+            }
+            // declared-but-not-probed creds stay quiet: only a STATUS.md
+            // probe line proves "missing" — declaration alone never reds
+            return out
+        },
+    }
+}
+
+// the store command is repo config DATA (`credsCommand` template) — the lib
+// never names any particular secret manager
+const credInstance = (name: string, cmdTemplate: string | undefined, decl?: { service?: string; mintUrl?: string; steps?: string[] }): Instance => ({
+    id: `cred:${name}`,
+    text: `${name} missing${decl?.service != null ? ` — ${decl.service}` : ''}`,
+    severity: 'red',
+    artifact: { copy: cmdTemplate?.replaceAll('{name}', name), url: decl?.mintUrl, steps: decl?.steps },
+    verbs: ['set'],
+})
+
+/** media kit instances — identity self-heals BEFORE surfacing; manual with
+ *  nothing uploaded = red (provide); rolls with no pick = yellow (a default
+ *  exists, taste pending — auto-pick-first is blessed); stale = yellow. */
+export function mediaKitCollection(root: string, kit: ResolvedKit | null, heal: typeof healIdentity = healIdentity): Collection {
+    return {
+        id: 'media',
+        title: 'assets',
+        media: 'image',
+        list: async () => {
+            const idn = await heal(root)
+            const out: Instance[] = []
+            if (idn.state === 'blocked')
+                out.push({ id: 'media:identity', text: `identity — ${idn.detail ?? 'blocked'}`, severity: 'red', href: '/assets/#identity-logo', verbs: ['pick'] })
+            if (kit == null) return out
+            for (const f of allAssets(kit)) {
+                const dir = assetDir(join(root, kit.workspace), f.asset.id)
+                const rolls = listRolls(dir)
+                const manual = f.kind.generate.backend === 'manual'
+                const href = `/assets/#${f.asset.id}`
+                if (manual && rolls.length === 0)
+                    // the brief IS the paste-ready artifact ("I don't even
+                    // know what to paste" — the tile hands him the prompt)
+                    out.push({ id: `media:${f.asset.id}`, text: `${f.asset.id} — manual, nothing uploaded`, severity: 'red', href, verbs: ['provide'], artifact: f.asset.prompt != null ? { copy: f.asset.prompt } : undefined })
+                else if (rolls.length > 0 && (await readPick(dir)).pick == null)
+                    out.push({ id: `media:${f.asset.id}`, text: `${f.asset.id} — ${rolls.length} roll(s), default in use, none picked`, severity: 'yellow', href, verbs: ['pick'] })
+                else if (await isStale(kit, join(root, kit.workspace), f))
+                    out.push({ id: `media:${f.asset.id}`, text: `${f.asset.id} — stale (a parent was re-picked)`, severity: 'yellow', href, verbs: ['pick'] })
+            }
+            return out
+        },
+    }
+}
+
+/** repo health — NON-curatable feed items: failing checks (minus cred lines
+ *  the creds provider owns), contract FAIL/WARN, hub process staleness. */
+export function repoHealthCollection(root: string, c: RepoConfig, o?: { bootVersion?: string; libVersion?: () => string }): Collection {
+    return {
+        id: 'health',
+        title: 'repo health',
+        media: 'health',
+        list: async () => {
+            const out: Instance[] = []
+            if (o?.bootVersion != null && o.libVersion != null) {
+                const now = o.libVersion()
+                if (now !== o.bootVersion)
+                    out.push({ id: 'health:stale-hub', severity: 'red', text: `hub is running shipkit ${o.bootVersion} but ${now} is on disk (stale process, stale pages, old studio code). Restart the 🚀 shipkit task` })
+            }
+            const statusPath = join(root, 'STATUS.md')
+            if (existsSync(statusPath))
+                for (const l of readFileSync(statusPath, 'utf8').split('\n'))
+                    if (l.trimStart().startsWith('FAIL') && !CRED_LINE.test(l)) {
+                        // the feed line carries severity already — a raw FAIL: marker would stack three signals
+                        const text = l.trim().replace(/^(FAIL|WARN):\s*/, '')
+                        // id = full text (never sliced: a shared 60-char prefix must not collide two items — pings dedup on ids)
+                        out.push({ id: `health:${text}`, severity: 'red', text, href: '/status' })
+                    }
+            const r = await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root))
+            for (const l of r.lines) {
+                if (l.kind === 'fail') out.push({ id: `health:contract:${l.text}`, severity: 'red', text: l.text })
+                else if (l.kind === 'warn') out.push({ id: `health:contractwarn:${l.text}`, severity: 'yellow', text: l.text })
+            }
+            return out
+        },
+    }
+}
+
+export function buildCollections(root: string, c: RepoConfig, kit: ResolvedKit | null, o?: { bootVersion?: string; libVersion?: () => string }): Collection[] {
+    return [
+        repoHealthCollection(root, c, o),
+        asksCollection(root, c),
+        credsCollection(root, c),
+        mediaKitCollection(root, kit),
+        socialPostsCollection(root),
+    ]
+}

package/src/repo-config.ts

@@ -45,6 +45,12 @@ export type RepoConfig = {
     tasks?: TaskDef[]
     /** emptyText: the `shipkit asks` all-clear line, in the repo's own voice */
     asks?: { dir?: string; emptyText?: string }
+    /** secrets this repo needs; mint artifact rides as data (needs feed tile) */
+    creds?: { name: string; service?: string; mintUrl?: string; steps?: string[] }[]
+    /** store-command template for a missing secret tile, `{name}` substituted (e.g. your secret manager's set command) */
+    credsCommand?: string
+    /** notify command for new RED needs while the hub serves, `{message}` substituted (e.g. a push-notification CLI) */
+    notifyCommand?: string
     contracts?: { exempt?: Record<string, string>; extra?: ContractManifest[] }
     /** extra dashboard panels appended after the built-in Tasks/Checks (`shipkit tui`) */
     tui?: { panels?: TuiPanelDef[] }
@@ -53,7 +59,7 @@ export type RepoConfig = {
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'contracts', 'tui', 'serve', 'logDir'])
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'notifyCommand', 'contracts', 'tui', 'serve', 'logDir'])
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')

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

@@ -9,15 +9,24 @@ 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 }
+type NeedItem = {
+    collection: string
+    id: string
+    text: string
+    severity?: 'red' | 'yellow'
+    href?: string
+    artifact?: { copy?: string; url?: string; steps?: string[] }
+    verbs?: string[]
+    candidates?: { id: string; label: string; hint?: string }[]
+}
 
 const RAIL_ICONS: Record<string, string> = { '/': '⚡', '/graph/wiki': '🕸', '/graph/agent': '🤖', '/assets/': '🖼', '/status': '📊' }
 
 class HubStore {
     name = ''
     tools: HubTool[] = []
-    sections: AttentionSection[] | null = null
+    needs: NeedItem[] | null = null
+    redsOnly = false
     statusMd: string | null = null
     running = false
     note = ''
@@ -28,17 +37,23 @@ class HubStore {
     }
 
     get redCount(): number {
-        return (this.sections ?? []).filter((s) => s.tone === 'red').reduce((n, s) => n + s.lines.length, 0)
+        return (this.needs ?? []).filter((n) => n.severity === 'red').length
+    }
+
+    get visible(): NeedItem[] {
+        const all = this.needs ?? []
+        const sorted = [...all].sort((a, b) => (a.severity === b.severity ? 0 : a.severity === 'red' ? -1 : 1))
+        return this.redsOnly ? sorted.filter((n) => n.severity === 'red') : sorted
     }
 
     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[] }
+            const nd = (await (await fetch('/api/needs.json')).json()) as { needs: NeedItem[] }
             runInAction(() => {
                 this.name = hub.name
                 this.tools = hub.tools
-                this.sections = att.sections
+                this.needs = nd.needs
             })
             if (location.pathname === '/status') {
                 const s = (await (await fetch('/api/status.json')).json()) as { statusMd: string | null }
@@ -49,6 +64,29 @@ class HubStore {
         }
     }
 
+    /** per-tile act errors — feedback lands WHERE he clicked, never only in
+     *  a scrolled-away bar */
+    actErr: Record<string, string> = {}
+    busy = false
+
+    /** POST an act-in-place verb, then refetch */
+    async act(id: string, path: string, body: Record<string, string>): Promise<void> {
+        runInAction(() => { this.busy = true; delete this.actErr[id] })
+        try {
+            const r = await fetch(`/api/act/${path}`, { method: 'POST', body: JSON.stringify(body) })
+            if (!r.ok) throw new Error(await r.text())
+            runInAction(() => { this.note = 'done' })
+            await this.load()
+        } catch (e) {
+            runInAction(() => { this.actErr[id] = (e as Error).message })
+        }
+        runInAction(() => { this.busy = false })
+    }
+
+    tileErr(id: string, msg: string): void {
+        runInAction(() => { this.actErr[id] = msg })
+    }
+
     async runCheck(): Promise<void> {
         this.running = true
         this.note = 'running…'
@@ -95,27 +133,81 @@ const Rail = observer(() => {
     )
 })
 
-const Attention = observer(() => {
-    const live = (store.sections ?? []).filter((s) => s.lines.length > 0)
+const copy = (s: string): void =>
+    void navigator.clipboard.writeText(s).then(
+        () => runInAction(() => { store.note = 'copied' }),
+        () => runInAction(() => { store.note = 'copy failed (clipboard needs a secure context)' }),
+    )
+
+/** one act-in-place tile per need — the artifact is IN HAND (copy buttons,
+ *  mint links, proof inputs), never a pointer to a flow */
+const NeedTile = observer(({ n }: { n: NeedItem }) => {
+    const askFile = n.collection === 'asks' ? n.id.replace(/^ask:/, '') : null
+    const post = n.collection === 'posts' ? n.id.match(/^post:([^/]+)\/(.+?):(pick|topost|invalid)$/) : null
+    const pickedFile = n.collection === 'posts' ? n.candidates?.[0]?.id : null
     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 className={`tile ${n.severity ?? ''}`}>
+            <div className="tline">
+                <span className="chip">{n.collection}</span>
+                {n.href != null ? <a href={n.href}>{n.text}</a> : <span>{n.text}</span>}
+            </div>
+            {n.artifact?.copy != null ? (
+                <div className="tact">
+                    <button onClick={() => copy(n.artifact!.copy!)}>copy {n.collection === 'creds' ? 'command' : n.collection === 'posts' ? 'post' : 'brief'}</button>
+                    <code>{n.artifact.copy.length > 120 ? `${n.artifact.copy.slice(0, 120)}…` : n.artifact.copy}</code>
+                </div>
+            ) : null}
+            {n.artifact?.url != null ? <div className="tact"><a href={n.artifact.url} target="_blank" rel="noreferrer">mint ↗</a></div> : null}
+            {n.artifact?.steps != null ? <details className="tact"><summary>steps</summary>{n.artifact.steps.map((s, i) => <div key={i}>{i + 1}. {s}</div>)}</details> : null}
+            {post?.[3] === 'pick' ? (
+                // the CORE taste interaction: candidates comparable at a
+                // glance, never a blind collapse
+                <div className="tact picks">
+                    {n.candidates?.map((c) => (
+                        <div key={c.id} className="cand">
+                            <div className="candhead">
+                                <span className="chip">{c.label}</span>
+                                <button disabled={store.busy} onClick={() => void store.act(n.id, 'post-pick', { channel: post[1]!, file: c.id })}>pick</button>
+                            </div>
+                            <div className="hint">{c.hint}</div>
+                        </div>
+                    ))}
+                </div>
+            ) : null}
+            {post?.[3] === 'topost' && pickedFile != null ? (
+                <form className="tact" onSubmit={(e) => { e.preventDefault(); const url = new FormData(e.currentTarget).get('url') as string; if (url === '') store.tileErr(n.id, 'paste the posted URL first — the proof is the point'); else void store.act(n.id, 'post-posted', { channel: post[1]!, file: pickedFile, url }) }}>
+                    <input name="url" placeholder="posted URL = proof" />
+                    <button type="submit" disabled={store.busy}>posted ✓</button>
+                </form>
+            ) : null}
+            {askFile != null ? (
+                <form className="tact" onSubmit={(e) => { e.preventDefault(); const url = new FormData(e.currentTarget).get('url') as string; void (url !== '' ? store.act(n.id, 'ask-proof', { file: askFile, url }) : store.act(n.id, 'ask-done', { file: askFile })) }}>
+                    <input name="url" placeholder="proof URL (optional)" />
+                    <button type="submit" disabled={store.busy}>done ✓</button>
+                </form>
+            ) : null}
+            {store.actErr[n.id] != null ? <div className="tileerr">✗ {store.actErr[n.id]}</div> : null}
         </div>
     )
 })
 
+const Attention = observer(() => (
+    <div className="wrap">
+        <div className="crumb">shipkit hub · needs</div>
+        <h1>{store.name}<small>everything that needs you, artifact in hand</small></h1>
+        {store.needs == null ? <div className="sub">loading…</div>
+            : store.needs.length === 0 ? <div className="clear">✅ all clear — nothing needs you</div>
+            : <>
+                <div className="bar">
+                    <label><input type="checkbox" checked={store.redsOnly} onChange={(e) => runInAction(() => { store.redsOnly = e.target.checked })} /> reds only</label>
+                    <span className="note">{store.redCount} red · {(store.needs.length - store.redCount)} yellow{store.note !== '' ? ` · ${store.note}` : ''}</span>
+                </div>
+                {store.visible.map((n) => <NeedTile key={n.id} n={n} />)}
+            </>}
+        <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'

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

@@ -39,3 +39,27 @@ pre{background:var(--panel);border:1px solid var(--line);border-radius:12px;padd
  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)}
+
+/* needs feed tiles — red blocks, yellow = taste pending */
+.tile{background:var(--panel);border:1px solid var(--line);border-left:3px solid var(--dim);border-radius:12px;
+ padding:12px 16px;margin-top:10px}
+.tile.red{border-left-color:var(--red)}
+.tile.yellow{border-left-color:var(--gold)}
+.tline{display:flex;align-items:baseline;gap:10px;font-size:14px}
+.tline a{color:var(--ink);text-decoration:underline dotted}.tline a:hover{color:var(--gold)}
+.chip{flex:none;font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:var(--dim);
+ background:var(--panel2);border-radius:8px;padding:1px 8px}
+.tile.red .chip{color:#e8a0a0}
+.tact{display:flex;align-items:center;gap:10px;margin-top:8px;font-size:12.5px;flex-wrap:wrap}
+.tact code{color:var(--dim);font:12px ui-monospace,Menlo,monospace;overflow:hidden;text-overflow:ellipsis;max-width:560px;white-space:nowrap}
+.tact button{padding:4px 10px;font-size:12px}
+.tact input{background:var(--panel2);border:1px solid var(--line);border-radius:8px;color:var(--ink);padding:6px 10px;font-size:12.5px;min-width:240px}
+.tact a{color:var(--accent)}
+.tact details{width:100%}
+.tact summary{cursor:pointer;color:var(--dim)}
+.hint{color:var(--dim);font-size:12.5px;white-space:pre-wrap;border-left:2px solid var(--line);padding-left:10px;margin:6px 0 4px}
+.picks{flex-direction:column;align-items:stretch}
+.cand{background:var(--panel2);border:1px solid var(--line);border-radius:9px;padding:8px 12px}
+.candhead{display:flex;align-items:center;gap:10px;margin-bottom:4px}
+.tileerr{margin-top:8px;font-size:12.5px;color:var(--red)}
+label{font-size:12.5px;color:var(--dim);display:flex;gap:6px;align-items:center;cursor:pointer}

package/src/serve/hub-pages.ts

@@ -32,14 +32,7 @@ export function withRail(html: string, o: { tools: HubTool[]; active: string }):
         })
         .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>`
+    // needs projection server-side (cost + heal side-effects)
+    const dotScript = `<script>fetch('/api/needs.json').then(r=>r.json()).then(j=>{const n=(j.needs||[]).filter(x=>x.severity==='red').length;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,20 +5,17 @@
 // 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, readdirSync, readFileSync, statSync } from 'fs'
+import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import { fileURLToPath } from 'url'
-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 { loadKit, type ResolvedKit } from '../assets/kit-config.ts'
 import { page as studioPage } from '../assets/server/studio-page.ts'
 import { studioRoutes, type StudioRoutes } from '../assets/server/studio-server.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 { projectNeeds } from '../collections/collection-types.ts'
+import { pingTick } from '../collections/pings.ts'
+import { buildCollections } from '../collections/providers.ts'
+import { 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 }
@@ -59,7 +56,21 @@ export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o
         agentGraph,
         studio,
         checkCmd: [process.execPath, cli, 'check'],
-        attention: attentionCollector(root, c, kit),
+        needs: () => projectNeeds(buildCollections(root, c, kit, { bootVersion: BOOT_VERSION, libVersion })),
+        asksDir: c.asks?.dir ?? 'asks',
+        // RED-only pings while serving; notify command is repo config data.
+        // Delivery failure must be LOUD — a silently broken notify path means
+        // he assumes no blockers exist
+        pingTick: (needs) =>
+            pingTick(root, c.asks?.dir ?? 'asks', needs, {
+                run: (cmd) => {
+                    const p = Bun.spawn(cmd, { stdout: 'ignore', stderr: 'pipe' })
+                    void p.exited.then(async (code) => {
+                        if (code !== 0) io.printErr(`WARN ping delivery failed (exit ${code}): ${await new Response(p.stderr).text().then((s) => s.trim().slice(0, 160))}`)
+                    })
+                },
+                notifyCommand: c.notifyCommand,
+            }),
     }
 }
 
@@ -72,79 +83,9 @@ const libVersion = (): string => {
 }
 const BOOT_VERSION = libVersion()
 
-// ── the / dashboard's data: everything red, one collector per source, each
-//    failure-isolated (a broken source reports itself, never blanks the page)
-export function attentionCollector(root: string, c: RepoConfig, kit: ResolvedKit | null): () => Promise<AttentionSection[]> {
-    const guard = async (title: string, tone: 'red' | 'warn', body: () => Promise<AttentionSection['lines']>): Promise<AttentionSection> => {
-        try { return { title, tone, lines: await body() } } catch (e) { return { title, tone: 'red', lines: [{ text: `collector broke: ${(e as Error).message}` }] } }
-    }
-    return async () => {
-        const sections = await Promise.all([
-            guard('hub process', 'red', async () => {
-                const now = libVersion()
-                if (now === BOOT_VERSION) return []
-                return [{ text: `hub is running shipkit ${BOOT_VERSION} but ${now} is on disk (stale process, stale pages, old studio code). Restart the 🚀 shipkit task` }]
-            }),
-            guard('failing checks', 'red', async () => {
-                const p = join(root, 'STATUS.md')
-                if (!existsSync(p)) return []
-                // a cred FAIL whose ask already sits in the asks section is
-                // ONE action shown twice — the ask (his hands) wins
-                const askDir = join(root, c.asks?.dir ?? 'asks')
-                const askText = existsSync(askDir) ? openAsks(askDir).map((a) => a.title.toLowerCase()).join(' ') : ''
-                return (await Bun.file(p).text()).split('\n')
-                    .filter((l) => l.trimStart().startsWith('FAIL'))
-                    .filter((l) => {
-                        const cred = l.match(/cred rv\/([a-z0-9-]+)\/[a-z0-9-]+ missing/)?.[1]
-                        return cred == null || !askText.includes(cred)
-                    })
-                    .map((text) => ({ text, href: '/status' }))
-            }),
-            guard('asks — waiting on you', 'red', async () => {
-                const dir = join(root, c.asks?.dir ?? 'asks')
-                if (!existsSync(dir)) return [] // read path must not mint an asks/ dir
-                return openAsks(dir).map((a) => ({ text: `${a.title}${a.kind !== '' ? ` (${a.kind})` : ''}` }))
-            }),
-            guard('assets', 'red', async () => {
-                // self-heal first: identity re-renders itself on brand.ts
-                // drift; only pick-blocked (taste) surfaces below
-                const idn = await healIdentity(root)
-                const lines: AttentionSection['lines'] = []
-                if (idn.state === 'blocked') lines.push({ text: `identity — ${idn.detail ?? 'blocked'}`, href: '/assets/#identity-logo' })
-                if (kit == null) return lines
-                for (const f of allAssets(kit)) {
-                    const dir = assetDir(join(root, kit.workspace), f.asset.id)
-                    const rolls = listRolls(dir)
-                    const manual = f.kind.generate.backend === 'manual'
-                    if (manual && rolls.length === 0) lines.push({ text: `${f.asset.id} — manual, nothing uploaded`, href: `/assets/#${f.asset.id}` })
-                    else if (rolls.length > 0 && (await readPick(dir)).pick == null) lines.push({ text: `${f.asset.id} — ${rolls.length} roll(s), none picked`, href: `/assets/#${f.asset.id}` })
-                    else if (await isStale(kit, join(root, kit.workspace), f)) lines.push({ text: `${f.asset.id} — stale (a parent was re-picked)`, href: `/assets/#${f.asset.id}` })
-                }
-                return lines
-            }),
-            guard('contracts', 'red', async () => {
-                const r = await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root))
-                return r.lines.filter((l) => l.kind === 'fail').map((l) => ({ text: l.text }))
-            }),
-            guard('contract warnings', 'warn', async () => {
-                const r = await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root))
-                return r.lines.filter((l) => l.kind === 'warn').map((l) => ({ text: l.text }))
-            }),
-            guard('posts to write', 'warn', async () => {
-                const social = join(root, '.rv-social')
-                if (!existsSync(social)) return []
-                const lines: AttentionSection['lines'] = []
-                for (const ch of readdirSync(social)) {
-                    const d = join(social, ch)
-                    if (!statSync(d).isDirectory()) continue
-                    for (const f of readdirSync(d).filter((x) => x.endsWith('.md'))) lines.push({ text: `${ch}/${f}` })
-                }
-                return lines
-            }),
-        ])
-        return sections
-    }
-}
+// the / dashboard's data now comes from the collection providers
+// (src/collections/providers.ts) — the old attentionCollector was DELETED
+// when they landed; never reintroduce a parallel projection.
 
 export async function runServe(root: string, io: ServeIo, o?: { port?: number }): Promise<number> {
     const c = await loadRepoConfig(root)

package/src/serve/serve-hub.ts

@@ -9,7 +9,9 @@ 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 { withRail, type AttentionSection } from './hub-pages.ts'
+import { appendPostFeedback, askDone, askProof, markPosted, pickPostVariant } from '../collections/actions.ts'
+import type { NeedItem } from '../collections/collection-types.ts'
+import { withRail } 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
@@ -29,9 +31,13 @@ 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[]>
+    /** the / needs feed — every human-action item, red/yellow, gathered per
+     *  request from the collection providers (run-serve builds it) */
+    needs: () => Promise<NeedItem[]>
+    /** asks dir (repo-root-relative) for the act-in-place ask verbs */
+    asksDir: string
+    /** RED-only ping tick, called on an interval while serving (null = off) */
+    pingTick?: ((needs: NeedItem[]) => void) | null
 }
 export type Hub = { server: ReturnType<typeof Bun.serve>; tools: HubTool[]; stop: () => void }
 
@@ -62,9 +68,29 @@ export function serveHub(d: HubDeps): Hub {
             // 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 === '/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/needs.json') {
+                const needs = await d.needs().catch((e: Error) => [{ collection: 'hub', id: 'hub:broken', text: `needs projection broke: ${e.message}`, severity: 'red' as const }])
+                return Response.json({ needs })
+            }
+            if (path.startsWith('/api/act/') && req.method === 'POST') {
+                // act-in-place verbs — every mutation hits a git-tracked truth
+                // file; errors surface as 400 text the tile shows verbatim
+                try {
+                    const b = (await req.json()) as Record<string, string>
+                    if (path === '/api/act/ask-done') askDone(d.root, d.asksDir, b.file ?? '')
+                    else if (path === '/api/act/ask-proof') askProof(d.root, d.asksDir, b.file ?? '', b.url ?? '')
+                    else if (path === '/api/act/post-pick') pickPostVariant(d.root, b.channel ?? '', b.file ?? '')
+                    else if (path === '/api/act/post-posted') {
+                        const rating = b.rating != null ? Number(b.rating) : undefined
+                        if (rating != null && (!Number.isFinite(rating) || rating < 1 || rating > 5)) return new Response('rating must be 1-5', { status: 400 })
+                        markPosted(d.root, b.channel ?? '', b.file ?? '', b.url ?? '', rating)
+                    }
+                    else if (path === '/api/act/post-feedback') appendPostFeedback(d.root, b.channel ?? '', b.file ?? '', b.text ?? '')
+                    else return new Response('unknown act', { status: 404 })
+                    return Response.json({ ok: true })
+                } catch (e) {
+                    return new Response((e as Error).message, { status: 400 })
+                }
             }
             if (path === '/api/status.json') {
                 const p = join(d.root, 'STATUS.md')
@@ -94,5 +120,14 @@ export function serveHub(d: HubDeps): Hub {
             return new Response('not found', { status: 404 })
         },
     })
-    return { server, tools, stop: () => server.stop(true) }
+    // RED-only pings ride the serving process: one tick now (state file
+    // guarantees a restart never re-fires), then every minute
+    let pingTimer: ReturnType<typeof setInterval> | null = null
+    if (d.pingTick != null) {
+        // tick failures are LOUD (console = the serve terminal), never swallowed
+        const tick = (): void => void d.needs().then((n) => d.pingTick?.(n)).catch((e: Error) => console.error(`WARN ping tick broke: ${e.message}`))
+        tick()
+        pingTimer = setInterval(tick, 60_000)
+    }
+    return { server, tools, stop: () => { if (pingTimer != null) clearInterval(pingTimer); server.stop(true) } }
 }

package/src/shipkit.ts

@@ -6,8 +6,11 @@ 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 { withRail, attentionRedCount } from './serve/hub-pages.ts'
-export type { AttentionSection, AttentionLine } from './serve/hub-pages.ts'
+export { withRail } from './serve/hub-pages.ts'
+export { projectNeeds, redCount } from './collections/collection-types.ts'
+export type { Collection, Instance, NeedItem, NeedSeverity, CurationVerb } from './collections/collection-types.ts'
+export { buildCollections } from './collections/providers.ts'
+export { socialPostsCollection, listPosts } from './collections/posts.ts'
 export { discoverChecks } from './core/discover-checks.ts'
 export type { DiscoveredCheck } from './core/discover-checks.ts'
 export { runTasks, selectTasks } from './core/task-runner.ts'

package/src/start-repo.ts

@@ -1,8 +1,9 @@
-// `shipkit start` — ensure <root>/<name> exists and, when --include is
-// given, that CLAUDE.md carries that include line. Plain module behind
-// cmd_Start. Status lines go to STDERR — the ONLY stdout output is the
-// resolved dir, so a sourced shell alias can `cd "$(shipkit start <name>)"`
-// (the one thing a child process can't do for its parent shell).
+// `shipkit start` — ensure <root>/<name> exists and, when --include lines
+// are given, that CLAUDE.md carries them (in order, at the top). Plain
+// module behind cmd_Start. Status lines go to STDERR — the ONLY stdout
+// output is the resolved dir, so a sourced shell alias can
+// `cd "$(shipkit start <name>)"` (the one thing a child process can't do
+// for its parent shell).
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
@@ -10,16 +11,14 @@ import { join } from 'path'
 export type StartOpts = {
     /** parent dir for repos — default ~/dev */
     root?: string
-    /** line CLAUDE.md must start with; omitted = only ensure the dir */
-    include?: string
-    /** alternative lines that already count as wired — never double-add */
+    /** lines CLAUDE.md must carry, in order; omitted = only ensure the dir */
+    include?: string[]
+    /** alternative lines that satisfy the FIRST include — never double-add */
     alsoOk?: string[]
-    /** repo names that never get the include */
+    /** repo names that never get includes */
     skip?: string[]
 }
 
-const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-
 export function startRepo(name: string, opts: StartOpts = {}): number {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) {
         console.error(`FAIL: bad repo name '${name}' — letters/digits/._- only, no leading dot, no slashes`)
@@ -30,18 +29,29 @@ export function startRepo(name: string, opts: StartOpts = {}): number {
         mkdirSync(dir, { recursive: true })
         console.error(`ok: created ${dir}`)
     }
-    if (opts.include == null || (opts.skip ?? []).includes(name)) {
-        if (opts.include != null) console.error(`skip: ${name} is include-exempt — CLAUDE.md untouched`)
+    const want = opts.include ?? []
+    if (want.length === 0 || (opts.skip ?? []).includes(name)) {
+        if (want.length > 0) console.error(`skip: ${name} is include-exempt — CLAUDE.md untouched`)
     } else {
         const claudeMd = join(dir, 'CLAUDE.md')
         if (!existsSync(claudeMd)) {
-            writeFileSync(claudeMd, `${opts.include}\n`)
-            console.error('ok: CLAUDE.md created with the include')
+            writeFileSync(claudeMd, `${want.join('\n')}\n`)
+            console.error(`ok: CLAUDE.md created with ${want.length} include line(s)`)
         } else {
-            const wiredRe = new RegExp([opts.include, ...(opts.alsoOk ?? [])].map((l) => `^${escapeRe(l)}$`).join('|'), 'm')
-            if (!wiredRe.test(readFileSync(claudeMd, 'utf8'))) {
-                writeFileSync(claudeMd, `${opts.include}\n\n${readFileSync(claudeMd, 'utf8')}`)
-                console.error('ok: include prepended to CLAUDE.md')
+            const cur = readFileSync(claudeMd, 'utf8')
+            const lineSet = new Set(cur.split('\n'))
+            const alt = opts.alsoOk ?? []
+            const satisfied = (w: string): boolean => lineSet.has(w) || (w === want[0] && alt.some((a) => lineSet.has(a)))
+            const missing = want.filter((w) => !satisfied(w))
+            if (missing.length > 0) {
+                // insert after any leading include/alt lines so order survives
+                const lines = cur.split('\n')
+                const known = new Set([...want, ...alt])
+                let at = 0
+                while (at < lines.length && known.has(lines[at]!)) at++
+                lines.splice(at, 0, ...missing)
+                writeFileSync(claudeMd, lines.join('\n'))
+                console.error(`ok: ${missing.length} missing include line(s) inserted into CLAUDE.md`)
             }
         }
     }

package/src/wiki/scan-md.ts

@@ -8,7 +8,7 @@
 // unreachable files stay in the graph with no depth (lint-md.ts turns those,
 // plus dangling refs, into failures — the graph itself is a viewer).
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
-import { dirname, join, relative, resolve } from 'path'
+import { basename, dirname, join, relative, resolve } from 'path'
 import type { MdEdge, MdGraph, MdNode } from 'rvlib-shipkit/src/wiki/md-graph.ts'
 
 export type ScanMdConfig = {
@@ -43,8 +43,13 @@ export function scanMd(cfg: ScanMdConfig): MdScan {
     files.sort()
     const inGraph = new Set(files)
 
+    // writers inside a scanned dir often name paths from the REPO root
+    // ("agent/architecture.md" while scanning agent/) — accept that form too
+    const rootBase = `${basename(cfg.root)}/`
     const resolveRef = (fromRel: string, token: string): string | null => {
-        for (const cand of [resolve(join(cfg.root, dirname(fromRel)), token), resolve(cfg.root, token)]) {
+        const cands = [resolve(join(cfg.root, dirname(fromRel)), token), resolve(cfg.root, token)]
+        if (token.startsWith(rootBase)) cands.push(resolve(cfg.root, token.slice(rootBase.length)))
+        for (const cand of cands) {
             const rel = relative(cfg.root, cand)
             if (!rel.startsWith('..') && inGraph.has(rel)) return rel
         }