octocode-cli 1.3.1 → 1.5.1

package/skills/octocode-slides/references/02-research.md

@@ -0,0 +1,149 @@
+# Phase 2 — Research
+
+**Role:** Research agent. Fill the gaps identified in `request.md` with sourced evidence — facts, code, context, comparisons, quotes, and data.
+
+**Input:** `.content/request.md`
+**Output:** Findings appended to `.content/request.md` under the `<!-- Phase 2 -->` separator
+
+---
+
+## Skip gate — read first
+
+Open `.content/request.md`. If **all** of the following are true, skip to the append step and write "None needed":
+- "Known gaps" section says "None"
+- User source files cover all key facts
+- User said "skip research", "quick deck", or "no research needed"
+
+Otherwise continue.
+
+---
+
+## Step 1 · Extract the research agenda
+
+From `request.md`, identify:
+- **Known gaps** (explicitly listed)
+- **Depth level** — determines what kind of evidence to prioritise
+
+| Depth level | Prioritise finding |
+|-------------|-------------------|
+| Executive | Business outcomes, risk statements, ROI data, market stats |
+| Management | Trade-off comparisons, feasibility evidence, progress signals |
+| Technical | Working code, benchmarks, architecture diagrams, failure modes |
+| Mixed | One strong narrative hook + technical proof in separate sections |
+| Async | Self-explanatory charts, step-by-step flows, full context |
+
+Only research what is needed to fill the gaps. Do not do exhaustive research for slides whose content is already in the source files.
+
+---
+
+## Step 2 · Deep-read source files (if not done in Phase 1)
+
+If source files were listed in `request.md` but not yet fully read, go deeper now. Use the same tool routing as Phase 1 Step 3:
+
+| Source type | Deeper research approach |
+|-------------|-------------------------|
+| Local workspace / folder | `localSearchCode` for key concepts and patterns → `localGetFileContent` on specific files → `lspGotoDefinition` to trace a function to its definition → `lspFindReferences` to see where a type/function is used → `lspCallHierarchy` to trace call chains (for code-flow slides) |
+| GitHub repo | `githubSearchCode` for key API patterns or architecture → `githubGetFileContent` for specific files/sections → `githubSearchPullRequests` for context on design decisions |
+| Package / library | `packageSearch` → check deprecation, repo URL → dive into repo with GitHub tools |
+
+For code repos: search key concepts, trace function call chains with LSP tools, and read 3–5 files that directly support the slide content. Extract: real code patterns (≤20 lines), architecture decisions, API signatures, error handling examples, benchmarks.
+
+Do not read all files indiscriminately — stay focused on what fills the gaps in `request.md → Known gaps`.
+
+---
+
+## Step 3 · Web research
+
+**When:** A gap requires context, data/stats, comparisons, or validation that source files don't cover.
+
+**Skip when:** Source files cover all gaps, or topic is internal/proprietary, or user said "skip research".
+
+Run queries in parallel — pick the types that match the gaps:
+
+| Gap type | Approach |
+|----------|---------|
+| Statistics / data | Primary or official source first; search only when URL is unknown |
+| Best practices | Official docs or known authoritative articles directly |
+| Case studies / examples | Search `"<topic> real-world"`, read original source |
+| Comparisons | Fetch both primary docs; don't rely on second-hand summaries |
+| Definitions | Official spec or standard directly |
+
+For each finding: record the exact URL and which slide it will support.
+
+**Ask the user only if:** a critical fact is needed and web research returned nothing reliable, and the gap would leave a slide marked `[NEEDS SOURCE]` with no alternative.
+
+---
+
+## Step 4 · Octocode research — external code, repos, and packages
+
+**When:** Deck needs real code samples, API references, real-world architecture patterns, or library usage examples that aren't in the user's source files.
+
+**Tool routing by goal:**
+
+| Goal | Tool chain |
+|------|-----------|
+| Find repos for a topic | `githubSearchCode(match="path", keywords)` → pick 1-2 credible results → `githubViewRepoStructure` → `githubGetFileContent` |
+| Find a code pattern in a known repo | `githubSearchCode(match="file", owner, repo, keywords)` → `githubGetFileContent(matchString=...)` for the relevant section |
+| Research a library / package | `packageSearch(name)` → check repo URL → `githubViewRepoStructure` → read README + key source files |
+| Trace how a function is used | Clone repo locally with `githubCloneRepo` → `localSearchCode` → `lspFindReferences` or `lspCallHierarchy` |
+| Find real-world examples of a pattern | `githubSearchCode(match="file", keywords=["pattern", "example"])` across GitHub |
+
+**Code quality criteria — feature only code that is:**
+- From a credible, maintained repo (known org, recent commits, reasonable star count)
+- Short enough to read on a slide (≤20 lines; trim setup/imports unless they're the point)
+- Directly illustrating the claim in the slide title — not surrounding scaffolding
+- Real, not paraphrased or invented from memory
+
+Record each code snippet with its exact source URL and line range in the `Code to feature` section (Step 5).
+
+---
+
+## Step 5 · Append findings to request.md
+
+Append the findings block below the `<!-- Phase 2 -->` separator in `.content/request.md`. Do not create a new file.
+
+```markdown
+## Research findings
+
+### From local workspace
+{{Key findings from local source files not already captured in Phase 1. Include file path and relevant lines.}}
+| Path:lines | Finding | Supports |
+|------------|---------|---------|
+| {{path:L12-28}} | {{architecture decision / API shape / key pattern}} | {{which slide}} |
+
+### From web
+| URL | Key fact / quote | Supports |
+|-----|-----------------|---------|
+| {{url}} | {{fact}} | {{which part of deck}} |
+
+### From GitHub / external repos
+| Repo | Key finding | Link |
+|------|-------------|------|
+| {{owner/repo}} | {{architecture insight or code pattern}} | {{URL#L}} |
+
+### Code to feature
+\```{{language}}
+// Source: {{full URL with line range, or local path:L12-28}}
+{{snippet — max 20 lines, trimmed to the point}}
+\```
+
+### Facts and data confirmed
+| Claim | Source | Status |
+|-------|--------|--------|
+| {{stat or insight}} | {{URL or path}} | confirmed / assumed |
+
+### Gaps still open
+{{Anything that couldn't be found. If none: "None."}}
+```
+
+---
+
+## Gate 2 — Continue immediately
+
+Research is infrastructure, not a deliverable. Do not ask for approval. Send a one-line note and continue:
+
+```
+Research complete → {{n}} sources · {{n}} code samples · gaps: {{list or "none"}} → building outline
+```
+
+Only stop here if a gap critical to the deck's main claim cannot be filled and only the user can resolve it. State the specific gap and ask one targeted question.

package/skills/octocode-slides/references/03-outline.md

@@ -0,0 +1,172 @@
+# Phase 3 — Outline
+
+**Role:** Information architect. You turn research into the smallest narrative structure that achieves the user's goal — choosing slide order, types, and content balance for the audience.
+
+**Input:** `.content/request.md`
+**Output:** `.content/outline.md`
+
+---
+
+## Step 1 · Read inputs
+
+Read both now (in parallel):
+- `.content/request.md` — audience, goal, tone, slide count, source content, research findings, gaps
+- `references/slide-rules.md` — master rule set for content, narrative, layout, and anti-patterns (required by Global Rule 9)
+
+---
+
+## Step 2 · Calibrate to audience depth
+
+Translate the brief's audience profile into slide-level constraints using `references/slide-rules.md` §0 (Audience & Depth).
+
+| From brief | Resolve to |
+|-----------|------------|
+| Audience expertise | Expert / Practitioner / Informed / General |
+| Depth level | Executive · Management · Technical · Mixed · Async |
+| Evidence type needed | Business outcomes · Code · Before/after · Timeline |
+| Target slide count | Cross-check against depth ranges in §0.5 |
+
+Take a moment before continuing — the answer here governs every later decision in this phase, including which material to cut. Write one sentence:
+
+> *"Depth: {{level}} — this means {{slide style implications}}."*
+
+If the audience is mixed or the brief is ambiguous, decide who the deck is *primarily* for and design for them; secondary audiences get appendix slides. Don't try to satisfy every viewer at full depth — that's how decks turn into documents.
+
+---
+
+## Step 3 · Choose the narrative arc
+
+Before writing any slides, decide how the deck should move:
+
+| Arc | When to use |
+|-----|-------------|
+| **Problem → Solution** | Pitches, proposals, product launches |
+| **Context → Insight → Action** | Executive updates, business reviews |
+| **Concept → Examples → Practice** | Technical talks, tutorials, onboarding |
+| **Before → After → How** | Case studies, retrospectives, migrations |
+| **Now → Future → Path** | Strategy decks, roadmaps, vision talks |
+
+Write one sentence naming the arc and why it fits the audience + goal.
+
+---
+
+## Step 4 · Select slide types
+
+For each idea from research, pick the type that makes the point legible in 3 seconds without the presenter speaking. **Type is a design decision, not a format choice.**
+
+The full type → use-case table lives in `SKILL.md → Visual Type Decision`. Read it once, then return here.
+
+**Two judgement calls only this phase makes:**
+
+- **Vary types as the arc demands.** Three consecutive `content` slides usually means the agent stopped thinking. If it's intentional rhythm (e.g., a teaching sequence), record why; otherwise rework.
+- **For `chart` slides — pick the library now, not in Phase 5.** Add it to the `Key content` column as `chart · {{Library}}` (e.g., `chart · Chart.js`). Decision rules → `references/resources.md → Data Visualization — Library Decision`. Deciding here prevents mis-matched library loads at implementation and flags `[NEEDS SOURCE]` for any chart whose data isn't confirmed.
+
+---
+
+## Step 5 · Draft the outline
+
+Create `.content/outline.md` inside `.octocode/slides/{{slideName}}/`. This file is the complete implementation contract — no per-slide spec files are needed.
+
+```markdown
+# Outline: {{Title}}
+
+**Arc:** {{name}} — {{one sentence justification}}
+**Depth:** {{Executive / Management / Technical / Mixed / Async}} — {{one sentence on what this means for slide style}}
+
+| # | Slug | Title (claim sentence) | Type | Key content | Source | Flow logic |
+|---|------|------------------------|------|-------------|--------|------------|
+| 01 | title | {{Deck title}} | title | Title, subtitle, presenter name | — | Raises: "What is this?" |
+| 02 | agenda | Agenda | agenda | Section list matching arc | — | Raises: "Where do we start?" |
+| 03 | {{slug}} | {{Claim sentence}} | content | {{final bullets · max 5 · ≤10 words each}} | request.md §{{section}} | Answers: {{prior Q}} · Raises: {{next Q}} |
+| … | … | … | … | … | … | … |
+| N | closing | {{CTA sentence}} | closing | Next step, contact, link | — | Answers: "What do I do now?" |
+
+## Slide notes
+
+{{Only add a note for slides that need special treatment — a specific widget, chart config, missing source, or layout instruction. Simple content/stats/code slides need no notes.}}
+
+### {{slug}} — {{title}}
+- **Widget/chart:** {{e.g., "Chart.js donut — data: [42, 31, 27] — labels: [A, B, C] — key: A dominates"}}
+- **Code:** {{e.g., "lines 12–28 of src/auth.ts — show the token validation path"}}
+- **Image:** {{path or "user will provide — placeholder needed"}}
+- **Data source:** {{URL or file — or "[NEEDS SOURCE]"}}
+- **Layout note:** {{anything special: two-col, full-bleed, specific animation}}
+
+### {{slug}} — {{title}}
+...
+```
+
+**Slide type options:**
+`title` · `agenda` · `section` · `content` · `two-col` · `stats` · `quote` · `code` · `chart` · `image` · `timeline` · `comparison` · `closing`
+
+**Guidelines:**
+- Non-structural slide titles (all except `title`, `agenda`, `section`, `closing`) should be **claim sentences** — sentences the audience can repeat without the slide.
+- Source columns point to sections in `request.md` or a user file path. If source support is missing, validate with Octocode/local tools or web research when appropriate; if still unresolved, mark `[NEEDS SOURCE]` and ask the user before making it a confident claim.
+- Slide count should stay within the range in `request.md` (calibrated by depth level in Step 2). If the outline exceeds the upper bound by more than 3, trim slides or explicitly note why the added depth is necessary.
+- Prefer the fewest slides that answer the audience's core question. If two adjacent slides make the same point, merge or cut.
+- Dense content → split the slide rather than shrinking text.
+- Avoid 3 consecutive slides of the same type unless the rhythm is intentional.
+- The opening should hook early — state the problem, opportunity, or striking fact before detailed solution content.
+- The close should land — one clear insight, one action, one next step.
+- **Ghost outline test:** Read the titles alone as a paragraph. They should tell the complete story — argument, evidence, and conclusion — without the body content. If they don't, revise the structure before adding body content.
+- **Question-Answer chain (slide-rules.md §5.1):** Each slide title should answer the implicit question raised by the previous slide and raise the question the next slide answers. Record each in the `Flow logic` column as `Answers: "X" · Raises: "Y"`. **If the chain breaks** (a slide answers a question that was never raised, or raises a question that is never answered): (a) reorder — the misplaced slide likely belongs earlier or later; (b) add a bridge slide if the logical gap is real; (c) cut the slide if it adds no new information to the chain. Never leave a broken chain and ship — a gap in titles means a gap in the audience's understanding.
+- **Data needs context:** each `chart`, `stats`, or `code` slide should have a context slide before or after it that states what the data means.
+- **Appendix slides** go after `closing`, are labeled `[APPENDIX]`, and do not count against the target slide count.
+
+---
+
+## Step 5b · Bidirectional validation
+
+Before Gate 3, run the bidirectional + three-lens check defined in `SKILL.md → Bidirectional Slide Planning`. Apply it to *this* outline:
+
+- **Top-down (row 1 → N):** Does the opening hook create discomfort before slide 3? Each section follow logically? Ghost outline test pass — reading titles alone tells the complete story?
+- **Bottom-up (row N → 1):** Does the closing CTA trace back to the opening problem? Each slide's claim support its section? Every `[NEEDS SOURCE]` resolvable, or should the slide be cut / reframed / sent to the user?
+- **Per-slide three-lens** (Content · UX · UI — defined in SKILL.md). Mark any slide failing two or more lenses `[REVISIT]`. Resolve before Phase 5 or ask the user which direction to take.
+
+The lenses are a thinking tool, not a checkbox grade. If a slide fails one lens but the brief explicitly justifies the trade-off (e.g., a known-dense reference slide for an async deck), record the reason inline rather than forcing a rewrite.
+
+---
+
+## Gate 3 — Always show the outline and ask
+
+**Default: always show the outline to the user and wait for feedback before moving to Phase 4.**
+
+The outline determines the entire arc, content, and slide count. Getting it wrong at this stage means rebuilding slides later. Showing it takes 30 seconds; rebuilding takes 30 minutes.
+
+**Run the Think-before-asking protocol first** (`SKILL.md → Think before asking`). Before presenting, complete this reasoning pass internally:
+- What did I know about the audience/goal, and how did it drive the arc choice?
+- What did I assume, and could the user correct it?
+- Are any beats missing or any slides weak in the chain?
+
+**Run the storytelling arc check:**
+
+| Beat | Required slide | Present? |
+|------|---------------|----------|
+| **Discomfort** | A slide that surfaces a real problem — before any solution | Slide #__ or `[MISSING]` |
+| **Relief** | A slide that reframes the problem or names the insight | Slide #__ or `[MISSING]` |
+| **Confidence** | Evidence slide — numbers, code, outcome — that proves the solution works | Slide #__ or `[MISSING]` |
+| **Momentum** | Closing CTA — one specific action the audience can take now | Slide #__ or `[MISSING]` |
+
+Any `[MISSING]` beat = structurally incomplete. Add the beat, merge it into an adjacent slide, or ask the user whether it is out of scope.
+
+**Then show the user** using the `SKILL.md → Presenting options to the user` format — reasoning first, choices second:
+
+```
+Outline ready — "{{title}}" · {{N}} slides · {{arc}} arc
+
+Why this arc: {{1-2 sentences — how audience + goal drove this structure}}
+Assumptions: {{list or "none — all confirmed"}}
+
+Story beats: Discomfort (#__) · Relief (#__) · Confidence (#__) · Momentum (#__)
+
+{{Paste full outline table}}
+
+Slides needing attention:
+{{List only [NEEDS SOURCE] or special-treatment slides — or "none"}}
+
+Reply "good" to move to design — or describe what to change.
+```
+
+**Exception — fast mode:** If the user said "your call", "just build it", or "fast mode", send a compact one-line summary ("Outline: {{N}} slides, {{arc}} arc — starting design") and continue without waiting.
+
+Update `.content/outline.md` with any changes before proceeding to Phase 4. Resolve all `[NEEDS SOURCE]` gaps before implementation or clearly flag them for the user.

package/skills/octocode-slides/references/04-design.md

@@ -0,0 +1,301 @@
+# Phase 4 — Design
+
+**Role:** Visual designer. You create a fitting visual identity for this specific deck through deliberate choices grounded in the brief. Be distinctive where it matters, but do not create design process overhead when the goal is speed.
+
+**Input:** `.content/request.md` · `.content/outline.md`
+**Output:** `.content/DESIGN.md` · `css/base.css` · `css/theme.css`
+
+> **Design gate (default: ask).** Show the user 3 design directions and wait for a choice before writing CSS. Skip when the user explicitly delegates ("fast mode", "your call", "just build it") or a brand guide is locked. Complete the Design Reasoning Chain (between Step 2 and Step 3 below) before any aesthetic choice — short-circuiting it is how decks end up looking like generic templates.
+
+---
+
+## Step 1 · Read design references
+
+Read now (in parallel):
+- `references/design-system.md` — CSS variable contract, design process, anti-slop guide, resources
+- `references/resources.md` — CDN libraries, font catalogs, color tools, inspiration sources
+- `references/wireframes.md` — general slide layout examples for content, images, stats, charts, quotes, code, timelines, and closing slides
+- `references/slide-rules.md` §§2–3 — Visual/Design rules and Layout rules (required by Global Rule 9)
+- `.content/outline.md` — slide list with inline notes from Phase 3; use Slide notes for special design treatment per slide
+
+---
+
+## Step 2 · Map explicit and implied images
+
+Read `request.md` → Images section and `.content/outline.md` → Slide notes. Map both:
+- **Explicit images** the user already mentioned.
+- **Implied images** the design would benefit from, such as title hero art, product screenshots, portraits, diagrams, object photos, or any visual used to describe something.
+
+Do **not** invent, search for, download, or generate missing images during design. If the image is not already provided, create a `PLACEHOLDER` entry and let the user add the real image later.
+
+| Decision | What to record |
+|----------|----------------|
+| Is the image file ready? | `ready` → use `<img src="{{path}}">` directly in Phase 5 |
+| Is the image "user will provide"? | `placeholder` → use the `PLACEHOLDER` component: `image-ph` / `image-ph-bleed` from `references/html-templates.md` |
+| Did design identify a needed image that the user did not provide? | `placeholder` → record the expected image in plain English and ask the user to provide it later |
+| Full-bleed or inline? | Full-bleed → `slide--image` type; inline → `image-ph` inside `content` or `two-col` |
+| Does image require text overlay? | Add `image-overlay` gradient div when needed to keep text legible on full-bleed slides |
+
+Record as a table in `DESIGN.md` → Layout notes. Also update each affected slide's inline notes in `outline.md` (`Images` and `UX / UI`). Leave placeholder slides marked with `[IMAGE PLACEHOLDER]` in the outline so Phase 5 knows to use the placeholder template.
+
+For every placeholder, include:
+- Slide slug or number.
+- Placement: `inline` or `full-bleed`.
+- Expected image description, e.g. "PLACEHOLDER: product screenshot showing the dashboard".
+- User question, e.g. "Please provide the dashboard screenshot for slide 03, or keep the placeholder."
+
+If no explicit or implied images are needed: record `Images: none` in `DESIGN.md` and continue.
+
+---
+
+## Design Reasoning Chain — complete this before any aesthetic decision
+
+Every design choice must trace back to the audience and goal. Work through these six questions in order. Write 1–2 sentence answers for each in `DESIGN.md → Visual identity`. Never skip this chain to jump to "looks cool."
+
+| Step | Question | What a strong answer sounds like |
+|------|----------|----------------------------------|
+| 1 · Audience signal | Who is in the room and what do they trust? | "Developers who distrust vague claims → high contrast, code-native fonts, specific numbers." |
+| 2 · Energy | Dark (focused, projector) or Light (readable, print)? | "Stage / conference room → dark background dominant." |
+| 3 · Temperature | Warm, cool, or neutral? | "AI/infrastructure topic → cool (blues, slates) signals precision." |
+| 4 · Personality | What emotion should the first slide trigger? | "Trust and momentum — not excitement, not fear." |
+| 5 · Differentiation | What does the competition look like, and what should this NOT look like? | "Generic startup decks use cyan+magenta on black → avoid, use slate+amber instead." |
+| 6 · Constraint | Is there a brand guide, color palette, or font stack locked by the user? | "No guide provided → full design latitude." |
+
+**Only after completing this chain:** pick colors, pick fonts, pick layouts, pick libraries. Every pick should have a one-line reason that points back to a step above.
+
+---
+
+## Step 3 · Review per-slide design needs
+
+Before writing CSS, check `outline.md → Slide notes` for any slide whose visual treatment is not obvious.
+
+For each slide with special treatment in `Slide notes`, confirm:
+
+| Section | What Phase 4 should add or confirm |
+|---------|----------------------------------|
+| `Content` | Final on-slide text is short enough for the chosen layout; flag overloaded copy before implementation |
+| `Data` | Exact values, units, source, and intended visual encoding for any metric or chart |
+| `Widgets` | Component choice and library, e.g. Motion counter, code block, Mermaid diagram, callout, progress bar |
+| `Graphs` | Chart type, library, data mapping, labels, key insight, source |
+| `Images` | File path or placeholder, alt text, crop/framing, overlay, caption |
+| `UX / UI` | Layout type, dominant visual, reading order, density, animation, accessibility/contrast |
+
+If a design review reveals a slide is overloaded, add a split note in `outline.md → Slide notes` and flag it for Phase 5.
+
+---
+
+## Step 4 · Research visual direction (skip if brand_guide: locked)
+
+Do this when the brief asks for a custom aesthetic, the topic benefits from visual research, or the direction is not obvious. Skip deep visual research when a brand guide is locked, the user delegated choices, or the design-system matrix clearly matches the goal.
+
+When research is useful, run at least 2 of these in parallel based on your analysis and the tools available in the current agent environment:
+
+```
+Open or search Dribbble for "{{mood}} presentation"
+Open or search Behance for "{{context}} presentation"
+Search GitHub/Octocode for "HTML presentation CSS theme {{aesthetic}}"
+Open or search Awwwards for "{{aesthetic}}"
+Open Fontshare for distinctive display fonts
+```
+
+Extract: color pairings, font personalities, layout patterns, spacing rhythms.
+Take notes — don't copy. The goal is direction, not theft.
+
+For fonts: pick a heading/body pair from `design-system.md` → Font Pairing Presets, OR find something new via Google Fonts / Fontshare. Guideline: the heading font should have enough personality to feel chosen, not defaulted.
+
+Fallback if these tools are unavailable: use available web search/browser tools, official font catalogs, local examples, or the curated palettes and font pairings in `design-system.md`.
+
+---
+
+## Step 5 · Generate style previews
+
+**Default:** generate three previews and ask the user to choose before writing CSS. Design is subjective — an agent that silently auto-selects colors and fonts produces a deck the user hates often enough that 3 minutes of previews beats 30 minutes of rebuilds.
+
+**Skip previews and auto-select when:**
+- User explicitly said "fast mode", "your call", "just build it", or "skip design"
+- A `brand_guide: locked` entry exists in `request.md`
+- The user already approved a specific theme in this conversation
+- The brief is so specific (e.g., "match this exact reference") that previews would only delay confirmation
+
+When skipping, write `> Auto-selected: {{theme}} — {{one-line reason}}` at the top of `DESIGN.md` so the choice is visible.
+
+When previews are needed, write exactly three standalone HTML files — each a different visual direction:
+- `.content/preview-a.html`
+- `.content/preview-b.html`
+- `.content/preview-c.html`
+
+Each preview shows **the title slide only**, fully rendered: color palette, font pair, heading hierarchy, spacing, one accent element. Must look great when opened in a browser.
+
+**Rules for the three previews:**
+- Each should have a **distinct visual direction** — not just the same layout with a different accent color
+- Prefer a mix of dark and light backgrounds when that helps the user choose
+- None may copy color values verbatim from `design-system.md` themes
+- None may score 2+ on the Visual Slop Test, and none may fail the Content Slop Test (from SKILL.md)
+- If the title slide would benefit from a hero image that is not provided, render the `PLACEHOLDER` component in the preview and label what image the user should add later.
+
+**Run the Think-before-asking protocol first** (`SKILL.md → Think before asking`). Before presenting previews, complete this reasoning pass internally:
+- What audience/goal signals drove the three direction choices?
+- Which direction is most likely right, and why?
+- What assumption could the user correct that would change the direction?
+
+Show the user using the `SKILL.md → Presenting options to the user` format — reasoning first, choices second:
+
+```
+Three style directions for "{{title}}" — built for {{audience}} × {{goal}}:
+
+Why these three: {{1-2 sentences on what drove the visual directions — audience trust signals, energy, differentiation}}
+
+A → .content/preview-a.html — {{8-word descriptor tied to audience signal}}
+B → .content/preview-b.html — {{8-word descriptor tied to a different signal}}
+C → .content/preview-c.html — {{8-word descriptor — most distinct from A and B}}
+
+Open them and reply "A", "B", or "C" — or describe what to adjust.
+```
+
+**Gate 4a — Smart stop.** Stop for a choice only when previews were generated. Write DESIGN.md after the user picks a direction or delegates the choice.
+
+**If the user rejects all three previews:** Ask for one concrete direction change ("darker", "more minimal", "warmer colors", "different font personality") and generate one revised preview incorporating that direction. Repeat Gate 4a. Generate 3 new previews only when the user explicitly requests it.
+
+**If `brief.md` has `brand_guide: locked`:** SKIP Steps 4–5 (research and style previews). Still do Step 2 (image mapping) and Step 3 (context analysis). Read the brand values from the brief, map them directly to DESIGN.md tokens, and proceed to Step 6.
+
+---
+
+## Step 5b · Pointer & click feedback (default: off — opt-in)
+
+A subtle layer of pointer chrome — custom cursor + mouse-down spark — makes the deck feel like a live console. **Default: off.** Enable only when the brief explicitly signals a live context.
+
+**Enable when** the user says "live presentation", "demo mode", or "add cursor effects", OR the brief explicitly calls for a live talk, demo, or dark/tech theme.
+
+**Leave off when:**
+- The brief is async/silent, print/PDF-first, or the presentation context is unspecified
+- Audience profile is `Executive` print-readers or accessibility-first contexts
+- Brand guide forbids non-OS cursor behaviour
+- User explicitly opts out ("no custom cursor", "default cursor only")
+- Running in fast mode with no live-context signal in the brief
+
+When kept, list the two libraries in `DESIGN.md → Libraries` (see `references/resources.md → Pointer & Click Feedback` for full URLs and theme bindings) and add the `## Pointer & click feedback` block to `DESIGN.md`. Implementation wiring belongs in Phase 5 — design only declares intent + tokens.
+
+When not enabled, write `Pointer chrome: off` in `DESIGN.md → Libraries` with a one-line reason (or omit the section entirely if the deck has no live context).
+
+---
+
+## Step 6 · Write DESIGN.md
+
+Write `.content/DESIGN.md` inside `.octocode/slides/{{slideName}}/`. Keep it short and actionable. Every decision should explain the WHY, not just the WHAT.
+
+```markdown
+# DESIGN.md — {{Deck Title}}
+
+> Visual system for this presentation. All CSS values come from this document.
+
+## Visual identity
+
+**Mood:** {{Two sentences — how it feels and what it communicates to this audience}}
+**Inspiration:** {{What informed the choices — describe the source, include URLs if from research}}
+**Distinctive choice:** {{The one design decision that sets this deck apart from a generic template}}
+
+## Color system
+
+| Token | Value | Role |
+|-------|-------|------|
+| `--bg` | `{{hex or oklch}}` | Slide background |
+| `--surface` | `{{}}` | Card / panel backgrounds |
+| `--border` | `{{}}` | Dividers, code block edges |
+| `--accent` | `{{}}` | One focal element per slide |
+| `--text` | `{{}}` | Body text |
+| `--muted` | `{{}}` | Captions, metadata, labels |
+| `--code-bg` | `{{}}` | Code block background |
+| `--code-text` | `{{}}` | Code block text |
+
+Contrast: `--text` vs `--bg` = {{ratio}} · Must be ≥ 4.5:1 WCAG AA
+
+## Typography
+
+| Token | Font | Weight | Use |
+|-------|------|--------|-----|
+| `--font-head` | {{Google/Fontshare name}} | 700 | Slide headings |
+| `--font-body` | {{Google/Fontshare name}} | 400/500 | Body text, bullets |
+| `--font-mono` | {{Font}} | 400 | Code blocks |
+
+Google Fonts `@import` URL: `{{full URL}}`
+
+Type scale (all clamp — no raw px or rem on text):
+- `--t-display`: `{{clamp(Xrem, Yvw, Zrem)}}` — title slides only
+- `--t-title`:   `{{clamp(...)}}` — slide headings
+- `--t-sub`:     `{{clamp(...)}}` — subtitles, column headings
+- `--t-body`:    `{{clamp(...)}}` — bullets, paragraphs
+- `--t-small`:   `{{clamp(...)}}` — captions, metadata
+
+## Layout notes
+
+List only slides that need special design attention. All slide-level notes live in `.content/outline.md → Slide notes`.
+
+| Slide | Special treatment |
+|-------|------------------|
+| {{01-title}} | {{Full-bleed? Background image? Specific layout?}} |
+| {{NN-chart}} | {{Chart.js? SVG? Color mapping?}} |
+
+## Animation approach
+
+- Simple entrances: CSS `.fade-in` / `.slide-up` from `base.css`
+- Sequences / stagger / counters: Motion (motion.dev) on slides: {{list or "none"}}
+- `@media (prefers-reduced-motion: reduce)` respected in every animated slide
+
+## Pointer & click feedback
+
+Default: OFF. Include this section only when enabled (see Step 5b). Add a one-line reason when enabled: which brief signal triggered the opt-in.
+
+| Element | Behaviour | Token |
+|---------|-----------|-------|
+| Custom cursor | Small ring + center dot; ring lags dot ~80 ms for a debugger-feel pointer. Native cursor preserved on form fields, links, and during text selection. | `--accent` ring, `--accent-2` dot |
+| Hover state | Ring scales to 1.6× and shifts to `--accent-strong` over interactive elements (buttons, cards, code panels). | `--accent-strong` |
+| Mouse-down spark | 6-spoke radial spark at click point — short (~320 ms), `cubic-bezier(0.22, 1, 0.36, 1)`. Honours `prefers-reduced-motion: reduce`. | `--accent` (+ optional `--violet` focal ray) |
+| Iframe handoff | Parent (`index.html`) owns one shared overlay so the cursor stays continuous across slide transitions; HUD/progress/counter excluded from spark hits. Disabled in overview mode (`body.overview`). | — |
+
+## Libraries
+
+Only list libraries actually needed. For each: which slide, and why this library over alternatives.
+
+| Library | Slides | Why this library |
+|---------|--------|------------------|
+| {{highlight.js}} | {{05}} | Code slide — real syntax colours, not faked |
+| {{Chart.js}} | {{06}} | Bar/line/donut — lightest option |
+| {{Motion}} | {{01}} | Counter/stagger — CSS alone cannot sequence |
+| {{tholman/cursor-effects}} | parent | Pointer chrome — themable custom cursor that already respects `prefers-reduced-motion` |
+| {{hexagoncircle/click-spark}} | parent | Mouse-down spark — single Web Component themed via `--click-spark-color` |
+
+**Library decision rules:** one chart lib per slide. Full table → `references/resources.md → Data Visualization — Library Decision`. Pointer chrome libs load once on `index.html`, not per-slide. The Libraries table above only needs to list libraries this deck actually uses, with the `Why` column tied back to the audience and content (not just "lightest").
+```
+
+---
+
+## Step 7 · Generate CSS files
+
+1. `css/base.css` at the deck root — **copy `scripts/base.css` verbatim** (`cp scripts/base.css css/base.css`). Never paraphrase.
+2. `css/theme.css` at the deck root — Google Fonts `@import` at top, then override only the variables defined in `:root` of `scripts/base.css` (colors, fonts, type scale `clamp()` ranges) using the exact values from DESIGN.md. Layout rules stay in `base.css`.
+
+---
+
+## Gate 4b — Smart stop
+
+Show this only when user design approval is needed. In fast/delegated mode, send a short update and continue to Phase 5.
+
+Use the `SKILL.md → Presenting options to the user` format — show reasoning before the approval ask:
+
+```
+Design locked — "{{title}}"
+
+Why these choices:
+- Color: {{accent is X — chosen because Y tied to audience signal}}
+- Font: {{X for headings — why it fits this audience; Y for body}}
+- Distinctive: {{the one decision that sets this apart from a generic template}}
+
+Libraries: {{list or "none"}}
+
+Image placeholders: {{list slide slug + expected image — or "none"}}
+{{If any: "Provide these later or reply that placeholders should remain."}}
+
+Reply "good" to start building slides — or describe any changes.
+```
+
+Stop only when approval is required. After approval, or when continuing in delegated mode, delete previews if they exist: `rm .content/preview-*.html`