@invisibleloop/pulse 0.12.3 → 0.14.1

package/src/agent/guide-templates.md

@@ -2,6 +2,8 @@
 
 Templates are complete, production-ready page specs you can adapt for a new brand. Always start from a template when the user's request matches one — do not build from scratch.
 
+**A template gives you the right *components and content slots* — not a mandatory section order.** The structural skeleton (hero → features → testimonials → CTA) suits corporate and minimal vibes. For playful, bold, brutalist, retro, and neon vibes, the template is a parts list, not a blueprint. Run `pulse_sketch` to find a layout that matches the emotional intent before you write a line of code.
+
 ---
 
 ## When to use a template
@@ -10,22 +12,93 @@ Read the user's request and match against the triggers below. If it matches, use
 
 | Template | Route | Triggers |
 |---|---|---|
-| Mobile App Landing | `docs/src/pages/templates/mobile-app.js` | "landing page for a mobile app", "app marketing site", "app homepage", "SaaS landing page" |
-| Blog Post          | `docs/src/pages/templates/blog-post.js`  | "blog post", "article page", "publication", "editorial site", "newsletter with blog" |
+| Mobile App Landing  | `docs/src/pages/templates/mobile-app.js`       | "landing page for a mobile app", "app marketing site", "app homepage", "SaaS landing page" |
+| Blog Post           | `docs/src/pages/templates/blog-post.js`        | "blog post", "article page", "publication", "editorial site", "newsletter with blog" |
+| Local Business      | `docs/src/pages/templates/local-business.js`   | "local business", "dog groomer", "bakery", "physio", "plumber", "florist", "salon", "restaurant", "tradesperson", "small business" |
+| Portfolio           | `docs/src/pages/templates/portfolio.js`        | "portfolio", "personal site", "freelancer site", "creative professional", "photographer", "designer site", "developer portfolio" |
+| Event / Conference  | `docs/src/pages/templates/event.js`            | "conference", "event", "festival", "workshop", "concert", "meetup", "summit" |
+| Editorial / Magazine | `docs/src/pages/templates/editorial.js`       | "magazine", "publication", "news site", "editorial", "online journal", "newsletter homepage" |
+
+**Always fetch `pulse://guide/design-references` after matching a template** — it tells you which vibe and component combinations suit the product's aesthetic, so you don't default to the same SaaS geometry every time.
 
 ---
 
-## Before writing any code — mandatory pre-build questions
+## Creative-override rule — when to ignore the template structure
+
+When the vibe is **playful, bold, brutalist, retro, or neon**, run `pulse_sketch` before writing any code and **treat the template section order as optional**. These vibes require structural decisions that the template's default skeleton actively works against.
+
+| Signal | What to do |
+|---|---|
+| Vibe is playful / bold / brutalist / retro / neon | Run `pulse_sketch` — pick one of 3 layout directions |
+| User says "fun", "pop-art", "loud", "unexpected", "editorial", "raw" | Run `pulse_sketch` — section order is your call |
+| User says "professional", "clean", "trustworthy", "corporate", "minimal" | Template structure is fine — adapt content only |
+
+**What this means in practice for expressive vibes:**
+
+- The template tells you *what to include* (a hero, features, social proof, CTA). It does **not** tell you how to arrange them or what shape they take.
+- Full-colour section blocks, oversized typography heroes, marquee strips, dense grids, and palette-as-structure are all fair game.
+- The `phoneFrame` in Mobile App Landing is **not mandatory** — a full-bleed game board, an oversized illustration, or a typography-only hero may serve the brief better.
+- `feature()` in a 3-column grid is the most predictable layout on the web. If the brief is "fun and bold", use a marquee strip of features, a zigzag alternating layout, or full-bleed feature sections instead.
+
+---
+
+## Template-mode: lighter planning
+
+When using a template, skip the full plan-and-confirm ceremony. Instead, output a single compact confirmation before writing:
+
+```
+Template:      Mobile App Landing
+App name:      Nova
+Substitutions: name, tagline, 5 features, 3 pricing tiers, palette, font
+Theme:         light  (palette: #6366f1 primary, #f8fafc bg)
+Files:         src/pages/nova.js, public/themes/nova.css
+Confirm to proceed — or reply with changes.
+```
+
+Wait one turn for confirmation. This replaces the full plan/build/confirm cycle. It is enough — the user can see exactly what will change.
 
-Ask these **before** presenting a plan. Do not skip them.
+**Do not skip the confirmation.** Even for templates, one turn of "does this look right?" prevents throwing away a completed build because the app name or palette was wrong.
 
-1. **Colour palette** — "Do you have a colour palette, or should I choose one?"
-2. **Brand fonts** — "Any brand fonts, or system-ui is fine?"
-3. **Theme** — "Light or dark theme preference?"
+### One-shot builds without a template
 
-Record the answers. If the user provides palette colours, note which are light/mid/dark toned so you can plan contrast strategy before writing any CSS.
+For a one-shot "build me X" request that doesn't use a named template, use the same compact style — a 3–5 line brief, not a full phase-2 plan:
 
-**Why this matters:** Building with placeholder colours and retrofitting a palette requires rebuilding components, fixing WCAG contrast failures, and touching multiple files. Getting the palette upfront avoids that loop entirely.
+```
+Building: Chess Club landing page (/chess-club)
+Vibe:     editorial · dark navy + gold · brutalist structure
+Sections: hero, about, schedule, join CTA
+Files:    src/pages/chess-club.js, public/themes/chess-club.css
+Confirm to proceed — or reply with changes.
+```
+
+Reserve the full plan-and-confirm ceremony (route / state / mutations / actions / server fetchers) for multi-page builds, pages with complex state, or when the user hasn't confirmed the scope yet.
+
+---
+
+## Before writing any code — mandatory product intake
+
+Run `pulse_intake` before presenting the confirmation. It collects the product details that make template content directionally right instead of fiction.
+
+**How to gather the intake information** — ask questions one at a time as plain prose, never as a batch with multiple-choice options. Product details are open-ended and free-form; preset choice lists don't fit and cause tool errors. Ask the simplest possible version of each question:
+
+1. "What's the name of the app or product?"
+2. "One sentence — what does it do?"
+3. "What are its main features? Give me 3–6."
+4. "Who's it for?" *(optional — skip if obvious from context)*
+5. "Do you have brand colours? If so, paste the hex values."
+6. "Any specific font, or system-ui?"
+7. "Light or dark theme preference?"
+8. "How should it feel visually? (e.g. warm and friendly, editorial and sharp, playful, minimal, bold — or describe in your own words)"
+
+Ask each question and wait for the answer before asking the next. Do not present a list of preset choices for any of these — the answers are arbitrary text.
+
+Once you have the answers, call `pulse_intake` with the collected details. It returns a product brief + early contrast warnings.
+
+**If `pulse_intake` is unavailable**, gather the answers via the questions above and use them directly when adapting the template — replace every placeholder with real content.
+
+**Do not invent app content.** Placeholder copy ("Lorem ipsum", "Feature A", "Benefit here") is thrown away immediately and makes the build feel broken. Real answers mean the first build is shippable copy.
+
+Record the intake answers. If the user provides palette hex values, note which are light/mid/dark toned before writing any CSS — this is when to spot contrast problems, not after Lighthouse runs.
 
 ---
 
@@ -237,7 +310,144 @@ Do NOT set `meta.theme: 'light'` on dark templates — the default pulse-ui them
 
 ---
 
-## Adding a new template
+## Local Business Landing Page
+
+**Design direction:** Warm Local Business · **Vibe:** `warm` · **Theme:** `light`
+
+### What it includes
+
+| Section | Component(s) |
+|---|---|
+| Sticky nav | `nav` with logo, links, Book Now CTA |
+| Hero | `hero(layout:'split')` with real photo of the business |
+| Stats strip | `stat` × 4 in `grid` — clients, rating, years, availability |
+| Services | `card` × 6 in `grid` with name, description, and price |
+| About | Two-column: photo + team bio with trust badges |
+| Reviews | `testimonial` × 3 in `grid` |
+| Contact / Hours | Two-column: address/phone/hours + booking form |
+| CTA banner | `cta` with offer (e.g. 10% off first visit) |
+| Footer | `footer` with address in `legal` |
+
+### Files to create
+
+| File | Purpose |
+|---|---|
+| `src/pages/[name].js` | The page spec |
+| `public/themes/[name].css` | Brand theme — warm palette, `[data-theme="light"]` |
+
+### Adapting the template
+
+1. **Business name** — replace "Pawfect Grooming" everywhere.
+2. **Service type** — update service names, descriptions, and prices to match the business.
+3. **Photo** — the hero image and about section both use real photos; provide Unsplash URLs or placeholder paths. **If using external images**, add the host to `csp` in `pulse.config.js` (see pulse://guide/styles for examples).
+4. **Palette** — earthy, warm tones work best. Terracotta, sage, cream, amber — avoid corporate blues.
+5. **Contact details** — update address, phone, and opening hours in the contact section.
+6. **Vibe** — always `warm` for local business; pairs with rounded cards and soft section dividers.
+
+---
+
+## Portfolio / Personal Site
+
+**Design direction:** Minimal Portfolio · **Vibe:** `minimal` · **Theme:** dark (default)
+
+### What it includes
+
+| Section | Component(s) |
+|---|---|
+| Nav | Minimal nav — name as logo, text links, no CTA |
+| Hero | `hero(layout:'centered', align:'left')` — title and short bio |
+| Work grid | `card` × 6 with image, project name, description, skill badges |
+| About | Single-column `container(size:'sm')` with `prose`-style paragraphs + skill badges |
+| Contact | Centered section with email link, GitHub link, CV download |
+| Footer | Minimal — name, 3 links, legal |
+
+### Files to create
+
+| File | Purpose |
+|---|---|
+| `src/pages/[name].js` | The page spec |
+
+Portfolio templates rarely need a separate theme CSS — the default dark palette with a single accent colour is sufficient. If the user has a brand colour, add it as a one-liner: `--ui-accent: #hex;` in `:root`.
+
+### Adapting the template
+
+1. **Name** — replace "Alex Mercer" everywhere, including the nav logo.
+2. **Profession** — update the eyebrow and hero subtitle.
+3. **Work grid** — replace with real project images, names, and descriptions. Use Unsplash or actual project screenshots. **If using external images**, add the host to `csp` in `pulse.config.js` (see pulse://guide/styles).
+4. **Skills badges** — update to match the person's actual disciplines.
+5. **Contact** — replace email, GitHub handle, and CV download link.
+6. **Vibe** — `minimal` keeps the focus on the work; do not add excess decoration.
+
+---
+
+## Event / Conference Landing Page
+
+**Design direction:** Event / Conference · **Vibe:** `bold` · **Theme:** dark (default)
+
+### What it includes
+
+| Section | Component(s) |
+|---|---|
+| Nav | `nav` with event logo, links, Get Tickets CTA |
+| Hero | `hero(size:'xl', align:'center')` with gradient background |
+| Stats strip | `stat` × 4 — days, speakers, attendees, tracks |
+| Sponsor logos | `marquee` with sponsor names/logos |
+| Speakers | `card` × 8 in `grid` with photo, name, role, topic |
+| Schedule | `accordion` — one item per day with time/session/location |
+| Venue | Two-column: venue info + photo |
+| Tickets CTA | `cta` with prominent ticket button |
+| Footer | `footer` with event links and company legal |
+
+### Files to create
+
+| File | Purpose |
+|---|---|
+| `src/pages/[name].js` | The page spec |
+| `public/themes/[name].css` | Optional — if brand has a specific accent colour |
+
+### Adapting the template
+
+1. **Event name and dates** — replace "SIGNAL", "14–16 October 2026", and "London" everywhere.
+2. **Speakers** — replace with real speaker names, roles, photos, and talk topics.
+3. **Schedule** — update accordion items with real session titles and times.
+4. **Venue** — update name, address, capacity, and photo.
+5. **Ticket price and URL** — update the ticket CTA with real link and price.
+6. **Gradient hero** — adjust the gradient colours to match the event brand.
+7. **Vibe** — `bold` for impact; consider `neon` for gaming/tech events.
+
+---
+
+## Editorial / Magazine Landing Page
+
+**Design direction:** Editorial / Publication · **Vibe:** `editorial` · **Theme:** dark (default)
+
+### What it includes
+
+| Section | Component(s) |
+|---|---|
+| Nav | `nav` with publication name + category links + Subscribe CTA |
+| Hero | `hero` with featured article title, deck, and author byline |
+| Pullquote | `pullquote` from the featured article |
+| Article grid | `card` × 6 with image, category badge, title, deck, author, date, read time |
+| Newsletter signup | `section(variant:'spotlight')` with email input and subscribe button |
+| Footer | `footer` with publication logo, category links, legal |
+
+### Files to create
+
+| File | Purpose |
+|---|---|
+| `src/pages/[name].js` | The page spec |
+
+### Adapting the template
+
+1. **Publication name** — replace "The Signal" everywhere.
+2. **Navigation categories** — update section names to match the publication's editorial categories.
+3. **Featured article** — replace hero title and subtitle with the actual lead story.
+4. **Article grid** — replace all 6 article stubs with real or representative articles.
+5. **Newsletter copy** — update the newsletter description and subscriber count.
+6. **Vibe** — `editorial` applies serif display font and zero-radius geometry; critical for the right feel. Do not change it.
+
+---
 
 When you build a new template and want it available for future scaffolding:
 

package/src/agent/guide.md

@@ -497,13 +497,18 @@ Convention: name dynamic-route files [param].js inside a subfolder:
 
 This is purely a human readability convention. Pulse does not process [ ] in filenames.
 
-## UI components — MANDATORY
+## UI components
 
-**RULE: Before writing any HTML, check whether a Pulse UI component exists for the purpose. If it does, you MUST use it. Raw HTML is only permitted for structural tags with no component equivalent (div, main, aside, footer, header).**
+**Default rule: Before writing any HTML, check whether a Pulse UI component exists for the purpose. If it does, use it.** Components ship with correct ARIA, token-based styling, and responsive behaviour — choosing them over raw HTML means less work, not more.
 
-**RULE: For every feature, page, or UI element you build — regardless of how the request is phrased, whether it came from text or an image — your first step is always to check whether a Pulse UI component exists for it. If it does, you MUST use it. There are no exceptions.**
+**Creative override:** When the design intent genuinely calls for a more expressive or unconventional layout — a distinctive visual identity, an asymmetric or typographically-driven composition, a brutalist or editorial structure that components would constrain — you may build with raw HTML instead. This is not a loophole; it is a deliberate design decision. When taking this path:
 
-Before writing a single line of HTML, mentally scan the task and list which components apply. Only after exhausting the component list should you write raw HTML — and only for structural wrappers (div, main, aside, footer) with no component equivalent.
+1. **State your intent explicitly** in the build brief: *"Building component-free — raw HTML throughout for maximum creative control."*
+2. **Pulse-ui.css is still required** — always load it in `meta.styles`. It provides the token system (`--ui-*` variables) that your custom CSS will reference.
+3. **Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components** unless there is a specific design reason to hand-roll them. These are the hardest to get right for accessibility.
+4. **The quality gate replaces the component checklist** — 100/100/100/100 Lighthouse (Accessibility, Best Practices, SEO, Agentic Browsing) on both desktop and mobile is the arbiter. A component-free page that passes every Lighthouse audit is correct. A component-heavy page that fails accessibility is not.
+
+Before writing a single line of HTML, decide which mode you are in and state it in the build brief:
 
 **RULE: All components accept a `class` prop — never `className` (that is React). Use `class` to add utility classes or custom identifiers to any component.**
 

package/src/agent/workflow.md

@@ -1,57 +1,186 @@
 # Build Workflow
 
-Every task follows this sequence exactly. Each phase has a pass gate — you do not move to the next phase until the gate is cleared. Do not skip phases. Do not reorder them.
+---
+
+## Quick decision tree
+
+| Situation | Start here |
+|---|---|
+| New site, new branded page, or "build me X from scratch" | `pulse_intake` → `pulse_sketch` → `pulse_intent` → build |
+| Editing an existing page, adding a section, fixing a bug | Go straight to Step 1 — Understand |
+| "Add X to the existing Y" (one-liner) | Read the relevant file, make the change, run `/verify` |
+| Stuck on which component to use | `pulse_intent("describe what I'm building")` |
+| Colours failing contrast / unsure about palette | `pulse_check_contrast` |
+| Something looks wrong in the browser | `pulse_restart_server`, then `/verify` |
+| Lighthouse < 100 | Fix the flagged audit, run `/verify` again — do not skip to commit |
 
 ---
 
-## Phase 1 — Understand
+## New project or new page? Start with Intake
+
+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]
+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.
+- **`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.
+- **`pulse_intent`** — maps the chosen direction to a spec scaffold and tells you which guides to read.
+
+For **small edits, bug fixes, or "add X to existing Y"** — skip intake/sketch and go straight to Step 0 below.
+
+---
+
+## Step 0 — Intent (always first for non-trivial builds)
+
+After intake + sketch (or directly for targeted tasks), call `pulse_intent`:
+
+```
+pulse_intent("a settings page with profile editing and a save action")
+```
+
+It returns a matched archetype, recommended components, a starter spec scaffold, and which guide sections to read. This replaces hunting through guide sections manually.
+
+If the user's request is already very specific (a one-liner edit, a bug fix, "add X to the existing Y"), skip this and go straight to Understand.
+
+---
 
-Before writing a single line of code:
+## Step 1 — Understand
 
-1. Fetch `pulse://guide` for the guide index.
-2. Fetch any topic sections you need (`pulse://guide/spec`, `pulse://guide/components`, etc.).
-3. Call `pulse_list_structure` to see what pages and components already exist.
+Call `pulse_list_structure` to see what already exists. Fetch only the guide sections relevant to your intent (the `pulse_intent` response tells you which ones).
 
-Do not guess about props, patterns, or rules. If you are unsure, fetch the relevant guide section.
+Do not fetch every guide section for every task. Fetch what you need.
 
 ---
 
-## Phase 2 — Plan (confirmation gate)
+## Step 2 — Plan
 
-Before building, output a concise plan:
+Decide the complexity tier (see below) and confirm with the user if the task is non-trivial. Output a concise plan:
 
-- What page(s) or component(s) you will create or modify
-- The route, state shape, mutations/actions, and server fetchers
+- Route, state shape, mutations/actions, server fetchers
 - Which UI components you will use
-- Any shared components you will create or reuse
+- Files you will create or modify
+
+**Skip confirmation for trivially small tasks** (add a button, fix a label, swap a component). When in doubt, confirm.
+
+**When asking the user questions:** ask one question at a time. If you present choices, use at most 4 options — the `ask_user` tool enforces this limit and will error if exceeded. For open-ended questions (names, copy, features, hex colours), ask as plain prose with no choices at all.
+
+---
+
+## Complexity tiers
+
+Not every task needs all 8 phases. Match the tier to the task:
+
+### Tier 1 — Simple (static or read-only content)
+
+*Applies to:* landing pages, blog posts, profile pages, any page with no mutations or actions.
+
+| Phase | Action | Gate |
+|---|---|---|
+| 1 | Intent + Understand | — |
+| 2 | Build | announce brief → write files |
+| 3 | Validate | `pulse_validate` clean |
+| 4 | Browser | screenshot + 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.
 
-Wait for the user to confirm or adjust the plan before writing any code.
+### Tier 2 — Standard (interactive, single-purpose)
 
-**Skip this gate only if the task is unambiguous and small** (e.g. "add a delete button to the existing list page"). When in doubt, confirm.
+*Applies to:* forms, CRUD pages, settings, auth flows, dashboards without complex state machines.
+
+| Phase | Action | Gate |
+|---|---|---|
+| 1 | Intent + Understand | — |
+| 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 |
+| 6 | Tests | mutations, view landmarks, any utility functions |
+| 7 | Code review | `pulse_review` — only after 4–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.
+
+| Phase | Action | Gate |
+|---|---|---|
+| 1 | Intent + Understand | — |
+| 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 |
+| 6 | Tests | full coverage: mutations, actions, guards, view |
+| 7 | Code review | `pulse_review` |
+| 8 | Fix + re-verify | re-run all gates |
+
+**If in doubt, default to Tier 2.** Choosing a lower tier than the task warrants means you'll hit problems at gates — the tiers are a shortcut, not a way to skip quality.
 
 ---
 
 ## Phase 3 — Build
 
-### 3a — Announce before writing
+### 3a — Decide: components or creative override
+
+**Two valid modes — choose one and state it in the build brief:**
+
+**Mode A — Components first (default)**
+Use Pulse UI components for all standard UI patterns. Before writing any view HTML, grep `src/ui/index.js` for the components you need:
+
+```bash
+grep -E "^export" src/ui/index.js | head -20
+```
+
+Or use the guide-components table. Never write these patterns from scratch in Mode A:
+
+- Hero section → `hero()`
+- Product/service cards → `card()`
+- Image + text layouts → `media()`
+- Horizontal strips → `banner()`
+- Feature tiles → `feature()`
+- Testimonials → `testimonial()`
+- CTAs → `cta()`
+
+If you're about to type `class="hero"` or `class="product-card"` in Mode A, stop — use the component instead.
+
+**Mode B — Creative override (raw HTML throughout)**
+When the design intent calls for a more expressive, unconventional, or typographically-driven layout that components would constrain, you may build with raw HTML throughout. This is a deliberate design decision, not a shortcut.
+
+Rules for Mode B:
+- Load `/pulse-ui.css` in `meta.styles` — the token system is still required
+- Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there is a specific design reason
+- The quality gate is 100/100/100/100 Lighthouse on both desktop and mobile — this replaces the component checklist as the pass bar
 
-Before writing any file, output a build brief so the user can see what is being constructed and catch misunderstandings before minutes of work are lost. Format:
+Announce Mode B explicitly in the build brief: *"Mode B — component-free, raw HTML for creative control."*
+
+### 3b — Announce before writing
+
+Before writing any file, output a build brief:
 
 ```
-Building: <page name> (<route>)
-State:     <fields and types, or "none">
-Mutations: <list, or "none">
-Actions:   <list with brief description, or "none">
-Server:    <fetcher names and what they fetch, or "none">
-View:      <key sections / landmarks>
-Files:     <list of files that will be written>
+Building:   <page name> (<route>)
+Mode:       A — components first | B — creative override (raw HTML, reason: ...)
+State:      <fields and types, or "none">
+Mutations:  <list, or "none">
+Actions:    <list with brief description, or "none">
+Server:     <fetcher names and what they fetch, or "none">
+Components: <which UI components you will use, or "none — Mode B">
+View:       <key sections / landmarks>
+Files:      <list of files that will be written>
 ```
 
-Output this before making any tool calls. Do not skip it for "simple" pages — a one-liner is fine for simple pages, but always output something.
+One-liners are fine for simple pages, but always output something. **Declaring the mode upfront** makes the design intent explicit and prevents unnecessary component-reinvention warnings during review.
 
-### 3b — Write
+### 3c — Write
 
-Write each file using the **Write tool** — not `pulse_create_page`. This shows the user a readable diff. Before each file write, output a one-line status (present-progressive, no tick — the work hasn't happened yet):
+Write each file using the **Write tool** — not `pulse_create_page`. This shows the user a readable diff. Before each file write, output a one-line status (present-progressive):
 
 ```
 Writing src/pages/my-page.js...
@@ -63,9 +192,11 @@ After the Write tool completes, call `pulse_create_page(name)` to register the p
 ✓ src/pages/my-page.js written and registered.
 ```
 
-**Rule: never output `✓` before the tool call that confirms the result. Use present-progressive (`Writing...`, `Running...`, `Checking...`) for pre-tool announcements.**
+### 3d — Suggest (optional but recommended)
 
-If multiple files are needed (spec + shared component, spec + test stub, etc.), announce and write them one at a time with a status line before each.
+After writing the first draft, call `pulse_suggest(content)` before running the hard validator. It catches obvious omissions collaboratively — a second opinion, not a gate.
+
+**Rule: never output `✓` before the tool call that confirms the result.**
 
 ---
 
@@ -74,7 +205,7 @@ If multiple files are needed (spec + shared component, spec + test stub, etc.),
 Run `pulse_validate` on the spec file.
 
 - **If it passes:** output `✓ Validation clean — checking browser...` and continue.
-- **If it fails:** fix every error and every warning, then re-run. Repeat until clean. Do not continue until validation is clean.
+- **If it fails:** fix every error and every warning, then re-run. Repeat until clean.
 
 ---
 
@@ -88,63 +219,82 @@ Do this before every screenshot, console check, or visual inspection. Never debu
 
 **Run `/verify` now — as soon as the first build is working.** Do not defer it to the end. Do not execute these steps manually.
 
-`/verify` is the canonical implementation of phases 4–7: it validates, screenshots, runs Lighthouse (desktop + mobile), runs the performance trace (LCP + CLS), checks console errors, runs `pulse_review`, and — critically — **writes the `.pulse-verified` stamp** at the end. Running the steps manually without writing the stamp will cause the stop hook to block.
+`/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:
+
+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
+3. `/verify` — Lighthouse desktop + mobile (100/100/100) + CLS 0.00 + `pulse_review`
+
+**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 (all must be met before continuing to Phase 6):
+Pass gates:
 - Screenshot: no layout or rendering issues
+- 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
-- Lighthouse mobile: same pass bar
-- **CLS: 0.00** — any layout shift is a blocker; fix it before proceeding
-- LCP: measured and reported; flag any fixable insight (render-blocking resources, large image delay)
+- Lighthouse mobile: same
+- **CLS: 0.00** — any layout shift is a blocker
 - No console errors
 
-**If any gate fails:** fix the issue and run `/verify` again. Repeat until all gates pass.
+**If any gate fails:** fix and run `/verify` again.
 
-Output after passing: `✓ Verified — writing tests...`
+**Troubleshooting browser profile lock:** If you see "browser already running" or chrome profile errors, another session is using the same Chrome profile. This is a `chrome-devtools-mcp` limitation — only one session can use the profile at a time. Ask the user to close other Claude sessions, or wait for the other session to finish.
+
+**CSS-only changes after verification:** If you've already run `/verify` successfully and the user asks for minor CSS tweaks (margins, colours, spacing), you must run the full `/verify` workflow again — the stop hook checks the file mtime against the stamp. There is no lighter CSS-only check. This is by design: even CSS changes can affect CLS, colour contrast, or readability.
 
 ---
 
-## Phase 6 — Tests (pass gate)
+## Phase 6 — Tests (pass gate, Tier 2+)
 
 Write tests for every spec you created or modified. At minimum:
 
-- Each mutation as a pure function (assert the returned state shape)
+- Each mutation as a pure function
 - View renders expected HTML landmarks
 - Any utility functions defined in the spec
 
-Run the tests. Fix every failure. Repeat until all tests pass.
-
-Output after passing: `✓ Tests passing — ready for review.`
+Run the tests. Fix every failure.
 
 ---
 
-## Phase 7 — Review
+## Phase 7 — Review (Tier 2+)
 
-**Only invoke the Review Agent after all of the above gates have passed.** The reviewer must receive: passing validation, passing Lighthouse (desktop + mobile), and passing tests. Never hand off code that has not cleared every gate.
+Only invoke `pulse_review` after phases 4–6 all pass. It checks the code for correctness, security, accessibility, DRY violations, and checklist adherence.
 
-The Review Agent checks the code for correctness, security, accessibility, DRY violations, and adherence to the checklist. It returns a list of issues.
-
-> Note: `/verify` includes the review step (`pulse_review`) — if you ran `/verify` and it passed cleanly, the Review Agent has already run. You do not need to invoke it again separately.
+> Note: `/verify` includes the review step — if you ran `/verify` and it passed, the Review Agent has already run.
 
 ---
 
-## Phase 8 — Fix review issues
+## Phase 8 — Fix review issues (Tier 3)
 
-Fix every issue raised by the Review Agent. If the fixes touch the spec or view, run `/verify` again — it re-runs validation, Lighthouse, the performance trace, console check, and review in one pass and writes a fresh stamp.
+Fix every issue raised. If fixes touch the spec or view, run `/verify` again.
 
-Only declare the task done after phase 8 is complete and all gates still pass.
+Only declare the task done after all gates still pass.
 
 ---
 
-## Gate summary
+## Summary
 
 ```
-Phase 1  Understand          (no gate — always run)
-Phase 2  Plan                gate: user confirmation
-Phase 3  Build               announce brief → write files (no gate, but always narrate)
-Phase 4  Validate            gate: pulse_validate clean
-Phase 5  Browser             gate: Lighthouse 100/100/100 (A/BP/SEO) + CLS 0.00, desktop + mobile
-Phase 6  Tests               gate: all tests pass
-Phase 7  Review Agent        (only reached after phases 4–6 all pass)
-Phase 8  Fix + re-verify     gate: all gates still pass
+New project / new page:
+  pulse_extract_inspiration  → (if user shares a URL or image) extract palette/layout/feel
+  pulse_intake               → capture real content, palette, vibe, anti-style
+  pulse_sketch               → choose 1 of 3 structural layout directions
+  pulse_intent               → get scaffold + guide list
+
+Targeted edit / bug fix:
+  pulse_intent    → (or skip entirely for trivial changes)
+
+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
 ```
+