docs(website): comprehensive documentation rewrite

website/pages/docs/_meta.json

@@ -3,6 +3,9 @@
   "getting-started": "Getting Started",
   "workflow": "The Specification Workflow",
   "guides": "Guides",
+  "concepts": "Concepts",
   "reference": "Reference",
-  "faq": "FAQ"
+  "troubleshooting": "Troubleshooting",
+  "faq": "FAQ",
+  "changelog": "Changelog"
 }

website/pages/docs/changelog.mdx

@@ -0,0 +1,51 @@
+# Changelog
+
+Track what's new, fixed, and changed in each SpecWright release.
+
+import { Callout } from 'nextra/components'
+
+SpecWright uses [semantic versioning](https://semver.org/). Releases are published automatically when changes merge to `main`.
+
+<Callout type="info">
+For the full release history with commit details, see the [GitHub Releases page](https://github.com/amelmo/specwright/releases) or the [CHANGELOG.md](https://github.com/amelmo/specwright/blob/main/CHANGELOG.md) file in the repository.
+</Callout>
+
+## 3.6.3 — February 25, 2026
+
+- **Fix:** Enable demo fixture loading in dev mode
+
+## 3.6.0 — February 23, 2026
+
+- **Feature:** Add analytics integration for the docs website
+- **Fix:** Mobile horizontal overflow on the landing page
+
+## 3.5.0 — February 23, 2026
+
+- **Feature:** Restructure workflow with unified questions and document-level approval — a major UX improvement to how you answer agent questions and review generated documents
+
+## 3.4.0 — February 16, 2026
+
+- **Feature:** Add resizable sidebar and enhanced document review workflow in the Web UI
+
+## 3.3.0 — February 11, 2026
+
+- **Feature:** Multi-AI tool routing — SpecWright now supports shipping to multiple AI coding tools from one setup
+
+## 3.2.0 — February 10, 2026
+
+- **Feature:** Manual issue status changes with drag-and-drop on the issues board
+
+## 3.0.0 — December 11, 2024
+
+Major release — complete TypeScript rewrite.
+
+- Complete TypeScript rewrite from JavaScript v2.0
+- Modern Web UI for scoping and browsing projects
+- Project playbook generation and auditing
+- Smart Scoping to classify work before specifying
+- Linear integration for syncing projects and issues
+- Five-phase specification workflow with specialized AI agents
+
+---
+
+Want to stay up to date? Watch the [GitHub repository](https://github.com/amelmo/specwright) for release notifications.

website/pages/docs/concepts/_meta.json

@@ -0,0 +1,4 @@
+{
+  "specification-driven-development": "Specification-Driven Development",
+  "vertical-slices": "Vertical Slices"
+}

website/pages/docs/concepts/specification-driven-development.mdx

@@ -0,0 +1,56 @@
+# Specification-Driven Development
+
+Specification-Driven Development (SDD) is the methodology behind SpecWright. The idea is simple: describe what you want to build, generate a structured specification, then implement from the spec — not from a vague idea.
+
+## The problem SDD solves
+
+Most software projects start the same way: someone has an idea, writes a brief description, and developers start coding. Somewhere between the idea and the code, requirements get lost. Edge cases are discovered mid-sprint. Architecture decisions are made on the fly. Features ship incomplete because nobody wrote down what "complete" looks like.
+
+This problem gets worse with AI coding tools. Tools like Cursor, Claude Code, and Copilot are powerful — but they're only as good as the context you give them. A vague prompt produces vague code. A detailed, structured specification produces focused, correct implementation.
+
+## How SDD works
+
+SDD adds a structured thinking step between "I have an idea" and "Let's start coding":
+
+1. **Describe** — You state what you want to build in plain language
+2. **Specify** — AI agents ask you targeted questions and generate structured documents: requirements, screen designs, architecture, and implementation tasks
+3. **Implement** — You (or your AI coding tool) build from the spec, with clear acceptance criteria and technical context for every task
+
+The specification isn't a formality. It's the artifact that prevents the problems listed above. When a developer picks up an issue, they know exactly what to build, how it should behave, what screens it touches, and what technology to use.
+
+## Why AI agents ask you questions
+
+SpecWright doesn't generate specs from your description alone. Each AI agent — Product Manager, Designer, Engineer — asks focused questions before producing output. You control the depth: light (2-3 questions per agent), standard (3-4), or thorough (4-6). This matters for two reasons:
+
+**You have context the AI doesn't.** You know your users, your business constraints, your technical environment, and your preferences. The questions extract this context so the specification reflects reality, not assumptions. Each agent also analyzes your existing codebase — so questions are grounded in what you already have, not generic templates.
+
+**Questions force clarity.** When you're asked "What authentication methods should be supported?", you have to decide. That decision is recorded along with the alternatives you rejected — and both feed into the specification. Your rejected alternatives become documented NoGos (scope exclusions), preventing scope creep later. The decision happens now, in the spec — not later, in a code review, when changing it costs more.
+
+## How SDD relates to existing methodologies
+
+SDD draws from established practices:
+
+- **Jobs-to-be-Done** — SpecWright uses job stories ("When [situation], I want [action], so [outcome]") instead of user stories. Job stories focus on the context and motivation behind a feature, which produces more specific requirements.
+- **Shape Up** — The scoping phase determines whether work is small enough to just do, or large enough to need a full spec. This mirrors Shape Up's concept of shaping work before building it.
+- **Vertical Slicing** — Issues are broken down as [vertical slices](/docs/concepts/vertical-slices) — self-contained pieces that deliver user-visible value through all layers of the stack.
+
+## When SDD is (and isn't) useful
+
+**SDD works well for:**
+- New features with multiple moving parts (UI, API, database, integrations)
+- Projects where multiple people need to understand the plan
+- Work that will be handed to AI coding tools — structured specs produce dramatically better AI output
+- Teams that want to version-control their decisions alongside their code
+
+**SDD is overkill for:**
+- Bug fixes and one-line changes
+- Simple configuration tweaks
+- Work where the implementation is obvious
+
+SpecWright handles this distinction automatically through [Smart Scoping](/docs/workflow/scoping). If your request is too small for a full spec, it tells you to just start coding.
+
+## Learn more
+
+- [The Specification Workflow](/docs/workflow) — How the five phases work in practice
+- [Vertical Slices](/docs/concepts/vertical-slices) — Why SpecWright structures tasks this way
+- [Getting Started](/docs/getting-started) — Try SDD on your own project

website/pages/docs/concepts/vertical-slices.mdx

@@ -0,0 +1,60 @@
+# Vertical Slices
+
+SpecWright breaks implementation work into vertical slices — self-contained tasks that deliver user-visible value through every layer of the stack. This page explains what that means and why it produces better results than the alternatives.
+
+## What a vertical slice is
+
+A vertical slice is a piece of work that cuts through all the layers needed to deliver a working feature — UI, API, database, business logic. When a developer finishes a vertical slice, something new works end-to-end. A user can see it, interact with it, or benefit from it.
+
+**Example — "Add a task to a project board":**
+
+A vertical slice for this feature includes:
+- The UI button and form for adding a task
+- The API endpoint that creates the task
+- The database schema for storing tasks
+- Validation logic for task fields
+- The board updating to show the new task
+
+After this slice is done, users can add tasks. It's incomplete — they can't edit or delete tasks yet — but it works.
+
+## Vertical vs. horizontal slicing
+
+The alternative is horizontal slicing — dividing work by technical layer:
+
+| Horizontal (layer-by-layer) | Vertical (feature-by-feature) |
+|---------------------------|-------------------------------|
+| "Set up the database schema for tasks" | "Users can create a task on the board" |
+| "Build the task API endpoints" | "Users can edit a task's title and status" |
+| "Create the task UI components" | "Users can delete a task with confirmation" |
+| "Wire up the frontend to the API" | "Users can drag tasks between columns" |
+
+With horizontal slicing, nothing works until every layer is connected. The database exists but nothing uses it. The API works but there's no UI. Bugs hide at the layer boundaries and surface late.
+
+With vertical slicing, each completed task is a working feature. Integration bugs surface immediately because every slice goes through all layers. Progress is visible — stakeholders can see and test what's done.
+
+## Why SpecWright uses vertical slices
+
+SpecWright generates issues as vertical slices because they're the best format for AI coding tools:
+
+**Clear scope.** Each issue describes a complete user-facing behavior. The AI tool knows exactly what "done" looks like — not just "build an API endpoint" but "users can create tasks, which appear on the board."
+
+**Testable in isolation.** Because each slice produces working functionality, you can verify it works before moving to the next slice. This catches problems early.
+
+**Ordered by dependency.** SpecWright sequences slices so each one builds on what came before. Slice 1 might be "users can view the board." Slice 2 is "users can add a task." The dependency chain is explicit.
+
+**Better AI output.** When you [ship an issue](/docs/guides/ship-to-ai-tools) to Cursor or Claude Code, the AI receives the full context for that slice: what to build, how it should behave, what screens it touches, and what technology to use. A well-scoped vertical slice produces focused, correct implementation.
+
+## How SpecWright structures slices
+
+During the [Issue Breakdown](/docs/workflow/issue-breakdown) phase, the Breakdown agent analyzes all previous specification documents — PRD, design brief, technical spec — and produces issues that are:
+
+- **Self-contained** — Each issue includes its own description, acceptance criteria, dependencies, and relevant specification context
+- **Sequenced** — Issues are ordered by dependency so you work through them in the right order
+- **Complexity-scored** — Each issue gets a 1-10 score mapped to estimated hours. Issues scoring 7+ are split into subtasks organized by technical layer within the vertical slice (backend, frontend, database, testing).
+- **Tested by humans** — Every issue includes manual verification steps and human-in-the-loop checks, even when automated tests are skipped. The agent follows a critical-only testing philosophy: automated tests for payments, auth, and security; manual verification for everything else.
+
+## Learn more
+
+- [Issue Breakdown](/docs/workflow/issue-breakdown) — How SpecWright generates vertical slices
+- [Ship to AI Tools](/docs/guides/ship-to-ai-tools) — How slices become AI coding prompts
+- [Specification-Driven Development](/docs/concepts/specification-driven-development) — The methodology behind the approach

website/pages/docs/faq.mdx

@@ -8,15 +8,15 @@ No. SpecWright works with whatever AI coding tool you already have installed —
 
 **What AI coding tools does SpecWright support?**
 
-SpecWright works with Cursor, Claude Code, GitHub Copilot, Codex, Gemini CLI, and Windsurf. You select your preferred tool during onboarding, and can change it anytime in Settings.
+SpecWright works with Cursor, Claude Code, GitHub Copilot, Codex, Gemini CLI, and Windsurf. Cursor, Claude Code, Codex, and Gemini support headless execution (direct CLI integration with real-time streaming). GitHub Copilot and Windsurf use keyboard automation. You select your preferred tool during onboarding, and can change it anytime in [Settings](/docs/reference/settings).
 
 **Can I use SpecWright without the Web UI?**
 
-Yes. SpecWright has both a CLI and a Web UI. The CLI can run the full specification workflow interactively in your terminal with `specwright spec`. The Web UI provides a visual dashboard with `specwright --ui`. Both produce the same output files.
+Yes. SpecWright has both a CLI and a Web UI. Most commands (like `specwright new`, `specwright ship`, `specwright view`) launch the Web UI for the visual workflow, but `specwright approve` works entirely in the terminal. The `specwright init` and `specwright finalize-scope` commands are also CLI-only. See [CLI Commands](/docs/reference/cli) for all available commands.
 
 **What does "Specification-Driven Development" mean?**
 
-SDD is a methodology where you create a structured specification before writing any code. Instead of jumping straight from an idea to implementation, SpecWright walks you through requirements, design, architecture, and task breakdown — so you (and your AI coding tool) know exactly what to build.
+SDD is a methodology where you create a structured specification before writing any code. Instead of jumping straight from an idea to implementation, SpecWright walks you through requirements, design, architecture, and task breakdown — so you (and your AI coding tool) know exactly what to build. See [Specification-Driven Development](/docs/concepts/specification-driven-development) for the full explanation.
 
 ## The Workflow
 

website/pages/docs/getting-started.mdx

@@ -41,47 +41,80 @@ cd /path/to/your/project
 specwright init
 ```
 
-This creates the `specwright/` folder with templates, agent prompts, and an outputs directory. All your specifications will live here.
+This creates the `specwright/` folder with:
+- `agents/` — AI agent prompts (PM, Designer, Engineer, Breakdown)
+- `templates/` — Output format templates
+- `outputs/` — Where generated specifications live
+
+It also creates `.cursor/commands/` at your project root with custom Cursor commands.
+
+After creating files, SpecWright asks if you want to generate a [Playbook](/docs/guides/playbooks) — a set of standards from your existing codebase.
 
 ### Launch the Web UI
 
 ```bash
-specwright --ui
+specwright view
 ```
 
-This opens the SpecWright dashboard in your browser. You'll see the onboarding screen on your first run, which walks you through selecting your preferred AI coding tool.
+This starts the server on port 5174 and opens the dashboard. On your first run, you'll see the onboarding screen, which walks you through:
+1. Selecting your preferred AI coding tool (Cursor, Claude Code, Codex, Gemini CLI, GitHub Copilot, or Windsurf)
+2. A quick intro to the workflow and AI squad
+3. Completing initialization
+
 ### Create a new project
 
-Click **New Project** and describe what you want to build in plain language. For example:
+Click **New Project**. You have two options:
+
+**AI-assisted mode (default)** — Describe what you want to build in plain language:
 
 > "Build a task management app with user authentication, project boards, and real-time collaboration"
 
-SpecWright's AI will analyze your request and determine if it needs a full specification or is small enough to implement directly. This is called [Smart Scoping](/docs/workflow/scoping).
+SpecWright classifies your request via [Smart Scoping](/docs/workflow/scoping) — it determines if this needs a full spec, is small enough to implement directly, or should be split into multiple projects.
+
+**Manual mode** — Enter a project name and description directly if you already know the scope.
 
 ### Walk through the specification phases
 
 If your request needs a full spec, SpecWright guides you through four phases — each powered by a specialized AI agent:
 
 1. **Product Manager** — Asks questions about requirements, then generates a PRD with job stories and acceptance criteria
-2. **Designer** — Asks about UX needs, then produces screen definitions and user flows
-3. **Engineer** — Asks about technical constraints, then creates architecture docs and technology choices
-4. **Issue Breakdown** — Analyzes all specs and breaks the work into implementation tasks
-
-At each phase, you answer a set of focused questions. The AI uses your answers to generate structured specification documents.
+2. **Designer** — Asks about UX needs, then produces screen definitions, wireframes, and user flows
+3. **Engineer** — Asks about technical constraints, then creates architecture docs and technology choices for you to select from
+4. **Issue Breakdown** — Analyzes all specs and breaks the work into vertical-slice implementation tasks
 
-### Review your outputs
+At each phase, you answer focused questions (the number depends on your [question depth](/docs/reference/settings) setting). The AI uses your answers to generate structured specification documents. You review each document — approve it, edit inline, or refine with AI feedback.
 
-Once all phases are complete, you'll have a full set of specifications in your `specwright/outputs/` directory:
+### Ship to your AI tool
 
-- A PRD with job stories and acceptance criteria
-- Screen designs and user flows
-- Technical architecture and technology choices
-- Implementation tasks ready for your AI coding tool
+Once issues are generated, click **Ship** on any issue. SpecWright sends a prompt to your AI coding tool with the full specification context — requirements, design decisions, architecture, acceptance criteria, and testing strategy. See [Ship to AI Tools](/docs/guides/ship-to-ai-tools).
 
 </Steps>
 
+## Your outputs
+
+After completing the workflow, your `specwright/outputs/` directory contains:
+
+```
+specwright/outputs/projects/001-your-project/
+├── project_request.md            # Your original description
+├── project_status.json           # Phase tracking
+├── questions/                    # Agent questions & your answers
+├── documents/
+│   ├── prd.md                    # Product Requirements Document
+│   ├── acceptance_criteria.json  # Testable criteria (Given/When/Then)
+│   ├── design_brief.md           # UX specification
+│   ├── screens.json              # Screen inventory with components
+│   ├── technical_specification.md # Architecture document
+│   └── technology_choices.json   # Tech decisions with trade-offs
+└── issues/
+    └── issues.json               # Implementation tasks
+```
+
+All files are plain Markdown and JSON — commit them to Git alongside your source code.
+
 ## What's next?
 
 - [The Specification Workflow](/docs/workflow) — Understand each phase in detail
-- [Using the Web UI](/docs/guides/web-ui) — Navigate the dashboard
+- [Using the Web UI](/docs/guides/web-ui) — Navigate every screen in the dashboard
 - [Ship to AI Tools](/docs/guides/ship-to-ai-tools) — Send tasks directly to Cursor, Claude Code, or other tools
+- [Settings Reference](/docs/reference/settings) — Configure question depth, document length, and more