docs: fix skill naming and refresh getting-started#13
Conversation
README: - Fix broken skill links: chartmetric → chart-metric, songwriting → song-writing - Remove brand-guidelines row (skill does not exist in this repo) getting-started: - Drop the CLI install step — everything is HTTP (REST + MCP) - Add quick-reference header with base URL, MCP URL, and auth headers - Add Path C for dashboard-based key creation at chat.recoupable.com/keys - Replace `recoup whoami` verification with a curl /api/accounts/id example - Add Python and JavaScript REST client examples alongside bash - Add "Auth gotchas" section covering x-api-key vs Bearer, hashing, rotation - Update "What's next" table to match actual folder names Made-with: Cursor
📝 WalkthroughWalkthroughThe README skill links table was updated to remove 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 |
Two corrections to Path A based on a live audit against prod and a read of the canonical authentication.mdx + agents.mdx in the docs worktree (feat/docs-design-overhaul-combined): - Soften "always returns a key" → "skips email verification and returns a key on the first call". The signup handler routes pre-existing agent+ emails through the existing-account path, so the unconditional "always" was technically incorrect even though the date+RANDOM trick makes collision impossible in practice. - Add a warning that agent+ emails create a brand-new sandboxed account that is NOT linked to the human's real email. This is the same warning that already lives in docs/agents.mdx — agents using agent+sid@recoupable.com would otherwise think they are working as Sid when they are actually in an isolated sandbox. Verified live against https://recoup-api.vercel.app: - /api/agents/signup with agent+ email returns api_key immediately - /api/accounts/id returns {status, accountId} (200) - Sending both x-api-key + Authorization returns 401 with the exact message documented in the skill - /api/research?q=Drake&type=artists&beta=true returns ranked Chartmetric matches - /api/research/profile?artist=Drake returns full profile - /api/tasks returns 200 - /mcp endpoint accepts Bearer auth and responds to JSON-RPC initialize as recoup-mcp v0.0.1 with tools capability Verified static against api/lib: - HMAC-SHA256 hashing in lib/keys/hashApiKey.ts - Org-account access semantics in lib/organizations/canAccessAccount.ts match the skill's "any account in your org" wording 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
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/getting-started/SKILL.md`:
- Around line 155-162: Update the "What's next." table entry that currently
reads "songwriting" to use the canonical skill name "song-writing" so it matches
the repo/docs naming; locate the table rows (entries like
music-industry-research, content-creation, release-management, setup-sandbox,
streaming-growth, songwriting, artist-workspace) in SKILL.md and replace the
"songwriting" identifier with "song-writing" to ensure folder/skill name mapping
is consistent.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: b7457932-7559-430d-b363-040c9fd83be7
📒 Files selected for processing (2)
README.mdskills/getting-started/SKILL.md
| | ----- | ------------ | | ||
| | music-industry-research | Deep artist analytics, people search, charts, competitive analysis, web intelligence | | ||
| | content-creation | Generate videos, images, captions from artist catalogs | | ||
| | industry-research | Deep artist analytics, people search, competitive analysis | | ||
| | release-management | Plan and execute release campaigns | | ||
| | setup-sandbox | Scaffold workspace for an account's orgs and artists | | ||
| | setup-sandbox | Scaffold the workspace for an account's orgs and artists | | ||
| | streaming-growth | Grow artists past streaming milestones | | ||
| | songwriting | Structured songwriting using the 7 C's method | | ||
| | artist-workspace | Manage artist directories — context, songs, brand, audience | |
There was a problem hiding this comment.
Use the canonical skill name consistently in “What’s next.”
Line 161 still says songwriting, while the repo/docs now use song-writing. Please align this entry to avoid confusion when users map names to folders/skills.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/getting-started/SKILL.md` around lines 155 - 162, Update the "What's
next." table entry that currently reads "songwriting" to use the canonical skill
name "song-writing" so it matches the repo/docs naming; locate the table rows
(entries like music-industry-research, content-creation, release-management,
setup-sandbox, streaming-growth, songwriting, artist-workspace) in SKILL.md and
replace the "songwriting" identifier with "song-writing" to ensure folder/skill
name mapping is consistent.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="skills/getting-started/SKILL.md">
<violation number="1" location="skills/getting-started/SKILL.md:30">
P3: This documentation claims `$(date +%s)` + `$RANDOM` “guarantees uniqueness,” but that combination only reduces collision risk and does not guarantee it.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
| ``` | ||
|
|
||
| The `agent+{unique}@recoupable.com` pattern always returns a key with no verification step. Combining `$(date +%s)` with `$RANDOM` guarantees unique addresses. | ||
| A new `agent+{unique}@recoupable.com` address skips email verification and returns a key on the first call. Combining `$(date +%s)` with `$RANDOM` guarantees uniqueness so you never collide with an existing account. |
There was a problem hiding this comment.
P3: This documentation claims $(date +%s) + $RANDOM “guarantees uniqueness,” but that combination only reduces collision risk and does not guarantee it.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At skills/getting-started/SKILL.md, line 30:
<comment>This documentation claims `$(date +%s)` + `$RANDOM` “guarantees uniqueness,” but that combination only reduces collision risk and does not guarantee it.</comment>
<file context>
@@ -19,15 +19,17 @@ Two paths depending on who is doing this.
-The agent+{unique}@recoupable.com pattern always returns a key with no verification step. Combining $(date +%s) with $RANDOM guarantees a unique address.
+A new agent+{unique}@recoupable.com address skips email verification and returns a key on the first call. Combining $(date +%s) with $RANDOM guarantees uniqueness so you never collide with an existing account.
+
+> agent+ emails create a separate account. agent+sid@recoupable.com is not linked to sid@recoupable.com — it's a brand-new sandboxed account with no roster, no orgs, and no history. To work on behalf of an existing human, use Path B with their real email.
</file context>
</details>
```suggestion
A new `agent+{unique}@recoupable.com` address skips email verification and returns a key on the first call. Combining `$(date +%s)` with `$RANDOM` makes collisions unlikely in practice.
2 participants
Summary
Two doc fixes to the skills repo, grouped together since they're both user-facing onboarding content.
README
chartmetric→chart-metric,songwriting→song-writing(folders use kebab-case; links pointed to folders that don't exist)brand-guidelinesrow — that skill doesn't live in this reposkills/getting-started/SKILL.md
Reframes the skill around the actual user experience: no CLI install needed — everything is HTTP (REST or MCP). Notable changes:
npm install -g @recoupable/clistepchat.recoupable.com/keysrecoup whoamiverification with an explicitcurl /api/accounts/idexample and 200/401 behaviorx-api-keyvsBearer, HMAC hashing, and rotationmusic-industry-researchinstead ofindustry-research, addsartist-workspace)Known tech debt (follow-up, not in this PR)
Some of the reference material in
getting-started(auth headers, gotchas, language examples) duplicates what should live indocs/(developers.recoupable.com). Consider moving that content to the docs submodule in a follow-up and having the skill link out instead.Test plan
curlcommand still returns a validapi_keyagainst the live APIcurl /api/accounts/idwith a valid key returns 200 +accountIdMade with Cursor
Summary by CodeRabbit