feat: add llms.txt and llms-full.txt for agent discoverability#264
Open
sidneyswift wants to merge 1 commit into
Open
feat: add llms.txt and llms-full.txt for agent discoverability#264sidneyswift wants to merge 1 commit into
sidneyswift wants to merge 1 commit into
Conversation
Custom llms.txt files that give AI agents a structured overview of the entire Recoup API surface — endpoints, plugins, CLI, MCP, and common workflows. Addresses the P2 roadmap item 'Agent discoverability in docs'. - llms.txt: compact overview (~6.7KB) with all sections and key endpoints - llms-full.txt: comprehensive reference (~17KB) with every endpoint, request/response details, and step-by-step workflows - Overrides Mintlify's auto-generated version with music-industry-specific context and plugin installation instructions
📝 WalkthroughWalkthroughThis PR adds two new documentation files, ChangesLLM Reference Documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Related issues: None mentioned in the PR. Related PRs: None mentioned in the PR. Suggested labels: documentation Suggested reviewers: None specified. 🐰 PoemA rabbit hops through docs anew, 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@llms-full.txt`:
- Around line 148-152: The API docs currently use the wrong response and polling
identifiers for the content pipeline. Update the `POST /api/content/create`
section in `llms-full.txt` so it returns `runIds` as an array instead of a
singular `runId`, and correct the `GET /api/tasks/runs` polling guidance to use
`runId` rather than `taskId`. Make sure the references around the content-create
endpoint and the tasks-runs polling example are consistent with the actual
`runIds`/`runId` naming.
- Around line 50-53: Update the route description to use the canonical research
endpoint referenced by the GET /api/research documentation, not GET
/api/research/search. Adjust the workflow lookup guidance in llms-full.txt so it
says the search uses q with optional type defaulting to artists, plus limit and
offset, and explicitly instructs callers to pass type=artists rather than
relying on a /search path. Keep the surrounding API reference wording consistent
with the existing GET /api/research section.
In `@llms.txt`:
- Around line 32-35: The artist search entry in llms.txt is pointing at the doc
page instead of the canonical API route. Update the Research section so the
lookup reference uses GET /api/research?q={query}&type=artists (with optional
limit) and keep the surrounding endpoint list consistent with the real search
contract; use the existing Research heading and search/profile entries to locate
the change.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Comment on lines
+50
to
+53
| ### GET /api/research/search | ||
| Search for artists by name. | ||
| Query params: `q` (required), `limit`, `offset` | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Locate the relevant documentation file and inspect the referenced ranges.
git ls-files | rg '^llms-full\.txt$'
wc -l llms-full.txt
sed -n '40,70p' llms-full.txt
printf '\n---\n'
sed -n '610,640p' llms-full.txt
# Search for research endpoint definitions and related query params across the repo.
rg -n "api/research|research/search|type=.*artists|offset|runIds|runId|api/content/create" .Repository: recoupable/docs
Length of output: 29774
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the exact parameter list for GET /api/research in the OpenAPI spec.
sed -n '939,985p' api-reference/openapi/research.json
# Inspect the content-create response shape in the OpenAPI spec.
sed -n '661,710p' api-reference/openapi/content.jsonRepository: recoupable/docs
Length of output: 4259
Use the canonical research route.
llms-full.txt:50-53, 618-623 should point to GET /api/research; that endpoint accepts q plus optional type (default artists), limit, and offset. The workflow lookup should use type=artists instead of the /search path.
Proposed fix
- ### GET /api/research/search
+ ### GET /api/research
Search for artists by name.
- Query params: `q` (required), `limit`, `offset`
+ Query params: `q` (required), `type`, `limit`, `offset`
@@
- `GET /api/research/search?q={name}` — find Spotify match
+ `GET /api/research?q={name}&type=artists` — find Spotify match🤖 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 `@llms-full.txt` around lines 50 - 53, Update the route description to use the
canonical research endpoint referenced by the GET /api/research documentation,
not GET /api/research/search. Adjust the workflow lookup guidance in
llms-full.txt so it says the search uses q with optional type defaulting to
artists, plus limit and offset, and explicitly instructs callers to pass
type=artists rather than relying on a /search path. Keep the surrounding API
reference wording consistent with the existing GET /api/research section.
Comment on lines
+148
to
+152
| ### POST /api/content/create | ||
| Full content pipeline — takes an artist account ID and produces a finished social-ready video with caption. | ||
| Body: `{"artistAccountId": "uuid", "template": "optional-name", "lipsync": false, "upscale": false}` | ||
| Returns: `{"runId": "uuid"}` — poll with tasks endpoint. | ||
|
|
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n## Relevant lines from llms-full.txt\n'
nl -ba llms-full.txt | sed -n '138,165p'
printf '\n## Search for endpoint and run id references\n'
rg -n --hidden --no-messages -S 'POST /api/content/create|GET /api/tasks/runs|runIds|runId|taskId=' .
printf '\n## File inventory for likely docs/contracts\n'
git ls-files | rg -n '(^|/)(README|docs|llms-full\.txt|openapi|api|swagger|schema|spec)' || trueRepository: recoupable/docs
Length of output: 231
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n## Relevant lines from llms-full.txt\n'
awk 'NR>=138 && NR<=165 { printf "%d:%s\n", NR, $0 }' llms-full.txt
printf '\n## Search for endpoint and run id references in llms-full.txt\n'
rg -n -S 'POST /api/content/create|GET /api/tasks/runs|runIds|runId|taskId=' llms-full.txt
printf '\n## Search the repository for related references\n'
rg -n -S 'POST /api/content/create|GET /api/tasks/runs|runIds|runId|taskId=' .Repository: recoupable/docs
Length of output: 14319
Use runIds here, and runId in the polling step. POST /api/content/create returns runIds (array), not a singular runId, and GET /api/tasks/runs should be polled with runId, not taskId. Update llms-full.txt at 148-152 and 630-631.
🤖 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 `@llms-full.txt` around lines 148 - 152, The API docs currently use the wrong
response and polling identifiers for the content pipeline. Update the `POST
/api/content/create` section in `llms-full.txt` so it returns `runIds` as an
array instead of a singular `runId`, and correct the `GET /api/tasks/runs`
polling guidance to use `runId` rather than `taskId`. Make sure the references
around the content-create endpoint and the tasks-runs polling example are
consistent with the actual `runIds`/`runId` naming.
Comment on lines
+32
to
+35
| ### Research (20+ endpoints) | ||
| Artist analytics, audience insights, playlist intelligence, competitive analysis, trend detection. | ||
| - `GET /api/research/search?q={query}` — Find artists | ||
| - `GET /api/research/profile?artistId={id}` — Artist profile |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== files =="
git ls-files | rg '(^|/)(llms\.txt|openapi|openapi\.ya?ml|swagger|api|research)'
echo
echo "== llms.txt lines around 32-35 =="
if [ -f llms.txt ]; then
cat -n llms.txt | sed -n '24,42p'
fi
echo
echo "== search for research route definitions =="
rg -n --hidden --glob '!**/node_modules/**' --glob '!**/dist/**' --glob '!**/build/**' '/api/research|research/search|research\?' .Repository: recoupable/docs
Length of output: 20870
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== research search doc =="
cat -n api-reference/research/search.mdx | sed -n '1,120p'
echo
echo "== openapi /api/research entry =="
python3 - <<'PY'
import json
from pathlib import Path
data = json.loads(Path('api-reference/openapi/research.json').read_text())
path = data['paths']['/api/research']['get']
print("summary:", path.get('summary'))
print("description:", path.get('description'))
print("parameters:")
for p in path.get('parameters', []):
print(f"- {p.get('name')!r} in {p.get('in')} required={p.get('required')} schema={p.get('schema')}")
PYRepository: recoupable/docs
Length of output: 1329
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== research search doc =="
cat -n api-reference/research/search.mdx | sed -n '1,120p'
echo
echo "== openapi /api/research entry =="
python3 - <<'PY'
import json
from pathlib import Path
data = json.loads(Path('api-reference/openapi/research.json').read_text())
path = data['paths']['/api/research']['get']
print("summary:", path.get("summary"))
print("description:", path.get("description"))
print("parameters:")
for p in path.get("parameters", []):
print(f"- {p.get('name')!r} in {p.get('in')} required={p.get('required')} schema={p.get('schema')}")
PYRepository: recoupable/docs
Length of output: 1329
Use the canonical research endpoint here.
/api/research/search is the doc page, not the API route. For artist lookup, point llms.txt at GET /api/research?q={query}&type=artists (with optional limit) so agents hit the real search contract.
🤖 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 `@llms.txt` around lines 32 - 35, The artist search entry in llms.txt is
pointing at the doc page instead of the canonical API route. Update the Research
section so the lookup reference uses GET /api/research?q={query}&type=artists
(with optional limit) and keep the surrounding endpoint list consistent with the
real search contract; use the existing Research heading and search/profile
entries to locate the change.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
5 issues found across 2 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="llms.txt">
<violation number="1" location="llms.txt:34">
P2: This endpoint path (`/api/research/search`) may reference a documentation page rather than the actual API route. If the canonical artist search endpoint is `GET /api/research?q={query}&type=artists`, agents following this documentation will call a non-existent route.</violation>
<violation number="2" location="llms.txt:76">
P3: The Chat section header says "12 endpoints" but only 11 are listed below it. An AI agent parsing the count literally could get incorrect metadata about the API surface. Either update the count to 11 to match what's listed, or add the missing endpoint.</violation>
<violation number="3" location="llms.txt:90">
P3: The Songs & Catalogs section header says "10 endpoints" but only 9 are listed below it (and the full reference in `llms-full.txt` also has exactly 9). This would mislead an AI agent about the available API surface. Update the count to 9.</violation>
</file>
<file name="llms-full.txt">
<violation number="1" location="llms-full.txt:50">
P2: The research search endpoint documented here as `GET /api/research/search` may not match the actual API route. If the canonical endpoint is `GET /api/research` (accepting `q`, `type`, `limit`, `offset` parameters, with `type=artists` for artist lookup), this documentation will cause agents to hit a non-existent route. The same path is referenced in the workflow section at line 619.</violation>
<violation number="2" location="llms-full.txt:151">
P2: The response format documented here (`{"runId": "uuid"}`) and the polling step in the workflow section (`GET /api/tasks/runs?taskId={runId}`) appear internally inconsistent. If the actual response returns `runIds` (an array), this will cause agents to look for the wrong field. Additionally, the workflow section passes a `runId` value to a `taskId` parameter, which is contradictory and suggests the polling parameter should be `runId` instead.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
|
|
||
| ### Research (20+ endpoints) | ||
| Artist analytics, audience insights, playlist intelligence, competitive analysis, trend detection. | ||
| - `GET /api/research/search?q={query}` — Find artists |
There was a problem hiding this comment.
P2: This endpoint path (/api/research/search) may reference a documentation page rather than the actual API route. If the canonical artist search endpoint is GET /api/research?q={query}&type=artists, agents following this documentation will call a non-existent route.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At llms.txt, line 34:
<comment>This endpoint path (`/api/research/search`) may reference a documentation page rather than the actual API route. If the canonical artist search endpoint is `GET /api/research?q={query}&type=artists`, agents following this documentation will call a non-existent route.</comment>
<file context>
@@ -0,0 +1,157 @@
+
+### Research (20+ endpoints)
+Artist analytics, audience insights, playlist intelligence, competitive analysis, trend detection.
+- `GET /api/research/search?q={query}` — Find artists
+- `GET /api/research/profile?artistId={id}` — Artist profile
+- `GET /api/research/metrics?artistId={id}` — Streaming metrics
</file context>
| ### POST /api/content/create | ||
| Full content pipeline — takes an artist account ID and produces a finished social-ready video with caption. | ||
| Body: `{"artistAccountId": "uuid", "template": "optional-name", "lipsync": false, "upscale": false}` | ||
| Returns: `{"runId": "uuid"}` — poll with tasks endpoint. |
There was a problem hiding this comment.
P2: The response format documented here ({"runId": "uuid"}) and the polling step in the workflow section (GET /api/tasks/runs?taskId={runId}) appear internally inconsistent. If the actual response returns runIds (an array), this will cause agents to look for the wrong field. Additionally, the workflow section passes a runId value to a taskId parameter, which is contradictory and suggests the polling parameter should be runId instead.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At llms-full.txt, line 151:
<comment>The response format documented here (`{"runId": "uuid"}`) and the polling step in the workflow section (`GET /api/tasks/runs?taskId={runId}`) appear internally inconsistent. If the actual response returns `runIds` (an array), this will cause agents to look for the wrong field. Additionally, the workflow section passes a `runId` value to a `taskId` parameter, which is contradictory and suggests the polling parameter should be `runId` instead.</comment>
<file context>
@@ -0,0 +1,647 @@
+### POST /api/content/create
+Full content pipeline — takes an artist account ID and produces a finished social-ready video with caption.
+Body: `{"artistAccountId": "uuid", "template": "optional-name", "lipsync": false, "upscale": false}`
+Returns: `{"runId": "uuid"}` — poll with tasks endpoint.
+
+### POST /api/content/image
</file context>
|
|
||
| ## Research Endpoints | ||
|
|
||
| ### GET /api/research/search |
There was a problem hiding this comment.
P2: The research search endpoint documented here as GET /api/research/search may not match the actual API route. If the canonical endpoint is GET /api/research (accepting q, type, limit, offset parameters, with type=artists for artist lookup), this documentation will cause agents to hit a non-existent route. The same path is referenced in the workflow section at line 619.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At llms-full.txt, line 50:
<comment>The research search endpoint documented here as `GET /api/research/search` may not match the actual API route. If the canonical endpoint is `GET /api/research` (accepting `q`, `type`, `limit`, `offset` parameters, with `type=artists` for artist lookup), this documentation will cause agents to hit a non-existent route. The same path is referenced in the workflow section at line 619.</comment>
<file context>
@@ -0,0 +1,647 @@
+
+## Research Endpoints
+
+### GET /api/research/search
+Search for artists by name.
+Query params: `q` (required), `limit`, `offset`
</file context>
| - `DELETE /api/chats` — Delete chat | ||
| - `POST /api/chats/compact` — Compact chat history | ||
|
|
||
| ### Songs & Catalogs (10 endpoints) |
There was a problem hiding this comment.
P3: The Songs & Catalogs section header says "10 endpoints" but only 9 are listed below it (and the full reference in llms-full.txt also has exactly 9). This would mislead an AI agent about the available API surface. Update the count to 9.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At llms.txt, line 90:
<comment>The Songs & Catalogs section header says "10 endpoints" but only 9 are listed below it (and the full reference in `llms-full.txt` also has exactly 9). This would mislead an AI agent about the available API surface. Update the count to 9.</comment>
<file context>
@@ -0,0 +1,157 @@
+- `DELETE /api/chats` — Delete chat
+- `POST /api/chats/compact` — Compact chat history
+
+### Songs & Catalogs (10 endpoints)
+- `GET /api/songs` — List songs
+- `POST /api/songs` — Create song
</file context>
Suggested change
| ### Songs & Catalogs (10 endpoints) | |
| ### Songs & Catalogs (9 endpoints) |
| - `GET /api/artists/socials?artistId={id}` — Artist social links | ||
| - `GET /api/artist/profile?artistId={id}` — Full artist profile | ||
|
|
||
| ### Chat (12 endpoints) |
There was a problem hiding this comment.
P3: The Chat section header says "12 endpoints" but only 11 are listed below it. An AI agent parsing the count literally could get incorrect metadata about the API surface. Either update the count to 11 to match what's listed, or add the missing endpoint.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At llms.txt, line 76:
<comment>The Chat section header says "12 endpoints" but only 11 are listed below it. An AI agent parsing the count literally could get incorrect metadata about the API surface. Either update the count to 11 to match what's listed, or add the missing endpoint.</comment>
<file context>
@@ -0,0 +1,157 @@
+- `GET /api/artists/socials?artistId={id}` — Artist social links
+- `GET /api/artist/profile?artistId={id}` — Full artist profile
+
+### Chat (12 endpoints)
+Conversations with artist context, streaming support.
+- `POST /api/chat/workflow` — Send message (non-streaming)
</file context>
Suggested change
| ### Chat (12 endpoints) | |
| ### Chat (11 endpoints) |
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.
Custom llms.txt and llms-full.txt for agent capability discovery. Addresses P2 roadmap item.
Summary by cubic
Add
llms.txtandllms-full.txtto improve agent/tool discoverability of the Recoup API. Provides a compact index and a full reference covering endpoints, plugins, CLI, MCP, and common workflows.llms.txt: compact overview with key endpoints by section, plugin install commands,@recoupable/cliquick start, MCP connection, and links.llms-full.txt: comprehensive reference with all endpoints, auth and signup flow, example payloads, CLI commands, MCP tools, and step-by-step workflows.Written for commit 18152f5. Summary will update on new commits.
Summary by CodeRabbit