# Build with an AI agent

> Point Claude, Cursor or any coding agent at mongrl and get a storefront that runs against real types, not guesses.

mongrl is built to be built on by coding agents. Everything an agent needs is machine-readable, in one place, and kept in sync with the API by the build.

## What to give your agent

| Resource | Use it for |
|---|---|
| [`/llms.txt`](https://dev.mongrl.com/llms.txt) | The entry point: what mongrl is, the rules, and links to every page as Markdown. |
| [`/llms-full.txt`](https://dev.mongrl.com/llms-full.txt) | Every guide and the full API reference in one file, for agents with a big context. |
| [`/llms-small.txt`](https://dev.mongrl.com/llms-small.txt) | The same, trimmed, for smaller contexts. |
| [`/openapi.json`](https://dev.mongrl.com/openapi.json) | The public API spec. Generate the client from it. |
| [`/AGENTS.md`](https://dev.mongrl.com/AGENTS.md) | Rules to keep in the storefront repo, so every session follows them. |
| Any page + `.md` | One topic as Markdown, e.g. [`/guides/checkout.md`](https://dev.mongrl.com/guides/checkout.md.md). |

## Set up the repo

```sh
curl -o AGENTS.md https://dev.mongrl.com/AGENTS.md
curl -o openapi.json https://dev.mongrl.com/openapi.json
```

If your agent reads `CLAUDE.md` rather than `AGENTS.md`, add a `CLAUDE.md` that says `@AGENTS.md`.

Then put the keys in your environment, never in the repo:

```sh
MONGRL_API_URL=https://api.staging.mongrl.com
MONGRL_SECRET_KEY=sk_test_…
STRIPE_PUBLISHABLE_KEY=pk_test_…   # the marketplace's Stripe account
```

## A first prompt

```text
Read https://dev.mongrl.com/llms.txt and AGENTS.md. We're building the storefront
for our marketplace on mongrl, with <your stack, e.g. TanStack Start / Next.js>.

1. Generate a typed client from openapi.json with @hey-api/openapi-ts.
2. Add a server-only mongrl client (secret key from MONGRL_SECRET_KEY, the
   user's session from an HttpOnly cookie as X-User-Session).
3. Build the shop page: search with q, category and brand filters, sort, and
   cursor paging, showing display_price in the visitor's currency.
4. Build the listing page from getListing.

Use only endpoints and fields from openapi.json. Show problem `detail`s from
errors to people. Stop and show me the shop page before going further.
```

Then go area by area, one guide per step, so the agent loads only what it needs:

1. Accounts: "Follow https://dev.mongrl.com/guides/accounts.md: sign-up, sign-in with password and with emailed links, confirm email, reset password."
2. Checkout: "Follow https://dev.mongrl.com/guides/checkout.md and https://dev.mongrl.com/guides/delivery.md."
3. Selling: "Follow https://dev.mongrl.com/guides/selling.md and https://dev.mongrl.com/guides/payouts.md."
4. Messages and the pages emails link to: "Follow https://dev.mongrl.com/guides/messages.md and https://dev.mongrl.com/guides/storefront-pages.md."

## Why agents get it right here

- **One spec, generated from code.** The spec on this site is built from the API's own code on every release. An agent coding against it codes against what the API does.
- **Types, not guesses.** With a generated client, a wrong field or path fails to compile instead of failing in production.
- **Errors that say how to fix them.** Validation errors name the field (`body.price.amount`) and the problem, so an agent can correct its own request.
- **Safe retries.** Idempotency keys make a repeated write run once, so an agent (or a flaky network) can't buy twice.
- **Test keys.** `sk_test_…` keys and Stripe test cards let an agent run the whole flow without touching real orders or money.