rvlib-shipkit 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.27.0
+
+- **`shipkit start` writes the whole day-one shape, not just a repo.** A started dir was a repo you still had to furnish: no tsconfig, no editor tasks, no agent wiki behind CLAUDE.md's own include, no verify skill, no attribution silencer, and two baseline scripts the rules then warned about. One scaffold pass now writes all of it (`src/scaffold/project-scaffold.ts`), installs the toolchain, and the result passes its OWN `shipkit ci` with nothing left but the identity assets a human has to choose. Every file is CREATE-ONLY, so running it over a half-built dir never destroys work.
+- **The scaffolded tsconfig drops the root `*.ts` glob.** That glob picks up `repo.config.ts`, whose `rvlib-shipkit` import is raw TypeScript, so `tsc --noEmit` walked into the dependency and typechecked the entire library (`skipLibCheck` covers `.d.ts` only). A fresh repo's typecheck failed on someone else's code, which no user can fix. List a root config file by name when one earns checking, the way a vite repo lists `vite.config.ts`.
+- **The baseline `.gitignore` is written before anything else can create one.** The scaffold's own ignore lines landed first, so the `node_modules/` baseline was skipped and the first commit refused on 7700 staged dependency files.
+- **`start` says how to land in the dir it made.** A child process cannot cd its parent shell, so the path goes to stdout for a sourced wrapper and, when none is in play, the last line names the `cd`. `SHIPKIT_CD=1` silences it for a wrapper that does the move.
+
+## 0.26.0
+
+- **start means START: the full bootstrap runs on any dir with no commit history.** 0.25.0 widened the scaffold to empty dirs and commitless husks, and the very next field run hit the remaining wall: a folder holding one stray readme was still refused. The gate is now commit history alone: no commits means the dir is startable, and loose files simply ride in the first commit as the repo's first backup. What start still refuses is structural: a repo with real history is never scaffolded or pushed over, a subdirectory of another work tree gets nothing, a temp dir never mints a github repo, and the risky-file refusal still blocks a first commit carrying a `.env` or `node_modules` anywhere in the tree.
+
 ## 0.25.0
 
 - **A pre-existing EMPTY dir (or a commitless git-only husk) starts like a brand-new one.** The full-bootstrap scaffold keyed on "this run created the dir", so `mkdir foo` followed by `shipkit start foo`, or a re-run over the husk an older shipkit left, still ended in git-only plus manual next steps. The everyday-cd guard exists to protect a folder holding files, and an empty folder holds none: emptiness (junk like `.DS_Store` aside) now counts as starting intent, a `.git` with no commits counts too, and a git dir with real history stays untouched. A folder with files keeps the old behavior exactly.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.25.0",
+    "version": "0.27.0",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
     "type": "module",

package/src/cli/cmd_Start.ts

@@ -9,7 +9,7 @@ export class StartCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in: ensures the dir, seeds CLAUDE.md include lines, and on a BRAND-NEW dir scaffolds a minimal package.json + src/index.ts + the rvlib-shipkit dev dep, wires shipkit (repo.config.ts via init), then runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. A pre-existing folder counts as brand new when it is EMPTY or a commitless git husk. One holding files gets git only, never a scaffold (--github forces only the github half for it). Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
+        description: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in: ensures the dir, seeds CLAUDE.md include lines, scaffolds a minimal package.json + src/index.ts + the rvlib-shipkit dev dep on any dir with no commit history (loose files ride in the first commit), wires shipkit (repo.config.ts via init), then runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Only a repo with real history is left as it is. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
         examples: [
             ['create or enter ~/dev/pong: dir, package.json, shipkit wiring, git, first commit, private github repo, push', 'shipkit start pong'],
             ['seed CLAUDE.md includes', "shipkit start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],

package/src/scaffold/files/agent-changelog.md

@@ -0,0 +1,9 @@
+# Changelog
+
+Newest first. Each entry narrates WHAT changed and WHY, for the next
+session that arrives with no context.
+
+## {{DATE}}
+
+- Repo scaffolded: package.json, tsconfig, vscode tasks, agent/ wiki,
+  shipkit wiring, first commit.

package/src/scaffold/files/agent-coding.md

@@ -0,0 +1,35 @@
+# Coding standards — {{NAME}}
+
+The always-loaded page. Keep it to hard gates plus a screen of standards.
+Once it grows past that, split the gates into `process.md`, make that the
+always-loaded one, and route the rest by surface.
+
+## Gates
+
+- **Spec-first**: the `agent/` page changes BEFORE the code it describes.
+- **`shipkit ci` is the verification.** Run it, not the linter, the
+  typechecker and the tests one at a time.
+- **Repro before fix**: write the failing test, then fix, then re-run it.
+- One code path per concern. Delete the redundant mechanism rather than
+  keeping two.
+
+## TypeScript
+
+- `strict`, `noUncheckedIndexedAccess`, `noUnusedLocals`,
+  `noUnusedParameters`, `noFallthroughCasesInSwitch`: all on, always.
+- No `as any`, no `@ts-ignore`. A cast that survives review is listed here
+  with the reason it is safe.
+- Imports are absolute (`src/...`), never `../..` chains.
+
+## Comments
+
+- The default is NO comment. Write one only for what the code cannot say:
+  a constraint, an invariant, a performance reason, a workaround.
+- Never narrate the edit, the date, or who asked for it. That is what git
+  and the changelog are for.
+- Lowercase, no dash punctuation, matching the density of the file.
+
+## Layout
+
+- A file past ~600 lines is a smell; carve it at ~800.
+- Anti-patterns: <fill as the project teaches them>.

package/src/scaffold/files/agent-index.md

@@ -0,0 +1,25 @@
+# {{NAME}}
+
+<One paragraph: what this project is, who it is for, and the stack.>
+
+## Quick start
+
+- `bun run hub` → the repo toolbox at http://localhost:{{PORT}}
+- `shipkit ci` → THE gate: run it to check your work, never the parts
+
+This folder is the project's internal wiki and its SPEC. Update the page
+BEFORE the change it describes.
+
+**Always loaded every session:**
+
+@coding.md
+
+Read the matching page before touching a surface:
+
+| read when touching… | page |
+|---|---|
+| any source file | `agent/coding.md` |
+| recent changes and why | `agent/changelog.md` |
+
+Grow this table: a subsystem, a service, a runbook each earn their own page,
+cross-linked from here.

package/src/scaffold/files/claude-settings-local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(shipkit *)",
+      "Bash(bun run *)",
+      "Bash(bun test*)",
+      "Bash(bun install*)",
+      "Bash(bun add *)",
+      "Bash(bunx tsc*)",
+      "Bash(bunx wrangler*)",
+      "Bash(git status*)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git add *)",
+      "Bash(git commit*)",
+      "Bash(git push*)",
+      "Bash(curl *)",
+      "Bash(oxlint*)",
+      "Bash(./deploy.sh)"
+    ],
+    "deny": []
+  }
+}

package/src/scaffold/files/claude-settings.json

@@ -0,0 +1,6 @@
+{
+  "attribution": {
+    "commit": "",
+    "pr": ""
+  }
+}

package/src/scaffold/files/tsconfig.json

@@ -0,0 +1,42 @@
+{
+   // ONE tsconfig at the repo root — copy as-is (replaces whatever
+   // `bun init` generated), adjust include/paths to the repo's dirs.
+   "compilerOptions": {
+      // real node resolution, no bundler hand-waving — what tsc resolves is
+      // what bun resolves at runtime (bun follows tsconfig paths)
+      "module": "nodenext",
+      "moduleResolution": "nodenext",
+
+      // the pair that legalizes `from 'src/foo/Bar.ts'` — extensions are part
+      // of the exact-path search key; tsc only typechecks, bun/vite emit
+      "allowImportingTsExtensions": true,
+      "noEmit": true,
+
+      // THE mapping that makes 'src/...' specifiers resolve. No baseUrl —
+      // explicit paths only, so bare specifiers can't collide with packages.
+      // paths doubles as an escape hatch for deps with broken "exports"
+      // (map the submodule) — but bun follows these at RUNTIME too, so
+      // runtime-loaded packages need "exports" patches instead, or bun
+      // resolves a .d.ts where it needs a .js.
+      "paths": {
+         "src/*": ["./src/*"],
+         "scripts/*": ["./scripts/*"]
+      },
+
+      // every file is a module even with no import/export (standalone scripts)
+      "moduleDetection": "force",
+
+      // the house TS standard is all five, always on (meta/rv-conventions):
+      // strict alone leaves dead locals and fallthrough bugs in the codebase
+      "strict": true,
+      "noUncheckedIndexedAccess": true,
+      "noUnusedLocals": true,
+      "noUnusedParameters": true,
+      "noFallthroughCasesInSwitch": true,
+      "isolatedModules": true,
+      "skipLibCheck": true,
+      "incremental": true,
+      "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json"
+   },
+   "include": ["src", "scripts", "*.ts"]
+}

package/src/scaffold/files/verify-skill.md

@@ -0,0 +1,31 @@
+---
+name: verify
+description: Prove a change in THIS project actually works — drive the real flow end to end, never trust green checks or self-reports. Use before committing any nontrivial change.
+---
+
+# verify — how to PROVE a change works here
+
+<!-- Template: copy to .claude/skills/verify/SKILL.md at project start, fill the
+     placeholders, then GROW it — every gotcha discovered in this repo gets
+     encoded here the same day. -->
+
+## The rules (house-wide)
+- Failing repro test BEFORE the fix. Green checks ≠ verification.
+- Logic → fast headless `bun test` (tiny ~10-line test files reusing fixtures).
+- Look & feel → NEVER screenshot-self-verify; the repo owner playtests it.
+- Verify as the end user would: drive the real flow, observe the real signal.
+
+## This project
+- Dev server: `bun run dev` → http://localhost:<PORT> (check it's not already
+  running first: `curl -s localhost:<PORT> >/dev/null && echo up`)
+- Full gate: `bunx tsc --noEmit && bun test && bun run build`
+- Live URL after deploy: https://<project>.pages.dev (curl 200 + drive the flow)
+
+## Browser verification (only when a browser is truly needed)
+Playwright with explicit `executablePath`, `deviceScaleFactor: 2`, localStorage
+reset between runs, `page.evaluate` probes for state, collect `pageerror`
+("none" is evidence). Screenshots are for LOOKS, never for "does it fit".
+
+## Gotchas discovered in this repo
+<!-- append as found — this list is the reason this file exists -->
+- (none yet)

package/src/scaffold/files/vscode-settings.json

@@ -0,0 +1,40 @@
+// merge into .vscode/settings.json — the convention only sticks if the editor
+// produces it by default. Load-bearing keys for the absolute-import style.
+// NOTE: `js/ts.*` is the unified prefix (recent VSCode); on older builds
+// expand each to its `typescript.*` + `javascript.*` twins
+// (e.g. typescript.preferences.importModuleSpecifier, typescript.tsdk).
+{
+   // THE key pair: auto-import inserts 'src/...' absolute specifiers, never
+   // './relative'. Modern tsserver respects this reliably.
+   // the ONE key that makes auto-import write `src/foo/Bar.ts`, not
+   // `../foo/Bar`. It is the only real id in that family (`…Ending` aside);
+   // vscode ignores unknown keys in silence, so an invented name looks like
+   // it works
+   "js/ts.preferences.importModuleSpecifier": "non-relative",
+
+   // use the workspace typescript (native ts7 compiler), not vscode's bundled one
+   "js/ts.tsdk.path": "node_modules/typescript/lib",
+
+   // auto-imports emit `import type` — saves don't fight the lint's
+   // consistent-type-imports rule
+   "js/ts.preferences.preferTypeOnlyAutoImports": true,
+
+   // kill junk suggestions: only tsserver speaks, no word-soup completions
+   "editor.suggest.showWords": false,
+   "editor.wordBasedSuggestions": "off",
+   "js/ts.preferences.includePackageJsonAutoImports": "off",
+
+   // rename the real symbol, not an import alias; rename both jsx tags
+   "js/ts.preferences.useAliasesForRenames": false,
+   "js/ts.preferences.renameMatchingJsxTags": true,
+
+   // big-repo hygiene: more tsserver memory, no npm probing, no auto type acquisition
+   "js/ts.tsserver.maxMemory": 6144,
+   "js/ts.tsserver.automaticTypeAcquisition.enabled": false,
+   "js/ts.tsserver.checkNpmIsInstalled": false,
+
+   // oxc lints in-editor; eslint off; formatter owns formatting, not tsserver
+   "oxc.enable": true,
+   "eslint.enable": false,
+   "js/ts.format.enabled": false
+}

package/src/scaffold/files/vscode-tasks.json

@@ -0,0 +1,45 @@
+{
+   // one master task with runOn folderOpen, every dev process as a subtask.
+   // Opening the folder in vscode starts them all. Add a subtask per
+   // long-running watcher the stack earns (dev server, css, tests), never
+   // for a one-off script.
+   "version": "2.0.0",
+   "tasks": [
+      {
+         "label": "starts everything",
+         "dependsOn": ["👁  TSC", "🚀  shipkit"],
+         "group": { "kind": "build", "isDefault": true },
+         "runOptions": { "runOn": "folderOpen", "instanceLimit": 1 },
+         "problemMatcher": []
+      },
+      {
+         "label": "👁  TSC",
+         "detail": "Get all typescript errors in problems pane",
+         "type": "process",
+         "command": "${workspaceFolder}/node_modules/.bin/tsc",
+         "args": ["--noEmit", "--incremental", "--watch", "--project", "tsconfig.json"],
+         "options": {
+            "cwd": "${workspaceFolder}",
+            "env": { "NODE_OPTIONS": "--max-old-space-size=8192" }
+         },
+         "isBackground": true,
+         "presentation": { "reveal": "never", "clear": true },
+         "group": "build",
+         "runOptions": { "instanceLimit": 1 },
+         "problemMatcher": []
+      },
+      {
+         "label": "🚀  shipkit",
+         "detail": "The shipkit hub at http://localhost:{{PORT}} — clickable URLs: the page, /graph/wiki, /graph/agent",
+         "type": "process",
+         "command": "bun",
+         "args": ["run", "hub"],
+         "options": { "cwd": "${workspaceFolder}" },
+         "isBackground": true,
+         "presentation": { "reveal": "always", "close": false },
+         "group": "build",
+         "runOptions": { "instanceLimit": 1 },
+         "problemMatcher": []
+      }
+   ]
+}

package/src/scaffold/project-scaffold.ts

@@ -0,0 +1,126 @@
+// the day-one shape of a repo, written by `shipkit start` for a dir with no
+// commit history. The bar: opening the folder in vscode starts the watchers,
+// an agent lands on a wiki that routes it, and `shipkit ci` is green with no
+// warning a machine could have cleared.
+//
+// Every file is CREATE-ONLY: a path that exists is left exactly as it is, so
+// the scaffold can run over a half-built dir without ever destroying work.
+// Templates live beside this file in files/ and ship in the npm tarball, so
+// none of them may name a machine-local tool or a private path.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { defaultHubPort } from '../serve/run-serve.ts'
+
+const FILES = join(import.meta.dir, 'files')
+
+export type ScaffoldOpts = {
+    /** repo name, substituted into the templates */
+    name: string
+    /** report sink */
+    print?: (line: string) => void
+    /** the changelog's first dated entry — injected so callers stay testable */
+    today?: string
+}
+
+/** every dep the house toolchain needs for the scripts below to run */
+export const TOOLCHAIN = ['typescript', 'oxlint', 'oxfmt', '@types/bun'] as const
+
+/** script bodies for a fresh repo whose only source dir is src/. A stack
+ *  scaffold (vite, hono) adds dev/build on top; these three are the floor
+ *  rule SK001 asks every repo for */
+const SCRIPTS: Record<string, string> = {
+    lint: 'oxlint src/',
+    fmt: 'oxfmt src/',
+    typecheck: 'tsc --noEmit',
+}
+
+/** repo-owned ignore lines, written OUTSIDE rule SK004's managed block so its
+ *  fixer never rewrites them */
+const IGNORE_EXTRA = ['backups/', '.claude/settings.local.json']
+
+const template = (file: string, vars: Record<string, string>): string => {
+    let out = readFileSync(join(FILES, file), 'utf8')
+    for (const [k, v] of Object.entries(vars)) out = out.replaceAll(`{{${k}}}`, v)
+    return out
+}
+
+/** write only when the path is free. Returns whether it wrote */
+function put(root: string, rel: string, body: string): boolean {
+    const path = join(root, rel)
+    if (existsSync(path)) return false
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, body)
+    return true
+}
+
+export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
+    const p = opts.print ?? console.log
+    const vars = {
+        NAME: opts.name,
+        PORT: String(defaultHubPort(opts.name)),
+        DATE: opts.today ?? new Date().toISOString().slice(0, 10),
+    }
+    const written: string[] = []
+    const write = (rel: string, body: string): void => { if (put(root, rel, body)) written.push(rel) }
+
+    write('src/index.ts', 'export {}\n')
+    // the reference says to adjust include to the repo's own dirs, and a
+    // fresh repo has exactly one. Its root `*.ts` glob must NOT ship: that
+    // glob picks up repo.config.ts, whose `rvlib-shipkit` import is raw .ts,
+    // so tsc walks into the dependency and typechecks the whole library
+    // (skipLibCheck covers .d.ts only). Add a root file back by name, the
+    // way a vite repo lists vite.config.ts
+    write('tsconfig.json', template('tsconfig.json', vars).replace(/"include":.*$/m, '"include": ["src"]'))
+    write('.vscode/settings.json', template('vscode-settings.json', vars))
+    write('.vscode/tasks.json', template('vscode-tasks.json', vars))
+    // the harness must never write an assistant trailer into this repo's
+    // history, and the setting only counts from the FIRST commit on
+    write('.claude/settings.json', template('claude-settings.json', vars))
+    write('.claude/settings.local.json', template('claude-settings-local.json', vars))
+    write('.claude/skills/verify/SKILL.md', template('verify-skill.md', vars))
+    write('agent/index.md', template('agent-index.md', vars))
+    write('agent/coding.md', template('agent-coding.md', vars))
+    write('agent/changelog.md', template('agent-changelog.md', vars))
+    // gitignored by policy, so it never ships: it exists so an agent hitting
+    // friction with the toolchain finds the place to write it down
+    write('.rv-reflections/README.md', REFLECTIONS_README)
+
+    addScripts(root, written)
+    addIgnoreLines(root, written)
+
+    if (written.length > 0) p(`ok: scaffolded ${written.length} file(s): ${written.slice(0, 6).join(', ')}${written.length > 6 ? `, +${written.length - 6} more` : ''}`)
+    return written
+}
+
+const REFLECTIONS_README = `# .rv-reflections
+
+One file per friction with the shared toolchain: \`YYYYMMDD-<slug>.md\`.
+What broke, which page or lib, what you expected. Gitignored on purpose,
+transient by design: it is harvested, then deleted.
+`
+
+/** the three baseline scripts, added only where the key is free */
+function addScripts(root: string, written: string[]): void {
+    const path = join(root, 'package.json')
+    if (!existsSync(path)) return
+    const raw = readFileSync(path, 'utf8')
+    let pkg: { scripts?: Record<string, string> }
+    try { pkg = JSON.parse(raw) as { scripts?: Record<string, string> } } catch { return }
+    pkg.scripts ??= {}
+    let added = 0
+    for (const [k, v] of Object.entries(SCRIPTS)) if (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }
+    if (added === 0) return
+    const indent = raw.match(/^(\s+)"/m)?.[1] ?? '  '
+    writeFileSync(path, JSON.stringify(pkg, null, indent) + '\n')
+    written.push(`package.json (${added} script(s))`)
+}
+
+function addIgnoreLines(root: string, written: string[]): void {
+    const path = join(root, '.gitignore')
+    const cur = existsSync(path) ? readFileSync(path, 'utf8') : ''
+    const have = new Set(cur.split('\n').map((l) => l.trim()))
+    const missing = IGNORE_EXTRA.filter((l) => !have.has(l))
+    if (missing.length === 0) return
+    writeFileSync(path, `${cur}${cur === '' || cur.endsWith('\n') ? '' : '\n'}${missing.join('\n')}\n`)
+    written.push('.gitignore')
+}

package/src/start-repo.ts

@@ -4,11 +4,12 @@
 // 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, readdirSync, readFileSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { ensureGitRepo, firstGhLine, IGNORE_BASELINE, isScratch, publishRepo, runner, type Run } from './git-bootstrap.ts'
 import { initRepo } from './init-repo.ts'
+import { scaffoldProject, TOOLCHAIN } from './scaffold/project-scaffold.ts'
 
 export type StartOpts = {
     /** parent dir for repos — default ~/dev */
@@ -35,18 +36,7 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
         return 2
     }
     const dir = join(opts.root ?? join(homedir(), 'dev'), name)
-    // this run creating the dir is the strongest signal that a repo is being
-    // STARTED, which is what the scaffold and the github half key on:
-    // `ship <name>` is also the everyday cd into a folder that already
-    // exists. A pre-existing dir with NOTHING in it carries the same intent
-    // (there are no files to protect), and so does a git-only husk with no
-    // commits (what an interrupted start leaves behind). Captured here,
-    // BEFORE the include seeding writes CLAUDE.md into the dir
     const justCreated = !existsSync(dir)
-    const JUNK = new Set(['.DS_Store', '.localized'])
-    const entries = justCreated ? [] : readdirSync(dir).filter((e) => !JUNK.has(e))
-    const emptyDir = !justCreated && entries.length === 0
-    const gitOnlyDir = !justCreated && entries.length === 1 && entries[0] === '.git'
     if (justCreated) {
         mkdirSync(dir, { recursive: true })
         console.error(`ok: created ${dir}`)
@@ -78,14 +68,12 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
         }
     }
     // 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.
+    // 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,
+    // first commit, private github repo, push. A dir that already holds a
+    // project (package.json) gets the same minus the scaffold. Only a repo
+    // with real history is left as it is (git wiring aside): that history
+    // owns the dir. 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.
@@ -98,43 +86,47 @@ 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 for a dir this run created, a pre-existing dir
-        // that was EMPTY, or a commitless git-only husk (never --github
-        // alone: forcing the github half on a folder holding files 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
-        let startable = justCreated || emptyDir
-        if (!startable && gitOnlyDir && wired)
-            startable = (await runner('git', dir, 120_000)(['rev-parse', '--verify', 'HEAD'])).code !== 0
-        if (wired && startable && !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)
+        // start means START: the scaffold fires for ANY dir with no commit
+        // history (created this run, found empty, found holding loose files,
+        // or the husk an interrupted start left). Pre-existing files simply
+        // ride in the first commit, which backs them up. What it never
+        // touches: a repo with real history (that history owns the dir), a
+        // subdirectory of another work tree (git refused, wired is false),
+        // and the risky-file commit refusal downstream still guards .env and
+        // node_modules
+        const startable = wired && (await runner('git', dir, 120_000)(['rev-parse', '--verify', 'HEAD'])).code !== 0
+        if (startable && !existsSync(join(dir, 'repo.config.ts'))) {
+            if (!existsSync(join(dir, 'package.json'))) {
+                const pkg = { name, version: '0.0.0', private: true, type: 'module', scripts: {} }
+                writeFileSync(join(dir, 'package.json'), JSON.stringify(pkg, null, 4) + '\n')
+                console.error('ok: package.json created (private, type module)')
+            }
+            // the baseline ignore goes FIRST, before anything else can create
+            // a .gitignore: the install below writes node_modules/ and
+            // neither SK004's block nor the scaffold's own lines carry it, so
+            // a file that already exists silently skips the baseline and the
+            // first commit refuses on 7000 staged dep files
             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
+            // the day-one shape: tsconfig, vscode tasks, the agent wiki, the
+            // verify skill, the attribution silencer. Create-only, so a dir
+            // that already holds any of them keeps its own
+            scaffoldProject(dir, { name, print })
+            // the wired scripts call node_modules binaries, so 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)
+            else if ((process.env.SHIPKIT_NO_INSTALL ?? '') !== '') { console.error('skip: dependency install — SHIPKIT_NO_INSTALL is set'); bun = null }
+            else if (isScratch(dir)) { console.error(`skip: dependency install — ${dir} is a temp dir`); bun = null }
+            else bun = Bun.which('bun') == null ? null : runner('bun', dir, 300_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)}`)
+                const deps = ['rvlib-shipkit', ...TOOLCHAIN]
+                const r = await bun(['add', '-d', ...deps])
+                if (r.code === 0) console.error(`ok: installed ${deps.join(', ')}`)
+                else console.error(`WARN dependency install failed: ${firstGhLine(r.out)}`)
             }
         }
         let unscaffolded = false
@@ -151,6 +143,11 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
         // last line, so what to do next is the last thing read
         if (unscaffolded) console.error(`next: scaffold the app in ${dir} (package.json), then \`shipkit init\` inside it — the commit gates arm on the first ci run`)
     }
+    // a child process cannot cd its parent shell, so the dir goes to stdout
+    // and a sourced wrapper does the move. Without one, say the move out
+    // loud: a verb that lands you nowhere reads as a verb that did nothing.
+    // A wrapper sets SHIPKIT_CD to silence this
+    if ((process.env.SHIPKIT_CD ?? '') === '') console.error(`next: cd ${dir}   (a sourced shell function running \`cd "$(shipkit start <name>)"\` does this for you)`)
     console.log(dir)
     return 0
 }