feat: docs design overhaul — achromatic design system + narrative alignment#128
Open
sidneyswift wants to merge 24 commits intomainfrom
Open
feat: docs design overhaul — achromatic design system + narrative alignment#128sidneyswift wants to merge 24 commits intomainfrom
sidneyswift wants to merge 24 commits intomainfrom
Conversation
- Theme: mint → sequoia with achromatic colors, Plus Jakarta Sans headings, Inter body - Background: "windows" decoration, dark mode #080808, always-dark code blocks - Navigation: reorganized into Overview/Research/Releases/Content/Social/Platform tabs - Homepage: aligned with "music intelligence" positioning, 3-mode access pattern, LLM endpoint table - Quickstart: leads with research endpoint, CLI inline, MCP connection step - Agent onboarding: simplified to agent-only flow, human verification moved to auth page - Authentication: use-case guidance at top, consolidated key creation methods - All guide pages: tighter copy, proof numbers, brand voice compliance - No API reference files touched (auto-generated from OpenAPI) Made-with: Cursor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughReworks onboarding, authentication, CLI, content-agent, MCP, quickstart, and site navigation docs: adds agent signup/verify flow (with immediate key for Changes
Sequence Diagram(s)sequenceDiagram
participant Client as Client
participant Signup as POST /api/agents/signup
participant EmailSvc as Email Service
participant API as API/Key Store
Client->>Signup: POST /api/agents/signup (email)
alt email starts with "agent+"
Signup->>API: Create blank account + API key
API-->>Client: Return `api_key` (immediate)
else regular email
Signup->>EmailSvc: Send verification code
EmailSvc-->>Client: Deliver code
Client->>Signup: POST /api/agents/verify (email + code)
Signup->>API: Verify code, create API key
API-->>Client: Return `api_key`
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 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 |
![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
🧹 Nitpick comments (1)
quickstart.mdx (1)
8-12: Extract this signup command into a shared snippet to prevent doc drift.This block is duplicated across multiple pages (
index.mdx,agents.mdx,authentication.mdx, and here). Centralize it once and reuse.As per coding guidelines: "Follow DRY principle - don't duplicate content across pages, use snippets instead".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@quickstart.mdx` around lines 8 - 12, Extract the duplicated bash signup block into a single shared MDX snippet component named SignupCommandSnippet that contains the exact curl + jq command, export that component once, and then replace the duplicated inline code blocks in each page (index.mdx, agents.mdx, authentication.mdx, quickstart.mdx) with an MDX import and usage of SignupCommandSnippet; ensure the snippet preserves the original command formatting and any required escaping so all pages render identically.
🤖 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`:
- Line 49: Update the wording that currently states the
`agent+{unique}@recoupable.com` pattern with `$(date +%s)` and `$RANDOM`
“guarantees” unique addresses to avoid absolute claims; change it to say the
combination makes collisions very unlikely (or similar probabilistic language)
and note that uniqueness is probabilistic rather than guaranteed. Ensure the
sentence referencing `agent+{unique}@recoupable.com`, `$(date +%s)`, and
`$RANDOM` is edited accordingly.
- Around line 6-11: The documentation currently states that any POST returns an
API key without authentication; update the "Get a key" section to explicitly
scope instant key issuance to agent+ email addresses by saying that only POSTs
using agent+ emails receive an immediate key, and clarify that non-agent+ emails
are still routed through /api/agents/verify for normal verification flow; ensure
you mention the /api/agents/verify endpoint and the agent+ email pattern in the
"Get a key" paragraph so the conditional behavior is unambiguous.
In `@docs.json`:
- Around line 6-8: The primary brand color in docs.json is incorrect: update the
colors.primary entry (currently "#0a0a0a") to the required brand hex "#345A5D"
to match the repo guideline; ensure the "primary" key in the same JSON object
remains a valid string value "#345A5D" so branding matches Recoup-Chat
tailwind.config.ts.
---
Nitpick comments:
In `@quickstart.mdx`:
- Around line 8-12: Extract the duplicated bash signup block into a single
shared MDX snippet component named SignupCommandSnippet that contains the exact
curl + jq command, export that component once, and then replace the duplicated
inline code blocks in each page (index.mdx, agents.mdx, authentication.mdx,
quickstart.mdx) with an MDX import and usage of SignupCommandSnippet; ensure the
snippet preserves the original command formatting and any required escaping so
all pages render identically.
🪄 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: 782362f7-fc00-4fd4-8ea4-636fe5849a05
📒 Files selected for processing (8)
agents.mdxauthentication.mdxcli.mdxcontent-agent.mdxdocs.jsonindex.mdxmcp.mdxquickstart.mdx
Comment on lines
+6
to
+8
| "primary": "#0a0a0a", | ||
| "light": "#ededed", | ||
| "dark": "#0a0a0a" |
There was a problem hiding this comment.
Primary brand color is out of policy.
Line 6 sets colors.primary to #0a0a0a, but the repo guideline requires #345A5D for branding consistency.
Suggested fix
"colors": {
- "primary": "#0a0a0a",
+ "primary": "#345A5D",
"light": "#ededed",
"dark": "#0a0a0a"
},As per coding guidelines: "Use primary color #345A5D from Recoup-Chat tailwind.config.ts for branding consistency".
📝 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
| "primary": "#0a0a0a", | |
| "light": "#ededed", | |
| "dark": "#0a0a0a" | |
| "colors": { | |
| "primary": "#345A5D", | |
| "light": "#ededed", | |
| "dark": "#0a0a0a" | |
| }, |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs.json` around lines 6 - 8, The primary brand color in docs.json is
incorrect: update the colors.primary entry (currently "#0a0a0a") to the required
brand hex "#345A5D" to match the repo guideline; ensure the "primary" key in the
same JSON object remains a valid string value "#345A5D" so branding matches
Recoup-Chat tailwind.config.ts.
Contributor
There was a problem hiding this comment.
#345A5D IS NOT THE PRIMARY BRAND COLOR
There was a problem hiding this comment.
@recoupableorg, apologies for the incorrect comment! I had an outdated learning stored that pointed to #345A5D, but this design overhaul intentionally moves to an achromatic system with #0a0a0a as the primary color. I'll update my knowledge base accordingly.
✏️ Learnings added
Learnt from: recoupableorg
Repo: recoupable/docs PR: 128
File: docs.json:6-8
Timestamp: 2026-04-14T03:51:07.712Z
Learning: Applies to docs.json in the recoupable/docs repository: The primary brand color is `#0a0a0a` (achromatic design system), NOT `#345A5D`. The color palette uses primary: "#0a0a0a", light: "#ededed", dark: "#0a0a0a". The theme is "sequoia". Do not flag `#0a0a0a` as an incorrect primary color.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
⛔ Learnings removed
Learnt from: CR
Repo: recoupable/docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-17T19:11:25.261Z
Learning: Applies to docs.json : Use primary color `#345A5D` from Recoup-Chat tailwind.config.ts for branding consistency
🧠 Learnings used
Learnt from: CR
Repo: recoupable/docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-17T19:11:25.261Z
Learning: Applies to docs.json : Use primary color `#345A5D` from Recoup-Chat tailwind.config.ts for branding consistency
Learnt from: CR
Repo: recoupable/docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-17T19:11:25.261Z
Learning: Applies to docs.json : Configure site settings in `docs.json` including name, colors (primary, light, dark), logo paths, favicon, navigation structure, navbar links, and footer social links
Learnt from: CR
Repo: recoupable/docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-02-17T19:11:25.261Z
Learning: Applies to docs.json : Reference correct branding values: support email agentrecoupable.com, app URL https://chat.recoupable.com, website https://recoupable.com, and social URLs (X, GitHub, LinkedIn)
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
6 issues found across 8 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="quickstart.mdx">
<violation number="1" location="quickstart.mdx:69">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**
These three curl examples use `?q=Drake` but the OpenAPI spec defines the parameter as `artist` for `/research/metrics`, `/research/audience`, and `/research/playlists`. Only the `/research` search endpoint accepts `q`. These examples will return errors or empty results.</violation>
</file>
<file name="agents.mdx">
<violation number="1" location="agents.mdx:49">
P3: `$RANDOM` is a 15-bit value (0–32767). Two calls within the same second have a non-zero collision probability (~1/32768). Replace "guarantees" with "makes collisions very unlikely" to avoid an inaccurate promise.</violation>
</file>
<file name="cli.mdx">
<violation number="1" location="cli.mdx:93">
P2: The `chats` section still documents `recoup chats create` but the link to `POST /api/chats` was dropped. Add it back so users can find the API reference for the create operation.</violation>
<violation number="2" location="cli.mdx:103">
P2: The `sandboxes` section still documents `recoup sandboxes create` but the link to `POST /api/sandboxes` was dropped. Add it back so users can find the API reference for the create operation.</violation>
</file>
<file name="index.mdx">
<violation number="1" location="index.mdx:142">
P1: The LLM endpoint table is labeled as "the complete endpoint map" but is missing at least 10 endpoint groups present in `docs.json` navigation: `/segment/*`, `/fans/*`, `/posts/*`, `/post/*`, `/comments/*`, `/image/*`, `/transcribe/*`, `/social/*`, `/apify/*`, and `/admins/*`. AI agents relying on this table will be unaware of these capabilities.</violation>
</file>
<file name="docs.json">
<violation number="1" location="docs.json:8">
P1: The dark-mode accent color (`#0a0a0a`) is nearly identical to the dark background (`#080808`), which will make links, buttons, and other accent-colored elements virtually invisible in dark mode. Similarly, the light-mode accent (`#ededed`) will have very poor contrast against white backgrounds. Consider using a color with sufficient contrast for each mode (e.g., a light accent for `dark` and a darker accent for `light`).</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
Old categories organized by data type (Releases, Social, Platform). New categories organized by what agents actually do: - Research: ALL intelligence from ANY source (chat, research, Spotify, Instagram, X, web intel, social scraping) - Artists: roster management (artists, songs, catalogs, fans, segments, posts, comments) - Content: media production (pipeline, 7 primitives, content agent) - Automation: scheduled agent work (tasks, sandboxes, connectors, pulses, notifications) - Accounts: business infrastructure (agent onboarding, accounts, orgs, workspaces, subscriptions, admins) Key moves: - Tasks out of "Releases" → Automation (they automate anything, not just releases) - Sandboxes out of "Content" → Automation (agent execution infrastructure) - Connectors out of "Social" → Automation (OAuth for any tool, not just social) - Spotify/Instagram/X into Research (they're data sources) - Fans/Segments/Posts/Comments into Artists (audience is part of roster context) - Research split into Artist Research + Web Intelligence subgroups - Content split into Pipeline + Primitives subgroups - Homepage updated with real value prop from strategy docs - Recoupable wordmark logos (clean vector SVGs) Made-with: Cursor
There was a problem hiding this comment.
1 issue found across 4 files (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="docs.json">
<violation number="1" location="docs.json:157">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**
PR description claims navigation tabs are "Overview, Research, **Releases**, Content, **Social**, **Platform**" but the actual config defines tabs as "Overview, Research, **Artists**, Content, **Automation**, **Accounts**." Three of six tab names in the description are the old names being replaced, not the new ones — a textbook case of a description that doesn't match the implemented change.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
… on "tools" - New Catalog tab: Songs + Catalogs separated from Artists (catalogs are label-level, not artist-level) - Artists tab: now just roster management + fans/segments - Connectors moved from Automation → Accounts (they're per-account OAuth connections) - "Primitives" → "Content Tools", "endpoints" → "tools" everywhere (matches marketing "40+ agent tools") - Homepage cards updated to reflect 7-tab structure Made-with: Cursor
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
docs.json (1)
6-8:⚠️ Potential issue | 🟠 MajorPrimary brand color is still out of policy.
colors.primaryis#0a0a0a; it must be#345A5Dfor brand consistency.Suggested fix
"colors": { - "primary": "#0a0a0a", + "primary": "#345A5D", "light": "#ededed", "dark": "#0a0a0a" },As per coding guidelines: "Use primary color
#345A5Dfrom Recoup-Chat tailwind.config.ts for branding consistency".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs.json` around lines 6 - 8, The primary brand color in the JSON theme is incorrect: change the "primary" property value from "#0a0a0a" to the mandated brand color "#345A5D" (update the "primary" key in the colors object), leaving other keys (e.g., "light", "dark") untouched to maintain existing variants.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@quickstart.mdx`:
- Around line 108-113: The "Content tools" Card currently links to the pipeline
endpoint href="/api-reference/content/create" which mismatches the card
title/description; update the Card's href to the appropriate tools landing or
tools-specific endpoint (e.g., the content tools index) so the link matches the
"Content tools" title—look for the Card component instance with title="Content
tools" and change its href to the tools endpoint.
- Around line 14-17: The current text claims "$RECOUP_API_KEY is now ready"
without clarifying scope; update the quickstart.mdx copy to state that instant
key issuance applies only when signing up with the example email pattern
(agent+...@recoupable.com) used in this guide, e.g., change the sentence around
"$RECOUP_API_KEY" to explicitly mention the agent+...@recoupable.com pattern
grants immediate keys, and keep the Tip about creating keys at
chat.recoupable.com/keys and the Agents guide to note that the dashboard/signup
flow with other emails requires email verification.
---
Duplicate comments:
In `@docs.json`:
- Around line 6-8: The primary brand color in the JSON theme is incorrect:
change the "primary" property value from "#0a0a0a" to the mandated brand color
"#345A5D" (update the "primary" key in the colors object), leaving other keys
(e.g., "light", "dark") untouched to maintain existing variants.
🪄 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: 0cc92532-53eb-494c-bedf-b3bf393c715e
📒 Files selected for processing (4)
content-agent.mdxdocs.jsonindex.mdxquickstart.mdx
✅ Files skipped from review due to trivial changes (1)
- content-agent.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- index.mdx
Comment on lines
108
to
113
| title="Content tools" | ||
| icon="sparkles" | ||
| href="/api-reference/content/create" | ||
| > | ||
| Access fan data across all connected social platforms. | ||
| 7 tools for images, videos, captions, transcription, editing, upscaling, and analysis. | ||
| </Card> |
There was a problem hiding this comment.
“Content tools” card points to a pipeline endpoint.
The card title/description says tools, but Line 110 links to /api-reference/content/create (pipeline). Point it to a tools endpoint (or a tools landing page) to match user intent.
As per coding guidelines: "Use clear, self-documenting titles and descriptions in documentation".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@quickstart.mdx` around lines 108 - 113, The "Content tools" Card currently
links to the pipeline endpoint href="/api-reference/content/create" which
mismatches the card title/description; update the Card's href to the appropriate
tools landing or tools-specific endpoint (e.g., the content tools index) so the
link matches the "Content tools" title—look for the Card component instance with
title="Content tools" and change its href to the tools endpoint.
There was a problem hiding this comment.
2 issues found across 4 files (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="content-agent.mdx">
<violation number="1" location="content-agent.mdx:40">
P2: The section heading and description were renamed from "primitives" to "tools", but the table's first column header still reads `Primitive`. Update it to `Tool` for consistency.</violation>
</file>
<file name="quickstart.mdx">
<violation number="1" location="quickstart.mdx:108">
P2: The card title says "Content tools" but `href` still points to `/api-reference/content/create`, which is the pipeline endpoint. Consider linking to a tools-specific page (e.g., `/api-reference/content/generate-image`) or a tools landing page to match user intent — `content/create` lives under the "Pipeline" group in `docs.json`, not "Content Tools".</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
… contexts - Homepage intro + meta descriptions: "40+ tools" (marketing copy) - MCP page: "tools" (MCP protocol term) - All technical docs: "endpoints" (industry standard for API docs) Made-with: Cursor
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs.json (1)
39-346:⚠️ Potential issue | 🟠 MajorTop-level navigation diverges from the PR’s stated IA contract.
The config defines 7 tabs (
Overview,Research,Artists,Catalog,Content,Automation,Accounts), but the PR objective states 6 tabs (Overview,Research,Releases,Content,Social,Platform). Please align the config or update the objective/spec before merge.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs.json` around lines 39 - 346, The top-level "tabs" definition in docs.json currently lists seven tabs ("Overview", "Research", "Artists", "Catalog", "Content", "Automation", "Accounts") which does not match the PR IA contract that requires six tabs ("Overview", "Research", "Releases", "Content", "Social", "Platform"); update the "tabs" array so its entries match the agreed IA (rename/remove/add tab objects and their "groups"/"pages" accordingly) or, if the IA changed, update the PR/spec to reflect the current "tabs" shape; look for the "tabs" array and tab objects (e.g., the "tab" keys "Overview","Research","Artists", etc.) and reconcile their names and grouped pages to exactly match the IA contract.
♻️ Duplicate comments (1)
docs.json (1)
6-8:⚠️ Potential issue | 🟠 MajorSet
colors.primaryto the required brand value (#345A5D).
colors.primaryis currently#0a0a0a, which is out of repo policy fordocs.json.Proposed fix
"colors": { - "primary": "#0a0a0a", + "primary": "#345A5D", "light": "#ededed", "dark": "#0a0a0a" },As per coding guidelines: "Use primary color
#345A5Dfrom Recoup-Chat tailwind.config.ts for branding consistency".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs.json` around lines 6 - 8, Update the docs.json color palette so colors.primary is the brand value `#345A5D` instead of `#0a0a0a`; locate the "primary" key in the colors object in docs.json (currently "primary": "#0a0a0a") and replace its value with "#345A5D" to match the Recoup-Chat tailwind.config.ts branding guidelines, keeping other keys (e.g., "light" and "dark") unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs.json`:
- Around line 407-409: Update the "og:description" metadata entry to match the
PR narrative by replacing the current "40+ tools" claim with the standardized
phrase "30 endpoints, 7 primitives, 14 platforms" (or an equivalent wording that
exactly mirrors the PR text) so external metadata and the PR content are
consistent; modify the "og:description" value in docs.json accordingly.
---
Outside diff comments:
In `@docs.json`:
- Around line 39-346: The top-level "tabs" definition in docs.json currently
lists seven tabs ("Overview", "Research", "Artists", "Catalog", "Content",
"Automation", "Accounts") which does not match the PR IA contract that requires
six tabs ("Overview", "Research", "Releases", "Content", "Social", "Platform");
update the "tabs" array so its entries match the agreed IA (rename/remove/add
tab objects and their "groups"/"pages" accordingly) or, if the IA changed,
update the PR/spec to reflect the current "tabs" shape; look for the "tabs"
array and tab objects (e.g., the "tab" keys "Overview","Research","Artists",
etc.) and reconcile their names and grouped pages to exactly match the IA
contract.
---
Duplicate comments:
In `@docs.json`:
- Around line 6-8: Update the docs.json color palette so colors.primary is the
brand value `#345A5D` instead of `#0a0a0a`; locate the "primary" key in the colors
object in docs.json (currently "primary": "#0a0a0a") and replace its value with
"#345A5D" to match the Recoup-Chat tailwind.config.ts branding guidelines,
keeping other keys (e.g., "light" and "dark") unchanged.
🪄 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: 12f5e058-977b-4bec-9d63-7a96ed5d433f
📒 Files selected for processing (5)
agents.mdxcontent-agent.mdxdocs.jsonindex.mdxquickstart.mdx
✅ Files skipped from review due to trivial changes (2)
- content-agent.mdx
- index.mdx
🚧 Files skipped from review as they are similar to previous changes (2)
- agents.mdx
- quickstart.mdx
Comment on lines
407
to
409
| "og:site_name": "Recoup API", | ||
| "og:description": "Music intelligence API — 40+ tools for artist research, content creation, and music business automation. Built for developers and AI agents.", | ||
| "twitter:card": "summary_large_image" |
There was a problem hiding this comment.
og:description count claim is inconsistent with this PR’s proof numbers.
Metadata says “40+ tools,” while the PR narrative standardizes on “30 endpoints, 7 primitives, 14 platforms.” Keep this consistent to avoid conflicting external messaging.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs.json` around lines 407 - 409, Update the "og:description" metadata entry
to match the PR narrative by replacing the current "40+ tools" claim with the
standardized phrase "30 endpoints, 7 primitives, 14 platforms" (or an equivalent
wording that exactly mirrors the PR text) so external metadata and the PR
content are consistent; modify the "og:description" value in docs.json
accordingly.
There was a problem hiding this comment.
6 issues found across 5 files (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="docs.json">
<violation number="1" location="docs.json:222">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**
This rename goes in the **opposite direction** of the PR's stated terminology change. The PR description says "endpoints" → "tools", but this diff changes `Content Tools` → `Content Endpoints`, reintroducing the term the PR claims to standardize away from.</violation>
</file>
<file name="index.mdx">
<violation number="1" location="index.mdx:34">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**
This change renames "tools" → "endpoints", which is the **opposite** of what the PR description claims (`"endpoints" → "tools"`). It also creates an inconsistency within this file — the page title/description still says "40+ tools" while this card now says "40+ endpoints".</violation>
<violation number="2" location="index.mdx:85">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**
Same issue: changes "content tools" → "endpoints" and "tool" → "endpoint", opposite to the PR's stated `"endpoints" → "tools"` renaming. The Research card just above still says "30+ research tools", making the terminology inconsistent across sibling cards.</violation>
</file>
<file name="content-agent.mdx">
<violation number="1" location="content-agent.mdx:40">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**
This rename goes in the **opposite direction** of the PR's stated naming convention. The PR description says `"endpoints" → "tools"`, but this diff changes `tools` → `endpoints`. Either the PR description or this change is wrong — as written, this file will be inconsistent with the rest of the docs overhaul.</violation>
</file>
<file name="agents.mdx">
<violation number="1" location="agents.mdx:63">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**
This change reverts "tools" back to "endpoints", which directly contradicts the PR's stated terminology update ("endpoints" → "tools"). The rest of the PR is supposed to standardize on "tools" naming, but this line goes in the opposite direction.</violation>
</file>
<file name="quickstart.mdx">
<violation number="1" location="quickstart.mdx:24">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**
PR description claims the naming change is `"endpoints" → "tools"`, but every change in this file does the opposite: `"tools" → "endpoints"`. Either the code is going the wrong direction or the PR description is fabricated. Verify which terminology is intended and make the code and description consistent.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
| ### Architecture | ||
| --- | ||
|
|
||
| ## Content endpoints |
There was a problem hiding this comment.
P1: Custom agent: Flag AI Slop and Fabricated Changes
This rename goes in the opposite direction of the PR's stated naming convention. The PR description says "endpoints" → "tools", but this diff changes tools → endpoints. Either the PR description or this change is wrong — as written, this file will be inconsistent with the rest of the docs overhaul.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At content-agent.mdx, line 40:
<comment>This rename goes in the **opposite direction** of the PR's stated naming convention. The PR description says `"endpoints" → "tools"`, but this diff changes `tools` → `endpoints`. Either the PR description or this change is wrong — as written, this file will be inconsistent with the rest of the docs overhaul.</comment>
<file context>
@@ -37,9 +37,9 @@ The Recoup Content Agent is a Slack bot that generates social-ready artist video
---
-## Content tools
+## Content endpoints
-The content API provides seven independent tools. Each does one thing well. You orchestrate them.
</file context>
Suggested change
| ## Content endpoints | |
| ## Content tools |
| @@ -1,175 +1,128 @@ | |||
| --- | |||
There was a problem hiding this comment.
P1: Custom agent: Flag AI Slop and Fabricated Changes
PR description claims the naming change is "endpoints" → "tools", but every change in this file does the opposite: "tools" → "endpoints". Either the code is going the wrong direction or the PR description is fabricated. Verify which terminology is intended and make the code and description consistent.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At quickstart.mdx, line 24:
<comment>PR description claims the naming change is `"endpoints" → "tools"`, but every change in this file does the opposite: `"tools" → "endpoints"`. Either the code is going the wrong direction or the PR description is fabricated. Verify which terminology is intended and make the code and description consistent.</comment>
<file context>
@@ -21,7 +21,7 @@ Prefer the dashboard? Create keys at [chat.recoupable.com/keys](https://chat.rec
## 2. Search for an artist
-The research API has 30+ tools. Start with search — it works for any artist on earth:
+The research API has 30+ endpoints. Start with search — it works for any artist on earth:
<CodeGroup>
</file context>
… to Recoupable
Homepage now has the narrative structure of world-class docs:
- Problem statement ("Running a record label takes a team")
- What is Recoupable? (infrastructure for agents to run labels)
- Core concepts table (Artist, Catalog, Chat, Task, Sandbox, Pulse, Connector)
- How it works flow (Connect → Research → Build context → Create → Automate)
- Then quickstart, interfaces, API reference, guides, agent endpoint map
Inspired by Claude Managed Agents (concepts table, how-it-works steps),
Paperclip (problem-first framing), and OpenClaw (clear what-is explanation).
Site name: "Recoup" → "Recoupable" everywhere.
Made-with: Cursor
Agent Onboarding (agents.mdx) is now a real operating manual for AI agents: 1. Authenticate — key reuse, email verification flow with exact user prompt 2. Understand the roster — list artists, orgs, scoping behavior 3. Know the sandbox filesystem — full directory structure, RECOUP.md, content readiness 4. Decide what to do — decision tree (have roster? → research or create? → save? → automate?) Homepage changes: - Agent callout links to Agent guide (not Quickstart) — agents need the operating manual - Tightened intro to one paragraph (problem + solution, no repetition) - Info callout instead of Note/Tip (neutral styling) - AccordionGroup for core concepts Made-with: Cursor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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`:
- Line 99: The docs incorrectly list the HTTP method for /api/content/validate
as POST; update the text to use GET and indicate artist_account_id is passed as
a query parameter (matching the OpenAPI operation "get" in
api-reference/openapi/content.json); replace any instances of "POST
/api/content/validate" with "GET /api/content/validate" and mention
artist_account_id as a query param for readiness checks.
- Line 130: Change the documentation reference for the readiness check to match
the OpenAPI spec: update the text that says "POST /api/content/validate" to "GET
/api/content/validate" (the endpoint path /api/content/validate) in the
agents.mdx content block where the "Content — check readiness..." sentence
appears; if the intended behavior was actually a POST, instead update the
OpenAPI spec to define POST /api/content/validate so the docs and spec are
consistent.
🪄 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: 01888090-196f-4315-bd84-e9673a99fe85
📒 Files selected for processing (3)
agents.mdxdocs.jsonindex.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- index.mdx
| - `context/audience.md` (audience insights) | ||
| - `context/era.json` (current era metadata) | ||
|
|
||
| Use `POST /api/content/validate` with `artist_account_id` to check readiness programmatically. |
There was a problem hiding this comment.
**Incorrect HTTP method — should be GET, not POST.**The web search didn't directly clarify the specific Recoupable API. However, based on the relevant code snippet provided from api-reference/openapi/content.json, the /api/content/validate endpoint uses a "get" operation, not POST.
The documentation at line 99 states POST /api/content/validate but the OpenAPI spec clearly shows it's a GET endpoint with artist_account_id as a query parameter.
✏️ Suggested fix
-Use `POST /api/content/validate` with `artist_account_id` to check readiness programmatically.
+Use `GET /api/content/validate` with `artist_account_id` to check readiness programmatically.📝 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
| Use `POST /api/content/validate` with `artist_account_id` to check readiness programmatically. | |
| Use `GET /api/content/validate` with `artist_account_id` to check readiness programmatically. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@agents.mdx` at line 99, The docs incorrectly list the HTTP method for
/api/content/validate as POST; update the text to use GET and indicate
artist_account_id is passed as a query parameter (matching the OpenAPI operation
"get" in api-reference/openapi/content.json); replace any instances of "POST
/api/content/validate" with "GET /api/content/validate" and mention
artist_account_id as a query param for readiness checks.
| <Step title="Are you researching or creating?"> | ||
| **Research** — use the 30+ research endpoints. Pass `artist_account_id` to scope to a rostered artist, or search by name for any artist globally. | ||
|
|
||
| **Content** — check readiness with `POST /api/content/validate`, then generate with the content endpoints. Artist context from the sandbox filesystem makes output more on-brand. |
There was a problem hiding this comment.
Same GET vs POST mismatch for /api/content/validate.
This line also references POST /api/content/validate, but the OpenAPI spec defines it as a GET endpoint.
✏️ Suggested fix
- **Content** — check readiness with `POST /api/content/validate`, then generate with the content endpoints. Artist context from the sandbox filesystem makes output more on-brand.
+ **Content** — check readiness with `GET /api/content/validate`, then generate with the content endpoints. Artist context from the sandbox filesystem makes output more on-brand.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@agents.mdx` at line 130, Change the documentation reference for the readiness
check to match the OpenAPI spec: update the text that says "POST
/api/content/validate" to "GET /api/content/validate" (the endpoint path
/api/content/validate) in the agents.mdx content block where the "Content —
check readiness..." sentence appears; if the intended behavior was actually a
POST, instead update the OpenAPI spec to define POST /api/content/validate so
the docs and spec are consistent.
agent+ emails are NOT linked to the base email address. agent+sidney@recoupable.com creates a completely separate account from sidney@recoupable.com. Email lookup uses exact match with no plus-address normalization (verified from selectAccountByEmail code). Made-with: Cursor
There was a problem hiding this comment.
3 issues found across 2 files (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:75">
P2: `context/era.json` is listed as a recommended file but is missing from the directory structure tree above. Add it to the tree so agents parsing the filesystem layout see the complete picture.</violation>
<violation number="2" location="agents.mdx:99">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**
Wrong HTTP method: the validate endpoint is `GET /api/content/validate`, not `POST`. This appears twice in the file (here and in step 2 of "Decide what to do"). An agent following this doc will get a 405.</violation>
</file>
<file name="index.mdx">
<violation number="1" location="index.mdx:23">
P2: The parameter names `organization_id` and `artist_account_id` referenced here don't appear anywhere in the OpenAPI specs (`api-reference/openapi/*.json`). If these are real API parameters, they should be added to the spec first; if they're planned but not yet implemented, documenting them now will mislead agents into sending unrecognized parameters.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
| | Concept | What it is | | ||
| |---------|------------| | ||
| | **Account** | A user or agent that authenticates with an API key. Your account owns artists, chats, tasks, and connectors. When no artist is specified, you see everything available to you. | | ||
| | **Organization** | A label or team that groups multiple accounts. Pass `organization_id` to scope to a specific roster. Accounts can belong to multiple organizations, each with different artists. | |
There was a problem hiding this comment.
P2: The parameter names organization_id and artist_account_id referenced here don't appear anywhere in the OpenAPI specs (api-reference/openapi/*.json). If these are real API parameters, they should be added to the spec first; if they're planned but not yet implemented, documenting them now will mislead agents into sending unrecognized parameters.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At index.mdx, line 23:
<comment>The parameter names `organization_id` and `artist_account_id` referenced here don't appear anywhere in the OpenAPI specs (`api-reference/openapi/*.json`). If these are real API parameters, they should be added to the spec first; if they're planned but not yet implemented, documenting them now will mislead agents into sending unrecognized parameters.</comment>
<file context>
@@ -1,29 +1,43 @@
+ | Concept | What it is |
+ |---------|------------|
+ | **Account** | A user or agent that authenticates with an API key. Your account owns artists, chats, tasks, and connectors. When no artist is specified, you see everything available to you. |
+ | **Organization** | A label or team that groups multiple accounts. Pass `organization_id` to scope to a specific roster. Accounts can belong to multiple organizations, each with different artists. |
+ | **Artist** | A managed artist with profile, social handles, and linked catalog. Pass `artist_account_id` to scope to a specific artist. When omitted, agents see all artists available to the account. |
+ </Accordion>
</file context>
- POST /api/content/create marked as legacy with Warning callout - Individual content endpoints (generate-image, generate-video, etc.) moved to top of Content tab - Templates split into own group - Pipeline moved to "Pipeline (Legacy)" group at bottom - Removed content readiness section from Agent Onboarding (face guide not universally required) - Added proactive roster check instruction after auth in Agent Onboarding Made-with: Cursor
There was a problem hiding this comment.
1 issue found across 3 files (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="api-reference/content/create.mdx">
<violation number="1" location="api-reference/content/create.mdx:6">
P2: API reference MDX files must be frontmatter-only per AGENTS.md and CLAUDE.md. Adding a `<Warning>` block here violates that convention — Mintlify should generate the page content entirely from the OpenAPI spec. If this endpoint is being deprecated, annotate it in the OpenAPI spec itself (e.g., via the `deprecated: true` field) so the generated docs reflect the status automatically.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
- Homepage: refined problem statement, dropped "the", removed condescending copy - Agent Onboarding: "user"→"human", Steps for auth flow, manage as work type, smarter task guidelines, filesystem not "sandbox filesystem", fixed content readiness reference, agent+ email warning with generic email - Navigation: Automation→Tasks (time-based only), Sandboxes→Accounts (infrastructure) - Content: pipeline endpoint marked legacy, individual endpoints promoted - OpenAPI create.mdx: deprecation warning added Made-with: Cursor
There was a problem hiding this comment.
1 issue found across 4 files (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="api-reference/content/create.mdx">
<violation number="1" location="api-reference/content/create.mdx:7">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**
Deprecation warning stripped of concrete migration guidance. The original named the replacement endpoints (`generate-image`, `generate-video`, `generate-caption`) and explained why to switch. The new text just says "Use the individual content endpoints directly" with no specifics — a developer hitting this deprecated endpoint gets no actionable next step.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
| --- | ||
|
|
||
| <Warning> | ||
| This endpoint is being phased out. Use the individual content endpoints directly. |
There was a problem hiding this comment.
P2: Custom agent: Flag AI Slop and Fabricated Changes
Deprecation warning stripped of concrete migration guidance. The original named the replacement endpoints (generate-image, generate-video, generate-caption) and explained why to switch. The new text just says "Use the individual content endpoints directly" with no specifics — a developer hitting this deprecated endpoint gets no actionable next step.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/content/create.mdx, line 7:
<comment>Deprecation warning stripped of concrete migration guidance. The original named the replacement endpoints (`generate-image`, `generate-video`, `generate-caption`) and explained why to switch. The new text just says "Use the individual content endpoints directly" with no specifics — a developer hitting this deprecated endpoint gets no actionable next step.</comment>
<file context>
@@ -4,5 +4,5 @@ openapi: "/api-reference/openapi/content.json POST /api/content/create"
<Warning>
-This pipeline endpoint is being phased out. Use the individual content endpoints (`generate-image`, `generate-video`, `generate-caption`, etc.) directly — they accept template parameters and don't require pre-configured artist files.
+This endpoint is being phased out. Use the individual content endpoints directly.
</Warning>
</file context>
Suggested change
| This endpoint is being phased out. Use the individual content endpoints directly. | |
| This endpoint is being phased out. Use the individual content endpoints (`generate-image`, `generate-video`, `generate-caption`, etc.) directly — they accept template parameters and don't require pre-configured artist files. |
- Core concepts: reduced to 4 essentials (Account, Organization, Artist, Filesystem) - Dropped Catalog, Task, Chat, Connector, Pulse, Sandbox from core concepts - Back to clean table format (cards were too cramped) - Intro copy: "That's what agents are for." bridge, no jargon - Agent onboarding: "human" not "user", manage as work type, task guidelines - Tasks tab renamed from Automation, Sandboxes moved to Accounts - Content pipeline marked legacy Made-with: Cursor
…esearch 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="docs.json">
<violation number="1" location="docs.json:62">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**
PR description claims navigation has "6 clear tabs (Overview, Research, Releases, Content, Social, Platform)" but the actual config implements 8 tabs: Overview, **Chat**, Research, Artists, Catalog, Content, Tasks, Accounts. Three claimed names (Releases, Social, Platform) are fabricated and don't exist in the codebase, while the new `Chat` tab from this diff isn't mentioned at all. Update the PR description to match the real navigation structure.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
| @@ -1,69 +1,68 @@ | |||
| { | |||
There was a problem hiding this comment.
P1: Custom agent: Flag AI Slop and Fabricated Changes
PR description claims navigation has "6 clear tabs (Overview, Research, Releases, Content, Social, Platform)" but the actual config implements 8 tabs: Overview, Chat, Research, Artists, Catalog, Content, Tasks, Accounts. Three claimed names (Releases, Social, Platform) are fabricated and don't exist in the codebase, while the new Chat tab from this diff isn't mentioned at all. Update the PR description to match the real navigation structure.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs.json, line 62:
<comment>PR description claims navigation has "6 clear tabs (Overview, Research, Releases, Content, Social, Platform)" but the actual config implements 8 tabs: Overview, **Chat**, Research, Artists, Catalog, Content, Tasks, Accounts. Three claimed names (Releases, Social, Platform) are fabricated and don't exist in the codebase, while the new `Chat` tab from this diff isn't mentioned at all. Update the PR description to match the real navigation structure.</comment>
<file context>
@@ -59,7 +59,7 @@
},
{
- "tab": "Research",
+ "tab": "Chat",
"groups": [
{
</file context>
Made-with: Cursor
|
You're iterating quickly on this pull request. To help protect your rate limits, cubic has paused automatic reviews on new pushes for now—when you're ready for another review, comment |
Made-with: Cursor
…ndpoints Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
…ttern Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
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
Complete docs design overhaul aligned with DESIGN.md and marketing site visual language.
mint→sequoiawith achromatic colors (#0a0a0a/#ededed), Plus Jakarta Sans headings, Inter body text8 files changed, 524 insertions, 918 deletions. Leaner, sharper, better for both humans and AI agents.
Test plan
Made with Cursor
Summary by cubic
Complete docs design and IA overhaul with the achromatic
sequoiatheme and an agent‑first narrative. Adds a Chat tab, promotes individual content endpoints (pipeline deprecated in OpenAPI), fixes research queries to?artist=, completes the endpoint map, improves dark‑mode contrast, and updates homepage links.New Features
era.json), and a decision tree.agent+...@recoupable.comone‑liner to export$RECOUP_API_KEY(works only foragent+emails; they create separate accounts; no plus‑normalization).x-api-keyorAuthorization: Bearer <jwt>); sending both returns401.Refactors
mint→sequoia; achromatic colors; Plus Jakarta Sans/Inter; always‑dark code blocks; Lucide icons; “Recoup” → “Recoupable” with new light/dark SVGs.generate-image.POST /api/content/createmarkeddeprecatedwith explicit alternatives (generate-image,generate-video,generate-caption, etc.).?artist=.POST /api/sandboxesandPOST /api/chats.Written for commit f0abb37. Summary will update on new commits.
Summary by CodeRabbit
Documentation
Style