> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfacearea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Start with your coding agent

> Install the platform's guides into your repository, then paste a prompt into Claude Code, Cursor or Codex to have it set up worlds, scenarios, tracing and CI for you.

Once the `gateway` CLI is installed and signed in, your coding agent can do most of the setup. Install the packaged guides so it knows the platform, then paste one of the prompts below and fill in the parts in angle brackets.

## Give your agent the guides

Run this at the root of your repository. It writes the platform's guides into `.claude/skills/`, where Claude Code picks them up; other agents can read the same files.

```bash theme={null}
gateway worlds skill --install .
```

To read or search the guides yourself:

```bash theme={null}
gateway skill list
gateway skill search <topic words>
```

## Connect the docs

These docs are also an MCP server, so your agent can search and read them while it works instead of guessing.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http surface-area-docs https://docs.surfacearea.ai/mcp
    ```
  </Tab>

  <Tab title="Cursor">
    In **Open MCP settings** → **Add custom MCP**, add to `mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "surface-area-docs": { "url": "https://docs.surfacearea.ai/mcp" }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    In `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.surface-area-docs]
    url = "https://docs.surfacearea.ai/mcp"
    ```
  </Tab>

  <Tab title="Claude">
    In **Settings** → **Connectors**, select **Add custom connector** and use the URL `https://docs.surfacearea.ai/mcp`.
  </Tab>
</Tabs>

The menu at the top of every page also copies the URL or connects it to Cursor and VS Code in one click.

<Info>
  The docs server only reads documentation. To let your agent act on your
  project (create worlds, open sessions, run evals), add the platform's
  [MCP server](/mcp/setup) too.
</Info>

Every prompt below asks the agent to read the right guide first. That keeps it on the commands that exist rather than guessing.

## Orient yourself

Start here if you are not sure what to build yet.

```text wrap theme={null}
Read the Surface Area guides installed in .claude/skills (run `gateway skill list` if you can't find them) and check `gateway auth status`. Then look at this repository and tell me, in a short list:
1. which external systems and APIs my agent calls,
2. which of them Surface Area ships a world template for (`gateway worlds schema templates`),
3. the smallest first world and scenario you would build to test my agent, and why.
Don't create anything yet.
```

## Create your first world

```text wrap theme={null}
Using the worlds-getting-started guide, create a world for <vendor, e.g. Slack> from the shipped template, open a session on it, call one of its routes, grade the session, and close it. Show me each command you ran and the world's link in the dashboard.
```

## Mock your own API

```text wrap theme={null}
Using the worlds-getting-started guide, build a world from our API spec at <path or URL to openapi.yaml> with `gateway worlds schema init <dir> --from-openapi <spec>`. Keep every entity and route the spec declares, add a few realistic rows of invented data, run `gateway worlds schema check` until it passes, then publish the first version and open a session to prove the routes answer.
```

## Load data into a world

```text wrap theme={null}
Using the world-data-ingestion guide, load <file, export, or "the tool calls in our recent traces"> into the world <world slug>. Run `gateway worlds describe` first so the rows match the world's entities and keys, report anything that was refused and why, and do not invent fields that aren't in the source.
```

## Write scenarios and run my agent

```text wrap theme={null}
Using the worlds-getting-started and benchmarks-getting-started guides, write <number> scenarios for the world <world slug> that cover what my agent in <path to agent code> is supposed to do. Each scenario needs a clear instruction and a grader that checks the world's end state. Then wire my agent up as an agent module, run every scenario with `gateway worlds run`, and summarise the pass rate and the failures.
```

## Build a benchmark

```text wrap theme={null}
Using the benchmarks-getting-started guide, turn <tasks, a harbor task tree, or a description of the job> into a benchmark. Pick the right kind (a world with tasks, or a container benchmark), validate it, do a dry run, and push it. Tell me how to run it against two models and read the per-task results.
```

## Trace my agent

```text wrap theme={null}
Instrument the agent in <path> with the Surface Area SDK so every run is traced to my project. Use the tracing docs at https://docs.surfacearea.ai/tracing/setup, read credentials from GATEWAY_HOST, GATEWAY_PUBLIC_KEY and GATEWAY_SECRET_KEY, run it once, and confirm the trace appears with `gateway traces list`.
```

## Gate pull requests in CI

```text wrap theme={null}
Add a CI job that runs my agent against the world <world slug> on every pull request and fails when the score drops below <threshold>, using `gateway worlds ci` (see `gateway worlds ci --help` and https://docs.surfacearea.ai/use-cases/evals-in-ci). Keep the agent module and world checked into the repository, keep the keys in CI secrets, and show me the workflow file before committing it.
```

## Put rules around my agent's tool calls

```text wrap theme={null}
Using the hooks-getting-started guide (`gateway skill show hooks-getting-started`), write a gateway-hooks.toml for the agent in <path> that <deny / record / redact what you need>. Validate it with `gateway hooks check gateway-hooks.toml` and wire it into the agent.
```

## Next step

Prefer to drive it yourself? The [Quickstart](/get-started/quickstart) walks the same first world by hand.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.