qualia-framework 6.2.9 → 6.3.0

package/skills/qualia-optimize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-optimize
-description: "Deep optimization pass — reads .planning/ AND codebase to find performance, design, UI, backend, frontend, AND architecture-deepening opportunities. Spawns parallel specialist agents. Use whenever the user says 'optimize', 'optimization pass', 'find issues', 'qualia-optimize', 'deep optimize', 'performance audit', 'design alignment check', 'speed up', 'slow', 'bundle size', 'refactor architecture', 'shallow modules', 'simplify', or wants a comprehensive quality sweep. Supports --perf, --ui, --backend, --alignment, --deepen, --fix flags."
+description: "Deep improvement discovery pass — reads .planning/ AND codebase to find performance, design, UI, backend, frontend, alignment, and architecture-deepening opportunities. Spawns parallel specialist agents and writes OPTIMIZE.md/RFCs; practical repair work routes to /qualia-fix or /qualia-polish. Use when the user says 'optimize', 'optimization pass', 'find issues', 'deep improve', 'performance audit', 'design alignment check', 'speed up', 'bundle size', 'refactor architecture', 'shallow modules', 'simplify', or wants a comprehensive quality sweep. Supports --perf, --ui, --backend, --alignment, --deepen, --fix flags."
 allowed-tools:
   - Bash
   - Read
@@ -21,6 +21,8 @@ Detailed agent-prompt templates live in `REFERENCE.md` (in this same skill folde
 
 Reads `.planning/` docs AND codebase. Never analyze one without the other.
 
+Optimize is discovery-first, not a hotfix lane. If the user has one broken behavior, route to `/qualia-fix`. If the user has visual quality problems, route to `/qualia-polish`. Use optimize when the question is "where can this system get better?"
+
 ## Usage
 
 - `/qualia-optimize` — Full (all 7 dimensions + architecture deepening)
@@ -29,7 +31,7 @@ Reads `.planning/` docs AND codebase. Never analyze one without the other.
 - `/qualia-optimize --backend` — Backend only (RLS, auth, queries, edge fns)
 - `/qualia-optimize --alignment` — Planning-code alignment only
 - `/qualia-optimize --deepen` — Architecture deepening only (Ousterhout: shallow modules, deeper interfaces)
-- `/qualia-optimize --fix` — Auto-fix LOW/MEDIUM from existing OPTIMIZE.md
+- `/qualia-optimize --fix` — Compatibility mode: convert LOW/MEDIUM `.planning/reports/optimize/OPTIMIZE.md` findings into safe repairs, using `/qualia-fix` rules for any code mutation
 
 ## Process
 
@@ -37,7 +39,7 @@ Reads `.planning/` docs AND codebase. Never analyze one without the other.
 
 Mode from $ARGUMENTS. Default: `full`.
 Modes: `full`, `perf`, `ui`, `backend`, `alignment`, `deepen`, `fix`.
-`--fix` skips to Step 9 (requires `.planning/OPTIMIZE.md`).
+`--fix` skips to Step 9 (requires `.planning/reports/optimize/OPTIMIZE.md`, with fallback to legacy `.planning/OPTIMIZE.md`) and follows `/qualia-fix` mutation rules.
 
 ### Step 2: Load Planning Context (MANDATORY)
 
@@ -73,8 +75,8 @@ ls .planning/decisions/ 2>/dev/null && cat .planning/decisions/*.md 2>/dev/null
 
 Also read rules:
 ```bash
-cat ~/.claude/qualia-design/frontend.md 2>/dev/null
-cat ~/.claude/rules/security.md 2>/dev/null
+cat ${QUALIA_DESIGN}/frontend.md 2>/dev/null
+cat ${QUALIA_RULES}/security.md 2>/dev/null
 ```
 
 Store all; inline into agent prompts.
@@ -146,7 +148,7 @@ Collect all 3 proposals. Present to the user as a side-by-side table:
 | 2 | ... | ... | ... | ... |
 | 3 | ... | ... | ... | ... |
 
-User picks `1`, `2`, `3`, or `hybrid` (with notes on which elements from which proposals to combine). The synthesizer then writes a "Refactor RFC" to `.planning/REFACTOR-{slug}.md` and optionally opens a GH issue.
+User picks `1`, `2`, `3`, or `hybrid` (with notes on which elements from which proposals to combine). The synthesizer then writes a "Refactor RFC" to `.planning/reports/refactor/REFACTOR-{slug}.md` and optionally opens a GH issue.
 
 **Why parallel + radically different**: a single deepening proposal anchors on the first idea the LLM has. Three parallel proposals with diverse design constraints surface trade-offs the user can see at a glance — and the human's "taste" dominates the choice rather than the agent's first instinct. Empirically (Matt Pocock + Qualia internal testing) this produces dramatically better refactor RFCs than a single-pass proposal.
 
@@ -187,7 +189,11 @@ All agents done:
 
 ### Step 8: Write OPTIMIZE.md and Present Results
 
-Write to `.planning/OPTIMIZE.md`:
+Create the report directory and write to `.planning/reports/optimize/OPTIMIZE.md`:
+
+```bash
+mkdir -p .planning/reports/optimize
+```
 
 ```markdown
 ---
@@ -237,7 +243,7 @@ status: {clean|needs_attention|critical_issues}
 
 Commit:
 ```bash
-git add .planning/OPTIMIZE.md && git commit -m "docs: optimization report ({mode} mode, {critical} critical)"
+git add .planning/reports/optimize/OPTIMIZE.md && git commit -m "docs: optimization report ({mode} mode, {critical} critical)"
 ```
 
 **Present results:**
@@ -247,25 +253,26 @@ If CRITICAL findings exist:
 {critical} critical issues found. Options:
 
 1. Create a fix phase in ROADMAP.md for critical + high findings
-2. Auto-fix LOW/MEDIUM findings: /qualia-optimize --fix
-3. Review full report: cat .planning/OPTIMIZE.md
+2. Repair a specific blocker: /qualia-fix {finding}
+3. Convert LOW/MEDIUM findings into safe repairs: /qualia-optimize --fix
+4. Review full report: cat .planning/reports/optimize/OPTIMIZE.md
 ```
 
 If no CRITICAL:
 ```
 Optimization complete. {total} findings ({high} high, {medium} medium, {low} low).
-Report: .planning/OPTIMIZE.md
+Report: .planning/reports/optimize/OPTIMIZE.md
 
-Run /qualia-optimize --fix to auto-fix LOW/MEDIUM findings.
+Run /qualia-fix for a specific defect, or /qualia-optimize --fix only for safe LOW/MEDIUM cleanup from this report.
 ```
 
 ### Step 9: --fix Mode
 
-`--fix` mode:
+`--fix` mode is a compatibility cleanup lane, not a replacement for `/qualia-fix`.
 
-1. Read `.planning/OPTIMIZE.md`; missing: "Run /qualia-optimize first"
+1. Read `.planning/reports/optimize/OPTIMIZE.md` (fallback: `.planning/OPTIMIZE.md` for older projects); missing: "Run /qualia-optimize first"
 2. Filter to LOW + MEDIUM only
-3. Per finding with clear, safe fix:
+3. Per finding with clear, safe fix, apply `/qualia-fix` mutation rules:
    - Read target file
    - Apply fix
    - Verify (npx tsc --noEmit if TS)
@@ -273,7 +280,7 @@ Run /qualia-optimize --fix to auto-fix LOW/MEDIUM findings.
 5. Commit
 6. Report fixed vs remaining
 
-**Never auto-fix CRITICAL/HIGH.** Require human judgment.
+**Never auto-fix CRITICAL/HIGH.** Require human judgment. If a finding is an actual broken behavior, use `/qualia-fix {finding}` instead of burying it in optimize.
 
 ### Step 10: Gap Phase Creation (user picks option 1)
 

package/skills/qualia-plan/SKILL.md

@@ -37,9 +37,9 @@ Per `rules/codex-goal.md` — set the thread goal at plan start with scope `phas
 cat .planning/STATE.md 2>/dev/null
 cat .planning/ROADMAP.md 2>/dev/null
 cat .planning/PROJECT.md 2>/dev/null
-node ~/.claude/bin/knowledge.js
-node ~/.claude/bin/knowledge.js load patterns
-node ~/.claude/bin/knowledge.js load client
+node ${QUALIA_BIN}/knowledge.js
+node ${QUALIA_BIN}/knowledge.js load patterns
+node ${QUALIA_BIN}/knowledge.js load client
 ```
 
 No phase number → current phase from STATE.md.
@@ -67,13 +67,13 @@ Suggest: *"Run /qualia-discuss {N} first to lock decisions? Optional."*
 ### 3. Spawn Planner (Fresh Context)
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner plan {N} "{phase name from ROADMAP.md}"
-node ~/.claude/bin/qualia-ui.js spawn planner "Breaking phase into tasks..."
+node ${QUALIA_BIN}/qualia-ui.js banner plan {N} "{phase name from ROADMAP.md}"
+node ${QUALIA_BIN}/qualia-ui.js spawn planner "Breaking phase into tasks..."
 ```
 
 ```
 Agent(prompt="
-Role: @~/.claude/agents/planner.md
+Role: @${QUALIA_AGENTS}/planner.md
 
 <project_context>
 @.planning/PROJECT.md
@@ -116,7 +116,7 @@ Read generated plan. Spawn checker:
 
 ```
 Agent(prompt="
-Role: @~/.claude/agents/plan-checker.md
+Role: @${QUALIA_AGENTS}/plan-checker.md
 
 <plan_path>.planning/phase-{N}-plan.md</plan_path>
 <phase_goal>{goal from ROADMAP.md}</phase_goal>
@@ -138,7 +138,7 @@ Per revision:
 
 ```
 Agent(prompt="
-Role: @~/.claude/agents/planner.md
+Role: @${QUALIA_AGENTS}/planner.md
 
 <revision_mode>true</revision_mode>
 <current_plan>@.planning/phase-{N}-plan.md</current_plan>
@@ -155,7 +155,7 @@ After revision, re-spawn checker. Max 2 total cycles.
 **BLOCKED after 2 cycles:**
 
 ```bash
-node ~/.claude/bin/qualia-ui.js fail "Plan failed validation after 2 revisions"
+node ${QUALIA_BIN}/qualia-ui.js fail "Plan failed validation after 2 revisions"
 ```
 
 Show remaining issues. Options:
@@ -165,10 +165,19 @@ Show remaining issues. Options:
 
 ### 5. Present Final Plan
 
+Before presenting, write the machine-readable contract:
+
+```bash
+node ${QUALIA_BIN}/plan-contract.js validate .planning/phase-{N}-contract.json
+node ${QUALIA_BIN}/state.js validate-plan --phase {N} --require-contract
+```
+
+The planner must create `.planning/phase-{N}-contract.json` from the final plan. This JSON contract is the authority for build and verification; Markdown contracts are explanatory only. If validation fails, revise the plan/contract pair before asking for approval.
+
 Render story-file dashboard:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js plan-summary .planning/phase-{N}-plan.md
+node ${QUALIA_BIN}/qualia-ui.js plan-summary .planning/phase-{N}-plan.md
 ```
 
 End with plain text: *"Approve? (yes / adjust)"*
@@ -178,7 +187,8 @@ If "adjust" — get feedback, re-spawn planner with revision context, re-validat
 ### 6. Update State
 
 ```bash
-node ~/.claude/bin/state.js transition --to planned --phase {N}
+node ${QUALIA_BIN}/state.js validate-plan --phase {N} --require-contract
+node ${QUALIA_BIN}/state.js transition --to planned --phase {N}
 ```
 
 Error → show, stop. Do NOT edit STATE.md or tracking.json manually.
@@ -188,7 +198,7 @@ Error → show, stop. Do NOT edit STATE.md or tracking.json manually.
 **`--auto`:** invoke `/qualia-build {N} --auto` inline. User approved at `/qualia-new`; no per-phase gate.
 
 ```bash
-node ~/.claude/bin/qualia-ui.js info "Auto mode — chaining into /qualia-build {N}"
+node ${QUALIA_BIN}/qualia-ui.js info "Auto mode — chaining into /qualia-build {N}"
 ```
 
 Then invoke `qualia-build` inline with `--auto`.
@@ -196,7 +206,7 @@ Then invoke `qualia-build` inline with `--auto`.
 **Guided mode:** stop, show next step:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "PHASE {N} PLANNED" "/qualia-build {N}"
+node ${QUALIA_BIN}/qualia-ui.js end "PHASE {N} PLANNED" "/qualia-build {N}"
 ```
 
 ## Gap Closure Mode (`--gaps`)

package/skills/qualia-polish/REFERENCE.md

@@ -55,10 +55,10 @@ Agent({
   subagent_type: "qualia-visual-evaluator",
   description: "Score iteration {N} screenshots against rubric",
   prompt: `
-Role: @~/.claude/agents/visual-evaluator.md
+Role: @${QUALIA_AGENTS}/visual-evaluator.md
 
 <rubric>
-{INLINE qualia-design/design-rubric.md §"The 8 dimensions" through §"Aggregate score"}
+{INLINE qualia-design/design-rubric.md §"The 9 dimensions" through §"Aggregate score"}
 </rubric>
 
 <brief>
@@ -101,7 +101,7 @@ Agent({
   subagent_type: "qualia-builder",
   description: "Fix {dim} issue: {short description}",
   prompt: `
-Role: @~/.claude/agents/builder.md
+Role: @${QUALIA_AGENTS}/builder.md
 
 <phase_context>
 You are inside /qualia-polish --loop iteration {N}. The vision evaluator scored
@@ -133,7 +133,7 @@ the {dim} dimension at {score}. Your single task: fix that one dimension.
 2. Make the MINIMUM edit to fix this one dimension. Do not refactor. Do not change logic. Do not touch state management. Do not change copy unless this is a microcopy issue.
 3. Use design tokens from DESIGN.md. Do not invent new color values, font names, or spacing.
 4. After the edit, commit via the orchestrator (slop-detect-gated):
-     node ~/.claude/skills/qualia-polish/scripts/loop.mjs commit-fix --state {STATE} --file {file} --slug {dim}-{short-keyword}
+     node ${QUALIA_SKILLS}/qualia-polish/scripts/loop.mjs commit-fix --state {STATE} --file {file} --slug {dim}-{short-keyword}
    If slop-detect blocks (exit 2), READ the slop output and re-edit. If you cannot fix without violating slop-detect, return BLOCKED with the conflict.
 5. Return DONE with: file modified, lines changed, slop-detect: pass, commit: {sha}.
 </task>
@@ -153,10 +153,10 @@ the {dim} dimension at {score}. Your single task: fix that one dimension.
 ```json
 {
   "iteration": 1,
-  "scores": { "typography": 1, "color": 1, "spatial": 3, "layout": 1, "shadow": 3, "motion": 3, "microcopy": 1, "container": 1 },
-  "aggregate": 14,
+  "scores": { "typography": 1, "color": 1, "spatial": 3, "layout": 1, "shadow": 3, "motion": 3, "microcopy": 1, "container": 1, "graphics": 1 },
+  "aggregate": 15,
   "pass": false,
-  "failing_dims": ["typography", "color", "layout", "microcopy", "container"],
+  "failing_dims": ["typography", "color", "layout", "microcopy", "container", "graphics"],
   "top_issues": [
     { "dim": "color", "severity": "critical", "description": "blue→purple gradient on hero", "likely_file": "src/styles/globals.css", "fix": "replace linear-gradient with single accent var(--accent)" },
     { "dim": "typography", "severity": "critical", "description": "Inter as primary font-family", "likely_file": "src/styles/globals.css", "fix": "swap to Fraunces + JetBrains Mono per DESIGN.md §3" },
@@ -222,23 +222,23 @@ The pilot-results doc at `docs/playwright-loop-pilot-results.md` records the act
 ## Iteration log
 
 ### Iteration 1
-- Scores: typo=1 colo=1 spat=3 layo=1 shad=3 moti=3 micr=1 cont=1
-- Aggregate: 14/40 (avg 1.75)
-- Pass: NO (failing: typography, color, layout, microcopy, container)
+- Scores: typo=1 colo=1 spat=3 layo=1 shad=3 moti=3 micr=1 cont=1 grap=1
+- Aggregate: 15/45 (avg 1.67)
+- Pass: NO (failing: typography, color, layout, microcopy, container, graphics)
 - Top issues:
   - **color** [critical] blue→purple gradient on hero → src/styles/globals.css
   - **typography** [critical] Inter as primary → src/styles/globals.css
   - **layout** [high] three identical cards → src/pages/index.tsx
 
 ### Iteration 2
-- Scores: typo=3 colo=3 spat=3 layo=2 shad=3 moti=3 micr=2 cont=2
-- Aggregate: 21/40 (avg 2.62)
+- Scores: typo=3 colo=3 spat=3 layo=2 shad=3 moti=3 micr=2 cont=2 grap=2
+- Aggregate: 23/45 (avg 2.56)
 - Pass: NO (failing: layout, microcopy, container)
 - ...
 
 ### Iteration 3
-- Scores: typo=4 colo=3 spat=3 layo=3 shad=3 moti=3 micr=3 cont=3
-- Aggregate: 25/40 (avg 3.13)
+- Scores: typo=4 colo=3 spat=3 layo=3 shad=3 moti=3 micr=3 cont=3 grap=4
+- Aggregate: 29/45 (avg 3.22)
 - Pass: YES
 
 ## Fix commits (revertable)
@@ -262,6 +262,6 @@ This is intentional. Most visual regressions Fawzi has documented in `/insights`
 - Accessibility audits beyond what the rubric scores — use `/qualia-polish` Stage 3 (Lighthouse + axe) for that.
 - Performance regressions — use `/qualia-polish --loop` only after Lighthouse score passes.
 - Reference-image-only mode (compare to a target screenshot without a brief) — the brief is required; reference is supplemental.
-- Aesthetic pivots — if the issue is "the whole vibe is wrong", `/qualia-vibe` swaps the aesthetic in minutes instead of grinding the loop against a vibe that doesn't fit.
+- Aesthetic pivots — if the issue is "the whole vibe is wrong", `/qualia-polish --vibe` swaps the aesthetic in minutes instead of grinding the loop against a vibe that doesn't fit.
 
 Implemented as of v5.2: `--routes a,b,c` for multi-route sweeps, `--reduced-motion` for `prefers-reduced-motion: reduce` capture.

package/skills/qualia-polish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-polish
-description: "Scope-adaptive design pass. Works on a single component, a route, the whole app, a ground-up redesign, or an autonomous visual loop. Trigger on 'polish', 'design pass', 'fix the design', 'redesign', 'critique', 'audit design', 'looks ugly', 'make it look better', 'polish loop', 'visual loop', 'fix what I see', 'iterate on the design until it's correct'. Replaces /qualia-polish-loop (now /qualia-polish --loop) and /qualia-design from earlier versions."
+description: "Scope-adaptive visual quality pass. Works on a single component, a route, the whole app, a ground-up redesign, an aesthetic token pivot, or an autonomous visual loop, but does not repair business logic or broken data flow. Trigger on 'polish', 'design pass', 'fix the design', 'redesign', 'critique', 'audit design', 'looks ugly', 'make it look better', 'different vibe', 'polish loop', 'visual loop', 'fix what I see', 'iterate on the design until it's correct'. Route functional bugs to /qualia-fix."
 allowed-tools:
   - Bash
   - Read
@@ -9,12 +9,16 @@ allowed-tools:
   - Grep
   - Glob
   - Agent
+  - WebSearch
+  - WebFetch
 argument-hint: "[file|route|--redesign|--critique|--quick|--loop] [--register=brand|product] [--brief PATH] [--max 8] [--viewports 375,768,1440]"
 ---
 
 # /qualia-polish — Scope-Adaptive Design Pass
 
-One command. Seven scopes. Use it whenever you need design work, from a 30-second component touch-up to a 30-minute ground-up redesign to a fully autonomous see-fix-verify loop.
+One command. Seven scopes. Use it whenever you need design work, from a 30-second component touch-up to a ground-up redesign with current design research, complex visuals, and a fully transparent see-fix-verify loop.
+
+Polish fixes visual quality only. Broken behavior, failing tests, API bugs, state bugs, and config errors go to `/qualia-fix`. Whole-site aesthetic token pivots stay inside `/qualia-polish --vibe` so the design surface is one command.
 
 ## Scopes
 
@@ -28,25 +32,54 @@ The first argument selects the scope. Stage selection follows from scope.
 | `/qualia-polish --redesign` | **Redesign** | ~30m | all + Stage 1 mandatory + 2 vision iterations |
 | `/qualia-polish --critique` | **Critique** | read-only | 0, 4, 5 (no edits) |
 | `/qualia-polish --quick` | **Quick** | ~1m | 0, 2, 7 (gates only, no vision loop) |
+| `/qualia-polish --vibe` | **Aesthetic pivot** | ~3m | token-only direction swap |
 | `/qualia-polish --loop {url}` | **Loop** | ~5-15m | autonomous see/fix/verify, max 8 iterations |
 
-Other flags: `--register=brand|product` overrides register inference. Loop-specific flags: `--brief PATH`, `--max N`, `--viewports 375,768,1440`, `--ref PATH`, `--budget 100000`.
+Other flags: `--register=brand|product` overrides register inference. Vibe-specific flags: `--variants N`, `--extract URL|image`, `--sync`, `--write`. Loop-specific flags: `--brief PATH`, `--max N`, `--viewports 375,768,1440`, `--ref PATH`, `--budget 100000`.
+
+## Transparent Command Output
+
+Follow `rules/command-output.md`. At minimum, show:
+
+```text
+Command: /qualia-polish {scope}
+Scope: {target files/routes}
+Intent: visual quality | redesign | critique | loop
+Mutation: none | planned | active | blocked
+Evidence: DESIGN.md, PRODUCT.md, qualia-design files, screenshots, online sources when used
+Output: changed files, screenshots, report, commit
+Next: {next command or done}
+```
 
 ## --loop mode (autonomous visual loop)
 
-When `--loop` is the first flag, the polish run is fully autonomous: screenshot a live URL at three viewports, score 8 design dimensions of `qualia-design/design-rubric.md` against the brief using vision, fix top issues in the codebase, re-screenshot, repeat until every dimension scores ≥ 3 or the kill-switch fires (regression, budget cap, max iterations).
+When `--loop` is the first flag, the polish run is fully autonomous: screenshot a live URL at three viewports, score 9 design dimensions of `qualia-design/design-rubric.md` against the brief using vision, fix top issues in the codebase, re-screenshot, repeat until every dimension scores >= 3 or the kill-switch fires (regression, budget cap, max iterations).
 
 Scripts ship at `skills/qualia-polish/scripts/{loop,playwright-capture,score}.mjs`; the vision evaluator is `agents/visual-evaluator.md`; the full loop spec lives in this skill's `REFERENCE.md`.
 
 When `--loop` is detected on entry, route to the loop process documented in `REFERENCE.md` and stop executing the standard stages below. The two paths share Stage 0 substrate gates and the rubric, but diverge from Stage 1 onward.
 
+## --vibe mode (aesthetic token pivot)
+
+When `--vibe` is detected, do not restructure JSX, routes, data flow, navigation, or layout grids. Change only aesthetic tokens and matching DESIGN.md sections: color, typography, depth, motion, brand accents, and short visual-direction copy.
+
+Supporting scripts ship inside this skill:
+
+```bash
+node ${QUALIA_SKILLS}/qualia-polish/scripts/vibe-tokens.mjs sync --design .planning/DESIGN.md
+node ${QUALIA_SKILLS}/qualia-polish/scripts/vibe-tokens.mjs propose-variants --product .planning/PRODUCT.md --design .planning/DESIGN.md --count 3
+node ${QUALIA_SKILLS}/qualia-polish/scripts/vibe-extract.mjs --source https://example.com
+```
+
+Default flow proposes one opinionated direction per `rules/one-opinion.md`. `--variants` is opt-in only. `--extract` stages a reference screenshot for the visual evaluator to reverse-engineer into DESIGN.md tokens; the user must review low-confidence extracted values before application. `--sync --write` patches DESIGN.md to reflect tokens already present in code.
+
 ## Setup gates (non-optional, every scope)
 
 Before any work — design or otherwise — pass these gates. Skipping them produces generic output that ignores the project.
 
 | Gate | Required check | If fail |
 |---|---|---|
-| Substrate | `qualia-design/design-laws.md`, `design-brand.md`, `design-product.md`, `design-rubric.md` exist and have been read | Read them. |
+| Substrate | `qualia-design/design-laws.md`, `design-brand.md`, `design-product.md`, `design-rubric.md`, `design-reference.md`, `frontend.md`, `graphics.md` exist and have been read when scope requires them | Read them. |
 | PRODUCT | `PRODUCT.md` exists at project root, has `register:` field, and is not placeholder (`[TODO]` markers, < 200 chars) | Run setup: ask 5 questions and generate it. Never synthesize from prompt alone. |
 | DESIGN | `DESIGN.md` exists. If missing on App / Redesign scope, BLOCK and run setup. If missing on Component / Section / Critique / Quick scope, NUDGE and proceed. | Generate from PRODUCT.md + 3 questions. |
 | Slop-detect | `bin/slop-detect.mjs` is callable | Install or pull from framework. |
@@ -55,13 +88,13 @@ Before any work — design or otherwise — pass these gates. Skipping them prod
 State this preflight explicitly before editing:
 
 ```
-POLISH_PREFLIGHT: substrate=pass product=pass design=pass|nudged slop_detect=pass mutation=open
+POLISH_PREFLIGHT: substrate=pass product=pass design=pass|nudged graphics=loaded|skipped slop_detect=pass mutation=open
 ```
 
 ## Process
 
 ```bash
-node ~/.claude/bin/qualia-ui.js banner polish
+node ${QUALIA_BIN}/qualia-ui.js banner polish
 ```
 
 ### Stage 0 — Direction commit (mandatory; light on small scopes)
@@ -79,9 +112,19 @@ Aesthetic direction:  {ONE concrete direction — e.g. "editorial broadsheet, iv
 Color strategy:       {ONE choice — Restrained / Committed / Full palette / Drenched — with one-line justification}
 Scene sentence:       {who uses this, where, ambient light, mood — concrete}
 Differentiation:      {what someone remembers 24 hours later}
+Complex visual:       {hero/product/data/diagram/3D/canvas concept, or "none because..."}
+Research anchors:     {2-4 sources checked, or "local only" for component/quick}
 ```
 
-If the user pushes back on the proposed direction, that is a `/qualia-vibe` trigger — switch surfaces, do not start enumerating alternatives in the brief.
+For Redesign scope, run a short online best-practices check before the brief unless the user explicitly says offline. Prefer primary sources:
+- W3C WCAG 2.2 / WAI for accessibility, focus, target size, contrast: https://www.w3.org/TR/WCAG22/
+- Apple Human Interface Guidelines for motion/accessibility restraint: https://developer.apple.com/design/human-interface-guidelines/motion
+- Material Design motion guidance for spatial continuity and state transitions: https://m3.material.io/styles/motion/overview
+- Nielsen Norman Group for visual hierarchy, scannability, and usability evidence: https://www.nngroup.com/articles/visual-hierarchy-ux-definition/
+
+Use the sources as constraints, not as a style to copy. Cite links in the report/summary when they shaped the redesign.
+
+If the user pushes back on the proposed direction, switch to `/qualia-polish --vibe` mode — do not start enumerating alternatives in the brief.
 
 For Component / Section / Quick scope, the brief is implicit (loaded from DESIGN.md). Skip the ultrathink step but cite the relevant DESIGN.md tokens you'll touch.
 
@@ -112,7 +155,9 @@ For App / Redesign / Section scope on multi-file work:
 
 Each agent receives:
 - `qualia-design/design-laws.md` + the matching register file
+- `qualia-design/frontend.md`, `design-reference.md`, and `graphics.md` for App / Redesign / Loop scopes
 - `PRODUCT.md` + `DESIGN.md` (inlined)
+- Online research anchors for Redesign scope, summarized in 3-6 bullets with links
 - Its 5 files (paths + contents)
 - Instruction: apply the Design Quality Rubric per file. Fix every dimension scoring < 3. Make literal edits. Do NOT change logic — only styling.
 
@@ -130,6 +175,21 @@ For Component scope: do the work in main context. Read, fix, verify.
 | Motion intent | DESIGN.md §7 — easing, stagger, signature motion |
 | Microcopy | rename "Get Started" / "Learn More" to action-named CTAs |
 | Container depth | flatten card-on-card; remove side-stripe borders |
+| Complex graphics | graphics.md — add meaningful product/data/process visuals, not decoration |
+
+### Stage 2b — Complex Visual Layer (App / Redesign / Loop)
+
+For whole-app, redesign, and loop scopes, decide whether the page needs a stronger visual system.
+
+1. Read `qualia-design/graphics.md`.
+2. Inspect the product/domain from PRODUCT.md and CONTEXT.md.
+3. Choose one:
+   - **No complex visual**: explain why typography/layout alone is stronger.
+   - **Bitmap/media**: real/generative/search asset that reveals product/place/person/state.
+   - **Diagram/data**: custom SVG/canvas/chart that explains relationships.
+   - **3D/canvas**: Three.js or canvas scene for spatial/product/system experience.
+4. If adding a visual, implement it as a first-viewport or primary-section signal, not a tiny decoration.
+5. Verify mobile framing, reduced-motion fallback, contrast, and nonblank rendering.
 
 ### Stage 3 — Runtime gates (App / Section / Redesign only — needs dev server)
 
@@ -170,7 +230,7 @@ For each iteration:
 
 1. Capture all 3 viewports
 2. Pass to a vision-model agent with `qualia-design/design-rubric.md` as the prompt anchor + DESIGN.md as the spec
-3. The agent scores 8 dimensions, anchored 1-5, with evidence per dimension
+3. The agent scores 9 dimensions, anchored 1-5, with evidence per dimension
 4. Apply fixes ONLY to dimensions scored 1 or 2 (don't nitpick 3s; prevents oscillation)
 5. STOP if: all dimensions ≥ 3 (success), OR any dimension regressed from previous iteration (regression-stop), OR 2 iterations reached (hard cap)
 
@@ -208,7 +268,7 @@ npx tsc --noEmit 2>&1 | tail -10
 
 ### Stage 7 — Commit & state
 
-For Critique scope: write the report to `.planning/polish-critique-{timestamp}.md` and STOP. Do not edit, do not commit.
+For Critique scope: create `.planning/reports/polish/`, write the report to `.planning/reports/polish/polish-critique-{timestamp}.md`, and STOP. Do not edit, do not commit.
 
 For all other scopes:
 
@@ -219,7 +279,7 @@ polish({scope}): {brief summary}
 
 - {key change 1}
 - {key change 2}
-- rubric scores: typography {N}, color {N}, ..., aggregate {N}/40
+- rubric scores: typography {N}, color {N}, graphics {N}, ..., aggregate {N}/45
 
 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 EOF
@@ -229,7 +289,7 @@ EOF
 If this is the FINAL polish before deploy (Handoff milestone, last phase):
 
 ```bash
-node ~/.claude/bin/state.js transition --to polished
+node ${QUALIA_BIN}/state.js transition --to polished
 ```
 
 Otherwise, no state transition (polish is now a normal verb, not a phase boundary).
@@ -237,21 +297,21 @@ Otherwise, no state transition (polish is now a normal verb, not a phase boundar
 ### Output
 
 ```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js ok "Scope: {component|section|app|redesign|critique|quick}"
-node ~/.claude/bin/qualia-ui.js ok "Files: {N}"
-node ~/.claude/bin/qualia-ui.js ok "Slop-detect: {N critical, M high, K medium}"
-node ~/.claude/bin/qualia-ui.js ok "Rubric aggregate: {N}/40 (avg {N})"
-node ~/.claude/bin/qualia-ui.js ok "Vision iterations: {0|1|2}"
-node ~/.claude/bin/qualia-ui.js ok "Drift findings: {N}"
-node ~/.claude/bin/qualia-ui.js end "POLISHED" "{next command — depends on context}"
+node ${QUALIA_BIN}/qualia-ui.js divider
+node ${QUALIA_BIN}/qualia-ui.js ok "Scope: {component|section|app|redesign|critique|quick}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Files: {N}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Slop-detect: {N critical, M high, K medium}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Rubric aggregate: {N}/45 (avg {N})"
+node ${QUALIA_BIN}/qualia-ui.js ok "Vision iterations: {0|1|2}"
+node ${QUALIA_BIN}/qualia-ui.js ok "Drift findings: {N}"
+node ${QUALIA_BIN}/qualia-ui.js end "POLISHED" "{next command — depends on context}"
 ```
 
 ## Rules
 
 1. **Read before write.** Understand every file before changing it.
 2. **DESIGN.md is law.** If a project decision exists, follow it. Don't override.
-3. **Don't break functionality.** Only change styling, never logic.
+3. **Don't repair functionality here.** Only change styling, layout, copy polish, accessibility attributes, and design tokens already authorized by DESIGN.md. Route logic/data/config bugs to `/qualia-fix`.
 4. **Slop is a bug.** Critical-severity findings block commit. No overriding the script.
 5. **TypeScript must pass** after every change.
 6. **One commit per polish run** — not per category, not per file.

package/skills/qualia-polish/scripts/loop.mjs

@@ -16,7 +16,7 @@
  *   {
  *     "iteration": 1,
  *     "viewport_results": [{ viewport, scores, top_issues }],
- *     "aggregate_scores": { typography, color, spatial, layout, shadow, motion, microcopy, container },
+ *     "aggregate_scores": { typography, color, spatial, layout, shadow, motion, microcopy, container, graphics },
  *     "top_issues": [{ dim, severity, description, likely_file, fix }],
  *     "tokens_used": 14500
  *   }
@@ -33,7 +33,7 @@ import path, { dirname } from "node:path";
 import { argv, exit } from "node:process";
 import { spawnSync } from "node:child_process";
 
-const DIMS = ["typography", "color", "spatial", "layout", "shadow", "motion", "microcopy", "container"];
+const DIMS = ["typography", "color", "spatial", "layout", "shadow", "motion", "microcopy", "container", "graphics"];
 
 // ── helpers ──────────────────────────────────────────────────────────────
 function loadState(p) {
@@ -271,7 +271,7 @@ function cmdReport() {
     lines.push(`### Iteration ${it.iteration}`);
     const dims = DIMS.map((d) => `${d.slice(0, 4)}=${it.scores[d] ?? "?"}`).join(" ");
     lines.push(`- Scores: ${dims}`);
-    lines.push(`- Aggregate: ${it.aggregate}/40 (avg ${(it.aggregate / 8).toFixed(2)})`);
+    lines.push(`- Aggregate: ${it.aggregate}/${DIMS.length * 5} (avg ${(it.aggregate / DIMS.length).toFixed(2)})`);
     lines.push(`- Pass: ${it.pass ? "YES" : "NO"} ${it.failing_dims.length ? `(failing: ${it.failing_dims.join(", ")})` : ""}`);
     if (it.top_issues && it.top_issues.length) {
       lines.push(`- Top issues:`);

package/skills/qualia-polish/scripts/score.mjs

@@ -2,11 +2,11 @@
 /**
  * score.mjs -- Qualia visual-polish loop scoring utility.
  *
- * Takes a JSON object with 8 dimension scores and computes pass/fail
+ * Takes a JSON object with 9 dimension scores and computes pass/fail
  * per the design rubric formula from qualia-design/design-rubric.md.
  *
  * Usage:
- *   echo '{"typography":3,"color":2,"spatial":3,"layout":3,"shadow":3,"motion":3,"microcopy":3,"container":3}' | node score.mjs
+ *   echo '{"typography":3,"color":2,"spatial":3,"layout":3,"shadow":3,"motion":3,"microcopy":3,"container":3,"graphics":3}' | node score.mjs
  *   node score.mjs --file scores.json
  *   node score.mjs --scores '{"typography":4,"color":3,...}'
  *
@@ -31,6 +31,7 @@ const DIMENSIONS = [
   "motion",
   "microcopy",
   "container",
+  "graphics",
 ];
 
 const DIMENSION_ALIASES = {
@@ -50,6 +51,11 @@ const DIMENSION_ALIASES = {
   "container depth": "container",
   "container_depth": "container",
   "container depth & nesting": "container",
+  "visual system": "graphics",
+  "visual_system": "graphics",
+  "visual system & graphics": "graphics",
+  "visual_system_graphics": "graphics",
+  "complex graphics": "graphics",
 };
 
 function normalizeKey(key) {
@@ -112,7 +118,7 @@ function computeResult(scores) {
   return {
     scores,
     total,
-    max: 40,
+    max: 45,
     avg,
     pass,
     failing,

package/skills/{qualia-vibe/scripts/extract.mjs → qualia-polish/scripts/vibe-extract.mjs}

@@ -6,11 +6,11 @@
  *   1. If source is a URL → capture screenshot at 1440 via playwright-capture.mjs.
  *      If source is a local image path → use it directly.
  *   2. Emit a JSON scaffold the LLM uses to generate the extracted token bundle.
- *   3. The skill (qualia-vibe) reads the scaffold, runs the vision evaluator in
+ *   3. The skill (qualia-polish --vibe) reads the scaffold, runs the vision evaluator in
  *      extract mode, gets the bundle back, renders it as a DESIGN.md draft.
  *
  * This script does NOT call any LLM directly — it stages the inputs and emits
- * a deterministic JSON contract. The /qualia-vibe skill orchestrates the LLM
+ * a deterministic JSON contract. The /qualia-polish --vibe skill orchestrates the LLM
  * call.
  *
  * Usage:
@@ -35,7 +35,7 @@ function flag(name, fallback) {
 }
 
 const source = flag("--source");
-const outDraft = flag("--out", ".planning/DESIGN-extracted.md");
+const outDraft = flag("--out", ".planning/design/DESIGN-extracted.md");
 
 if (!source) {
   console.error("--source required (URL or local image path)");
@@ -49,7 +49,7 @@ let screenshotPath;
 const isUrl = /^https?:\/\//i.test(source);
 if (isUrl) {
   const stamp = Date.now().toString(36);
-  const outDir = join(tmpdir(), `qualia-vibe-extract-${stamp}`);
+  const outDir = join(tmpdir(), `qualia-polish-vibe-extract-${stamp}`);
   mkdirSync(outDir, { recursive: true });
   screenshotPath = join(outDir, "ref-1440.png");
 
@@ -132,7 +132,7 @@ const scaffold = {
   rules: [
     "Banned fonts: Inter, Roboto, Arial, Helvetica, system-ui, Space Grotesk, Montserrat, Poppins, Lato, Open Sans. If you see one of these, name it AND flag it so the user can decide whether to ban or accept.",
     "Banned patterns: purple-blue gradient, gradient text, bounce/elastic easing. Flag the same way.",
-    "Confidence < high → user must review before /qualia-vibe applies.",
+    "Confidence < high → user must review before /qualia-polish --vibe applies.",
   ],
   next_step: `After producing the bundle, write a DESIGN.md draft to ${outDraft} using the bundle to populate sections 1 (Direction), 2 (Color), 3 (Typography), 4 (Spacing), 6 (Depth), 7 (Motion). Leave sections that depend on PRODUCT.md or anti-references empty — the user will fill them.`,
 };