docs: agent-first onboarding overhaul#172
Open
recoupableorg wants to merge 7 commits intomainfrom
Open
Conversation
|
Warning Rate limit exceeded
To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (4)
📝 WalkthroughWalkthroughDocumentation restructured to adopt an agent-centric onboarding approach. Five MDX files transformed with updated authentication flows (multi-step signup/verify), expanded agent guidance with persistent storage warnings, reorganized API overview with functional cards, refreshed quickstart using research API examples, and preconditions added to workflow documentation. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 4 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="agents.mdx">
<violation number="1" location="agents.mdx:48">
P2: Use a single documented env var name for auth headers (`RECOUP_API_KEY`) instead of `$API_KEY` to keep examples copy/paste-safe and consistent.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
recoupableorg
pushed a commit
that referenced
this pull request
Apr 27, 2026
The page used $API_KEY in 5 curl examples but quickstart.mdx (and the rest of the docs) document RECOUP_API_KEY as the env var to set after signup. Rename all 5 occurrences for consistency, and add a one-line note in step 1 explaining how to set the env var after receiving the api_key from /agents/verify, so the variable used in subsequent examples isn't undefined. Caught by cubic-dev-ai on PR #172. Made-with: Cursor
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="agents.mdx">
<violation number="1" location="agents.mdx:29">
P2: The export example uses `<value>` in a Bash command, which is interpreted as input redirection and can fail when users copy-paste it.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
recoupableorg
pushed a commit
that referenced
this pull request
Apr 28, 2026
Bash interprets `<value>` as input redirection from a file named "value", so the previous example failed with "no such file or directory" when copy-pasted. Use `your-api-key` instead, matching the convention already in cli.mdx. Caught by cubic-dev-ai on PR #172. Made-with: Cursor
Rewrites the onboarding surface so AI agents landing on the docs
can self-serve API access in two unauthenticated curl calls instead
of being routed to a browser-based dashboard signup. The four pages
in this PR form one coherent narrative — index → quickstart →
authentication → agents — and they're now consistent with each
other.
index.mdx (homepage):
- New <Info> box at the top dedicated to agents, with the base URL,
auth model, and one-step signup decision tree.
- Reorganized into three reader paths: REST API, MCP Server, CLI.
- New "What's in the API" card group organized by what agents do
(Chat, Research, Artists, Catalog, Content, Automation, Accounts)
rather than by HTTP verb or resource shape.
- New "For AI agents" footer section with a domain → OpenAPI spec
table, root-relative paths so the links don't 404 if served from
a non-prod domain.
quickstart.mdx:
- Two-call agent-signup flow as the primary path (signup → ask user
for verification code → verify → API key in env var).
- Tabbed code samples (cURL / Python / JavaScript) all pull the API
key from RECOUP_API_KEY env var consistently — no literal
YOUR_API_KEY placeholders.
- Removed the fictional `recoup research "Drake"` CLI snippet.
authentication.mdx:
- Honest, scoped access-control rules: account_id, organization_id,
and artist_account_id each documented separately with allow/deny
conditions.
- Single source of truth for the HMAC-SHA256 storage note (was
previously duplicated in two places).
- Note that BOTH /agents/signup and /agents/verify are
unauthenticated, so readers don't wonder which header to send to
/verify before they have a key.
agents.mdx:
- Reframes as the "operating manual for AI agents using the Recoup
API" — explicit, ordered steps an agent should follow on first
contact: authenticate → understand the roster → know the
filesystem → decide what to do.
- Documents the artist-workspace filesystem convention
(orgs/{org}/artists/{slug}/RECOUP.md, context/, songs/, etc.)
so agents know how to persist context across runs.
- Sandbox upload example uses the correct request shape
({path, files: [{url, name}]}) per the OpenAPI spec.
These changes don't touch nav structure or content reference pages
— those concerns ship in the other stack PRs.
Made-with: Cursor
The page used $API_KEY in 5 curl examples but quickstart.mdx (and the rest of the docs) document RECOUP_API_KEY as the env var to set after signup. Rename all 5 occurrences for consistency, and add a one-line note in step 1 explaining how to set the env var after receiving the api_key from /agents/verify, so the variable used in subsequent examples isn't undefined. Caught by cubic-dev-ai on PR #172. Made-with: Cursor
Bash interprets `<value>` as input redirection from a file named "value", so the previous example failed with "no such file or directory" when copy-pasted. Use `your-api-key` instead, matching the convention already in cli.mdx. Caught by cubic-dev-ai on PR #172. Made-with: Cursor
recoupableorg
force-pushed
the
feat/docs-onboarding
branch
from
164f42a to
8025291
Compare
…rning
Helps agents pick the right auth path BEFORE they authenticate, and
warns them away from creating persistent records under throwaway
accounts.
agents.mdx — new "## 0. Choose your path" section:
A decision-tree table mapping each scenario to the right auth path:
- Research/content output, no persistent state
→ throwaway agent+...@recoupable.com signup
→ DON'T create artists
- Has account, work with existing roster
→ sign in with real email
→ list /api/artists
- Has account, add a new artist
→ sign in with real email
→ run /workflows/create-artist
- No account but wants persistent state
→ sign in with real email
→ run /workflows/create-artist after auth
Followed by an explicit "key distinction" callout:
agent+ emails create isolated, unrecoverable accounts. Use them
ONLY for one-shot work where losing the API key has no cost. For
persistent records, use the user's real email.
This sits BEFORE step 1 so agents make the choice up front instead
of falling through to the default flow.
workflows/create-artist.mdx — new <Warning> at the top:
Don't run this workflow under a throwaway agent+ account. Artist
data is permanently isolated to that account and can't be
recovered if the API key is lost. See /agents#0-choose-your-path
for guidance.
Why this matters:
The signup endpoint takes three paths (verified against
api/lib/agents/agentSignupHandler.ts):
1. Existing account → always sends verification code, returns
api_key: null
2. Brand-new agent+ email → creates isolated account, returns key
instantly. No recovery mechanism.
3. Brand-new normal email → sends verification code
Path 2 is the throwaway path. Each unique agent+xyz creates a
separate account; data created on one is unreachable from another.
If the API key is lost, the data is permanently orphaned (the email
recovery code goes to a Recoupable inbox nobody monitors).
Without this guidance, a literal-minded agent following the docs
could create artists under a throwaway account and silently produce
data that can't be retrieved later.
Made-with: Cursor
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@agents.mdx`:
- Around line 12-17: Update the last table row in agents.mdx so the auth action
clearly indicates account creation rather than sign-in: change the "Sign in with
their real email" cell in the final scenario row (the "User has no Recoup
account yet but wants persistent state" row) to "Sign up with their real email"
(or "Sign up / create an account with their real email") and keep the Then
column unchanged ("After auth, run Create a New Artist workflow...") so readers
understand this path requires signup rather than signin.
- Around line 63-100: The filesystem section contradicts itself about where
artist folders live; update either the prose or the example tree so they match:
if artists live at the top level, change the example path from
orgs/{org-name}/artists/{artist-slug}/ to artists/{artist-slug}/ (keeping
RECOUP.md, context/, songs/, releases/, and config/ entries and filenames like
RECOUP.md and config/content-creation/config.json), otherwise change the prose
to say artists live under orgs/{org-name}/artists/{artist-slug}/ so the text and
the example tree are consistent.
In `@quickstart.mdx`:
- Around line 2-22: Update the frontmatter description to match the documented
flow: change the description string that currently reads "API key in 2 calls.
First request in minutes. No signup form, no dashboard." to reflect that a
dashboard fallback exists (for example, mention the dashboard option or remove
the "no dashboard" phrase) so the page summary aligns with the content under the
"Get your API key" section and the Tip referencing chat.recoupable.com/keys;
edit the frontmatter block near the "title: \"Quickstart\"" entry.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 582470c3-59cc-4777-b86f-e2b624b492f4
📒 Files selected for processing (5)
agents.mdxauthentication.mdxindex.mdxquickstart.mdxworkflows/create-artist.mdx
Comment on lines
+12
to
+17
| | Scenario | Auth path | Then | | ||
| |----------|-----------|------| | ||
| | User wants research or content output and doesn't need persistent state | Throwaway [`agent+...@recoupable.com`](#step-1-fast-throwaway) signup | Use research and content endpoints. **Don't create artists** — they'll orphan when the API key is lost. | | ||
| | User has a Recoup account and wants you to act on their existing roster | Sign in with their real email | List [`/api/artists`](/api-reference/artists/list); work with the roster they already have | | ||
| | User has a Recoup account and wants to add a new artist to their roster | Sign in with their real email | Run the [Create a New Artist](/workflows/create-artist) workflow | | ||
| | User has no Recoup account yet but wants persistent state | Sign in with their real email | After auth, run [Create a New Artist](/workflows/create-artist) to start their roster | |
There was a problem hiding this comment.
Use “sign up” for the no-account path.
The last row says a user with no Recoup account should “Sign in with their real email,” which reads like they already have an account. That row should clearly distinguish sign-up/authentication from sign-in.
Suggested fix
-| User has no Recoup account yet but wants persistent state | Sign in with their real email | After auth, run [Create a New Artist](/workflows/create-artist) to start their roster |
+| User has no Recoup account yet but wants persistent state | Sign up with their real email | After auth, run [Create a New Artist](/workflows/create-artist) to start their roster |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| | Scenario | Auth path | Then | | |
| |----------|-----------|------| | |
| | User wants research or content output and doesn't need persistent state | Throwaway [`agent+...@recoupable.com`](#step-1-fast-throwaway) signup | Use research and content endpoints. **Don't create artists** — they'll orphan when the API key is lost. | | |
| | User has a Recoup account and wants you to act on their existing roster | Sign in with their real email | List [`/api/artists`](/api-reference/artists/list); work with the roster they already have | | |
| | User has a Recoup account and wants to add a new artist to their roster | Sign in with their real email | Run the [Create a New Artist](/workflows/create-artist) workflow | | |
| | User has no Recoup account yet but wants persistent state | Sign in with their real email | After auth, run [Create a New Artist](/workflows/create-artist) to start their roster | | |
| | Scenario | Auth path | Then | | |
| |----------|-----------|------| | |
| | User wants research or content output and doesn't need persistent state | Throwaway [`agent+...@recoupable.com`](`#step-1-fast-throwaway`) signup | Use research and content endpoints. **Don't create artists** — they'll orphan when the API key is lost. | | |
| | User has a Recoup account and wants you to act on their existing roster | Sign in with their real email | List [`/api/artists`](/api-reference/artists/list); work with the roster they already have | | |
| | User has a Recoup account and wants to add a new artist to their roster | Sign in with their real email | Run the [Create a New Artist](/workflows/create-artist) workflow | | |
| | User has no Recoup account yet but wants persistent state | Sign up with their real email | After auth, run [Create a New Artist](/workflows/create-artist) to start their roster | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@agents.mdx` around lines 12 - 17, Update the last table row in agents.mdx so
the auth action clearly indicates account creation rather than sign-in: change
the "Sign in with their real email" cell in the final scenario row (the "User
has no Recoup account yet but wants persistent state" row) to "Sign up with
their real email" (or "Sign up / create an account with their real email") and
keep the Then column unchanged ("After auth, run Create a New Artist
workflow...") so readers understand this path requires signup rather than
signin.
Comment on lines
+63
to
+100
| # List organizations (labels/teams) the account belongs to | ||
| curl "https://recoup-api.vercel.app/api/organizations" \ | ||
| -H "x-api-key: $RECOUP_API_KEY" | ||
| ``` | ||
|
|
||
| ## How it works | ||
| **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. | ||
|
|
||
| Two unauthenticated endpoints power agent onboarding: | ||
| **If the human has organizations**, pass `organization_id` to scope to a specific label's roster. | ||
|
|
||
| - **[`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. | ||
| **If neither is specified**, you operate at the account level and can see everything available to the human. | ||
|
|
||
| Multiple API keys per account are supported — each signup or verification generates a new key without revoking existing ones. | ||
| --- | ||
|
|
||
| ## Standard signup (email verification) | ||
| ## 3. Know the filesystem | ||
|
|
||
| If you're building a human-facing integration and want the user to verify their real email, use any non-`agent+` address: | ||
| Each account has a persistent filesystem backed by a GitHub repo. This is where artist context lives — the files agents use to do informed work. | ||
|
|
||
| Step 1 — request a verification code: | ||
| ### Artist directory structure | ||
|
|
||
| ```bash | ||
| curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"email": "you@example.com"}' | ||
| ``` | ||
| 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`. |
There was a problem hiding this comment.
Fix the filesystem path contradiction.
This section says there is no orgs/ directory and that artists live at the top level, but the example tree still uses orgs/{org-name}/artists/{artist-slug}. That inconsistency will send agents to the wrong path.
Suggested fix
-orgs/{org-name}/artists/{artist-slug}/
+artists/{artist-slug}/🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@agents.mdx` around lines 63 - 100, The filesystem section contradicts itself
about where artist folders live; update either the prose or the example tree so
they match: if artists live at the top level, change the example path from
orgs/{org-name}/artists/{artist-slug}/ to artists/{artist-slug}/ (keeping
RECOUP.md, context/, songs/, releases/, and config/ entries and filenames like
RECOUP.md and config/content-creation/config.json), otherwise change the prose
to say artists live under orgs/{org-name}/artists/{artist-slug}/ so the text and
the example tree are consistent.
Comment on lines
2
to
22
| title: "Quickstart" | ||
| description: "Get a Recoup API key in one call and make your first request — no browser, no dashboard." | ||
| description: "API key in 2 calls. First request in minutes. No signup form, no dashboard." | ||
| --- | ||
|
|
||
| ## Quickest start | ||
|
|
||
| Sign up your agent and get an API key in a single API call — no dashboard, no browser, no human in the loop. This one-liner signs up a fresh `agent+` address and exports the returned key to `$RECOUP_API_KEY`: | ||
| ## 1. Get your API key | ||
|
|
||
| ```bash | ||
| export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \ | ||
| # 1. Trigger a verification code to your inbox | ||
| curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key) | ||
| ``` | ||
| -d '{"email": "you@example.com"}' | ||
|
|
||
| Verify it worked: | ||
|
|
||
| ```bash | ||
| curl -H "x-api-key: $RECOUP_API_KEY" https://recoup-api.vercel.app/api/accounts/id | ||
| # 2. Check your email, then exchange the code for a key | ||
| export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/verify" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"email": "you@example.com", "code": "123456"}' | jq -r .api_key) | ||
| ``` | ||
|
|
||
| <Tip> | ||
| The `agent+{timestamp}@recoupable.com` shape is the fastest path for agents — it guarantees a fresh `agent+` address and returns an API key instantly without email verification. | ||
| Prefer the dashboard? Create keys at [chat.recoupable.com/keys](https://chat.recoupable.com/keys). See the [Agents guide](/agents) for the full flow including how an agent passes the code on behalf of a human. | ||
| </Tip> |
There was a problem hiding this comment.
Align the description with the documented flow.
The frontmatter still says “No signup form, no dashboard,” but this page now explicitly offers a dashboard fallback. That mismatch will confuse readers scanning the page summary.
Suggested fix
-description: "API key in 2 calls. First request in minutes. No signup form, no dashboard."
+description: "API key in 2 calls. First request in minutes. Optional dashboard fallback."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@quickstart.mdx` around lines 2 - 22, Update the frontmatter description to
match the documented flow: change the description string that currently reads
"API key in 2 calls. First request in minutes. No signup form, no dashboard." to
reflect that a dashboard fallback exists (for example, mention the dashboard
option or remove the "no dashboard" phrase) so the page summary aligns with the
content under the "Get your API key" section and the Tip referencing
chat.recoupable.com/keys; edit the frontmatter block near the "title:
\"Quickstart\"" entry.
Adds an explicit "ask first" instruction with a verbatim question
template. The previous "Choose your path" section gave the scenarios
but assumed the agent could read the human's intent — which is
unreliable.
The new pattern:
1. ASK the human up front (verbatim question template provided)
2. Match their answer to the path table
3. Skip the question only when context makes it obvious
(explicit demo intent, explicit email already given, or
autonomous agent with no human in the loop)
Why this matters:
The previous text relied on the agent inferring whether the human
wants persistence. Real-world prompts like "build me a content
campaign" don't reliably indicate intent — half the users want
account-based persistence, half are just trying a demo. If the
agent silently picks throwaway and the user re-prompts later, their
roster is orphaned and they didn't know to expect that.
A 5-second clarifying question is cheaper than that surprise.
The verbatim template surfaces the trade-off (persist vs one-shot)
in language a human can actually answer, and gives the agent a
ready-made script so it doesn't have to invent the question itself.
The "skip the question" clause preserves the easy-demo path: a
human who says "just try the platform" or already provides their
email gets straight to work without an extra round-trip.
Editorial pass on the prose I added in the previous commit. Three
issues to address:
1. Lead instruction was self-referential ("Agents are unreliable at
guessing intent...") and used softer "Always ask... unless..."
framing. Switched to a direct imperative ("Ask the human which
path they want before authenticating.") with the consequence
stated in concrete terms ("creates records under a throwaway
account that can't be recovered if the API key is lost").
2. Question template had three weaknesses:
- "Quick question before we start" — fluff opener that agents
reproduce verbatim, padding every interaction with the same
wind-up phrase
- "share your email and I'll send a verification code" — the
agent doesn't send the code (the API does); small accuracy
bug that agents would propagate
- "spin up a temporary one for one-shot use" — colloquial jargon
that doesn't surface the actual consequence
Rewritten to be tighter, accurate, and to surface the trade-off
in the question itself: "...I'll create a temporary account —
but you won't be able to save artists, releases, or scheduled
tasks under it." The human now has enough to make an informed
choice in one round-trip instead of asking a follow-up.
3. "Use this as your default opener (paraphrase as appropriate to
context)" let the agent paraphrase away the trade-off. Changed
to "paraphrase if needed, but keep the trade-off explicit" which
gates the paraphrasing on preserving the key information.
Net change: 3 lines, same structure, tighter language, accurate
description of who does what.
The four onboarding pages (index, quickstart, agents, authentication)
were each trying to be self-contained, which produced contradictions:
- Three different "first call after auth" instructions:
index.mdx -> GET /accounts and /organizations
quickstart -> GET /research?q=Drake
agents.mdx -> GET /artists and /organizations
- Three different "agent loop" descriptions on three pages
- "Filesystem" introduced as a Core Concept on the homepage but
only explained on agents.mdx
- The signup curl duplicated 4x across pages, drifting subtly
- Throwaway vs real-email path mentioned on agents.mdx but
invisible on index/quickstart, leaving readers with mismatched
mental models
Fix: give each page one job and link elsewhere for everything else.
index.mdx — now a router, not a tutorial:
- Removed the "How it works" 5-step agent loop (third version of
the agent flow, conflicted with quickstart and agents)
- Removed the "Get an API key" section with inline curl (now lives
in quickstart, the natural home for that snippet)
- Removed Filesystem from Core Concepts (it's an agent-specific
implementation detail, not a top-level concept)
- New "Get started" routing block links to Quickstart, Agents, and
Authentication with one-sentence descriptions of each
quickstart.mdx — now explicitly the demo path:
- New <Note> at top: "Building an AI agent that acts on a user's
behalf? See /agents instead — it covers throwaway-vs-account,
the roster, and the persistent filesystem."
- Page intro reframes as "5-minute hello-world"
agents.mdx — now explicitly the production manual:
- New <Note> at top: "Just trying the API yourself? See /quickstart
for a 5-minute hello-world."
- Frames itself as the operating manual for production agents
authentication.mdx — now pure reference:
- Trimmed "Create a key" section: removed the inline signup curl
(links to quickstart#1-get-your-api-key instead) and condensed
the dashboard option to one line
- Other sections (use a key, org access, Bearer tokens, access
control rules, errors, security) stay as reference material
After this change, each page has exactly one job:
index - homepage router (no operational steps)
quickstart - 5-min demo flow, one canonical scenario
agents - production agent operating manual
authentication - pure auth reference
The signup curl now lives in exactly two places (quickstart and
agents.mdx), each appropriate to its page's role. Other pages link.
Made-with: Cursor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rewrites the four onboarding pages — `index.mdx`, `quickstart.mdx`, `authentication.mdx`, `agents.mdx` — so AI agents landing on the docs can self-serve API access in two curl calls instead of being routed to a browser-based dashboard signup.
Why this matters
When you tell an AI agent to "read the Recoup docs and use the API," the agent should be able to follow the docs to a working API key without driving a browser. Previously the docs primarily routed through `chat.recoupable.com/keys`, which works for humans but fails for headless agents. The two-step `POST /api/agents/signup` → `POST /api/agents/verify` flow has been live for a while; this PR makes it the documented primary path.
Changes per page
`index.mdx` (homepage)
`quickstart.mdx`
`authentication.mdx`
`agents.mdx`
What this PR does NOT change
Doesn't touch `docs.json` nav, doesn't add Skills, doesn't rewrite CLI/MCP. Those land separately in the stack.
Stack
PR 5 of 7. Replaces #145.
Made with Cursor
Summary by CodeRabbit