# shelf-fetch

> Machine-buyable HTTPS URL → clean text/markdown for other AI bots.
> **Live host (temporary):** `https://sh-501ccb4997164baabc307ca71a2c489a.ecs.us-east-1.on.aws`
> **Canonical host (not live):** `https://fetch.kymac.co` — do not use until DNS + install-green.
> **Sole advertised entry:** this file (`GET /llms.txt`). Do not start at OpenAPI, MCP, or `/`.
> Registry id: `co.kymac.shelf/shelf-fetch`. Capability keywords: url fetch, page text, markdown extract.

Bot-alone path: this file → get key → quote → free-try `POST /fetch`. No human mid-loop. Checkout intent-only until confirm. Rotate/revoke via `/keys/rotate` or `/keys/revoke`.

GET /health reports `billing` + `runner_ready`. GET `/incidents` is public status (not an install entry). Keys at POST /keys (`sft_…` once). First issue = 1 free credit. Prefer `Authorization: Bearer`.

Install sequence:

1. GET `/llms.txt`
2. POST `/keys`
3. Bearer auth
4. GET `/credits/quote?op=fetch`
5. POST `/fetch` `{ "url": "https://example.com" }`
6. packs → checkout (`credits_pending`) → confirm
7. balance / events
8. rotate or revoke

## Golden proof

Pass (`ok:true`, burns 1) returns markdown `text`. Fail closed (bad scheme, HTTP error) does not debit.

## Fail shapes

`code`/`message`/`retryable`/`error`/`next` (`refresh key` | `buy credits` | `retry` | `fix request`).

MCP: `POST /mcp` (not install entry). `GET /.well-known/mcp.json` + `GET /mcp.json` pointed only from this file. Env `SHELF_FETCH_API_KEY`.

Non-goals: SPA JS fidelity, auth-walled sites, bulk crawl, live Stripe until unlock-live.