@invisibleloop/pulse 0.12.0 → 0.12.2

package/.claude/pulse-checklist.md

@@ -4,16 +4,42 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 ### Critical
 
-- **`hydrate` is set on every interactive page.** Without it, `data-event` / `data-action` bindings do nothing, `persist` never runs, and client-side navigation cannot re-mount the page. Every spec with `mutations`, `actions`, or `persist` must include:
+- **`meta` must be a plain object — never a function.** Individual fields (`title`, `description`, `styles`) can be `async (ctx) => value` functions, but `meta` itself is always `{}`.
+
   ```js
-  hydrate: '/src/pages/my-page.js',  // browser-importable path to this file
+  // WRONG — meta is not a function factory
+  meta: async (ctx) => ({ title: '...', styles: [...] })
+
+  // CORRECT — meta is a plain object; individual fields are functions
+  meta: {
+    title:       async (ctx) => (await post(ctx)).frontmatter.title,
+    description: async (ctx) => (await post(ctx)).frontmatter.description,
+    styles:      ['/pulse-ui.css', '/app.css'],
+  }
   ```
-  Omit `hydrate` only for purely server-rendered pages with zero client interactivity.
+
+- **Do not set `hydrate` in specs.** It is auto-derived by the framework from the URL entry passed to `createServer`. Specs with `mutations`, `actions`, or `persist` are hydrated automatically. Purely server-rendered specs get zero JavaScript — no configuration needed.
+
+- **Always restart the server and reload the browser after every file edit — before checking the result.** The dev server restarts on file changes but the browser tab stays stale. The required sequence is: `pulse_restart_server` → `navigate_page`. Never attempt to debug a visual problem without doing both steps first.
 
 ### Components first
 
 - **Before writing any HTML by hand, check `src/ui/index.js`.** There are 50+ components. Use `button`, `card`, `alert`, `input`, `spinner`, `badge`, `modal`, `nav`, `pagination`, `table`, etc. before writing equivalent HTML from scratch.
 
+- **Never write App Store or Google Play download buttons by hand.** Always use `appBadge({ store: 'apple', href })` and `appBadge({ store: 'google', href })`. Raw `<a>` tags with badge images are incorrect — `appBadge` renders the correct accessible, styled badge for each store.
+
+  ```js
+  import { appBadge } from '@invisibleloop/pulse/ui'
+
+  // In a hero() actions slot:
+  ${hero({
+    actions: `
+      ${appBadge({ store: 'apple',  href: 'https://apps.apple.com/...' })}
+      ${appBadge({ store: 'google', href: 'https://play.google.com/...' })}
+    `,
+  })}
+  ```
+
 ### Reuse (DRY)
 
 - **Extract a view helper when the same HTML pattern appears 3 or more times in a single spec.** A plain JS function returning an HTML string is sufficient — no framework needed:
@@ -56,6 +82,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.
@@ -81,6 +112,12 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   ```
   Supported selectors: `tag`, `.class`, `#id`, `[attr]`, `[attr="value"]`, and combinations (`button.primary[disabled]`).
 
+### Markdown
+
+- **Use `md()` from `@invisibleloop/pulse/md` for `.md` file content.** Never read and parse markdown manually. Pass the result's `html` to `prose()`.
+- **Call the same `md()` fetcher in both `meta` and `server`** — it caches on `ctx._mdCache` so the file is only read once per request. Do not create two separate fetchers for the same file.
+- **Always add `onViewError` on dynamic markdown routes** (routes with `:param` segments loading `.md` files). A missing file throws `{ status: 404 }` which must be caught gracefully.
+
 ### View error handling
 
 - **Define `onViewError` on any page where the view could throw due to bad or missing data.** Without it, a runtime view error returns a 500 on the server and shows a generic inline message on the client. With it, the server returns 200 with your fallback HTML instead of a 500, and the client renders your fallback:
@@ -109,3 +146,14 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 - Interactive elements without visible text have an `aria-label`.
 - Disabled state is reflected with the `disabled` attribute, not just CSS.
 - The page has a `<main id="main-content">` landmark.
+- **Every element with `data-event`, `data-store-event`, `data-dialog-open`, or `data-dialog-close` is natively interactive (`button`, `a`, `input`, `select`, `textarea`, `summary`) or has `tabindex="0"`.** Non-interactive tags (`div`, `span`, `li`, `td`, etc.) with these attributes are not keyboard reachable. Prefer `<button>` — it is focusable, fires on Enter/Space, and carries the correct ARIA role for free. Only use `tabindex="0"` on a non-interactive element when a `<button>` genuinely cannot be used.
+- **Every interactive element communicates its purpose and state:**
+  - Buttons have visible text or `aria-label`. Links use descriptive text — "click here", "here", "read more" are failures.
+  - Form inputs have an associated `<label for="id">` or `aria-label`. `placeholder` alone is not a label.
+  - Toggle controls (open/close, show/hide, expand/collapse) carry `aria-expanded="true|false"` or `aria-pressed="true|false"`.
+  - While an action is in flight, the trigger button has `aria-busy="true"` or its label changes (e.g. "Saving…"). A spinner alone is not enough.
+  - Active nav items have `aria-current="page"`. Selected items in a list, tab set, or option group have `aria-selected="true"`.
+- **The page has a logical tab order:**
+  - No `tabindex` value greater than 0. Positive tabindex values override the natural DOM order and create a broken tab sequence. Remove them and reorder the DOM instead.
+  - Visually hidden interactive content (off-canvas menus, collapsed panels, `opacity:0` elements) is removed from the tab order with `tabindex="-1"` or the `inert` attribute — CSS alone does not remove an element from tab order.
+  - DOM order matches the visual reading order. When flexbox `order` or CSS grid placement visually reposition elements, the tab sequence still follows the DOM — author the DOM in the order a user would read and interact with the page.

package/docs/public/docs.css

@@ -1375,7 +1375,7 @@ a:hover {
   top: 0;
   left: 0;
   width: var(--sidebar-w);
-  height: 100vh;
+  height: 100dvh;
   overflow-y: auto;
   background: var(--surface);
   border-right: 1px solid var(--border);
@@ -1941,6 +1941,10 @@ hr.doc-hr {
     padding: 2rem 1.25rem 4rem;
   }
 
+  .sidebar-nav {
+    padding-bottom: 6rem;
+  }
+
   .doc-h1 {
     font-size: 1.75rem;
   }

package/docs/public/themes/observatory.css

@@ -68,6 +68,7 @@
 
 @media (max-width: 767px) {
   .obs-article { grid-template-columns: 1fr; }
+  .obs-aside-section:first-child { display: none; } /* ToC not useful below article on mobile */
 }
 
 /* Aside sections */

package/docs/src/pages/getting-started.js

@@ -17,16 +17,19 @@ export default {
     next,
     content: `
       ${h1('Getting Started')}
-      ${lead('Install Pulse, run one command, and have Claude building your first page — with streaming SSR, security headers, and a 100 Lighthouse score already in place.')}
+      ${lead('Install Pulse, run one command, and have an AI agent building your first page — with streaming SSR, security headers, and a 100 Lighthouse score already in place.')}
 
       ${section('requirements', 'Requirements')}
       <ul>
         <li><strong>Node.js 22 or later</strong> — <a href="https://nodejs.org" target="_blank" rel="noopener" aria-label="nodejs.org (opens in new tab)">nodejs.org</a></li>
         <li><strong>Google Chrome</strong> — used by the agent for screenshots and Lighthouse audits — <a href="https://www.google.com/chrome" target="_blank" rel="noopener" aria-label="Download Google Chrome (opens in new tab)">google.com/chrome</a></li>
-        <li><strong>Claude Code</strong> — the CLI for Claude, installed and authenticated — <a href="https://docs.anthropic.com/en/docs/claude-code/getting-started" target="_blank" rel="noopener" aria-label="Claude Code installation guide (opens in new tab)">installation guide</a></li>
+        <li><strong>An AI agent</strong> — Claude Code or GitHub Copilot CLI (pick one):</li>
       </ul>
-      <p>Claude Code provides the <code>claude</code> command. Pulse launches it automatically with the Pulse MCP server wired in — so the agent has instant access to the framework reference, your project structure, and all Pulse tools without any manual configuration.</p>
-      ${callout('note', 'GitHub Copilot integration is coming soon. For now, Pulse works exclusively with Claude Code.')}
+      <ul>
+        <li><strong>Claude Code</strong> — <a href="https://docs.anthropic.com/en/docs/claude-code/getting-started" target="_blank" rel="noopener" aria-label="Claude Code installation guide (opens in new tab)">installation guide</a> — the default; no extra config needed</li>
+        <li><strong>GitHub Copilot CLI</strong> — <a href="https://docs.github.com/copilot/concepts/agents/about-copilot-cli" target="_blank" rel="noopener" aria-label="GitHub Copilot CLI documentation (opens in new tab)">documentation</a> — use with the <code>--agent copilot</code> flag</li>
+      </ul>
+      <p>Pulse launches your chosen agent automatically with the Pulse MCP server wired in — so the agent has instant access to the framework reference, your project structure, and all Pulse tools without any manual configuration.</p>
 
       ${section('install', 'Install Pulse')}
       <p>Install the Pulse CLI globally:</p>
@@ -44,8 +47,17 @@ pulse`, 'bash'))}
       ${section('session', 'Start a session')}
       <p>Run <code>pulse</code> again from inside your project directory:</p>
       ${codeBlock(highlight('pulse', 'bash'))}
-      <p>This time, Pulse detects the existing project and launches Claude Code with the Pulse MCP server already connected. Claude opens with the complete framework guide loaded, your project structure visible, and all Pulse tools available — ready to build immediately.</p>
-      ${callout('note', 'Run <code>pulse</code> every time you open a working session. It handles starting Claude and wiring up the MCP server. Once Claude is open, use <code>/pulse-dev</code> to start the dev server.')}
+      <p>Pulse detects the existing project and launches Claude Code with the Pulse MCP server already connected. Claude opens with the complete framework guide loaded, your project structure visible, and all Pulse tools available — ready to build immediately.</p>
+      ${callout('note', 'Run <code>pulse</code> every time you open a working session. It handles starting the agent and wiring up the MCP server. Once the agent is open, use <code>/pulse-dev</code> (Claude) or the <code>build-page</code> skill (Copilot) to start the dev server.')}
+
+      ${section('copilot', 'Using GitHub Copilot')}
+      <p>To use GitHub Copilot CLI instead of Claude, pass the <code>--agent</code> flag when scaffolding:</p>
+      ${codeBlock(highlight('pulse --agent copilot', 'bash'))}
+      <p>This scaffolds the project and writes <code>agent: \'copilot\'</code> into <code>pulse.config.js</code> — so subsequent <code>pulse</code> runs pick up the preference automatically. You can also set it manually in <code>pulse.config.js</code> at any time:</p>
+      ${codeBlock(highlight(`export default {
+  agent: 'copilot',
+}`, 'js'))}
+      <p>When using Copilot, project skills (<code>build-page</code>, <code>verify</code>, <code>new-doc-page</code>) are available via the <code>/skills</code> command inside the Copilot CLI session. The Pulse MCP server is automatically injected into your Copilot MCP config for the duration of the session and removed cleanly on exit.</p>
 
       ${section('first-build', 'Build your first page')}
       <p>Once Claude opens, start the dev server and ask for something:</p>
@@ -74,7 +86,7 @@ Validate the email format before submitting."`, 'bash'))}
 │   ├── app.css              ← global stylesheet
 │   ├── pulse-ui.css         ← Pulse component library styles
 │   └── pulse-ui.js          ← Pulse component library behaviour
-├── .claude/
+├── .claude/                 ← Claude Code agent context
 │   ├── CLAUDE.md            ← session instructions Claude reads on startup
 │   ├── settings.json        ← hooks: syntax checks, colour guards, package blocklist
 │   ├── pulse-checklist.md   ← spec review checklist, kept in sync by Pulse
@@ -83,10 +95,19 @@ Validate the email format before submitting."`, 'bash'))}
 │       ├── pulse-stop.md
 │       ├── pulse-build.md
 │       └── pulse-start.md
+├── .copilot/                ← GitHub Copilot CLI agent context
+│   └── skills/              ← project skills available inside Copilot
+│       ├── build-page/
+│       ├── verify/
+│       └── new-doc-page/
+├── .github/
+│   ├── copilot-instructions.md          ← session instructions for Copilot
+│   └── instructions/
+│       └── pulse-checklist.instructions.md
 ├── package.json
-└── pulse.config.js          ← port and project settings`, 'bash'))}
-      <p><code>src/pages/home.js</code> is a complete working spec — a counter with increment and decrement buttons. Open <a href="http://localhost:3000">localhost:3000</a> after running <code>/pulse-dev</code> to see it. Every new page you create goes into <code>src/pages/</code> and is discovered automatically.</p>
-      <p>The <code>.claude/</code> directory contains the agent's operating context. <code>CLAUDE.md</code> tells Claude how the project is structured, <code>settings.json</code> configures hooks that catch common mistakes before they reach you — hardcoded hex colours, emoji in UI output, and installing client-side rendering libraries are all flagged or blocked automatically.</p>
+└── pulse.config.js          ← port, agent, and project settings`, 'bash'))}
+      <p><code>src/pages/home.js</code> is a complete working spec — a counter with increment and decrement buttons. Open <a href="http://localhost:3000">localhost:3000</a> after starting the dev server to see it. Every new page you create goes into <code>src/pages/</code> and is discovered automatically.</p>
+      <p>The <code>.claude/</code> directory contains the Claude agent's operating context. The <code>.copilot/</code> directory contains the equivalent context for GitHub Copilot — project skills and instructions. Both are scaffolded by default so you can switch agents at any time.</p>
 
       ${section('commands', 'Agent commands')}
       <p>These slash commands are available once Claude is open:</p>
@@ -95,7 +116,8 @@ Validate the email format before submitting."`, 'bash'))}
 /pulse-build   # production build → public/dist/
 /pulse-start   # run the production server
 /pulse-report  # Lighthouse audit + performance report`, 'bash'))}
-      <p>You can also skip the commands entirely — just describe what you want and the agent handles the rest, including starting the dev server when needed.</p>
+      <p>When using GitHub Copilot CLI, the equivalent capabilities are available as project skills. Type <code>/skills</code> inside Copilot to browse them — <code>build-page</code>, <code>verify</code>, and <code>new-doc-page</code> are all pre-installed.</p>
+      <p>You can also skip commands and skills entirely — just describe what you want and the agent handles the rest.</p>
 
       ${section('update', 'Keeping up to date')}
       <p>When a new version of Pulse is released, update the package and then run <code>pulse update</code> from your project root:</p>
@@ -104,10 +126,11 @@ pulse update`, 'bash'))}
       <p><code>pulse update</code> copies the latest UI assets and agent files into your project:</p>
       <ul>
         <li><code>public/pulse-ui.css</code> and <code>public/pulse-ui.js</code> — component library styles and behaviour</li>
-        <li><code>.claude/pulse-checklist.md</code> — spec review checklist</li>
-        <li><code>.claude/commands/</code> — slash commands</li>
+        <li><code>.claude/pulse-checklist.md</code> and <code>.claude/commands/</code> — Claude agent files</li>
+        <li><code>.copilot/skills/</code> — Copilot project skills</li>
+        <li><code>.github/instructions/pulse-checklist.instructions.md</code> — Copilot checklist</li>
       </ul>
-      <p>Your own source files, <code>CLAUDE.md</code>, and <code>pulse.config.js</code> are never touched.</p>
+      <p>Your own source files, <code>CLAUDE.md</code>, <code>.github/copilot-instructions.md</code>, and <code>pulse.config.js</code> are never touched.</p>
 
       ${section('next-steps', 'Next steps')}
       <ul>

package/docs/src/pages/templates.js

@@ -111,6 +111,53 @@ const mobileAppPreview = `
     </div>
   </div>`
 
+const blogPostPreview = `
+  <div style="display:flex;flex-direction:column;gap:6px;font-size:0;background:#0a2239;border-radius:4px;padding:8px">
+
+    <!-- nav -->
+    <div style="display:flex;align-items:center;gap:6px">
+      ${bar('20px', 6, '#53a2be')}
+      ${bar('36px', 4, '#53a2be', 2)}
+      <div style="flex:1"></div>
+      ${bar('28px', 4)}  ${bar('28px', 4)}  ${bar('28px', 4)}
+    </div>
+
+    <!-- hero -->
+    <div style="display:flex;flex-direction:column;align-items:center;gap:4px;padding:8px 0 6px;background:linear-gradient(160deg,#0a2239 0%,#132e32 100%);border-radius:3px;margin-top:2px">
+      ${bar('40px', 3, '#53a2be')}
+      ${bar('90%', 8, 'rgba(255,255,255,0.7)', 2)}
+      ${bar('75%', 8, 'rgba(255,255,255,0.7)', 2)}
+      ${bar('65%', 4, 'rgba(83,162,190,0.6)', 2)}
+      ${bar('50%', 3, 'rgba(83,162,190,0.4)', 2)}
+    </div>
+
+    <!-- article + aside -->
+    <div style="display:flex;gap:6px;margin-top:2px">
+      <div style="flex:1;display:flex;flex-direction:column;gap:4px">
+        ${bar('100%', 48, 'rgba(83,162,190,0.15)', 3)}
+        ${bar('100%', 4, 'rgba(255,255,255,0.5)', 1)}
+        ${bar('90%',  4, 'rgba(255,255,255,0.5)', 1)}
+        ${bar('95%',  4, 'rgba(255,255,255,0.5)', 1)}
+        ${bar('60%',  4, 'rgba(255,255,255,0.5)', 1)}
+        ${bar('55%',  6, 'rgba(255,255,255,0.7)', 1)}
+        ${bar('100%', 3, 'rgba(255,255,255,0.4)', 1)}
+        ${bar('85%',  3, 'rgba(255,255,255,0.4)', 1)}
+      </div>
+      <div style="width:38px;display:flex;flex-direction:column;gap:3px">
+        ${bar('100%', 4, 'rgba(255,255,255,0.5)', 1)}
+        ${bar('100%', 3, 'rgba(83,162,190,0.6)', 1)}
+        ${bar('100%', 3, 'rgba(83,162,190,0.6)', 1)}
+        ${bar('100%', 3, 'rgba(83,162,190,0.6)', 1)}
+        <div style="margin-top:3px;background:#132e32;border-radius:3px;padding:3px;display:flex;flex-direction:column;gap:2px">
+          ${bar('60%', 3, '#53a2be')}
+          ${bar('100%', 5, 'rgba(255,255,255,0.6)', 1)}
+          ${bar('100%', 5, 'rgba(255,255,255,0.6)', 1)}
+          ${bar('100%', 10, 'rgba(83,162,190,0.5)', 2)}
+        </div>
+      </div>
+    </div>
+  </div>`
+
 const TEMPLATES = [
   {
     name:        'Mobile App Landing Page',
@@ -126,6 +173,20 @@ const TEMPLATES = [
       'JS':            '~4.2 kB',
     },
   },
+  {
+    name:        'Blog Post',
+    route:       '/templates/blog-post',
+    description: 'A full editorial article page — sticky nav, article hero, prose with image, two-column layout with table-of-contents sidebar, newsletter signup, and footer. Dark astronomy theme.',
+    tags:        ['Blog', 'Editorial'],
+    preview:     blogPostPreview,
+    stats: {
+      'Accessibility': '100',
+      'Best Practices': '100',
+      'SEO':           '100',
+      'CLS':           '0.00',
+      'JS':            '~4.2 kB',
+    },
+  },
 ]
 
 const content = `

package/package.json

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

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.12.0
+0.12.2

package/src/agent/checklist.md

@@ -20,10 +20,26 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 - **Do not set `hydrate` in specs.** It is auto-derived by the framework from the URL entry passed to `createServer`. Specs with `mutations`, `actions`, or `persist` are hydrated automatically. Purely server-rendered specs get zero JavaScript — no configuration needed.
 
+- **Always restart the server and reload the browser after every file edit — before checking the result.** The dev server restarts on file changes but the browser tab stays stale. The required sequence is: `pulse_restart_server` → `navigate_page`. Never attempt to debug a visual problem without doing both steps first.
+
 ### Components first
 
 - **Before writing any HTML by hand, check `src/ui/index.js`.** There are 50+ components. Use `button`, `card`, `alert`, `input`, `spinner`, `badge`, `modal`, `nav`, `pagination`, `table`, etc. before writing equivalent HTML from scratch.
 
+- **Never write App Store or Google Play download buttons by hand.** Always use `appBadge({ store: 'apple', href })` and `appBadge({ store: 'google', href })`. Raw `<a>` tags with badge images are incorrect — `appBadge` renders the correct accessible, styled badge for each store.
+
+  ```js
+  import { appBadge } from '@invisibleloop/pulse/ui'
+
+  // In a hero() actions slot:
+  ${hero({
+    actions: `
+      ${appBadge({ store: 'apple',  href: 'https://apps.apple.com/...' })}
+      ${appBadge({ store: 'google', href: 'https://play.google.com/...' })}
+    `,
+  })}
+  ```
+
 ### Reuse (DRY)
 
 - **Extract a view helper when the same HTML pattern appears 3 or more times in a single spec.** A plain JS function returning an HTML string is sufficient — no framework needed:

package/src/agent/guide-components.md

@@ -153,7 +153,7 @@ Use `prose()` for HTML from external sources (CMS, markdown). Use `heading()`/`l
 | `testimonial` | `quote`, `name`, `role`, `src`, `rating` (1–5) |
 | `pricing` | `name`, `level` (1–6, default 3), `price`, `period`, `features` ([strings]), `action` (HTML slot), `highlighted` |
 | `accordion` | `items` ([{question,answer}]) — native `<details>`, no JS |
-| `appBadge` | `store` (apple/google), `href` |
+| `appBadge` | `store` (apple/google), `href` — **always use this for App Store / Google Play download buttons. Never write a raw `<a>` with an SVG badge image.** Designed to sit in a `hero()` `actions` slot or anywhere a download CTA is needed. |
 | `cta` | `eyebrow`, `title`, `level` (1–6, default 2), `subtitle`, `actions` (HTML slot), `align` |
 
 ### Layout components

package/src/agent/identity.md

@@ -62,6 +62,13 @@ Every build task follows a fixed sequence of phases with explicit pass gates. Fe
 
 You work exclusively inside the Pulse project directory. You do not read or modify files outside that directory.
 
+**After writing any file, always refresh before checking the result.** The dev server restarts automatically on file changes (node --watch), but the browser does not. The sequence after every edit is:
+1. Call `pulse_restart_server` — waits for the server to be ready
+2. Call `navigate_page` with the page URL — reloads the browser tab
+3. Only then take a screenshot or check for errors
+
+Never attempt to diagnose a visual problem without first doing these two steps. A stale browser tab is not a bug — it is an unrefreshed tab.
+
 When a shell command fails, you diagnose the root cause before retrying. You never retry the same failing command more than once. If a command fails due to permissions, auth, or token scope issues — these are unrecoverable without user action. Stop immediately, explain what failed and why, and tell the user exactly what they need to do to unblock it. Do not attempt workarounds that will also fail.
 
 Before installing any npm package, check whether the task can be accomplished with Node.js built-ins or code already in the project. Only install a package if there is no reasonable built-in alternative.

package/src/agent/skills/build-page/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: build-page
+description: "Scaffold a new Pulse page spec, validate it, and visually confirm it renders correctly. $ARGUMENTS Read `src/ui/index.js` to see what UI components are available before writing any HTML. Note which components apply to this page."
+---
+
+# Build Page
+
+Scaffold a new Pulse page spec, validate it, and visually confirm it renders correctly.
+
+## What to build
+
+$ARGUMENTS
+
+## Steps — follow in order
+
+### 1. Check existing components
+
+Read `src/ui/index.js` to see what UI components are available before writing any HTML. Note which components apply to this page.
+
+### 2. Plan
+
+State before writing any files:
+- The route (e.g. `/dashboard`)
+- The file path (e.g. `src/pages/dashboard.js`)
+- State shape
+- Mutations and/or actions needed
+- Which UI components will be used
+- Whether `server` data fetchers are needed
+
+### 3. Build the spec
+
+Write the spec file. Follow these rules:
+- Use `class` not `className`, template literals not JSX
+- No React imports, hooks, or patterns
+- Use components from `src/ui/` — do not hand-write HTML that a component already covers
+- Use optional chaining (`?.`) on any server data that could be null
+- Escape any user-supplied values interpolated into HTML
+
+### 4. Validate
+
+Use `pulse_validate` on the spec. Fix any errors before continuing.
+
+### 5. Register with the server
+
+Check the project's server entry file (e.g. `src/server.js` or `pulse.config.js`) and add the new spec if needed.
+
+### 6. Screenshot
+
+Use the chrome-devtools navigate_page tool to load the page, then take_screenshot.
+
+Check for:
+- Page renders without a blank screen or error
+- Layout looks correct
+- No console errors via list_console_messages
+
+### 7. Lighthouse
+
+Run lighthouse_audit (desktop, then mobile). All four scores — Accessibility, Best Practices, SEO, Performance — must be 100 before continuing.
+
+### 8. Run the checklist
+
+Go through `.github/instructions/pulse-checklist.instructions.md` and confirm every applicable point passes. Fix anything that fails.
+
+### 9. Write tests
+
+Write a `src/pages/<name>.test.js` covering:
+- View renders expected HTML landmarks
+- Each mutation as a pure function
+- Any utility functions the page defines
+
+Run them with `node src/pages/<name>.test.js` and fix every failure.
+
+### 10. Report
+
+Summarise what was built, what components were used, and confirm validation + visual check passed.

package/src/agent/skills/new-doc-page/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: new-doc-page
+description: "Create a new documentation page for the Pulse docs site. $ARGUMENTS - Read `docs/src/lib/nav.js` to understand the full nav structure and find where the new page fits"
+---
+
+# New Docs Page
+
+Create a new documentation page for the Pulse docs site.
+
+## What to build
+
+$ARGUMENTS
+
+## Steps — follow in order
+
+### 1. Research
+- Read `docs/src/lib/nav.js` to understand the full nav structure and find where the new page fits
+- Read 2–3 adjacent pages (the pages that will be `prev`/`next` neighbours) to match tone, section depth, and helper usage (`h1`, `lead`, `section`, `sub`, `codeBlock`, `callout`, `table`)
+- Read `docs/src/lib/layout.js` exported functions to confirm available helpers
+- If the feature being documented has a source file (e.g. in `src/`), read it to ensure accuracy
+
+### 2. Plan
+Before writing any files, state:
+- The route (e.g. `/request-bodies`)
+- Where it sits in the nav (section, between which two pages)
+- Sections the page will cover (IDs + titles)
+- Any doc pages that need updating to link to or mention this page
+
+Wait for approval if anything is uncertain.
+
+### 3. Implement
+
+**a) Write the page file** at `docs/src/pages/<name>.js`:
+- Import from `../lib/layout.js`, `../lib/nav.js`, `../lib/highlight.js`
+- Use `prevNext('/your-route')` for prev/next links
+- Export a valid Pulse spec as `export default { route, meta, state, view }`
+- `meta.styles` must be `['/docs.css']`
+- Use `renderLayout({ currentHref, prev, next, content })` for the page body
+- All code examples must use `${codeBlock(highlight(\`...\`, 'js'))}` — never raw `<pre>`
+- Tables use `${table(['Col1', 'Col2'], [['val', 'val']])}`
+- Callouts use `${callout('note|tip|warning|info', 'text')}`
+- Section anchors use `${section('anchor-id', 'Section Title')}`
+
+**b) Register in nav** — add the entry to `docs/src/lib/nav.js` in the correct position
+
+**c) Verify syntax** — run `node --check docs/src/pages/<name>.js`
+
+**d) Check neighbours** — read the prev and next pages. If they reference topics this new page covers, add a cross-link.
+
+**e) Final check** — confirm the new route appears in `prevNext` output for its neighbours (the nav order drives prev/next automatically, so adding to NAV is sufficient).

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

@@ -0,0 +1,67 @@
+---
+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."
+---
+
+# Verify
+
+Run the full verification loop on the current page or the page specified in $ARGUMENTS.
+
+## Steps
+
+### 1. Identify the target
+
+If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify the most recently edited spec file from context.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 5. Lighthouse — desktop
+
+Run lighthouse_audit on the route in desktop mode.
+
+**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.
+
+### 6. Lighthouse — mobile
+
+Run lighthouse_audit on the same route in mobile mode.
+
+**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.
+
+### 7. Performance
+
+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.).
+
+### 8. Console errors
+
+Use list_console_messages — report any errors or unexpected warnings.
+
+### 9. Code review
+
+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.
+
+### 10. Close the browser
+
+Use list_pages to get all open pages, then call close_page for every page ID returned.
+
+### 11. Report
+
+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
+
+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.

package/src/agent/workflow.md

@@ -80,6 +80,12 @@ Run `pulse_validate` on the spec file.
 
 ## Phase 5 — Browser check (pass gate)
 
+**After every file edit, restart the server and reload the browser before checking anything.** The dev server auto-restarts on file changes but the browser tab stays stale. Always:
+1. Call `pulse_restart_server` — waits for the server to be ready
+2. Call `navigate_page` with the page URL — reloads the browser tab
+
+Do this before every screenshot, console check, or visual inspection. Never debug a problem that might just be a stale tab.
+
 **Run `/verify` now — as soon as the first build is working.** Do not defer it to the end. Do not execute these steps manually.
 
 `/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.

package/src/cli/cli.test.js

@@ -8,6 +8,9 @@
  * run: node src/cli/cli.test.js
  */
 
+import { existsSync, readFileSync } from 'fs'
+import path from 'path'
+
 let passed = 0
 let failed = 0
 
@@ -76,6 +79,32 @@ test('discover: nested pages get unique names (collision prevention)', () => {
   }
 })
 
+// ---------------------------------------------------------------------------
+// Skill source files
+
+console.log('\nCopilot skill source files\n')
+
+const skillsDir = new URL('../agent/skills', import.meta.url).pathname
+const requiredSkills = ['build-page', 'verify', 'new-doc-page']
+
+for (const skill of requiredSkills) {
+  const skillMd = path.join(skillsDir, skill, 'SKILL.md')
+
+  test(`${skill}/SKILL.md exists`, () => {
+    if (!existsSync(skillMd)) throw new Error(`Missing: ${skillMd}`)
+  })
+
+  test(`${skill}/SKILL.md has valid frontmatter`, () => {
+    const content = readFileSync(skillMd, 'utf8')
+    if (!content.startsWith('---\n')) throw new Error('Missing opening YAML frontmatter ---')
+    const end = content.indexOf('\n---\n', 4)
+    if (end === -1) throw new Error('Missing closing YAML frontmatter ---')
+    const frontmatter = content.slice(4, end)
+    if (!frontmatter.includes('name:'))        throw new Error('Frontmatter missing name:')
+    if (!frontmatter.includes('description:')) throw new Error('Frontmatter missing description:')
+  })
+}
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)

package/src/cli/index.js

@@ -12,13 +12,24 @@
  *   pulse -v           alias for --version
  *   pulse --help       show usage and exit
  *   pulse -h           alias for --help
+ *   pulse --agent copilot   use GitHub Copilot CLI instead of Claude
  */
 
 import path from 'path'
 import fs   from 'fs'
 import { scaffold } from './scaffold.js'
 
-const args    = process.argv.slice(2)
+// Extract --agent flag before routing, so it works alongside any subcommand
+const rawArgs   = process.argv.slice(2)
+let agentFlag   = null
+const args      = []
+for (let i = 0; i < rawArgs.length; i++) {
+  if (rawArgs[i] === '--agent' && rawArgs[i + 1] && !rawArgs[i + 1].startsWith('-')) {
+    agentFlag = rawArgs[++i]
+  } else {
+    args.push(rawArgs[i])
+  }
+}
 const command = args[0]
 const CWD     = process.cwd()
 
@@ -112,7 +123,7 @@ async function runDefault(root) {
     }
 
     console.log()
-    await scaffold(targetDir, { name })
+    await scaffold(targetDir, { name, agent: agentFlag })
 
     if (targetDir !== root) {
       console.log(`\n✓ Project created at ./${name}/\n`)
@@ -126,21 +137,21 @@ async function runDefault(root) {
   }
 
   // Start dev server + AI session
-  await launchSession(root)
+  await launchSession(root, agentFlag)
 }
 
 // ---------------------------------------------------------------------------
 // Launch AI session (Claude by default)
 // ---------------------------------------------------------------------------
 
-async function launchSession(root) {
+async function launchSession(root, agentOverride = null) {
   const { spawn } = await import('child_process')
   const os        = await import('os')
 
-  // Load project config for agent preference
+  // Load project config for agent preference — CLI flag takes priority
   const configPath = path.join(root, 'pulse.config.js')
-  let agent = 'claude'
-  if (fs.existsSync(configPath)) {
+  let agent = agentOverride || 'claude'
+  if (!agentOverride && fs.existsSync(configPath)) {
     try {
       const mod = await import(configPath)
       agent = mod.default?.agent || 'claude'
@@ -157,18 +168,30 @@ async function launchSession(root) {
       }
     }
   }
-  const mcpConfigPath = path.join(os.default.tmpdir(), `pulse-mcp-${Date.now()}.json`)
-  fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2))
 
   console.log(`\n⚡ Pulse project: ${root}`)
   console.log(`   Use /pulse-dev to start the dev server, /pulse-stop to stop it, /pulse-build to build, /pulse-start to run production.`)
   console.log(`   Tell me what you'd like to build — a new page, a component, a form, or anything else.\n`)
 
+  if (agent === 'copilot') {
+    await launchCopilotSession(root, mcpServerPath, spawn, os.default)
+  } else {
+    await launchClaudeSession(root, mcpConfig, spawn, os.default)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Claude session — temp MCP config file passed via --mcp-config flag
+// ---------------------------------------------------------------------------
+
+async function launchClaudeSession(root, mcpConfig, spawn, os) {
+  const mcpConfigPath = path.join(os.tmpdir(), `pulse-mcp-${Date.now()}.json`)
+  fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2))
+
   // Launch the agent with MCP config — don't spawn a dev server here,
   // Claude Code cannot be launched as a child process from within a Claude session.
   // The dev server is started via the /dev slash command instead.
-  const agentCmd  = agentCommand(agent, mcpConfigPath)
-  const agentProc = spawn(agentCmd.cmd, agentCmd.args, {
+  const agentProc = spawn('claude', ['--mcp-config', mcpConfigPath], {
     stdio: 'inherit',
     cwd:   root,
   })
@@ -179,13 +202,55 @@ async function launchSession(root) {
   })
 }
 
-function agentCommand(agent, mcpConfigPath) {
-  if (agent === 'claude') {
-    return { cmd: 'claude', args: ['--mcp-config', mcpConfigPath] }
+// ---------------------------------------------------------------------------
+// Copilot session — pulse entry injected into ~/.copilot/mcp-config.json
+// ---------------------------------------------------------------------------
+
+async function launchCopilotSession(root, mcpServerPath, spawn, os) {
+  const mcpConfigPath = path.join(os.homedir(), '.copilot', 'mcp-config.json')
+
+  // Read existing Copilot MCP config (or start fresh)
+  let config = { mcpServers: {} }
+  if (fs.existsSync(mcpConfigPath)) {
+    try { config = JSON.parse(fs.readFileSync(mcpConfigPath, 'utf8')) } catch { /* use default */ }
   }
-  // Future: copilot, etc.
-  console.warn(`Unknown agent "${agent}", falling back to claude`)
-  return { cmd: 'claude', args: ['--mcp-config', mcpConfigPath] }
+  config.mcpServers ??= {}
+
+  const hadPulse      = 'pulse' in config.mcpServers
+  const originalPulse = hadPulse ? config.mcpServers.pulse : undefined
+
+  // Inject pulse MCP server
+  config.mcpServers.pulse = {
+    type:    'local',
+    command: process.execPath,
+    args:    [mcpServerPath, '--root', root],
+    tools:   ['*'],
+  }
+  fs.mkdirSync(path.dirname(mcpConfigPath), { recursive: true })
+  fs.writeFileSync(mcpConfigPath, JSON.stringify(config, null, 2))
+
+  // Restore config on exit — removes pulse entry (or restores original if it existed)
+  let cleaned = false
+  const cleanup = () => {
+    if (cleaned) return
+    cleaned = true
+    try {
+      const current = JSON.parse(fs.readFileSync(mcpConfigPath, 'utf8'))
+      if (hadPulse) {
+        current.mcpServers.pulse = originalPulse
+      } else {
+        delete current.mcpServers.pulse
+      }
+      fs.writeFileSync(mcpConfigPath, JSON.stringify(current, null, 2))
+    } catch { /* ignore cleanup errors */ }
+    process.exit(0)
+  }
+
+  process.on('SIGINT',  cleanup)
+  process.on('SIGTERM', cleanup)
+
+  const agentProc = spawn('copilot', [], { stdio: 'inherit', cwd: root })
+  agentProc.on('exit', cleanup)
 }
 
 // ---------------------------------------------------------------------------
@@ -318,6 +383,29 @@ async function runUpdate(root) {
     }
   }
 
+  // Sync Copilot skills into .copilot/skills/
+  const skillsSrc = new URL('../agent/skills', import.meta.url).pathname
+  if (fs.existsSync(skillsSrc)) {
+    for (const skillDir of fs.readdirSync(skillsSrc)) {
+      const skillMd = path.join(skillsSrc, skillDir, 'SKILL.md')
+      if (fs.existsSync(skillMd)) {
+        const dstDir = path.join(root, '.copilot', 'skills', skillDir)
+        fs.mkdirSync(dstDir, { recursive: true })
+        fs.copyFileSync(skillMd, path.join(dstDir, 'SKILL.md'))
+        updated.push(`.copilot/skills/${skillDir}/SKILL.md`)
+      }
+    }
+  }
+
+  // Sync checklist to .github/instructions/ for Copilot
+  const checklistSrc = new URL('../agent/checklist.md', import.meta.url).pathname
+  if (fs.existsSync(checklistSrc)) {
+    const checklistDst = path.join(root, '.github', 'instructions', 'pulse-checklist.instructions.md')
+    fs.mkdirSync(path.dirname(checklistDst), { recursive: true })
+    fs.copyFileSync(checklistSrc, checklistDst)
+    updated.push('.github/instructions/pulse-checklist.instructions.md')
+  }
+
   // Read the new version for the success message
   const versionFile = path.join(publicDir, '.pulse-ui-version')
   const version     = fs.existsSync(versionFile) ? fs.readFileSync(versionFile, 'utf8').trim() : '?'
@@ -362,7 +450,7 @@ switch (command) {
     console.log(`
   ⚡ Pulse — spec-first frontend framework
 
-  Usage: pulse [command]
+  Usage: pulse [command] [options]
 
   Commands:
     (none)      detect project or start scaffold wizard
@@ -372,8 +460,13 @@ switch (command) {
     update      re-copy pulse-ui assets from installed package → public/
 
   Options:
+    --agent <name>  AI agent to use: claude (default) or copilot
     -v, --version   print version and exit
     -h, --help      show this help
+
+  Examples:
+    pulse                    start with Claude (default)
+    pulse --agent copilot    start with GitHub Copilot CLI
 `)
     process.exit(0)
   case 'dev':

package/src/cli/scaffold.js

@@ -20,8 +20,9 @@ const PULSE_PKG = '@invisibleloop/pulse'
  * @param {number} [options.port]  - Dev server port (defaults to 3000)
  */
 export async function scaffold(targetDir, options = {}) {
-  const name = options.name || path.basename(targetDir)
-  const port = options.port || 3000
+  const name  = options.name  || path.basename(targetDir)
+  const port  = options.port  || 3000
+  const agent = options.agent || null
 
   fs.mkdirSync(path.join(targetDir, 'src', 'pages'),      { recursive: true })
   fs.mkdirSync(path.join(targetDir, 'src', 'components'), { recursive: true })
@@ -47,10 +48,10 @@ export async function scaffold(targetDir, options = {}) {
     }
   }, null, 2))
 
-  // pulse.config.js
+  // pulse.config.js — write agent if specified, otherwise leave as commented hint
   write(targetDir, 'pulse.config.js',
 `export default {
-${port !== 3000 ? `  port: ${port},\n` : ''}}
+${port !== 3000 ? `  port: ${port},\n` : ''}${agent && agent !== 'claude' ? `  agent: '${agent}',\n` : `  // agent: 'copilot',  // uncomment to use GitHub Copilot CLI instead of Claude\n`}}
 `)
 
   // Home page + tests — working counter proves the app runs
@@ -94,6 +95,27 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}}
     }
   }
 
+  // Copilot skills — .copilot/skills/ so GitHub Copilot CLI picks them up as project skills
+  const skillsSrc = new URL('../agent/skills', import.meta.url).pathname
+  if (fs.existsSync(skillsSrc)) {
+    for (const skillDir of fs.readdirSync(skillsSrc)) {
+      const skillMd = path.join(skillsSrc, skillDir, 'SKILL.md')
+      if (fs.existsSync(skillMd)) {
+        write(targetDir, `.copilot/skills/${skillDir}/SKILL.md`, fs.readFileSync(skillMd, 'utf8'))
+      }
+    }
+  }
+
+  // Copilot project instructions — .github/copilot-instructions.md is the canonical Copilot location
+  write(targetDir, '.github/copilot-instructions.md', copilotInstructionsMd(name))
+
+  // Copilot checklist as a separate instructions file — auto-loaded from .github/instructions/
+  const checklistSrc = new URL('../agent/checklist.md', import.meta.url).pathname
+  if (fs.existsSync(checklistSrc)) {
+    write(targetDir, '.github/instructions/pulse-checklist.instructions.md',
+      fs.readFileSync(checklistSrc, 'utf8'))
+  }
+
   // settings.json — hooks that enforce correct agent behaviour
   write(targetDir, '.claude/settings.json', JSON.stringify({
     hooks: {
@@ -436,6 +458,98 @@ Descendant selectors (\`tbody tr\`, \`ul li\`) are NOT supported — use \`r.cou
 `
 }
 
+function copilotInstructionsMd(appName) {
+  return `\
+# ${appName} — Pulse App
+
+## Project
+
+\`\`\`
+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
+
+1. Run \`pulse_list_structure\` to see what already exists
+2. Read \`pulse://guide\` from MCP — the complete reference for spec format, components, verification workflow, CSS rules, and patterns
+
+The MCP guide is the single source of truth. Follow it for all technical decisions, component usage, and the mandatory verification workflow.
+
+## CSS and theming
+
+- Hex values and colour token definitions go in \`public/theme.css\` — that is the only file where hex is allowed.
+- \`public/app.css\` must not contain hex colour values. Use \`var(--ui-space-N)\` spacing tokens for padding, margin, and gap. Use \`var(--ui-text-*)\` tokens for font sizes.
+- Load order in \`meta.styles\`: \`/pulse-ui.css\` → \`/theme.css\` → \`/app.css\`.
+
+## Before writing any code
+
+**Always present a plan and wait for the user to confirm before writing a single line of code.**
+
+The plan must include: route, page sections, components used, state shape, and whether hydration is needed. End the plan with an explicit question — "Shall I go ahead?" — and stop. Do not proceed until the user says yes (or equivalent). This applies to every new page or significant change, no matter how clear the task seems.
+
+## After completing any feature
+
+Run these steps in order — do not declare work done without them:
+
+1. \`pulse_validate\` — fix all errors and warnings
+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) — Accessibility, Best Practices, and SEO must all be 100
+
+## Writing tests
+
+Test files live next to the page they test: \`src/pages/foo.test.js\` for \`src/pages/foo.js\`.
+
+\`\`\`
+npm test               # run all tests
+npm run test:coverage  # run tests + show branch/line coverage for src/pages/
+\`\`\`
+
+Coverage target: **100% branch coverage on every view function**. The coverage report shows uncovered lines — add tests until every branch is exercised. Server fetcher functions (which hit real APIs) are exempt.
+
+What to test for every page:
+- View with real/populated server data (success path)
+- View with \`null\` server data per fetcher (each fetcher can fail independently)
+- View with empty arrays/collections (empty state vs populated state)
+- \`onViewError\` fallback — call it directly: \`spec.onViewError(new Error('x'), {}, {})\`
+- Every mutation — pure functions, test directly
+- Every exported pure function (formatters, validators, etc.)
+- XSS: pass \`'<script>alert(1)</script>'\` as user-controlled strings, assert \`!r.has('script')\`
+
+\`\`\`js
+import assert from 'node:assert/strict'
+import { renderSync } from '@invisibleloop/pulse/testing'
+import spec from './my-page.js'
+
+// View — pass mock state and server data
+const r = renderSync(spec, { state: { count: 5 }, server: { items: [] } })
+assert(r.has('main#main-content'))          // element exists
+assert.equal(r.get('h1').text, 'Title')    // text content (throws if not found)
+assert(r.has('button[disabled]'))           // attribute present
+assert(!r.has('.ui-badge'))                 // element absent
+assert.equal(r.count('li'), 3)             // count elements
+
+// Mutations — pure functions, test directly
+assert.deepEqual(spec.mutations.increment({ count: 0 }), { count: 1 })
+
+// onViewError
+const fallback = spec.onViewError(new Error('boom'), {}, {})
+assert(fallback.includes('main-content'))
+\`\`\`
+
+**Selector support:** \`tag\`, \`.class\`, \`#id\`, \`[attr]\`, \`[attr="value"]\`, and combinations (\`button.primary[disabled]\`).
+Descendant selectors (\`tbody tr\`, \`ul li\`) are NOT supported — use \`r.count('tr')\` not \`r.count('tbody tr')\`.
+
+## Spec review checklist
+
+See \`.github/instructions/pulse-checklist.instructions.md\` — loaded automatically by Copilot.
+`
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------