@oaklandzoo/ostup 0.11.0 → 0.13.0

package/src/credential-prompts-npm.mjs

@@ -0,0 +1,154 @@
+// credential-prompts-npm.mjs: detect npm credentials, walk operator through token-paste or browser flow.
+
+import * as p from '@clack/prompts';
+import { execSync } from 'node:child_process';
+import { readFileSync, existsSync, appendFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { run as exec } from './exec.mjs';
+
+const NPMRC_PATH = join(homedir(), '.npmrc');
+
+export function checkNpmAuth({ env = process.env, runner = defaultCmdOk, npmrcReader = defaultNpmrcReader } = {}) {
+  if (env.NPM_TOKEN) return { ok: true, source: 'env' };
+  const npmrc = npmrcReader();
+  if (npmrc && /_authToken=/.test(npmrc)) return { ok: true, source: 'npmrc' };
+  if (runner('npm whoami')) return { ok: true, source: 'npm-cli' };
+  return { ok: false };
+}
+
+function defaultCmdOk(cmd) {
+  try {
+    execSync(cmd, { stdio: ['ignore', 'ignore', 'ignore'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultNpmrcReader() {
+  try {
+    return existsSync(NPMRC_PATH) ? readFileSync(NPMRC_PATH, 'utf8') : '';
+  } catch {
+    return '';
+  }
+}
+
+const NPM_BLURB = [
+  '',
+  'npm credentials not found.',
+  '',
+  'Why this matters: if you ever want to publish a package from this machine,',
+  'you need a token. Skip this step if you are only building apps (most users).',
+  '',
+  'If you do not have an npm account yet:',
+  '  1. Open https://www.npmjs.com/signup',
+  '  2. Create an account, then return here.',
+  '',
+  'To create a granular Bypass-2FA token (recommended; survives 2FA-required publishes):',
+  '  1. Open https://www.npmjs.com/settings/<your-username>/tokens/new',
+  '  2. Token type: Granular access token',
+  '  3. Expiration: 90 days (or longer)',
+  '  4. Packages and scopes: select what you plan to publish',
+  '  5. Permissions: Read and Write',
+  '  6. 2FA: select "Bypass 2FA"',
+  '  7. Generate token, copy the value (starts with npm_)',
+  '',
+].join('\n');
+
+export async function promptForNpmToken() {
+  process.stdout.write(NPM_BLURB);
+  const token = await p.password({
+    message: 'Paste your npm token (starts with npm_; leave blank to skip)',
+  });
+  if (p.isCancel(token)) return null;
+  const trimmed = typeof token === 'string' ? token.trim() : '';
+  if (!trimmed) return null;
+  return trimmed;
+}
+
+function binaryOnPath(bin) {
+  try {
+    execSync(`${bin} --version`, { stdio: ['ignore', 'ignore', 'ignore'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function chooseNpmAuthMethod() {
+  const choice = await p.select({
+    message: 'npm: how would you like to set up publishing?',
+    options: [
+      { value: 'browser', label: 'Sign in via npm login --auth-type=web (recommended)' },
+      { value: 'token', label: 'Paste a Bypass-2FA token instead' },
+      { value: 'skip', label: 'Skip for now (no publishing from this machine)' },
+    ],
+    initialValue: 'browser',
+  });
+  if (p.isCancel(choice)) return 'skip';
+  return choice;
+}
+
+async function attemptBrowserAuth() {
+  try {
+    await exec('npm-login', 'npm', ['login', '--auth-type=web'], { stdio: 'inherit' });
+    return true;
+  } catch {
+    process.stdout.write('npm browser sign-in did not complete. Falling back to token paste.\n');
+    return false;
+  }
+}
+
+function writeNpmrcToken(token, npmrcPath = NPMRC_PATH) {
+  const line = `//registry.npmjs.org/:_authToken=${token}\n`;
+  if (existsSync(npmrcPath)) {
+    const existing = readFileSync(npmrcPath, 'utf8');
+    if (existing.includes('//registry.npmjs.org/:_authToken=')) {
+      const replaced = existing.replace(/^\/\/registry\.npmjs\.org\/:_authToken=.*$/m, line.trim());
+      writeFileSync(npmrcPath, replaced, 'utf8');
+    } else {
+      appendFileSync(npmrcPath, (existing.endsWith('\n') ? '' : '\n') + line, 'utf8');
+    }
+  } else {
+    writeFileSync(npmrcPath, line, 'utf8');
+  }
+}
+
+export async function ensureNpmCredentials({ flags = {} } = {}) {
+  const result = checkNpmAuth();
+  if (result.ok) {
+    process.stdout.write(`npm: using existing auth (${result.source}).\n`);
+    return { ok: true, source: result.source };
+  }
+
+  if (!binaryOnPath('npm')) {
+    process.stdout.write('npm CLI not on PATH; skipping npm setup.\n');
+    return { ok: false, source: 'missing-npm' };
+  }
+
+  const method = flags.yes ? 'skip' : await chooseNpmAuthMethod();
+  if (method === 'skip') {
+    process.stdout.write('npm: setup skipped. Run `npm login` later if you need to publish.\n');
+    return { ok: false, source: 'skipped' };
+  }
+
+  if (method === 'browser') {
+    const ok = await attemptBrowserAuth();
+    if (ok && checkNpmAuth().ok) {
+      process.stdout.write('npm: signed in via browser.\n');
+      return { ok: true, source: 'browser' };
+    }
+  }
+
+  const token = await promptForNpmToken();
+  if (!token) {
+    process.stdout.write('npm: no token provided. Skipping.\n');
+    return { ok: false, source: 'skipped' };
+  }
+  writeNpmrcToken(token);
+  process.stdout.write(`npm: token saved to ${NPMRC_PATH}.\n`);
+  return { ok: true, source: 'npmrc-write' };
+}
+
+export { writeNpmrcToken, NPMRC_PATH };

package/src/credential-prompts.mjs

@@ -2,6 +2,7 @@
 import * as p from '@clack/prompts';
 import { execSync } from 'node:child_process';
 import { run as exec } from './exec.mjs';
+import { ensureNpmCredentials } from './credential-prompts-npm.mjs';
 
 export function checkGithubAuth({ env = process.env, runner = defaultCmdOk } = {}) {
   if (env.GH_TOKEN) return { ok: true, source: 'env-or-dotenv' };
@@ -178,5 +179,9 @@ export async function ensureCredentials({ stack = 'next', flags = {} } = {}) {
     }
   }
 
+  if (flags.publishReady) {
+    await ensureNpmCredentials({ flags });
+  }
+
   return { collected };
 }

package/src/mvp-flow.mjs

@@ -107,6 +107,36 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
     stack: answers.stack === 'next' ? 'Next.js + TypeScript + Tailwind' : answers.stack,
   });
 
+  let brandPackUsed = null;
+  if (flags.brandPack) {
+    const { findBrandPack } = await import('./brand-packs.mjs');
+    const pack = await findBrandPack(flags.brandPack);
+    if (!pack) {
+      const err = new Error(`No brand pack named '${flags.brandPack}'. Run 'ostup brand-pack list' to see available packs.`);
+      err.code = 'BRAND_PACK_NOT_FOUND';
+      throw err;
+    }
+    brandPackUsed = pack.name;
+    tokens.BRAND_PRIMARY = pack.colors.primary;
+    tokens.BRAND_ACCENT = pack.colors.accent;
+    tokens.BRAND_BACKGROUND = pack.colors.background;
+    tokens.BRAND_FONT_HEADING = pack.fonts.heading;
+    tokens.BRAND_FONT_BODY = pack.fonts.body;
+    if (pack.tagline) tokens.BRAND_TAGLINE = pack.tagline;
+    process.stdout.write(`[brand-pack] using '${pack.name}' (primary=${pack.colors.primary})\n`);
+  }
+
+  if (flags.templates) {
+    const { resolveTemplatesRoot } = await import('./template-resolver.mjs');
+    try {
+      resolveTemplatesRoot(flags.templates);
+      process.stdout.write(`[templates] override path noted: ${flags.templates}\n`);
+      process.stdout.write('[templates] NOTE: v1 ships the resolver + flag; overlay-applier integration lands in v2.1.\n');
+    } catch (err) {
+      throw err;
+    }
+  }
+
   await overlayKit({ targetDir, tokens });
   if (brief) {
     await writeBriefFiles({ targetDir, brief, force: true });
@@ -134,6 +164,23 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
     }
   }
 
+  if (flags.auth && flags.auth !== 'none') {
+    const profile = brief?.scaffold?.profile || null;
+    if (flags.auth === 'clerk') {
+      const { applyAuthClerk } = await import('./auth-clerk.mjs');
+      const r = await applyAuthClerk({ targetDir, profile, tokens });
+      process.stdout.write(`[auth] applied clerk overlay. ${r.touched.length} file(s) touched\n`);
+    } else if (flags.auth === 'google') {
+      const { applyAuthGoogle } = await import('./auth-google.mjs');
+      const r = await applyAuthGoogle({ targetDir, profile, tokens });
+      process.stdout.write(`[auth] applied google overlay. ${r.touched.length} file(s) touched\n`);
+    } else {
+      const err = new Error(`Unknown --auth value '${flags.auth}'. Use clerk, google, or none.`);
+      err.code = 'AUTH_UNKNOWN_PROVIDER';
+      throw err;
+    }
+  }
+
   if (flags.private) {
     const { applyPrivate } = await import('./private.mjs');
     const profile = brief?.scaffold?.profile || null;
@@ -144,6 +191,29 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
     );
   }
 
+  // Record this scaffold in the operator's workspace registry. Best-effort: don't fail the scaffold if write fails.
+  try {
+    const { recordWorkspace } = await import('./workspaces.mjs');
+    const { createHash } = await import('node:crypto');
+    const briefHash = brief ? createHash('sha256').update(JSON.stringify(brief)).digest('hex').slice(0, 16) : null;
+    const pkgVersion = await readFile(resolve(PKG_ROOT, 'package.json'), 'utf8').then((r) => JSON.parse(r).version).catch(() => null);
+    await recordWorkspace({
+      name: answers.projectName,
+      path: targetDir,
+      profile: brief?.scaffold?.profile || null,
+      brief_hash: briefHash,
+      templates_path: flags.templates || null,
+      ostup_version: pkgVersion,
+      white_label: !!flags.whiteLabel,
+      private: !!flags.private,
+      auth: flags.auth && flags.auth !== 'none' ? flags.auth : null,
+      brand_pack: brandPackUsed,
+    });
+    process.stdout.write(`[workspaces] recorded '${answers.projectName}' in ~/.ostup/workspaces.json\n`);
+  } catch (err) {
+    process.stdout.write(`[workspaces] WARN: ${err.message} (scaffold succeeded; registry write failed)\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/private.mjs

@@ -41,7 +41,7 @@ function detectSaas(targetDir, profile) {
 }
 
 function plannedOperations(targetDir, useKvRateLimit) {
-  // Each op: { kind: 'create'|'patch', dest: <relative path>, src: <template relpath>|null, patcher?: fn }
+  // Each op: { kind: 'create'|'patch'|'package-merge', dest, src, mode?, patcher? }
   const rateLimitSrc = useKvRateLimit ? 'lib-rate-limit-kv.ts' : 'lib-rate-limit-memory.ts';
   return [
     { kind: 'create', dest: 'middleware.ts', src: 'middleware.ts' },
@@ -50,11 +50,32 @@ function plannedOperations(targetDir, useKvRateLimit) {
     { kind: 'create', dest: 'app/api/audit/health/route.ts', src: 'api-audit-health.ts' },
     { kind: 'create', dest: 'lib/audit.ts', src: 'lib-audit.ts' },
     { kind: 'create', dest: 'lib/rate-limit.ts', src: rateLimitSrc },
+    { kind: 'package-merge', dest: 'package.json', src: 'package.json.additions' },
+    ...(useKvRateLimit
+      ? [{ kind: 'package-merge-extra', dest: 'package.json', deps: { '@vercel/kv': '^3.0.0' } }]
+      : []),
     { kind: 'patch', dest: 'CLAUDE.md', src: 'CLAUDE_PART_20.md', mode: 'append' },
     { kind: 'patch', dest: 'app/layout.tsx', src: null, mode: 'layout-robots' },
   ];
 }
 
+function mergePackageJson(existing, additionsText) {
+  const additions = JSON.parse(additionsText);
+  const target = existing ? JSON.parse(existing) : {};
+  for (const section of ['dependencies', 'devDependencies', 'scripts']) {
+    if (additions[section]) {
+      target[section] = { ...(target[section] || {}), ...additions[section] };
+    }
+  }
+  return JSON.stringify(target, null, 2) + '\n';
+}
+
+function mergePackageJsonExtra(existing, extraDeps) {
+  const target = existing ? JSON.parse(existing) : {};
+  target.dependencies = { ...(target.dependencies || {}), ...extraDeps };
+  return JSON.stringify(target, null, 2) + '\n';
+}
+
 async function loadTemplate(rel) {
   return readFile(join(PRIVATE_TEMPLATES, rel), 'utf8');
 }
@@ -120,6 +141,23 @@ export async function applyPrivate({ targetDir, profile = null, force = false }
       await mkdir(dirname(destPath), { recursive: true });
       await writeFile(destPath, content, 'utf8');
       performed.push({ kind: 'created', path: op.dest });
+    } else if (op.kind === 'package-merge') {
+      const additionsText = await loadTemplate(op.src);
+      const prior = existsSync(destPath) ? await readFile(destPath, 'utf8') : null;
+      const merged = mergePackageJson(prior, additionsText);
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, merged, 'utf8');
+      if (prior !== null) {
+        performed.push({ kind: 'patched', path: op.dest, prior });
+      } else {
+        performed.push({ kind: 'created', path: op.dest });
+      }
+    } else if (op.kind === 'package-merge-extra') {
+      const prior = existsSync(destPath) ? await readFile(destPath, 'utf8') : null;
+      const merged = mergePackageJsonExtra(prior, op.deps);
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, merged, 'utf8');
+      // No new manifest entry — the prior package-merge op already tracks this file.
     } else if (op.kind === 'patch') {
       if (!existsSync(destPath)) {
         // Patching a missing file is a soft-skip (e.g. no app/layout.tsx exists).

package/src/template-resolver.mjs

@@ -0,0 +1,38 @@
+// template-resolver.mjs: resolve overlay paths, honoring --templates <path> override before falling back to built-in.
+
+import { existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const BUILT_IN_TEMPLATES_ROOT = resolve(PKG_ROOT, 'templates');
+
+class TemplateResolverError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export function resolveTemplatesRoot(override) {
+  if (!override) return BUILT_IN_TEMPLATES_ROOT;
+  const abs = resolve(override);
+  if (!existsSync(abs)) {
+    throw new TemplateResolverError(
+      'TEMPLATES_PATH_NOT_FOUND',
+      `--templates path does not exist: ${abs}`,
+    );
+  }
+  return abs;
+}
+
+export function resolveOverlayPath(overlayName, override) {
+  if (override) {
+    const candidate = resolve(override, overlayName);
+    if (existsSync(candidate)) return candidate;
+  }
+  const builtIn = resolve(BUILT_IN_TEMPLATES_ROOT, overlayName);
+  return existsSync(builtIn) ? builtIn : null;
+}
+
+export { BUILT_IN_TEMPLATES_ROOT, TemplateResolverError };

package/src/white-label.mjs

@@ -1,9 +1,12 @@
 // 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 { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+
+const WHITE_LABEL_MANIFEST_PATH = '.ostup/white-label.json';
+const SCHEMA_VERSION = '1.0.0';
 
 const TARGETS = [
   'AGENTS.md',
@@ -50,5 +53,17 @@ export async function applyWhiteLabel({ targetDir } = {}) {
       touched.push(rel);
     }
   }
+
+  // Write manifest so downstream commands (e.g. /handoff-package) can detect white-label mode.
+  const manifestPath = join(targetDir, WHITE_LABEL_MANIFEST_PATH);
+  await mkdir(dirname(manifestPath), { recursive: true });
+  await writeFile(
+    manifestPath,
+    JSON.stringify({ schema_version: SCHEMA_VERSION, appliedAt: new Date().toISOString(), touched }, null, 2) + '\n',
+    'utf8',
+  );
+
   return { touched };
 }
+
+export { WHITE_LABEL_MANIFEST_PATH };

package/src/workspaces-cmd.mjs

@@ -0,0 +1,50 @@
+// workspaces-cmd.mjs: ostup workspaces ls|show subcommand handler.
+
+import { listWorkspaces, findWorkspace, WorkspacesError } from './workspaces.mjs';
+import { homedir } from 'node:os';
+
+function homeRelative(p) {
+  if (!p) return '';
+  const home = homedir();
+  return p.startsWith(home) ? '~' + p.slice(home.length) : p;
+}
+
+export async function runWorkspaces({ action = 'ls', positional = [] } = {}) {
+  if (action === 'ls') {
+    const items = await listWorkspaces();
+    if (items.length === 0) {
+      process.stdout.write('No workspaces recorded yet. They appear here after `ostup init` succeeds.\n');
+      return;
+    }
+    const header = `${pad('name', 24)}  ${pad('profile', 16)}  ${pad('version', 8)}  ${pad('date', 10)}  path`;
+    process.stdout.write(header + '\n');
+    process.stdout.write('-'.repeat(header.length) + '\n');
+    for (const w of items) {
+      const name = pad(w.name, 24);
+      const profile = pad(w.profile || '-', 16);
+      const version = pad(w.ostup_version || '-', 8);
+      const date = pad((w.scaffolded_at || '').slice(0, 10), 10);
+      process.stdout.write(`${name}  ${profile}  ${version}  ${date}  ${homeRelative(w.path)}\n`);
+    }
+    return;
+  }
+  if (action === 'show') {
+    const name = positional[0];
+    if (!name) {
+      throw new WorkspacesError('WORKSPACES_INVALID', 'Usage: ostup workspaces show <name>');
+    }
+    const entry = await findWorkspace(name);
+    if (!entry) {
+      throw new WorkspacesError('WORKSPACES_NOT_FOUND', `No workspace named '${name}'.`);
+    }
+    process.stdout.write(JSON.stringify(entry, null, 2) + '\n');
+    return;
+  }
+  throw new WorkspacesError('WORKSPACES_UNKNOWN_ACTION', `Unknown action '${action}'. Use: ls | show <name>`);
+}
+
+function pad(s, n) {
+  s = String(s);
+  if (s.length >= n) return s.slice(0, n - 1) + '_';
+  return s + ' '.repeat(n - s.length);
+}

package/src/workspaces.mjs

@@ -0,0 +1,74 @@
+// workspaces.mjs: ~/.ostup/workspaces.json local registry. Atomic writes. Never phones home.
+
+import { readFile, writeFile, mkdir, rename } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const WORKSPACES_PATH = join(homedir(), '.ostup', 'workspaces.json');
+const SCHEMA_VERSION = '1.0.0';
+
+class WorkspacesError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+function emptyRegistry() {
+  return { schema_version: SCHEMA_VERSION, workspaces: [] };
+}
+
+export async function readWorkspaces(path = WORKSPACES_PATH) {
+  if (!existsSync(path)) return emptyRegistry();
+  try {
+    const raw = await readFile(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.workspaces)) return emptyRegistry();
+    return parsed;
+  } catch (err) {
+    throw new WorkspacesError('WORKSPACES_INVALID', `Cannot parse ${path}: ${err.message}`);
+  }
+}
+
+async function atomicWrite(path, content) {
+  await mkdir(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(temp, content, 'utf8');
+  await rename(temp, path);
+}
+
+export async function recordWorkspace(entry, path = WORKSPACES_PATH) {
+  if (!entry || typeof entry.name !== 'string') {
+    throw new WorkspacesError('WORKSPACES_INVALID_ENTRY', 'entry.name is required');
+  }
+  const registry = await readWorkspaces(path);
+  const normalized = {
+    name: entry.name,
+    path: entry.path || '',
+    scaffolded_at: entry.scaffolded_at || new Date().toISOString(),
+    profile: entry.profile || null,
+    brief_hash: entry.brief_hash || null,
+    templates_path: entry.templates_path || null,
+    ostup_version: entry.ostup_version || null,
+    white_label: !!entry.white_label,
+    private: !!entry.private,
+    auth: entry.auth || null,
+    brand_pack: entry.brand_pack || null,
+  };
+  registry.workspaces.push(normalized);
+  await atomicWrite(path, JSON.stringify(registry, null, 2) + '\n');
+  return normalized;
+}
+
+export async function listWorkspaces(path = WORKSPACES_PATH) {
+  const registry = await readWorkspaces(path);
+  return registry.workspaces;
+}
+
+export async function findWorkspace(name, path = WORKSPACES_PATH) {
+  const items = await listWorkspaces(path);
+  return items.find((w) => w.name === name) || null;
+}
+
+export { WORKSPACES_PATH, SCHEMA_VERSION, WorkspacesError };

package/templates/.claude/commands/add-auth.md

@@ -0,0 +1,87 @@
+---
+description: Add authentication to this project after the fact. Clerk or Google OAuth (NextAuth v5).
+---
+
+# Add auth
+
+Use this when the project was scaffolded without `--auth` and the operator now wants login.
+
+## Step 1: Which provider?
+
+If the operator named one (e.g. `/add-auth clerk`), use it. Otherwise ask:
+
+| Provider | Cost | Best for |
+|---|---|---|
+| `clerk` | Free tier up to 10k MAU | Production-grade hosted auth UI; faster setup |
+| `google` | Free | Sign in with Google only (no custom auth); requires Google Cloud Console |
+
+## Step 2: Apply the overlay
+
+Run from the project root:
+
+```bash
+ostup private add  # if you also want default-deny middleware (skip if already on)
+```
+
+Then for Clerk:
+
+```bash
+# Manually run the auth-clerk overlay path (or rerun ostup with --auth=clerk via update)
+```
+
+Or scaffold the files by hand from the templates at `node_modules/@oaklandzoo/ostup/templates/auth-clerk/` (or `auth-google/`).
+
+## Step 3: Get the keys
+
+### Clerk
+
+1. Open https://dashboard.clerk.com/apps
+2. Click **Create application** if you do not have one. Name it the project name. Select Email + Google.
+3. Once created, go to **API Keys**. Copy:
+   - **Publishable key** → `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`
+   - **Secret key** → `CLERK_SECRET_KEY`
+4. Paste both into `.env.local`.
+
+### Google OAuth
+
+1. Open https://console.cloud.google.com/apis/credentials/oauthclient
+2. **Application type**: Web application.
+3. **Authorized redirect URIs**: add `http://localhost:3000/api/auth/callback/google` AND your production URL with the same path.
+4. Click **Create**. Copy:
+   - **Client ID** → `GOOGLE_CLIENT_ID`
+   - **Client secret** → `GOOGLE_CLIENT_SECRET`
+5. Generate a NextAuth secret:
+   ```bash
+   openssl rand -base64 32
+   ```
+   Paste as `AUTH_SECRET`.
+6. Paste all three into `.env.local`.
+
+## Step 4: Verify
+
+```bash
+npm run dev
+```
+
+Open http://localhost:3000/sign-in. You should see the Clerk widget or the Google sign-in button. Sign in. You should land on `/dashboard` or `/`.
+
+If the sign-in page renders but sign-in fails, double-check the env vars are loaded (`npm run dev` reads `.env.local` automatically).
+
+## Step 5: Deploy the env vars to Vercel
+
+```bash
+vercel env add NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY production    # repeat per env per key
+```
+
+Or paste them into the Vercel dashboard under **Settings → Environment Variables**.
+
+## Report
+
+```
+Added <provider> auth:
+- Provider:  <clerk|google>
+- Sign-in:   /sign-in
+- Sign-up:   /sign-up
+- Protected: /dashboard
+- Env vars:  added to .env.local (also push to Vercel before deploying)
+```

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

@@ -115,9 +115,46 @@ Optional bundle: handoff-<project>-<YYYY-MM-DD>.zip (run ostup export-pro to cre
 The recipient can read the package in ~10 minutes and pick up the work.
 ```
 
+## Step 0: Agency-aware mode (Studio v2+)
+
+Before reading project context, check two operator-level signals:
+
+### Detect white-label mode
+
+If `.ostup/white-label.json` exists at the project root, this project was scaffolded with `--white-label`. The generated handoff package MUST scrub OSTUP / Goodshin attribution from its text (Same scrub rules as `ostup init --white-label`).
+
+```bash
+[ -f .ostup/white-label.json ] && echo "white-label mode active"
+```
+
+### Detect agency cover sheet
+
+If `~/.ostup/agency.json` exists, prepend a "Client-ready" cover sheet at the top of `docs/HANDOFF_PACKAGE.md` with the agency's branding. Read it via:
+
+```bash
+[ -f ~/.ostup/agency.json ] && cat ~/.ostup/agency.json
+```
+
+Then render a cover sheet block at the very top of the package:
+
+```markdown
+> # Prepared by <agency.name>
+>
+> <agency.tagline (if set)>
+>
+> Contact: <agency.contact_email (if set)>
+> Web: <agency.website (if set)>
+>
+> ---
+```
+
+If `agency.name` is missing or `agency.json` doesn't exist, skip the cover sheet entirely. The package still works without it.
+
 ## 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.
+- When `.ostup/white-label.json` is present, NEVER emit "OSTUP" / "Goodshin" / "scaffolded with ostup" in the generated package.
+- Agency cover sheet renders gracefully with missing optional fields (only `name` required).