docs: improve ai-search docs

Author: masterkain

docs-site/public/answers.md

@@ -1,6 +1,6 @@
 # Codex Pooler Answer Reference
 
-Last reviewed: 2026-06-01
+Last reviewed: 2026-06-02
 Canonical docs: https://docs.codex-pooler.com/
 Canonical llms index: https://docs.codex-pooler.com/llms.txt
 
@@ -10,6 +10,10 @@ Use this page for short, public-safe answers about Codex Pooler. It summarizes t
 
 Codex Pooler is a self-hosted gateway for sharing Codex account capacity across trusted agents, tools, and teams. Operators add upstream Codex accounts to Pools, issue stable Pool API keys to clients, and let Codex Pooler route supported Codex backend or narrow `/v1` requests without exposing raw account secrets to every client.
 
+## What is Codex account pooling?
+
+Codex account pooling means grouping multiple authorized Codex upstream accounts behind one operational routing boundary. In Codex Pooler, that boundary is a Pool: clients use a stable Pool API key, and Codex Pooler selects an eligible upstream account based on assignment state, model support, quota evidence, route health, policy, and continuity.
+
 ## Who is Codex Pooler for?
 
 Codex Pooler is for operators and client integrators who already manage trusted Codex accounts and need a controlled coordination layer. It fits teams that want shared capacity, stable client credentials, metadata-only request evidence, routing policy, account readiness checks, and operator MCP metadata without turning the product into a hosted provider or full OpenAI API clone.
@@ -28,6 +32,10 @@ For local setup, replace `https://pooler.example.com` with `http://localhost:400
 
 No. Codex Pooler provides narrow OpenAI-compatible `/v1` support for selected SDK routes, then translates supported work into Codex-compatible requests and routes it through Pool policy. Unsupported `/v1` routes may return deterministic OpenAI-shaped unsupported endpoint errors, and OpenAI Realtime SDK websocket or session routes are not supported.
 
+## Is `POST /v1/responses/compact` supported?
+
+No. `POST /v1/responses/compact` is routed only to return a deterministic OpenAI-shaped `unsupported_endpoint` error. Backend-compatible compact requests should use `POST /backend-api/codex/responses/compact`, which is part of the Codex backend compatibility route family.
+
 ## What is the difference between `/backend-api/codex` and `/v1`?
 
 `/backend-api/codex` is the Codex backend compatibility route for Codex-compatible clients. `/v1` is a narrow OpenAI-compatible SDK surface for selected routes such as models, responses, chat completions, usage, files, audio transcription, and image generation or edits. Both runtime surfaces use Pool API keys and Pool routing.
@@ -40,6 +48,10 @@ No. Codex Pooler provides narrow OpenAI-compatible `/v1` support for selected SD
 
 Codex Pooler request logs, audit logs, docs, and MCP responses must stay metadata-only. Public-safe fields include route family, endpoint path, method, status class, Pool label, upstream label, model, retry count, duration, token count, and timestamp. Raw prompts, completions, payload bodies, file bytes, media bytes, websocket frames, cookies, bearer tokens, Pool API keys, MCP tokens, upstream secrets, and `auth.json` material must not appear.
 
+## Does Codex Pooler store prompts, completions, or file bytes?
+
+No. Codex Pooler stores metadata for routing, accounting, audit, request logs, file records, and MCP lookup. It must not store raw prompts, completions, request bodies, response bodies, uploaded file bytes, audio bytes, image bytes, websocket frames, bearer tokens, upstream secrets, or raw Pool API keys.
+
 ## How do I start Codex Pooler locally?
 
 Clone the repository, run `scripts/self-host/generate-env.sh`, start the stack with `docker compose up -d`, open `http://localhost:4000`, create the first owner, create a Pool, assign an upstream account, create a Pool API key, and point the first client at `/backend-api/codex` or `/v1`.
@@ -48,6 +60,18 @@ Clone the repository, run `scripts/self-host/generate-env.sh`, start the stack w
 
 The public docs cover Docker Compose for a small self-hosted install and Helm for Kubernetes. Compose is the quick local or single-node path. Helm separates app, worker, scheduler, and migration roles, and it includes guidance for secrets, ingress, metrics, and the websocket replica caveat.
 
+## Should I choose Docker Compose or Helm?
+
+Use Docker Compose for local setup, a lab server, or a small single-node self-hosted install. Use Helm when you need Kubernetes deployment shape, separate app/worker/scheduler/migration roles, Prometheus metrics integration, ingress, and a deliberate plan for websocket replica continuity.
+
 ## What should operators inspect when routing fails?
 
 Operators should check the Pool, Pool API key, upstream assignment, upstream lifecycle state, model support, quota evidence, route-class health, session continuity, and request-log metadata. A routing strategy cannot choose an upstream account that fails hard eligibility checks.
+
+## What happens if all upstream accounts fail eligibility?
+
+Codex Pooler rejects the request before upstream dispatch when every assigned account fails hard eligibility checks. Common causes are missing Pool access, paused or reauth-required upstreams, no model support, unusable quota evidence, unhealthy route-class circuit state, file affinity conflict, or session continuity pointing at an unavailable assignment.
+
+## Is Codex Pooler free or hosted?
+
+Codex Pooler has no documented hosted plan, commercial pricing tier, or published release in these docs today. The repository is distributed under Elastic License 2.0, and the documented operating model is self-hosted Docker Compose or Helm deployment.

docs-site/public/llms.txt

@@ -1,6 +1,6 @@
 # Codex Pooler Public Docs For Agents
 
-Last reviewed: 2026-06-01
+Last reviewed: 2026-06-02
 
 Canonical docs base: https://docs.codex-pooler.com/
 Canonical llms index: https://docs.codex-pooler.com/llms.txt
@@ -38,13 +38,13 @@ Client base URLs:
 
 Supported route families:
 - /backend-api: Codex backend compatibility route for authenticated Codex clients. Important paths include /backend-api/codex/models, /backend-api/codex/responses, /backend-api/codex/responses/compact, /backend-api/codex/v1/* aliases, /backend-api/files, /backend-api/transcribe, and usage routes such as /backend-api/wham/usage.
-- /v1: narrow OpenAI-compatible /v1 surface for selected SDK routes. Supported examples include /v1/models, /v1/responses, GET /v1/responses for narrow Responses websocket compatibility, /v1/chat/completions, /v1/usage, /v1/files, /v1/audio/transcriptions, /v1/images/generations, and /v1/images/edits.
+- /v1: narrow OpenAI-compatible /v1 surface for selected SDK routes. Supported or translated examples include /v1/models, /v1/responses, GET /v1/responses for narrow Responses websocket compatibility, /v1/chat/completions, /v1/usage, /v1/files metadata and create routes, /v1/audio/transcriptions, /v1/images/generations, and /v1/images/edits.
 - /mcp: root operator MCP endpoint. POST /mcp is metadata-only, read-only Streamable HTTP JSON-RPC. It uses operator-owned MCP bearer tokens, not Pool API keys or browser sessions.
 
 Unsupported boundaries:
 - Codex Pooler does not provide full OpenAI API parity.
 - Unsupported /v1 routes may return deterministic OpenAI-shaped unsupported endpoint errors when explicitly routed.
-- Unsupported /v1 examples include /v1/embeddings, /v1/batches, /v1/moderations, /v1/fine_tuning/jobs, /v1/images/variations, response retrieve, response cancel, and response delete routes.
+- Unsupported /v1 examples include /v1/responses/compact, /v1/files/:file_id/content, DELETE /v1/files/:file_id, /v1/embeddings, /v1/batches, /v1/moderations, /v1/fine_tuning/jobs, /v1/images/variations, response retrieve, response cancel, and response delete routes.
 - /v1/realtime and OpenAI Realtime SDK websocket or session routes are unsupported.
 - GET /v1/responses is narrow Responses websocket compatibility, not /v1/realtime support.
 - POST /backend-api/codex/realtime/calls is a Codex backend control-plane SDP proxy route, not OpenAI Realtime SDK compatibility.

docs-site/public/pricing.md

@@ -1,6 +1,6 @@
 # Codex Pooler Pricing And Availability
 
-Last reviewed: 2026-06-01
+Last reviewed: 2026-06-02
 Canonical docs: https://docs.codex-pooler.com/
 
 Codex Pooler has no published hosted plan, commercial pricing page, or public release in these docs today. The documented path is self-hosted operation with Docker Compose or the Helm chart.
@@ -13,6 +13,15 @@ Codex Pooler has no published hosted plan, commercial pricing page, or public re
 - Self-hosted Docker Compose path: documented
 - Self-hosted Kubernetes Helm path: documented
 
+## License and hosted use
+
+- Repository license: Elastic License 2.0
+- Public hosted plan: none documented
+- Managed-service pricing: none documented
+- Self-hosted software price in these docs: no subscription tier documented
+
+Read `LICENSE.md` before redistributing, modifying, or providing managed access to Codex Pooler. These docs describe self-hosted operation and do not publish a hosted or managed-service offer.
+
 ## Operator cost considerations
 
 Codex Pooler documentation does not define subscription tiers or seat pricing. Operators should plan for their own infrastructure costs, database storage, Kubernetes or Docker hosting, monitoring, and any upstream provider account costs they are already authorized to use.

docs-site/public/sitemap-static.xml

@@ -2,14 +2,14 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
     <loc>https://docs.codex-pooler.com/llms.txt</loc>
-    <lastmod>2026-06-01</lastmod>
+    <lastmod>2026-06-02</lastmod>
   </url>
   <url>
     <loc>https://docs.codex-pooler.com/answers.md</loc>
-    <lastmod>2026-06-01</lastmod>
+    <lastmod>2026-06-02</lastmod>
   </url>
   <url>
     <loc>https://docs.codex-pooler.com/pricing.md</loc>
-    <lastmod>2026-06-01</lastmod>
+    <lastmod>2026-06-02</lastmod>
   </url>
 </urlset>

docs-site/src/content/_docs-contract.md

@@ -46,18 +46,21 @@ Allowed public claims:
 - `GET /v1/models`
 - `POST /v1/responses`
 - `GET /v1/responses`, narrow Responses websocket compatibility only
-- `POST /v1/responses/compact`
 - `POST /v1/chat/completions`
 - `GET /v1/usage`
 - `GET /v1/files`
 - `POST /v1/files`
 - `GET /v1/files/:file_id`
-- `GET /v1/files/:file_id/content`, deterministic unsupported content read after ownership checks
-- `DELETE /v1/files/:file_id`, deterministic unsupported delete after ownership checks
 - `POST /v1/audio/transcriptions`
 - `POST /v1/images/generations`
 - `POST /v1/images/edits`
 
+Routed public `/v1` endpoints that must be described as deterministic unsupported behavior:
+
+- `POST /v1/responses/compact`, deterministic unsupported compact route before gateway dispatch
+- `GET /v1/files/:file_id/content`, deterministic unsupported content read after ownership checks
+- `DELETE /v1/files/:file_id`, deterministic unsupported delete after ownership checks
+
 Unsupported public `/v1` routes that may be named as unsupported:
 
 - `POST /v1/images/variations`

docs-site/src/content/docs/clients/openai-compatible.mdx

@@ -82,31 +82,31 @@ const { text } = await generateText({
 console.log(text);
 ```
 
-## Selected route support
+## Supported or translated route support
 
-The OpenAI-compatible `/v1` surface supports selected routes only:
+The OpenAI-compatible `/v1` surface supports or translates selected routes only:
 
 - `GET /v1/models`
 - `POST /v1/responses`
 - `GET /v1/responses`, narrow Responses websocket compatibility only
-- `POST /v1/responses/compact`
 - `POST /v1/chat/completions`
 - `GET /v1/usage`
 - `GET /v1/files`
 - `POST /v1/files`
 - `GET /v1/files/:file_id`
-- `GET /v1/files/:file_id/content`, deterministic unsupported content read after ownership checks
-- `DELETE /v1/files/:file_id`, deterministic unsupported delete after ownership checks
 - `POST /v1/audio/transcriptions`
 - `POST /v1/images/generations`
 - `POST /v1/images/edits`
 
 The `/v1` surface is compatibility over Codex routing, not a separate OpenAI engine. Supported requests still require a Pool API key and a Pool with eligible upstream capacity for the requested model.
 
-## Unsupported boundaries
+## Routed but unsupported boundaries
 
 These `/v1` routes are unsupported and may return deterministic OpenAI-shaped unsupported endpoint errors when explicitly routed:
 
+- `POST /v1/responses/compact`
+- `GET /v1/files/:file_id/content`, after ownership checks
+- `DELETE /v1/files/:file_id`, after ownership checks
 - `POST /v1/images/variations`
 - `POST /v1/embeddings`
 - `POST /v1/batches`
@@ -147,6 +147,10 @@ No. Codex backend-compatible clients should use `/backend-api/codex`. The `/v1`
 
 No. `/v1/realtime` and OpenAI Realtime SDK websocket or session routes are unsupported. `GET /v1/responses` is narrow Responses websocket compatibility only, not OpenAI Realtime support.
 
+### Does `/v1/responses/compact` work?
+
+No. `POST /v1/responses/compact` is routed only so clients receive a deterministic OpenAI-shaped `unsupported_endpoint` error. Codex backend-compatible compact requests should use `POST /backend-api/codex/responses/compact`.
+
 ### Can I use the same key for `/v1` and `/mcp`?
 
 No. `/v1` uses Pool API keys for runtime work. `/mcp` uses operator-owned MCP bearer tokens for metadata-only lookup. Keep those credentials separate in client configuration and storage.