docs: make flux documentation match the code (#126)

* docs(runtime): describe runtime as engine-internal

The runtime package comment called runtime the recommended host entry
point, listed provider/catalog/config/credentials/setup/storage as the
packages hosts import, and claimed the registry holds 16 providers. The
host contract is engine/llm/graph/tools, rho imports none of those
packages directly, and catalog/registry defines 28 providers.

Rewrite the comment to say runtime is engine-internal and not covered by
engine.ContractVersion, and point at the registry instead of restating
its size (F294).

* docs: derive provider count, table and env example from the registry

AGENTS.md claimed "75+ LLM providers" while catalog/registry defines 28.
The README table said it was in registry SortOrder but was not, and
listed STEPFUN_API_KEY although StepFun reads STEP_API_KEY. .env.example
carried the same wrong StepFun variable plus FLUX_API_KEY, KIMI_API_KEY
and MINIMAX_API_KEY, which nothing in flux reads.

- AGENTS.md: state the 28 provider gateways in catalog/registry.
- README: reorder the table to real SortOrder, fix StepFun, add the
  Z.AI and StepFun region options.
- .env.example: list exactly the registry CredentialEnv variables.
- catalog/registry/docs_test.go: fail when any provider count stated in
  README, AGENTS.md, docs or runtime.go, the README table (IDs, order,
  credential variables, fallbacks, regions) or the .env.example block
  drift from registry.All() (F041, F294).

* fix(scripts): derive config-flow provider counts from the registry

test-config-flow.sh counted providers with `cd .. && grep flux/catalog/...`,
so any checkout not named "flux" reported 0 providers and failed, and it
printed "all 11 providers have live fetchers" while the registry holds 28.
`grep -c ... || echo 0` also produced "0\n0" on no match.

cd to the repo root once, compare the live-fetcher count to the registry
count instead of a hardcoded 11, and report the real numbers (F294).

* docs(grpc): describe the opt-in gRPC transport as it is

README called the gRPC surface a "dependency-free skeleton ... wired when
generated stubs are available" and the grpc.go package comment said flux
"does not currently import google.golang.org/grpc". In fact go.mod
requires google.golang.org/grpc directly (so it lands in consumers'
go.sum), server_grpc.go (tag grpc) serves flux.v1.ChatService/Chat with a
JSON codec and no protobuf stubs, and EngineChatService already adapts
conversation.Engine. The unit test comment also claimed the tagged test
covers the engine-backed round trip, but it uses a stub service.

- README: rewrite the section and the Quick Start dependency list.
- grpc.go / internal/grpc/README.md: state the real status (tagged JSON
  transport, direct go.mod requirement, internal package, no caller
  starts it) and drop the stale "until stubs are added" comments.
- grpc_engine_test.go: exercise EngineChatService over a store-backed
  conversation.Engine without the build tag: aggregated deltas, saved
  node ID, request fields forwarded, stream error surfaced, nil request
  rejected (F042).

* docs(engine): document and guard the frozen engine-internal symbols

README and AGENTS.md said hosts depend only on engine/llm/graph/tools
and that credentials, provider and the rest are not shared contracts.
But the facade exposes engine-internal symbols: engine.MapStore,
DefaultStore and SetDefaultStore re-export credentials, Options.
SecretStore is a credentials.Store, OperationsGraphInput/Export alias
operationsgraph, and Options.RateLimitConfig/CacheConfig carry
provider/resilience and provider/cache structs (plus HeaderExtractor
and RateLimitHeaders transitively). Rho's import-path checks cannot see
through these aliases.

Narrowing the exports is not possible without breaking rho: its
production code uses engine.MapStore, DefaultStore, SetDefaultStore,
OperationsGraphInput and BuildOperationsGraph. So document the set as
frozen contract-v2 symbols instead:

- HOST-ENGINE-BOUNDARY.md: new "Frozen engine-internal types" table.
- README, AGENTS.md, engine/doc.go: point at it; replace the
  nonexistent `client` package with `provider`.
- engine/host_surface_test.go: walk the exported surface of the four
  contract packages with go/ast, follow engine-internal symbols through
  struct fields, signatures and exported methods, and fail when the
  reachable set differs from the frozen list or the doc omits one
  (F043).

* docs(architecture): drop the nonexistent flux serve binary

docs/ARCHITECTURE.md advertised a Port 8080 badge, "Override: flux serve
<port>" and "Set via FLUX_API_KEY". flux is a library with no cmd/ and
no serve command, nothing reads FLUX_API_KEY, and internal/api's server
takes its key from api.Config.APIKey and its address from
ListenAndServe(addr); nothing in flux starts it.

Other claims in the same doc were also false: the provider-detection
table (openai is 19th, not 2nd, and detection reads the credential
store, not env vars), "blocking responses wrap the stream" (FluxClient.
Chat calls the provider's blocking Chat), sr.Events() (a field, not a
method), Retry-After "on 429 only", and the caching table (the exact
cache is provider/cache, the similarity cache is provider/embeddings).

docs/README.md listed docs/api/openapi.yaml (it is at the repo root),
three guides that do not exist, a Discussions link although Discussions
are disabled, and claimed the OpenAPI spec covers /v1/chat/completions,
/rerank and /ready, which it does not.

Rewrite those sections to match the code and note the OpenAPI gap
(F273).

* docs(agents): point AGENTS.md and the README tree at real files

AGENTS.md cited provider/stream.go, provider/resilience/fallback.go,
provider/errors.go and errors/errors.go (none exist), told contributors
to add providers as provider/<name>.go registered in
provider_registry.go, named provider.NewFluxClient and parseSSEStream
(neither exists), said DetectProvider checks env vars in
ANTHROPIC/OPENAI order, pointed "semantic caching" at the exact-match
cache, and described a parent graycode-eco/go.work that does not exist.
The README architecture tree listed errors/, catalog/legacy/ and
internal/version/ (none exist) and omitted the llm, graph and tools
contract packages.

- AGENTS.md: real paths and symbols, the actual add-a-provider flow
  (registry spec, config profile, setup deployment case, live fetcher,
  adapter only when not OpenAI-compatible), the real linter set, and
  the no-go.work/no-replace rule.
- README: rebuild the architecture tree from the current layout.
- docs_paths_test.go: fail when a path cited in AGENTS.md or an entry in
  the README.md / docs/README.md trees does not exist (F272).

* docs: correct five stale file paths in AGENTS.md

docs_paths_test.go asserts that every path-like token in AGENTS.md resolves to
a real file. Merging main's prose during the rebase reinstated citations that
had been fixed on this branch:

- provider/stream.go            -> provider/core/stream.go
- provider/resilience/fallback.go -> router/router.go, router/deployment_router.go
- provider/errors.go            -> provider/core/errors.go
- errors/errors.go              -> types/errors.go
- provider/adapters/AnthropicClient -> provider/adapters/anthropic.go


---------

Author: Patel230

.env.example

@@ -1,37 +1,37 @@
 # flux environment variables — copy to .env and fill in
 
-# Provider API keys (or store them in the OS keychain — see
-# docs/guides/CREDENTIAL-SETUP-FLOW.md)
-FLUX_API_KEY=
-OPENAI_API_KEY=
+# Provider credentials, one per registry entry in catalog/registry/providers.go
+# (registry SortOrder). Or store them in the OS keychain — see
+# docs/guides/CREDENTIAL-SETUP-FLOW.md. catalog/registry/docs_test.go keeps this
+# block in sync with the registry.
+AGNES_API_KEY=
+AWS_SECRET_ACCESS_KEY=
 ANTHROPIC_API_KEY=
-GEMINI_API_KEY=
+AZURE_OPENAI_API_KEY=
+CANOPYWAVE_API_KEY=
+CLINE_API_KEY=
+CONCENTRATE_API_KEY=
 DEEPSEEK_API_KEY=
+GEMINI_API_KEY=
 GROQ_API_KEY=
-KIMI_API_KEY=
 MOONSHOT_API_KEY=
-ZAI_API_KEY=
-ZAI_CODING_API_KEY=
-XIAOMI_MIMO_PAYG_API_KEY=
-XIAOMI_MIMO_TOKEN_PLAN_API_KEY=
-MINIMAX_API_KEY=
+LONGCAT_API_KEY=
+MINIMAX_PAYG_API_KEY=
 MINIMAX_TOKEN_PLAN_API_KEY=
-AZURE_OPENAI_API_KEY=
-AWS_SECRET_ACCESS_KEY=
-VERTEX_ACCESS_TOKEN=
+OPENAI_API_KEY=
+OPENCODEGO_API_KEY=
 OPENROUTER_API_KEY=
-CONCENTRATE_API_KEY=
-OPENGATEWAY_API_KEY=
-STEPFUN_API_KEY=
-AGNES_API_KEY=
-LONGCAT_API_KEY=
-FIREWORKS_API_KEY=
-CANOPYWAVE_API_KEY=
+OLLAMA_BASE_URL=
 POOLSIDE_API_KEY=
-CLINE_API_KEY=
-OPENCODEGO_API_KEY=
+VERTEX_ACCESS_TOKEN=
 XAI_API_KEY=
-OLLAMA_BASE_URL=
+XIAOMI_MIMO_PAYG_API_KEY=
+XIAOMI_MIMO_TOKEN_PLAN_API_KEY=
+ZAI_CODING_API_KEY=
+ZAI_API_KEY=
+STEP_API_KEY=
+OPENGATEWAY_API_KEY=
+FIREWORKS_API_KEY=
 
 # Default model overrides
 OPENAI_MODEL=gpt-4o

AGENTS.md

@@ -8,7 +8,8 @@ When starting any new work (feature, fix, refactor, chore), always create a feat
 
 ## Design Principles
 
-- **Model-agnostic** — single interface for 75+ LLM providers
+- **Model-agnostic** — single interface for the 28 provider gateways in
+  `catalog/registry/providers.go` (see README "Supported Providers")
 - **Host-neutral engine** — Flux owns provider routing, transport, caching,
   retry/fallback, and normalized telemetry; hosts own product UX and semantics
 - **Streaming-first** — all responses are streamed; blocking is opt-in
@@ -55,6 +56,12 @@ make ci                          # Full CI suite
   `StreamResult`, `ResponseFormat`, `ImageURLPart`, `InputAudioPart`) live in
   `llm` with no `engine` alias; widening the facade to cover them is a
   deliberate API change, not an incidental one.
+- The facade already exposes a frozen set of engine-internal symbols
+  (`credentials.Store`/`MapStore`, `operationsgraph.Input`/`Export`, the
+  `provider/resilience` rate-limit config and `provider/cache.CacheConfig`),
+  listed in `docs/architecture/HOST-ENGINE-BOUNDARY.md`. Changing them breaks
+  hosts. `engine/host_surface_test.go` fails whenever that reachable set
+  changes; update its list and the doc together, deliberately.
 - `provider/core.Provider` is the lower-level provider contract; keep its
   method set stable and use it across feature packages
 - Streaming tests need careful goroutine management
@@ -77,7 +84,7 @@ make ci                          # Full CI suite
 - **Provider interface**: `provider/core.Provider` with `Chat()`, `StreamChat()`, `Ping()`, `Name()`
 - **Core request types**: `provider/core.FluxMessage`, `FluxResponse`, `FluxTool`, `FluxUsage`
 - **Config struct**: `provider/core.FluxConfig` with `Provider`, `APIKey`, `BaseURL`, `Model`, `MaxRetries`
-- **Provider implementations**: `provider/adapters/AnthropicClient`, `OpenAIClient`, `GeminiClient`, etc.
+- **Provider implementations**: `provider/adapters/anthropic.go` (`AnthropicClient`), `openai.go` (`OpenAIClient`), `gemini.go` (`GeminiClient`), etc.
 - **Compatibility configs**: `provider/adapters.OpenAICompat`, `GrokCompat`, `OpenRouterCompat`
 - **Error type**: `FluxError` with `Provider`, `Op`, `StatusCode`, `RequestID`, `Message`, `Err` fields
 - **Stream types**: `StreamResult`, `SSEEvent`, `StreamEvent` — streaming is SSE-based
@@ -140,14 +147,14 @@ make ci                          # Full CI suite
 | Azure provider | `provider/adapters/azure.go` |
 | Provider registry | `provider/adapters/provider_registry.go` |
 | Provider compatibility | `provider/adapters/compat.go` (`OpenAICompat`, `GrokCompat`, etc.) |
-| SSE streaming | `provider/stream.go` (`parseSSEStream()`, `SSEEvent`) |
+| SSE streaming | `provider/core/stream.go` (`parseSSEStream()`, `SSEEvent`) |
 | Retry logic | `provider/core/retry.go` (`RetryConfig`, `backoffDelay()`, `shouldRetry()`) |
 | Rate limiting | `provider/resilience/ratelimit.go`, `provider/resilience/adaptive_ratelimit.go` |
 | Caching | `provider/cache/cache.go`, `provider/cache/semantic_cache.go` |
-| Fallback chains | `provider/resilience/fallback.go` |
+| Fallback chains | `router/router.go` (fallback providers), `router/deployment_router.go` (fallback deployment stages) |
 | Auto-continuation | `provider/resilience/continuation.go` |
-| Error types | `provider/errors.go` (`FluxError`, `IsRetriable()`, `IsAuthError()`) |
-| Error constants | `errors/errors.go` (API error messages, prompt-too-long parsing) |
+| Error types | `provider/core/errors.go` (`FluxError`, `IsRetriable()`, `IsAuthError()`) |
+| Error constants | `types/errors.go` (API error messages, prompt-too-long parsing) |
 | Model catalog | `catalog/` (pricing, context windows, capabilities per provider) |
 | Credentials | `credentials/` (key storage, env detection, scrubbing) — `HasSecret` is silent on miss (boolean predicate); `LookupSecret` logs `Debug` on `ErrNotFound` and `Warn` on real backend errors |
 | Mock provider | `provider/testkit/mock.go` |

README.md

@@ -61,6 +61,13 @@ Everything else is engine-internal: `provider`, `catalog`, `config`,
 contracts. Enforced by `rho/scripts/check-flux-engine-boundary.sh`
 and two Go AST tests in `rho/internal/testaudit/`.
 
+Exception: a fixed set of engine-internal symbols is reachable through the
+facade (for example `credentials.Store` behind `engine.Options.SecretStore`
+and `operationsgraph.Input` behind `engine.OperationsGraphInput`). Those
+symbols are frozen as part of the contract; see
+[Frozen engine-internal types](docs/architecture/HOST-ENGINE-BOUNDARY.md#frozen-engine-internal-types).
+`engine/host_surface_test.go` fails when that set changes.
+
 - do not import `rho/internal/*`
 - do not import the removed legacy path `rho/shared/types`
 
@@ -70,8 +77,9 @@ and two Go AST tests in `rho/internal/testaudit/`.
 go get github.com/GrayCodeAI/flux
 ```
 
-Requires Go 1.26+ and a configured provider credential. Minimal dependencies
-(UUID, OpenTelemetry, SQLite, keyring).
+Requires Go 1.26+ and a configured provider credential. Direct dependencies:
+UUID, tiktoken tokenizer, OS keyring, OpenTelemetry, pure-Go SQLite, and gRPC
+(linked only into `-tags grpc` builds of `internal/grpc`).
 
 ```go
 import (
@@ -171,9 +179,9 @@ Named `primary` / `weak` / `editor` model slots with fallback to primary, plus a
 
 `POST /rerank` endpoint (provider-backed with lexical fallback) and a `GET /ready` readiness probe alongside the existing health check.
 
-### gRPC Skeleton
+### gRPC Transport (opt-in, internal)
 
-Dependency-free gRPC API skeleton behind the `grpc` build tag — wired when generated stubs are available.
+`internal/grpc` holds an optional gRPC transport behind the `grpc` build tag. It serves `flux.v1.ChatService/Chat` with a registered `json` content subtype (no `.proto` files or generated stubs; clients call with `grpc.CallContentSubtype("json")`), backed by `EngineChatService` over `conversation.Engine`. The package is internal, so hosts cannot import it, and nothing in flux starts it. `google.golang.org/grpc` is a direct requirement in `go.mod`, so it appears in consumers' module graphs, but only `-tags grpc` builds link it.
 
 ## Documentation
 
@@ -199,40 +207,40 @@ ANTHROPIC_API_KEY=sk-... go run ./examples/basic/
 
 ## Supported Providers
 
-28 provider gateways in `catalog/registry/providers.go` (rho `/config` uses the same list), listed in registry `SortOrder`:
+28 provider gateways in `catalog/registry/providers.go` (rho `/config` uses the same list), listed in registry `SortOrder`. `catalog/registry/docs_test.go` fails when this table, the count, or `.env.example` drift from the registry.
 
 | Provider | ID | Env variable |
 |---|---|---|
+| **Agnes** | `agnes` | `AGNES_API_KEY` |
+| **Amazon Bedrock** | `bedrock` | `AWS_SECRET_ACCESS_KEY` (+ `AWS_ACCESS_KEY_ID`, `AWS_SESSION_TOKEN`) |
 | **Anthropic** | `anthropic` | `ANTHROPIC_API_KEY` |
-| **OpenAI** | `openai` | `OPENAI_API_KEY` |
-| **Google Gemini** | `gemini` | `GEMINI_API_KEY` |
-| **DeepSeek** | `deepseek` | `DEEPSEEK_API_KEY` |
-| **xAI (Grok)** | `grok` | `XAI_API_KEY` |
-| **Kimi (Moonshot)** | `kimi` | `MOONSHOT_API_KEY` |
-| **Z.AI — Coding Plan** | `zai_coding` | `ZAI_CODING_API_KEY` |
-| **Z.AI — Pay-as-you-go** | `zai_payg` | `ZAI_API_KEY` |
-| **Xiaomi (MiMo) Token Plan** | `xiaomi_mimo_token_plan` | `XIAOMI_MIMO_TOKEN_PLAN_API_KEY` (+ region `cn` / `sgp` / `ams`) |
-| **Xiaomi (MiMo) Pay-as-you-go** | `xiaomi_mimo_payg` | `XIAOMI_MIMO_PAYG_API_KEY` |
-| **MiniMax — Token Plan** | `minimax_token_plan` | `MINIMAX_TOKEN_PLAN_API_KEY` |
-| **MiniMax — Pay-as-you-go** | `minimax_payg` | `MINIMAX_PAYG_API_KEY` |
 | **Azure OpenAI** | `azure` | `AZURE_OPENAI_API_KEY` (+ `AZURE_OPENAI_ENDPOINT`) |
-| **Amazon Bedrock** | `bedrock` | `AWS_SECRET_ACCESS_KEY` (+ `AWS_ACCESS_KEY_ID`, `AWS_SESSION_TOKEN`) |
-| **Vertex AI** | `vertex` | `VERTEX_ACCESS_TOKEN` (or `GOOGLE_OAUTH_ACCESS_TOKEN`) |
-| **OpenRouter** | `openrouter` | `OPENROUTER_API_KEY` |
 | **CanopyWave** | `canopywave` | `CANOPYWAVE_API_KEY` |
-| **Poolside** | `poolside` | `POOLSIDE_API_KEY` |
-| **Groq** | `groq` | `GROQ_API_KEY` |
 | **ClinePass** | `clinepass` | `CLINE_API_KEY` |
 | **Concentrate** | `concentrate` | `CONCENTRATE_API_KEY` |
-| **OpenGateway** | `opengateway` | `OPENGATEWAY_API_KEY` |
-| **StepFun** | `stepfun` | `STEPFUN_API_KEY` |
-| **Agnes** | `agnes` | `AGNES_API_KEY` |
+| **DeepSeek** | `deepseek` | `DEEPSEEK_API_KEY` |
+| **Google Gemini** | `gemini` | `GEMINI_API_KEY` |
+| **Groq** | `groq` | `GROQ_API_KEY` |
+| **Kimi (Moonshot)** | `kimi` | `MOONSHOT_API_KEY` |
 | **LongCat** | `longcat` | `LONGCAT_API_KEY` |
-| **Fireworks AI** | `fireworks` | `FIREWORKS_API_KEY` |
+| **MiniMax — Pay-as-you-go** | `minimax_payg` | `MINIMAX_PAYG_API_KEY` |
+| **MiniMax — Token Plan** | `minimax_token_plan` | `MINIMAX_TOKEN_PLAN_API_KEY` |
+| **OpenAI** | `openai` | `OPENAI_API_KEY` |
 | **OpenCode Go** | `opencodego` | `OPENCODEGO_API_KEY` |
+| **OpenRouter** | `openrouter` | `OPENROUTER_API_KEY` |
 | **Ollama** | `ollama` | `OLLAMA_BASE_URL` (local; no API key) |
+| **Poolside** | `poolside` | `POOLSIDE_API_KEY` |
+| **Vertex AI** | `vertex` | `VERTEX_ACCESS_TOKEN` (or `GOOGLE_OAUTH_ACCESS_TOKEN`) |
+| **xAI (Grok)** | `grok` | `XAI_API_KEY` |
+| **Xiaomi (MiMo) Pay-as-you-go** | `xiaomi_mimo_payg` | `XIAOMI_MIMO_PAYG_API_KEY` |
+| **Xiaomi (MiMo) Token Plan** | `xiaomi_mimo_token_plan` | `XIAOMI_MIMO_TOKEN_PLAN_API_KEY` (+ region `cn` / `sgp` / `ams`) |
+| **Z.AI — Coding Plan** | `zai_coding` | `ZAI_CODING_API_KEY` (+ region `international` / `cn`) |
+| **Z.AI — Pay-as-you-go** | `zai_payg` | `ZAI_API_KEY` (+ region `international` / `cn`) |
+| **StepFun** | `stepfun` | `STEP_API_KEY` (+ region `global` / `cn`) |
+| **OpenGateway** | `opengateway` | `OPENGATEWAY_API_KEY` |
+| **Fireworks AI** | `fireworks` | `FIREWORKS_API_KEY` |
 
-Runtime auto-detection uses a separate priority order for chat when no deployment is pinned; see `config` profiles.
+Runtime auto-detection uses a separate priority order (`config.APIProviderDetectionOrder`) when no deployment is pinned.
 
 ## Usage
 
@@ -289,38 +297,54 @@ config.SaveProviderConfig(cfg, "")               // save changes
 
 ```
 flux/
-├── engine/                 # Stable host-facing facade and provider-neutral DTOs
-├── provider/               # Provider runtime and feature packages
+├── engine/                 # Stable host-facing facade (hosts import engine, llm, graph, tools)
+├── llm/                    # Host-facing DTOs and the Provider port that engine re-exports
+├── graph/                  # Portable execution-graph vocabulary
+├── tools/                  # Tool-call and tool-result contracts
+├── provider/               # Provider runtime composition root (FluxClient)
 │   ├── core/               # Provider-neutral wire, stream, retry, and transport primitives
 │   ├── adapters/           # Provider protocol adapters and construction registry
-│   └── embeddings/         # Embedding clients, cache, and defaults
-├── config/                 # Provider configuration & routing
-│   └── credential/         # Credential file management
+│   ├── resilience/         # Rate limits, continuation, guardrails, and error policy
+│   ├── cache/              # Response and semantic caches
+│   ├── batch/              # Batch execution
+│   ├── embeddings/         # Embedding clients, cache, and defaults
+│   ├── media/              # Image and audio clients, structured prompts
+│   ├── extraction/         # Structured extraction
+│   ├── observability/      # Usage, cost, metrics, tracing, and recording
+│   └── testkit/            # Mock provider for tests
 ├── catalog/                # Model catalog & tier system
+│   ├── registry/           # Provider registry (single source of truth for providers)
 │   ├── discover/           # Model discovery
-│   ├── legacy/             # Legacy model support
-│   ├── live/               # Live model data
-│   └── registry/           # Model registry
-├── codeagent/              # Code agent retry & fallback strategies
-├── conversation/           # Conversation engine with branching
-├── credentials/            # Credential management
-├── docs/                   # Documentation & guides
-├── examples/               # Runnable code examples
-├── router/                 # Provider routing strategies
+│   ├── live/               # Live model listing per provider
+│   ├── capabilities/       # Capability and deprecation data
+│   └── concentrate/ opencodego/ opengateway/ xiaomi/ zai/  # Gateway-specific helpers
+├── config/                 # Provider configuration & routing
+│   └── credential/         # Credential file management
+├── credentials/            # Keyring/env credential stores and OIDC keyless auth
+├── router/                 # Routing strategies, deployment router, circuit breakers
+│   └── controlplane/       # Versioned, signed peer manifests and replicas
+├── runtime/                # Engine-internal provider/model/credential resolution
+├── setup/                  # Catalog-backed deployment wiring
 ├── operationsgraph/        # Privacy-safe route and generation telemetry projection
-├── runtime/                # Runtime manifest & routing policies
-├── storage/                # SQLite conversation DAG store
-├── types/                  # Branded types & API errors
-├── errors/                 # Error message constants
+├── conversation/           # Conversation engine with branching
+├── storage/                # SQLite conversation DAG store, virtual keys, budgets
+├── codeagent/              # Code agent retry & fallback strategies
+├── verify/                 # Provider conformance harness
+├── types/                  # Shared message types & API errors
 ├── constants/              # API limits
 ├── utils/                  # Error utilities
+├── api/                    # OpenAPI spec for internal/api
 ├── internal/
-│   ├── api/                # HTTP API handlers
-│   ├── cache/              # Response cache warmer
+│   ├── api/                # HTTP API server (library code; no flux binary starts it)
+│   ├── cache/              # Cache backends and response cache warmer
+│   ├── grpc/               # Optional gRPC transport (build tag grpc)
 │   ├── health/             # Provider health checker
-│   ├── observability/      # OpenTelemetry spans & metrics
-│   ├── sdk/                # Go, Python, TypeScript client SDKs
-│   └── version/            # Version information
+│   ├── httputil/ probehttp/ shrink/  # HTTP, probe, and tool-description helpers
+│   ├── observability/      # OpenTelemetry spans, metrics, and audit sinks
+│   └── sdk/                # Go, Python, TypeScript clients for the internal/api HTTP surface
+├── docs/                   # Documentation & guides
+├── examples/               # Runnable code examples
+├── scripts/                # CI guards and helper scripts
 └── assets/                 # Logo and branding
 ```