# Agent quick start

Written for the agent, not the human. What to do beyond Installation, what to report back, and the machine-readable surfaces.

You are a coding agent trying Rystic for a human. [Installation](https://www.rystic.ai/docs/installation.md) is the quickstart for you both; this page holds only what you need beyond it. [What you can do](https://www.rystic.ai/docs/what-you-can-do.md) maps each task to the page that explains it.

## What to do

1. **Follow [Installation](https://www.rystic.ai/docs/installation.md) end to end.** [Without a browser](https://www.rystic.ai/docs/installation.md#without-a-browser-ci-and-agents) says what to hand the human at the sign-in, which you cannot approve.
2. **Ask which plan they are on**, Free, Pro or Enterprise. An Enterprise customer may hand you a license file or install link instead ([Plans and API keys](https://www.rystic.ai/docs/licensing.md)).
3. **Discover before guessing** ([Discover what a simulator can do](https://www.rystic.ai/docs/installation.md#discover-what-a-simulator-can-do)): `rystic docs <product>`, [`GET /_rystic/routes`](https://www.rystic.ai/docs/control-plane-reference.md#rystic-routes), the scenario list.
4. **Try each simulator the human cares about.** Run the Quickstart on its page, load a [scenario](https://www.rystic.ai/docs/concepts/glossary.md#scenario), read [`GET /_rystic/egress`](https://www.rystic.ai/docs/control-plane-reference.md#rystic-egress) and run one worked example from that page.
5. **Optional, only if the human asked:** point this repository's client at the simulator and run its existing tests against it ([below](#swap-the-vendor-for-the-simulator-in-a-test-suite)).
6. **Report back** ([below](#what-to-report)).

Each simulator has a page under [Simulators](https://www.rystic.ai/docs.md#simulators).

## What to report

1. The login output and `rystic doctor <product>` for each simulator.
2. `rystic ps`.
3. One request and response per simulator.
4. Anything that failed or returned `403` or `404`, with the command and the body.
5. Anything the human's code relies on that the simulator's page lists under Limitations.

## Two things agents get wrong

1. **Webhooks are not sent by default.** Where [Which simulators send what](https://www.rystic.ai/docs/webhooks.md#which-simulators-send-what) says the egress log holds them, assert on the log instead of a receiver.
2. **A scenario file has a wrapper.** Its records sit under `seed`: [Two shapes](https://www.rystic.ai/docs/concepts/worlds.md#two-shapes).

## Swap the vendor for the simulator in a test suite

1. Where the client is constructed, add a base-URL override from an environment variable (`STRIPE_API_BASE`, `GITHUB_API_URL`) that defaults to the vendor.
2. Start the simulator detached. In test setup, [`POST /_rystic/scenario`](https://www.rystic.ai/docs/control-plane-reference.md#rystic-scenario) with the scenario the test needs, so tests are order-independent.
3. Assert on [`GET /_rystic/egress`](https://www.rystic.ai/docs/control-plane-reference.md#rystic-egress) ([above](#two-things-agents-get-wrong)).
4. Run the suite. For each failure, check the simulator page's limitations before touching the test.
5. `rystic stop <name>` in teardown.

To run the same suite in GitHub Actions, see [Integration tests in CI](https://www.rystic.ai/docs/integration-testing.md). To inject latency or `429`s, see [Network profiles and fault injection](https://www.rystic.ai/docs/network-profiles.md).

## Tell Rystic

When a simulator differs from the real API, or something fails, is missing or confuses you, `rystic feedback` files a report. Send one only when the human asks, and show them it first.

```bash
rystic feedback --type bug --command "stripe POST /v1/charges" \
  --task "charge a declined test card" --expected "402 card_declined" --actual "200 succeeded" \
  "the simulator accepted tok_chargeDeclined"
# filed <report id> — thank you; Rystic reads every report
```

Past 100 reports an hour per key it returns `rate_limited`; do not retry. [`rystic feedback`](https://www.rystic.ai/docs/cli-reference.md#feedback) lists its flags and what the CLI adds.

## Machine-readable surfaces

| Surface | Where | Use when |
|---|---|---|
| This page as Markdown | `https://www.rystic.ai/docs/agent-quick-start.md` | first read; append `.md` to any docs URL for the raw page |
| `rystic docs` | the CLI, offline | one page or section in the terminal: `rystic docs <slug>`, `rystic docs search <terms>` |
| Agent skill | `https://www.rystic.ai/.well-known/agent-skills/rystic/skill.md` | your agent loads skills |
| Skills index | `https://www.rystic.ai/.well-known/agent-skills/index.json` | discovery, with a content digest to detect a changed skill |
| Docs MCP | `https://www.rystic.ai/mcp` | searching these docs over MCP ([not `rystic mcp`](https://www.rystic.ai/docs/mcp-server.md#the-docs-mcp-is-a-different-server)) |
| `rystic mcp` | the CLI, local MCP over stdio | driving simulators as tool calls: [Drive simulators from your coding agent](https://www.rystic.ai/docs/mcp-server.md) |
| MCP server card | `https://www.rystic.ai/.well-known/mcp/server-card.json` | tool schemas without connecting |
| `llms.txt` | `https://www.rystic.ai/llms.txt` | one line per page, the compact index |
| `llms-full.txt` | `https://www.rystic.ai/llms-full.txt` | every page as one file, for a single context load |

Claude Code takes the docs MCP in one line:

```bash
claude mcp add --transport http rystic https://www.rystic.ai/mcp
```

---

Source: https://www.rystic.ai/docs/agent-quick-start · Markdown: https://www.rystic.ai/docs/agent-quick-start.md