@invisibleloop/pulse 0.12.3 → 0.14.2

package/src/agent/workflow.md

@@ -1,57 +1,193 @@
 # Build Workflow
 
-Every task follows this sequence exactly. Each phase has a pass gate — you do not move to the next phase until the gate is cleared. Do not skip phases. Do not reorder them.
+---
+
+## Quick decision tree
+
+| Situation | Start here |
+|---|---|
+| New site, new branded page, or "build me X from scratch" | `pulse_intake` → `pulse_sketch` → `pulse_intent` → build |
+| Editing an existing page, adding a section, fixing a bug | Go straight to Step 1 — Understand |
+| "Add X to the existing Y" (one-liner) | Read the relevant file, make the change, run `/verify` |
+| Stuck on which component to use | `pulse_intent("describe what I'm building")` |
+| Colours failing contrast / unsure about palette | `pulse_check_contrast` |
+| Something looks wrong in the browser | `pulse_restart_server`, then `/verify` |
+| Lighthouse < 100 | Fix the flagged audit, run `/verify` again — do not skip to commit |
+
+---
+
+## New project or new page? Start with Intake
+
+For any **new page, landing page, or branded site**, run the intake sequence first:
+
+```
+0. ASK:  "Do you have any design inspiration — a site you love, a screenshot, or a mood board
+          image? Drop images into public/intake/ or paste a URL and I'll extract the design
+          intent before we start."   ← MANDATORY. Ask this before doing anything else.
+0b. pulse_extract_inspiration(url/image) → structured design brief  [if user supplies reference]
+1. pulse_intake(name, pitch, features, ...)   → product brief + contrast check
+2. pulse_sketch(brief, vibe?, antiStyle?)     → 3 layout directions to choose from
+3. pulse_intent(description)                  → archetype + scaffold + guide list
+```
+
+- **Step 0 — Ask for inspiration first (mandatory):** Before calling any tool or presenting any plan, ask the user: *"Do you have any design inspiration — a site you love, a screenshot, or a mood board image? Drop images into `public/intake/` or paste a URL and I'll extract the design intent before we start."* Wait for the answer. Do not skip this question, even if the user's brief already seems detailed. Check `public/intake/` for any images already dropped there.
+- **`pulse_extract_inspiration`** — call this after step 0 if the user supplies a URL, site name, or image they like. Also call it for any images already present in `public/intake/`. Gives you a structured extraction template: visit the URL or analyse the image with your vision tools, extract colours, layout, typography, and feel, then feed those findings into pulse_intake. If the user explicitly says they have no reference, skip this step.
+- **`pulse_intake`** — captures the real content (name, pitch, features, palette, vibe, what it should NOT look like). Returns a brief with copy-ready content and early contrast warnings. Always ask the user one question at a time — never multi-choice for open-ended questions.
+- **`pulse_sketch`** — generates 3 structurally distinct layout directions (full-bleed, asymmetric split, typography-only, editorial, dense grid, story scroll, content-first). **Call this before writing any code.** Prevents defaulting to centred hero + three-column features every time.
+- **Skip `pulse_sketch` only** when the vibe is `corporate` or `minimal` AND the user hasn't expressed any structural preference. For `playful`, `bold`, `brutalist`, `retro`, or `neon` vibes, `pulse_sketch` is mandatory — templates have default section orders that actively fight these vibes.
+- **`pulse_intent`** — maps the chosen direction to a spec scaffold and tells you which guides to read.
+
+For **small edits, bug fixes, or "add X to existing Y"** — skip intake/sketch and go straight to Step 0 below.
 
 ---
 
-## Phase 1 — Understand
+## Step 0 — Intent (always first for non-trivial builds)
+
+After intake + sketch (or directly for targeted tasks), call `pulse_intent`:
+
+```
+pulse_intent("a settings page with profile editing and a save action")
+```
+
+It returns a matched archetype, recommended components, a starter spec scaffold, and which guide sections to read. This replaces hunting through guide sections manually.
+
+If the user's request is already very specific (a one-liner edit, a bug fix, "add X to the existing Y"), skip this and go straight to Understand.
 
-Before writing a single line of code:
+---
+
+## Step 1 — Understand
 
-1. Fetch `pulse://guide` for the guide index.
-2. Fetch any topic sections you need (`pulse://guide/spec`, `pulse://guide/components`, etc.).
-3. Call `pulse_list_structure` to see what pages and components already exist.
+Call `pulse_list_structure` to see what already exists. Fetch only the guide sections relevant to your intent (the `pulse_intent` response tells you which ones).
 
-Do not guess about props, patterns, or rules. If you are unsure, fetch the relevant guide section.
+Do not fetch every guide section for every task. Fetch what you need.
 
 ---
 
-## Phase 2 — Plan (confirmation gate)
+## Step 2 — Plan
 
-Before building, output a concise plan:
+Decide the complexity tier (see below) and confirm with the user if the task is non-trivial. Output a concise plan:
 
-- What page(s) or component(s) you will create or modify
-- The route, state shape, mutations/actions, and server fetchers
+- Route, state shape, mutations/actions, server fetchers
 - Which UI components you will use
-- Any shared components you will create or reuse
+- Files you will create or modify
+
+**Skip confirmation for trivially small tasks** (add a button, fix a label, swap a component). When in doubt, confirm.
+
+**When asking the user questions:** ask one question at a time. If you present choices, use at most 4 options — the `ask_user` tool enforces this limit and will error if exceeded. For open-ended questions (names, copy, features, hex colours), ask as plain prose with no choices at all.
+
+---
+
+## Complexity tiers
+
+Not every task needs all 8 phases. Match the tier to the task:
+
+### Tier 1 — Simple (static or read-only content)
+
+*Applies to:* landing pages, blog posts, profile pages, any page with no mutations or actions.
+
+| Phase | Action | Gate |
+|---|---|---|
+| 1 | Intent + Understand | — |
+| 2 | Build | announce brief → write files |
+| 3 | Validate | `pulse_validate` clean |
+| 4a | Design approval | screenshot → show user → **wait for approval** *(new-build only)* |
+| 4b | Verify | `pulse_design_review` (if intake ran) → `pulse_layout_review` → Lighthouse desktop + mobile (100/100/100) |
+
+No tests required for pure view specs with no logic. Add tests if the view has non-trivial helper functions.
+
+### Tier 2 — Standard (interactive, single-purpose)
+
+*Applies to:* forms, CRUD pages, settings, auth flows, dashboards without complex state machines.
+
+| Phase | Action | Gate |
+|---|---|---|
+| 1 | Intent + Understand | — |
+| 2 | Plan | user confirmation (skip if unambiguous) |
+| 3 | Build | announce brief → write files |
+| 4 | Validate | `pulse_validate` clean |
+| 5a | Design approval | screenshot → show user → **wait for approval** *(new-build only)* |
+| 5b | Verify | `pulse_design_review` (if intake ran) → `pulse_layout_review` → Lighthouse desktop + mobile (100/100/100) + CLS 0.00 |
+| 6 | Tests | mutations, view landmarks, any utility functions |
+| 7 | Code review | `pulse_review` — only after 5–6 pass |
+
+### Tier 3 — Complex (multi-step, shared state, or security-sensitive)
+
+*Applies to:* multi-step wizards, pages with guards and auth, store-connected pages, anything touching sensitive data or complex branching state.
+
+All phases as originally defined — full flow with every gate.
 
-Wait for the user to confirm or adjust the plan before writing any code.
+| Phase | Action | Gate |
+|---|---|---|
+| 1 | Intent + Understand | — |
+| 2 | Plan | **user confirmation required** |
+| 3 | Build | announce brief → write files |
+| 4 | Validate | `pulse_validate` clean |
+| 5a | Design approval | screenshot → show user → **wait for approval** *(new-build only)* |
+| 5b | Verify | `pulse_design_review` (if intake ran) → `pulse_layout_review` → Lighthouse 100/100/100 + CLS 0.00, desktop + mobile |
+| 6 | Tests | full coverage: mutations, actions, guards, view |
+| 7 | Code review | `pulse_review` |
+| 8 | Fix + re-verify | re-run all gates |
 
-**Skip this gate only if the task is unambiguous and small** (e.g. "add a delete button to the existing list page"). When in doubt, confirm.
+**If in doubt, default to Tier 2.** Choosing a lower tier than the task warrants means you'll hit problems at gates — the tiers are a shortcut, not a way to skip quality.
 
 ---
 
 ## Phase 3 — Build
 
-### 3a — Announce before writing
+### 3a — Decide: components or creative override
 
-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:
+**Two valid modes — choose one and state it in the build brief:**
+
+**Mode A — Components first (default)**
+Use Pulse UI components for all standard UI patterns. Before writing any view HTML, grep `src/ui/index.js` for the components you need:
+
+```bash
+grep -E "^export" src/ui/index.js | head -20
+```
+
+Or use the guide-components table. Never write these patterns from scratch in Mode A:
+
+- Hero section → `hero()`
+- Product/service cards → `card()`
+- Image + text layouts → `media()`
+- Horizontal strips → `banner()`
+- Feature tiles → `feature()`
+- Testimonials → `testimonial()`
+- CTAs → `cta()`
+
+If you're about to type `class="hero"` or `class="product-card"` in Mode A, stop — use the component instead.
+
+**Mode B — Creative override (raw HTML throughout)**
+When the design intent calls for a more expressive, unconventional, or typographically-driven layout that components would constrain, you may build with raw HTML throughout. This is a deliberate design decision, not a shortcut.
+
+Rules for Mode B:
+- Load `/pulse-ui.css` in `meta.styles` — the token system is still required
+- Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there is a specific design reason
+- The quality gate is 100/100/100/100 Lighthouse on both desktop and mobile — this replaces the component checklist as the pass bar
+
+Announce Mode B explicitly in the build brief: *"Mode B — component-free, raw HTML for creative control."*
+
+### 3b — Announce before writing
+
+Before writing any file, output a build brief:
 
 ```
-Building: <page name> (<route>)
-State:     <fields and types, or "none">
-Mutations: <list, or "none">
-Actions:   <list with brief description, or "none">
-Server:    <fetcher names and what they fetch, or "none">
-View:      <key sections / landmarks>
-Files:     <list of files that will be written>
+Building:   <page name> (<route>)
+Mode:       A — components first | B — creative override (raw HTML, reason: ...)
+State:      <fields and types, or "none">
+Mutations:  <list, or "none">
+Actions:    <list with brief description, or "none">
+Server:     <fetcher names and what they fetch, or "none">
+Components: <which UI components you will use, or "none — Mode B">
+View:       <key sections / landmarks>
+Files:      <list of files that will be written>
 ```
 
-Output this before making any tool calls. Do not skip it for "simple" pages — a one-liner is fine for simple pages, but always output something.
+One-liners are fine for simple pages, but always output something. **Declaring the mode upfront** makes the design intent explicit and prevents unnecessary component-reinvention warnings during review.
 
-### 3b — Write
+### 3c — Write
 
-Write each file using the **Write tool** — not `pulse_create_page`. This shows the user a readable diff. Before each file write, output a one-line status (present-progressive, no tick — the work hasn't happened yet):
+Write each file using the **Write tool** — not `pulse_create_page`. This shows the user a readable diff. Before each file write, output a one-line status (present-progressive):
 
 ```
 Writing src/pages/my-page.js...
@@ -63,9 +199,11 @@ After the Write tool completes, call `pulse_create_page(name)` to register the p
 ✓ src/pages/my-page.js written and registered.
 ```
 
-**Rule: never output `✓` before the tool call that confirms the result. Use present-progressive (`Writing...`, `Running...`, `Checking...`) for pre-tool announcements.**
+### 3d — Suggest (optional but recommended)
+
+After writing the first draft, call `pulse_suggest(content)` before running the hard validator. It catches obvious omissions collaboratively — a second opinion, not a gate.
 
-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.
+**Rule: never output `✓` before the tool call that confirms the result.**
 
 ---
 
@@ -74,11 +212,11 @@ If multiple files are needed (spec + shared component, spec + test stub, etc.),
 Run `pulse_validate` on the spec file.
 
 - **If it passes:** output `✓ Validation clean — checking browser...` and continue.
-- **If it fails:** fix every error and every warning, then re-run. Repeat until clean. Do not continue until validation is clean.
+- **If it fails:** fix every error and every warning, then re-run. Repeat until clean.
 
 ---
 
-## Phase 5 — Browser check (pass gate)
+## Phase 5 — Browser check
 
 **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
@@ -86,65 +224,113 @@ Run `pulse_validate` on the spec file.
 
 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.
+---
+
+### Phase 5a — Design approval *(new builds from `pulse_intake` only)*
+
+**This phase applies when `pulse_intake` ran** — i.e. you are building a new page or site from scratch, not editing an existing one. For edits, bug fixes, or "add X to existing Y", skip to Phase 5b immediately.
+
+1. Take a screenshot of the built page
+2. Describe what you see in 2–3 plain sentences — layout structure, visual tone, key sections. Do NOT list features or code details.
+3. **Ask the user directly:** *"Happy with the layout and direction, or any changes before I run tests and Lighthouse?"*
+4. **Wait for their response before doing anything else.** Do not run design_review, layout_review, or Lighthouse until you have a clear go-ahead.
+
+**If the user requests changes:**
+- Make the edits
+- Take a new screenshot
+- Describe what changed
+- Ask again
+- Repeat until approved — each iteration is design-only, no Lighthouse between rounds
+
+**If the user approves (or says "looks good", "go ahead", "yes", etc.):**
+- Continue to Phase 5b
 
-`/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.
+> The point of this gate is to let the user redirect the design before expensive, slow checks run. A Lighthouse build takes ~90 seconds — do not start it until the user has seen and approved the visual result.
 
-Pass gates (all must be met before continuing to Phase 6):
-- Screenshot: no layout or rendering issues
+---
+
+### Phase 5b — Full verification (pass gate)
+
+**Run `/verify` now.** Do not execute these steps manually.
+
+`/verify` validates, screenshots, runs Lighthouse (desktop + mobile), runs the performance trace (LCP + CLS), checks console errors, runs `pulse_review`, and writes the `.pulse-verified` stamp. Running steps manually does not write the stamp.
+
+> **Lighthouse pre-flight:** `/verify` calls `pulse_build` automatically before running Lighthouse, and audits against the production server on port 3001. If you ever call `lighthouse_audit` manually outside `/verify`, you must first run `pulse_build` and navigate to `http://localhost:3001/your-route`. Auditing the dev server (port 3000) will produce misleading results.
+
+### ⛔ After design approval — mandatory steps before continuing
+
+1. `pulse_design_review` (if `pulse_intake` ran) — work through all 7 signals, fix any Fail
+2. `pulse_layout_review <url>` — 390/768/1280px overflow, broken images, collapsed sections
+3. `/verify` — Lighthouse desktop + mobile (100/100/100) + CLS 0.00 + `pulse_review`
+
+**Do not report the page as done until `/verify` writes the `.pulse-verified` stamp.** Skipping Lighthouse means broken contrast, missing landmarks, and Best Practices failures ship to the user.
+
+Pass gates:
+- Design approval: user has explicitly said they're happy with the layout
+- Design review: all 7 signals pass (or intake didn't run)
+- Layout review: no overflow, broken images, or collapsed sections at any viewport
 - Lighthouse desktop: Accessibility, Best Practices, SEO all 100
-- Lighthouse mobile: same pass bar
-- **CLS: 0.00** — any layout shift is a blocker; fix it before proceeding
-- LCP: measured and reported; flag any fixable insight (render-blocking resources, large image delay)
+- Lighthouse mobile: same
+- **CLS: 0.00** — any layout shift is a blocker
 - No console errors
 
-**If any gate fails:** fix the issue and run `/verify` again. Repeat until all gates pass.
+**If any gate fails:** fix and run `/verify` again.
 
-Output after passing: `✓ Verified — writing tests...`
+**Troubleshooting browser profile lock:** If you see "browser already running" or chrome profile errors, another session is using the same Chrome profile. This is a `chrome-devtools-mcp` limitation — only one session can use the profile at a time. Ask the user to close other Claude sessions, or wait for the other session to finish.
+
+**CSS-only changes after verification:** If you've already run `/verify` successfully and the user asks for minor CSS tweaks (margins, colours, spacing), you must run the full `/verify` workflow again — the stop hook checks the file mtime against the stamp. There is no lighter CSS-only check. This is by design: even CSS changes can affect CLS, colour contrast, or readability.
 
 ---
 
-## Phase 6 — Tests (pass gate)
+## Phase 6 — Tests (pass gate, Tier 2+)
 
 Write tests for every spec you created or modified. At minimum:
 
-- Each mutation as a pure function (assert the returned state shape)
+- Each mutation as a pure function
 - View renders expected HTML landmarks
 - Any utility functions defined in the spec
 
-Run the tests. Fix every failure. Repeat until all tests pass.
-
-Output after passing: `✓ Tests passing — ready for review.`
+Run the tests. Fix every failure.
 
 ---
 
-## Phase 7 — Review
+## Phase 7 — Review (Tier 2+)
 
-**Only invoke the Review Agent after all of the above gates have passed.** The reviewer must receive: passing validation, passing Lighthouse (desktop + mobile), and passing tests. Never hand off code that has not cleared every gate.
+Only invoke `pulse_review` after phases 4–6 all pass. It checks the code for correctness, security, accessibility, DRY violations, and checklist adherence.
 
-The Review Agent checks the code for correctness, security, accessibility, DRY violations, and adherence to the checklist. It returns a list of issues.
-
-> Note: `/verify` includes the review step (`pulse_review`) — if you ran `/verify` and it passed cleanly, the Review Agent has already run. You do not need to invoke it again separately.
+> Note: `/verify` includes the review step — if you ran `/verify` and it passed, the Review Agent has already run.
 
 ---
 
-## Phase 8 — Fix review issues
+## Phase 8 — Fix review issues (Tier 3)
 
-Fix every issue raised by the Review Agent. If the fixes touch the spec or view, run `/verify` again — it re-runs validation, Lighthouse, the performance trace, console check, and review in one pass and writes a fresh stamp.
+Fix every issue raised. If fixes touch the spec or view, run `/verify` again.
 
-Only declare the task done after phase 8 is complete and all gates still pass.
+Only declare the task done after all gates still pass.
 
 ---
 
-## Gate summary
+## Summary
 
 ```
-Phase 1  Understand          (no gate — always run)
-Phase 2  Plan                gate: user confirmation
-Phase 3  Build               announce brief → write files (no gate, but always narrate)
-Phase 4  Validate            gate: pulse_validate clean
-Phase 5  Browser             gate: Lighthouse 100/100/100 (A/BP/SEO) + CLS 0.00, desktop + mobile
-Phase 6  Tests               gate: all tests pass
-Phase 7  Review Agent        (only reached after phases 4–6 all pass)
-Phase 8  Fix + re-verify     gate: all gates still pass
+New project / new page:
+  ASK first              → "Do you have any design inspiration — a site, screenshot, or
+                            mood board? Drop into public/intake/ or paste a URL."
+  pulse_extract_inspiration  → (if user supplies a URL or image, or images found in public/intake/)
+  pulse_intake               → capture real content, palette, vibe, anti-style
+  pulse_sketch               → choose 1 of 3 structural layout directions
+  pulse_intent               → get scaffold + guide list
+
+Targeted edit / bug fix:
+  pulse_intent    → (or skip entirely for trivial changes)
+
+Step 1   Understand        pulse_list_structure + relevant guides
+Step 2   Plan             confirm with user if non-trivial
+
+Tier 1  Simple     → phases 3 → 4 → 5a (design approval) → 5b (verify)
+Tier 2  Standard   → phases 3 → 4 → 5a (design approval) → 5b (verify) → 6 → 7
+Tier 3  Complex    → phases 3 → 4 → 5a (design approval) → 5b (verify) → 6 → 7 → 8
+
+Phase 5a is skipped for edits, bug fixes, and "add X to existing Y".
 ```
+

package/src/cli/dev.js

@@ -12,6 +12,7 @@ import path    from 'path'
 import fs      from 'fs'
 import { createServer } from '../server/index.js'
 import { loadPages }    from './discover.js'
+import * as log         from './logger.js'
 
 // ---------------------------------------------------------------------------
 // Args
@@ -57,7 +58,15 @@ const PUBLIC_DIR     = path.join(ROOT, 'public')
   const stampPath  = path.join(PUBLIC_DIR, '.pulse-ui-version')
   const stamp      = fs.existsSync(stampPath) ? fs.readFileSync(stampPath, 'utf8').trim() : null
 
-  if (stamp === pkgVersion) return
+  // Compare CSS byte-length so any content change triggers a re-copy, even
+  // within the same version (e.g. when iterating locally with npm link).
+  const srcCss    = path.join(pkgPublic, 'pulse-ui.css')
+  const dstCss    = path.join(PUBLIC_DIR, 'pulse-ui.css')
+  const srcSize   = fs.existsSync(srcCss) ? fs.statSync(srcCss).size : -1
+  const dstSize   = fs.existsSync(dstCss) ? fs.statSync(dstCss).size : -2
+  const cssStale  = srcSize !== dstSize
+
+  if (stamp === pkgVersion && !cssStale) return
 
   fs.mkdirSync(PUBLIC_DIR, { recursive: true })
   for (const asset of ['pulse-ui.css', 'pulse-ui.js']) {
@@ -98,19 +107,13 @@ const PUBLIC_DIR     = path.join(ROOT, 'public')
 // Start
 // ---------------------------------------------------------------------------
 
-console.log(`⚡ Pulse dev server starting...\n`)
-
 const specs = await loadPages(ROOT)
 
 if (specs.length === 0) {
-  console.error('No pages found in src/pages/. Create a page to get started.')
+  log.error('No pages found in src/pages/. Create a page to get started.')
   process.exit(1)
 }
 
-console.log('Pages:\n')
-specs.forEach(spec => console.log(`  ${spec.route}`))
-console.log()
-
 // ---------------------------------------------------------------------------
 // Hot reload — SSE clients + file watcher
 // ---------------------------------------------------------------------------
@@ -135,16 +138,37 @@ process.on('SIGTERM', closeReloadClients)
 process.on('SIGINT',  closeReloadClients)
 
 let reloadTimer = null
-fs.watch(path.join(ROOT, 'src'), { recursive: true }, () => {
+let lastReload = 0
+
+async function triggerReload(label = 'File changed') {
   clearTimeout(reloadTimer)
   reloadTimer = setTimeout(async () => {
+    const now = Date.now()
+    if (now - lastReload < 100) return
+    lastReload = now
+
     try {
-      const fresh = await loadPages(ROOT, Date.now())
+      const fresh = await loadPages(ROOT, now)
       updateSpecs(fresh)
-    } catch { /* spec error — browser will show the old page, not crash */ }
+      log.info(`${label} — specs reloaded`)
+    } catch (err) {
+      log.error(`Spec reload failed: ${err.message}`)
+    }
     notifyReload()
-  }, 50)
-})
+  }, 200)
+}
+
+// Watch src/ for changes to existing files (spec edits, component edits)
+fs.watch(path.join(ROOT, 'src'), { recursive: true }, () => triggerReload('File changed'))
+
+// Also watch the pages directory explicitly so macOS reliably fires on new file creation.
+// On macOS, fs.watch with recursive=true watches subdirectory contents but may not fire
+// for the parent dir entry when a brand-new file is created. Watching the dir non-recursively
+// catches the "new entry added to this directory" event.
+const pagesDir = path.join(ROOT, 'src', 'pages')
+if (fs.existsSync(pagesDir)) {
+  fs.watch(pagesDir, { recursive: false }, () => triggerReload('New page detected'))
+}
 
 // Tiny script injected into every page — connects to SSE and reloads on change
 // Passed as a function so the server can inject the per-request CSP nonce
@@ -160,13 +184,14 @@ const reloadScript = (nonce) => `<script nonce="${nonce}">
   })();
 </script>`
 
-const { updateSpecs } = createServer(specs, {
+const { updateSpecs } = await createServer(specs, {
   port:      PORT,
   stream:    true,
   staticDir: fs.existsSync(PUBLIC_DIR) ? PUBLIC_DIR : null,
   manifest:  {},        // never use a build manifest in dev — always serve source files
   extraBody: reloadScript,
   dev:       true,
+  agentMode: !!process.env.PULSE_AGENT_MODE,
   ...(_config.csp ? { csp: _config.csp } : {}),
 
   onRequest(req, res) {

package/src/cli/fmt.js

@@ -0,0 +1,113 @@
+/**
+ * Pulse CLI — terminal formatting helpers
+ *
+ * Respects NO_COLOR and CI env vars — falls back to plain text automatically.
+ * Zero dependencies, Node built-ins only.
+ */
+
+const USE_COLOR = !process.env.NO_COLOR && !process.env.CI && process.stdout.isTTY
+
+// ANSI escape helpers — no-ops when colour is disabled
+const c = {
+  reset:  s => USE_COLOR ? `\x1b[0m${s}\x1b[0m`  : s,
+  bold:   s => USE_COLOR ? `\x1b[1m${s}\x1b[0m`   : s,
+  dim:    s => USE_COLOR ? `\x1b[2m${s}\x1b[0m`   : s,
+  green:  s => USE_COLOR ? `\x1b[32m${s}\x1b[0m`  : s,
+  yellow: s => USE_COLOR ? `\x1b[33m${s}\x1b[0m`  : s,
+  blue:   s => USE_COLOR ? `\x1b[34m${s}\x1b[0m`  : s,
+  cyan:   s => USE_COLOR ? `\x1b[36m${s}\x1b[0m`  : s,
+  white:  s => USE_COLOR ? `\x1b[97m${s}\x1b[0m`  : s,
+  red:    s => USE_COLOR ? `\x1b[31m${s}\x1b[0m`  : s,
+  purple: s => USE_COLOR ? `\x1b[35m${s}\x1b[0m`  : s,
+}
+
+// Strip ANSI codes to measure true visual width
+function visLen(s) {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\x1b\[[0-9;]*m/g, '').length
+}
+
+// Pad a string to a visual width (accounting for ANSI codes)
+function pad(s, width, align = 'left') {
+  const len  = visLen(s)
+  const fill = Math.max(0, width - len)
+  return align === 'right' ? ' '.repeat(fill) + s : s + ' '.repeat(fill)
+}
+
+// ─── Box ─────────────────────────────────────────────────────────────────────
+
+export function box(lines, opts = {}) {
+  const { title = '', style = 'single' } = opts
+  const chars = style === 'double'
+    ? { tl: '╔', tr: '╗', bl: '╚', br: '╝', h: '═', v: '║' }
+    : { tl: '┌', tr: '┐', bl: '└', br: '┘', h: '─', v: '│' }
+
+  const inner = Array.isArray(lines) ? lines : [lines]
+  const maxW  = Math.max(...inner.map(visLen), title ? visLen(title) + 2 : 0)
+  const bar   = chars.h.repeat(maxW + 2)
+
+  const top = title
+    ? `${chars.tl}${chars.h} ${c.bold(title)} ${chars.h.repeat(maxW - visLen(title) - 1)}${chars.tr}`
+    : `${chars.tl}${bar}${chars.tr}`
+
+  const rows = inner.map(l => `${chars.v} ${pad(l, maxW)} ${chars.v}`)
+  return [top, ...rows, `${chars.bl}${bar}${chars.br}`].join('\n')
+}
+
+// ─── Header (branded section label) ──────────────────────────────────────────
+
+export function header(text) {
+  const line = `${c.purple('⚡')} ${c.bold(c.white(text))}`
+  return `\n${line}\n${c.dim('─'.repeat(visLen('⚡ ' + text) - (USE_COLOR ? 0 : 0)))}`
+}
+
+// ─── Table ───────────────────────────────────────────────────────────────────
+
+/**
+ * Render an aligned table.
+ * @param {string[]}   cols    - Column headers
+ * @param {string[][]} rows    - Data rows (array of arrays)
+ * @param {{align?: ('left'|'right')[]}} opts
+ */
+export function table(cols, rows, opts = {}) {
+  const aligns  = opts.align || cols.map(() => 'left')
+  const allRows = [cols, ...rows]
+  const widths  = cols.map((_, i) => Math.max(...allRows.map(r => visLen(r[i] ?? ''))))
+
+  const sep = '  '
+
+  const headerRow = cols.map((h, i) => pad(c.dim(h), widths[i], aligns[i])).join(sep)
+  const divider   = c.dim('─'.repeat(widths.reduce((s, w, i) => s + w + (i < widths.length - 1 ? sep.length : 0), 0)))
+  const body      = rows.map(row =>
+    row.map((cell, i) => pad(cell ?? '', widths[i], aligns[i])).join(sep)
+  )
+
+  return [headerRow, divider, ...body].join('\n')
+}
+
+// ─── Status line helpers ──────────────────────────────────────────────────────
+
+export const icon = {
+  ok:   () => c.green('✓'),
+  fail: () => c.red('✗'),
+  warn: () => c.yellow('⚠'),
+  info: () => c.cyan('·'),
+  run:  () => c.yellow('›'),
+  bolt: () => c.purple('⚡'),
+}
+
+export function ok(msg)   { return `  ${icon.ok()}  ${msg}` }
+export function fail(msg) { return `  ${icon.fail()}  ${c.red(msg)}` }
+export function warn(msg) { return `  ${icon.warn()}  ${c.yellow(msg)}` }
+export function info(msg) { return `  ${icon.info()}  ${c.dim(msg)}` }
+
+// ─── Timing ───────────────────────────────────────────────────────────────────
+
+export function elapsed(ms) {
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  return `${(ms / 1000).toFixed(1)}s`
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+export { c, pad, visLen }