@oaklandzoo/ostup 0.3.0 → 0.4.0

package/src/brief/sample-briefs.mjs

@@ -0,0 +1,304 @@
+// brief/sample-briefs.mjs: fixture briefs used by tests + dry-run flows. One per profile.
+
+import { SCHEMA_VERSION } from './schema.mjs';
+
+export const BOOKING_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'lodge-booking',
+    display_name: 'Lodge Booking',
+    summary: 'A booking site for a boutique ski lodge with deposits, calendar sync, and a guest dashboard.',
+    owner_or_client: 'Hakuba Lodge LLC',
+  },
+  classification: {
+    site_profile: 'booking',
+    confidence: 0.94,
+    why: ['Booking + deposit explicit', 'Calendar/availability is a core flow', 'Guest dashboard implied'],
+    secondary_profiles: ['saas-dashboard'],
+  },
+  audience: { primary: 'small_business', buyer: 'Lodge owner', end_users: ['Travel guests', 'Lodge admins'] },
+  business_model: {
+    types: ['booking_revenue', 'deposit'],
+    pricing_notes: '$200-600/night peak; 30% deposit at booking',
+  },
+  scope: {
+    must_have_sections: ['hero', 'availability calendar', 'rooms', 'amenities', 'about', 'contact'],
+    core_flows: ['booking', 'payment', 'contact_form'],
+    non_goals: ['Channel manager integration v1', 'Multi-property support v1'],
+  },
+  data_model: {
+    needs_storage: true,
+    entities: [
+      { name: 'Booking', fields: ['date_start', 'date_end', 'guest_name', 'status', 'deposit_status'], source: 'intake' },
+      { name: 'Room', fields: ['name', 'capacity', 'nightly_rate'], source: 'intake' },
+    ],
+    recommended_storage: ['postgres', 'blob'],
+  },
+  brand: {
+    vibe: ['warm', 'rustic', 'premium'],
+    inspiration_urls: [],
+    color_notes: 'Espresso, sand, walnut. Earthy.',
+    font_notes: 'Serif header + clean sans body.',
+    logo_notes: 'Mountain silhouette + lodge name.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: {
+    deadline: 'mvp_7_days',
+    budget_posture: 'under_50_month',
+    must_use: ['Stripe'],
+    must_avoid: [],
+  },
+  scaffold: {
+    base: 'next',
+    profile: 'booking',
+    addons: ['postgres', 'email', 'payments'],
+    template_paths: ['templates/base', 'templates/profiles/booking'],
+  },
+  verification: {
+    acceptance_tests: [
+      'Visitor can request dates for a room',
+      'Admin receives booking-request email',
+      'Deposit checkout can be initiated',
+    ],
+    visual_checks: ['Hero readable on mobile', 'Calendar mobile-friendly'],
+    deploy_checks: ['Live URL returns 200', 'OG image renders'],
+  },
+};
+
+export const SAAS_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'tasktrace',
+    display_name: 'TaskTrace',
+    summary: 'A SaaS dashboard for solo founders to trace AI agent actions across their codebases.',
+    owner_or_client: 'GG Solo',
+  },
+  classification: {
+    site_profile: 'saas-dashboard',
+    confidence: 0.92,
+    why: ['Subscription billing planned', 'Auth + dashboard required', 'Multi-tenant data implied'],
+    secondary_profiles: ['marketing'],
+  },
+  audience: { primary: 'founder', buyer: 'Solo dev', end_users: ['Solo developers', 'Small teams'] },
+  business_model: {
+    types: ['subscription', 'dashboard'],
+    pricing_notes: '$19/mo solo, $49/mo team',
+  },
+  scope: {
+    must_have_sections: ['landing hero', 'pricing', 'login', 'dashboard shell', 'settings', 'billing'],
+    core_flows: ['auth', 'payment', 'dashboard', 'contact_form'],
+    non_goals: ['Custom roles v1', 'SSO v1'],
+  },
+  data_model: {
+    needs_storage: true,
+    entities: [
+      { name: 'User', fields: ['email', 'name', 'created_at', 'plan'], source: 'intake' },
+      { name: 'Trace', fields: ['user_id', 'repo', 'agent', 'action', 'timestamp'], source: 'intake' },
+    ],
+    recommended_storage: ['postgres'],
+  },
+  brand: {
+    vibe: ['credible', 'fast', 'minimal'],
+    inspiration_urls: ['https://linear.app', 'https://vercel.com'],
+    color_notes: 'Dark mode default. Neutral grays + one accent.',
+    font_notes: 'Geist or system sans.',
+    logo_notes: 'Geometric mark.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: {
+    deadline: 'production_2_4_weeks',
+    budget_posture: 'under_50_month',
+    must_use: ['Stripe', 'Neon'],
+    must_avoid: [],
+  },
+  scaffold: {
+    base: 'next',
+    profile: 'saas-dashboard',
+    addons: ['auth', 'payments', 'postgres'],
+    template_paths: ['templates/base', 'templates/profiles/saas-dashboard'],
+  },
+  verification: {
+    acceptance_tests: [
+      'User can sign up and log in',
+      'Stripe subscription can be initiated',
+      'Authenticated user sees the dashboard shell',
+    ],
+    visual_checks: ['Dashboard readable on mobile', 'Login page focused on the form'],
+    deploy_checks: ['Live URL returns 200 unauthenticated landing', 'Auth flow round-trips'],
+  },
+};
+
+export const BLOG_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'goodshin-notes',
+    display_name: 'Goodshin Notes',
+    summary: 'A content engine for technical essays and case studies, MDX-based, SEO-first, with RSS and sitemap.',
+    owner_or_client: 'GG',
+  },
+  classification: {
+    site_profile: 'blog',
+    confidence: 0.93,
+    why: ['Content engine explicit', 'MDX requested', 'SEO + RSS are core flows'],
+    secondary_profiles: ['portfolio'],
+  },
+  audience: { primary: 'creator', buyer: 'GG', end_users: ['Engineers', 'Indie hackers', 'Designers'] },
+  business_model: {
+    types: ['content_traffic', 'brand_awareness'],
+    pricing_notes: 'No revenue v1; lead-gen for consulting',
+  },
+  scope: {
+    must_have_sections: ['homepage with latest 6', 'individual post page', 'tag index', 'about', 'rss', 'sitemap'],
+    core_flows: ['content_crud', 'newsletter'],
+    non_goals: ['Member-gated posts v1', 'Comments v1'],
+  },
+  data_model: {
+    needs_storage: false,
+    entities: [{ name: 'Post', fields: ['title', 'slug', 'date', 'tags', 'body_mdx'], source: 'intake' }],
+    recommended_storage: [],
+  },
+  brand: {
+    vibe: ['quiet', 'opinionated', 'craft'],
+    inspiration_urls: ['https://overreacted.io', 'https://jvns.ca'],
+    color_notes: 'Off-white background, dark text, restrained accent.',
+    font_notes: 'Serif headers, mono code, sans body.',
+    logo_notes: 'Wordmark only.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: {
+    deadline: 'mvp_7_days',
+    budget_posture: 'free_tier_first',
+    must_use: [],
+    must_avoid: ['JS-heavy content tools', 'analytics that track readers'],
+  },
+  scaffold: {
+    base: 'next',
+    profile: 'blog',
+    addons: ['mdx'],
+    template_paths: ['templates/base', 'templates/profiles/blog'],
+  },
+  verification: {
+    acceptance_tests: [
+      'Visitor can read a post',
+      'RSS feed validates',
+      'Sitemap includes every post',
+    ],
+    visual_checks: ['Post body has comfortable line length', 'Code blocks readable on mobile'],
+    deploy_checks: ['Live URL returns 200', '/rss.xml returns valid XML'],
+  },
+};
+
+export const LEAD_GEN_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'palm-roofing',
+    display_name: 'Palm Roofing Co.',
+    summary: 'A lead-gen site for a roofing company that captures contact requests and routes them to the owner by email.',
+    owner_or_client: 'Palm Roofing Co.',
+  },
+  classification: {
+    site_profile: 'lead-gen',
+    confidence: 0.95,
+    why: ['Service company explicit', 'Contact-request flow is the primary action', 'No ecommerce signals'],
+    secondary_profiles: ['marketing'],
+  },
+  audience: { primary: 'small_business', buyer: 'Roofing co. owner', end_users: ['Homeowners with roof issues'] },
+  business_model: {
+    types: ['lead_capture', 'brand_awareness'],
+    pricing_notes: 'Free quotes; revenue is offline at job acceptance',
+  },
+  scope: {
+    must_have_sections: ['hero', 'services', 'service area', 'testimonials', 'faq', 'contact form'],
+    core_flows: ['contact_form'],
+    non_goals: ['Online payments v1', 'Customer portal v1'],
+  },
+  data_model: {
+    needs_storage: false,
+    entities: [{ name: 'Lead', fields: ['name', 'email', 'phone', 'address', 'message', 'created_at'], source: 'intake' }],
+    recommended_storage: [],
+  },
+  brand: {
+    vibe: ['trustworthy', 'local', 'no-nonsense'],
+    inspiration_urls: [],
+    color_notes: 'Navy and white. Accent orange for CTAs.',
+    font_notes: 'Bold sans for headlines.',
+    logo_notes: 'Wordmark with palm icon.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: {
+    deadline: 'mvp_7_days',
+    budget_posture: 'free_tier_first',
+    must_use: ['Resend'],
+    must_avoid: [],
+  },
+  scaffold: {
+    base: 'next',
+    profile: 'lead-gen',
+    addons: ['email'],
+    template_paths: ['templates/base', 'templates/profiles/lead-gen'],
+  },
+  verification: {
+    acceptance_tests: [
+      'Visitor can submit the contact form',
+      'Owner receives the lead by email',
+      'JSON-LD LocalBusiness schema renders',
+    ],
+    visual_checks: ['Hero CTA above the fold on mobile', 'Service area map placeholder or text present'],
+    deploy_checks: ['Live URL returns 200', '/contact form posts to /api/contact'],
+  },
+};
+
+export const MARKETING_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'launch-soon',
+    display_name: 'Launch Soon',
+    summary: 'A single-page marketing site that announces a product, captures interest emails, and links to the GitHub repo.',
+    owner_or_client: 'GG',
+  },
+  classification: {
+    site_profile: 'marketing',
+    confidence: 0.85,
+    why: ['No data persistence beyond email list', 'Single primary CTA', 'No transaction flow'],
+    secondary_profiles: ['lead-gen'],
+  },
+  audience: { primary: 'founder', buyer: 'GG', end_users: ['Early-interest visitors'] },
+  business_model: { types: ['brand_awareness'], pricing_notes: 'Free; pre-launch' },
+  scope: {
+    must_have_sections: ['hero', 'features', 'pricing', 'email signup', 'footer'],
+    core_flows: ['newsletter'],
+    non_goals: ['Multi-page v1', 'Blog v1'],
+  },
+  data_model: { needs_storage: false, entities: [], recommended_storage: [] },
+  brand: {
+    vibe: ['bold', 'clear', 'modern'],
+    inspiration_urls: [],
+    color_notes: 'High contrast.',
+    font_notes: 'System sans, large hero.',
+    logo_notes: 'Wordmark.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: { deadline: 'demo_today', budget_posture: 'free_tier_first', must_use: [], must_avoid: [] },
+  scaffold: {
+    base: 'next',
+    profile: 'marketing',
+    addons: [],
+    template_paths: ['templates/base', 'templates/profiles/marketing'],
+  },
+  verification: {
+    acceptance_tests: ['Visitor can submit email', 'Hero is readable on mobile'],
+    visual_checks: ['Hero readable at 420x900'],
+    deploy_checks: ['Live URL returns 200'],
+  },
+};
+
+// Alias export so that profile-name-derived lookups work consistently.
+export const SAAS_DASHBOARD_BRIEF = SAAS_BRIEF;
+
+export const SAMPLE_BRIEFS = {
+  marketing: MARKETING_BRIEF,
+  'lead-gen': LEAD_GEN_BRIEF,
+  booking: BOOKING_BRIEF,
+  blog: BLOG_BRIEF,
+  'saas-dashboard': SAAS_BRIEF,
+};

package/src/brief/schema.mjs

@@ -0,0 +1,176 @@
+// brief/schema.mjs: shape of brief.json + validation. Schema version 1.0.0.
+
+export const SCHEMA_VERSION = '1.0.0';
+
+export const PROFILES = ['marketing', 'lead-gen', 'booking', 'blog', 'storefront', 'saas-dashboard', 'directory', 'portfolio'];
+
+export const ADDONS = ['auth', 'payments', 'email', 'postgres', 'mdx', 'blob', 'analytics'];
+
+export const AUDIENCES = ['small_business', 'founder', 'agency', 'creator', 'community', 'other'];
+
+export const BUSINESS_MODELS = [
+  'lead_capture',
+  'booking_revenue',
+  'deposit',
+  'subscription',
+  'one_time_sale',
+  'content_traffic',
+  'dashboard',
+  'operations',
+  'brand_awareness',
+];
+
+export const CORE_FLOWS = [
+  'contact_form',
+  'booking',
+  'payment',
+  'auth',
+  'dashboard',
+  'content_crud',
+  'search_filter',
+  'newsletter',
+  'file_upload_download',
+  'other',
+];
+
+export const DATA_KINDS = [
+  'none',
+  'leads',
+  'bookings',
+  'products_orders',
+  'users_accounts',
+  'content',
+  'listings',
+  'files',
+  'unsure',
+];
+
+export const DEADLINES = ['demo_today', 'mvp_7_days', 'production_2_4_weeks', 'none'];
+
+export const BUDGET_POSTURES = ['free_tier_first', 'under_50_month', 'under_250_month', 'paid_ok'];
+
+const STRING = (v) => typeof v === 'string';
+const NONEMPTY = (v) => STRING(v) && v.trim().length > 0;
+const ARRAY_OF = (pred) => (v) => Array.isArray(v) && v.every(pred);
+
+export function validateBrief(brief) {
+  const errors = [];
+  if (!brief || typeof brief !== 'object') {
+    return { ok: false, errors: ['brief must be an object'] };
+  }
+
+  if (brief.schema_version !== SCHEMA_VERSION) {
+    errors.push(`schema_version must be ${SCHEMA_VERSION}, got ${brief.schema_version}`);
+  }
+
+  const p = brief.project;
+  if (!p || typeof p !== 'object') {
+    errors.push('project missing');
+  } else {
+    if (!NONEMPTY(p.name)) errors.push('project.name required');
+    if (!NONEMPTY(p.summary)) errors.push('project.summary required');
+    if (p.summary && (p.summary.length < 20 || p.summary.length > 240)) {
+      errors.push('project.summary must be 20-240 chars');
+    }
+  }
+
+  const c = brief.classification;
+  if (!c || typeof c !== 'object') {
+    errors.push('classification missing');
+  } else {
+    if (!PROFILES.includes(c.site_profile)) {
+      errors.push(`classification.site_profile must be one of: ${PROFILES.join(', ')}`);
+    }
+    if (typeof c.confidence !== 'number' || c.confidence < 0 || c.confidence > 1) {
+      errors.push('classification.confidence must be number 0-1');
+    }
+    if (!ARRAY_OF(NONEMPTY)(c.why)) {
+      errors.push('classification.why must be array of non-empty strings');
+    }
+  }
+
+  const a = brief.audience;
+  if (!a || typeof a !== 'object') {
+    errors.push('audience missing');
+  } else {
+    if (!AUDIENCES.includes(a.primary)) {
+      errors.push(`audience.primary must be one of: ${AUDIENCES.join(', ')}`);
+    }
+  }
+
+  const bm = brief.business_model;
+  if (!bm || typeof bm !== 'object') {
+    errors.push('business_model missing');
+  } else if (!Array.isArray(bm.types) || !bm.types.every((t) => BUSINESS_MODELS.includes(t))) {
+    errors.push(`business_model.types must be array of values from: ${BUSINESS_MODELS.join(', ')}`);
+  }
+
+  const scope = brief.scope;
+  if (!scope || typeof scope !== 'object') {
+    errors.push('scope missing');
+  } else {
+    if (!ARRAY_OF(NONEMPTY)(scope.must_have_sections) || scope.must_have_sections.length === 0) {
+      errors.push('scope.must_have_sections must be non-empty array');
+    }
+    if (!ARRAY_OF(NONEMPTY)(scope.core_flows) || scope.core_flows.length === 0) {
+      errors.push('scope.core_flows must be non-empty array');
+    }
+  }
+
+  const dm = brief.data_model;
+  if (!dm || typeof dm !== 'object') {
+    errors.push('data_model missing');
+  } else if (typeof dm.needs_storage !== 'boolean') {
+    errors.push('data_model.needs_storage must be boolean');
+  }
+
+  const brand = brief.brand;
+  if (!brand || typeof brand !== 'object') {
+    errors.push('brand missing');
+  } else if (!ARRAY_OF(NONEMPTY)(brand.vibe)) {
+    errors.push('brand.vibe must be array of strings');
+  }
+
+  const constraints = brief.constraints;
+  if (!constraints || typeof constraints !== 'object') {
+    errors.push('constraints missing');
+  } else {
+    if (!DEADLINES.includes(constraints.deadline)) {
+      errors.push(`constraints.deadline must be one of: ${DEADLINES.join(', ')}`);
+    }
+    if (!BUDGET_POSTURES.includes(constraints.budget_posture)) {
+      errors.push(`constraints.budget_posture must be one of: ${BUDGET_POSTURES.join(', ')}`);
+    }
+  }
+
+  const sc = brief.scaffold;
+  if (!sc || typeof sc !== 'object') {
+    errors.push('scaffold missing');
+  } else {
+    if (!PROFILES.includes(sc.profile)) {
+      errors.push(`scaffold.profile must be one of: ${PROFILES.join(', ')}`);
+    }
+    if (!Array.isArray(sc.addons) || !sc.addons.every((a) => ADDONS.includes(a))) {
+      errors.push(`scaffold.addons must be array of values from: ${ADDONS.join(', ')}`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function emptyBrief() {
+  return {
+    schema_version: SCHEMA_VERSION,
+    project: { name: '', display_name: '', summary: '', owner_or_client: '' },
+    classification: { site_profile: 'marketing', confidence: 0, why: [], secondary_profiles: [] },
+    audience: { primary: 'small_business', buyer: '', end_users: [] },
+    business_model: { types: [], pricing_notes: '' },
+    scope: { must_have_sections: [], core_flows: [], non_goals: [] },
+    data_model: { needs_storage: false, entities: [], recommended_storage: [] },
+    brand: { vibe: [], inspiration_urls: [], color_notes: '', font_notes: '', logo_notes: '' },
+    inputs: { ingested: false, source_path: null, manifest_path: null },
+    constraints: { deadline: 'mvp_7_days', budget_posture: 'free_tier_first', must_use: [], must_avoid: [] },
+    scaffold: { base: 'next', profile: 'marketing', addons: [], template_paths: ['templates/base'] },
+    verification: { acceptance_tests: [], visual_checks: [], deploy_checks: [] },
+  };
+}

package/src/mvp-flow.mjs

@@ -17,6 +17,8 @@ import { renderSummary } from './summary.mjs';
 import { substitute, buildTokenMap } from './substitute.mjs';
 import { REGISTRY, OPTIONAL_REGISTRY } from './templates.mjs';
 import { run as exec, isDryRun } from './exec.mjs';
+import { loadBrief, writeBriefFiles } from './brief/index.mjs';
+import { applyProfileOverlay } from './brief/profile-router.mjs';
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const TEMPLATES_ROOT = resolve(PKG_ROOT, 'templates');
@@ -33,7 +35,23 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
 
   preflightOrExit();
 
-  const answers = await runProjectPrompts({ flags });
+  let brief = null;
+  if (flags.brief) {
+    brief = await loadBrief(flags.brief);
+    process.stdout.write(`Loaded brief from ${resolve(flags.brief)}\n`);
+    process.stdout.write(`  Profile: ${brief.classification.site_profile} (confidence ${brief.classification.confidence})\n`);
+    process.stdout.write(`  Add-ons: ${(brief.scaffold.addons || []).join(', ') || '(none)'}\n`);
+  }
+
+  const promptFlags = brief
+    ? {
+        ...flags,
+        name: flags.name || brief.project.name,
+        profile: flags.profile || 'goodshin',
+      }
+    : flags;
+
+  const answers = await runProjectPrompts({ flags: promptFlags });
   if (!answers || answers.cancelled) {
     process.stdout.write('Cancelled.\n');
     const err = new Error('user cancelled prompts');
@@ -41,6 +59,14 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
     throw err;
   }
 
+  if (brief) {
+    answers.displayName = brief.project.display_name || answers.displayName;
+    answers.description = brief.project.summary || answers.description;
+    if (brief.inputs?.source_path && !answers.ingestPath) {
+      answers.ingestPath = brief.inputs.source_path;
+    }
+  }
+
   printAnswersSummary(answers);
   if (!flags.yes) {
     const proceed = await confirmProceed();
@@ -76,6 +102,22 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
   });
 
   await overlayKit({ targetDir, tokens });
+  if (brief) {
+    await writeBriefFiles({ targetDir, brief, force: true });
+    const overlay = await applyProfileOverlay({
+      targetDir,
+      profile: brief.scaffold.profile,
+      tokens,
+      dryRun: isDryRun(),
+    });
+    if (overlay.applied) {
+      process.stdout.write(`[brief] applied profile overlay '${brief.scaffold.profile}': ${overlay.files.length} file(s)\n`);
+    } else if (isDryRun()) {
+      process.stdout.write(`[brief] would apply profile overlay '${brief.scaffold.profile}': ${overlay.files.length} file(s)\n`);
+    } else {
+      process.stdout.write(`[brief] profile overlay '${brief.scaffold.profile}': ${overlay.reason}\n`);
+    }
+  }
   await writeProjectEnvFiles({ targetDir, collected: creds.collected });
   await ensureGitignoreEnv({ targetDir });
 

package/templates/AGENTS.md

@@ -33,6 +33,16 @@ Building: `/create-prd`, `/generate-tasks`, `/update-image`, `/update-gui`, `/up
 
 See each file under `.claude/commands/` for the full routine.
 
+## ostup CLI subcommands (run outside Claude Code)
+
+- `ostup brief` — 10-question operator intake; writes `docs/brief.md`, `docs/brief.json`, `tasks/prd-initial-build.md`.
+- `ostup init --brief <path>` — scaffold using an existing brief.json; applies the matching profile overlay.
+- `ostup init` — interactive scaffold without brief.
+
 ## Helpers
 
 - `scripts/screenshot.sh <url> [out] [WxH]` — headless Chrome screenshot. Required for visual verification per `CLAUDE.md` Part 19.
+
+## If `docs/brief.md` is present in this project
+
+Treat it as authoritative for scope, profile, brand, business model, and constraints. Downstream commands (`/create-prd`, `/generate-tasks`, etc.) should read `docs/brief.json` first to avoid re-asking the operator the same questions. Profile-specific guidance lives at `templates/profiles/<profile>/` (copied into your project root as `README.md` and `section-prompts.md` when the overlay is applied).

package/templates/CLAUDE.md

@@ -227,6 +227,9 @@ Detailed file map: `docs/ARCHITECTURE.md`.
 > Things unique to THIS repo. Filled by `/bootstrap` or as discovered.
 
 - Operator materials live in `{{INPUTS_PATH}}`. Read `{{INPUTS_PATH}}README.md` for the layout. If `{{INPUTS_PATH}}INGEST_MANIFEST.md` exists, read it before starting work.
+- If `docs/brief.md` exists, it is the **authoritative source** for scope, profile, brand, business model, and constraints. Read `docs/brief.json` for the machine-readable version. Do not re-ask the operator the questions already answered there.
+- If `tasks/prd-initial-build.md` exists, it is the **first PRD seed** generated from the brief. Start there before writing code.
+- If a `README.md` and `section-prompts.md` exist at the project root from a profile overlay (e.g. `lead-gen`, `booking`, `saas-dashboard`, `blog`), follow that profile's hard rules and section guidance.
 - {{CONVENTION_1}}
 - {{CONVENTION_2}}
 - {{CONVENTION_3}}

package/templates/START_HERE.md

@@ -17,9 +17,9 @@ Or use `codex`, `gemini`, or whichever CLI agent you prefer.
 ### 2. Paste this as your first message
 
 ```
-Read CLAUDE.md, AGENTS.md, and everything in {{INPUTS_PATH}}. If {{INPUTS_PATH}} has source materials (research, reference repos, brand assets, notes), use them as context. If it is empty or only has a README, that is fine. Either way, ask me up to 3 clarifying questions about what I want to build. Then propose a 30 to 60 minute MVP scope as a numbered list. Do not write code until I approve the scope.
+Read CLAUDE.md, AGENTS.md, docs/brief.md (if it exists), tasks/prd-initial-build.md (if it exists), and everything in {{INPUTS_PATH}}. If {{INPUTS_PATH}} has source materials (research, reference repos, brand assets, notes), use them as context. If it is empty or only has a README, that is fine. Either way, ask me up to 3 clarifying questions about what I want to build. Then propose a 30 to 60 minute MVP scope as a numbered list. Do not write code until I approve the scope.
 
-After I approve, run /bootstrap to fill in this project's metadata, then start building.
+After I approve, run /bootstrap to fill in this project's metadata, then start building. If docs/brief.md exists, treat it as authoritative for scope, brand, and constraints.
 ```
 
 That is the whole jump-in. The agent reads, asks, proposes, you approve, it builds.
@@ -38,6 +38,10 @@ That is the whole jump-in. The agent reads, asks, proposes, you approve, it buil
 | `docs/ARCHITECTURE.md` | Stack, file map, env vars, deploy details. | Agent |
 | `{{INPUTS_PATH}}` | Your source materials. May be empty. You can add files anytime. | Both |
 | `tasks/` | PRDs and task lists for features. | Both |
+| `docs/brief.md` | Operator brief (only if you scaffolded with `ostup brief`). Source of truth for scope, brand, constraints. | Both |
+| `docs/brief.json` | Machine-readable brief (same trigger). Used by downstream commands. | Agent |
+| `tasks/prd-initial-build.md` | Auto-seeded first PRD from the brief (same trigger). | Both |
+| `templates/profiles/<profile>/` | (if applicable) Profile-specific guidance the agent reads on day one. | Agent |
 | `.claude/commands/` | Slash command definitions. | Agent |
 
 ## Slash commands
@@ -66,13 +70,13 @@ Type these in your CLI agent. Each runs a structured routine.
 
 1. `claude` in this folder.
 2. Paste the prompt from step 2 above.
-3. The agent reads everything, asks 2 or 3 questions, proposes an MVP.
+3. The agent reads everything (including `docs/brief.md` if present), asks 2 or 3 questions, proposes an MVP.
 4. You approve (or refine).
 5. The agent runs `/bootstrap` to fill in project metadata.
 6. The agent builds the first cut and pushes commits.
 7. `/prompt-end` when you stop.
 
-Works the same whether `{{INPUTS_PATH}}` is empty or full. With materials, the agent uses them. Without, it asks you what to build outright.
+Works the same whether `{{INPUTS_PATH}}` is empty or full. With materials, the agent uses them. Without, it asks you what to build outright. If you scaffolded with `ostup brief` or `ostup init --brief`, the agent has a richer starting point: scope, profile, business model, and add-ons already chosen.
 
 ### B. Return session (pick up where you left off)
 

package/templates/profiles/blog/.env.example.additions

@@ -0,0 +1,7 @@
+# --- blog profile additions ---
+# Public app URL (used for absolute URLs in RSS + sitemap)
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# Optional: site author / RSS metadata
+NEXT_PUBLIC_AUTHOR_NAME=
+NEXT_PUBLIC_AUTHOR_URL=