Set Up an Agent

An agent builds correctly with OPERATOR when it has two things: a short set of rules and a component index that are always in front of it, and a way to look up the rest at the moment it needs it. operator-ds init provides the first, and the lookup commands the second.

Write the instructions

Run this once in the project:

pnpm exec operator-ds init

It writes a block into AGENTS.md, between <!-- OPERATOR:START --> and <!-- OPERATOR:END -->: the house rules as "use this, not that" pairs, one line per component saying what it is for, the recipes, and the commands that print the rest. The block is about 10 KB. Whatever else the file holds is kept.

Name an agent to write the file it reads:

Run init again after an upgrade: it replaces only its block. --dry-run previews, and --remove takes the block out. operator-ds doctor reports a block that is missing or was written by an older version.

The instruction file is the place for this because an agent reads it on every turn without being asked. A document it has to decide to open is opened less often than it is needed.

Look things up

The block tells the agent to use these instead of guessing. Each prints the facts for the installed version.

pnpm exec operator-ds search "table with selection"
pnpm exec operator-ds component DataGrid --dense
pnpm exec operator-ds component --list

• search <need> ranks the components and recipes that answer a need, and follows redirects: "go to another page" leads to Link, because Button is not for that.
• component <Name> prints one component: what it is for, what to use instead, every prop, what each option value is for, its nesting rules and its example. --dense is the short form for an agent; without it the full descriptions are included. Several names can be given at once.
• component --list prints every component in one line each, parts under their parent.

Every command takes --json and answers in one envelope, { apiVersion, type, data }. A failure is { apiVersion, error, code, suggestions }. The code is stable: a caller branches on it, never on the wording. suggestions holds the nearest valid names.

Other ways in

The same content, from the same source, for agents that work differently.

Model Context Protocol. operator-ds mcp serves search, get_component, list_components, get_instructions and check_code on stdin and stdout. For Claude Code, in .mcp.json:

{
  "mcpServers": {
    "operator-ds": { "command": "pnpm", "args": ["exec", "operator-ds", "mcp"] }
  }
}

Plain pages. This site serves /llms.txt, an index for agents; /llms/instructions.md, the block as a page; and one plain page per component, such as /llms/components/button.md.

A skill. skills/operator-ds/SKILL.md in the repository is a short method for agents that load skills: find, read, write, check. It holds no component facts of its own; it sends the agent to the commands.

Where it all comes from

One source feeds every one of these: each component's manifest (what it accepts) and packages/manifest/scripts/guidance.mjs (when to choose it, and what each option is for). The build fails when a component has no guidance or a note names a value its prop no longer takes, so none of them can describe a component the library does not ship. See Extending the Manifest.