docs: clarify client connection checks

Author: masterkain

README.md

@@ -110,10 +110,12 @@ for example `https://codex-pooler.example.com`.
 
 ![Codex Pooler OpenCode integration](.github/assets/codex-pooler-opencode.png)
 
-OpenCode talks to Codex Pooler through the OpenAI-compatible `/v1` surface. The
-provider uses the Pool API key, and the optional remote MCP entry uses an
-operator-owned MCP token. MCP is not required for OpenCode to use Codex Pooler;
-it only gives an operator MCP host read-only metadata tools. Its websocket
+OpenCode talks to Codex Pooler through the OpenAI-compatible `/v1` surface. Keep
+the provider id as `openai` for this setup so OpenCode continues to use its
+OpenAI provider-family behavior. The provider uses the Pool API key, and the
+optional remote MCP entry uses an operator-owned MCP token. MCP is not required
+for OpenCode to use Codex Pooler; it only gives an operator MCP host read-only
+metadata tools. Its websocket
 support is the narrow Responses websocket route at `GET /v1/responses`, not
 OpenAI Realtime SDK compatibility.
 
@@ -414,12 +416,12 @@ hermes -z 'Reply with exactly: hermes openai api ok' --ignore-rules
 ```
 
 Hermes can also be made to use its `openai-codex` provider against Codex
-Pooler. This is less direct because Hermes treats `openai-codex` as an OAuth
-provider by default; add a Pool API key credential ahead of any existing
+Pooler, but this alternate path is less direct because Hermes treats `openai-codex` as an
+OAuth provider by default; add a Pool API key credential ahead of any existing
 device-code credential and keep the entry's `base_url` on `/v1`. Use this only
 when you specifically need Hermes' `openai-codex` credential-pool behavior; the
-`openai-api` configuration above is the preferred setup. This variant stores
-the key in `auth.json` because Hermes credential pools live there.
+`openai-api` configuration above is the preferred setup. This variant stores the
+key in `auth.json` because Hermes credential pools live there.
 
 ```bash
 HERMES_CODEX_BASE_URL=http://localhost:4000/v1
@@ -688,8 +690,8 @@ do not set `"permission": "ask"`, which is not a valid config shape.
 Check the headless tool path from an isolated directory:
 
 ```bash
-mkdir -p /tmp/codex-pooler-kilo-smoke
-cd /tmp/codex-pooler-kilo-smoke
+mkdir -p /tmp/codex-pooler-kilo-check
+cd /tmp/codex-pooler-kilo-check
 
 export CODEX_POOLER_API_KEY=<pool-api-key>
 kilo run \
@@ -720,13 +722,24 @@ model: openai/gpt-5.5
 openai-api-base: http://localhost:4000/v1
 ```
 
-Smoke-test from a repository:
+Check Aider from a repository with a real file edit:
 
 ```bash
 export OPENAI_API_KEY="$CODEX_POOLER_API_KEY"
-aider --model openai/gpt-5.5 --message 'Reply with exactly: aider ok'
+aider --model openai/gpt-5.5 \
+  --openai-api-base http://localhost:4000/v1 \
+  --message 'Create a file named aider-ok.txt containing exactly: aider ok. After the file exists, reply with exactly: aider ok' \
+  --yes-always \
+  --no-auto-commits \
+  --no-git \
+  --no-browser \
+  --no-gui \
+  --no-analytics
 ```
 
+The check is only useful if the file exists with the expected content; a text
+reply alone does not prove Aider can edit through the configured model path.
+
 For deployed instances, change `openai-api-base` to
 `https://codex-pooler.example.com/v1`.
 
@@ -1305,7 +1318,7 @@ web app to one replica because backend
 websocket continuity owns a live upstream websocket in an app pod. Owner-alive
 cross-node forwarding is wired, but scaling web replicas still requires
 clustering, owner-forwarding, and the explicit unsafe topology acknowledgement
-until Kubernetes smoke evidence relaxes that guard.
+until Kubernetes deployment validation relaxes that guard.
 
 The Helm migration hook runs database migrations and imports the vendored OpenAI
 pricing feed so request-log cost reporting has pricing snapshots after install

docs-site/src/content/docs/clients/aider.mdx

@@ -19,11 +19,21 @@ model: openai/gpt-5.5
 openai-api-base: http://localhost:4000/v1
 ```
 
-Smoke-test from a repository:
+Check Aider from a repository with a real file edit:
 
 ```bash
 export OPENAI_API_KEY="$CODEX_POOLER_API_KEY"
-aider --model openai/gpt-5.5 --message 'Reply with exactly: aider ok'
+aider --model openai/gpt-5.5 \
+  --openai-api-base https://codex-pooler.example.com/v1 \
+  --message 'Create a file named aider-ok.txt containing exactly: aider ok. After the file exists, reply with exactly: aider ok' \
+  --yes-always \
+  --no-auto-commits \
+  --no-git \
+  --no-browser \
+  --no-gui \
+  --no-analytics
 ```
 
+The check is only useful if `aider-ok.txt` exists with the expected content; a text reply alone does not prove Aider can edit through the configured model path. For local setup, change `--openai-api-base` to `http://localhost:4000/v1`.
+
 The Pool API key authenticates `/v1` model requests. Do not use an operator MCP token as the OpenAI API key.

docs-site/src/content/docs/clients/codex-cli.mdx

@@ -13,7 +13,7 @@ For a deployed instance, the Codex backend base URL is:
 https://codex-pooler.example.com/backend-api/codex
 ```
 
-For local setup and local smoke checks, use:
+For local setup and local connection checks, use:
 
 ```text
 http://localhost:4000/backend-api/codex

docs-site/src/content/docs/clients/hermes.mdx

@@ -75,7 +75,7 @@ That test should create normal `/v1` traffic using the Pool API key. The MCP ent
 
 ## Alternate `openai-codex` credential-pool path
 
-Hermes can also use its `openai-codex` provider against Codex Pooler, but this path is less direct. Hermes treats `openai-codex` as an OAuth provider by default, so add a Pool API key credential ahead of any device-code credential and keep the credential `base_url` on `/v1`.
+Hermes can also use its `openai-codex` provider against Codex Pooler, but this alternate path is less direct. The preferred setup is the `openai-api` provider above with `api_mode: codex_responses`. Hermes treats `openai-codex` as an OAuth provider by default, so add a Pool API key credential ahead of any device-code credential and keep the credential `base_url` on `/v1`.
 
 Keep endpoint and MCP token values in the environment:
 

docs-site/src/content/docs/clients/kilo.mdx

@@ -61,13 +61,13 @@ For local setup, change `baseURL` to `http://localhost:4000/v1`.
 
 Kilo is a chat-completions client. It sends model requests to `POST /v1/chat/completions`, and Codex Pooler translates supported chat-completions requests into Codex Responses work internally. Do not point Kilo at `/backend-api/codex`, `/v1/responses`, or `/v1/chat/completions` as the configured base URL.
 
-## Smoke check
+## Connection Check
 
 Run a tool-using prompt from an isolated directory:
 
 ```bash
-mkdir -p /tmp/codex-pooler-kilo-smoke
-cd /tmp/codex-pooler-kilo-smoke
+mkdir -p /tmp/codex-pooler-kilo-check
+cd /tmp/codex-pooler-kilo-check
 
 export CODEX_POOLER_API_KEY=<pool-api-key>
 kilo run \

docs-site/src/content/docs/clients/omp.mdx

@@ -71,7 +71,7 @@ modelRoles:
 
 `startup.setupWizard: false` keeps OMP from opening the initial setup flow after the provider and roles are already configured.
 
-## Smoke check
+## Connection Check
 
 Run a one-shot prompt from the repository you want OMP to inspect:
 

docs-site/src/content/docs/clients/opencode.mdx

@@ -5,7 +5,7 @@ description: Configure OpenCode with Codex Pooler's narrow OpenAI-compatible /v1
 
 ![Codex Pooler OpenCode integration](/codex-pooler-opencode.png)
 
-OpenCode should use Codex Pooler through the narrow OpenAI-compatible `/v1` surface. The Pool API key authenticates model requests. A separate operator MCP token authenticates the optional remote MCP endpoint. MCP is not required for OpenCode to use Codex Pooler; it only gives an operator MCP host read-only metadata tools.
+OpenCode should use Codex Pooler through the narrow OpenAI-compatible `/v1` surface. Keep the provider id as `openai` for this setup so OpenCode continues to use its OpenAI provider-family behavior. The Pool API key authenticates model requests. A separate operator MCP token authenticates the optional remote MCP endpoint. MCP is not required for OpenCode to use Codex Pooler; it only gives an operator MCP host read-only metadata tools.
 
 OpenCode websocket support is the narrow Responses websocket route at `GET /v1/responses`, not OpenAI Realtime SDK compatibility.
 
@@ -93,6 +93,8 @@ Use a dedicated operator MCP token for hosts that persist remote MCP headers. Do
 
 ## Compatibility notes
 
+If you automate OpenCode from scripts, use OpenCode's own documented headless command shape for your installed version and verify both the final response and the expected file changes. The examples on this page focus on configuration, not a full automation workflow.
+
 Codex Pooler provides narrow OpenAI-compatible `/v1` support for selected SDK routes. Supported OpenCode traffic should stay on `/v1/responses` or `/v1/chat/completions`, depending on the OpenAI provider path OpenCode uses.
 
 `GET /v1/responses` is narrow Responses websocket compatibility, not `/v1/realtime` support. `/v1/realtime` and OpenAI Realtime SDK websocket or session routes are unsupported.

docs-site/src/content/docs/clients/pi.mdx

@@ -65,7 +65,7 @@ If you want plain `pi` or `pi -p ...` to start on Codex Pooler, add the defaults
 }
 ```
 
-## Smoke check
+## Connection Check
 
 Run a one-shot prompt from the repository you want Pi to inspect:
 
@@ -79,7 +79,7 @@ pi --provider codex-pooler \
   -p 'Reply with exactly: pi ok'
 ```
 
-`--no-session` keeps the check ephemeral. `--no-context-files` keeps the smoke independent from local project instructions. For normal interactive use, omit those flags if you want Pi to load `AGENTS.md`, skills, sessions, and project settings.
+`--no-session` keeps the check ephemeral. `--no-context-files` keeps it independent from local project instructions. For normal interactive use, omit those flags if you want Pi to load `AGENTS.md`, skills, sessions, and project settings.
 
 ## MCP boundary
 

docs-site/src/content/docs/clients/windmill.mdx

@@ -111,7 +111,7 @@ windmill:
 This setting belongs to Windmill, not Codex Pooler. Use it only when the
 Codex Pooler base URL is intentionally private from Windmill's point of view.
 
-## Smoke test through Windmill
+## Connection Check Through Windmill
 
 After saving the resource and workspace AI settings, call Windmill's AI proxy
 route. Use a Windmill user token for the Windmill API request and let Windmill