docs: full overhaul — positioning, developer experience, and navigation#86
Open
sidneyswift wants to merge 13 commits intomainfrom
Open
docs: full overhaul — positioning, developer experience, and navigation#86sidneyswift wants to merge 13 commits intomainfrom
sidneyswift wants to merge 13 commits intomainfrom
Conversation
Rewrites all core pages to properly communicate what Recoup is (autonomous music infrastructure) and how to use it (API, MCP, CLI). Adds how-it-works concept page, authentication guide, and restructured navigation. Inspired by Composio docs quality bar. Voice follows brand guidelines. Made-with: Cursor
📝 WalkthroughWalkthroughThis PR rewrites and reorganizes site documentation: replaces the API intro with an API Reference landing, streamlines authentication and CLI docs, expands MCP and how-it-works architecture pages, updates quickstart and index content, and adjusts navigation in Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Made-with: Cursor
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
quickstart.mdx (1)
8-13: Deduplicate repeated auth and MCP config content.The API-key warning and MCP config blocks are duplicated across Quickstart, Authentication, and MCP pages. Consider extracting these into shared snippets to keep updates in one place.
As per coding guidelines, follow DRY across docs pages and use snippets instead of duplicating content.
Also applies to: 74-98
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@quickstart.mdx` around lines 8 - 13, Extract the duplicated API key and MCP configuration blocks (the "Go to the [API Keys page]..." step and the "<Warning>Store your API key securely..." admonition plus the MCP config block repeated across Quickstart, Authentication, and MCP pages) into a single shared snippet file and replace the copies with an include/import of that snippet; update references in the Quickstart, Authentication, and MCP docs to reference the shared snippet name so future edits happen in one place and remove the duplicate blocks from those pages.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@api-reference/introduction.mdx`:
- Around line 1-4: The api-reference/introduction.mdx file contains narrative
MDX content but should be frontmatter-only and include an openapi entry; remove
all body/narrative content from that file and either move it into a new
guide/snippet page (e.g., a non-api-reference MDX guide) or into a separate docs
component, then replace api-reference/introduction.mdx with only YAML
frontmatter including title, description and an openapi field (e.g., openapi:
'METHOD /path') so the file is OpenAPI-driven; ensure any links/refs updated
where you moved the narrative content.
---
Nitpick comments:
In `@quickstart.mdx`:
- Around line 8-13: Extract the duplicated API key and MCP configuration blocks
(the "Go to the [API Keys page]..." step and the "<Warning>Store your API key
securely..." admonition plus the MCP config block repeated across Quickstart,
Authentication, and MCP pages) into a single shared snippet file and replace the
copies with an include/import of that snippet; update references in the
Quickstart, Authentication, and MCP docs to reference the shared snippet name so
future edits happen in one place and remove the duplicate blocks from those
pages.
🪄 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: 6100f9d5-f992-4df9-a6f7-70f4655e08af
📒 Files selected for processing (8)
api-reference/introduction.mdxauthentication.mdxcli.mdxdocs.jsonhow-it-works.mdxindex.mdxmcp.mdxquickstart.mdx
Comment on lines
1
to
4
| --- | ||
| title: 'Introduction' | ||
| description: 'API documentation for the Recoup platform - AI agents for the music industry' | ||
| title: 'API Reference' | ||
| description: 'Programmatic access to the Recoup platform — agents, artists, content, analytics, and tasks.' | ||
| --- |
There was a problem hiding this comment.
api-reference/introduction.mdx should be frontmatter-only, not a custom docs page.
This page currently mixes narrative sections/components inside api-reference/**, and it’s missing an openapi frontmatter entry. Please move narrative content to a non-API-reference guide page (or snippet-driven guide) and keep this file OpenAPI-driven only.
As per coding guidelines, API reference MDX pages should be frontmatter-only and include OpenAPI spec reference in frontmatter (openapi: 'METHOD /path').
Also applies to: 6-108
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@api-reference/introduction.mdx` around lines 1 - 4, The
api-reference/introduction.mdx file contains narrative MDX content but should be
frontmatter-only and include an openapi entry; remove all body/narrative content
from that file and either move it into a new guide/snippet page (e.g., a
non-api-reference MDX guide) or into a separate docs component, then replace
api-reference/introduction.mdx with only YAML frontmatter including title,
description and an openapi field (e.g., openapi: 'METHOD /path') so the file is
OpenAPI-driven; ensure any links/refs updated where you moved the narrative
content.
Inspired by Claude Code, Exa, and Trigger.dev docs. Uses Mintlify Tabs for integration methods (MCP/API/CLI/Slack), AccordionGroup for capabilities, and a routing table for different user types. Made-with: Cursor
Uses real founder language: "AI infrastructure for the music industry", "general purpose agents can't do what we do because they don't know the artist", context as the entire edge. Made-with: Cursor
Leads with what you can do. Tabs for connecting Cursor, Claude Code, OpenClaw, Claude Desktop, API, CLI. Accordions show real prompts and tool names. No preamble — connect in under a minute. Made-with: Cursor
Made-with: Cursor
There was a problem hiding this comment.
🧹 Nitpick comments (2)
how-it-works.mdx (1)
6-6: Minor grammar fix: hyphenate "General-purpose".The static analysis flagged that "General purpose" should be hyphenated when used as a compound adjective.
📝 Proposed fix
-General purpose AI tools don't know the artist, the catalog, the audience, or the history. +General-purpose AI tools don't know the artist, the catalog, the audience, or the history.And on line 96:
-General purpose agents can generate a marketing plan for any artist. +General-purpose agents can generate a marketing plan for any artist.Also applies to: 96-96
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@how-it-works.mdx` at line 6, Replace the unhyphenated compound adjective "General purpose AI tools" with "General-purpose AI tools" in the text (occurrences include the phrase on the line containing "General purpose AI tools don't know the artist..." and the similar instance around line 96) so the compound adjective is correctly hyphenated; update both occurrences to "General-purpose" to satisfy the static analysis and maintain consistency.index.mdx (1)
169-169: Minor grammar fix: hyphenate "General-purpose".Same hyphenation issue as in how-it-works.mdx.
📝 Proposed fix
-General purpose AI doesn't know the artist, the catalog, the audience, or the history. +General-purpose AI doesn't know the artist, the catalog, the audience, or the history.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@index.mdx` at line 169, Change the phrase "General purpose AI" to use the correct hyphenation "General-purpose AI" wherever it appears (e.g., the sentence starting with "General purpose AI doesn't know the artist..." in the diff). Update the text in index.mdx to replace "General purpose" with "General-purpose" and ensure the same correction is applied consistently in other files with the same phrase (like how-it-works.mdx).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@how-it-works.mdx`:
- Line 6: Replace the unhyphenated compound adjective "General purpose AI tools"
with "General-purpose AI tools" in the text (occurrences include the phrase on
the line containing "General purpose AI tools don't know the artist..." and the
similar instance around line 96) so the compound adjective is correctly
hyphenated; update both occurrences to "General-purpose" to satisfy the static
analysis and maintain consistency.
In `@index.mdx`:
- Line 169: Change the phrase "General purpose AI" to use the correct
hyphenation "General-purpose AI" wherever it appears (e.g., the sentence
starting with "General purpose AI doesn't know the artist..." in the diff).
Update the text in index.mdx to replace "General purpose" with "General-purpose"
and ensure the same correction is applied consistently in other files with the
same phrase (like how-it-works.mdx).
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 7b7e47a6-36a3-487e-a0fc-9d8a589c312d
📒 Files selected for processing (2)
how-it-works.mdxindex.mdx
"The MCP server for music" — agents need clarity (what tools exist), confidence (real example with real output), and hype (why pick this over generic tools). Tool names on every card. Connect in 30 seconds. Made-with: Cursor
CLI-first positioning. npm install is the hero. Cards show CLI commands alongside MCP tool names. MCP tabs are secondary. Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
43 MCP tools with descriptions, params, and types. 13 CLI commands with flags. Connection instructions for MCP/API/CLI. Single-file reference that agents can fetch in one request. Made-with: Cursor
Fixed compound adjective in how-it-works.mdx and index.mdx. Other CodeRabbit comments addressed: - introduction.mdx narrative: this is a landing page, not an endpoint page — frontmatter-only rule doesn't apply here - Duplicated API key blocks: minor overlap across quickstart, auth, and MCP pages — each is contextual, not worth a snippet for 2-3 lines Made-with: Cursor
Made-with: Cursor
There was a problem hiding this comment.
🧹 Nitpick comments (2)
index.mdx (2)
1-168: Consider the multi-purpose nature of this landing page.While the coding guidelines recommend "put one concept per page," this index.mdx serves as the main entry point and appropriately combines:
- Marketing/positioning
- Quick-start onboarding
- Capability showcase
- Navigation hub
For a landing page, this multi-purpose approach is common and effective. The clear section headings and organization keep it scannable. However, if the page grows significantly, consider extracting some sections (e.g., "Why Recoup") into dedicated pages to maintain simplicity.
As per coding guidelines: "Follow Single Responsibility principle - put one concept per page."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@index.mdx` around lines 1 - 168, Summary: index.mdx currently bundles multiple concepts (marketing, quick-start, capability showcase, navigation) which contradicts the one-concept-per-page guideline. Fix: split large sections into dedicated pages and keep index.mdx as a focused landing hub — extract "Why Recoup" into a new why-recoup.mdx, move detailed "Get started" CLI/MCP/REST examples into a quickstart.mdx, and move the full tool list from "What you get" to a mcp-tools.mdx (or similar); update index.mdx to include concise summaries and clear links/cards to these new pages (referencing the headings "Why Recoup", "Get started", and "What you get" in the current file when making the edits). Ensure navigation links (Card hrefs/Tabs) point to the new pages and remove duplicated detailed content from index.mdx.
10-12: Remove duplicate installation command.This npm install snippet is duplicated in the CLI tab (lines 18-20), violating the DRY principle. Consider removing it from here and keeping only the version inside the CLI tab, or vice versa.
♻️ Suggested fix: remove the duplicate
# Music Industry Tools for AI Agents Spotify data. Content generation. Audience research. Catalog management. YouTube analytics. 40+ tools, one connection. Install the CLI or connect via MCP. -```bash -npm install -g `@recoupable/cli` -``` - ## Get startedAs per coding guidelines: "Follow DRY principle - don't duplicate content across pages, use snippets instead."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@index.mdx` around lines 10 - 12, Remove the duplicated npm install snippet by deleting the standalone code block that contains "npm install -g `@recoupable/cli`" and keep the single occurrence inside the CLI tab section; search for the code block with that exact command and remove the duplicate instance so only the CLI tab's snippet remains, ensuring surrounding headings (e.g., "Get started") remain intact.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@index.mdx`:
- Around line 1-168: Summary: index.mdx currently bundles multiple concepts
(marketing, quick-start, capability showcase, navigation) which contradicts the
one-concept-per-page guideline. Fix: split large sections into dedicated pages
and keep index.mdx as a focused landing hub — extract "Why Recoup" into a new
why-recoup.mdx, move detailed "Get started" CLI/MCP/REST examples into a
quickstart.mdx, and move the full tool list from "What you get" to a
mcp-tools.mdx (or similar); update index.mdx to include concise summaries and
clear links/cards to these new pages (referencing the headings "Why Recoup",
"Get started", and "What you get" in the current file when making the edits).
Ensure navigation links (Card hrefs/Tabs) point to the new pages and remove
duplicated detailed content from index.mdx.
- Around line 10-12: Remove the duplicated npm install snippet by deleting the
standalone code block that contains "npm install -g `@recoupable/cli`" and keep
the single occurrence inside the CLI tab section; search for the code block with
that exact command and remove the duplicate instance so only the CLI tab's
snippet remains, ensuring surrounding headings (e.g., "Get started") remain
intact.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: c57b8c63-df6b-4f78-a931-a88bda7a6e1e
📒 Files selected for processing (3)
docs.jsonhow-it-works.mdxindex.mdx
✅ Files skipped from review due to trivial changes (1)
- how-it-works.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- docs.json
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
What changed
index.mdxquickstart.mdxhow-it-works.mdxcli.mdxmcp.mdxauthentication.mdxapi-reference/introduction.mdxdocs.jsonContext
Inspired by Composio's documentation quality. Voice follows
marketing/content/brand/voice.md— specific, show-don't-tell, no hype words. Positioning aligned withmarketing/content/brand/positioning.md.Test plan
npx mintlify@latest devMade with Cursor
Summary by CodeRabbit