Bump version to 0.8.1

Previously unblock only checked for blocked=true. Stories stuck in
merge with a merge_failure field were not considered "blocked" and
unblock refused to act. Now it clears both blocked and merge_failure,
and reports which fields were cleared.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.storkit/README.md

@@ -9,16 +9,21 @@
 
 When you start a new session with this project:
 
-1. **Check for MCP Tools:** Read `.mcp.json` to discover the MCP server endpoint. Then list available tools by calling:
+1. **Check Setup Wizard:** Call `wizard_status` to check if project setup is complete. If the wizard is not complete, guide the user through the remaining steps. Important rules for the wizard flow:
+   - **Be conversational.** Don't show tool names, step numbers, or raw wizard output to the user.
+   - **On projects with existing code:** Read the codebase and generate each file, then show the user what you wrote and ask if it looks right.
+   - **On bare projects with no code:** Ask the user what they want to build, what language/framework they plan to use, and generate files from their answers.
+   - Use `wizard_generate` to create content, show it to the user, then call `wizard_confirm` (they approve), `wizard_retry` (they want changes), or `wizard_skip` (they want to skip this step).
+2. **Check for MCP Tools:** Read `.mcp.json` to discover the MCP server endpoint. Then list available tools by calling:
    ```bash
    curl -s "$(jq -r '.mcpServers["storkit"].url' .mcp.json)" \
      -H 'Content-Type: application/json' \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
    ```
    This returns the full tool catalog (create stories, spawn agents, record tests, manage worktrees, etc.). Familiarize yourself with the available tools before proceeding. These tools allow you to directly manipulate the workflow and spawn subsidiary agents without manual file manipulation.
-2. **Read Context:** Check `.story_kit/specs/00_CONTEXT.md` for high-level project goals.
+3. **Read Context:** Check `.storkit/specs/00_CONTEXT.md` for high-level project goals.
-3. **Read Stack:** Check `.story_kit/specs/tech/STACK.md` for technical constraints and patterns.
+4. **Read Stack:** Check `.storkit/specs/tech/STACK.md` for technical constraints and patterns.
-4. **Check Work Items:** Look at `.story_kit/work/1_backlog/` and `.story_kit/work/2_current/` to see what work is pending.
+5. **Check Work Items:** Look at `.storkit/work/1_backlog/` and `.storkit/work/2_current/` to see what work is pending.
 
 
 ---

.storkit/project.toml

@@ -63,30 +63,52 @@ system_prompt = "You are a full-stack engineer working autonomously in a git wor
 [[agent]]
 name = "qa-2"
 stage = "qa"
-role = "Reviews coder work in worktrees: runs quality gates, generates testing plans, and reports findings."
+role = "Reviews coder work in worktrees: runs quality gates, verifies acceptance criteria, and reports findings."
 model = "sonnet"
 max_turns = 40
 max_budget_usd = 4.00
-prompt = """You are the QA agent for story {{story_id}}. Your job is to review the coder's work in the worktree and produce a structured QA report.
+prompt = """You are the QA agent for story {{story_id}}. Your job is to verify the coder's work satisfies the story's acceptance criteria and produce a structured QA report.
 
 Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
 
 ## Your Workflow
 
-### 1. Code Quality Scan
+### 0. Read the Story
-- Run `git diff master...HEAD --stat` to see what files changed
+- Read the story file at `.storkit/work/3_qa/{{story_id}}.md`
-- Run `git diff master...HEAD` to review the actual changes for obvious coding mistakes (unused imports, dead code, unhandled errors, hardcoded values)
+- Extract every acceptance criterion (the `- [ ]` checkbox lines)
-- Run `cargo clippy --all-targets --all-features` and note any warnings
+- Keep this list in mind for Step 3
+
+### 1. Deterministic Gates (Prerequisites)
+Run these first — if any fail, reject immediately without proceeding to AC review:
+- Run `cargo clippy --all-targets --all-features` — must show 0 errors, 0 warnings
+- Run `cargo test` and verify all tests pass
 - If a `frontend/` directory exists:
   - Run `npm run build` and note any TypeScript errors
   - Run `npx @biomejs/biome check src/` and note any linting issues
+  - Run `npm test` and verify all frontend tests pass
 
-### 2. Test Verification
+### 2. Code Change Review
-- Run `cargo test` and verify all tests pass
+- Run `git diff master...HEAD --stat` to see what files changed
-- If `frontend/` exists: run `npm test` and verify all frontend tests pass
+- Run `git diff master...HEAD` to review the actual changes
-- Review test quality: look for tests that are trivial or don't assert meaningful behavior
+- Flag any incomplete implementations:
+  - `todo!()`, `unimplemented!()`, `panic!()` used as stubs
+  - Placeholder strings like "TODO", "FIXME", "not implemented"
+  - Empty match arms or arms that just return `Default::default()`
+  - Hardcoded values where real logic is expected
+- Note any obvious coding mistakes (unused imports, dead code, unhandled errors)
 
-### 3. Manual Testing Support
+### 3. Acceptance Criteria Review
+For each AC extracted in Step 0:
+- Review the diff and test files to determine if the code addresses this AC
+- PASS: describe specifically how the code addresses it (which file/function/test)
+- FAIL: explain exactly what is missing or incorrect
+
+An AC fails if:
+- No code change or test relates to it
+- The implementation is stubbed out (todo!/unimplemented!)
+- A test exists but doesn't actually assert the behaviour described
+
+### 4. Manual Testing Support (only if all gates PASS and all ACs PASS)
 - Build the server: run `cargo build` and note success/failure
 - If build succeeds: find a free port (try 3010-3020) and attempt to start the server
 - Generate a testing plan including:
@@ -95,8 +117,8 @@ Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
   - curl commands to exercise relevant API endpoints
 - Kill the test server when done: `pkill -f 'target.*storkit' || true` (NEVER use `pkill -f storkit` — it kills the vite dev server)
 
-### 4. Produce Structured Report
+### 5. Produce Structured Report and Verdict
-Print your QA report to stdout before your process exits. The server will automatically run acceptance gates. Use this format:
+Print your QA report to stdout. Then call `approve_qa` or `reject_qa` via the MCP tool based on the overall result. Use this format:
 
 ```
 ## QA Report for {{story_id}}
@@ -105,27 +127,38 @@ Print your QA report to stdout before your process exits. The server will automa
 - clippy: PASS/FAIL (details)
 - TypeScript build: PASS/FAIL/SKIP (details)
 - Biome lint: PASS/FAIL/SKIP (details)
-- Code review findings: (list any issues found, or "None")
-
-### Test Verification
 - cargo test: PASS/FAIL (N tests)
 - npm test: PASS/FAIL/SKIP (N tests)
-- Test quality issues: (list any trivial/weak tests, or "None")
+- Incomplete implementations: (list any todo!/unimplemented!/stubs found, or "None")
+- Other code review findings: (list any issues found, or "None")
+
+### Acceptance Criteria Review
+- AC: <criterion text>
+  Result: PASS/FAIL
+  Evidence: <how the code addresses it, or what is missing>
+
+(repeat for each AC)
 
 ### Manual Testing Plan
-- Server URL: http://localhost:PORT (or "Build failed")
+- Server URL: http://localhost:PORT (or "Skipped — gate/AC failure" or "Build failed")
-- Pages to visit: (list)
+- Pages to visit: (list, or "N/A")
-- Things to check: (list)
+- Things to check: (list, or "N/A")
-- curl commands: (list)
+- curl commands: (list, or "N/A")
 
 ### Overall: PASS/FAIL
+Reason: (summary of why it passed or the primary reason it failed)
 ```
 
+After printing the report:
+- If Overall is PASS: call `approve_qa(story_id='{{story_id}}')` via MCP
+- If Overall is FAIL: call `reject_qa(story_id='{{story_id}}', notes='<concise reason>')` via MCP so the coder knows exactly what to fix
+
 ## Rules
 - Do NOT modify any code — read-only review only
-- If the server fails to start, still provide the testing plan with curl commands
+- Gates must pass before AC review — a gate failure is an automatic reject
-- The server automatically runs acceptance gates when your process exits"""
+- If any AC is not met, the overall result is FAIL
-system_prompt = "You are a QA agent. Your job is read-only: review code quality, run tests, try to start the server, and produce a structured QA report. Do not modify code. The server automatically runs acceptance gates when your process exits."
+- Always call approve_qa or reject_qa — never leave the story without a verdict"""
+system_prompt = "You are a QA agent. Your job is read-only: run quality gates, verify each acceptance criterion against the diff, and produce a structured QA report. Always call approve_qa or reject_qa via MCP to record your verdict. Do not modify code."
 
 [[agent]]
 name = "coder-opus"
@@ -140,30 +173,52 @@ system_prompt = "You are a senior full-stack engineer working autonomously in a
 [[agent]]
 name = "qa"
 stage = "qa"
-role = "Reviews coder work in worktrees: runs quality gates, generates testing plans, and reports findings."
+role = "Reviews coder work in worktrees: runs quality gates, verifies acceptance criteria, and reports findings."
 model = "sonnet"
 max_turns = 40
 max_budget_usd = 4.00
-prompt = """You are the QA agent for story {{story_id}}. Your job is to review the coder's work in the worktree and produce a structured QA report.
+prompt = """You are the QA agent for story {{story_id}}. Your job is to verify the coder's work satisfies the story's acceptance criteria and produce a structured QA report.
 
 Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
 
 ## Your Workflow
 
-### 1. Code Quality Scan
+### 0. Read the Story
-- Run `git diff master...HEAD --stat` to see what files changed
+- Read the story file at `.storkit/work/3_qa/{{story_id}}.md`
-- Run `git diff master...HEAD` to review the actual changes for obvious coding mistakes (unused imports, dead code, unhandled errors, hardcoded values)
+- Extract every acceptance criterion (the `- [ ]` checkbox lines)
-- Run `cargo clippy --all-targets --all-features` and note any warnings
+- Keep this list in mind for Step 3
+
+### 1. Deterministic Gates (Prerequisites)
+Run these first — if any fail, reject immediately without proceeding to AC review:
+- Run `cargo clippy --all-targets --all-features` — must show 0 errors, 0 warnings
+- Run `cargo test` and verify all tests pass
 - If a `frontend/` directory exists:
   - Run `npm run build` and note any TypeScript errors
   - Run `npx @biomejs/biome check src/` and note any linting issues
+  - Run `npm test` and verify all frontend tests pass
 
-### 2. Test Verification
+### 2. Code Change Review
-- Run `cargo test` and verify all tests pass
+- Run `git diff master...HEAD --stat` to see what files changed
-- If `frontend/` exists: run `npm test` and verify all frontend tests pass
+- Run `git diff master...HEAD` to review the actual changes
-- Review test quality: look for tests that are trivial or don't assert meaningful behavior
+- Flag any incomplete implementations:
+  - `todo!()`, `unimplemented!()`, `panic!()` used as stubs
+  - Placeholder strings like "TODO", "FIXME", "not implemented"
+  - Empty match arms or arms that just return `Default::default()`
+  - Hardcoded values where real logic is expected
+- Note any obvious coding mistakes (unused imports, dead code, unhandled errors)
 
-### 3. Manual Testing Support
+### 3. Acceptance Criteria Review
+For each AC extracted in Step 0:
+- Review the diff and test files to determine if the code addresses this AC
+- PASS: describe specifically how the code addresses it (which file/function/test)
+- FAIL: explain exactly what is missing or incorrect
+
+An AC fails if:
+- No code change or test relates to it
+- The implementation is stubbed out (todo!/unimplemented!)
+- A test exists but doesn't actually assert the behaviour described
+
+### 4. Manual Testing Support (only if all gates PASS and all ACs PASS)
 - Build the server: run `cargo build` and note success/failure
 - If build succeeds: find a free port (try 3010-3020) and attempt to start the server
 - Generate a testing plan including:
@@ -172,8 +227,8 @@ Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
   - curl commands to exercise relevant API endpoints
 - Kill the test server when done: `pkill -f 'target.*storkit' || true` (NEVER use `pkill -f storkit` — it kills the vite dev server)
 
-### 4. Produce Structured Report
+### 5. Produce Structured Report and Verdict
-Print your QA report to stdout before your process exits. The server will automatically run acceptance gates. Use this format:
+Print your QA report to stdout. Then call `approve_qa` or `reject_qa` via the MCP tool based on the overall result. Use this format:
 
 ```
 ## QA Report for {{story_id}}
@@ -182,27 +237,38 @@ Print your QA report to stdout before your process exits. The server will automa
 - clippy: PASS/FAIL (details)
 - TypeScript build: PASS/FAIL/SKIP (details)
 - Biome lint: PASS/FAIL/SKIP (details)
-- Code review findings: (list any issues found, or "None")
-
-### Test Verification
 - cargo test: PASS/FAIL (N tests)
 - npm test: PASS/FAIL/SKIP (N tests)
-- Test quality issues: (list any trivial/weak tests, or "None")
+- Incomplete implementations: (list any todo!/unimplemented!/stubs found, or "None")
+- Other code review findings: (list any issues found, or "None")
+
+### Acceptance Criteria Review
+- AC: <criterion text>
+  Result: PASS/FAIL
+  Evidence: <how the code addresses it, or what is missing>
+
+(repeat for each AC)
 
 ### Manual Testing Plan
-- Server URL: http://localhost:PORT (or "Build failed")
+- Server URL: http://localhost:PORT (or "Skipped — gate/AC failure" or "Build failed")
-- Pages to visit: (list)
+- Pages to visit: (list, or "N/A")
-- Things to check: (list)
+- Things to check: (list, or "N/A")
-- curl commands: (list)
+- curl commands: (list, or "N/A")
 
 ### Overall: PASS/FAIL
+Reason: (summary of why it passed or the primary reason it failed)
 ```
 
+After printing the report:
+- If Overall is PASS: call `approve_qa(story_id='{{story_id}}')` via MCP
+- If Overall is FAIL: call `reject_qa(story_id='{{story_id}}', notes='<concise reason>')` via MCP so the coder knows exactly what to fix
+
 ## Rules
 - Do NOT modify any code — read-only review only
-- If the server fails to start, still provide the testing plan with curl commands
+- Gates must pass before AC review — a gate failure is an automatic reject
-- The server automatically runs acceptance gates when your process exits"""
+- If any AC is not met, the overall result is FAIL
-system_prompt = "You are a QA agent. Your job is read-only: review code quality, run tests, try to start the server, and produce a structured QA report. Do not modify code. The server automatically runs acceptance gates when your process exits."
+- Always call approve_qa or reject_qa — never leave the story without a verdict"""
+system_prompt = "You are a QA agent. Your job is read-only: run quality gates, verify each acceptance criterion against the diff, and produce a structured QA report. Always call approve_qa or reject_qa via MCP to record your verdict. Do not modify code."
 
 [[agent]]
 name = "mergemaster"

.storkit/work/1_backlog/433_story_setup_wizard_interviews_user_on_bare_projects_with_no_existing_code.md

@@ -0,0 +1,23 @@
+---
+name: "Setup wizard interviews user on bare projects with no existing code"
+---
+
+# Story 433: Setup wizard interviews user on bare projects with no existing code
+
+## User Story
+
+As a developer starting a brand new project from an empty directory, I want the setup wizard to ask me what I'm building and what tech stack I plan to use, so that it can generate meaningful CONTEXT.md and STACK.md without any codebase to analyze.
+
+## Acceptance Criteria
+
+- [ ] wizard_generate detects when the project directory has no source code files
+- [ ] On bare projects, the wizard asks the user what they want to build instead of trying to analyze code
+- [ ] Wizard asks about intended tech stack, frameworks, and language choices
+- [ ] Conversation continues until the user confirms the generated CONTEXT.md captures their intent
+- [ ] STACK.md is generated from the user's stated tech choices rather than from codebase detection
+- [ ] script/test and script/release are generated with appropriate stubs for the stated stack
+- [ ] The interview flow works via both MCP tools (Claude Code terminal) and bot commands (Matrix/WhatsApp/Slack)
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/434_story_wizard_auto_checks_completion_on_first_conversation.md

@@ -0,0 +1,20 @@
+---
+name: "Wizard auto-checks completion on first conversation"
+---
+
+# Story 434: Wizard auto-checks completion on first conversation
+
+## User Story
+
+As a developer opening Claude Code on a storkit project for the first time, I want the wizard to automatically check if setup is complete and prompt me through remaining steps, so I don't have to know to ask for it.
+
+## Acceptance Criteria
+
+- [ ] Scaffolded CLAUDE.md includes an IMPORTANT instruction telling Claude to call wizard_status on first conversation
+- [ ] If wizard is incomplete, Claude guides the user through remaining steps without being asked
+- [ ] If wizard is already complete, no wizard prompt appears — Claude behaves normally
+- [ ] Works on both existing projects with code and bare projects with no code
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/435_story_unblock_command_handles_all_stuck_states_not_just_blocked_flag.md

@@ -0,0 +1,21 @@
+---
+name: "Unblock command handles all stuck states not just blocked flag"
+---
+
+# Story 435: Unblock command handles all stuck states not just blocked flag
+
+## User Story
+
+As a project owner, I want the unblock command to clear any stuck state on a story — not just the blocked flag — so that I have a single command to unstick stories regardless of why they're stuck.
+
+## Acceptance Criteria
+
+- [ ] Unblock clears merge_failure field in addition to blocked flag
+- [ ] Unblock clears review_hold field
+- [ ] Unblock reports which fields were cleared in the confirmation message
+- [ ] Unblock works on stories in any pipeline stage (backlog, current, qa, merge, done)
+- [ ] If no stuck state is found (no blocked, merge_failure, or review_hold), returns a clear message saying so
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/436_refactor_unify_story_stuck_states_into_a_single_status_field.md

@@ -0,0 +1,26 @@
+---
+name: "Unify story stuck states into a single status field"
+---
+
+# Refactor 436: Unify story stuck states into a single status field
+
+## Current State
+
+- TBD
+
+## Desired State
+
+Replace the separate blocked, merge_failure, and review_hold front matter fields with a single status field (e.g. status: blocked, status: merge_failure, status: review_hold). Simplifies the unblock command, auto-assign checks, and pipeline advance logic.
+
+## Acceptance Criteria
+
+- [ ] Replace blocked: true, merge_failure: string, and review_hold: true with a single status: field in story front matter
+- [ ] Auto-assign checks a single field instead of three separate ones
+- [ ] Pipeline advance and lifecycle code reads/writes the unified status field
+- [ ] Unblock command clears the status field regardless of which stuck state it was
+- [ ] retry_count remains a separate field (it's a counter, not a state)
+- [ ] Migration: existing stories with old fields are handled gracefully on read
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/430_bug_status_command_traffic_light_dots_not_coloured_in_matrix.md

@@ -0,0 +1,27 @@
+---
+name: "Status command traffic light dots not coloured in Matrix"
+---
+
+# Bug 430: Status command traffic light dots not coloured in Matrix
+
+## Description
+
+The traffic light dots in the status command use plain Unicode characters (○ ● ◑ ✗) which render without colour in Matrix. The HTML formatted_body should use data-mx-color to colour them green/yellow/red.
+
+## How to Reproduce
+
+Send the status command to the bot in Matrix. Observe the dots are monochrome.
+
+## Actual Result
+
+Dots render as plain monochrome Unicode characters.
+
+## Expected Result
+
+Dots render in colour: green (● running), yellow (◑ throttled), red (✗ blocked), grey (○ idle). Use font tag with data-mx-color attribute for Matrix HTML formatted_body.
+
+## Acceptance Criteria
+
+- [ ] HTML formatted_body uses <font data-mx-color="#colour">dot</font> for each traffic light state
+- [ ] Green (#00cc00) for running, yellow (#ffaa00) for throttled, red (#cc0000) for blocked, grey (#888888) for idle
+- [ ] Plain text fallback remains unchanged (Unicode dots for non-HTML transports)

.storkit/work/5_done/431_story_qa_agent_reviews_code_changes_against_acceptance_criteria.md

@@ -0,0 +1,24 @@
+---
+name: "QA agent reviews code changes against acceptance criteria"
+---
+
+# Story 431: QA agent reviews code changes against acceptance criteria
+
+## User Story
+
+As a project owner, I want the QA agent to actually verify that the coder's implementation matches the story's acceptance criteria, so that incomplete or incorrect work is caught before merge.
+
+## Acceptance Criteria
+
+- [ ] QA agent reads the story's acceptance criteria before reviewing code
+- [ ] QA agent reads the full diff against master to understand what changed
+- [ ] For each AC, QA agent verifies the code addresses it and explains how
+- [ ] QA agent flags incomplete implementations: todo!(), unimplemented!(), missing match arms, placeholder values
+- [ ] QA agent checks that new code has corresponding test coverage
+- [ ] QA agent produces a structured report: each AC with pass/fail and explanation
+- [ ] If any AC is not met, QA rejects the story with a clear reason so the coder can fix it
+- [ ] Deterministic gates (clippy, tests) still run as a prerequisite before the AC review
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/432_story_complete_setup_wizard_with_mcp_tools_and_agent_driven_file_generation.md

@@ -0,0 +1,27 @@
+---
+name: "Complete setup wizard with MCP tools and agent-driven file generation"
+agent: "coder-opus"
+---
+
+# Story 432: Complete setup wizard with MCP tools and agent-driven file generation
+
+## User Story
+
+As a developer running storkit init on a new project, I want the setup wizard to walk me through each step interactively — generating files, letting me review them, and confirming before moving on — so that my project is correctly configured without manual file editing.
+
+## Acceptance Criteria
+
+- [ ] MCP tool wizard_status returns the current wizard state: which step is active, which are done/skipped/pending
+- [ ] MCP tool wizard_generate triggers the agent to read the codebase and generate content for the current step (CONTEXT.md, STACK.md, script/test, script/release, script/test_coverage)
+- [ ] MCP tool wizard_confirm confirms the current step and advances to the next
+- [ ] MCP tool wizard_skip skips the current step and advances to the next
+- [ ] MCP tool wizard_retry re-generates content for the current step if the user isn't happy with it
+- [ ] Bot command setup shows wizard progress and the current step with instructions
+- [ ] Bot command setup confirm / setup skip / setup retry drive the wizard from chat
+- [ ] Generated files are written to disk only after user confirmation, not during generation preview
+- [ ] The wizard works from Claude Code terminal via MCP tools without requiring the web UI or chat bot
+- [ ] Existing files (especially CLAUDE.md) are never overwritten — wizard appends or skips
+
+## Out of Scope
+
+- TBD

Cargo.lock

@@ -4019,7 +4019,7 @@ checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
 
 [[package]]
 name = "storkit"
-version = "0.7.1"
+version = "0.8.1"
 dependencies = [
  "async-stream",
  "async-trait",

README.md

@@ -1,6 +1,37 @@
 # Storkit
 
-A story-driven development server that manages work items, spawns coding agents, and runs them through a pipeline from backlog to done. Ships as a single Rust binary with an embedded React frontend. Communicates via Matrix, WhatsApp, and Slack bot transports, and exposes MCP tools for programmatic access.
+A story-driven development server that manages work items, spawns coding agents, and runs them through a pipeline from backlog to done. Ships as a single Rust binary with an embedded React frontend.
+
+## Getting started with Claude Code
+
+1. Download the storkit binary (or build from source — see below).
+
+2. From your project directory, scaffold and start the server:
+
+```bash
+storkit init --port 3000
+```
+
+This creates a `.storkit/` directory with the pipeline structure, `project.toml`, and `.mcp.json`. The `.mcp.json` file lets Claude Code discover storkit's MCP tools automatically.
+
+3. Open a Claude Code session in the same project directory. Claude will pick up the MCP tools from `.mcp.json`.
+
+4. Tell Claude: "help me set up this project with storkit." Claude will walk you through the setup wizard — generating project context, tech stack docs, and test/release scripts. Review each step and confirm or ask to retry.
+
+Once setup is complete, Claude can create stories, start agents, check status, and manage the full pipeline via MCP tools — no commands to memorize.
+
+## Web UI
+
+Storkit also ships an embedded React frontend. Once the server is running, open `http://localhost:3000` to see the pipeline board, agent status, and chat interface.
+
+## Chat transports
+
+Storkit can be controlled via bot commands in **Matrix**, **WhatsApp**, and **Slack**. Configure a transport in `.storkit/bot.toml` — see the example files:
+
+- `.storkit/bot.toml.matrix.example`
+- `.storkit/bot.toml.whatsapp-meta.example`
+- `.storkit/bot.toml.whatsapp-twilio.example`
+- `.storkit/bot.toml.slack.example`
 
 ## Prerequisites
 
@@ -49,7 +80,11 @@ Configuration lives in `.storkit/project.toml`. See `.storkit/bot.toml.*.example
 Requires a Gitea API token in `.env` (`GITEA_TOKEN=your_token`).
 
 ```bash
-script/release 0.6.1
+script/release 0.7.1
 ```
 
 This bumps version in `Cargo.toml` and `package.json`, builds macOS arm64 and Linux amd64 binaries, tags the repo, and publishes a Gitea release with changelog and binaries attached.
+
+## License
+
+GPL-3.0. See [LICENSE](LICENSE).

frontend/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "living-spec-standalone",
-	"version": "0.7.1",
+	"version": "0.8.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "living-spec-standalone",
-			"version": "0.7.1",
+			"version": "0.8.1",
 			"dependencies": {
 				"@types/react-syntax-highlighter": "^15.5.13",
 				"react": "^19.1.0",

frontend/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "living-spec-standalone",
 	"private": true,
-	"version": "0.7.1",
+	"version": "0.8.1",
 	"type": "module",
 	"scripts": {
 		"dev": "vite",

frontend/src/api/client.ts

@@ -21,6 +21,19 @@ export type WsRequest =
 			config: ProviderConfig;
 	  };
 
+export interface WizardStepInfo {
+	step: string;
+	label: string;
+	status: string;
+	content?: string;
+}
+
+export interface WizardStateData {
+	steps: WizardStepInfo[];
+	current_step_index: number;
+	completed: boolean;
+}
+
 export interface AgentAssignment {
 	agent_name: string;
 	model: string | null;
@@ -80,6 +93,13 @@ export type WsResponse =
 	| { type: "pong" }
 	/** Sent on connect when the project still needs onboarding (specs are placeholders). */
 	| { type: "onboarding_status"; needs_onboarding: boolean }
+	/** Sent on connect when a setup wizard is active. */
+	| {
+			type: "wizard_state";
+			steps: WizardStepInfo[];
+			current_step_index: number;
+			completed: boolean;
+	  }
 	/** Streaming thinking token from an extended-thinking block, separate from regular text. */
 	| { type: "thinking_token"; content: string }
 	/** Streaming token from a /btw side question response. */
@@ -438,6 +458,7 @@ export class ChatWebSocket {
 	private onAgentConfigChanged?: () => void;
 	private onAgentStateChanged?: () => void;
 	private onOnboardingStatus?: (needsOnboarding: boolean) => void;
+	private onWizardState?: (state: WizardStateData) => void;
 	private onSideQuestionToken?: (content: string) => void;
 	private onSideQuestionDone?: (response: string) => void;
 	private onLogEntry?: (
@@ -528,6 +549,12 @@ export class ChatWebSocket {
 				if (data.type === "agent_state_changed") this.onAgentStateChanged?.();
 				if (data.type === "onboarding_status")
 					this.onOnboardingStatus?.(data.needs_onboarding);
+				if (data.type === "wizard_state")
+					this.onWizardState?.({
+						steps: data.steps,
+						current_step_index: data.current_step_index,
+						completed: data.completed,
+					});
 				if (data.type === "side_question_token")
 					this.onSideQuestionToken?.(data.content);
 				if (data.type === "side_question_done")
@@ -587,6 +614,7 @@ export class ChatWebSocket {
 			onAgentConfigChanged?: () => void;
 			onAgentStateChanged?: () => void;
 			onOnboardingStatus?: (needsOnboarding: boolean) => void;
+			onWizardState?: (state: WizardStateData) => void;
 			onSideQuestionToken?: (content: string) => void;
 			onSideQuestionDone?: (response: string) => void;
 			onLogEntry?: (timestamp: string, level: string, message: string) => void;
@@ -606,6 +634,7 @@ export class ChatWebSocket {
 		this.onAgentConfigChanged = handlers.onAgentConfigChanged;
 		this.onAgentStateChanged = handlers.onAgentStateChanged;
 		this.onOnboardingStatus = handlers.onOnboardingStatus;
+		this.onWizardState = handlers.onWizardState;
 		this.onSideQuestionToken = handlers.onSideQuestionToken;
 		this.onSideQuestionDone = handlers.onSideQuestionDone;
 		this.onLogEntry = handlers.onLogEntry;

frontend/src/components/Chat.tsx

@@ -4,7 +4,11 @@ import { Prism as SyntaxHighlighter } from "react-syntax-highlighter";
 import { oneDark } from "react-syntax-highlighter/dist/esm/styles/prism";
 import type { AgentConfigInfo } from "../api/agents";
 import { agentsApi } from "../api/agents";
-import type { AnthropicModelInfo, PipelineState } from "../api/client";
+import type {
+	AnthropicModelInfo,
+	PipelineState,
+	WizardStateData,
+} from "../api/client";
 import { api, ChatWebSocket } from "../api/client";
 import { useChatHistory } from "../hooks/useChatHistory";
 import type { Message, ProviderConfig } from "../types";
@@ -17,6 +21,7 @@ import { LozengeFlyProvider } from "./LozengeFlyContext";
 import { MessageItem } from "./MessageItem";
 import type { LogEntry } from "./ServerLogsPanel";
 import { ServerLogsPanel } from "./ServerLogsPanel";
+import SetupWizard from "./SetupWizard";
 import { SideQuestionOverlay } from "./SideQuestionOverlay";
 import { StagePanel } from "./StagePanel";
 import { WorkItemDetailPanel } from "./WorkItemDetailPanel";
@@ -217,6 +222,7 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 		new Map(),
 	);
 	const [needsOnboarding, setNeedsOnboarding] = useState(false);
+	const [wizardState, setWizardState] = useState<WizardStateData | null>(null);
 	const onboardingTriggeredRef = useRef(false);
 	const [selectedWorkItemId, setSelectedWorkItemId] = useState<string | null>(
 		null,
@@ -466,6 +472,9 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 			onOnboardingStatus: (onboarding: boolean) => {
 				setNeedsOnboarding(onboarding);
 			},
+			onWizardState: (state: WizardStateData) => {
+				setWizardState(state);
+			},
 			onSideQuestionToken: (content) => {
 				setSideQuestion((prev) =>
 					prev ? { ...prev, response: prev.response + content } : prev,
@@ -978,7 +987,20 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 								gap: "24px",
 							}}
 						>
-							{needsOnboarding && messages.length === 0 && !loading && (
+							{wizardState &&
+								!wizardState.completed &&
+								messages.length === 0 &&
+								!loading && (
+									<SetupWizard
+										wizardState={wizardState}
+										onWizardUpdate={setWizardState}
+										sendMessage={sendMessage}
+									/>
+								)}
+							{needsOnboarding &&
+								!wizardState &&
+								messages.length === 0 &&
+								!loading && (
 									<div
 										data-testid="onboarding-welcome"
 										style={{
@@ -1005,9 +1027,9 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 												lineHeight: 1.5,
 											}}
 										>
-										This project needs to be set up before you can start writing
+											This project needs to be set up before you can start
-										stories. The agent will guide you through configuring your
+											writing stories. The agent will guide you through
-										project goals and tech stack.
+											configuring your project goals and tech stack.
 										</p>
 										<button
 											type="button"

frontend/src/components/SetupWizard.tsx

@@ -0,0 +1,354 @@
+import { useCallback, useState } from "react";
+import type { WizardStateData, WizardStepInfo } from "../api/client";
+
+const API_BASE = "/api";
+
+interface SetupWizardProps {
+	wizardState: WizardStateData;
+	onWizardUpdate: (state: WizardStateData) => void;
+	sendMessage: (message: string) => void;
+}
+
+/** Style constants for the wizard UI. */
+const STEP_BG_PENDING = "#1a1f2e";
+const STEP_BG_ACTIVE = "#1c2a1c";
+const STEP_BG_DONE = "#1a2a1a";
+const STEP_BORDER_PENDING = "#2a2f3e";
+const STEP_BORDER_ACTIVE = "#2d4a2d";
+const STEP_BORDER_DONE = "#2d4a2d";
+const COLOR_LABEL = "#ccc";
+const COLOR_LABEL_DONE = "#a0d4a0";
+const COLOR_ACCENT = "#a0d4a0";
+
+function statusIcon(status: string): string {
+	switch (status) {
+		case "confirmed":
+			return "\u2713";
+		case "skipped":
+			return "\u2013";
+		case "generating":
+			return "\u2026";
+		case "awaiting_confirmation":
+			return "?";
+		default:
+			return "\u00B7";
+	}
+}
+
+function stepBackground(status: string, isActive: boolean): string {
+	if (status === "confirmed" || status === "skipped") return STEP_BG_DONE;
+	if (isActive) return STEP_BG_ACTIVE;
+	return STEP_BG_PENDING;
+}
+
+function stepBorder(status: string, isActive: boolean): string {
+	if (status === "confirmed" || status === "skipped") return STEP_BORDER_DONE;
+	if (isActive) return STEP_BORDER_ACTIVE;
+	return STEP_BORDER_PENDING;
+}
+
+/** Messages sent to the chat to trigger agent generation for each step. */
+const STEP_PROMPTS: Record<string, string> = {
+	context:
+		"Read the codebase and generate .storkit/specs/00_CONTEXT.md with a project context spec. Include High-Level Goal, Core Features, Domain Definition, and Glossary sections. Then call the wizard API to store the content: PUT /api/wizard/step/context/content",
+	stack:
+		"Read the tech stack and generate .storkit/specs/tech/STACK.md with a tech stack spec. Include Core Stack, Coding Standards, Quality Gates, and Libraries sections. Then call the wizard API to store the content: PUT /api/wizard/step/stack/content",
+	test_script:
+		"Read the project structure and create script/test — a bash script that runs the project's actual test suite. Then call the wizard API: PUT /api/wizard/step/test_script/content",
+	release_script:
+		"Read the project's deployment setup and create script/release tailored to the project. Then call the wizard API: PUT /api/wizard/step/release_script/content",
+	test_coverage:
+		"If the stack supports coverage reporting, create script/test_coverage. Then call the wizard API: PUT /api/wizard/step/test_coverage/content",
+};
+
+async function apiPost(path: string): Promise<WizardStateData | null> {
+	try {
+		const resp = await fetch(`${API_BASE}${path}`, { method: "POST" });
+		if (!resp.ok) return null;
+		return (await resp.json()) as WizardStateData;
+	} catch {
+		return null;
+	}
+}
+
+function StepCard({
+	step,
+	isActive,
+	onGenerate,
+	onConfirm,
+	onSkip,
+}: {
+	step: WizardStepInfo;
+	isActive: boolean;
+	onGenerate: () => void;
+	onConfirm: () => void;
+	onSkip: () => void;
+}) {
+	const isDone = step.status === "confirmed" || step.status === "skipped";
+
+	return (
+		<div
+			data-testid={`wizard-step-${step.step}`}
+			style={{
+				padding: "16px",
+				borderRadius: "8px",
+				background: stepBackground(step.status, isActive),
+				border: `1px solid ${stepBorder(step.status, isActive)}`,
+				opacity: !isActive && !isDone ? 0.5 : 1,
+				transition: "all 0.2s ease",
+			}}
+		>
+			<div
+				style={{
+					display: "flex",
+					alignItems: "center",
+					gap: "12px",
+				}}
+			>
+				<span
+					style={{
+						width: "24px",
+						height: "24px",
+						borderRadius: "50%",
+						display: "flex",
+						alignItems: "center",
+						justifyContent: "center",
+						fontSize: "14px",
+						fontWeight: 600,
+						background: isDone ? COLOR_ACCENT : "transparent",
+						border: isDone ? "none" : `1px solid ${COLOR_LABEL}`,
+						color: isDone ? "#1a1a1a" : COLOR_LABEL,
+					}}
+				>
+					{statusIcon(step.status)}
+				</span>
+				<span
+					style={{
+						flex: 1,
+						color: isDone ? COLOR_LABEL_DONE : COLOR_LABEL,
+						fontWeight: isActive ? 600 : 400,
+					}}
+				>
+					{step.label}
+				</span>
+				{isActive && step.status === "pending" && (
+					<button
+						type="button"
+						data-testid={`wizard-generate-${step.step}`}
+						onClick={onGenerate}
+						style={{
+							padding: "6px 14px",
+							borderRadius: "6px",
+							border: "none",
+							backgroundColor: COLOR_ACCENT,
+							color: "#1a1a1a",
+							cursor: "pointer",
+							fontSize: "0.85rem",
+							fontWeight: 600,
+						}}
+					>
+						Generate
+					</button>
+				)}
+				{isActive && step.status === "generating" && (
+					<span style={{ color: "#aaa", fontSize: "0.85rem" }}>
+						Generating...
+					</span>
+				)}
+			</div>
+
+			{step.content && step.status === "awaiting_confirmation" && (
+				<div style={{ marginTop: "12px" }}>
+					<pre
+						data-testid={`wizard-preview-${step.step}`}
+						style={{
+							background: "#111",
+							padding: "12px",
+							borderRadius: "6px",
+							fontSize: "0.8rem",
+							color: "#ddd",
+							whiteSpace: "pre-wrap",
+							maxHeight: "200px",
+							overflow: "auto",
+							margin: "0 0 12px 0",
+						}}
+					>
+						{step.content}
+					</pre>
+					<div style={{ display: "flex", gap: "8px" }}>
+						<button
+							type="button"
+							data-testid={`wizard-confirm-${step.step}`}
+							onClick={onConfirm}
+							style={{
+								padding: "6px 14px",
+								borderRadius: "6px",
+								border: "none",
+								backgroundColor: COLOR_ACCENT,
+								color: "#1a1a1a",
+								cursor: "pointer",
+								fontSize: "0.85rem",
+								fontWeight: 600,
+							}}
+						>
+							Confirm
+						</button>
+						<button
+							type="button"
+							data-testid={`wizard-revise-${step.step}`}
+							onClick={onGenerate}
+							style={{
+								padding: "6px 14px",
+								borderRadius: "6px",
+								border: "1px solid #555",
+								backgroundColor: "transparent",
+								color: "#ccc",
+								cursor: "pointer",
+								fontSize: "0.85rem",
+							}}
+						>
+							Revise
+						</button>
+						<button
+							type="button"
+							data-testid={`wizard-skip-${step.step}`}
+							onClick={onSkip}
+							style={{
+								padding: "6px 14px",
+								borderRadius: "6px",
+								border: "1px solid #555",
+								backgroundColor: "transparent",
+								color: "#888",
+								cursor: "pointer",
+								fontSize: "0.85rem",
+							}}
+						>
+							Skip
+						</button>
+					</div>
+				</div>
+			)}
+
+			{isActive && step.status === "pending" && !step.content && (
+				<div style={{ marginTop: "8px", display: "flex", gap: "8px" }}>
+					<button
+						type="button"
+						data-testid={`wizard-skip-${step.step}`}
+						onClick={onSkip}
+						style={{
+							padding: "4px 10px",
+							borderRadius: "6px",
+							border: "1px solid #444",
+							backgroundColor: "transparent",
+							color: "#888",
+							cursor: "pointer",
+							fontSize: "0.8rem",
+						}}
+					>
+						Skip this step
+					</button>
+				</div>
+			)}
+		</div>
+	);
+}
+
+export default function SetupWizard({
+	wizardState,
+	onWizardUpdate,
+	sendMessage,
+}: SetupWizardProps) {
+	const [, setRefreshKey] = useState(0);
+
+	const handleGenerate = useCallback(
+		(step: WizardStepInfo) => {
+			const prompt = STEP_PROMPTS[step.step];
+			if (prompt) {
+				sendMessage(prompt);
+			}
+		},
+		[sendMessage],
+	);
+
+	const handleConfirm = useCallback(
+		async (step: WizardStepInfo) => {
+			const result = await apiPost(`/wizard/step/${step.step}/confirm`);
+			if (result) {
+				onWizardUpdate(result);
+				setRefreshKey((k) => k + 1);
+			}
+		},
+		[onWizardUpdate],
+	);
+
+	const handleSkip = useCallback(
+		async (step: WizardStepInfo) => {
+			const result = await apiPost(`/wizard/step/${step.step}/skip`);
+			if (result) {
+				onWizardUpdate(result);
+				setRefreshKey((k) => k + 1);
+			}
+		},
+		[onWizardUpdate],
+	);
+
+	if (wizardState.completed) {
+		return (
+			<div
+				data-testid="wizard-complete"
+				style={{
+					padding: "24px",
+					borderRadius: "12px",
+					background: STEP_BG_DONE,
+					border: `1px solid ${STEP_BORDER_DONE}`,
+					textAlign: "center",
+				}}
+			>
+				<h3 style={{ margin: "0 0 8px 0", color: COLOR_ACCENT }}>
+					Setup Complete
+				</h3>
+				<p style={{ margin: 0, color: COLOR_LABEL }}>
+					Your project is configured. You can start writing stories.
+				</p>
+			</div>
+		);
+	}
+
+	return (
+		<div
+			data-testid="setup-wizard"
+			style={{
+				display: "flex",
+				flexDirection: "column",
+				gap: "12px",
+			}}
+		>
+			<div style={{ marginBottom: "8px" }}>
+				<h3
+					style={{
+						margin: "0 0 4px 0",
+						color: COLOR_ACCENT,
+						fontSize: "1.1rem",
+					}}
+				>
+					Project Setup Wizard
+				</h3>
+				<p style={{ margin: 0, color: "#999", fontSize: "0.85rem" }}>
+					Step {wizardState.current_step_index + 1} of{" "}
+					{wizardState.steps.length}
+				</p>
+			</div>
+
+			{wizardState.steps.map((step, idx) => (
+				<StepCard
+					key={step.step}
+					step={step}
+					isActive={idx === wizardState.current_step_index}
+					onGenerate={() => handleGenerate(step)}
+					onConfirm={() => handleConfirm(step)}
+					onSkip={() => handleSkip(step)}
+				/>
+			))}
+		</div>
+	);
+}

server/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "storkit"
-version = "0.7.1"
+version = "0.8.1"
 edition = "2024"
 build = "build.rs"
 

server/src/agents/merge.rs

@@ -247,7 +247,7 @@ pub(crate) fn run_squash_merge(
             .output()
             .map_err(|e| format!("Failed to check merge diff: {e}"))?;
         let changed_files = String::from_utf8_lossy(&diff_check.stdout);
-        let has_code_changes = changed_files.lines().any(|f| !f.starts_with(".storkit/"));
+        let has_code_changes = changed_files.lines().any(|f| !f.starts_with(".storkit/work/"));
         if !has_code_changes {
             all_output.push_str(
                 "=== Merge commit contains only .storkit/ file moves, no code changes ===\n",
@@ -419,9 +419,10 @@ pub(crate) fn run_squash_merge(
     }
 
     // Verify HEAD commit has actual code changes (not an empty cherry-pick).
-    // Exclude .storkit/ so that story-file-only commits don't pass this check.
+    // Exclude .storkit/work/ (pipeline file moves) but keep .storkit/project.toml
+    // and other config files which are legitimate deliverables.
     let diff_stat = Command::new("git")
-        .args(["diff", "--stat", "HEAD~1..HEAD", "--", ".", ":(exclude).storkit"])
+        .args(["diff", "--stat", "HEAD~1..HEAD", "--", ".", ":(exclude).storkit/work"])
         .current_dir(project_root)
         .output()
         .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())

server/src/chat/commands/mod.rs

@@ -13,6 +13,7 @@ mod help;
 pub(crate) mod loc;
 mod move_story;
 mod overview;
+mod setup;
 mod show;
 mod status;
 mod timer;
@@ -177,9 +178,62 @@ pub fn commands() -> &'static [BotCommand] {
             description: "Show stories merged to master since the last release tag",
             handler: unreleased::handle_unreleased,
         },
+        BotCommand {
+            name: "setup",
+            description: "Show setup wizard progress; or `setup confirm` / `setup skip` / `setup retry` to drive the wizard from chat",
+            handler: setup::handle_setup,
+        },
     ]
 }
 
+/// Like [`try_handle_command`] but returns `(plain_body, html_body)`.
+///
+/// The plain body is unchanged Markdown text suitable for the Matrix `body`
+/// field (non-HTML clients). The HTML body is suitable for `formatted_body`.
+///
+/// The pipeline-status command (no args) injects Matrix `<font data-mx-color>`
+/// tags on the traffic-light dots. All other commands produce HTML by running
+/// the plain body through pulldown-cmark.
+pub fn try_handle_command_with_html(
+    dispatch: &CommandDispatch<'_>,
+    message: &str,
+) -> Option<(String, String)> {
+    let command_text = strip_bot_mention(message, dispatch.bot_name, dispatch.bot_user_id);
+    let trimmed = command_text.trim();
+    if !trimmed.is_empty() {
+        let (cmd_name, args) = match trimmed.split_once(char::is_whitespace) {
+            Some((c, a)) => (c, a.trim()),
+            None => (trimmed, ""),
+        };
+        // Only the no-arg status variant shows the pipeline with traffic-light
+        // dots; `status <number>` is a triage dump that needs no colour tags.
+        if cmd_name.eq_ignore_ascii_case("status") && args.is_empty() {
+            let body = status::build_pipeline_status(dispatch.project_root, dispatch.agents);
+            let html = status::build_pipeline_status_html(dispatch.project_root, dispatch.agents);
+            return Some((body, html));
+        }
+    }
+    // Generic path: plain text body → Markdown-to-HTML.
+    let body = try_handle_command(dispatch, message)?;
+    let html = plain_to_html(&body);
+    Some((body, html))
+}
+
+/// Convert a Markdown string to HTML using the same options as the Matrix
+/// transport's `markdown_to_html` helper.
+fn plain_to_html(markdown: &str) -> String {
+    use pulldown_cmark::{Options, Parser, html};
+    let normalized = crate::chat::util::normalize_line_breaks(markdown);
+    let options = Options::ENABLE_TABLES
+        | Options::ENABLE_FOOTNOTES
+        | Options::ENABLE_STRIKETHROUGH
+        | Options::ENABLE_TASKLISTS;
+    let parser = Parser::new_ext(&normalized, options);
+    let mut out = String::new();
+    html::push_html(&mut out, parser);
+    out
+}
+
 /// Try to match a user message against a registered bot command.
 ///
 /// The message is expected to be the raw body text (e.g., `"@timmy help"`).

server/src/chat/commands/setup.rs

@@ -0,0 +1,266 @@
+//! Handler for the `setup` bot command.
+//!
+//! Drives the setup wizard from any chat transport (Matrix, Slack, WhatsApp).
+//!
+//! Usage:
+//! - `setup`         — show wizard progress and current step instructions
+//! - `setup confirm` — confirm the current step (writes staged content to disk)
+//! - `setup skip`    — skip the current step
+//! - `setup retry`   — discard staged content and reset the current step
+
+use super::CommandContext;
+use crate::http::mcp::wizard_tools::{is_script_step, step_output_path, write_if_missing};
+use crate::io::wizard::{format_wizard_state, StepStatus, WizardState};
+
+pub(super) fn handle_setup(ctx: &CommandContext) -> Option<String> {
+    let sub = ctx.args.trim().to_ascii_lowercase();
+
+    match sub.as_str() {
+        "" => Some(wizard_status_reply(ctx)),
+        "confirm" => Some(wizard_confirm_reply(ctx)),
+        "skip" => Some(wizard_skip_reply(ctx)),
+        "retry" => Some(wizard_retry_reply(ctx)),
+        _ => Some(format!(
+            "Unknown sub-command `{sub}`. Usage: `setup`, `setup confirm`, `setup skip`, `setup retry`."
+        )),
+    }
+}
+
+/// Compose a status reply for the `setup` command (no args).
+fn wizard_status_reply(ctx: &CommandContext) -> String {
+    match WizardState::load(ctx.project_root) {
+        Some(state) => format_wizard_state(&state),
+        None => {
+            "No setup wizard active. Run `storkit init` in the project root to begin.".to_string()
+        }
+    }
+}
+
+/// Confirm the current wizard step, writing any staged content to disk.
+fn wizard_confirm_reply(ctx: &CommandContext) -> String {
+    let root = ctx.project_root;
+    let mut state = match WizardState::load(root) {
+        Some(s) => s,
+        None => return "No wizard active.".to_string(),
+    };
+    if state.completed {
+        return "Wizard is already complete.".to_string();
+    }
+
+    let idx = state.current_step_index();
+    let step = state.steps[idx].step;
+    let content = state.steps[idx].content.clone();
+
+    // Write content to disk (only if a file path exists and the file is absent).
+    let write_msg =
+        if let (Some(c), Some(ref path)) = (&content, step_output_path(root, step)) {
+            let executable = is_script_step(step);
+            match write_if_missing(path, c, executable) {
+                Ok(true) => format!(" File written: `{}`.", path.display()),
+                Ok(false) => format!(" File `{}` already exists — skipped.", path.display()),
+                Err(e) => return format!("Error: {e}"),
+            }
+        } else {
+            String::new()
+        };
+
+    if let Err(e) = state.confirm_step(step) {
+        return format!("Cannot confirm step: {e}");
+    }
+    if let Err(e) = state.save(root) {
+        return format!("Failed to save wizard state: {e}");
+    }
+
+    if state.completed {
+        format!(
+            "Step '{}' confirmed.{write_msg}\n\nSetup wizard complete!",
+            step.label()
+        )
+    } else {
+        let next = &state.steps[state.current_step_index()];
+        format!(
+            "Step '{}' confirmed.{write_msg}\n\nNext: {} — run `wizard_generate` to begin.",
+            step.label(),
+            next.step.label()
+        )
+    }
+}
+
+/// Skip the current wizard step without writing any file.
+fn wizard_skip_reply(ctx: &CommandContext) -> String {
+    let root = ctx.project_root;
+    let mut state = match WizardState::load(root) {
+        Some(s) => s,
+        None => return "No wizard active.".to_string(),
+    };
+    if state.completed {
+        return "Wizard is already complete.".to_string();
+    }
+
+    let idx = state.current_step_index();
+    let step = state.steps[idx].step;
+
+    if let Err(e) = state.skip_step(step) {
+        return format!("Cannot skip step: {e}");
+    }
+    if let Err(e) = state.save(root) {
+        return format!("Failed to save wizard state: {e}");
+    }
+
+    if state.completed {
+        format!(
+            "Step '{}' skipped. Setup wizard complete!",
+            step.label()
+        )
+    } else {
+        let next = &state.steps[state.current_step_index()];
+        format!(
+            "Step '{}' skipped.\n\nNext: {} — run `wizard_generate` to begin.",
+            step.label(),
+            next.step.label()
+        )
+    }
+}
+
+/// Discard staged content and reset the current step to pending.
+fn wizard_retry_reply(ctx: &CommandContext) -> String {
+    let root = ctx.project_root;
+    let mut state = match WizardState::load(root) {
+        Some(s) => s,
+        None => return "No wizard active.".to_string(),
+    };
+    if state.completed {
+        return "Wizard is already complete.".to_string();
+    }
+
+    let idx = state.current_step_index();
+    let step = state.steps[idx].step;
+
+    if let Some(s) = state.steps.iter_mut().find(|s| s.step == step) {
+        s.status = StepStatus::Pending;
+        s.content = None;
+    }
+    if let Err(e) = state.save(root) {
+        return format!("Failed to save wizard state: {e}");
+    }
+
+    format!(
+        "Step '{}' reset to pending. Run `wizard_generate` to regenerate content.",
+        step.label()
+    )
+}
+
+// ── tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::io::wizard::WizardState;
+    use std::collections::HashSet;
+    use std::sync::{Arc, Mutex};
+    use tempfile::TempDir;
+
+    fn make_ctx<'a>(
+        args: &'a str,
+        project_root: &'a std::path::Path,
+        agents: &'a Arc<crate::agents::AgentPool>,
+        ambient_rooms: &'a Arc<Mutex<HashSet<String>>>,
+    ) -> CommandContext<'a> {
+        CommandContext {
+            bot_name: "Bot",
+            args,
+            project_root,
+            agents,
+            ambient_rooms,
+            room_id: "!test:example.com",
+        }
+    }
+
+    #[test]
+    fn setup_no_wizard_returns_helpful_message() {
+        let dir = TempDir::new().unwrap();
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4000));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("storkit init"));
+    }
+
+    #[test]
+    fn setup_with_wizard_shows_status() {
+        let dir = TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join(".storkit")).unwrap();
+        WizardState::init_if_missing(dir.path());
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4001));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("Setup wizard"));
+    }
+
+    #[test]
+    fn setup_skip_advances_wizard() {
+        let dir = TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join(".storkit")).unwrap();
+        WizardState::init_if_missing(dir.path());
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4002));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("skip", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("skipped"));
+        let state = WizardState::load(dir.path()).unwrap();
+        assert_eq!(state.current_step_index(), 2);
+    }
+
+    #[test]
+    fn setup_confirm_advances_wizard() {
+        let dir = TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join(".storkit")).unwrap();
+        WizardState::init_if_missing(dir.path());
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4003));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("confirm", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("confirmed"));
+        let state = WizardState::load(dir.path()).unwrap();
+        assert_eq!(state.current_step_index(), 2);
+    }
+
+    #[test]
+    fn setup_retry_resets_step() {
+        let dir = TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join(".storkit")).unwrap();
+        WizardState::init_if_missing(dir.path());
+        // Stage some content first.
+        {
+            let mut state = WizardState::load(dir.path()).unwrap();
+            state.set_step_status(
+                crate::io::wizard::WizardStep::Context,
+                crate::io::wizard::StepStatus::AwaitingConfirmation,
+                Some("content".to_string()),
+            );
+            state.save(dir.path()).unwrap();
+        }
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4004));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("retry", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("reset"));
+        let state = WizardState::load(dir.path()).unwrap();
+        assert_eq!(
+            state.steps[1].status,
+            crate::io::wizard::StepStatus::Pending
+        );
+    }
+
+    #[test]
+    fn setup_unknown_sub_command_returns_usage() {
+        let dir = TempDir::new().unwrap();
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4005));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("foobar", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("Unknown sub-command"));
+        assert!(result.contains("Usage"));
+    }
+}

server/src/chat/commands/status.rs

@@ -122,6 +122,34 @@ fn read_stage_items(
     items
 }
 
+/// Build the HTML `formatted_body` for the pipeline status with Matrix colour
+/// tags on the traffic-light dots.
+///
+/// Converts the plain-text pipeline status (Markdown) to HTML via
+/// pulldown-cmark and wraps each traffic-light character in a
+/// `<font data-mx-color="#rrggbb">` tag so Matrix clients display them in
+/// colour.
+pub(super) fn build_pipeline_status_html(project_root: &std::path::Path, agents: &AgentPool) -> String {
+    use pulldown_cmark::{Options, Parser, html};
+
+    let plain = build_pipeline_status(project_root, agents);
+    let normalized = crate::chat::util::normalize_line_breaks(&plain);
+    let options = Options::ENABLE_TABLES
+        | Options::ENABLE_FOOTNOTES
+        | Options::ENABLE_STRIKETHROUGH
+        | Options::ENABLE_TASKLISTS;
+    let parser = Parser::new_ext(&normalized, options);
+    let mut html_out = String::new();
+    html::push_html(&mut html_out, parser);
+
+    // Wrap each traffic-light character with a Matrix colour tag.
+    html_out
+        .replace('\u{2717}', "<font data-mx-color=\"#cc0000\">\u{2717}</font>") // ✗ blocked
+        .replace('\u{25D1}', "<font data-mx-color=\"#ffaa00\">\u{25D1}</font>") // ◑ throttled
+        .replace('\u{25CF}', "<font data-mx-color=\"#00cc00\">\u{25CF}</font>") // ● running
+        .replace('\u{25CB}', "<font data-mx-color=\"#888888\">\u{25CB}</font>") // ○ idle
+}
+
 /// Build the full pipeline status text formatted for Matrix (markdown).
 pub(super) fn build_pipeline_status(project_root: &std::path::Path, agents: &AgentPool) -> String {
     // Build a map from story_id → active AgentInfo for quick lookup.
@@ -444,6 +472,81 @@ mod tests {
 
     // -- traffic_light_dot --------------------------------------------------
 
+    // -- build_pipeline_status_html (colored dots) --------------------------
+
+    #[test]
+    fn html_status_colors_idle_dot_grey() {
+        use std::io::Write;
+        use tempfile::TempDir;
+
+        let tmp = TempDir::new().unwrap();
+        let stage_dir = tmp.path().join(".storkit/work/2_current");
+        std::fs::create_dir_all(&stage_dir).unwrap();
+
+        let story_path = stage_dir.join("42_story_idle.md");
+        let mut f = std::fs::File::create(&story_path).unwrap();
+        writeln!(f, "---\nname: Idle Story\n---\n").unwrap();
+
+        let agents = AgentPool::new_test(3000);
+        let html = build_pipeline_status_html(tmp.path(), &agents);
+
+        assert!(
+            html.contains("<font data-mx-color=\"#888888\">\u{25CB}</font>"),
+            "idle dot should be grey (#888888): {html}"
+        );
+    }
+
+    #[test]
+    fn html_status_colors_blocked_dot_red() {
+        use std::io::Write;
+        use tempfile::TempDir;
+
+        let tmp = TempDir::new().unwrap();
+        let stage_dir = tmp.path().join(".storkit/work/2_current");
+        std::fs::create_dir_all(&stage_dir).unwrap();
+
+        let story_path = stage_dir.join("42_story_blocked.md");
+        let mut f = std::fs::File::create(&story_path).unwrap();
+        writeln!(f, "---\nname: Blocked Story\nblocked: true\n---\n").unwrap();
+
+        let agents = AgentPool::new_test(3000);
+        let html = build_pipeline_status_html(tmp.path(), &agents);
+
+        assert!(
+            html.contains("<font data-mx-color=\"#cc0000\">\u{2717}</font>"),
+            "blocked dot should be red (#cc0000): {html}"
+        );
+    }
+
+    #[test]
+    fn html_status_plain_text_body_unchanged() {
+        use std::io::Write;
+        use tempfile::TempDir;
+
+        let tmp = TempDir::new().unwrap();
+        let stage_dir = tmp.path().join(".storkit/work/2_current");
+        std::fs::create_dir_all(&stage_dir).unwrap();
+
+        let story_path = stage_dir.join("42_story_idle.md");
+        let mut f = std::fs::File::create(&story_path).unwrap();
+        writeln!(f, "---\nname: Idle Story\n---\n").unwrap();
+
+        let agents = AgentPool::new_test(3000);
+        let plain = build_pipeline_status(tmp.path(), &agents);
+
+        // Plain text must still use bare Unicode dots (no HTML tags).
+        assert!(
+            plain.contains('\u{25CB}'),
+            "plain text should have bare Unicode idle dot: {plain}"
+        );
+        assert!(
+            !plain.contains("data-mx-color"),
+            "plain text must not contain HTML colour attributes: {plain}"
+        );
+    }
+
+    // -- traffic_light_dot --------------------------------------------------
+
     #[test]
     fn dot_idle_when_no_agent() {
         assert_eq!(traffic_light_dot(false, false, false), "\u{25CB} "); // ○

server/src/chat/commands/unblock.rs

@@ -98,16 +98,28 @@ pub(crate) fn unblock_by_path(path: &Path, story_id: &str) -> String {
 
     let story_name = meta.name.as_deref().unwrap_or(story_id).to_string();
 
-    if meta.blocked != Some(true) {
+    let has_blocked = meta.blocked == Some(true);
+    let has_merge_failure = meta.merge_failure.is_some();
+
+    if !has_blocked && !has_merge_failure {
         return format!(
             "**{story_name}** ({story_id}) is not blocked. Nothing to unblock."
         );
     }
 
-    // Clear the blocked flag (reads + writes the file).
+    // Clear the blocked flag if present.
+    if has_blocked {
         if let Err(e) = clear_front_matter_field(path, "blocked") {
             return format!("Failed to clear blocked flag on **{story_id}**: {e}");
         }
+    }
+
+    // Clear merge_failure if present.
+    if has_merge_failure {
+        if let Err(e) = clear_front_matter_field(path, "merge_failure") {
+            return format!("Failed to clear merge_failure on **{story_id}**: {e}");
+        }
+    }
 
     // Reset retry_count to 0 (re-read the updated file, modify, write).
     let updated_contents = match std::fs::read_to_string(path) {
@@ -119,7 +131,10 @@ pub(crate) fn unblock_by_path(path: &Path, story_id: &str) -> String {
         return format!("Failed to reset retry_count on **{story_id}**: {e}");
     }
 
-    format!("Unblocked **{story_name}** ({story_id}). Retry count reset to 0.")
+    let mut cleared = Vec::new();
+    if has_blocked { cleared.push("blocked"); }
+    if has_merge_failure { cleared.push("merge_failure"); }
+    format!("Unblocked **{story_name}** ({story_id}). Cleared: {}. Retry count reset to 0.", cleared.join(", "))
 }
 
 // ---------------------------------------------------------------------------

server/src/chat/transport/matrix/bot/messages.rs

@@ -186,10 +186,9 @@ pub(super) async fn on_room_message(
         ambient_rooms: &ctx.ambient_rooms,
         room_id: &room_id_str,
     };
-    if let Some(response) = super::super::commands::try_handle_command(&dispatch, &user_message) {
+    if let Some((response, response_html)) = super::super::commands::try_handle_command_with_html(&dispatch, &user_message) {
         slog!("[matrix-bot] Handled bot command from {sender}");
-        let html = markdown_to_html(&response);
+        if let Ok(msg_id) = ctx.transport.send_message(&room_id_str, &response, &response_html).await
-        if let Ok(msg_id) = ctx.transport.send_message(&room_id_str, &response, &html).await
             && let Ok(event_id) = msg_id.parse()
         {
             ctx.bot_sent_event_ids.lock().await.insert(event_id);

server/src/http/mcp/mod.rs

@@ -14,8 +14,9 @@ pub mod git_tools;
 pub mod merge_tools;
 pub mod qa_tools;
 pub mod shell_tools;
-pub mod story_tools;
 pub mod status_tools;
+pub mod story_tools;
+pub mod wizard_tools;
 
 /// Returns true when the Accept header includes text/event-stream.
 fn wants_sse(req: &Request) -> bool {
@@ -1164,6 +1165,51 @@ fn handle_tools_list(id: Option<Value>) -> JsonRpcResponse {
                         },
                         "required": ["file_path"]
                     }
+                },
+                {
+                    "name": "wizard_status",
+                    "description": "Return the current setup wizard state: which step is active, and which are done/skipped/pending. Use this to inspect progress before calling wizard_generate, wizard_confirm, wizard_skip, or wizard_retry.",
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {}
+                    }
+                },
+                {
+                    "name": "wizard_generate",
+                    "description": "Drive content generation for the current wizard step. Call with no arguments to mark the step as 'generating' and receive a hint about what to produce. Call again with a 'content' argument (the full file body you generated) to stage it for review. Content is NOT written to disk until wizard_confirm is called.",
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {
+                            "content": {
+                                "type": "string",
+                                "description": "The generated file content to stage for the current step. Omit to receive a generation hint and mark the step as generating."
+                            }
+                        }
+                    }
+                },
+                {
+                    "name": "wizard_confirm",
+                    "description": "Confirm the current wizard step: writes any staged content to disk (only if the target file does not already exist) and advances to the next step. Existing files are never overwritten.",
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {}
+                    }
+                },
+                {
+                    "name": "wizard_skip",
+                    "description": "Skip the current wizard step without writing any file. Use when a step does not apply to this project.",
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {}
+                    }
+                },
+                {
+                    "name": "wizard_retry",
+                    "description": "Discard any staged content for the current wizard step and reset it to pending so it can be regenerated. Use when the generated content needs improvement.",
+                    "inputSchema": {
+                        "type": "object",
+                        "properties": {}
+                    }
                 }
             ]
         }),
@@ -1258,6 +1304,12 @@ async fn handle_tools_call(
         "status" => status_tools::tool_status(&args, ctx).await,
         // File line count
         "loc_file" => diagnostics::tool_loc_file(&args, ctx),
+        // Setup wizard tools
+        "wizard_status" => wizard_tools::tool_wizard_status(ctx),
+        "wizard_generate" => wizard_tools::tool_wizard_generate(&args, ctx),
+        "wizard_confirm" => wizard_tools::tool_wizard_confirm(ctx),
+        "wizard_skip" => wizard_tools::tool_wizard_skip(ctx),
+        "wizard_retry" => wizard_tools::tool_wizard_retry(ctx),
         _ => Err(format!("Unknown tool: {tool_name}")),
     };
 
@@ -1376,7 +1428,7 @@ mod tests {
         assert!(names.contains(&"git_log"));
         assert!(names.contains(&"status"));
         assert!(names.contains(&"loc_file"));
-        assert_eq!(tools.len(), 51);
+        assert_eq!(tools.len(), 56);
     }
 
     #[test]

server/src/http/mcp/wizard_tools.rs

@@ -0,0 +1,521 @@
+//! MCP tool implementations for the interactive setup wizard.
+//!
+//! These tools allow Claude Code (and other MCP clients) to drive the setup
+//! wizard entirely from the terminal without requiring the web UI or chat bot.
+//!
+//! Typical flow:
+//! 1. `wizard_status`  — inspect current state
+//! 2. `wizard_generate` — read the codebase and call again with `content` to
+//!    stage generated text for review
+//! 3. `wizard_confirm`  — write staged content to disk and advance the wizard
+//! 4. `wizard_skip`     — skip a step that does not apply
+//! 5. `wizard_retry`    — discard staged content and regenerate from scratch
+
+use crate::http::context::AppContext;
+use crate::io::wizard::{StepStatus, WizardState, WizardStep, format_wizard_state};
+use serde_json::Value;
+use std::fs;
+use std::path::Path;
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+/// Return the filesystem path (relative to `project_root`) for a step's output.
+///
+/// Returns `None` for `Scaffold` since that step has no single output file — it
+/// creates the full `.storkit/` directory structure and is handled by
+/// `storkit init` before the server starts.
+pub(crate) fn step_output_path(project_root: &Path, step: WizardStep) -> Option<std::path::PathBuf> {
+    match step {
+        WizardStep::Context => Some(
+            project_root
+                .join(".storkit")
+                .join("specs")
+                .join("00_CONTEXT.md"),
+        ),
+        WizardStep::Stack => Some(
+            project_root
+                .join(".storkit")
+                .join("specs")
+                .join("tech")
+                .join("STACK.md"),
+        ),
+        WizardStep::TestScript => Some(project_root.join("script").join("test")),
+        WizardStep::ReleaseScript => Some(project_root.join("script").join("release")),
+        WizardStep::TestCoverage => Some(project_root.join("script").join("test_coverage")),
+        WizardStep::Scaffold => None,
+    }
+}
+
+pub(crate) fn is_script_step(step: WizardStep) -> bool {
+    matches!(
+        step,
+        WizardStep::TestScript | WizardStep::ReleaseScript | WizardStep::TestCoverage
+    )
+}
+
+/// Write `content` to `path` only when the file does not already exist.
+///
+/// Existing files (including `CLAUDE.md`) are never overwritten — the wizard
+/// appends or skips per the acceptance criteria.  For script steps the file is
+/// also made executable after writing.
+pub(crate) fn write_if_missing(path: &Path, content: &str, executable: bool) -> Result<bool, String> {
+    if path.exists() {
+        return Ok(false); // already present — skip silently
+    }
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent)
+            .map_err(|e| format!("Failed to create directory {}: {e}", parent.display()))?;
+    }
+    fs::write(path, content)
+        .map_err(|e| format!("Failed to write {}: {e}", path.display()))?;
+
+    if executable {
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            let mut perms = fs::metadata(path)
+                .map_err(|e| format!("Failed to read permissions: {e}"))?
+                .permissions();
+            perms.set_mode(0o755);
+            fs::set_permissions(path, perms)
+                .map_err(|e| format!("Failed to set permissions: {e}"))?;
+        }
+    }
+
+    Ok(true)
+}
+
+/// Serialise a `WizardStep` to its snake_case string (e.g. `"test_script"`).
+fn step_slug(step: WizardStep) -> String {
+    serde_json::to_value(step)
+        .ok()
+        .and_then(|v| v.as_str().map(String::from))
+        .unwrap_or_default()
+}
+
+// ── MCP tool handlers ─────────────────────────────────────────────────────────
+
+/// `wizard_status` — return current wizard state as a human-readable summary.
+pub(super) fn tool_wizard_status(ctx: &AppContext) -> Result<String, String> {
+    let root = ctx.state.get_project_root()?;
+    let state =
+        WizardState::load(&root).ok_or("No wizard active. Run `storkit init` to begin setup.")?;
+    Ok(format_wizard_state(&state))
+}
+
+/// `wizard_generate` — mark the current step as generating or stage content.
+///
+/// Call with no `content` argument to mark the step as `Generating` and
+/// receive a hint describing what to generate.  Call again with a `content`
+/// argument (the generated file body) to stage it for review; the step will
+/// transition to `AwaitingConfirmation`.  Content is **not** written to disk
+/// until `wizard_confirm` is called.
+pub(super) fn tool_wizard_generate(args: &Value, ctx: &AppContext) -> Result<String, String> {
+    let root = ctx.state.get_project_root()?;
+    let mut state = WizardState::load(&root).ok_or("No wizard active.")?;
+
+    if state.completed {
+        return Ok("Wizard is already complete.".to_string());
+    }
+
+    let current_idx = state.current_step_index();
+    let step = state.steps[current_idx].step;
+
+    // If content is provided, stage it for confirmation.
+    if let Some(content) = args.get("content").and_then(|v| v.as_str()) {
+        state.set_step_status(
+            step,
+            StepStatus::AwaitingConfirmation,
+            Some(content.to_string()),
+        );
+        state
+            .save(&root)
+            .map_err(|e| format!("Failed to save wizard state: {e}"))?;
+        return Ok(format!(
+            "Content staged for '{}'. Run `wizard_confirm` to write it to disk, `wizard_retry` to regenerate, or `wizard_skip` to skip.",
+            step.label()
+        ));
+    }
+
+    // No content provided — mark as generating and return a hint.
+    state.set_step_status(step, StepStatus::Generating, None);
+    state
+        .save(&root)
+        .map_err(|e| format!("Failed to save wizard state: {e}"))?;
+
+    let hint = generation_hint(step, &root);
+    let slug = step_slug(step);
+
+    Ok(format!(
+        "Step '{}' marked as generating.\n\n{hint}\n\nOnce you have the content, call `wizard_generate` again with a `content` argument (or PUT /wizard/step/{slug}/content). Then call `wizard_confirm` to write it to disk.",
+        step.label(),
+    ))
+}
+
+/// Return true if the project directory has no meaningful source files.
+fn is_bare_project(project_root: &Path) -> bool {
+    let dominated_by_storkit = std::fs::read_dir(project_root)
+        .ok()
+        .map(|entries| {
+            let names: Vec<String> = entries
+                .filter_map(|e| e.ok())
+                .map(|e| e.file_name().to_string_lossy().to_string())
+                .collect();
+            // A bare project only has storkit scaffolding and no real code
+            names.iter().all(|n| {
+                n.starts_with('.')
+                    || n == "CLAUDE.md"
+                    || n == "LICENSE"
+                    || n == "README.md"
+                    || n == "script"
+                    || n == "store.json"
+            })
+        })
+        .unwrap_or(true);
+    dominated_by_storkit
+}
+
+/// Return a generation hint for a step based on the project root.
+fn generation_hint(step: WizardStep, project_root: &Path) -> String {
+    let bare = is_bare_project(project_root);
+
+    match step {
+        WizardStep::Context => {
+            if bare {
+                "This is a bare project with no existing code. Ask the user what they want \
+                 to build — the project's purpose, goals, target users, and key features. \
+                 Then generate `.storkit/specs/00_CONTEXT.md` from their answers covering:\n\
+                 - High-level goal of the project\n\
+                 - Core features\n\
+                 - Domain concepts and entities\n\
+                 - Glossary of abbreviations and technical terms".to_string()
+            } else {
+                "Read the project source tree and generate a `.storkit/specs/00_CONTEXT.md` describing:\n\
+                 - High-level goal of the project\n\
+                 - Core features\n\
+                 - Domain concepts and entities\n\
+                 - Glossary of abbreviations and technical terms".to_string()
+            }
+        }
+        WizardStep::Stack => {
+            if bare {
+                "This is a bare project with no existing code. Ask the user what language, \
+                 frameworks, and tools they plan to use. Then generate `.storkit/specs/tech/STACK.md` \
+                 from their answers covering:\n\
+                 - Language, frameworks, and runtimes\n\
+                 - Coding standards and linting rules\n\
+                 - Quality gates (commands that must pass before merging)\n\
+                 - Approved libraries and their purpose".to_string()
+            } else {
+                "Read the project source tree and generate a `.storkit/specs/tech/STACK.md` describing:\n\
+                 - Language, frameworks, and runtimes\n\
+                 - Coding standards and linting rules\n\
+                 - Quality gates (commands that must pass before merging)\n\
+                 - Approved libraries and their purpose".to_string()
+            }
+        }
+        WizardStep::TestScript => {
+            let has_cargo = project_root.join("Cargo.toml").exists();
+            let has_pkg = project_root.join("package.json").exists();
+            let has_pnpm = project_root.join("pnpm-lock.yaml").exists();
+            let mut cmds = Vec::new();
+            if has_cargo {
+                cmds.push("cargo nextest run");
+            }
+            if has_pkg {
+                cmds.push(if has_pnpm { "pnpm test" } else { "npm test" });
+            }
+            if cmds.is_empty() {
+                "Generate a `script/test` shell script (#!/usr/bin/env bash, set -euo pipefail) that runs the project's test suite.".to_string()
+            } else {
+                format!(
+                    "Generate a `script/test` shell script (#!/usr/bin/env bash, set -euo pipefail) that runs: {}",
+                    cmds.join(", ")
+                )
+            }
+        }
+        WizardStep::ReleaseScript => {
+            "Generate a `script/release` shell script (#!/usr/bin/env bash, set -euo pipefail) that builds and releases the project (e.g. `cargo build --release` or `npm run build`).".to_string()
+        }
+        WizardStep::TestCoverage => {
+            "Generate a `script/test_coverage` shell script (#!/usr/bin/env bash, set -euo pipefail) that generates a test coverage report (e.g. `cargo llvm-cov nextest` or `npm run coverage`).".to_string()
+        }
+        WizardStep::Scaffold => "Scaffold step is handled automatically by `storkit init`.".to_string(),
+    }
+}
+
+/// `wizard_confirm` — confirm the current step and write its content to disk.
+///
+/// If the step has staged content, the content is written to its target file
+/// (only if that file does not already exist — existing files are never
+/// overwritten).  The step is then marked as `Confirmed` and the wizard
+/// advances to the next pending step.
+pub(super) fn tool_wizard_confirm(ctx: &AppContext) -> Result<String, String> {
+    let root = ctx.state.get_project_root()?;
+    let mut state = WizardState::load(&root).ok_or("No wizard active.")?;
+
+    if state.completed {
+        return Ok("Wizard is already complete.".to_string());
+    }
+
+    let current_idx = state.current_step_index();
+    let step = state.steps[current_idx].step;
+    let content = state.steps[current_idx].content.clone();
+
+    // Write content to disk (only if a file path exists and the file is absent).
+    let write_msg = if let (Some(c), Some(ref path)) = (&content, step_output_path(&root, step)) {
+        let executable = is_script_step(step);
+        match write_if_missing(path, c, executable)? {
+            true => format!(" File written: `{}`.", path.display()),
+            false => format!(" File `{}` already exists — skipped.", path.display()),
+        }
+    } else {
+        String::new()
+    };
+
+    state
+        .confirm_step(step)
+        .map_err(|e| format!("Cannot confirm step: {e}"))?;
+    state
+        .save(&root)
+        .map_err(|e| format!("Failed to save wizard state: {e}"))?;
+
+    let next_idx = state.current_step_index();
+    if state.completed {
+        Ok(format!(
+            "Step '{}' confirmed.{write_msg}\n\nSetup wizard complete! All steps done.",
+            step.label()
+        ))
+    } else {
+        let next = &state.steps[next_idx];
+        Ok(format!(
+            "Step '{}' confirmed.{write_msg}\n\nNext: {} — run `wizard_generate` to begin.",
+            step.label(),
+            next.step.label()
+        ))
+    }
+}
+
+/// `wizard_skip` — skip the current step without writing any file.
+pub(super) fn tool_wizard_skip(ctx: &AppContext) -> Result<String, String> {
+    let root = ctx.state.get_project_root()?;
+    let mut state = WizardState::load(&root).ok_or("No wizard active.")?;
+
+    if state.completed {
+        return Ok("Wizard is already complete.".to_string());
+    }
+
+    let current_idx = state.current_step_index();
+    let step = state.steps[current_idx].step;
+
+    state
+        .skip_step(step)
+        .map_err(|e| format!("Cannot skip step: {e}"))?;
+    state
+        .save(&root)
+        .map_err(|e| format!("Failed to save wizard state: {e}"))?;
+
+    let next_idx = state.current_step_index();
+    if state.completed {
+        Ok(format!(
+            "Step '{}' skipped. Setup wizard complete!",
+            step.label()
+        ))
+    } else {
+        let next = &state.steps[next_idx];
+        Ok(format!(
+            "Step '{}' skipped.\n\nNext: {} — run `wizard_generate` to begin.",
+            step.label(),
+            next.step.label()
+        ))
+    }
+}
+
+/// `wizard_retry` — discard staged content and reset the current step to
+/// `Pending` so it can be regenerated.
+pub(super) fn tool_wizard_retry(ctx: &AppContext) -> Result<String, String> {
+    let root = ctx.state.get_project_root()?;
+    let mut state = WizardState::load(&root).ok_or("No wizard active.")?;
+
+    if state.completed {
+        return Ok("Wizard is already complete.".to_string());
+    }
+
+    let current_idx = state.current_step_index();
+    let step = state.steps[current_idx].step;
+
+    // Clear content and reset to pending.
+    if let Some(s) = state.steps.iter_mut().find(|s| s.step == step) {
+        s.status = StepStatus::Pending;
+        s.content = None;
+    }
+    state
+        .save(&root)
+        .map_err(|e| format!("Failed to save wizard state: {e}"))?;
+
+    Ok(format!(
+        "Step '{}' reset to pending. Run `wizard_generate` to regenerate content.",
+        step.label()
+    ))
+}
+
+// ── tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::http::context::AppContext;
+    use tempfile::TempDir;
+
+    fn setup(dir: &TempDir) -> AppContext {
+        let root = dir.path().to_path_buf();
+        std::fs::create_dir_all(root.join(".storkit")).unwrap();
+        WizardState::init_if_missing(&root);
+        AppContext::new_test(root)
+    }
+
+    #[test]
+    fn wizard_status_returns_state() {
+        let dir = TempDir::new().unwrap();
+        let ctx = setup(&dir);
+        let result = tool_wizard_status(&ctx).unwrap();
+        assert!(result.contains("Setup wizard"));
+        assert!(result.contains("context"));
+    }
+
+    #[test]
+    fn wizard_status_no_wizard_returns_error() {
+        let dir = TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join(".storkit")).unwrap();
+        let ctx = AppContext::new_test(dir.path().to_path_buf());
+        assert!(tool_wizard_status(&ctx).is_err());
+    }
+
+    #[test]
+    fn wizard_generate_marks_generating() {
+        let dir = TempDir::new().unwrap();
+        let ctx = setup(&dir);
+        let result = tool_wizard_generate(&serde_json::json!({}), &ctx).unwrap();
+        assert!(result.contains("generating"));
+        let state = WizardState::load(dir.path()).unwrap();
+        assert_eq!(state.steps[1].status, StepStatus::Generating);
+    }
+
+    #[test]
+    fn wizard_generate_with_content_stages_content() {
+        let dir = TempDir::new().unwrap();
+        let ctx = setup(&dir);
+        let result = tool_wizard_generate(
+            &serde_json::json!({"content": "# My Project"}),
+            &ctx,
+        )
+        .unwrap();
+        assert!(result.contains("staged"));
+        let state = WizardState::load(dir.path()).unwrap();
+        assert_eq!(state.steps[1].status, StepStatus::AwaitingConfirmation);
+        assert_eq!(state.steps[1].content.as_deref(), Some("# My Project"));
+    }
+
+    #[test]
+    fn wizard_confirm_writes_file_and_advances() {
+        let dir = TempDir::new().unwrap();
+        let ctx = setup(&dir);
+        // Stage content for Context step.
+        tool_wizard_generate(
+            &serde_json::json!({"content": "# Context content"}),
+            &ctx,
+        )
+        .unwrap();
+        let result = tool_wizard_confirm(&ctx).unwrap();
+        assert!(result.contains("confirmed"));
+        // File should now exist.
+        let context_path = dir
+            .path()
+            .join(".storkit")
+            .join("specs")
+            .join("00_CONTEXT.md");
+        assert!(context_path.exists());
+        assert_eq!(
+            std::fs::read_to_string(&context_path).unwrap(),
+            "# Context content"
+        );
+        // Wizard should have advanced.
+        let state = WizardState::load(dir.path()).unwrap();
+        assert_eq!(state.steps[1].status, StepStatus::Confirmed);
+        assert_eq!(state.current_step_index(), 2);
+    }
+
+    #[test]
+    fn wizard_confirm_does_not_overwrite_existing_file() {
+        let dir = TempDir::new().unwrap();
+        let ctx = setup(&dir);
+        // Pre-create the specs directory and file.
+        let specs_dir = dir.path().join(".storkit").join("specs");
+        std::fs::create_dir_all(&specs_dir).unwrap();
+        let context_path = specs_dir.join("00_CONTEXT.md");
+        std::fs::write(&context_path, "original content").unwrap();
+
+        // Stage and confirm — existing file should NOT be overwritten.
+        tool_wizard_generate(
+            &serde_json::json!({"content": "new content"}),
+            &ctx,
+        )
+        .unwrap();
+        let result = tool_wizard_confirm(&ctx).unwrap();
+        assert!(result.contains("already exists"));
+        assert_eq!(
+            std::fs::read_to_string(&context_path).unwrap(),
+            "original content"
+        );
+    }
+
+    #[test]
+    fn wizard_skip_advances_wizard() {
+        let dir = TempDir::new().unwrap();
+        let ctx = setup(&dir);
+        let result = tool_wizard_skip(&ctx).unwrap();
+        assert!(result.contains("skipped"));
+        let state = WizardState::load(dir.path()).unwrap();
+        assert_eq!(state.steps[1].status, StepStatus::Skipped);
+        assert_eq!(state.current_step_index(), 2);
+    }
+
+    #[test]
+    fn wizard_retry_resets_to_pending() {
+        let dir = TempDir::new().unwrap();
+        let ctx = setup(&dir);
+        // Stage content first.
+        tool_wizard_generate(
+            &serde_json::json!({"content": "some content"}),
+            &ctx,
+        )
+        .unwrap();
+        let result = tool_wizard_retry(&ctx).unwrap();
+        assert!(result.contains("reset"));
+        let state = WizardState::load(dir.path()).unwrap();
+        assert_eq!(state.steps[1].status, StepStatus::Pending);
+        assert!(state.steps[1].content.is_none());
+    }
+
+    #[test]
+    fn wizard_complete_returns_done_message() {
+        let dir = TempDir::new().unwrap();
+        let ctx = setup(&dir);
+        // Skip all remaining steps.
+        for _ in 0..5 {
+            tool_wizard_skip(&ctx).unwrap();
+        }
+        let result = tool_wizard_status(&ctx).unwrap();
+        assert!(result.contains("complete"));
+    }
+
+    #[test]
+    fn format_wizard_state_shows_all_steps() {
+        let mut state = WizardState::default();
+        state.steps[0].status = StepStatus::Confirmed;
+        let output = format_wizard_state(&state);
+        assert!(output.contains("✓"));
+        assert!(output.contains("Scaffold"));
+        assert!(output.contains("← current"));
+    }
+}

server/src/http/mod.rs

@@ -14,6 +14,7 @@ pub mod settings;
 pub mod workflow;
 
 pub mod project;
+pub mod wizard;
 pub mod ws;
 
 use agents::AgentsApi;
@@ -131,6 +132,7 @@ type ApiTuple = (
     SettingsApi,
     HealthApi,
     BotCommandApi,
+    wizard::WizardApi,
 );
 
 type ApiService = OpenApiService<ApiTuple, ()>;
@@ -147,6 +149,7 @@ pub fn build_openapi_service(ctx: Arc<AppContext>) -> (ApiService, ApiService) {
         SettingsApi { ctx: ctx.clone() },
         HealthApi,
         BotCommandApi { ctx: ctx.clone() },
+        wizard::WizardApi { ctx: ctx.clone() },
     );
 
     let api_service =
@@ -161,7 +164,8 @@ pub fn build_openapi_service(ctx: Arc<AppContext>) -> (ApiService, ApiService) {
         AgentsApi { ctx: ctx.clone() },
         SettingsApi { ctx: ctx.clone() },
         HealthApi,
-        BotCommandApi { ctx },
+        BotCommandApi { ctx: ctx.clone() },
+        wizard::WizardApi { ctx },
     );
 
     let docs_service =

server/src/http/wizard.rs

@@ -0,0 +1,303 @@
+use crate::http::context::{AppContext, OpenApiResult, bad_request, not_found};
+use crate::io::wizard::{StepStatus, WizardState, WizardStep};
+use poem_openapi::{Object, OpenApi, Tags, param::Path, payload::Json};
+use serde::{Deserialize, Serialize};
+use std::sync::Arc;
+
+#[derive(Tags)]
+enum WizardTags {
+    Wizard,
+}
+
+/// Response for a single wizard step.
+#[derive(Serialize, Object)]
+struct StepResponse {
+    step: String,
+    label: String,
+    status: String,
+    #[oai(skip_serializing_if = "Option::is_none")]
+    content: Option<String>,
+}
+
+/// Full wizard state response.
+#[derive(Serialize, Object)]
+struct WizardResponse {
+    steps: Vec<StepResponse>,
+    current_step_index: usize,
+    completed: bool,
+}
+
+/// Request body for confirming/skipping a step or submitting content.
+#[derive(Deserialize, Object)]
+struct StepActionPayload {
+    /// Optional content to store for the step (e.g., generated spec).
+    #[oai(skip_serializing_if = "Option::is_none")]
+    content: Option<String>,
+}
+
+impl From<&WizardState> for WizardResponse {
+    fn from(state: &WizardState) -> Self {
+        WizardResponse {
+            steps: state
+                .steps
+                .iter()
+                .map(|s| StepResponse {
+                    step: serde_json::to_value(s.step)
+                        .ok()
+                        .and_then(|v| v.as_str().map(String::from))
+                        .unwrap_or_default(),
+                    label: s.step.label().to_string(),
+                    status: serde_json::to_value(&s.status)
+                        .ok()
+                        .and_then(|v| v.as_str().map(String::from))
+                        .unwrap_or_default(),
+                    content: s.content.clone(),
+                })
+                .collect(),
+            current_step_index: state.current_step_index(),
+            completed: state.completed,
+        }
+    }
+}
+
+fn parse_step(step_str: &str) -> Result<WizardStep, poem::Error> {
+    let quoted = format!("\"{step_str}\"");
+    serde_json::from_str::<WizardStep>(&quoted)
+        .map_err(|_| not_found(format!("Unknown wizard step: {step_str}")))
+}
+
+pub struct WizardApi {
+    pub ctx: Arc<AppContext>,
+}
+
+#[OpenApi(tag = "WizardTags::Wizard")]
+impl WizardApi {
+    /// Get the current wizard state.
+    ///
+    /// Returns the full setup wizard progress including all steps and their
+    /// statuses. Returns 404 if no wizard is active.
+    #[oai(path = "/wizard", method = "get")]
+    async fn get_wizard_state(&self) -> OpenApiResult<Json<WizardResponse>> {
+        let root = self.ctx.state.get_project_root().map_err(bad_request)?;
+        let state =
+            WizardState::load(&root).ok_or_else(|| not_found("No wizard active".to_string()))?;
+        Ok(Json(WizardResponse::from(&state)))
+    }
+
+    /// Set a step's content and mark it as awaiting confirmation.
+    ///
+    /// Used after the agent generates content for a step. The content is
+    /// stored for preview and the step is marked as awaiting user confirmation.
+    #[oai(path = "/wizard/step/:step/content", method = "put")]
+    async fn set_step_content(
+        &self,
+        step: Path<String>,
+        payload: Json<StepActionPayload>,
+    ) -> OpenApiResult<Json<WizardResponse>> {
+        let root = self.ctx.state.get_project_root().map_err(bad_request)?;
+        let wizard_step = parse_step(&step.0)?;
+        let mut state =
+            WizardState::load(&root).ok_or_else(|| not_found("No wizard active".to_string()))?;
+
+        state.set_step_status(
+            wizard_step,
+            StepStatus::AwaitingConfirmation,
+            payload.0.content,
+        );
+        state.save(&root).map_err(bad_request)?;
+
+        Ok(Json(WizardResponse::from(&state)))
+    }
+
+    /// Confirm a step and advance to the next.
+    ///
+    /// The step must be the current active step. Returns the updated wizard state.
+    #[oai(path = "/wizard/step/:step/confirm", method = "post")]
+    async fn confirm_step(&self, step: Path<String>) -> OpenApiResult<Json<WizardResponse>> {
+        let root = self.ctx.state.get_project_root().map_err(bad_request)?;
+        let wizard_step = parse_step(&step.0)?;
+        let mut state =
+            WizardState::load(&root).ok_or_else(|| not_found("No wizard active".to_string()))?;
+
+        state.confirm_step(wizard_step).map_err(bad_request)?;
+        state.save(&root).map_err(bad_request)?;
+
+        Ok(Json(WizardResponse::from(&state)))
+    }
+
+    /// Skip a step and advance to the next.
+    ///
+    /// The step must be the current active step.
+    #[oai(path = "/wizard/step/:step/skip", method = "post")]
+    async fn skip_step(&self, step: Path<String>) -> OpenApiResult<Json<WizardResponse>> {
+        let root = self.ctx.state.get_project_root().map_err(bad_request)?;
+        let wizard_step = parse_step(&step.0)?;
+        let mut state =
+            WizardState::load(&root).ok_or_else(|| not_found("No wizard active".to_string()))?;
+
+        state.skip_step(wizard_step).map_err(bad_request)?;
+        state.save(&root).map_err(bad_request)?;
+
+        Ok(Json(WizardResponse::from(&state)))
+    }
+
+    /// Mark a step as generating (agent is working on it).
+    #[oai(path = "/wizard/step/:step/generating", method = "post")]
+    async fn mark_generating(&self, step: Path<String>) -> OpenApiResult<Json<WizardResponse>> {
+        let root = self.ctx.state.get_project_root().map_err(bad_request)?;
+        let wizard_step = parse_step(&step.0)?;
+        let mut state =
+            WizardState::load(&root).ok_or_else(|| not_found("No wizard active".to_string()))?;
+
+        state.set_step_status(wizard_step, StepStatus::Generating, None);
+        state.save(&root).map_err(bad_request)?;
+
+        Ok(Json(WizardResponse::from(&state)))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::http::context::AppContext;
+    use poem::http::StatusCode;
+    use poem::test::TestClient;
+    use poem_openapi::OpenApiService;
+    use tempfile::TempDir;
+
+    fn setup() -> (TempDir, TestClient<impl poem::Endpoint>) {
+        let dir = TempDir::new().unwrap();
+        let root = dir.path().to_path_buf();
+        std::fs::create_dir_all(root.join(".storkit")).unwrap();
+
+        let ctx = Arc::new(AppContext::new_test(root.clone()));
+        let api = WizardApi { ctx };
+        let service = OpenApiService::new(api, "test", "0.1.0");
+        let client = TestClient::new(service);
+        (dir, client)
+    }
+
+    #[tokio::test]
+    async fn get_wizard_returns_404_when_no_wizard() {
+        let (_dir, client) = setup();
+        let resp = client.get("/wizard").send().await;
+        resp.assert_status(StatusCode::NOT_FOUND);
+    }
+
+    #[tokio::test]
+    async fn get_wizard_returns_state_when_active() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        let resp = client.get("/wizard").send().await;
+        resp.assert_status_is_ok();
+        let body: serde_json::Value = resp.0.into_body().into_json().await.unwrap();
+        assert_eq!(body["current_step_index"], 1);
+        assert!(!body["completed"].as_bool().unwrap());
+        assert_eq!(body["steps"].as_array().unwrap().len(), 6);
+        assert_eq!(body["steps"][0]["status"], "confirmed");
+    }
+
+    #[tokio::test]
+    async fn confirm_step_advances_wizard() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        let resp = client.post("/wizard/step/context/confirm").send().await;
+        resp.assert_status_is_ok();
+        let body: serde_json::Value = resp.0.into_body().into_json().await.unwrap();
+        assert_eq!(body["current_step_index"], 2);
+        assert_eq!(body["steps"][1]["status"], "confirmed");
+    }
+
+    #[tokio::test]
+    async fn confirm_wrong_step_returns_error() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        // Try to confirm step 3 (stack) when current is step 2 (context)
+        let resp = client.post("/wizard/step/stack/confirm").send().await;
+        resp.assert_status(StatusCode::BAD_REQUEST);
+    }
+
+    #[tokio::test]
+    async fn skip_step_advances_wizard() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        let resp = client.post("/wizard/step/context/skip").send().await;
+        resp.assert_status_is_ok();
+        let body: serde_json::Value = resp.0.into_body().into_json().await.unwrap();
+        assert_eq!(body["steps"][1]["status"], "skipped");
+        assert_eq!(body["current_step_index"], 2);
+    }
+
+    #[tokio::test]
+    async fn set_step_content_marks_awaiting_confirmation() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        let resp = client
+            .put("/wizard/step/context/content")
+            .body_json(&serde_json::json!({
+                "content": "# My Project\n\nA great project."
+            }))
+            .send()
+            .await;
+        resp.assert_status_is_ok();
+        let body: serde_json::Value = resp.0.into_body().into_json().await.unwrap();
+        assert_eq!(body["steps"][1]["status"], "awaiting_confirmation");
+        assert_eq!(
+            body["steps"][1]["content"],
+            "# My Project\n\nA great project."
+        );
+    }
+
+    #[tokio::test]
+    async fn mark_generating_updates_step() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        let resp = client
+            .post("/wizard/step/context/generating")
+            .send()
+            .await;
+        resp.assert_status_is_ok();
+        let body: serde_json::Value = resp.0.into_body().into_json().await.unwrap();
+        assert_eq!(body["steps"][1]["status"], "generating");
+    }
+
+    #[tokio::test]
+    async fn unknown_step_returns_404() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        let resp = client
+            .post("/wizard/step/nonexistent/confirm")
+            .send()
+            .await;
+        resp.assert_status(StatusCode::NOT_FOUND);
+    }
+
+    #[tokio::test]
+    async fn full_wizard_flow_completes() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        // Steps 2-6 (scaffold is already confirmed)
+        let steps = ["context", "stack", "test_script", "release_script", "test_coverage"];
+        for step in steps {
+            let resp = client
+                .post(format!("/wizard/step/{step}/confirm"))
+                .send()
+                .await;
+            resp.assert_status_is_ok();
+        }
+
+        // Check final state
+        let resp = client.get("/wizard").send().await;
+        resp.assert_status_is_ok();
+        let body: serde_json::Value = resp.0.into_body().into_json().await.unwrap();
+        assert!(body["completed"].as_bool().unwrap());
+    }
+}

server/src/http/ws.rs

@@ -2,6 +2,7 @@ use crate::http::context::{AppContext, PermissionDecision};
 use crate::http::workflow::{PipelineState, load_pipeline_state};
 use crate::io::onboarding;
 use crate::io::watcher::WatcherEvent;
+use crate::io::wizard;
 use crate::llm::chat;
 use crate::llm::types::Message;
 use crate::log_buffer;
@@ -46,6 +47,16 @@ enum WsRequest {
     },
 }
 
+/// Serialisable summary of a single wizard step for WebSocket broadcast.
+#[derive(Serialize, Clone)]
+pub struct WizardStepInfo {
+    pub step: String,
+    pub label: String,
+    pub status: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub content: Option<String>,
+}
+
 #[derive(Serialize)]
 #[serde(tag = "type", rename_all = "snake_case")]
 /// WebSocket response messages sent by the server.
@@ -125,6 +136,13 @@ enum WsResponse {
     OnboardingStatus {
         needs_onboarding: bool,
     },
+    /// Sent on connect when a setup wizard is active. Contains the full
+    /// wizard state so the frontend can render the step-by-step UI.
+    WizardState {
+        steps: Vec<WizardStepInfo>,
+        current_step_index: usize,
+        completed: bool,
+    },
     /// Streaming token from a `/btw` side question response.
     SideQuestionToken {
         content: String,
@@ -219,6 +237,35 @@ pub async fn ws_handler(ws: WebSocket, ctx: Data<&Arc<AppContext>>) -> impl poem
             });
         }
 
+        // Push wizard state if an active wizard exists.
+        {
+            if let Ok(root) = ctx.state.get_project_root()
+                && let Some(ws) = wizard::WizardState::load(&root)
+            {
+                let steps: Vec<WizardStepInfo> = ws
+                    .steps
+                    .iter()
+                    .map(|s| WizardStepInfo {
+                        step: serde_json::to_value(s.step)
+                            .ok()
+                            .and_then(|v| v.as_str().map(String::from))
+                            .unwrap_or_default(),
+                        label: s.step.label().to_string(),
+                        status: serde_json::to_value(&s.status)
+                            .ok()
+                            .and_then(|v| v.as_str().map(String::from))
+                            .unwrap_or_default(),
+                        content: s.content.clone(),
+                    })
+                    .collect();
+                let _ = tx.send(WsResponse::WizardState {
+                    steps,
+                    current_step_index: ws.current_step_index(),
+                    completed: ws.completed,
+                });
+            }
+        }
+
         // Push recent server log entries so the client has history on connect.
         {
             let entries = log_buffer::global().get_recent_entries(100, None, None);

server/src/io/fs/scaffold.rs

@@ -57,7 +57,11 @@ The permission system validates the entire command string, and chained commands
 won't match allow rules like `Bash(git *)`. Use separate Bash calls instead — \
 parallel calls work fine.\n\
 \n\
-Read .storkit/README.md to see our dev process.\n";
+Read .storkit/README.md to see our dev process.\n\
+\n\
+IMPORTANT: On your first conversation, call `wizard_status` to check if \
+project setup is complete. If not, read .storkit/README.md for the full \
+setup wizard instructions and guide the user through it conversationally.\n";
 
 const STORY_KIT_CLAUDE_SETTINGS: &str = r#"{
   "permissions": {
@@ -289,6 +293,7 @@ fn write_story_kit_gitignore(root: &Path) -> Result<(), String> {
         "work/4_merge/",
         "logs/",
         "token_usage.jsonl",
+        "wizard_state.json",
     ];
 
     let gitignore_path = root.join(".storkit").join(".gitignore");

server/src/io/mod.rs

@@ -4,3 +4,4 @@ pub mod search;
 pub mod shell;
 pub mod story_metadata;
 pub mod watcher;
+pub mod wizard;

server/src/io/wizard.rs

@@ -0,0 +1,413 @@
+use serde::{Deserialize, Serialize};
+use serde_json;
+use std::fs;
+use std::path::Path;
+
+/// Ordered wizard steps for project setup.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum WizardStep {
+    /// Step 1: scaffold .storkit/ directory structure and project.toml
+    Scaffold,
+    /// Step 2: generate specs/00_CONTEXT.md
+    Context,
+    /// Step 3: generate specs/tech/STACK.md
+    Stack,
+    /// Step 4: create script/test
+    TestScript,
+    /// Step 5: create script/release
+    ReleaseScript,
+    /// Step 6: create script/test_coverage
+    TestCoverage,
+}
+
+impl WizardStep {
+    /// All steps in order.
+    pub const ALL: &[WizardStep] = &[
+        WizardStep::Scaffold,
+        WizardStep::Context,
+        WizardStep::Stack,
+        WizardStep::TestScript,
+        WizardStep::ReleaseScript,
+        WizardStep::TestCoverage,
+    ];
+
+    /// Human-readable label for this step.
+    pub fn label(&self) -> &'static str {
+        match self {
+            WizardStep::Scaffold => "Scaffold directory structure",
+            WizardStep::Context => "Generate project context (00_CONTEXT.md)",
+            WizardStep::Stack => "Generate tech stack spec (STACK.md)",
+            WizardStep::TestScript => "Create test script (script/test)",
+            WizardStep::ReleaseScript => "Create release script (script/release)",
+            WizardStep::TestCoverage => "Create test coverage script (script/test_coverage)",
+        }
+    }
+
+    /// Zero-based index of this step.
+    pub fn index(&self) -> usize {
+        Self::ALL.iter().position(|s| s == self).unwrap_or(0)
+    }
+}
+
+/// Status of an individual wizard step.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum StepStatus {
+    /// Not yet started.
+    Pending,
+    /// Agent is generating content for this step.
+    Generating,
+    /// Content generated, awaiting user confirmation.
+    AwaitingConfirmation,
+    /// User confirmed this step.
+    Confirmed,
+    /// User skipped this step.
+    Skipped,
+}
+
+/// State of a single wizard step.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StepState {
+    pub step: WizardStep,
+    pub status: StepStatus,
+    /// The generated content (if any) for preview.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub content: Option<String>,
+}
+
+/// Persistent wizard state, stored in `.storkit/wizard_state.json`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WizardState {
+    pub steps: Vec<StepState>,
+    /// True when all steps are confirmed or skipped.
+    pub completed: bool,
+}
+
+impl Default for WizardState {
+    fn default() -> Self {
+        Self {
+            steps: WizardStep::ALL
+                .iter()
+                .map(|&step| StepState {
+                    step,
+                    status: StepStatus::Pending,
+                    content: None,
+                })
+                .collect(),
+            completed: false,
+        }
+    }
+}
+
+impl WizardState {
+    /// Path to the wizard state file relative to the project root.
+    fn state_path(project_root: &Path) -> std::path::PathBuf {
+        project_root.join(".storkit").join("wizard_state.json")
+    }
+
+    /// Load wizard state from disk, or return None if it doesn't exist.
+    pub fn load(project_root: &Path) -> Option<Self> {
+        let path = Self::state_path(project_root);
+        let content = fs::read_to_string(&path).ok()?;
+        serde_json::from_str(&content).ok()
+    }
+
+    /// Save wizard state to disk.
+    pub fn save(&self, project_root: &Path) -> Result<(), String> {
+        let path = Self::state_path(project_root);
+        let content =
+            serde_json::to_string_pretty(self).map_err(|e| format!("Serialize error: {e}"))?;
+        fs::write(&path, content).map_err(|e| format!("Failed to write wizard state: {e}"))
+    }
+
+    /// Create wizard state file if it doesn't already exist.
+    /// Step 1 (Scaffold) is automatically confirmed since `storkit init`
+    /// has already run the scaffold.
+    pub fn init_if_missing(project_root: &Path) {
+        if Self::load(project_root).is_some() {
+            return;
+        }
+        let mut state = Self::default();
+        // Scaffold step is done by the time the server starts.
+        state.steps[0].status = StepStatus::Confirmed;
+        let _ = state.save(project_root);
+    }
+
+    /// Get the current step index (0-based).
+    pub fn current_step_index(&self) -> usize {
+        self.steps
+            .iter()
+            .position(|s| !matches!(s.status, StepStatus::Confirmed | StepStatus::Skipped))
+            .unwrap_or(self.steps.len())
+    }
+
+    /// Mark a step's status and update completion state.
+    pub fn set_step_status(
+        &mut self,
+        step: WizardStep,
+        status: StepStatus,
+        content: Option<String>,
+    ) {
+        if let Some(s) = self.steps.iter_mut().find(|s| s.step == step) {
+            s.status = status;
+            if content.is_some() {
+                s.content = content;
+            }
+        }
+        self.completed = self
+            .steps
+            .iter()
+            .all(|s| matches!(s.status, StepStatus::Confirmed | StepStatus::Skipped));
+    }
+
+    /// Confirm a step. Returns error if the step is not the current one
+    /// (enforces sequential progression).
+    pub fn confirm_step(&mut self, step: WizardStep) -> Result<(), String> {
+        let current_idx = self.current_step_index();
+        let target_idx = step.index();
+        if target_idx != current_idx {
+            return Err(format!(
+                "Cannot confirm step {:?}: current step is {}",
+                step, current_idx
+            ));
+        }
+        self.set_step_status(step, StepStatus::Confirmed, None);
+        Ok(())
+    }
+
+    /// Skip a step. Only the current step can be skipped.
+    pub fn skip_step(&mut self, step: WizardStep) -> Result<(), String> {
+        let current_idx = self.current_step_index();
+        let target_idx = step.index();
+        if target_idx != current_idx {
+            return Err(format!(
+                "Cannot skip step {:?}: current step is {}",
+                step, current_idx
+            ));
+        }
+        self.set_step_status(step, StepStatus::Skipped, None);
+        Ok(())
+    }
+}
+
+/// Format a `WizardState` as a human-readable Markdown summary for display in
+/// bot messages and MCP responses.
+pub fn format_wizard_state(state: &WizardState) -> String {
+    let total = state.steps.len();
+    let current_idx = state.current_step_index();
+
+    let header = if state.completed {
+        format!("**Setup wizard — complete** ({total}/{total} steps done)")
+    } else {
+        format!("**Setup wizard — step {}/{}**", current_idx + 1, total)
+    };
+
+    let mut lines = vec![header, String::new()];
+
+    for (i, step) in state.steps.iter().enumerate() {
+        let marker = match step.status {
+            StepStatus::Confirmed => "✓",
+            StepStatus::Skipped => "~",
+            StepStatus::Generating => "⟳",
+            StepStatus::AwaitingConfirmation => "?",
+            StepStatus::Pending => "○",
+        };
+        let is_current = !state.completed && i == current_idx;
+        let suffix = if is_current { " ← current" } else { "" };
+        let status_str = serde_json::to_value(&step.status)
+            .ok()
+            .and_then(|v| v.as_str().map(String::from))
+            .unwrap_or_default();
+        lines.push(format!(
+            "  {} {} ({}){suffix}",
+            marker,
+            step.step.label(),
+            status_str
+        ));
+    }
+
+    if state.completed {
+        lines.push(String::new());
+        lines.push("All steps done. Your project is fully configured.".to_string());
+    } else {
+        let current = &state.steps[current_idx];
+        lines.push(String::new());
+        lines.push(format!("**Current:** {}", current.step.label()));
+        let hint = match current.status {
+            StepStatus::Pending => {
+                "Ready to generate. Proceed by calling wizard_generate.".to_string()
+            }
+            StepStatus::Generating => "Generating content…".to_string(),
+            StepStatus::AwaitingConfirmation => {
+                "Content ready for review. Show it to the user and ask if they're happy with it. Then call wizard_confirm, wizard_retry, or wizard_skip based on their response.".to_string()
+            }
+            StepStatus::Confirmed | StepStatus::Skipped => String::new(),
+        };
+        if !hint.is_empty() {
+            lines.push(hint);
+        }
+    }
+
+    lines.join("\n")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    fn setup_project(dir: &TempDir) -> std::path::PathBuf {
+        let root = dir.path().to_path_buf();
+        let sk = root.join(".storkit");
+        std::fs::create_dir_all(&sk).unwrap();
+        root
+    }
+
+    #[test]
+    fn default_state_has_all_steps_pending() {
+        let state = WizardState::default();
+        assert_eq!(state.steps.len(), 6);
+        for step in &state.steps {
+            assert_eq!(step.status, StepStatus::Pending);
+        }
+        assert!(!state.completed);
+    }
+
+    #[test]
+    fn init_if_missing_creates_state_with_scaffold_confirmed() {
+        let dir = TempDir::new().unwrap();
+        let root = setup_project(&dir);
+
+        WizardState::init_if_missing(&root);
+
+        let state = WizardState::load(&root).unwrap();
+        assert_eq!(state.steps[0].status, StepStatus::Confirmed);
+        assert_eq!(state.steps[0].step, WizardStep::Scaffold);
+        // Rest should be pending
+        for step in &state.steps[1..] {
+            assert_eq!(step.status, StepStatus::Pending);
+        }
+    }
+
+    #[test]
+    fn init_if_missing_does_not_overwrite_existing() {
+        let dir = TempDir::new().unwrap();
+        let root = setup_project(&dir);
+
+        // Create a custom state
+        let mut state = WizardState::default();
+        state.steps[0].status = StepStatus::Confirmed;
+        state.steps[1].status = StepStatus::Confirmed;
+        state.save(&root).unwrap();
+
+        // init_if_missing should not overwrite
+        WizardState::init_if_missing(&root);
+
+        let loaded = WizardState::load(&root).unwrap();
+        assert_eq!(loaded.steps[1].status, StepStatus::Confirmed);
+    }
+
+    #[test]
+    fn save_and_load_round_trip() {
+        let dir = TempDir::new().unwrap();
+        let root = setup_project(&dir);
+
+        let mut state = WizardState::default();
+        state.steps[0].status = StepStatus::Confirmed;
+        state.steps[1].status = StepStatus::AwaitingConfirmation;
+        state.steps[1].content = Some("# My Project\n\nA cool project.".to_string());
+        state.save(&root).unwrap();
+
+        let loaded = WizardState::load(&root).unwrap();
+        assert_eq!(loaded.steps[0].status, StepStatus::Confirmed);
+        assert_eq!(loaded.steps[1].status, StepStatus::AwaitingConfirmation);
+        assert_eq!(
+            loaded.steps[1].content.as_deref(),
+            Some("# My Project\n\nA cool project.")
+        );
+    }
+
+    #[test]
+    fn current_step_index_correct() {
+        let mut state = WizardState::default();
+        state.steps[0].status = StepStatus::Confirmed;
+        assert_eq!(state.current_step_index(), 1);
+
+        state.steps[1].status = StepStatus::Skipped;
+        assert_eq!(state.current_step_index(), 2);
+    }
+
+    #[test]
+    fn confirm_step_enforces_order() {
+        let mut state = WizardState::default();
+        state.steps[0].status = StepStatus::Confirmed;
+
+        // Can confirm the current step (Context, index 1)
+        assert!(state.confirm_step(WizardStep::Context).is_ok());
+
+        // Cannot confirm a step that's not current
+        assert!(state.confirm_step(WizardStep::TestScript).is_err());
+    }
+
+    #[test]
+    fn skip_step_works() {
+        let mut state = WizardState::default();
+        state.steps[0].status = StepStatus::Confirmed;
+
+        assert!(state.skip_step(WizardStep::Context).is_ok());
+        assert_eq!(state.steps[1].status, StepStatus::Skipped);
+        assert_eq!(state.current_step_index(), 2);
+    }
+
+    #[test]
+    fn completed_when_all_confirmed_or_skipped() {
+        let mut state = WizardState::default();
+        for step in WizardStep::ALL {
+            state.set_step_status(*step, StepStatus::Confirmed, None);
+        }
+        assert!(state.completed);
+    }
+
+    #[test]
+    fn not_completed_when_some_pending() {
+        let mut state = WizardState::default();
+        state.set_step_status(WizardStep::Scaffold, StepStatus::Confirmed, None);
+        assert!(!state.completed);
+    }
+
+    #[test]
+    fn set_step_status_with_content() {
+        let mut state = WizardState::default();
+        state.set_step_status(
+            WizardStep::Context,
+            StepStatus::AwaitingConfirmation,
+            Some("generated content".to_string()),
+        );
+        assert_eq!(state.steps[1].status, StepStatus::AwaitingConfirmation);
+        assert_eq!(
+            state.steps[1].content.as_deref(),
+            Some("generated content")
+        );
+    }
+
+    #[test]
+    fn load_returns_none_when_no_file() {
+        let dir = TempDir::new().unwrap();
+        assert!(WizardState::load(dir.path()).is_none());
+    }
+
+    #[test]
+    fn step_labels_are_non_empty() {
+        for step in WizardStep::ALL {
+            assert!(!step.label().is_empty());
+        }
+    }
+
+    #[test]
+    fn step_indices_are_sequential() {
+        for (i, step) in WizardStep::ALL.iter().enumerate() {
+            assert_eq!(step.index(), i);
+        }
+    }
+}

server/src/main.rs

@@ -32,61 +32,78 @@ use std::path::PathBuf;
 use std::sync::Arc;
 use tokio::sync::broadcast;
 
-/// What the first CLI argument means.
+/// Parsed CLI arguments.
 #[derive(Debug, PartialEq)]
-enum CliDirective {
+struct CliArgs {
-    /// `--help` / `-h`
+    /// Value from `--port <VALUE>` flag, if supplied.
-    Help,
+    port: Option<u16>,
-    /// `--version` / `-V`
+    /// Positional project path argument, if supplied.
-    Version,
+    path: Option<String>,
-    /// An unrecognised flag (starts with `-`).
+    /// Whether the `init` subcommand was given.
-    UnknownFlag(String),
+    init: bool,
-    /// A positional path argument.
-    Path,
-    /// No arguments at all.
-    None,
 }
 
-/// Inspect the raw CLI arguments and return the directive they imply.
+/// Parse CLI arguments into `CliArgs`, or exit early for `--help` / `--version`.
-fn classify_cli_args(args: &[String]) -> CliDirective {
+fn parse_cli_args(args: &[String]) -> Result<CliArgs, String> {
-    match args.first().map(String::as_str) {
+    let mut port: Option<u16> = None;
-        None => CliDirective::None,
+    let mut path: Option<String> = None;
-        Some("--help" | "-h") => CliDirective::Help,
+    let mut init = false;
-        Some("--version" | "-V") => CliDirective::Version,
+    let mut i = 0;
-        Some(a) if a.starts_with('-') => CliDirective::UnknownFlag(a.to_string()),
+
-        Some(_) => CliDirective::Path,
+    while i < args.len() {
+        match args[i].as_str() {
+            "--help" | "-h" => {
+                print_help();
+                std::process::exit(0);
             }
+            "--version" | "-V" => {
+                println!("storkit {}", env!("CARGO_PKG_VERSION"));
+                std::process::exit(0);
+            }
+            "--port" => {
+                i += 1;
+                if i >= args.len() {
+                    return Err("--port requires a value".to_string());
+                }
+                match args[i].parse::<u16>() {
+                    Ok(p) => port = Some(p),
+                    Err(_) => return Err(format!("invalid port value: '{}'", args[i])),
+                }
+            }
+            a if a.starts_with("--port=") => {
+                let val = &a["--port=".len()..];
+                match val.parse::<u16>() {
+                    Ok(p) => port = Some(p),
+                    Err(_) => return Err(format!("invalid port value: '{val}'")),
+                }
+            }
+            "init" => {
+                init = true;
+            }
+            a if a.starts_with('-') => {
+                return Err(format!("unknown option: {a}"));
+            }
+            a => {
+                if path.is_some() {
+                    return Err(format!("unexpected argument: {a}"));
+                }
+                path = Some(a.to_string());
+            }
+        }
+        i += 1;
+    }
+
+    Ok(CliArgs { port, path, init })
 }
 
-/// Resolve the optional positional path argument (everything after the binary
+fn print_help() {
-/// name) into an absolute `PathBuf`.  Returns `None` when no argument was
+    println!("storkit [OPTIONS] [PATH]");
-/// supplied so that the caller can fall back to the auto-detect behaviour.
+    println!("storkit init [OPTIONS] [PATH]");
-fn parse_project_path_arg(args: &[String], cwd: &std::path::Path) -> Option<PathBuf> {
-    args.first().map(|s| io::fs::resolve_cli_path(cwd, s))
-}
-
-#[tokio::main]
-async fn main() -> Result<(), std::io::Error> {
-    let app_state = Arc::new(SessionState::default());
-    let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
-    let store = Arc::new(
-        JsonFileStore::from_path(PathBuf::from("store.json")).map_err(std::io::Error::other)?,
-    );
-
-    let port = resolve_port();
-
-    // Collect CLI args, skipping the binary name (argv[0]).
-    let cli_args: Vec<String> = std::env::args().skip(1).collect();
-
-    // Handle CLI flags before treating anything as a project path.
-    match classify_cli_args(&cli_args) {
-        CliDirective::Help => {
-            println!("storkit [PATH]");
     println!();
     println!("Serve a storkit project.");
     println!();
-            println!("USAGE:");
+    println!("COMMANDS:");
-            println!("  storkit [PATH]");
+    println!("  init  Scaffold a new .storkit/ project and start the interactive setup wizard.");
     println!();
     println!("ARGS:");
     println!(
@@ -97,21 +114,41 @@ async fn main() -> Result<(), std::io::Error> {
     println!("OPTIONS:");
     println!("  -h, --help          Print this help and exit");
     println!("  -V, --version       Print the version and exit");
-            std::process::exit(0);
+    println!("  --port <PORT>       Port to listen on (default: 3001). Persisted to project.toml.");
-        }
+}
-        CliDirective::Version => {
+
-            println!("storkit {}", env!("CARGO_PKG_VERSION"));
+/// Resolve the optional positional path argument into an absolute `PathBuf`.
-            std::process::exit(0);
+fn resolve_path_arg(path_str: Option<&str>, cwd: &std::path::Path) -> Option<PathBuf> {
-        }
+    path_str.map(|s| io::fs::resolve_cli_path(cwd, s))
-        CliDirective::UnknownFlag(flag) => {
+}
-            eprintln!("error: unknown option: {flag}");
+
+#[tokio::main]
+async fn main() -> Result<(), std::io::Error> {
+    let app_state = Arc::new(SessionState::default());
+    let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
+    let store = Arc::new(
+        JsonFileStore::from_path(PathBuf::from("store.json")).map_err(std::io::Error::other)?,
+    );
+
+    // Collect CLI args, skipping the binary name (argv[0]).
+    let raw_args: Vec<String> = std::env::args().skip(1).collect();
+
+    let cli = match parse_cli_args(&raw_args) {
+        Ok(args) => args,
+        Err(msg) => {
+            eprintln!("error: {msg}");
             eprintln!("Run 'storkit --help' for usage.");
             std::process::exit(1);
         }
-        CliDirective::Path | CliDirective::None => {}
+    };
-    }
 
-    let explicit_path = parse_project_path_arg(&cli_args, &cwd);
+    let is_init = cli.init;
+    let explicit_path = resolve_path_arg(cli.path.as_deref(), &cwd);
+
+    // Port resolution: CLI flag > project.toml (loaded later) > default.
+    // Use the CLI port for scaffolding .mcp.json; final port is resolved
+    // after the project root is known.
+    let port = cli.port.unwrap_or_else(resolve_port);
 
     // When a path is given explicitly on the CLI, it must already exist as a
     // directory.  We do not create directories from the command line.
@@ -126,7 +163,37 @@ async fn main() -> Result<(), std::io::Error> {
         }
     }
 
-    if let Some(explicit_root) = explicit_path {
+    if is_init {
+        // `storkit init [PATH]` — always scaffold, never search parents.
+        let init_root = explicit_path.unwrap_or_else(|| cwd.clone());
+        if !init_root.exists() {
+            std::fs::create_dir_all(&init_root).unwrap_or_else(|e| {
+                eprintln!("error: cannot create directory {}: {e}", init_root.display());
+                std::process::exit(1);
+            });
+        }
+        match io::fs::open_project(
+            init_root.to_string_lossy().to_string(),
+            &app_state,
+            store.as_ref(),
+            port,
+        )
+        .await
+        {
+            Ok(_) => {
+                if let Some(root) = app_state.project_root.lock().unwrap().as_ref() {
+                    config::ProjectConfig::load(root)
+                        .unwrap_or_else(|e| panic!("Invalid project.toml: {e}"));
+                    // Initialize wizard state for the setup flow.
+                    io::wizard::WizardState::init_if_missing(root);
+                }
+            }
+            Err(e) => {
+                eprintln!("error: {e}");
+                std::process::exit(1);
+            }
+        }
+    } else if let Some(explicit_root) = explicit_path {
         // An explicit path was given on the command line.
         // Open it directly — scaffold .storkit/ if it is missing — and
         // exit with a clear error message if the path is invalid.
@@ -565,96 +632,106 @@ name = "coder"
             .unwrap_or_else(|e| panic!("Invalid project.toml: {e}"));
     }
 
-    // ── classify_cli_args ─────────────────────────────────────────────────
+    // ── parse_cli_args ─────────────────────────────────────────────────
 
     #[test]
-    fn classify_none_when_no_args() {
+    fn parse_no_args() {
-        assert_eq!(classify_cli_args(&[]), CliDirective::None);
+        let result = parse_cli_args(&[]).unwrap();
+        assert_eq!(result.port, None);
+        assert_eq!(result.path, None);
+        assert!(!result.init);
     }
 
     #[test]
-    fn classify_help_long() {
+    fn parse_unknown_flag_is_error() {
-        assert_eq!(
+        let args = vec!["--serve".to_string()];
-            classify_cli_args(&["--help".to_string()]),
+        assert!(parse_cli_args(&args).is_err());
-            CliDirective::Help
-        );
     }
 
     #[test]
-    fn classify_help_short() {
+    fn parse_path_only() {
-        assert_eq!(classify_cli_args(&["-h".to_string()]), CliDirective::Help);
+        let args = vec!["/some/path".to_string()];
+        let result = parse_cli_args(&args).unwrap();
+        assert_eq!(result.path, Some("/some/path".to_string()));
+        assert_eq!(result.port, None);
+        assert!(!result.init);
     }
 
     #[test]
-    fn classify_version_long() {
+    fn parse_port_flag() {
-        assert_eq!(
+        let args = vec!["--port".to_string(), "4000".to_string()];
-            classify_cli_args(&["--version".to_string()]),
+        let result = parse_cli_args(&args).unwrap();
-            CliDirective::Version
+        assert_eq!(result.port, Some(4000));
-        );
+        assert_eq!(result.path, None);
     }
 
     #[test]
-    fn classify_version_short() {
+    fn parse_port_equals_syntax() {
-        assert_eq!(
+        let args = vec!["--port=5000".to_string()];
-            classify_cli_args(&["-V".to_string()]),
+        let result = parse_cli_args(&args).unwrap();
-            CliDirective::Version
+        assert_eq!(result.port, Some(5000));
-        );
     }
 
     #[test]
-    fn classify_unknown_flag() {
+    fn parse_port_with_path() {
-        assert_eq!(
+        let args = vec!["--port".to_string(), "4200".to_string(), "/some/path".to_string()];
-            classify_cli_args(&["--serve".to_string()]),
+        let result = parse_cli_args(&args).unwrap();
-            CliDirective::UnknownFlag("--serve".to_string())
+        assert_eq!(result.port, Some(4200));
-        );
+        assert_eq!(result.path, Some("/some/path".to_string()));
     }
 
     #[test]
-    fn classify_path() {
+    fn parse_port_missing_value_is_error() {
-        assert_eq!(
+        let args = vec!["--port".to_string()];
-            classify_cli_args(&["/some/path".to_string()]),
+        assert!(parse_cli_args(&args).is_err());
-            CliDirective::Path
-        );
     }
 
-    // ── parse_project_path_arg ────────────────────────────────────────────
+    #[test]
+    fn parse_port_invalid_value_is_error() {
+        let args = vec!["--port".to_string(), "abc".to_string()];
+        assert!(parse_cli_args(&args).is_err());
+    }
 
     #[test]
-    fn parse_project_path_arg_none_when_no_args() {
+    fn parse_init_subcommand() {
+        let args = vec!["init".to_string()];
+        let result = parse_cli_args(&args).unwrap();
+        assert!(result.init);
+        assert_eq!(result.path, None);
+    }
+
+    #[test]
+    fn parse_init_with_path_and_port() {
+        let args = vec!["init".to_string(), "--port".to_string(), "3000".to_string(), "/my/project".to_string()];
+        let result = parse_cli_args(&args).unwrap();
+        assert!(result.init);
+        assert_eq!(result.port, Some(3000));
+        assert_eq!(result.path, Some("/my/project".to_string()));
+    }
+
+    // ── resolve_path_arg ────────────────────────────────────────────
+
+    #[test]
+    fn resolve_path_arg_none_when_no_path() {
         let cwd = PathBuf::from("/home/user/project");
-        let result = parse_project_path_arg(&[], &cwd);
+        let result = resolve_path_arg(None, &cwd);
         assert!(result.is_none());
     }
 
     #[test]
-    fn parse_project_path_arg_returns_path_for_absolute_arg() {
+    fn resolve_path_arg_returns_path_for_absolute_arg() {
         let cwd = PathBuf::from("/home/user/project");
-        let args = vec!["/some/absolute/path".to_string()];
+        let result = resolve_path_arg(Some("/some/absolute/path"), &cwd).unwrap();
-        let result = parse_project_path_arg(&args, &cwd).unwrap();
-        // Absolute path returned as-is (canonicalize may fail, fallback used)
         assert!(
             result.ends_with("absolute/path") || result == PathBuf::from("/some/absolute/path")
         );
     }
 
     #[test]
-    fn parse_project_path_arg_resolves_dot_to_cwd() {
+    fn resolve_path_arg_resolves_dot_to_cwd() {
         let tmp = tempfile::tempdir().unwrap();
         let cwd = tmp.path().to_path_buf();
-        let args = vec![".".to_string()];
+        let result = resolve_path_arg(Some("."), &cwd).unwrap();
-        let result = parse_project_path_arg(&args, &cwd).unwrap();
-        // "." relative to an existing cwd should canonicalize to the cwd itself
         assert_eq!(result, cwd.canonicalize().unwrap_or(cwd));
     }
-
-    #[test]
-    fn parse_project_path_arg_resolves_relative_path() {
-        let tmp = tempfile::tempdir().unwrap();
-        let cwd = tmp.path().to_path_buf();
-        let subdir = cwd.join("myproject");
-        std::fs::create_dir_all(&subdir).unwrap();
-        let args = vec!["myproject".to_string()];
-        let result = parse_project_path_arg(&args, &cwd).unwrap();
-        assert_eq!(result, subdir.canonicalize().unwrap_or(subdir));
-    }
 }