rvlib-shipkit 0.38.0 → 1.0.0

package/src/serve/serve-hub.ts

@@ -1,31 +1,80 @@
 // shipkit serve — the repo's ONE Bun.serve, serving the ONE page (one server per repo, one surface, mobx+react). `/` is
 // the hub app (Bun HTML import — media studio + asks + creds + posts +
-// health + graphs as sections); the studio route table mounts as the media
+// health + wikis as sections); the studio route table mounts as the media
 // API under /media/*; graph canvases stay as drill-down pages. Route logic
 // only — resolving WHAT to mount from repo.config is run-serve.ts's job.
 import { existsSync } from 'fs'
 import { join } from 'path'
-import { graphHtml } from 'rvlib-shipkit/src/wiki/graph-page.ts'
+import { positionsFile } from 'rvlib-shipkit/src/wiki/graph-positions.ts'
+import { graphRoutes } from 'rvlib-shipkit/src/wiki/serve-graph.ts'
 import type { StudioRoutes } from '../assets/server/studio-server.ts'
+import { comfyBoxUp, type ComfyBox, type ComfyPanelUp } from '../comfy/comfy-panel.ts'
 import { appendAskRemark, appendAssetNote, appendPostFeedback, askDone, askProof, markPosted, pickPostVariant } from '../collections/actions.ts'
-import type { Collection, Instance, NeedItem } from '../collections/collection-types.ts'
+import { projectResources, type Collection, type Instance, type NeedItem } from '../collections/collection-types.ts'
+import type { CheckEvent } from '../core/run-check.ts'
+import { configDirty, readGateBlock, writeGateBlock, type GateEdit } from '../core/when-block.ts'
+import type { InvokedBy } from '../ledger/run-log.ts'
 import type { GraphMount } from '../wiki/graph-mount.ts'
+import type { ProseView } from '../prose/prose-view.ts'
+import type { Timeline } from '../ledger/run-timeline.ts'
+import type { TestCheckView, TestsRootView } from '../collections/test-time.ts'
+import type { LiveView } from '../ledger/live-timeline.ts'
+
+export type { LiveView }
+import type { HealthSchedule } from './health-schedule.ts'
 import hubIndex from './hub-app/index.html'
+import { projectGutter } from './project-gutter-route.ts'
+import { sameOrigin } from './same-origin.ts'
+import { LAYOUT } from '../core/layout.ts'
+
+export { sameOrigin }
 
 export type HubTool = { path: string; label: string; desc: string }
+
+/** what a running gate streams back to the page */
+export type CheckTap = { line: (l: string) => void; check: (e: CheckEvent) => void }
+/** the comfy panel, as the hub needs it: the child process it embeds and the
+ *  box those workflows generate on (src/comfy/comfy-panel.ts owns both) */
+export type ComfyDeps = {
+    ensure: () => Promise<ComfyPanelUp>
+    restart: () => Promise<ComfyPanelUp>
+    box: () => ComfyBox
+    stop: () => void
+}
 export type HubDeps = {
     root: string
     name: string
     /** 0 = random (tests); real launches pass repo.config/default */
     port: number
     /** every md graph this hub serves, in card order: /graph/<id>. run-serve
-     *  resolves the list, the routes AND the graphs section read it */
+     *  resolves the list, the routes AND the wikis page read it */
     graphs: GraphMount[]
     /** the media API (mounted under /media/*); null only if the route
      *  table failed to build — the page shows the WARN, never a second page */
     studio: StudioRoutes | null
-    /** argv shelling the check run streamed by /api/check/run (test seam) */
-    checkCmd: string[]
+    /** the check run, IN PROCESS: wire lines and per CHECK results stream out
+     *  as they finish, which is what lets a tree row recolour the moment its
+     *  check is done. `only` narrows it to a named set (the run button on a
+     *  check page, or on a folder header); `gate` asks for the whole gate,
+     *  tasks included. `auto` marks a run the hub started on its own (at
+     *  start, after a save): quick tier, no repair pass, so it never writes
+     *  into a tree someone is editing. run-serve owns the routing between the
+     *  two engines. */
+    runChecks: (tap: CheckTap, o?: { only?: string[]; gate?: boolean; by?: InvokedBy; auto?: boolean }) => Promise<number>
+    /** the daily health pass timer (health-schedule.ts). The page reads its
+     *  state to say when a health check runs next; absent = no timer */
+    schedule?: HealthSchedule | null
+    /** every run on record, shaped for the timeline page. Absent = the page
+     *  says there is no record rather than drawing an empty one */
+    timeline?: () => Promise<Timeline>
+    /** where the test checks' time goes: the `tests` page (check null) or one
+     *  test check's page (collections/test-time.ts). Absent = 404 */
+    tests?: (check: string | null) => Promise<TestsRootView | TestCheckView>
+    /** the live strip's view: the recent runs and the ones in flight, here
+     *  and in the other house repos, shaped on the server clock */
+    live?: () => LiveView
+    /** another house repo's hub url when it serves, null when it does not */
+    repoHub?: (repo: string) => Promise<string | null>
     /** every human-action item, red/yellow, gathered per request from the
      *  collection providers (run-serve builds it) */
     needs: () => Promise<NeedItem[]>
@@ -34,27 +83,48 @@ export type HubDeps = {
     collections: () => Collection[]
     /** asks dir (repo-root-relative) for the act-in-place ask verbs */
     asksDir: string
+    /** the comfy panel; null when the repo declares no workflow module, which
+     *  is also when the comfy section is absent from the page */
+    comfy: ComfyDeps | null
+    /** rule SK014's hits, grouped by word, over the config on disk: the data
+     *  of the SK014 page. Absent = the endpoint answers 404 */
+    prose?: () => Promise<ProseView>
+    /** re-read repo.config.ts when its bytes moved. The switch WRITES that
+     *  file, so every surface built on the config asks for this first, or a
+     *  toggle reads as a toggle that did nothing until the next restart */
+    refresh?: () => Promise<void>
     /** 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 }
+export type Hub = { server: ReturnType<typeof Bun.serve>; tools: HubTool[]; liveReload: boolean; stop: () => void }
+
+/** the tab refreshes ITSELF through bun's hot reload client, which rides in
+ *  the served page: it swaps a hub-app edit in, and reconnects across the
+ *  process restart a source edit triggers under `bun --watch`. Bun puts that
+ *  client on the page only in development mode, which it derives from
+ *  NODE_ENV at process start, so a production shell serves a page that can
+ *  never refresh itself. Pinned against the real served bytes in
+ *  tests/hub-server.test.ts, and run-serve turns a false into a WARN line:
+ *  silent, this reads exactly like a hub that is simply broken */
+export const canLiveReload = (): boolean => process.env.NODE_ENV !== 'production'
 
 // the toolbox as data — stdout ok: lines and /hub.json render THIS list,
 // so they can never disagree
 export function hubTools(d: Pick<HubDeps, 'graphs'>): HubTool[] {
     return [
-        { path: '/', label: 'hub', desc: 'THE page — media · asks · creds · posts · health · graphs' },
+        { path: '/', label: 'hub', desc: 'THE page — media · asks · creds · posts · health · wikis' },
         ...d.graphs.map((g) => ({ path: `/graph/${g.id}`, label: g.label, desc: g.title })),
     ]
 }
 
 // drill-down pages (graph canvases) get one fixed home link back to THE page
 const HOME_LINK = `<style>.skhome{position:fixed;left:10px;top:10px;z-index:9999;font-size:17px;text-decoration:none;
- background:#17140f;border:1px solid #332b22;border-radius:9px;padding:5px 9px}</style><a class=skhome href="/" title="hub — THE page">⌂</a>`
+ background:#141619;border:1px solid #282c31;border-radius:3px;padding:5px 9px}</style><a class=skhome href="/" title="hub — THE page">⌂</a>`
 const withHome = (html: string): string => html.replace(/<body([^>]*)>/, `<body$1>${HOME_LINK}`)
 
 export function serveHub(d: HubDeps): Hub {
     const tools = hubTools(d)
+    const projects = projectGutter({ root: d.root })
     const server: ReturnType<typeof Bun.serve> = Bun.serve({
         hostname: '127.0.0.1',
         port: d.port,
@@ -62,13 +132,32 @@ export function serveHub(d: HubDeps): Hub {
         routes: { '/': hubIndex },
         async fetch(req): Promise<Response> {
             const path = new URL(req.url).pathname
+            if (!sameOrigin(req)) return new Response('refused: a request that changes something must come from the hub page', { status: 403 })
             // 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 })
+            // `root` rides with it so a page can put a file link into his
+            // editor: only the server knows where this repo sits on disk
+            if (path === '/hub.json') return Response.json({ hub: 'shipkit', name: d.name, root: d.root, tools })
+            if (path.startsWith('/api/projects')) return (await projects.handle(req, path)) ?? new Response('not found', { status: 404 })
+            // the three surfaces built on the config read the config on disk
+            if (path === '/api/needs.json' || path === '/api/resources.json' || path === '/api/checks.json' || path === '/api/collections.json') await d.refresh?.()
             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 === '/api/resources.json') {
+                // ONE flat list for the whole repo: the page groups it by
+                // path and by type, and a second endpoint would be a second
+                // answer to drift from this one
+                const cols = d.collections()
+                return Response.json({
+                    collections: cols.map((c) => ({ id: c.id, title: c.title, media: c.media })),
+                    resources: await projectResources(cols),
+                    schedule: d.schedule?.state() ?? null,
+                })
+            }
+            // the previous address, answered while pages opened before the
+            // tree are still on screen
             if (path === '/api/collections.json') {
                 // browse-all: every instance of every collection, healthy
                 // included — failure-isolated per collection
@@ -77,7 +166,7 @@ export function serveHub(d: HubDeps): Hub {
                     try {
                         out.push({ id: col.id, title: col.title, media: col.media, instances: await col.list() })
                     } catch (e) {
-                        out.push({ id: col.id, title: col.title, media: col.media, instances: [{ id: `${col.id}:broken`, text: `collector broke: ${(e as Error).message}`, severity: 'red' }] })
+                        out.push({ id: col.id, title: col.title, media: col.media, instances: [{ id: `${col.id}:broken`, type: 'health', path: `health/${col.id}-collector`, virtual: true, text: `collector broke: ${(e as Error).message}`, severity: 'red' }] })
                     }
                 }
                 return Response.json({ collections: out })
@@ -112,20 +201,124 @@ export function serveHub(d: HubDeps): Hub {
                     return new Response((e as Error).message, { status: 400 })
                 }
             }
+            if (path.startsWith('/api/comfy/')) {
+                // the panel is comfy-ts's, on its own port: the page embeds it,
+                // and these two answers are everything the hub knows about it
+                if (d.comfy == null) return new Response('this repo has no .shipkit/comfy/workflows module', { status: 400 })
+                if (path === '/api/comfy/panel' && req.method === 'POST') {
+                    try {
+                        // comfy-ts serve imports the modules at BOOT, so an
+                        // edited workflow needs a new process, never a reload
+                        const b = (await req.json().catch(() => ({}))) as { restart?: boolean }
+                        return Response.json(b.restart === true ? await d.comfy.restart() : await d.comfy.ensure())
+                    } catch (e) {
+                        return new Response((e as Error).message, { status: 400 })
+                    }
+                }
+                if (path === '/api/comfy/box') {
+                    const box = d.comfy.box()
+                    return Response.json({ ...box, up: await comfyBoxUp(box.url) })
+                }
+            }
+            if (path === '/api/live.json') {
+                if (d.live == null) return Response.json({ now: Date.now(), historyMs: 0, cap: 0, busy: 0, invocations: [], repos: [], runs: [], queued: 0, blocked: [] } satisfies LiveView)
+                return Response.json(d.live(), { headers: { 'cache-control': 'no-store' } })
+            }
+            if (path === '/api/repo-hub') {
+                const repo = new URL(req.url).searchParams.get('repo') ?? ''
+                return Response.json({ url: d.repoHub == null ? null : await d.repoHub(repo) })
+            }
+            if (path === '/api/timeline.json') {
+                if (d.timeline == null) return new Response('this hub keeps no run record', { status: 404 })
+                try {
+                    return Response.json(await d.timeline())
+                } catch (e) {
+                    return new Response(`the run record could not be shaped: ${(e as Error).message}`, { status: 500 })
+                }
+            }
+            if (path === '/api/tests.json') {
+                if (d.tests == null) return new Response('this hub keeps no run record', { status: 404 })
+                await d.refresh?.()
+                try {
+                    return Response.json(await d.tests(new URL(req.url).searchParams.get('check')), { headers: { 'cache-control': 'no-store' } })
+                } catch (e) {
+                    return new Response(`the test times could not be shaped: ${(e as Error).message}`, { status: 500 })
+                }
+            }
             if (path === '/api/status.json') {
-                const p = join(d.root, 'STATUS.md')
+                const p = join(d.root, LAYOUT.status)
                 return Response.json({ statusMd: existsSync(p) ? await Bun.file(p).text() : null })
             }
+            if (path === '/api/checks.json') {
+                // the SAME rows /api/resources.json carries, addressable on
+                // their own so an agent can curl them. One provider, two
+                // addresses, so the two can never disagree
+                const checks = d.collections().find((c) => c.id === 'checks')
+                if (checks == null) return Response.json({ checks: [] })
+                return Response.json({ checks: await checks.list() })
+            }
+            if (path === '/api/checks/when') {
+                // THE SWITCH. One endpoint for one writer: where a check runs
+                // and which suites are slow are the same managed block in
+                // repo.config.ts, and `expect` is the hash of the file the
+                // page last read, so a write can never land on top of an edit
+                // it never saw. The file is left DIRTY: committing it is his
+                if (req.method === 'GET') {
+                    const b = await readGateBlock(d.root)
+                    return Response.json({ ...b, dirty: configDirty(d.root) })
+                }
+                if (req.method === 'POST') {
+                    try {
+                        const body = (await req.json()) as GateEdit & { expect?: string }
+                        const b = await writeGateBlock(d.root, { when: body.when, slow: body.slow, slowRemove: body.slowRemove, words: body.words }, { expect: body.expect })
+                        await d.refresh?.()
+                        return Response.json({ ...b, dirty: configDirty(d.root) })
+                    } catch (e) {
+                        return new Response((e as Error).message, { status: 400 })
+                    }
+                }
+            }
+            if (path === '/api/prose.json' && d.prose != null) {
+                // every SK014 hit, grouped by word, noisiest first. The word
+                // lists are written through /api/checks/when like every other
+                // edit of repo.config.ts
+                await d.refresh?.()
+                try {
+                    return Response.json(await d.prose())
+                } catch (e) {
+                    return new Response(`the prose check could not run: ${(e as Error).message}`, { status: 500 })
+                }
+            }
             if (path === '/api/check/run' && req.method === 'POST') {
-                // stream wire lines as the check emits them; sh merges stderr
-                // so FAIL lines reach the page, not just the terminal
-                const proc = Bun.spawn(['sh', '-c', 'exec "$0" "$@" 2>&1', ...d.checkCmd], { cwd: d.root, stdout: 'pipe', stderr: 'ignore' })
-                return new Response(proc.stdout, { headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' } })
+                const body = (await req.json().catch(() => ({}))) as { only?: string[]; gate?: boolean }
+                // NDJSON: one line per event, so the page colours a row the
+                // moment its check finishes instead of waiting for the wall of
+                // text a shelled run could only deliver whole
+                const enc = new TextEncoder()
+                const stream = new ReadableStream({
+                    async start(ctrl) {
+                        const send = (e: Record<string, unknown>): void => {
+                            try { ctrl.enqueue(enc.encode(`${JSON.stringify(e)}\n`)) } catch { /* the tab went away mid-run */ }
+                        }
+                        let code = 1
+                        try {
+                            code = await d.runChecks({ line: (text) => send({ t: 'line', text }), check: (u) => send({ t: 'check', ...u }) }, { only: body.only, gate: body.gate })
+                        } catch (e) {
+                            send({ t: 'line', text: `FAIL: the run broke: ${(e as Error).message}` })
+                        }
+                        send({ t: 'done', code })
+                        ctrl.close()
+                    },
+                })
+                return new Response(stream, { headers: { 'content-type': 'application/x-ndjson; charset=utf-8', 'cache-control': 'no-store' } })
             }
             const page = (s: string): Response => new Response(withHome(s), { headers: { 'content-type': 'text/html; charset=utf-8' } })
             for (const g of d.graphs) {
-                if (path === `/graph/${g.id}`) return page(graphHtml(g.load(), { title: g.title }))
+                if (!path.startsWith(`/graph/${g.id}`)) continue
+                const routes = graphRoutes({ load: g.load, title: g.title, file: positionsFile(d.root, g.id), saveUrl: `/graph/${g.id}/positions` })
+                if (path === `/graph/${g.id}`) return page(routes.page())
                 if (path === `/graph/${g.id}/graph.json`) return Response.json(g.load())
+                if (path === `/graph/${g.id}/positions`) return routes.save(req)
             }
             // the media API namespace — the studio route table, ONE prefix strip
             if (d.studio != null && path.startsWith('/media/')) return d.studio.handle(req, path.slice('/media'.length))
@@ -142,5 +335,7 @@ export function serveHub(d: HubDeps): Hub {
         tick()
         pingTimer = setInterval(tick, 60_000)
     }
-    return { server, tools, stop: () => { if (pingTimer != null) clearInterval(pingTimer); server.stop(true) } }
+    // the panel process belongs to this hub: leaving it behind means the next
+    // launch adopts a server holding the previous run's modules
+    return { server, tools, liveReload: canLiveReload(), stop: () => { if (pingTimer != null) clearInterval(pingTimer); d.schedule?.stop(); d.comfy?.stop(); server.stop(true) } }
 }

package/src/shipkit.ts

@@ -1,6 +1,14 @@
 // rvlib-shipkit — barrel. One import per repo: defineRepo in repo.config.ts;
 // everything else is the machinery behind the shipkit CLI.
-export { defineRepo, loadRepoConfig, resolveFloor, allTasks, contractsTask } from './repo-config.ts'
+export { defineRepo, loadRepoConfig, resolveFloor } from './repo-config.ts'
+export { allTasks, composeChecks, gateInventory, gateRunnables, gateChecks } from './ledger/gate-checks.ts'
+export type { GateCheck, CheckRow } from './ledger/gate-checks.ts'
+// THE one shape every gate check has, and the file suffix that registers one
+export { check } from './check.ts'
+export { defineScan, mdPages, packageJson, type MdPage, type PackageJson, type Scan } from './scan.ts'
+export type { CheckDef, CheckEnv, CheckFrom } from './check.ts'
+export { discoverChecks, builtinCheckIds } from './core/discover-checks.ts'
+export type { DiscoveredCheck } from './core/discover-checks.ts'
 export type { RepoConfig, ServeConfig, FloorResolution, FloorSource } from './repo-config.ts'
 export { contractsConfigFrom, activeContracts, applyContractsResult } from './contracts/apply-contracts.ts'
 // the hub (`shipkit serve`): one server, one port, every tool a click away
@@ -12,24 +20,24 @@ 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'
-// release units — the ONE discovery every release surface reads (drift
+// units — the ONE discovery every release surface reads (drift
 // probes, per-unit tests, per-unit typecheck, the stranded-tag probe)
 export { resolveUnits, releaseOrder, unitById, renderTag, tagGlobs, prepublishScripts, unitPrepublishScripts } from './release/units.ts'
-export type { ReleaseUnit, ReleaseUnitDecl, UnitResolution } from './release/units.ts'
+export type { ReleaseUnit, UnitDecl, UnitResolution } from './release/units.ts'
 export { deriveRemote, dirtyPaths, remoteTags, strandedTags, tagExistsLocally } from './release/git-facts.ts'
 export { collectReports, renderReports, attentionLines } from './release/run-releases.ts'
 export { extractChangelogSection, promoteUnreleased, hasUnreleasedNotes, hasVersionSection } from './release/changelog.ts'
 export type { UnitReport } from './release/run-releases.ts'
-export { discoverChecks } from './core/discover-checks.ts'
-export type { DiscoveredCheck } from './core/discover-checks.ts'
-export { runTasks, selectTasks } from './core/task-runner.ts'
-export type { TaskDef, TaskResult, RunOpts, RunSummary } from './core/task-runner.ts'
-export { CheckSuite } from './core/check-suite.ts'
-export type { CheckSuiteOpts, CheckOutcome, GetSecret, SecretSpec } from './core/check-suite.ts'
+export { discoverLegacyChecks } from './core/discover-legacy-checks.ts'
+export type { LegacyCheck } from './core/discover-legacy-checks.ts'
+// THE runner: one DAG over every check, whatever declared it
+export { runChecks, selectChecks } from './core/check-runner.ts'
+export type { RunnableCheck, CheckResult, CheckEvent, RunChecksOpts, RunChecksSummary } from './core/check-runner.ts'
+export type { TaskDef } from './check.ts'
 // tui: type-only here — the store/view/panels import ink+mobx, which must
 // not load on every `shipkit ci`; runtime pieces live at rvlib-shipkit/src/tui/*
 export type { TuiPanelDef, TuiRow, TuiRowStatus, MarkedLine } from './tui/tui-panel.ts'
-export { CheckCtx, RateLimited, ToolUnresolved } from './core/check-ctx.ts'
+export { CheckCtx, RateLimited, type ScanCtx } from './core/check-ctx.ts'
 export { spawnWithTimeout } from './core/spawn-timeout.ts'
 export type { SpawnOutcome, SpawnTimeoutOpts } from './core/spawn-timeout.ts'
 export { writeStatus } from './core/write-status.ts'
@@ -38,7 +46,6 @@ export { formatLine, parseDuration, fmtStamp, parseWireOutput } from './core/wir
 export type { Line } from './core/wire.ts'
 // the SK rule registry — stable-id invariants `shipkit check` enforces;
 // consumers (e.g. a wiki lint verifying mentioned ids exist) read RULES
-export { RULES, ruleById } from './rules/rule-registry.ts'
 export { tagRuleLines } from './rules/rule.ts'
 export type { Rule, RuleEnv, FixResult } from './rules/rule.ts'
 export { evaluateContracts, pngDims } from './contracts/contracts-engine.ts'
@@ -49,7 +56,7 @@ export { allContracts } from './contracts/contract-manifests.ts'
 export { listAsks, openAsks, checkAsks, createAsk, renderAsksTable } from './asks/asks-queue.ts'
 export type { Ask, CreateOpts } from './asks/asks-queue.ts'
 // assets surface (folded in from the standalone atelier lib; that npm
-// package is frozen). A repo's .rv-assets/kit.ts imports defineKit and
+// package is frozen). A repo's .shipkit/assets/kit.ts imports defineKit and
 // declares its kinds; `shipkit assets …` derives the rest.
 export { defineKit, defineKind, comfy, canvas, manual, gemini, mediaOf, MEDIA_EXTS, geometryPanel, gridPanel, customPanel, validateKit, missingPanelScripts, loadKit, findAsset, allAssets, categoriesOf } from './assets/kit-config.ts'
 export type { KitConfig, ResolvedKit, Kind, KindMeta, Media, AssetSpec, GeneratorSpec, ComfyGen, CanvasGen, ManualGen, GeminiGen, PanelSpec, GeometryPanelSpec, GridPanelSpec, CustomPanelSpec, FoundAsset, ShipContext, ShipFn } from './assets/kit-config.ts'

package/src/smoke/run-smoke.ts

@@ -15,6 +15,7 @@
 // exercised in the field, by the run itself.
 import { mkdirSync } from 'fs'
 import { join } from 'path'
+import { LAYOUT } from '../core/layout.ts'
 
 export type SmokeRoute = {
     /** the path to visit, always leading `/` */
@@ -50,7 +51,7 @@ export type SmokeConfig = {
     routes: (string | SmokeRoute)[]
     /** absent: the run visits the routes anonymously */
     login?: SmokeLogin
-    /** pause between routes, ms. A route change fires a burst of requests, and
+    /** pause between routes, ms, default 3000. A route change fires a burst of requests, and
      *  a host with a CONCURRENT cap sheds some of them without CORS headers,
      *  which then reads as a broken app. 3000 is measured against PocketHost's
      *  15 concurrent per IP: 0 reported 8 of 12 routes, 3000 reports 12 of 12. */
@@ -66,7 +67,7 @@ const ROUTE_KEYS = new Set(['path', 'waitFor', 'open'])
 export const DEFAULT_LOGIN_PATH = '/login'
 
 export const DEFAULT_PACE_MS = 3000
-export const DEFAULT_SHOTS = 'tmp/smoke'
+export const DEFAULT_SHOTS = `${LAYOUT.tmp}/smoke`
 
 /** the whole shape, refused loud on the first thing that is not so. A typo
  *  here would otherwise land as a run that visits nothing and exits 0. */

package/src/start-repo.ts

@@ -1,7 +1,10 @@
-// `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
+// `shipkit start` — ensure <root>/<name> exists and that CLAUDE.md carries
+// its include lines (in order, at the top): the HOUSE lines below, unless
+// --include overrides them or the house index is not on this disk, then
+// `@./agent/index.md` whenever the repo has that file, because the scaffold
+// writes it and SK003 fails a repo that has it unrouted. 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'
@@ -9,18 +12,37 @@ import { homedir } from 'os'
 import { join } from 'path'
 import { ensureGitRepo, ensureIgnoreBaseline, firstGhLine, isScratch, publishRepo, runner, type Run } from './git-bootstrap.ts'
 import { initRepo } from './init-repo.ts'
+import { AGENT_LINE } from './checks/SK003-claude-md-shape.check.ts'
 import { scaffoldProject, TOOLCHAIN } from './scaffold/project-scaffold.ts'
 import { defaultHubPort } from './serve/hub-port.ts'
 
+/** the one template: `shipkit start <name>` is the only thing anyone types,
+ *  and a repo without the corvion wiki in its context is not a started repo.
+ *  Base context first, the repo's own router last, so repo docs override.
+ *  A public repo swaps line 1 for the gitignored `@./CLAUDE.local.md`,
+ *  which is why that line satisfies the first include (SK003) */
+export const HOUSE_INCLUDE = ['@~/dev/corvion/wiki/index.md', '@./agent/index.md']
+export const HOUSE_ALSO_OK = ['@./CLAUDE.local.md']
+/** the day-job checkout: never wired, never given an include */
+export const HOUSE_SKIP = ['monoloco']
+
+/** where the first house line points, `~` resolved against `home` */
+export const housePath = (home: string): string => {
+    const p = HOUSE_INCLUDE[0]!.replace(/^@/, '')
+    return p.startsWith('~/') ? join(home, p.slice(2)) : p
+}
+
 export type StartOpts = {
     /** parent dir for repos — default ~/dev */
     root?: string
-    /** lines CLAUDE.md must carry, in order; omitted = only ensure the dir */
+    /** lines CLAUDE.md must carry, in order; omitted = HOUSE_INCLUDE. An empty list means no house: only the agent route lands */
     include?: string[]
-    /** alternative lines that satisfy the FIRST include — never double-add */
+    /** alternative lines that satisfy the FIRST include — never double-add; omitted = HOUSE_ALSO_OK */
     alsoOk?: string[]
-    /** repo names that never get includes */
+    /** repo names shipkit never touches; omitted = HOUSE_SKIP */
     skip?: string[]
+    /** the home dir the first house line resolves against; omitted = os.homedir() */
+    home?: string
     /** true forces the github half, false refuses it. undefined = the default:
      *  a dir this run created, or an existing project, gets its private repo */
     github?: boolean
@@ -36,38 +58,22 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
         console.error(`FAIL: bad repo name '${name}' — letters/digits/._- only, no leading dot, no slashes`)
         return 2
     }
-    const dir = join(opts.root ?? join(homedir(), 'dev'), name)
+    const home = opts.home ?? homedir()
+    const dir = join(opts.root ?? join(home, 'dev'), name)
     const justCreated = !existsSync(dir)
     if (justCreated) {
         mkdirSync(dir, { recursive: true })
         console.error(`ok: created ${dir}`)
     }
-    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, `${want.join('\n')}\n`)
-            console.error(`ok: CLAUDE.md created with ${want.length} include line(s)`)
-        } else {
-            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`)
-            }
-        }
-    }
+    // flags win, else the house, and only on a machine that HAS the house:
+    // this lib is on npm, so elsewhere the template would be an include
+    // pointing at nothing plus the widened agent permissions riding on it
+    const houseOnDisk = existsSync(housePath(home))
+    const house = opts.include ?? (houseOnDisk ? HOUSE_INCLUDE : [])
+    if (opts.include == null && !houseOnDisk) console.error(`skip: no house wiki at ${housePath(home)} — CLAUDE.md gets the agent route only, and no .claude/ policy files`)
+    const alt = opts.alsoOk ?? HOUSE_ALSO_OK
+    const skipped = (opts.skip ?? HOUSE_SKIP).includes(name)
+    if (skipped && house.length > 0) console.error(`skip: ${name} is include-exempt — CLAUDE.md untouched`)
     // start is the from-anywhere verb, and a STARTED repo comes out READY:
     // any dir with no commit history gets a minimal package.json, a first
     // src/index.ts, the rvlib-shipkit dev dep, repo.config.ts via init, git,
@@ -78,7 +84,7 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
     // --skip means shipkit NEVER TOUCHES a listed repo (a day-job checkout
     // belongs on that list), not just no CLAUDE.md. And the cd contract survives a
     // failed adoption: the dir always prints, wiring trouble is a WARN.
-    if (!(opts.skip ?? []).includes(name)) {
+    if (!skipped) {
         // git BEFORE the shipkit scaffold, and whether or not the dir is a
         // project yet: an empty new dir is still work that must not live on
         // one disk. The PUBLISH (first commit → private repo → push) is the
@@ -120,7 +126,7 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
             // command line: init takes the caller's name over the manifest's,
             // and a dir found holding a forked package.json carries a name
             // nothing will listen on
-            try { scaffoldProject(dir, { name, port: defaultHubPort(name), print, claudePolicy: (opts.include ?? []).length > 0 }) }
+            try { scaffoldProject(dir, { name, port: defaultHubPort(name), print, claudePolicy: house.length > 0 }) }
             catch (e) { console.error(`WARN scaffold incomplete in ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
             // the wired scripts call node_modules binaries, so a scaffold
             // whose scripts exit 127 is not a started repo. Skips mirror the
@@ -150,6 +156,12 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
                 catch (e) { console.error(`WARN could not wire ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
             } else unscaffolded = true
         }
+        // CLAUDE.md after the scaffold and before the publish: the agent/
+        // router the scaffold just wrote gets routed, LAST (include order is
+        // semantic, SK003), and the file rides inside the first commit
+        const want = [...house]
+        if (existsSync(join(dir, 'agent/index.md')) && !want.includes(AGENT_LINE)) want.push(AGENT_LINE)
+        if (want.length > 0) ensureIncludes(join(dir, 'CLAUDE.md'), want, alt)
         if (wired) {
             try { await publishRepo(dir, { name, github: opts.github, justCreated, gh: opts.gh, print }) }
             catch (e) { console.error(`WARN could not publish ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
@@ -167,6 +179,33 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
     return 0
 }
 
+/** CLAUDE.md carries every wanted line, in order, at the top. Idempotent:
+ *  a line already there, or an `alt` line standing in for the first one, is
+ *  never added twice */
+function ensureIncludes(claudeMd: string, want: string[], alt: string[]): void {
+    if (!existsSync(claudeMd)) {
+        writeFileSync(claudeMd, `${want.join('\n')}\n`)
+        console.error(`ok: CLAUDE.md created with ${want.length} include line(s)`)
+        return
+    }
+    const lines = readFileSync(claudeMd, 'utf8').split('\n')
+    const lineSet = new Set(lines)
+    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) return
+    // insert after any leading include/alt lines so order survives, and
+    // BEFORE an agent route already there: a base line arriving later must
+    // not land under it and invert the order
+    const known = new Set([...want, ...alt])
+    let at = 0
+    while (at < lines.length && known.has(lines[at]!)) at++
+    const agentAt = lines.slice(0, at).indexOf(AGENT_LINE)
+    if (agentAt !== -1) at = agentAt
+    lines.splice(at, 0, ...missing)
+    writeFileSync(claudeMd, lines.join('\n'))
+    console.error(`ok: ${missing.length} missing include line(s) inserted into CLAUDE.md`)
+}
+
 /** what the closing line is allowed to say, all of it measured */
 export type RepoFacts = { tracked: number; uncommitted: number; hasHead: boolean; origin: string | null; pushed: boolean }