@jamie-tam/forge 6.0.0

package/skills/build-wireframe/references/gotchas.md

@@ -0,0 +1,188 @@
+# Gotchas — bugs that took multiple iterations to find
+
+Read this when something renders wrong despite following the rules. These are real bugs that appeared during the 7-iteration build and are easy to repeat.
+
+## Layout traps
+
+### Sticky tab bar covers top callouts
+
+**Symptom:** Top-side callout labels are missing from the rendered output, or appear *under* the tab strip.
+
+**Cause:** Tab bar has `sticky top-3 z-20`. Top callouts are positioned at `bottom: stage_height + margin + label_height` from the bottom of the parent — which puts them in the y-range of the sticky tab bar. Tab bar's z-index wins because `z-20 > z-5` on Callouts.
+
+**Fix:** Drop `sticky` from the tab bar. Make it `flex flex-wrap items-center gap-x-4 gap-y-2` in normal flow. Then ensure the stage wrapper has `mt-32` (128 px) to give top callouts breathing room below the tab bar's natural height (~106 px when wrapped to 2 rows).
+
+### Side-callout labels clipped at viewport edge
+
+**Symptom:** Left/right callout labels have their first/last few characters cut off.
+
+**Cause:** The label box is 230 px wide and sits 60 px outside the stage edge — total footprint 290 px. If the gutter is < 290 px, the label overflows the page container. With a body that has `overflow: hidden` (or even default behavior on narrow viewports), the overflow is clipped.
+
+**Fix:** Use 320 px gutters minimum. Update `marginLeft: 320, marginRight: 320, width: "calc(100% - 640px)"` on the stage container. On a 1920 viewport this gives a 1280-px-wide stage at scale 0.667, with 320 px of clear gutter space on each side.
+
+### Stage scaled too small on wide monitors
+
+**Symptom:** On a 4K screen, the wireframe sits in the middle at ~60% of available width.
+
+**Cause:** Outer container has `max-w-[1680px] mx-auto` and stage has `maxWidth: 1280`. Both cap the size.
+
+**Fix:** Outer container `style={{maxWidth: 2400}}`, stage `maxWidth: 1920`. Now on a wide monitor the stage hits 1:1 scale instead of being capped at 67%.
+
+## Callout traps
+
+### Two callouts pointing at the same `id`
+
+**Symptom:** Two leader lines terminate at the same dot.
+
+**Cause:** The `_CALLOUTS` array has two entries with the same `id`. The Callouts overlay queries by id and renders both leaders pointing to the same anchor.
+
+**Fix:** Each callout needs a unique `id`. If you want to label the same element from two angles (rare and usually wrong), give each angle its own anchor with a distinct id.
+
+### Zero-length leader (label flush against stage edge)
+
+**Symptom:** A side label has effectively no visible leader; the dot is right at the wireframe boundary.
+
+**Cause:** The element is at the wireframe edge AND `anchor` is on the same edge. E.g. WhySheet is flush-right; setting `anchor: "right"` puts the dot on the right edge of the sheet, which IS the wireframe right edge — leader has zero horizontal travel.
+
+**Fix:** Flip `anchor` to the opposite edge so the leader has visible travel. `WhySheet` callouts use `anchor: "left"` so the dot lands inside the sheet near its left boundary; the leader travels right across the sheet to the gutter.
+
+### Leader cuts across the wrong row
+
+**Symptom:** A multi-column row (e.g. announcements + schedule + recent) gets a callout described as "this row of supporting components" but the leader points at one specific column instead.
+
+**Cause:** Anchor span is inside ONE cell of the grid (e.g. the announcements column). Its bounding rect is the cell's right edge, which is in the middle of the row.
+
+**Fix:** Move the span out of the inner cell. Add `relative` to the OUTER row wrapper and host the span there at `right-0 top-1/2`. Now the dot lands at the row's outer right edge, which (when the centre extends to the wireframe edge) is at the wireframe's right border. Reads as "this whole row".
+
+### Leader goes to the FAR gutter
+
+**Symptom:** A banner at the top of the wireframe has its label in the bottom gutter; a button in the right rail has its label in the bottom gutter.
+
+**Cause:** Wrong `side` chosen. The rule is "closest gutter wins" — but it's tempting to default to `bottom` for action buttons or `top` for global elements without thinking about which gutter is actually closest.
+
+**Fix:** Pick `side` by physical proximity to the anchor.
+- Top-of-stage banner → `side: "top"`
+- Right-rail button → `side: "right"`
+- Bottom-of-stage footer → `side: "bottom"`
+- Sidebar item → `side: "left"`
+
+The leader should never cross the stage to reach a far gutter.
+
+## Demo state traps
+
+### Per-step callouts disappear immediately on demo mount
+
+**Symptom:** The demo's step 0 has no callouts visible. Console is clean. The anchor IDs are present in the DOM. The CALLOUTS array has entries.
+
+**Cause:** App component has a useEffect that resets dynamic callouts on `[active]`. Parent useEffects run AFTER child useEffects, so:
+1. Demo mounts, useEffect fires, pushes step-0 callouts
+2. App's reset useEffect fires, sets dynamicCallouts back to null
+3. Re-render with no callouts
+
+**Fix:** Don't reset in App. Move the reset to the demo's useEffect cleanup function:
+
+```jsx
+React.useEffect(() => {
+  if (setCallouts) setCallouts(D1_STEP_CALLOUTS[step] || []);
+  return () => { if (setCallouts) setCallouts(null); };  // cleanup on unmount
+}, [step, setCallouts]);
+```
+
+When the demo unmounts (view change), cleanup runs and nulls the callouts. New view's mount push (or static view's nothing) takes over cleanly.
+
+### Inbox highlighted case is wrong channel after Accept
+
+**Symptom:** D1 inbound demo accepts a phone call, but the inbox's highlighted row is an EMAIL case for the same customer.
+
+**Cause:** The demo passed `activeCaseId="CS-4860"` — but CS-4860 is the existing email row in the shared `LeftCaseList`. The demo treated it as the new call case but the inbox doesn't have a phone row for that customer.
+
+**Fix:** Use the `injectActive` prop on `LeftCaseList`:
+
+```jsx
+<LeftCaseList
+  activeCaseId="CS-4861"
+  injectActive={{id: "CS-4861", name: "Chan · live call", channel: "phone"}}
+/>
+```
+
+This prepends a fresh phone row at the top of the Open section, bumps the count by 1, and highlights it. The existing email row stays below — modeling that the customer might have multiple cases.
+
+### Two demos share the wrap-up modal but their content diverges
+
+**Symptom:** The demo's wrap-up has fewer fields than S7's. Tags / Case status / merge nudge missing.
+
+**Cause:** A `DemoWrapUpModal` was created as a stripped-down clone of S7's `WrapUpModal`. They drift over time — one gets a new field, the other doesn't.
+
+**Fix:** Don't fork. Refactor S7's `WrapUpModal` to accept `onSave`, `onHome`, `headline`, `subline`, `saveAnchorId` props (all optional, defaults match S7's existing behavior). Demos use the same component with their props. Single source of truth.
+
+## Component / styling traps
+
+### `bg-amber-50/50` matches the same selector as callout label boxes
+
+**Symptom:** Counting callout labels via `[class*="bg-amber-50"][class*="border-amber-200"][class*="rounded"]` returns more labels than expected.
+
+**Cause:** The `AnnouncementsBlock` "System" announcement row has `bg-amber-50/50` + `border-amber-200` + `rounded-md`. Selector matches.
+
+**Fix:** Use a more specific selector that includes `text-center` (which only callout labels have):
+
+```js
+document.querySelectorAll('.pointer-events-none [class*="text-center"][class*="bg-amber-50"]')
+```
+
+### Browser caches the artifact across iterations
+
+**Symptom:** Edits to the file aren't reflected in the browser even after reload.
+
+**Fix:** Add a cache buster to the URL: `http://localhost:8767/index.html?v=2#s1`. Bump `v` each iteration.
+
+### `file://` protocol blocked in Playwright
+
+**Symptom:** Trying to navigate to `file:///path/to/index.html` in Playwright produces "Access to file: protocol is blocked".
+
+**Fix:** Run a local server: `npx http-server -p 8767 -c-1 .` from the wireframe directory. Then navigate to `http://localhost:8767/index.html`.
+
+## Verification recipe (Playwright)
+
+When you've made callout changes, this query batch-checks every state for clipping and tab-overlap issues:
+
+```js
+async () => {
+  const views = ['s1','s2','s3','s4','s5','s6','s7','sup1','sup2','sup3','sup4','sup5'];
+  const out = {};
+  for (const v of views) {
+    window.location.hash = '#' + v;
+    await new Promise(r => setTimeout(r, 400));
+    const labels = Array.from(document.querySelectorAll('.pointer-events-none [class*="text-center"][class*="bg-amber-50"]'));
+    const tabbar = document.querySelector('[class*="flex flex-wrap"][class*="border-border"][class*="rounded-md"]');
+    const tabBottom = tabbar ? tabbar.getBoundingClientRect().bottom : 0;
+    const issues = [];
+    labels.forEach(l => {
+      const r = l.getBoundingClientRect();
+      if (r.left < 0) issues.push('L'+Math.round(-r.left));
+      if (r.right > window.innerWidth) issues.push('R'+Math.round(r.right - window.innerWidth));
+      if (r.top < tabBottom + 4) issues.push('T');
+    });
+    out[v] = {n: labels.length, issues};
+  }
+  return out;
+}
+```
+
+Goal: every state has `issues: []`. If any view shows L/R/T entries, look up the matching gotcha above.
+
+## Iteration history (one-line each)
+
+These are the iterations the wireframe artifact went through. Each one closed a real bug.
+
+- **i1** — Initial 14-state build.
+- **i2** — Removed duplicate-anchor entries, larger flow thumbs, 3 interactive demo tabs.
+- **i3** — Wider stage, tab-bar wraps, callouts 30→48 (rule 4 flipped from "less" to "comprehensive").
+- **i4** — Playwright-verified everything; tab-bar non-sticky; gutter 220→320; rule 7 v1 added.
+- **i5a–b** — Sidebar/Inbox leaders moved to left edge; KPI footer to bottom; announcements to outer row wrapper.
+- **i5c** — Per-step demo callouts wired up; race condition fixed via cleanup-on-unmount.
+- **i5d** — Rule 7 generalized: closest path wins for `side` AND `anchor`.
+- **i5e** — Wrap-up modal de-duplicated; one canonical component for S7 + demos.
+- **i5f** — D3 email composer became a real editor (toolbar + To/Subject + body) with templates rail.
+- **i5g** — Inbound demo highlights fresh phone case via `injectActive`, not stale email row.
+
+Don't try to skip directly to "the final state" — the rules above only make sense if you understand what they're protecting against. When stuck, find the matching iteration and read its log entry.

package/skills/build-wireframe/references/legend-lines.md

@@ -0,0 +1,141 @@
+# Legend lines — visual reference
+
+This is the consolidated rulebook for the dashed-line callouts that connect outer-gutter labels to dots inside the wireframe. The rules below are non-negotiable.
+
+## The pattern at a glance
+
+Every callout has TWO halves: an anchor element inside the wireframe, and a CALLOUTS entry that describes how to draw the leader.
+
+```jsx
+// inside a component — option 1: id directly on a content element
+<div id="a-mything" className="...">...</div>
+
+// inside a component — option 2: a 0-size span anchor positioned at a chosen edge
+<div className="relative ...">
+  <span id="a-mything" className="absolute right-0 top-1/2" data-callout-anchor="" />
+  ... content ...
+</div>
+
+// then in the state's _CALLOUTS array
+const SXyz_CALLOUTS = [
+  { id: "a-mything", side: "right", anchor: "right", label: "Description ≤ 80 chars" },
+];
+```
+
+`side` picks the gutter the label lives in (`top` · `bottom` · `left` · `right`).
+`anchor` picks which edge of the anchor element's bounding box the dot lands on (`left` · `right` · `top` · `bottom` · `center`).
+
+For 0-size span anchors, the `anchor` field is essentially a no-op (the bbox has zero width/height) — the **span position is what matters**. Use `right-0 top-1/2` to put the dot at the right edge of the parent container, `left-0 top-1/2` for the left edge, `left-1/2 top-0` for top-centre, `left-1/2 bottom-0` for bottom-centre.
+
+## The 7 rules
+
+### 1. Anchor on the section's edge facing its label
+
+A right-side label anchors on the section's right edge, not its centre. A left-side label anchors on the left edge. Why: the leader becomes a tiny stub from element-edge to gutter, instead of a long line cutting through the element.
+
+### 2. Leader is mostly a single straight run
+
+One horizontal or vertical run from anchor to label. No diagonals through the wireframe. The render code uses an L-shaped elbow when label.y ≠ anchor.y; rule 3 governs where the bend happens.
+
+### 3. Bend only in the gutter, never over UI
+
+When the label sits at a different y from the anchor (collision pushed it), the leader bends 16px inside the gutter — never crossing the wireframe stage. The render code already handles this (look for `elbowX = p.lx ± 16` in the Callouts component). Don't introduce custom paths that route through UI.
+
+### 4. Comprehensive over minimal
+
+Aim for **5–8 callouts per main-shell state**, covering each chrome column AND each section of the main-content area. Earlier versions of this skill said "less is more · 2-4 callouts" — that turned out to be wrong for presales artifacts where viewers want the entire UI explained. Drop a callout only if its leader genuinely cannot avoid crossing other UI.
+
+The split: column callouts describe shell elements (topbar, sidebar, case list, right rail). Section callouts describe content (each section in the main centre). Both are valued.
+
+### 5. Collision-avoidance push direction is fixed
+
+When two labels on the same gutter would overlap, push later-in-DOM-order labels:
+- Top/bottom labels: push right (later moves x+).
+- Left/right labels: push down (later moves y+).
+
+This keeps each label visually paired with its anchor — the eye expects to look down/right for the next callout, not up or left.
+
+### 6. Overlay states annotate the overlay, not the underlying shell
+
+Modal / sheet / banner states (Command palette, Why? sheet, Inbound banner, Wrap-up modal) draw their callouts targeting overlay anchors. The dimmed shell underneath is context, not content. Don't double up by annotating the shell at the same time.
+
+### 7. Closest path wins — for both `side` and `anchor`
+
+This is the most important rule and the one most often violated.
+
+Pick the **side** whose gutter is NEAREST the anchor element. Then anchor on the element's edge facing that gutter.
+
+- A banner at the top of the wireframe gets `side: "top"`, NEVER `"bottom"`. The leader should never cross the stage to reach a far gutter.
+- A toast in the top-right corner gets `side: "top"` (or `"right"`).
+- A button in the right rail gets `side: "right"`, even if the button is at the bottom of the rail.
+- The KPI footer at the bottom of the wireframe gets `side: "bottom"`.
+
+For row-spanning components (a row of cards · a footer strip · a multi-column row), the dot lands on the outer ROW's edge — humans read that as "this row of components" rather than "this single column". Add `relative` to the outer row wrapper and host the anchor span there.
+
+## Common patterns table
+
+| Component type | Side | Anchor edge |
+|---|---|---|
+| Sidebar (column on left edge of stage) | left | left |
+| Inbox / case list (column to right of sidebar) | left | left (so dot is at the column's left boundary, not buried inside) |
+| Right rail (column on right edge of stage) | right | left or right (whichever is the gutter side) |
+| Topbar | top | bottom or top |
+| Slide-down banner at top of stage | top | top |
+| Top-right corner toast | top | top |
+| KPI footer | bottom | bottom |
+| Channel-cards row | right | right |
+| Multi-column row (announcements + wrap-ups + recent) | right | right of the OUTER row wrapper |
+| Modal centred on screen | left or right | the matching edge of the modal |
+| Slide-in sheet flush against wireframe right | right | left (so the leader has visible travel through the sheet) |
+| Single in-row cell (e.g. table column header on left side of a wide row) | left | matching edge of the cell |
+
+## Anchor placement quick reference
+
+Where to put the `<span id="..." className="absolute ..." />` based on what edge you want the dot on:
+
+| Span position | Dot lands at | Use case |
+|---|---|---|
+| `right-0 top-1/2` | Right edge, vertical centre | Right-side callout pointing into the parent's right edge |
+| `left-0 top-1/2` | Left edge, vertical centre | Left-side callout |
+| `left-1/2 top-0` | Top edge, horizontal centre | Top-side callout (banner, topbar) |
+| `left-1/2 bottom-0` | Bottom edge, horizontal centre | Bottom-side callout (KPI footer, button at bottom of section) |
+
+For row-spanning callouts: put the span at `right-0 top-1/2` of the OUTER row wrapper (which is `relative`), not inside an inner cell.
+
+## Stage geometry (the magic numbers)
+
+| Knob | Value | Notes |
+|---|---|---|
+| Stage design size | 1920 × 1080 | Fixed; everything scales from this |
+| Outer container max-width | 2400 px | Allows 1:1 scale on wide monitors |
+| Stage container maxWidth | 1920 px | Caps scale = 1.0 |
+| Gutter (each side) | 320 px | Hard constraint: ≥ label_width + offset + slack |
+| Top/bottom callout offset | 60 px | Distance from stage edge to dot |
+| Top padding above stage | mt-32 = 128 px | Tab-bar clearance |
+| Label width | 230 px | Fits ~2 lines of 12px text |
+| Label height (estimated) | ~32 px | Two-line labels render up to ~45px |
+
+The interlocking constraints:
+- `gutter ≥ label_width + offset` — must hold or labels clip past viewport edge
+- `top_padding ≥ tab_bar_height + label_height + buffer` — must hold or top labels hide behind tab bar
+- Outer max-width should be ≥ stage_width + 2 × gutter — so on max-width monitor, no compression
+
+## When NOT to add a callout
+
+- Pure flow views (`agent-flow`, `sup-flow`) — the layout itself is the explanation.
+- A second callout pointing at the same `id` as another callout in the same view — one is enough; duplicate IDs produce two leaders into the same dot.
+- An element whose function is obvious from its on-screen label.
+
+## Iteration history (where these rules came from)
+
+The rules above didn't come out of one design pass. They came from a 7-iteration loop with a real user reviewing real outputs:
+
+1. **i1**: Initial build of 14 wireframe states. Naive callouts.
+2. **i2**: Removed duplicate-anchor entries (S4/S6 had two callouts targeting same id), routed flow tabs more cleanly, added 3 interactive demo tabs.
+3. **i3**: User said "page is too small, tabs cut off, need column callouts". Stage gutters expanded, tab bar wraps, callout density bumped to 5–8/state. **Rule 4 flipped from "less is more" to "comprehensive".**
+4. **i4**: Playwright-verified everything. Bug found: tab bar covered top callouts (it was `sticky`). Removed sticky, bumped gutter further, added top padding. **Rule 7 v1 added: "edge nearest the gutter wins".**
+5. **i5a–b**: Sidebar + Inbox leaders moved to left edge of column. KPI footer leader moved to bottom border. Announcements anchor moved to outer row wrapper. **Edge-nearest-gutter became universal.**
+6. **i5c**: Per-step demo callouts wired up. App-level dynamicCallouts state. Race condition discovered (parent reset useEffect overrides child mount push) → fixed via cleanup-on-unmount.
+7. **i5d**: User pointed out banner callouts were going to the FAR gutter. **Rule 7 generalized: closest path wins for `side` AND `anchor`.**
+
+Each iteration came with browser-rendered evidence. If a rule above feels arbitrary, it isn't — it's the answer to a real bug.

package/skills/concept-slides/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: concept-slides
+description: "Use to produce a marp slide deck that captures a product or feature concept at low fidelity — hook, concept overview, visual sketches, user journey, what's deferred. Iterate with the user before any wireframing or prototyping. The deck is the lowest-fidelity artifact in the pipeline; it answers 'are we building the right thing?' before fidelity escalates."
+---
+
+# Concept Slides
+
+## Overview
+
+A concept deck is the cheapest artifact in the pipeline. It exists to verify the WHAT before the team commits to the HOW. The deck has hook + 3-5 sub-concepts + visual sketches + user journey + explicit deferrals. That's it. If the user can't react to a 5-15 slide deck, they can't react to a wireframe either — start here.
+
+**Core principle:** low fidelity is the feature. The deck is meant to be edited, rejected, redirected. It should take an hour or two of dispatched work to produce, not a day. Match that ambition: short, sharp, sketch-grade.
+
+**Announce at start:** "I'm using the concept-slides skill to produce a marp deck for [concept]."
+
+## When to Use
+
+- Phase 2 of a prototype-driven flow (after discovery, before wireframing)
+- For `/feature` on existing apps: a 1-3 slide mini-deck — what the feature is, where it sits, the visual sketch. Often a single slide.
+- Ad-hoc when a user wants to put a concept on paper before building anything
+
+**Do NOT skip when:**
+- The concept "feels obvious" — obvious concepts still benefit from a sketch the user can react to. Skipping the deck is how scope creep starts.
+- The user is in a hurry — the deck is the cheap artifact; resist the temptation to skip to wireframes
+
+**Do NOT use this skill for:**
+- Marketing decks, sales pitches, finalized presentations (use the underlying `marp-slides` skill directly with full-fidelity intent)
+- Replacing the wireframe — the deck has visual sketches, NOT a UI specification. The wireframe comes next.
+- Replacing requirements documentation — the deck is a starting artifact; the spec emerges through iteration
+
+## What concept-slides produces
+
+A single marp deck at `decks/{name}/slides.md` that conforms to:
+
+| Slide | Purpose | Length |
+|---|---|---|
+| 1. Hook | The question the product/feature answers | 1 slide; one sentence |
+| 2. Concept overview | 3-5 sub-concepts, one per slide; each with one-sentence description + tiny visual | 3-5 slides |
+| 3. Visual sketches | Per concept, low-fidelity sketches (HTML/SVG embedded in marp; NOT full UI mockups) | 2-4 slides |
+| 4. User journey | The flow at low fidelity — boxes, arrows, named steps | 1-2 slides |
+| 5. Out of scope | Explicit deferrals; what this concept is NOT | 1 slide |
+
+Total target: 8-15 slides for a full product concept; 1-3 slides for a `/feature` concept on an existing app.
+
+The deck is rendered with `marp` and previewed in HTML so the user can click through. Iteration takes 1-3 cycles for full products, often 1 for features.
+
+## What concept-slides does NOT produce
+
+- A wireframe (Phase 3 deliverable; uses `build-wireframe` skill)
+- A prototype (Phase 4 deliverable; uses `build-prototype` skill)
+- An architecture doc (Phase 5 deliverable; uses `harden`)
+- A finalized pitch deck (use `marp-slides` directly for finalized presentations)
+
+If the user asks for "a real deck for the leadership pitch," use `marp-slides` with full presentation intent — concept-slides is intentionally low-fidelity.
+
+## Inputs
+
+| Source | Required | Purpose |
+|---|---|---|
+| Rough concept brief from the user | yes | One-sentence to one-paragraph description of what's being built |
+| Discovery output (if existing repo) | if Phase 1 ran | Codebase conventions, existing UX patterns to align with |
+| Reference decks the user likes | optional | Style/composition reference (links or paths) |
+
+## Process
+
+### Step 0: orient
+
+Read:
+- `~/.claude/skills/marp-slides/SKILL.md` — the marp engine and its rendering rules
+- 2-3 example decks in `~/.claude/skills/marp-slides/examples/` matching the concept's style (overview decks, journey decks, sketch-style decks)
+- The user's brief
+
+If no brief is provided, ask the user 1-3 clarifying questions and stop until answered. Do not invent the concept.
+
+### Step 1: dispatch the concept-designer subagent
+
+The deck content (slide drafts, visual sketches, user-journey diagrams) is synthesized by the `concept-designer` subagent in its own context window. The main session aggregates the result and writes the file.
+
+Dispatch with:
+- The user's brief
+- Discovery output if available
+- Reference deck paths if any
+- Target output path (`decks/{name}/slides.md`)
+
+The subagent returns slide-by-slide content, with sketch markup inline (HTML/SVG that renders in marp).
+
+### Step 2: write the deck file
+
+Write the deck to `decks/{name}/slides.md` using the marp frontmatter the subagent returned. Common frontmatter:
+
+```yaml
+---
+marp: true
+theme: default
+paginate: true
+size: 16:9
+---
+```
+
+### Step 3: render and present
+
+Render with marp:
+
+```bash
+npx @marp-team/marp-cli decks/{name}/slides.md --html --output decks/{name}/slides.html
+```
+
+Open `decks/{name}/slides.html` in the user's browser. The user clicks through and gives feedback.
+
+### Step 4: iterate
+
+User feedback drives revisions:
+- Concept missing → add a slide
+- Concept off → revise the description and sketch
+- Visual sketch wrong → redraw
+- Journey wrong → reorder steps or simplify
+
+Re-dispatch the subagent with the feedback as part of the prompt; rewrite the deck; re-render. 1-3 iterations is typical.
+
+### Step 5: lock
+
+When the user emits "concept locked" (or equivalent), the phase closes. The locked deck is the input to Phase 3 (`build-wireframe`).
+
+Update the manifest at `.forge/work/{type}/{name}/manifest.yaml`:
+- `artifacts.concept.deck_path: decks/{name}/slides.md`
+- `artifacts.concept.locked_at: <ISO-8601 timestamp>`
+
+Presence of `artifacts.concept.locked_at` is the lock signal that Phase 3 (`build-wireframe`) reads to confirm the concept is locked before proceeding.
+
+## Visual sketch guidance
+
+Sketches inside marp slides use HTML/SVG inline. Keep them low-fidelity:
+
+- Boxes, arrows, named regions — NOT pixel-perfect mockups
+- Fonts: system; colors: 2-3 max; no shadows / gradients / animations
+- One concept per sketch; if you need multiple sketches per slide, you have multiple concepts (split slides)
+
+Avoid:
+- Full UI mockups (that's the wireframe's job)
+- Detailed icons (the wireframe will have lucide-react; the deck has emoji or simple shapes)
+- Real data (use placeholders like "ITEM 1", "USER A")
+- Click interactions (the deck is static; the wireframe handles interactivity)
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Treating the deck as a finalized pitch | It's a draft; lower the polish bar to "sketch-grade" |
+| Embedding real UI mockups | Move that to Phase 3 wireframe; sketches in the deck are boxes-and-arrows |
+| Producing a 30-slide deck | Cap at 15 for full products, 3 for features. Cut or split. |
+| Skipping the "out of scope" slide | The deferral list IS the spec — what NOT to build is as important as what to build |
+| Iterating with the user before the first render | Render first, get feedback against something concrete; don't iterate against imagined slides |
+| Inventing concepts the user didn't ask for | Ask 1-3 clarifying questions instead; do not synthesize beyond the brief |
+
+## Red Flags
+
+**Never:**
+- Build a polished marketing deck under this skill (different intent — use `marp-slides` directly)
+- Skip the "out of scope" slide — defining what's NOT built is half the value
+- Iterate without rendering — text-only edits invite imaginary feedback
+- Carry a draft to Phase 3 without an explicit user lock
+
+**Always:**
+- Render to HTML and let the user click through — that's the iteration surface
+- Cap iterations at 3 for full products; surface "are we converging?" on iteration 4
+- Update the manifest at lock — the deck path becomes input to wireframe + prototype phases
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | User brief, target output path, optional discovery output |
+| **Produces** | `decks/{name}/slides.md` (marp source) + `decks/{name}/slides.html` (rendered preview) |
+| **Updates manifest** | `artifacts.concept.{deck_path, locked_at}` |
+| **Feeds into** | `build-wireframe` (Phase 3 — wireframe extends the visual sketches into clickable HTML) |
+
+## Integration
+
+| Caller | When |
+|---|---|
+| Phase 2 of `/feature` and `/greenfield` | Default flow entry point for prototype-driven work |
+| Manual invocation | When a concept needs sketching outside a workflow |
+
+| Dispatches | For |
+|---|---|
+| `concept-designer` subagent | Slide content synthesis in own context window |
+
+| Pairs with | For |
+|---|---|
+| `marp-slides` (user-level skill) | Underlying rendering engine — concept-slides specializes the format |
+| `build-wireframe` | Phase 3 successor — wireframer reads the locked deck as input |
+| `discover-codebase-analysis` | If existing repo, supplies UX/convention context |