rvlib-shipkit 0.10.0 → 0.13.0

package/src/cli/cmd_Reflect.ts

@@ -0,0 +1,116 @@
+// shipkit reflect — the user's typed prompts across every Claude Code session
+// of a repo, as a chronological corpus for retrospective extraction passes.
+// REPORT-ONLY: exit 0 with prompts, 1 when a repo has no transcripts (loud,
+// naming the config roots that were searched).
+import { mkdirSync, writeFileSync } from 'fs'
+import { basename, join, resolve } from 'path'
+import { Command, Option } from 'clipanion'
+import { type PromptEntry, collectRepoPrompts, corpusMarkdown, projectSlug } from '../reflect/prompt-corpus.ts'
+
+const SHORT_MAX_LINES = 20
+
+/** the --json unit: one per requested repo, failures carried in-band */
+export type RepoDoc = { repo: string; prompts: PromptEntry[]; error?: string }
+
+export class ReflectCommand extends Command {
+    static override paths = [['reflect']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description:
+            "the user's typed prompts across every Claude Code session of a repo — chronological md corpus for retrospectives",
+        examples: [
+            ['corpus for the current repo', 'shipkit reflect'],
+            ['corpus for other repos', 'shipkit reflect ~/dev/one-repo ~/dev/another-repo'],
+            ['drop the long pastes', 'shipkit reflect --short'],
+            ['batch to files instead of stdout', 'shipkit reflect ~/dev/a ~/dev/b --out stats'],
+            ['machine-readable', 'shipkit reflect --json'],
+        ],
+    })
+
+    repoPaths = Option.Rest()
+    json = Option.Boolean('--json', false, { description: 'emit [{repo, prompts, error?}] JSON — same shape for 1 or N repos' })
+    short = Option.Boolean('--short', false, { description: `only prompts of ${SHORT_MAX_LINES} lines or fewer` })
+    out = Option.String('--out', { description: 'write <repo>[.short].md (or .json) per repo into this dir instead of stdout' })
+
+    async execute(): Promise<number> {
+        const repos = this.repoPaths.length > 0 ? this.repoPaths : [process.cwd()]
+        if (this.out != null) mkdirSync(this.out, { recursive: true })
+        let failed = false
+        const jsonDocs: RepoDoc[] = []
+        for (const repo of repos) {
+            const { prompts, dirs, roots } = collectRepoPrompts(repo)
+            const kept = this.short ? prompts.filter((p) => p.text.split('\n').length <= SHORT_MAX_LINES) : prompts
+            if (kept.length === 0) {
+                const error = this.fail(repo, prompts.length, roots)
+                failed = true
+                if (this.json) jsonDocs.push({ repo: resolve(repo), prompts: [], error })
+                continue
+            }
+            if (this.json) jsonDocs.push({ repo: resolve(repo), prompts: kept })
+            else this.emitMarkdown(repo, kept, dirs)
+        }
+        if (this.json) this.emitJson(jsonDocs)
+        return failed ? 1 : 0
+    }
+
+    /** one FAIL line per repo, and a fix that is not "do what you just did".
+     * Returns the same reason for the --json payload: a consumer must not have
+     * to diff stderr against stdout to learn a repo produced nothing. */
+    private fail(repo: string, total: number, roots: string[]): string {
+        const e = this.context.stderr
+        if (this.short && total > 0) {
+            const reason = `${total} prompts, none of ${SHORT_MAX_LINES} lines or fewer`
+            e.write(`FAIL: ${resolve(repo)}: ${reason}\n`)
+            e.write(`      fix: drop --short\n`)
+            return reason
+        }
+        e.write(`FAIL: no typed prompts for ${resolve(repo)}\n`)
+        e.write(`      looked for projects/${projectSlug(repo)}* under: ${roots.join(' · ')}\n`)
+        e.write(
+            this.repoPaths.length === 0
+                ? `      fix: this repo has no Claude Code sessions — name another, shipkit reflect ~/dev/<repo>\n`
+                : `      fix: check the path (it is slugged verbatim) — a session dir appears only after a session ran there\n`,
+        )
+        return 'no typed prompts'
+    }
+
+    /** ONE shape whatever the run looked like: RepoDoc[], failures included with
+     * their reason. A data-dependent schema breaks every consumer eventually. */
+    private emitJson(docs: RepoDoc[]): void {
+        if (this.out == null) {
+            this.context.stdout.write(`${JSON.stringify(docs, null, 2)}\n`)
+            return
+        }
+        for (const d of docs) {
+            if (d.error != null) continue
+            const file = this.outFile(d.repo, '.json')
+            writeFileSync(file, `${JSON.stringify(d, null, 2)}\n`)
+            this.context.stdout.write(`ok: ${this.counts(d.prompts)} → ${file}\n`)
+        }
+    }
+
+    /** queued prompts are the ones typed mid-run: say how many, so a future hole
+     * in that path is visible instead of silent */
+    private counts(prompts: PromptEntry[]): string {
+        const queued = prompts.filter((p) => p.origin === 'queued').length
+        const base = `${String(prompts.length).padStart(4)} prompts`
+        return queued === 0 ? base : `${base} (${queued} queued mid-run)`
+    }
+
+    private emitMarkdown(repo: string, prompts: PromptEntry[], dirs: string[]): void {
+        const md = corpusMarkdown(repo, prompts)
+        if (this.out == null) {
+            this.context.stdout.write(md)
+            return
+        }
+        const file = this.outFile(repo, '.md')
+        writeFileSync(file, md)
+        this.context.stdout.write(`ok: ${this.counts(prompts)} → ${file} (${dirs.length} session dir(s))\n`)
+    }
+
+    /** --short writes its OWN file: the filtered corpus must never overwrite the full one */
+    private outFile(repo: string, ext: string): string {
+        return join(this.out ?? '.', `${basename(resolve(repo))}${this.short ? '.short' : ''}${ext}`)
+    }
+}

package/src/cli/cmd_Rules.ts

@@ -0,0 +1,32 @@
+// shipkit rules — render the SK rule registry. Agents read ids HERE (or
+// --json), never guess or mint one: the registry is the single source.
+import { Command, Option } from 'clipanion'
+import { RULES } from '../rules/rule-registry.ts'
+
+export class RulesCommand extends Command {
+    static override paths = [['rules']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'list every built-in SK rule: id, what it lints, owning doc, whether check --fix can repair it',
+        examples: [
+            ['list rules', 'shipkit rules'],
+            ['machine-readable', 'shipkit rules --json'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'machine-readable [{id, title, owner, fixable}]' })
+
+    async execute(): Promise<number> {
+        const rows = RULES.map((r) => ({ id: r.id, title: r.title, owner: r.owner, fixable: r.fix != null }))
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify(rows)}\n`)
+            return 0
+        }
+        // a catalog, not a health run — no wire prefixes (`ok:` would assert
+        // a passing check into anything that parses wire output)
+        for (const r of rows)
+            this.context.stdout.write(`${r.id}  ${r.title} — ${r.owner}${r.fixable ? ' · fixable' : ''}\n`)
+        return 0
+    }
+}

package/src/cli/cmd_Serve.ts

@@ -8,7 +8,7 @@ export class ServeCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Serve',
-        description: 'ONE hub server per repo: landing page linking the wiki/agent graphs, the assets studio, and live status',
+        description: 'ONE server, ONE page: media studio + asks + creds + posts + health + graphs, with drill-down graph pages',
         examples: [
             ['serve the repo toolbox', 'shipkit serve'],
             ['pin the port for this launch', 'shipkit serve --port 4804'],

package/src/cli.ts

@@ -5,12 +5,15 @@
 import { readFileSync } from 'fs'
 import { Builtins, Cli } from 'clipanion'
 import { AskNewCommand, AsksCheckCommand, AsksCommand } from './cli/cmd_Asks.ts'
-import { AssetsAddCommand, AssetsCheckCommand, AssetsFillCommand, AssetsGenCommand, AssetsIdentityCommand, AssetsServeCommand } from './cli/cmd_Assets.ts'
+import { AssetsAddCommand, AssetsCheckCommand, AssetsFillCommand, AssetsGenCommand, AssetsIdentityCommand } from './cli/cmd_Assets.ts'
 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 { NeedsCommand } from './cli/cmd_Needs.ts'
+import { ReflectCommand } from './cli/cmd_Reflect.ts'
+import { RulesCommand } from './cli/cmd_Rules.ts'
 import { ServeCommand } from './cli/cmd_Serve.ts'
 import { StartCommand } from './cli/cmd_Start.ts'
 import { TuiCommand } from './cli/cmd_Tui.ts'
@@ -39,7 +42,6 @@ cli.register(AsksCheckCommand)
 cli.register(AskNewCommand)
 cli.register(WikiServeCommand)
 cli.register(WikiLintCommand)
-cli.register(AssetsServeCommand)
 cli.register(AssetsFillCommand)
 cli.register(AssetsAddCommand)
 cli.register(AssetsGenCommand)
@@ -47,5 +49,8 @@ cli.register(AssetsIdentityCommand)
 cli.register(AssetsCheckCommand)
 cli.register(InitCommand)
 cli.register(StartCommand)
+cli.register(NeedsCommand)
+cli.register(ReflectCommand)
+cli.register(RulesCommand)
 
 cli.runExit(process.argv.slice(2))

package/src/collections/actions.ts

@@ -0,0 +1,85 @@
+// 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`)
+}
+
+/** his asset remark → `.rv-assets/notes.md` (git-tracked; the studio
+ *  workspace is gitignored, so notes live beside kit.ts) */
+export function appendAssetNote(root: string, assetId: string, text: string): void {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(assetId)) throw new Error('bad asset id')
+    const p = join(root, '.rv-assets', 'notes.md')
+    const line = `- ${today()} [${assetId}]: ${text.replace(/\n+/g, ' ').trim()}`
+    writeFileSync(p, existsSync(p) ? `${readFileSync(p, 'utf8').trimEnd()}\n${line}\n` : `# asset notes — his remarks, read by agents at boot\n\n${line}\n`)
+}
+
+/** his remark on an ask → appended to the ask file, dated, non-destructive.
+ *  Accepts exactly one optional `done/` prefix (archived asks stay
+ *  annotatable); any other slash or traversal is a bad path. */
+export function appendAskRemark(root: string, asksDir: string, file: string, text: string): void {
+    if (!/^(done\/)?[A-Za-z0-9][A-Za-z0-9._-]*$/.test(file) || file.includes('..')) throw new Error('bad path')
+    const p = join(root, asksDir, file)
+    if (!existsSync(p)) throw new Error(`no such ask: ${file}`)
+    writeFileSync(p, `${readFileSync(p, 'utf8').trimEnd()}\n- ${today()}: ${text.replace(/\n+/g, ' ').trim()}\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,65 @@
+// 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 }[]
+    /** TRUST: the git file this instance IS — shown on the tile; the file
+     *  always wins over the page */
+    file?: string
+    /** thumbnail URL for media tiles */
+    img?: string
+    /** his latest remarks from the item's own file — agents boot on these */
+    remarks?: string[]
+    /** the truth file's markdown BODY (frontmatter stripped) — clamped card
+     *  in the grid, full in the item view; capped server-side, never a dump */
+    md?: string
+    /** an open ask owns the action (dedup = acted-on once, never hidden):
+     *  the instance stays red HERE but verbs and pings live with the ask */
+    askOwned?: boolean
+}
+
+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/graphs.ts

@@ -0,0 +1,34 @@
+// graphs collection — the mounted md graphs as CHECKED section entries:
+// each graph instance carries its lint state (orphans + dangling refs =
+// yellow with counts; clean = quiet). Custom wiki-graph providers (repos
+// with their own loader + their own lint) get a link-only instance — their
+// repo lint owns correctness, never double-judged here.
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { lintMd } from '../wiki/lint-md.ts'
+import type { Collection, Instance } from './collection-types.ts'
+
+export function graphsCollection(root: string, o: { customWiki: boolean; agentIndex?: string }): Collection {
+    return {
+        id: 'graphs',
+        title: 'graphs',
+        media: 'data',
+        list: async () => {
+            const out: Instance[] = []
+            const checked = (id: string, title: string, href: string, dir: string, index?: string): Instance => {
+                const r = lintMd({ root: dir, index })
+                const issues = r.orphans.length + r.dangling.length
+                return {
+                    id,
+                    text: issues === 0 ? title : `${title} — ${r.orphans.length} orphan(s), ${r.dangling.length} dangling ref(s)`,
+                    severity: issues === 0 ? undefined : 'yellow',
+                    href,
+                }
+            }
+            if (o.customWiki) out.push({ id: 'graph:wiki', text: 'wiki graph (repo-owned lint)', href: '/graph/wiki' })
+            else out.push(checked('graph:wiki', 'wiki graph', '/graph/wiki', root))
+            if (existsSync(join(root, 'agent'))) out.push(checked('graph:agent', 'agent graph', '/graph/agent', join(root, 'agent'), o.agentIndex))
+            return out
+        },
+    }
+}

package/src/collections/pings.ts

@@ -0,0 +1,72 @@
+// 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
+    /** hub URL appended to the message — the OFF-MACHINE form
+     *  (serve.publicHost); a phone can't resolve localhost */
+    link?: string
+}
+
+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.askOwned === true) continue // the covering ask's pinged: field already fired the once-ever ping
+        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 ? ' · …' : ''}${io.link != null ? ` → ${io.link}` : ''}`
+    // 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,125 @@
+// 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[] = []
+            const feedback = (v: PostFile): string[] | undefined => {
+                const lines = v.body.split('\n').filter((l) => /^- \d{4}-\d{2}-\d{2}: /.test(l))
+                return lines.length > 0 ? lines.slice(-3) : undefined
+            }
+            for (const [key, variants] of bySlug) {
+                const fileOf = (v: PostFile): string => `.rv-social/${v.channel}/${v.file}`
+                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',
+                        file: fileOf(missing[0]!),
+                    })
+                    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' }],
+                        file: fileOf(picked),
+                        remarks: feedback(picked),
+                    })
+                    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) })),
+                        file: fileOf(drafts[0]!),
+                        remarks: feedback(drafts[0]!),
+                    })
+                    continue
+                }
+                // posted / rejected history: VISIBLE (browse-all), never in needs
+                const posted = variants.find((v) => v.status === 'posted')
+                const shown = posted ?? variants[0]!
+                out.push({
+                    id: `post:${key}:${posted != null ? 'posted' : 'rejected'}`,
+                    text: `${key} — ${posted != null ? `posted${posted.posted != null ? ` (${posted.posted})` : ''}` : 'rejected'}`,
+                    file: fileOf(shown),
+                    remarks: feedback(shown),
+                })
+            }
+            return out
+        },
+    }
+}