docs: combined overhaul — brand, MCP, content cleanup, onboarding, skills, nav (PRs #168, #170-174)

.gitignore

@@ -0,0 +1 @@
+superpowers/

agents.mdx

@@ -1,96 +1,173 @@
 ---
-title: 'Agents'
-description: 'Programmatic agent onboarding — sign up and obtain API keys in one call, no dashboard, no human in the loop.'
+title: "Agent Onboarding"
+description: "The operating manual for AI agents using the Recoup API."
 ---
 
-## Quickest start
+This page is for AI agents that act on a user's behalf. Follow the steps in order.
 
-Get a working API key in a single unauthenticated request:
+<Note>
+**Just trying the API yourself?** See [Quickstart](/quickstart) for a 5-minute hello-world. This page is the production operating manual. It covers the throwaway-vs-account decision, the roster, the filesystem, and the agent loop.
+</Note>
 
-```bash
-curl -X POST "https://api.recoupable.com/api/agents/signup" \
-  -H "Content-Type: application/json" \
-  -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}'
-```
+## 0. Choose your path
 
-Response:
+**Ask the human which path they want before authenticating.** Guessing wrong creates records under a throwaway account that can't be recovered if the API key is lost. The user re-prompts later and their roster is gone.
 
-```json
-{
-  "account_id": "123e4567-e89b-12d3-a456-426614174000",
-  "api_key": "recoup_sk_abc123...",
-  "message": "If this is a new agent+ email, your API key is included. Otherwise, check your email for a verification code."
-}
-```
+Use this question. Paraphrase if needed, but keep the trade-off explicit:
 
-That's it. Store `api_key`, pass it in the `x-api-key` header on every subsequent request, and you're done.
+> "Are you just exploring Recoup, or do you want me to set this up against your account so the work persists? If you have an account, what email should I use? Otherwise I'll create a temporary account, but you won't be able to save artists, releases, or scheduled tasks under it."
 
-<Tip>
-**One-liner — sign up and export the key in one shot.** Drop this into your shell and you'll have `$RECOUP_API_KEY` ready to use on the next line:
+Once you have the answer, match the human's intent to the right path:
 
-```bash
-export RECOUP_API_KEY=$(curl -s -X POST "https://api.recoupable.com/api/agents/signup" \
-  -H "Content-Type: application/json" \
-  -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key)
-```
+| Human's answer | Auth path | Then |
+|----------------|-----------|------|
+| "Just exploring / quick demo / one-shot research" | Throwaway [`agent+...@recoupable.com`](#1-authenticate) signup | Use research and content endpoints. **Don't create artists.** They'll orphan when the API key is lost. |
+| "I have an account, here's my email" (existing roster) | Sign in with their real email | List [`/api/artists`](/api-reference/artists/list); work with the roster they already have |
+| "I have an account, here's my email" (new artist) | Sign in with their real email | Run the [`create-artist`](https://github.com/recoupable/skills/tree/main/skills/create-artist) skill |
+| "I don't have an account but I want to set one up" | Sign in with their real email | After auth, run the [`create-artist`](https://github.com/recoupable/skills/tree/main/skills/create-artist) skill to start their roster |
 
-Verify it worked:
+**The key distinction:** `agent+` emails create isolated, unrecoverable accounts. Use them ONLY for one-shot work (research, content generation) where losing the API key has no cost. For anything that creates persistent records (artists, releases, scheduled tasks), use the user's real email.
 
-```bash
-curl -H "x-api-key: $RECOUP_API_KEY" https://api.recoupable.com/api/accounts/id
-```
-</Tip>
+**When you can skip the question:** if the human's instruction explicitly names the path (e.g., *"just try the demo"*, *"use my Recoup account, my email is x@y.com"*, or you were invoked autonomously by another agent with no human in the loop), you don't need to ask. Proceed directly.
 
-<Tip>
-The `agent+{unique-suffix}@recoupable.com` shape is the recommended path for agents — it always returns an API key instantly, with no email verification required. Combining `$(date +%s)` with `$RANDOM` guarantees a fresh, collision-free address on every call (including multiple signups within the same second) and is portable across macOS and Linux shells.
-</Tip>
+## 1. Authenticate
 
-## How it works
+If your human has an API key, pass it via `x-api-key`. If not, generate one based on the path you chose above. **Note**: the throwaway `agent+...@recoupable.com` path returns the API key immediately on signup with no verification step. Skip steps 2 and 3 below.
 
-Two unauthenticated endpoints power agent onboarding:
+<Steps>
+  <Step title="Call signup with their email">
+    ```bash
+    curl -X POST "https://api.recoupable.com/api/agents/signup" \
+      -H "Content-Type: application/json" \
+      -d '{"email": "user@example.com"}'
+    ```
+    For an `agent+...@recoupable.com` email, the response includes `api_key` directly. Store it (e.g. `export RECOUP_API_KEY=your-api-key`) and you're done. For any other email, the response says a verification code was sent; continue with steps 2 and 3.
+  </Step>
+  <Step title="Ask the human for the code">
+    A 6-digit code was sent to their inbox. Ask them: *"Check your email for a verification code and share it with me."*
+  </Step>
+  <Step title="Call verify with the code">
+    ```bash
+    curl -X POST "https://api.recoupable.com/api/agents/verify" \
+      -H "Content-Type: application/json" \
+      -d '{"email": "user@example.com", "code": "123456"}'
+    ```
+    Store the returned `api_key` (e.g. `export RECOUP_API_KEY=your-api-key`) and pass it as `x-api-key` on every request.
+  </Step>
+</Steps>
 
-- **[`POST /api/agents/signup`](/api-reference/agents/signup)** — Register with an email address. Emails with the `agent+` prefix that have never been seen before receive an API key immediately. Any other email (or a previously-used `agent+` address) receives a 6-digit verification code via email.
-- **[`POST /api/agents/verify`](/api-reference/agents/verify)** — Submit the verification code to receive an API key.
+**After authenticating, immediately check the roster.** Don't wait for the human to tell you what to do.
 
-Multiple API keys per account are supported — each signup or verification generates a new key without revoking existing ones.
+<Warning>
+`agent+` emails create a **separate account**. `agent+user@example.com` is NOT linked to `user@example.com`. To work on behalf of an existing human, use their real email.
+</Warning>
 
-## Standard signup (email verification)
+---
 
-If you're building a human-facing integration and want the user to verify their real email, use any non-`agent+` address:
+## 2. Understand the roster
 
-Step 1 — request a verification code:
+After getting a key, your next call should always be to check what the human has:
 
 ```bash
-curl -X POST "https://api.recoupable.com/api/agents/signup" \
-  -H "Content-Type: application/json" \
-  -d '{"email": "you@example.com"}'
+# List all artists available to this account
+curl "https://api.recoupable.com/api/artists" \
+  -H "x-api-key: $RECOUP_API_KEY"
+
+# List organizations (labels/teams) the account belongs to
+curl "https://api.recoupable.com/api/organizations" \
+  -H "x-api-key: $RECOUP_API_KEY"
+```
+
+**If the human has artists**, you can scope work to a specific artist by passing `artist_account_id` on supported endpoints. Research, content, tasks, and fan data all become artist-specific.
+
+**If the human has organizations**, pass `organization_id` to scope to a specific label's roster.
+
+**If neither is specified**, you operate at the account level and can see everything available to the human.
+
+---
+
+## 3. Know the filesystem
+
+Each account has a persistent filesystem backed by a GitHub repo. This is where artist context lives. Files agents use to do informed work.
+
+### Artist directory structure
+
 ```
+orgs/{org-name}/artists/{artist-slug}/
+├── RECOUP.md                              # Identity file (artistName, artistSlug, artistId)
+├── context/
+│   ├── artist.md                          # Brand voice, bio, constraints
+│   ├── audience.md                        # Audience insights, resonance
+│   ├── era.json                           # Current era metadata
+│   └── images/
+│       └── face-guide.png                 # Face reference for visual content
+├── songs/{song-slug}/
+│   └── {song-slug}.mp3                    # Audio files
+├── releases/{release-slug}/
+│   └── RELEASE.md                         # Release plan and metadata
+└── config/
+    └── content-creation/
+        └── config.json                    # Pipeline overrides
+```
+
+The `RECOUP.md` file ties the folder to the platform. It contains YAML frontmatter with `artistName`, `artistSlug`, and `artistId`.
 
-Step 2 — submit the 6-digit code from the verification email:
+### Accessing sandbox files
 
 ```bash
-curl -X POST "https://api.recoupable.com/api/agents/verify" \
+# List the full file tree
+curl "https://api.recoupable.com/api/sandboxes" \
+  -H "x-api-key: $RECOUP_API_KEY"
+
+# Read a specific file
+curl "https://api.recoupable.com/api/sandboxes/file?path=orgs/my-label/artists/drake/context/artist.md" \
+  -H "x-api-key: $RECOUP_API_KEY"
+
+# Upload files to the repo
+# path is top-level (target directory); each file needs url + name
+curl -X POST "https://api.recoupable.com/api/sandboxes/files" \
+  -H "x-api-key: $RECOUP_API_KEY" \
   -H "Content-Type: application/json" \
-  -d '{"email": "you@example.com", "code": "123456"}'
+  -d '{"path": "orgs/my-label/artists/drake/context", "files": [{"url": "https://...", "name": "audience.md"}]}'
 ```
 
-Response:
+---
 
-```json
-{
-  "account_id": "123e4567-e89b-12d3-a456-426614174000",
-  "api_key": "recoup_sk_abc123...",
-  "message": "Verified"
-}
-```
+## 4. Decide what to do
 
-## Using your API key
+<Steps>
+  <Step title="Does the human have a roster?">
+    Call `GET /api/artists`. If they have artists, list them and ask which one to work with. If not, you can research any artist with `GET /api/research?q=...` or create one with `POST /api/artists`.
+  </Step>
+  <Step title="What kind of work?">
+    **Research.** Use the 30+ research endpoints. Pass `artist_account_id` to scope to a rostered artist, or search by name for any artist globally.
 
-Pass the returned `api_key` in the `x-api-key` header on every authenticated request:
+    **Content.** Generate images, videos, and captions with the content endpoints. Artist context from the filesystem makes output more on-brand.
 
-```bash
-curl -X GET "https://api.recoupable.com/api/tasks" \
-  -H "x-api-key: YOUR_API_KEY"
+    **Manage.** Plan and track releases by creating and updating `RELEASE.md` files in the artist's `releases/` directory. Add songs to catalogs, update artist context, and organize the roster.
+  </Step>
+  <Step title="Should you save the work?">
+    Save research, generated content, or notes to the artist's directory in the filesystem so future calls have more context. Use `POST /api/sandboxes/files` to upload files to the repo.
+  </Step>
+  <Step title="Should this be recurring?">
+    If the human asks for something more than once, or if the work is time-sensitive and repeating, turn it into a task with `POST /api/tasks`.
+
+    Good candidates for tasks:
+    - Daily or weekly reports (streaming stats, fan growth, playlist adds)
+    - Monitoring competitors or trending artists
+    - Generating recurring content (weekly social posts, monthly recaps)
+    - Checking release milestones as a date approaches
+
+    If the human only needs it once, just do it. Don't create a task for everything.
+  </Step>
+</Steps>
+
+---
+
+## Base URL
+
+```
+https://api.recoupable.com/api
 ```
 
-See [Authentication](/authentication) for the full authentication model, including organization access and Bearer token support, and [Quickstart](/quickstart) for your first end-to-end request.
+All endpoints require `x-api-key` header unless noted. See [Authentication](/authentication) for the full auth model, and the [endpoint map](/#for-ai-agents) for every available endpoint.

api-reference/image/generation.mdx

@@ -1,4 +1,4 @@
 ---
-title: 'Generate Image'
+title: 'Generate Image (Legacy)'
 openapi: "/api-reference/openapi/content.json GET /api/image/generate"
 ---

api-reference/openapi/ai.json

@@ -10,7 +10,7 @@
   },
   "servers": [
     {
-      "url": "https://recoup-api.vercel.app"
+      "url": "https://api.recoupable.com"
     }
   ],
   "paths": {