Agents

Most people will reach Stepwise through a coding agent rather than these docs. Everything here is set up so an agent can find the components, learn how to call them, and install them without guessing.

The quickest path

Give the agent the reference once, then ask for whatever you are building:

Stepwise UI's full reference is at https://ui.stepwise.studio/llms.txt
Read it before using the library.

The install command, the setup rules and every component are already in that file, so the prompt does not need to repeat them. No plugin, no configuration, and it works with any assistant that can read a URL.

llms.txt

ui.stepwise.studio/llms.txt is the whole library as plain text, generated from the same registry the CLI installs from, so it cannot drift from what you actually get.

It contains the setup rules first, then every component as:

#### frame

The raw, unopinionated content container.

- Install: `npx stepwise-ui add frame`
- Docs: https://ui.stepwise.studio/docs/frame
- Exports: Frame, FrameContent, FrameDescription, FrameFooter, FrameHeader, FrameTitle

```tsx
import { Frame } from '@/components/stepwise/frame'

<Frame className="p-5">
  Whatever you want goes here.
</Frame>
```

Why the exports matter. Without them an agent has no way to know that frame also exports FrameHeader and four more, or that toast exports both a toast() function and a <Toaster />. The alternative is downloading every component's source and parsing it.

AGENTS.md

llms.txt tells an agent what exists. A project rule file tells it what to do by default, so it reaches for Stepwise instead of writing a button from scratch. Drop this into your repo:

## Stepwise UI

UI components come from Stepwise UI. Do not hand-write a component that
already exists in the registry, and do not install a package for it.

Add one with the CLI, which writes the source into this project:

    npx stepwise-ui add <component>

List everything available:

    npx stepwise-ui list --all

Do NOT run `npx stepwise-ui init`. It is an interactive picker and needs a
real terminal; use `add` instead.

Full component reference, including exports and a usage example for each:
https://ui.stepwise.studio/llms.txt

Rules:
- Components land in `components/stepwise/`. They are normal project files
  and may be edited directly.
- Never add `stepwise-ui` to package.json. It is only ever run via npx.
- `add` never edits project config, which is why it is the command to use here.
  Do not run `init` to fix setup: it is interactive, and accepting its offer to
  add the path alias rewrites tsconfig.json as plain JSON and drops any comments.
  Make the two changes below by hand instead.
- Dark mode is class-based. `app/globals.css` must contain
  `@custom-variant dark (&:where(.dark, .dark *));` or every `dark:` class
  in every component silently does nothing.
- Requires Tailwind CSS v4 and the `@/` path alias.

The dark-mode line is the one worth keeping. It is the single most common way a Stepwise install looks broken, and an agent has no way to guess it.

Registry API

Skip this unless you are building tooling. Everything above is enough to use Stepwise with an agent. This section is for anyone writing an editor plugin, a bot, or their own integration, and for anyone who wants to check that the file above is telling the truth.

The registry is plain JSON over HTTP. /r/index.json lists every component with its metadata and a usage example, in one request:

[
  {
    "name": "frame",
    "description": "The raw, unopinionated content container.",
    "category": "components",
    "dependencies": ["@lisse/react", "clsx", "tailwind-merge"],
    "peerDependencies": ["react"],
    "registryDependencies": [],
    "exports": ["Frame", "FrameContent", "FrameDescription",
                "FrameFooter", "FrameHeader", "FrameTitle"],
    "example": "import { Frame } from '@/components/stepwise/frame'\n\n<Frame className=\"p-5\">…</Frame>"
  }
]

/r/<name>.json returns the same thing plus the full contents of every file that component installs. That is exactly what the CLI fetches, so an agent reading it sees precisely what would land on disk. It is also generated from the same source as llms.txt, which is why the two cannot disagree.

Per-tool setup

The block above is plain markdown, so it goes wherever your tool reads project rules from:

Tool	File	Notes
Claude Code	`CLAUDE.md or AGENTS.md`	Read automatically from the project root. Nested files apply to their own directory.
Cursor	`.cursor/rules/*.mdc`	Paste the block into a rule file. Legacy .cursorrules also works.
Windsurf	`.windsurfrules`	Project root. Read on every request in the workspace.
GitHub Copilot	`.github/copilot-instructions.md`	Applies to Copilot Chat across the repository.
Codex CLI	`AGENTS.md`	Read from the project root.
Zed	`.rules`	Project root.
Anything else	`AGENTS.md`	The emerging cross-tool convention. Start here if unsure.

Whichever you use, the agent still installs components the same way:

npx stepwise-ui add button

What about MCP?

There is no MCP server, deliberately. An MCP server would be another service to run and keep in sync, and the registry is already a plain HTTP API that any agent can read without one.

If you have a workflow where an MCP server genuinely beats fetching llms.txt, say so on GitHub.