@oaklandzoo/ostup 0.12.0 → 0.13.0

package/bin/cli.mjs

@@ -11,7 +11,7 @@ loadDotEnv();
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-const SUBCOMMANDS = new Set(['init', 'update', 'brief', 'export-pro', 'doctor', 'bootstrap', 'private']);
+const SUBCOMMANDS = new Set(['init', 'update', 'brief', 'export-pro', 'doctor', 'bootstrap', 'private', 'workspaces', 'brand-pack']);
 
 async function readPkg() {
   const raw = await readFile(resolve(PKG_ROOT, 'package.json'), 'utf8');
@@ -48,6 +48,10 @@ function parseArgs(argv) {
     else if (a === '--auth') flags.auth = argv[++i];
     else if (a.startsWith('--auth=')) flags.auth = a.slice('--auth='.length);
     else if (a === '--publish-ready') flags.publishReady = true;
+    else if (a === '--templates') flags.templates = argv[++i];
+    else if (a.startsWith('--templates=')) flags.templates = a.slice('--templates='.length);
+    else if (a === '--brand-pack') flags.brandPack = argv[++i];
+    else if (a.startsWith('--brand-pack=')) flags.brandPack = a.slice('--brand-pack='.length);
     else if (a === '--private') flags.private = true;
     else if (a === '--privacy') flags.privacy = true;
     else if (a === '--url') flags.url = argv[++i];
@@ -233,6 +237,46 @@ if (subcommand === 'private') {
   }
 }
 
+if (subcommand === 'workspaces') {
+  const action = subPositional[0] || 'ls';
+  const positional = subPositional.slice(1);
+  const { runWorkspaces } = await import('../src/workspaces-cmd.mjs');
+  try {
+    await runWorkspaces({ action, positional });
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    const userErrors = new Set([
+      'WORKSPACES_INVALID',
+      'WORKSPACES_NOT_FOUND',
+      'WORKSPACES_UNKNOWN_ACTION',
+      'WORKSPACES_INVALID_ENTRY',
+    ]);
+    process.exit(userErrors.has(err.code) ? 1 : 2);
+  }
+}
+
+if (subcommand === 'brand-pack') {
+  const action = subPositional[0] || 'list';
+  const positional = subPositional.slice(1);
+  const { runBrandPack } = await import('../src/brand-pack-cmd.mjs');
+  try {
+    await runBrandPack({ action, positional, flags });
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    const userErrors = new Set([
+      'BRAND_PACK_INVALID_ENTRY',
+      'BRAND_PACK_NOT_FOUND',
+      'BRAND_PACK_DUPLICATE_NAME',
+      'BRAND_PACK_LIMIT_EXCEEDED',
+      'BRAND_PACK_UNKNOWN_ACTION',
+      'BRAND_PACK_INVALID_REGISTRY',
+    ]);
+    process.exit(userErrors.has(err.code) ? 1 : 2);
+  }
+}
+
 if (subcommand === 'bootstrap') {
   const { runBootstrapStandalone } = await import('../src/bootstrap.mjs');
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.12.0",
+  "version": "0.13.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/scripts/verify-studio.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# verify-studio.sh: run Studio v2 unit tests in isolation.
+
+set -euo pipefail
+
+OSTUP_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$OSTUP_ROOT"
+
+echo ">> verifying Studio v2 modules"
+node --test \
+  test/template-resolver.test.mjs \
+  test/workspaces.test.mjs \
+  test/brand-packs.test.mjs \
+  test/agency.test.mjs
+
+echo ">> ok: all Studio v2 module tests pass"

package/src/agency.mjs

@@ -0,0 +1,45 @@
+// agency.mjs: ~/.ostup/agency.json operator-level config for Studio handoff bundles.
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const AGENCY_CONFIG_PATH = join(homedir(), '.ostup', 'agency.json');
+
+class AgencyError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export async function readAgencyConfig(path = AGENCY_CONFIG_PATH) {
+  if (!existsSync(path)) return null;
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new AgencyError('AGENCY_CONFIG_INVALID', `Cannot parse ${path}: ${err.message}`);
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  if (typeof parsed.name !== 'string' || !parsed.name.trim()) {
+    throw new AgencyError('AGENCY_CONFIG_INVALID', 'agency.name is required and must be a non-empty string');
+  }
+  return {
+    schema_version: parsed.schema_version || '1.0.0',
+    name: parsed.name.trim(),
+    logo_path: parsed.logo_path || null,
+    tagline: parsed.tagline || null,
+    contact_email: parsed.contact_email || null,
+    website: parsed.website || null,
+  };
+}
+
+export { AGENCY_CONFIG_PATH, AgencyError };

package/src/brand-pack-cmd.mjs

@@ -0,0 +1,76 @@
+// brand-pack-cmd.mjs: ostup brand-pack add|remove|list|show subcommand handler.
+
+import * as p from '@clack/prompts';
+import { addBrandPack, removeBrandPack, listBrandPacks, findBrandPack, BrandPackError, MAX_PACKS } from './brand-packs.mjs';
+
+export async function runBrandPack({ action = 'list', positional = [], flags = {} } = {}) {
+  if (action === 'list' || action === 'ls') {
+    const packs = await listBrandPacks();
+    if (packs.length === 0) {
+      process.stdout.write(`No brand packs yet. Cap: ${MAX_PACKS} per user.\n`);
+      process.stdout.write(`Add one with: ostup brand-pack add\n`);
+      return;
+    }
+    process.stdout.write(`${packs.length} brand pack(s) (cap: ${MAX_PACKS}):\n`);
+    for (const pk of packs) {
+      process.stdout.write(`  - ${pk.name}  primary=${pk.colors.primary}  tagline="${pk.tagline || ''}"  created=${pk.created_at.slice(0, 10)}\n`);
+    }
+    return;
+  }
+  if (action === 'show') {
+    const name = positional[0];
+    if (!name) throw new BrandPackError('BRAND_PACK_INVALID_ENTRY', 'Usage: ostup brand-pack show <name>');
+    const pk = await findBrandPack(name);
+    if (!pk) throw new BrandPackError('BRAND_PACK_NOT_FOUND', `No brand pack named '${name}'.`);
+    process.stdout.write(JSON.stringify(pk, null, 2) + '\n');
+    return;
+  }
+  if (action === 'remove' || action === 'rm') {
+    const name = positional[0];
+    if (!name) throw new BrandPackError('BRAND_PACK_INVALID_ENTRY', 'Usage: ostup brand-pack remove <name>');
+    const removed = await removeBrandPack(name);
+    process.stdout.write(`Removed brand pack '${removed.name}'.\n`);
+    return;
+  }
+  if (action === 'add') {
+    if (flags.yes) {
+      // Non-interactive add with defaults: name from positional, everything else default.
+      const name = positional[0];
+      if (!name) throw new BrandPackError('BRAND_PACK_INVALID_ENTRY', 'Usage with --yes: ostup brand-pack add <name>');
+      const added = await addBrandPack({ name });
+      process.stdout.write(`Added '${added.name}' with default colors/fonts. Edit ~/.ostup/brand-packs.json to customize.\n`);
+      return;
+    }
+    const name = await p.text({ message: 'Brand pack name (kebab-case)', validate: (v) => (!v || !v.trim() ? 'Required.' : undefined) });
+    if (p.isCancel(name)) { process.stdout.write('Cancelled.\n'); return; }
+    const primary = await p.text({ message: 'Primary color (hex)', initialValue: '#0f172a', placeholder: '#0f172a' });
+    if (p.isCancel(primary)) { process.stdout.write('Cancelled.\n'); return; }
+    const accent = await p.text({ message: 'Accent color (hex)', initialValue: '#2563eb', placeholder: '#2563eb' });
+    if (p.isCancel(accent)) { process.stdout.write('Cancelled.\n'); return; }
+    const background = await p.text({ message: 'Background color (hex)', initialValue: '#ffffff', placeholder: '#ffffff' });
+    if (p.isCancel(background)) { process.stdout.write('Cancelled.\n'); return; }
+    const heading = await p.text({ message: 'Heading font family', initialValue: 'system-ui, sans-serif' });
+    if (p.isCancel(heading)) { process.stdout.write('Cancelled.\n'); return; }
+    const body = await p.text({ message: 'Body font family', initialValue: 'system-ui, sans-serif' });
+    if (p.isCancel(body)) { process.stdout.write('Cancelled.\n'); return; }
+    const voiceRaw = await p.text({ message: 'Voice (3-5 comma-separated words; e.g. credible, warm, premium)', initialValue: '' });
+    if (p.isCancel(voiceRaw)) { process.stdout.write('Cancelled.\n'); return; }
+    const tagline = await p.text({ message: 'Tagline (one line; optional)', initialValue: '' });
+    if (p.isCancel(tagline)) { process.stdout.write('Cancelled.\n'); return; }
+    const logoPath = await p.text({ message: 'Logo path (absolute; optional)', initialValue: '' });
+    if (p.isCancel(logoPath)) { process.stdout.write('Cancelled.\n'); return; }
+
+    const voice = String(voiceRaw).split(',').map((s) => s.trim()).filter(Boolean).slice(0, 5);
+    const added = await addBrandPack({
+      name: String(name).trim(),
+      colors: { primary: String(primary), accent: String(accent), background: String(background) },
+      fonts: { heading: String(heading), body: String(body) },
+      voice,
+      logo_path: String(logoPath).trim() || null,
+      tagline: String(tagline).trim() || null,
+    });
+    process.stdout.write(`Added brand pack '${added.name}'. Now ${(await listBrandPacks()).length}/${MAX_PACKS} used.\n`);
+    return;
+  }
+  throw new BrandPackError('BRAND_PACK_UNKNOWN_ACTION', `Unknown action '${action}'. Use: add | remove | list | show <name>`);
+}

package/src/brand-packs.mjs

@@ -0,0 +1,101 @@
+// brand-packs.mjs: ~/.ostup/brand-packs.json operator-level registry. Cap: 5 per user.
+
+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 BRAND_PACKS_PATH = join(homedir(), '.ostup', 'brand-packs.json');
+const SCHEMA_VERSION = '1.0.0';
+export const MAX_PACKS = 5;
+
+class BrandPackError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+function emptyRegistry() {
+  return { schema_version: SCHEMA_VERSION, packs: [] };
+}
+
+export async function readBrandPacks(path = BRAND_PACKS_PATH) {
+  if (!existsSync(path)) return emptyRegistry();
+  try {
+    const raw = await readFile(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.packs)) return emptyRegistry();
+    return parsed;
+  } catch (err) {
+    throw new BrandPackError('BRAND_PACK_INVALID_REGISTRY', `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 addBrandPack(entry, path = BRAND_PACKS_PATH) {
+  if (!entry || typeof entry.name !== 'string' || !entry.name.trim()) {
+    throw new BrandPackError('BRAND_PACK_INVALID_ENTRY', 'entry.name is required and must be a non-empty string');
+  }
+  const registry = await readBrandPacks(path);
+  if (registry.packs.some((p) => p.name === entry.name)) {
+    throw new BrandPackError(
+      'BRAND_PACK_DUPLICATE_NAME',
+      `A brand pack named '${entry.name}' already exists. Remove it first or pick a different name.`,
+    );
+  }
+  if (registry.packs.length >= MAX_PACKS) {
+    throw new BrandPackError(
+      'BRAND_PACK_LIMIT_EXCEEDED',
+      `Maximum ${MAX_PACKS} brand packs per user. Remove one with 'ostup brand-pack remove <name>' before adding a new one.`,
+    );
+  }
+  const normalized = {
+    name: entry.name.trim(),
+    created_at: entry.created_at || new Date().toISOString(),
+    colors: {
+      primary: entry.colors?.primary || '#0f172a',
+      accent: entry.colors?.accent || '#2563eb',
+      background: entry.colors?.background || '#ffffff',
+    },
+    fonts: {
+      heading: entry.fonts?.heading || 'system-ui, sans-serif',
+      body: entry.fonts?.body || 'system-ui, sans-serif',
+    },
+    voice: Array.isArray(entry.voice) ? entry.voice.slice(0, 5) : [],
+    logo_path: entry.logo_path || null,
+    tagline: entry.tagline || null,
+  };
+  registry.packs.push(normalized);
+  await atomicWrite(path, JSON.stringify(registry, null, 2) + '\n');
+  return normalized;
+}
+
+export async function removeBrandPack(name, path = BRAND_PACKS_PATH) {
+  const registry = await readBrandPacks(path);
+  const idx = registry.packs.findIndex((p) => p.name === name);
+  if (idx === -1) {
+    throw new BrandPackError('BRAND_PACK_NOT_FOUND', `No brand pack named '${name}'.`);
+  }
+  const removed = registry.packs.splice(idx, 1)[0];
+  await atomicWrite(path, JSON.stringify(registry, null, 2) + '\n');
+  return removed;
+}
+
+export async function listBrandPacks(path = BRAND_PACKS_PATH) {
+  const registry = await readBrandPacks(path);
+  return registry.packs;
+}
+
+export async function findBrandPack(name, path = BRAND_PACKS_PATH) {
+  const items = await listBrandPacks(path);
+  return items.find((p) => p.name === name) || null;
+}
+
+export { BRAND_PACKS_PATH, SCHEMA_VERSION, BrandPackError };

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 });
@@ -161,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/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).

package/templates/private/package.json.additions

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "@vercel/blob": "^0.27.0"
+  }
+}