Bump version to 0.5.0

gVisor is incompatible with OrbStack bind mounts on macOS — writes to
/mnt/mac are blocked by the gVisor filesystem sandbox. Removing
runtime: runsc from docker-compose.yml, the gVisor setup docs from
README.md, and the runsc assertion test from rebuild.rs.

The existing Docker hardening (read-only root, cap_drop ALL,
no-new-privileges, resource limits) remains in place.

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

.claude/settings.json

@@ -1,12 +1,10 @@
 {
-  "enabledMcpjsonServers": [
+  "enabledMcpjsonServers": ["storkit"],
-    "story-kit"
-  ],
   "permissions": {
     "allow": [
-      "Bash(./server/target/debug/story-kit:*)",
+      "Bash(./server/target/debug/storkit:*)",
-      "Bash(./target/debug/story-kit:*)",
+      "Bash(./target/debug/storkit:*)",
-      "Bash(STORYKIT_PORT=*)",
+      "Bash(STORKIT_PORT=*)",
       "Bash(cargo build:*)",
       "Bash(cargo check:*)",
       "Bash(cargo clippy:*)",
@@ -56,11 +54,20 @@
       "WebFetch(domain:portkey.ai)",
       "WebFetch(domain:www.shuttle.dev)",
       "WebSearch",
-      "mcp__story-kit__*",
+      "mcp__storkit__*",
       "Edit",
       "Write",
       "Bash(find *)",
-      "Bash(sqlite3 *)"
+      "Bash(sqlite3 *)",
+      "Bash(cat <<:*)",
+      "Bash(cat <<'ENDJSON:*)",
+      "Bash(make release:*)",
+      "Bash(npm test:*)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(wc *)",
+      "Bash(npx vite:*)",
+      "Bash(npm run dev:*)"
     ]
   }
 }

.dockerignore

@@ -0,0 +1,11 @@
+# Docker build context exclusions
+**/target/
+**/node_modules/
+frontend/dist/
+.storkit/worktrees/
+.storkit/logs/
+.storkit/work/6_archived/
+.git/
+*.swp
+*.swo
+.DS_Store

.gitignore

@@ -5,9 +5,9 @@
 # Local environment (secrets)
 .env
 
-# App specific (root-level; story-kit subdirectory patterns live in .story_kit/.gitignore)
+# App specific (root-level; storkit subdirectory patterns live in .storkit/.gitignore)
 store.json
-.story_kit_port
+.storkit_port
 
 # Rust stuff
 target

.ignore

@@ -3,6 +3,6 @@ frontend/
 node_modules/
 .claude/
 .git/
-.story_kit/
+.storkit/
 store.json
-.story_kit_port
+.storkit_port

.mcp.json

@@ -1,6 +1,6 @@
 {
   "mcpServers": {
-    "story-kit": {
+    "storkit": {
       "type": "http",
       "url": "http://localhost:3001/mcp"
     }

.storkit/.gitignore

@@ -17,3 +17,6 @@ work/4_merge/
 
 # Coverage reports (generated by cargo-llvm-cov, not tracked in git)
 coverage/
+
+# Token usage log (generated at runtime, contains cost data)
+token_usage.jsonl

.storkit/README.md

@@ -11,14 +11,14 @@ 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:
    ```bash
-   curl -s "$(jq -r '.mcpServers["story-kit"].url' .mcp.json)" \
+   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 Stack:** Check `.story_kit/specs/tech/STACK.md` for technical constraints and patterns.
-4. **Check Work Items:** Look at `.story_kit/work/1_upcoming/` and `.story_kit/work/2_current/` to see what work is pending.
+4. **Check Work Items:** Look at `.story_kit/work/1_backlog/` and `.story_kit/work/2_current/` to see what work is pending.
 
 
 ---
@@ -52,7 +52,7 @@ project_root/
   ├── README.md          # This document
   ├── project.toml       # Agent configuration (roles, models, prompts)
   ├── work/              # Unified work item pipeline (stories, bugs, spikes)
-  │   ├── 1_upcoming/    # New work items awaiting implementation
+  │   ├── 1_backlog/    # New work items awaiting implementation
   │   ├── 2_current/     # Work in progress
   │   ├── 3_qa/          # QA review
   │   ├── 4_merge/       # Ready to merge to master
@@ -78,7 +78,7 @@ All work items (stories, bugs, spikes) live in the same `work/` pipeline. Items
 
 Items move through stages by moving the file between directories:
 
-`1_upcoming` → `2_current` → `3_qa` → `4_merge` → `5_done` → `6_archived`
+`1_backlog` → `2_current` → `3_qa` → `4_merge` → `5_done` → `6_archived`
 
 Items in `5_done` are auto-swept to `6_archived` after 4 hours by the server.
 
@@ -87,7 +87,7 @@ Items in `5_done` are auto-swept to `6_archived` after 4 hours by the server.
 The server watches `.story_kit/work/` for changes. When a file is created, moved, or modified, the watcher auto-commits with a deterministic message and broadcasts a WebSocket notification to the frontend. This means:
 
 *   MCP tools only need to write/move files — the watcher handles git commits
-*   IDE drag-and-drop works (drag a story from `1_upcoming/` to `2_current/`)
+*   IDE drag-and-drop works (drag a story from `1_backlog/` to `2_current/`)
 *   The frontend updates automatically without manual refresh
 
 ---
@@ -156,7 +156,7 @@ Not everything needs to be a full story. Simple bugs can skip the story process:
 *   Performance issues with known fixes
 
 ### Bug Process
-1.  **Document Bug:** Create a bug file in `work/1_upcoming/` named `{id}_bug_{slug}.md` with:
+1.  **Document Bug:** Create a bug file in `work/1_backlog/` named `{id}_bug_{slug}.md` with:
     *   **Symptom:** What the user observes
     *   **Root Cause:** Technical explanation (if known)
     *   **Reproduction Steps:** How to trigger the bug
@@ -186,7 +186,7 @@ Not everything needs a story or bug fix. Spikes are time-boxed investigations to
 *   Need to validate performance constraints
 
 ### Spike Process
-1.  **Document Spike:** Create a spike file in `work/1_upcoming/` named `{id}_spike_{slug}.md` with:
+1.  **Document Spike:** Create a spike file in `work/1_backlog/` named `{id}_spike_{slug}.md` with:
     *   **Question:** What you need to answer
     *   **Hypothesis:** What you expect to be true
     *   **Timebox:** Strict limit for the research
@@ -209,7 +209,7 @@ When the LLM context window fills up (or the chat gets slow/confused):
 1.  **Stop Coding.**
 2.  **Instruction:** Tell the user to open a new chat.
 3.  **Handoff:** The only context the new LLM needs is in the `specs/` folder and `.mcp.json`.
-    *   *Prompt for New Session:* "I am working on Project X. Read `.mcp.json` to discover available tools, then read `specs/00_CONTEXT.md` and `specs/tech/STACK.md`. Then look at `work/1_upcoming/` and `work/2_current/` to see what is pending."
+    *   *Prompt for New Session:* "I am working on Project X. Read `.mcp.json` to discover available tools, then read `specs/00_CONTEXT.md` and `specs/tech/STACK.md`. Then look at `work/1_backlog/` and `work/2_current/` to see what is pending."
 
 
 ---
@@ -221,7 +221,7 @@ If a user hands you this document and says "Apply this process to my project":
 1.  **Check for MCP Tools:** Look for `.mcp.json` in the project root. If it exists, you have programmatic access to workflow tools and agent spawning capabilities.
 2.  **Analyze the Request:** Ask for the high-level goal ("What are we building?") and the tech preferences ("Rust or Python?").
 3.  **Git Check:** Check if the directory is a git repository (`git status`). If not, run `git init`.
-4.  **Scaffold:** Run commands to create the `work/` and `specs/` folders with the 6-stage pipeline (`work/1_upcoming/` through `work/6_archived/`).
+4.  **Scaffold:** Run commands to create the `work/` and `specs/` folders with the 6-stage pipeline (`work/1_backlog/` through `work/6_archived/`).
 5.  **Draft Context:** Write `specs/00_CONTEXT.md` based on the user's answer.
 6.  **Draft Stack:** Write `specs/tech/STACK.md` based on best practices for that language.
 7.  **Wait:** Ask the user for "Story #1".

.storkit/bot.toml.example

@@ -0,0 +1,61 @@
+homeserver = "https://matrix.example.com"
+username = "@botname:example.com"
+password = "your-bot-password"
+
+# List one or more rooms to listen in.  Use a single-element list for one room.
+room_ids = ["!roomid:example.com"]
+
+# Optional: the deprecated single-room key is still accepted for backwards compat.
+# room_id = "!roomid:example.com"
+
+allowed_users = ["@youruser:example.com"]
+enabled = false
+
+# Maximum conversation turns to remember per room (default: 20).
+# history_size = 20
+
+# Rooms where the bot responds to all messages (not just addressed ones).
+# This list is updated automatically when users toggle ambient mode at runtime.
+# ambient_rooms = ["!roomid:example.com"]
+
+# ── WhatsApp Business API ──────────────────────────────────────────────
+# Set transport = "whatsapp" to use WhatsApp instead of Matrix.
+# The webhook endpoint will be available at /webhook/whatsapp.
+# You must configure this URL in the Meta Developer Dashboard.
+#
+# transport = "whatsapp"
+# whatsapp_phone_number_id = "123456789012345"
+# whatsapp_access_token = "EAAx..."
+# whatsapp_verify_token = "my-secret-verify-token"
+#
+# ── 24-hour messaging window & notification templates ─────────────────
+# WhatsApp only allows free-form text messages within 24 hours of the last
+# inbound message from a user.  For proactive pipeline notifications sent
+# after the window expires, an approved Meta message template is used.
+#
+# Register the template in the Meta Business Manager:
+#   1. Go to Business Settings → WhatsApp → Message Templates → Create.
+#   2. Category: UTILITY
+#   3. Template name: pipeline_notification   (or your chosen name below)
+#   4. Language: English (en_US)
+#   5. Body text (example):
+#        Story *{{1}}* has moved to *{{2}}*.
+#      Where {{1}} = story name, {{2}} = pipeline stage.
+#   6. Submit for review.  Meta typically approves utility templates within
+#      minutes; transactional categories may take longer.
+#
+# Once approved, set the name below (default: "pipeline_notification"):
+# whatsapp_notification_template = "pipeline_notification"
+
+# ── Slack Bot API ─────────────────────────────────────────────────────
+# Set transport = "slack" to use Slack instead of Matrix.
+# The webhook endpoint will be available at /webhook/slack.
+# Configure this URL in the Slack App → Event Subscriptions → Request URL.
+#
+# Required Slack App scopes: chat:write, chat:update
+# Subscribe to bot events: message.channels, message.groups, message.im
+#
+# transport = "slack"
+# slack_bot_token = "xoxb-..."
+# slack_signing_secret = "your-signing-secret"
+# slack_channel_ids = ["C01ABCDEF"]

.storkit/problems.md

@@ -0,0 +1,28 @@
+# Problems
+
+Recurring issues observed during pipeline operation. Review periodically and create stories for systemic problems.
+
+## 2026-03-18: Stories graduating to "done" with empty merges (7 of 10)
+
+Pipeline allows stories to move through coding → QA → merge → done without any actual code changes landing on master. The squash-merge produces an empty diff but the pipeline still marks the story as done. Affected stories: 247, 273, 274, 278, 279, 280, 92. Only 266, 271, 277, and 281 actually shipped code. Root cause: no check that the merge commit contains a non-empty diff. Filed bug 283 for the manual_qa gate issue specifically, but the empty-merge-to-done problem is broader and needs its own fix.
+
+## 2026-03-18: Agent committed directly to master instead of worktree
+
+Multiple agents have committed directly to master instead of their worktree/feature branch:
+
+- Commit `5f4591f` ("fix: update should_commit_stage test to match 5_done") — likely mergemaster
+- Commit `a32cfbd` ("Add bot-level command registry with help command") — story 285 coder committed code + Cargo.lock directly to master
+
+Agents should only commit to their feature branch or merge-queue branch, never to master directly. Suspect agents are running `git commit` in the project root instead of the worktree directory. This can also revert uncommitted fixes on master (e.g. project.toml pkill fix was overwritten). Frequency: at least 2 confirmed cases. This is a recurring and serious problem — needs a guard in the server or agent prompts.
+
+## 2026-03-19: Auto-assign re-assigns mergemaster to failed merge stories in a loop
+
+After bug 295 fix (`auto_assign_available_work` after every pipeline advance), mergemaster gets re-assigned to stories that already have a merge failure flag. Story 310 had an empty diff merge failure — mergemaster correctly reported the failure, but auto-assign immediately re-assigned mergemaster to the same story, creating an infinite retry loop. The auto-assign logic needs to check for the `merge_failure` front matter flag before re-assigning agents to stories in `4_merge/`.
+
+## 2026-03-19: Coder produces no code (complete ghost — story 310)
+
+Story 310 (Bot delete command) went through the full pipeline — coder session ran, passed QA/gates, moved to merge — but the coder produced zero code. No commits on the feature branch, no commits on master. The entire agent session was a no-op. This is different from the "committed to master instead of worktree" problem — in this case, the coder simply did nothing. Need to investigate the coder logs to understand what happened. The empty-diff merge check would catch this at merge time, but ideally the server should detect "coder finished with no commits on feature branch" at the gate-check stage and fail early.
+
+## 2026-03-19: Auto-assign assigns mergemaster to coding-stage stories
+
+Auto-assign picked mergemaster for story 310 which was in `2_current/`. Mergemaster should only work on stories in `4_merge/`. The `auto_assign_available_work` function doesn't enforce that the agent's configured stage matches the pipeline stage of the story it's being assigned to. Story 279 (auto-assign respects agent stage from front matter) was supposed to fix this, but the check may only apply to front-matter preferences, not the fallback assignment path.

.storkit/project.toml

@@ -1,3 +1,18 @@
+# Project-wide default QA mode: "server", "agent", or "human".
+# Per-story `qa` front matter overrides this setting.
+default_qa = "server"
+
+# Default model for coder agents. Only agents with this model are auto-assigned.
+# Opus coders are reserved for explicit per-story `agent:` front matter requests.
+default_coder_model = "sonnet"
+
+# Maximum concurrent coder agents. Stories wait in 2_current/ when all slots are full.
+max_coders = 3
+
+# Maximum retries per story per pipeline stage before marking as blocked.
+# Set to 0 to disable retry limits.
+max_retries = 2
+
 [[component]]
 name = "frontend"
 path = "frontend"
@@ -10,45 +25,6 @@ path = "."
 setup = ["mkdir -p frontend/dist", "cargo check"]
 teardown = []
 
-[[agent]]
-name = "supervisor"
-stage = "other"
-role = "Coordinates work, reviews PRs, decomposes stories."
-model = "opus"
-max_turns = 200
-max_budget_usd = 15.00
-prompt = """You are the supervisor for story {{story_id}}. Your job is to coordinate coder agents to implement this story.
-
-Read CLAUDE.md first, then .story_kit/README.md to understand the dev process (SDTW). You are responsible for ensuring coders follow this process.
-
-## Your MCP Tools
-You have these tools via the story-kit MCP server:
-- start_agent(story_id, agent_name) - Start a coder agent on a story
-- wait_for_agent(story_id, agent_name, timeout_ms) - Block until the agent reaches a terminal state (completed/failed). Returns final status including completion report with gates_passed.
-- get_agent_output(story_id, agent_name, timeout_ms) - Poll agent output (returns recent events, call repeatedly)
-- list_agents() - See all running agents and their status
-- stop_agent(story_id, agent_name) - Stop a running agent
-- get_story_todos(story_id) - Get unchecked acceptance criteria for a story in work/2_current/
-- ensure_acceptance(story_id) - Check if a story passes acceptance gates
-
-## Your Workflow
-1. Read CLAUDE.md and .story_kit/README.md to understand the project and dev process
-2. Read the story file from .story_kit/work/ to understand requirements
-3. Move it to work/2_current/ if it is in work/1_upcoming/
-4. Start coder-1 on the story: call start_agent with story_id="{{story_id}}" and agent_name="coder-1"
-5. Wait for completion: call wait_for_agent with story_id="{{story_id}}" and agent_name="coder-1". The server automatically runs acceptance gates (cargo clippy + tests) when the coder process exits. wait_for_agent returns when the coder reaches a terminal state.
-6. Check the result: inspect the "completion" field in the wait_for_agent response — if gates_passed is true, the work is done; if false, review the gate_output and decide whether to start a fresh coder.
-7. If the agent gets stuck, stop it and start a fresh agent.
-8. STOP here. Do NOT accept the story or merge to master. Report the status to the human for final review and acceptance.
-
-## Rules
-- Do NOT implement code yourself - delegate to coder agents
-- Only run one coder at a time per story
-- Focus on coordination, monitoring, and quality review
-- Never accept stories or merge to master - that is the human's job
-- Your job ends when the coder's completion report shows gates_passed=true and you have reported the result"""
-system_prompt = "You are a supervisor agent. Read CLAUDE.md and .story_kit/README.md first to understand the project dev process. Use MCP tools to coordinate sub-agents. Never implement code directly - always delegate to coder agents and monitor their progress. Use wait_for_agent to block until the coder finishes — the server automatically runs acceptance gates when the agent process exits. Never accept stories or merge to master - get all gates green and report to the human."
-
 [[agent]]
 name = "coder-1"
 stage = "coder"
@@ -57,7 +33,7 @@ model = "sonnet"
 max_turns = 50
 max_budget_usd = 5.00
 prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results.\n\n## Bug Workflow: Root Cause First\nWhen working on bugs:\n1. Investigate the root cause before writing any fix. Use `git bisect` to find the breaking commit or `git log` to trace history. Read the relevant code before touching anything.\n2. Fix the root cause with a surgical, minimal change. Do NOT add new abstractions, wrappers, or workarounds when a targeted fix to the original code is possible.\n3. Write commit messages that explain what broke and why, not just what was changed.\n4. If you cannot determine the root cause after thorough investigation, document what you tried and why it was inconclusive — do not guess and ship a speculative fix."
-system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
+system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy --all-targets --all-features and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
 
 [[agent]]
 name = "coder-2"
@@ -67,7 +43,17 @@ model = "sonnet"
 max_turns = 50
 max_budget_usd = 5.00
 prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results.\n\n## Bug Workflow: Root Cause First\nWhen working on bugs:\n1. Investigate the root cause before writing any fix. Use `git bisect` to find the breaking commit or `git log` to trace history. Read the relevant code before touching anything.\n2. Fix the root cause with a surgical, minimal change. Do NOT add new abstractions, wrappers, or workarounds when a targeted fix to the original code is possible.\n3. Write commit messages that explain what broke and why, not just what was changed.\n4. If you cannot determine the root cause after thorough investigation, document what you tried and why it was inconclusive — do not guess and ship a speculative fix."
-system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
+system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy --all-targets --all-features and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
+
+[[agent]]
+name = "coder-3"
+stage = "coder"
+role = "Full-stack engineer. Implements features across all components."
+model = "sonnet"
+max_turns = 50
+max_budget_usd = 5.00
+prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results.\n\n## Bug Workflow: Root Cause First\nWhen working on bugs:\n1. Investigate the root cause before writing any fix. Use `git bisect` to find the breaking commit or `git log` to trace history. Read the relevant code before touching anything.\n2. Fix the root cause with a surgical, minimal change. Do NOT add new abstractions, wrappers, or workarounds when a targeted fix to the original code is possible.\n3. Write commit messages that explain what broke and why, not just what was changed.\n4. If you cannot determine the root cause after thorough investigation, document what you tried and why it was inconclusive — do not guess and ship a speculative fix."
+system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy --all-targets --all-features and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
 
 [[agent]]
 name = "qa-2"
@@ -102,7 +88,7 @@ Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
   - URL to visit in the browser
   - Things to check in the UI
   - curl commands to exercise relevant API endpoints
-- Kill the test server when done: `pkill -f story-kit || true`
+- 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
 Print your QA report to stdout before your process exits. The server will automatically run acceptance gates. Use this format:
@@ -144,7 +130,7 @@ model = "opus"
 max_turns = 80
 max_budget_usd = 20.00
 prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results.\n\n## Bug Workflow: Root Cause First\nWhen working on bugs:\n1. Investigate the root cause before writing any fix. Use `git bisect` to find the breaking commit or `git log` to trace history. Read the relevant code before touching anything.\n2. Fix the root cause with a surgical, minimal change. Do NOT add new abstractions, wrappers, or workarounds when a targeted fix to the original code is possible.\n3. Write commit messages that explain what broke and why, not just what was changed.\n4. If you cannot determine the root cause after thorough investigation, document what you tried and why it was inconclusive — do not guess and ship a speculative fix."
-system_prompt = "You are a senior full-stack engineer working autonomously in a git worktree. You handle complex tasks requiring deep architectural understanding. Follow the Story-Driven Test Workflow strictly. Run cargo clippy and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
+system_prompt = "You are a senior full-stack engineer working autonomously in a git worktree. You handle complex tasks requiring deep architectural understanding. Follow the Story-Driven Test Workflow strictly. Run cargo clippy --all-targets --all-features and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
 
 [[agent]]
 name = "qa"
@@ -179,7 +165,7 @@ Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
   - URL to visit in the browser
   - Things to check in the UI
   - curl commands to exercise relevant API endpoints
-- Kill the test server when done: `pkill -f story-kit || true`
+- 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
 Print your QA report to stdout before your process exits. The server will automatically run acceptance gates. Use this format:

.storkit/specs/functional/SLACK_SETUP.md

@@ -0,0 +1,44 @@
+# Slack Integration Setup
+
+## Bot Configuration
+
+Slack integration is configured via `bot.toml` in the project's `.story_kit/` directory:
+
+```toml
+transport = "slack"
+display_name = "Storkit"
+slack_bot_token = "xoxb-..."
+slack_signing_secret = "..."
+slack_channel_ids = ["C01ABCDEF"]
+```
+
+## Slack App Configuration
+
+### Event Subscriptions
+
+1. In your Slack app settings, enable **Event Subscriptions**.
+2. Set the **Request URL** to: `https://<your-host>/webhook/slack`
+3. Subscribe to the `message.channels` and `message.im` bot events.
+
+### Slash Commands
+
+Slash commands provide quick access to pipeline commands without mentioning the bot.
+
+1. In your Slack app settings, go to **Slash Commands**.
+2. Create the following commands, all pointing to the same **Request URL**: `https://<your-host>/webhook/slack/command`
+
+| Command | Description |
+|---------|-------------|
+| `/storkit-status` | Show pipeline status and agent availability |
+| `/storkit-cost` | Show token spend: 24h total, top stories, and breakdown |
+| `/storkit-show` | Display the full text of a work item (e.g. `/storkit-show 42`) |
+| `/storkit-git` | Show git status: branch, changes, ahead/behind |
+| `/storkit-htop` | Show system and agent process dashboard |
+
+All slash command responses are **ephemeral** — only the user who invoked the command sees the response.
+
+### OAuth & Permissions
+
+Required bot token scopes:
+- `chat:write` — send messages
+- `commands` — handle slash commands

.storkit/specs/tech/STACK.md

@@ -118,8 +118,8 @@ To support both Remote and Local models, the system implements a `ModelProvider`
 
 Multiple instances can run simultaneously in different worktrees. To avoid port conflicts:
 
-- **Backend:** Set `STORYKIT_PORT` to a unique port (default is 3001). Example: `STORYKIT_PORT=3002 cargo run`
+- **Backend:** Set `STORKIT_PORT` to a unique port (default is 3001). Example: `STORKIT_PORT=3002 cargo run`
-- **Frontend:** Run `npm run dev` from `frontend/`. It auto-selects the next unused port. It reads `STORYKIT_PORT` to know which backend to talk to, so export it before running: `export STORYKIT_PORT=3002 && cd frontend && npm run dev`
+- **Frontend:** Run `npm run dev` from `frontend/`. It auto-selects the next unused port. It reads `STORKIT_PORT` to know which backend to talk to, so export it before running: `export STORKIT_PORT=3002 && cd frontend && npm run dev`
 
 When running in a worktree, use a port that won't conflict with the main instance (3001). Ports 3002+ are good choices.
 

.storkit/work/1_backlog/368_story_web_ui_oauth_flow_for_claude_authentication.md

@@ -0,0 +1,24 @@
+---
+name: "Web UI OAuth flow for Claude authentication"
+---
+
+# Story 368: Web UI OAuth flow for Claude authentication
+
+## User Story
+
+As a new user running storkit in Docker, I want to authenticate Claude through the web UI instead of running `claude login` in a terminal inside the container, so that the entire setup experience stays in the browser after `docker compose up`.
+
+## Acceptance Criteria
+
+- [ ] Backend exposes /auth/start endpoint that generates the Claude OAuth URL with redirect_uri pointing to localhost:3001
+- [ ] Backend exposes /auth/callback endpoint that receives the OAuth token and stores it where Claude Code expects it
+- [ ] Backend exposes /auth/status endpoint that reports whether valid Claude credentials exist
+- [ ] Frontend shows a setup screen when no Claude auth is detected on first visit
+- [ ] Setup screen has a 'Connect Claude Account' button that initiates the OAuth flow
+- [ ] OAuth redirect returns to the web UI which confirms success and dismisses the setup screen
+- [ ] Credentials are persisted in the claude-state Docker volume so they survive container restarts
+- [ ] The entire flow works without any terminal interaction after docker compose up
+
+## Out of Scope
+
+- TBD

.storkit/work/5_done/369_bug_cli_treats_help_and_version_as_project_paths.md

@@ -0,0 +1,34 @@
+---
+name: "CLI treats --help and --version as project paths"
+---
+
+# Bug 369: CLI treats --help and --version as project paths
+
+## Description
+
+When running `storkit <anything>`, the binary treats the first argument as a project path, creates a directory for it, and scaffolds `.storkit/` inside. This happens for `--help`, `--version`, `serve`, `x`, or any other string. There is no validation that the argument is an existing directory or a reasonable path before creating it.
+
+## How to Reproduce
+
+1. Run `storkit --help` or `storkit serve` or `storkit x` in any directory
+2. Observe that a directory with that name is created with a full `.storkit/` scaffold inside it
+
+## Actual Result
+
+Any argument is treated as a project path and a directory is created and scaffolded. No flags are recognised.
+
+## Expected Result
+
+- `storkit --help` prints usage info and exits
+- `storkit --version` prints the version and exits
+- `storkit <path>` only works if the path already exists as a directory
+- If the path does not exist, storkit prints a clear error and exits non-zero
+
+## Acceptance Criteria
+
+- [ ] storkit --help prints usage information and exits with code 0
+- [ ] storkit --version prints the version and exits with code 0
+- [ ] storkit -h and storkit -V work as short aliases
+- [ ] storkit does not create directories for any argument — the path must already exist
+- [ ] If the path does not exist, storkit prints a clear error and exits non-zero
+- [ ] Arguments starting with - that are not recognised produce a clear error message

.storkit/work/5_done/370_bug_scaffold_does_not_create_mcp_json_in_project_root.md

@@ -0,0 +1,33 @@
+---
+name: "Scaffold does not create .mcp.json in project root"
+---
+
+# Bug 370: Scaffold does not create .mcp.json in project root
+
+## Description
+
+Two related problems with project setup:
+
+1. When the user clicks the "project setup" button in the web UI to open a new project, the scaffold does not reliably run — the `.storkit/` directory and associated files may not be created.
+2. Even when the scaffold does run, it does not write `.mcp.json` to the project root. Without this file, agents spawned in worktrees cannot find the MCP server, causing `--permission-prompt-tool mcp__storkit__prompt_permission not found` errors and agent failures.
+
+## How to Reproduce
+
+1. Open the storkit web UI and use the project setup button to open a new project directory
+2. Check whether the full scaffold was created (`.storkit/`, `CLAUDE.md`, `script/test`, etc.)
+3. Check the project root for `.mcp.json`
+
+## Actual Result
+
+The scaffold may not run when using the UI project setup flow. When it does run, `.mcp.json` is not created in the project root. Agents fail because MCP tools are unavailable.
+
+## Expected Result
+
+Clicking the project setup button reliably runs the full scaffold, including `.mcp.json` pointing to the server's port.
+
+## Acceptance Criteria
+
+- [ ] The web UI project setup button triggers the full scaffold for new projects
+- [ ] scaffold_story_kit writes .mcp.json to the project root with the server's port
+- [ ] Existing .mcp.json is not overwritten if already present
+- [ ] .mcp.json is included in .gitignore since the port is environment-specific

.storkit/work/6_archived/130_bug_permission_approval_returns_wrong_format_tools_fail_after_user_approves.md

@@ -10,7 +10,7 @@ The `prompt_permission` MCP tool returns plain text ("Permission granted for '..
 
 ## How to Reproduce
 
-1. Start the story-kit server and open the web UI
+1. Start the storkit server and open the web UI
 2. Chat with the claude-code-pty model
 3. Ask it to do something that requires a tool NOT in `.claude/settings.json` allow list (e.g. `wc -l /etc/hosts`, or WebFetch to a non-allowed domain)
 4. The permission dialog appears — click Approve

.storkit/work/6_archived/139_story_retry_limit_for_mergemaster_and_pipeline_restarts.md

@@ -6,7 +6,7 @@ name: "Retry limit for mergemaster and pipeline restarts"
 
 ## User Story
 
-As a developer using story-kit, I want pipeline auto-restarts to have a configurable retry limit so that failing agents don't loop infinitely consuming CPU and API credits.
+As a developer using storkit, I want pipeline auto-restarts to have a configurable retry limit so that failing agents don't loop infinitely consuming CPU and API credits.
 
 ## Acceptance Criteria
 

.storkit/work/6_archived/151_story_split_archived_into_done_and_archived_with_time_based_promotion.md

@@ -23,7 +23,7 @@ The watcher should periodically check `5_done/` and move items older than 4 hour
 - All MCP tools and pipeline logic that reference `5_archived` need updating to use `5_done`
 - Frontend pipeline display if it shows archived/done items
 - `.story_kit/README.md`: update pipeline stage documentation
-- Story 116's init scaffolding: `story-kit init` must create `5_done/` and `6_archived/` directories
+- Story 116's init scaffolding: `storkit init` must create `5_done/` and `6_archived/` directories
 - Any templates or scaffold code that creates the `.story_kit/work/` directory structure
 
 ## Acceptance Criteria
@@ -35,7 +35,7 @@ The watcher should periodically check `5_done/` and move items older than 4 hour
 - [ ] Existing items in old `5_archived/` are migrated to `6_archived/`
 - [ ] Frontend pipeline display updated if applicable
 - [ ] `.story_kit/README.md` updated to reflect the new pipeline stages
-- [ ] `story-kit init` scaffolding creates `5_done/` and `6_archived/` (coordinate with story 116)
+- [ ] `storkit init` scaffolding creates `5_done/` and `6_archived/` (coordinate with story 116)
 
 ## Out of Scope
 

.storkit/work/6_archived/156_bug_onboarding_welcome_screen_triggers_on_already_configured_projects.md

@@ -17,21 +17,21 @@ const TEMPLATE_MARKER_CONTEXT: &str = "Agentic AI Code Assistant";
 const TEMPLATE_MARKER_STACK: &str = "Agentic Code Assistant";
 ```
 
-These markers are phrases that appear in the scaffold templates (`server/src/io/fs.rs` lines 233 and 269). The detection logic (`is_template_or_missing` at line 59) checks if the file *contains* the marker string. But these phrases are generic enough that real project content can contain them too — especially when the project being managed IS an agentic code assistant (i.e. story-kit managing itself).
+These markers are phrases that appear in the scaffold templates (`server/src/io/fs.rs` lines 233 and 269). The detection logic (`is_template_or_missing` at line 59) checks if the file *contains* the marker string. But these phrases are generic enough that real project content can contain them too — especially when the project being managed IS an agentic code assistant (i.e. storkit managing itself).
 
 ## The Fix
 
 Replace the content-based marker detection with a dedicated sentinel comment that only exists in untouched scaffold templates. The sentinel should be something that would never appear in real content, like an HTML comment:
 
 ```
-<!-- story-kit:scaffold-template -->
+<!-- storkit:scaffold-template -->
 ```
 
 Changes needed:
 
-1. **`server/src/io/onboarding.rs`**: Replace `TEMPLATE_MARKER_CONTEXT` and `TEMPLATE_MARKER_STACK` with a single `TEMPLATE_SENTINEL` constant set to `"<!-- story-kit:scaffold-template -->"`. Update `check_onboarding_status` to use it for both context and stack checks.
+1. **`server/src/io/onboarding.rs`**: Replace `TEMPLATE_MARKER_CONTEXT` and `TEMPLATE_MARKER_STACK` with a single `TEMPLATE_SENTINEL` constant set to `"<!-- storkit:scaffold-template -->"`. Update `check_onboarding_status` to use it for both context and stack checks.
 
-2. **`server/src/io/fs.rs`**: Add `<!-- story-kit:scaffold-template -->` as the first line of both `STORY_KIT_CONTEXT` and `STORY_KIT_STACK` template constants (lines 233 and 269).
+2. **`server/src/io/fs.rs`**: Add `<!-- storkit:scaffold-template -->` as the first line of both `STORY_KIT_CONTEXT` and `STORY_KIT_STACK` template constants (lines 233 and 269).
 
 3. **`server/src/io/onboarding.rs` tests**: Update the test `needs_onboarding_true_when_specs_contain_scaffold_markers` to use the sentinel instead of the old marker phrases. Also add a test confirming that content containing "Agentic AI Code Assistant" WITHOUT the sentinel does NOT trigger onboarding.
 
@@ -42,7 +42,7 @@ Changes needed:
 
 ## Acceptance Criteria
 
-- [ ] Scaffold templates contain the sentinel `<!-- story-kit:scaffold-template -->` as first line
+- [ ] Scaffold templates contain the sentinel `<!-- storkit:scaffold-template -->` as first line
 - [ ] `needs_onboarding()` returns false for projects whose specs contain "Agentic AI Code Assistant" but NOT the sentinel
 - [ ] `needs_onboarding()` returns true for untouched scaffold content (which contains the sentinel)
 - [ ] Existing tests updated and passing