fix: scaffold and pipeline follow-through from the screenshot run

.claude/CUSTOM-AGENTS-GUIDE.md

@@ -120,7 +120,7 @@ Agents are auto-selected by Claude Code based on task context, or you can reques
 
 ## How Agents Work
 
-Agents are invoked through Claude Code's Agent tool. They are automatically selected based on task context:
+Agents are invoked through Claude Code's Agent tool. Claude Code delegates when a request matches an agent's description, and may handle a small task itself instead; name the agent to make the delegation certain:
 
 ```
 User: "Help me optimize this component's rendering"
@@ -129,11 +129,11 @@ Claude: [Uses performance-benchmarker agent]
 User: "Convert this Figma design to React"
 Claude: [Uses figma-react-converter agent]
 
-User: "Write tests for the auth hook"
+User: "Use the test-writer-fixer agent to write tests for the auth hook"
 Claude: [Uses test-writer-fixer agent]
 ```
 
-You can also request a specific agent:
+Naming the agent, as in the last example, is the sure way to get it:
 ```
 User: "Use the accessibility-auditor agent to check this page"
 ```

.claude/agents/test-writer-fixer.md

@@ -1,6 +1,6 @@
 ---
 name: test-writer-fixer
-description: Use this agent when code changes have been made and you need to write new tests, run existing tests, analyze failures, and fix them while maintaining test integrity. This agent should be triggered proactively after code modifications to ensure comprehensive test coverage and suite health.
+description: Use this agent for any request to write, add, extend, fix or run tests, including a plain "write tests for the Checklist component", and proactively after code changes to run the affected tests, analyze failures and repair them while keeping the tests honest. Covers unit, integration and E2E tests for components, hooks, modules, pages and flows. MUST BE USED instead of writing tests in the main session.
 color: cyan
 memory: local
 skills:

.claude/skills/README.md

@@ -150,7 +150,7 @@ These skills provide patterns and best practices. They trigger on relevant keywo
 
 #### 24. storybook-story-generation (Phase 4.5)
 
-- **Purpose:** Auto-generates Storybook 8 (CSF3) `.stories.tsx` and `.mdx` docs from built React components using a `ts-morph` AST. Emits prop-aware `argTypes`/controls, a `Default` story seeded with destructured defaults, one variant story per string-literal-union value, `True`/`False` stories for booleans, and action args for `on*` callbacks. Wraps `scripts/generate-stories.sh`. Non-blocking.
+- **Purpose:** Auto-generates Storybook 10 (CSF3) `.stories.tsx` and `.mdx` docs from built React components using a `ts-morph` AST. Emits prop-aware `argTypes`/controls, a `Default` story seeded with destructured defaults, one variant story per string-literal-union value, `True`/`False` stories for booleans, and action args for `on*` callbacks. Wraps `scripts/generate-stories.sh`. Non-blocking.
 - **Triggers:** Phase 4.5 of `/build-from-figma`, `/build-from-canva`, and `/build-from-screenshot` (after component build), "generate Storybook stories", "auto-generate stories", "add MDX docs"
 - **Output:** `src/components/**/*.stories.tsx` and `src/components/**/*.mdx`
 

.claude/skills/build-from-figma/SKILL.md

@@ -173,7 +173,7 @@ Building components and fixing visual differences are per-item work, so they run
      "skipVisual": false
    }
    ```
-   `tier` follows the component's `category` in the build spec: `ui` 0, `layout` 1, `sections` 2, `pages` 3. `maxVisualIterations` and `diffPassThreshold` come from `pipeline.config.json → iterationLoop`. Set `skipVisual` when the manifest excludes `visual-diff`.
+   `tier` follows the component's `category` in the build spec: `ui` 0, `layout` 1, `sections` 2, `pages` 3. `maxVisualIterations` and `diffPassThreshold` come from `pipeline.config.json → iterationLoop`. Set `skipVisual` when the manifest excludes `visual-diff`. A reference may also be an object, `{ "path", "renderWidth", "crop": { "x", "y", "width", "height" } }`, for a source screenshot taken at a non-standard width or covering only part of the page: the visual check then captures at `renderWidth` and passes `--crop` to `visual-diff.js` (the screenshot pipeline fills it from the build spec's `reference`).
 3. **What it does:** each tier's components build in parallel lanes (the converter writes only inside its own directory; shared files such as barrels are applied once per tier), and a separate check reruns each component's tests and compares its test file's checksum. Then up to `maxVisualIterations` rounds: every page is diffed in parallel, the pass decision is made from the numbers, fixes are grouped so each component has one fixer per round, and every round re-checks every page.
 4. **Record the result** in `pipeline-state.json`: phases 4 and 5, each component's status, each page's status and worst mismatch. A `TEST_TAMPERED` component changed its test file: restore that file from the Phase 3 output (`git checkout -- <test>` when it is committed) and mark the component `needs-review`. Leave the dev server running for the phases below.
 
@@ -247,7 +247,7 @@ This phase:
 3. Runs `pnpm build-storybook --quiet` as a smoke test (if Storybook is installed)
 4. Skips components that already have story files
 
-Non-blocking: if Storybook is not installed or generation fails, log a warning and continue.
+Non-blocking. When the app's `package.json` lists no Storybook package, `generate-stories.sh` exits 0 with `status: skipped` and the install command, because stories without Storybook would break `tsc` and the build; record the phase as `skipped`. Any other failure logs a warning and the pipeline continues.
 
 ## Phase 5: Visual Verification (Automated Pixel Diff)
 

.claude/skills/build-from-screenshot/SKILL.md

@@ -106,7 +106,7 @@ Identical to `/build-from-figma` Phase 3.
 
 After Phase 3 confirms RED, resolve the renderer manifest (`node scripts/renderer-registry.js resolve <renderer> --json`) and run Phases 4-9 exactly as `/build-from-figma` describes (`.claude/skills/build-from-figma/SKILL.md` → Phases 4-9): the `component-lanes` workflow for Phases 4-5 when the Workflow tool is available, then `parallel-orchestration` for Phases 4.5-9. The screenshot differences:
 
-- **Workflow args:** `"source": "screenshot"`; `converter` is `manifest.converter` (`figma-react-converter`, the generic React builder, for React renderers; `react-native-converter` for expo); `testCommand` is `manifest.commands.test`. The page `references` are the source captures in `.claude/visual-qa/screenshots/source/`, keyed by the width they were captured at. Set `skipVisual` when the manifest excludes `visual-diff` (expo).
+- **Workflow args:** `"source": "screenshot"`; `converter` is `manifest.converter` (`figma-react-converter`, the generic React builder, for React renderers; `react-native-converter` for expo); `testCommand` is `manifest.commands.test`. The page `references` are the source captures in `.claude/visual-qa/screenshots/source/`, keyed by the width they were captured at. A page whose build-spec entry carries `reference` (a `renderWidth` and/or a `crop`, screenshot-intake Step 5) passes it through as an object, `"1280": { "path": "…", "renderWidth": 1265, "crop": { "x": 0, "y": 180, "width": 1265, "height": 2400 } }`, so the visual stage captures at that width and diffs only that region of the capture (issue #145). Set `skipVisual` when the manifest excludes `visual-diff` (expo).
 - **parallel-orchestration:** drop every phase in `manifest.phases.exclude` (expo excludes `visual-diff`, `dark-mode`, `cross-browser` and `responsive`), and also `cross-browser` for `appType: "chrome-extension"`. Context: pipeline source `"screenshot"`, test files `src/components/**/*.test.*`, reference screenshots `.claude/visual-qa/screenshots/source/`. `e2e-tests` follows `component-build` when `visual-diff` is excluded.
 
 Without the Workflow tool, invoke `parallel-orchestration` with all of `["component-build", "storybook", "visual-diff", "dark-mode", "e2e-tests", "cross-browser", "quality-gate", "responsive", "report"]` minus those exclusions. If `orchestration.enabled` is `false`, run the phases sequentially as documented below.
@@ -135,12 +135,13 @@ This phase:
 4. Uses source screenshots for layout/structure decisions
 5. Generates components (at `manifest.component.dir` with `manifest.component.ext`) that satisfy the test files from Phase 3
 6. Runs `manifest.commands.test` after each component batch to confirm GREEN
+7. Sets each page's `<title>` and `<meta name="description">` from `pages[].seo` in the build spec (`index.html` for Vite, the route's metadata for Next.js) and keeps `public/robots.txt`. The quality gate's SEO floor (`qualityGate.lighthouseThresholds.seo`, 90) applies to a screenshot build too; these come from the intake, not from the design, and the build report lists them as additions
 
 **Critical rule:** If tests fail, fix the component — never modify the test files.
 
 ## Phase 4.5: Storybook Generation (Non-Blocking)
 
-Identical to `/build-from-figma` Phase 4.5. Skipped when the renderer has no browser story (e.g. expo).
+Identical to `/build-from-figma` Phase 4.5. Skipped when the renderer has no browser story (e.g. expo), and skipped by design when the app's `package.json` lists no Storybook package: `generate-stories.sh` then exits 0 with `status: skipped` and the install command, and the phase is recorded as `skipped` in `pipeline-state.json`. Stories without Storybook installed would break `tsc` and the build. When the app is scaffolded beside the framework, run it from the app directory (`cd my-app && ../scripts/generate-stories.sh`).
 
 ```bash
 ./scripts/generate-stories.sh

.claude/skills/e2e-test-generator/SKILL.md

@@ -44,9 +44,12 @@ Generate comprehensive Playwright E2E tests based on the build specification. Re
 Copy the shared Playwright config template and customize:
 
 1. Copy `templates/shared/playwright.config.ts` → project root `playwright.config.ts`
-2. Adjust `baseURL` and `webServer.command` based on framework:
-   - **Next.js:** `baseURL: "http://localhost:3000"`, `command: "pnpm dev"`
-   - **Vite:** `baseURL: "http://localhost:5173"`, `command: "pnpm dev"`
+2. The config reads the dev server port from `E2E_PORT` and falls back to the port
+   `setup-project.sh` set for the framework (Vite and SvelteKit 5173, Astro 4321,
+   Next.js 3000); `baseURL` and `webServer.url` both derive from it, and
+   `webServer.command` is `pnpm dev`, which a scaffolded app resolves itself since it
+   is its own pnpm root. For an app not scaffolded by `setup-project.sh`, set the
+   fallback (`|| 3000`) to its port before the first run.
 3. The template includes 5 browser projects by default:
    - Desktop: `chromium`, `firefox`, `webkit`
    - Mobile: `mobile-chrome` (Pixel 5), `mobile-safari` (iPhone 13)

.claude/skills/parallel-orchestration/SKILL.md

@@ -138,16 +138,18 @@ function hasResourceConflict(candidatePhase, runningPhases):
 
 ### Step 5: Phase Dispatch Table
 
+When the app is scaffolded beside the framework (`./scripts/setup-project.sh my-app`), run each **Bash** dispatch from the app directory, `cd my-app && ../scripts/<name>.sh …`: `generate-stories.sh` reads that directory's `src/components` and `package.json`, and `check-responsive.sh` installs Playwright there. The artifacts still land under the Aurelius checkout's `.claude/`.
+
 | Phase | Dispatch Method |
 |-------|----------------|
 | `component-build` | **Agent:** dispatch the converter named by the resolved renderer manifest. For React renderers the calling command supplies the source-appropriate converter (figma/screenshot → figma-react-converter via the figma-to-react-workflow skill, canva → canva-react-converter); otherwise dispatch `manifest.converter` (e.g. react-native-converter for expo, future vue-converter / svelte-converter) |
-| `storybook` | **Bash:** `./scripts/generate-stories.sh` |
+| `storybook` | **Bash:** `./scripts/generate-stories.sh` (exits 0 with `status: skipped` when the app's `package.json` lists no Storybook package; record the phase as skipped) |
 | `visual-diff` | **Agent:** invoke visual-qa-verification skill with pixel-diff loop (max iterations from `iterationLoop.maxVisualIterations`) |
 | `dark-mode` | **Bash:** `./scripts/check-dark-mode.sh http://localhost:3000` |
 | `e2e-tests` | **Agent:** invoke e2e-test-generator skill with flows from build-spec.json |
 | `cross-browser` | **Bash:** `./scripts/cross-browser-baseline.sh compare http://localhost:3000 --json` (diffs firefox/webkit against committed baselines with provenance checks — RFC 0002; skips with a capture hint when no baselines exist) |
 | `quality-gate` | **Parallel sub-dispatch:** run all `qualityGateSubtasks` concurrently (see below) |
-| `responsive` | **Bash:** `./scripts/check-responsive.sh http://localhost:3000` |
+| `responsive` | **Bash:** `./scripts/check-responsive.sh http://localhost:3000` (installs Playwright in the directory it runs from when that holds a `package.json`) |
 | `report` | **Agent:** generate `build-report.md` in `.claude/visual-qa/` from all collected phase results, timings, and diff images |
 
 ### Step 6: Quality Gate Sub-Parallelization

.claude/skills/screenshot-intake/SKILL.md

@@ -117,6 +117,12 @@ If both MCPs fail or are unavailable:
    Preserve original filenames where unambiguous; otherwise rename:
    page-1-desktop.png, page-2-desktop.png, ...
 3. Record original paths and dimensions in build-spec.json
+4. When a file's width is none of the configured viewports, or the file does
+   not start at the top of the page, add a `reference` to its page (Step 5):
+   `renderWidth` is the file's pixel width (a 1280 px window with a 15 px
+   scrollbar gives 1265), `crop` the region of the full-page render the file
+   covers. Ask whether a file is a partial capture when the vision pass sees
+   no page header; `crop.y` may be left for visual round 1 to measure.
 ```
 
 ### Step 1.1: Multi-Page Handling
@@ -222,7 +228,7 @@ Store extracted data in working memory for Step 4 (questions) and Step 5 (build-
    Read .claude/pipeline.config.json (screenshot, appTypes sections).
 ```
 
-### Step 4: Ask Targeted Questions (Max 6)
+### Step 4: Ask Targeted Questions (Max 7)
 
 Only ask what cannot be derived from captures or local scan. Use `AskUserQuestion` tool with multiple questions in one prompt where possible.
 
@@ -259,6 +265,12 @@ Only ask what cannot be derived from captures or local scan. Use `AskUserQuestio
 > a) Standalone app (new project scaffold)
 > b) Integrate into the existing project at [detected path]
 
+**Q7 — Page title and description (always, with defaults):**
+> A `<title>` and a one-line meta description for each page, defaulting to the
+> main heading and the first paragraph the vision pass extracted. The quality
+> gate's Lighthouse SEO floor needs both, and a screenshot cannot supply them;
+> Phase 4 writes them into the page and the build report lists them as additions.
+
 ### Step 5: Generate build-spec.json
 
 Write `.claude/plans/build-spec.json`. The schema is consumed by `canva-token-inference` (Phase 2), `tdd-from-figma` (Phase 3), and the framework-specific converter agents (Phase 4).
@@ -301,6 +313,12 @@ Write `.claude/plans/build-spec.json`. The schema is consumed by `canva-token-in
       "name": "Home",
       "route": "/",
       "screenshotPath": ".claude/visual-qa/screenshots/source/page-1-desktop.png",
+      "seo": {                   // Q7: written into <title> and <meta name="description"> in Phase 4
+        "title": "Example: build faster with AI",
+        "description": "Ship production apps in days, not months."
+      },
+      // Only for a screenshot taken at a non-standard width or covering part of the page:
+      // "reference": { "renderWidth": 1265, "crop": { "x": 0, "y": 180, "width": 1265, "height": 2400 } },
       "sections": ["nav", "hero", "features", "pricing", "footer"]
     }
   ],

.claude/skills/storybook-story-generation/SKILL.md

@@ -9,7 +9,7 @@ allowed-tools: Bash(./scripts/generate-stories.sh *), Bash(pnpm build-storybook
 
 ## Purpose
 
-Auto-generate Storybook 8 (CSF3) stories and MDX documentation from built React
+Auto-generate Storybook 10 (CSF3) stories and MDX documentation from built React
 components. The generator parses each component's TypeScript source with a
 `ts-morph` AST — not regex — so it can reliably extract prop types, string-literal
 unions, default values, callback props, and JSDoc comments, then emit:
@@ -24,7 +24,13 @@ unions, default values, callback props, and JSDoc comments, then emit:
 
 The skill wraps `scripts/generate-stories.sh` (a thin wrapper over
 `scripts/generate-stories.js`). It is a **non-blocking** step: a failure never
-fails the build.
+fails the build. When the project's `package.json` lists no Storybook package,
+the script exits 0 with `status: skipped` (in `--json` mode) and prints the
+install command, because stories without Storybook installed would break `tsc`
+and the build; the pipelines record the phase as `skipped`. Generated stories
+import their types from the framework package named in `.storybook/main.ts`
+(`@storybook/react-vite` when none is found), as Storybook 9+ recommends, and
+the MDX pages take their blocks from `@storybook/addon-docs/blocks`.
 
 ## When to Use
 
@@ -103,7 +109,7 @@ Emit CSF3 with `title: 'Components/<path-relative-to-src>'`, `tags: ['autodocs']
 `includeResponsiveViewports` is enabled.
 
 ```tsx
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite'; // the framework named in .storybook/main.ts
 import { Badge } from './Badge';
 
 const meta: Meta<typeof Badge> = {
@@ -126,12 +132,12 @@ export const Success: Story = { args: { variant: 'success' } };
 
 ### Step 5: Generate `.mdx` (unless `--no-mdx` or `generateMdx: false`)
 
-Emit an autodocs page importing `@storybook/blocks`, referencing the sibling
+Emit an autodocs page importing `@storybook/addon-docs/blocks`, referencing the sibling
 `.stories`, and embedding the component's JSDoc description, the `Default`
 `Canvas`, `Controls`, a `Canvas` per variant, and the full `ArgTypes` table.
 
 ```mdx
-import { Meta, Canvas, Controls, ArgTypes } from '@storybook/blocks';
+import { Meta, Canvas, Controls, ArgTypes } from '@storybook/addon-docs/blocks';
 import * as Stories from './Badge.stories';
 
 <Meta of={Stories} />