@invisibleloop/pulse 0.12.3 → 0.14.2

package/src/agent/guide-templates.md

@@ -2,6 +2,8 @@
 
 Templates are complete, production-ready page specs you can adapt for a new brand. Always start from a template when the user's request matches one — do not build from scratch.
 
+**A template gives you the right *components and content slots* — not a mandatory section order.** The structural skeleton (hero → features → testimonials → CTA) suits corporate and minimal vibes. For playful, bold, brutalist, retro, and neon vibes, the template is a parts list, not a blueprint. Run `pulse_sketch` to find a layout that matches the emotional intent before you write a line of code.
+
 ---
 
 ## When to use a template
@@ -10,22 +12,96 @@ Read the user's request and match against the triggers below. If it matches, use
 
 | Template | Route | Triggers |
 |---|---|---|
-| Mobile App Landing | `docs/src/pages/templates/mobile-app.js` | "landing page for a mobile app", "app marketing site", "app homepage", "SaaS landing page" |
-| Blog Post          | `docs/src/pages/templates/blog-post.js`  | "blog post", "article page", "publication", "editorial site", "newsletter with blog" |
+| Mobile App Landing  | `docs/src/pages/templates/mobile-app.js`       | "landing page for a mobile app", "app marketing site", "app homepage", "SaaS landing page" |
+| Blog Post           | `docs/src/pages/templates/blog-post.js`        | "blog post", "article page", "publication", "editorial site", "newsletter with blog" |
+| Local Business      | `docs/src/pages/templates/local-business.js`   | "local business", "dog groomer", "bakery", "physio", "plumber", "florist", "salon", "restaurant", "tradesperson", "small business" |
+| Portfolio           | `docs/src/pages/templates/portfolio.js`        | "portfolio", "personal site", "freelancer site", "creative professional", "photographer", "designer site", "developer portfolio" |
+| Event / Conference  | `docs/src/pages/templates/event.js`            | "conference", "event", "festival", "workshop", "concert", "meetup", "summit" |
+| Editorial / Magazine | `docs/src/pages/templates/editorial.js`       | "magazine", "publication", "news site", "editorial", "online journal", "newsletter homepage" |
+
+**Always fetch `pulse://guide/design-references` after matching a template** — it tells you which vibe and component combinations suit the product's aesthetic, so you don't default to the same SaaS geometry every time.
 
 ---
 
-## Before writing any code — mandatory pre-build questions
+## Creative-override rule — when to ignore the template structure
+
+When the vibe is **playful, bold, brutalist, retro, or neon**, run `pulse_sketch` before writing any code and **treat the template section order as optional**. These vibes require structural decisions that the template's default skeleton actively works against.
+
+| Signal | What to do |
+|---|---|
+| Vibe is playful / bold / brutalist / retro / neon | Run `pulse_sketch` — pick one of 3 layout directions |
+| User says "fun", "pop-art", "loud", "unexpected", "editorial", "raw" | Run `pulse_sketch` — section order is your call |
+| User says "professional", "clean", "trustworthy", "corporate", "minimal" | Template structure is fine — adapt content only |
+
+**What this means in practice for expressive vibes:**
+
+- The template tells you *what to include* (a hero, features, social proof, CTA). It does **not** tell you how to arrange them or what shape they take.
+- Full-colour section blocks, oversized typography heroes, marquee strips, dense grids, and palette-as-structure are all fair game.
+- The `phoneFrame` in Mobile App Landing is **not mandatory** — a full-bleed game board, an oversized illustration, or a typography-only hero may serve the brief better.
+- `feature()` in a 3-column grid is the most predictable layout on the web. If the brief is "fun and bold", use a marquee strip of features, a zigzag alternating layout, or full-bleed feature sections instead.
+
+---
+
+## Template-mode: lighter planning
+
+When using a template, skip the full plan-and-confirm ceremony. Instead, output a single compact confirmation before writing:
+
+```
+Template:      Mobile App Landing
+App name:      Nova
+Substitutions: name, tagline, 5 features, 3 pricing tiers, palette, font
+Theme:         light  (palette: #6366f1 primary, #f8fafc bg)
+Files:         src/pages/nova.js, public/themes/nova.css
+Confirm to proceed — or reply with changes.
+```
+
+Wait one turn for confirmation. This replaces the full plan/build/confirm cycle. It is enough — the user can see exactly what will change.
 
-Ask these **before** presenting a plan. Do not skip them.
+**Do not skip the confirmation.** Even for templates, one turn of "does this look right?" prevents throwing away a completed build because the app name or palette was wrong.
 
-1. **Colour palette** — "Do you have a colour palette, or should I choose one?"
-2. **Brand fonts** — "Any brand fonts, or system-ui is fine?"
-3. **Theme** — "Light or dark theme preference?"
+### One-shot builds without a template
 
-Record the answers. If the user provides palette colours, note which are light/mid/dark toned so you can plan contrast strategy before writing any CSS.
+For a one-shot "build me X" request that doesn't use a named template, use the same compact style — a 3–5 line brief, not a full phase-2 plan:
 
-**Why this matters:** Building with placeholder colours and retrofitting a palette requires rebuilding components, fixing WCAG contrast failures, and touching multiple files. Getting the palette upfront avoids that loop entirely.
+```
+Building: Chess Club landing page (/chess-club)
+Vibe:     editorial · dark navy + gold · brutalist structure
+Sections: hero, about, schedule, join CTA
+Files:    src/pages/chess-club.js, public/themes/chess-club.css
+Confirm to proceed — or reply with changes.
+```
+
+Reserve the full plan-and-confirm ceremony (route / state / mutations / actions / server fetchers) for multi-page builds, pages with complex state, or when the user hasn't confirmed the scope yet.
+
+---
+
+## Before writing any code — mandatory product intake
+
+Run `pulse_intake` before presenting the confirmation. It collects the product details that make template content directionally right instead of fiction.
+
+**How to gather the intake information** — ask questions one at a time as plain prose, never as a batch with multiple-choice options. Product details are open-ended and free-form; preset choice lists don't fit and cause tool errors. Ask the simplest possible version of each question:
+
+1. "What's the name of the app or product?"
+2. "One sentence — what does it do?"
+3. "What are its main features? Give me 3–6."
+4. "Who's it for?" *(optional — skip if obvious from context)*
+5. "Do you have brand colours? If so, paste the hex values."
+6. "Any specific font, or system-ui?"
+7. "Light or dark theme preference?"
+8. "How should it feel visually? (e.g. warm and friendly, editorial and sharp, playful, minimal, bold — or describe in your own words)"
+9. "Do you have any design inspiration — a site you love, a screenshot, a mood board image? Drop images into `public/intake/` or paste a URL and I'll extract the design intent before we start."
+
+Ask each question and wait for the answer before asking the next. Do not present a list of preset choices for any of these — the answers are arbitrary text.
+
+**Question 9 is not optional.** Always ask it. If the user provides an image in `public/intake/`, call `pulse_extract_inspiration` on it before calling `pulse_intake`. If they provide a URL, call `pulse_extract_inspiration` with the URL. If they say no or skip it, proceed without — but always ask.
+
+Once you have the answers, call `pulse_intake` with the collected details. It returns a product brief + early contrast warnings.
+
+**If `pulse_intake` is unavailable**, gather the answers via the questions above and use them directly when adapting the template — replace every placeholder with real content.
+
+**Do not invent app content.** Placeholder copy ("Lorem ipsum", "Feature A", "Benefit here") is thrown away immediately and makes the build feel broken. Real answers mean the first build is shippable copy.
+
+Record the intake answers. If the user provides palette hex values, note which are light/mid/dark toned before writing any CSS — this is when to spot contrast problems, not after Lighthouse runs.
 
 ---
 
@@ -237,7 +313,144 @@ Do NOT set `meta.theme: 'light'` on dark templates — the default pulse-ui them
 
 ---
 
-## Adding a new template
+## Local Business Landing Page
+
+**Design direction:** Warm Local Business · **Vibe:** `warm` · **Theme:** `light`
+
+### What it includes
+
+| Section | Component(s) |
+|---|---|
+| Sticky nav | `nav` with logo, links, Book Now CTA |
+| Hero | `hero(layout:'split')` with real photo of the business |
+| Stats strip | `stat` × 4 in `grid` — clients, rating, years, availability |
+| Services | `card` × 6 in `grid` with name, description, and price |
+| About | Two-column: photo + team bio with trust badges |
+| Reviews | `testimonial` × 3 in `grid` |
+| Contact / Hours | Two-column: address/phone/hours + booking form |
+| CTA banner | `cta` with offer (e.g. 10% off first visit) |
+| Footer | `footer` with address in `legal` |
+
+### Files to create
+
+| File | Purpose |
+|---|---|
+| `src/pages/[name].js` | The page spec |
+| `public/themes/[name].css` | Brand theme — warm palette, `[data-theme="light"]` |
+
+### Adapting the template
+
+1. **Business name** — replace "Pawfect Grooming" everywhere.
+2. **Service type** — update service names, descriptions, and prices to match the business.
+3. **Photo** — the hero image and about section both use real photos; provide Unsplash URLs or placeholder paths. **If using external images**, add the host to `csp` in `pulse.config.js` (see pulse://guide/styles for examples).
+4. **Palette** — earthy, warm tones work best. Terracotta, sage, cream, amber — avoid corporate blues.
+5. **Contact details** — update address, phone, and opening hours in the contact section.
+6. **Vibe** — always `warm` for local business; pairs with rounded cards and soft section dividers.
+
+---
+
+## Portfolio / Personal Site
+
+**Design direction:** Minimal Portfolio · **Vibe:** `minimal` · **Theme:** dark (default)
+
+### What it includes
+
+| Section | Component(s) |
+|---|---|
+| Nav | Minimal nav — name as logo, text links, no CTA |
+| Hero | `hero(layout:'centered', align:'left')` — title and short bio |
+| Work grid | `card` × 6 with image, project name, description, skill badges |
+| About | Single-column `container(size:'sm')` with `prose`-style paragraphs + skill badges |
+| Contact | Centered section with email link, GitHub link, CV download |
+| Footer | Minimal — name, 3 links, legal |
+
+### Files to create
+
+| File | Purpose |
+|---|---|
+| `src/pages/[name].js` | The page spec |
+
+Portfolio templates rarely need a separate theme CSS — the default dark palette with a single accent colour is sufficient. If the user has a brand colour, add it as a one-liner: `--ui-accent: #hex;` in `:root`.
+
+### Adapting the template
+
+1. **Name** — replace "Alex Mercer" everywhere, including the nav logo.
+2. **Profession** — update the eyebrow and hero subtitle.
+3. **Work grid** — replace with real project images, names, and descriptions. Use Unsplash or actual project screenshots. **If using external images**, add the host to `csp` in `pulse.config.js` (see pulse://guide/styles).
+4. **Skills badges** — update to match the person's actual disciplines.
+5. **Contact** — replace email, GitHub handle, and CV download link.
+6. **Vibe** — `minimal` keeps the focus on the work; do not add excess decoration.
+
+---
+
+## Event / Conference Landing Page
+
+**Design direction:** Event / Conference · **Vibe:** `bold` · **Theme:** dark (default)
+
+### What it includes
+
+| Section | Component(s) |
+|---|---|
+| Nav | `nav` with event logo, links, Get Tickets CTA |
+| Hero | `hero(size:'xl', align:'center')` with gradient background |
+| Stats strip | `stat` × 4 — days, speakers, attendees, tracks |
+| Sponsor logos | `marquee` with sponsor names/logos |
+| Speakers | `card` × 8 in `grid` with photo, name, role, topic |
+| Schedule | `accordion` — one item per day with time/session/location |
+| Venue | Two-column: venue info + photo |
+| Tickets CTA | `cta` with prominent ticket button |
+| Footer | `footer` with event links and company legal |
+
+### Files to create
+
+| File | Purpose |
+|---|---|
+| `src/pages/[name].js` | The page spec |
+| `public/themes/[name].css` | Optional — if brand has a specific accent colour |
+
+### Adapting the template
+
+1. **Event name and dates** — replace "SIGNAL", "14–16 October 2026", and "London" everywhere.
+2. **Speakers** — replace with real speaker names, roles, photos, and talk topics.
+3. **Schedule** — update accordion items with real session titles and times.
+4. **Venue** — update name, address, capacity, and photo.
+5. **Ticket price and URL** — update the ticket CTA with real link and price.
+6. **Gradient hero** — adjust the gradient colours to match the event brand.
+7. **Vibe** — `bold` for impact; consider `neon` for gaming/tech events.
+
+---
+
+## Editorial / Magazine Landing Page
+
+**Design direction:** Editorial / Publication · **Vibe:** `editorial` · **Theme:** dark (default)
+
+### What it includes
+
+| Section | Component(s) |
+|---|---|
+| Nav | `nav` with publication name + category links + Subscribe CTA |
+| Hero | `hero` with featured article title, deck, and author byline |
+| Pullquote | `pullquote` from the featured article |
+| Article grid | `card` × 6 with image, category badge, title, deck, author, date, read time |
+| Newsletter signup | `section(variant:'spotlight')` with email input and subscribe button |
+| Footer | `footer` with publication logo, category links, legal |
+
+### Files to create
+
+| File | Purpose |
+|---|---|
+| `src/pages/[name].js` | The page spec |
+
+### Adapting the template
+
+1. **Publication name** — replace "The Signal" everywhere.
+2. **Navigation categories** — update section names to match the publication's editorial categories.
+3. **Featured article** — replace hero title and subtitle with the actual lead story.
+4. **Article grid** — replace all 6 article stubs with real or representative articles.
+5. **Newsletter copy** — update the newsletter description and subscriber count.
+6. **Vibe** — `editorial` applies serif display font and zero-radius geometry; critical for the right feel. Do not change it.
+
+---
 
 When you build a new template and want it available for future scaffolding:
 

package/src/agent/guide.md

@@ -497,13 +497,18 @@ Convention: name dynamic-route files [param].js inside a subfolder:
 
 This is purely a human readability convention. Pulse does not process [ ] in filenames.
 
-## UI components — MANDATORY
+## UI components
 
-**RULE: Before writing any HTML, check whether a Pulse UI component exists for the purpose. If it does, you MUST use it. Raw HTML is only permitted for structural tags with no component equivalent (div, main, aside, footer, header).**
+**Default rule: Before writing any HTML, check whether a Pulse UI component exists for the purpose. If it does, use it.** Components ship with correct ARIA, token-based styling, and responsive behaviour — choosing them over raw HTML means less work, not more.
 
-**RULE: For every feature, page, or UI element you build — regardless of how the request is phrased, whether it came from text or an image — your first step is always to check whether a Pulse UI component exists for it. If it does, you MUST use it. There are no exceptions.**
+**Creative override:** When the design intent genuinely calls for a more expressive or unconventional layout — a distinctive visual identity, an asymmetric or typographically-driven composition, a brutalist or editorial structure that components would constrain — you may build with raw HTML instead. This is not a loophole; it is a deliberate design decision. When taking this path:
 
-Before writing a single line of HTML, mentally scan the task and list which components apply. Only after exhausting the component list should you write raw HTML — and only for structural wrappers (div, main, aside, footer) with no component equivalent.
+1. **State your intent explicitly** in the build brief: *"Building component-free — raw HTML throughout for maximum creative control."*
+2. **Pulse-ui.css is still required** — always load it in `meta.styles`. It provides the token system (`--ui-*` variables) that your custom CSS will reference.
+3. **Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components** unless there is a specific design reason to hand-roll them. These are the hardest to get right for accessibility.
+4. **The quality gate replaces the component checklist** — 100/100/100/100 Lighthouse (Accessibility, Best Practices, SEO, Agentic Browsing) on both desktop and mobile is the arbiter. A component-free page that passes every Lighthouse audit is correct. A component-heavy page that fails accessibility is not.
+
+Before writing a single line of HTML, decide which mode you are in and state it in the build brief:
 
 **RULE: All components accept a `class` prop — never `className` (that is React). Use `class` to add utility classes or custom identifiers to any component.**
 

package/src/agent/identity.md

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

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

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