diff --git a/skills/hyperframes/references/design-picker.md b/skills/hyperframes/references/design-picker.md
index b2fcc44508..0635daea0d 100644
--- a/skills/hyperframes/references/design-picker.md
+++ b/skills/hyperframes/references/design-picker.md
@@ -13,7 +13,7 @@ Before generating options, read these style references — all options must comp
## Building the picker
1. Generate 2-3 visual directions based on the prompt. Each direction needs: name, mood, colors (bg/fg/accent), fonts (headline/body), energy level, and transition style.
-2. Copy [../templates/design-picker.html](../templates/design-picker.html) to the project directory as `.hyperframes/pick-design.html`.
+2. `mkdir -p .hyperframes` then copy [../templates/design-picker.html](../templates/design-picker.html) to `.hyperframes/pick-design.html`.
3. Replace `__ARCHITECTURES_JSON__`, `__PALETTES_JSON__`, and `__TYPEPAIRS_JSON__` with your generated options. The user picks one from each category independently — structure, palette, type pairing, plus theme (dark/light/full palette), corners, density, and depth.
### Architecture data format
@@ -32,9 +32,21 @@ Optionally include `components` (component styling rules) and `dos` (do's and do
**Palette variety:** Always include a mix of light, dark, and tinted backgrounds across the 6 palettes — even for calm/wellness prompts.
+### Example architecture object
+
+```json
+{
+ "name": "Editorial Stack",
+ "description": "Vertical rhythm with large type, pull quotes, and data callouts",
+ "tag": "editorial / longform / narrative",
+ "mood": "Confident, unhurried, typographically driven",
+ "preview_html": "
Overline Label
The Headline Goes Here
Subheading text that introduces the narrative arc of this composition with enough words to fill two lines.
Body paragraph with real sentences. The quick brown fox jumps over the lazy dog. This gives a sense of text density and reading rhythm at the chosen type size.
2.4M
Primary Stat
87%
Secondary Stat
\"A pull quote that captures the key insight of the piece.\"
— Attribution Name
Card Title
Card body text with a different treatment than the main content area.
Accent Card
Second card with a tinted accent treatment for variety.
$ hyperframes render --output video.mp4
Tag OneTag TwoAccent Tag
Data row label1,234
"
+}
+```
+
## Serving and user selection
-4. Serve the file with a simple HTTP server in the background: `cd && python3 -m http.server &`. Then verify: `curl -s -o /dev/null -w "%{http_code}" http://localhost:/.hyperframes/pick-design.html` — only share the link if it returns 200. Do NOT use `npx hyperframes preview` for the picker — it blocks. Do NOT start servers inside subagents — the parent handles serving.
-5. Once the user picks, tell them: "Copy the design.md from the picker and paste it here." The user pastes the markdown back into the conversation. Save it to `design.md` in the project root, then proceed with construction.
+4. Serve the file: `cd && python3 -m http.server 8723 &` (use port 8723 or any unused port above 8000; if the curl check fails, try the next port). Verify: `curl -s -o /dev/null -w "%{http_code}" http://localhost:8723/.hyperframes/pick-design.html` — only share the link if it returns 200. Do NOT use `npx hyperframes preview` for the picker — it blocks. Only start the HTTP server from the main conversation thread. If you are running as a dispatched task or subagent, return the file path and let the caller serve it.
+5. Once the user picks, tell them: "Copy the design.md from the picker and paste it here." The user pastes the markdown back into the conversation. Save it to `design.md` in the project root. After the user pastes, kill the background server: `kill %1` or `kill $(lsof -ti:8723)`. Then proceed with construction.
The design.md format is generated by the picker template — it includes mood, theme, structure, colors, typography, corners, spacing, depth, components, and do's/don'ts based on the user's selections.