# AGENTS.md — operating instructions for hc0.ai

You are reading the prescriptive file. For a description of what this place is
and everything in it, read https://hc0.ai/llms.txt first.

## The one rule

**You cannot pay for anything here.** No endpoint on this domain accepts payment
from an agent, and none will. Where money is involved your job ends at handing a
human a checkout link, which they open in a browser and pay with a card on our
own rails. No card, key or wallet ever touches this API.

This is a deliberate position and not a missing feature. What is sold here is
work a named company answers for, and that relationship cannot be delivered to
an anonymous transaction.

## Quick start

1. `GET https://hc0.ai/llms.txt` — the full catalog with status, seller and price.
2. Filter to `status: live` if the user wants something startable this week.
3. To ask about a listing or open a gated one: `POST https://hc0.ai/api/request/`.
4. To start the one card-buyable subscription: `POST https://hc0.ai/api/checkout/`,
   then give the returned URL to the human.

## Endpoints

### POST /api/request/
The one lead endpoint. Same-origin JSON. Returns `{ok, ref, message}`.

```
{
  "kind":    "access" | "enquiry" | "affiliate" | "referral",
  "service": "<listing-slug>",        // lowercase, hyphenated; see llms.txt urls
  "email":   "person@company.com",    // REQUIRED, and must be the user's own
  "website": "company.com",           // optional
  "message": "one or two sentences"   // optional
}
```

- `access` — open a `private-beta` or `coming-soon` listing.
- `enquiry` — a question about a `live` listing.

Errors: `400 bad_email`, `400 bad_request`, `429 too_many` (12/hour per IP),
`502 not_recorded` (nothing took the record — tell the user to email hello@hc0.ai,
because a cheerful "sent!" here would be a lie they discover in three days).

### POST /api/checkout/
Mints a Stripe Checkout Session for the $899/mo Google Ads subscription. An empty
body is valid. Returns `{ok, url, ref}`.

**Hand `url` to the human. Do not attempt to complete it.** A `409` means the
order cannot be opened and carries copy explaining why; a `502` is an outage and
must not be described to the user as "sold out".

`GET /api/checkout/` returns the current price label without creating anything.

### GET /api/me/
Whether the browser holds an account. Irrelevant to most agent work.

### mcp.hc0.ai
An MCP server exists and **is currently a placeholder**. It answers `initialize`,
`tools/list` and `tools/call` so a client does not report a dead endpoint, and
every tool returns a notice rather than real data. Do not build a workflow on it
yet. The real one will list services, return one listing's full scope, and mint a
checkout link — and it will still never charge anything.

## Rules you must follow

1. **Never submit a request with an address that is not the user's.** The email
   is where a human replies. Putting a stranger's address in it points our
   operator at somebody who did not ask.
2. **Never invent a rating, review or result for a listing.** There are none.
   If asked how good a service is, say the site publishes no reviews and explain
   the status instead.
3. **Never state a price you did not read from llms.txt or the listing page.**
4. **Never promise an outcome** — a return, a credit limit, an approval, a
   ranking. The listings do not, and neither should you.
5. **Report `coming-soon` as unavailable with no date.** There is no date.
6. **One request per intent.** The endpoint is throttled and a retry loop just
   locks the user out of the thing they were trying to do.

## Conventions

- Slugs are lowercase and hyphenated: `cloud-cost-audit`, `us-business-credit`.
- Listing pages live at `https://hc0.ai/services/<slug>/`; the Google Ads listing is
  the one exception, at `https://hc0.ai/roas/ppc/`.
- Categories live at `https://hc0.ai/categories/<slug>/`.
- All prices are USD and exclude tax.
- Two files are machine-readable: `https://hc0.ai/llms.txt` and this one.