@fayegram-ai/decision-bridge 0.0.0-stage → 0.1.0

package/docs/guides/OPENAI_DECISIONS.md

@@ -0,0 +1,210 @@
+# OpenAI Decisions
+
+The `openai-decisions` provider implements the native `POST /v1/decisions` API,
+supporting `gpt-6-luna` as its default and only accepted model in this release.
+This integration follows the official [Decisions guide](https://developers.openai.com/api/docs/guides/decisions)
+and [API reference](https://developers.openai.com/api/reference/resources/decisions/methods/create).
+Account access and remote limits still apply. Unknown models fail locally with
+`UNSUPPORTED_CAPABILITY`. The opt-in `openai-compatible` preset in `custom/generative` continues
+using Chat Completions.
+
+## Common bridge access
+
+Set `OPENAI_API_KEY` in the process environment:
+
+```javascript
+import { createBridge, createProvider, choice, noul, scoreLevels } from '@fayegram-ai/decision-bridge';
+
+const provider = createProvider({ type: 'openai-decisions' });
+const bridge = createBridge({ provider });
+const result = await bridge.evaluate({
+    state: { complaint: 'I was charged twice.' },
+    questions: {
+        route: choice('Route the complaint.', { billing: 'Payments.', other: null }),
+        duplicate: noul('Does this describe a duplicate charge?'),
+        impact: scoreLevels('Rate the impact.', [
+            { label: 'Low', description: 'Small inconvenience.' },
+            { label: 'High', description: 'A required task is blocked.' },
+        ]),
+    },
+});
+console.log(result.answers.route.choice);
+```
+
+Existing state/question forms and answer shapes are retained. Strings remain
+unchanged; structured state, instructions, and descriptions become JSON text.
+Null choice descriptions are omitted. Legacy scores use zero-based native labels
+and preserve the original rubric in their common legend.
+
+`noul` without criteria, or with empty criteria, uses a native predicate. With
+true/false descriptions, it uses a native boolean choice carrying both options
+and the supplied descriptions; `noul` is the probability for boolean `true`.
+That native choice's confidence is retained in provider metadata.
+
+## Ordered text and images
+
+Provide exactly one of `state` or `input`. An existing JSON array supplied as
+`state` retains its original meaning. New `input` is a nonempty ordered array:
+
+```javascript
+const result = await bridge.evaluate({
+    input: [
+        { type: 'text', text: 'Assess this product photo.' },
+        { type: 'image', dataUrl: imageDataUrl, detail: 'high' },
+        { type: 'text', text: 'Consider only visible damage.' },
+    ],
+    safetyIdentifier: 'opaque-application-user-id',
+    questions: { damaged: noul('Is visible damage present?') },
+});
+```
+
+Images must be nonempty inline base64 data URLs, such as
+`data:image/png;base64,...`. The bridge does not fetch image URLs or read files.
+Convert image bytes in your application. OpenAI permits at most 128 images.
+Detail accepts `low`, `high`, `auto`, `original`, or null; omission uses the service
+default. Text/image ordering is preserved.
+
+The default transport request/response limits are 8 MiB each, including encoded
+images. Set `maxRequestBytes` explicitly for larger requests, up to the existing
+64 MiB ceiling. These local limits do not override service limits.
+
+`safetyIdentifier` is an optional per-request opaque string of at most 128
+Unicode characters, or null. It maps to `safety_identifier`; avoid private identity
+data. Character limits count Unicode code points rather than UTF-16 code units.
+
+## Typed choices and labelled scores
+
+The array overload of `choice` accepts `{ value: string | boolean, description? }`:
+
+```javascript
+const question = choice('Choose the matching outcome.', [
+    { value: true, description: 'The condition is satisfied.' },
+    { value: false, description: 'The condition is not satisfied.' },
+    { value: 'unknown', description: 'Insufficient evidence.' },
+]);
+```
+
+This question stores `options` instead of `criteria`. Its answer preserves the
+typed `choice` and uses `probabilities: [{ value, probability }, ...]`. Boolean
+`true` and string `"true"` are distinct; values must be unique. Numeric choices and
+coercion to object keys are not supported. TypeScript preserves literal unions.
+`decideChoice` supports these answers and typed abstention values.
+
+`scoreLevels` stores ordered `levels` instead of `criteria` and requires at least
+two `{ label, description? }` objects. Its answer retains the numeric score and
+index-keyed probability map, with the original level objects in the legend.
+OpenAI choice questions require 2–255 unique options in both common forms and
+native requests. Labelled scores do not inherit Jev's 10-level limit; legacy
+score criteria retain the 2–10-level limit. JSON snapshots and transport caps
+apply to all requests.
+
+## Capabilities and preparation
+
+`bridge.getCapabilities(model?)` synchronously reports support and limits for
+ordered input, images, typed choices, labelled scores, and safety identifiers.
+`bridge.validate(request)` resolves the model, snapshots/freezes the request,
+and checks capabilities without inference. Unsupported combinations fail before
+dispatch with `UNSUPPORTED_CAPABILITY`.
+
+Preflight also checks the encoded native field limits and the complete UTF-8 wire
+body against `maxRequestBytes`. SDK array batches check every raw request before
+dispatching any entry. Prepared input is revalidated during each evaluation.
+
+Jev, OpenAI-compatible, OpenRouter, and Anthropic currently support the legacy
+common forms. Existing custom providers default to that profile; implement
+`getCapabilities(model)` and corresponding behavior to support new forms.
+
+Use `prepareInput(parts, context)` for ordered input and `prepareState` for state.
+A preparation extension must implement the hook for the form being used;
+incompatible extensions fail explicitly rather than being skipped. Extensions
+can implement both hooks. `onResult` works with either form and runs only after
+success, with the existing isolated-failure policy.
+
+Legacy common requests retain `meta.schemaVersion: 1`. New input/question forms
+or safety identifiers use version 2.
+
+## Dedicated native access
+
+```javascript
+const { decision, meta } = await provider.createDecision({
+    input: 'The customer reports a broken screen.',
+    questions: [
+        { type: 'predicate', name: 'damaged', instructions: 'Is damage reported?' },
+        { type: 'choice', instructions: 'Choose a route.', choices: [
+            { value: 'repair' }, { value: 'review' },
+        ] },
+        { type: 'score', name: 'impact', instructions: 'Rate the impact.', levels: [
+            { label: 'Low' }, { label: 'High' },
+        ] },
+    ],
+    safety_identifier: 'opaque-application-user-id',
+}, { signal: controller.signal });
+```
+
+An omitted model resolves to the provider default. Native input accepts text or
+multiple user messages containing text or ordered `input_text`/`input_image`
+parts. Only user roles are supported. Files, external image URLs, audio, tools,
+and item references are rejected locally. Exported `NativeDecisionRequest` and
+related types describe this format.
+
+`decision` preserves native answer arrays, optional question names, probabilities,
+confidence, and full usage. `meta` contains transport duration, attempt count,
+and request ID when available. Results are immutable. This method bypasses
+common bridge extensions.
+
+## Refusals, results, and execution
+
+Both paths fail the complete call with `MODEL_REFUSAL` if any question is refused.
+They return no fabricated answer or partial success. The error retains validated
+`usage`, `refusedQuestions: [{ index, name }]`, and available HTTP diagnostics;
+it does not retain sibling answers or raw upstream bodies. JSONL batches mark
+that request `ok: false`; independent rows can succeed.
+
+Common confidence is preserved within its existing [0, 1] invariant. Native
+access validates finite confidence without imposing that common range or an
+undocumented argmax rule. Common validation rejects inconsistent responses
+rather than repairing them. Provider confidence semantics are not assumed to
+be equivalent or equally calibrated.
+
+Common usage maps reported input/output and cache counts.
+`meta.openaiDecisions.usage` preserves full native usage, including total and
+reasoning tokens. `meta.openaiDecisions.answers` retains native answer types and
+reported confidence. Predicate confidence and token counts are never invented.
+
+Decisions defaults to **zero HTTP retries**. Explicit `maxRetries` opts into the
+existing bounded policy and may repeat a billed request. There is no model
+fallback, streaming, generation-parameter passthrough, or model listing.
+`bridge.listModels()` fails with `UNSUPPORTED_OPERATION`.
+
+Ambient `OPENAI_API_KEY` is used only for the default `https://api.openai.com`
+origin. Custom origins require an explicit key; the CLI requires `apiKeyEnv`.
+Supply an origin without a `/v1` base path. Authentication cannot be disabled.
+Existing transport deadlines, cancellation, byte limits, and redaction apply.
+
+## Command runner
+
+```bash
+decision-bridge evaluate request.json --provider openai-decisions --env-file .env
+decision-bridge validate request.json --provider openai-decisions
+decision-bridge init ./native-decisions --provider openai-decisions --native
+decision-bridge validate ./native-decisions/request.json --provider openai-decisions --native
+decision-bridge evaluate ./native-decisions/request.json --provider openai-decisions --native --env-file .env
+decision-bridge batch native-requests.jsonl --provider openai-decisions --native --env-file .env
+```
+
+`--native` applies only to `init`, `evaluate`, `validate`, and `batch` with this
+provider. Native evaluation/validation/batch require an explicit file or `-`.
+Mode is never inferred from JSON. Initialization writes a native request, which
+must still be evaluated with `--native`. Offline validation checks built-in
+capabilities without credentials; custom capabilities are checked at evaluation.
+Decisions offline validation also checks native field limits and the configured
+request byte limit in both modes.
+
+The `schema` command remains a generative utility and rejects the new request
+forms. Generation settings (`maxTokens`, `responseFormat`, `parameters`, etc.)
+are rejected for Decisions. See the [CLI reference](../reference/CLI.md).
+
+From a source checkout, the optional `npm run smoke:live -- --decisions --env-file .env`
+checks four bounded requests when `RUN_LIVE_TESTS=1` is explicitly set. It checks
+protocol behavior rather than prediction quality, disables retries, and prints
+only model identities and token usage. Normal verification never runs it.

package/docs/guides/PLATFORMS.md

@@ -0,0 +1,107 @@
+# Platforms and installation
+
+## Compatibility and verification
+
+The SDK targets Node.js **22.16 or newer** on native Windows, macOS, and Linux,
+and modern browsers through a browser application's module bundler. Its SDK
+module graph uses standard web APIs and has no third-party runtime dependencies.
+The optional command runner uses Node built-ins and remains Node-only. WSL and
+Bash are not required, and no standalone `.exe` or `.app` is provided. Direct
+browser calls also depend on [provider CORS and credential rules](BROWSER.md).
+
+For application integration, follow the [SDK quickstart](GETTING_STARTED.md).
+The shell-specific source commands below are for working in a source checkout.
+
+The CI matrix targets Windows, macOS, and Linux with Node 22.16 and Node 24.
+Consult run results for the exact commit and environment being evaluated;
+the matrix itself is not a completed platform check. ARM machines require a
+compatible native Node runtime. See [testing](../development/TESTING.md).
+
+## Windows / PowerShell
+
+Open PowerShell at the cloned repository or extracted source directory:
+
+```powershell
+cd "C:\path\to\decision-bridge-0.1.0"
+node --version
+node bin/decision.mjs validate examples/request.json
+Copy-Item .env.example .env
+notepad .env
+```
+
+Replace the placeholder value for `TYPESAFE_API_KEY` in `.env` and save it locally.
+The following file-based commands work without shell-specific continuation or
+stdin encoding rules:
+
+```powershell
+node bin/decision.mjs models --env-file .env
+node bin/decision.mjs evaluate examples/request.json --env-file .env
+```
+
+`npm run models` and `npm run ask` are equivalent convenience commands. If a local
+PowerShell execution policy blocks the npm PowerShell shim, use `npm.cmd test` /
+`npm.cmd run ask`, or the direct `node` commands above. Do not weaken your system's
+execution policy merely to run this project. Paths containing spaces should be
+quoted. A project copied across operating systems should be re-extracted from
+the archive rather than reusing generated `node_modules` or executable shims.
+
+## macOS / Linux
+
+```bash
+cd "/path/to/decision-bridge-0.1.0"
+node --version
+node bin/decision.mjs validate examples/request.json
+cp .env.example .env
+```
+
+Edit `.env` locally, then:
+
+```bash
+node bin/decision.mjs models --env-file .env
+node bin/decision.mjs evaluate examples/request.json --env-file .env
+```
+
+Use a currently maintained, compatible Node release according to your organization’s
+runtime policy; the minimum here describes this package's API requirements, not a
+security recommendation to remain on an old patch release.
+
+## Install in another project
+
+Install the package with npm from your application's directory:
+
+```text
+npm install @fayegram-ai/decision-bridge
+```
+
+For installation from a verified local archive, see
+[getting started](GETTING_STARTED.md#install-into-your-application).
+
+Import from `@fayegram-ai/decision-bridge` in ESM JavaScript, or invoke the installed
+command runner through npm from your application directory:
+
+```text
+npm exec -- decision-bridge --version
+npm exec -- decision-bridge init ./my-decisions
+npm exec -- decision-bridge validate ./my-decisions/request.json
+```
+
+A CommonJS application can use `await import('@fayegram-ai/decision-bridge')` from an async
+function; this package exports an ESM entry point, not a native `require()` entry.
+The runtime package includes implementation, examples, type declarations and
+maintained documentation. Use a source checkout for tests and CI. Node/npm and
+the development TypeScript compiler are external prerequisites, not bundled
+executables.
+
+## Filesystems, streams, and limits
+
+Output files use exclusive temporary files and no-clobber finalization by default.
+Some filesystems do not support hard links; such no-clobber output fails explicitly
+rather than falling back to overwriting. Unix mode 0600 is applied where supported;
+on Windows, secure the working directory using your normal Windows permissions.
+
+Input/output JSON is UTF-8. File arguments are the most portable way to avoid
+shell pipeline encoding differences. A POSIX subprocess test covers SIGINT;
+Windows console signal delivery still needs native validation.
+Cancellation can stop waiting and close a blocked CLI output pipe, but cannot undo
+an API request that already ran or force arbitrary custom-provider resources to
+terminate. See [CLI I/O](../reference/CLI.md).

package/docs/guides/SWITCHING_MODELS.md

@@ -0,0 +1,202 @@
+# Switching models without rewriting the application
+
+The bridge's request contains `questions`, either `state` or ordered `input`, and
+optionally `model`. Ordered input and richer question types require provider capabilities.
+The provider translates it into that service's wire protocol and validates the
+response. Select a provider when constructing your SDK bridge.
+The root README lists [supported model selectors and aliases](../../README.md#supported-models).
+
+## Native and custom selection
+
+The main package supports native Jev, OpenAI Decisions, and Cloudflare. The
+request remains shared when switching providers, subject to capabilities.
+General-purpose models use the explicit [custom generative](CUSTOM_GENERATIVE.md)
+entry point. A new decision protocol uses [custom decision](CUSTOM_DECISION.md).
+The example below demonstrates the opt-in generative path; native alternatives
+follow it.
+
+## SDK: same request, different provider
+
+Install the package as described in [getting started](GETTING_STARTED.md).
+Create or update `.env` in your application directory with the selected backend's
+key and an actual model ID available to your account. For OpenRouter:
+
+```dotenv
+OPENROUTER_API_KEY=replace_with_your_openrouter_key
+DECISION_MODEL=VENDOR/MODEL_ID
+```
+
+Keep `.env` out of source control. `VENDOR/MODEL_ID` is a placeholder to replace.
+Save this complete example as `use-model.mjs` beside `.env`:
+
+```javascript
+import { createBridge, choice, publicError } from '@fayegram-ai/decision-bridge';
+import { createGenerativeProvider } from '@fayegram-ai/decision-bridge/custom/generative';
+
+try {
+    const provider = createGenerativeProvider({
+        type: 'openrouter',
+        model: process.env.DECISION_MODEL,
+        responseFormat: 'json_schema',
+    });
+    const bridge = createBridge({ provider });
+    const result = await bridge.evaluate({
+        state: { message: 'I was charged twice for the same invoice.' },
+        questions: {
+            route: choice('Which team should inspect this message?', {
+                billing: 'Invoices, charges, or payment problems.',
+                technical: 'Software defects or connectivity problems.',
+                unknown: 'The evidence does not establish a team.',
+            }),
+        },
+    });
+    console.log(JSON.stringify(result, null, 2));
+} catch (error) {
+    console.error(publicError(error));
+    process.exitCode = 1;
+}
+```
+
+Run it from your application directory:
+
+```bash
+node --env-file=.env use-model.mjs
+```
+
+This performs a real evaluation and may incur charges. The request is defined in
+this script; it does not need files from the bridge's source checkout.
+
+To use another backend, replace the provider configuration in the
+example and provide that backend's credential in `.env`:
+
+| Native SDK `createProvider` type | Credential variable | Model selection |
+| --- | --- | --- |
+| `jev` | `TYPESAFE_API_KEY` | Defaults to `jev-latest`; an explicit model overrides it |
+| `openai-decisions` | `OPENAI_API_KEY` | Defaults to `gpt-6-luna` |
+| `cloudflare-decisions` | `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` for REST | Defaults to `clef`; also supports `clef-flash` and `clef-omni` |
+
+Custom generative presets use `createGenerativeProvider` instead. Their types are
+`openai-compatible` (`OPENAI_API_KEY` at the default OpenAI origin), `openrouter`
+(`OPENROUTER_API_KEY`), and `anthropic` (`ANTHROPIC_API_KEY`). Each requires a model
+available to your account. Import the native `createProvider` from the root when
+using the following native alternatives:
+
+```javascript
+createProvider({ type: 'jev', model: 'jev-latest' });
+createProvider({ type: 'openai-decisions', model: 'gpt-6-luna' });
+createProvider({ type: 'cloudflare-decisions', model: 'clef-flash' });
+createGenerativeProvider({ type: 'openai-compatible', model: process.env.DECISION_MODEL });
+createGenerativeProvider({ type: 'anthropic', model: process.env.DECISION_MODEL });
+```
+
+Each line is an alternative configuration. Constructors validate credentials but
+make no inference calls. `evaluate()` sends the request. In the SDK, a request's
+`model` overrides the provider default; omit it when the provider should choose.
+The SDK does not automatically read `DECISION_*` settings: this example passes
+`process.env.DECISION_MODEL` explicitly. The SDK factory property is **`type`**;
+a command-runner JSON profile uses **`provider`**.
+
+For Jev and the generative providers, list models with `await bridge.listModels()`.
+OpenAI Decisions and Cloudflare Clef do not implement model discovery and return
+`UNSUPPORTED_OPERATION`; their capability profiles do not prove account availability.
+A catalog entry does not prove support for a particular response format. Check
+that the selected serving endpoint supports the configured output mode. Anthropic
+model listing preserves first-page pagination metadata; this client does not
+fetch all pages automatically.
+
+## Local or other compatible services
+
+For a loopback server using Chat Completions, replace the provider configuration
+in the complete example with:
+
+```javascript
+const provider = createGenerativeProvider({
+    type: 'openai-compatible',
+    baseURL: 'http://127.0.0.1:8000/v1',
+    apiKey: null,
+    model: process.env.LOCAL_MODEL,
+    responseFormat: 'json_schema',
+    tokenParameter: 'max_tokens',
+});
+```
+
+Set `LOCAL_MODEL` in `.env` to your served model ID. `apiKey: null` explicitly
+allows no authentication only for loopback compatible endpoints. A remote custom
+endpoint requires HTTPS and an explicit `apiKey`, for example
+`apiKey: process.env.MY_SERVICE_KEY`. See [credential boundaries](../reference/CONFIGURATION.md#custom-endpoint-credential-boundary).
+
+Select `responseFormat: 'json_object'` or `'text'` only when appropriate for that
+service. Validation remains strict, and the client does not silently retry with
+a weaker format.
+
+## Optional command runner
+
+From an application with the package installed locally, create a request to edit:
+
+```bash
+npm exec -- decision-bridge init ./my-decisions
+```
+
+Edit `my-decisions/request.json` for your task. Keep `.env` in the application
+root for the commands below, with the selected backend's key. Replace the
+uppercase model placeholders with IDs available to your account/server:
+
+```bash
+npm exec -- decision-bridge evaluate ./my-decisions/request.json --provider jev --model jev-latest --env-file .env
+npm exec -- decision-bridge evaluate ./my-decisions/request.json --provider openai-decisions --model gpt-6-luna --env-file .env
+npm exec -- decision-bridge evaluate ./my-decisions/request.json --provider cloudflare-decisions --model clef-flash --env-file .env
+npm exec -- decision-bridge evaluate ./my-decisions/request.json --provider custom-generative --preset openrouter --model VENDOR/MODEL_ID --env-file .env
+npm exec -- decision-bridge evaluate ./my-decisions/request.json --provider custom-generative --preset openai-compatible --model MODEL_ID --env-file .env
+npm exec -- decision-bridge evaluate ./my-decisions/request.json --provider custom-generative --preset anthropic --model MODEL_ID --env-file .env
+```
+
+List models with `npm exec -- decision-bridge models --provider custom-generative --preset openrouter --env-file .env`.
+For a loopback compatible server:
+
+```bash
+npm exec -- decision-bridge evaluate ./my-decisions/request.json --provider custom-generative --preset openai-compatible --base-url http://127.0.0.1:8000/v1 --no-auth --model LOCAL_MODEL_ID --token-parameter max_tokens --response-format json_schema
+```
+
+For a remote custom endpoint, explicitly select its credential variable with
+`--api-key-env MY_SERVICE_KEY` alongside `--base-url`.
+
+### Save a command-runner profile
+
+Create `openrouter.config.json` in your application directory:
+
+```json
+{
+    "schemaVersion": 1,
+    "provider": "custom-generative",
+    "preset": "openrouter",
+    "model": "VENDOR/MODEL_ID",
+    "apiKeyEnv": "OPENROUTER_API_KEY",
+    "responseFormat": "json_schema",
+    "timeoutMs": 30000
+}
+```
+
+```bash
+npm exec -- decision-bridge evaluate ./my-decisions/request.json --config openrouter.config.json --env-file .env
+```
+
+Command-runner model precedence is `--model` > `request.model` > resolved
+configuration > provider default. Omit `model` from reusable request files when
+profiles should choose it. Provider, preset, and module changes reset lower-precedence
+provider-specific settings; supply overrides for the new provider explicitly.
+See [configuration](../reference/CONFIGURATION.md).
+
+## Boundaries
+
+The opt-in custom generative compatible preset uses Chat Completions, not the OpenAI Responses API.
+Anthropic uses one forced output-schema tool, not an agent loop. A different
+protocol requires the [custom-provider contract](CUSTOM_PROVIDERS.md).
+Jev, OpenAI Decisions, and Cloudflare Clef each have a dedicated native provider;
+use those provider types for their decision APIs. Native Decisions providers
+reject generative output settings such as `responseFormat` and `maxTokens`.
+
+All shipped evaluations return probability-based decisions. Jev, OpenAI Decisions,
+and Cloudflare probabilities are marked `native`; generative estimates are `elicited`, not logprobs or
+a calibration guarantee. There is no discrete-only mode in this release. The
+bridge standardizes the software interface, not model accuracy or statistical
+semantics. See [provider reference](../reference/PROVIDERS.md).

package/docs/guides/TROUBLESHOOTING.md

@@ -0,0 +1,82 @@
+# Troubleshooting
+
+## The command cannot find a key
+
+General `node bin/decision.mjs ...` calls need exported environment variables or an
+explicit `--env-file .env`. Only the documented convenience npm scripts
+preload `.env`. The file must name the selected provider's credential variable.
+Do not pass a TypeSafe key to OpenRouter or vice versa. Existing shell environment
+values win over a file; an old exported value can therefore mask a newly edited file.
+
+## My model or base URL seems ignored
+
+Unknown options are rejected, but model precedence still matters:
+`--model > request.model > resolved config/environment model > provider default`.
+Provider changes discard
+incompatible fields inherited from a different JSON profile. Use a complete
+explicit config. A compatible base includes its version prefix, not the final
+`/chat/completions` path. Jev and the custom Anthropic preset require origins
+without a path. See [configuration](../reference/CONFIGURATION.md#precedence).
+
+## Structured output is rejected
+
+Check that the selected endpoint/model supports the requested `json_schema` mode.
+Choose `json_object` or `text` explicitly when appropriate; local validation remains
+strict. Some servers require `--token-parameter max_tokens`. A valid schema does
+not guarantee probabilities sum to one. `INVALID_RESPONSE` must not be treated as
+an approved decision. Large schemas also consume context/output budget.
+
+## The model returns JSON but confidence is absent
+
+This is expected for generative backends. They produce elicited probabilities
+and do not report the native confidence carried by Jev, OpenAI Decisions, or
+Cloudflare choice/score answers. Read `meta.probabilitySource`. A null token
+count means the server did not report it. Neither absence should be silently
+converted to a number.
+
+## Cloudflare needs an account ID as well as a token
+
+REST inference targets an account-specific URL. Supply `CLOUDFLARE_ACCOUNT_ID`
+and `CLOUDFLARE_API_TOKEN`, or explicit SDK credentials, for that account.
+Standard REST inference needs no Worker or Gateway. Binding calls instead require
+an injected `env.AI`; Gateway routing requires explicit Gateway configuration.
+See the [Cloudflare guide](CLOUDFLARE_DECISIONS.md#supported-inference-paths).
+
+## Cloudflare REST busy mode is unavailable
+
+The bridge rejects enabled Clef REST busy mode locally with
+`UNSUPPORTED_CAPABILITY` before inference. Direct hosted requests were observed
+to reject the execution field with HTTP 422/code `5012`. Leave `rejectIfBusy`
+disabled for REST, or use the Workers AI binding for the enabled setting.
+This differs from a capacity rejection (`3040`) or an allocation limit (`3036`);
+increasing client retries does not fix unsupported
+execution options. See [capacity and Gateway settings](CLOUDFLARE_DECISIONS.md#capacity-rejection-and-ai-gateway).
+
+## Evaluation succeeds but an extension failed
+
+Inspect `meta.observerFailures`. Observation occurs after inference; a failed log
+sink must not cause another model call. Preparation failures instead throw
+`EXTENSION_ERROR` before continuing to inference. Observe the separate provider,
+bridge, and observer deadlines documented in the SDK reference.
+
+## Batch output is incomplete
+
+Per-record errors are explicit JSONL records and do not stop the CLI. A global
+input, UTF-8, limit, interruption, or filesystem failure can stop the batch. Atomic
+file output is not finalized in that case; stdout can contain a completed prefix.
+Some requests may already have been sent/billed. Retrying an entire prefix can
+repeat work, so retain completed records externally when designing resumability.
+
+## Type checks fail because tsc is missing
+
+Runtime and tests have no TypeScript dependency. Development type checks require
+TypeScript 5.8.3, the verified compiler. Install it as a developer tool using the
+instructions in [Testing](../development/TESTING.md). Do not confuse an absent
+development compiler with a broken runtime package.
+
+## Filing a useful issue
+
+Include bridge version, Node version, OS, command with secrets removed, provider,
+requested model, safe error JSON, and a minimal nonsensitive reproduction. Never
+include `.env`, keys, private prompts, or raw confidential documents. Security
+reports should be private; see the root security policy.