# AGENTS.md — supportsheep

supportsheep is an AI-interview and support-content platform on Cloudflare (Next.js, D1, R2, Workers).
Public site: https://supportsheep.com

## Who it is for

- Site owners and support teams who turn customer interviews into help content.
- AI agents that an owner authorizes to manage one blog through the MCP server.

Mental model: you operate one blog (tenant) through a remote MCP server.
Your API key binds you to that blog. Every tool call touches only that blog.

## Discovery

Fetch these first to learn the live interface:

- `https://supportsheep.com/.well-known/agent-card.json` — agent card
- `https://supportsheep.com/.well-known/agent-skills/index.json` — agent skills index
- `https://supportsheep.com/llms.txt` — llms.txt suite entry point
- `https://supportsheep.com/auth.md` — authentication guide

## Onboarding loop

Do these steps in order:

1. Get an invite code from a supportsheep admin.
   Admins mint codes with `POST /api/v1/signup-codes`.
2. Redeem the code with `POST /api/v1/agent/signup`.
   Send JSON body `{ "code": "...", "email": "...", "name": "..." }` (`name` is optional).
   Add `"sandbox": true` to mint a sandbox key and try the full flow with no real side effects.
   This provisions a Better Auth user.
3. Capture the API key from the signup response.
   It is shown ONCE, in plaintext. Store it immediately.
4. Call the MCP server at `https://supportsheep.com/api/v1/mcp`.
   Send header `Authorization: Bearer <key>`.
   Transport is Streamable HTTP: POST for JSON-RPC, GET for SSE, DELETE to close a session.

## MCP tools

| Module | Tools | Purpose |
| --- | --- | --- |
| interviews | `start_interview` | Mint a share link for an AI interview. Returns a join URL plus a plaintext guest token. The token is shown once. The guest opens the URL to reach the consent screen and start. |
| articles | `search_articles`, `get_article`, `list_articles`, `create_article`, `update_article`, `save_article_draft`, `publish_article`, `schedule_article`, `unpublish_article`, `delete_article` | Full article lifecycle, keyed by slug: search, read, list, create, edit, save versioned drafts, publish, schedule, unpublish, delete. |
| context | none (defines the `McpToolContext` type) | Per-request tenant scope `{ blogId, ownerId, isSandbox }` resolved from your API key. Every tool closes over it, so your calls only touch the blog the key was issued for. |
| context-tags | `list_context_tags`, `get_context_tag`, `create_context_tag`, `update_context_tag`, `delete_context_tag` | Manage generation-context presets: target audience, tone, style, language, article length, CTA, and image settings. |
| writing-skills | `list_writing_skills`, `get_writing_skill`, `create_writing_skill`, `update_writing_skill`, `delete_writing_skill`, `reorder_writing_skills`, `run_writing_skills` | Manage D1-backed writing skills (prompt plus provider/model) and run a skills pipeline against content. |

## Rules

- Your API key is shown once at signup. It cannot be retrieved later.
- The server stores the key hashed. Keep the plaintext key secret.
- Invite codes are one-use. A redeemed code does not work again.
- Rate limits exist. Back off and retry later when you are throttled.
- Interview share-link tokens are also shown once. Store them like the API key.
- A sandbox key (`{ "sandbox": true }` at signup) can list and read tools against its own account, but every mutating tool (create/update/delete/publish/generate/schedule/interview) returns a simulated success with `"sandbox": true` and performs no real write, publish, generation, email, or interview.
- Switch to a real key (omit `sandbox`, or send `false`) when you are ready to write for real.

Human-facing docs live in `README.md`.