mcpx: thin provider layer core — internal/model, model.* settings, intent routing (#1925 slice 1)

pkgs/mcpx/docs/configuration.md

@@ -432,6 +432,17 @@ and a switch to turn the report off would have kept it quiet.
 | `mcp.pageSize` | int | `100` | client | no | `--mcp-page-size` | `MCPX_MCP_PAGE_SIZE` | how many items one tools/list reply carries |
 | `mcp.passthrough` | string | *(empty)* | client | no | `--mcp-passthrough`, `--passthrough` | `MCPX_MCP_PASSTHROUGH` | serve upstreams' tools, prompts and resources under their own names |
 
+### model
+
+| setting | kind | default | scope | hot | flag | variable | governs |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `model.apiKeyEnv` | string | *(empty)* | daemon | no | `--model-api-key-env` | `MCPX_MODEL_API_KEY_ENV` | the environment variable holding the configured provider's API key |
+| `model.baseURL` | string | *(empty)* | daemon | no | `--model-base-url` | `MCPX_MODEL_BASE_URL` | the OpenAI-compatible endpoint the configured provider calls |
+| `model.budget` | int | `0` | daemon | no | `--model-budget` | `MCPX_MODEL_BUDGET` | hard ceiling on the tokens one generation through the layer may ask for; 0 is no ceiling |
+| `model.default` | string | *(empty)* | daemon | no | `--model-default` | `MCPX_MODEL_DEFAULT` | the model id used when an operation names none, as provider/model |
+| `model.provider` | enum | `none` | daemon | no | `--model-provider` | `MCPX_MODEL_PROVIDER` | where mcpx's own generation gets a model: a configured provider, sampling through the caller, or none |
+| `model.timeout` | duration | `1m30s` | daemon | no | `--model-timeout` | `MCPX_MODEL_TIMEOUT` | how long one generation through the layer may take |
+
 ### output
 
 | setting | kind | default | scope | hot | flag | variable | governs |

pkgs/mcpx/docs/consumer.md

@@ -236,11 +236,24 @@ through it. It is one function, marked, for exactly that reason.
 
 **Scope — "anything that makes mcpx call a model has to justify that it isn't
 rebuilding the harness."** Three of the four things built here never call one.
-The fourth has no model of its own and never will: option 3 from the issue, a
-configured provider with an API key, was not built and should not be. It is
-the one that makes mcpx an agent. Sampling through the caller is the opposite
-— it is mcpx asking the harness it already sits under, which is what the
-specification is for.
+The fourth originally stopped there: option 3 from the issue, a configured
+provider with an API key, was not built, on the grounds that it is the one
+that makes mcpx an agent. That conclusion has since been reversed by the
+facts #1925 records: the 2026-07-28 MCP revision deprecates sampling
+(SEP-2577) and names integrating directly with provider APIs as the
+migration, and no opencode — the primary consumer — declares sampling at
+all. So a configured provider now exists, as one backend of the thin
+provider layer in `internal/model`: a `Provider` interface with a single
+`Generate`, reached only through the `model.*` settings, with
+`model.provider` defaulting to `none` — a user who configures nothing gets
+exactly the behaviour described above. Sampling through the caller survives
+as another backend of the same layer: it is mcpx asking the harness it
+already sits under, which remains right where a client declares it. What
+has not changed is the guard that made the original refusal coherent: no
+operation calls a model on a path where a deterministic answer exists, and
+a provider error returns the deterministic result plus a note that the
+model was unavailable. A `Generate` function is not an agent; the harness
+mcpx sits under still owns the loop, the tools and the session.
 
 **Trust — "generated code runs with the user's credentials."** Return the
 script by default (`prompt.autonomy: propose`, one level of the dial in