These docs follow a simple rule: tutorials teach, how-to guides solve one job, reference pages answer exact questions. Nothing here is filler — if a page exists, a command or workflow needed it.

Content is edited in wiki/*.md in the repo; the site pages are generated from it.

Where to start

Your goal	Start here
Install the CLI	Install
First `.specui/` in an app	Quick start
Pick a workflow — monorepo, DS repo, agents, shadcn	Scenarios
Understand the mental model	Concepts
Wire Cursor, Claude, or MCP	Agents & MCP
Give the agent a ready prompt	Agent prompts
Feed the docs to an LLM or crawler	/llms.txt
Fail PRs when the spec breaks	CI/CD
Look up any command	CLI reference
Look up any `init` flag	init reference
Something broke	Troubleshooting
Quick answers	FAQ

How these docs are written

Commands you can paste. Examples use npx @logicplanes/specui@latest or npx specui from the project root unless a page says otherwise.
Register before code. Every how-to repeats the same loop: specui add → implement → validate → sync → commit .specui/ with the code.
One source of truth. .specui/ (or a flat SPEC.md repo) is canonical; exports are regenerated, never hand-edited.
Agents are first-class. AGENTS.md, .specui/AGENTS-GUIDE.md, rules, skills, and MCP get the same coverage as human workflows.
Strict in CI. validate --strict is the recommended production gate throughout.

Every page

Getting started

Page	Covers
Introduction	What SpecUI is, comparisons, layouts, doc map
Install	npx, global, devDependency, verifying, offline installs
Quick start	Tutorial: `init` → `doctor` → `add` → `validate` → optional `get`
Concepts	The contract, consumer vs flat layout, registry, tokens, presets

How-to guides

Page	Covers
Scenarios	Web app, flat DS, monorepo, agent-first, shadcn, export, migrate, upgrade, open source
Tokens & components	`add token/component/asset/pattern`, TOKENS.yaml, manifests
Agents & MCP	AGENTS.md, AGENTS-GUIDE, rules, skills, MCP hooks
Agent prompts	Copy-paste prompts to install SpecUI with a coding agent
CI/CD	validate in CI, GitHub Actions, JSON output, monorepos, pre-commit
Distribution	load, link, unlink, push, pull, import, export, update, diff
Registries	`get`, shadcn, custom JSON registries, when to use `load` instead
Interop	designmd, dtcg, tailwind, css, json, tarball, dir exports
DESIGN.md bridge	SpecUI as canonical source with DESIGN.md as an export
Validation	validate, strict mode, JSON output, doctor, how sync relates
Troubleshooting	install, init, validate, get, load, MCP, wiki, docs URLs

Reference

Page	Covers
CLI reference	Every command, exit codes, environment variables
init reference	Presets, flags, worked examples
Schema	Files, folders, front matter, components, assets, patterns
Specification	Normative summary, link to the full `docs/SPEC.md`

Community

Page	Covers
Contributing	Contributing to SpecUI vs documenting your own app
FAQ	Short answers with links to the long ones

The whole CLI, mapped to docs

Area	Commands	Primary doc
Scaffold	`init`, `new`	init reference, CLI
Register	`add component\|asset\|token\|pattern`	Tokens & components
Quality	`validate`, `sync`, `doctor`	Validation
Inspect	`list`	CLI
Registry	`get`	Registries
Distribute	`load`, `link`, `unlink`, `push`, `pull`, `import`, `export`, `update`, `diff`	Distribution, Interop
Agents	`rules`, `skills`, `spec`, `mcp`	Agents & MCP
Meta	`--help`, `--version`	CLI

Docs that live in the repo instead

Path	Audience
`docs/SPEC.md`	The normative standard (print it with `specui spec`)
`docs/schema.md`	Maintainer-level schema detail
`.specui/AGENTS-GUIDE.md` in your app	Agent reference shipped by `specui init`

New here? Install, then the quick start. Know what you're building? Pick a scenario. Just have a question? Try the FAQ.

Documentation overview