Skip to content

Reconcile current API docs and Context preview contracts - #152

Merged
sidneyswift merged 5 commits into
mainfrom
codex/docs-contract-accuracy-20261012
Oct 13, 2026
Merged

sidneyswift merged 5 commits into
mainfrom
codex/docs-contract-accuracy-20261012

Conversation

@sidneyswift

@sidneyswift sidneyswift commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

The maintained docs contained stale social prices/defaults, catalog limits, task inputs, chat resume statuses, callback authentication and artist pin routes. Correct those contracts, CLI examples and Sites deletion/cancellation instructions against the current source. Expand Context from five to 26 request schemas plus delegated MCP mappings, labeled as a source-verified preview with explicit pilot restrictions. Keep provider-bound catalog planning as a tracked gap.

Mark ten unmatched REST paths as pending reconciliation rather than presenting them as supported or retiring their retained outcomes. The reviewed source baseline is 406 implemented method/path pairs, ten unmatched documented pairs and 59 static MCP registrations; this is not a promised live feature/tool count.

Add shared contract fixtures checked against API validators and helpers. The MCP table is generated from the canonical mapping metadata. The inventory also rejects unmatched REST references unless their public description and metadata explicitly mark pending or retired availability. The inventory pins the coordinated API PR's reviewed source commit; refresh it to the actual API merge commit before releasing this change, then refresh the Docs copy to the actual Marketing merge commit.

Validation: 437 Marketing tests, docs generation/checks, shared fixture parity, contract-inventory and publication-sync tests pass. Local Turbopack fails because this environment blocks its helper port; the Webpack fallback fails parsing the existing Eve dependency. Pushed for remote preview validation under Sidney's existing approval; merge remains blocked until the remote production build passes at the final head. No hosting, DNS, redirect or paid-provider operation is changed.

API companion: recoupable/api#1032
CLI companion: recoupable/cli#26

Refs recoupable/mono#318, recoupable/mono#326, recoupable/mono#327, recoupable/mono#329, recoupable/mono#330, recoupable/mono#331, recoupable/mono#332, recoupable/mono#333, recoupable/mono#335, recoupable/mono#336, recoupable/mono#346, recoupable/mono#355, recoupable/mono#356, recoupable/mono#360, recoupable/mono#361.

Review notes: generated OpenAPI contracts and snapshots remain generated data; no arbitrary 100-line cap is applied. Artist profile song_count comes from an independent exact catalog count and can exceed the returned songs, so its existing description is preserved.

@vercel

vercel Bot commented Oct 13, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
marketing Ready Ready Preview Oct 13, 2026 2:24am UTC

Request Review

@coderabbitai

coderabbitai Bot commented Oct 13, 2026 •

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: bed7adf8-a914-4157-bccb-34932938a257
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

7 issues found across 17 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="content/docs/source/api-reference/sites/overview.mdx">

<violation number="1" location="content/docs/source/api-reference/sites/overview.mdx:114">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**

This hand-authored MDX file is 137 lines after the addition, exceeding the rule's under-100-line cap. Split the deletion/cancellation material into a separate page or restructure the overview so each source file stays under 100 lines.</violation>

<violation number="2" location="content/docs/source/api-reference/sites/overview.mdx:114">
P3: This new section introduces `DELETE /api/sites/{id}` as a public REST operation, but the "Endpoints and tools" table at the top of this same page still has no DELETE row (it lists `GET /api/sites`, `POST /api/sites`, `GET /api/sites/{id}`, the four PATCH actions, `GET .../signups`, and `POST /api/sites/assets`). Readers and LLMs that discover operations through the table won't find deletion. Add a row such as `| \`DELETE /api/sites/{id}\` | \`delete_site\` | \`{ "deleted": true, "id": "..." }\` |` to keep the table in sync with the prose.</violation>

<violation number="3" location="content/docs/source/api-reference/sites/overview.mdx:116">
P3: The section says to send `revision` and `generationToken` with the DELETE but never states how they are transmitted (JSON body, query parameters, or headers), and no curl example is given. Every other parameterized request on this page is a JSON body sent to a PATCH (e.g. `{"action":"generate","revision":0}`), so a reader will guess; many HTTP clients also strip DELETE bodies, which makes transport worth stating explicitly. Confirm against the API source and specify the transport, ideally with one curl example.</violation>
</file>

<file name="scripts/refresh-contract-inventory.py">

<violation number="1" location="scripts/refresh-contract-inventory.py:105">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**

`main()` now adds unmatched-contract validation to a 134-line script, violating the under-100-line and single-responsibility requirements. Extract this validation into a separate cohesive module and keep `main()` focused on orchestration.</violation>

<violation number="2" location="scripts/refresh-contract-inventory.py:109">
P3: The gate depends on a prose marker, not just the structured field: it requires the literal substring `availability: pending`/`availability: retired` inside the operation description, so an otherwise correct `x-recoup-availability` value fails the refresh whenever the description formats the disclosure differently (e.g. `**Status:** pending`). It is also brittle on exact-path lookup: `['paths'][route]` uses the trailing-slash-stripped route from the docs key, while `social.json` stores `/api/spotify/artist/` with a trailing slash, so if that route ever became unmatched the script would raise an unhandled `KeyError` instead of the intended `SystemExit`. Consider gating on the structured field alone and normalizing the path lookup.</violation>
</file>

<file name="content/docs/source/api-reference/openapi/context.json">

<violation number="1" location="content/docs/source/api-reference/openapi/context.json:55">
P1: Custom agent: **Enforce Clear Code Style and Maintainability Practices**

This OpenAPI source file now spans 1,327 lines, violating the under-100-line maintainability rule; split the action schemas and single-source the MCP mapping instead of inlining both representations.</violation>
</file>

<file name="content/docs/source/api-reference/openapi/releases.json">

<violation number="1" location="content/docs/source/api-reference/openapi/releases.json:1049">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**

`releases.json` is a 6,733-line, multi-domain source file, and this change adds another 295 lines to it. Split the OpenAPI contracts into smaller single-domain files before extending this spec further.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

@@ -32,7 +32,7 @@
"post": {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: Custom agent: Enforce Clear Code Style and Maintainability Practices

This OpenAPI source file now spans 1,327 lines, violating the under-100-line maintainability rule; split the action schemas and single-source the MCP mapping instead of inlining both representations.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/openapi/context.json, line 55:

<comment>This OpenAPI source file now spans 1,327 lines, violating the under-100-line maintainability rule; split the action schemas and single-source the MCP mapping instead of inlining both representations.</comment>

<file context>
@@ -49,38 +49,819 @@
+                    "properties": {
+                      "action": {
+                        "type": "string",
+                        "const": "list_release_cases"
+                      },
+                      "organization_id": {
</file context>

Comment thread scripts/refresh-contract-inventory.py Resolved
dispositions = json.loads((out / 'operation-dispositions.json').read_text())
operations = implementation_operations(api, docs, dispositions)
implemented = {item['method'] + ' ' + item['path'] for item in operations}
for key in sorted(set(docs) - implemented):

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Custom agent: Enforce Clear Code Style and Maintainability Practices

main() now adds unmatched-contract validation to a 134-line script, violating the under-100-line and single-responsibility requirements. Extract this validation into a separate cohesive module and keep main() focused on orchestration.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At scripts/refresh-contract-inventory.py, line 105:

<comment>`main()` now adds unmatched-contract validation to a 134-line script, violating the under-100-line and single-responsibility requirements. Extract this validation into a separate cohesive module and keep `main()` focused on orchestration.</comment>

<file context>
@@ -102,6 +102,12 @@ def main():
     dispositions = json.loads((out / 'operation-dispositions.json').read_text())
     operations = implementation_operations(api, docs, dispositions)
     implemented = {item['method'] + ' ' + item['path'] for item in operations}
+    for key in sorted(set(docs) - implemented):
+        method, route = key.split(' ', 1)
+        operation = json.loads((root / docs[key]).read_text())['paths'][route][method.lower()]
</file context>


Unpublish with `action: "unpublish"`, or `unpublish_site`. Agents should publish only when explicitly instructed.

## Delete and cancel generation

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Custom agent: Enforce Clear Code Style and Maintainability Practices

This hand-authored MDX file is 137 lines after the addition, exceeding the rule's under-100-line cap. Split the deletion/cancellation material into a separate page or restructure the overview so each source file stays under 100 lines.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/sites/overview.mdx, line 114:

<comment>This hand-authored MDX file is 137 lines after the addition, exceeding the rule's under-100-line cap. Split the deletion/cancellation material into a separate page or restructure the overview so each source file stays under 100 lines.</comment>

<file context>
@@ -111,6 +111,12 @@ The public page is `https://chat.recoupable.dev/s/{id}`.
 
 Unpublish with `action: "unpublish"`, or `unpublish_site`. Agents should publish only when explicitly instructed.
 
+## Delete and cancel generation
+
+Delete only when explicitly instructed. Send `DELETE /api/sites/{id}` with the current `revision`. Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.
</file context>

@@ -17,7 +17,7 @@
"/api/catalogs/{catalogId}/streams": {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Custom agent: Enforce Clear Code Style and Maintainability Practices

releases.json is a 6,733-line, multi-domain source file, and this change adds another 295 lines to it. Split the OpenAPI contracts into smaller single-domain files before extending this spec further.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/openapi/releases.json, line 1049:

<comment>`releases.json` is a 6,733-line, multi-domain source file, and this change adds another 295 lines to it. Split the OpenAPI contracts into smaller single-domain files before extending this spec further.</comment>

<file context>
@@ -1040,6 +1045,16 @@
               }
             }
+          },
+          "402": {
+            "description": "A single task fetched by id is blocked by its owner plan. Returns plan_limit with task_count or min_cadence and billingUrl. Ordinary listing does not apply this pre-run gate.",
+            "content": {
</file context>


## Delete and cancel generation

Delete only when explicitly instructed. Send `DELETE /api/sites/{id}` with the current `revision`. Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The section says to send revision and generationToken with the DELETE but never states how they are transmitted (JSON body, query parameters, or headers), and no curl example is given. Every other parameterized request on this page is a JSON body sent to a PATCH (e.g. {"action":"generate","revision":0}), so a reader will guess; many HTTP clients also strip DELETE bodies, which makes transport worth stating explicitly. Confirm against the API source and specify the transport, ideally with one curl example.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/sites/overview.mdx, line 116:

<comment>The section says to send `revision` and `generationToken` with the DELETE but never states how they are transmitted (JSON body, query parameters, or headers), and no curl example is given. Every other parameterized request on this page is a JSON body sent to a PATCH (e.g. `{"action":"generate","revision":0}`), so a reader will guess; many HTTP clients also strip DELETE bodies, which makes transport worth stating explicitly. Confirm against the API source and specify the transport, ideally with one curl example.</comment>

<file context>
@@ -111,6 +111,12 @@ The public page is `https://chat.recoupable.dev/s/{id}`.
 
+## Delete and cancel generation
+
+Delete only when explicitly instructed. Send `DELETE /api/sites/{id}` with the current `revision`. Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.
+
+Deletion checks workspace access and revision, then returns `{ "deleted": true, "id": "..." }`. A stale revision returns 409; reload before retrying. Unpublish with `action: "unpublish"` when the draft should remain available.
</file context>


Unpublish with `action: "unpublish"`, or `unpublish_site`. Agents should publish only when explicitly instructed.

## Delete and cancel generation

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: This new section introduces DELETE /api/sites/{id} as a public REST operation, but the "Endpoints and tools" table at the top of this same page still has no DELETE row (it lists GET /api/sites, POST /api/sites, GET /api/sites/{id}, the four PATCH actions, GET .../signups, and POST /api/sites/assets). Readers and LLMs that discover operations through the table won't find deletion. Add a row such as | \DELETE /api/sites/{id}` | `delete_site` | `{ "deleted": true, "id": "..." }` |` to keep the table in sync with the prose.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/source/api-reference/sites/overview.mdx, line 114:

<comment>This new section introduces `DELETE /api/sites/{id}` as a public REST operation, but the "Endpoints and tools" table at the top of this same page still has no DELETE row (it lists `GET /api/sites`, `POST /api/sites`, `GET /api/sites/{id}`, the four PATCH actions, `GET .../signups`, and `POST /api/sites/assets`). Readers and LLMs that discover operations through the table won't find deletion. Add a row such as `| \`DELETE /api/sites/{id}\` | \`delete_site\` | \`{ "deleted": true, "id": "..." }\` |` to keep the table in sync with the prose.</comment>

<file context>
@@ -111,6 +111,12 @@ The public page is `https://chat.recoupable.dev/s/{id}`.
 
 Unpublish with `action: "unpublish"`, or `unpublish_site`. Agents should publish only when explicitly instructed.
 
+## Delete and cancel generation
+
+Delete only when explicitly instructed. Send `DELETE /api/sites/{id}` with the current `revision`. Include `generationToken` when cancelling a known in-progress generation. The token must belong to this site and caller; cancellation is attempted before deletion. Omitting it does not request cancellation of every running job.
</file context>

Comment thread scripts/refresh-contract-inventory.py Outdated
method, route = key.split(' ', 1)
operation = json.loads((root / docs[key]).read_text())['paths'][route][method.lower()]
availability = operation.get('x-recoup-availability')
if availability not in ('pending', 'retired') or ('availability: ' + availability) not in operation.get('description', '').lower():

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The gate depends on a prose marker, not just the structured field: it requires the literal substring availability: pending/availability: retired inside the operation description, so an otherwise correct x-recoup-availability value fails the refresh whenever the description formats the disclosure differently (e.g. **Status:** pending). It is also brittle on exact-path lookup: ['paths'][route] uses the trailing-slash-stripped route from the docs key, while social.json stores /api/spotify/artist/ with a trailing slash, so if that route ever became unmatched the script would raise an unhandled KeyError instead of the intended SystemExit. Consider gating on the structured field alone and normalizing the path lookup.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At scripts/refresh-contract-inventory.py, line 109:

<comment>The gate depends on a prose marker, not just the structured field: it requires the literal substring `availability: pending`/`availability: retired` inside the operation description, so an otherwise correct `x-recoup-availability` value fails the refresh whenever the description formats the disclosure differently (e.g. `**Status:** pending`). It is also brittle on exact-path lookup: `['paths'][route]` uses the trailing-slash-stripped route from the docs key, while `social.json` stores `/api/spotify/artist/` with a trailing slash, so if that route ever became unmatched the script would raise an unhandled `KeyError` instead of the intended `SystemExit`. Consider gating on the structured field alone and normalizing the path lookup.</comment>

<file context>
@@ -102,6 +102,12 @@ def main():
+        method, route = key.split(' ', 1)
+        operation = json.loads((root / docs[key]).read_text())['paths'][route][method.lower()]
+        availability = operation.get('x-recoup-availability')
+        if availability not in ('pending', 'retired') or ('availability: ' + availability) not in operation.get('description', '').lower():
+            raise SystemExit('Unmatched documentation needs explicit pending/retired availability: ' + key)
     registrations = static_mcp_registrations(api)
</file context>

This was referenced Oct 13, 2026

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 existing issues remain and 1 new issue found across 12 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="content/docs/contracts/context-contract.json">

<violation number="1" location="content/docs/contracts/context-contract.json:1">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**

`context-contract.json` is 1,039 lines, exceeding Rule 1's under-100-line limit. Keep the generated contract data outside the rule's file-size scope or change the contract-fixture design so the committed artifact does not violate the limit; the navigation-specific generated-output exception does not cover this file.</violation>
</file>

Requires human review: Auto-approval blocked because this review re-detected 2 unresolved issues already reported by Cubic.

View guided diff | Turn on auto-fix | Re-trigger cubic

@@ -0,0 +1,1039 @@
{

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Custom agent: Enforce Clear Code Style and Maintainability Practices

context-contract.json is 1,039 lines, exceeding Rule 1's under-100-line limit. Keep the generated contract data outside the rule's file-size scope or change the contract-fixture design so the committed artifact does not violate the limit; the navigation-specific generated-output exception does not cover this file.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/contracts/context-contract.json, line 1:

<comment>`context-contract.json` is 1,039 lines, exceeding Rule 1's under-100-line limit. Keep the generated contract data outside the rule's file-size scope or change the contract-fixture design so the committed artifact does not violate the limit; the navigation-specific generated-output exception does not cover this file.</comment>

<file context>
@@ -0,0 +1,1039 @@
+{
+  "evidence": "Provider-free request syntax and static contract claims only. URLs are placeholders; no provider, payment or customer workflow is exercised.",
+  "sourceHash": "de67b0fecf1759ffad99f0f32eedd2e9b33e22c7feebcebfd961e4d26d21262e",
</file context>

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="content/docs/contracts/operation-inventory.json">

<violation number="1" location="content/docs/contracts/operation-inventory.json:2">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**

This inventory still pins the reviewed API SHA, although the PR description requires the actual API merge commit before release. Regenerate the inventory against the merged API checkout so `apiSourceCommit` matches `git rev-parse HEAD`.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

@@ -1,5 +1,5 @@
{
"apiSourceCommit": "2a882dd460ef6757af6d7b1b93bbc1fd8d0c6e86",
"apiSourceCommit": "0a590490c0e005045e4cbf399fe552dc41e6b9a3",

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: Custom agent: Flag AI Slop and Fabricated Changes

This inventory still pins the reviewed API SHA, although the PR description requires the actual API merge commit before release. Regenerate the inventory against the merged API checkout so apiSourceCommit matches git rev-parse HEAD.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At content/docs/contracts/operation-inventory.json, line 2:

<comment>This inventory still pins the reviewed API SHA, although the PR description requires the actual API merge commit before release. Regenerate the inventory against the merged API checkout so `apiSourceCommit` matches `git rev-parse HEAD`.</comment>

<file context>
@@ -1,5 +1,5 @@
 {
-  "apiSourceCommit": "a4315940ef61df1620ca169a6ba5a17e2d1b92f0",
+  "apiSourceCommit": "0a590490c0e005045e4cbf399fe552dc41e6b9a3",
   "evidence": "Static source only; tool discovery and OAuth host verification remain separate. Conditional registration and scope filters mean this is not a promised catalog count.",
   "operations": [
</file context>

@sidneyswift
sidneyswift merged commit 62cc352 into main Oct 13, 2026
5 checks passed

This branch was successfully deployed

1 active deployment
Preview — d315d6ce Deployed Oct 13, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant