owflow 0.1.1 → 0.1.3

package/dist/skills/product-design/references/characteristic-detection.md

@@ -0,0 +1,92 @@
+# Characteristic Detection
+
+Guides how the product-design orchestrator detects design characteristics to adapt phase depth. Prevents "specification as bureaucracy" for simple tasks while ensuring complex designs get thorough exploration.
+
+---
+
+## Purpose
+
+Not every design task needs the same depth. A quick "add a settings page" should not go through the same 8-question exploration as "design a new SaaS product from scratch." Characteristic detection runs once during Phase 0 (Initialization) and shapes every subsequent phase.
+
+**Core idea**: Detect early, confirm with user, adapt throughout.
+
+---
+
+## Six Design Characteristics
+
+| Characteristic   | Detection Signals                                                                                            | Mutually Exclusive With               |
+| ---------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
+| `is_greenfield`  | No existing codebase, "new product/app/tool" language, no `.owflow/docs/` present                            | `is_enhancement`                      |
+| `is_enhancement` | Existing codebase, "add/improve/enhance/extend" language, references existing features                       | `is_greenfield`                       |
+| `is_ui_focused`  | "UI/UX/interface/page/screen/dashboard/form" language, UI framework detected in codebase                     | -- (can coexist with `is_backend`)    |
+| `is_backend`     | "API/endpoint/service/data/model/schema" language, no UI framework detected                                  | -- (can coexist with `is_ui_focused`) |
+| `is_complex`     | Long description (>200 words), multiple user types mentioned, cross-cutting concerns, safety-critical domain | `is_simple`                           |
+| `is_simple`      | Short description (<50 words), single clear feature, well-defined scope                                      | `is_complex`                          |
+
+**Mutual exclusivity**: `is_greenfield` and `is_enhancement` cannot both be true. `is_complex` and `is_simple` cannot both be true. UI and backend characteristics can coexist (full-stack designs).
+
+**Default when ambiguous**: When signals are mixed or insufficient, default to higher complexity. Better to ask too many questions and have the user approve-and-move-on than to miss critical context.
+
+---
+
+## Phase Activation Matrix
+
+Characteristics gate which phases activate and at what depth.
+
+| Phase                   | is_greenfield           | is_enhancement                   | is_ui_focused | is_backend | is_complex     | is_simple    |
+| ----------------------- | ----------------------- | -------------------------------- | ------------- | ---------- | -------------- | ------------ |
+| 1 (Context Synthesis)   | User context only       | Codebase + user context          | --            | --         | --             | --           |
+| 2 (Problem Exploration) | Full depth (8-10 Qs)    | Abbreviated (2-3 Qs)             | --            | --         | Full depth     | Abbreviated  |
+| 3 (Personas)            | Full (2-3 personas)     | Skipped                          | --            | --         | Full           | Skipped      |
+| 4 (Ideation)            | Full brainstorm         | Constrained by existing patterns | --            | --         | Full           | Abbreviated  |
+| 5 (Convergence)         | Multiple decision areas | Focused on enhancement scope     | --            | --         | Multiple areas | 1-2 areas    |
+| 6 (Specification)       | Comprehensive sections  | Targeted sections                | --            | --         | 6-8 sections   | 3-4 sections |
+| 7 (Visual Prototyping)  | --                      | --                               | Active        | Skipped    | --             | --           |
+| 8 (Refinement)          | Full review             | Targeted review                  | --            | --         | Full review    | Quick review |
+
+**Reading the matrix**: "--" means the characteristic does not influence that phase. Multiple characteristics combine: a `is_greenfield + is_complex + is_ui_focused` task gets full depth everywhere plus visual prototyping.
+
+---
+
+## Adaptive Depth Scaling
+
+The complexity axis (`is_simple` / standard / `is_complex`) controls depth across interactive phases.
+
+| Complexity           | Exploration Questions | Convergence Areas | Spec Sections | Section Depth                                                                                                                                                         | Refinement Patience     |
+| -------------------- | --------------------- | ----------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| Simple               | 2-3                   | 1-2               | 3-4           | Summary: captures _what_ to build (~20-50 lines/section)                                                                                                              | 2 iterations (soft cap) |
+| Standard             | 4-6                   | 2-3               | 5-6           | Design-level: _what_ + key _how_ decisions (~50-100 lines/section)                                                                                                    | 3 iterations (soft cap) |
+| Complex / Greenfield | 8-10                  | 3-5               | 6-8           | Implementation-level: _what_ + _how_ + edge cases + schemas/contracts (~100-300 lines/section). Developer should be able to start implementation from sections alone. | 3 iterations (soft cap) |
+
+**Standard** is the implicit default when neither `is_simple` nor `is_complex` is detected.
+
+**Refinement patience**: The soft cap on iterative refinement loops before suggesting approval. Not a hard limit -- users can always extend with "One more revision."
+
+---
+
+## User Override Pattern
+
+Detected characteristics are presented to the user at the Phase 0 exit gate for confirmation.
+
+**Flow**:
+
+1. Orchestrator detects characteristics from task description and codebase signals
+2. Phase 0 exit gate presents detected characteristics with rationale
+3. User confirms or corrects misclassification
+4. Override updates `design_characteristics` in orchestrator-state.yml before any phase uses them
+
+**Why this matters**: Automated detection can misread intent. A short description might describe a complex system. An existing codebase might be getting a greenfield module. User confirmation prevents the workflow from optimizing for the wrong depth.
+
+---
+
+## Detection Quality Guidance
+
+**Prefer over-detection**: When description is ambiguous, lean toward higher complexity. The cost of unnecessary depth (user approves-and-moves-on through questions) is much lower than the cost of insufficient depth (missing critical requirements discovered during implementation).
+
+**Codebase signals supplement, not override**: A detected UI framework suggests `is_ui_focused`, but the user's task description takes precedence. If they say "add an API endpoint" in a React codebase, trust the description.
+
+**Re-detection is not supported**: Characteristics are set once during Phase 0 and confirmed by the user. They do not change mid-workflow. If scope changes significantly, the user should start a new design task.
+
+---
+
+This reference provides detection patterns and depth-scaling frameworks. The orchestrator's SKILL.md defines the specific phase logic that consumes these characteristics.

package/dist/skills/product-design/references/interaction-patterns.md

@@ -0,0 +1,206 @@
+# Interaction Patterns
+
+Guides interaction quality in the product-design orchestrator's interactive phases. Defines two cognitive modes, the iterative refinement loop, and question option design.
+
+---
+
+## Purpose
+
+Product design is a conversation, not a form. The orchestrator alternates between exploring the problem space and converging on solutions. These patterns ensure that interaction feels like working with a thoughtful design partner rather than filling out a requirements template.
+
+**Core idea**: Exploration opens possibilities. Convergence narrows them. Both require different interaction strategies.
+
+---
+
+## Cognitive Mode Framework
+
+### Exploration Mode
+
+**When**: Phases 2 (Problem Exploration) and 3 (Persona Development)
+
+**Purpose**: Understand the design space before proposing solutions. Discover constraints, motivations, and context that shape the design.
+
+**Principles**:
+
+- **Avoid anchoring bias**: Do not propose solutions during exploration. Premature solutions close off discovery.
+- **One major question at a time**: Deep understanding of one area before moving to the next. Batch questions overwhelm and produce shallow answers.
+- **Context-aware questions**: Reference codebase analysis findings, user-supplied context, and previous answers. Generic questions waste the user's time.
+- **"Need more info" escape hatches**: Always allow the user to say "I need to think about this" or "Not sure yet" without blocking progress.
+
+**Signal to user**: Announce exploration mode explicitly to set expectations.
+
+> "Let's explore who this feature is really for and what problem it solves..."
+
+**Anti-pattern**: Asking "What do you want?" when you have enough context to ask something specific. Exploration questions should demonstrate understanding of the domain.
+
+### Convergence Mode
+
+**When**: Phases 5 (Idea Convergence), 6 (Specification), 7 (Visual Prototyping review), 8 (Specification Refinement)
+
+**Purpose**: Narrow down from explored possibilities to concrete decisions. Present drafts for reaction rather than asking open-ended questions.
+
+**Principles**:
+
+- **Propose-and-refine**: "Editing is cognitively easier than creating." Present concrete drafts for the user to react to rather than asking them to create from scratch.
+- **Structured drafts**: Present complete artifacts (not summaries or bullet points) so the user can evaluate the actual output.
+- **Aspect-specific feedback**: Guide refinement toward specific dimensions rather than asking "What would you change?"
+
+**Signal to user**: Announce convergence mode to mark the narrative transition.
+
+> "Based on our exploration, here's what I think we've agreed on..."
+
+### Mode Transition
+
+Explicitly announce transitions between modes. This creates a narrative arc that helps the user understand where they are in the process.
+
+> "We've explored the problem space thoroughly. Now let me synthesize what we've discussed into a concrete direction."
+
+**Why explicit transitions matter**: Without them, the shift from open-ended questions to concrete proposals feels abrupt. The user may still be in exploration mindset when you need them to evaluate specifics.
+
+---
+
+## Iterative Refinement Loop Pattern
+
+A new owflow pattern for convergence points where artifacts need user approval.
+
+### When to Apply
+
+At every convergence point where the orchestrator produces a draft artifact:
+
+- Phase 2: Problem statement synthesis
+- Phase 5: Idea convergence and direction selection
+- Phase 6: Specification sections
+- Phase 7: Visual mockups
+- Phase 8: Final specification review
+
+### Flow
+
+```
+Present complete draft → question (approve / change / rethink / add detail / explain)
+  → [revision] → present complete revised draft → question (same options)
+  → [after soft cap] → question (approve current / one more revision / step back)
+```
+
+**Standard options**: "Approve and continue", "Change [aspect A]", "Change [aspect B]", "Rethink the approach", "Add more detail", "Let me explain my thinking"
+
+**Soft cap options** (after iteration limit): "Approve current version and move on", "One more revision", "Step back and rethink"
+
+### Key Rules
+
+**Complete drafts always**: Every revision presents the COMPLETE updated artifact. Never present a diff, a summary of changes, or a table of what changed. The user should be able to evaluate the artifact on its own merits without referencing the previous version.
+
+**Soft cap, not hard limit**: `refinement_iterations.[phase]` tracks iteration count in orchestrator-state.yml. After reaching the soft cap (2 for simple tasks, 3 for standard/complex), the options shift to encourage approval. But the user can always choose "One more revision."
+
+**"Rethink the approach"**: This is a significant action. It signals that incremental changes will not fix the problem. The orchestrator should step back, re-examine assumptions, and present a substantially different draft -- not a minor variation of the previous one.
+
+**Special option in Phase 5**: "Explore more" triggers re-generation by returning to Phase 4 (Ideation) for fresh brainstorming. This acknowledges that sometimes none of the converged ideas feel right.
+
+### State Tracking
+
+```yaml
+refinement_iterations:
+  phase_2: 1
+  phase_5: 0
+  phase_6_section_user_stories: 2
+  phase_7: 1
+```
+
+Track per-phase (or per-section in Phase 6) to apply soft caps independently. A heavily-iterated persona definition should not consume the refinement budget for specification sections.
+
+---
+
+## question Option Design
+
+Options are not just UI -- they shape the conversation. Well-designed options anticipate what the user is likely thinking.
+
+### Exploration Mode Options
+
+Structure: topical choices + escape hatches
+
+**Pattern**:
+
+- 2-4 topical options that advance exploration in specific directions
+- "Need more info" or "Not sure yet" option (does not block progress)
+- "Let me explain my thinking" (open-ended escape hatch)
+
+**Example** (Phase 2 exploration):
+
+```
+- "The main problem is [user frustration with X]"
+- "Actually, it's more about [business need Y]"
+- "Both are important, but prioritize [X]"
+- "Let me explain my thinking"
+```
+
+**Why topical options work in exploration**: They demonstrate that the orchestrator is listening and synthesizing. The user confirms, corrects, or elaborates -- all of which deepen understanding faster than open-ended "What else should I know?"
+
+### Convergence Mode Options
+
+Structure: approve + aspect-specific changes + structural options + escape hatch
+
+**Pattern**:
+
+- "Approve and continue" (always first)
+- "Change [aspect A]" / "Change [aspect B]" (2-3 specific refinement targets)
+- "Rethink the approach" / "Add more detail" (structural options)
+- "Let me explain my thinking" (open-ended escape hatch)
+
+**Aspect-specific "Change" options**: Anticipate the most likely refinement areas for the artifact type:
+
+- For a persona: "Change role", "Change goals", "Change pain points"
+- For a problem statement: "Change scope", "Change priority", "Change constraints"
+- For a spec section: "Change requirements", "Change acceptance criteria", "Change scope"
+- For a mockup: "Change layout", "Change content", "Change interactions"
+
+### Universal Rules
+
+**Always include an open-ended escape hatch**: "Let me explain my thinking" covers cases where none of the structured options match the user's intent. Without it, users feel trapped in a multiple-choice quiz.
+
+**Never present all decision areas in a single batch**: One area at a time with full context. Batch decisions produce shallow answers because users optimize for completion speed rather than quality.
+
+**Order matters**: Put the most likely action first. In convergence, that is usually "Approve" (most drafts are close enough). In exploration, lead with the option that advances the conversation most.
+
+---
+
+## Interaction Quality Principles
+
+### Prose is the Conversation
+
+Rich contextual prose BETWEEN question calls is the actual design conversation. question calls are punctuation marks -- they structure the conversation but do not replace it.
+
+**Before asking**: Synthesize what you have learned. Show the user that their previous answer was heard and integrated.
+
+> "Got it -- so the key constraint is that existing users should not need to re-learn navigation. That means we need to extend the current sidebar pattern rather than introducing a new navigation model."
+
+**After receiving an answer**: Acknowledge and bridge to the next question or draft.
+
+> "That makes sense. The two-persona approach (admin vs. viewer) gives us clear boundaries for feature scoping. Let me draft the admin persona first since they have the more complex workflow."
+
+### Synthesis Over Repetition
+
+After each answer, synthesize -- do not merely acknowledge. The synthesis shows understanding and gives the user a chance to correct misinterpretation before it compounds.
+
+**Pattern**: "So what I'm hearing is [synthesis]. [Bridge to next step]."
+
+### Mode Labels at Transitions
+
+Every phase transition between exploration and convergence gets an explicit label. This is not optional -- users need the narrative context to understand why the interaction style is changing.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern                                         | Why It Fails                                                    | Better Approach                                      |
+| ---------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
+| Summary table of changes across iterations           | User must mentally diff two versions                            | Present complete revised draft every time            |
+| Skipping mode labels                                 | User is confused by sudden shift from questions to proposals    | Always announce "Now let's converge..."              |
+| Single-round approve-or-reject                       | No room for iterative refinement                                | Use the refinement loop with aspect-specific options |
+| "What do you want?" in convergence                   | Shifts cognitive burden to user when you have enough to propose | Use propose-and-refine: present a draft              |
+| All decision areas in one batch                      | Produces shallow answers                                        | One area at a time with full context                 |
+| Form-filling: rapid-fire questions without synthesis | Feels like a bureaucratic intake process                        | Synthesize between questions, show understanding     |
+| Proposing solutions during exploration               | Anchors thinking, closes off discovery                          | Explore fully before proposing                       |
+| Generic questions ignoring context                   | Wastes user's time, signals lack of understanding               | Reference codebase analysis and prior answers        |
+
+---
+
+This reference provides interaction patterns and frameworks. The orchestrator's SKILL.md defines the specific phase logic that applies these patterns.

package/dist/skills/product-design/references/visual-companion.md

@@ -0,0 +1,190 @@
+# Visual Companion
+
+Documents the browser-based visual companion architecture for the product-design orchestrator. Provides high-fidelity visual feedback by rendering HTML/CSS mockups in a browser during design sessions.
+
+---
+
+## Purpose
+
+Terminal-based ASCII mockups are useful but limited. For UI-focused design tasks, seeing actual rendered HTML/CSS in a browser gives qualitatively better feedback. The visual companion provides this without requiring any external tools, npm packages, or design software.
+
+**Core idea**: Orchestrator generates HTML/CSS, sends to a local server, browser renders it, user reviews and provides feedback in the terminal. Browser is read-only visual output -- all interaction stays in the terminal via question.
+
+---
+
+## Architecture Overview
+
+```
+Orchestrator → POST /update → Node.js Server → SSE "refresh" → Browser (renders mockup)
+                                                                   ↓ user views
+                                                              Terminal (question)
+```
+
+**Data flow is one-directional**: Orchestrator pushes content to server, server pushes to browser, user reviews in browser, feedback flows through terminal. The browser never sends data back to the orchestrator.
+
+---
+
+## Zero-Dependency Principle
+
+The server uses ONLY Node.js built-in modules: `http`, `fs`, `path`, `url`. No npm install required. No package.json needed.
+
+**SSE over WebSocket**: Server-Sent Events replace WebSocket for simplicity. SSE works with the native browser `EventSource` API, requires no client library, and handles reconnection automatically. One-directional push (server to browser) is all we need.
+
+**Why zero-dependency matters**: The visual companion starts inside a product-design workflow. Requiring `npm install` would add failure modes, slow down startup, and create version compatibility issues. Node.js built-in modules are sufficient for a local development server.
+
+---
+
+## Communication Protocol
+
+| Endpoint | Method | Purpose | Request/Response |
+|---|---|---|---|
+| `/status` | GET | Health check | Response: `{"status":"ok","version":"1.0.0"}` |
+| `/` | GET | Current mockup | Response: HTML page with mockup wrapped in template |
+| `/events` | GET | SSE stream | Response: `text/event-stream`, sends `data: refresh\n\n` on update |
+| `/update` | POST | Push new mockup | Body: `{type, title, html, css, annotations}` |
+
+### POST /update Body Schema
+
+```json
+{
+  "type": "mockup",
+  "title": "Settings Page - Desktop",
+  "html": "<div class='settings'>...</div>",
+  "css": ".settings { padding: 1rem; }",
+  "annotations": [
+    {"selector": ".settings", "text": "Reuses existing card component"}
+  ]
+}
+```
+
+**Annotations**: Positioned tooltips overlaid on mockup elements. Togglable via the "Annotations" button in the UI header (on by default, preference persists via localStorage). Use for component reuse hints, integration points, and interaction hints — NOT for feature descriptions or requirements.
+
+Example annotations:
+- `{"selector": ".patient-card", "note": "Reuses existing <PatientCard> component"}`
+- `{"selector": ".save-btn", "note": "Triggers webhook notification"}`
+- `{"selector": ".drag-handle", "note": "Drag to reorder"}`
+
+---
+
+## Lifecycle
+
+### Startup
+
+1. Spawn server process: `node ${SKILL_DIR}/server/index.mjs`
+2. Port allocation: try 3847, fallback through 3848-3850
+3. Verify ready: poll `GET /status` until ok (timeout after 3 seconds)
+
+### Browser Opening
+
+1. **Primary**: Playwright MCP `browser_navigate` (if configured)
+2. **Fallback 1**: `open` command (macOS) / `xdg-open` (Linux)
+3. **Fallback 2**: Log URL for manual opening, continue with terminal-only review
+
+### Teardown
+
+Kill server via `POST /shutdown` endpoint on:
+- Workflow completion (Phase 8 sends POST /shutdown after final approval)
+- Workflow cancellation
+
+**PID file**: Server writes its PID to `{taskPath}/analysis/mockups/.visual-companion.pid` on startup. Cleaned up on shutdown, SIGTERM, and SIGINT. Enables reliable process identification.
+
+**Stale server detection**: Phase 7 checks `/status` before starting a new server. The response includes `taskPath` — if it belongs to a different task, the server is stale and gets shut down via `POST /shutdown` before starting a new one.
+
+---
+
+## Graceful Degradation Matrix
+
+The visual companion is an enhancement, not a requirement. Every failure has a fallback.
+
+| Scenario | Detection | Fallback |
+|---|---|---|
+| Node.js not available | `which node` fails | ASCII mockups via ui-mockup-generator agent |
+| Port 3847 in use | Server startup error (EADDRINUSE) | Try ports 3848-3850, then ASCII fallback |
+| Playwright MCP not configured | MCP tool call fails | Log URL for manual browser opening |
+| Browser fails to open | Playwright error + open command error | Log URL, continue with terminal-only review |
+| Server crashes mid-session | `GET /status` returns error or timeout | Restart server; if 2nd failure, ASCII fallback |
+| No issues | `GET /status` returns ok | Full visual companion experience |
+
+**Degradation principle**: Never block the design workflow because the visual companion failed. The core design conversation happens in the terminal. Visual rendering is additive value.
+
+---
+
+## HTML Template Pattern
+
+The server wraps mockup content in a base template that provides:
+
+- **Viewport meta**: Responsive rendering matching common device widths
+- **CSS reset**: Minimal reset so mockup styles render predictably
+- **SSE client script**: `EventSource` connection to `/events` with auto-reconnect on disconnect
+- **Annotation overlay script**: Renders positioned tooltips from annotation data
+- **Placeholder state**: "Waiting for design mockup..." shown before first `POST /update`
+
+**Template is server-side, not orchestrator-side**: The orchestrator sends only the mockup `html` and `css`. The server wraps it in the template. This keeps the orchestrator focused on design content rather than boilerplate.
+
+**Auto-refresh behavior**: When the SSE stream receives a `refresh` event, the page reloads to fetch the updated mockup from `GET /`. No manual refresh needed.
+
+---
+
+## Integration with Phase 7 (Visual Prototyping)
+
+Phase 7 follows this sequence when visual companion is available:
+
+1. **Check availability**: `GET /status` to see if server is already running
+2. **Start server if needed**: Spawn Node.js process, verify ready
+3. **Open browser**: Playwright MCP or open command or log URL
+4. **Generate mockup**: Create HTML/CSS from spec context and design decisions
+5. **Push to server**: `POST /update` with mockup content
+6. **Present for review**: question in terminal (user views mockup in browser)
+7. **Iterative refinement**: Revise mockup, re-POST, re-review (follows refinement loop pattern)
+8. **Save approved mockup**: Write final HTML/CSS to `analysis/mockups/` in task directory
+
+**When visual companion is unavailable**: Phase 7 falls back to the `ui-mockup-generator` agent for ASCII mockups. The iterative refinement loop still applies -- only the rendering medium changes.
+
+### Mockup Generation Guidance
+
+The orchestrator generates mockup HTML/CSS based on:
+- Specification sections from Phase 6
+- Design decisions from Phase 5 convergence
+- Existing codebase UI patterns (from Phase 1 codebase analysis, if enhancement)
+- Persona workflows from Phase 3 (if greenfield)
+
+**Fidelity target**: Mid-fidelity. Enough structure and styling to evaluate layout, hierarchy, and flow. Not pixel-perfect production CSS. Focus on communicating the design intent, not building the final UI.
+
+**What to generate** (user-facing wireframes/screens):
+- Dashboard views, settings pages, list/detail screens
+- Forms, modals, navigation bars, sidebars
+- Data tables, cards, search/filter interfaces
+- Empty states, error states, loading states
+- Responsive layouts (desktop and mobile variations)
+
+**What NOT to generate** (technical diagrams — these belong in analysis artifacts):
+- System architecture diagrams
+- Data flow charts, sequence diagrams
+- Entity relationship diagrams
+- Component dependency graphs
+
+**Multiple screens**: Complex designs need multiple screens. The visual companion maintains a gallery — each `POST /update` adds a screen. Give each a descriptive title (e.g., "Patient Dashboard", "Settings - Notifications", "Error State - Network Failure"). The user can browse all screens via the gallery at `GET /`.
+
+**Screen-to-screen navigation**: Add `data-screen="slug"` to interactive elements (links, buttons, cards) in mockup HTML. Clicking navigates to the target screen in the visual companion. The slug is the lowercase-hyphenated version of the screen title (e.g., "Settings Page" → `data-screen="settings-page"`). This creates an interactive prototype experience where the user can click through the flow.
+
+---
+
+## Server State & Persistence
+
+The server maintains a screen gallery in memory and persists to disk:
+
+- **Mockups array**: All POSTed screens (ordered, accessible by slug ID)
+- **SSE clients**: Active EventSource connections for refresh notifications
+- **Version counter**: Incremented on each update
+- **Disk persistence**: Each POST automatically saves the rendered HTML to `{task_path}/analysis/mockups/{slug}.html` — pass `--task-path` when starting the server
+
+**Routes**:
+- `GET /` → Gallery index (grid of all screen cards)
+- `GET /screen/{id}` → Individual screen with prev/next navigation
+- `GET /latest` → Most recently POSTed screen (SSE refresh target)
+
+Screens are saved to disk immediately on POST — if the session drops, mockups survive in `analysis/mockups/`.
+
+---
+
+This reference provides the visual companion architecture and integration patterns. The server implementation lives in `server/index.mjs` and the orchestrator's SKILL.md defines the specific phase logic that uses the visual companion.