@invisibleloop/pulse 0.14.1 → 0.15.0

package/src/agent/guide-examples.md

@@ -1,54 +1,332 @@
-## Example page — contact form
+## Pattern: action with validation and field errors
 
-```js
-import { nav, section, input, textarea, button, alert, container } from '@invisibleloop/pulse/ui'
-import { layout } from '../components/layout.js'
+The correct wiring for a form action with per-field validation errors. `onStart` captures `FormData` before `validate` runs (uncontrolled inputs — never use `data-event` to mirror input values). `validate: true` runs the spec's `validation` rules before `run`. Field errors are surfaced via `state.errors`.
 
+```js
 export default {
-  meta: {
-    title:  'Contact',
-    styles: ['/app.css', '/pulse-ui.css'],
-  },
+  route: '/signup',
+  meta: { title: 'Sign up', styles: ['/pulse-ui.css', '/app.css'] },
   state: {
-    status: 'idle',
+    status: 'idle',   // 'idle' | 'loading' | 'success' | 'error'
     errors: [],
+    fields: { name: '', email: '' },
+  },
+  validation: {
+    'fields.name':  { required: true, minLength: 2 },
+    'fields.email': { required: true, format: 'email' },
   },
   actions: {
-    send: {
+    submit: {
       onStart: (state, formData) => ({
-        status:  'loading',
-        name:    formData.get('name'),
-        email:   formData.get('email'),
-        message: formData.get('message'),
+        status: 'loading',
+        errors: [],
+        fields: { name: formData.get('name') ?? '', email: formData.get('email') ?? '' },
       }),
+      validate: true,
       run: async (state, serverState, formData) => {
-        const res = await fetch('/api/contact', { method: 'POST', body: formData })
-        if (!res.ok) throw new Error(await res.text())
+        const res = await fetch('/api/signup', { method: 'POST', body: formData })
+        if (!res.ok) {
+          let message = `Request failed: ${res.status}`
+          try { const j = await res.json(); message = j.message || j.error || message } catch {}
+          throw new Error(message)
+        }
         return await res.json()
       },
-      onSuccess: (state, result) => ({ status: 'success' }),
-      onError:   (state, err)    => ({
+      onSuccess: (state, result) => ({
+        status: 'success',
+        _toast: { message: 'Account created!', variant: 'success' },
+      }),
+      onError: (state, err) => ({
         status: 'error',
         errors: err?.validation ?? [{ message: err.message }],
+        _toast: { message: 'Please check the form', variant: 'error' },
       }),
     },
   },
-  view: (state) => layout(`
-    ${container({ content: `
-      ${section({ title: 'Contact Us', subtitle: 'We will get back to you within 24 hours.' })}
+  view: (state) => `
+    <main id="main-content">
       ${state.status === 'success'
-        ? alert({ type: 'success', message: 'Message sent!' })
-        : `<form data-action="send" class="u-flex u-flex-col u-gap-4">
-            ${grid({ cols: 2, gap: 'md', content: `
-              ${input({ name: 'name',  label: 'Name',  placeholder: 'Your name',       required: true })}
-              ${input({ name: 'email', label: 'Email', type: 'email', placeholder: 'you@example.com', required: true })}
-            ` })}
-            ${textarea({ name: 'message', label: 'Message', rows: 5, required: true })}
-            ${state.errors.length ? alert({ type: 'error', message: state.errors[0].message }) : ''}
-            ${button({ label: state.status === 'loading' ? 'Sending…' : 'Send', type: 'submit', variant: 'primary', fullWidth: true })}
+        ? `<p>You're signed up.</p>`
+        : `<form data-action="submit" class="u-flex u-flex-col u-gap-4">
+            ${input({ name: 'name',  label: 'Name',  value: state.fields.name,
+              error: state.errors.find(e => e.field === 'fields.name')?.message })}
+            ${input({ name: 'email', label: 'Email', type: 'email', value: state.fields.email,
+              error: state.errors.find(e => e.field === 'fields.email')?.message })}
+            ${button({ label: state.status === 'loading' ? 'Saving…' : 'Sign up',
+              type: 'submit', variant: 'primary',
+              attrs: state.status === 'loading' ? 'aria-busy="true" disabled' : '' })}
           </form>`
       }
-    ` })}
-  `),
+    </main>
+  `,
+}
+```
+
+**Key points:**
+- `onStart` captures `FormData` into state so field values survive the re-render
+- `validate: true` runs before `run()` — validation errors arrive in `onError` as `err.validation`
+- Always check `err?.validation` first; fall back to `err.message`
+- `aria-busy="true"` on the submit button while loading — spinner alone is not sufficient for accessibility
+- `res.ok` checked before parsing; never use `await res.text()` as an error message
+
+---
+
+## Pattern: server data with dynamic route and missing-data fallback
+
+The correct pattern for a dynamic route that loads data from a server fetcher. Always add `onViewError` — a missing or invalid param must not produce a 500.
+
+```js
+import { md }   from '@invisibleloop/pulse/md'
+import { prose } from '@invisibleloop/pulse/ui'
+
+const post = md('content/blog/:slug.md')
+
+export default {
+  route: '/blog/:slug',
+  meta: {
+    title:       async (ctx) => (await post(ctx)).frontmatter.title ?? 'Post not found',
+    description: async (ctx) => (await post(ctx)).frontmatter.description ?? '',
+  },
+  server: { post },
+  view: (state, server) => `
+    <main id="main-content">
+      <h1>${server.post.frontmatter.title}</h1>
+      ${prose({ content: server.post.html })}
+    </main>
+  `,
+  onViewError: (err) => `
+    <main id="main-content">
+      <p>Post not found. <a href="/blog">Back to blog</a></p>
+    </main>
+  `,
+}
+```
+
+**Key points:**
+- Call the same `md()` fetcher in both `meta` and `server` — it caches on `ctx._mdCache`, file is read once
+- `onViewError` is required on any dynamic route where the view can receive null/missing data
+- For database-backed routes: validate `ctx.params.id` before use; return a 404-equivalent via `onViewError` if not found
+- Use `?.` and `??` throughout the view when server data can be null
+
+---
+
+## Pattern: streaming SSR with scoped fetchers
+
+Use streaming when a page has slow data (feeds, lists, analytics) and you want the shell to paint instantly. `scope` prevents slow fetchers from blocking the shell.
+
+```js
+export default {
+  route: '/dashboard',
+  meta: { title: 'Dashboard', styles: ['/pulse-ui.css', '/app.css'] },
+  state: {},
+  server: {
+    user:  async (ctx) => db.users.findByCookie(ctx.cookies.session),  // fast
+    feed:  async () => fetchFeed(),   // slow
+    ads:   async () => fetchAds(),    // slow
+  },
+  stream: {
+    shell:    ['header'],
+    deferred: ['feed'],
+    scope: {
+      header: ['user'],        // shell sends as soon as 'user' resolves
+      feed:   ['feed', 'ads'], // deferred sends when both resolve
+    },
+  },
+  view: {
+    header: (state, server) => `
+      <header>
+        <p>Hello, ${server.user?.name ?? 'Guest'}</p>
+      </header>
+    `,
+    feed: (state, server) => `
+      <ul>
+        ${server.feed.map(item => `<li data-key="${item.id}">${item.title}</li>`).join('')}
+      </ul>
+    `,
+  },
+}
+```
+
+**Key points:**
+- `view` must be a named object of functions — not a single function — when using `stream`
+- `scope` is optional but important: without it the shell waits for all fetchers
+- `data-key` on list items enables O(1) keyed reconciliation when the list updates client-side
+- A fetcher listed in `scope.header` but slow will delay the shell — keep shell fetchers fast
+
+---
+
+## Pattern: global store subscription and `_storeUpdate`
+
+Use the global store for data shared across pages (user session, cart, theme). Read store data via `spec.store`; push changes back with `_storeUpdate` from `onSuccess`.
+
+```js
+// Page that reads from store and updates it on save
+export default {
+  route: '/settings',
+  store: ['user', 'settings'],   // declares which store keys this page subscribes to
+  meta: { title: 'Settings', styles: ['/pulse-ui.css', '/app.css'] },
+  state: { status: 'idle' },
+  actions: {
+    save: {
+      onStart: (state, formData) => ({ status: 'loading' }),
+      run: async (state, serverState, formData) => {
+        const theme = formData.get('theme')
+        const res = await fetch('/api/settings', {
+          method: 'POST',
+          body: JSON.stringify({ theme }),
+          headers: { 'Content-Type': 'application/json' },
+        })
+        if (!res.ok) throw new Error(`Save failed: ${res.status}`)
+        return { theme }
+      },
+      onSuccess: (state, { theme }) => ({
+        status: 'idle',
+        _storeUpdate: { settings: { theme } },  // merged into store; all subscribed pages re-render
+        _toast: { message: 'Saved', variant: 'success' },
+      }),
+      onError: (state, err) => ({
+        status: 'error',
+        _toast: { message: err.message, variant: 'error' },
+      }),
+    },
+  },
+  view: (state, server) => `
+    <main id="main-content">
+      <form data-action="save" class="u-flex u-flex-col u-gap-4">
+        ${select({ name: 'theme', label: 'Theme',
+          options: [{ value: 'dark', label: 'Dark' }, { value: 'light', label: 'Light' }],
+          value: server.settings?.theme ?? 'dark' })}
+        ${button({ label: state.status === 'loading' ? 'Saving…' : 'Save', type: 'submit', variant: 'primary' })}
+      </form>
+    </main>
+  `,
+}
+```
+
+**Key points:**
+- `spec.store` declares subscriptions — store data appears in the view's `server` argument
+- `_storeUpdate` is stripped from page state and merged into the store — do not store it
+- All pages subscribed to the affected store keys re-render without a server round-trip
+- Never use a full page reload to propagate shared state changes — use `_storeUpdate`
+
+---
+
+## Pattern: guard with auth redirect
+
+Use `guard` to protect routes. It runs before server fetchers. Return `{ redirect }` to send unauthenticated users elsewhere.
+
+```js
+export default {
+  route: '/account',
+  meta: { title: 'Account', styles: ['/pulse-ui.css', '/app.css'] },
+  server: {
+    user: async (ctx) => db.users.find(ctx.cookies.session),
+  },
+  guard: async (ctx) => {
+    const user = await db.users.findByCookie(ctx.cookies.session)
+    if (!user) return { redirect: '/login?next=/account' }
+  },
+  state: {},
+  view: (state, server) => `
+    <main id="main-content">
+      <h1>Hello, ${server.user?.name}</h1>
+    </main>
+  `,
+}
+```
+
+**Key points:**
+- `guard` runs before server fetchers — returning `{ redirect }` short-circuits the entire request
+- Return nothing (or `undefined`) to allow the request through
+- For shared auth logic, extract to a helper and call it from `guard` on each protected spec
+- `ctx.cookies` is available in `guard` — check session cookies here, not in the view
+
+---
+
+## Pattern: keyed list with client mutations
+
+Use `data-key` on repeated elements whenever a list can be reordered, filtered, or have items added/removed client-side.
+
+```js
+export default {
+  route: '/todos',
+  meta: { title: 'Todos', styles: ['/pulse-ui.css', '/app.css'] },
+  state: {
+    items: [
+      { id: 1, text: 'Buy milk', done: false },
+      { id: 2, text: 'Write spec', done: false },
+    ],
+    filter: 'all',  // 'all' | 'active' | 'done'
+  },
+  mutations: {
+    toggle: (state, e) => {
+      const id = Number(e.target.closest('[data-id]').dataset.id)
+      return { items: state.items.map(i => i.id === id ? { ...i, done: !i.done } : i) }
+    },
+    setFilter: (state, e) => ({ filter: e.target.value }),
+  },
+  view: (state) => {
+    const visible = state.items.filter(i =>
+      state.filter === 'all' ? true : state.filter === 'done' ? i.done : !i.done
+    )
+    return `
+      <main id="main-content">
+        <ul>
+          ${visible.map(item => `
+            <li data-key="${item.id}" data-id="${item.id}">
+              <button data-event="toggle" aria-pressed="${item.done}">${item.text}</button>
+            </li>
+          `).join('')}
+        </ul>
+        <select data-event="change:setFilter" aria-label="Filter todos">
+          <option value="all">All</option>
+          <option value="active">Active</option>
+          <option value="done">Done</option>
+        </select>
+      </main>
+    `
+  },
+}
+```
+
+**Key points:**
+- `data-key` must be on every sibling element in the container — mixed keyed/unkeyed falls back to position matching
+- Use `e.target.closest('[data-id]')` in mutations — never assume `e.target` is the element with the attribute
+- `aria-pressed` on toggle buttons communicates state to screen readers
+- Mutations are pure — no fetch, no DOM access, return partial state only
+
+---
+
+## Pattern: persist — what belongs and what doesn't
+
+`persist` survives page reload via `localStorage`. Only serialisable, user-owned state that should survive a refresh belongs here.
+
+```js
+export default {
+  route: '/builder',
+  meta: { title: 'Builder', styles: ['/pulse-ui.css', '/app.css'] },
+  state: {
+    // ✓ persist these — user-owned, meaningful across sessions
+    items:      [],
+    activeStep: 0,
+    draft:      { name: '', description: '' },
+
+    // ✗ do NOT persist these — ephemeral UI state
+    status:     'idle',
+    errors:     [],
+    modalOpen:  false,
+  },
+  persist: ['items', 'activeStep', 'draft'],
+  mutations: {
+    nextStep: (state) => ({ activeStep: Math.min(state.activeStep + 1, 3) }),
+    prevStep: (state) => ({ activeStep: Math.max(state.activeStep - 1, 0) }),
+  },
+  view: (state) => `<main id="main-content">…</main>`,
 }
 ```
+
+**Key points:**
+- Never persist `status`, `errors`, loading flags, or modal open state — these are session-only
+- Never persist large objects or arrays that could grow unbounded — `localStorage` has a ~5MB limit
+- Restored persist values override spec defaults on mount and trigger a re-render if different
+- `persist` keys must exist in `state` — persisting a key not in state has no effect

package/src/agent/guide-styles.md

@@ -89,6 +89,15 @@ meta: {
 
 **Colour tokens:** `--ui-bg`, `--ui-surface`, `--ui-surface-2`, `--ui-border`, `--ui-text`, `--ui-muted`, `--ui-accent`, `--ui-accent-hover`, `--ui-accent-dim`, `--ui-accent-text`, `--ui-green`, `--ui-red`, `--ui-yellow`, `--ui-blue`, `--ui-radius`, `--ui-radius-sm`, `--ui-font`, `--ui-font-display`, `--ui-mono`. Never hardcode hex values — override the tokens.
 
+> **⚠ `--ui-muted` contrast on warm/light palettes** — The default `--ui-muted` value (`#60607a` in light theme) achieves 4.5:1 on the default white `--ui-bg`. When you set a warm or coloured background (`--bg: #f5e6d3` etc.) the luminance difference shrinks and `--ui-muted` can drop below the WCAG AA threshold of 4.5:1. **Always override `--muted` when changing `--bg`**, and run `pulse_check_contrast` immediately after writing your `theme.css`. A common failure mode: stat labels, nav links, and feature descriptions all use `--ui-muted` and will fail contrast silently if this token is not rechecked against your actual background colour.
+
+> **⚠ `section--dark` in light theme** — `section({ variant: 'dark' })` uses `--ui-surface-2` as its background, which in the default light theme resolves to `#f0f0f8` — a light grey, not a dark background. The framework now auto-corrects this via a `[data-theme="light"] .ui-section--dark` override (navy `#1a1a2e`), and ghost buttons inside it get automatic light-text treatment. If you use a custom `--surface-2` override in your theme, set `--ui-dark-bg` and `--ui-dark-text` to pin the dark section to specific values:
+> ```css
+> [data-theme="light"] { --ui-dark-bg: #1a1a2e; --ui-dark-text: #e8e0d0; }
+> ```
+
+> **Ghost buttons on dark backgrounds** — use `variant: 'ghost-light'` instead of `variant: 'ghost'` whenever the button sits on a dark background (custom hero div, `section--dark`, navy sections). `ghost-light` renders white text with a subtle white border, maintaining 4.5:1 contrast regardless of the surrounding theme. `ghost` uses `--ui-muted` text which fails on dark backgrounds in light theme.
+
 **Display font token:** `--ui-font-display` is used for hero titles and section headings. By default it inherits `--ui-font`. Override it separately to get a display/heading face that differs from body text:
 ```css
 /* app.css */
@@ -219,6 +228,12 @@ createServer(specs, {
 
 > **picsum CDN note:** `picsum.photos` redirects image requests through `fastly.picsum.photos`. You must whitelist **both** domains — whitelisting only `https://picsum.photos` will still block the actual image bytes and the browser error will point to the `fastly.picsum.photos` URL, which is confusing to debug.
 
+> **⚠ Unsplash and third-party cookies — Lighthouse Best Practices failure:** `images.unsplash.com` sets tracking cookies (`azk`, `azk-ss`) on every image request. These are classified as third-party cookies and cause Lighthouse Best Practices to drop to ~77, failing the 100 pass bar. **For production builds, download images locally instead of referencing Unsplash URLs directly.** Use `curl` to save images to `public/images/`:
+> ```bash
+> curl -sL "https://images.unsplash.com/photo-ID?w=900&q=85" -o public/images/hero.jpg
+> ```
+> Then reference `/images/hero.jpg` in your spec. This also improves performance (no external DNS lookup) and avoids rate limiting. `picsum.photos` does **not** set tracking cookies and is safe to use via CDN for prototypes.
+
 Without this, external images will be blocked in production and Lighthouse will flag a Best Practices failure. Use the same pattern for other external resource types (`media-src` for video, `connect-src` for fetch/XHR to external APIs).
 
 For multiple weights or italic variants, separate them with a semicolon in the URL:

package/src/agent/guide-templates.md

@@ -89,9 +89,12 @@ Run `pulse_intake` before presenting the confirmation. It collects the product d
 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)"
+9. "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'll extract the design intent before we start."
 
 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.
 
+**Question 9 is not optional.** Always ask it. If the user provides an image in `public/intake/`, call `pulse_extract_inspiration` on it before calling `pulse_intake`. If they provide a URL, call `pulse_extract_inspiration` with the URL. If they say no or skip it, proceed without — but always ask.
+
 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.

package/src/agent/identity.md

@@ -51,7 +51,8 @@ Every build task follows a fixed sequence of phases with explicit pass gates. Fe
 2. **Plan** — present your plan, wait for user confirmation (skip only for trivially small tasks)
 3. **Build** — write the spec and related files
 4. **Validate** — `pulse_validate` must be clean before continuing
-5. **Browser** — screenshot + Lighthouse desktop + Lighthouse mobile, all 100/100/100 before continuing
+5. **Design approval** *(new builds only)* — take a screenshot, show the user, **wait for their go-ahead on layout and direction** before running any slow checks. For edits/fixes, skip this.
+5. **Verify** — `pulse_design_review` → `pulse_layout_review` → Lighthouse desktop + mobile, all 100/100/100 before continuing
 6. **Tests** — write and run tests, all must pass before continuing
 7. **Review Agent** — invoke only after phases 4–6 all pass
 8. **Fix** — fix every review issue, re-run any affected gates

package/src/agent/skills/verify/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: verify
-description: "Run the full verification loop on the current page or the page specified in $ARGUMENTS. If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify the most recently edited spec file from context. Use `pulse_validate` with the spec file content. If validation fails, report every error clearly and stop — do not proceed to screenshot until the spec is valid."
+description: "Run the full verification loop on the current page or the page specified in $ARGUMENTS. If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify the most recently edited spec file from context."
 ---
 
 # Verify
 
 Run the full verification loop on the current page or the page specified in $ARGUMENTS.
 
+**Output style:** be terse throughout. One sentence per step. Do not quote raw tool output — summarise findings only. Reserve detail for failures that need explaining.
+
 ## Steps
 
 ### 1. Identify the target
@@ -15,53 +17,87 @@ If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify
 
 ### 2. Validate the spec
 
-Use `pulse_validate` with the spec file content. If validation fails, report every error clearly and stop — do not proceed to screenshot until the spec is valid.
+Run `pulse_validate` on the spec file. Report clean or list errors. Stop if there are errors — do not continue until the spec is valid.
 
 ### 3. Check the dev server
 
-Use `pulse_fetch_page` to confirm the server is responding for the route. If it errors, use `pulse_restart_server` and retry once.
+Run `pulse_fetch_page` to confirm the server is responding. If it errors, run `pulse_restart_server` and retry once. Report HTTP status only — do not quote the HTML body.
+
+**If the response has no `X-Pulse` header**, the wrong server is running on that port — stop and tell the user before continuing.
 
 ### 4. Screenshot
 
-Use the chrome-devtools navigate_page tool to load the page route, then take_screenshot to capture the result. Describe what you see — layout, content, any obvious rendering issues.
+Navigate to the page route with `mcp__chrome-devtools__navigate_page`, then take a screenshot with `mcp__chrome-devtools__take_screenshot`. Describe what you see in 2–3 plain sentences — layout structure, visual tone, key sections. Do not list features or code details.
+
+### 4a. Design approval gate *(new builds only)*
+
+**If `pulse_intake` ran earlier in this session** (i.e. this is a new page or site, not an edit or bug fix):
+
+1. Show the screenshot to the user.
+2. Ask: *"Happy with the layout and direction, or any changes before I run Lighthouse?"*
+3. **Stop and wait for their response.** Do not proceed to step 4b or Lighthouse until the user explicitly approves.
+
+If the user requests changes: make edits, restart the server, take a new screenshot, describe what changed, ask again. Repeat until approved. No Lighthouse between design rounds.
+
+**For edits, bug fixes, or "add X to existing Y"** — skip this step and go straight to 4b.
+
+### 4b. Design review *(if `pulse_intake` ran)*
+
+Run `pulse_design_review`. Work through every signal it returns. Fix any Fail before continuing. Report pass/fail count only — do not quote the full output.
+
+### 4c. Layout review
+
+Run `pulse_layout_review` with the page URL. It checks 390/768/1280px viewports for overflow, broken images, and collapsed sections. Fix any failures before continuing. Report pass or list failures only.
+
+### 5. Production build
+
+Run `pulse_build` to start the production server on port 3001. Tell the user: "Building for production — ~30s…" before calling it.
+
+### 6. Lighthouse — desktop
+
+Navigate to `http://localhost:3001/<route>` with `mcp__chrome-devtools__navigate_page`, then run `mcp__chrome-devtools__lighthouse_audit` with `device: "desktop"`.
+
+**Pass bar: Accessibility, Best Practices, and SEO must all be 100.** Report scores as a single line, e.g. `Accessibility 100 · Best Practices 100 · SEO 100`. If any score is below 100, identify the failing audit(s), fix, and restart from step 2.
+
+### 7. Lighthouse — mobile
 
-### 5. Lighthouse — desktop
+Run `mcp__chrome-devtools__lighthouse_audit` with `device: "mobile"` against the same production URL. Same pass bar. Report scores as a single line. Fix failures and restart from step 2 if needed.
 
-Run lighthouse_audit on the route in desktop mode.
+**To inspect mobile layout** use `mcp__chrome-devtools__emulate` with `viewport: "390x844x2,mobile,touch"` — not `resize_page`. Reset with `"1440x900x1"` afterward.
 
-**Pass bar: Accessibility, Best Practices, and SEO must all be 100.** Report the actual scores. If any score is below 100, identify the failing audit(s), fix the issue, and restart from step 2.
+### 8. Performance
 
-### 6. Lighthouse — mobile
+Navigate to the page route, then run `mcp__chrome-devtools__performance_start_trace` with `reload: true` and `autoStop: true`. Report LCP and CLS as a single line, e.g. `LCP 73ms · CLS 0.00`. Flag any insight that identifies a fixable cause (render-blocking resources, large image delay). CLS must be 0.00.
 
-Run lighthouse_audit on the same route in mobile mode.
+### 9. Console errors
 
-**Same pass bar: all three categories must be 100.** Report the actual scores. If any score is below 100, fix and restart from step 2.
+Run `mcp__chrome-devtools__list_console_messages` filtered to errors and warnings. Report count only if clean. List any errors found.
 
-### 7. Performance
+### 10. Code review
 
-Navigate to the page route, then run performance_start_trace with `reload: true` and `autoStop: true`. Report LCP and CLS. Flag any LCP insight that suggests a fixable problem (render-blocking resources, large image load delay, etc.).
+Run `pulse_review` with the absolute path to the spec file. Work through every item in the checklist it returns. Fix every issue before proceeding. Report pass or list what was fixed — do not quote the full review output.
 
-### 8. Console errors
+### 11. Close the browser
 
-Use list_console_messages — report any errors or unexpected warnings.
+Run `mcp__chrome-devtools__list_pages`, then `mcp__chrome-devtools__close_page` for every page ID returned. `pageId` must be a JSON number, not a string.
 
-### 9. Code review
+### 12. Write verification stamp
 
-Use `pulse_review` to switch into reviewer mode. Read the spec against the checklist in `.github/instructions/pulse-checklist.instructions.md`. Work through every item. Fix anything that fails before proceeding.
+```bash
+date +%s > .pulse-verified
+```
 
-### 10. Close the browser
+**This must be the last write before stopping.** Do not edit any spec file after writing the stamp.
 
-Use list_pages to get all open pages, then call close_page for every page ID returned.
+### 13. Report
 
-### 11. Report
+One short paragraph covering: validation, Lighthouse desktop/mobile scores, LCP, CLS, console, review. Flag anything that needed fixing. No raw tool output.
 
-Summarise:
-- Validation: pass or fail (with errors if any)
-- Visual: what was visible in the screenshot
-- Lighthouse desktop: scores for all three categories
-- Lighthouse mobile: scores for all three categories
-- Performance: LCP and CLS values, any flagged insights
-- Console: any errors
-- Review: pass or issues found and fixed
+**Pass bar — all must be met:**
+- Validation: clean
+- Lighthouse desktop: Accessibility, Best Practices, SEO all 100
+- Lighthouse mobile: same
+- CLS: 0.00
+- Console: no errors
 
-Only confirm the page is good when validation passes, both Lighthouse runs are 100/100/100, CLS is 0.00, and there are no console errors. Otherwise, fix and run `/verify` again.
+If any gate fails, fix and run `/verify` again.