docs: comprehensive overhaul — discoverability, explore-first, and closing recurring doc-request issues

[clay-good]

Summary

A comprehensive, documentation-only overhaul addressing #1228 ("the docs are fragmented and, in practice, almost nonexistent") and the broader maintainer feedback that the docs in general need work, and /opsx:explore should be a lot more front and center.

The existing reference docs were actually fairly thorough, so the real problems were discoverability, a missing new-user mental model, explore being undersold, and a set of recurring questions that good docs should answer but didn't. This PR fixes all of that while staying additive (new pages plus small surgical edits; no reference doc was rewritten wholesale).

What's new

Orientation and mental model

• docs/README.md — a documentation home / index that maps every doc and offers "pick your path" routes (the direct fix for "fragmented").
• docs/how-commands-work.md — the single biggest gap from the issue thread: /opsx:* runs in your AI chat, openspec runs in your terminal, what "interactive mode" really means, per-tool syntax, and how to confirm install. (Answers the "how do I start interactive mode?" comments directly.)
• docs/overview.md — core concepts on one page.
• docs/glossary.md — every term in one place.

Explore, front and center

• docs/explore.md — a dedicated "Explore First" guide. The canonical loop is reframed as explore → propose → apply → archive, and explore now leads the README demo, Quick Start, docs home, getting-started, overview, how-commands-work, and workflows (promoted out of "expanded mode," since it ships in the default profile).

Closing recurring doc-request issues

• docs/existing-projects.md — adopting OpenSpec on a large brownfield codebase without documenting everything up front (How can I use OpenSpec in a large existing project，what is the first step I should do? #510, if i have tla+ and srs docs, how can i create project with openspec? #1100, Question: Best practices for scaling OpenSpec in a large monorepo? #176).
• docs/editing-changes.md — editing any artifact, updating a proposal/spec after starting, going back after implementing, reconciling manual code edits (How to update specifications during the apply phase? #684, how to update the existing change,such as propose.md #976, How to return to the Review phase after Implement Tasks? #355, Add a command to update proposal ,design and task #1188, How should manual code edits be reconciled with OpenSpec? #169, Is there a good solution for refine proposal now? #1206).
• docs/faq.md, docs/troubleshooting.md — consolidated answers, including context limits / long sessions (How to use OpenSpec when context exceeds limits or requirements change after implementation？ #257) and uninstalling (How to uninstall OpenSpec #308).
• docs/examples.md — seven real changes, start to finish.

Accuracy and surgical edits

• installation.md — added Updating and Uninstalling sections (How to uninstall OpenSpec #308).
• cli.md — --tools list now includes vibe and matches AI_TOOLS in src/core/config.ts, with a pointer to the source (docs/cli.md tool ID list out of sync with src/core/config.ts #1213).
• getting-started.md, commands.md, workflows.md, README.md — small additive edits: a "where do I type this?" callout, a first-five-minutes path, explore prominence, and updated docs lists.

Issues addressed

Primary: #1228. Also closes or substantially answers the doc-shaped parts of: #510, #1100, #176, #684, #976, #355, #1188, #169, #1206, #257, #308, #1213. Complements (no overlap with) the open #1146 beginner-workflow guide.

Validation

• Documentation-only. git diff is limited to docs/ and README.md; no code changed.
• All internal links and section anchors verified to resolve.
• Voice is warm and bottom-line-up-front; no em-dashes in prose; every file starts with an H1 (per Generated MD file documentation should follow MD041/first-line-heading/first-line-h1: First line in a file should be a top-level heading #1138 / fix(templates): start generated docs with H1 headings #1163).

Note to maintainers

Opened from a fork as a collaborator. Happy to split this into smaller PRs (for example, land the docs home + how-commands-work.md first) if that's easier to review. Feedback very welcome.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added/expanded the documentation hub and new end-user guides: Getting Started, How Commands Work, Core Concepts (at a glance), Explore, Examples & Recipes, Editing & Iterating, Existing Projects, FAQ, Glossary, and Troubleshooting.
  • Updated Quick Start and workflow examples to route new users through /opsx:explore early, including “Start here when unsure” guidance and revised command-flow diagrams.
  • Enhanced operational support with clearer installation/update/uninstall instructions, broader CLI tool notes, and more actionable troubleshooting fixes.
  • Refreshed the README with a filled “See it in action” dialogue example and reorganized documentation entry points.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f36aab20-a258-4783-9985-7b46a3d15cd6

📥 Commits

Reviewing files that changed from the base of the PR and between f75a62c and 7ad51b0.

📒 Files selected for processing (3)

• docs/README.md
• docs/existing-projects.md
• docs/glossary.md

✅ Files skipped from review due to trivial changes (3)

• docs/README.md
• docs/glossary.md
• docs/existing-projects.md

---

📝 Walkthrough

Walkthrough

Adds new documentation pages for concepts, examples, FAQ, glossary, troubleshooting, and workflow guidance. Updates README.md, getting-started.md, and command reference pages to route users toward the explore-first flow.

Changes

OpenSpec Documentation Expansion and Navigation Redesign

Layer / File(s)	Summary
Navigation entry points and onboarding flow README.md, docs/README.md, docs/getting-started.md	README.md adds a /opsx:explore example, revises Quick Start routing, and expands docs links. docs/README.md is added as the documentation landing page. docs/getting-started.md adds command-context guidance, updates the quick-path diagram, and extends Next Steps.
Core concepts and command model docs/overview.md, docs/how-commands-work.md, docs/glossary.md	Adds the core concepts overview, command-context guide, and terminology glossary for OpenSpec.
Examples and recipes docs/examples.md	Adds seven workflow recipes, terminal inspection commands, and follow-up links.
Explore, editing, existing projects, and installation docs/explore.md, docs/editing-changes.md, docs/existing-projects.md, docs/installation.md	Adds explore guidance, artifact editing workflow, brownfield adoption guidance, and update/uninstall instructions.
FAQ and troubleshooting reference docs/faq.md, docs/troubleshooting.md	Adds FAQ content plus symptom-based troubleshooting for setup, commands, configuration, migration, and support.
Command reference updates docs/cli.md, docs/commands.md, docs/workflows.md	Updates supported tool IDs, adds explore guidance, and reorders the default quick path to start with /opsx:explore.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• docs/cli.md tool ID list out of sync with src/core/config.ts #1213: The docs/cli.md update adds the missing vibe tool ID to the supported tool list.

Possibly related PRs

• Fission-AI/OpenSpec#746: Touches the same workflow and command-reference docs while shifting the default explore/propose flow.
• Fission-AI/OpenSpec#1027: Also updates the docs/cli.md supported tool IDs list to match AI_TOOLS.

Suggested reviewers

• TabishB

Poem

🐇 I hopped through the docs with a curious nose,
Found explore-first paths where the new guidance goes.
A glossary, recipes, FAQs in a row,
Now the warren has maps for wherever folks go.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the PR’s docs overhaul, improved discoverability, and stronger explore-first emphasis.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/faq.md (1)

43-43: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick win

Fix awkward grammar in the skill/command explanation.

Line 43: "OpenSpec installs whichever your tool uses" is grammatically incomplete. "Whichever" requires an object noun.

Suggested revision: "OpenSpec installs whichever commands your tool needs."

Proposed wording fix

- Both are files OpenSpec writes so your assistant can run the workflow. Skills (`.../skills/openspec-*/SKILL.md`) are the newer cross-tool standard; commands (`.../commands/opsx-*`) are the older per-tool slash files. You don't need to pick. You just type the slash command, and OpenSpec installs whichever your tool uses.
+ Both are files OpenSpec writes so your assistant can run the workflow. Skills (`.../skills/openspec-*/SKILL.md`) are the newer cross-tool standard; commands (`.../commands/opsx-*`) are the older per-tool slash files. You don't need to pick. You just type the slash command, and OpenSpec installs whichever commands your tool needs.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/faq.md` at line 43, The sentence in the skill/command explanation
contains a grammar error where "whichever" lacks a noun object, leaving the
statement incomplete. Revise the phrase "OpenSpec installs whichever your tool
uses" by adding an appropriate noun after "whichever" to complete the
grammatical structure, such as "OpenSpec installs whichever commands your tool
needs" or similar phrasing that provides the missing object noun.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/faq.md`:
- Line 43: The sentence in the skill/command explanation contains a grammar
error where "whichever" lacks a noun object, leaving the statement incomplete.
Revise the phrase "OpenSpec installs whichever your tool uses" by adding an
appropriate noun after "whichever" to complete the grammatical structure, such
as "OpenSpec installs whichever commands your tool needs" or similar phrasing
that provides the missing object noun.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 858bb264-a68f-4ba5-a534-677f25c9ade1

📥 Commits

Reviewing files that changed from the base of the PR and between 1b06fdd and c37253c.

📒 Files selected for processing (9)

• README.md
• docs/README.md
• docs/examples.md
• docs/faq.md
• docs/getting-started.md
• docs/glossary.md
• docs/how-commands-work.md
• docs/overview.md
• docs/troubleshooting.md

[clay-good]

Pushed a follow-up commit acting on the feedback that the docs need more work and that /opsx:explore should be a lot more front and center.

explore already ships in the default core profile, but every doc led with propose and treated explore as a footnote for "unclear requirements." This reframes the canonical loop as explore → propose → apply → archive and gives explore real prominence:

• New docs/explore.md ("Explore First"): a dedicated guide. When to use it, what it does and doesn't do, a full transcript, the handoff to propose, and honest tradeoffs.
• Featured at the top of the high-traffic pages: the repo README's "See it in action" demo and Quick Start now open with explore; the docs home, getting-started, overview, how-commands-work, and workflows all lead with "start by exploring when you're unsure."
• Promoted out of expanded mode: workflows.md now has a first-class "Start by exploring" pattern in the default section (it was previously only shown under the expanded command set).
• Reference touchpoints: commands.md, faq.md, and glossary.md all surface explore as the recommended starting point.

Still docs-only and additive. No em-dashes in prose; relative links verified. Happy to keep iterating, and as before I can split this into smaller PRs if that's easier to review.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

docs/existing-projects.md (2)

27-35: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick win

Reduce repetition of "exactly" in nearby sentences.

Lines 31 and 33 both use "exactly" within close proximity ("This is exactly what brownfield work needs" and "which is exactly when you want it thorough"). Consider rephrasing one of them using alternatives like "precisely," "this," or restructuring the sentence.

Proposed fix

-This is exactly what brownfield work needs. You're rarely building from nothing. You're adding a field, fixing a redirect, tightening a timeout. A delta lets you specify that one change precisely without first writing a 40-page spec of everything around it.
+This is what brownfield work needs. You're rarely building from nothing. You're adding a field, fixing a redirect, tightening a timeout. A delta lets you specify that one change precisely without first writing a 40-page spec of everything around it.

And:

-The spec for `auth/` becomes thorough only after you've made several auth changes, which is exactly when you want it thorough.
+The spec for `auth/` becomes thorough only after you've made several auth changes, which is when you want it thorough.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/existing-projects.md` around lines 27 - 35, The section "Why delta-first
is the whole trick" uses the word "exactly" twice in close proximity: once in
the phrase "This is exactly what brownfield work needs" and again in "which is
exactly when you want it thorough". To reduce repetition, rephrase one of these
instances by replacing "exactly" with an alternative word like "precisely" or
"this," or by restructuring the sentence to convey the same meaning without
repeating the word.

---

11-14: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick win

Bash command blocks need either output or no dollar signs (MD014).

Lines 12–13 and 74–75 show $ prefixes without subsequent command output. Either remove the $ or add placeholder output like # output: or > openspec init installed.

Proposed fix (remove `$` prefixes)

-$ cd your-existing-project
-$ openspec init          # adds openspec/ and your AI tool's commands
+cd your-existing-project
+openspec init          # adds openspec/ and your AI tool's commands

Similarly for lines 74–75:

-$ openspec config profile      # select the expanded workflows
-$ openspec update              # apply them to this project
+openspec config profile      # select the expanded workflows
+openspec update              # apply them to this project

Also applies to: 73-76

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/existing-projects.md` around lines 11 - 14, The bash code blocks at
lines 12-13 and 74-75 contain dollar sign ($) command prompts but do not include
any subsequent output or results, which violates the MD014 markdown linting
rule. Remove the dollar sign prefixes from these bash command blocks in the
existing-projects.md file so that the commands appear without prompts. This
applies to both the cd and openspec init commands in the first block and the
corresponding commands in the second block referenced at lines 73-76.

docs/explore.md (1)

9-11: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick win

Consider alternative to "right first step" to improve word variety.

Line 11 ("Explore is the right first step more often than people expect") uses "right" where the phrase could also leverage "best," "ideal," or restructure slightly. If "right" appears elsewhere in nearby context, this will feel repetitive.

Proposed alternatives

-Explore is the right first step more often than people expect.
+Explore is the best first step more often than people expect.

Or:

-Explore is the right first step more often than people expect.
+In most cases, explore is the right first move more often than people expect.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/explore.md` around lines 9 - 11, In the sentence "Explore is the right
first step more often than people expect", replace the word "right" with a more
varied alternative such as "best" or "ideal" to improve word variety and avoid
repetition if "right" appears elsewhere in the nearby context. Alternatively,
consider restructuring the sentence entirely to convey the same meaning while
improving readability and vocabulary diversity.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/cli.md`:
- Line 110: The supported tool IDs list is out of order and does not match the
AI_TOOLS array in src/core/config.ts. Reorder the tools in the Supported tool
IDs list so that vibe appears immediately after lingma and before opencode,
instead of appearing near the end between trae and windsurf. This will ensure
the documentation accurately mirrors the source-of-truth configuration as
claimed.

---

Nitpick comments:
In `@docs/existing-projects.md`:
- Around line 27-35: The section "Why delta-first is the whole trick" uses the
word "exactly" twice in close proximity: once in the phrase "This is exactly
what brownfield work needs" and again in "which is exactly when you want it
thorough". To reduce repetition, rephrase one of these instances by replacing
"exactly" with an alternative word like "precisely" or "this," or by
restructuring the sentence to convey the same meaning without repeating the
word.
- Around line 11-14: The bash code blocks at lines 12-13 and 74-75 contain
dollar sign ($) command prompts but do not include any subsequent output or
results, which violates the MD014 markdown linting rule. Remove the dollar sign
prefixes from these bash command blocks in the existing-projects.md file so that
the commands appear without prompts. This applies to both the cd and openspec
init commands in the first block and the corresponding commands in the second
block referenced at lines 73-76.

In `@docs/explore.md`:
- Around line 9-11: In the sentence "Explore is the right first step more often
than people expect", replace the word "right" with a more varied alternative
such as "best" or "ideal" to improve word variety and avoid repetition if
"right" appears elsewhere in the nearby context. Alternatively, consider
restructuring the sentence entirely to convey the same meaning while improving
readability and vocabulary diversity.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c8793466-d8d9-45dc-9112-16af284ba5d6

📥 Commits

Reviewing files that changed from the base of the PR and between c37253c and 7552233.

📒 Files selected for processing (15)

• README.md
• docs/README.md
• docs/cli.md
• docs/commands.md
• docs/editing-changes.md
• docs/examples.md
• docs/existing-projects.md
• docs/explore.md
• docs/faq.md
• docs/getting-started.md
• docs/glossary.md
• docs/how-commands-work.md
• docs/installation.md
• docs/overview.md
• docs/workflows.md

✅ Files skipped from review due to trivial changes (8)

• docs/overview.md
• docs/README.md
• docs/how-commands-work.md
• README.md
• docs/glossary.md
• docs/workflows.md
• docs/getting-started.md
• docs/examples.md

[lorenzoceglia]

Hi! Thanks for creating the PR for my issue. One thing I wanted to bring up: wouldn't it be nice to add this information to the main website, just like other library docs? I assume those .md doc files are meant for agents, right?

[clay-good]

Hi! Thanks for creating the PR for my issue. One thing I wanted to bring up: wouldn't it be nice to add this information to the main website, just like other library docs? I assume those .md doc files are meant for agents, right?

Hi @lorenzoceglia, yes these are for the repo (humans and agents alike). Pinging @TabishB about the website copy.

[lorenzoceglia]

@clay-good Let me know if I can help :)

[TabishB]

Thanks for all the improvements! I think this is a really good step in the right direction @clay-good

[TabishB]

@lorenzoceglia We're definitely keen to add a proper docs site for OpenSpec. I'd be keen to get something set up with Fuma Docs. I wouldn't mind someone taking a stab at it to begin with.

Feel free to reach out to me on discord to coordinate and/or email (tabish@openspec.dev). Or whatever other messaging platform you prefer.