@oaklandzoo/ostup 0.1.0

package/src/steps/ingest.mjs

@@ -0,0 +1,121 @@
+// steps/ingest.mjs: create the inputs/ folder skeleton and optionally copy operator-supplied materials.
+import { existsSync } from 'node:fs';
+import { mkdir, cp, writeFile, readdir, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { isDryRun } from '../exec.mjs';
+
+export const INGEST_SUBFOLDERS = ['research', 'references', 'images', 'notes'];
+
+export async function ingestMaterials({ targetDir, ingestPath, isDryRun: dryRunOverride } = {}) {
+  if (!targetDir) {
+    const err = new Error('ingestMaterials requires targetDir');
+    err.code = 'INGEST_BAD_ARGS';
+    throw err;
+  }
+
+  const inputsDir = join(targetDir, 'inputs');
+  const dryRun = dryRunOverride !== undefined ? dryRunOverride : isDryRun();
+
+  let srcResolved = null;
+  if (ingestPath) {
+    srcResolved = resolve(ingestPath);
+    if (!existsSync(srcResolved)) {
+      const err = new Error(`ingest source path does not exist: ${srcResolved}`);
+      err.code = 'INGEST_PATH_NOT_FOUND';
+      throw err;
+    }
+  }
+
+  if (dryRun) {
+    process.stdout.write(`[ingest] would create: ${inputsDir} + ${INGEST_SUBFOLDERS.map((s) => `${s}/`).join(', ')}\n`);
+    if (srcResolved) {
+      process.stdout.write(`[ingest] would copy: ${srcResolved} -> ${inputsDir}\n`);
+      process.stdout.write(`[ingest] would write: ${join(inputsDir, 'INGEST_MANIFEST.md')}\n`);
+    }
+    return {
+      inputsDir,
+      created: ['inputs/', ...INGEST_SUBFOLDERS.map((s) => `inputs/${s}/`)],
+      copied: 0,
+      manifest: null,
+      dryRun: true,
+    };
+  }
+
+  const created = ['inputs/'];
+  await mkdir(inputsDir, { recursive: true });
+  for (const sub of INGEST_SUBFOLDERS) {
+    await mkdir(join(inputsDir, sub), { recursive: true });
+    created.push(`inputs/${sub}/`);
+  }
+
+  if (!srcResolved) {
+    return { inputsDir, created, copied: 0, manifest: null };
+  }
+
+  await cp(srcResolved, inputsDir, { recursive: true, errorOnExist: false, force: true });
+
+  const summary = await summarize(srcResolved);
+  const manifestPath = join(inputsDir, 'INGEST_MANIFEST.md');
+  await writeFile(manifestPath, renderManifest({ src: srcResolved, ...summary }), 'utf8');
+
+  return { inputsDir, created, copied: summary.fileCount, manifest: manifestPath };
+}
+
+async function summarize(dir) {
+  let fileCount = 0;
+  let totalBytes = 0;
+  const topLevel = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    topLevel.push(entry.isDirectory() ? `${entry.name}/` : entry.name);
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const sub = await walk(full);
+      fileCount += sub.fileCount;
+      totalBytes += sub.totalBytes;
+    } else if (entry.isFile()) {
+      fileCount += 1;
+      const s = await stat(full);
+      totalBytes += s.size;
+    }
+  }
+  return { fileCount, totalBytes, topLevel };
+}
+
+async function walk(dir) {
+  let fileCount = 0;
+  let totalBytes = 0;
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const sub = await walk(full);
+      fileCount += sub.fileCount;
+      totalBytes += sub.totalBytes;
+    } else if (entry.isFile()) {
+      fileCount += 1;
+      const s = await stat(full);
+      totalBytes += s.size;
+    }
+  }
+  return { fileCount, totalBytes };
+}
+
+function renderManifest({ src, fileCount, totalBytes, topLevel }) {
+  const sizeKb = (totalBytes / 1024).toFixed(1);
+  const lines = [
+    '# Ingest manifest',
+    '',
+    `Source path: ${src}`,
+    `Files copied: ${fileCount}`,
+    `Total size: ${sizeKb} KB`,
+    '',
+    '## Top-level entries',
+    '',
+    ...topLevel.sort().map((name) => `- ${name}`),
+    '',
+    '> Generated by ostup at scaffold time. Safe to delete or regenerate.',
+    '',
+  ];
+  return lines.join('\n');
+}

package/src/steps/inject.mjs

@@ -0,0 +1,22 @@
+// steps/inject.mjs: re-substitute templates after deploy to inject REPO_URL and DEPLOY_URL into CLAUDE.md, AGENTS.md, README.md.
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { substitute } from '../substitute.mjs';
+
+const TARGETS = ['CLAUDE.md', 'AGENTS.md', 'README.md'];
+
+export async function injectUrls({ targetDir, tokens }) {
+  const touched = [];
+  for (const rel of TARGETS) {
+    const path = join(targetDir, rel);
+    if (!existsSync(path)) continue;
+    const raw = await readFile(path, 'utf8');
+    const out = substitute(raw, tokens);
+    if (out !== raw) {
+      await writeFile(path, out, 'utf8');
+      touched.push(rel);
+    }
+  }
+  return touched;
+}

package/src/steps/next-app.mjs

@@ -0,0 +1,41 @@
+// steps/next-app.mjs: run create-next-app or write a minimal static index.html into the target.
+import { writeFile, mkdir } from 'node:fs/promises';
+import { run } from '../exec.mjs';
+
+export async function maybeScaffoldStack({ stack, projectName, targetDir }) {
+  if (stack === 'next') {
+    await run('next-app', 'npx', [
+      'create-next-app@latest', '.',
+      '--typescript',
+      '--tailwind',
+      '--app',
+      '--src-dir',
+      '--import-alias', '@/*',
+      '--use-npm',
+      '--eslint',
+      '--yes',
+    ], { cwd: targetDir });
+    return { stack };
+  }
+  if (stack === 'static') {
+    await mkdir(targetDir, { recursive: true });
+    const html = [
+      '<!doctype html>',
+      '<html lang="en">',
+      '<head>',
+      '  <meta charset="utf-8" />',
+      '  <meta name="viewport" content="width=device-width, initial-scale=1" />',
+      `  <title>${projectName}</title>`,
+      '</head>',
+      '<body>',
+      `  <h1>${projectName}</h1>`,
+      '  <p>Scaffolded by ostup.</p>',
+      '</body>',
+      '</html>',
+      '',
+    ].join('\n');
+    await writeFile(`${targetDir}/index.html`, html, 'utf8');
+    return { stack };
+  }
+  return { stack };
+}

package/src/steps/protection.mjs

@@ -0,0 +1,181 @@
+// steps/protection.mjs: after vercel deploy, auto-disable ssoProtection + passwordProtection
+// on the linked project via the Vercel REST API so the deploy URL returns 200 publicly.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export const PROTECTION_BODY = Object.freeze({
+  ssoProtection: null,
+  passwordProtection: null,
+});
+
+export const AUTH_JSON_PATHS = {
+  darwin: () => join(homedir(), 'Library', 'Application Support', 'com.vercel.cli', 'auth.json'),
+  linux: () => join(homedir(), '.local', 'share', 'com.vercel.cli', 'auth.json'),
+  win32: () => process.env.APPDATA ? join(process.env.APPDATA, 'com.vercel.cli', 'auth.json') : '',
+};
+
+export async function resolveVercelToken({ env = process.env, platform = process.platform } = {}) {
+  if (env.VERCEL_TOKEN && env.VERCEL_TOKEN.length > 0) {
+    return { token: env.VERCEL_TOKEN, source: 'env' };
+  }
+  const fn = AUTH_JSON_PATHS[platform];
+  if (!fn) return { token: null, source: null };
+  const path = fn();
+  if (!path || !existsSync(path)) return { token: null, source: null };
+  try {
+    const raw = await readFile(path, 'utf8');
+    const json = JSON.parse(raw);
+    if (json && typeof json.token === 'string' && json.token.length > 0) {
+      return { token: json.token, source: 'auth.json', path };
+    }
+  } catch {
+    // fall through to null
+  }
+  return { token: null, source: null };
+}
+
+export async function readLinkedProject(targetDir) {
+  const path = join(targetDir, '.vercel', 'project.json');
+  if (!existsSync(path)) return null;
+  try {
+    const raw = await readFile(path, 'utf8');
+    const json = JSON.parse(raw);
+    return {
+      projectId: typeof json.projectId === 'string' ? json.projectId : null,
+      orgId: typeof json.orgId === 'string' ? json.orgId : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function isTeamOrgId(orgId) {
+  return typeof orgId === 'string' && orgId.startsWith('team_');
+}
+
+export function buildPatchUrl(projectId, orgId) {
+  const url = new URL(`https://api.vercel.com/v9/projects/${projectId}`);
+  if (isTeamOrgId(orgId)) url.searchParams.set('teamId', orgId);
+  return url.toString();
+}
+
+export async function patchProtection({ token, projectId, orgId, fetchImpl = fetch }) {
+  const url = buildPatchUrl(projectId, orgId);
+  const res = await fetchImpl(url, {
+    method: 'PATCH',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(PROTECTION_BODY),
+  });
+  return res;
+}
+
+export async function verifyDeployStatus(deployUrl, {
+  delayMs = 5000,
+  retryDelayMs = 10000,
+  fetchImpl = fetch,
+  sleep,
+} = {}) {
+  const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  await wait(delayMs);
+  let res = await fetchImpl(deployUrl, { method: 'HEAD', redirect: 'manual' });
+  if (res.status === 200) return { status: 200, attempts: 1 };
+  if (res.status === 401) {
+    await wait(retryDelayMs);
+    res = await fetchImpl(deployUrl, { method: 'HEAD', redirect: 'manual' });
+    return { status: res.status, attempts: 2 };
+  }
+  return { status: res.status, attempts: 1 };
+}
+
+function printManualWarn(projectName, stream = process.stdout) {
+  stream.write(
+    [
+      '[protection] WARN: could not auto-disable deployment protection.',
+      'Your deploy URL will return 401 until you disable it manually:',
+      '  1. Open https://vercel.com/dashboard',
+      `  2. Click the project: ${projectName}`,
+      '  3. Settings, Deployment Protection, Disable',
+      'Continuing without disabling.',
+      '',
+    ].join('\n')
+  );
+}
+
+function printVerifyWarn(projectName, status, stream = process.stdout) {
+  stream.write(
+    [
+      `[protection] WARN: deploy URL still returns ${status} after disable.`,
+      'Protection may not have cleared. Manual fix:',
+      '  1. Open https://vercel.com/dashboard',
+      `  2. Click the project: ${projectName}`,
+      '  3. Settings, Deployment Protection, Disable',
+      '',
+    ].join('\n')
+  );
+}
+
+export async function disableProtection({
+  projectName,
+  deployUrl,
+  targetDir,
+  env = process.env,
+  platform = process.platform,
+  fetchImpl = fetch,
+  sleep,
+  skipVerify = false,
+  stream = process.stdout,
+} = {}) {
+  const tokenInfo = await resolveVercelToken({ env, platform });
+  if (!tokenInfo.token) {
+    printManualWarn(projectName, stream);
+    return { disabled: false, reason: 'no-token' };
+  }
+
+  const linked = await readLinkedProject(targetDir);
+  if (!linked || !linked.projectId) {
+    printManualWarn(projectName, stream);
+    return { disabled: false, reason: 'no-project-id' };
+  }
+
+  const { projectId, orgId } = linked;
+
+  let patchRes;
+  try {
+    patchRes = await patchProtection({ token: tokenInfo.token, projectId, orgId, fetchImpl });
+  } catch (err) {
+    printManualWarn(projectName, stream);
+    return { disabled: false, reason: 'patch-network-error', error: err && err.message };
+  }
+  if (!patchRes || !patchRes.ok) {
+    printManualWarn(projectName, stream);
+    return { disabled: false, reason: 'patch-failed', status: patchRes && patchRes.status };
+  }
+
+  stream.write('[protection] PATCH ok\n');
+
+  if (skipVerify || !deployUrl) {
+    stream.write('[protection] disabled successfully\n');
+    return { disabled: true, verified: false, status: null, skippedVerify: true };
+  }
+
+  let verify;
+  try {
+    verify = await verifyDeployStatus(deployUrl, { fetchImpl, sleep });
+  } catch (err) {
+    printVerifyWarn(projectName, 'unreachable', stream);
+    return { disabled: true, verified: false, status: null, error: err && err.message };
+  }
+
+  if (verify.status === 200) {
+    stream.write('[protection] disabled successfully\n');
+    return { disabled: true, verified: true, status: 200 };
+  }
+
+  printVerifyWarn(projectName, verify.status, stream);
+  return { disabled: true, verified: false, status: verify.status };
+}

package/src/steps/vercel.mjs

@@ -0,0 +1,46 @@
+// steps/vercel.mjs: link the project to a Vercel scope and trigger a deploy; capture the URL.
+import { run } from '../exec.mjs';
+
+export function parseDeployUrl(stdout) {
+  const text = String(stdout || '');
+  const urls = [];
+  const re = /https?:\/\/[^\s"'`<>)\]]+/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    urls.push(m[0].replace(/[.,;:!?'"`)\]]+$/, ''));
+  }
+  if (urls.length === 0) return null;
+  const isProdLike = (u) => /\.vercel\.app(\/|$)/.test(u) && !u.includes('api.vercel.com') && !u.includes('/inspect');
+  const prod = urls.filter(isProdLike);
+  if (prod.length > 0) return prod[prod.length - 1];
+  return null;
+}
+
+async function getPersonalScope() {
+  try {
+    const r = await run('vercel-whoami', 'vercel', ['whoami'], {});
+    return (r.stdout || '').toString().trim();
+  } catch {
+    return '';
+  }
+}
+
+export async function linkAndDeploy({ projectName, vercelScope, cwd }) {
+  const personal = await getPersonalScope();
+  const linkArgs = ['link', '--yes', '--project', projectName];
+  if (vercelScope && vercelScope !== personal) {
+    linkArgs.push('--scope', vercelScope);
+  }
+  await run('vercel-link', 'vercel', linkArgs, { cwd });
+  const deploy = await run('vercel-deploy', 'vercel', ['--yes'], { cwd });
+  let url = parseDeployUrl(deploy.stdout);
+  if (!url) {
+    try {
+      const ls = await run('vercel-ls', 'vercel', ['ls', '--prod'], { cwd });
+      url = parseDeployUrl(ls.stdout);
+    } catch {
+      // ignore, fallback to no URL
+    }
+  }
+  return { url, raw: deploy.stdout };
+}

package/src/substitute.mjs

@@ -0,0 +1,44 @@
+// substitute.mjs: replace {{UPPERCASE_TOKENS}} in content with values; unknown keys fall back to TBD or stay deferred.
+const TOKEN_RE = /\{\{([A-Z_][A-Z_0-9]*)\}\}/g;
+
+export function substitute(content, values = {}, opts = {}) {
+  const defer = new Set(opts.defer || []);
+  return content.replace(TOKEN_RE, (match, key) => {
+    const v = values[key];
+    if (v == null || v === '') {
+      if (defer.has(key)) return match;
+      return 'TBD';
+    }
+    return String(v);
+  });
+}
+
+export function buildTokenMap({
+  projectName,
+  purpose,
+  owner,
+  stack,
+  deploy,
+  displayName,
+  description,
+  repoUrl,
+  deployUrl,
+} = {}) {
+  return {
+    PROJECT_NAME: projectName,
+    REPO_NAME: projectName,
+    DISPLAY_NAME: displayName || projectName,
+    PROJECT_PURPOSE_ONE_SENTENCE: description || purpose,
+    PURPOSE: description || purpose,
+    WHAT_WE_ARE_BUILDING_OR_FIXING: description || purpose,
+    WHAT_LIVES_HERE: description || purpose,
+    OWNER_OR_CLIENT: owner,
+    FRAMEWORK: stack,
+    LANGUAGE: stack,
+    LIVE_URL_OR_TBD: deployUrl || deploy,
+    DEPLOY_TARGET: deployUrl || deploy,
+    REPO_URL: repoUrl,
+    DEPLOY_URL: deployUrl,
+    INPUTS_PATH: 'inputs/',
+  };
+}

package/src/summary.mjs

@@ -0,0 +1,34 @@
+// summary.mjs: render the final "Project ready" block exactly per spec.
+export function renderProtectionLine(protection, deployUrl) {
+  if (!protection) return null;
+  if (protection.dryRun) return 'skipped (dry-run)';
+  if (protection.disabled && protection.verified) return 'disabled';
+  if (protection.disabled && protection.skippedVerify) return 'disabled (not verified)';
+  return `MANUAL FIX NEEDED: ${deployUrl || 'see Vercel dashboard'}`;
+}
+
+export function renderSummary({ targetDir, repoUrl, deployUrl, profile, projectName, stack, protection }) {
+  const deploy = deployUrl || (stack === 'none' ? 'skipped (stack=none)' : 'TBD');
+  const protectionLine = renderProtectionLine(protection, deployUrl);
+  const lines = [
+    '================================================',
+    '  Project ready',
+    '================================================',
+    `  Local path:  ${targetDir}`,
+    `  Repo:        ${repoUrl || 'TBD'}`,
+    `  Deploy:      ${deploy}`,
+  ];
+  if (protectionLine) lines.push(`  Protection:  ${protectionLine}`);
+  lines.push(
+    `  Profile:     ${profile || 'goodshin'}`,
+    '================================================',
+    `  Next: cd ${projectName} && claude`,
+    '================================================',
+    ''
+  );
+  return lines.join('\n');
+}
+
+export function printSummary(opts) {
+  process.stdout.write(renderSummary(opts));
+}

package/src/templates.mjs

@@ -0,0 +1,41 @@
+/**
+ * Template registry: every file copied into a scaffolded repo.
+ *
+ * Source paths are relative to the package root (`templates/...`).
+ * Destination paths are relative to the user's target directory.
+ *
+ * Placeholder vocabulary (any `{{TOKEN}}` not in buildTokenMap() becomes `TBD`):
+ *   PROJECT_NAME, REPO_NAME, PROJECT_PURPOSE_ONE_SENTENCE, PURPOSE,
+ *   WHAT_WE_ARE_BUILDING_OR_FIXING, WHAT_LIVES_HERE, OWNER_OR_CLIENT,
+ *   FRAMEWORK, LANGUAGE, LIVE_URL_OR_TBD, DEPLOY_TARGET
+ *
+ * The rest of the kit's tokens (BUILD_CMD, ENV_VAR_*, ACTIVE_TASK_*, etc.)
+ * are intentionally left as TBD here; /bootstrap inside Claude Code fills
+ * them by scanning the target repo.
+ */
+
+export const REGISTRY = [
+  { src: '.claude/commands/bootstrap.md',     dest: '.claude/commands/bootstrap.md' },
+  { src: '.claude/commands/prompt-start.md',  dest: '.claude/commands/prompt-start.md' },
+  { src: '.claude/commands/prompt-mid.md',    dest: '.claude/commands/prompt-mid.md' },
+  { src: '.claude/commands/prompt-end.md',    dest: '.claude/commands/prompt-end.md' },
+  { src: '.claude/commands/create-prd.md',    dest: '.claude/commands/create-prd.md' },
+  { src: '.claude/commands/generate-tasks.md', dest: '.claude/commands/generate-tasks.md' },
+  { src: 'CLAUDE.md',                          dest: 'CLAUDE.md' },
+  { src: 'AGENTS.md',                          dest: 'AGENTS.md' },
+  { src: 'HANDOFF.md',                         dest: 'HANDOFF.md' },
+  { src: 'docs/PROJECT_STATE.md',              dest: 'docs/PROJECT_STATE.md' },
+  { src: 'docs/MANUAL_TASKS.md',               dest: 'docs/MANUAL_TASKS.md' },
+  { src: 'docs/SESSION_NOTES.md',              dest: 'docs/SESSION_NOTES.md' },
+  { src: 'docs/ARCHITECTURE.md',               dest: 'docs/ARCHITECTURE.md' },
+  { src: 'tasks/.gitkeep',                     dest: 'tasks/.gitkeep' },
+  { src: 'inputs/README.md',                   dest: 'inputs/README.md' },
+];
+
+export const OPTIONAL_REGISTRY = [
+  { src: 'README.md',              dest: 'README.md',              onlyIfMissing: true },
+  // Stored as `_gitignore` in the package because npm strips top-level
+  // `.gitignore` from published tarballs. Renamed back on copy.
+  { src: '_gitignore',             dest: '.gitignore',             onlyIfMissing: true },
+  { src: '.ostup-config.yml.example', dest: '.ostup-config.yml.example', onlyIfMissing: true },
+];

package/src/update.mjs

@@ -0,0 +1,26 @@
+/**
+ * `ostup update`: refresh bundled templates from a pinned public GitHub release.
+ *
+ * The templates mirror repo is not wired up yet. Until TEMPLATES_SOURCE_URL
+ * below is set to a real release URL, `ostup update` fails fast with a clear
+ * message instead of making a network call.
+ */
+
+const TEMPLATES_SOURCE_URL = 'TODO_TEMPLATES_REPO_NOT_YET_CREATED';
+
+export async function update() {
+  if (TEMPLATES_SOURCE_URL.startsWith('TODO_')) {
+    const err = new Error(
+      '`ostup update` is not available yet in this release. To upgrade, reinstall the tool: npm install -g ostup@latest'
+    );
+    err.code = 'UPDATE_NOT_CONFIGURED';
+    throw err;
+  }
+
+  // Implementation deferred to v0.2:
+  //   1. fetch ${TEMPLATES_SOURCE_URL}/releases/latest tarball
+  //   2. extract into a sibling `templates.new/` dir
+  //   3. atomic swap: templates -> templates.bak, templates.new -> templates
+  //   4. clean up templates.bak on success
+  throw new Error('update() implementation pending');
+}

package/templates/.claude/commands/bootstrap.md

@@ -0,0 +1,111 @@
+---
+description: First-run on a new repo. Scan, ask up to 5 clarifiers if needed, fill all templates including HANDOFF.md.
+---
+
+# Bootstrap this project
+
+You are bootstrapping a new project. Job: populate the doc templates with real, project-specific content based on **evidence in this repo**. Do NOT invent facts. If you cannot determine something, ask a clarifier or write `TBD`.
+
+## Step 1: Scan the repo (no questions yet)
+
+Run these and absorb output:
+
+```bash
+ls -la
+find . -maxdepth 3 -type f \( -name "package.json" -o -name "pyproject.toml" -o -name "Cargo.toml" -o -name "go.mod" -o -name "Gemfile" -o -name "composer.json" -o -name "requirements.txt" -o -name "next.config.*" -o -name "supabase" -o -name "vercel.json" \) 2>/dev/null
+[ -f README.md ] && cat README.md | head -100
+[ -f package.json ] && cat package.json
+[ -f .env.example ] && cat .env.example
+[ -d .git ] && git remote -v && git log --oneline -5 2>/dev/null
+find . -maxdepth 2 -type d ! -path '*/node_modules*' ! -path '*/.git*' ! -path '*/.next*' ! -path '*/dist*' ! -path '*/build*'
+# Operator materials (if any) live in inputs/. Read the manifest and README first.
+[ -f inputs/INGEST_MANIFEST.md ] && cat inputs/INGEST_MANIFEST.md
+[ -f inputs/README.md ] && cat inputs/README.md
+[ -d inputs ] && ls -la inputs/
+```
+
+## Step 2: Determine what you know
+
+Classify each as KNOWN (from scan) or UNKNOWN:
+
+1. **Project name**: from package.json, README, or git remote
+2. **Project purpose**: what this codebase does (one sentence)
+3. **Tech stack**: language, framework, database, hosting, package manager
+4. **Live URL / deploy target**: production URL if any
+5. **Owner / client name**: who this is for
+
+## Step 3: Ask clarifiers (only if needed)
+
+If 1+ items are UNKNOWN, ask the operator up to **5 clarifiers** in a single numbered list with example answers:
+
+```
+Need a few facts before I fill the docs:
+
+1. Project name and one-sentence purpose? (e.g. "OwlNest: boutique ski lodge booking site")
+2. Owner or client? (e.g. "Sea Star SF" or "personal use")
+3. Stack confirmed? (e.g. "Next.js 14 + Supabase + Vercel" or "different: please specify")
+4. Live URL or deploy target? (e.g. "owlnest.jp" or "TBD, deploying to Vercel")
+5. Any project-specific conventions to bake in? (e.g. "uses pnpm not npm", "deploy via `npm run ship`", "API keys in 1Password")
+
+Reply with answers and I'll fill all docs.
+```
+
+Skip questions you already answered from scan. Never ask more than 5. If everything was KNOWN, skip Step 3.
+
+## Step 4: Fill the templates
+
+Edit each file. Replace every `{{PLACEHOLDER}}` with real content.
+
+Files to update:
+
+- **`CLAUDE.md`**: fill Parts 13, 14, 15, 16, 17 only. Do NOT modify Parts 1 through 12 (universal rules).
+- **`HANDOFF.md`**: first entry: status = "Bootstrapped. No work started yet." Next actions = "the operator to brief on first feature/fix to tackle."
+- **`docs/PROJECT_STATE.md`**: fill phase, priorities, key paths.
+- **`docs/MANUAL_TASKS.md`**: leave Active section empty for now.
+- **`docs/SESSION_NOTES.md`**: first entry: "Bootstrap session: repo scaffolded with Ostup Agent Kit."
+- **`docs/ARCHITECTURE.md`**: fill stack table, file map, env vars (names only), deploy details.
+
+**Rules for filling:**
+
+1. Pull facts from repo scan FIRST.
+2. Pull facts from the operator's clarifier answers SECOND.
+3. For anything still unknown, write `TBD` not a guess.
+4. Keep `CLAUDE.md` Parts 13 through 17 tight. Move detail to `docs/ARCHITECTURE.md`.
+
+## Step 5: Verify each file
+
+```bash
+for f in CLAUDE.md HANDOFF.md docs/PROJECT_STATE.md docs/MANUAL_TASKS.md docs/SESSION_NOTES.md docs/ARCHITECTURE.md; do
+  echo "=== $f ==="
+  wc -l "$f"
+  grep -c "{{" "$f" 2>/dev/null || echo "0 placeholders left"
+done
+```
+
+Any file with `{{` remaining means you missed a placeholder. Fix it. The only exception is the COMMENT block in `docs/SESSION_NOTES.md` template formatting: those are HTML comments, not placeholders.
+
+## Step 6: Report back
+
+```
+BOOTSTRAP COMPLETE
+
+Files filled:
+- CLAUDE.md             (X lines, 0 placeholders left)
+- HANDOFF.md            (X lines, 0 placeholders left)
+- docs/PROJECT_STATE.md (X lines, 0 placeholders left)
+- docs/MANUAL_TASKS.md  (X lines, 0 placeholders left)
+- docs/SESSION_NOTES.md (X lines, first entry written)
+- docs/ARCHITECTURE.md  (X lines, 0 placeholders left)
+
+Project: <name>
+Stack: <stack>
+Owner: <owner>
+Deploy: <url or target>
+
+TBDs that need operator attention:
+- <list any TBD fields, or "none">
+
+Next: run /prompt-start to begin a working session.
+```
+
+Stop. Do not start working on features yet.