rvlib-shipkit 0.22.2 → 0.24.0

package/src/rules/SK006-npm-publish-safety.ts

@@ -14,9 +14,23 @@
 // and sanctioned sub-lib publishing must not turn this rule red.
 import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
+import { resolveUnits } from '../release/units.ts'
 import type { Rule } from './rule.ts'
 
-type Pkg = { name?: string; private?: boolean; publishConfig?: unknown; scripts?: Record<string, string> }
+type Pkg = {
+    name?: string
+    private?: boolean
+    publishConfig?: unknown
+    scripts?: Record<string, string>
+    dependencies?: Record<string, string>
+    peerDependencies?: Record<string, string>
+    optionalDependencies?: Record<string, string>
+}
+
+/** protocols that resolve to a path on THIS machine. In a block a consumer
+ *  installs, they are unresolvable: the published package is broken on
+ *  arrival, and it fails at install time for a stranger, never here. */
+const LOCAL_PROTOCOL = /^(link|file|portal|workspace):/
 
 export const npmPublishSafety: Rule = {
     id: 'SK006',
@@ -28,7 +42,27 @@ export const npmPublishSafety: Rule = {
         if (!existsSync(p)) return t.ok('no package.json — nothing publishable')
         let pkg: Pkg
         try { pkg = JSON.parse(readFileSync(p, 'utf8')) as Pkg } catch { return t.note('package.json unreadable — SK001 reports it') }
-        if (pkg.name?.startsWith('rvlib-') === true) return t.ok('rvlib-* package — publishes by design (distribute/npm owns it)')
+        // every block a CONSUMER resolves, for every unit that can publish:
+        // the ROOT is usually private, so scanning it alone guards nothing
+        const localHits: string[] = []
+        for (const u of [{ dir: env.root, id: 'root' }, ...resolveUnits(env.root, env.config).units.filter((x) => x.rel !== '')]) {
+            const up = join(u.dir, 'package.json')
+            if (!existsSync(up)) continue
+            let upkg: Pkg
+            try { upkg = JSON.parse(readFileSync(up, 'utf8')) as Pkg } catch { continue }
+            if (upkg.private === true) continue
+            for (const block of ['dependencies', 'peerDependencies', 'optionalDependencies'] as const)
+                for (const [dep, range] of Object.entries(upkg[block] ?? {}))
+                    if (LOCAL_PROTOCOL.test(range)) localHits.push(`${u.id}: ${block}.${dep} = ${range}`)
+        }
+        if (localHits.length > 0)
+            t.fail(
+                `${localHits.join(', ')} — a local protocol cannot resolve on a consumer's machine, so publishing that ships a package which fails at install. Declare the version it WILL be, and keep the local wiring in overrides (npm ignores those from a dependency) or in devDependencies`,
+            )
+        if (pkg.name?.startsWith('rvlib-') === true) {
+            if (localHits.length === 0) t.ok('rvlib-* package — publishes by design (distribute/npm owns it)')
+            return
+        }
         if (pkg.private !== true) return t.note('private:true missing — SK001 reports it; publish machinery not judged until the lock is on')
         const machinery: string[] = []
         if (pkg.publishConfig != null) machinery.push('publishConfig')
@@ -38,6 +72,6 @@ export const npmPublishSafety: Rule = {
             machinery.push(`scripts.publish (runs npm/bun publish)`)
         if (machinery.length > 0)
             t.fail(`private package carries publish machinery: ${machinery.join(', ')} — dead weight now, a loaded gun the day private flips; delete it or make the repo a published lib on purpose`)
-        else t.ok(`private package — no publishConfig / prepublish* / npm-publishing 'publish' script on the root`)
+        else if (localHits.length === 0) t.ok(`private package — no publishConfig / prepublish* / npm-publishing 'publish' script on the root, no local dependency protocol in any unit`)
     },
 }

package/src/rules/SK011-sibling-unit-ranges.ts

@@ -0,0 +1,91 @@
+// SK011 — a dependency range on a SIBLING release unit must be satisfied by
+// the version that sibling actually carries (build/shipkit.md, release units).
+//
+// The failure it exists for: one unit is edited and its dependents keep a
+// range that names a version nobody published, or an older one that lacks the
+// code they now call. Both are invisible until a consumer installs, which is
+// the worst place to find out. `shipkit bump` moves these ranges forward on
+// every bump, so a red here means someone hand-edited a range, or a bump was
+// interrupted.
+//
+// Local protocols (link:, file:) are SK006's story, not this rule's.
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { resolveUnits } from '../release/units.ts'
+import type { Rule } from './rule.ts'
+
+type Pkg = {
+    dependencies?: Record<string, string>
+    peerDependencies?: Record<string, string>
+    optionalDependencies?: Record<string, string>
+    devDependencies?: Record<string, string>
+}
+
+const BLOCKS = ['dependencies', 'peerDependencies', 'optionalDependencies', 'devDependencies'] as const
+
+/** does this range name the sibling's CURRENT version as its floor? Not
+ *  "does it resolve": `^0.1.1` happily resolves 0.1.2, and then a consumer
+ *  whose tree already holds 0.1.1 keeps it and misses the release. The floor
+ *  moves on every bump, so a stale one means a bump nobody propagated.
+ *  Deliberately small: `^x.y.z`, `~x.y.z` or an exact pin, and a range shape
+ *  it cannot read is SKIPPED rather than guessed at. */
+export function floorMatches(version: string, range: string): boolean | null {
+    const r = range.trim().match(/^([\^~]?)(\d+\.\d+\.\d+)$/)
+    if (r == null || !/^\d+\.\d+\.\d+/.test(version)) return null
+    return r[2] === version
+}
+
+/** does `version` satisfy a caret/tilde/exact range? Kept for the resolution
+ *  question, which is a different one from the floor question above. */
+export function satisfiesSimple(version: string, range: string): boolean | null {
+    const v = version.match(/^(\d+)\.(\d+)\.(\d+)/)
+    const r = range.trim().match(/^([\^~]?)(\d+)\.(\d+)\.(\d+)$/)
+    if (v == null || r == null) return null
+    const [, op, RA, RI, RP] = r as unknown as [string, string, string, string, string]
+    const [va, vi, vp] = [Number(v[1]), Number(v[2]), Number(v[3])]
+    const [ra, ri, rp] = [Number(RA), Number(RI), Number(RP)]
+    const atLeast = va > ra || (va === ra && (vi > ri || (vi === ri && vp >= rp)))
+    if (op === '^') {
+        // caret on 0.x pins the MINOR: ^0.1.4 accepts 0.1.9, never 0.2.0
+        if (ra === 0) return va === 0 && vi === ri && atLeast
+        return va === ra && atLeast
+    }
+    if (op === '~') return va === ra && vi === ri && atLeast
+    return va === ra && vi === ri && vp === rp
+}
+
+export const siblingUnitRanges: Rule = {
+    id: 'SK011',
+    blocking: true,
+    title: 'sibling unit ranges',
+    owner: 'build/shipkit.md',
+    lint: (t, env) => {
+        const { units } = resolveUnits(env.root, env.config)
+        const version = new Map(units.map((u) => [u.name, u.version]))
+        if (units.length < 2) return t.ok('one release unit — no sibling ranges to keep honest')
+        const bad: string[] = []
+        let checked = 0
+        for (const u of units) {
+            const p = join(u.dir, 'package.json')
+            if (!existsSync(p)) continue
+            let pkg: Pkg
+            try { pkg = JSON.parse(readFileSync(p, 'utf8')) as Pkg } catch { continue }
+            for (const block of BLOCKS)
+                for (const [dep, range] of Object.entries(pkg[block] ?? {})) {
+                    const actual = version.get(dep)
+                    if (actual == null) continue
+                    if (/^(link|file|portal|workspace):/.test(range)) continue
+                    const ok = floorMatches(actual, range)
+                    if (ok == null) continue
+                    checked++
+                    if (!ok)
+                        bad.push(
+                            `${u.id}: ${block}.${dep} floors at ${range}, ${dep} is ${actual}${satisfiesSimple(actual, range) === true ? ' (it resolves, but a tree already holding the older one keeps it)' : ''}`,
+                        )
+                }
+        }
+        if (bad.length > 0)
+            t.fail(`${bad.join(' · ')} — a sibling range FLOORS at the version it names, so a stale floor lets a consumer keep an older copy and miss the release. \`shipkit bump\` moves every floor forward in the version commit, so a red here is a bump nobody propagated`)
+        else t.ok(`${checked} sibling range(s) floor at exactly the version each unit carries`)
+    },
+}

package/src/rules/rule-registry.ts

@@ -13,6 +13,7 @@ import { githubVisibility } from './SK007-github-visibility.ts'
 import { reviewerAgent } from './SK008-reviewer-agent.ts'
 import { commitAiTells } from './SK009-commit-ai-tells.ts'
 import { undeclaredReleaseUnit } from './SK010-undeclared-release-unit.ts'
+import { siblingUnitRanges } from './SK011-sibling-unit-ranges.ts'
 
 export const RULES: readonly Rule[] = [
     packageJsonShape,
@@ -25,6 +26,7 @@ export const RULES: readonly Rule[] = [
     reviewerAgent,
     commitAiTells,
     undeclaredReleaseUnit,
+    siblingUnitRanges,
 ]
 
 // THE id shape, one place: 2-4 uppercase letters + exactly 3 digits. `SK` is

package/src/serve/hub-app/cols-svc.ts

@@ -129,7 +129,7 @@ export class ColsSvc {
     async remark(body: Record<string, unknown>): Promise<void> {
         const text = this.remarkDraft.trim()
         if (text === '') return
-        // draft survives a failed send — his words are never erased
+        // draft survives a failed send, so nothing typed is ever erased
         const ok = await this.act('remark', { ...body, text })
         if (ok) runInAction(() => { this.remarkDraft = '' })
     }

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

@@ -173,7 +173,7 @@ const Palette = observer(() => {
     )
 })
 
-// remark box on the ASSET view too — his words land in .rv-assets/notes.md
+// remark box on the ASSET view too: remarks land in .rv-assets/notes.md
 // and come back as `remarks` (exchange both ways, media included)
 const AssetRemarks = observer(() => {
     const m = app.media

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

@@ -60,12 +60,18 @@ aside{border-right:1px solid var(--line);background:var(--panel);overflow-y:auto
 
 /* ── main column ── */
 main{display:flex;flex-direction:column;height:100vh;overflow:hidden}
-/* topbar: the prompt is its OWN full-width row (small mono, auto-grows to
-   its content, scrolls only past ~14 lines), then ONE slim toolbar row */
+/* topbar: the prompt is its OWN full-width row (folded by default to one
+   ellipsized line; expanded = small mono, auto-grows to its content,
+   scrolls only past ~14 lines), then ONE slim toolbar row */
 .bar{display:flex;flex-direction:column;gap:8px;padding:10px 16px;border-bottom:1px solid var(--line);background:var(--panel)}
 textarea{width:100%;min-height:64px;background:var(--bg);color:var(--ink);border:1px solid var(--line);
  border-radius:9px;padding:9px 11px;font:12px/1.5 ui-monospace,Menlo,monospace;resize:vertical}
-.bar .prompt{min-height:36px;max-height:252px;overflow-y:auto;resize:none;font:11px/1.5 ui-monospace,Menlo,monospace;padding:7px 10px}
+.promptrow{display:flex;gap:6px;align-items:flex-start}
+.promptrow .fold{flex:none;background:var(--panel2);color:var(--dim);border:1px solid var(--line);border-radius:9px;
+ padding:6px 9px;font-size:11px;line-height:1.5}
+.bar .prompt{flex:1;min-height:36px;max-height:252px;overflow-y:auto;resize:none;font:11px/1.5 ui-monospace,Menlo,monospace;padding:7px 10px}
+.bar .prompt.folded{min-height:0;max-height:none;overflow:hidden;white-space:nowrap;text-overflow:ellipsis;cursor:pointer;
+ color:var(--dim);background:var(--bg);border:1px solid var(--line);border-radius:9px}
 .toolbar{display:flex;gap:8px;align-items:center;min-height:30px}
 .toolbar button{padding:5px 11px;font-size:12px}
 .toolbar .sp{flex:1}

package/src/serve/hub-app/media-svc.ts

@@ -58,6 +58,11 @@ export class MediaSvc {
     drawerOpen = false
     jsonText = ''
     jsonMsg = ''
+    /** prompt folded to one ellipsized line (session state, click toggles) */
+    promptOpen = false
+
+    /** latched by picking a NON-default tab, until then a sole custom panel is the default */
+    private tabPicked = false
 
     private hbTimer: ReturnType<typeof setInterval> | null = null
     private rectTimer: ReturnType<typeof setTimeout> | null = null
@@ -66,8 +71,8 @@ export class MediaSvc {
     private savedPrompt = ''
 
     constructor(private st: HubSt) {
-        makeAutoObservable<this, 'st' | 'hbTimer' | 'rectTimer' | 'promptTimer' | 'savedPrompt'>(
-            this, { st: false, hbTimer: false, rectTimer: false, promptTimer: false, savedPrompt: false })
+        makeAutoObservable<this, 'st' | 'hbTimer' | 'rectTimer' | 'promptTimer' | 'savedPrompt' | 'tabPicked'>(
+            this, { st: false, hbTimer: false, rectTimer: false, promptTimer: false, savedPrompt: false, tabPicked: false })
     }
 
     start(): void {
@@ -161,7 +166,11 @@ export class MediaSvc {
             this.savedPrompt = r.asset.prompt
             this.promptMsg = ''
             if (this.deterministic) this.n = '1'
-            if (this.tab.startsWith('c:') && !r.asset.custom.some((c) => `c:${c.id}` === this.tab)) this.tab = 'asset'
+            // custom panels are the working surfaces, a kind with exactly one
+            // gets it as the default tab (setTab latches an explicit divergence)
+            const sole = r.asset.custom.length === 1 ? `c:${r.asset.custom[0]!.id}` : null
+            if (this.tab.startsWith('c:') && !r.asset.custom.some((c) => `c:${c.id}` === this.tab)) this.tab = sole ?? 'asset'
+            else if (!this.tabPicked && sole != null) this.tab = sole
             this.pickActive(r)
         })
         if (this.hasGeom) await this.loadRect()
@@ -279,6 +288,9 @@ export class MediaSvc {
         this.promptMsg = 'copied'
         setTimeout(() => runInAction(() => { this.promptMsg = '' }), 900)
     }
+    togglePrompt(): void {
+        this.promptOpen = !this.promptOpen
+    }
 
     toggleFold(cat: string): void {
         if (this.st.query.trim() !== '') return // folds yield to a live search
@@ -370,9 +382,12 @@ export class MediaSvc {
         await this.fillCat()
     }
 
-    // ── drawer: asset json (read-only) · roll meta sidecar · custom panels ─
+    // ── drawer: custom panels · asset json (read-only) · roll meta sidecar ─
     setTab(tab: string): void {
         this.tab = tab
+        // clicking the sole panel IS the default, only a different pick latches
+        const c = this.detail?.asset.custom ?? []
+        if (tab !== (c.length === 1 ? `c:${c[0]!.id}` : null)) this.tabPicked = true
         this.drawerOpen = true
         void this.loadTab()
     }

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

@@ -1,6 +1,6 @@
 // Media views — topbar, info chips, stage (image/audio + geometry), roll
-// strip, category grid + size-true lineup, drawer (asset json · roll meta ·
-// repo-defined custom panels). Feature parity with the deleted vanilla
+// strip, category grid + size-true lineup, drawer (repo-defined custom
+// panels · asset json · roll meta). Feature parity with the deleted vanilla
 // studio SPA; state lives in MediaSvc (components read and call).
 import { runInAction } from 'mobx'
 import { observer } from 'mobx-react-lite'
@@ -27,12 +27,23 @@ export const MediaTopbar = observer(({ app }: { app: HubSt }) => {
         if (t == null) return
         t.style.height = 'auto'
         t.style.height = `${t.scrollHeight + 2}px`
-    }, [m.prompt])
+    }, [m.prompt, m.promptOpen])
     return (
         <div className="bar">
-            {/* the prompt AUTOSAVES (debounced) — no save button, no fear */}
-            <textarea className="prompt" ref={taRef} value={m.prompt} placeholder="select an asset ←"
-                onChange={(e) => m.setPrompt(e.target.value)} />
+            {/* the prompt AUTOSAVES (debounced), no save button, no fear.
+                folded (default) = one ellipsized line, click to expand */}
+            <div className="promptrow">
+                <button className="fold" title={m.promptOpen ? 'fold the prompt' : 'expand the prompt'}
+                    onClick={() => m.togglePrompt()}>{m.promptOpen ? '▾' : '▸'}</button>
+                {m.promptOpen
+                    ? <textarea className="prompt" ref={taRef} value={m.prompt} placeholder="select an asset ←"
+                        onChange={(e) => m.setPrompt(e.target.value)} />
+                    : <div className="prompt folded" onClick={() => m.togglePrompt()}>
+                        {/* placeholder only when NOTHING is selected, a selected
+                            asset with an empty prompt shows an empty line */}
+                        {m.curId == null ? 'select an asset ←' : m.prompt === '' ? '\u00a0' : m.prompt}
+                    </div>}
+            </div>
             <div className="toolbar">
                 {!manual ? <button disabled={m.curId == null} onClick={() => void m.generate()}>Generate</button> : null}
                 {!manual ? (
@@ -232,7 +243,7 @@ export const CatGrid = observer(({ app }: { app: HubSt }) => {
     )
 })
 
-// ── drawer: asset json (read-only) · roll meta · custom panels ───────────
+// ── drawer: custom panels · asset json (read-only) · roll meta ───────────
 const PanelHost = observer(({ app }: { app: HubSt }) => {
     const m = app.media
     const ref = useRef<HTMLDivElement>(null)
@@ -273,11 +284,13 @@ export const Drawer = observer(({ app }: { app: HubSt }) => {
     return (
         <div className="drawer">
             <div className="tabs">
-                {[{ id: 'asset', label: 'asset' }, { id: 'meta', label: 'roll meta' }, ...customs.map((c) => ({ id: `c:${c.id}`, label: c.id }))].map((t) => (
+                {/* customs lead: they are the working surfaces, json tabs are diagnostics */}
+                {[...customs.map((c) => ({ id: `c:${c.id}`, label: c.id })), { id: 'asset', label: 'asset' }, { id: 'meta', label: 'roll meta' }].map((t) => (
                     <button key={t.id} className={m.tab === t.id ? 'on' : ''} onClick={() => m.setTab(t.id)}>{t.label}</button>
                 ))}
                 <span className="sp" />
-                <button className="ghost" onClick={() => runInAction(() => { m.drawerOpen = !m.drawerOpen })}>JSON ▾</button>
+                {/* names the drawer, not the tab set (a sole custom panel is the default content) */}
+                <button className="ghost" onClick={() => runInAction(() => { m.drawerOpen = !m.drawerOpen })}>drawer ▾</button>
             </div>
             {m.drawerOpen ? (
                 <div id="drawerbody" className="on">

package/src/serve/run-serve.ts

@@ -28,7 +28,7 @@ export function defaultHubPort(name: string): number {
 
 export async function resolveHubDeps(root: string, c: RepoConfig, io: ServeIo, o?: { port?: number }): Promise<HubDeps> {
     // the default wiki graph exists only when the repo HAS a wiki dir: a
-    // game repo's hub advertising a wiki route was startup noise (his catch
+    // game repo's hub advertising a wiki route was startup noise
     // 2026-08-05). A config-declared wikiGraph always mounts.
     const wikiGraph = c.serve?.wikiGraph != null
         ? { title: c.serve.wikiGraph.title ?? `${c.name} wiki`, load: c.serve.wikiGraph.load }
@@ -109,11 +109,13 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
     try {
         const hub = serveHub(deps)
         const base = `http://localhost:${hub.server.port}`
-        io.print(`ok: ${c.name} hub → ${base}`)
-        // the '/' tool IS the banner line above — printing it again was noise
-        for (const t of hub.tools) if (t.path !== '/') io.print(`ok: ${t.label} → ${base}${t.path}`)
+        // a banner, not a checklist: one clickable line, then what is inside,
+        // dimmed by indentation. Wire prefixes stay reserved for problems.
+        io.print(`${c.name} hub → ${base}`)
+        const routes = hub.tools.filter((t) => t.path !== '/').map((t) => `${t.label} ${t.path}`).join(' · ')
+        if (routes !== '') io.print(`  also: ${routes}`)
         // the off-machine door (phone, other machines) — publicHost is config
-        if (c.serve?.publicHost != null) io.print(`ok: public → http://${c.serve.publicHost}:${hub.server.port}/`)
+        if (c.serve?.publicHost != null) io.print(`  phone: http://${c.serve.publicHost}:${hub.server.port}/`)
         await new Promise(() => {}) // the hub owns the process — never resolve
         return 0
     } catch (e) {
@@ -126,8 +128,9 @@ export async function runServe(root: string, io: ServeIo, o?: { port?: number })
             if (owner?.hub === 'shipkit' && owner.name === c.name) {
                 // a re-run terminal stays as clickable as a first run — the
                 // owner's /hub.json tool list is the same source of truth
-                io.print(`ok: hub already served → http://localhost:${deps.port} (another window owns it)`)
-                for (const t of owner.tools ?? []) if (t.path !== '/') io.print(`ok: ${t.label} → http://localhost:${deps.port}${t.path}`)
+                io.print(`${c.name} hub → http://localhost:${deps.port} (already running in another window)`)
+                const routes = (owner.tools ?? []).filter((t) => t.path !== '/').map((t) => `${t.label} ${t.path}`).join(' · ')
+                if (routes !== '') io.print(`  also: ${routes}`)
                 return 0
             }
             io.printErr(`FAIL: port ${deps.port} is taken by ${owner?.name != null ? `repo '${owner.name}'` : 'another process'} — set serve: { port } in repo.config.ts to a free one`)

package/src/serve/serve-hub.ts

@@ -99,8 +99,8 @@ export function serveHub(d: HubDeps): Hub {
                     }
                     else if (path === '/api/act/post-feedback') appendPostFeedback(d.root, b.channel ?? '', b.file ?? '', b.text ?? '')
                     else if (path === '/api/act/remark') {
-                        // ONE remark verb, routed by collection — his words
-                        // land in the item's own truth file
+                        // ONE remark verb, routed by collection: a remark
+                        // lands in the item's own truth file
                         const text = (b.text ?? '').trim()
                         if (text === '') return new Response('empty remark', { status: 400 })
                         if (b.kind === 'ask') appendAskRemark(d.root, d.asksDir, b.file ?? '', text)

package/src/start-repo.ts

@@ -7,7 +7,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
-import { ensureGitRepo, publishRepo, type Run } from './git-bootstrap.ts'
+import { ensureGitRepo, firstGhLine, IGNORE_BASELINE, isScratch, publishRepo, runner, type Run } from './git-bootstrap.ts'
 import { initRepo } from './init-repo.ts'
 
 export type StartOpts = {
@@ -24,6 +24,9 @@ export type StartOpts = {
     github?: boolean
     /** how `gh` runs — injected by tests, which never touch a real account */
     gh?: Run | null
+    /** how `bun` runs for the dep install — injected by tests, which never
+     *  touch the network. An explicit null means no bun on this machine */
+    bun?: Run | null
 }
 
 export async function startRepo(name: string, opts: StartOpts = {}): Promise<number> {
@@ -66,13 +69,17 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
             }
         }
     }
-    // start is the from-anywhere verb: a dir that is already a real project
-    // (package.json) gets wired on the spot, so a pre-existing repo goes
-    // 0 → shipkit'd with the one command. init itself stays cwd-only, like
-    // git init. A brand-new empty dir gets git + its remote all the same, and
-    // is told what is next, because the shipkit scaffold needs a package.json.
-    // --skip means shipkit NEVER TOUCHES that repo (his job repo lives on
-    // this list), not just no CLAUDE.md. And the cd contract survives a
+    // start is the from-anywhere verb, and a STARTED repo comes out READY:
+    // a brand-new dir gets a minimal package.json, a first src/index.ts, the
+    // rvlib-shipkit dev dep, repo.config.ts via init, git, first commit,
+    // private github repo, push. A dir that already holds a project
+    // (package.json) gets the same minus the scaffold. A PRE-EXISTING dir
+    // with NO project is the everyday cd into some old folder: git only,
+    // never a scaffold (--github forces only the github half, so it must
+    // never write a package.json into a folder that holds someone's files).
+    // init itself stays cwd-only, like git init.
+    // --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)) {
         // git BEFORE the shipkit scaffold, and whether or not the dir is a
@@ -83,6 +90,41 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
         let wired = false
         try { wired = await ensureGitRepo(dir, { print }) }
         catch (e) { console.error(`WARN could not wire git in ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
+        // the scaffold fires ONLY for a dir this run created (never --github:
+        // forcing the github half on an old folder must not write a project
+        // into it), and only where git actually wired (a subdirectory of
+        // another work tree gets nothing): the minimal package.json lands so
+        // init below has its floor and the first commit carries a working
+        // repo, not an empty husk
+        if (wired && justCreated && !existsSync(join(dir, 'package.json')) && !existsSync(join(dir, 'repo.config.ts'))) {
+            const pkg = { name, version: '0.0.0', private: true, type: 'module', scripts: {} }
+            writeFileSync(join(dir, 'package.json'), JSON.stringify(pkg, null, 4) + '\n')
+            // the first source file, so the ci gate is green from commit one:
+            // an imports gate over zero files fails loud on purpose
+            mkdirSync(join(dir, 'src'), { recursive: true })
+            writeFileSync(join(dir, 'src', 'index.ts'), 'export {}\n')
+            console.error('ok: package.json + src/index.ts scaffolded (private, type module)')
+            // the install below creates node_modules/ BEFORE the first
+            // commit, so the baseline ignore must exist first (SK004's block,
+            // written by init, does not carry node_modules)
+            if (!existsSync(join(dir, '.gitignore'))) writeFileSync(join(dir, '.gitignore'), `${IGNORE_BASELINE.join('\n')}\n`)
+            // the scripts init wires call node_modules/rvlib-shipkit — a
+            // scaffold whose scripts exit 127 is not a started repo. Skips
+            // mirror the github half's guards: an injected runner wins, the
+            // env switch turns it off machine-wide, a temp dir is a rehearsal
+            // that must not pull the network. init owns the fix line for
+            // every not-installed outcome
+            let bun: Run | null
+            if (opts.bun !== undefined) bun = opts.bun
+            else if ((process.env.SHIPKIT_NO_INSTALL ?? '') !== '') { console.error('skip: rvlib-shipkit install — SHIPKIT_NO_INSTALL is set'); bun = null }
+            else if (isScratch(dir)) { console.error(`skip: rvlib-shipkit install — ${dir} is a temp dir`); bun = null }
+            else bun = Bun.which('bun') == null ? null : runner('bun', dir, 180_000)
+            if (bun != null) {
+                const r = await bun(['add', '-d', 'rvlib-shipkit'])
+                if (r.code === 0) console.error('ok: rvlib-shipkit installed (dev dep)')
+                else console.error(`WARN rvlib-shipkit install failed: ${firstGhLine(r.out)}`)
+            }
+        }
         let unscaffolded = false
         if (!existsSync(join(dir, 'repo.config.ts'))) {
             if (existsSync(join(dir, 'package.json'))) {