overview

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

1. Commands you can paste. Examples use npx @logicplanes/specui@latest or npx specui from the project root unless a page says otherwise.
2. Register before code. Every how-to repeats the same loop: specui add → implement → validate → sync → commit .specui/ with the code.
3. One source of truth. .specui/ (or a flat SPEC.md repo) is canonical; exports are regenerated, never hand-edited.
4. Agents are first-class. AGENTS.md, .specui/AGENTS-GUIDE.md, rules, skills, and MCP get the same coverage as human workflows.
5. 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

---

Next

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