Fission-AI
diff --git a/‎README.md‎
Lines changed: 23 additions & 3 deletions b/‎README.md‎
Lines changed: 23 additions & 3 deletions
diff --git a/‎docs/README.md‎
Lines changed: 107 additions & 0 deletions b/‎docs/README.md‎
Lines changed: 107 additions & 0 deletions
diff --git a/‎docs/cli.md‎
Lines changed: 3 additions & 1 deletion b/‎docs/cli.md‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎docs/commands.md‎
Lines changed: 2 additions & 0 deletions b/‎docs/commands.md‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎docs/editing-changes.md‎
Lines changed: 90 additions & 0 deletions b/‎docs/editing-changes.md‎
Lines changed: 90 additions & 0 deletions
@@ -47,6 +47,14 @@ Our philosophy:
 ## See it in action
 
 ```text
+You: /opsx:explore
+AI:  What would you like to explore?
+You: I want dark mode but I'm not sure how to do it cleanly.
+AI:  Let me look at your styling setup...
+     Cleanest path here: CSS variables + a small theme context,
+     with system-preference detection. No new dependencies. Scope it?
+You: Yes, let's do it.
+
 You: /opsx:propose add-dark-mode
 AI:  Created openspec/changes/add-dark-mode/
      ✓ proposal.md — why we're doing this, what's changing
@@ -94,9 +102,12 @@ cd your-project
 openspec init
 ```
 
-Now tell your AI: `/opsx:propose <what-you-want-to-build>`
+Now talk to your AI:
+
+- **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. ([Explore guide](docs/explore.md))
+- **Already know what you want?** Go straight to `/opsx:propose <what-you-want-to-build>`.
 
-If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
+Both are in the default profile. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
 
 > [!NOTE]
 > Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 25+ tools and growing.
@@ -105,15 +116,24 @@ If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/
 
 ## Docs
 
+**Start here:** the **[Documentation Home](docs/README.md)** maps everything. New to OpenSpec? Read [Getting Started](docs/getting-started.md), then [How Commands Work](docs/how-commands-work.md) (where you actually type `/opsx:propose`).
+
 → **[Getting Started](docs/getting-started.md)**: first steps<br>
+→ **[Explore First](docs/explore.md)**: think it through with `/opsx:explore` before you commit<br>
+→ **[How Commands Work](docs/how-commands-work.md)**: where slash commands run vs the CLI<br>
+→ **[Core Concepts at a Glance](docs/overview.md)**: the whole mental model, one page<br>
+→ **[Examples & Recipes](docs/examples.md)**: real changes, start to finish<br>
 → **[Workflows](docs/workflows.md)**: combos and patterns<br>
+→ **[Existing Projects](docs/existing-projects.md)**: adopt OpenSpec on a brownfield codebase<br>
+→ **[Editing a Change](docs/editing-changes.md)**: update artifacts, go back, reconcile manual edits<br>
 → **[Commands](docs/commands.md)**: slash commands & skills<br>
 → **[CLI](docs/cli.md)**: terminal reference<br>
 → **[Stores](docs/stores-beta/user-guide.md)**: plan in a separate repo, shared across your team (beta)<br>
 → **[Supported Tools](docs/supported-tools.md)**: tool integrations & install paths<br>
 → **[Concepts](docs/concepts.md)**: how it all fits<br>
 → **[Multi-Language](docs/multi-language.md)**: multi-language support<br>
-→ **[Customization](docs/customization.md)**: make it yours
+→ **[Customization](docs/customization.md)**: make it yours<br>
+→ **[FAQ](docs/faq.md)** · **[Troubleshooting](docs/troubleshooting.md)** · **[Glossary](docs/glossary.md)**: quick help
 
 
 ## Community schemas
 
@@ -0,0 +1,107 @@
+# OpenSpec Documentation
+
+Welcome. This is the home for everything OpenSpec.
+
+OpenSpec helps you and your AI coding assistant **agree on what to build before any code is written.** You describe the change, the AI drafts a short spec and a task list, you both look at the same plan, and then the work happens. No more discovering halfway through that the AI built the wrong thing.
+
+If you read nothing else, read these two pages:
+
+1. [Getting Started](getting-started.md): install, initialize, and ship your first change.
+2. [How Commands Work](how-commands-work.md): where you actually type `/opsx:propose` (hint: in your AI chat, not the terminal). This trips up almost everyone once.
+
+That second one matters more than it looks. OpenSpec has two halves: a command line tool you run in your terminal, and slash commands you give to your AI assistant. Knowing which is which saves you the most common moment of confusion.
+
+> **The best habit to build first: when you're not sure what to build, start with `/opsx:explore`.** It's a no-stakes thinking partner that reads your code, weighs options, and sharpens a fuzzy idea into a concrete plan before any artifact or code exists. The [Explore First](explore.md) guide makes the case.
+
+## Pick your path
+
+**I'm brand new.** Start with [Getting Started](getting-started.md), then skim the [Core Concepts at a Glance](overview.md). When something feels mysterious, the [FAQ](faq.md) and [Glossary](glossary.md) are nearby.
+
+**I have a problem but not a plan.** This is the common case, and it has a dedicated answer: [Explore First](explore.md). Use `/opsx:explore` to think it through with the AI before committing to anything.
+
+**I have a big existing codebase.** You don't document all of it. [Using OpenSpec in an Existing Project](existing-projects.md) shows how to start on real, brownfield code without boiling the ocean.
+
+**I just want to get it working.** [Install](installation.md), run `openspec init`, then read [How Commands Work](how-commands-work.md) so your first slash command lands in the right place.
+
+**I learn by example.** The [Examples & Recipes](examples.md) page walks through real changes start to finish: a small feature, a bug fix, a refactor, an exploration.
+
+**I'm coming from the old workflow.** The [Migration Guide](migration-guide.md) explains what changed and why, and promises your existing work is safe.
+
+**I want to bend it to my team's process.** [Customization](customization.md) covers project config, custom schemas, and shared context.
+
+**Something's broken.** [Troubleshooting](troubleshooting.md) collects the failures people actually hit, with fixes.
+
+## The whole map
+
+### Start here
+
+| Doc | What it gives you |
+|-----|-------------------|
+| [Getting Started](getting-started.md) | Install, initialize, and run your first change end to end |
+| [Explore First](explore.md) | Use `/opsx:explore` to think through an idea before you commit |
+| [How Commands Work](how-commands-work.md) | Where slash commands run, what "interactive mode" means, terminal vs chat |
+| [Core Concepts at a Glance](overview.md) | The whole mental model on one page: specs, changes, deltas, archive |
+| [Installation](installation.md) | npm, pnpm, yarn, bun, Nix, and how to verify it worked |
+
+### Use it day to day
+
+| Doc | What it gives you |
+|-----|-------------------|
+| [Workflows](workflows.md) | Common patterns and when to reach for each command |
+| [Examples & Recipes](examples.md) | Full walkthroughs of real changes, copy-pasteable |
+| [Using OpenSpec in an Existing Project](existing-projects.md) | Adopting OpenSpec on a large brownfield codebase |
+| [Editing & Iterating on a Change](editing-changes.md) | Update artifacts, go back, reconcile manual edits |
+| [Commands](commands.md) | Reference for every `/opsx:*` slash command |
+| [CLI](cli.md) | Reference for every `openspec` terminal command |
+
+### Understand it deeply
+
+| Doc | What it gives you |
+|-----|-------------------|
+| [Concepts](concepts.md) | The long-form explanation of specs, changes, artifacts, schemas, and archive |
+| [OPSX Workflow](opsx.md) | Why the workflow is fluid instead of phase-locked, plus an architecture deep dive |
+| [Glossary](glossary.md) | Every term defined in one place |
+
+### Make it yours
+
+| Doc | What it gives you |
+|-----|-------------------|
+| [Customization](customization.md) | Project config, custom schemas, shared context |
+| [Multi-Language](multi-language.md) | Generate artifacts in languages other than English |
+| [Supported Tools](supported-tools.md) | The 25+ AI tools OpenSpec integrates with, and where files land |
+
+### When you need help
+
+| Doc | What it gives you |
+|-----|-------------------|
+| [FAQ](faq.md) | Quick answers to the questions people ask most |
+| [Troubleshooting](troubleshooting.md) | Concrete fixes for concrete failures |
+| [Migration Guide](migration-guide.md) | Moving from the legacy workflow to OPSX |
+
+### Coordinate across repos (beta)
+
+| Doc | What it gives you |
+|-----|-------------------|
+| [Stores: User Guide](stores-beta/user-guide.md) | Plan in its own repo when your work spans repos or teams |
+| [Agent Contract](agent-contract.md) | The machine-readable CLI surfaces agents drive |
+
+## The thirty-second version
+
+```text
+1. Install        npm install -g @fission-ai/openspec@latest
+2. Initialize     cd your-project && openspec init
+3. Explore        (in your AI chat)  /opsx:explore           ← optional, but a great habit
+4. Propose        (in your AI chat)  /opsx:propose add-dark-mode
+5. Build          (in your AI chat)  /opsx:apply
+6. Archive        (in your AI chat)  /opsx:archive
+```
+
+Steps 1 and 2 happen in your terminal. The rest happen in your AI assistant's chat. That split is the one thing worth memorizing, and [How Commands Work](how-commands-work.md) explains exactly why. Step 3 is optional, but starting with `/opsx:explore` when you're unsure is the habit most worth forming.
+
+## Where else to get help
+
+- **Discord:** [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC) for questions, ideas, and help.
+- **GitHub Issues:** [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues) for bugs and feature requests.
+- **`openspec feedback "your message"`** sends feedback straight from your terminal (it opens a GitHub issue).
+
+Found something in these docs that's wrong, stale, or confusing? That's a bug. Open an issue or a PR. Documentation improvements are some of the most valuable contributions you can make.
@@ -104,7 +104,9 @@ openspec init [path] [options]
 
 `--profile custom` uses whatever workflows are currently selected in global config (`openspec config profile`).
 
-**Supported tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `opencode`, `pi`, `qoder`, `lingma`, `qwen`, `roocode`, `trae`, `vibe`, `windsurf`
+**Supported tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `vibe`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `windsurf`
+
+> This list mirrors `AI_TOOLS` in `src/core/config.ts`. See [Supported Tools](supported-tools.md) for each tool's skill and command paths.
 
 **Examples:**
 
 
@@ -72,6 +72,8 @@ AI:  Created openspec/changes/add-dark-mode/
 
 ### `/opsx:explore`
 
+> **Start here when you're unsure.** Explore is a no-stakes thinking partner: it reads your codebase, compares options, and sharpens a fuzzy idea into a concrete plan before any change exists. It ships in the default profile. For the full case and more examples, see the [Explore First](explore.md) guide.
+
 Think through ideas, investigate problems, and clarify requirements before committing to a change.
 
 **Syntax:**
 
@@ -0,0 +1,90 @@
+# Editing & Iterating on a Change
+
+**Every artifact in a change is just a Markdown file you can edit at any time.** There is no locked "planning phase," no approval gate, no special edit mode to enter. Want to change the proposal after you've started building? Open `proposal.md` and change it. Realized the design is wrong mid-implementation? Fix `design.md` and keep going. That's the whole answer, and it's by design.
+
+This page is for the moment you think "wait, can I go back and change that?" Yes. Here's how, for each common case.
+
+## Two ways to edit anything
+
+You always have both:
+
+1. **Edit the file directly.** Artifacts are plain Markdown in `openspec/changes/<name>/`. Open `proposal.md`, `design.md`, `tasks.md`, or a delta spec under `specs/` in your editor and change it. Nothing else is required.
+
+2. **Ask your AI to revise it.** In chat, just say what you want: "Update the proposal to drop the caching idea and add a rate-limit section," or "the design should use a queue, not polling." The AI edits the artifact for you, using the rest of the change as context.
+
+Use whichever fits the moment. Small wording tweak? Edit the file. Substantive rethink? Let the AI revise with full context.
+
+## "How do I update the proposal (or specs) after I've started?"
+
+Just update it. Same change, refined.
+
+If you're using the expanded commands, the natural flow is: edit the artifact, then run `/opsx:continue` to pick up from the new state, or `/opsx:apply` to keep implementing against the updated plan. If you're on the default `core` commands, edit the artifact and run `/opsx:apply`; it reads the current files, so it builds against whatever the artifacts now say.
+
+The mental model: artifacts are the live plan, not a signed contract. The AI always works from their current contents, so editing them steers the work.
+
+```text
+You: I want to change the approach in this change.
+
+You: [edit design.md, or tell the AI:]
+     Update design.md to use a background job instead of a synchronous call.
+
+AI:  Updated design.md. The task list still fits; want me to continue applying?
+
+You: /opsx:apply
+```
+
+This answers a very common question: there's no separate "update proposal" command because you don't need one. The file is the source of truth, and editing it (by hand or via the AI) is the update.
+
+## "How do I go back to review after implementing?"
+
+You don't have to "go back," because you never left. The workflow is fluid: review, edit, and implementation aren't sequential phases you're trapped in.
+
+Concretely, after some `/opsx:apply` work:
+
+- Want to re-examine the plan? Open the artifacts and read them, or run `openspec show <change>` in your terminal for a consolidated view.
+- Found something to change? Edit the artifact (or ask the AI to), then continue.
+- Want a structured check that the code matches the plan? Run `/opsx:verify` (expanded command). It reports completeness, correctness, and coherence without blocking anything. See [Workflows: Verify](workflows.md#verify-check-your-work).
+
+There's no "review phase" to return to, because review is something you can do at any point, including after implementation.
+
+## "I edited the code by hand. How do I reconcile that with OpenSpec?"
+
+This happens constantly and it's fine. You tweaked something in your editor, and now the code and the artifacts disagree. Bring them back in sync in whichever direction is true:
+
+- **The code is now correct, the spec is stale.** Update the delta spec (and tasks, if relevant) to describe the behavior you actually shipped. The spec should match reality before you archive, because archiving merges the spec into your source of truth.
+- **The spec is correct, the code drifted.** Keep building or fixing until the code matches the spec.
+
+A fast way to surface mismatches is `/opsx:verify`: it reads your artifacts and your code and tells you where they diverge. Treat its output as a to-do list for reconciliation, then archive once they agree.
+
+The principle: at archive time, your specs become the truth of record. So before you archive, make the specs honest about what the code does. Manual edits are welcome; just don't let them quietly desync the spec.
+
+## Refining a proposal you're not happy with
+
+If a generated proposal misses the mark, you have three good moves:
+
+- **Iterate in place.** Tell the AI what's off ("the scope is too broad, drop the admin features") and let it revise. Cheapest and usually right.
+- **Explore first, then re-propose.** If the problem is that the idea itself is unclear, step back to `/opsx:explore`, think it through, and let a sharper proposal come out of that. See [Explore First](explore.md).
+- **Start fresh.** If the intent has fundamentally changed, a new change can be clearer than patching the old one.
+
+That last move has its own decision guide, next.
+
+## When to update vs. start a new change
+
+Short version: **update when it's the same work refined; start new when the intent fundamentally changed or the scope exploded into different work.**
+
+- Same goal, better approach? Update.
+- Scope narrowing (ship the MVP now, more later)? Update, then archive, then a new change for phase two.
+- The problem itself changed ("add dark mode" became "build a full theming system")? New change.
+
+There's a full flowchart and worked examples in [Workflows: When to Update vs Start Fresh](workflows.md#when-to-update-vs-start-fresh) and a deeper treatment in [OPSX: When to Update vs. Start Fresh](opsx.md#when-to-update-vs-start-fresh).
+
+## A note on tasks
+
+`tasks.md` is a living checklist, not a frozen plan. As you implement, you can add tasks you discover, remove ones that turned out unnecessary, or reorder them. The AI checks items off as it completes them during `/opsx:apply`, and it resumes from the first unchecked task if you come back later. Editing the list mid-flight is expected.
+
+## Where to go next
+
+- [Workflows](workflows.md) - patterns, plus the update-vs-new decision guide
+- [Explore First](explore.md) - the place to step back to when an idea needs rethinking
+- [Commands](commands.md) - `/opsx:continue`, `/opsx:apply`, and `/opsx:verify` in detail
+- [Concepts: Artifacts](concepts.md#artifacts) - what each artifact is for