@oaklandzoo/ostup 0.5.0 → 0.6.0

package/bin/cli.mjs

@@ -10,7 +10,7 @@ loadDotEnv();
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-const SUBCOMMANDS = new Set(['init', 'update', 'brief']);
+const SUBCOMMANDS = new Set(['init', 'update', 'brief', 'export-pro']);
 
 async function readPkg() {
   const raw = await readFile(resolve(PKG_ROOT, 'package.json'), 'utf8');
@@ -41,6 +41,9 @@ function parseArgs(argv) {
     else if (a.startsWith('--brief=')) flags.brief = a.slice('--brief='.length);
     else if (a === '--target') flags.target = argv[++i];
     else if (a.startsWith('--target=')) flags.target = a.slice('--target='.length);
+    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.startsWith('-')) {
       process.stderr.write(`unknown flag: ${a}\n`);
       process.exit(1);
@@ -62,6 +65,7 @@ function printHelp() {
       'Commands:',
       '  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.',
       '  update              Refresh bundled templates from the pinned source.',
       '',
       'Flags for `ostup init`:',
@@ -72,6 +76,7 @@ function printHelp() {
       '  --name <kebab>      Skip the projectName prompt.',
       '  --ingest <path>     Copy operator materials from <path> into inputs/.',
       '  --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).',
       '  --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).',
       '',
@@ -81,6 +86,10 @@ function printHelp() {
       '  --force             Overwrite existing docs/brief.md, docs/brief.json, tasks/prd-initial-build.md.',
       '  --dry-run           Print what would be written without writing.',
       '',
+      'Flags for `ostup export-pro`:',
+      '  --output <file>     ZIP filename (default: pro-export-<project>-<timestamp>.zip).',
+      '  --dry-run           Print what would be bundled without writing the ZIP.',
+      '',
       'Global flags:',
       '  --version, -v       Print version and exit.',
       '  --help, -h          Print this help and exit.',
@@ -142,6 +151,26 @@ if (subcommand === 'brief') {
   }
 }
 
+if (subcommand === 'export-pro') {
+  const { exportPro } = await import('../src/export-pro.mjs');
+  try {
+    const result = await exportPro({ output: flags.output, dryRun: flags.dryRun });
+    if (!result.dryRun) {
+      const kb = (result.bytes / 1024).toFixed(1);
+      process.stdout.write(`Exported: ${result.zipPath} (${kb} KB)\n`);
+      process.stdout.write(`Included ${result.present.length} path(s).\n`);
+      if (result.missing.length > 0) {
+        process.stdout.write(`Skipped ${result.missing.length} missing path(s): ${result.missing.join(', ')}\n`);
+      }
+    }
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    const userErrors = new Set(['EXPORT_EMPTY', 'EXPORT_FAILED']);
+    process.exit(userErrors.has(err.code) ? 1 : 2);
+  }
+}
+
 // subcommand === 'init'
 if (flags.kitOnly) {
   const { scaffold } = await import('../src/scaffold.mjs');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.5.0",
+  "version": "0.6.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/export-pro.mjs

@@ -0,0 +1,87 @@
+// export-pro.mjs: bundle docs/brief + assets/brand + assets/content + tasks/prd-initial-build into a single ZIP for client handoff.
+
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, writeFile, stat } from 'node:fs/promises';
+import { resolve, join, relative, dirname } from 'node:path';
+import { execSync } from 'node:child_process';
+
+const INCLUDE_PATHS = [
+  'docs/brief.md',
+  'docs/brief.json',
+  'tasks/prd-initial-build.md',
+  'assets/brand',
+  'assets/content',
+  'README.md',
+  'CLAUDE.md',
+  'AGENTS.md',
+  'START_HERE.md',
+];
+
+async function walk(dir, base = dir, out = []) {
+  if (!existsSync(dir)) return out;
+  const s = await stat(dir);
+  if (!s.isDirectory()) {
+    out.push(relative(base, dir) || dir.split('/').pop());
+    return out;
+  }
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) await walk(full, base, out);
+    else if (entry.isFile()) out.push(full);
+  }
+  return out;
+}
+
+export async function exportPro({ cwd = process.cwd(), output, dryRun = false } = {}) {
+  const root = resolve(cwd);
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 17);
+  const projectName = (() => {
+    try {
+      const pkg = require('node:fs').readFileSync(join(root, 'package.json'), 'utf8');
+      return JSON.parse(pkg).name?.replace(/[^a-z0-9-]/gi, '-') || 'project';
+    } catch {
+      return root.split('/').pop() || 'project';
+    }
+  })();
+  const zipName = output || `pro-export-${projectName}-${timestamp}.zip`;
+  const zipPath = resolve(root, zipName);
+
+  // Verify what's available before bundling
+  const present = [];
+  const missing = [];
+  for (const p of INCLUDE_PATHS) {
+    if (existsSync(join(root, p))) present.push(p);
+    else missing.push(p);
+  }
+
+  if (present.length === 0) {
+    const err = new Error('nothing to export: none of the standard pro-export paths exist in this project');
+    err.code = 'EXPORT_EMPTY';
+    throw err;
+  }
+
+  if (dryRun) {
+    process.stdout.write('[export-pro] would bundle:\n');
+    for (const p of present) process.stdout.write(`  + ${p}\n`);
+    if (missing.length > 0) {
+      process.stdout.write('[export-pro] missing (skipped):\n');
+      for (const p of missing) process.stdout.write(`  - ${p}\n`);
+    }
+    process.stdout.write(`[export-pro] would write: ${zipPath}\n`);
+    return { zipPath, present, missing, dryRun: true };
+  }
+
+  // Use zip CLI (universally available on macOS + Linux). Build a list of relative paths to include.
+  const args = ['-r', '-q', zipPath, ...present];
+  try {
+    execSync(`zip ${args.map((a) => `"${a}"`).join(' ')}`, { cwd: root, stdio: 'pipe' });
+  } catch (err) {
+    const e = new Error(`zip failed: ${err.message || err}`);
+    e.code = 'EXPORT_FAILED';
+    throw e;
+  }
+
+  const bytes = (await stat(zipPath)).size;
+  return { zipPath, present, missing, bytes };
+}

package/src/templates.mjs

@@ -31,6 +31,8 @@ export const REGISTRY = [
   { src: '.claude/commands/resume.md',         dest: '.claude/commands/resume.md' },
   { src: '.claude/commands/handoff-doctor.md', dest: '.claude/commands/handoff-doctor.md' },
   { 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.md',                          dest: 'CLAUDE.md' },
   { src: 'AGENTS.md',                          dest: 'AGENTS.md' },
   { src: 'START_HERE.md',                      dest: 'START_HERE.md' },

package/templates/.claude/commands/generate-brand-kit.md

@@ -0,0 +1,225 @@
+---
+description: Compose a brand kit from the operator brief and any existing inputs/images. Writes assets/brand/{palette.md, typography.md, voice.md, logo.svg, MANIFEST.md}. Composer-only; no API call. Operator promotes individual assets into the actual project.
+---
+
+# /generate-brand-kit
+
+Build a project-specific brand kit from the brief. Composer-only. Designed so the agent can produce a coherent, opinionated brand starter without an external design step.
+
+## Step 1: read context
+
+```bash
+[ -f docs/brief.md ] && cat docs/brief.md
+[ -f docs/brief.json ] && cat docs/brief.json
+ls inputs/images/ 2>/dev/null
+[ -f inputs/images/MANIFEST.md ] && cat inputs/images/MANIFEST.md
+```
+
+Absorb: `brand.vibe`, `brand.color_notes`, `brand.font_notes`, `brand.logo_notes`, `brand.inspiration_urls`, and any image in `inputs/images/`.
+
+## Step 2: clarify if needed (max 2 questions)
+
+If the brief is silent on a critical field, ask:
+
+- Color direction: warm or cool? Light, dark, or both?
+- Type direction: serif headers + sans body, sans-only, mono-accents?
+
+Skip the question if the brief already answers it.
+
+## Step 3: write the 5 brand-kit files
+
+```bash
+mkdir -p assets/brand
+```
+
+### `assets/brand/palette.md`
+
+```markdown
+# Color palette
+
+> Source: `docs/brief.md` (brand.color_notes + brand.vibe).
+
+## Primary
+
+| Role | Token | Hex | Use |
+|---|---|---|---|
+| Primary | `--color-primary` | #XXXXXX | Buttons, links, focused state |
+| Primary contrast | `--color-on-primary` | #FFFFFF | Text on primary |
+| Surface | `--color-surface` | #XXXXXX | Default page background |
+| Surface contrast | `--color-on-surface` | #XXXXXX | Body text |
+
+## Secondary
+
+| Role | Token | Hex | Use |
+|---|---|---|---|
+| Accent | `--color-accent` | #XXXXXX | Highlights, callouts |
+| Muted | `--color-muted` | #XXXXXX | Secondary text, borders |
+| Surface alt | `--color-surface-alt` | #XXXXXX | Cards, hovered rows |
+
+## Semantic
+
+| Role | Token | Hex |
+|---|---|---|
+| Success | `--color-success` | #XXXXXX |
+| Warning | `--color-warning` | #XXXXXX |
+| Error | `--color-error` | #XXXXXX |
+
+## Dark mode
+
+Provide a mirrored palette using `prefers-color-scheme`. Same role names; different hex.
+
+## CSS export
+
+```css
+:root {
+  --color-primary: #XXXXXX;
+  --color-on-primary: #FFFFFF;
+  /* etc. */
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-primary: #XXXXXX;
+    /* etc. */
+  }
+}
+```
+```
+
+Fill the placeholders with REAL hex codes derived from the brief's color_notes + vibe. Examples:
+
+- Warm + premium + lodge → espresso `#3a2a1f`, sand `#e8dcc4`, accent walnut `#5b3a2a`
+- Credible + minimal + SaaS → near-black `#0a0a0a`, off-white `#fafafa`, accent blue `#2563eb`
+- Bold + playful + creator → mid-saturation primary, generous accents, dark+light parity
+
+Show the palette in context with usage examples.
+
+### `assets/brand/typography.md`
+
+```markdown
+# Typography
+
+> Source: `docs/brief.md` (brand.font_notes + brand.vibe).
+
+## Scale
+
+| Role | Family | Size | Weight | Line height | Use |
+|---|---|---|---|---|---|
+| Display | system or named | 48-72px | 700-800 | 1.1 | Hero headlines |
+| H1 | same | 32-40px | 600-700 | 1.2 | Page titles |
+| H2 | same | 24-28px | 600 | 1.3 | Section headers |
+| H3 | same | 20-22px | 600 | 1.3 | Subsections |
+| Body | system sans | 16-18px | 400 | 1.6 | Reading copy |
+| Small | system sans | 14px | 400 | 1.5 | Metadata, caption |
+| Mono | system mono | 14-16px | 400 | 1.5 | Code, terminal |
+
+## Recommended families
+
+- **Body:** `-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif` (zero webfont weight).
+- **Mono:** `ui-monospace, SFMono-Regular, "Consolas", monospace`.
+- **Display:** decide per the brief. If brief mentions "serif" or "editorial," use `ui-serif, Georgia, serif`. If "minimal" or "tech," stick with system sans at a heavier weight.
+
+If the operator wants a named webfont, document the load strategy: `<link rel="preconnect">` + `font-display: swap` + `<link rel="stylesheet">`. Never block first paint.
+
+## Tailwind-safe scale
+
+Map the above to Tailwind's default scale where possible. If the brief specifies a custom scale, override in `tailwind.config.ts` under `theme.extend.fontSize`.
+```
+
+### `assets/brand/voice.md`
+
+```markdown
+# Voice and tone
+
+> Source: `docs/brief.md` (brand.vibe + project.summary).
+
+## Three-word vibe
+
+<copy from brief>
+
+## Tone rules
+
+- **Plain English.** No jargon. No "leverage," no "delight," no "empower."
+- **Short sentences.** Periods over commas. No em dashes.
+- **Anti-fluff.** No apologies, no "we're excited," no "great question."
+- **Honest about limits.** State what the product cannot do.
+
+## Voice in components
+
+| Component | Pattern |
+|---|---|
+| Headlines | 5-9 words, declarative, name the change |
+| Subheads | one sentence: who it's for + what changes |
+| Buttons | imperative verb, never "Click here" |
+| Empty states | explain what goes there + how to get something there |
+| Errors | tell the user what to do, not what went wrong technically |
+| Success | one word or one short sentence |
+
+## Adjectives to avoid
+
+- Best, leading, world-class, cutting-edge, revolutionary, seamless, frictionless, robust, scalable.
+
+## Adjectives to consider (if the brief vibe matches)
+
+- Warm / quiet / opinionated / fast / honest / specific / concrete.
+```
+
+### `assets/brand/logo.svg`
+
+Generate a simple SVG mark based on the brief. Constraints:
+
+- 256x256 viewBox.
+- Single color (use the primary from the palette).
+- 2-3 geometric shapes max.
+- Recognizable at 32x32 (favicon).
+- No text in the SVG (wordmark is a separate concern).
+
+If the brief mentions a specific mark concept (e.g. "mountain silhouette + lodge name"), translate it geometrically. Otherwise: a simple monogram of the project's initial in a circle or square.
+
+### `assets/brand/MANIFEST.md`
+
+```markdown
+# Brand kit
+
+Generated by `/generate-brand-kit` on <YYYY-MM-DD> from `docs/brief.json`.
+
+## Files
+
+- `palette.md` — color tokens + CSS export.
+- `typography.md` — type scale + family recommendations.
+- `voice.md` — tone rules + copy patterns.
+- `logo.svg` — single-color geometric mark.
+
+## How to use
+
+1. Copy the CSS export from `palette.md` into your `globals.css` or `tailwind.config.ts`.
+2. Pick one family pair from `typography.md` and apply in `globals.css` or `<body>`.
+3. Read `voice.md` once. Apply to every piece of copy you write.
+4. Use `logo.svg` in `<header>` and as a favicon source.
+
+## Regenerate
+
+`/generate-brand-kit` overwrites this folder. Make manual edits OUTSIDE `assets/brand/` (e.g. in `globals.css`) so regeneration does not stomp them.
+```
+
+## Step 4: report
+
+```
+Brand kit generated: assets/brand/
+  - palette.md
+  - typography.md
+  - voice.md
+  - logo.svg
+  - MANIFEST.md
+
+Apply the CSS export from palette.md to globals.css, then run /update-gui
+to ship the visual change. Verify per CLAUDE.md Part 19.
+```
+
+## Hard rules
+
+- Real hex codes, not placeholders. The agent must commit to specific values derived from the brief.
+- Single color SVG. No multi-color marks v1.
+- No webfonts unless brief explicitly says so.
+- Generated files always land in `assets/brand/`. Operator promotes into the actual app via `/update-gui` or manual copy.
+- Regeneration overwrites; manual edits go elsewhere.

package/templates/.claude/commands/generate-content-pack.md

@@ -0,0 +1,215 @@
+---
+description: Compose page-level copy (homepage hero, CTAs, metadata, OG, JSON-LD) from the operator brief. Writes assets/content/{homepage.md, cta-bank.md, metadata.md, og.md, MANIFEST.md}. Composer-only.
+---
+
+# /generate-content-pack
+
+Turn the brief into ready-to-use page copy. Eliminates the "blank page" problem when the agent starts on the homepage.
+
+## Step 1: read context
+
+```bash
+[ -f docs/brief.md ] && cat docs/brief.md
+[ -f docs/brief.json ] && cat docs/brief.json
+[ -f assets/brand/voice.md ] && cat assets/brand/voice.md
+```
+
+## Step 2: ask at most 1 clarifying question
+
+If the brief leaves the headline tone ambiguous (e.g. vibe says both "credible" and "playful"), ask which leads.
+
+Otherwise skip.
+
+## Step 3: write the 5 files
+
+```bash
+mkdir -p assets/content
+```
+
+### `assets/content/homepage.md`
+
+```markdown
+# Homepage copy
+
+> Source: `docs/brief.md`. Honor `brand.vibe` + `business_model` + `scope.must_have_sections`.
+
+## Hero
+
+**Headline (5-9 words):**
+<derived from project.summary>
+
+**Subhead (one sentence):**
+<who it serves + what they get>
+
+**Primary CTA:** <imperative verb + object>
+
+## Sections (in order)
+
+<for each item in scope.must_have_sections, write a small block:>
+
+### <Section name>
+
+**Heading:** <3-7 words>
+
+**Body (1-2 sentences):**
+<what this section communicates, in the brand voice>
+
+**(if applicable) CTA:** <imperative>
+
+## Footer
+
+**Tagline / closing line:** <one-sentence echo of the headline, from a different angle>
+```
+
+### `assets/content/cta-bank.md`
+
+```markdown
+# CTA bank
+
+Reuse across pages. Pick one per context. Never "Click here."
+
+## Primary actions (convert the visitor)
+
+| Context | CTA |
+|---|---|
+| Hero | <imperative tied to business model> |
+| Mid-page repeat | <same intent, different verb> |
+| Final call | <last-chance phrasing> |
+
+## Secondary actions
+
+| Context | CTA |
+|---|---|
+| Learn more (in feature card) | "See how it works" / "Read the docs" |
+| Email capture | "Get the early access link" / "Join the list" |
+| Contact | "Talk to us" / "Get a quote" |
+
+## What NOT to say
+
+- "Click here"
+- "Learn more" with no context
+- "Submit" (use the action, e.g. "Send message")
+- "Sign up now" (drop "now"; the urgency is implicit)
+```
+
+### `assets/content/metadata.md`
+
+```markdown
+# Page metadata
+
+> All pages should set these via Next.js `metadata` export.
+
+## Site-wide defaults
+
+```ts
+export const metadata: Metadata = {
+  title: { default: '<project name>', template: '%s — <project name>' },
+  description: '<one-sentence project summary from brief.project.summary>',
+  metadataBase: new URL(process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:3000'),
+  openGraph: {
+    title: '<project name>',
+    description: '<one-sentence summary>',
+    type: 'website',
+    images: ['/og.png'],
+  },
+  twitter: {
+    card: 'summary_large_image',
+    title: '<project name>',
+    description: '<one-sentence summary>',
+  },
+  robots: { index: true, follow: true },
+};
+```
+
+## Per-page overrides
+
+- Homepage: keep defaults.
+- Post / detail pages (blog/booking/storefront): override title, description, og.type, published_time.
+- Auth pages (/login, /signup): `robots: { index: false }`.
+- Dashboard (saas-dashboard): `robots: { index: false }`, no OG.
+
+## JSON-LD
+
+| Page | Schema |
+|---|---|
+| Homepage of lead-gen / booking / marketing | `Organization` or `LocalBusiness` |
+| Booking page | `Reservation` if applicable |
+| Blog post | `Article` with `author`, `datePublished`, `image` |
+| SaaS marketing | `SoftwareApplication` |
+| Directory entry | `LocalBusiness` per entry |
+```
+
+### `assets/content/og.md`
+
+```markdown
+# Open Graph image
+
+Spec for a 1200x630 OG image (Twitter card + LinkedIn + iMessage previews).
+
+## Composition
+
+- Solid brand background (use `--color-surface` or `--color-primary`).
+- Wordmark or logo in upper-left at ~80px height.
+- Headline at center: 5-9 words, ~84-96px font size, in the contrasting color.
+- Optional small tag in lower-right: project URL or tagline.
+
+## Variants
+
+- Default: the headline from `homepage.md` hero.
+- Per-post (blog): the post title.
+- Per-listing (directory): listing title + city or category.
+
+## How to ship it
+
+- Static: hand-design once, save to `public/og.png`, reference in `metadata`.
+- Dynamic: use Next.js `opengraph-image.tsx` route convention. ImageResponse from `next/og`.
+- Generated: run `/generate-image og-image` to compose a prompt then either paste it elsewhere or call Vercel AI Gateway via `/generate-image`.
+```
+
+### `assets/content/MANIFEST.md`
+
+```markdown
+# Content pack
+
+Generated by `/generate-content-pack` on <YYYY-MM-DD> from `docs/brief.json`.
+
+## Files
+
+- `homepage.md` — hero + every must-have section, in-voice.
+- `cta-bank.md` — reusable CTA strings, primary + secondary.
+- `metadata.md` — Next.js `metadata` exports + per-page overrides + JSON-LD direction.
+- `og.md` — Open Graph image spec.
+
+## How to use
+
+1. Build the homepage from `homepage.md` (one heading + one body per section).
+2. Use CTAs from `cta-bank.md` consistently across pages.
+3. Drop `metadata.md` examples into `app/layout.tsx` and per-page route files.
+4. Generate or design the OG image per `og.md`.
+
+## Regenerate
+
+`/generate-content-pack` overwrites this folder. Manual copy edits to the live site live in your `app/` code, not here.
+```
+
+## Step 4: report
+
+```
+Content pack generated: assets/content/
+  - homepage.md   (hero + N sections)
+  - cta-bank.md
+  - metadata.md
+  - og.md
+  - MANIFEST.md
+
+Next: copy the homepage hero into app/page.tsx, set metadata in
+app/layout.tsx, and run /update-gui to ship. Verify per CLAUDE.md Part 19.
+```
+
+## Hard rules
+
+- Honor the brief's voice rules (or `assets/brand/voice.md` if present).
+- Headlines: 5-9 words. Never longer.
+- CTAs: imperative + concrete object. Never "Click here." Never "Submit." Never "Sign up now."
+- No invented claims. If the brief does not say it, do not write it.
+- Generated files always land in `assets/content/`. Operator copies into `app/` deliberately.