@invisibleloop/pulse 0.14.1 → 0.14.2

package/src/agent/workflow.md

@@ -21,13 +21,17 @@
 For any **new page, landing page, or branded site**, run the intake sequence first:
 
 ```
-0. pulse_extract_inspiration(url/image) → structured design brief  [if user shares reference]
+0. ASK:  "Do you have any design inspiration — a site you love, a screenshot, or a mood board
+          image? Drop images into public/intake/ or paste a URL and I'll extract the design
+          intent before we start."   ← MANDATORY. Ask this before doing anything else.
+0b. pulse_extract_inspiration(url/image) → structured design brief  [if user supplies reference]
 1. pulse_intake(name, pitch, features, ...)   → product brief + contrast check
 2. pulse_sketch(brief, vibe?, antiStyle?)     → 3 layout directions to choose from
 3. pulse_intent(description)                  → archetype + scaffold + guide list
 ```
 
-- **`pulse_extract_inspiration`** — call this first if the user shares a URL, site name, or image they like. Gives you a structured extraction template: visit the URL or analyse the image with your vision tools, extract colours, layout, typography, and feel, then feed those findings into pulse_intake. If no inspiration is shared, skip this step.
+- **Step 0 — Ask for inspiration first (mandatory):** Before calling any tool or presenting any plan, ask the user: *"Do you have any design inspiration — a site you love, a screenshot, or a mood board image? Drop images into `public/intake/` or paste a URL and I'll extract the design intent before we start."* Wait for the answer. Do not skip this question, even if the user's brief already seems detailed. Check `public/intake/` for any images already dropped there.
+- **`pulse_extract_inspiration`** — call this after step 0 if the user supplies a URL, site name, or image they like. Also call it for any images already present in `public/intake/`. Gives you a structured extraction template: visit the URL or analyse the image with your vision tools, extract colours, layout, typography, and feel, then feed those findings into pulse_intake. If the user explicitly says they have no reference, skip this step.
 - **`pulse_intake`** — captures the real content (name, pitch, features, palette, vibe, what it should NOT look like). Returns a brief with copy-ready content and early contrast warnings. Always ask the user one question at a time — never multi-choice for open-ended questions.
 - **`pulse_sketch`** — generates 3 structurally distinct layout directions (full-bleed, asymmetric split, typography-only, editorial, dense grid, story scroll, content-first). **Call this before writing any code.** Prevents defaulting to centred hero + three-column features every time.
 - **Skip `pulse_sketch` only** when the vibe is `corporate` or `minimal` AND the user hasn't expressed any structural preference. For `playful`, `bold`, `brutalist`, `retro`, or `neon` vibes, `pulse_sketch` is mandatory — templates have default section orders that actively fight these vibes.
@@ -86,7 +90,8 @@ Not every task needs all 8 phases. Match the tier to the task:
 | 1 | Intent + Understand | — |
 | 2 | Build | announce brief → write files |
 | 3 | Validate | `pulse_validate` clean |
-| 4 | Browser | screenshot + Lighthouse desktop + mobile (100/100/100) |
+| 4a | Design approval | screenshot → show user → **wait for approval** *(new-build only)* |
+| 4b | Verify | `pulse_design_review` (if intake ran) → `pulse_layout_review` → Lighthouse desktop + mobile (100/100/100) |
 
 No tests required for pure view specs with no logic. Add tests if the view has non-trivial helper functions.
 
@@ -100,15 +105,16 @@ No tests required for pure view specs with no logic. Add tests if the view has n
 | 2 | Plan | user confirmation (skip if unambiguous) |
 | 3 | Build | announce brief → write files |
 | 4 | Validate | `pulse_validate` clean |
-| 5 | Browser | screenshot → `pulse_design_review` (if intake ran) → `pulse_layout_review` → Lighthouse desktop + mobile (100/100/100) + CLS 0.00 |
+| 5a | Design approval | screenshot → show user → **wait for approval** *(new-build only)* |
+| 5b | Verify | `pulse_design_review` (if intake ran) → `pulse_layout_review` → Lighthouse desktop + mobile (100/100/100) + CLS 0.00 |
 | 6 | Tests | mutations, view landmarks, any utility functions |
-| 7 | Code review | `pulse_review` — only after 4–6 pass |
+| 7 | Code review | `pulse_review` — only after 5–6 pass |
 
 ### Tier 3 — Complex (multi-step, shared state, or security-sensitive)
 
 *Applies to:* multi-step wizards, pages with guards and auth, store-connected pages, anything touching sensitive data or complex branching state.
 
-All phases as originally defined — full 8-phase flow with every gate.
+All phases as originally defined — full flow with every gate.
 
 | Phase | Action | Gate |
 |---|---|---|
@@ -116,7 +122,8 @@ All phases as originally defined — full 8-phase flow with every gate.
 | 2 | Plan | **user confirmation required** |
 | 3 | Build | announce brief → write files |
 | 4 | Validate | `pulse_validate` clean |
-| 5 | Browser | screenshot → `pulse_design_review` (if intake ran) → `pulse_layout_review` → Lighthouse 100/100/100 + CLS 0.00, desktop + mobile |
+| 5a | Design approval | screenshot → show user → **wait for approval** *(new-build only)* |
+| 5b | Verify | `pulse_design_review` (if intake ran) → `pulse_layout_review` → Lighthouse 100/100/100 + CLS 0.00, desktop + mobile |
 | 6 | Tests | full coverage: mutations, actions, guards, view |
 | 7 | Code review | `pulse_review` |
 | 8 | Fix + re-verify | re-run all gates |
@@ -209,7 +216,7 @@ Run `pulse_validate` on the spec file.
 
 ---
 
-## Phase 5 — Browser check (pass gate)
+## Phase 5 — Browser check
 
 **After every file edit, restart the server and reload the browser before checking anything.** The dev server auto-restarts on file changes but the browser tab stays stale. Always:
 1. Call `pulse_restart_server` — waits for the server to be ready
@@ -217,15 +224,40 @@ Run `pulse_validate` on the spec file.
 
 Do this before every screenshot, console check, or visual inspection. Never debug a problem that might just be a stale tab.
 
-**Run `/verify` now — as soon as the first build is working.** Do not defer it to the end. Do not execute these steps manually.
+---
+
+### Phase 5a — Design approval *(new builds from `pulse_intake` only)*
+
+**This phase applies when `pulse_intake` ran** — i.e. you are building a new page or site from scratch, not editing an existing one. For edits, bug fixes, or "add X to existing Y", skip to Phase 5b immediately.
+
+1. Take a screenshot of the built page
+2. Describe what you see in 2–3 plain sentences — layout structure, visual tone, key sections. Do NOT list features or code details.
+3. **Ask the user directly:** *"Happy with the layout and direction, or any changes before I run tests and Lighthouse?"*
+4. **Wait for their response before doing anything else.** Do not run design_review, layout_review, or Lighthouse until you have a clear go-ahead.
+
+**If the user requests changes:**
+- Make the edits
+- Take a new screenshot
+- Describe what changed
+- Ask again
+- Repeat until approved — each iteration is design-only, no Lighthouse between rounds
+
+**If the user approves (or says "looks good", "go ahead", "yes", etc.):**
+- Continue to Phase 5b
+
+> The point of this gate is to let the user redirect the design before expensive, slow checks run. A Lighthouse build takes ~90 seconds — do not start it until the user has seen and approved the visual result.
+
+---
+
+### Phase 5b — Full verification (pass gate)
+
+**Run `/verify` now.** Do not execute these steps manually.
 
 `/verify` validates, screenshots, runs Lighthouse (desktop + mobile), runs the performance trace (LCP + CLS), checks console errors, runs `pulse_review`, and writes the `.pulse-verified` stamp. Running steps manually does not write the stamp.
 
 > **Lighthouse pre-flight:** `/verify` calls `pulse_build` automatically before running Lighthouse, and audits against the production server on port 3001. If you ever call `lighthouse_audit` manually outside `/verify`, you must first run `pulse_build` and navigate to `http://localhost:3001/your-route`. Auditing the dev server (port 3000) will produce misleading results.
 
-### ⛔ After every screenshot — mandatory steps before continuing
-
-Taking a screenshot is NOT the end of phase 5. After every screenshot, you **must** run:
+### ⛔ After design approval — mandatory steps before continuing
 
 1. `pulse_design_review` (if `pulse_intake` ran) — work through all 7 signals, fix any Fail
 2. `pulse_layout_review <url>` — 390/768/1280px overflow, broken images, collapsed sections
@@ -234,7 +266,7 @@ Taking a screenshot is NOT the end of phase 5. After every screenshot, you **mus
 **Do not report the page as done until `/verify` writes the `.pulse-verified` stamp.** Skipping Lighthouse means broken contrast, missing landmarks, and Best Practices failures ship to the user.
 
 Pass gates:
-- Screenshot: no layout or rendering issues
+- Design approval: user has explicitly said they're happy with the layout
 - Design review: all 7 signals pass (or intake didn't run)
 - Layout review: no overflow, broken images, or collapsed sections at any viewport
 - Lighthouse desktop: Accessibility, Best Practices, SEO all 100
@@ -282,7 +314,9 @@ Only declare the task done after all gates still pass.
 
 ```
 New project / new page:
-  pulse_extract_inspiration  → (if user shares a URL or image) extract palette/layout/feel
+  ASK first              → "Do you have any design inspiration — a site, screenshot, or
+                            mood board? Drop into public/intake/ or paste a URL."
+  pulse_extract_inspiration  → (if user supplies a URL or image, or images found in public/intake/)
   pulse_intake               → capture real content, palette, vibe, anti-style
   pulse_sketch               → choose 1 of 3 structural layout directions
   pulse_intent               → get scaffold + guide list
@@ -293,8 +327,10 @@ Targeted edit / bug fix:
 Step 1   Understand        pulse_list_structure + relevant guides
 Step 2   Plan             confirm with user if non-trivial
 
-Tier 1  Simple     → phases 3 → 4 → 5
-Tier 2  Standard   → phases 3 → 4 → 5 → 6 → 7
-Tier 3  Complex    → phases 3 → 4 → 5 → 6 → 7 → 8
+Tier 1  Simple     → phases 3 → 4 → 5a (design approval) → 5b (verify)
+Tier 2  Standard   → phases 3 → 4 → 5a (design approval) → 5b (verify) → 6 → 7
+Tier 3  Complex    → phases 3 → 4 → 5a (design approval) → 5b (verify) → 6 → 7 → 8
+
+Phase 5a is skipped for edits, bug fixes, and "add X to existing Y".
 ```
 

package/src/cli/dev.js

@@ -12,6 +12,7 @@ import path    from 'path'
 import fs      from 'fs'
 import { createServer } from '../server/index.js'
 import { loadPages }    from './discover.js'
+import * as log         from './logger.js'
 
 // ---------------------------------------------------------------------------
 // Args
@@ -106,19 +107,13 @@ const PUBLIC_DIR     = path.join(ROOT, 'public')
 // Start
 // ---------------------------------------------------------------------------
 
-console.log(`⚡ Pulse dev server starting...\n`)
-
 const specs = await loadPages(ROOT)
 
 if (specs.length === 0) {
-  console.error('No pages found in src/pages/. Create a page to get started.')
+  log.error('No pages found in src/pages/. Create a page to get started.')
   process.exit(1)
 }
 
-console.log('Pages:\n')
-specs.forEach(spec => console.log(`  ${spec.route}`))
-console.log()
-
 // ---------------------------------------------------------------------------
 // Hot reload — SSE clients + file watcher
 // ---------------------------------------------------------------------------
@@ -148,19 +143,16 @@ let lastReload = 0
 async function triggerReload(label = 'File changed') {
   clearTimeout(reloadTimer)
   reloadTimer = setTimeout(async () => {
-    // Debounce rapid file changes (e.g. multiple Edit tool calls)
     const now = Date.now()
     if (now - lastReload < 100) return
     lastReload = now
-    
-    console.log(`  ⟳ ${label}, reloading specs...`)
+
     try {
       const fresh = await loadPages(ROOT, now)
       updateSpecs(fresh)
-      console.log('  ✓ Specs reloaded')
+      log.info(`${label} — specs reloaded`)
     } catch (err) {
-      console.error('  ✗ Spec reload failed:', err.message)
-      /* spec error — browser will show the old page, not crash */
+      log.error(`Spec reload failed: ${err.message}`)
     }
     notifyReload()
   }, 200)
@@ -199,6 +191,7 @@ const { updateSpecs } = await createServer(specs, {
   manifest:  {},        // never use a build manifest in dev — always serve source files
   extraBody: reloadScript,
   dev:       true,
+  agentMode: !!process.env.PULSE_AGENT_MODE,
   ...(_config.csp ? { csp: _config.csp } : {}),
 
   onRequest(req, res) {

package/src/cli/index.js

@@ -33,13 +33,6 @@ for (let i = 0; i < rawArgs.length; i++) {
 const command = args[0]
 const CWD     = process.cwd()
 
-// Parse --agent flag before routing to commands
-let agentFlag = null
-const agentIdx = args.indexOf('--agent')
-if (agentIdx !== -1 && args[agentIdx + 1]) {
-  agentFlag = args[agentIdx + 1]
-}
-
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -176,13 +169,14 @@ async function launchSession(root, agentOverride = null) {
     }
   }
 
-  console.log(`\n⚡ Pulse project: ${root}`)
-  console.log(`   Use /pulse-dev to start the dev server, /pulse-stop to stop it, /pulse-build to build, /pulse-start to run production.`)
-  console.log(`   Tell me what you'd like to build — a new page, a component, a form, or anything else.\n`)
+  console.log(`\n  ⚡ Pulse  →  ${root}`)
+  console.log(`  ${agent === 'copilot' ? '● Copilot' : '● Claude'} agent starting — tell me what you'd like to build.\n`)
 
   if (agent === 'copilot') {
+    process.env.PULSE_AGENT_MODE = '1'
     await launchCopilotSession(root, mcpServerPath, spawn, os.default)
   } else {
+    process.env.PULSE_AGENT_MODE = '1'
     await launchClaudeSession(root, mcpConfig, spawn, os.default)
   }
 }

package/src/cli/logger.js

@@ -0,0 +1,145 @@
+/**
+ * Pulse CLI — structured terminal logger
+ *
+ * Single module that owns all terminal output. Produces clean, scannable
+ * output: one-time startup banner, then a timestamped scrolling log.
+ *
+ * Rules:
+ *  - Static asset requests (JS, CSS, images, fonts) are dimmed and collapsed
+ *  - Errors always stand out (red ✗ prefix)
+ *  - Agent activity gets a distinct indicator
+ *  - Respects NO_COLOR and CI env vars
+ */
+
+import { c, icon, elapsed, visLen } from './fmt.js'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const STATIC_EXT = /\.(js|css|map|ico|png|jpg|jpeg|gif|svg|woff2?|ttf|eot|webp|avif|json)$/i
+const STATIC_PATH = /^\/(dist|fonts|images|public)\//
+
+function isStatic(pathname) {
+  return STATIC_EXT.test(pathname) || STATIC_PATH.test(pathname)
+}
+
+function timestamp() {
+  return c.dim(new Date().toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit', second: '2-digit' }))
+}
+
+function statusColor(code) {
+  if (code >= 500) return c.red(String(code))
+  if (code >= 400) return c.yellow(String(code))
+  if (code >= 300) return c.cyan(String(code))
+  return c.dim(String(code))
+}
+
+function methodColor(method) {
+  if (method === 'POST' || method === 'PUT' || method === 'PATCH') return c.yellow(method.padEnd(4))
+  if (method === 'DELETE') return c.red(method.padEnd(4))
+  return c.dim(method.padEnd(4))
+}
+
+// ---------------------------------------------------------------------------
+// Banner — printed once at startup
+// ---------------------------------------------------------------------------
+
+/**
+ * Print the startup banner.
+ * @param {{ url: string, version: string, specs: Array<{route:string, method?:string, hydrate?:string}>, agentMode?: boolean }} opts
+ */
+export function banner({ url, version, specs = [], agentMode = false }) {
+  const agentLabel = agentMode ? `  ${c.cyan('●')} ${c.dim('Agent active')}` : ''
+
+  process.stdout.write('\n')
+  process.stdout.write(`  ${icon.bolt()} ${c.bold('Pulse')}  ${c.dim(`v${version}`)}  ${c.dim('→')}  ${c.cyan(url)}${agentLabel}\n`)
+  process.stdout.write('\n')
+
+  if (specs.length > 0) {
+    // Column widths
+    const routeW  = Math.max(5, ...specs.map(s => (s.route || '?').length))
+    const methodW = 6
+
+    const header = `  ${c.dim('Route'.padEnd(routeW))}  ${c.dim('Method'.padEnd(methodW))}  ${c.dim('JS')}`
+    const divider = `  ${c.dim('─'.repeat(routeW + methodW + 8))}`
+
+    process.stdout.write(header + '\n')
+    process.stdout.write(divider + '\n')
+
+    for (const s of specs) {
+      const route   = (s.route || '?').padEnd(routeW)
+      const method  = (s.method?.toUpperCase() || 'GET').padEnd(methodW)
+      const hydrate = s.hydrate ? c.green('✓ hydrated') : c.dim('— static')
+      process.stdout.write(`  ${c.cyan(route)}  ${c.dim(method)}  ${hydrate}\n`)
+    }
+
+    process.stdout.write('\n')
+  }
+
+  process.stdout.write(c.dim('  Ready. Watching for changes…\n'))
+  process.stdout.write(c.dim('  ' + '─'.repeat(48) + '\n'))
+  process.stdout.write('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Request log — one line per request
+// ---------------------------------------------------------------------------
+
+/**
+ * Log a completed HTTP request.
+ * @param {{ method: string, pathname: string, status: number, ms: number }} opts
+ */
+export function request({ method, pathname, status, ms }) {
+  const isAsset = isStatic(pathname)
+
+  // Skip health check noise
+  if (pathname === '/healthz' || pathname === '/_pulse/health') return
+
+  const ts     = timestamp()
+  const m      = methodColor(method)
+  const p      = isAsset ? c.dim(pathname) : pathname
+  const s      = statusColor(status)
+  const t      = c.dim(elapsed(ms))
+
+  if (isAsset) {
+    // Static assets — dim the whole line, no leading symbol
+    process.stdout.write(`${ts}  ${c.dim(method.padEnd(4))}  ${p}  ${c.dim(String(status))}  ${t}\n`)
+  } else if (status >= 500) {
+    process.stdout.write(`${ts}  ${icon.fail()}  ${m}  ${c.red(pathname)}  ${s}  ${t}\n`)
+  } else if (status >= 400) {
+    process.stdout.write(`${ts}  ${icon.warn()}  ${m}  ${c.yellow(pathname)}  ${s}  ${t}\n`)
+  } else {
+    process.stdout.write(`${ts}  ${icon.info()}  ${m}  ${p}  ${s}  ${t}\n`)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Named events — server lifecycle
+// ---------------------------------------------------------------------------
+
+export function ready(url) {
+  process.stdout.write(`${timestamp()}  ${icon.ok()}  ${c.dim('Server ready')}  ${c.dim(url)}\n`)
+}
+
+export function shutdown(forced = false) {
+  process.stdout.write('\n')
+  if (forced) {
+    process.stdout.write(`  ${icon.fail()}  ${c.red('Force-exiting after shutdown timeout')}\n`)
+  } else {
+    process.stdout.write(`  ${icon.info()}  ${c.dim('Shutting down gracefully…')}\n`)
+  }
+}
+
+export function error(msg, err) {
+  process.stdout.write(`${timestamp()}  ${icon.fail()}  ${c.red(msg)}\n`)
+  if (err?.stack) process.stdout.write(c.dim(err.stack.split('\n').slice(1, 4).map(l => '    ' + l).join('\n')) + '\n')
+}
+
+export function info(msg) {
+  process.stdout.write(`${timestamp()}  ${icon.info()}  ${c.dim(msg)}\n`)
+}
+
+export function warn(msg) {
+  process.stdout.write(`${timestamp()}  ${icon.warn()}  ${c.yellow(msg)}\n`)
+}

package/src/cli/scaffold.js

@@ -27,6 +27,7 @@ export async function scaffold(targetDir, options = {}) {
   fs.mkdirSync(path.join(targetDir, 'src', 'pages'),      { recursive: true })
   fs.mkdirSync(path.join(targetDir, 'src', 'components'), { recursive: true })
   fs.mkdirSync(path.join(targetDir, 'public'),             { recursive: true })
+  fs.mkdirSync(path.join(targetDir, 'public', 'intake'),   { recursive: true })
 
   // package.json
   write(targetDir, 'package.json', JSON.stringify({
@@ -62,6 +63,9 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}${agent && agent !== 'claude' ? `  a
   write(targetDir, 'public/theme.css', themeCSS())
   write(targetDir, 'public/app.css',   baseCSS())
 
+  // Intake directory — drop inspiration images here before running pulse_intake
+  write(targetDir, 'public/intake/README.md', intakeReadme())
+
   // Copy pulse-ui assets from the package into public/ so they're served immediately
   const pkgPublic = new URL('../../public', import.meta.url).pathname
   for (const asset of ['pulse-ui.css', 'pulse-ui.js']) {
@@ -124,13 +128,18 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}${agent && agent !== 'claude' ? `  a
           hooks: [
             {
               type: 'command',
-              command: `node -e "process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'SessionStart',additionalContext:'START OF SESSION: Before doing anything else — (1) run pulse_list_structure to see the current project structure, (2) read pulse://guide from MCP for the complete Pulse reference. Both are mandatory. Do not skip them.'}}))"`,
+              command: `node -e "process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'SessionStart',additionalContext:'START OF SESSION: Before doing anything else — (1) run pulse_list_structure to see the current project structure, (2) read pulse://guide from MCP for the complete Pulse reference. Both are mandatory. Do not skip them.\\n\\nBUILD RULE — ALWAYS ASK BEFORE PLANNING: If the user is requesting a new page or site, your FIRST action must be to ask: \\'Do you have any design inspiration — a site you love, a screenshot, a mood board image? Drop images into public/intake/ or paste a URL and I will extract the design intent before we start.\\' Do not present a plan or write any code until you have asked this question and received an answer. This question is not optional and cannot be skipped.'}}))"`,
               statusMessage: 'Loading Pulse session...',
             },
             {
               type: 'command',
               command: `node -e "const{execSync}=require('child_process');let out='';let ok=true;try{out=execSync('npm test 2>&1',{encoding:'utf8',timeout:60000});}catch(e){ok=false;out=e.stdout||e.message;}const lines=out.trim().split('\\n');const summary=lines[lines.length-1]||'';const msg=ok?'TEST BASELINE — all tests passing: '+summary+'. Note this result. If tests fail after your changes, you introduced the regression.':'PRE-EXISTING TEST FAILURES detected before you wrote any code:\\n'+out.slice(-2000)+'\\nDo not treat these as regressions you caused. Fix them first if they are related to your task, otherwise note them and proceed.';process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'SessionStart',additionalContext:msg}}))"`,
               statusMessage: 'Running test baseline...',
+            },
+            {
+              type: 'command',
+              command: `node -e "const fs=require('fs');const path=require('path');const intakeDir='public/intake';let images=[];try{images=fs.readdirSync(intakeDir).filter(f=>/\\.(jpe?g|png|gif|webp|avif)$/i.test(f));}catch{}if(!images.length){process.exit(0);}const list=images.map(f=>'  • '+f).join('\\n');process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'SessionStart',additionalContext:'DESIGN REFERENCES FOUND in public/intake/:\\n'+list+'\\n\\nBefore running pulse_intake, call pulse_extract_inspiration on each image to extract palette, vibe, layout density, and type signals. This gives the design much more precision than text descriptions alone.\\n\\nWorkflow: pulse_extract_inspiration(image) → fill in the template using your vision → feed results into pulse_intake(inspiration: \\'...\\')'}}));"`,
+              statusMessage: 'Checking for design references...',
             }
           ]
         }
@@ -209,6 +218,13 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}${agent && agent !== 'claude' ? `  a
     'public/dist',
     '.pulse-build',
     '.DS_Store',
+    '# Intake images — local design references, not committed',
+    'public/intake/*.jpg',
+    'public/intake/*.jpeg',
+    'public/intake/*.png',
+    'public/intake/*.gif',
+    'public/intake/*.webp',
+    'public/intake/*.avif',
   ].join('\n') + '\n')
 
   console.log('  ✓ Project files created')
@@ -349,6 +365,42 @@ function themeCSS() {
 `
 }
 
+function intakeReadme() {
+  return `\
+# Design References
+
+Drop inspiration images here before starting a new build.
+
+The session start hook will detect them and remind the agent to run
+\`pulse_extract_inspiration\` on each one before \`pulse_intake\`.
+
+## What to put here
+
+- Screenshots of sites whose design you admire
+- Your brand mood board or style guide
+- Product photography that anchors the visual direction
+- Competitor sites you want to differentiate from
+- Any image that captures the feeling you're going for
+
+## How the agent uses them
+
+1. \`pulse_extract_inspiration(image)\` — reads the image and extracts palette,
+   type weight, spacing density, radius signals, and layout intent
+2. The extracted values feed into \`pulse_intake\` as concrete constraints
+3. \`pulse_sketch\` uses them to generate layout directions matched to the actual
+   visual reference, not just a text description of a vibe
+
+## File formats
+
+JPEG, PNG, WebP, AVIF, GIF — any image the model can read.
+
+## Note
+
+These files are listed in .gitignore and will not be committed.
+Only this README is tracked.
+`
+}
+
 function baseCSS() {
   return `\
 *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
@@ -377,12 +429,14 @@ src/pages/        ← one .js file per page, auto-discovered
 src/components/   ← shared view fragments (JS functions returning HTML strings)
 public/theme.css  ← token definitions (hex values, colour overrides) — hex allowed here only
 public/app.css    ← layout and component overrides — var() references only, no hex
+public/intake/    ← drop design reference images here before starting (not committed to git)
 \`\`\`
 
 ## Start of every session
 
 1. Run \`pulse_list_structure\` to see what already exists
 2. Read \`pulse://guide\` from MCP — the complete reference for spec format, components, verification workflow, CSS rules, and patterns
+3. If images are present in \`public/intake/\`, call \`pulse_extract_inspiration\` on each before \`pulse_intake\` — the session hook will remind you if you forget
 
 The MCP guide is the single source of truth. Follow it for all technical decisions, component usage, and the mandatory verification workflow.