stream_weaver 0.3.0

data/docs/visual-skills/design/gemini-review.md

@@ -0,0 +1,55 @@
+# Gemini Review Assessment
+
+*Date: 2026-03-12*
+*Gemini CLI run from stream_weaver root with full file access*
+
+## Gemini's Points and Our Assessment
+
+### Point 1: Three-Party "Hanging" Problem — RIGHT
+Tab-close leaves `run_once!` hanging. "Shimmering death" (skeletons that never resolve) is real.
+Stale request scoping to session ID is a good catch neither prior reviewer raised.
+**Action:** Design cancellation path. `run_once!` needs timeout/heartbeat abort. Session-scope requests.
+
+### Point 2: DSL Rigidity "Visual Wall" — HALF-RIGHT
+Agents will occasionally need precise layout control. But escape hatch already exists:
+`div(style: "position: relative; top: 20px") { mermaid "..." }`.
+**Action:** Document `div(style:)` as the explicit escape hatch. No new component needed.
+
+### Point 3: Token Efficiency "Context Bloat" — WRONG
+Gemini's math is off. Current: agent reads ~30K tokens of reference material. With DSL: ~2-3K tokens of
+DSL reference. Net savings of 25K+ input tokens. Retry costs (~500 tokens) are dwarfed by savings.
+Structured DSL is MORE debuggable than raw HTML, not less.
+**No action needed.** 80-85% claim holds.
+
+### Point 4: "Phantom Option" Race Condition — GOOD CATCH
+User requests options for Slide A, navigates to Slide B, options arrive for Slide A.
+Neither prior reviewer caught this specific race condition.
+**Action:** Address in generate-more spike. Push to state, re-render on navigate-back.
+
+### Point 5: Push-to-State Not Push-to-DOM — BEST INSIGHT
+Instead of SSE pushing HTML snippets to DOM targets, push new options to server-side state
+and let StreamWeaver's reactive re-render handle display. This:
+- Eliminates phantom option problem
+- Keeps summary slide in sync automatically
+- Aligns with StreamWeaver's existing reactive model
+- Is simpler than SSE-to-DOM approach
+**Action:** Revise generate-more architecture to push-to-state. Significant improvement.
+
+Disagree with "JSON-over-HTTP as primary protocol" — DSL is right for Ruby-capable agents.
+JSON API is the secondary protocol (already planned for Phase 5 per Codex review).
+
+### Point 6: Component Rot — MOSTLY WRONG
+StreamWeaver is a bounded DSL for agent-to-browser communication, not a general-purpose UI framework.
+"Interactive maps" and "multi-step forms" are out of scope. CSS changes don't require DSL changes.
+Theme presets can be added without touching components.
+**No action needed** beyond keeping component set focused.
+
+## Changes to Incorporate
+
+| Point | Action | Priority |
+|---|---|---|
+| Tab-close cancellation | Design heartbeat + abort for `run_once!` | High (spike) |
+| Session-scoped requests | Scope generate queue to session ID | High (spike) |
+| Escape hatch docs | Document `div(style:)` pattern | Medium (Phase 1) |
+| Phantom option race | Address in spike | High (spike) |
+| Push-to-state | Revise generate-more to push state not DOM | High (architecture change) |

data/docs/visual-skills/design/review-synthesis.md

@@ -0,0 +1,149 @@
+# Review Synthesis: DHH + Codex Second Opinion
+
+## Verdict
+Both reviewers approve the architecture. "Fundamentally sound" (DHH). "Solid" (Codex).
+The DSL design is the strongest element — both reviewers independently praised it.
+
+---
+
+## Where Both Reviewers Agree
+
+### 1. Merge redundant components
+- **VeCard → Card** with `depth:` option
+- **DataTable → Table** with `sticky_header:`, `alternating:`, `scrollable:` options
+- **ProgressIndicator → progress_bar** with `position: :fixed` variant
+**Action:** Reduce component count from ~50 to ~35. Collapse CSS-only wrappers.
+
+### 2. DSL reads beautifully
+Both independently called out Section 10 examples as excellent. "Reads like prose" (DHH).
+"DSL-first approach is well-reasoned" (Codex). No changes needed here.
+
+### 3. Flat namespace is correct
+Both approve. Shared components alongside existing ones. Deck subsystem namespaced.
+
+### 4. Design deck as DSL methods, not subclass
+Both approve. `design_deck` is like `tabs` or `modal`.
+
+### 5. All 9 open questions mostly well-answered
+DHH: "All nine recommendations are sound."
+Codex: "Agree on 7 of 9" (disagrees on Q1 and partially on Q9).
+
+### 6. Phase 1 (shared foundation) is correctly prioritized
+Both agree: Mermaid, CodeBlock, theme enhancements first.
+
+### 7. Polling for generate-more is acceptable
+Both agree polling is fine for an operation that takes 5-15 seconds.
+Codex suggests long-polling as documented future optimization.
+
+---
+
+## Where They Differ
+
+### State Management (Q1)
+- **DHH:** "Start with server session (A). Do not prematurely optimize."
+- **Codex:** "Start with file-backed state (B) from day one. Cookie overflow is when-not-if."
+- **Resolution:** Codex is right here. User-generated notes make cookie overflow likely with 5+ slides. File-backed state is trivially harder to implement but avoids a painful mid-stream migration. **Go with (B).**
+
+### Generate-More Complexity
+- **DHH:** "Kill the state machine. Queue, poll, push. Three steps."
+- **Codex:** "The state machine is too simple — missing CANCELLED, ERROR, PARTIAL states."
+- **Resolution:** Both are right from different angles. DHH says don't over-plan it; Codex says don't under-plan it. **Compromise: spike it first** (Codex's recommendation). The spike will reveal which edge cases matter. Don't design the state machine on paper — discover it through implementation.
+
+### Component Count
+- **DHH:** "Cut by 40%. A div with a CSS class is still a div."
+- **Codex:** "Slightly high but defensible. 50 is manageable."
+- **Resolution:** **DHH is right.** Merge the CSS-only wrappers. The bar for a new component class should be "does it have behavior or state?" not "does it have styling?" Target ~30-35 components.
+
+### Skill Entry Points (Section 6.5)
+- **DHH:** "Kill them. The DSL is the API."
+- **Codex:** "Start with Claude Code custom commands (option C)."
+- **Resolution:** **DHH is right for the gem itself** — no Skill classes in StreamWeaver. **Codex is right for the agent integration** — custom commands are the right glue layer, living outside the gem.
+
+---
+
+## New Issues Raised (Codex Only)
+
+### Must Address Before Implementation
+1. **`beforeunload` / tab-close cancellation** — if user closes tab, `run_once!` hangs forever. Need a cancellation path. Critical.
+2. **State ownership table** — document what state lives where (server/client/localStorage) and how it syncs. Essential for implementation clarity.
+3. **Agent process lifecycle** — heartbeat, crash recovery, clean shutdown of polling thread when `run_once!` resolves.
+4. **CSS naming convention** — enforce `sw-` prefix, define specificity rules before 35 components ship.
+
+### Should Address (Medium Priority)
+5. **Accessibility requirements** — `aria-live`, `aria-current`, `aria-busy` for key components.
+6. **Scalability section** — soft limits (10 slides, 50 files) and hard limits (20 slides, 200 files).
+7. **Phase 2 splitting** — 2a (slide nav), 2b (deck+selection), 2c (summary). Incremental validation.
+8. **Integration test checkpoints** between phases.
+9. **Double-submit prevention.**
+
+### Can Defer (Low Priority)
+10. **JSON-over-HTTP API** — secondary protocol for non-Ruby agents. Phase 5.
+11. **Long-polling optimization** — document as future path.
+12. **CDN fallback / offline degradation.**
+13. **Touch/swipe navigation.**
+
+---
+
+## Revised Architecture Changes
+
+Based on both reviews, the architecture should be updated:
+
+### Component Changes
+| Original | Revised | Rationale |
+|----------|---------|-----------|
+| VeCard | Card with `depth:` option | DHH + Codex agree |
+| DataTable | Table with `sticky_header:` etc. | DHH + Codex agree |
+| ProgressIndicator | progress_bar with `position: :fixed` | DHH |
+| HeroSection | div with CSS class via `hero` DSL helper | DHH |
+| Prose | div with CSS class | DHH |
+| Pullquote | div with CSS class | DHH |
+| FlowArrow | CSS-only, no component class | DHH |
+| Legend | CSS-only, no component class | DHH |
+| DesignDeckSkill | Removed (DSL is API) | DHH |
+| VisualExplainerSkill | Removed (DSL is API) | DHH |
+
+### State Management Change
+- Cookie session → File-backed state (write JSON to temp file per session)
+- Implement `DeckState` object abstracting storage backend (Codex)
+
+### Generate-More Change
+- Spike before designing state machine
+- Phase 3 becomes "spike + implement based on findings"
+
+### New Documentation Sections
+- State ownership table
+- CSS naming convention (`sw-` prefix)
+- Accessibility requirements
+- Scalability limits
+- Agent lifecycle (heartbeat, crash, shutdown)
+
+### Phase Refinement
+- Phase 2 → 2a/2b/2c (incremental validation)
+- Phase 5 → 5a/5b (utility components vs workflow features)
+- Add integration test checkpoints
+
+---
+
+## Revised Component Count: ~32
+
+### Shared (8, down from 9)
+Mermaid, CodeBlock, ImageBlock, SlideContainer, KeyboardShortcuts,
+Toast, HtmlExporter, Chart
+
+### Deck (9, down from 10)
+DesignDeck, DeckSlide, DeckOption, DeckSummary,
+GenerateMoreControls, SkeletonPlaceholder, ModelSelector,
+ConfirmationBar, CloseOverlay
+
+### Explainer-specific (5, down from 19)
+SidebarToc, Comparison, Pipeline, Callout, KpiDashboard
+
+### Enhanced existing (10, down from 12)
+Card (+depth), Table (+sticky/alternating/scrollable),
+Grid, Alert, StatDisplay, Collapsible, ProgressBar (+fixed),
+RadioGroup, Theme (+presets/auto), AlpineJS adapter
+
+### CSS-only helpers (no component class, just DSL methods wrapping div)
+hero, prose, pullquote, dir_tree, legend, flow_arrow, layout_toggle
+
+**Total: ~32 component classes + ~7 CSS helpers = ~39 DSL methods**

data/docs/visual-skills/implementation/STATE.md

@@ -0,0 +1,22 @@
+# Implementation State
+
+## Current Wave: COMPLETE
+## Status: ALL 15 TASKS DONE — 1427 tests, 0 failures
+
+| Task | Status | Commit | Notes |
+|------|--------|--------|-------|
+| T1 | DONE | -- | Generate-more spike - push-to-state validated |
+| T2 | DONE | -- | Theme + CSS foundation |
+| T3 | DONE | -- | Mermaid component with zoom/pan, compact, ELK, theme-aware |
+| T4 | DONE | -- | CodeBlock (Prism.js CDN, file header, truncation) + ImageBlock (caption, base64 export) |
+| T5 | DONE | -- | KeyboardShortcuts (mod mapping, context suppression) + SlideContainer (swap/scroll_snap, progress bar, nav dots, counter, arrow key nav) |
+| T6 | DONE | -- | Card depth/accent/label + Table alternating/scrollable/hover enhancements |
+| T7 | DONE | -- | DesignDeck + DeckSlide + DeckOption shell with SlideContainer swap, auto-columns, ARIA, notes textarea |
+| T8 | DONE | -- | DeckState file-backed store, selection + notes persistence, ARIA, number-key quick-select, selection JS/CSS |
+| T9 | DONE | -- | DeckSummary auto-appended, selection/notes display, submit gating, final notes, submit sets _result for run_once!, fixed progress bar, sw- CSS |
+| T10 | DONE | -- | Generate-more full implementation: GenerateMoreControls + SkeletonPlaceholder components, DeckState generate queue, 4-state machine (idle/generating/timed_out/cancelled), request versioning, server routes (generate/pending/add_option/cancel), push-to-state with SSE re-render, 56 tests |
+| T11 | DONE | -- | SidebarToc (sticky sidebar, scroll spy, mobile horizontal bar) + Callout (5 variants, icon, colored border) + Comparison (side-by-side panels, responsive stacking) |
+| T12 | DONE | -- | Pipeline (horizontal flow, arrow connectors, responsive vertical, status colors) + KpiDashboard (auto-fit grid, fadeIn animation, trend arrows, color accents) + Chart (Chart.js 4 CDN lazy load, bar/line/pie/doughnut/radar, dark mode aware) |
+| T13 | DONE | -- | 7 CSS-only helpers (hero, prose, pullquote, dir_tree, legend, flow_arrow, layout_toggle) + HtmlExporter (self-contained HTML export, CDN collection, inline CSS, base64 images), 80 tests |
+| T14 | DONE | -- | ModelSelector (provider filter pills, model list, DeckState persistence, visibility gating), ConfirmationBar (fixed top bar, slide-down animation, auto-hide timer, confirm/cancel buttons), CloseOverlay (full-screen blur backdrop, submitted/cancelled status, auto-close tab, countdown), server route /deck/set_model, sw- CSS prefix, 46 tests |
+| T15 | DONE | -- | 5 theme presets (editorial/technical/warm/minimal/terminal), theme_preset DSL, Google Fonts injection, CSS animations (fadeIn/slideUp/fadeScale/shimmer/slideDown), stagger delays, slide transitions, prefers-reduced-motion, 104 tests |

data/docs/visual-skills/implementation/plan.md

@@ -0,0 +1,347 @@
+# Visual Skills Implementation Plan
+
+*GSD Ralph-Loop Orchestration*
+*Created: 2026-03-12*
+
+---
+
+## Overview
+
+This plan describes how to execute the 15 tasks in `tasks.md` using the GSD ralph-loop pattern: each task gets a fresh subagent with its own 200K context window, reads specs from files, produces independently committable output, and tracks progress via file-based state.
+
+---
+
+## 1. State Tracking Files
+
+### PLAN.md (this file)
+- Describes the orchestration process
+- Does not change during execution
+
+### STATE.md
+Create at: `docs/visual-skills/implementation/STATE.md`
+
+Tracks live execution state. Format:
+
+```markdown
+# Implementation State
+
+## Current Task: T2
+## Last Completed: T1
+## Status: IN_PROGRESS
+
+| Task | Status | Commit | Notes |
+|------|--------|--------|-------|
+| T1 | DONE | abc1234 | Spike complete. See spike-findings.md |
+| T2 | IN_PROGRESS | -- | Started theme enhancement |
+| T3 | BLOCKED | -- | Waiting on T2 |
+| T4 | NOT_STARTED | -- | |
+| ... | | | |
+```
+
+Status values: `NOT_STARTED`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`
+
+### spike-findings.md
+Created by T1 at: `docs/visual-skills/implementation/spike-findings.md`
+Consumed by T10. Contains the discovered state machine, edge cases, and architectural decisions from the generate-more spike.
+
+---
+
+## 2. Execution Order
+
+### Wave 1: Spike + Foundation (parallel)
+
+**T1 (Generate-More Spike)** and **T2 (Theme + CSS Foundation)** run first, in parallel. T1 has no dependencies. T2 is the foundation for everything else.
+
+```
+Subagent A: T1 (spike)         -- standalone, ~40% context
+Subagent B: T2 (theme)         -- standalone, ~35% context
+```
+
+### Wave 2: Shared Components (parallel after T2)
+
+Once T2 is done, T3, T4, T5, T6 can all run in parallel.
+
+```
+Subagent C: T3 (mermaid)       -- needs T2
+Subagent D: T4 (codeblock)     -- needs T2
+Subagent E: T5 (keyboard+slides) -- needs T2
+Subagent F: T6 (card+table)   -- needs T2
+```
+
+### Wave 3: Deck Core (sequential)
+
+T7, T8, T9 are sequential (each builds on the previous).
+
+```
+Subagent G: T7 (deck shell)    -- needs T5, T6
+Subagent G: T8 (selection)     -- needs T7
+Subagent G: T9 (summary)      -- needs T8
+```
+
+### Wave 4: Generate-More + Explainer (parallel)
+
+T10 needs both T1 and T8. T11, T12 need T2 and T6.
+
+```
+Subagent H: T10 (generate-more) -- needs T1, T8
+Subagent I: T11 (explainer 1)   -- needs T2, T6
+Subagent J: T12 (explainer 2)   -- needs T2, T6
+```
+
+### Wave 5: Polish (parallel)
+
+T13, T14, T15 are independent of each other.
+
+```
+Subagent K: T13 (css helpers)    -- needs T2
+Subagent L: T14 (deck polish)    -- needs T10
+Subagent M: T15 (presets)        -- needs T2
+```
+
+### Optimal Timeline (with parallelization)
+
+```
+Wave 1:  T1 ─────────  T2 ────────
+Wave 2:                  T3  T4  T5  T6
+Wave 3:                              T7 ── T8 ── T9
+Wave 4:                                          T10  T11  T12
+Wave 5:                                                T13  T14  T15
+```
+
+With maximum parallelization, critical path is: **T2 -> T5 -> T7 -> T8 -> T10 -> T14** (6 sequential steps).
+
+---
+
+## 3. Subagent Invocation Protocol
+
+### Starting a Task
+
+Each subagent receives a prompt like this:
+
+```
+You are implementing task T{N} of the StreamWeaver visual skills project.
+
+Read these files first:
+1. docs/visual-skills/implementation/tasks.md -- find task T{N}, read its full specification
+2. docs/visual-skills/implementation/STATE.md -- verify dependencies are DONE
+3. {each file listed in the task's "Input Files" section}
+
+Your job:
+- Create/modify ONLY the files listed in "Output Files"
+- Meet ALL acceptance criteria
+- Run tests: `bundle exec rspec {spec files}`
+- Commit with message: "feat(visual-skills): T{N} - {task title}"
+
+When done:
+- Update STATE.md: set T{N} to DONE, record commit hash
+- Unblock any tasks that depend on T{N}
+```
+
+### Context Budget
+
+Each task is designed to fit within ~50% of the 200K context window:
+- Task spec reading: ~5%
+- Input file reading: ~15-25%
+- Implementation: ~15-20%
+- Test output / iteration: ~5-10%
+- Total: ~40-55%
+
+This leaves ~50% headroom for debugging, retries, and exploratory reading.
+
+### Commit Convention
+
+Each task produces exactly one commit:
+
+```
+feat(visual-skills): T{N} - {task title}
+
+- {bullet 1: what was created}
+- {bullet 2: what was modified}
+- {bullet 3: key decisions made}
+```
+
+Example:
+```
+feat(visual-skills): T3 - Mermaid component
+
+- Add Components::Mermaid with zoom/pan support
+- Add mermaid() DSL method to DisplayDSL
+- CDN loads Mermaid.js lazily via ESM import
+- Theme-aware: reads data-theme for Mermaid themeVariables
+```
+
+---
+
+## 4. Failure Recovery
+
+### Task Fails Tests
+
+1. Subagent fixes and retries within same context window
+2. If context is exhausted, mark task as `FAILED` in STATE.md with notes
+3. Next subagent reads STATE.md, sees failure notes, picks up where previous left off
+
+### Task Produces Wrong Output
+
+1. `git revert {commit}` the bad commit
+2. Update STATE.md to `NOT_STARTED` with notes on what went wrong
+3. Re-run with additional guidance in the prompt
+
+### Dependency Not Ready
+
+1. Subagent reads STATE.md, sees dependency is not `DONE`
+2. Subagent reports `BLOCKED` and exits
+3. Orchestrator retries after dependency completes
+
+### Context Exhaustion
+
+If a task is too large for one context window:
+1. Split into T{N}a and T{N}b
+2. First subagent commits partial work, updates STATE.md
+3. Second subagent continues from committed state
+
+---
+
+## 5. Integration Checkpoints
+
+After each wave, run full test suite and verify integration:
+
+### After Wave 2 (shared components)
+```bash
+bundle exec rspec spec/components/mermaid_spec.rb \
+                   spec/components/code_block_spec.rb \
+                   spec/components/image_block_spec.rb \
+                   spec/components/keyboard_shortcuts_spec.rb \
+                   spec/components/slide_container_spec.rb \
+                   spec/components/card_depth_spec.rb \
+                   spec/components/table_enhanced_spec.rb
+```
+Verify: existing tests still pass (`bundle exec rspec` -- full suite).
+
+### After Wave 3 (deck core)
+```bash
+bundle exec rspec spec/components/deck/
+```
+Manual verification: run example deck app, navigate slides, select options, verify state persistence.
+
+### After Wave 4 (generate-more + explainer)
+```bash
+bundle exec rspec spec/components/deck/generate_more_spec.rb \
+                   spec/components/sidebar_toc_spec.rb \
+                   spec/components/callout_spec.rb \
+                   spec/components/comparison_spec.rb \
+                   spec/components/pipeline_spec.rb \
+                   spec/components/kpi_dashboard_spec.rb \
+                   spec/components/chart_spec.rb
+```
+Manual verification: generate-more flow end-to-end with simulated agent.
+
+### After Wave 5 (polish)
+Full suite: `bundle exec rspec`
+Manual verification: theme presets, HTML export, all deck workflows.
+
+---
+
+## 6. Running the Orchestrator
+
+### Manual Orchestration (recommended to start)
+
+The orchestrator is you (the human or the main Claude Code session). Steps:
+
+1. **Initialize STATE.md:**
+   ```bash
+   cat > docs/visual-skills/implementation/STATE.md << 'EOF'
+   # Implementation State
+
+   ## Current Task: T1, T2
+   ## Last Completed: --
+   ## Status: IN_PROGRESS
+
+   | Task | Status | Commit | Notes |
+   |------|--------|--------|-------|
+   | T1 | NOT_STARTED | -- | |
+   | T2 | NOT_STARTED | -- | |
+   | T3 | BLOCKED | -- | Needs T2 |
+   | T4 | BLOCKED | -- | Needs T2 |
+   | T5 | BLOCKED | -- | Needs T2 |
+   | T6 | BLOCKED | -- | Needs T2 |
+   | T7 | BLOCKED | -- | Needs T5, T6 |
+   | T8 | BLOCKED | -- | Needs T7 |
+   | T9 | BLOCKED | -- | Needs T8 |
+   | T10 | BLOCKED | -- | Needs T1, T8 |
+   | T11 | BLOCKED | -- | Needs T2, T6 |
+   | T12 | BLOCKED | -- | Needs T2, T6 |
+   | T13 | BLOCKED | -- | Needs T2 |
+   | T14 | BLOCKED | -- | Needs T10 |
+   | T15 | BLOCKED | -- | Needs T2 |
+   EOF
+   ```
+
+2. **Launch Wave 1:** Start two subagent sessions (or one at a time):
+   - Session 1: "Implement task T1 per docs/visual-skills/implementation/tasks.md"
+   - Session 2: "Implement task T2 per docs/visual-skills/implementation/tasks.md"
+
+3. **After each task completes:** Verify the commit, check STATE.md was updated, unblock dependent tasks.
+
+4. **Launch next wave** when all dependencies are met.
+
+### Automated Orchestration (future)
+
+A script could automate the loop:
+
+```ruby
+#!/usr/bin/env ruby
+# bin/ralph-loop.rb -- automated task orchestration
+#
+# Reads STATE.md, finds next runnable task (NOT_STARTED with all deps DONE),
+# launches subagent, waits for completion, updates state.
+#
+# Not implemented yet -- manual orchestration is fine for 15 tasks.
+```
+
+---
+
+## 7. Verification Checklist (End-to-End)
+
+When all 15 tasks are complete:
+
+- [ ] `bundle exec rspec` -- all tests pass (existing + new)
+- [ ] Example design deck app renders and navigates
+- [ ] Option selection persists across page reloads
+- [ ] Generate-more flow works with simulated agent
+- [ ] Summary slide shows all selections
+- [ ] Theme toggle works (dark/light/auto)
+- [ ] Theme presets apply correctly
+- [ ] Explainer components render in isolation
+- [ ] SidebarToc scroll spy works
+- [ ] HTML export produces valid self-contained file
+- [ ] CSS uses `sw-` prefix consistently
+- [ ] No regressions in existing StreamWeaver functionality
+- [ ] All components have ARIA attributes where applicable
+
+---
+
+## 8. Key Risks and Mitigations
+
+| Risk | Likelihood | Mitigation |
+|------|-----------|------------|
+| Generate-more state machine more complex than expected | High | T1 spike discovers reality before T10 commits to design |
+| Pushable SSE insufficient for generate-more | Medium | Spike (T1) validates this early; fallback is WebSocket |
+| Card/Table backward compat broken by enhancements | Low | T6 tests verify existing usage unchanged |
+| Context window too small for T7 (deck shell) | Medium | Deck shell is the largest task at ~45%; can split into T7a/T7b if needed |
+| AlpineJS adapter doesn't support new component patterns | Low | New components follow existing adapter pattern; adapter is well-understood |
+| CDN loading conflicts (Mermaid + Prism + Chart.js) | Low | Each loads lazily only when component is used; no global conflicts expected |
+
+---
+
+## 9. File Summary
+
+| File | Purpose |
+|------|---------|
+| `docs/visual-skills/implementation/plan.md` | This file -- how to run the ralph-loop |
+| `docs/visual-skills/implementation/tasks.md` | All 15 tasks with specs |
+| `docs/visual-skills/implementation/STATE.md` | Live execution state (create at start) |
+| `docs/visual-skills/implementation/spike-findings.md` | T1 output, consumed by T10 |
+| `docs/visual-skills/SESSION-CONTEXT.md` | Overall project context |
+| `docs/visual-skills/design/architecture.md` | Architecture reference |
+| `docs/visual-skills/design/review-synthesis.md` | Post-review decisions |
+| `docs/visual-skills/analysis/components.md` | Component inventory |