@invisibleloop/pulse 0.20.11 → 0.20.19

package/docs/src/pages/home.js

@@ -1,350 +0,0 @@
-// component-free — creative override: asymmetric typography-driven layout (wide headline column + narrower supporting column), a solid gold mark treatment on "page.", and a light/dark section rhythm that component patterns cannot express
-import { highlight }                                        from '../lib/highlight.js'
-import { iconZap, iconShield, iconSettings }               from '../../../src/ui/icons.js'
-import { metricsStore }  from '../lib/metrics-store.js'
-import pkg from '../../../package.json' with { type: 'json' }
-
-// macOS-style code window chrome — raw HTML (creative override), replacing
-// the removed codeWindow() component. Reuses the same .ui-code-window*
-// CSS classes still defined in pulse-ui.css.
-const codeWindow = ({ content = '', filename = '', lang = '' }) => `
-  <div class="ui-code-window" role="region"${filename ? ` aria-label="${filename}"` : ''}>
-    <div class="ui-code-window-chrome" aria-hidden="true">
-      <span class="ui-code-window-dot"></span>
-      <span class="ui-code-window-dot"></span>
-      <span class="ui-code-window-dot"></span>
-      ${filename ? `<span class="ui-code-window-filename">${filename}</span>` : ''}
-      ${lang     ? `<span class="ui-code-window-lang">${lang}</span>` : ''}
-    </div>
-    <pre class="ui-code-window-pre"><code class="ui-code-window-code">${content}</code></pre>
-  </div>
-`
-
-const { version } = pkg
-
-const exampleSpec = highlight(`export default {
-  route: '/dashboard',
-  meta: {
-    title: 'Dashboard — My App',
-    styles: ['/app.css'],
-  },
-  server: {
-    data: async (ctx) => {
-      const user = await db.users.find(ctx.cookies.userId)
-      return { user, stats: await db.stats.forUser(user.id) }
-    },
-  },
-  state: { filter: 'all' },
-  mutations: {
-    setFilter: (state, event) => ({ filter: event.target.value }),
-  },
-  view: (state, server) => \`
-    <main id="main-content">
-      <h1>Hello, \${server.data.user.name}</h1>
-      <select data-event="change:setFilter">
-        <option value="all">All time</option>
-        <option value="week">This week</option>
-      </select>
-      <p>\${server.data.stats[state.filter].total} requests</p>
-    </main>
-  \`,
-}`, 'js')
-
-export default {
-  route: '/',
-  meta: {
-    title: 'Pulse — The spec-first web framework',
-    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.',
-    theme: 'light',
-    styles: ['/pulse-ui.css', '/theme.css', '/docs.css', '/home-brut.css'],
-    // Loaded via JS after initial parse — non-render-blocking. The preconnect
-    // hints below still warm the connection up early, and display=swap in the
-    // URL means the browser paints with a fallback font immediately and swaps
-    // to Inter once it arrives, so there's no invisible-text window either way.
-    deferredStyles: ['https://fonts.googleapis.com/css2?family=Inter:wght@400;600;800;900&display=swap'],
-    schema: {
-      '@context': 'https://schema.org',
-      '@type': 'SoftwareApplication',
-      name: 'Pulse',
-      applicationCategory: 'DeveloperApplication',
-      operatingSystem: 'Node.js ≥ 22',
-      offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' },
-      license: 'https://opensource.org/licenses/MIT',
-      description: 'Spec-first Node.js web framework. Zero runtime dependencies. Streaming SSR, built-in security headers, and production caching enforced by the architecture.',
-      url: 'https://pulse.invisibleloop.com',
-      codeRepository: 'https://github.com/invisibleloop/pulse-framework',
-    },
-  },
-  state: {},
-  server: {
-    metrics: () => metricsStore.current,
-  },
-  view: (state, server) => `
-    <div class="brut">
-
-      <nav class="brut-nav" aria-label="Site navigation">
-        <a href="/" class="brut-nav-logo" aria-label="Pulse home">
-          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" aria-hidden="true">
-            <path d="M13 2L4.5 13.5H11L10 22L19.5 10.5H13L13 2Z" fill="currentColor" stroke="currentColor" stroke-width="1" stroke-linejoin="round"/>
-          </svg>
-          <span>PULSE</span>
-        </a>
-        <div class="brut-nav-links">
-          <a href="/getting-started">Docs</a>
-          <a href="https://github.com/invisibleloop/pulse-framework" target="_blank" rel="noopener" aria-label="GitHub (opens in new tab)">GitHub</a>
-          <a href="/getting-started" class="brut-nav-cta">Get Started</a>
-        </div>
-      </nav>
-
-      <main id="main-content">
-
-        <section class="brut-hero">
-          <div class="brut-hero-tag">v${version} — EARLY ACCESS</div>
-          <h1 class="brut-hero-h1">
-            <span class="brut-hero-kicker">with Pulse</span>
-            <span class="brut-hero-line1">The spec is</span>
-            <span class="brut-hero-line2">the <span class="brut-hero-mark">page.</span></span>
-          </h1>
-          <div class="brut-hero-aside">
-            <p class="brut-hero-tag-inline">ONE SPEC. ONE WAY TO BUILD.</p>
-            <p class="brut-hero-desc">One plain JS object — server data, state, mutations, and view. No split files, no hidden conventions.</p>
-            <p class="brut-hero-sub"><strong>So constrained that doing it wrong isn't an option.<br>Whether you write it or an AI&nbsp;does.</strong></p>
-            <div class="brut-hero-ctas">
-              <a href="/getting-started" class="brut-btn-primary">Get Started</a>
-              <a href="/spec" class="brut-btn-ghost">Read the Spec</a>
-            </div>
-          </div>
-        </section>
-
-        <div class="brut-stats-bar">
-          <div class="brut-stat">
-            <span class="brut-stat-val">4 kB</span>
-            <span class="brut-stat-lbl">Runtime JS · first visit</span>
-          </div>
-          <div class="brut-stat">
-            <span class="brut-stat-val">0.00</span>
-            <span class="brut-stat-lbl">Cumulative Layout Shift</span>
-          </div>
-          <div class="brut-stat">
-            <span class="brut-stat-val">100</span>
-            <span class="brut-stat-lbl">Lighthouse · by design</span>
-          </div>
-          <div class="brut-stat">
-            <span class="brut-stat-val">0</span>
-            <span class="brut-stat-lbl">Runtime dependencies</span>
-          </div>
-        </div>
-
-        <section class="brut-idea">
-          <div class="brut-idea-label">THE IDEA</div>
-          <div class="brut-idea-grid">
-            <div class="brut-idea-step">
-              <div class="brut-idea-num" aria-hidden="true">01</div>
-              <h2>The spec is the page</h2>
-              <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="brut-idea-step">
-              <div class="brut-idea-num" aria-hidden="true">02</div>
-              <h2>The schema is the contract</h2>
-              <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="brut-idea-step">
-              <div class="brut-idea-num" aria-hidden="true">03</div>
-              <h2>The framework is the guarantee</h2>
-              <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>
-        </section>
-
-        <section class="brut-code-section">
-          <div class="brut-code-header">
-            <h2>Everything a page needs.<br>Nothing it doesn't.</h2>
-            <p>Server fetchers, client state, mutations, and view. All co-located in one object. The spec <em>is</em> the page.</p>
-          </div>
-          <div class="brut-code-block">
-            ${codeWindow({ content: exampleSpec, filename: 'src/pages/dashboard.js', lang: 'JavaScript' })}
-          </div>
-        </section>
-
-        <section class="brut-constraint">
-          <div class="brut-constraint-inner">
-            <div class="brut-constraint-label">AI + PULSE</div>
-            <h2 class="brut-constraint-h2">Constrained enough<br>to be trusted.<br>Free enough<br>to be creative.</h2>
-            <p class="brut-constraint-lead">The spec format tells an agent exactly how to wire up data, state, and behaviour. What it doesn't do is dictate the design. Layout, typography, CSS — those are still real decisions. The agent makes them. Pulse just makes sure the page it builds actually works.</p>
-            <div class="brut-constraint-cols">
-              <div class="brut-col">
-                <div class="brut-col-head">The structure is fixed</div>
-                <ul class="brut-col-list">
-                  <li>One spec format. No ambiguity about how a page should be built</li>
-                  <li>Schema validation at startup. Bad output is rejected before it ships</li>
-                  <li>Security, SSR, and caching are part of the architecture. Not optional</li>
-                  <li>Consistent, reviewable output across every agent and every session</li>
-                </ul>
-              </div>
-              <div class="brut-col brut-col--hi">
-                <div class="brut-col-head brut-col-head--hi">The design is not</div>
-                <ul class="brut-col-list">
-                  <li>The view is a plain JS function. The agent writes whatever HTML it wants</li>
-                  <li>CSS, layout, and typography are entirely up to the agent</li>
-                  <li>A component library is there when needed. Custom HTML when it isn't</li>
-                  <li>The result looks considered because the agent had room to make it so</li>
-                </ul>
-              </div>
-            </div>
-          </div>
-        </section>
-
-        <section class="brut-versus">
-          <div class="brut-versus-header">
-            <div class="brut-versus-label">HOW PULSE COMPARES</div>
-            <h2 class="brut-versus-h2">Constraints enforced.<br>Not recommended.</h2>
-          </div>
-          <div class="versus-table-wrap table-sticky-col">
-            <table class="brut-table">
-              <thead>
-                <tr>
-                  <th></th>
-                  <th class="brut-th-pulse">
-                    <svg width="12" height="12" viewBox="0 0 24 24" fill="none" aria-hidden="true" style="vertical-align:middle;margin-right:.3rem">
-                      <path d="M13 2L4.5 13.5H11L10 22L19.5 10.5H13L13 2Z" fill="currentColor" stroke="currentColor" stroke-width="1" stroke-linejoin="round"/>
-                    </svg>PULSE
-                  </th>
-                  <th>Next.js / Remix</th>
-                  <th>SvelteKit</th>
-                </tr>
-              </thead>
-              <tbody>
-                <tr>
-                  <th scope="row">Ways to write a page</th>
-                  <td class="v-yes">One: the spec schema</td>
-                  <td class="v-no">App Router, Pages Router, RSC, client components, loaders…</td>
-                  <td class="v-no">+page.svelte, +page.server.js, load(), form actions…</td>
-                </tr>
-                <tr>
-                  <th scope="row">Agent-readable structure</th>
-                  <td class="v-yes">One JS object per page</td>
-                  <td class="v-no">Files, folders, magic exports spread across dirs</td>
-                  <td class="v-no">Files, folders, Svelte syntax</td>
-                </tr>
-                <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 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 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>
-                  <th scope="row">Security headers</th>
-                  <td class="v-yes">On every response, built in</td>
-                  <td class="v-no">Manual middleware or plugin</td>
-                  <td class="v-no">Manual hooks setup</td>
-                </tr>
-                <tr>
-                  <th scope="row">Runtime dependencies</th>
-                  <td class="v-yes">Zero. Pure Node.js HTTP</td>
-                  <td class="v-no">React, 50+ transitive packages</td>
-                  <td class="v-no">Svelte runtime + adapters</td>
-                </tr>
-                <tr>
-                  <th scope="row">Production build step</th>
-                  <td class="v-yes">Server needs none. <code>node server.js</code> is production</td>
-                  <td class="v-no">Required: <code>next build</code></td>
-                  <td class="v-no">Required: <code>vite build</code></td>
-                </tr>
-              </tbody>
-            </table>
-          </div>
-        </section>
-
-        <section class="brut-pillars">
-          <div class="brut-pillar">
-            <div class="brut-pillar-icon">${iconZap({ size: 36 })}</div>
-            <div class="brut-pillar-body">
-              <h3>Performance by design</h3>
-              <p>The shell streams to the browser instantly. Deferred segments arrive as data resolves. ~4 kB of JS on first visit. Zero CLS. Immutable bundle caching on deploy. Not configured. Structural.</p>
-            </div>
-          </div>
-          <div class="brut-pillar brut-pillar--alt">
-            <div class="brut-pillar-icon">${iconShield({ size: 36 })}</div>
-            <div class="brut-pillar-body">
-              <h3>Safe by design</h3>
-              <p>Security headers on every response, including 404 and 500. Declarative constraints enforce state bounds after every mutation. Guard runs before any server fetcher. Not a plugin. Part of the pipeline.</p>
-            </div>
-          </div>
-          <div class="brut-pillar">
-            <div class="brut-pillar-icon">${iconSettings({ size: 36 })}</div>
-            <div class="brut-pillar-body">
-              <h3>Nothing to configure</h3>
-              <p>No bundler config. No runtime dependencies to install, audit, or upgrade. <code>node server.js</code> is production. No breaking upgrades. Page files have no framework imports to version.</p>
-            </div>
-          </div>
-        </section>
-
-        ${server.metrics ? `<section class="brut-metrics">
-          <div class="brut-metrics-label">BY THE NUMBERS</div>
-          <h2 class="brut-metrics-h2">Performance you can measure.</h2>
-          <p class="brut-metrics-sub">Report generated ${server.metrics.generatedAt} · measured from a real Pulse build</p>
-          <div class="brut-metrics-grid">
-            <div class="brut-metrics-group">
-              <div class="brut-metrics-group-label">Lighthouse</div>
-              ${server.metrics.lighthouse.map(m => `
-                <div class="brut-metric">
-                  <span class="brut-metric-val brut-metric-val--hi">${m.value}</span>
-                  <span class="brut-metric-lbl">${m.label}</span>
-                </div>`).join('')}
-            </div>
-            <div class="brut-metrics-group">
-              <div class="brut-metrics-group-label">Bundle sizes</div>
-              ${server.metrics.bundles.map(m => `
-                <div class="brut-metric">
-                  <span class="brut-metric-val">${m.value}</span>
-                  <span class="brut-metric-lbl">${m.label}</span>
-                </div>`).join('')}
-            </div>
-            <div class="brut-metrics-group">
-              <div class="brut-metrics-group-label">Web Vitals</div>
-              ${server.metrics.vitals.map(m => `
-                <div class="brut-metric">
-                  <span class="brut-metric-val brut-metric-val--hi">${m.value}</span>
-                  <span class="brut-metric-lbl">${m.label}</span>
-                </div>`).join('')}
-            </div>
-            <div class="brut-metrics-group">
-              <div class="brut-metrics-group-label">Architecture</div>
-              ${server.metrics.architecture.map(m => `
-                <div class="brut-metric">
-                  <span class="brut-metric-val brut-metric-val--accent">${m.value}</span>
-                  <span class="brut-metric-lbl">${m.label}</span>
-                </div>`).join('')}
-            </div>
-          </div>
-        </section>` : ''}
-
-        <section class="brut-cta">
-          <h2 class="brut-cta-h2">Your first page<br>in under<br>2 minutes.</h2>
-          <p class="brut-cta-lead">One spec object. Server data, client state, mutations, and view. In one place. Streaming SSR, security headers, and 100 Lighthouse scores come with it. Nothing to configure.</p>
-          <p class="brut-cta-note">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="brut-cta-actions">
-            <a href="/getting-started" class="brut-btn-primary brut-btn-primary--inv">Get Started</a>
-            <a href="/spec" class="brut-btn-ghost brut-btn-ghost--light">Read the Spec</a>
-          </div>
-        </section>
-
-      </main>
-
-      <footer class="brut-footer">
-        <span>MIT License</span>
-        <span class="brut-footer-sep">·</span>
-        <a href="https://github.com/invisibleloop/pulse-framework" target="_blank" rel="noopener" aria-label="GitHub (opens in new tab)">GitHub</a>
-        <span class="brut-footer-sep">·</span>
-        <a href="/getting-started">Get started in 2 minutes</a>
-      </footer>
-
-    </div>
-  `,
-}

package/docs/src/pages/how-it-works.js

@@ -1,244 +0,0 @@
-import { renderLayout, h1, lead, section, callout } from '../lib/layout.js'
-import { prevNext } from '../lib/nav.js'
-import { card } from '../../../src/ui/index.js'
-
-const { prev, next } = prevNext('/how-it-works')
-
-// Numbered vertical flow diagram — raw HTML (creative override), replacing
-// the removed timeline()/timelineItem() components. Styled via .hiw-flow*
-// classes in docs.css.
-const flowStep = ({ dot, label, content }) => `
-  <li class="hiw-flow-item">
-    <div class="hiw-flow-side">
-      <div class="hiw-flow-connector hiw-flow-connector--before"></div>
-      <div class="hiw-flow-dot" aria-hidden="true">${dot}</div>
-      <div class="hiw-flow-connector hiw-flow-connector--after"></div>
-    </div>
-    <div class="hiw-flow-main">
-      <span class="hiw-flow-label">${label}</span>
-      <div class="hiw-flow-body">${content}</div>
-    </div>
-  </li>
-`
-
-const agentFlow = `<ol class="hiw-flow">${[
-    {
-      dot: '1',
-      label: 'Understand',
-      content: card({ content: `<strong style="color:var(--ui-text)">Read the guide and inspect the project</strong><p style="color:var(--ui-muted);margin:.25rem 0 0">The agent fetches <code>pulse://workflow</code> and the relevant <code>pulse://guide/*</code> sections, then calls <code>pulse_list_structure</code> to see every existing page, component, and store. Ambiguities are surfaced before any files are touched.</p>` }),
-    },
-    {
-      dot: '2',
-      label: 'Plan',
-      content: card({ content: `<strong style="color:var(--ui-text)">Present a plan — wait for confirmation</strong><p style="color:var(--ui-muted);margin:.25rem 0 0">Before writing anything the agent describes what it intends to build: the route, state shape, server data, interactions, and any components or integrations it will use. The task does not proceed until you confirm.</p>` }),
-    },
-    {
-      dot: '3',
-      label: 'Build',
-      content: card({ content: `<strong style="color:var(--ui-text)">Write the spec and any supporting files</strong><p style="color:var(--ui-muted);margin:.25rem 0 0">The spec is written as a plain JS object: route, state, server data, mutations, actions, view. The guide constrains every decision — where state lives, how validation is wired, how the view is structured.</p>` }),
-    },
-    {
-      dot: '4',
-      label: 'Validate',
-      content: card({ content: `<strong style="color:var(--ui-text)">Call <code>pulse_validate</code> — fix all errors and warnings</strong><p style="color:var(--ui-muted);margin:.25rem 0 0">The spec is checked against the Pulse schema. Every error and warning is resolved before moving on — missing hydrate, heading order violations, missing escaping, structural mistakes. A clean output is the gate to the next phase.</p>` }),
-    },
-    {
-      dot: '5',
-      label: 'Browser',
-      content: card({ content: `<strong style="color:var(--ui-text)">Screenshot + Lighthouse — desktop and mobile</strong><p style="color:var(--ui-muted);margin:.25rem 0 0">The agent navigates to the route, takes a screenshot to confirm the rendered output, then runs Lighthouse on both desktop and mobile. Accessibility, Best Practices, and SEO must all be 100. Any failure is fixed and re-verified before continuing.</p>` }),
-    },
-    {
-      dot: '6',
-      label: 'Tests',
-      content: card({ content: `<strong style="color:var(--ui-text)">Write tests, run them, fix failures</strong><p style="color:var(--ui-muted);margin:.25rem 0 0">Unit tests cover any pure logic extracted from the spec. View tests use <code>renderSync</code> / <code>render</code> to assert HTML output. All tests must pass. When fixing a bug, a failing test is written first to pin the behaviour.</p>` }),
-    },
-    {
-      dot: '7',
-      label: 'Review',
-      content: card({ content: `<strong style="color:var(--ui-text)">Call <code>pulse_review</code> — only after phases 4–6 all pass</strong><p style="color:var(--ui-muted);margin:.25rem 0 0">The agent switches into reviewer mode — reading the source and rendered output against the full spec checklist. Accessibility, empty states, error handling, component usage, and security are all checked. The review agent is always last.</p>` }),
-    },
-    {
-      dot: '8',
-      label: 'Fix and re-verify',
-      content: card({ content: `<strong style="color:var(--ui-text)">Fix every review issue — re-run affected gates</strong><p style="color:var(--ui-muted);margin:.25rem 0 0">Every issue raised in review is resolved. Validate, Lighthouse, and tests are re-run to confirm all gates still pass. The task is complete only when every phase clears cleanly.</p>` }),
-    },
-    {
-      dot: '✓',
-      label: 'Done',
-      content: card({ content: `<strong style="color:var(--ui-text)">The spec is the source of truth</strong><p style="color:var(--ui-muted);margin:.25rem 0 0">Validate clean. Lighthouse 100. Tests passing. Review clear. When all four gates pass, the page is done.</p>` }),
-    },
-  ].map(flowStep).join('')}</ol>`
-
-export default {
-  route: '/how-it-works',
-  meta: {
-    theme:       'light',
-    title: 'How It Works — Pulse Docs',
-    description: 'How the Pulse MCP server gives an AI agent the knowledge and tools to build Pulse apps correctly.',
-    styles: ['/pulse-ui.css', '/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/how-it-works',
-    prev,
-    next,
-    content: `
-      ${h1('How It Works')}
-      ${lead('When you run <code>pulse</code> in a project directory, a Model Context Protocol (MCP) server starts alongside the dev server. That MCP server is what gives your AI agent the knowledge, tools, and guardrails to build Pulse pages correctly — without you having to explain the framework in every prompt.')}
-
-      ${section('mcp', 'The Pulse MCP server')}
-      <p>MCP is a standard protocol that connects AI agents to external tools and knowledge. When Claude (or any MCP-compatible agent) opens a Pulse project, the MCP server is automatically detected and two things happen:</p>
-      <ul>
-        <li>The agent gains access to <strong>resources</strong> — read-only documents it can fetch at any time</li>
-        <li>The agent gains access to <strong>tools</strong> — functions it can call to inspect and modify the project</li>
-      </ul>
-      <p>Together these replace the need to paste documentation into a system prompt or rely on the agent's training data to know how Pulse works.</p>
-
-      ${section('resources', 'Resources: what the agent knows')}
-      <p>The MCP server exposes read-only documents the agent fetches at any time. There are two top-level resources and a set of focused guide sections:</p>
-
-      <dl class="definition-list">
-        <dt><code>pulse://quickstart</code></dt>
-        <dd>Workflow phases, spec skeleton, component rules, and theming essentials combined into a single fetch. Used for targeted edits, bug fixes, or simple one-shot page builds — avoids loading the full guide for small tasks.</dd>
-
-        <dt><code>pulse://workflow</code></dt>
-        <dd>The full build workflow — every phase, pass gate, and ordering rule. The agent reads this before starting any new page or project.</dd>
-
-        <dt><code>pulse://persona</code></dt>
-        <dd>The quality bar the agent holds itself to: always write correct SSR, always handle errors, never skip empty states, never hardcode colours, never use <code>data-event</code> on text inputs. The persona defines what "done" means.</dd>
-      </dl>
-
-      <p>The guide is split into topic sections the agent fetches as needed:</p>
-      <dl class="definition-list">
-        <dt><code>pulse://guide/spec</code></dt>
-        <dd>Spec format — state, mutations, actions, streaming SSR, validation, key rules, and form layout.</dd>
-
-        <dt><code>pulse://guide/server</code></dt>
-        <dd>Server data fetchers, global store, persist, cookies, redirects, and POST handling.</dd>
-
-        <dt><code>pulse://guide/styles</code></dt>
-        <dd>CSS tokens, theming, custom fonts, and utility classes.</dd>
-
-        <dt><code>pulse://guide/routing</code></dt>
-        <dd>Client-side navigation, page discovery, and dynamic routes.</dd>
-
-        <dt><code>pulse://guide/components</code></dt>
-        <dd>All UI components and their props, icons, charts, and composition patterns.</dd>
-
-        <dt><code>pulse://guide/examples</code></dt>
-        <dd>Complete working page examples covering common patterns.</dd>
-
-        <dt><code>pulse://guide/templates</code></dt>
-        <dd>Pre-built landing page templates, adaptation rules, and theme CSS patterns. Fetched when building a new branded site or landing page.</dd>
-
-        <dt><code>pulse://guide/design-references</code></dt>
-        <dd>Twelve design directions with vibes, component combinations, palette patterns, and signature moves. Fetched during intake to pick the right aesthetic rather than defaulting to a generic SaaS look.</dd>
-
-        <dt><code>pulse://guide/design-gallery</code></dt>
-        <dd>All templates with visual descriptions and key components. Includes critical prop-name references and component recipes for cards, stat strips, and forms. Fetched when adapting a template or combining components.</dd>
-
-        <dt><code>pulse://guide/explore</code></dt>
-        <dd>Zone-based layout thinking, seven structural gestures, raw HTML patterns without components, and an anti-pattern checklist. Fetched when a distinctive or unusual layout is needed.</dd>
-      </dl>
-
-      ${callout('note', 'The guide is authoritative. When there is a question about how something should be structured — where state lives, how validation is wired, how streaming works — the guide answers it. The agent does not guess.')}
-
-      ${section('tools', 'Tools: what the agent can do')}
-      <p>The MCP server provides tools across five categories:</p>
-
-      <h3 class="doc-h3">Design &amp; intake</h3>
-      <dl class="definition-list">
-        <dt><code>pulse_extract_inspiration</code></dt>
-        <dd>Extracts a structured design brief from a URL or image shared as inspiration. Called before <code>pulse_intake</code> when the user says "I like the look of X" — it tells the agent exactly what to observe and capture.</dd>
-
-        <dt><code>pulse_intake</code></dt>
-        <dd>Captures the product name, pitch, features, palette, vibe, and anti-style before scaffolding any new page or branded template. Returns a structured brief with copy-ready content, early contrast warnings, and component suggestions. Always runs before <code>pulse_sketch</code>.</dd>
-
-        <dt><code>pulse_sketch</code></dt>
-        <dd>Generates three structurally distinct layout directions (full-bleed, asymmetric split, editorial flow, etc.) before any code is written. Called after <code>pulse_intake</code> — prevents every project from defaulting to the same centred-hero layout.</dd>
-
-        <dt><code>pulse_intent</code></dt>
-        <dd>Intent engine — describe what you want to build and get back a matched archetype, recommended components, a ready-to-adapt spec scaffold, and which guide sections to read first. An alternative entry point to <code>pulse://workflow</code> for targeted tasks.</dd>
-
-        <dt><code>pulse_design_review</code></dt>
-        <dd>Reviews the built page's visual design against the original product brief from <code>pulse_intake</code>. Checks whether the design looks and feels appropriate for the product, audience, and vibe. Runs after screenshot, before Lighthouse.</dd>
-
-        <dt><code>pulse_layout_review</code></dt>
-        <dd>Multi-viewport layout review — checks for overflow, collapsed sections, and broken images at different screen widths. Runs after design approval but before Lighthouse, catching layout issues that Lighthouse doesn't flag.</dd>
-
-        <dt><code>pulse_tokens</code></dt>
-        <dd>Lists all available <code>--ui-*</code> CSS custom property tokens from the installed <code>pulse-ui.css</code>. Used before writing theme overrides to avoid guessing token names.</dd>
-
-        <dt><code>pulse_check_contrast</code></dt>
-        <dd>Static WCAG contrast checker. Extracts colour variable definitions from a theme file and checks common foreground/background pairings for WCAG AA compliance. Run immediately after writing a theme file to catch palette mistakes before Lighthouse.</dd>
-      </dl>
-
-      <h3 class="doc-h3">Scaffolding</h3>
-      <dl class="definition-list">
-        <dt><code>pulse_create_page</code></dt>
-        <dd>Creates a new page spec file from a correct template. The filename determines the route — <code>about.js</code> becomes <code>/about</code>, <code>posts/[slug].js</code> becomes <code>/posts/:slug</code>. The file is written to <code>src/pages/</code> and picked up by the server automatically.</dd>
-
-        <dt><code>pulse_create_component</code></dt>
-        <dd>Creates a reusable view component in <code>src/components/</code>. Components export named functions that return HTML strings — no classes, no JSX, no lifecycle hooks.</dd>
-
-        <dt><code>pulse_create_store</code></dt>
-        <dd>Creates a global store module in <code>src/store/</code>. Stores hold shared state (cart, user session, theme) that multiple pages can subscribe to and mutate.</dd>
-
-        <dt><code>pulse_create_action</code></dt>
-        <dd>Scaffolds a reusable server action — useful for shared form submission logic, API calls, or mutations that appear on more than one page.</dd>
-      </dl>
-
-      <h3 class="doc-h3">Inspection</h3>
-      <dl class="definition-list">
-        <dt><code>pulse_status</code></dt>
-        <dd>Project health snapshot — pages, routes, server status, last build. Called at the start of a session to orient quickly without reading files individually.</dd>
-
-        <dt><code>pulse_list_structure</code></dt>
-        <dd>Lists every page, component, and store that already exists in the project. The agent calls this before creating anything — to avoid duplication and to understand what the codebase already provides.</dd>
-
-        <dt><code>pulse_fetch_page</code></dt>
-        <dd>Reads the full source of an existing spec file. Used when the agent needs to understand an existing page before editing it, or when a review of the current state is needed.</dd>
-
-        <dt><code>pulse_list_icons</code></dt>
-        <dd>Lists all available Pulse UI icon names, grouped by category. Called before importing icons — the agent never guesses a name.</dd>
-      </dl>
-
-      <h3 class="doc-h3">Validation &amp; review</h3>
-      <dl class="definition-list">
-        <dt><code>pulse_validate</code></dt>
-        <dd>Validates a spec against the Pulse schema. Returns errors (which block progress) and warnings (which must also be resolved). The agent calls this after writing or editing every spec file.</dd>
-
-        <dt><code>pulse_suggest</code></dt>
-        <dd>Draft-mode feedback — paste a partial or complete spec and get constructive suggestions before running the hard validator. Unlike <code>pulse_validate</code>, it is collaborative rather than a gate: it notices patterns, spots likely omissions, and offers ideas. Used mid-build for a second opinion.</dd>
-
-        <dt><code>pulse_review</code></dt>
-        <dd>Switches the agent into reviewer mode. Returns the spec source, the rendered HTML output, and a structured checklist covering accessibility, empty states, error handling, component usage, security, and correctness. The agent reads its own output critically and fixes every issue before continuing.</dd>
-
-        <dt><code>pulse_run_tests</code></dt>
-        <dd>Runs the project test suite (<code>npm test</code>) and returns the full output. Called after writing or editing specs to verify nothing is broken.</dd>
-      </dl>
-
-      <h3 class="doc-h3">Server &amp; maintenance</h3>
-      <dl class="definition-list">
-        <dt><code>pulse_restart_server</code></dt>
-        <dd>Restarts the Pulse dev server. Called after structural changes — adding a new page, modifying the server entry — to reload all specs and re-register routes.</dd>
-
-        <dt><code>pulse_build</code></dt>
-        <dd>Builds the project for production. Bundles specs, hashes assets, and writes the manifest. Called when the agent needs to verify the production build or prepare a release.</dd>
-
-        <dt><code>pulse_check_version</code></dt>
-        <dd>Reports the installed Pulse version and whether an update is available.</dd>
-
-        <dt><code>pulse_update</code></dt>
-        <dd>Updates the Pulse package to the latest version and copies the latest UI assets and agent files into the project.</dd>
-      </dl>
-
-      ${section('flow', 'What happens when you ask for something')}
-
-      ${agentFlow}
-
-      ${section('why-mcp', 'Why MCP instead of a system prompt')}
-      <p>A system prompt is static — it cannot see your project, cannot validate your code, and cannot guarantee the agent uses the right version of the framework. The MCP server is dynamic: it reads the guide from the installed version of Pulse, inspects the actual files in your project, and calls real validation on the spec the agent just wrote.</p>
-      <p>The result is that the agent builds correctly on the first attempt far more often — not because it is smarter, but because the feedback loop is tighter and the knowledge is always current.</p>
-    `,
-  }),
-}