@cartanova/qgrid-cli 2.3.7 → 2.3.9

package/skills/qgrid/references/ai-sdk-provider-contract.md

@@ -0,0 +1,100 @@
+# AI SDK Provider Contract
+
+Use this reference before changing `packages/ai-sdk`.
+
+## Active public surface
+
+`packages/ai-sdk` is the active public SDK package. `packages/sdk` is deprecated and context-only.
+
+qgrid's custom provider implements the AI SDK `LanguageModelV3` contract. General usage should follow the AI SDK docs and normal AI SDK APIs such as `generateText`, `streamText`, tools, structured output, and telemetry. Do not re-document generic AI SDK usage in qgrid-specific docs unless the behavior differs. qgrid docs and this skill should focus on qgrid-specific config, `providerOptions.qgrid`, request logging, runtime routing, cache/session behavior, and provider limitations.
+
+For tool calling, qgrid intentionally follows the AI SDK interface while implementing provider calls through qgrid structured-output emulation. Read `tool-calling-and-multiturn.md` before changing tool behavior, `stopWhen`/multi-step behavior, or tool-call request logs.
+
+Main files:
+
+- `packages/ai-sdk/src/index.ts`: `qgrid()` provider implementation.
+- `packages/ai-sdk/src/index.types.ts`: public config/options/types.
+- `packages/ai-sdk/src/utils.ts`: prompt/history/tool conversion.
+- `packages/ai-sdk/src/logger.ts`: telemetry logger integration.
+- `packages/ai-sdk/src/qgrid.constant.ts`: defaults and warnings.
+
+## Provider config
+
+`qgrid(modelId, config)` supports:
+
+- `serverUrl`: default `process.env.QGRID_URL`, then `http://localhost:44900`.
+- `defaultEffort`: default `low`.
+- `projectName`: default `process.env.QGRID_PROJECT_NAME`.
+
+Strongly recommend setting `QGRID_PROJECT_NAME` in the environment for real workloads. The config-level `projectName` override is valid, but the env var is the preferred project-wide default. It is stored as `request_logs.project_name` and makes high-volume request logs usable: operators can filter by project/workflow, identify which task produced which request, compare token/cache/cost/TTFT metrics by workload, and debug noisy callers without scanning prompts manually.
+
+Use camelCase `projectName` in TypeScript and qgrid API payloads. `project_name` is the database/Sonamu request-log field name, not an AI SDK provider option.
+
+Setup agents should treat a missing project label as an actionable configuration gap. When installing or wiring qgrid for a local app, inspect the target app's env/config. If neither `QGRID_PROJECT_NAME` nor qgrid provider/logger config `projectName` is present, ask the user for a stable project or workflow name, then add it using the project's normal env/config pattern. A repo or package name is an acceptable default only when it is clearly the user's intended workload label.
+
+## Provider options
+
+qgrid-specific behavior is controlled through `providerOptions.qgrid`. Explain these options precisely because they are qgrid's extension point beyond normal AI SDK usage.
+
+`providerOptions.qgrid` supports:
+
+- `sessionKey`: OpenAI thread reuse key. Disabled for Anthropic models.
+- `effort`
+- `verbosity`: OpenAI/Codex route only.
+- `reasoningSummary`: OpenAI/Codex route only.
+- `serviceTier`: OpenAI/Codex route only.
+- `fallbackModels`: reserved for future fallback routing.
+- `imageGeneration`: OpenAI/Codex non-stream only. Enables Codex's built-in `image_generation` tool for that request.
+- `imageGenerationOptions`: optional image quality/size hints and cost-estimation basis. Current supported values are `quality: "low" | "medium" | "high"` and `size: "1024x1024" | "1024x1536" | "1536x1024"`.
+
+`providerOptions.qgrid` does not currently support `projectName` or `project_name`. Prefer `QGRID_PROJECT_NAME` for the default project label; use config `projectName` only when a caller needs to override that default.
+
+## Request construction
+
+The provider sends `POST /api/qgrid/query` for generate and `prepareStream` plus SSE for stream.
+
+Payload responsibilities:
+
+- Extract current prompt, system prompt, and history from AI SDK prompt messages.
+- Convert AI SDK function tools to qgrid tools.
+- Send `jsonSchema` only when no tools are present and response format top-level schema is `object`.
+- Send `history` as JSON string when prior messages exist.
+- Send `projectName` when configured.
+- Use `logMode: "run"` for tool-call loops.
+- Preserve and resend `runContext` for tool-call follow-ups.
+- Store/resend OpenAI `threadCoord` by `sessionKey`.
+- Send `imageGeneration` and `imageGenerationOptions` when configured.
+
+Tools and `jsonSchema` cannot be used together at qgrid dispatcher level.
+
+When tools are present, qgrid sends tool definitions to the server as `tools`; it does not send them to OpenAI or Anthropic as native provider tools. The server converts them into a strict structured-output schema and maps the model's structured result back into AI SDK `tool-call` content.
+
+Image generation is different from AI SDK client tools: it is an opt-in Codex-hosted tool exposed by qgrid through `providerOptions.qgrid.imageGeneration`. Use `generateText`; `streamText` rejects image generation before opening the stream.
+
+## Response mapping
+
+qgrid response content maps to AI SDK content:
+
+- qgrid `text` -> AI SDK text content.
+- qgrid `tool-call` -> AI SDK tool-call content.
+- qgrid `image` -> AI SDK file content with `mediaType: "image/png"`.
+
+`finishReason` maps `tool-calls` when qgrid returns tool calls.
+
+When `imageGeneration` was requested and the server returns no image part, the AI SDK provider throws a version-skew/error guard instead of silently accepting text-only output.
+
+Usage maps qgrid standard usage into AI SDK V3 usage:
+
+- `inputTokens.total = input_tokens`
+- `inputTokens.cacheRead = cache_read_input_tokens`
+- `inputTokens.cacheWrite = cache_creation_input_tokens`
+- `inputTokens.noCache = max(input - cacheRead - cacheWrite, 0)`
+- `outputTokens.total = output_tokens`
+
+## Anthropic sessionKey guard
+
+Do not store or replay `sessionKey` thread coordinates for `anthropic/*` models. Tests cover this because Anthropic fresh-spawn runtime cannot safely use Codex-style thread reuse.
+
+## Logger integration
+
+`createQgridLogger` records external provider calls into qgrid request logs. It skips qgrid provider calls to avoid double-logging. When changing logger behavior, preserve stale-run fallback because AI SDK telemetry lacks a reliable error hook for all failure modes.

package/skills/qgrid/references/anthropic-claude-code-runtime.md

@@ -0,0 +1,170 @@
+# Anthropic Claude Code Runtime
+
+Use this reference before changing Anthropic provider behavior, Claude Code spawn args/env, stream-json adaptation, structured output, 1M context behavior, token routing, OAuth refresh, or quota handling.
+
+## Contents
+
+- Process model
+- Token routing
+- OAuth refresh
+- Spawn args
+- Spawn env
+- Config isolation
+- Input adaptation
+- Output adaptation
+- Structured output
+- 1M context
+
+## Process model
+
+Anthropic uses fresh Claude Code process spawn per request. It does not use a persistent worker pool.
+
+- Dispatcher: `packages/api/src/utils/providers/anthropic/anthropic-dispatcher.ts`.
+- Session runner: `packages/api/src/utils/providers/anthropic/claude-session.ts`.
+- Stream adapter: `packages/api/src/utils/providers/anthropic/stream-json-adapter.ts`.
+- Constants/model normalization: `packages/api/src/utils/providers/anthropic/anthropic-constants.ts`.
+- Process command: `claude -p ...`.
+- Each request gets a fresh UUID `--session-id`.
+- `workerId` is `tokenId`.
+- `epoch` is always `0`.
+
+The emitted `threadCoord` lets qgrid keep a shared response shape, but AI SDK disables `sessionKey` storage/replay for `anthropic/*` models. Do not implement Anthropic cache by pretending Claude sessions are reused unless the runtime design changes.
+
+## Token routing
+
+Anthropic tokens live in an in-memory `Map<tokenId, PooledToken>`.
+
+- Startup loads active Anthropic tokens from DB.
+- Token subscriber events add/update/remove entries.
+- Periodic reconcile replaces pool contents from active DB rows.
+- Request selection is least-used plus round-robin tie-break.
+- Request count is incremented before awaiting execution so concurrent requests spread across tokens.
+
+Quota threshold:
+
+- `quota_threshold` is checked through Anthropic quota usage.
+- Lookup failure is fail-open.
+- If all eligible tokens exceed threshold, throw `QuotaThresholdExceededError`.
+
+## OAuth refresh
+
+Before spawning Claude, qgrid refreshes access tokens when expiration is within 60 seconds and a refresh token exists.
+
+Refresh is attempted through `QgridFrame.refreshToken` with provider set to `anthropic`. Refresh failure is logged and the current access token is still tried.
+
+## Spawn args
+
+`buildClaudeArgs` constructs Claude Code flags:
+
+```text
+claude -p
+  --tools ""
+  --allowed-tools StructuredOutput        # only when jsonSchema exists
+  --disallowedTools Monitor PushNotification RemoteTrigger
+  --input-format stream-json
+  --output-format stream-json
+  --verbose
+  --include-partial-messages              # streaming path only
+  --permission-mode bypassPermissions
+  --setting-sources project
+  --model <canonical-model-or-1m-suffix>
+  --system-prompt <text>                  # small system prompt
+  --system-prompt-file <path>             # large system prompt
+  --thinking disabled
+  --effort <effort-or-low>
+  --disable-slash-commands
+  --session-id <uuid>
+  --json-schema <schema>                  # only when jsonSchema exists
+```
+
+Important details:
+
+- `--tools ""` blocks normal tools. With structured output, only `StructuredOutput` is allowed.
+- `--setting-sources project` plus seeded settings isolates user configuration.
+- `--system-prompt` or `--system-prompt-file` is always supplied. Omitting it would allow Claude Code default system prompt injection.
+- Large system prompts over 64 KiB are written to a temporary file to avoid argv `E2BIG`.
+- `--thinking disabled`, `MAX_THINKING_TOKENS=0`, and adaptive thinking env suppression keep thinking off.
+
+## Spawn env
+
+qgrid builds a fresh env whitelist. Do not spread `process.env` into Claude child env.
+
+Included env:
+
+- `PATH`
+- `TMPDIR`
+- `CLAUDE_CODE_OAUTH_TOKEN`
+- `CLAUDE_CONFIG_DIR`
+- `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`
+- `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`
+- `CLAUDE_CODE_DISABLE_CLAUDE_MDS=1`
+- `CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1`
+- `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1`
+- `CLAUDE_CODE_DISABLE_WORKFLOWS=1`
+- `CLAUDE_CODE_ATTRIBUTION_HEADER=0`
+- `MAX_THINKING_TOKENS=0`
+- `CLAUDE_CODE_DISABLE_1M_CONTEXT=1` when model does not support qgrid's 1M path
+- `MAX_STRUCTURED_OUTPUT_RETRIES` for structured output only
+
+Never pass `ANTHROPIC_API_KEY` or inherited auth env vars to child processes. OAuth must flow through `CLAUDE_CODE_OAUTH_TOKEN`.
+
+## Config isolation
+
+- Shared cwd: `/tmp/qgrid-anthropic`.
+- Project settings file: `/tmp/qgrid-anthropic/.claude/settings.json`, written as `{}`.
+- Per-token config dir: `/tmp/qgrid-anthropic-config/${tokenId}`.
+- qgrid writes `{}` to both `.claude.json` and `settings.json` inside the per-token config dir before each run.
+
+This blocks user-scope Claude settings, hooks, memory, and token cross-contamination as much as the current Claude Code interface allows.
+
+## Input adaptation
+
+qgrid sends Claude stdin as JSONL with `--input-format stream-json`.
+
+- Current input is the only executable user line.
+- Prior conversation history is flattened into a single assistant context line prefixed with `Prior conversation context:`.
+- Function calls and function outputs from AI SDK history are flattened into text.
+- Each JSONL line is decorated with `session_id`, `uuid`, and `parent_tool_use_id: null`.
+
+This is not equivalent to persistent Claude session reuse. It is full-history replay through a fresh process.
+
+## Output adaptation
+
+Claude stdout JSONL is parsed by `stream-json-adapter.ts`.
+
+- Text mode streams `text_delta`.
+- Structured mode streams `input_json_delta` and preserves `StructuredOutput` tool input as final text.
+- `result` lines provide final text, usage, duration, cost, subtype, and terminal reason.
+- Non-success subtype, `is_error`, or `terminal_reason: model_error` is treated as an error.
+- Quota exhaustion is detected when text starts with `You've hit`.
+
+Anthropic native usage categories are mutually exclusive. qgrid normalizes them into its provider-standard shape by setting:
+
+```text
+inputTokens = input_tokens + cache_creation_input_tokens + cache_read_input_tokens
+cachedInputTokens = cache_read_input_tokens
+cacheCreationInputTokens = cache_creation_input_tokens
+```
+
+## Structured output
+
+qgrid strictifies schemas before provider dispatch. Claude Code `--json-schema` is not grammar-constrained decoding; it is a `StructuredOutput` tool plus post-validation behavior. Keep schemas strict and preserve error signaling for failed structured-output attempts.
+
+`MAX_STRUCTURED_OUTPUT_RETRIES` defaults to `1` for structured Anthropic calls and is clamped to at least 1. Avoid setting it to 0; Claude Code can fail before emitting a useful attempt.
+
+## 1M context
+
+Model normalization strips provider prefix and `[1m]` for canonical model/cost keys.
+
+qgrid's measured 1M support set currently includes:
+
+- `claude-sonnet-4-6`
+- `claude-opus-4-6`
+- `claude-opus-4-8`
+
+Models requiring CLI `[1m]` suffix:
+
+- `claude-sonnet-4-6`
+- `claude-opus-4-6`
+
+Unsupported `[1m]` suffixes throw early.

package/skills/qgrid/references/cli-env-and-server-boot.md

@@ -0,0 +1,66 @@
+# CLI, Env, And Server Boot
+
+Use this reference for qgrid startup, configuration, and runtime-facing environment variables.
+
+## CLI options
+
+- `--db <url>`: PostgreSQL URL in `postgres://user:password@host:port/dbname` or `postgresql://...` form. Parsed by `packages/cli/src/cli.ts` and copied into `QGRID_DB_*` env vars before server boot.
+- `-p, --port <port>`: server port. Default `44900`. The CLI validates the port and refuses to start if it is already in use.
+- `--skip-update`: skip qgrid CLI self-update check.
+
+The CLI also ensures runtime CLIs are installed/current enough:
+
+- `codex` from `@openai/codex`, required for OpenAI tokens.
+- `claude` from `@anthropic-ai/claude-code`, required for Anthropic tokens.
+
+## Server env vars agents should know
+
+| Env | Default | Meaning |
+|---|---:|---|
+| `QGRID_DB_HOST` | `localhost` | PostgreSQL host. |
+| `QGRID_DB_PORT` | `5432` | PostgreSQL port. |
+| `QGRID_DB_USER` | `postgres` | PostgreSQL user. |
+| `QGRID_DB_PASSWORD` | `postgres` | PostgreSQL password. |
+| `QGRID_DB_NAME` | `qgrid` | PostgreSQL database. |
+| `HOST` | `localhost` | Sonamu server listen host when running API directly. |
+| `PORT` | `44900` | Sonamu server listen port. In CLI mode this is derived from `--port`, not read as user input. |
+| `QGRID_PUBLIC_BASE_URL` | empty | Public base URL used to construct Anthropic OAuth callback URL. If unset, callback defaults to `http://localhost:${PORT}/callback`. |
+| `PROJECT_NAME` | `Qgrid` | Sonamu project name. Not the same as request log `projectName`. |
+
+Do not treat CLI bundle bootstrapping internals as user-facing qgrid configuration.
+
+## SDK/client env vars
+
+| Env | Default | Meaning |
+|---|---:|---|
+| `QGRID_URL` | `http://localhost:44900` | Server URL used by `@cartanova/qgrid-ai-sdk` and logger integration. |
+| `QGRID_PROJECT_NAME` | empty | Request log project name sent by the AI SDK provider/logger unless overridden in config. Configure this in the calling app or agent runtime environment, not only in the qgrid server process. |
+
+When helping a user set up qgrid locally, check for `QGRID_PROJECT_NAME` or config `projectName`. If absent, ask for a stable project/workflow label or add the obvious app/repo name when the setup context makes it unambiguous. This keeps request logs, metrics, and dashboard filters usable once traffic volume grows.
+
+## Provider runtime knobs
+
+| Env | Default | Meaning |
+|---|---:|---|
+| `QGRID_WORKERS_PER_TOKEN` | `3` | OpenAI Codex workers per token. Capped at 5 in code. |
+| `QGRID_OPENAI_THREAD_REUSE` | enabled | Set to `"false"` to disable OpenAI thread reuse and force cold thread behavior. |
+| `MAX_STRUCTURED_OUTPUT_RETRIES` | `1` for structured Anthropic calls | Claude Code structured-output retry count, clamped to at least 1 by qgrid. |
+
+## Server boot lifecycle
+
+On server start, `packages/api/src/sonamu.config.ts`:
+
+1. Loads `.env` from `packages/api/.env` when running API directly.
+2. Configures Sonamu database connection from `QGRID_DB_*`.
+3. Runs latest migrations from `packages/api/src/migrations`.
+4. Ensures PostgreSQL `tokens_changed` triggers.
+5. Starts `TokenSubscriber` for LISTEN/NOTIFY plus periodic reconcile.
+6. Starts `OpenAIDispatcher` and `AnthropicDispatcher`.
+7. Logs server URL and provider readiness counts.
+
+On shutdown, it stops provider dispatchers and the token subscriber.
+
+## OAuth callbacks
+
+- Anthropic OAuth uses `/callback` on the qgrid server. The callback URL is based on `QGRID_PUBLIC_BASE_URL` when set, otherwise localhost and `PORT`.
+- OpenAI OAuth is handled by Codex app-server's own callback flow and completed through qgrid's OpenAI OAuth APIs.

package/skills/qgrid/references/decision-rationale.md

@@ -0,0 +1,179 @@
+# Decision Rationale
+
+Use this reference when the question is "why is qgrid designed this way?" or before changing an established runtime contract. Current code is the source of truth for behavior; repo docs are the source of truth for the decision trail.
+
+Do not copy these notes blindly into implementation. Use them to find the relevant docs, then inspect the current code and tests.
+
+## Contents
+
+- AI SDK provider boundary
+- Tool calling and request-log lifecycle
+- OpenAI/Codex runtime
+- Anthropic/Claude Code runtime
+- Token sync and quota thresholds
+- Request logs, metrics, and dashboard
+- CLI packaging and server boot
+- Image generation
+
+## AI SDK Provider Boundary
+
+Sources:
+
+- `docs/plans/2026-05-07-feat-qgrid-ai-sdk-provider-plan.md`
+- `docs/solutions/conventions/qgrid-provider-options-boundary.md`
+- `docs/plans/2026-05-26-refactor-ai-sdk-wrapper-correlation-boundary-plan.md`
+
+Key decisions:
+
+- `packages/ai-sdk` is the active public SDK. `packages/sdk` is deprecated and should be read only for legacy context.
+- qgrid's AI SDK provider follows the AI SDK `LanguageModelV3` contract. Generic usage belongs to AI SDK docs; qgrid-specific docs should focus on qgrid routing, logging, cache/session behavior, and `providerOptions.qgrid`.
+- qgrid-specific options live under `providerOptions.qgrid`, not under provider-specific namespaces such as `providerOptions.openai`. Consumers should not need to branch on Codex versus Claude internals.
+- `projectName` is provider config/payload camelCase. `project_name` is the Sonamu/database request-log column. Prefer `QGRID_PROJECT_NAME` as the project-wide default so request logs and metrics remain filterable at volume.
+- `fallbackModels` may exist as a typed future option, but it is not a server wire contract until the server implements fallback routing. Do not forward it as behavior just because the type exists.
+- The SDK should stay a thin adapter. Server APIs own request-log lifecycle, provider dispatch, structured-output emulation, and provider runtime details.
+
+## Tool Calling And Request-Log Lifecycle
+
+Sources:
+
+- `docs/plans/2026-05-07-feat-qgrid-ai-sdk-provider-plan.md`
+- `docs/plans/2026-05-20-feat-request-log-run-lifecycle-api-plan.md`
+- `docs/plans/2026-05-26-refactor-ai-sdk-wrapper-correlation-boundary-plan.md`
+- `docs/solutions/tooling-decisions/anthropic-structured-stream-keep-required-and-fail-honestly.md`
+
+Key decisions:
+
+- qgrid tool calling is intentionally implemented through structured-output emulation, not native provider tool use. The provider call returns a structured action with tool calls; the AI SDK loop executes tools and sends follow-up turns.
+- Tools and `jsonSchema` are mutually exclusive at the qgrid dispatcher boundary because both need the provider structured-output slot.
+- Tool-call request logs are a multi-step run: create run, append generate/tool steps, then finish run. This makes AI SDK multi-step behavior visible in the dashboard instead of logging only one opaque completion.
+- Tool results update the existing `tool_call` step by `request_log_id + tool_call_id`. They are not logged as a second unrelated completion row.
+- `runContext.requestLogId` is intentionally direct. qgrid SDK and server are in the same product boundary, so an opaque indirection was not worth the complexity.
+- Lifecycle endpoints remain public because `createQgridLogger` records non-qgrid AI SDK calls into qgrid logs without forcing those calls through the qgrid provider.
+- Structured-output failures should fail honestly. Especially on Claude Code, partial or invalid structured output must not be rescued into a fake success.
+
+## OpenAI/Codex Runtime
+
+Sources:
+
+- `docs/plans/2026-05-18-feat-codex-app-server-backend-pivot-plan.md`
+- `docs/plans/2026-05-30-feat-codex-builtin-tool-suppression-plan.md`
+- `docs/plans/2026-06-06-feat-codex-thread-reuse-prompt-cache-plan.md`
+- `docs/solutions/logic-errors/qgrid-prompt-cache-hit-rate-metric-miscalculation.md`
+
+Key decisions:
+
+- OpenAI uses Codex `app-server` directly over stdio, not `codex exec`. The app-server path gives qgrid OAuth login, persistent workers, and thread handles.
+- Workers are persistent and token-scoped. qgrid can spawn multiple workers per token, but each worker is single-flight for turns. This differs from Anthropic, which fresh-spawns per request.
+- qgrid unsets normal OpenAI API-key paths and logs in with ChatGPT/OAuth credentials. This keeps the runtime aligned with subscription-token pooling rather than API billing.
+- Built-in Codex tools, apps, skills, web search, shell, and large instruction blocks are suppressed. The primary reason is tool-call correctness: Codex built-ins can steal calls that qgrid expects to represent as emulated AI SDK tool calls. Token savings are secondary.
+- Thread reuse exists because Codex/OpenAI prompt cache keys are tied to the Codex conversation/thread. New `thread/start` calls miss cache even with identical prefixes.
+- Reuse must be explicit through a server-issued coordinate such as `threadCoord`. Do not use content hashes or hidden closures; same-looking prompts from different sessions can cross-contaminate.
+- Reuse fallback should be cold and correct. Invalid worker id, epoch mismatch, missing thread, busy worker timeout, or over-threshold token should not corrupt a conversation.
+- Cache and usage metrics use per-turn usage. For Codex, `tokenUsage.total` is conversation cumulative; request logs must use `tokenUsage.last`.
+- OpenAI/Codex cached tokens are included in `input_tokens`. Cache-hit denominator is `input_tokens`, not `input + cache_read + cache_creation`.
+
+## Anthropic/Claude Code Runtime
+
+Sources:
+
+- `docs/brainstorms/2026-06-16-anthropic-provider-revival-problem-definition.md`
+- `docs/plans/2026-06-24-001-refactor-anthropic-cold-only-routing-plan.md`
+- `docs/solutions/integration-issues/claude-cli-drops-assistant-role-in-stream-json.md`
+- `docs/solutions/tooling-decisions/anthropic-structured-stream-keep-required-and-fail-honestly.md`
+- `docs/plans/2026-06-23-001-feat-anthropic-1m-context-plan.md`
+- `docs/solutions/security-issues/claude-cli-anthropic-api-key-leak-audit.md`
+- `docs/solutions/security-issues/qgrid-cross-user-context-leak-via-claude-settings-sources.md`
+- `docs/solutions/integration-issues/claude-code-oauth-tokens-share-prompt-cache.md`
+
+Key decisions:
+
+- Anthropic is an internal Claude subscription OAuth path. The API-key provider was not pursued because it does not serve qgrid's subscription-pooling value.
+- Anthropic is cold-only. It does not use Codex-style thread reuse because Claude Code prompt cache is prefix-based and AI SDK consumers already send full message history for each step.
+- The shared `threadCoord` response shape may still appear for provider symmetry, but AI SDK storage/replay is disabled for `anthropic/*` models.
+- Claude Code `stream-json` drops structural assistant role replay in the outbound API payload. qgrid flattens prior history into text because structural role replay through the CLI is not reliable.
+- Claude Code `--json-schema` is not constrained native tool calling. It creates a `StructuredOutput` tool and validates after model generation. Keep schemas strict and fail on non-success subtypes or retry exhaustion.
+- `MAX_STRUCTURED_OUTPUT_RETRIES=1` means one attempt. Do not set it to 0 expecting "no retry but one attempt"; that can mean no useful attempt.
+- 1M context support is measured per model and is a mitigation, not a guarantee. It reduces compaction/hang frequency for huge prompts, but does not make every structured prompt reliable.
+- Spawn env must be whitelisted. Never pass inherited `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `ANTHROPIC_BASE_URL` unless intentionally building an API-key/proxy path.
+- `--setting-sources project` is required for shared-service isolation. User/local Claude settings can load hooks or memory and leak context across requests.
+- Claude Code OAuth prompt cache sharing across tokens in the same workspace is an observed cost behavior, not a product contract. Monitor it; do not promise it.
+
+## Token Sync And Quota Thresholds
+
+Sources:
+
+- `docs/plans/2026-05-02-feat-token-sync-via-pg-listen-notify-plan.md`
+- `docs/brainstorms/2026-06-30-token-quota-threshold-requirements.md`
+- `docs/plans/2026-06-30-001-feat-token-quota-threshold-plan.md`
+
+Key decisions:
+
+- Token changes propagate with PostgreSQL `LISTEN/NOTIFY` plus periodic reconcile. Reconcile is kept because notifications can be missed during disconnects.
+- Trigger setup is boot-time idempotent SQL, not a raw migration file, because the Sonamu migration directory is managed and raw files can conflict.
+- Trigger payloads stay small (`op`, `id`). Dispatchers reload token rows instead of trusting a large notification body.
+- The token subscriber disables statement/idle timeouts for `LISTEN` and uses reconnect backoff.
+- `quota_threshold` is a routing guardrail, not a load balancer. It prevents an individual token from crossing a configured utilization percentage; it does not equalize traffic.
+- Threshold values are nullable integers from 1 to 100. `0` is not valid; `100` means exclude only at full utilization.
+- Provider criteria differ by primary window: Anthropic uses `five_hour.utilization`; OpenAI uses `primary.usedPercent`.
+- Threshold gates are by token id, not token name. Names are display/logging labels and can change.
+- Lookup failure is fail-open with logs/metrics. Hard failure happens only when usage was read successfully and the token is over threshold.
+- OpenAI needs the gate in reuse, idle selection, and queue drain paths. A reusable but over-threshold worker must fall back cold to another eligible token when possible.
+
+## Request Logs, Metrics, And Dashboard
+
+Sources:
+
+- `docs/plans/2026-05-21-feat-qgrid-logger-telemetry-integration-plan.md`
+- `docs/brainstorms/2026-07-01-request-log-ttft-metric-requirements.md`
+- `docs/solutions/logic-errors/qgrid-prompt-cache-hit-rate-metric-miscalculation.md`
+- `docs/solutions/performance-issues/sonamu-findmany-aggregate-slowdown.md`
+- `docs/solutions/performance-issues/qgrid-request-logs-subset-and-distinct-query-optimization.md`
+
+Key decisions:
+
+- The dashboard/logging layer is a core qgrid value, not an incidental web UI. It lets operators see cost, cache, TTFT, token routing, tool steps, and project-level workloads.
+- `createQgridLogger` exists so teams can keep using native AI SDK providers while still recording those calls in qgrid request logs. It should not throw into user code.
+- Request-log TTFT is the first generate-step TTFT. It intentionally measures generation responsiveness, not queue time or full request latency.
+- Cache-hit metrics must be derived consistently from normalized provider accounting. Keep metric logic centralized when possible.
+- Request-log list queries should avoid large text/blob columns unless the UI needs them. The list view is for scanning, not payload archival.
+- Aggregate endpoints can intentionally duplicate filters in raw SQL instead of reusing `findMany`. Materializing full rows for aggregates was measured as too slow.
+- Project-name filters matter at scale. Encourage `QGRID_PROJECT_NAME` so dashboards can distinguish workloads without inspecting prompts.
+- Setup agents are part of the intended local qgrid workflow. They should ask for or add a project label during setup because retroactively untangling anonymous request logs is expensive once multiple projects or workflows share a qgrid server.
+
+## CLI Packaging And Server Boot
+
+Sources:
+
+- `docs/plans/2026-04-06-feat-package-split-sdk-cli-plan.md`
+- `docs/plans/2026-04-13-refactor-cli-bundle-rollback-plan.md`
+- `references/cli-env-and-server-boot.md`
+
+Key decisions:
+
+- CLI and SDK were split so AI consumers do not install Sonamu, database, and runtime-server dependencies just to call qgrid.
+- The CLI is a direct Node/bundle runner, not a Docker wrapper. Docker was removed to keep `npm i -g ...` plus `qgrid start` usable without local Docker setup.
+- CLI user-facing configuration is intentionally small: database connection, port, public callback URL, server URL, and project name. Bundle bootstrapping details are implementation internals.
+- The CLI checks runtime CLIs (`codex`, `claude`) because qgrid delegates provider execution to those local binaries.
+- The dashboard version should follow the CLI package version because the dashboard is shipped by the CLI bundle, not as an independently versioned web product.
+- qgrid skills ship with the CLI package, not a separate skills package. qgrid cannot be used with the AI SDK alone; a local qgrid CLI server is required, so CLI install is the right moment to sync `.agents/skills/qgrid` and `.claude/skills/qgrid` into the consuming project.
+
+## Image Generation
+
+Sources:
+
+- `docs/brainstorms/2026-07-05-qgrid-image-generation-requirements.md`
+- `docs/plans/2026-07-05-001-feat-codex-image-generation-plan.md`
+- `docs/brainstorms/2026-07-06-qgrid-image-persistence-requirements.md`
+- `docs/brainstorms/2026-07-06-codex-image-cost-estimate.md`
+
+Key decisions:
+
+- Image generation is OpenAI/Codex-only and request-level opt-in. It is essentially a Codex-hosted `image_generation` tool call, not qgrid directly calling the OpenAI Images API. Always-on image tools would change every turn's tool configuration and threaten prompt-cache stability.
+- It is non-stream only. Codex returns completed base64 image payloads, not useful image deltas.
+- Image turns are cold one-shot threads and are excluded from thread reuse. This prevents base64 payloads from entering reusable conversation state and cache prefixes.
+- qgrid performs preflight capability/model gates and postflight "image count must be greater than zero" checks. Codex can otherwise silently return text when image generation is unavailable or unused.
+- Returned images are inline base64 content parts for consumers and AI SDK `file` parts. qgrid does not promise aspect ratio, edits, or reference-image control on this path.
+- `imageGenerationOptions` currently supports quality and size. The worker instruction and request-log pricing assumption use `gpt-image-2`, with defaults `medium` and `1536x1024`.
+- qgrid does not manage generated images as durable assets through a `generated_images` table or object-storage layer. Current request logs can still contain inline image data URLs for inspection and synthetic `image_generation` tool-call steps.
+- Image cost is stored separately in `request_logs.image_cost_usd`; `request_logs.cost_usd` remains the Codex driver model token cost. Because Codex does not expose exact image tool usage, `image_cost_usd` is a price-table estimate and may be inaccurate.
+- Inspect current plans, tests, and implementation before changing behavior; the Codex tool surface can change underneath qgrid.

package/skills/qgrid/references/docs-workflow.md

@@ -0,0 +1,32 @@
+# Docs Workflow
+
+Use this reference for qgrid planning, diagnosis, and review workflow.
+
+The project workflow is documented in `docs/WORKFLOW.md`.
+
+## Standard flow
+
+1. Brainstorm and plan before substantial work.
+2. Store local docs under `docs/` using existing directories:
+   - `docs/brainstorms/`
+   - `docs/plans/`
+   - `docs/diagnosis/`
+   - `docs/solutions/`
+3. Use peer review for plans and docs when requested.
+4. Accept review feedback by default unless there is a concrete tradeoff-based reason not to.
+
+## Existing docs are context
+
+Before changing runtime-sensitive areas, search `docs/diagnosis`, `docs/solutions`, and recent `docs/plans` for prior decisions. qgrid has important historical decisions around:
+
+- Codex thread reuse and prompt cache.
+- Claude Code fresh spawn.
+- structured output strictness.
+- Anthropic usage categories.
+- request log cache hit metrics.
+- quota threshold routing.
+- token isolation and auth env leaks.
+
+Do not copy stale docs blindly. Use docs to identify decisions and then verify against current code.
+
+When a repo doc establishes or changes durable rationale for a qgrid feature, reflect the stable decision in `references/decision-rationale.md`. Keep the skill reference as a compact index of why the decision exists and where the source docs live; do not copy full plans or brainstorms into the skill.