stoa-mcp 0.1.2 → 0.1.3

package/README.md

@@ -32,48 +32,60 @@ This creates a `.stoa/` folder with everything Stoa needs:
 ```
 .stoa/
   moodboard/notes.md    ← your design direction (colors, layout, style)
+  moodboard/tokens.json  ← auto-generated machine-readable design tokens
   context.md            ← dependencies, conventions, brand voice
   lessons.md            ← project memory (grows automatically)
   guardrails/           ← rules the AI must follow
   roles/                ← AI personas (Builder, Fixer, Planner)
+  presets/              ← your saved custom style presets
   specs/                ← saved specifications
 ```
 
+Every new project starts with the **Clean** style preset (white, minimal, Linear-style). Every spec you generate will include these design tokens automatically.
+
 ### 2. Set up your moodboard (optional but powerful)
 
-Open the moodboard file:
+Your project already has a working design system. Check it:
 
 ```bash
-stoa edit moodboard
+stoa moodboard
 ```
 
-Replace the template with your design preferences:
+**Want a different style?** Pick a preset:
 
-```markdown
-# Design Direction
-Minimal and dark like Linear
+```bash
+stoa moodboard preset
+```
 
-# Colors
-Primary: #E8C872
-Background: #1A1A1A
-Text: #F5F5F5
+Use arrow keys to browse 4 built-in presets with live previews:
+- **Clean** — White, minimal, Linear/Vercel style
+- **Dark** — Dark background, muted accents, GitHub/Raycast style
+- **Warm** — Cream tones, friendly SaaS feel
+- **Bold** — High contrast, sharp corners, brutalist
 
-# Layout
-Sidebar navigation left, main content right
+Or apply directly: `stoa moodboard preset dark`
 
-# Typography
-Clean sans-serif, large headings
+**Want to customize?** Edit interactively in the terminal:
+
+```bash
+stoa moodboard edit
 ```
 
-That's it. Four lines. Every spec you generate will include these design tokens.
+Walks you through each field (colors, typography, layout) one by one. Press Enter to keep, type a new value to change, or `q` to quit anytime.
 
-**Have a screenshot of a design you like?** Drop it in `.stoa/moodboard/` and run:
+**Have a screenshot of a design you like?** Run:
 
 ```bash
 stoa moodboard describe
 ```
 
-If you have an Anthropic API key, Stoa will analyze the image and write the design system for you. If not, it prints a prompt you can paste into any Claude chat along with your screenshot.
+This opens the moodboard folder in Finder — drop your screenshots in, press Enter. If you have an Anthropic API key, Stoa analyzes the images and writes the design system for you. If not, it prints a prompt you can paste into any Claude chat.
+
+**Save your custom style** for reuse across projects:
+
+```bash
+stoa moodboard save-preset my-brand
+```
 
 ### 3. Refine your idea
 
@@ -185,12 +197,11 @@ Stage 1 will reference your existing files, components, and design system. The s
 
 ## Changing the Design
 
-Update your moodboard, then refine:
+Switch preset, edit interactively, or both:
 
 ```bash
-stoa edit moodboard
-# Change colors, layout, style...
-
+stoa moodboard preset dark       # switch to dark theme
+stoa moodboard edit              # tweak individual values
 stoa refine "Redesign the app to match the updated design system"
 ```
 
@@ -206,6 +217,7 @@ All files in `.stoa/` are optional. Use what you need, ignore what you don't.
 |------|-------------|----------|
 | `moodboard/notes.md` | Design direction: colors, layout, typography | Web apps, UI projects |
 | `moodboard/tokens.json` | Auto-generated machine-readable design values | Generated by `stoa moodboard sync` |
+| `presets/*.json` | Custom saved style presets | Reuse across projects |
 | `context.md` | Dependencies, conventions, brand voice | All projects |
 | `lessons.md` | Past mistakes — auto-grows, prevents repeats | All projects (grows over time) |
 | `guardrails/*.md` | Rules the AI must follow (e.g. "don't delete code") | All projects |
@@ -253,62 +265,190 @@ Every future refine includes past lessons as failure modes to avoid. Your projec
 
 ## CLI Reference
 
+### Setup
+
+```bash
+stoa init
+```
+Creates `.stoa/` in the current directory with the Clean style preset, 5 guardrails, and 3 roles. Run this once per project.
+
+```bash
+stoa edit moodboard          # open moodboard in VS Code/Cursor
+stoa edit context             # open context.md
+stoa edit lessons             # open lessons.md
+```
+Opens files in the best available editor. Detection order: Cursor → VS Code → `$EDITOR` → macOS default → nano.
+
+---
+
+### Moodboard
+
+```bash
+stoa moodboard
+```
+Shows current moodboard status: active style, color count, image count, and available commands.
+
+```bash
+stoa moodboard preset
+```
+**Interactive.** Browse 4 built-in presets (Clean, Dark, Warm, Bold) + any custom presets with arrow keys. Shows a live preview with colors, typography, and references. Press **Enter** to apply, **q** to cancel.
+
+You can also apply directly without the picker:
+```bash
+stoa moodboard preset dark
+```
+
+```bash
+stoa moodboard edit
+```
+**Interactive.** Walks through each field one by one: Design Direction → Colors (each individually) → Typography → Layout → Component Style → References. Press **Enter** to keep current value. Type a new value to replace. Type **q** to quit at any point.
+
+```bash
+stoa moodboard describe
+```
+**Interactive.** Opens the `.stoa/moodboard/` folder in Finder so you can drag screenshots in. Press **Enter** when ready. If you have an API key, Stoa analyzes the images with AI and writes the design system automatically. Without an API key, it prints a prompt you can paste into any Claude chat alongside your screenshot.
+
+```bash
+stoa moodboard sync
+```
+Regenerates `tokens.json` from `notes.md`. Usually happens automatically after preset or edit, but run this if you edited `notes.md` by hand.
+
+```bash
+stoa moodboard save-preset my-brand
+```
+Saves the current moodboard as `.stoa/presets/my-brand.json`. Reusable across projects — shows up in `stoa moodboard preset` picker.
+
+---
+
+### Refine
+
+```bash
+stoa refine "Build a waitlist page with email signup and referral system"
+```
+Runs the 5-stage pipeline. After completion, shows an interactive menu:
+
+| Key | Action | Notes |
+|-----|--------|-------|
+| **b** | Build with Claude Code | Launches Claude Code with the spec |
+| **c** | Copy spec to clipboard | Re-copy (Stage 1 is auto-copied on finish) |
+| **e** | Export as markdown | Writes to `specs/<slug>/spec.md` in project root |
+| **v** | View spec files | Opens spec directory in Finder |
+| **q** | Done | Exits |
+
+**Options:**
 ```bash
-# Setup
-stoa init                        # Create .stoa/ folder with templates
-stoa edit moodboard              # Open moodboard in your editor
-stoa edit context                # Open context.md in your editor
-stoa edit lessons                # Open lessons.md in your editor
-
-# Moodboard
-stoa moodboard sync              # Generate tokens.json from notes.md
-stoa moodboard describe          # AI-analyze screenshots in moodboard/
-stoa moodboard describe --overwrite  # Overwrite existing notes.md
-
-# Refine
-stoa refine "your task"          # Run 5-stage pipeline
-stoa refine "task" --mode api    # Force API mode (needs API key)
-stoa refine "task" --mode clipboard  # Get prompts without AI calls
-
-# Specs
-stoa specs list                  # List all saved specs
-stoa specs show <name>           # View a spec's contents
-# Export (also available as [e] in the post-refine menu)
-# Writes to specs/<slug>/spec.md in your project root
-
-# Scenarios
-stoa scenarios list              # List scenarios for latest spec
+stoa refine "task" --mode api         # Force Anthropic API (needs key)
+stoa refine "task" --mode claude-code # Force Claude Code CLI
+stoa refine "task" --mode clipboard   # Get prompts without AI calls (free)
+stoa refine "task" --role planner     # Use a specific role
+stoa refine "task" --stages clarify,structure  # Run specific stages only
+```
+
+---
+
+### Specs
+
+```bash
+stoa specs list                # List all saved specs with dates and stage count
+stoa specs show <name>         # Print a spec's contents to terminal
+```
+
+Specs are saved in `.stoa/specs/<slug>/` with one markdown file per stage. The `[e]` export writes a combined `spec.md` to the visible `specs/` folder in your project root.
+
+---
+
+### Scenarios
+
+```bash
+stoa scenarios list              # List scenarios for the latest spec
+stoa scenarios list <name>       # List scenarios for a specific spec
 stoa scenarios run               # Walk through scenarios interactively
 stoa scenarios run <name>        # Run scenarios for a specific spec
+```
+
+**Interactive.** Each scenario shows GIVEN (what to set up) and EXPECTED (what to check). Press **y** for pass, **n** for fail, **s** to skip. Shows a summary at the end.
+
+---
+
+### Review
+
+```bash
+stoa review                    # Review the latest spec
+stoa review <name>             # Review a specific spec
+```
+
+**Interactive.** Opens each stage for review. Accept, edit, or skip. After editing, optionally re-runs affected pipeline stages.
+
+---
+
+### Build & Verify
 
-# Guardrails & Roles
-stoa guardrails list             # List active guardrails
-stoa guardrails show <name>      # View a guardrail
-stoa roles list                  # List available roles
-stoa roles show <name>           # View a role
+```bash
+stoa build                     # Build the latest spec with Claude Code
+stoa build <name>              # Build a specific spec
+stoa verify                    # Run blind test verification
+stoa verify <name>             # Verify a specific spec
+```
+
+Build gives you a choice: build all at once or subtask by subtask. Verify runs the scenarios interactively after the build.
+
+---
+
+### Guardrails & Roles
+
+```bash
+stoa guardrails list           # List active guardrails
+stoa guardrails show <name>    # View a guardrail's content
+stoa guardrails add <name>     # Add a new guardrail
+stoa guardrails remove <name>  # Remove a guardrail
+stoa roles list                # List available roles
+stoa roles show <name>         # View a role's content
+stoa roles add <name>          # Add a new role
+stoa roles remove <name>       # Remove a role
+```
+
+Guardrails are rules injected into every refine (e.g. "don't delete existing code"). Roles are AI personas used via `--role` flag.
+
+---
+
+### Config
 
-# Config
-stoa config                      # View current config
+```bash
+stoa config                      # View current settings
 stoa config set apiKey <key>     # Set Anthropic API key
-stoa config set model <model>    # Set model (default: claude-sonnet-4-20250514)
-stoa config set mode <mode>      # Set mode: api, claude-code, clipboard
+stoa config set model <model>    # Set model (default: claude-sonnet-4-6)
+stoa config set mode <mode>      # Set default mode: api, claude-code, clipboard
 ```
 
 ---
 
 ## Execution Modes
 
-Stoa has three ways to run the AI pipeline:
+| Mode | How it works | You need | Cost |
+|------|-------------|----------|------|
+| `api` | Direct Anthropic API call | API key (`stoa config set apiKey`) | ~$0.05/refine |
+| `claude-code` | Pipes to Claude Code CLI | Claude Code installed + subscription | Included in subscription |
+| `clipboard` | Returns prompts — no AI calls | Nothing | Free |
 
-| Mode | How it works | You need |
-|------|-------------|----------|
-| `api` | Direct Anthropic API call | API key (`stoa config set apiKey`) |
-| `claude-code` | Pipes to Claude Code CLI | Claude Code installed + subscription |
-| `clipboard` | Returns prompts — no AI calls | Nothing (free) |
+Stoa auto-detects: API key → `api`, Claude Code in PATH → `claude-code`, otherwise → `clipboard`.
+
+In clipboard mode, Stoa prints each stage's prompt. Paste into any AI chat (Claude, ChatGPT, Cursor) and copy the response back. Same pipeline, just manual.
+
+---
+
+## Keyboard Shortcuts
 
-Stoa auto-detects: if you have an API key it uses `api`, if Claude Code is installed it uses `claude-code`, otherwise `clipboard`.
+All interactive commands support these:
 
-In clipboard mode, Stoa prints each stage's prompt. You paste it into any AI chat (Claude, ChatGPT, Cursor) and copy the response back. Everything works — just manually.
+| Context | Key | Action |
+|---------|-----|--------|
+| Any prompt | `q` / `quit` / `exit` | Cancel and go back |
+| Arrow key menus | `↑` `↓` or `k` `j` | Navigate |
+| Arrow key menus | `Enter` | Select |
+| Arrow key menus | `q` | Cancel |
+| Post-refine menu | `b` `c` `e` `v` `q` | See table above |
+| Scenario runner | `y` `n` `s` | Pass / Fail / Skip |
+| Ctrl+C | Always | Force quit |
 
 ---
 
@@ -327,18 +467,24 @@ Add Stoa as an MCP server in Cursor. Create or edit `.cursor/mcp.json` in your p
 }
 ```
 
-Find the global path with:
-
+Find the global path:
 ```bash
-npm root -g
+echo "$(npm root -g)/stoa-mcp/dist/index.js"
 ```
 
 Then in Cursor's Agent chat:
-
 ```
 Use the refine_task tool with title: "My App" and description: "description of what I want"
 ```
 
+## Use with Claude Code
+
+Stoa works directly with Claude Code. After refining:
+
+1. Press `[b]` in the post-refine menu — launches Claude Code automatically
+2. Or copy the spec and paste it: `claude "Read the spec in .stoa/specs/<name>/ and build it"`
+3. Or use `stoa build` for the full guided experience
+
 ---
 
 ## How It Works
@@ -389,6 +535,12 @@ The spec references existing files by name and says "add to" instead of "rebuild
 - `Fixer` — fixes bugs from failure context
 - `Planner` — breaks down large tasks
 
+**4 Style Presets:**
+- `Clean` — white, minimal, Linear/Vercel (applied by default)
+- `Dark` — dark background, violet accents, GitHub/Raycast
+- `Warm` — cream tones, amber accents, Cal.com/Stripe
+- `Bold` — high contrast, sharp corners, brutalist
+
 ---
 
 ## The Stoa Desktop App
@@ -402,7 +554,7 @@ The CLI is the free version. The full loop lives in the Stoa desktop app:
 - Task hierarchy (parent → subtask → fix task)
 - Dashboard with spec scores across all tasks
 
-**Same pipeline, full GUI.** Coming soon at [stoafactory.com](https://stoafactory.com).
+**Same pipeline, full GUI.** Coming soon at [stoafactory.com](https://stoafactory.dev).
 
 ---
 

package/dist/cli/moodboard-edit.d.ts

@@ -0,0 +1 @@
+export declare function runMoodboardEdit(projectDir: string): Promise<void>;

package/dist/cli/moodboard-edit.js

@@ -0,0 +1,245 @@
+import chalk from "chalk";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { syncMoodboard } from "../storage/moodboard-sync.js";
+function writeln(text = "") {
+    process.stdout.write(text + "\n");
+}
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+function parseMoodboard(notesPath) {
+    const defaults = {
+        designDirection: "",
+        colors: {},
+        layout: "",
+        typography: "",
+        componentStyle: "",
+        references: "",
+    };
+    if (!existsSync(notesPath))
+        return defaults;
+    const raw = readFileSync(notesPath, "utf-8");
+    const sections = {};
+    const parts = raw.split(/^# /m);
+    for (const part of parts) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const newlineIdx = trimmed.indexOf("\n");
+        if (newlineIdx === -1)
+            continue;
+        const heading = trimmed.slice(0, newlineIdx).trim();
+        const body = trimmed.slice(newlineIdx + 1).replace(HTML_COMMENT_RE, "").trim();
+        if (body)
+            sections[heading] = body;
+    }
+    // Parse colors
+    const colors = {};
+    if (sections["Colors"]) {
+        const lines = sections["Colors"].split("\n");
+        for (const line of lines) {
+            const match = line.match(/^([A-Za-z][A-Za-z0-9 /]*?)\s*:\s*(#[0-9A-Fa-f]{6})\b/);
+            if (match) {
+                colors[match[1].trim()] = match[2];
+            }
+        }
+    }
+    return {
+        designDirection: sections["Design Direction"] ?? "",
+        colors,
+        layout: sections["Layout"] ?? "",
+        typography: sections["Typography"] ?? "",
+        componentStyle: sections["Component Style"] ?? "",
+        references: sections["References"] ?? "",
+    };
+}
+const QUIT_COMMANDS = new Set(["q", "quit", "exit"]);
+function prompt(rl, question) {
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            if (QUIT_COMMANDS.has(answer.trim().toLowerCase())) {
+                resolve(null);
+            }
+            else {
+                resolve(answer);
+            }
+        });
+    });
+}
+export async function runMoodboardEdit(projectDir) {
+    const notesPath = join(projectDir, ".stoa", "moodboard", "notes.md");
+    const current = parseMoodboard(notesPath);
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    writeln();
+    writeln(chalk.bold("Edit Moodboard"));
+    writeln(chalk.dim("Enter to keep current value. Type new value to replace. Type 'q' to quit."));
+    writeln();
+    let changed = false;
+    // Helper to handle a text field
+    async function editField(label, currentValue) {
+        writeln(chalk.bold(label));
+        if (currentValue) {
+            writeln(chalk.dim(`  Current: ${currentValue}`));
+        }
+        const answer = await prompt(rl, chalk.cyan("  New: "));
+        if (answer === null)
+            return "quit";
+        if (answer.trim()) {
+            writeln(chalk.green("  ✓ Updated"));
+            return answer.trim();
+        }
+        writeln(chalk.dim("  ✓ Kept"));
+        return currentValue;
+    }
+    // Design Direction
+    const dir = await editField("Design Direction", current.designDirection);
+    if (dir === "quit") {
+        rl.close();
+        writeln(chalk.dim("\nCancelled."));
+        return;
+    }
+    if (dir !== current.designDirection) {
+        current.designDirection = dir;
+        changed = true;
+    }
+    writeln();
+    // Colors
+    writeln(chalk.bold("Colors"));
+    const colorKeys = Object.keys(current.colors);
+    if (colorKeys.length > 0) {
+        for (const key of colorKeys) {
+            const hex = current.colors[key];
+            const swatch = chalk.hex(hex)("██");
+            writeln(`  ${chalk.dim(key)}: ${swatch} ${chalk.dim(hex)}`);
+            const newColor = await prompt(rl, chalk.cyan(`  New ${key}: `));
+            if (newColor === null) {
+                rl.close();
+                writeln(chalk.dim("\nCancelled."));
+                return;
+            }
+            if (newColor.trim()) {
+                if (/^#[0-9A-Fa-f]{6}$/.test(newColor.trim())) {
+                    current.colors[key] = newColor.trim();
+                    changed = true;
+                    writeln(chalk.green("  ✓ Updated"));
+                }
+                else {
+                    writeln(chalk.yellow("  ✗ Invalid hex (use #RRGGBB). Kept original."));
+                }
+            }
+            else {
+                writeln(chalk.dim("  ✓ Kept"));
+            }
+        }
+    }
+    else {
+        writeln(chalk.dim("  No colors defined. Add them in format: Label: #HEXVAL"));
+    }
+    // Add new color?
+    const addColor = await prompt(rl, chalk.cyan("  Add new color? (name: #hex or Enter to skip): "));
+    if (addColor === null) {
+        rl.close();
+        writeln(chalk.dim("\nCancelled."));
+        return;
+    }
+    if (addColor.trim()) {
+        const match = addColor.match(/^([A-Za-z][A-Za-z0-9 ]*?)\s*:\s*(#[0-9A-Fa-f]{6})$/);
+        if (match) {
+            current.colors[match[1].trim()] = match[2];
+            changed = true;
+            writeln(chalk.green(`  ✓ Added ${match[1].trim()}`));
+        }
+        else {
+            writeln(chalk.yellow("  ✗ Format: Name: #HEXVAL"));
+        }
+    }
+    writeln();
+    // Typography
+    const typo = await editField("Typography", current.typography);
+    if (typo === "quit") {
+        rl.close();
+        writeln(chalk.dim("\nCancelled."));
+        return;
+    }
+    if (typo !== current.typography) {
+        current.typography = typo;
+        changed = true;
+    }
+    writeln();
+    // Layout
+    const layout = await editField("Layout", current.layout);
+    if (layout === "quit") {
+        rl.close();
+        writeln(chalk.dim("\nCancelled."));
+        return;
+    }
+    if (layout !== current.layout) {
+        current.layout = layout;
+        changed = true;
+    }
+    writeln();
+    // Component Style
+    const style = await editField("Component Style", current.componentStyle);
+    if (style === "quit") {
+        rl.close();
+        writeln(chalk.dim("\nCancelled."));
+        return;
+    }
+    if (style !== current.componentStyle) {
+        current.componentStyle = style;
+        changed = true;
+    }
+    writeln();
+    // References
+    const refs = await editField("References", current.references);
+    if (refs === "quit") {
+        rl.close();
+        writeln(chalk.dim("\nCancelled."));
+        return;
+    }
+    if (refs !== current.references) {
+        current.references = refs;
+        changed = true;
+    }
+    rl.close();
+    writeln();
+    if (!changed) {
+        writeln(chalk.dim("No changes made."));
+        return;
+    }
+    // Write notes.md
+    const colorLines = Object.entries(current.colors)
+        .map(([key, value]) => `${key}: ${value}`)
+        .join("\n");
+    const markdown = `# Design Direction
+${current.designDirection || ""}
+
+# Colors
+${colorLines || ""}
+
+# Layout
+${current.layout || ""}
+
+# Typography
+${current.typography || ""}
+
+# Component Style
+${current.componentStyle || ""}
+
+# References
+${current.references || ""}
+`;
+    writeFileSync(notesPath, markdown, "utf-8");
+    writeln(chalk.green("✓ Saved to .stoa/moodboard/notes.md"));
+    // Auto-sync tokens
+    try {
+        syncMoodboard(projectDir);
+        writeln(chalk.green("✓ Synced tokens.json"));
+    }
+    catch {
+        // Non-critical
+    }
+}

package/dist/cli/moodboard-picker.d.ts

@@ -0,0 +1,2 @@
+import type { PresetEntry } from "../storage/moodboard-presets.js";
+export declare function pickPreset(entries: PresetEntry[]): Promise<PresetEntry | null>;

package/dist/cli/moodboard-picker.js

@@ -0,0 +1,125 @@
+import chalk from "chalk";
+function writeln(text = "") {
+    process.stdout.write(text + "\n");
+}
+function clearLines(count) {
+    for (let i = 0; i < count; i++) {
+        process.stdout.write("\x1B[1A\x1B[2K");
+    }
+}
+function renderPreview(entry) {
+    const { preset } = entry;
+    const lines = [];
+    const c = preset.colors;
+    // Color swatches line
+    const colorPairs = [
+        ["Bg", c.background],
+        ["Primary", c.primary],
+        ["Text", c.text],
+        ["Border", c.border],
+    ].filter(([, v]) => v);
+    const colorLine = colorPairs
+        .map(([label, hex]) => `${label}: ${chalk.hex(hex)("██")} ${chalk.dim(hex)}`)
+        .join("  ");
+    lines.push(`    ${colorLine}`);
+    lines.push(`    ${chalk.dim(preset.typography.split(".")[0])}`);
+    lines.push(`    ${chalk.dim(preset.componentStyle.split(".")[0])}`);
+    lines.push(`    ${chalk.dim(`Like: ${preset.references}`)}`);
+    return lines;
+}
+function render(entries, selected) {
+    const lines = [];
+    lines.push("");
+    lines.push(chalk.bold("Choose a style preset:"));
+    lines.push("");
+    let builtinDone = false;
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        // Separator between built-in and custom
+        if (entry.isCustom && !builtinDone) {
+            builtinDone = true;
+            lines.push("  " + chalk.dim("─".repeat(40)));
+        }
+        const isSelected = i === selected;
+        const marker = isSelected ? chalk.cyan("● ") : "  ";
+        const name = isSelected ? chalk.cyan.bold(entry.preset.name) : entry.preset.name;
+        const desc = chalk.dim(entry.preset.description);
+        const tag = entry.isCustom ? chalk.dim(" (custom)") : "";
+        lines.push(`  ${marker}${name}  ${desc}${tag}`);
+        // Show preview for selected
+        if (isSelected) {
+            const preview = renderPreview(entry);
+            lines.push(...preview);
+            lines.push("");
+        }
+    }
+    lines.push(chalk.dim("  ↑↓ navigate  Enter apply  q cancel"));
+    lines.push("");
+    for (const line of lines) {
+        writeln(line);
+    }
+    return lines.length;
+}
+function waitForKey() {
+    return new Promise((resolve) => {
+        const { stdin } = process;
+        if (!stdin.isTTY || typeof stdin.setRawMode !== "function") {
+            resolve("q");
+            return;
+        }
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.once("data", (data) => {
+            stdin.setRawMode(wasRaw);
+            stdin.pause();
+            resolve(data.toString());
+        });
+    });
+}
+export async function pickPreset(entries) {
+    if (entries.length === 0) {
+        writeln(chalk.red("No presets found."));
+        return null;
+    }
+    if (!process.stdin.isTTY) {
+        writeln(chalk.red("Interactive preset picker requires a TTY terminal."));
+        return null;
+    }
+    let selected = 0;
+    let lastLineCount = 0;
+    // Initial render
+    lastLineCount = render(entries, selected);
+    while (true) {
+        const key = await waitForKey();
+        // Ctrl+C
+        if (key === "\x03") {
+            return null;
+        }
+        // q to cancel
+        if (key === "q") {
+            return null;
+        }
+        // Enter to select
+        if (key === "\r" || key === "\n") {
+            return entries[selected];
+        }
+        // Arrow keys (escape sequences)
+        if (key === "\x1B[A" || key === "k") {
+            // Up
+            if (selected > 0) {
+                selected--;
+                clearLines(lastLineCount);
+                lastLineCount = render(entries, selected);
+            }
+        }
+        else if (key === "\x1B[B" || key === "j") {
+            // Down
+            if (selected < entries.length - 1) {
+                selected++;
+                clearLines(lastLineCount);
+                lastLineCount = render(entries, selected);
+            }
+        }
+    }
+}

package/dist/cli.js

@@ -3,9 +3,9 @@ import { Command } from "commander";
 import chalk from "chalk";
 import ora from "ora";
 import { readFile, writeFile, mkdir, access } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { basename, join, extname } from "node:path";
 import { homedir } from "node:os";
-import { existsSync, readFileSync, constants } from "node:fs";
+import { existsSync, readFileSync, readdirSync, constants } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { refinePipeline } from "./core/refine.js";
 import { computeSpecScore } from "./core/spec-score.js";
@@ -28,7 +28,10 @@ import { scanProject } from "./storage/project-scan.js";
 import { syncMoodboard } from "./storage/moodboard-sync.js";
 import { describeMoodboard } from "./storage/moodboard-describe.js";
 import { runSpecScenarios } from "./cli/scenarios-runner.js";
-import { spawn } from "node:child_process";
+import { spawn, execFileSync } from "node:child_process";
+import { listPresets, loadPreset, applyPreset, savePreset } from "./storage/moodboard-presets.js";
+import { pickPreset } from "./cli/moodboard-picker.js";
+import { runMoodboardEdit } from "./cli/moodboard-edit.js";
 // ── Constants ─────────────────────────────────────────────────────────
 const STAGE_NAMES = ["clarify", "structure", "score", "harden", "finalize"];
 const STAGE_NAME_TO_NUMBER = {
@@ -120,6 +123,24 @@ function maskApiKey(value) {
         return value;
     return value.slice(0, 3) + "..." + value.slice(-4);
 }
+function detectEditor() {
+    // Prefer cursor → code → $EDITOR → open (macOS) → nano
+    try {
+        execFileSync("which", ["cursor"], { stdio: "ignore" });
+        return "cursor";
+    }
+    catch { /* */ }
+    try {
+        execFileSync("which", ["code"], { stdio: "ignore" });
+        return "code";
+    }
+    catch { /* */ }
+    if (process.env.EDITOR)
+        return process.env.EDITOR;
+    if (process.platform === "darwin")
+        return "open";
+    return "nano";
+}
 function copyToClipboard(text) {
     try {
         const child = spawn("pbcopy", { stdio: ["pipe", "ignore", "ignore"] });
@@ -568,7 +589,8 @@ program
         process.stderr.write(chalk.red(`File not found: ${relativePath}. Run 'stoa init' first.`) + "\n");
         process.exit(1);
     }
-    const editor = process.env.EDITOR || "nano";
+    // Detect best editor: cursor → code → $EDITOR → open (macOS) → nano
+    const editor = detectEditor();
     const child = spawn(editor, [fullPath], { stdio: "inherit" });
     child.on("exit", (code) => {
         process.exit(code ?? 0);
@@ -995,7 +1017,119 @@ scenariosCmd
 // ── stoa moodboard ──────────────────────────────────────────────────
 const moodboardCmd = program
     .command("moodboard")
-    .description("Manage project moodboard (.stoa/moodboard/)");
+    .description("Manage project moodboard (.stoa/moodboard/)")
+    .action(() => {
+    // No subcommand → show status
+    const cwd = process.cwd();
+    const notesPath = join(cwd, ".stoa", "moodboard", "notes.md");
+    const tokensPath = join(cwd, ".stoa", "moodboard", "tokens.json");
+    if (!existsSync(join(cwd, ".stoa"))) {
+        writeln(chalk.red("No .stoa/ directory. Run 'stoa init' first."));
+        process.exit(1);
+    }
+    writeln();
+    writeln(chalk.bold("Moodboard Status"));
+    writeln();
+    // Check notes.md
+    if (existsSync(notesPath)) {
+        const raw = readFileSync(notesPath, "utf-8");
+        const stripped = raw.replace(/<!--[\s\S]*?-->/g, "").replace(/^#.*$/gm, "").trim();
+        if (stripped.length > 0) {
+            // Extract design direction (first non-empty section)
+            const dirMatch = raw.match(/# Design Direction\n([^\n#]+)/);
+            if (dirMatch) {
+                writeln(`  Style: ${chalk.cyan(dirMatch[1].trim())}`);
+            }
+        }
+        else {
+            writeln(`  Style: ${chalk.dim("(empty — run 'stoa moodboard preset' to set one)")}`);
+        }
+    }
+    else {
+        writeln(`  Style: ${chalk.dim("(no notes.md)")}`);
+    }
+    // Check tokens
+    if (existsSync(tokensPath)) {
+        try {
+            const tokens = JSON.parse(readFileSync(tokensPath, "utf-8"));
+            const colorCount = tokens.colors ? Object.keys(tokens.colors).length : 0;
+            writeln(`  Colors: ${colorCount > 0 ? chalk.green(`${colorCount} defined`) : chalk.dim("none")}`);
+        }
+        catch {
+            writeln(`  Tokens: ${chalk.dim("invalid")}`);
+        }
+    }
+    else {
+        writeln(`  Tokens: ${chalk.dim("not synced")}`);
+    }
+    // Check images
+    const moodboardDir = join(cwd, ".stoa", "moodboard");
+    if (existsSync(moodboardDir)) {
+        try {
+            const files = readdirSync(moodboardDir);
+            const imageExts = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg"]);
+            const imageCount = files.filter((f) => imageExts.has(extname(f).toLowerCase())).length;
+            writeln(`  Images: ${imageCount > 0 ? chalk.green(`${imageCount} screenshot(s)`) : chalk.dim("none")}`);
+        }
+        catch {
+            // ignore
+        }
+    }
+    writeln();
+    writeln(chalk.bold("Commands:"));
+    writeln(`  ${chalk.cyan("stoa moodboard preset")}       Switch style preset`);
+    writeln(`  ${chalk.cyan("stoa moodboard edit")}          Edit interactively`);
+    writeln(`  ${chalk.cyan("stoa moodboard describe")}      Extract design from screenshots`);
+    writeln(`  ${chalk.cyan("stoa moodboard sync")}          Regenerate tokens.json`);
+    writeln(`  ${chalk.cyan("stoa moodboard save-preset")}   Save current as reusable preset`);
+    writeln(`  ${chalk.cyan("stoa edit moodboard")}          Open in editor`);
+    writeln();
+});
+moodboardCmd
+    .command("preset")
+    .description("Choose a style preset for your moodboard")
+    .argument("[name]", "Preset name (omit for interactive picker)")
+    .action(async (name) => {
+    const cwd = process.cwd();
+    if (name) {
+        // Direct apply by name
+        const preset = loadPreset(cwd, name);
+        if (!preset) {
+            const available = listPresets(cwd).map((e) => e.id).join(", ");
+            process.stderr.write(chalk.red(`Preset "${name}" not found. Available: ${available}`) + "\n");
+            process.exit(1);
+        }
+        applyPreset(cwd, preset);
+        writeln(chalk.green(`Applied "${preset.name}" preset.`));
+        return;
+    }
+    // Interactive picker
+    const entries = listPresets(cwd);
+    if (entries.length === 0) {
+        writeln(chalk.red("No presets found."));
+        process.exit(1);
+    }
+    const selected = await pickPreset(entries);
+    if (!selected) {
+        writeln(chalk.dim("Cancelled."));
+        return;
+    }
+    applyPreset(cwd, selected.preset);
+    writeln(chalk.green(`Applied "${selected.preset.name}" preset.`));
+    writeln(chalk.dim("Run 'stoa moodboard edit' to customize, or 'stoa refine' to use it."));
+});
+moodboardCmd
+    .command("edit")
+    .description("Edit moodboard interactively in the terminal")
+    .action(async () => {
+    try {
+        await runMoodboardEdit(process.cwd());
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+});
 moodboardCmd
     .command("sync")
     .description("Parse notes.md and generate tokens.json")
@@ -1048,6 +1182,28 @@ moodboardCmd
     else {
         mode = "clipboard";
     }
+    // Open moodboard folder so user can drop screenshots
+    const moodboardDir = join(process.cwd(), ".stoa", "moodboard");
+    if (existsSync(moodboardDir)) {
+        writeln(chalk.cyan("Opening moodboard folder — drop your screenshots in..."));
+        if (process.platform === "darwin") {
+            spawn("open", [moodboardDir], { stdio: "ignore", detached: true });
+        }
+        else {
+            spawn("xdg-open", [moodboardDir], { stdio: "ignore", detached: true });
+        }
+        // Wait for user to confirm
+        if (process.stdin.isTTY) {
+            const { createInterface } = await import("node:readline");
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            await new Promise((resolve) => {
+                rl.question(chalk.dim("Press Enter when ready → "), () => {
+                    rl.close();
+                    resolve();
+                });
+            });
+        }
+    }
     const spinner = mode === "api" ? ora({ text: "Analyzing screenshots...", color: "cyan" }) : null;
     try {
         if (spinner)
@@ -1089,6 +1245,21 @@ moodboardCmd
         process.exit(1);
     }
 });
+moodboardCmd
+    .command("save-preset")
+    .description("Save current moodboard as a reusable preset")
+    .argument("<name>", "Name for the preset")
+    .action((name) => {
+    try {
+        const preset = savePreset(process.cwd(), name);
+        writeln(chalk.green(`Saved preset "${preset.name}" to .stoa/presets/${name}.json`));
+        writeln(chalk.dim("Use 'stoa moodboard preset' to apply it in other projects."));
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+    }
+});
 // ── stoa review ──────────────────────────────────────────────────────
 program
     .command("review")

package/dist/storage/moodboard-presets.d.ts

@@ -0,0 +1,30 @@
+export interface PresetColors {
+    background: string;
+    surface: string;
+    border: string;
+    text: string;
+    text_secondary: string;
+    primary: string;
+    primary_hover: string;
+    [key: string]: string;
+}
+export interface MoodboardPreset {
+    name: string;
+    description: string;
+    designDirection: string;
+    colors: PresetColors;
+    typography: string;
+    layout: string;
+    componentStyle: string;
+    references: string;
+}
+export interface PresetEntry {
+    id: string;
+    preset: MoodboardPreset;
+    isCustom: boolean;
+}
+export declare function listPresets(projectDir: string): PresetEntry[];
+export declare function loadPreset(projectDir: string, name: string): MoodboardPreset | null;
+export declare function presetToNotesMarkdown(preset: MoodboardPreset): string;
+export declare function applyPreset(projectDir: string, preset: MoodboardPreset): void;
+export declare function savePreset(projectDir: string, name: string): MoodboardPreset;

package/dist/storage/moodboard-presets.js

@@ -0,0 +1,160 @@
+import { readFileSync, readdirSync, existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, basename, extname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { syncMoodboard } from "./moodboard-sync.js";
+function getBuiltinPresetsDir() {
+    return fileURLToPath(new URL("../../templates/moodboard-presets/", import.meta.url));
+}
+function getCustomPresetsDir(projectDir) {
+    return join(projectDir, ".stoa", "presets");
+}
+function loadPresetFile(filePath) {
+    try {
+        const raw = readFileSync(filePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function listPresets(projectDir) {
+    const entries = [];
+    // Built-in presets
+    const builtinDir = getBuiltinPresetsDir();
+    if (existsSync(builtinDir)) {
+        const files = readdirSync(builtinDir)
+            .filter((f) => extname(f) === ".json")
+            .sort();
+        for (const file of files) {
+            const preset = loadPresetFile(join(builtinDir, file));
+            if (preset) {
+                entries.push({
+                    id: basename(file, ".json"),
+                    preset,
+                    isCustom: false,
+                });
+            }
+        }
+    }
+    // Custom presets
+    const customDir = getCustomPresetsDir(projectDir);
+    if (existsSync(customDir)) {
+        const files = readdirSync(customDir)
+            .filter((f) => extname(f) === ".json")
+            .sort();
+        for (const file of files) {
+            const preset = loadPresetFile(join(customDir, file));
+            if (preset) {
+                entries.push({
+                    id: basename(file, ".json"),
+                    preset,
+                    isCustom: true,
+                });
+            }
+        }
+    }
+    return entries;
+}
+export function loadPreset(projectDir, name) {
+    // Check custom first
+    const customPath = join(getCustomPresetsDir(projectDir), `${name}.json`);
+    if (existsSync(customPath)) {
+        return loadPresetFile(customPath);
+    }
+    // Then built-in
+    const builtinPath = join(getBuiltinPresetsDir(), `${name}.json`);
+    if (existsSync(builtinPath)) {
+        return loadPresetFile(builtinPath);
+    }
+    return null;
+}
+export function presetToNotesMarkdown(preset) {
+    const colorLines = Object.entries(preset.colors)
+        .map(([key, value]) => {
+        const label = key
+            .replace(/_/g, " ")
+            .replace(/\b\w/g, (c) => c.toUpperCase());
+        return `${label}: ${value}`;
+    })
+        .join("\n");
+    return `# Design Direction
+${preset.designDirection}
+
+# Colors
+${colorLines}
+
+# Layout
+${preset.layout}
+
+# Typography
+${preset.typography}
+
+# Component Style
+${preset.componentStyle}
+
+# References
+${preset.references}
+`;
+}
+export function applyPreset(projectDir, preset) {
+    const moodboardDir = join(projectDir, ".stoa", "moodboard");
+    mkdirSync(moodboardDir, { recursive: true });
+    const notesPath = join(moodboardDir, "notes.md");
+    const markdown = presetToNotesMarkdown(preset);
+    writeFileSync(notesPath, markdown, "utf-8");
+    // Auto-sync tokens
+    try {
+        syncMoodboard(projectDir);
+    }
+    catch {
+        // Non-critical
+    }
+}
+export function savePreset(projectDir, name) {
+    const moodboardDir = join(projectDir, ".stoa", "moodboard");
+    const notesPath = join(moodboardDir, "notes.md");
+    if (!existsSync(notesPath)) {
+        throw new Error("No moodboard/notes.md found. Run 'stoa init' first.");
+    }
+    // Try to load tokens.json for structured data
+    const tokensPath = join(moodboardDir, "tokens.json");
+    let tokens = {};
+    if (existsSync(tokensPath)) {
+        try {
+            tokens = JSON.parse(readFileSync(tokensPath, "utf-8"));
+        }
+        catch {
+            // ignore
+        }
+    }
+    // Parse notes.md sections
+    const raw = readFileSync(notesPath, "utf-8");
+    const sections = {};
+    const parts = raw.split(/^# /m);
+    for (const part of parts) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const newlineIdx = trimmed.indexOf("\n");
+        if (newlineIdx === -1)
+            continue;
+        const heading = trimmed.slice(0, newlineIdx).trim();
+        const body = trimmed.slice(newlineIdx + 1).replace(/<!--[\s\S]*?-->/g, "").trim();
+        if (body)
+            sections[heading] = body;
+    }
+    const preset = {
+        name: name.charAt(0).toUpperCase() + name.slice(1),
+        description: "Custom preset",
+        designDirection: sections["Design Direction"] ?? "",
+        colors: tokens.colors ?? {},
+        typography: sections["Typography"] ?? "",
+        layout: sections["Layout"] ?? "",
+        componentStyle: sections["Component Style"] ?? "",
+        references: sections["References"] ?? "",
+    };
+    const presetsDir = getCustomPresetsDir(projectDir);
+    mkdirSync(presetsDir, { recursive: true });
+    writeFileSync(join(presetsDir, `${name}.json`), JSON.stringify(preset, null, 2) + "\n", "utf-8");
+    return preset;
+}

package/dist/storage/project.js

@@ -3,6 +3,7 @@ import { copyFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises"
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { toSlug } from "../utils/slug.js";
+import { loadPreset, applyPreset } from "./moodboard-presets.js";
 function getTemplatesDir() {
     return fileURLToPath(new URL("../../templates/", import.meta.url));
 }
@@ -38,28 +39,39 @@ export async function initProject(name, type, noTemplates = false) {
     await mkdir(join(stoaDir, "scenarios"), { recursive: true });
     await mkdir(join(stoaDir, "specs"), { recursive: true });
     await mkdir(join(stoaDir, "moodboard"), { recursive: true });
-    await writeFile(join(stoaDir, "moodboard", "notes.md"), `# Design Direction
-<!-- What should this feel like? E.g. "Minimal and fast like Linear" -->
+    await mkdir(join(stoaDir, "presets"), { recursive: true });
+    // Apply "clean" preset as default moodboard
+    const cleanPreset = loadPreset(process.cwd(), "clean");
+    if (cleanPreset) {
+        applyPreset(process.cwd(), cleanPreset);
+    }
+    else {
+        // Fallback if preset file missing
+        await writeFile(join(stoaDir, "moodboard", "notes.md"), `# Design Direction
+Clean, modern, minimal — inspired by Linear and Vercel
 
 # Colors
-<!-- Hex values. E.g. Primary: #E8C872, Background: #1A1A1A -->
+Background: #FFFFFF
+Surface: #FAFAFA
+Border: #E5E7EB
+Text: #111827
+Text Secondary: #6B7280
+Primary: #6366F1
+Primary Hover: #4F46E5
 
 # Layout
-<!-- E.g. "Sidebar navigation left, card-based content right" -->
+Single column centered, max-width 768px. Cards for grouped content.
 
 # Typography
-<!-- E.g. "Sans-serif, large headings, compact body text" -->
+Sans-serif (Inter or system font). Large bold headings, regular weight body.
 
 # Component Style
-<!-- E.g. "Rounded corners, subtle borders, no drop shadows" -->
+Rounded corners (8px). Subtle borders, no heavy shadows. Filled primary buttons, ghost secondary buttons.
 
 # References
-<!-- Apps to emulate. E.g. "Linear — task list density. Arc — sidebar tabs." -->
-
-# Images
-<!-- Drop files in moodboard/ folder, describe each here -->
-<!-- E.g. homepage-inspo.png — I want this hero layout -->
+Linear, Notion, Vercel
 `, "utf-8");
+    }
     // Create context.md (brand voice + dependencies + conventions in one file)
     await writeFile(join(stoaDir, "context.md"), `# Project Context
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stoa-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "The Specification Compiler for AI Agents. Transform vague tasks into executable specs with blind test scenarios.",
   "type": "module",
   "main": "dist/index.js",

package/templates/moodboard-presets/bold.json

@@ -0,0 +1,18 @@
+{
+  "name": "Bold",
+  "description": "High contrast, strong colors, brutalist",
+  "designDirection": "Bold, high-contrast, brutalist — unapologetically opinionated",
+  "colors": {
+    "background": "#FFFFFF",
+    "surface": "#F5F5F5",
+    "border": "#000000",
+    "text": "#000000",
+    "text_secondary": "#525252",
+    "primary": "#DC2626",
+    "primary_hover": "#B91C1C"
+  },
+  "typography": "Sans-serif (Helvetica, Arial, or system). Heavy weight headings, tight letter spacing. All-caps for labels.",
+  "layout": "Single column, full-width sections. Grid-based. Tight spacing, dense information.",
+  "componentStyle": "Sharp corners (2px radius). Thick borders (2px). No shadows. High contrast buttons. Monospace for data.",
+  "references": "Bloomberg terminal, Supreme, brutalist web design"
+}

package/templates/moodboard-presets/clean.json

@@ -0,0 +1,18 @@
+{
+  "name": "Clean",
+  "description": "White, minimal, Linear-style",
+  "designDirection": "Clean, modern, minimal — inspired by Linear and Vercel",
+  "colors": {
+    "background": "#FFFFFF",
+    "surface": "#FAFAFA",
+    "border": "#E5E7EB",
+    "text": "#111827",
+    "text_secondary": "#6B7280",
+    "primary": "#6366F1",
+    "primary_hover": "#4F46E5"
+  },
+  "typography": "Sans-serif (Inter or system font). Large bold headings, regular weight body.",
+  "layout": "Single column centered, max-width 768px. Cards for grouped content.",
+  "componentStyle": "Rounded corners (8px). Subtle borders, no heavy shadows. Filled primary buttons, ghost secondary buttons.",
+  "references": "Linear, Notion, Vercel"
+}

package/templates/moodboard-presets/dark.json

@@ -0,0 +1,18 @@
+{
+  "name": "Dark",
+  "description": "Dark background, muted accents, like GitHub/Raycast",
+  "designDirection": "Dark, focused, minimal — inspired by Raycast and GitHub",
+  "colors": {
+    "background": "#0A0A0B",
+    "surface": "#18181B",
+    "border": "#27272A",
+    "text": "#FAFAFA",
+    "text_secondary": "#A1A1AA",
+    "primary": "#8B5CF6",
+    "primary_hover": "#7C3AED"
+  },
+  "typography": "Sans-serif (Inter or system font). High contrast text on dark backgrounds.",
+  "layout": "Single column centered, max-width 768px. Cards with subtle borders on dark surfaces.",
+  "componentStyle": "Rounded corners (8px). Faint borders, no shadows, glow accents on focus. Filled primary buttons.",
+  "references": "GitHub dark, Raycast, Arc browser"
+}

package/templates/moodboard-presets/warm.json

@@ -0,0 +1,18 @@
+{
+  "name": "Warm",
+  "description": "Cream tones, friendly SaaS feel",
+  "designDirection": "Warm, approachable, organic — inspired by Cal.com and Stripe docs",
+  "colors": {
+    "background": "#FFFBF5",
+    "surface": "#FFF7ED",
+    "border": "#E7D5C0",
+    "text": "#1C1917",
+    "text_secondary": "#78716C",
+    "primary": "#D97706",
+    "primary_hover": "#B45309"
+  },
+  "typography": "Serif headings (Georgia or Playfair Display), sans-serif body (Inter or system). Generous line height.",
+  "layout": "Single column centered, max-width 720px. Generous whitespace. Soft grouped sections.",
+  "componentStyle": "Rounded corners (12px). Soft shadows, warm borders. Filled buttons with slight rounding. Spacious padding.",
+  "references": "Cal.com, Stripe documentation, Notion in sepia"
+}