docs: combined overhaul — brand, MCP, content cleanup, onboarding, skills, nav (PRs #168, #170-174)#189
Open
sidneyswift wants to merge 49 commits intomainfrom
Open
docs: combined overhaul — brand, MCP, content cleanup, onboarding, skills, nav (PRs #168, #170-174)#189sidneyswift wants to merge 49 commits intomainfrom
sidneyswift wants to merge 49 commits intomainfrom
Conversation
Pure visual update — no content or navigation changes. - theme: mint → sequoia - colors: green palette → achromatic (primary #0a0a0a, light #ededed) - background: light #f3f3f3 / dark #171717 (matches Mintlify's gray-50 / gray-900 chrome so the page bg blends with the tab bar) - fonts: Geist (body), Geist Pixel Square (headings); also adds GeistMono, Instrument Serif, Plus Jakarta Sans for use in MDX - appearance: default system (respects OS dark/light pref) - styling: eyebrows as breadcrumbs, codeblocks dark by default - icons: lucide library - logo: replace dark.png + light.svg with wordmark-lightmode.svg / wordmark-darkmode.svg (full wordmark) plus icon-only variants Adds the woff2/ttf font files in fonts/ and the new SVG logos in logo/. Removes the old PNG/SVG logos. navigation, navbar, footer, and metatags are byte-identical to main — this PR intentionally does not change content surface or info architecture. Those land in subsequent stack PRs. Made-with: Cursor
Brings mcp.mdx in line with what's actually registered in the production MCP server (api/lib/mcp/tools/). The previous page documented 2 tools; the actual server registers 43 across 11 domains. Replaces the previous 2-tool description with a real tool catalog grouped by activity: - Artists (4 tools) - Spotify (4) - Catalog (3) - YouTube (5) - Chats (2) - Tasks (5) - Content — image, video, - Pulses (2) audio (8) - Sandbox (1) - Research (4) - Utilities (3) Tool names and descriptions extracted directly from the register*Tool.ts source files for accuracy. Also fixes: - Removes the fictional `run_sandbox_command` tool (never existed in the registered tool set). - Drops the "Beta" framing — 43 working tools is just under- marketed production, not beta. - Trims the overpromise in the opening line to match the actual capability surface. Made-with: Cursor
Three classes of fixes to the API reference and content-agent docs. All fixes were verified against the OpenAPI spec — no fictional endpoints or paths remain. OpenAPI hygiene (api-reference/openapi/*.json): - research.json: replace internal "memories" wording with "messages" in chat endpoint descriptions and schema fields. Database tables remain named `memories` internally; this only affects what API consumers see in docs. - releases.json: align PATCH /api/tasks summary "Update scheduled task" → "Update Task" so it matches the visible MDX page title in the sidebar. - content.json: surface legacy framing in operation descriptions for POST /api/content/create, GET /api/image/generate, and POST /api/transcribe — explains what each does, why it predates the current /api/content/* primitives, and links to the recommended modern endpoint. Avoids breaking the AGENTS.md "api-reference MDX pages must be frontmatter-only" rule (which a previous attempt at inline <Note> blocks would have violated). API reference page titles: - api-reference/research/search.mdx: "Search" → "Artist Search" - api-reference/spotify/search.mdx: "Search" → "Spotify Search" - api-reference/image/generation.mdx: "Generate Image" → "Generate Image (Legacy)" - api-reference/transcribe/audio.mdx: "Transcribe Audio" → "Transcribe Audio (Legacy)" These four pages previously had titles that were either duplicates of other pages (Search, Generate Image, Transcribe Audio) or didn't indicate the legacy status. Renames disambiguate them in the sidebar and in autocomplete. Content Agent page (content-agent.mdx): - Refactored the architecture and data-flow sections to match the current Slack-bot implementation. - Endpoint table updated to use the canonical short paths from the OpenAPI spec (POST /api/content/image, /video, /caption, /transcribe; PATCH /api/content; POST /api/content/analyze) rather than the descriptive variants that don't actually exist in the spec. - Marked POST /api/content/create as legacy inline. - Standardized the "Endpoints it uses" heading to match the convention used on every skills/* page. 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
Adds a new "Skills" surface to the docs — a set of markdown playbooks that teach AI agents how to do music industry work. Skills complement the API: the API tells an agent HOW to take action, Skills tell it WHEN and WHY. New pages: - skills.mdx — overview of what skills are, the structure of a SKILL.md file, and how to install via Claude Code's plugin marketplace or `git clone`. - skills/getting-started.mdx — install CLI, get API key, connect via MCP/REST. - skills/setup-sandbox.mdx — provision a sandbox for an account. - skills/artist-workspace.mdx — manage artist directories (RECOUP.md, context/, songs/, releases/). - skills/streaming-growth.mdx — grow a new artist past streaming milestones. - skills/chart-metric.mdx — query and analyze Chartmetric data. - skills/music-industry-research.mdx — analytics, people search, competitive analysis. - skills/song-writing.mdx — songwriting workflow. - skills/trend-to-song.mdx — reverse-engineer a song from a cultural moment. - skills/content-creation.mdx — compose social videos via the content endpoints. - skills/release-management.mdx — plan and track release campaigns. Each page summarizes when the agent uses the skill, what it produces, and which API endpoints it depends on. The canonical skill instructions live in github.com/recoupable/skills, where each skill is a directory with a SKILL.md root file plus optional references/, scripts/, and assets/. This PR adds content only — it does NOT add a Skills tab to the sidebar nav. That nav integration ships in the navigation restructure PR (PR 7 of the stack), which makes these pages visible alongside the existing reference docs. Made-with: Cursor
Reorganizes the docs sidebar into a tab structure organized around
what agents actually do, rather than around HTTP verbs or resource
shapes. Pure docs.json change — no MDX content modified, no brand
fields touched.
New tab structure:
Overview - Start here / Interfaces / Skills entry points
Chat - AI Chat conversation endpoints
Research - Artist discovery + 9 sub-groups
(metrics, audience, playlists, charts, web, ...)
Artists - Artist Management + Fans & Posts
Catalog - Songs + Catalogs
Content - Generate / Edit / Analyze / Templates / Legacy /
Content Agent (verb-based, matches Research style)
Automation - Scheduled Tasks / Pulses / Notifications
Accounts - Agent Onboarding + Accounts/Orgs/Sandboxes/...
Skills - 10 skill playbooks
Within each tab, groups use single-verb or short-phrase names
(Generate, Edit, Analyze) rather than the previous
"Content Endpoints" / "Pipeline Endpoints" pattern. This matches the
naming convention Research already uses (Artist discovery,
Metrics & insights, Charts & radio).
Also touches:
- navbar: GitHub moved from sidebar global anchors to navbar links;
Launch App removed (redundant with primary "Get API Key" CTA);
Blog and Support kept.
- global anchors: emptied (no more competing CTAs at the top of the
sidebar; the navbar handles it).
- contextual: enables copy/view/chatgpt/claude/perplexity/mcp/cursor/
vscode export options on every page.
This PR depends on the Skills system (PR 6 of the stack) and the
agent-first onboarding pages (PR 5) for its referenced page slugs to
exist. If this lands before those, several nav entries will 404
until they merge — recommend reviewing/landing 5 and 6 first.
Made-with: Cursor
The favicon was still pointing at the legacy default favicon.ico
(15KB, dated April 18) — never updated when the rest of the brand
was. This PR's docs.json kept the same `favicon: "/favicon.ico"`
reference as main.
Three fixes:
1. Replace the bloated logo/icon-lightmode.svg (457KB — was a
base64-embedded raster) with a clean 871-byte vector. The path
data comes from icon-darkmode.svg with the fill swapped from
white to #0a0a0a (the brand primary).
2. Switch docs.json to Mintlify's theme-aware favicon syntax so
light-mode browsers use the dark-colored icon and dark-mode
browsers use the white-on-transparent variant:
"favicon": {
"light": "/logo/icon-lightmode.svg",
"dark": "/logo/icon-darkmode.svg"
}
3. Delete the now-unused root favicon.ico. Mintlify auto-generates
/favicons/favicon-16x16.png, /favicon-32x32.png,
/apple-touch-icon.png, and /favicon.ico from whatever's in the
docs.json favicon config — keeping a stale .ico at the root just
creates confusion.
Verified by curl-ing the dev server's auto-generated favicon
endpoints — sizes changed (15406 → 33310 bytes for favicon.ico),
confirming the new SVG is the source.
Made-with: Cursor
…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
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
- Update favicon.ico - Replace legacy logo/dark.png and logo/light.svg with new icon/wordmark variants (icon-darkmode, icon-lightmode, wordmark-darkmode, wordmark-lightmode) - Add Geist, GeistMono, GeistPixel, InstrumentSerif, and PlusJakartaSans font families under fonts/ for the new brand system Sets the asset baseline for the upcoming brand and theme refresh PRs. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # favicon.ico # logo/icon-lightmode.svg
Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # api-reference/openapi/content.json # content-agent.mdx
Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # agents.mdx # authentication.mdx # index.mdx # quickstart.mdx
Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # docs.json
|
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 documentation and OpenAPI specs for an agent-first experience: replaces single-call signup with a two-step ChangesDocs + API / Agent onboarding
Sequence Diagram(s)sequenceDiagram
participant Agent as AI Agent
participant SignupAPI as /api/agents/signup
participant VerifyAPI as /api/agents/verify
participant RecoupAPI as Recoup API
participant Skills as Skills System
Agent->>SignupAPI: POST email
SignupAPI-->>Agent: verification code
Agent->>VerifyAPI: POST code
VerifyAPI-->>Agent: x-api-key
Agent->>RecoupAPI: Authenticated requests (Header: x-api-key)
RecoupAPI-->>Agent: account/roster/filesystem data
Agent->>Skills: Load SKILL.md (triggers, endpoints)
Skills-->>Agent: parsed skill metadata
Agent->>RecoupAPI: Execute skill workflows (content, research, etc.)
RecoupAPI-->>Agent: operation results / task callbacks
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested reviewers
🚥 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)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. 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 |
PR #174's nav structure was written Apr 27, before three pages were added to main: - api-reference/ai/models (added by #177 on May 1) - api-reference/sessions/create (added by #186 on May 3) - api-reference/sessions/get (added by #185 on May 4) These pages exist on disk but had no nav entry in the combined PR, which would orphan them once #189 lands. Adding them in: - Accounts tab → new "Sessions" group placed after "Sandboxes" (matches main's grouping of sessions with sandboxes) - Chat tab → new "Models" group at the end (closest semantic fit; main grouped this under "Tools & Reference" which doesn't exist in our restructured 9-tab layout) Co-authored-by: Cursor <cursoragent@cursor.com>
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
7 issues found across 47 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="mcp.mdx">
<violation number="1" location="mcp.mdx:2">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**
mcp.mdx exceeds the rule’s 100-line file limit, so it should be split or reduced for maintainability.</violation>
</file>
<file name="docs.json">
<violation number="1" location="docs.json:171">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**
Navigation references docs routes that do not exist in the repository, creating broken doc links.</violation>
</file>
<file name="agents.mdx">
<violation number="1" location="agents.mdx:2">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**
`agents.mdx` exceeds the rule’s <100 line limit and combines multiple responsibilities into one page.</violation>
<violation number="2" location="agents.mdx:46">
P2: The authentication steps are written as if every signup requires email-code verification, which contradicts the documented throwaway `agent+...@recoupable.com` path and can misroute onboarding.</violation>
</file>
<file name="skills/music-industry-research.mdx">
<violation number="1" location="skills/music-industry-research.mdx:16">
P2: Use a consistent endpoint prefix: this line incorrectly references `/research/*` instead of `/api/research/*`.</violation>
</file>
<file name="api-reference/openapi/content.json">
<violation number="1" location="api-reference/openapi/content.json:619">
P2: `POST /api/content/create` description now documents `{run_id}`, but the actual documented response shape uses `runIds` (array). Update the description to match the response schema.</violation>
</file>
<file name="authentication.mdx">
<violation number="1" location="authentication.mdx:11">
P2: Bearer token guidance is too narrow: it says Bearer is only for Privy JWTs, but MCP docs require API keys in the Bearer header.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| @@ -1,78 +1,161 @@ | |||
| --- | |||
There was a problem hiding this comment.
P2: Custom agent: Enforce Clear Code Style and Maintainability Practices
mcp.mdx exceeds the rule’s 100-line file limit, so it should be split or reduced for maintainability.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At mcp.mdx, line 2:
<comment>mcp.mdx exceeds the rule’s 100-line file limit, so it should be split or reduced for maintainability.</comment>
<file context>
@@ -1,78 +1,161 @@
---
-title: "MCP"
-description: "Connect AI agents to the Recoup platform using the Model Context Protocol (MCP) server."
+title: "MCP Server"
+description: "Connect any AI agent to Recoup via the Model Context Protocol — Claude, ChatGPT, Cursor, and 40+ Recoup tools natively."
---
</file context>
| @@ -1,96 +1,172 @@ | |||
| --- | |||
There was a problem hiding this comment.
P2: Custom agent: Enforce Clear Code Style and Maintainability Practices
agents.mdx exceeds the rule’s <100 line limit and combines multiple responsibilities into one page.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At agents.mdx, line 2:
<comment>`agents.mdx` exceeds the rule’s <100 line limit and combines multiple responsibilities into one page.</comment>
<file context>
@@ -1,96 +1,172 @@
---
-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."
---
</file context>
|
|
||
| ## What it produces | ||
|
|
||
| A structured research output answering the user's question — usually a synthesis across multiple `/research/*` calls (e.g. profile + metrics + audience + similar artists), formatted for either the agent's continued reasoning or direct delivery to the user. |
There was a problem hiding this comment.
P2: Use a consistent endpoint prefix: this line incorrectly references /research/* instead of /api/research/*.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At skills/music-industry-research.mdx, line 16:
<comment>Use a consistent endpoint prefix: this line incorrectly references `/research/*` instead of `/api/research/*`.</comment>
<file context>
@@ -0,0 +1,24 @@
+
+## What it produces
+
+A structured research output answering the user's question — usually a synthesis across multiple `/research/*` calls (e.g. profile + metrics + audience + similar artists), formatted for either the agent's continued reasoning or direct delivery to the user.
+
+## Endpoints it uses
</file context>
| "post": { | ||
| "description": "Trigger the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `runIds` — an array of run IDs that can each be polled via [GET /api/tasks/runs](/api-reference/tasks/runs).", | ||
| "deprecated": true, | ||
| "description": "**Legacy pipeline.** Runs the full content-creation pipeline (image, video, caption, edit, upscale) in a single call. Powers the Content Agent Slack bot. New integrations should compose the individual primitives ([`POST /api/content/image`](/api-reference/content/generate-image), [`POST /api/content/video`](/api-reference/content/generate-video), [`POST /api/content/caption`](/api-reference/content/generate-caption), and so on) for finer-grained control.\n\nTriggers the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `{run_id}` for polling progress via [`GET /api/tasks/runs`](/api-reference/tasks/runs).", |
There was a problem hiding this comment.
P2: POST /api/content/create description now documents {run_id}, but the actual documented response shape uses runIds (array). Update the description to match the response schema.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/content.json, line 619:
<comment>`POST /api/content/create` description now documents `{run_id}`, but the actual documented response shape uses `runIds` (array). Update the description to match the response schema.</comment>
<file context>
@@ -610,7 +615,8 @@
"post": {
- "description": "Trigger the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `runIds` — an array of run IDs that can each be polled via [GET /api/tasks/runs](/api-reference/tasks/runs).",
+ "deprecated": true,
+ "description": "**Legacy pipeline.** Runs the full content-creation pipeline (image, video, caption, edit, upscale) in a single call. Powers the Content Agent Slack bot. New integrations should compose the individual primitives ([`POST /api/content/image`](/api-reference/content/generate-image), [`POST /api/content/video`](/api-reference/content/generate-video), [`POST /api/content/caption`](/api-reference/content/generate-caption), and so on) for finer-grained control.\n\nTriggers the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `{run_id}` for polling progress via [`GET /api/tasks/runs`](/api-reference/tasks/runs).",
"security": [
{
</file context>
Suggested change
| "description": "**Legacy pipeline.** Runs the full content-creation pipeline (image, video, caption, edit, upscale) in a single call. Powers the Content Agent Slack bot. New integrations should compose the individual primitives ([`POST /api/content/image`](/api-reference/content/generate-image), [`POST /api/content/video`](/api-reference/content/generate-video), [`POST /api/content/caption`](/api-reference/content/generate-caption), and so on) for finer-grained control.\n\nTriggers the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `{run_id}` for polling progress via [`GET /api/tasks/runs`](/api-reference/tasks/runs).", | |
| "description": "**Legacy pipeline.** Runs the full content-creation pipeline (image, video, caption, edit, upscale) in a single call. Powers the Content Agent Slack bot. New integrations should compose the individual primitives ([`POST /api/content/image`](/api-reference/content/generate-image), [`POST /api/content/video`](/api-reference/content/generate-video), [`POST /api/content/caption`](/api-reference/content/generate-caption), and so on) for finer-grained control.\n\nTriggers the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `runIds` (an array of run IDs) for polling progress via [`GET /api/tasks/runs`](/api-reference/tasks/runs).", |
|
|
||
| Providing both headers in the same request will result in a `401` error. | ||
| | API Key | `x-api-key` | Servers, scripts, CLI, AI agents | | ||
| | Bearer Token | `Authorization: Bearer <jwt>` | Frontend apps via Privy | |
There was a problem hiding this comment.
P2: Bearer token guidance is too narrow: it says Bearer is only for Privy JWTs, but MCP docs require API keys in the Bearer header.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At authentication.mdx, line 11:
<comment>Bearer token guidance is too narrow: it says Bearer is only for Privy JWTs, but MCP docs require API keys in the Bearer header.</comment>
<file context>
@@ -1,115 +1,94 @@
-
-Providing both headers in the same request will result in a `401` error.
+| API Key | `x-api-key` | Servers, scripts, CLI, AI agents |
+| Bearer Token | `Authorization: Bearer <jwt>` | Frontend apps via Privy |
<Note>
</file context>
| ``` | ||
| </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."* |
There was a problem hiding this comment.
P2: The authentication steps are written as if every signup requires email-code verification, which contradicts the documented throwaway agent+...@recoupable.com path and can misroute onboarding.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At agents.mdx, line 46:
<comment>The authentication steps are written as if every signup requires email-code verification, which contradicts the documented throwaway `agent+...@recoupable.com` path and can misroute onboarding.</comment>
<file context>
@@ -1,96 +1,172 @@
+ ```
+ </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">
</file context>
Suggested change
| A 6-digit code was sent to their inbox. Ask them: *"Check your email for a verification code and share it with me."* | |
| If signup returned an `api_key`, use it immediately. Otherwise, ask the human for the 6-digit verification code sent to their inbox. |
PR #174's nav was written Apr 27. On Apr 28, main #163 ("docs: remove instagram scrape endpoints") deleted these two MDX files entirely: - api-reference/instagram/comments.mdx - api-reference/instagram/profiles.mdx The combined PR's nav still pointed at them, which would 404 in production. Removing the nav entries to match main's intent. Co-authored-by: Cursor <cursoragent@cursor.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 11
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
api-reference/openapi/content.json (1)
3575-3586:⚠️ Potential issue | 🟠 Major | ⚡ Quick winRequire
promptorcomposition_planin the music request schemas.All three schemas describe “provide either a text prompt or a composition plan,” but none of them require either field. Generated clients and validators will therefore accept
{}as valid input even though the prose says otherwise. Please encode that rule in the schema instead of leaving it only in descriptions.Also applies to: 3609-3619, 3700-3710
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@api-reference/openapi/content.json` around lines 3575 - 3586, The MusicComposeDetailedRequest schema currently lists "prompt" and "composition_plan" as optional properties but must require at least one; update MusicComposeDetailedRequest to enforce this by adding an anyOf with [{"required":["prompt"]},{"required":["composition_plan"]}] (or equivalent JSON Schema construct) alongside the existing properties so {} is invalid; apply the same change to the other two music compose request schemas that declare "prompt" and "composition_plan" (the schemas in the other two ranges) so all compose endpoints require either prompt or composition_plan.
🧹 Nitpick comments (3)
index.mdx (1)
6-8: ⚡ Quick winSplit the top Info block into scannable bullets.
Line 7 packs multiple actions into one long sentence, which is hard to scan quickly for onboarding-critical steps.
Proposed refactor
<Info> -**AI agent?** Base URL: `https://recoup-api.vercel.app/api`. Use `x-api-key` if your human has a key. Otherwise, `POST /api/agents/signup` with their email — ask them for the verification code from their inbox, then `POST /api/agents/verify` to get a key. [Agent guide →](/agents) | [Endpoint map ↓](`#for-ai-agents`) +**AI agent?** +- Base URL: `https://recoup-api.vercel.app/api` +- If your human already has a key, send `x-api-key`. +- Otherwise: + 1. `POST /api/agents/signup` with their email + 2. Ask for the inbox verification code + 3. `POST /api/agents/verify` to get a key +- [Agent guide →](/agents) | [Endpoint map ↓](`#for-ai-agents`) </Info>As per coding guidelines, "Keep documentation content concise and scannable".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@index.mdx` around lines 6 - 8, Split the single Info block into scannable bullets: break the long sentence inside the <Info> block into separate bullet lines for Base URL (https://recoup-api.vercel.app/api), authentication with x-api-key, the signup flow (POST /api/agents/signup with email → request verification code), the verify step (POST /api/agents/verify to obtain a key), and keep the two links as distinct inline items (“Agent guide →” and “Endpoint map ↓”) so readers can quickly scan onboarding steps and links.agents.mdx (1)
37-56: ⚡ Quick winExtract signup/verify steps into a shared snippet to prevent doc drift.
This flow is duplicated across onboarding/auth pages. Centralizing it will keep behavior changes consistent.
As per coding guidelines, "Follow DRY principle - don't duplicate content across pages, use snippets instead".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@agents.mdx` around lines 37 - 56, Extract the duplicated signup/verify flow (the Steps/Step block that shows the POST to /api/agents/signup and /api/agents/verify and the instruction to store the returned api_key) into a single shared MDX snippet (e.g., a reusable snippet named "agents-signup-verify") and replace the duplicated blocks on onboarding/auth pages with an include/import of that snippet; ensure the snippet contains the exact curl examples and the note about exporting RECOUP_API_KEY and that pages reference the snippet (instead of copying Steps/Step) so future changes to the signup or verify flow are made in one location.content-agent.mdx (1)
40-56: ⚡ Quick winThis section overstates what the agent actually calls today.
The heading says “Endpoints it uses” and the copy says “You orchestrate them,” but the data-flow section below still says the agent triggers legacy
POST /api/content/create. Renaming this to something like “Available content primitives” or collapsing it into links would avoid duplicating seven API descriptions and drifting from the actual flow.As per coding guidelines,
**/*.mdx:Follow DRY principle - don't duplicate content across pages, use snippets instead.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@content-agent.mdx` around lines 40 - 56, Rename the section titled "Endpoints it uses" to something like "Available content primitives" and change the wording from "You orchestrate them" to neutral phrasing that reflects these are available primitives (e.g., "The content API exposes the following primitives"). Remove or de-emphasize the duplicated endpoint descriptions by collapsing them into concise links or including a reusable snippet reference, and update the data-flow text that still references legacy POST /api/content/create to clearly state that the agent currently triggers the legacy POST /api/content/create pipeline (or call out the preferred approach) to avoid contradiction; ensure the MDX follows the DRY guideline for **/*.mdx by replacing the inline table with a snippet/include and keeping only a short summary in this page.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@api-reference/openapi/content.json`:
- Line 1345: The API docs list a text-only "prompt" video mode but the request
schema ContentCreateVideoRequest still requires image_url (and notes prompt-only
is unsupported), causing a contract mismatch; fix by either removing "prompt"
from the mode enumeration in the description string (the block listing modes in
api-reference/openapi/content.json) or by updating the ContentCreateVideoRequest
schema to allow prompt-only requests (make image_url optional and adjust
validation/comments), and ensure the description and schema consistently reflect
the chosen behavior.
- Around line 618-619: The description for the legacy content pipeline
incorrectly says it returns `{run_id}` while the 202 response/schema expose
`runIds` (an array); update the description text in the legacy create docs to
state that the endpoint returns `runIds` (array) and use `runIds` consistently
across the legacy pipeline doc (replace any `{run_id}` occurrences, including
the other occurrence noted nearby) so the intro, response example, and schema
match the `runIds` field name used in the 202 response.
In `@api-reference/openapi/releases.json`:
- Around line 3532-3537: The schema for profileUrls currently allows arbitrary
keys/strings but the description mandates only specific uppercase platform keys;
update the schema to enforce that contract by replacing additionalProperties
with explicit properties for SPOTIFY, INSTAGRAM, TIKTOK, TWITTER, YOUTUBE,
APPLE, FACEBOOK, and THREADS (each with type: string) and set
additionalProperties: false on the profileUrls object, or if you prefer not to
enforce it in the schema, remove the normative language from the description;
locate the profileUrls object in the OpenAPI JSON and modify the
additionalProperties/properties there to implement one of these two options.
In `@docs.json`:
- Around line 459-462: Update the primary CTA object (the "primary" button with
label "Get API Key") in docs.json so its href uses the canonical app URL
"https://chat.recoupable.com" instead of the "/keys" subpath, and while you’re
there verify and correct other branding entries in docs.json to match the spec:
support email agent@recoupable.com, app URL https://chat.recoupable.com, website
https://recoupable.com, and the official social URLs for X, GitHub, and
LinkedIn.
- Around line 168-174: Remove the known-broken Instagram sidebar entries by
updating the "Instagram" nav block: either delete the entire object with
"group": "Instagram" or remove the two page strings
"api-reference/instagram/comments" and "api-reference/instagram/profiles" from
its "pages" array (or replace them with existing Instagram doc paths); ensure
the "pages" array only lists pages that actually exist so the published sidebar
has no dead links.
- Around line 5-9: Update the branded primary color in the JSON by replacing the
"colors.primary" value (currently "#0a0a0a") with the Recoup brand hex "#345A5D"
so the docs' primary accent matches Recoup-Chat; ensure the "colors" object
still contains "light" and "dark" keys unchanged and that only the "primary"
property is modified.
In `@mcp.mdx`:
- Around line 14-25: The documentation example uses
https://api.recoupable.com/mcp for the MCP client (created via
StreamableHTTPClientTransport and the URL passed to its constructor) while other
onboarding docs reference the REST/OpenAPI host
https://recoup-api.vercel.app/api; add an explicit note near the example (or
change the example host if that was a mistake) clarifying that MCP (used by
StreamableHTTPClientTransport) and REST/OpenAPI are different endpoints and must
not be interchanged, and reference the RECOUP_API_KEY usage so readers know the
same API key is used but the base URL differs.
In `@quickstart.mdx`:
- Around line 21-23: The curl + jq command that sets RECOUP_API_KEY uses "jq -r
.api_key" which silently returns null on error responses; change it to use jq
with the -e flag so jq exits nonzero when .api_key is missing or null (i.e.,
replace the jq invocation that extracts .api_key with one that includes -e), and
ensure the shell command checks the exit status so RECOUP_API_KEY is not
exported on failed verification; reference the RECOUP_API_KEY assignment and the
jq invocation in your update.
In `@skills/artist-workspace.mdx`:
- Line 2: Update the frontmatter title in the MDX file so it uses human-readable
title casing instead of kebab-case: change the title value currently set as
"artist-workspace" to a proper title like "Artist Workspace" (the frontmatter
key is title in skills/artist-workspace.mdx and this value is used to render the
page H1 and browser tab).
In `@skills/getting-started.mdx`:
- Line 2: Update the frontmatter title value from the kebab-case string
("getting-started") to a human-readable, title-cased form (e.g., "Getting
Started") so the page H1 and browser tab show a readable title; edit the title
field in the frontmatter of the getting-started page (the title key in the
file's frontmatter) and ensure it follows title-casing and documentation style
guidelines.
In `@skills/release-management.mdx`:
- Line 2: The frontmatter title currently uses kebab-case ("release-management")
and must be changed to human-readable casing; update the title value in the
frontmatter (the line with title: "release-management") to a properly cased,
spaced string such as "Release Management" so the page H1 renders correctly and
follows the documentation casing guidelines.
---
Outside diff comments:
In `@api-reference/openapi/content.json`:
- Around line 3575-3586: The MusicComposeDetailedRequest schema currently lists
"prompt" and "composition_plan" as optional properties but must require at least
one; update MusicComposeDetailedRequest to enforce this by adding an anyOf with
[{"required":["prompt"]},{"required":["composition_plan"]}] (or equivalent JSON
Schema construct) alongside the existing properties so {} is invalid; apply the
same change to the other two music compose request schemas that declare "prompt"
and "composition_plan" (the schemas in the other two ranges) so all compose
endpoints require either prompt or composition_plan.
---
Nitpick comments:
In `@agents.mdx`:
- Around line 37-56: Extract the duplicated signup/verify flow (the Steps/Step
block that shows the POST to /api/agents/signup and /api/agents/verify and the
instruction to store the returned api_key) into a single shared MDX snippet
(e.g., a reusable snippet named "agents-signup-verify") and replace the
duplicated blocks on onboarding/auth pages with an include/import of that
snippet; ensure the snippet contains the exact curl examples and the note about
exporting RECOUP_API_KEY and that pages reference the snippet (instead of
copying Steps/Step) so future changes to the signup or verify flow are made in
one location.
In `@content-agent.mdx`:
- Around line 40-56: Rename the section titled "Endpoints it uses" to something
like "Available content primitives" and change the wording from "You orchestrate
them" to neutral phrasing that reflects these are available primitives (e.g.,
"The content API exposes the following primitives"). Remove or de-emphasize the
duplicated endpoint descriptions by collapsing them into concise links or
including a reusable snippet reference, and update the data-flow text that still
references legacy POST /api/content/create to clearly state that the agent
currently triggers the legacy POST /api/content/create pipeline (or call out the
preferred approach) to avoid contradiction; ensure the MDX follows the DRY
guideline for **/*.mdx by replacing the inline table with a snippet/include and
keeping only a short summary in this page.
In `@index.mdx`:
- Around line 6-8: Split the single Info block into scannable bullets: break the
long sentence inside the <Info> block into separate bullet lines for Base URL
(https://recoup-api.vercel.app/api), authentication with x-api-key, the signup
flow (POST /api/agents/signup with email → request verification code), the
verify step (POST /api/agents/verify to obtain a key), and keep the two links as
distinct inline items (“Agent guide →” and “Endpoint map ↓”) so readers can
quickly scan onboarding steps and links.
🪄 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: f6e31ddb-556b-42ac-a384-a067ff1a7b61
⛔ Files ignored due to path filters (20)
favicon.icois excluded by!**/*.icofonts/Geist/Geist-Variable.woff2is excluded by!**/*.woff2fonts/Geist/Geist-VariableItalic.woff2is excluded by!**/*.woff2fonts/GeistMono/GeistMono-Variable.woff2is excluded by!**/*.woff2fonts/GeistMono/GeistMono-VariableItalic.woff2is excluded by!**/*.woff2fonts/GeistPixel/GeistPixel-Circle.woff2is excluded by!**/*.woff2fonts/GeistPixel/GeistPixel-Grid.woff2is excluded by!**/*.woff2fonts/GeistPixel/GeistPixel-Line.woff2is excluded by!**/*.woff2fonts/GeistPixel/GeistPixel-Square.woff2is excluded by!**/*.woff2fonts/GeistPixel/GeistPixel-Triangle.woff2is excluded by!**/*.woff2fonts/InstrumentSerif/InstrumentSerif-Italic.ttfis excluded by!**/*.ttffonts/InstrumentSerif/InstrumentSerif-Regular.ttfis excluded by!**/*.ttffonts/PlusJakartaSans/PlusJakartaSans-Variable.ttfis excluded by!**/*.ttffonts/PlusJakartaSans/PlusJakartaSans-VariableItalic.ttfis excluded by!**/*.ttflogo/dark.pngis excluded by!**/*.pnglogo/icon-darkmode.svgis excluded by!**/*.svglogo/icon-lightmode.svgis excluded by!**/*.svglogo/light.svgis excluded by!**/*.svglogo/wordmark-darkmode.svgis excluded by!**/*.svglogo/wordmark-lightmode.svgis excluded by!**/*.svg
📒 Files selected for processing (27)
agents.mdxapi-reference/image/generation.mdxapi-reference/openapi/content.jsonapi-reference/openapi/releases.jsonapi-reference/openapi/research.jsonapi-reference/research/search.mdxapi-reference/spotify/search.mdxapi-reference/transcribe/audio.mdxauthentication.mdxcontent-agent.mdxdocs.jsonfonts/InstrumentSerif/OFL.txtindex.mdxmcp.mdxquickstart.mdxskills.mdxskills/artist-workspace.mdxskills/chart-metric.mdxskills/content-creation.mdxskills/getting-started.mdxskills/music-industry-research.mdxskills/release-management.mdxskills/setup-sandbox.mdxskills/song-writing.mdxskills/streaming-growth.mdxskills/trend-to-song.mdxworkflows/create-artist.mdx
Comment on lines
+618
to
+619
| "deprecated": true, | ||
| "description": "**Legacy pipeline.** Runs the full content-creation pipeline (image, video, caption, edit, upscale) in a single call. Powers the Content Agent Slack bot. New integrations should compose the individual primitives ([`POST /api/content/image`](/api-reference/content/generate-image), [`POST /api/content/video`](/api-reference/content/generate-video), [`POST /api/content/caption`](/api-reference/content/generate-caption), and so on) for finer-grained control.\n\nTriggers the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `{run_id}` for polling progress via [`GET /api/tasks/runs`](/api-reference/tasks/runs).", |
There was a problem hiding this comment.
Use runIds consistently in the legacy create docs.
The intro still says this endpoint returns {run_id}, but the 202 response and schema expose runIds as an array. That mismatch will push readers toward parsing the wrong field name.
Also applies to: 640-641
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@api-reference/openapi/content.json` around lines 618 - 619, The description
for the legacy content pipeline incorrectly says it returns `{run_id}` while the
202 response/schema expose `runIds` (an array); update the description text in
the legacy create docs to state that the endpoint returns `runIds` (array) and
use `runIds` consistently across the legacy pipeline doc (replace any `{run_id}`
occurrences, including the other occurrence noted nearby) so the intro, response
example, and schema match the `runIds` field name used in the 202 response.
| "/api/content/video": { | ||
| "post": { | ||
| "description": "Generate a video. Set `mode` to control what kind of video you get:\n\n- `prompt` — create a video from a text description\n- `animate` — animate a still image\n- `reference` — use an image as a style/subject reference (not the first frame)\n- `extend` — continue an existing video\n- `first-last` — generate a video that transitions between two images\n- `lipsync` — sync face movement to an audio clip\n\nIf `mode` is omitted, it's inferred from the inputs you provide.", | ||
| "description": "Generate a video. Set `mode` to control what kind of video you get:\n\n- `prompt` \u2014 create a video from a text description\n- `animate` \u2014 animate a still image\n- `reference` \u2014 use an image as a style/subject reference (not the first frame)\n- `extend` \u2014 continue an existing video\n- `first-last` \u2014 generate a video that transitions between two images\n- `lipsync` \u2014 sync face movement to an audio clip\n\nIf `mode` is omitted, it's inferred from the inputs you provide.", |
There was a problem hiding this comment.
Don't document a text-only video mode that the schema rejects.
The endpoint description says prompt mode creates a video from text alone, but ContentCreateVideoRequest still requires image_url and even says prompt-only is unsupported. Right now the published contract contradicts itself. Either remove text-only prompt from the mode list or relax the schema so those requests are actually valid.
Also applies to: 2675-2704
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@api-reference/openapi/content.json` at line 1345, The API docs list a
text-only "prompt" video mode but the request schema ContentCreateVideoRequest
still requires image_url (and notes prompt-only is unsupported), causing a
contract mismatch; fix by either removing "prompt" from the mode enumeration in
the description string (the block listing modes in
api-reference/openapi/content.json) or by updating the ContentCreateVideoRequest
schema to allow prompt-only requests (make image_url optional and adjust
validation/comments), and ensure the description and schema consistently reflect
the chosen behavior.
Comment on lines
3532
to
3537
| "profileUrls": { | ||
| "type": "object", | ||
| "description": "Map of uppercase platform identifier to social profile URL. Each entry replaces the existing social for that platform; platforms not included are preserved. Recognized keys: SPOTIFY, INSTAGRAM, TIKTOK, TWITTER, YOUTUBE, APPLE, FACEBOOK, THREADS. Keys are matched case-sensitively — lowercase keys will create duplicate socials instead of replacing the existing entry.", | ||
| "description": "Map of uppercase platform identifier to social profile URL. Each entry replaces the existing social for that platform; platforms not included are preserved. Recognized keys: SPOTIFY, INSTAGRAM, TIKTOK, TWITTER, YOUTUBE, APPLE, FACEBOOK, THREADS. Keys are matched case-sensitively \u2014 lowercase keys will create duplicate socials instead of replacing the existing entry.", | ||
| "additionalProperties": { | ||
| "type": "string" | ||
| }, |
There was a problem hiding this comment.
Encode the profileUrls contract in the schema.
The description now makes uppercase platform keys and social-profile URLs part of the public API, but the schema still accepts any property name and any string value. That means generated clients/docs won't catch instagram: "foo" and users only discover the duplicate-social behavior at runtime. Either model those constraints here or remove the normative validation language from the description.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@api-reference/openapi/releases.json` around lines 3532 - 3537, The schema for
profileUrls currently allows arbitrary keys/strings but the description mandates
only specific uppercase platform keys; update the schema to enforce that
contract by replacing additionalProperties with explicit properties for SPOTIFY,
INSTAGRAM, TIKTOK, TWITTER, YOUTUBE, APPLE, FACEBOOK, and THREADS (each with
type: string) and set additionalProperties: false on the profileUrls object, or
if you prefer not to enforce it in the schema, remove the normative language
from the description; locate the profileUrls object in the OpenAPI JSON and
modify the additionalProperties/properties there to implement one of these two
options.
Comment on lines
5
to
+9
| "colors": { | ||
| "primary": "#345A5D", | ||
| "light": "#4A7A7D", | ||
| "dark": "#1E3A3D" | ||
| "primary": "#0a0a0a", | ||
| "light": "#ededed", | ||
| "dark": "#0a0a0a" | ||
| }, |
There was a problem hiding this comment.
Restore the branded primary color.
#0a0a0a changes the docs’ primary accent away from the required Recoup brand color, so buttons, links, and other primary UI affordances will render off-brand.
Suggested fix
"colors": {
- "primary": "#0a0a0a",
+ "primary": "#345A5D",
"light": "#ededed",
"dark": "#0a0a0a"
},As per coding guidelines, docs.json: 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
| "colors": { | |
| "primary": "#345A5D", | |
| "light": "#4A7A7D", | |
| "dark": "#1E3A3D" | |
| "primary": "#0a0a0a", | |
| "light": "#ededed", | |
| "dark": "#0a0a0a" | |
| }, | |
| "colors": { | |
| "primary": "#345A5D", | |
| "light": "#ededed", | |
| "dark": "#0a0a0a" | |
| }, |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs.json` around lines 5 - 9, Update the branded primary color in the JSON
by replacing the "colors.primary" value (currently "#0a0a0a") with the Recoup
brand hex "#345A5D" so the docs' primary accent matches Recoup-Chat; ensure the
"colors" object still contains "light" and "dark" keys unchanged and that only
the "primary" property is modified.
Comment on lines
+14
to
+25
| Pass your API key as a Bearer token when connecting: | ||
|
|
||
| You can get a key from the [API Keys page](https://chat.recoupable.com/keys). | ||
| ```typescript | ||
| import { Client } from "@modelcontextprotocol/sdk/client/index.js"; | ||
| import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; | ||
|
|
||
| ## Tools | ||
| const RECOUP_API_KEY = process.env.RECOUP_API_KEY; | ||
|
|
||
| ### prompt_sandbox | ||
| const transport = new StreamableHTTPClientTransport( | ||
| new URL("https://api.recoupable.com/mcp"), | ||
| { requestInit: { headers: { Authorization: `Bearer ${RECOUP_API_KEY}` } } }, | ||
| ); |
There was a problem hiding this comment.
Clarify MCP host vs REST host to avoid misconfiguration.
Line 23 uses https://api.recoupable.com/mcp, while other onboarding pages use https://recoup-api.vercel.app/api for REST. Add an explicit note that these are different endpoints (or align if not intentional), otherwise users can wire the wrong base URL.
Proposed clarification
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);+
+MCP uses https://api.recoupable.com/mcp. REST/OpenAPI calls use https://recoup-api.vercel.app/api.
+
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @mcp.mdx around lines 14 - 25, The documentation example uses
https://api.recoupable.com/mcp for the MCP client (created via
StreamableHTTPClientTransport and the URL passed to its constructor) while other
onboarding docs reference the REST/OpenAPI host
https://recoup-api.vercel.app/api; add an explicit note near the example (or
change the example host if that was a mistake) clarifying that MCP (used by
StreamableHTTPClientTransport) and REST/OpenAPI are different endpoints and must
not be interchanged, and reference the RECOUP_API_KEY usage so readers know the
same API key is used but the base URL differs.
</details>
<!-- fingerprinting:phantom:poseidon:hawk -->
<!-- 4e71b3a2 -->
<!-- This is an auto-generated comment by CodeRabbit -->
| @@ -0,0 +1,25 @@ | |||
| --- | |||
| title: "artist-workspace" | |||
There was a problem hiding this comment.
Title should use human-readable casing, not kebab-case.
"artist-workspace" will render as the page H1 and browser tab title verbatim. It should read as a proper title.
✏️ Proposed fix
-title: "artist-workspace"
+title: "Artist Workspace"As per coding guidelines: "Use clear, self-documenting titles and descriptions in documentation."
📝 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
| title: "artist-workspace" | |
| title: "Artist Workspace" |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/artist-workspace.mdx` at line 2, Update the frontmatter title in the
MDX file so it uses human-readable title casing instead of kebab-case: change
the title value currently set as "artist-workspace" to a proper title like
"Artist Workspace" (the frontmatter key is title in skills/artist-workspace.mdx
and this value is used to render the page H1 and browser tab).
| @@ -0,0 +1,23 @@ | |||
| --- | |||
| title: "getting-started" | |||
There was a problem hiding this comment.
Title should use human-readable casing, not kebab-case.
"getting-started" renders verbatim as the page H1 and browser tab title. This is the first page many users will land on in the Skills section.
✏️ Proposed fix
-title: "getting-started"
+title: "Getting Started"As per coding guidelines: "Use clear, self-documenting titles and descriptions in documentation."
📝 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
| title: "getting-started" | |
| title: "Getting Started" |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/getting-started.mdx` at line 2, Update the frontmatter title value
from the kebab-case string ("getting-started") to a human-readable, title-cased
form (e.g., "Getting Started") so the page H1 and browser tab show a readable
title; edit the title field in the frontmatter of the getting-started page (the
title key in the file's frontmatter) and ensure it follows title-casing and
documentation style guidelines.
| @@ -0,0 +1,27 @@ | |||
| --- | |||
| title: "release-management" | |||
There was a problem hiding this comment.
Title should use human-readable casing, not kebab-case.
Same issue as skills/artist-workspace.mdx — "release-management" renders verbatim as the page H1.
✏️ Proposed fix
-title: "release-management"
+title: "Release Management"As per coding guidelines: "Use clear, self-documenting titles and descriptions in documentation."
📝 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
| title: "release-management" | |
| title: "Release Management" |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/release-management.mdx` at line 2, The frontmatter title currently
uses kebab-case ("release-management") and must be changed to human-readable
casing; update the title value in the frontmatter (the line with title:
"release-management") to a properly cased, spaced string such as "Release
Management" so the page H1 renders correctly and follows the documentation
casing guidelines.
Reorganize the Skills sidebar around what skills actually do, not how
"creative" they are. Earlier grouping mixed pure craft (song-writing)
with marketing/distribution work (content-creation, release-management)
under one "Creative work" header — that obscured that content production
is marketing, not art.
New 5-group structure:
Overview - landing page
Foundations - recoup-api, getting-started, setup-sandbox,
artist-workspace
(everything that gets an agent integrated and
operating inside a Recoup sandbox)
Research - music-industry-research
(information gathering — distinct mode)
Songwriting - song-writing
(pure craft, no platform dependency)
Marketing & growth - content-creation, release-management,
streaming-growth, trend-to-song
(everything around getting music out and growing
the artist post-release)
Adds a new docs page for the recoup-api skill (the meta-client that
teaches an agent how to authenticate inside a sandbox using the short-
lived RECOUP_ACCESS_TOKEN, scope to RECOUP_ORG_ID, and reach external
services through Recoup's connector actions).
Drops chart-metric entirely — both the nav entry and the .mdx file.
It's not part of the canonical "use what we ship" flow; the same data
is reachable through the Recoup-wrapped /api/research/* endpoints.
Verified locally: all 11 active skill pages return HTTP 200, zero
nav 404s, zero orphan pages.
Co-authored-by: Cursor <cursoragent@cursor.com>
Earlier sidebar over-grouped 10 skills into 5 sections, two of which
(Research, Songwriting) were singletons and looked broken. The genre-
flavored groupings (Songwriting vs Marketing & growth) also forced
debates about where boundary skills like trend-to-song belong.
The only distinction that genuinely matters is do-this-first vs
do-this-when-you-need-it. New 2-group structure:
Overview landing page
Setup recoup-api, getting-started, setup-sandbox,
artist-workspace
Playbooks research → song-writing → trend-to-song →
release-management → content-creation →
streaming-growth (ordered by artist workflow stage)
"Playbooks" matches the language already used in skills.mdx ("markdown
playbooks that teach AI agents..."). Drops "& growth" naming, which
was redundant — all marketing in this context is growth.
Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
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)
492-498:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFooter GitHub URL should match the canonical organization in navbar.
Navbar links to
https://github.com/recoupable(line 467), but footer useshttps://github.com/recoupable-com(line 495). Per the branding guidelines for canonical social URLs, the footer should use the same organization namespace as the navbar.🔧 Proposed fix
"footer": { "socials": { "x": "https://x.com/recoupai", - "github": "https://github.com/recoupable-com", + "github": "https://github.com/recoupable", "linkedin": "https://www.linkedin.com/company/recoupable" } },🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs.json` around lines 492 - 498, The footer's GitHub URL in footer.socials.github is inconsistent with the navbar's canonical org; update footer.socials.github to match the navbar value (replace "https://github.com/recoupable-com" with "https://github.com/recoupable") so both navbar and footer use the same canonical GitHub organization.
♻️ Duplicate comments (3)
docs.json (3)
5-9:⚠️ Potential issue | 🟠 Major | ⚡ Quick winRestore the branded primary color.
primaryis still#0a0a0ain this revision. As per coding guidelines,docs.jsonmust use#345A5Dfrom Recoup-Chat's tailwind config; otherwise primary buttons, links, and accents will render off-brand.🎨 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 current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs.json` around lines 5 - 9, The primary color in docs.json is incorrect: update the "primary" value inside the "colors" object from "#0a0a0a" to the branded value "#345A5D" so that entries using colors.primary (the "colors" object and its "primary" key) match Recoup-Chat's tailwind.config.ts branding.
474-478:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winPrimary CTA still points at
/keysand label was not updated.Two issues on the same block:
hrefstill targetshttps://chat.recoupable.com/keys. As per coding guidelines, the canonical app URL ishttps://chat.recoupable.com. If this is the main app entrypoint, drop the/keyssubpath.- The AI summary states the label was changed from "Get API Key" to "Dashboard", but the file still shows
"Get API Key". Either the summary or the code is stale — please reconcile.🔗 Proposed fix (matches the AI summary intent)
"primary": { "type": "button", - "label": "Get API Key", - "href": "https://chat.recoupable.com/keys" + "label": "Dashboard", + "href": "https://chat.recoupable.com" }As per coding guidelines,
Reference correct branding values: support email agent@recoupable.com, app URL https://chat.recoupable.com, website https://recoupable.com, and social URLs (X, GitHub, LinkedIn).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs.json` around lines 474 - 478, The primary CTA object currently has an incorrect href and stale label; update the "primary" object's href to the canonical app URL "https://chat.recoupable.com" (remove the "/keys" path) and change the "label" from "Get API Key" to "Dashboard" to match the AI summary, and while editing confirm branding values in this block use the canonical app URL and support email "agent@recoupable.com" (also ensure website and social links elsewhere follow https://recoupable.com and the approved social URLs).
174-177:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRemove the empty
The
pagesarray was emptied to drop broken Instagram entries, but the group object remains. Mintlify will still render an empty "Instagram" header in the sidebar with no child pages. Either remove the entire group object or repopulate it with real pages.🧹 Proposed fix (drop the empty group)
{ "group": "Web intelligence", "pages": [ "api-reference/research/instagram-posts", "api-reference/research/web", "api-reference/research/deep", "api-reference/research/people", "api-reference/research/extract", "api-reference/research/enrich" ] }, { "group": "Spotify", "pages": [ "api-reference/spotify/search", "api-reference/spotify/artist", "api-reference/spotify/artist-albums", "api-reference/spotify/artist-top-tracks", "api-reference/spotify/album" ] }, - { - "group": "Instagram", - "pages": [] - }, { "group": "Social Scraping",🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs.json` around lines 174 - 177, Remove the empty navigation group object for "Instagram" in docs.json (the object with "group": "Instagram" and an empty "pages" array) so Mintlify won't render an empty sidebar header; alternatively, if you intend to keep it, populate its "pages" array with valid page entries—also ensure the surrounding JSON remains syntactically valid (no dangling commas) after removing or updating the group.
🧹 Nitpick comments (1)
skills/recoup-api.mdx (1)
23-23: ⚡ Quick winAdd links to the referenced OpenAPI spec areas.
The sentence points readers to five spec areas (accounts, social, releases, research, content) but provides no links, leaving them to navigate elsewhere without guidance.
✏️ Suggested improvement
-For internal Recoup calls, see the OpenAPI specs grouped by area: accounts, social, releases, research, content. +For internal Recoup calls, see the OpenAPI specs grouped by area: +[accounts](/api-reference/accounts), [social](/api-reference/social), [releases](/api-reference/releases), [research](/api-reference/research), [content](/api-reference/content).Adjust the paths to match the actual nav routes if they differ.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/recoup-api.mdx` at line 23, Add inline links for the five referenced OpenAPI spec areas so readers can jump directly to each spec: update the sentence that lists "accounts, social, releases, research, content" to convert each area name into a link to its OpenAPI nav route (use the actual nav routes for your docs site), e.g., link "accounts" -> accounts OpenAPI page, "social" -> social OpenAPI page, etc.; ensure the anchor text matches the existing area names and verify the paths resolve in the site navigation.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@docs.json`:
- Around line 492-498: The footer's GitHub URL in footer.socials.github is
inconsistent with the navbar's canonical org; update footer.socials.github to
match the navbar value (replace "https://github.com/recoupable-com" with
"https://github.com/recoupable") so both navbar and footer use the same
canonical GitHub organization.
---
Duplicate comments:
In `@docs.json`:
- Around line 5-9: The primary color in docs.json is incorrect: update the
"primary" value inside the "colors" object from "#0a0a0a" to the branded value
"#345A5D" so that entries using colors.primary (the "colors" object and its
"primary" key) match Recoup-Chat's tailwind.config.ts branding.
- Around line 474-478: The primary CTA object currently has an incorrect href
and stale label; update the "primary" object's href to the canonical app URL
"https://chat.recoupable.com" (remove the "/keys" path) and change the "label"
from "Get API Key" to "Dashboard" to match the AI summary, and while editing
confirm branding values in this block use the canonical app URL and support
email "agent@recoupable.com" (also ensure website and social links elsewhere
follow https://recoupable.com and the approved social URLs).
- Around line 174-177: Remove the empty navigation group object for "Instagram"
in docs.json (the object with "group": "Instagram" and an empty "pages" array)
so Mintlify won't render an empty sidebar header; alternatively, if you intend
to keep it, populate its "pages" array with valid page entries—also ensure the
surrounding JSON remains syntactically valid (no dangling commas) after removing
or updating the group.
---
Nitpick comments:
In `@skills/recoup-api.mdx`:
- Line 23: Add inline links for the five referenced OpenAPI spec areas so
readers can jump directly to each spec: update the sentence that lists
"accounts, social, releases, research, content" to convert each area name into a
link to its OpenAPI nav route (use the actual nav routes for your docs site),
e.g., link "accounts" -> accounts OpenAPI page, "social" -> social OpenAPI page,
etc.; ensure the anchor text matches the existing area names and verify the
paths resolve in the site navigation.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: b921a00b-a819-4378-ba40-c62bb8c24c24
📒 Files selected for processing (2)
docs.jsonskills/recoup-api.mdx
Adds the vercel-labs/add-skill CLI as the primary install method on the Skills landing page. Works with Claude Code, Codex, OpenCode, Cursor, and 50+ other agents — strictly better than the Claude-Code- only `/plugin marketplace add` we had as the lead command. Landing page (skills.mdx) Install section now reads: Install everything: npx skills add recoupable/skills Install one skill: npx skills add recoupable/skills --skill <name> Preview before: npx skills add recoupable/skills --list Plus flags (`-a claude-code`, `--global`, `-y`) and a link to the full CLI reference. Marketplace and git-clone paths kept as alternatives below. Each skill page also gets a tiny `## Install` block right above `## Source` with the per-skill command, so a reader who lands on e.g. /skills/recoup-api can grab just that one. Co-authored-by: Cursor <cursoragent@cursor.com>
A plugin is a different abstraction from a skill — it bundles multiple
skills + commands + agents into one installable workflow. The skills
repo and the plugins repo are distinct distribution surfaces (skills
install via `npx skills add`, plugins via `/plugin marketplace add`),
so they earn distinct nav surfaces.
New tab structure (placed right after Skills):
Plugins
├── Overview ────────────── plugins (landing — what plugins are,
│ install paths for Claude/Codex/Cursor,
│ list of available plugins, how to build
│ and contribute)
└── Available plugins
└── music-catalog-diligence
(comprehensive single page — value prop,
audience, deal workspace structure, all
9 skills with trigger descriptions, all
6 slash commands, QC philosophy, source
link)
Plugin's internal skills (catalog-ingest, rights-diligence, royalty-
audit, etc.) are deliberately NOT listed in the main /skills tab.
Those are music-INVESTMENT skills (M&A diligence audience) and would
pollute the music-MAKING playbook navigation.
Verified: both new pages return HTTP 200, zero nav 404s, zero orphans.
Co-authored-by: Cursor <cursoragent@cursor.com>
content-creation.mdx had `title: "Content Creation"` while every other skill page uses kebab-case matching its URL slug (e.g. `title: "song-writing"`, `title: "music-industry-research"`). That made it the visual outlier in the Skills sidebar — every other entry rendered as kebab-case, "Content Creation" as Title Case. Standardize on the existing pattern. Co-authored-by: Cursor <cursoragent@cursor.com>
…le commands The previous Install section had hand-wavy "add to your config" copy for Codex and Cursor that I cannot find documented anywhere. The user caught it: docs read by agents need literal commands or literal click sequences, not config-talk. Researched and documented the actually correct paths for each runtime: - Claude Code: `/plugin marketplace add` + `/plugin install` (slash commands inside a session). Already correct, kept. - Claude Cowork (NEW section): UI-only install via Claude Desktop's Cowork tab → Customize → Browse plugins → Install. Plugins save locally; require a paid Claude plan. No CLI path exists. - Codex: `codex plugin marketplace add recoupable/plugins` is scriptable. The plugin install step itself currently goes through the interactive `codex /plugins` UI — no headless one-shot install. - Cursor: marketplace UI for human-in-the-loop, OR scriptable manual install via `git clone` into `~/.cursor/plugins/local/<name>`. Note that Cursor doesn't follow symlinks there — must be a real copy. Reload the window after. Lead-in to the section now also says explicitly that these are written for the agent, with each path ending in a verifiable installed state. Plugin page (music-catalog-diligence.mdx) gets a compact one-row-per- agent table for the same four runtimes, linking back to the landing page for prerequisites. Sources: - developers.openai.com/codex/plugins/build (Codex marketplace add) - support.claude.com/en/articles/13837440-use-plugins-in-cowork - code.claude.com/docs/en/plugin-marketplaces (Claude Code) - cursor.com/docs/plugins (Cursor marketplace + local install) Co-authored-by: Cursor <cursoragent@cursor.com>
…sor is manual-only Real install paths verified against the published Cowork tutorial, not against marketing claims of being in any curated marketplace. Cowork (corrected — was completely wrong before): - Path is Customize → Plugins → Add → paste the GitHub URL - For us: https://github.com/recoupable/music-catalog-diligence - Cowork pulls the folder, parses .claude-plugin/plugin.json, and installs. Updates auto-sync when we push to that repo. - Source: https://claude.com/resources/tutorials/how-to-customize-plugins-in-cowork Cursor (corrected — removed false marketplace claim): - recoupable/music-catalog-diligence is NOT in cursor.com/marketplace (which is curated by the Cursor team) - Only path today is `git clone` into ~/.cursor/plugins/local/<name> followed by a window reload - Symlinks still don't work — must be a real copy - Added a note on how to pull updates later (`git pull` + reload) Claude Code and Codex sections unchanged — those use GitHub-shorthand syntax against the registry repo, which works regardless of any curated marketplace listing. Lead-in clarified: the plugin is hosted at recoupable/music-catalog- diligence on GitHub; each agent reads from that source differently. Co-authored-by: Cursor <cursoragent@cursor.com>
Tested live end-to-end against Claude Cowork tonight. The actual UI flow is: Customize > Plugins > [+] > Create plugin > Add marketplace > paste https://github.com/recoupable/plugins > Sync (Earlier copy described an "Add" button and a single-plugin URL paste that don't exist — the real menu has "Add marketplace", "Upload plugin", and "Create with Claude". And the URL must point at a marketplace repo with .claude-plugin/marketplace.json, not at a standalone plugin repo.) The fix that made the install actually work landed on recoupable/plugins/main as f048522: switched the music-catalog- diligence source from a relative submodule path ("./music-catalog- diligence") to a github source object ({"source":"github","repo": "recoupable/music-catalog-diligence"}). Cowork doesn't recurse submodules during marketplace sync, so the relative path resolved to an empty folder and sync failed. Per-plugin install table also updated to point at the marketplace URL (not the standalone repo URL). Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (2)
docs.json (2)
5-9:⚠️ Potential issue | 🟠 Major | ⚡ Quick winRestore the branded primary color.
#0a0a0achanges the site-wide primary accent away from the required Recoup brand color, so buttons, links, and other primary UI elements will render off-brand.As per coding guidelines,
docs.json:Use primary color#345A5Dfrom Recoup-Chat tailwind.config.ts for branding consistency.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs.json` around lines 5 - 9, The primary color value in the colors block (property "primary" inside the "colors" object) is incorrect; update the "primary" entry from "#0a0a0a" back to the Recoup brand color "#345A5D" so that buttons, links and other primary UI elements use the branded color specified in Recoup-Chat's tailwind.config.ts.
481-485:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winPoint the primary CTA at the canonical app URL.
The navbar’s main CTA still targets
/keys, but the branding spec defineshttps://chat.recoupable.comas the canonical app URL.As per coding guidelines,
docs.json:Reference correct branding values: support email agent@recoupable.com, app URL https://chat.recoupable.com, website https://recoupable.com, and social URLs (X, GitHub, LinkedIn).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs.json` around lines 481 - 485, The primary CTA object ("primary" with label "Get API Key") currently points to /keys; update its href to the canonical app URL "https://chat.recoupable.com". While editing docs.json, also verify and correct the branding entries to the required values: support email "agent@recoupable.com", app URL "https://chat.recoupable.com", website "https://recoupable.com", and the social URLs for X, GitHub, and LinkedIn to match the branding spec.
🧹 Nitpick comments (2)
skills/trend-to-song.mdx (1)
2-2: ⚡ Quick winReplace the slug-style title with a readable page title.
trend-to-songwill surface as-is in the page header and search UI. A title likeTrend to Songis clearer for readers.As per coding guidelines,
**/*.mdx:Use clear, self-documenting titles and descriptions in documentation.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/trend-to-song.mdx` at line 2, The page frontmatter title is using a slug-style value "trend-to-song" which appears verbatim in the header and search UI; update the title in skills/trend-to-song.mdx frontmatter (the title field) to a readable, self-documenting string such as "Trend to Song" so the page header and search display a human-friendly title.skills/streaming-growth.mdx (1)
2-2: ⚡ Quick winUse a reader-facing title instead of the slug.
streaming-growthreads like an internal identifier in the page heading and search results. Prefer a human-facing title such asStreaming Growth.As per coding guidelines,
**/*.mdx:Use clear, self-documenting titles and descriptions in documentation.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/streaming-growth.mdx` at line 2, Replace the reader-unfriendly slug-style frontmatter title "streaming-growth" with a human-facing title (e.g., "Streaming Growth") in the file's frontmatter; update the title key value so the page heading and search index use the clear, self-documenting string instead of the slug.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@skills/music-industry-research.mdx`:
- Line 2: Update the frontmatter title value to a human-readable, title-cased
string: replace title: "music-industry-research" with a title-cased label such
as title: "Music Industry Research" so the H1/tab label is clear and
self-documenting (look for the frontmatter `title` key in this file).
In `@skills/recoup-api.mdx`:
- Line 2: Update the frontmatter title value "title: \"recoup-api\"" to a
human-readable, title-cased string (e.g., "Recoup API") so the page label is
clear and self-documenting; locate the frontmatter title line in the
skills/recoup-api.mdx file and replace the kebab-case value with the title-cased
version.
---
Duplicate comments:
In `@docs.json`:
- Around line 5-9: The primary color value in the colors block (property
"primary" inside the "colors" object) is incorrect; update the "primary" entry
from "#0a0a0a" back to the Recoup brand color "#345A5D" so that buttons, links
and other primary UI elements use the branded color specified in Recoup-Chat's
tailwind.config.ts.
- Around line 481-485: The primary CTA object ("primary" with label "Get API
Key") currently points to /keys; update its href to the canonical app URL
"https://chat.recoupable.com". While editing docs.json, also verify and correct
the branding entries to the required values: support email
"agent@recoupable.com", app URL "https://chat.recoupable.com", website
"https://recoupable.com", and the social URLs for X, GitHub, and LinkedIn to
match the branding spec.
---
Nitpick comments:
In `@skills/streaming-growth.mdx`:
- Line 2: Replace the reader-unfriendly slug-style frontmatter title
"streaming-growth" with a human-facing title (e.g., "Streaming Growth") in the
file's frontmatter; update the title key value so the page heading and search
index use the clear, self-documenting string instead of the slug.
In `@skills/trend-to-song.mdx`:
- Line 2: The page frontmatter title is using a slug-style value "trend-to-song"
which appears verbatim in the header and search UI; update the title in
skills/trend-to-song.mdx frontmatter (the title field) to a readable,
self-documenting string such as "Trend to Song" so the page header and search
display a human-friendly title.
🪄 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: 323b940b-40f0-4fe1-bd3e-2af5db621ad2
📒 Files selected for processing (14)
docs.jsonplugins.mdxplugins/music-catalog-diligence.mdxskills.mdxskills/artist-workspace.mdxskills/content-creation.mdxskills/getting-started.mdxskills/music-industry-research.mdxskills/recoup-api.mdxskills/release-management.mdxskills/setup-sandbox.mdxskills/song-writing.mdxskills/streaming-growth.mdxskills/trend-to-song.mdx
🚧 Files skipped from review as they are similar to previous changes (3)
- skills/setup-sandbox.mdx
- skills/song-writing.mdx
- skills/content-creation.mdx
| @@ -0,0 +1,30 @@ | |||
| --- | |||
| title: "music-industry-research" | |||
There was a problem hiding this comment.
Use a human-readable title in frontmatter.
title: "music-industry-research" should be title-cased for a clearer H1/tab label.
✏️ Suggested fix
-title: "music-industry-research"
+title: "Music Industry Research"As per coding guidelines, "Use clear, self-documenting titles and descriptions in documentation."
📝 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
| title: "music-industry-research" | |
| title: "Music Industry Research" |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/music-industry-research.mdx` at line 2, Update the frontmatter title
value to a human-readable, title-cased string: replace title:
"music-industry-research" with a title-cased label such as title: "Music
Industry Research" so the H1/tab label is clear and self-documenting (look for
the frontmatter `title` key in this file).
| @@ -0,0 +1,33 @@ | |||
| --- | |||
| title: "recoup-api" | |||
There was a problem hiding this comment.
Use a human-readable title in frontmatter.
title: "recoup-api" should be title-cased for clearer page labeling.
✏️ Suggested fix
-title: "recoup-api"
+title: "Recoup API"As per coding guidelines, "Use clear, self-documenting titles and descriptions in documentation."
📝 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
| title: "recoup-api" | |
| title: "Recoup API" |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/recoup-api.mdx` at line 2, Update the frontmatter title value "title:
\"recoup-api\"" to a human-readable, title-cased string (e.g., "Recoup API") so
the page label is clear and self-documenting; locate the frontmatter title line
in the skills/recoup-api.mdx file and replace the kebab-case value with the
title-cased version.
Per-plugin install table was missing the 'Create plugin' submenu step that the landing page already documents. Aligns the two surfaces so both describe the actual UI flow: Customize > Plugins > + > Create plugin > Add marketplace > paste URL > Sync. Co-authored-by: Cursor <cursoragent@cursor.com>
|
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 |
…scription A customer's agent reviewing prod docs hit null URLs trying to fetch "Instagram Comments" and "Instagram Profiles" — the description text on the apify scraper endpoint named them as if they were dedicated pages, but main #163 deleted those pages on Apr 28. Three lines in social.json mentioned them by name: 1. Endpoint description for /api/apify/runs/{runId}: now lists the actual surviving trigger endpoints (POST /api/social/scrape, POST /api/artist/socials-scrape) instead of legacy named endpoints. 2. runId parameter description: same fix. 3. Result-array description: clarified that the Apify "scraper type" (Instagram profile scraper, Instagram comments scraper, TikTok scraper) is what determines the response shape — these are upstream Apify scraper identifiers, not Recoup endpoint pages. Fixes the customer's friction point #1: "A few endpoint URLs returned null specifically the fans, social posts, and Instagram." The fans/ social/posts endpoints still exist (api-reference/fans/get, api-reference/posts/get) — only the description text was misleading. Co-authored-by: Cursor <cursoragent@cursor.com>
Customer-agent feedback called out "Credit costs were inconsistent — one endpoint mentioned '5 credits per request' inline, but I had no overall picture of the cost model. A credits reference table somewhere in the index would be useful when evaluating which calls are cheap to make frequently versus which should be cached." New page at /credits, placed in the Overview > Start here group right after Authentication so agents bootstrapping integration find it immediately. Researched all costs against the api/ source code (full findings + open questions in .local/plans/credit-check.md): - Most research GET endpoints: 5 credits per successful call - Research POST: web/people 5; extract 5×URLs; enrich 5/10/25 by processor; deep 25 - /api/image/generate: 15 credits (from $0.15 x402 price) - POST /api/chat (streaming): variable, min 1 credit, computed as max(1, round(usage_usd × 100)) - Everything else free at the API layer (content, tasks, etc.) Page also covers: - How to check balance (GET /api/credits/get) - Caching guidance (cheap vs expensive calls) - How balance changes (success-only deduction; new-account starting credits intentionally not asserted because the API/chat values conflict in code — page directs readers to /api/credits/get for truth instead) - Top-up flow (chat app billing — no API-only top-up yet) - FAQ covering failed-call deductions, content endpoint billing status, scheduled tasks, and the double-deduct edge case in resolveTrack Verified: page returns HTTP 200, brand fields preserved, nav reads cleanly. Open product questions logged in credit-check.md include the 25 vs 333 vs 1000 starting-credit conflict between API and chat constants — flagged but not surfaced publicly until product aligns. Co-authored-by: Cursor <cursoragent@cursor.com>
Customer-agent feedback: only one workflow-level guide existed (workflows/create-artist) and they wanted more. The right architectural move is to surface that guide as a skill rather than maintain a parallel "workflows" concept — skills are the canonical agent-readable playbook format. Companion commit on recoupable/skills/main (7993be6) created the new create-artist skill with the full 8-step API playbook: https://github.com/recoupable/skills/tree/main/skills/create-artist This commit completes the docs-side migration: - New skills/create-artist.mdx page following the standard skill- summary format (When to use it, What it produces, Endpoints it uses, Install, Source). Linked to the new skill repo URL. - Added skills/create-artist to the Skills tab > Setup group, alongside artist-workspace (they're complementary: artist-workspace handles workspace files, create-artist drives the 8-call API chain). - Deleted docs/workflows/create-artist.mdx (16,663 bytes, 324 lines). All substantive content was migrated to the create-artist SKILL.md in the skills repo. - Removed the empty Workflows nav group from the Artists tab. - Updated agents.mdx "Choose your path" decision tree: the two table rows that linked to /workflows/create-artist now link to /skills/create-artist (the new home). - Removed the empty workflows/ directory from the docs tree. Audit confirms 152 nav entries, 0 404s, 0 orphans on disk. The "Workflows" concept is now retired in the docs site. If we add more guided workflows in the future, they'll live as skills (matches the structure shipped earlier in this PR). Co-authored-by: Cursor <cursoragent@cursor.com>
Previous commit (56902ba) used `git add -A` and accidentally picked up two .md files from the local superpowers/ directory — those are agent workspace state, not docs content. This commit: - Removes the two files from git tracking (--cached, files stay on disk locally) - Adds .gitignore with `superpowers/` to prevent it happening again Files removed: - superpowers/plans/2026-04-28-content-api-artist-launch-video.md - superpowers/specs/2026-04-28-content-api-artist-launch-video-design.md Co-authored-by: Cursor <cursoragent@cursor.com>
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)
502-505:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFooter GitHub URL should use the canonical organization handle.
footer.socials.githubcurrently points tohttps://github.com/recoupable-com, but the canonical Recoupable organization ishttps://github.com/recoupable(matching the navbar link at line 475). Therecoupable-comhandle is stale and should be corrected.Suggested fix
"footer": { "socials": { "x": "https://x.com/recoupai", - "github": "https://github.com/recoupable-com", + "github": "https://github.com/recoupable", "linkedin": "https://www.linkedin.com/company/recoupable" } },🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs.json` around lines 502 - 505, Update the footer social link so it uses the canonical GitHub organization handle: change the value of the footer.socials.github entry (the JSON property "github" inside the footer/socials object in docs.json) from "https://github.com/recoupable-com" to "https://github.com/recoupable" to match the navbar GitHub URL.
♻️ Duplicate comments (2)
docs.json (2)
482-486:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winPrimary CTA href and label inconsistent with PR direction.
The branding guideline pins the canonical app URL to
https://chat.recoupable.com, and the AI summary for this PR notes the primary button label was supposed to change to "Dashboard". The current state still has"Get API Key"pointing atchat.recoupable.com/keys, which contradicts both. Decide which is intended and align label + href.As per coding guidelines,
docs.json: "Reference correct branding values: support email agent@recoupable.com, app URL https://chat.recoupable.com, website https://recoupable.com, and social URLs (X, GitHub, LinkedIn)".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs.json` around lines 482 - 486, The primary CTA in docs.json uses an outdated label and href; update the "primary" object's "label" to "Dashboard" and change its "href" to the canonical app URL "https://chat.recoupable.com" so the label and link are consistent with the PR direction and branding; while here, verify other branding values in docs.json (support email agent@recoupable.com, website https://recoupable.com and social URLs) remain correct.
5-9:⚠️ Potential issue | 🟠 Major | ⚡ Quick winPrimary color still off-brand.
#0a0a0adoesn't match the Recoup brand primary, which the coding guideline pins to#345A5D. This was raised previously and the value is still#0a0a0ain the current state.Suggested fix
"colors": { - "primary": "#0a0a0a", + "primary": "#345A5D", "light": "#ededed", "dark": "#0a0a0a" },As per coding guidelines,
docs.json: "Use primary color#345A5Dfrom Recoup-Chat tailwind.config.ts for branding consistency".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs.json` around lines 5 - 9, Update the primary color value in docs.json so the "colors" -> "primary" entry uses the Recoup brand hex; locate the "primary" key in the "colors" object and replace "#0a0a0a" with "#345A5D" to match Recoup-Chat's tailwind.config.ts branding, ensuring the file now reflects the mandated primary color.
🧹 Nitpick comments (3)
credits.mdx (2)
6-8: 💤 Low valueSource-of-truth phrasing risks staleness.
"as of the latest deploy" makes this page authoritative without a refresh mechanism. If the credits source changes (e.g., processor tiers shift in
/api/research/enrich, chat formula changes, content endpoints become billed), this page silently lies. Consider either (a) linking to the source-of-truth file/repo for cost constants, or (b) adding a "Last verified: " line so consumers know the cadence.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@credits.mdx` around lines 6 - 8, The wording "as of the latest deploy" is risky because it implies the page is authoritative without a refresh mechanism; update credits.mdx to either link to the canonical source-of-truth (the repo/file that holds the credit constants or the API endpoints like /api/research/enrich and billing logic) or add a visible "Last verified: <date>" line and a short note about verification cadence so readers know freshness; locate and edit the paragraph that currently contains "as of the latest deploy" and replace it with the chosen approach (link to source-of-truth file/repo or a Last verified date and verification instructions).
100-114: ⚡ Quick winAdd an OpenAPI-backed reference for
/api/credits/get.This is the only documented credits endpoint and it's defined inline here rather than in
api-reference/openapi/*.json. That's fine for narrative docs, but agents/users navigating from the API Reference tab won't find it. Consider adding it to the appropriate OpenAPI spec so it appears in the sidebar like the other endpoints, then linking from this page.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@credits.mdx` around lines 100 - 114, The /api/credits/get endpoint is only documented inline in credits.mdx and must be added to the OpenAPI spec so it appears in the API Reference; add an operation object for path "/api/credits/get" in the appropriate OpenAPI JSON under api-reference/openapi (include method GET, security requirements for x-api-key/Authorization, request/response content types, and a response schema with properties remaining_credits (integer) and account_id (string)), then update credits.mdx to reference or link to that OpenAPI operation (or include an x-ref) so the endpoint appears in the sidebar like other endpoints.docs.json (1)
175-178: 💤 Low valueRemove the empty Instagram nav group.
A navigation group with no pages serves no purpose in the sidebar. Either drop the
"hidden": trueinstead.Suggested fix
- }, - { - "group": "Instagram", - "pages": [] - }, { "group": "Social Scraping",🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs.json` around lines 175 - 178, Remove the empty navigation group entry that has "group": "Instagram" with an empty "pages" array from the docs.json; either delete that entire object or, if you want to keep a placeholder, add "hidden": true to the same object so it doesn't appear in the sidebar (look for the object containing "group": "Instagram" and "pages": [] to locate it).
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@credits.mdx`:
- Line 140: Remove or replace the sentence that references the non-existent GET
/api/subscription/status endpoint and the isPro field in credits.mdx; either
delete that line or update it to reference the actual subscriptions flow (e.g.,
mention POST /api/subscriptions/sessions for creating a checkout session) or
point to the real status-check mechanism if one exists, ensuring you remove the
`isPro` claim and any endpoint that isn't present in the codebase.
---
Outside diff comments:
In `@docs.json`:
- Around line 502-505: Update the footer social link so it uses the canonical
GitHub organization handle: change the value of the footer.socials.github entry
(the JSON property "github" inside the footer/socials object in docs.json) from
"https://github.com/recoupable-com" to "https://github.com/recoupable" to match
the navbar GitHub URL.
---
Duplicate comments:
In `@docs.json`:
- Around line 482-486: The primary CTA in docs.json uses an outdated label and
href; update the "primary" object's "label" to "Dashboard" and change its "href"
to the canonical app URL "https://chat.recoupable.com" so the label and link are
consistent with the PR direction and branding; while here, verify other branding
values in docs.json (support email agent@recoupable.com, website
https://recoupable.com and social URLs) remain correct.
- Around line 5-9: Update the primary color value in docs.json so the "colors"
-> "primary" entry uses the Recoup brand hex; locate the "primary" key in the
"colors" object and replace "#0a0a0a" with "#345A5D" to match Recoup-Chat's
tailwind.config.ts branding, ensuring the file now reflects the mandated primary
color.
---
Nitpick comments:
In `@credits.mdx`:
- Around line 6-8: The wording "as of the latest deploy" is risky because it
implies the page is authoritative without a refresh mechanism; update
credits.mdx to either link to the canonical source-of-truth (the repo/file that
holds the credit constants or the API endpoints like /api/research/enrich and
billing logic) or add a visible "Last verified: <date>" line and a short note
about verification cadence so readers know freshness; locate and edit the
paragraph that currently contains "as of the latest deploy" and replace it with
the chosen approach (link to source-of-truth file/repo or a Last verified date
and verification instructions).
- Around line 100-114: The /api/credits/get endpoint is only documented inline
in credits.mdx and must be added to the OpenAPI spec so it appears in the API
Reference; add an operation object for path "/api/credits/get" in the
appropriate OpenAPI JSON under api-reference/openapi (include method GET,
security requirements for x-api-key/Authorization, request/response content
types, and a response schema with properties remaining_credits (integer) and
account_id (string)), then update credits.mdx to reference or link to that
OpenAPI operation (or include an x-ref) so the endpoint appears in the sidebar
like other endpoints.
In `@docs.json`:
- Around line 175-178: Remove the empty navigation group entry that has "group":
"Instagram" with an empty "pages" array from the docs.json; either delete that
entire object or, if you want to keep a placeholder, add "hidden": true to the
same object so it doesn't appear in the sidebar (look for the object containing
"group": "Instagram" and "pages": [] to locate it).
🪄 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: 60242eff-994e-4024-9f7f-148578de639b
📒 Files selected for processing (4)
api-reference/openapi/social.jsoncredits.mdxdocs.jsonplugins/music-catalog-diligence.mdx
…umbers The previous version (237b621) listed exact credit costs per endpoint (5 for research, 15 for image, etc.) which couples the docs to current pricing logic in code. Per product call, we don't want to commit to maintaining that table while the credits system has known inconsistencies (signup amount differs between API and chat code paths; new content endpoints are not yet wired into deduction). The slim version keeps the page in nav and addresses the customer's "no overall picture of the cost model" friction point in a way that won't drift: - Categorical "what's billed" table: research family billed, content generation billed, streaming chat billed, everything else free at the API layer - "Treat /api/credits/get as the source of truth for both balance AND cost" — directs agents to call it before/after a request and use the delta as the actual deduction. Future-proof against pricing changes in code. - How to top up (chat dashboard subscription via Stripe) - Three FAQ items: how to know a specific cost (call /api/credits/get bracketed), scheduled tasks billing model, double-deduct edge case 156 lines -> 66 lines. Page still answers the customer's question ("which calls are cheap to make frequently versus which should be cached") at the family level — research and content are the two categories to cache; everything else is free. Co-authored-by: Cursor <cursoragent@cursor.com>
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)
462-500:⚠️ Potential issue | 🟠 Major | ⚡ Quick winFix broken GitHub social link in footer.
The footer social link on line 498 points to
https://github.com/recoupable-com, which does not exist (returns 404). The navbar link on line 470 correctly referenceshttps://github.com/recoupable, which is the canonical organization (confirmed by the repository remote origingithub.com/recoupable/docs.gitand all other codebase references). Update the footer social link to use the canonical org:Diff
"x": "https://x.com/recoupai", - "github": "https://github.com/recoupable-com", + "github": "https://github.com/recoupable", "linkedin": "https://www.linkedin.com/company/recoupable"🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs.json` around lines 462 - 500, The footer socials object contains an incorrect GitHub URL; update the "github" value inside the JSON "footer" -> "socials" object (the "github" key) from "https://github.com/recoupable-com" to the canonical "https://github.com/recoupable" so it matches the navbar GitHub link and the org used across the repo.
♻️ Duplicate comments (4)
docs.json (3)
477-481:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winPrimary CTA href still points to
/keysinstead of the canonical app URL.Coding guidelines specify
https://chat.recoupable.comas the canonical app URL for branding references. The CTA target should align with that unless a deep-link to/keysis intentional and documented elsewhere (in which case keeping the label "Get API Key" is fine, but you should verify/keysis a stable, public route on chat.recoupable.com).Suggested fix
"primary": { "type": "button", "label": "Get API Key", - "href": "https://chat.recoupable.com/keys" + "href": "https://chat.recoupable.com" }As per coding guidelines,
docs.json: "Reference correct branding values: support email agent@recoupable.com, app URL https://chat.recoupable.com, website https://recoupable.com, and social URLs (X, GitHub, LinkedIn)".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs.json` around lines 477 - 481, The CTA in the "primary" object currently uses a deep-link href "/keys" which doesn't match the canonical app URL; update the "primary" object's href from "https://chat.recoupable.com/keys" to the canonical app URL "https://chat.recoupable.com" (or, if a deep-link is intentional, confirm /keys is a stable public route and document that decision), referencing the "primary" object and its "label": "Get API Key" to locate the change.
5-9:⚠️ Potential issue | 🟠 Major | ⚡ Quick winPrimary brand color still off-brand.
Per coding guidelines,
colors.primarymust be#345A5Dfor branding consistency with Recoup-Chat. Current value#0a0a0a(anddark:#0a0a0a``) leaves all primary UI affordances rendering as near-black instead of the brand teal.Suggested fix
"colors": { - "primary": "#0a0a0a", + "primary": "#345A5D", "light": "#ededed", - "dark": "#0a0a0a" + "dark": "#345A5D" },As per coding guidelines,
docs.json: "Use primary color#345A5Dfrom Recoup-Chat tailwind.config.ts for branding consistency".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs.json` around lines 5 - 9, Update docs.json to use the Recoup-Chat brand teal: change colors.primary to `#345A5D` and replace the near-black colors.dark value with a brand-consistent darker teal (or the exact darker shade used in tailwind.config.ts) so UI affordances render in the correct brand colors; modify the colors.primary and colors.dark entries accordingly.
175-178:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winDrop the empty Instagram group — it renders as a dead sidebar entry.
This group has
"pages": [], which produces an empty section header in the Research tab with no destinations. Per the PR's audit ("0 nav entries that 404; 0 orphan pages"), an empty group is still user-facing noise; remove the entry until Instagram pages exist.Suggested fix
- { - "group": "Instagram", - "pages": [] - }, { "group": "Social Scraping",🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs.json` around lines 175 - 178, Remove the empty "Instagram" group object (the entry with "group": "Instagram" and "pages": []) from docs.json so it no longer renders an empty Research sidebar section; if you plan to add Instagram pages later, reintroduce the group only when "pages" contains at least one page entry.credits.mdx (1)
53-53:⚠️ Potential issue | 🟠 Major | ⚡ Quick winReference to
GET /api/subscription/statusandisProis still unbacked by any spec.This was already flagged on the previous revision — no
subscription/statusendpoint and noisProfield exist in the OpenAPI specs (the only documented subscription surface isPOST /api/subscriptions/sessions). Either remove the sentence or replace it with the actual mechanism (e.g., point to the Subscriptions sessions flow, or/api/credits/getfor limit-relevant signal).Suggested fix
-Subscription status is reflected via `GET /api/subscription/status` — if `isPro` is `true`, the account is on the paid tier with higher monthly limits. +After checkout completes, the subscription is tied to the same account your API key authenticates against; current balance and usage are visible via `GET /api/credits/get`.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@credits.mdx` at line 53, The sentence referencing GET /api/subscription/status and the isPro field is incorrect because those API surfaces don't exist in the spec; update credits.mdx to either remove that sentence or replace it with the real mechanism — for example point readers to POST /api/subscriptions/sessions for the subscriptions flow or to /api/credits/get for limit-relevant signals, and ensure you remove any mention of the nonexistent isPro field.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@credits.mdx`:
- Around line 27-30: The curl example in the "Check your balance" snippet uses
the wrong hostname; update the request URL in credits.mdx to use the canonical
API base (https://recoup-api.vercel.app) instead of https://api.recoupable.com
so it matches agents.mdx and index.mdx; ensure the example remains otherwise
unchanged (keep the -H "x-api-key: $RECOUP_API_KEY" header and the same endpoint
path /api/credits/get).
---
Outside diff comments:
In `@docs.json`:
- Around line 462-500: The footer socials object contains an incorrect GitHub
URL; update the "github" value inside the JSON "footer" -> "socials" object (the
"github" key) from "https://github.com/recoupable-com" to the canonical
"https://github.com/recoupable" so it matches the navbar GitHub link and the org
used across the repo.
---
Duplicate comments:
In `@credits.mdx`:
- Line 53: The sentence referencing GET /api/subscription/status and the isPro
field is incorrect because those API surfaces don't exist in the spec; update
credits.mdx to either remove that sentence or replace it with the real mechanism
— for example point readers to POST /api/subscriptions/sessions for the
subscriptions flow or to /api/credits/get for limit-relevant signals, and ensure
you remove any mention of the nonexistent isPro field.
In `@docs.json`:
- Around line 477-481: The CTA in the "primary" object currently uses a
deep-link href "/keys" which doesn't match the canonical app URL; update the
"primary" object's href from "https://chat.recoupable.com/keys" to the canonical
app URL "https://chat.recoupable.com" (or, if a deep-link is intentional,
confirm /keys is a stable public route and document that decision), referencing
the "primary" object and its "label": "Get API Key" to locate the change.
- Around line 5-9: Update docs.json to use the Recoup-Chat brand teal: change
colors.primary to `#345A5D` and replace the near-black colors.dark value with a
brand-consistent darker teal (or the exact darker shade used in
tailwind.config.ts) so UI affordances render in the correct brand colors; modify
the colors.primary and colors.dark entries accordingly.
- Around line 175-178: Remove the empty "Instagram" group object (the entry with
"group": "Instagram" and "pages": []) from docs.json so it no longer renders an
empty Research sidebar section; if you plan to add Instagram pages later,
reintroduce the group only when "pages" contains at least one page 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: 94022814-4501-4c80-b2bc-906c63585a50
📒 Files selected for processing (6)
.gitignoreagents.mdxcredits.mdxdocs.jsonskills/create-artist.mdxworkflows/create-artist.mdx
💤 Files with no reviewable changes (1)
- workflows/create-artist.mdx
✅ Files skipped from review due to trivial changes (1)
- .gitignore
…-ups coming soon Two changes after reviewing the rendered page in production: 1. Cut redundancy. The "call /api/credits/get before and after" message appeared four times across the page (lead, Check your balance, FAQ #1). Now lives once, in the lead. Removed: - FAQ #1 ("How do I know what a specific call costs?") — fully redundant with the lead. - FAQ #3 ("Why might one logical action deduct twice?") — surfaces an internal `resolveTrack` quirk that customers shouldn't need to know about, and would become wrong if we ever fix it. - "(artist management, sandboxes, sessions, ...)" parenthetical in the lead — the table's "Everything else" row already covers it. - "Call this before any sequence... bail out cleanly" filler in Check your balance. 2. Replace "Top up" with "Subscription". Old name implied one-time purchases work today, which they don't — only subscription via Stripe is implemented. New section: - Two-tier table (Free / Pro), both refill monthly - Concrete upgrade flow: chat.recoupable.com > Billing > Subscribe, including the 30-day trial detail - GET /api/subscription/status command to check current tier - Explicit "One-time top-ups: Coming soon" callout so anyone looking for a per-request top-up path understands the timeline Specific monthly credit numbers (e.g. "333 free / 1000 pro") are intentionally not stated. Production has a separate signup-vs-monthly inconsistency in code that would make those numbers misleading on day one for a new free account. The page directs readers to their actual balance via /api/credits/get instead. 66 lines -> 76 lines on disk, but with notably more substance per line and zero repetition. Co-authored-by: Cursor <cursoragent@cursor.com>
The homepage subheader and lead paragraph framed Recoup narrowly as "infrastructure for record labels." That misses the actual customer range — distributors, catalog companies, management firms, and independent artists all use Recoup, and they self-select away when the landing page sounds label-only. Changes: - Description: "Infrastructure for agents to run record labels" --> "Infrastructure for agents to operate the music business" - Lead paragraph: rewrite to enumerate the five real audiences in the "whether you're..." clause (indie artist, label, distributor, catalog company, management firm) and replace the closing "perform the work of a major label" with the more universal "do the work that used to take an entire team" Kept the H1 "What is Recoup?" — the question framing supports an expansive answer naturally, and the title doubles as the sidebar label so it has to stay short. Co-authored-by: Cursor <cursoragent@cursor.com>
Previous paragraph had two issues: 1. Two back-to-back lists (work types + audience types) made it feel listy. Now there's one list (work types), and the audience identification is a tight "whether you're..." preamble. 2. The closing claim — "captures context... so agents can do the work" — undersold what Recoup actually ships. Recoup is two layers: structured context AND the domain expertise + workflows that music professionals actually use day-to-day. The new paragraph names both with "not just the context (your catalog, artists, releases, fans), but the domain expertise and workflows that operate it day-to-day." Also reframes Recoup as "the agent harness for the music business, built by people who've done it" — a credibility-anchored positioning line that earns the claim instead of stating it abstractly. Co-authored-by: Cursor <cursoragent@cursor.com>
Said it wrong. Claiming the work is "the same" across an indie artist
and a major distributor reads as condescending — those businesses
operate at radically different scales and the work isn't the same,
even if some categories overlap.
Reframe: describe what each audience is doing ("you're juggling
research, content, marketing...") without claiming they're all doing
the same thing. The juggle metaphor names the volume problem
without flattening the differences.
Co-authored-by: Cursor <cursoragent@cursor.com>
Core concepts (Account / Organization / Artist) was the first H2 on the homepage, sitting between the lead paragraph and "Get started." That's a textbook interruption — readers landing on the page want "what is this -> how do I try it -> what can it do," not "here are our entity primitives" first. The natural home is /authentication. That page already references all three IDs (account_id, organization_id, artist_account_id) under "Access control" but doesn't define what the entities actually are first — readers had to guess. Changes: - index.mdx: remove ## Core concepts and its table. Homepage now flows lead -> Get started -> Three interfaces -> What's in the API -> ... with no textbook-y interruption. - authentication.mdx: add ## Concepts (with the same table) right before "Create a key" — readers see the entity types BEFORE learning to authenticate against them. Reading order: entities -> get a key -> use a key -> scope across organizations -> access control rules. - Same change broadens the Organization definition from "A label or team that groups multiple accounts" to "A label, distributor, catalog company, management firm, or team that groups multiple accounts" — matches the audience framing on the new homepage lead. Co-authored-by: Cursor <cursoragent@cursor.com>
The Base URL on the homepage still showed https://recoup-api.vercel.app/api after main #180 ("default base URL to api.recoupable.com") had already standardized the canonical hostname. Most pages on the docs branch had been updated during the PR #189 merge, but several stragglers still pointed at the Vercel preview URL. Replaced 27 occurrences across 8 files: index.mdx (3x) — Base URL section, AI agent Info callout, "For AI agents" footer authentication.mdx (2x) — Use a key + Bearer tokens curl examples agents.mdx (8x) — Choose-your-path curls (signup, verify, list artists, list orgs, list sandboxes, file read, file upload, Base URL footer) quickstart.mdx (9x) — Every numbered curl example content-agent.mdx (1x) — endpoint reference skills/recoup-api.mdx (1x) — when-to-use trigger phrase api-reference/openapi/ai.json (1x) — server URL api-reference/openapi/content.json (2x) — server URLs Validated: both touched OpenAPI specs still parse as valid JSON. All 6 affected pages return HTTP 200. Note: the recoup-api SKILL.md in recoupable/skills still references the Vercel hostname. That's a parallel source-of-truth and per the no-other-repo-changes constraint, not updated here. Worth a follow-up PR on the skills repo to keep them aligned. Co-authored-by: Cursor <cursoragent@cursor.com>
Verified across five independent tests today (OpenAPI param check,
control vs known-fake endpoint, comparison vs known-working endpoints,
wide source grep, multi-domain probe) that GET /api/comments has no
handler in the API source code. Both api.recoupable.com and
recoup-api.vercel.app return 404 — same response shape as a known-
fake endpoint, distinct from real protected endpoints which return
401 unauthenticated.
The page has been live on production docs (developers.recoupable.com/
api-reference/comments/get currently returns HTTP 200), advertising
an endpoint that doesn't exist. Plausibly one of the "URLs returned
null" friction points sweetman's agent reported in the customer
review last night — the agent saw "Get Comments" in the sidebar,
derived the URL pattern, hit it, got nothing back.
Three-location cleanup, all docs-only:
- api-reference/openapi/social.json: removed the /api/comments path
entry from the spec
- api-reference/comments/get.mdx: deleted (was 5-line frontmatter-only
stub auto-generating from the now-removed spec entry)
- docs.json: removed "api-reference/comments/get" from the Artists
tab > Fans & Posts group
Sibling group entries Get Artist Fans (GET /api/artists/{id}/fans)
and Get Artist Posts (GET /api/artists/{id}/posts) verified working
and remain in the nav.
Audit: 151 nav entries, 0 404s, social.json + docs.json both
re-validated as parseable JSON, /api-reference/comments/get correctly
404s on dev (was 200 before).
Spotted by a rendered-page review. Two pages had outdated or misleading content that needed correction: index.mdx: - "any of the 40+ endpoints" -> "130+ endpoints" (actual: 137 across all 7 OpenAPI specs) - "running a label" -> "running a music business" (matches the homepage lead paragraph that was already broadened) - Artists card: removed "and comments" — that endpoint was deleted in f896bc7 because it has no API handler. Card now reads "browse fans and posts" - Artists / Catalog cards: "your label" -> "your roster" (consistent with broader audience framing) - Content card: "7 endpoints" -> "11 endpoints" (7 primitives + create, estimate, validate, templates) - Quickstart bullet vs Quickstart Guides card: now both say "Under a minute" (was inconsistent — one said "~5 minutes") - For AI agents OpenAPI table: added rows for ai.json (added by main #177) and sessions.json (added by main #185-187). Was missing 2 of 7 specs. mcp.mdx: - Reframe the "Org-scoped keys can target any account... Personal API keys can only operate on their own data" callout. The phrasing implied two key types exist, which is wrong — there's only one key type, and access is determined by the OWNER ACCOUNT's organization membership. New phrasing matches /authentication's access rules and explicitly says there's no separate "org-scoped" key type. Links out to /authentication#access-control for the full ladder.
Numbers in cards just become things to maintain (and get wrong). Several were already off when caught — "40+ endpoints" was actually 137; "7 endpoints" was actually 11. The number was never the information a reader needed; what each section DOES is. index.mdx: - REST API card: "any of the 130+ endpoints" -> "any of them" - Chat card: dropped "11 endpoints" - Research card: dropped "31 endpoints" - Content card: dropped "11 endpoints — 7 creative primitives plus full-pipeline..." structure; rewrote as a fluid description of what's available mcp.mdx: - Frontmatter description: "40+ Recoup tools" -> "the full Recoup tool catalog" - Tool catalog intro: "exposes 40+ tools organized by domain" -> "Tools are organized by domain" Net: descriptions lead with capability, not arithmetic.
…search Followup to ff66c3b. Sweep caught more endpoint-count claims in quickstart.mdx and skills/music-industry-research.mdx that weren't in the previous round. quickstart.mdx (4 places): - "The research API has 30+ endpoints" -> dropped - "all 40+ endpoints" -> "the full Recoup tool catalog" - Research card: "30+ endpoints — metrics across..." -> "Metrics across..." - Content card: "7 endpoints for images, videos..." -> "Images, videos..." skills/music-industry-research.mdx (1 place): - "All of [Research] (31 endpoints)" -> "All of [Research]" Final sweep returns zero remaining count claims across all .mdx files.
Two cuts: 1. The "Treat GET /api/credits/get as the source of truth..." paragraph was over-explaining. The "Check your balance" section already shows the curl — readers don't need a meta-paragraph telling them to "treat" something as the source of truth. They'll just use it. The sentence about hard-coded numbers drifting was author-side editorial that doesn't help the reader. 2. The "Common questions" section only had one entry (scheduled tasks billing) — and that's not actually a common question. Cut it. Page is now 76 lines -> 65 lines, one fewer section header, no redundant lead-in. Reader path is: what's billed -> check your balance -> subscription. Done.
Earlier in this PR (56902ba) we deleted docs/workflows/create-artist.mdx and converted the content into a sibling skill at /skills/create-artist. That worked architecturally — but the recoup-api SKILL.md in recoupable/skills (already shipped, in production) hard-codes the URL https://developers.recoupable.com/workflows/create-artist as the canonical "fetch this for the full curl-by-curl playbook" reference when an agent is creating a new artist. When this PR lands, that link 404s, breaking every agent that loads the recoup-api skill. Per the no-other-repo-changes constraint we set this morning, the right fix is to restore the docs page rather than update the skill. Restored docs/workflows/create-artist.mdx verbatim from origin/main (319 lines — the canonical 8-step curl playbook with throwaway-account warning, RECOUP.md scaffold, resume pattern, and platform key reference). Added a "Workflows" group at the top of the Artists tab in docs.json so the page is also discoverable from the sidebar. Both pages now coexist by design: - /workflows/create-artist — full curl playbook (the URL the recoup-api skill points at; backward-compat surface for agents) - /skills/create-artist — skill-summary page in the Skills tab (discovery surface for users browsing the Skills system; links to the recoupable/skills repo for the playbook source) When/if recoup-api SKILL.md gets updated in the skills repo to point at /skills/create-artist instead, this workflow page can be revisited.
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
1 participant
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
Combines the six related April 27 docs PRs into a single coordinated landing, with several rounds of cleanup and customer-driven fixes layered on top:
recoup-api, droppedchart-metric, documented thenpx skillsinstall pathmusic-catalog-diligence— Cowork install path verified end-to-end/api/commentsendpoint live on prod, base URL standardizationSource PR consolidation
feat/docs-brandfeat/docs-mcpfeat/docs-content-cleanupfeat/docs-onboardingfeat/docs-skillsfeat/docs-navSkills tab
Collapsed to two groups (down from 5 — two were singletons that read as visual bugs):
recoup-api,getting-started,setup-sandbox,artist-workspace,create-artistmusic-industry-research,song-writing,content-creation,release-management,streaming-growth,trend-to-songEvery skill page now has a per-skill
npx skills add recoupable/skills --skill <name>install command. The Skills landing leads with the universal CLI install path (works with Claude Code, Codex, OpenCode, Cursor, 50+ agents) — strictly better than the Claude-Code-only/plugin marketplace addwe previously led with.create-artistis new in this PR — converted fromworkflows/create-artist.mdx(deleted) into a proper skill. The "Workflows" concept is retired in this PR; if we add more guided procedures, they live as skills (matches the structure shipped earlier in this PR).chart-metricremoved entirely — both nav entry and MDX file deleted.Plugins tab (new)
New top-level tab placed right after Skills:
/plugins— landing covering what plugins are vs skills, install paths for Claude Code, Cowork, Codex, and Cursor/plugins/music-catalog-diligence— comprehensive page with deal workspace structure, 9 skills, 6 commands, QC philosophyCowork install path verified end-to-end by pasting
https://github.com/recoupable/pluginsintoCustomize → Plugins → + → Create plugin → Add marketplace → Sync.Required a parallel fix on
recoupable/plugins(already pushed) to switch the marketplace.json source from a relative submodule path to agithubsource object — the relative path failed because Cowork doesn't recurse submodules during sync. Same fix applied to the Codex marketplace file with itsurl-source schema.Credits reference page (new)
/creditsplaced inOverview > Start heregroup right after Authentication. Covers:GET /api/credits/getcurl + response shape)GET /api/subscription/statusfor tier checkSpecific per-endpoint credit numbers intentionally not asserted — the page directs readers to
/api/credits/getas the source of truth for both balance and per-call cost. Robust to the engineering inconsistencies we discovered (signup credit value disagrees between API code and chat code; new content endpoints aren't yet wired into the deduction system). Full research findings in.local/plans/credit-check.mdin the mono repo (not part of this PR).Customer feedback fixes
Addresses 3 of 4 friction points raised in the customer review last night:
dde5524,f896bc7,318a555237b621→908dd1d→17bf22a56902baf896bc7removed the non-existentGET /api/commentsendpoint that's currently live on production docs. Verified across five independent tests:artist_account_idparamroute.tsfiles inapi/app/api/mention "comments"api.recoupable.comandrecoup-api.vercel.appThe OpenAPI spec has been advertising a 74-line endpoint definition for a route that was never built (or has been removed). Plausibly one of the "URLs returned null" friction points the customer's agent reported.
dde5524cleaned up thesocial.jsondescription text on/api/apify/runs/{runId}that referenced the deleted Instagram Comments and Instagram Profiles endpoints by name — agents derived those URLs from the description and got 404s.Homepage positioning broadened
description: "Infrastructure for agents to run record labels"→description: "Infrastructure for agents to operate the music business".Lead paragraph now names the 5 audience types (indie artist, label, distributor, catalog company, management firm) and adds the workflows layer ("not just the context — your catalog, artists, releases, fans — but the domain expertise and workflows that operate it day-to-day, built by people who've done it").
Core concepts table moved off the homepage to
/authentication— the natural home since the page already referencesaccount_id/organization_id/artist_account_idunder Access Control. The Organization definition was also broadened to match (label / distributor / catalog company / management firm / team that groups multiple accounts).Base URL standardization
Replaced 27 occurrences of
recoup-api.vercel.appwithapi.recoupable.comacross 8 files (index.mdx3x,agents.mdx8x,quickstart.mdx9x,authentication.mdx2x,content-agent.mdx1x,skills/recoup-api.mdx1x, plus 2 OpenAPI specs). Aligns the branch with main #180.Final audit
Companion-repo commits (already pushed, not part of this PR)
recoupable/skills7993be6— addedskills/create-artist/SKILL.md, updatedartist-workspace/SKILL.mdto deferrecoupable/pluginsf048522— fixed.claude-plugin/marketplace.jsonsource (Cowork sync)recoupable/plugins062bce6— fixed.agents/plugins/marketplace.json(Codex), rewrote READMEOpen items for follow-up PRs
recoupable/skills/skills/recoup-api/SKILL.mdwith theapi.recoupable.combase URL change (still referencesrecoup-api.vercel.app)POST /api/chat/generatedoesn't deduct credits in the source code — bug or intentional, needs product callOriginal source PRs
All six (#168, #170-174) left open — they serve as the per-scope review surface, and humans can close them once this lands.