From e88651b67401ef21a55710bc8f2ae71b2dab58b9 Mon Sep 17 00:00:00 2001 From: Miya Date: Thu, 10 Sep 2026 16:22:23 +0200 Subject: [PATCH] fix(docs): clarify inline model behavior without project config Session-Id: 01a08ba4-4473-7903-b7c3-e778edb9b523 Session-Id: 01a08ba4-4473-7903-b7c3-e778edb9b523 --- docs/SURFACE.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/SURFACE.md b/docs/SURFACE.md index ea42412ee..742181f7b 100644 --- a/docs/SURFACE.md +++ b/docs/SURFACE.md @@ -163,14 +163,20 @@ No process runs between events: the handler wakes, executes to its next await, p **Deterministic model registry:** model existence is not inferred from a regex or provider prefix. The nearest `flows.json` owns an exact, - case-sensitive `models` allowlist. `flows check` first refuses a declared - model absent from that list as `model_unknown`, without starting the CLI. - One pure first pass collects every unknown named/inline model and every + case-sensitive `models` allowlist. When that file exists, `flows check` + first refuses a declared model absent from that list as `model_unknown`, + without starting the CLI. When no `flows.json` exists anywhere in the flow + file's ancestry, inline named-agent declarations (`agents: { drafter: + { cli, model } }`) proceed to the real CLI/model probe without a registry. + A model declared directly on a step still requires the project allowlist. + An existing config with no `models` field or an empty list remains an + explicit policy and refuses unlisted models, including named agents. + One pure first pass collects every model rejected by that policy and every unresolved step CLI before any CLI, command, executor, or daemon probe, independent of step order. This includes every named declaration, even when unused or shadowed - by a step override; - only an allowlisted value reaches the live model-scoped probe above. The + by a step override. When a registry exists, only an allowlisted value + reaches the live model-scoped probe above. The registry is author-owned project configuration, reviewed and versioned with the project. Updating it is an explicit file change made only after the project verifies access to the added model. No remote catalog is fetched,