Docs: document centralized model registry

Add a documentation menu and refresh the architecture and API guides\nto reflect the shared core-owned model registry contract.\n\nDocument the resolved payload flow, removed local policy ownership,\nand current model-selection entrypoints for Codex consumers.

Author: nshkrdotcom

README.md

@@ -13,6 +13,15 @@
 
 An idiomatic Elixir SDK for embedding OpenAI's Codex agent in your workflows and applications. This SDK wraps the `codex-rs` executable, providing a complete, production-ready interface with streaming support and comprehensive event handling.
 
+## Documentation Menu
+
+- `README.md` - installation, quick start, and runtime boundaries
+- `guides/01-getting-started.md` - first threads, turns, and sessions
+- `guides/02-architecture.md` - transport layering and ownership boundaries
+- `guides/03-api-guide.md` - public modules and common call patterns
+- `guides/07-models-and-reasoning.md` - shared catalog projections and reasoning controls
+- `guides/08-configuration-defaults.md` - config precedence and default resolution
+
 ## Features
 
 - **End-to-End Codex Lifecycle**: Spawn, resume, and manage full Codex threads with rich turn instrumentation.
@@ -115,9 +124,35 @@ Custom trust roots use `CODEX_CA_CERTIFICATE` first and `SSL_CERT_FILE` second.
 ignored. The same PEM bundle is applied consistently to Codex CLI subprocesses, direct HTTP
 clients, remote model fetches, MCP HTTP/OAuth, realtime websockets, and voice HTTP requests.
 
-Default model: `Codex.Models.default_model/0` currently resolves to `gpt-5.4` with the bundled catalog unless `CODEX_MODEL`, `OPENAI_DEFAULT_MODEL`, `CODEX_MODEL_DEFAULT`, or a fresher ChatGPT `/models` cache overrides it.
+## Centralized Model Selection
+
+`codex_sdk` no longer owns the active model catalog, fallback rules, or default
+selection policy. That authority now lives in `cli_subprocess_core`.
+
+The authoritative path is:
+
+- `CliSubprocessCore.ModelRegistry.resolve/3`
+- `CliSubprocessCore.ModelRegistry.validate/2`
+- `CliSubprocessCore.ModelRegistry.default_model/2`
+- `CliSubprocessCore.ModelRegistry.build_arg_payload/3`
+
+`Codex.Options.new/1` resolves a shared `model_payload`, then projects the
+current `model` and `reasoning_effort` from that payload. `Codex.Models` is now
+a read-only projection of the shared core catalog. It no longer owns a separate
+catalog or a separate fallback/defaulting path.
+
+Operationally, that means:
+
+- explicit request wins first
+- environment override comes next
+- provider default and remote default are core-owned, not SDK-owned
+- missing provider, missing model, placeholder model input, and invalid
+  reasoning effort all fail through the core error contract
+- CLI argument rendering only emits `--model` from a non-empty resolved value
 
-The SDK always loads the bundled upstream model catalog from `priv/models.json`, which is synced from the vendored upstream catalog in `codex/codex-rs/core/models.json`. When ChatGPT auth tokens are available it can still refresh `/models` and cache the result, but the old `features.remote_models` flag is no longer required for current catalog/default behavior. See `guides/07-models-and-reasoning.md` for the current bundled snapshot and how to inspect the effective runtime list.
+Use `Codex.Models.default_model/0`, `Codex.Models.list_visible/1`, and
+`Codex.Models.default_reasoning_effort/1` as convenience readers over that
+shared contract.
 
 See the [OpenAI Codex documentation](https://github.com/openai/codex) for more authentication options.
 

guides/02-architecture.md

@@ -74,6 +74,33 @@ The publication boundary on that split is now:
 - optional ASM integration may exist only as an explicit bridge above the
   normalized kernel; it does not re-home these families or widen the core
 
+## Centralized Model Selection
+
+`cli_subprocess_core` is the only model-policy owner in the Codex stack.
+`codex_sdk` consumes the resolved selection payload and never implements a
+second defaulting or fallback path.
+
+Resolution ownership:
+
+- `CliSubprocessCore.ModelRegistry.resolve/3`
+- `CliSubprocessCore.ModelRegistry.validate/2`
+- `CliSubprocessCore.ModelRegistry.default_model/2`
+- `CliSubprocessCore.ModelRegistry.build_arg_payload/3`
+
+Codex-side consumption points:
+
+- `Codex.Options.new/1` resolves `model_payload`, `model`, and
+  `reasoning_effort`
+- `Codex.Models` projects visible models and defaults from the shared catalog
+- `Codex.Runtime.Exec` renders CLI args from the current resolved options state
+
+Contract rules:
+
+- no repo-local model catalog owns policy
+- no implicit provider fallback exists outside the core registry
+- no silent acceptance of blank, placeholder, or invalid model requests
+- no `--model nil`, `--model null`, or blank `--model` emission
+
 ## Component Architecture
 
 ### High-Level Component Diagram

guides/03-api-guide.md

@@ -36,6 +36,43 @@ Complete API documentation for all modules in the Elixir Codex SDK.
 
 ---
 
+## Model Selection APIs
+
+Model policy is centralized in `cli_subprocess_core`. In `codex_sdk`, the
+public API surfaces are projections and consumers of that shared contract.
+
+Primary entrypoints:
+
+- `Codex.Options.new/1` resolves the shared `model_payload` via
+  `CliSubprocessCore.ModelRegistry.build_arg_payload/3`
+- `Codex.Models.default_model/0` returns the current shared core default
+- `Codex.Models.list_visible/1` returns the shared visible Codex catalog
+- `Codex.Models.default_reasoning_effort/1` projects reasoning defaults from
+  the shared catalog
+
+Operational notes:
+
+- `codex_sdk` does not own a separate bundled policy layer anymore
+- unknown model, invalid reasoning effort, and unavailable model errors come
+  from the core registry contract
+- runtime CLI rendering consumes resolved state and does not invent fallback
+  models locally
+
+Example:
+
+```elixir
+{:ok, opts} =
+  Codex.Options.new(%{
+    model: "gpt-5.4-mini",
+    reasoning_effort: :medium
+  })
+
+opts.model_payload.resolved_model
+# => "gpt-5.4-mini"
+```
+
+---
+
 ## Codex.CLI and Codex.CLI.Session
 
 Use `Codex.CLI` when you need the upstream command surface directly rather than