@oaklandzoo/ostup 0.6.0 → 0.8.0

package/bin/cli.mjs

@@ -5,12 +5,13 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadDotEnv } from '../src/env-loader.mjs';
 import { setDryRun } from '../src/exec.mjs';
+import { startRun, endRun, disableTracer, traceError } from '../src/tracer.mjs';
 
 loadDotEnv();
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-const SUBCOMMANDS = new Set(['init', 'update', 'brief', 'export-pro']);
+const SUBCOMMANDS = new Set(['init', 'update', 'brief', 'export-pro', 'doctor']);
 
 async function readPkg() {
   const raw = await readFile(resolve(PKG_ROOT, 'package.json'), 'utf8');
@@ -44,6 +45,7 @@ function parseArgs(argv) {
     else if (a === '--output') flags.output = argv[++i];
     else if (a.startsWith('--output=')) flags.output = a.slice('--output='.length);
     else if (a === '--white-label') flags.whiteLabel = true;
+    else if (a === '--no-log') flags.noLog = true;
     else if (a.startsWith('-')) {
       process.stderr.write(`unknown flag: ${a}\n`);
       process.exit(1);
@@ -66,6 +68,7 @@ function printHelp() {
       '  init                Scaffold a new project (interactive or with --yes).',
       '  brief               Run the 10-question operator intake; write docs/brief.md + brief.json.',
       '  export-pro          Bundle brief + brand + content + initial PRD into a ZIP for client handoff.',
+      '  doctor              Self-diagnosis: preflight + auth + permissions + disk + Chrome. Read-only.',
       '  update              Refresh bundled templates from the pinned source.',
       '',
       'Flags for `ostup init`:',
@@ -93,6 +96,7 @@ function printHelp() {
       'Global flags:',
       '  --version, -v       Print version and exit.',
       '  --help, -h          Print this help and exit.',
+      '  --no-log            Disable auto-logging to ~/.ostup/logs/. (default: write a log per run)',
       '',
     ].join('\n')
   );
@@ -171,6 +175,18 @@ if (subcommand === 'export-pro') {
   }
 }
 
+if (subcommand === 'doctor') {
+  const { runDoctor, printDoctorReport } = await import('../src/doctor.mjs');
+  try {
+    const result = await runDoctor();
+    process.stdout.write(printDoctorReport(result));
+    process.exit(result.failCount > 0 ? 1 : 0);
+  } catch (err) {
+    process.stderr.write(`doctor failed: ${err.message}\n`);
+    process.exit(2);
+  }
+}
+
 // subcommand === 'init'
 if (flags.kitOnly) {
   const { scaffold } = await import('../src/scaffold.mjs');
@@ -185,12 +201,20 @@ if (flags.kitOnly) {
   }
 }
 
+if (flags.noLog) disableTracer();
+const logPath = await startRun({ label: 'init' });
+if (logPath) process.stdout.write(`Logging this run to ${logPath}\n`);
+
 const { runMvp } = await import('../src/mvp-flow.mjs');
 try {
   await runMvp({ flags });
+  await endRun({ ok: true });
   process.exit(0);
 } catch (err) {
+  await traceError('init', err);
+  await endRun({ ok: false });
   process.stderr.write(`${err.message}\n`);
+  if (logPath) process.stderr.write(`Full run log: ${logPath}\n`);
   const userErrors = new Set([
     'NO_TTY',
     'USER_ABORT',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Scaffolds a new repo with the Ostup Agent Kit pre-installed: slash commands, doc templates, and a clean working state.",
   "type": "module",
   "bin": {

package/src/doctor.mjs

@@ -0,0 +1,186 @@
+// doctor.mjs: self-diagnosis subcommand. Runs preflight + auth checks + permissions + reports.
+
+import { existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { preflight } from './preflight.mjs';
+import { checkGithubAuth, checkVercelAuth } from './credential-prompts.mjs';
+
+function runOk(cmd) {
+  try {
+    execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runCapture(cmd) {
+  try {
+    return execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+  } catch {
+    return null;
+  }
+}
+
+export async function runDoctor() {
+  const findings = [];
+  let okCount = 0;
+  let failCount = 0;
+  let warnCount = 0;
+
+  function report(level, label, detail) {
+    findings.push({ level, label, detail });
+    if (level === 'ok') okCount++;
+    else if (level === 'fail') failCount++;
+    else warnCount++;
+  }
+
+  // === Preflight ===
+  const pf = preflight();
+  if (pf.ok) {
+    report('ok', 'preflight', 'all required binaries present (node 20+, git, gh, vercel)');
+  } else {
+    report('fail', `preflight: ${pf.failed?.name || 'unknown'}`, pf.reason || pf.failed?.fix || '(no detail)');
+  }
+
+  // === Node version detail ===
+  const nodeVer = runCapture('node --version');
+  if (nodeVer) {
+    report('ok', 'node', nodeVer);
+  }
+
+  // === Git config ===
+  const gitName = runCapture('git config --global user.name');
+  const gitEmail = runCapture('git config --global user.email');
+  if (gitName && gitEmail) {
+    report('ok', 'git config', `${gitName} <${gitEmail}>`);
+  } else {
+    report('fail', 'git config', 'user.name or user.email not set; commits will fail. Run: git config --global user.name "Your Name" && git config --global user.email you@example.com');
+  }
+
+  // === GitHub auth ===
+  const gh = checkGithubAuth();
+  if (gh.ok) {
+    const ghUser = runCapture('gh api user --jq .login') || '(unknown)';
+    report('ok', 'gh auth', `authenticated as ${ghUser} (source: ${gh.source})`);
+    // Check scopes
+    const scopes = runCapture('gh auth status 2>&1 | grep -oE "Token scopes:.*"');
+    if (scopes) {
+      report('ok', 'gh scopes', scopes.replace('Token scopes:', '').trim());
+      if (!scopes.includes('delete_repo')) {
+        report('warn', 'gh delete_repo scope', 'missing; synthetic test cleanup will require manual deletion. Run: gh auth refresh -h github.com -s delete_repo');
+      }
+    }
+  } else {
+    report('fail', 'gh auth', 'not authenticated; run: gh auth login');
+  }
+
+  // === Vercel auth ===
+  const v = checkVercelAuth();
+  if (v.ok) {
+    const vUser = runCapture('vercel whoami');
+    report('ok', 'vercel auth', `authenticated as ${vUser || '(unknown)'} (source: ${v.source})`);
+
+    // Detect personal-account-as-scope risk
+    const teams = runCapture('vercel teams ls 2>&1 | grep -E "^✔|^\\*" | head -5');
+    if (teams) {
+      report('ok', 'vercel teams', teams.replace(/\n/g, '; '));
+    }
+  } else {
+    report('fail', 'vercel auth', 'not authenticated; run: vercel login');
+  }
+
+  // === Vercel AI Gateway key (optional but needed for /generate-image) ===
+  if (process.env.VERCEL_AI_GATEWAY_KEY) {
+    report('ok', 'VERCEL_AI_GATEWAY_KEY', 'present (image generation enabled)');
+  } else {
+    report('warn', 'VERCEL_AI_GATEWAY_KEY', 'not set; /generate-image will fail until set. Get key at https://vercel.com/dashboard/ai-gateway');
+  }
+
+  // === Chrome for screenshot verification ===
+  const chromeMac = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+  if (existsSync(chromeMac)) {
+    report('ok', 'chrome', 'present (visual verification supported per CLAUDE.md Part 19)');
+  } else if (runOk('which chromium 2>/dev/null') || runOk('which google-chrome 2>/dev/null')) {
+    report('ok', 'chrome', 'chromium or google-chrome on PATH');
+  } else {
+    report('warn', 'chrome', 'no Chrome detected; visual verification per CLAUDE.md Part 19 will not work. Install from https://www.google.com/chrome/');
+  }
+
+  // === Disk space in home dir ===
+  const dfHome = runCapture(`df -k ${homedir()} | tail -1 | awk '{print $4}'`);
+  if (dfHome) {
+    const kbFree = parseInt(dfHome, 10);
+    if (Number.isFinite(kbFree) && kbFree < 1024 * 1024) {
+      // less than 1 GB free
+      report('warn', 'disk space', `${(kbFree / 1024).toFixed(0)} MB free in ${homedir()}; scaffolds may fail (npm install needs ~500 MB)`);
+    } else {
+      report('ok', 'disk space', `${(kbFree / 1024 / 1024).toFixed(1)} GB free in ${homedir()}`);
+    }
+  }
+
+  // === Memory dir creatable ===
+  const memTest = join(homedir(), '.claude', 'projects', '__ostup_doctor_test__', 'memory');
+  try {
+    const { mkdir, rm } = await import('node:fs/promises');
+    await mkdir(memTest, { recursive: true });
+    await rm(memTest, { recursive: true, force: true });
+    report('ok', 'memory dir', 'can create ~/.claude/projects/<project>/memory at scaffold time');
+  } catch (err) {
+    report('fail', 'memory dir', `cannot create ~/.claude/projects/__ostup_doctor_test__/memory: ${err.message}`);
+  }
+
+  // === Log dir creatable ===
+  try {
+    const { mkdir } = await import('node:fs/promises');
+    await mkdir(join(homedir(), '.ostup', 'logs'), { recursive: true });
+    report('ok', 'log dir', `~/.ostup/logs/ writable (run logs land here)`);
+  } catch (err) {
+    report('fail', 'log dir', `cannot create ~/.ostup/logs/: ${err.message}`);
+  }
+
+  // === npm version (we don't call `npm bin` anymore, but warn on very old npm) ===
+  const npmVer = runCapture('npm --version');
+  if (npmVer) {
+    const major = parseInt(npmVer.split('.')[0], 10);
+    if (major < 9) {
+      report('warn', 'npm version', `${npmVer} is old; recommend npm 9+. Run: npm install -g npm@latest`);
+    } else {
+      report('ok', 'npm', npmVer);
+    }
+  }
+
+  // === ostup tarball install location (sanity) ===
+  const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  report('ok', 'ostup install', pkgRoot);
+
+  return { findings, okCount, warnCount, failCount };
+}
+
+export function printDoctorReport({ findings, okCount, warnCount, failCount }) {
+  const lines = [];
+  lines.push('');
+  lines.push('=====================================');
+  lines.push('  ostup doctor: self-diagnosis');
+  lines.push('=====================================');
+  lines.push('');
+  for (const f of findings) {
+    const sym = f.level === 'ok' ? '  OK  ' : f.level === 'warn' ? ' WARN ' : ' FAIL ';
+    lines.push(`[${sym}] ${f.label.padEnd(28)} ${f.detail || ''}`);
+  }
+  lines.push('');
+  lines.push(`Summary: ${okCount} OK, ${warnCount} WARN, ${failCount} FAIL`);
+  lines.push('');
+  if (failCount > 0) {
+    lines.push('Fix the FAILs before running `ostup init`. WARNs are optional.');
+  } else if (warnCount > 0) {
+    lines.push('No blockers. WARNs are optional improvements.');
+  } else {
+    lines.push('Everything clean. Ready to scaffold.');
+  }
+  lines.push('');
+  return lines.join('\n');
+}

package/src/exec.mjs

@@ -1,5 +1,6 @@
 // exec.mjs: uniform shell call wrapper with logging, dry-run capture, and step-aware error formatting.
 import { execa } from 'execa';
+import { traceStep, getLogPath } from './tracer.mjs';
 
 const HINTS = {
   'gh repo create': 'Confirm the repo name is not already taken under this owner.',
@@ -56,19 +57,55 @@ export async function run(step, cmd, args = [], opts = {}) {
     return { stdout: '', stderr: '', exitCode: 0, dryRun: true };
   }
   if (!_quiet) process.stdout.write(`[${step}] start: ${display}\n`);
+  const start = Date.now();
   try {
-    return await _runner(cmd, args, { ...opts });
+    const result = await _runner(cmd, args, { ...opts });
+    const duration = Date.now() - start;
+    await traceStep({
+      step, cmd, args,
+      stdout: result?.stdout || '',
+      stderr: result?.stderr || '',
+      exitCode: result?.exitCode || 0,
+      durationMs: duration,
+    });
+    return result;
   } catch (err) {
-    const stderr = (err && (err.stderr || err.shortMessage || err.message) || '').toString().trim();
-    process.stderr.write(
-      [
-        `[${step}] FAIL`,
-        `  Command: ${display}`,
-        `  Stderr:  ${stderr || '(empty)'}`,
-        `  Fix:     ${hintFor(cmd, args)}`,
-        'Exit 1.',
-      ].join('\n') + '\n'
-    );
+    const duration = Date.now() - start;
+    const stdout = (err && err.stdout || '').toString();
+    const stderr = (err && err.stderr || '').toString();
+    const message = (err && (err.shortMessage || err.message) || '').toString().trim();
+
+    // Capture both stdout AND stderr (was stderr-only). Some tools (vercel, gh) output errors to stdout.
+    const stdoutTail = stdout.split('\n').slice(-15).join('\n').trim();
+    const stderrTail = stderr.split('\n').slice(-15).join('\n').trim();
+    const logPath = getLogPath();
+
+    const lines = [`[${step}] FAIL`, `  Command: ${display}`];
+    if (stderrTail) {
+      lines.push(`  Stderr (last 15 lines):`);
+      for (const l of stderrTail.split('\n')) lines.push(`    ${l}`);
+    }
+    if (stdoutTail) {
+      lines.push(`  Stdout (last 15 lines):`);
+      for (const l of stdoutTail.split('\n')) lines.push(`    ${l}`);
+    }
+    if (!stderrTail && !stdoutTail && message) {
+      lines.push(`  Error: ${message}`);
+    }
+    lines.push(`  Fix:     ${hintFor(cmd, args)}`);
+    if (logPath) {
+      lines.push(`  Log:     ${logPath}`);
+    }
+    lines.push('Exit 1.');
+    process.stderr.write(lines.join('\n') + '\n');
+
+    await traceStep({
+      step, cmd, args,
+      stdout, stderr,
+      exitCode: err?.exitCode || 1,
+      durationMs: duration,
+    });
+
     const e = new Error(`step ${step} failed`);
     e.code = 'STEP_FAILED';
     e.step = step;

package/src/mvp-flow.mjs

@@ -19,6 +19,7 @@ import { REGISTRY, OPTIONAL_REGISTRY } from './templates.mjs';
 import { run as exec, isDryRun } from './exec.mjs';
 import { loadBrief, writeBriefFiles } from './brief/index.mjs';
 import { applyProfileOverlay } from './brief/profile-router.mjs';
+import { applyWhiteLabel } from './white-label.mjs';
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const TEMPLATES_ROOT = resolve(PKG_ROOT, 'templates');
@@ -121,6 +122,13 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
   await writeProjectEnvFiles({ targetDir, collected: creds.collected });
   await ensureGitignoreEnv({ targetDir });
 
+  if (flags.whiteLabel) {
+    const wl = await applyWhiteLabel({ targetDir });
+    if (wl.touched.length > 0) {
+      process.stdout.write(`[white-label] scrubbed OSTUP/Goodshin attribution in ${wl.touched.length} file(s)\n`);
+    }
+  }
+
   await exec('git-init',  'git', ['init'], { cwd: targetDir });
   await exec('git-branch','git', ['branch', '-M', 'main'], { cwd: targetDir });
   await exec('git-add',   'git', ['add', '.'], { cwd: targetDir });

package/src/scaffold.mjs

@@ -51,6 +51,14 @@ export async function scaffold({ targetDir, flags, stdinIsTTY = process.stdin.is
     await writeOne({ entry, absTarget, tokens });
   }
 
+  if (flags.whiteLabel) {
+    const { applyWhiteLabel } = await import('./white-label.mjs');
+    const wl = await applyWhiteLabel({ targetDir: absTarget });
+    if (wl.touched.length > 0) {
+      process.stdout.write(`[white-label] scrubbed OSTUP/Goodshin attribution in ${wl.touched.length} file(s)\n`);
+    }
+  }
+
   initGitIfNeeded(absTarget);
   printNextSteps(absTarget);
 }

package/src/templates.mjs

@@ -33,6 +33,7 @@ export const REGISTRY = [
   { src: '.claude/commands/break-into-stories.md', dest: '.claude/commands/break-into-stories.md' },
   { src: '.claude/commands/generate-brand-kit.md', dest: '.claude/commands/generate-brand-kit.md' },
   { src: '.claude/commands/generate-content-pack.md', dest: '.claude/commands/generate-content-pack.md' },
+  { src: '.claude/commands/handoff-package.md', dest: '.claude/commands/handoff-package.md' },
   { src: 'CLAUDE.md',                          dest: 'CLAUDE.md' },
   { src: 'AGENTS.md',                          dest: 'AGENTS.md' },
   { src: 'START_HERE.md',                      dest: 'START_HERE.md' },

package/src/tracer.mjs

@@ -0,0 +1,116 @@
+// tracer.mjs: structured per-run log file. Writes every step + output to ~/.ostup/logs/<run-id>.log.
+// Auto-enabled on every ostup init / brief / export-pro run unless --no-log is passed.
+
+import { existsSync } from 'node:fs';
+import { mkdir, appendFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+let _enabled = true;
+let _logPath = null;
+let _runId = null;
+
+export function disableTracer() {
+  _enabled = false;
+}
+
+export function enableTracer() {
+  _enabled = true;
+}
+
+export function isTracerEnabled() {
+  return _enabled;
+}
+
+export async function startRun({ label = 'run' } = {}) {
+  if (!_enabled) return null;
+  _runId = `${label}-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}`;
+  const dir = join(homedir(), '.ostup', 'logs');
+  await mkdir(dir, { recursive: true });
+  _logPath = join(dir, `${_runId}.log`);
+  await appendFile(_logPath, `# ostup run ${_runId}\n# started: ${new Date().toISOString()}\n# cwd: ${process.cwd()}\n# argv: ${process.argv.slice(2).join(' ')}\n\n`);
+  return _logPath;
+}
+
+export async function trace(category, message) {
+  if (!_enabled || !_logPath) return;
+  const stamp = new Date().toISOString();
+  const line = `[${stamp}] [${category}] ${message}\n`;
+  try {
+    await appendFile(_logPath, line);
+  } catch {
+    // Logging must never crash the main flow.
+  }
+}
+
+export async function traceStep({ step, cmd, args = [], stdout = '', stderr = '', exitCode = 0, durationMs = 0 }) {
+  if (!_enabled || !_logPath) return;
+  const display = `${cmd} ${(args || []).join(' ')}`.trim();
+  const stdoutTail = (stdout || '').toString().split('\n').slice(-30).join('\n');
+  const stderrTail = (stderr || '').toString().split('\n').slice(-30).join('\n');
+  const lines = [
+    `## step ${step} | exit=${exitCode} | ${durationMs}ms`,
+    `  cmd: ${display}`,
+  ];
+  if (stdoutTail.trim()) {
+    lines.push(`  stdout (last 30 lines):`);
+    for (const l of stdoutTail.split('\n')) lines.push(`    ${l}`);
+  }
+  if (stderrTail.trim()) {
+    lines.push(`  stderr (last 30 lines):`);
+    for (const l of stderrTail.split('\n')) lines.push(`    ${l}`);
+  }
+  lines.push('');
+  try {
+    await appendFile(_logPath, lines.join('\n'));
+  } catch {
+    // ignore
+  }
+}
+
+export async function traceError(category, err) {
+  if (!_enabled || !_logPath) return;
+  const stamp = new Date().toISOString();
+  const lines = [
+    `## ERROR [${stamp}] [${category}]`,
+    `  message: ${err?.message || err}`,
+    `  code:    ${err?.code || '(none)'}`,
+  ];
+  if (err?.cause) {
+    lines.push(`  cause:`);
+    const causeStr = (err.cause.message || String(err.cause)).split('\n');
+    for (const l of causeStr.slice(0, 20)) lines.push(`    ${l}`);
+  }
+  if (err?.stack) {
+    lines.push(`  stack (first 10 lines):`);
+    for (const l of err.stack.split('\n').slice(0, 10)) lines.push(`    ${l}`);
+  }
+  lines.push('');
+  try {
+    await appendFile(_logPath, lines.join('\n'));
+  } catch {
+    // ignore
+  }
+}
+
+export async function endRun({ ok = true } = {}) {
+  if (!_enabled || !_logPath) return null;
+  const stamp = new Date().toISOString();
+  try {
+    await appendFile(_logPath, `\n# ended: ${stamp}\n# status: ${ok ? 'ok' : 'failed'}\n`);
+  } catch {
+    // ignore
+  }
+  const path = _logPath;
+  _logPath = null;
+  _runId = null;
+  return path;
+}
+
+export function getLogPath() {
+  return _logPath;
+}
+
+export function getRunId() {
+  return _runId;
+}

package/src/white-label.mjs

@@ -0,0 +1,54 @@
+// white-label.mjs: post-process specific generated files to strip OSTUP / Goodshin attribution.
+// Used when `ostup init --white-label` is passed (Studio tier).
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const TARGETS = [
+  'AGENTS.md',
+  'README.md',
+  'START_HERE.md',
+  '.claude/commands/bootstrap.md',
+  '.claude/commands/prompt-start.md',
+  '.claude/commands/prompt-end.md',
+  '.claude/commands/preflight.md',
+];
+
+const REPLACEMENTS = [
+  { from: /Ostup Agent Kit/g, to: 'Project Kit' },
+  { from: /the Ostup Agent Kit/g, to: 'the Project Kit' },
+  { from: /scaffolded with ostup/gi, to: 'scaffolded' },
+  { from: /Built by Goodshin\.?/gi, to: '' },
+  { from: /Generated by `ostup brief`/g, to: 'Generated' },
+  { from: /Generated by `ostup [a-z-]+`/g, to: 'Generated' },
+  { from: /\bostup CLI subcommands.*\n/g, to: '' },
+  { from: /^\s*-\s*`ostup [a-z-]+`.*$/gm, to: '' },
+  { from: /\bnpx @oaklandzoo\/ostup [a-z-]+/g, to: 'project tooling' },
+  { from: /\(Vercel \+ GitHub \+ Goodshin\)/g, to: '(Vercel + GitHub)' },
+];
+
+export async function applyWhiteLabel({ targetDir } = {}) {
+  const touched = [];
+  for (const rel of TARGETS) {
+    const path = join(targetDir, rel);
+    if (!existsSync(path)) continue;
+    let body = await readFile(path, 'utf8');
+    let changed = false;
+    for (const rule of REPLACEMENTS) {
+      if (rule.to === undefined) continue;
+      const next = body.replace(rule.from, rule.to);
+      if (next !== body) {
+        body = next;
+        changed = true;
+      }
+    }
+    if (changed) {
+      // Collapse stray double blank lines that replacements may have left.
+      body = body.replace(/\n{3,}/g, '\n\n');
+      await writeFile(path, body, 'utf8');
+      touched.push(rel);
+    }
+  }
+  return { touched };
+}

package/templates/.claude/commands/handoff-package.md

@@ -0,0 +1,123 @@
+---
+description: Bundle the current project state into a single client-ready handoff document. Useful for agencies handing off a project to a client or a new developer. Writes docs/HANDOFF_PACKAGE.md and optionally calls `ostup export-pro` for the ZIP.
+---
+
+# /handoff-package
+
+The Studio-tier (or any operator's) equivalent of a one-page handoff summary. Distills the current state into a single Markdown doc that someone new to the project can read in 10 minutes and understand:
+
+- What this project is
+- What is shipped
+- What is in flight
+- How to run it locally
+- How to deploy
+- Who to ask about what
+
+## Step 1: read context
+
+```bash
+[ -f docs/brief.md ] && head -80 docs/brief.md
+[ -f HANDOFF.md ] && cat HANDOFF.md
+[ -f docs/PROJECT_STATE.md ] && cat docs/PROJECT_STATE.md
+[ -f docs/MANUAL_TASKS.md ] && cat docs/MANUAL_TASKS.md
+[ -f docs/ARCHITECTURE.md ] && cat docs/ARCHITECTURE.md
+[ -f README.md ] && head -40 README.md
+ls tasks/ 2>/dev/null
+git log --oneline -10
+```
+
+## Step 2: write `docs/HANDOFF_PACKAGE.md`
+
+```markdown
+# Handoff: <project name>
+
+> One-page client-ready overview. Generated <YYYY-MM-DD>.
+> If something here is wrong, the source of truth is `docs/brief.md` and the git log.
+
+## 1. What this project is
+
+<one paragraph from brief.summary + audience>
+
+## 2. Where it lives
+
+- **Repo:** <git remote URL>
+- **Live URL:** <from HANDOFF or brief>
+- **Latest commit:** <SHA + subject>
+
+## 3. What is shipped
+
+<from PROJECT_STATE "Recently done" + git log of last 10 commits>
+
+## 4. What is in flight
+
+<from HANDOFF "Active context" / "What to do next">
+
+## 5. How to run it locally
+
+```bash
+git clone <repo URL>
+cd <project>
+npm install
+cp .env.example .env.local   # fill in the values
+npm run dev
+```
+
+## 6. Environment variables required
+
+| Var | Purpose | Where to get it |
+|---|---|---|
+<list each from .env.example with brief purpose>
+
+## 7. How to deploy
+
+<from ARCHITECTURE.md or PROJECT_STATE — Vercel default; document any custom CI/CD>
+
+## 8. Profile and add-ons
+
+<from brief.scaffold.profile + brief.scaffold.addons; explain each add-on briefly>
+
+## 9. Blockers + things the operator must do manually
+
+<from MANUAL_TASKS.md "Active" section>
+
+## 10. Who to ask
+
+- **Project owner:** <from brief.project.owner_or_client>
+- **Last agent / dev:** <from HANDOFF if recorded>
+
+## 11. Recommended next steps for whoever picks this up
+
+1. Run `/preflight` to confirm Vercel + GitHub + env state.
+2. Run `/prompt-start` (or `/resume` if HANDOFF feels stale).
+3. Read `docs/brief.md` end to end.
+4. Pick the first item from "What is in flight" and confirm before changing anything.
+```
+
+## Step 3: optionally bundle into a ZIP
+
+Ask the operator: "Bundle into a ZIP via `ostup export-pro`?"
+
+If yes:
+
+```bash
+ostup export-pro --output handoff-<project>-$(date +%Y%m%d).zip
+```
+
+The ZIP includes `docs/HANDOFF_PACKAGE.md` plus the standard pro-export contents (brief, brand, content, initial PRD, agent kit).
+
+## Step 4: report
+
+```
+Handoff package: docs/HANDOFF_PACKAGE.md
+
+Optional bundle: handoff-<project>-<YYYY-MM-DD>.zip (run ostup export-pro to create)
+
+The recipient can read the package in ~10 minutes and pick up the work.
+```
+
+## Hard rules
+
+- Pull every fact from existing files (brief, HANDOFF, PROJECT_STATE, ARCHITECTURE, MANUAL_TASKS, git log). Do not invent.
+- If a section has no source, write `_TBD — operator to fill_` rather than guess.
+- This is a SNAPSHOT. Regenerate when you re-hand-off.
+- Operator can edit the file directly to refine; do not auto-regenerate on every session.

package/templates/AGENTS.md

@@ -29,7 +29,7 @@ Operator materials live in `{{INPUTS_PATH}}`. Read `{{INPUTS_PATH}}README.md` fo
 
 Session lifecycle: `/bootstrap`, `/prompt-start`, `/prompt-mid`, `/prompt-end`, `/preflight`, `/resume`, `/handoff-doctor`
 
-Building: `/create-prd`, `/break-into-stories`, `/generate-tasks`, `/update-image`, `/update-gui`, `/update-backend`, `/add-storage`, `/generate-image-prompt`, `/generate-image`
+Building: `/create-prd`, `/break-into-stories`, `/generate-tasks`, `/update-image`, `/update-gui`, `/update-backend`, `/add-storage`, `/generate-image-prompt`, `/generate-image`, `/generate-brand-kit`, `/generate-content-pack`, `/handoff-package`
 
 See each file under `.claude/commands/` for the full routine.
 
@@ -38,6 +38,8 @@ See each file under `.claude/commands/` for the full routine.
 - `ostup brief` — 10-question operator intake; writes `docs/brief.md`, `docs/brief.json`, `tasks/prd-initial-build.md`.
 - `ostup init --brief <path>` — scaffold using an existing brief.json; applies the matching profile overlay.
 - `ostup init` — interactive scaffold without brief.
+- `ostup init --white-label` — Studio tier; strips OSTUP/Goodshin attribution from generated docs.
+- `ostup export-pro` — bundle docs/brief + assets/brand + assets/content + initial PRD into a ZIP for client handoff.
 
 ## Helpers