@oaklandzoo/ostup 0.11.0 → 0.13.0

package/README.md

@@ -32,6 +32,18 @@ When you run this tool, it will:
    verify. Toggle on/off an existing project with `ostup private add` /
    `ostup private remove` (manifest at `.ostup/private.json` makes the
    remove cleanly revertable).
+9. Optionally pass `--auth=clerk` or `--auth=google` to wire **a
+   working login flow** into the scaffold. Clerk uses `@clerk/nextjs`
+   (hosted UI, free up to 10k MAU); Google uses NextAuth v5 with the
+   Google provider (free; you create the OAuth app on Google Cloud).
+   Both ship sign-in / sign-up pages out of the box. `--auth` composes
+   cleanly with `--private` (the default-deny middleware recognizes
+   both providers' session cookies).
+10. Optionally pass `--publish-ready` if this CLI will be used to
+    publish an npm package later. ostup walks you through getting an
+    npm Bypass-2FA token (browser flow or guided token paste) and
+    saves it to `~/.npmrc`. After that, the `/publish` slash command
+    lets your agent ship a new version with one command.
 
 ## Quick Start
 

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');
@@ -45,6 +45,13 @@ 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 === '--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];
@@ -96,6 +103,8 @@ function printHelp() {
       '  --brief <path>      Load a brief.json from <path> and write brief files + apply profile overlay.',
       '  --white-label       Strip OSTUP / Goodshin attribution from generated docs (Studio tier).',
       '  --private           App-level default-deny: middleware, blob proxy, image-optimizer lock, audit + rate-limit, CLAUDE.md Part 20. Refused with --profile saas-dashboard.',
+      '  --auth <provider>   Wire authentication. Values: clerk (Clerk + @clerk/nextjs), google (NextAuth v5 + Google), none. Refused with --profile saas-dashboard.',
+      '  --publish-ready     Walk through npm token setup so this CLI can publish later (writes ~/.npmrc).',
       '  --kit-only          Drop the markdown kit into a target dir, no GitHub or Vercel.',
       '  --config <path>     Read .ostup-config.yml from this path (kit-only mode).',
       '  --skip-bootstrap    Skip the in-CLI tool detection / install step (advanced).',
@@ -228,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 {
@@ -283,6 +332,13 @@ try {
     'INGEST_PATH_NOT_FOUND',
     'BRIEF_NOT_FOUND',
     'BRIEF_INVALID',
+    'AUTH_ALREADY_APPLIED',
+    'AUTH_PROFILE_CONFLICT',
+    'AUTH_DIRTY',
+    'AUTH_UNKNOWN_PROVIDER',
+    'PRIVATE_SAAS_CONFLICT',
+    'PRIVATE_ALREADY_APPLIED',
+    'PRIVATE_DIRTY',
     'NO_TTY_BOOTSTRAP',
     'BOOTSTRAP_DECLINED',
     'BOOTSTRAP_FAILED',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.11.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-auth.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# verify-auth.sh: apply an auth overlay to a fresh temp dir and assert files + manifest land.
+#
+# Usage: bash scripts/verify-auth.sh <clerk|google>
+
+set -euo pipefail
+
+PROVIDER="${1:-}"
+case "$PROVIDER" in
+  clerk|google) ;;
+  *)
+    echo "usage: $0 <clerk|google>" >&2
+    exit 2
+    ;;
+esac
+
+OSTUP_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TEST_FILE="$OSTUP_ROOT/test/auth-$PROVIDER.test.mjs"
+
+echo ">> verifying auth provider: $PROVIDER"
+echo ">> running: node --test $TEST_FILE"
+cd "$OSTUP_ROOT"
+node --test "$TEST_FILE"
+
+echo ">> ok: $PROVIDER overlay applies and asserts pass"
+echo ""
+echo ">> for live verification (operator only):"
+echo "   1. ostup init --yes --name verify-auth --brief test/fixtures/brief-leadgen.json --auth=$PROVIDER"
+echo "   2. cd verify-auth && npm install && npx next build"
+echo "   3. open the deployed URL, sign in, verify session lands on /dashboard"

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/auth-clerk.mjs

@@ -0,0 +1,146 @@
+// auth-clerk.mjs: applyAuthClerk post-processor. Drops Clerk integration into a scaffold.
+
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const TEMPLATES_ROOT = resolve(PKG_ROOT, 'templates', 'auth-clerk');
+
+export const AUTH_MANIFEST_PATH = '.ostup/auth.json';
+
+class AuthError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+function plannedOps(targetDir) {
+  return [
+    { kind: 'create-or-overwrite', dest: 'middleware.ts', src: 'middleware.ts' },
+    { kind: 'create-or-overwrite', dest: 'app/layout.tsx', src: 'layout.tsx' },
+    { kind: 'create', dest: 'app/sign-in/[[...sign-in]]/page.tsx', src: 'sign-in-page.tsx' },
+    { kind: 'create', dest: 'app/sign-up/[[...sign-up]]/page.tsx', src: 'sign-up-page.tsx' },
+    { kind: 'package-merge', dest: 'package.json', src: 'package.json.additions' },
+    { kind: 'env-append', dest: '.env.example', src: 'env.example.additions' },
+  ];
+}
+
+async function loadTemplate(rel) {
+  return readFile(join(TEMPLATES_ROOT, rel), 'utf8');
+}
+
+function tokenSubstitute(body, tokens) {
+  if (!tokens) return body;
+  return body.replace(/\{\{([A-Z_][A-Z_0-9]*)\}\}/g, (m, k) => (tokens[k] != null ? String(tokens[k]) : 'TBD'));
+}
+
+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';
+}
+
+export async function applyAuthClerk({ targetDir, profile = null, tokens = {}, force = false } = {}) {
+  const manifestPath = join(targetDir, AUTH_MANIFEST_PATH);
+  if (existsSync(manifestPath) && !force) {
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    throw new AuthError(
+      'AUTH_ALREADY_APPLIED',
+      `${AUTH_MANIFEST_PATH} already exists (provider: ${manifest.provider}). Run remove first, or pass --force.`,
+    );
+  }
+  if (profile === 'saas-dashboard') {
+    throw new AuthError(
+      'AUTH_PROFILE_CONFLICT',
+      '--auth=clerk is not compatible with --profile saas-dashboard. saas-dashboard ships Better Auth. Pick one.',
+    );
+  }
+
+  const ops = plannedOps(targetDir);
+  const performed = [];
+
+  for (const op of ops) {
+    const destPath = join(targetDir, op.dest);
+    const tmpl = await loadTemplate(op.src);
+    const content = tokenSubstitute(tmpl, tokens);
+
+    if (op.kind === 'create') {
+      if (existsSync(destPath) && !force) {
+        throw new AuthError('AUTH_DIRTY', `${op.dest} already exists; refuse to overwrite without --force.`);
+      }
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, content, 'utf8');
+      performed.push({ kind: 'created', path: op.dest });
+    } else if (op.kind === 'create-or-overwrite') {
+      const prior = existsSync(destPath) ? await readFile(destPath, 'utf8') : null;
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, content, 'utf8');
+      if (prior !== null) {
+        performed.push({ kind: 'replaced', path: op.dest, prior });
+      } else {
+        performed.push({ kind: 'created', path: op.dest });
+      }
+    } else if (op.kind === 'package-merge') {
+      const prior = existsSync(destPath) ? await readFile(destPath, 'utf8') : null;
+      const merged = mergePackageJson(prior, content);
+      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 === 'env-append') {
+      const prior = existsSync(destPath) ? await readFile(destPath, 'utf8') : null;
+      const next = prior ? prior + (prior.endsWith('\n') ? '' : '\n') + '\n' + content : content;
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, next, 'utf8');
+      if (prior !== null) {
+        performed.push({ kind: 'patched', path: op.dest, prior });
+      } else {
+        performed.push({ kind: 'created', path: op.dest });
+      }
+    }
+  }
+
+  await mkdir(dirname(manifestPath), { recursive: true });
+  await writeFile(
+    manifestPath,
+    JSON.stringify({ appliedAt: new Date().toISOString(), provider: 'clerk', ops: performed }, null, 2) + '\n',
+    'utf8',
+  );
+
+  return { applied: true, provider: 'clerk', touched: performed.map((p) => p.path) };
+}
+
+export async function removeAuthClerk({ targetDir } = {}) {
+  const manifestPath = join(targetDir, AUTH_MANIFEST_PATH);
+  if (!existsSync(manifestPath)) {
+    throw new AuthError('AUTH_NOT_APPLIED', `${AUTH_MANIFEST_PATH} not found.`);
+  }
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  const restored = [];
+  for (const op of [...manifest.ops].reverse()) {
+    const p = join(targetDir, op.path);
+    if (op.kind === 'created' && existsSync(p)) {
+      await rm(p, { force: true });
+      restored.push({ kind: 'deleted', path: op.path });
+    } else if ((op.kind === 'replaced' || op.kind === 'patched') && existsSync(p)) {
+      await writeFile(p, op.prior, 'utf8');
+      restored.push({ kind: 'restored', path: op.path });
+    }
+  }
+  await rm(manifestPath, { force: true });
+  try { await rm(join(targetDir, '.ostup'), { recursive: false }); } catch {}
+  return { restored: restored.map((r) => r.path), provider: manifest.provider };
+}
+
+export { AuthError };

package/src/auth-google.mjs

@@ -0,0 +1,137 @@
+// auth-google.mjs: applyAuthGoogle post-processor. Drops NextAuth v5 + Google provider into a scaffold.
+
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const TEMPLATES_ROOT = resolve(PKG_ROOT, 'templates', 'auth-google');
+
+export const AUTH_MANIFEST_PATH = '.ostup/auth.json';
+
+class AuthError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+function plannedOps() {
+  return [
+    { kind: 'create', dest: 'auth.ts', src: 'auth.ts' },
+    { kind: 'create', dest: 'app/api/auth/[...nextauth]/route.ts', src: 'route.ts' },
+    { kind: 'create', dest: 'app/sign-in/page.tsx', src: 'sign-in-page.tsx' },
+    { kind: 'create', dest: 'app/sign-up/page.tsx', src: 'sign-up-page.tsx' },
+    { kind: 'package-merge', dest: 'package.json', src: 'package.json.additions' },
+    { kind: 'env-append', dest: '.env.example', src: 'env.example.additions' },
+  ];
+}
+
+async function loadTemplate(rel) {
+  return readFile(join(TEMPLATES_ROOT, rel), 'utf8');
+}
+
+function tokenSubstitute(body, tokens) {
+  if (!tokens) return body;
+  return body.replace(/\{\{([A-Z_][A-Z_0-9]*)\}\}/g, (m, k) => (tokens[k] != null ? String(tokens[k]) : 'TBD'));
+}
+
+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';
+}
+
+export async function applyAuthGoogle({ targetDir, profile = null, tokens = {}, force = false } = {}) {
+  const manifestPath = join(targetDir, AUTH_MANIFEST_PATH);
+  if (existsSync(manifestPath) && !force) {
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    throw new AuthError(
+      'AUTH_ALREADY_APPLIED',
+      `${AUTH_MANIFEST_PATH} already exists (provider: ${manifest.provider}). Run remove first, or pass --force.`,
+    );
+  }
+  if (profile === 'saas-dashboard') {
+    throw new AuthError(
+      'AUTH_PROFILE_CONFLICT',
+      '--auth=google is not compatible with --profile saas-dashboard. saas-dashboard ships Better Auth. Pick one.',
+    );
+  }
+
+  const ops = plannedOps();
+  const performed = [];
+
+  for (const op of ops) {
+    const destPath = join(targetDir, op.dest);
+    const tmpl = await loadTemplate(op.src);
+    const content = tokenSubstitute(tmpl, tokens);
+
+    if (op.kind === 'create') {
+      if (existsSync(destPath) && !force) {
+        throw new AuthError('AUTH_DIRTY', `${op.dest} already exists; refuse to overwrite without --force.`);
+      }
+      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 prior = existsSync(destPath) ? await readFile(destPath, 'utf8') : null;
+      const merged = mergePackageJson(prior, content);
+      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 === 'env-append') {
+      const prior = existsSync(destPath) ? await readFile(destPath, 'utf8') : null;
+      const next = prior ? prior + (prior.endsWith('\n') ? '' : '\n') + '\n' + content : content;
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, next, 'utf8');
+      if (prior !== null) {
+        performed.push({ kind: 'patched', path: op.dest, prior });
+      } else {
+        performed.push({ kind: 'created', path: op.dest });
+      }
+    }
+  }
+
+  await mkdir(dirname(manifestPath), { recursive: true });
+  await writeFile(
+    manifestPath,
+    JSON.stringify({ appliedAt: new Date().toISOString(), provider: 'google', ops: performed }, null, 2) + '\n',
+    'utf8',
+  );
+
+  return { applied: true, provider: 'google', touched: performed.map((p) => p.path) };
+}
+
+export async function removeAuthGoogle({ targetDir } = {}) {
+  const manifestPath = join(targetDir, AUTH_MANIFEST_PATH);
+  if (!existsSync(manifestPath)) {
+    throw new AuthError('AUTH_NOT_APPLIED', `${AUTH_MANIFEST_PATH} not found.`);
+  }
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  const restored = [];
+  for (const op of [...manifest.ops].reverse()) {
+    const p = join(targetDir, op.path);
+    if (op.kind === 'created' && existsSync(p)) {
+      await rm(p, { force: true });
+      restored.push({ kind: 'deleted', path: op.path });
+    } else if (op.kind === 'patched' && existsSync(p)) {
+      await writeFile(p, op.prior, 'utf8');
+      restored.push({ kind: 'restored', path: op.path });
+    }
+  }
+  await rm(manifestPath, { force: true });
+  try { await rm(join(targetDir, '.ostup'), { recursive: false }); } catch {}
+  return { restored: restored.map((r) => r.path), provider: manifest.provider };
+}
+
+export { AuthError };

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 };