@oaklandzoo/ostup 0.4.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.4.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

@@ -28,6 +28,11 @@ export const REGISTRY = [
   { src: '.claude/commands/add-storage.md',   dest: '.claude/commands/add-storage.md' },
   { src: '.claude/commands/generate-image-prompt.md', dest: '.claude/commands/generate-image-prompt.md' },
   { src: '.claude/commands/generate-image.md', dest: '.claude/commands/generate-image.md' },
+  { 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' },
@@ -39,6 +44,7 @@ export const REGISTRY = [
   { src: 'tasks/.gitkeep',                     dest: 'tasks/.gitkeep' },
   { src: 'inputs/README.md',                   dest: 'inputs/README.md' },
   { src: 'scripts/screenshot.sh',              dest: 'scripts/screenshot.sh', executable: true },
+  { src: 'scripts/verify.sh',                  dest: 'scripts/verify.sh', executable: true },
 ];
 
 export const OPTIONAL_REGISTRY = [

package/templates/.claude/commands/break-into-stories.md

@@ -0,0 +1,101 @@
+---
+description: Break a PRD into vertical stories (each story is independently shippable) before generating granular tasks. Sits between /create-prd and /generate-tasks. Borrowed pattern from BMAD; kept light.
+---
+
+# /break-into-stories
+
+A PRD is a description. Tasks are atoms. **Stories are the missing middle layer.** A story is a small vertical slice that can be shipped on its own and feels meaningful to the operator on a deployed URL.
+
+Use this command after `/create-prd` and before `/generate-tasks`. It produces `tasks/stories-<feature>.md` with 3-7 stories.
+
+## Step 1: locate the PRD
+
+```bash
+ls tasks/prd-*.md
+```
+
+If the operator named a feature (e.g. `/break-into-stories user-auth`), use `tasks/prd-user-auth.md`.
+
+If no name: ask the operator which PRD.
+
+## Step 2: read the PRD + the brief
+
+```bash
+cat tasks/prd-<feature>.md
+[ -f docs/brief.md ] && head -80 docs/brief.md
+```
+
+## Step 3: derive stories
+
+For each story, fill this shape:
+
+```markdown
+## Story <N>: <one-line goal>
+
+**Why this is a story:** <one sentence on why this is a meaningful vertical slice>
+
+**User journey:** <2-3 sentences describing what the operator or end user does>
+
+**Acceptance:**
+- <observable behavior 1>
+- <observable behavior 2>
+
+**Deployable check:** <one sentence on what you can show on the live URL after this story ships>
+
+**Out of scope for this story:** <bullets of things explicitly NOT in this story; they belong to other stories>
+```
+
+### Rules for cutting stories
+
+1. **Vertical, not horizontal.** A story crosses UI + API + data if needed. It does NOT say "build the API for X" as a story; that is a task.
+2. **Shippable.** Each story can be merged + deployed and produces an observable change on the live URL.
+3. **Small.** 30 minutes to 2 hours of agent work each. If a story feels bigger, split it.
+4. **Independent where possible.** Story 2 should not require Story 1's completion unless there is a hard dependency (then state it).
+5. **Acceptance is observable.** "Visitor can click X and see Y" not "The reducer handles X."
+6. **3 to 7 stories per PRD.** More than 7 means the PRD is too big; less than 3 means you do not need stories, just tasks.
+
+## Step 4: write `tasks/stories-<feature>.md`
+
+```markdown
+# Stories: <feature>
+
+> Source PRD: `tasks/prd-<feature>.md`
+> Generated by `/break-into-stories` on <YYYY-MM-DD>.
+> Each story is independently shippable.
+
+## Story order (recommended)
+
+1. Story 1 — <goal>
+2. Story 2 — <goal>
+3. ...
+
+## Stories
+
+<the N stories from Step 3>
+
+## Dependencies
+
+<if any: "Story 3 depends on Story 1 because ..." else "All stories are independent.">
+
+## Next step
+
+For the first story, run `/generate-tasks` referencing `Story 1` to break it into atoms. Implement, deploy, verify, then move to the next story.
+```
+
+## Step 5: report
+
+```
+Stories generated: tasks/stories-<feature>.md (N stories)
+
+Recommended first story: Story 1 — <goal>
+  Estimated agent work: <30 min | 1 hr | 2 hr>
+
+Next: /generate-tasks for Story 1, then implement.
+```
+
+## Hard rules
+
+- Stories never cross PRDs. One PRD → one stories file.
+- Each story's acceptance criteria must be observable from the live URL after deploy, or via a `curl` probe (for backend stories).
+- If a story has no deployable check, it is not a story; it is a task. Roll it into another story.
+- Mark dependencies explicitly. Do not pretend stories are independent when one needs another's API.

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.

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

@@ -0,0 +1,93 @@
+---
+description: Audit HANDOFF.md against actual repo state. Flags stale claims, missing follow-throughs, and orphan files not mentioned anywhere. Read-only; surfaces a punch list for /prompt-end to fix.
+---
+
+# /handoff-doctor
+
+HANDOFF.md should reflect repo reality. When it does not, agents (including you) make decisions based on lies. This command catches lies before they cause work loss.
+
+## Step 1: probe
+
+```bash
+echo "=== HANDOFF claims ==="
+grep -E "^(\*\*Status:\*\*|\*\*Branch:\*\*|\*\*Working tree:\*\*|\*\*Last session ended:\*\*)" HANDOFF.md | head -8
+
+echo ""
+echo "=== Repo reality ==="
+echo "Branch:       $(git branch --show-current)"
+echo "Last commit:  $(git log -1 --oneline)"
+echo "Ahead of origin: $(git rev-list --count origin/$(git branch --show-current)..HEAD 2>/dev/null || echo 'no upstream')"
+echo "Behind origin:   $(git rev-list --count HEAD..origin/$(git branch --show-current) 2>/dev/null || echo 'no upstream')"
+echo "Working tree:"
+git status --short
+
+echo ""
+echo "=== Files HANDOFF claims were touched ==="
+grep -E "^\s*-\s*\`[^\`]+\`" HANDOFF.md | head -20
+
+echo ""
+echo "=== Files actually changed in last 5 commits ==="
+git log --name-only --oneline -5 | grep -v "^[0-9a-f]\{7\}" | sort -u | head -30
+
+echo ""
+echo "=== Tasks mentioned in HANDOFF ==="
+grep -E "tasks/|prd-|\.md" HANDOFF.md | head -10
+
+echo ""
+echo "=== Tasks actually in tasks/ ==="
+ls tasks/ 2>/dev/null
+
+echo ""
+echo "=== Manual blockers claimed ==="
+[ -f docs/MANUAL_TASKS.md ] && grep -c "^\s*-\s*\[ \]" docs/MANUAL_TASKS.md
+```
+
+## Step 2: diagnose
+
+Audit each of these axes. For each finding, state CLAIM vs ACTUAL.
+
+1. **Branch mismatch.** HANDOFF says branch X, git is on branch Y.
+2. **Push lag.** HANDOFF says "push commit X" but `git log origin/$(git branch --show-current)` already includes X.
+3. **Working tree drift.** HANDOFF says "clean" but `git status` shows N dirty files.
+4. **Last-session timestamp.** HANDOFF "Last session ended" is more than 7 days old. Mark as STALE.
+5. **Orphan tasks.** Files in `tasks/` not referenced by HANDOFF.
+6. **Phantom files.** HANDOFF references files that do not exist (`ls` them to verify).
+7. **Phantom commits.** HANDOFF references SHAs not in `git log`.
+8. **Manual-task drift.** HANDOFF says no blockers but MANUAL_TASKS.md has Active items (or vice versa).
+9. **Brief drift.** docs/brief.md exists but HANDOFF makes no reference to it; or HANDOFF references a brief that does not exist.
+10. **Test-pass lie.** HANDOFF says "N/N tests green" — run `npm test` (or similar) and compare.
+
+## Step 3: print findings
+
+```
+HANDOFF DOCTOR REPORT
+
+Overall: <CLEAN | NEEDS REWRITE | CRITICAL>
+
+Findings:
+
+[CRITICAL]   <description>      Fix: <what to do>
+[STALE]      <description>      Fix: <what to do>
+[ORPHAN]     <description>      Fix: <what to do>
+[PHANTOM]    <description>      Fix: <what to do>
+[CLEAN]      No issues on this axis: <axis name>
+
+Recommended actions:
+  1. <action>
+  2. <action>
+
+Run /prompt-end to rewrite HANDOFF.md with current reality.
+```
+
+## Hard rules
+
+- Read-only. Never modify HANDOFF.md from this command. `/prompt-end` is the writer.
+- Be specific in findings. "HANDOFF says push 9a4708f but it is already at origin/main" is useful. "HANDOFF is wrong" is not.
+- If a finding is borderline (e.g. timestamp 6 days old, threshold is 7), mark it CLEAN with a note rather than STALE.
+- If everything passes, say so. Do not invent issues.
+
+## When to run
+
+- Before `/prompt-start` if you suspect HANDOFF is wrong.
+- After a long AFK session before a new agent picks up.
+- Any time HANDOFF claims something that does not match what you just saw in git.

package/templates/.claude/commands/resume.md

@@ -0,0 +1,102 @@
+---
+description: Resume an in-progress session by reading git diff, HANDOFF, tasks, and the brief if present. Briefs the agent on actual current state vs claimed state. Use instead of /prompt-start when you suspect HANDOFF.md is stale.
+---
+
+# /resume
+
+`/prompt-start` reads HANDOFF and trusts it. `/resume` reads HANDOFF and **verifies it against git reality**. Use when:
+
+- You stopped mid-feature and HANDOFF was not rewritten.
+- You came back after several days and are not sure HANDOFF is current.
+- A teammate worked in this repo while you were away.
+- Something feels off about the briefing.
+
+## Step 1: collect ground truth
+
+Run all of these in one bash block:
+
+```bash
+echo "=== Git reality ==="
+git status --short
+git log --oneline -10
+git diff --stat HEAD~5..HEAD 2>/dev/null || git diff --stat
+
+echo ""
+echo "=== HANDOFF.md (claimed state) ==="
+[ -f HANDOFF.md ] && head -60 HANDOFF.md || echo "no HANDOFF.md"
+
+echo ""
+echo "=== Active tasks / PRDs ==="
+ls tasks/ 2>/dev/null
+[ -f tasks/prd-initial-build.md ] && head -30 tasks/prd-initial-build.md
+
+echo ""
+echo "=== Brief (if present) ==="
+[ -f docs/brief.md ] && head -40 docs/brief.md || echo "no brief"
+
+echo ""
+echo "=== Manual blockers ==="
+[ -f docs/MANUAL_TASKS.md ] && grep -A 2 "## Active" docs/MANUAL_TASKS.md | head -20
+```
+
+## Step 2: compare claimed vs actual
+
+Build a diff in your head between:
+
+| Source | Status they show |
+|---|---|
+| HANDOFF.md "What to do next" | What the last session said is queued |
+| `git log` | What actually got committed |
+| `git status` | What is in-flight and uncommitted |
+| `tasks/` PRDs and PRD-seeds | What features are scoped |
+| `docs/brief.md` (if any) | What the project is supposed to be |
+
+Flag every mismatch. Examples of mismatches:
+
+- HANDOFF says "push commit X" but `git log` shows X is already pushed (HANDOFF is stale; rewrite at session close).
+- HANDOFF lists a "next action" but uncommitted work in `git status` shows that action was started and abandoned.
+- `tasks/prd-foo.md` exists but is not mentioned in HANDOFF (forgotten artifact).
+- Brief says profile is `booking` but the codebase has no booking-related files.
+
+## Step 3: print the resume brief
+
+```
+RESUMED
+
+Last commit:     <SHA + subject>
+Working tree:    <clean | N dirty files: list>
+HANDOFF claim:   <one-line status>
+Git reality:    <does it match? if not, what's the gap?>
+
+In-flight (uncommitted) work:
+  <git status summary>
+
+What the brief expects (if brief exists):
+  <profile + add-ons + must-have sections> 
+
+Queued from HANDOFF:
+  1. <action>
+  2. <action>
+
+Mismatches surfaced:
+  - <mismatch 1, or "none">
+  - <mismatch 2>
+
+Recommended next move:
+  <pick one: continue queued action / resolve mismatch / pivot>
+```
+
+## Step 4: ask before doing
+
+```
+Continue with the recommended next move? Or pivot?
+```
+
+Wait for confirmation. Do NOT modify any files until the operator picks.
+
+## Hard rules
+
+- Never silently rewrite HANDOFF to match git. Surface the mismatch; let the operator decide.
+- Never silently amend or rebase to "fix" git history.
+- If `git status` shows uncommitted changes that the operator might not remember making, ask before doing anything that could lose them.
+- This command is read-only by default. The only writes are after the operator confirms the next move.

package/templates/AGENTS.md

@@ -27,9 +27,9 @@ Operator materials live in `{{INPUTS_PATH}}`. Read `{{INPUTS_PATH}}README.md` fo
 
 ## Slash commands available
 
-Session lifecycle: `/bootstrap`, `/prompt-start`, `/prompt-mid`, `/prompt-end`, `/preflight`
+Session lifecycle: `/bootstrap`, `/prompt-start`, `/prompt-mid`, `/prompt-end`, `/preflight`, `/resume`, `/handoff-doctor`
 
-Building: `/create-prd`, `/generate-tasks`, `/update-image`, `/update-gui`, `/update-backend`, `/add-storage`, `/generate-image-prompt`, `/generate-image`
+Building: `/create-prd`, `/break-into-stories`, `/generate-tasks`, `/update-image`, `/update-gui`, `/update-backend`, `/add-storage`, `/generate-image-prompt`, `/generate-image`
 
 See each file under `.claude/commands/` for the full routine.
 
@@ -42,6 +42,7 @@ See each file under `.claude/commands/` for the full routine.
 ## Helpers
 
 - `scripts/screenshot.sh <url> [out] [WxH]` — headless Chrome screenshot. Required for visual verification per `CLAUDE.md` Part 19.
+- `scripts/verify.sh [profile] [deploy_url]` — profile-aware verification gate. Auto-detects profile from `docs/brief.json` and deploy URL from `.vercel/project.json`. Runs common checks (build, env, live URL) plus profile-specific checks (e.g. `/api/contact` for lead-gen, `/rss.xml` for blog).
 
 ## If `docs/brief.md` is present in this project
 

package/templates/START_HERE.md

@@ -63,6 +63,9 @@ Type these in your CLI agent. Each runs a structured routine.
 | `/add-storage` | Provision a Vercel Blob, KV, Postgres, or Edge Config store + scaffold a typed `src/lib/<type>.ts` helper + pull env vars. | When you need persistent storage. |
 | `/generate-image-prompt` | Compose an image-generation prompt from the project brief + 2-3 questions. No API call. Paste the prompt into your preferred image tool. | When you need a visual asset and want to use Midjourney, DALL-E, Imagen, etc. directly. |
 | `/generate-image` | Compose the prompt AND call Vercel AI Gateway, saving the image to `inputs/images/`. Requires `VERCEL_AI_GATEWAY_KEY`. | When you want the image generated in-line without leaving your agent. |
+| `/resume` | Read git diff + HANDOFF + tasks + brief, surface mismatches between claimed and actual state. | When HANDOFF.md feels stale, you came back after several days, or something feels off about the briefing. |
+| `/handoff-doctor` | Audit HANDOFF.md against actual repo reality (commits, working tree, files, tasks, manual blockers). Read-only punch list. | Before `/prompt-start` if you suspect HANDOFF is wrong; after a long AFK session. |
+| `/break-into-stories` | Break a PRD into 3-7 vertical, shippable stories before generating granular tasks. | Between `/create-prd` and `/generate-tasks` for any non-trivial feature. |
 
 ## Three workflows
 

package/templates/scripts/verify.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# Profile-aware verification gate. Runs the right checks for the project's profile.
+# Called after /update-image, /update-gui, /update-backend, or at any time the operator wants to verify.
+#
+# Usage:   scripts/verify.sh [profile] [deploy_url]
+# Reads:   docs/brief.json (for profile) if no profile arg
+# Defaults: profile=marketing, deploy_url from .vercel/project.json if available
+
+set -e
+
+PROFILE="${1:-}"
+DEPLOY_URL="${2:-}"
+
+# Auto-detect profile from brief.json if not given
+if [ -z "$PROFILE" ] && [ -f docs/brief.json ]; then
+  PROFILE=$(python3 -c "import json; print(json.load(open('docs/brief.json'))['scaffold']['profile'])" 2>/dev/null || echo "marketing")
+fi
+PROFILE="${PROFILE:-marketing}"
+
+# Auto-detect deploy URL if not given (best-effort; operator may need to pass it)
+if [ -z "$DEPLOY_URL" ]; then
+  if [ -f .vercel/project.json ]; then
+    PROJECT_NAME=$(python3 -c "import json; print(json.load(open('.vercel/project.json'))['projectName'])" 2>/dev/null || echo "")
+    if [ -n "$PROJECT_NAME" ]; then
+      DEPLOY_URL="https://${PROJECT_NAME}.vercel.app"
+    fi
+  fi
+fi
+
+echo "=========================================="
+echo "  Verifying profile: $PROFILE"
+echo "  Deploy URL: ${DEPLOY_URL:-<not detected; pass as arg 2>}"
+echo "=========================================="
+
+PASS=0
+FAIL=0
+
+check() {
+  local desc="$1"
+  local cmd="$2"
+  echo -n "  [$PROFILE] $desc ... "
+  if eval "$cmd" > /tmp/verify-out 2>&1; then
+    echo "PASS"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL"
+    echo "    Output: $(head -3 /tmp/verify-out)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# === Common checks (all profiles) ===
+echo ""
+echo "--- common ---"
+check "build succeeds" "npm run build"
+check ".env.example exists" "[ -f .env.example ]"
+check "no {{TOKEN}} placeholders in CLAUDE.md" "! grep -E '\\{\\{[A-Z_]+\\}\\}' CLAUDE.md || true"
+
+if [ -n "$DEPLOY_URL" ]; then
+  check "live URL returns 200" "curl -sI '$DEPLOY_URL' | head -1 | grep -E '200|301|302'"
+fi
+
+# === Profile-specific checks ===
+case "$PROFILE" in
+  lead-gen)
+    echo ""
+    echo "--- lead-gen ---"
+    check "/api/contact route exists" "[ -f src/app/api/contact/route.ts ] || [ -f src/app/api/contact/route.js ] || [ -f app/api/contact/route.ts ]"
+    check "JSON-LD LocalBusiness in HTML" "grep -r 'LocalBusiness' src/ 2>/dev/null"
+    if [ -n "$DEPLOY_URL" ]; then
+      check "POST /api/contact returns 200 or 400" "curl -s -X POST '$DEPLOY_URL/api/contact' -H 'Content-Type: application/json' -d '{\"name\":\"verify\",\"email\":\"verify@example.com\",\"message\":\"verify\"}' -o /dev/null -w '%{http_code}' | grep -E '^(200|400)$'"
+    fi
+    ;;
+  booking)
+    echo ""
+    echo "--- booking ---"
+    check "booking API route exists" "find src/app/api/booking -type f 2>/dev/null | head -1 | grep -q ."
+    check "DATABASE_URL referenced in code or env" "grep -r 'DATABASE_URL' src/ .env.example 2>/dev/null | head -1"
+    ;;
+  saas-dashboard)
+    echo ""
+    echo "--- saas-dashboard ---"
+    check "auth middleware exists" "[ -f src/middleware.ts ] || [ -f src/middleware.js ] || [ -f middleware.ts ]"
+    check "/login or /signup page exists" "find src/app -type d \\( -name 'login' -o -name 'signup' -o -name 'auth' \\) 2>/dev/null | head -1 | grep -q ."
+    check "/dashboard page exists" "find src/app -type d -name 'dashboard' 2>/dev/null | head -1 | grep -q ."
+    if [ -n "$DEPLOY_URL" ]; then
+      check "/dashboard redirects unauthenticated" "curl -s -o /dev/null -w '%{http_code}' '$DEPLOY_URL/dashboard' | grep -E '^(301|302|307|401)$'"
+    fi
+    ;;
+  blog)
+    echo ""
+    echo "--- blog ---"
+    check "content/posts/ exists" "[ -d content/posts ] || [ -d src/content/posts ]"
+    check "mdx package installed" "grep -q '@next/mdx\\|next-mdx-remote\\|@mdx-js' package.json 2>/dev/null"
+    if [ -n "$DEPLOY_URL" ]; then
+      check "/rss.xml returns 200" "curl -sI '$DEPLOY_URL/rss.xml' | head -1 | grep -q 200"
+      check "/sitemap.xml returns 200" "curl -sI '$DEPLOY_URL/sitemap.xml' | head -1 | grep -q 200"
+    fi
+    ;;
+  marketing|*)
+    echo ""
+    echo "--- marketing baseline ---"
+    if [ -n "$DEPLOY_URL" ]; then
+      check "homepage has hero text" "curl -s '$DEPLOY_URL' | grep -iE '<h1' | head -1 | grep -q ."
+    fi
+    ;;
+esac
+
+# === Visual verification reminder ===
+echo ""
+echo "--- visual (per CLAUDE.md Part 19) ---"
+if [ -n "$DEPLOY_URL" ] && [ -x "scripts/screenshot.sh" ]; then
+  scripts/screenshot.sh "$DEPLOY_URL" /tmp/verify-screenshot.png 420,900 > /dev/null && \
+    echo "  Screenshot: /tmp/verify-screenshot.png (READ it to complete Part 19 verification)"
+else
+  echo "  Skipped (no deploy URL or no scripts/screenshot.sh)"
+fi
+
+# === Summary ===
+echo ""
+echo "=========================================="
+echo "  Verify summary: PASS=$PASS FAIL=$FAIL"
+echo "=========================================="
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi
+exit 0