docs: document every API operation and check the contract against the code

apps/docs/app/[[...slug]]/page.tsx

@@ -22,7 +22,7 @@ export default async function DocsPageRoute({
 
   const MDX = page.data.body
   return (
-    <DocsPage toc={page.data.toc}>
+    <DocsPage toc={page.data.toc} full={page.data.full}>
       <DocsTitle>{page.data.title}</DocsTitle>
       <DocsDescription>{page.data.description}</DocsDescription>
       <DocsBody>

apps/docs/app/global.css

@@ -101,3 +101,21 @@ body {
 ::selection {
   background: color-mix(in srgb, var(--color-fd-primary) 22%, transparent);
 }
+
+/* A folded operation description: the contract's full prose stays on the page
+   without pushing the request and response sections below the fold. */
+.prose details.api-details {
+  margin: 1rem 0;
+  padding: 0.25rem 0.75rem;
+  border: 1px solid var(--color-fd-border);
+  border-radius: 0.5rem;
+  background: color-mix(in srgb, var(--color-fd-muted) 35%, transparent);
+}
+
+.prose details.api-details > summary {
+  padding: 0.35rem 0;
+  color: var(--color-fd-muted-foreground);
+  font-size: 0.8125rem;
+  font-weight: 600;
+  cursor: pointer;
+}

apps/docs/app/layout.tsx

@@ -16,7 +16,16 @@ export default function RootLayout({ children }: { children: ReactNode }) {
     <html lang="en" suppressHydrationWarning>
       <body suppressHydrationWarning>
         <DocsProviders>
-          <DocsLayout tree={source.pageTree} {...baseOptions}>{children}</DocsLayout>
+          <DocsLayout
+            tree={source.pageTree}
+            {...baseOptions}
+            // Every visible sidebar link would otherwise prefetch its whole
+            // page: expanding one API tag downloaded several MB of operation
+            // schemas before any click. Pages load on click instead.
+            sidebar={{ prefetch: false }}
+          >
+            {children}
+          </DocsLayout>
         </DocsProviders>
       </body>
     </html>

apps/docs/components/api-page.tsx

@@ -9,5 +9,15 @@ export async function APIPage({
   ...props
 }: Omit<ApiPageProps, "document"> & { document: string }) {
   // References never collect credentials or dispatch requests from the browser.
-  return <OpenAPIPage {...props} document={await loadSurface(document)} disablePlayground={true} />
+  // Response schemas are shown in full; generating a TypeScript copy of every
+  // response for every status compiled the same schemas again and was about
+  // half of each page's render time.
+  return (
+    <OpenAPIPage
+      {...props}
+      document={await loadSurface(document)}
+      disablePlayground={true}
+      generateTypeScriptSchema={false}
+    />
+  )
 }

apps/docs/content/docs/api-reference/agents/create-a-reusable-agent.mdx

@@ -0,0 +1,53 @@
+---
+title: Create a reusable Agent
+description: Persists configuration independently of execution.
+full: true
+_openapi:
+  method: POST
+  route: /agents
+  toc: []
+  structuredData:
+    headings: []
+    contents:
+      - content: >-
+          Persists configuration independently of execution. Names over 128 characters and metadata
+          outside 16 string pairs with 64-character keys and 512-character values return
+          invalid_request_error with the official param; U+0000 in stored strings is rejected as a
+          local storage limit. As on every Agents API JSON route, a non-JSON Content-Type, invalid
+          UTF-8, malformed JSON, a repeated key at any depth or a non-object root returns
+          invalid_request_error with a null param and the official message before other checks; an
+          empty or null body is {}. Missing, unknown, wrongly typed or unsupported enum members of
+          the pinned configuration shapes (tools, text, reasoning, service_tier, multi_agent) return
+          invalid_request_error with the JSON path as param; duplicate function names, repeated
+          web_search or tool_search and non-object schema root types return it with a null param.
+          Supports model/name/instructions/metadata, explicit reasoning and service tiers,
+          multi_agent, text/json_schema, function/tool_search/programmatic_tool_calling/web_search
+          and HTTP MCP with nullable credential_id, service origin (omitted or null on HTTP
+          transport is saved as service) and boolean required defaulting to false. Saving
+          credential_id grants no access: Session admission checks attached Vault ownership and
+          destination. MCP allowed_tools preserves null versus empty; saved HTTP transport includes
+          empty headers. Model-derived reasoning defaults, other MCP variants and public retry
+          conformance remain incomplete. web_search saves every pinned mode: omitted or null mode is
+          saved as live and omitted or null context_size as medium; allowed_domains preserves null
+          versus empty and a present location, including {}, includes all four keys with null for
+          omitted ones, as observed officially (req_db41d2f6261b4abfb69465eafe719ab5,
+          req_165d53b88445490b9146d8272c54134d). Session execution accepts only explicit disabled
+          web_search and disabled programmatic_tool_calling through qualified Runtime controls;
+          saved enabled forms reject at Session admission. Session execution admits only its
+          supported configuration subset.
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+<details className="api-details">
+<summary>Full description</summary>
+
+Names over 128 characters and metadata outside 16 string pairs with 64-character keys and 512-character values return invalid_request_error with the official param; U+0000 in stored strings is rejected as a local storage limit. As on every Agents API JSON route, a non-JSON Content-Type, invalid UTF-8, malformed JSON, a repeated key at any depth or a non-object root returns invalid_request_error with a null param and the official message before other checks; an empty or null body is &#123;&#125;. Missing, unknown, wrongly typed or unsupported enum members of the pinned configuration shapes (tools, text, reasoning, service_tier, multi_agent) return invalid_request_error with the JSON path as param; duplicate function names, repeated web_search or tool_search and non-object schema root types return it with a null param.
+
+Supports model/name/instructions/metadata, explicit reasoning and service tiers, multi_agent, text/json_schema, function/tool_search/programmatic_tool_calling/web_search and HTTP MCP with nullable credential_id, service origin (omitted or null on HTTP transport is saved as service) and boolean required defaulting to false. Saving credential_id grants no access: Session admission checks attached Vault ownership and destination. MCP allowed_tools preserves null versus empty; saved HTTP transport includes empty headers.
+
+Model-derived reasoning defaults, other MCP variants and public retry conformance remain incomplete. web_search saves every pinned mode: omitted or null mode is saved as live and omitted or null context_size as medium; allowed_domains preserves null versus empty and a present location, including &#123;&#125;, includes all four keys with null for omitted ones, as observed officially (req_db41d2f6261b4abfb69465eafe719ab5, req_165d53b88445490b9146d8272c54134d). Session execution accepts only explicit disabled web_search and disabled programmatic_tool_calling through qualified Runtime controls; saved enabled forms reject at Session admission. Session execution admits only its supported configuration subset.
+
+</details>
+
+<APIPage document={"public-api"} operations={[{"path":"/agents","method":"post"}]} webhooks={[]} hasHead={false} />

apps/docs/content/docs/api-reference/agents/delete-a-reusable-agent.mdx

@@ -0,0 +1,23 @@
+---
+title: Delete a reusable Agent
+description: Deletes only the authenticated tenant's saved configuration.
+full: true
+_openapi:
+  method: DELETE
+  route: /agents/{agent_id}
+  toc: []
+  structuredData:
+    headings: []
+    contents:
+      - content: >-
+          Deletes only the authenticated tenant's saved configuration. Existing Session snapshots,
+          history and recorded creation retry identities remain independent. Missing and repeated
+          deletion locally return404; exact hosted error and in-flight creation/deletion semantics
+          remain unverified.
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+Existing Session snapshots, history and recorded creation retry identities remain independent. Missing and repeated deletion locally return404; exact hosted error and in-flight creation/deletion semantics remain unverified.
+
+<APIPage document={"public-api"} operations={[{"path":"/agents/{agent_id}","method":"delete"}]} webhooks={[]} hasHead={false} />

apps/docs/content/docs/api-reference/agents/index.mdx

@@ -0,0 +1,14 @@
+---
+title: "Agents"
+description: "Agents. Application API: Project API key."
+---
+
+Public schema constrained by the pinned OpenAI Agents API baseline; documented x_agents_core fields remain Core extensions.
+
+| Operation | Method | Path |
+| --- | --- | --- |
+| [List reusable Agents](/api-reference/agents/list-reusable-agents) | `GET` | `/v1/agents` |
+| [Create a reusable Agent](/api-reference/agents/create-a-reusable-agent) | `POST` | `/v1/agents` |
+| [Retrieve a reusable Agent](/api-reference/agents/retrieve-a-reusable-agent) | `GET` | `/v1/agents/{agent_id}` |
+| [Update a reusable Agent](/api-reference/agents/update-a-reusable-agent) | `POST` | `/v1/agents/{agent_id}` |
+| [Delete a reusable Agent](/api-reference/agents/delete-a-reusable-agent) | `DELETE` | `/v1/agents/{agent_id}` |

apps/docs/content/docs/api-reference/agents/list-reusable-agents.mdx

@@ -0,0 +1,23 @@
+---
+title: List reusable Agents
+description: Lists only the authenticated tenant's saved Agents, independently of Sessions.
+full: true
+_openapi:
+  method: GET
+  route: /agents
+  toc: []
+  structuredData:
+    headings: []
+    contents:
+      - content: >-
+          Lists only the authenticated tenant's saved Agents, independently of Sessions. Limit 0 is
+          treated as 1 and larger limits as 100, as observed on the hosted service. The local
+          default is 20; exact upstream default/cap and empty cursor fields remain unverified. An
+          unknown, malformed or foreign after cursor returns not found.
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+Limit 0 is treated as 1 and larger limits as 100, as observed on the hosted service. The local default is 20; exact upstream default/cap and empty cursor fields remain unverified. An unknown, malformed or foreign after cursor returns not found.
+
+<APIPage document={"public-api"} operations={[{"path":"/agents","method":"get"}]} webhooks={[]} hasHead={false} />

apps/docs/content/docs/api-reference/agents/meta.json

@@ -0,0 +1,10 @@
+{
+  "title": "Agents",
+  "pages": [
+    "list-reusable-agents",
+    "create-a-reusable-agent",
+    "retrieve-a-reusable-agent",
+    "update-a-reusable-agent",
+    "delete-a-reusable-agent"
+  ]
+}

apps/docs/content/docs/api-reference/agents/retrieve-a-reusable-agent.mdx

@@ -0,0 +1,19 @@
+---
+title: Retrieve a reusable Agent
+description: Reads the saved resource owned by the authenticated tenant, independently of execution Sessions.
+full: true
+_openapi:
+  method: GET
+  route: /agents/{agent_id}
+  toc: []
+  structuredData:
+    headings: []
+    contents:
+      - content: >-
+          Reads the saved resource owned by the authenticated tenant, independently of execution
+          Sessions.
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+<APIPage document={"public-api"} operations={[{"path":"/agents/{agent_id}","method":"get"}]} webhooks={[]} hasHead={false} />

apps/docs/content/docs/api-reference/agents/update-a-reusable-agent.mdx

@@ -0,0 +1,33 @@
+---
+title: Update a reusable Agent
+description: Preserves omitted fields and replaces supplied fields using shared saved-configuration validation.
+full: true
+_openapi:
+  method: POST
+  route: /agents/{agent_id}
+  toc: []
+  structuredData:
+    headings: []
+    contents:
+      - content: >-
+          Preserves omitted fields and replaces supplied fields using shared saved-configuration
+          validation. Null name/instructions clear; null or empty metadata clears all pairs. Name,
+          metadata and configuration validation errors return invalid_request_error with the
+          official param, using the Agent create rules before the Agent lookup. Existing Session
+          snapshots are unchanged. Empty updates advance updated_at without changing saved fields.
+          Nested replacement/null defaults, model-derived reasoning and exact hosted error behavior
+          remain incompletely verified.
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+<details className="api-details">
+<summary>Full description</summary>
+
+Null name/instructions clear; null or empty metadata clears all pairs. Name, metadata and configuration validation errors return invalid_request_error with the official param, using the Agent create rules before the Agent lookup. Existing Session snapshots are unchanged.
+
+Empty updates advance updated_at without changing saved fields. Nested replacement/null defaults, model-derived reasoning and exact hosted error behavior remain incompletely verified.
+
+</details>
+
+<APIPage document={"public-api"} operations={[{"path":"/agents/{agent_id}","method":"post"}]} webhooks={[]} hasHead={false} />