@invisibleloop/pulse 0.7.3 → 0.8.1

package/CLAUDE.md

@@ -336,6 +336,39 @@ Always target `[data-theme="light"]` when overriding colours for the light theme
 
 If a colour must apply in both themes, set it in both `:root` and `[data-theme="light"]`.
 
+## CSS File Responsibilities
+
+There are two CSS files and they have distinct roles — do not mix them:
+
+| File | Purpose | Allowed content |
+|---|---|---|
+| `public/theme.css` | Token definitions — hex values, raw colours, font URLs | Hex values, `rgb()`, raw values, `@font-face`, `@import` |
+| `app.css` (or per-page) | Layout and component overrides | `var()` tokens **only** — no hex, no raw colour values |
+
+**`app.css` must never contain hex values or raw colour values.** A lint hook enforces this. If you need to define or override a colour token, put it in `public/theme.css` and reference it via `var()` in `app.css`.
+
+```css
+/* public/theme.css — hex values live here */
+[data-theme="light"] {
+  --color-accent: #e25;
+  --color-bg: #ffffff;
+}
+
+/* app.css — only var() references */
+.hero {
+  background: var(--color-bg);
+  color: var(--color-accent);
+}
+```
+
+Load both files via `meta.styles`, theme first:
+
+```js
+meta: {
+  styles: ['/pulse-ui.css', '/theme.css', '/app.css'],
+}
+```
+
 ## HTTP Response Behaviour
 
 - **Full page request** — SSR HTML with hydration bootstrap

package/docs/public/docs.css

@@ -683,6 +683,7 @@ a:hover {
   font-weight: 700;
   letter-spacing: -0.02em;
   margin: 0.75rem 0 1.25rem;
+  text-align: center;
 }
 
 .ai-first-lead {
@@ -691,6 +692,9 @@ a:hover {
   line-height: 1.75;
   max-width: 72ch;
   margin-bottom: 3rem;
+  text-align: center;
+  margin-left: auto;
+  margin-right: auto;
 }
 
 .ai-cols {
@@ -751,10 +755,10 @@ a:hover {
 }
 
 .ai-col-list li::before {
-  content: "–";
+  content: "✓";
   position: absolute;
   left: 0;
-  color: var(--muted-2);
+  color: var(--accent);
 }
 
 .ai-col--pulse .ai-col-list li {

package/docs/src/pages/home.js

@@ -37,7 +37,7 @@ export default {
   route: '/',
   meta: {
     title: 'Pulse — The spec-first web framework',
-    description: 'Pulse is a server-first web framework with streaming SSR, zero client JS by default, and Lighthouse 100 built into the architecture. One spec format. One way to build. Production quality by design.',
+    description: 'Pulse is a server-first Node.js framework with zero runtime dependencies. One spec object per page — server data, state, mutations, and view in plain JS. Streaming SSR, security headers, and production caching are enforced by the architecture.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
   state: {},
@@ -67,9 +67,9 @@ export default {
           </svg>
         </div>
         <div class="hero-badge">v${version} — EARLY ACCESS</div>
-        <p class="hero-kicker">A Node.js framework for building server-rendered web apps</p>
-        <h1 class="hero-title">Describe the outcome. Pulse guarantees it.</h1>
-        <p class="hero-subtitle">One spec object per page — server data, state, mutations, and view in plain JS. Streaming SSR, security headers, and production caching are enforced by the framework, not left to configuration.<br><strong>Designed for AI agents.</strong></p>
+        <p class="hero-kicker">A server-first Node.js framework. Zero runtime dependencies.</p>
+        <h1 class="hero-title">One spec. One way to build. Production quality by design.</h1>
+        <p class="hero-subtitle">Each page is a single plain JS object — server data, client state, mutations, and view co-located in one place. Streaming SSR, security headers, and production caching are enforced by the framework, not left to configuration.<br><strong>Designed for AI agents. Simple enough to write yourself.</strong></p>
         <div class="hero-ctas">
           <a href="/getting-started" class="btn-primary">Get Started</a>
           <a href="/spec" class="btn-secondary">Read the Spec</a>
@@ -94,30 +94,30 @@ export default {
         <div class="home-stat-divider"></div>
         <div class="home-stat">
           <span class="home-stat-value">100</span>
-          <span class="home-stat-label">Lighthouse score</span>
+          <span class="home-stat-label">Lighthouse score, by design</span>
         </div>
       </section>
 
       <section class="how">
         <div class="how-inner">
-        <h2 class="section-label">How it works</h2>
+        <h2 class="section-label">The idea</h2>
         <div class="how-steps">
           <div class="how-step">
             <div class="how-step-num">1</div>
-            <h3>Write a spec</h3>
-            <p>Everything for a page lives in one object: server data, state, mutations, view. One format, no conventions to learn.</p>
+            <h3>The spec is the page</h3>
+            <p>Everything a page needs lives in one plain JS object — server data, client state, mutations, and view. One format, no split files, no hidden conventions.</p>
           </div>
           <div class="how-connector" aria-hidden="true"></div>
           <div class="how-step">
             <div class="how-step-num">2</div>
-            <h3>Validate automatically</h3>
-            <p>The schema enforces a single, correct structure. Either the spec is valid, or it’s rejected — no ambiguity, no runtime surprises.</p>
+            <h3>The schema is the contract</h3>
+            <p>Every spec is validated at startup. Either it's correct or it's rejected — no ambiguity, no misconfiguration that surfaces later in production.</p>
           </div>
           <div class="how-connector" aria-hidden="true"></div>
           <div class="how-step">
             <div class="how-step-num">3</div>
-            <h3>Production quality, built in</h3>
-            <p>Streaming SSR, security headers, and immutable caching come from the framework — not your config. Follow the spec, and the results follow.</p>
+            <h3>The framework is the guarantee</h3>
+            <p>Streaming SSR, security headers, and production caching come from the architecture. You write the product logic. The framework ships the quality.</p>
           </div>
         </div>
         </div>
@@ -126,8 +126,8 @@ export default {
       <section class="home-code">
         <div class="home-code-inner">
           <div class="home-code-header">
-            <h2>Everything in one object</h2>
-            <p>Server data, state, mutations, and view are co-located. No split files. No hidden conventions. The spec <strong>is</strong> the page.</p>
+            <h2>Everything a page needs. Nothing it doesn't.</h2>
+            <p>Server fetchers, client state, mutations, and view are co-located in one object. No split files. No magic exports. The spec <strong>is</strong> the page — readable, predictable, complete.</p>
           </div>
           <div class="home-code-block">
             ${codeWindow({ content: exampleSpec, filename: 'src/pages/dashboard.js', lang: 'JavaScript' })}
@@ -136,26 +136,26 @@ export default {
       </section>
 
       <section class="ai-first">
-        <div class="section-label">Why Pulse + AI</div>
-        <h2 class="ai-first-title">Designed for AI agents. Enforced by the framework.</h2>
-        <p class="ai-first-lead"><strong>Traditional frameworks</strong> were built for humans — multiple valid patterns, optional decisions, enough surface area for output to drift. Pulse is different.</p>
+        <div class="section-label">AI + Pulse</div>
+        <h2 class="ai-first-title">The constraint is the point. For humans and agents&nbsp;alike.</h2>
+        <p class="ai-first-lead">Pulse was designed around a simple observation: when there is only one correct way to build a page, every page is built correctly — whether you wrote it or an AI did. The spec format is the advantage. The schema is the enforcement.</p>
         <div class="ai-cols">
           <div class="ai-col">
-            <h3 class="ai-col-title ai-col-title--bad">AI + existing frameworks</h3>
+            <h3 class="ai-col-title">For developers</h3>
             <ul class="ai-col-list">
-              <li>Multiple valid patterns per page — the agent picks one, the next picks another.</li>
-              <li>Security headers, SSR config, and caching are optional decisions the agent can miss.</li>
-              <li>Output drifts over time as different agents make different choices.</li>
-              <li>Reviewing AI output requires knowing every pattern it could have used.</li>
+              <li>One format to learn — server, state, mutations, view in one place.</li>
+              <li>Production quality is the starting point, not a final audit.</li>
+              <li>Specs are short, self-contained, and easy to review.</li>
+              <li>Nothing to misconfigure — the framework doesn't give you the choice.</li>
             </ul>
           </div>
           <div class="ai-col ai-col--pulse">
-            <h3 class="ai-col-title ai-col-title--good">Pulse + AI enforces structure</h3>
+            <h3 class="ai-col-title ai-col-title--good">For AI agents</h3>
             <ul class="ai-col-list">
-              <li>One spec format per page.</li>
-              <li>Architecture enforces SSR, security, and caching.</li>
-              <li>Agents fill in the contract, never off-pattern.</li>
-              <li>Reading AI output means reading one JS object — nothing hidden.</li>
+              <li>One valid structure per page — agents can't pick the wrong pattern.</li>
+              <li>The schema rejects bad output at startup, not in production.</li>
+              <li>Security, SSR, and caching can't be accidentally omitted.</li>
+              <li>Consistent output across agents, sessions, and team members.</li>
             </ul>
           </div>
         </div>
@@ -164,7 +164,7 @@ export default {
       <section class="versus">
         <div class="section-label">How Pulse compares</div>
         <h2 class="versus-title">Constraints enforced. Not recommended.</h2>
-        <p class="versus-sub">Pulse enforces constraints and correctness out of the box; other frameworks leave it to the developer.</p>
+        <p class="versus-sub">Pulse enforces correctness out of the box. Other frameworks leave production quality to the developer.</p>
         <div class="versus-table-wrap table-sticky-col">
           <table class="versus-table">
             <thead>
@@ -195,13 +195,13 @@ export default {
               <tr>
                 <th scope="row">SSR out of the box</th>
                 <td class="v-yes">Streaming SSR, zero config</td>
-                <td class="v-partial">Yes, but client hydration adds JS overhead on every page</td>
+                <td class="v-partial">Yes, but client hydration adds JS on every page</td>
                 <td class="v-partial">Yes, but requires an adapter and client runtime on every page</td>
               </tr>
               <tr>
                 <th scope="row">Client JS shipped</th>
-                <td class="v-yes">~4 kB brotli (shared runtime, first visit)</td>
-                <td class="v-no">50-200 kB+ depending on features</td>
+                <td class="v-yes">~4 kB brotli on first visit; 0 kB on static pages</td>
+                <td class="v-no">50–200 kB+ depending on features used</td>
                 <td class="v-partial">~15 kB brotli</td>
               </tr>
               <tr>
@@ -224,7 +224,7 @@ export default {
               </tr>
               <tr>
                 <th scope="row">Production build step</th>
-                <td class="v-yes">None — <code>node server.js</code> is production</td>
+                <td class="v-yes">Server needs none — <code>node server.js</code> is production. Client bundles are optional.</td>
                 <td class="v-no">Required — <code>next build</code></td>
                 <td class="v-no">Required — <code>vite build</code></td>
               </tr>
@@ -243,24 +243,24 @@ export default {
               </svg>
             </div>
             <h2>Performance by design</h2>
-            <p>Pulse does not offer performance as an option — it enforces it structurally. A high Lighthouse score is the baseline. There is nothing to configure because there is nothing to get wrong.</p>
+            <p>Performance is not a Pulse feature — it is a structural outcome. A high Lighthouse score is the baseline. There is nothing to configure because the architecture makes the right choices automatically.</p>
           </div>
           <ul class="usp-points">
             <li>
               <strong>Fast LCP by design.</strong>
-              The shell renders and streams instantly. Deferred segments arrive as data resolves — no blocking, no flash.
+              The shell streams to the browser instantly. Deferred segments arrive as data resolves — no blocking, no flash, no placeholder juggling.
             </li>
             <li>
               <strong>~4 kB of JS on first visit.</strong>
-              The shared runtime is brotli-compressed and cached across all navigations. Subsequent pages cost 0.4–0.9 kB.
+              The shared runtime is brotli-compressed and cached across all navigations. Subsequent pages cost 0.4–0.9 kB. Static pages ship zero JS.
             </li>
             <li>
               <strong>Zero CLS.</strong>
-              The shell occupies the correct layout before data arrives. No placeholder juggling, no layout shift.
+              The shell occupies the correct layout before data arrives. No layout shift because there is no placeholder to replace.
             </li>
             <li>
               <strong>Immutable bundle caching.</strong>
-              Production bundles are content-hashed and served with <code>immutable, max-age=31536000</code>. Browsers cache them forever — deploys are instant for returning visitors.
+              Production bundles are content-hashed and served with <code>immutable, max-age=31536000</code>. Returning visitors pay no JS cost on deploy.
             </li>
           </ul>
         </div>
@@ -274,20 +274,20 @@ export default {
               </svg>
             </div>
             <h2>Safe by design</h2>
-            <p>Security is not a plugin or a checklist in Pulse — it is part of the response pipeline. Every page ships the headers most frameworks leave to the developer to remember.</p>
+            <p>Security is not a plugin in Pulse — it is part of the response pipeline. Every response ships the headers most frameworks leave to the developer to remember to add.</p>
           </div>
           <ul class="usp-points">
             <li>
               <strong>Security headers on every response.</strong>
-              <code>X-Frame-Options</code>, <code>X-Content-Type-Options</code>, <code>Referrer-Policy</code>, <code>Permissions-Policy</code>, <code>Cross-Origin-Opener-Policy</code> — all set automatically, including on 404 and 500 pages.
+              <code>X-Frame-Options</code>, <code>X-Content-Type-Options</code>, <code>Referrer-Policy</code>, <code>Permissions-Policy</code>, <code>Cross-Origin-Opener-Policy</code> — set automatically, including on 404 and 500 pages.
             </li>
             <li>
               <strong>Declarative state constraints.</strong>
-              <code>constraints</code> enforce min/max bounds on state after every mutation. The value can never go out of range regardless of what the client sends.
+              <code>constraints</code> enforce min/max bounds on state after every mutation. Values can never go out of range regardless of what the client sends.
             </li>
             <li>
               <strong>Co-located validation.</strong>
-              Validation rules live next to the state they guard. The agent can see what is being validated and why, in one place.
+              Validation rules live next to the state they guard. Easy to read, easy to review, impossible to misplace.
             </li>
             <li>
               <strong>Guard before data.</strong>
@@ -314,16 +314,16 @@ export default {
               The server is pure Node.js HTTP. No Express, no Fastify, no React. Nothing to add to <code>package.json</code> to run a production server.
             </li>
             <li>
-              <strong>No production build step.</strong>
-              <code>node server.js</code> is production. The build step is only needed to generate content-hashed client bundles — the server runs without it in dev.
+              <strong>No server build step.</strong>
+              <code>node server.js</code> is production. The optional build step generates content-hashed client bundles — the server runs without it.
             </li>
             <li>
               <strong>esbuild only in development.</strong>
-              The one dev dependency that compiles client bundles is esbuild. Fast, no plugins to configure, never part of the production runtime.
+              The one dev dependency that compiles client bundles is esbuild. Fast, zero plugins to configure, never part of the production runtime.
             </li>
             <li>
-              <strong>No framework upgrades breaking your app.</strong>
-              Because the spec is a plain JS object with no framework imports in page files, there is no framework API surface to break across versions.
+              <strong>No breaking upgrades.</strong>
+              Page files have no framework imports. The spec is a plain JS object. There is no framework API surface in your code to break across versions.
             </li>
           </ul>
         </div>
@@ -381,15 +381,15 @@ export default {
       </section>` : ''}
 
       <section class="home-cta">
-        <h2>The spec is the contract.<br>Your agent fills it in.</h2>
+        <h2>One format. Every page. Production ready.</h2>
         <ul class="home-cta-checks">
-          <li>Writes the spec</li>
-          <li>Validates against the schema</li>
-          <li>Checks Lighthouse — desktop and mobile</li>
-          <li>Runs the tests</li>
-          <li>Ships production quality</li>
+          <li>One spec object per page — always valid, always readable</li>
+          <li>Streaming SSR and security headers, zero configuration</li>
+          <li>100 Lighthouse built into the architecture</li>
+          <li>Works with AI agents — and without them</li>
+          <li>MIT licensed, zero runtime dependencies</li>
         </ul>
-        <p>MIT licensed and available now. Production quality is not the goal. It is the starting point.</p>
+        <p>Pulse is in early access. The goal is not to compete on features — it is to eliminate the class of problems that come from having too many of them.</p>
         <div class="home-cta-actions">
           <a href="/getting-started" class="btn-primary">Get Started</a>
           <a href="/spec" class="btn-secondary">Read the Spec</a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.7.3
+0.8.1

package/public/pulse-ui.css

@@ -40,6 +40,30 @@
 
   /* Touch target minimum per WCAG 2.5.5 */
   --ui-touch-min: 44px;
+
+  /* ── Spacing scale ── */
+  --ui-space-1:  0.25rem;   /*  4px */
+  --ui-space-2:  0.5rem;    /*  8px */
+  --ui-space-3:  0.75rem;   /* 12px */
+  --ui-space-4:  1rem;      /* 16px */
+  --ui-space-5:  1.25rem;   /* 20px */
+  --ui-space-6:  1.5rem;    /* 24px */
+  --ui-space-8:  2rem;      /* 32px */
+  --ui-space-10: 2.5rem;    /* 40px */
+  --ui-space-12: 3rem;      /* 48px */
+  --ui-space-16: 4rem;      /* 64px */
+  --ui-space-20: 5rem;      /* 80px */
+  --ui-space-24: 6rem;      /* 96px */
+
+  /* ── Type scale ── */
+  --ui-text-xs:   0.75rem;    /* 12px */
+  --ui-text-sm:   0.875rem;   /* 14px */
+  --ui-text-base: 1rem;       /* 16px */
+  --ui-text-lg:   1.125rem;   /* 18px */
+  --ui-text-xl:   1.25rem;    /* 20px */
+  --ui-text-2xl:  1.5rem;     /* 24px */
+  --ui-text-3xl:  1.875rem;   /* 30px */
+  --ui-text-4xl:  2.25rem;    /* 36px */
 }
 
 /* ─── Base reset ─────────────────────────────────────────────────────────────

package/src/agent/checklist.md

@@ -66,6 +66,11 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 - **Validate FormData fields before use.** `formData.get('email')` returns `null` if the field is missing. Check for null/empty before passing to an API or database.
 - **Do not trust URL params.** `ctx.params.id` is a raw string from the URL. Validate it before use — check it exists, is the right type, and refers to a real resource. Return a 404 or redirect if it doesn't.
 
+### CSS
+
+- **`app.css` must contain no hex values or raw colour values.** A lint hook enforces this and will block the build. Hex values belong in `public/theme.css` as token definitions; `app.css` references them via `var()` only.
+- **Load order in `meta.styles`:** `pulse-ui.css` → `theme.css` → `app.css`. Theme tokens must be defined before `app.css` references them.
+
 ### Security
 
 - Any value from user input (URL params, form fields, external APIs) interpolated into view HTML must be escaped.

package/src/agent/commands/verify.md

@@ -24,13 +24,13 @@ Use `mcp__chrome-devtools__navigate_page` to load the page route, then `mcp__chr
 
 Run `mcp__chrome-devtools__lighthouse_audit` on the route with `{ "strategy": "desktop" }`.
 
-**Pass bar: Performance, 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.
+**Pass bar: Accessibility, Best Practices, and SEO must all be 100.** Performance is measured and reported but is not a hard requirement (it varies with machine load). Report the actual scores. If Accessibility, Best Practices, or SEO is below 100, identify the failing audit(s), fix the issue, and restart from step 2.
 
 ### 6. Lighthouse — mobile
 
 Run `mcp__chrome-devtools__lighthouse_audit` on the same route with `{ "strategy": "mobile" }`.
 
-**Same pass bar: all four categories must be 100.** Report the actual scores. If any score is below 100, fix and restart from step 2.
+**Same pass bar: Accessibility, Best Practices, and SEO must all be 100.** Fix any failures and restart from step 2.
 
 ### 7. Performance
 
@@ -42,7 +42,7 @@ Use `mcp__chrome-devtools__list_console_messages` — report any errors or unexp
 
 ### 9. Code review
 
-Check the spec against the checklist in `.claude/pulse-checklist.md`. Work through every item. Fix anything that fails before proceeding to the next step.
+Call `pulse_review` with the absolute path to the spec file. Read the source, rendered HTML, validator output, and checklist it returns. Fix every issue before proceeding. This is the structured review — do not skip it or replace it with a manual checklist read.
 
 ### 10. Close the browser
 
@@ -56,7 +56,7 @@ Run:
 date +%s > .pulse-verified
 ```
 
-This records that verify completed successfully. The stop hook checks this stamp — do not skip this step.
+**This must be the last write operation before stopping.** The stop hook compares each edited spec's modification time against this stamp — if any spec is newer than the stamp, the hook blocks. Do not edit any spec file after writing the stamp.
 
 ### 12. Report
 
@@ -69,4 +69,12 @@ Summarise:
 - Console: any errors
 - Review: pass or issues found and fixed
 
-Only confirm the page is good when validation passes, both Lighthouse runs are 100/100/100/100, CLS is 0.00, and there are no console errors. Otherwise, fix and run `/verify` again.
+**Pass bar — all of these must be met before the page is confirmed good:**
+- Validation: clean (no errors, no warnings)
+- Lighthouse desktop: Accessibility, Best Practices, SEO all 100
+- Lighthouse mobile: same
+- CLS: 0.00 — any layout shift is a blocker
+- LCP: report the value; flag and fix any insight that identifies a fixable cause
+- Console: no errors
+
+If any gate fails, fix the issue and run `/verify` again.

package/src/agent/guide-styles.md

@@ -61,7 +61,11 @@ meta: {
 }
 ```
 
-Token list: --ui-bg, --ui-surface, --ui-surface-2, --ui-border, --ui-text, --ui-muted, --ui-accent, --ui-accent-hover, --ui-green, --ui-red, --ui-yellow, --ui-blue, --ui-radius, --ui-radius-sm, --ui-font, --ui-mono. Never hardcode hex values — override the tokens.
+**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-mono`. Never hardcode hex values — override the tokens.
+
+**Spacing tokens** (`--ui-space-N`): `--ui-space-1` (4px), `--ui-space-2` (8px), `--ui-space-3` (12px), `--ui-space-4` (16px), `--ui-space-5` (20px), `--ui-space-6` (24px), `--ui-space-8` (32px), `--ui-space-10` (40px), `--ui-space-12` (48px), `--ui-space-16` (64px), `--ui-space-20` (80px), `--ui-space-24` (96px). Use these for `padding`, `margin`, and `gap`.
+
+**Type-scale tokens** (`--ui-text-*`): `--ui-text-xs` (12px), `--ui-text-sm` (14px), `--ui-text-base` (16px), `--ui-text-lg` (18px), `--ui-text-xl` (20px), `--ui-text-2xl` (24px), `--ui-text-3xl` (30px), `--ui-text-4xl` (36px). Use these for `font-size`.
 
 ## Custom fonts
 

package/src/agent/workflow.md

@@ -33,7 +33,39 @@ Wait for the user to confirm or adjust the plan before writing any code.
 
 ## Phase 3 — Build
 
-Write the spec and any related files using the **Write tool** — not `pulse_create_page`. This shows the user a readable diff of the file content. After writing, call `pulse_create_page(name)` to validate the file you just wrote. After each file is written, output a one-line status: `✓ Page written — validating...`
+### 3a — Announce before writing
+
+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:
+
+```
+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>
+```
+
+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.
+
+### 3b — 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):
+
+```
+Writing src/pages/my-page.js...
+```
+
+After the Write tool completes, call `pulse_create_page(name)` to register the page. Only after that call succeeds output:
+
+```
+✓ 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.**
+
+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.
 
 ---
 
@@ -48,15 +80,21 @@ Run `pulse_validate` on the spec file.
 
 ## Phase 5 — Browser check (pass gate)
 
-1. Navigate to the page route in the browser.
-2. Take a screenshot. Check it visually — layout, content, spacing, no raw unstyled HTML.
-3. Check the browser console for errors (JS errors, failed network requests).
-4. Run Lighthouse with `strategy: 'desktop'`. All three scores must be 100: Accessibility, Best Practices, SEO. The tool does not return a Performance score — use `performance_start_trace` separately if performance profiling is needed. Tell the user before calling Lighthouse — it takes 30–60 s.
-5. Run Lighthouse with `strategy: 'mobile'`. Same pass bar.
+**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.
+
+Pass gates (all must be met before continuing to Phase 6):
+- Screenshot: no layout or rendering issues
+- 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)
+- No console errors
 
-**If any score is below 100:** fix the issue, reload, re-run Lighthouse. Repeat until both strategies pass 100/100/100. Do not continue until both pass.
+**If any gate fails:** fix the issue and run `/verify` again. Repeat until all gates pass.
 
-Output after passing: `✓ Lighthouse 100/100/100 desktop + mobile — writing tests...`
+Output after passing: `✓ Verified — writing tests...`
 
 ---
 
@@ -80,15 +118,13 @@ Output after passing: `✓ Tests passing — ready for review.`
 
 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.
+
 ---
 
 ## Phase 8 — Fix review issues
 
-Fix every issue raised by the Review Agent. If the fixes touch the spec or view:
-
-- Re-run `pulse_validate`
-- Re-run Lighthouse if visual or structural changes were made
-- Re-run tests
+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.
 
 Only declare the task done after phase 8 is complete and all gates still pass.
 
@@ -99,9 +135,9 @@ Only declare the task done after phase 8 is complete and all gates still pass.
 ```
 Phase 1  Understand          (no gate — always run)
 Phase 2  Plan                gate: user confirmation
-Phase 3  Build               (no gate — write the code)
+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 (Accessibility/Best Practices/SEO) desktop + mobile
+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

package/src/cli/scaffold.js

@@ -57,8 +57,9 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}}
   write(targetDir, 'src/pages/home.js',      homePage(name))
   write(targetDir, 'src/pages/home.test.js', homePageTest(name))
 
-  // Minimal stylesheet
-  write(targetDir, 'public/app.css', baseCSS())
+  // Stylesheets — theme.css holds hex token definitions, app.css uses only var() references
+  write(targetDir, 'public/theme.css', themeCSS())
+  write(targetDir, 'public/app.css',   baseCSS())
 
   // Copy pulse-ui assets from the package into public/ so they're served immediately
   const pkgPublic = new URL('../../public', import.meta.url).pathname
@@ -95,9 +96,6 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}}
 
   // settings.json — hooks that enforce correct agent behaviour
   write(targetDir, '.claude/settings.json', JSON.stringify({
-    enabledPlugins: {
-      'frontend-design@claude-plugins-official': true,
-    },
     hooks: {
       SessionStart: [
         {
@@ -148,7 +146,7 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}}
             },
             {
               type: 'command',
-              command: `node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const f=(i.tool_input||{}).file_path||'';if(!f.endsWith('.css')){return;}const fs=require('fs');let c;try{c=fs.readFileSync(f,'utf8');}catch(e){return;}const m=c.match(/#[0-9a-fA-F]{6}|#[0-9a-fA-F]{3}/g);if(m&&m.length){const u=[...new Set(m)];process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'PostToolUse',additionalContext:'HARDCODED HEX in '+f+': '+u.join(', ')+'. Use var(--ui-*) tokens instead — hardcoded colours break theming.'}}));}})"`,
+              command: `node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const f=(i.tool_input||{}).file_path||'';if(!f.endsWith('.css')){return;}if(f.endsWith('theme.css')){return;}const fs=require('fs');let c;try{c=fs.readFileSync(f,'utf8');}catch(e){return;}const m=c.match(/#[0-9a-fA-F]{6}|#[0-9a-fA-F]{3}/g);if(m&&m.length){const u=[...new Set(m)];process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'PostToolUse',additionalContext:'HARDCODED HEX in '+f+': '+u.join(', ')+'. Hex values belong in public/theme.css as token definitions — '+f+' should use var(--token-name) references only.'}}));}})"`,
               statusMessage: 'Checking for hardcoded colours...',
             },
             {
@@ -226,7 +224,7 @@ export default {
   meta: {
     title:       '${appName}',
     description: '${appName} — built with Pulse.',
-    styles:      ['/pulse-ui.css', '/app.css'],
+    styles:      ['/pulse-ui.css', '/theme.css', '/app.css'],
   },
 
   state: {
@@ -313,6 +311,22 @@ test('decrement mutation subtracts 1', () => {
 `
 }
 
+function themeCSS() {
+  return `\
+/*
+ * theme.css — token definitions
+ * Hex values and raw colours live here. app.css references these via var().
+ * Override pulse-ui tokens by targeting [data-theme="light"] (higher specificity than :root).
+ */
+
+/* Example — uncomment and edit to set a custom accent colour:
+[data-theme="light"] {
+  --color-accent: #0066cc;
+}
+*/
+`
+}
+
 function baseCSS() {
   return `\
 *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
@@ -337,9 +351,10 @@ function claudeMd(appName) {
 ## Project
 
 \`\`\`
-src/pages/       ← one .js file per page, auto-discovered
-src/components/  ← shared view fragments (JS functions returning HTML strings)
-public/app.css   ← global stylesheet
+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
 \`\`\`
 
 ## Start of every session
@@ -349,18 +364,13 @@ public/app.css   ← global stylesheet
 
 The MCP guide is the single source of truth. Follow it for all technical decisions, component usage, and the mandatory verification workflow.
 
-## Design — do this before writing any HTML
-
-Before planning any new page or component, use the \`frontend-design\` plugin to establish the visual direction:
-
-1. Call the plugin's design tools with the page brief (what it does, who it's for, the tone)
-2. The plugin will return decisions — colour palette, typography, spacing scale, component variants, layout approach
-3. **Apply those decisions as CSS custom property overrides in \`public/app.css\`** — not as inline styles or class hacks
-4. Document the chosen tokens at the top of \`public/app.css\` so every page stays consistent
+## CSS and theming
 
-The plugin informs *what* to build visually. The Pulse component library is *how* you build it. Use both — the plugin gives direction, the components implement it.
+- Hex values and colour token definitions go in \`public/theme.css\` — that is the only file where hex is allowed. The hex lint hook will fire on any other CSS file.
+- \`public/app.css\` must not contain hex colour values. Use \`var(--ui-space-N)\` spacing tokens (\`--ui-space-1\` = 4px through \`--ui-space-24\` = 96px) for padding, margin, and gap. Use \`var(--ui-text-*)\` tokens (\`--ui-text-xs\` through \`--ui-text-4xl\`) for font sizes. Plain values like \`1rem\` are also fine when no token fits.
+- Load order in \`meta.styles\`: \`/pulse-ui.css\` → \`/theme.css\` → \`/app.css\`.
 
-**Do not default to stock component styles.** If the design plugin gives you a colour, use it. If it suggests a layout pattern, follow it. Every page should reflect deliberate design decisions, not the component library defaults.
+When the user asks for layout or spacing changes, apply them directly — do not ask for confirmation on small CSS tweaks. Only pause for confirmation before large structural changes (new pages, major layout reworks).
 
 ## Before writing any code
 
@@ -376,7 +386,7 @@ Run these steps in order — do not declare work done without them:
 2. \`pulse_review\` — switch into reviewer mode, read the source and rendered HTML critically, fix every issue before continuing
 3. Write tests for every page you created or changed, run \`npm test\` (all pass), then \`npm run test:coverage\` — fix any untested branches
 4. Navigate to the page in the browser and take a screenshot
-5. Run Lighthouse (desktop then mobile) — all four scores must be 100
+5. Run Lighthouse (desktop then mobile) — Accessibility, Best Practices, and SEO must all be 100
 
 ## Writing tests
 

package/src/mcp/server.js

@@ -281,19 +281,24 @@ Rules for the spec you write:
 server.registerTool(
   'pulse_create_component',
   {
-    description: `Create a reusable view component in src/components/. Components export named functions that return HTML strings.
+    description: `Register a component you have already written to disk with the Write tool.
 
-IMPORTANT rules for component content:
+Workflow — always in this order:
+1. Write the component file to src/components/<name>.js using the Write tool (user sees the diff)
+2. Call pulse_create_component with just the name to confirm it was created correctly
+
+Do NOT pass content here — write the file first, then call this tool.
+
+Rules for the component you write:
 - Import Pulse UI components from '@invisibleloop/pulse/ui' where applicable
 - Use u- utility classes for spacing/layout — never inline styles
 - Use var(--ui-*) CSS tokens for any colour references — never hardcode hex values
 - Export named functions only (no default export needed)`,
     inputSchema: {
-      name:    z.string().describe('Component name, e.g. "hero" or "nav"'),
-      content: z.string().describe('JS — export named functions that return HTML strings'),
+      name: z.string().describe('Component filename without extension, e.g. "hero" or "nav"'),
     },
   },
-  async ({ name, content }) => {
+  ({ name }) => {
     const safeName = name.replace(/\.js$/, '')
     const fullPath = path.join(COMPONENTS_DIR, `${safeName}.js`)
 
@@ -301,10 +306,15 @@ IMPORTANT rules for component content:
       return text('Error: component name must not escape src/components/')
     }
 
-    fs.mkdirSync(path.dirname(fullPath), { recursive: true })
-    fs.writeFileSync(fullPath, content, 'utf8')
+    if (!fs.existsSync(fullPath)) {
+      return text(`Error: ${path.relative(ROOT, fullPath)} does not exist — write the file with the Write tool first, then call pulse_create_component.`)
+    }
+
+    const content = fs.readFileSync(fullPath, 'utf8')
+    const exports = [...content.matchAll(/^export\s+(?:function|const|async function)\s+(\w+)/gm)].map(m => m[1])
+    const exportNote = exports.length > 0 ? `Exports: ${exports.join(', ')}` : 'Warning: no named exports found — check the file exports at least one function.'
 
-    return text(`Created ${path.relative(ROOT, fullPath)}`)
+    return text(`Registered ${path.relative(ROOT, fullPath)}\n${exportNote}`)
   }
 )
 
@@ -315,42 +325,59 @@ IMPORTANT rules for component content:
 server.registerTool(
   'pulse_create_store',
   {
-    description: `Create a pulse.store.js global store at the project root. The store defines server fetchers and client mutations that are shared across pages.
+    description: `Register a pulse.store.js global store that you have already written to disk with the Write tool.
+
+Workflow — always in this order:
+1. Write pulse.store.js to the project root using the Write tool (user sees the diff)
+2. Call pulse_create_store to validate the file you just wrote
+
+Do NOT pass content here — write the file first, then call this tool.
 
-IMPORTANT rules:
+Rules for the store you write:
 - server fetchers must be async functions: async (ctx) => value
 - mutations must be pure functions: (storeState, payload?) => partialState — no fetch, no side effects
 - hydrate is required if the store has mutations (enables client-side store mutation dispatch)
 - Register the store in your server file by passing it to createServer({ store })
 - Pages subscribe to store keys via spec.store: ['user', 'settings']`,
-    inputSchema: {
-      content: z.string().describe('Complete pulse.store.js content — must export default a valid store object'),
-    },
+    inputSchema: {},
   },
-  async ({ content }) => {
+  () => {
     const storePath = path.join(ROOT, 'pulse.store.js')
 
-    // Basic structure check before writing
+    if (!fs.existsSync(storePath)) {
+      return text('Error: pulse.store.js does not exist — write the file with the Write tool first, then call pulse_create_store.')
+    }
+
+    const content = fs.readFileSync(storePath, 'utf8')
+
     if (!content.includes('export default')) {
-      return text('Invalid: store must contain "export default { ... }"')
+      return text('Invalid: pulse.store.js must contain "export default { ... }"')
     }
 
-    fs.writeFileSync(storePath, content, 'utf8')
+    const hasServer    = content.includes('server:')
+    const hasMutations = content.includes('mutations:')
+    const hasHydrate   = content.includes('hydrate:')
 
-    return text(`Created pulse.store.js
+    const warnings = []
+    if (hasMutations && !hasHydrate) {
+      warnings.push('Warning: store has mutations but no hydrate — add hydrate: \'/pulse.store.js\' to enable client-side store dispatch.')
+    }
 
+    const lines = ['Validated pulse.store.js']
+    if (hasServer)    lines.push('  ✓ server fetchers defined')
+    if (hasMutations) lines.push('  ✓ mutations defined')
+    if (hasHydrate)   lines.push('  ✓ hydrate set')
+    if (warnings.length) lines.push('', ...warnings)
+    lines.push(`
 Next steps:
 1. Import and register it in your server file:
    import store from './pulse.store.js'
    createServer(specs, { store })
 
 2. Declare which keys each page uses:
-   export default { route: '/dashboard', store: ['user', 'settings'], ... }
-
-3. If you added mutations, set hydrate in pulse.store.js:
-   hydrate: '/pulse.store.js'
+   export default { route: '/dashboard', store: ['user', 'settings'], ... }`)
 
-Store data is available in the view as the second argument alongside page server data.`)
+    return text(lines.join('\n'))
   }
 )
 
@@ -447,9 +474,12 @@ server.registerTool(
     const proc = spawn(process.execPath, [devScript, '--root', ROOT], { detached: true, stdio: 'ignore' })
     proc.unref()
 
-    // Give it a moment to bind the port
-    await new Promise(r => setTimeout(r, 1500))
-    return text(`Dev server restarted on port ${port}`)
+    // Wait until the server is actually accepting requests
+    const ready = await waitForServer(port)
+    return text(ready
+      ? `Dev server restarted on port ${port}`
+      : `Dev server started on port ${port} (did not respond within 10 s — check for errors)`
+    )
   }
 )
 
@@ -491,11 +521,12 @@ server.registerTool(
     const proc = spawn(process.execPath, [startScript, '--root', ROOT, '--port', String(prodPort)], { detached: true, stdio: 'ignore' })
     proc.unref()
 
-    // Wait for it to bind
-    setTimeout(() => resolve(text(
-      `Production build complete. Server running at http://localhost:${prodPort}/\n` +
-      `Run Lighthouse against this URL, then call pulse_restart_server to return to dev.`
-    )), 2000)
+    // Wait until the prod server is actually accepting requests
+    waitForServer(prodPort, 15_000).then(ready => resolve(text(
+      ready
+        ? `Production build complete. Server running at http://localhost:${prodPort}/\nRun Lighthouse against this URL, then call pulse_restart_server to return to dev.`
+        : `Build complete but prod server on port ${prodPort} did not respond within 15 s — check for startup errors.`
+    )))
   })
 )
 
@@ -587,7 +618,7 @@ Work through every item. Fix anything that fails.
 
 ### Structure
 - [ ] \`route\` is set explicitly — not left to auto-discovery
-- [ ] \`hydrate\` is set if the page has mutations, actions, or persist
+- [ ] \`hydrate\` is NOT set manually — the framework injects it automatically. Remove it if present.
 - [ ] \`state\` shape is consistent — no fields that flip between null/string/boolean
 - [ ] \`meta.title\` is meaningful and unique to this page
 - [ ] \`meta.description\` is a real description, not "Built with Pulse"
@@ -636,6 +667,38 @@ Fix every issue you find. Then confirm what was changed.
   }
 )
 
+// ---------------------------------------------------------------------------
+// pulse_run_tests
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  'pulse_run_tests',
+  {
+    description: 'Run the project test suite (npm test). Returns the full output. Use after writing or editing specs to verify nothing is broken.',
+    inputSchema: {},
+  },
+  () => new Promise(resolve => {
+    const result = spawnSync('npm', ['test'], {
+      cwd:      ROOT,
+      encoding: 'utf8',
+      timeout:  120_000,
+    })
+
+    const output   = (result.stdout || '') + (result.stderr || '')
+    const exitCode = result.status ?? 1
+
+    if (exitCode === 0) {
+      // Surface just the per-suite summary lines — enough to confirm all passed
+      const summaryLines = output.split('\n').filter(l => /\d+ tests?:/.test(l) || /passed|failed/.test(l))
+      const summary = summaryLines.length ? summaryLines.join('\n') : output.slice(-2000)
+      resolve(text(`All tests passed.\n\n${summary}`))
+    } else {
+      // Return the tail of the output where failures are reported
+      resolve(text(`Tests failed (exit ${exitCode}):\n\n${output.slice(-4000)}`))
+    }
+  })
+)
+
 // ---------------------------------------------------------------------------
 // pulse_check_version
 // ---------------------------------------------------------------------------
@@ -735,6 +798,24 @@ server.registerTool(
 // Helpers
 // ---------------------------------------------------------------------------
 
+/** Poll until the HTTP server on the given port accepts a connection, or timeout. */
+async function waitForServer(port, maxMs = 10_000) {
+  const deadline = Date.now() + maxMs
+  while (Date.now() < deadline) {
+    const alive = await new Promise(resolve => {
+      const req = http.get(`http://localhost:${port}/`, { timeout: 500 }, res => {
+        res.resume()
+        resolve(true)
+      })
+      req.on('error',   () => resolve(false))
+      req.on('timeout', () => { req.destroy(); resolve(false) })
+    })
+    if (alive) return true
+    await new Promise(r => setTimeout(r, 300))
+  }
+  return false
+}
+
 async function validateContent(content) {
   // Write into PAGES_DIR so relative imports (e.g. '../components/nav.js') resolve correctly
   fs.mkdirSync(PAGES_DIR, { recursive: true })
@@ -843,9 +924,10 @@ const PULSE_GUIDE_INDEX = `# Pulse Framework Guide
 - \`pulse_validate\` — validate spec content. Call after every write. Fix all errors AND warnings.
 - \`pulse_review\` — switch into reviewer mode and critically examine a spec you just built. Returns the source, rendered HTML, validator output, and a full review checklist. **Call this only after validate, Lighthouse (desktop + mobile), and tests all pass — it is the final phase before declaring done.**
 - \`pulse_create_page\` — validate a page spec you already wrote to disk. **Always write the file with the Write tool first, then call this.** Never pass content to this tool.
-- \`pulse_create_component\` — create a reusable component.
-- \`pulse_create_store\` — create the pulse.store.js global store.
+- \`pulse_create_component\` — register a component you wrote with the Write tool. Write the file first, then call this.
+- \`pulse_create_store\` — register a pulse.store.js you wrote with the Write tool. Write the file first, then call this.
 - \`pulse_create_action\` — generate a correctly-structured action snippet.
+- \`pulse_run_tests\` — run the project test suite (npm test). Use after writing or editing specs.
 - \`pulse_fetch_page(url)\` — HTTP GET the dev server URL. Use to verify SSR output.
 - \`pulse_restart_server\` — stop and restart the dev server.
 - \`pulse_build\` — production build + starts prod server on devPort+1 for Lighthouse. Returns the URL. Call \`pulse_restart_server\` after to return to dev. **Slow — takes 30–60 s. Tell the user before calling.**
@@ -863,32 +945,15 @@ const PULSE_GUIDE_INDEX = `# Pulse Framework Guide
 
 ## MANDATORY: Verify every build
 
-**RULE: NEVER run \`lighthouse_audit\` against the dev server. Dev mode serves unminified source files — scores are meaningless. Lighthouse MUST always run against the production build.**
-
-**Before calling any slow tool (\`pulse_build\`, \`lighthouse_audit\`), output a short status message to the user explaining what you are about to do and that it may take a moment.** Example: "Building for production — this takes ~30 s…" or "Running Lighthouse desktop audit — may take up to a minute…". Do not call the tool silently.
-
-After writing or editing any page, run ALL of the following steps in order before telling the user you are done:
-
-1. \`pulse_validate\` — validate the spec. Fix all errors and warnings before continuing.
-2. \`pulse_review\` — **switch into reviewer mode**. Read the source, rendered HTML, and checklist returned by the tool. Fix every issue found before moving on. This is mandatory — do not skip it.
-3. \`pulse_restart_server\` — only if you added a new page or changed imports.
-2. \`mcp__chrome-devtools__navigate_page\` — navigate to the dev server URL. After any CSS or asset change, follow immediately with \`mcp__chrome-devtools__evaluate_script\` running \`location.reload(true)\` to force a hard refresh.
-3. \`mcp__chrome-devtools__take_screenshot\` — check layout, spacing, content visibility, no overflow. Also check headings for orphans (a single short word stranded on the last line). To detect them programmatically, run \`mcp__chrome-devtools__evaluate_script\` with:
-   \`\`\`js
-   Array.from(document.querySelectorAll('h1,h2,h3,h4,h5,h6')).filter(h=>{const r=document.createRange();r.selectNodeContents(h);const rects=r.getClientRects();if(rects.length<2)return false;const last=rects[rects.length-1];return last.width/h.getBoundingClientRect().width<0.4;}).map(h=>h.tagName+': '+h.textContent.trim())
-   \`\`\`
-   Any heading returned has a last line shorter than 40% of its width — fix it with \`balance: true\` on the \`heading()\` component.
-4. \`mcp__chrome-devtools__list_console_messages\` (errors) — fix every JS error.
-5. \`mcp__chrome-devtools__list_network_requests\` (failed) — fix every 404 or failed fetch.
-6. \`pulse_fetch_page\` — pass the full URL e.g. \`{ url: "http://localhost:3000/" }\`. Confirm SSR renders expected content, no blank body.
-7. \`pulse_build\` — this builds for production AND starts a prod server on devPort+1. Wait for it to return the prod URL.
-8. \`mcp__chrome-devtools__navigate_page\` — navigate to the production URL returned by \`pulse_build\` (e.g. \`http://localhost:3001/\`).
-9. \`mcp__chrome-devtools__lighthouse_audit\` with \`{ "strategy": "desktop" }\` — run against the production URL. All four scores (Performance, Accessibility, Best Practices, SEO) must be 100. Report the actual scores and fix every failing audit before continuing.
-10. \`mcp__chrome-devtools__lighthouse_audit\` with \`{ "strategy": "mobile" }\` — run the same audit for mobile. All four scores must also be 100. Fix any failures before continuing.
-11. \`pulse_restart_server\` — shut down the prod server and return to dev.
-12. \`mcp__chrome-devtools__list_pages\` then \`mcp__chrome-devtools__close_page\` — close **every** page returned by \`list_pages\` to shut the browser down entirely. \`pageId\` must be a number: \`{ pageId: 2 }\` ✓ — NOT \`{ pageId: "2" }\` ✗ (string will fail). Loop through all page IDs and close each one.
-
-Do not declare success until all steps pass (step 12 is cleanup — always run it). If any step reveals a problem, fix it and repeat from step 2.
+**After writing or editing any page spec, you MUST run \`/verify\` before declaring done.**
+
+\`/verify\` is the single canonical verification workflow. It runs: validate → screenshot → console check → network check → SSR check → production build → Lighthouse desktop → Lighthouse mobile → performance trace → code review → writes the \`.pulse-verified\` stamp. The stop hook checks this stamp — if it is missing or older than the last spec edit, the hook will block and make you run verification again.
+
+**Do not replicate \`/verify\` steps manually.** Running the individual tools yourself does not write the stamp. The agent will be blocked at the end regardless.
+
+**RULE: NEVER run \`lighthouse_audit\` against the dev server.** Dev mode serves unminified source files — scores are meaningless. \`/verify\` handles this correctly by calling \`pulse_build\` first.
+
+**Before calling any slow tool (\`pulse_build\`, \`lighthouse_audit\`), output a short status message to the user.** Example: "Building for production — this takes ~30 s…". Do not call slow tools silently.
 
 ${CHECKLIST}`