feature/Drop-mcp-pr-citation · L-261026-5f9cda

docs/decisions.md

@@ -733,7 +733,7 @@ The workshop-proving campaign found that a designed method pinned a model handle
 - **Leave `model` out unless the user asks for a model, a setting or a kind of behaviour.** The default is the deployment's, which the account can run; anything else pins a model a gateway may refuse, which validation cannot see. With the deck listable, a setting no longer forces an invented handle, so the exception covers it again: the skill offers the category's presets, or puts the setting in an inline table on an alias the deck lists.
 - **An input the default cannot read names its model, asked or not.** The rule above predates the lookup, when it read "omit `model` unless the user names a model", and followed to the letter it dropped the one model a web page needs. The extract deck's default choice is `@default-extract-document`, Azure Document Intelligence, whose gateway entry lists `inputs = ["pdf", "image"]`, while `@default-extract-web-page` points at `linkup-fetch`, whose entry lists `inputs = ["web_page"]`; under the default, the runner downloads the URL's bytes and sends them as a document (`pipelex/providers/gateway/gateway_extract_worker.py`, `_extract_document`), and only `linkup-fetch` takes the web-fetch path that honours `render_js` and `include_raw_html`. On the dev API on 2026-09-28, a one-pipe `PipeExtract` with no `model` validated, and its run over `https://example.com` failed at the extraction with "Could not identify file type of given bytes: b'<!doctype html>…'" (`run_6cca0f3c-b19c-4c9c-86a1-16e121c2eb2f`), while the same pipe with `@default-extract-web-page` read the page (`run_2da99bdc-755e-4fe3-a176-24d11cf65046`). A URL to a PDF read under the default in the same session, so the carve-out follows what the URL holds, not the fact that it is a URL. Validation cannot catch the mismatch, since a `Document` input says nothing of what it will hold, so the reference states the carve-out beside the omit rule and makes the web-page sentence of `PipeExtract`'s section a rule rather than "if needed", and `pipelex-run` routes that failure to `pipelex-edit` rather than to `pipelex-inputs`, which its wording would otherwise suggest: the input is sound, and the method lacks its model.
 - **An inline table's `model` is an alias, a waterfall or a handle, never a preset, and validation never looks at it.** `pipelex`'s `PipeLLM.validate_inputs_static` skips an inline table ("an inline setting table is not a reference and is not looked up"), and at run time the model deck resolves the table's `model` through aliases and waterfalls but refuses a preset (`pipelex/cogt/models/model_deck.py`, `_get_optional_inference_model`). So a wrong reference there fails only once a run reaches the pipe, after credit is spent, and the section says to write one only once `mthds_models` answers `resolved`. The example names `@default-general`, the alias the default deck's `for_text` choice uses, rather than a handle placeholder: an agent that copies it pins nothing the default does not already use. A one-pipe method written with that table validated and ran on the dev API on 2026-09-28 (`run_fa86a4a3-a8e4-442d-8bed-27b53d80d207`).
-- **A hint is read before the resolution's own branch, and the check is the runner's.** Since pipelex-mcp#132 (43f325c), `mthds_models` relays the runner's own reference check, `GET /v1/models/check`, which answers as a validation of the same reference would: `resolved` or `not_found`. A `resolved` answer never carries a sigil hint, while a `not_found` one can carry a sigil hint, a category hint or both, and acting on the resolution first would skip them. On the dev API on 2026-10-10, `$best-gpt` checked as `llm` answered `not_found` with `other_kinds: ["@best-gpt"]`, and `gpt-image-2` checked as `llm` answered `not_found` with `img_gen` in `other_categories` and `gpt-oss-20b` and `gpt-oss-120b` as its suggestions, which read first would have offered two language models for an image model. So the section reads the answer in one order, the hints before the resolution's own branch, and acts on the first case that fits; as separate rules, `$best-gpt` `not_found` with `@best-gpt` beside it was told both to write the alias and to write only what the user picks. A bare name the runtime finds through an alias resolves as a handle (`best-gpt` reached `gpt-6.1-sol` the same day), so the section's `other_kinds` example is a preset's sigil, not a missing one. Until #132, the workshop checked references against the deck with a copy of the runner's parser and answered a third outcome, `unconfirmed`, for a bare handle no alias or waterfall named, which the section wrote only as a pipe's `model` string so that `mthds_validate` would check it; the runner knows every model it can call, so the outcome and its rule were retired on 2026-10-10. A model named together with a setting has no safe form when the model does not resolve, reaches no model or is a preset, since the setting needs an inline table, the table is never validated, and a preset answers `resolved` yet is refused inside one at run time; the skill says so and lets the user keep the setting on an alias the deck lists or the model without the setting, written as the typed-reference case allows.
+- **A hint is read before the resolution's own branch, and the check is the runner's.** Since `@pipelex/mcp` 0.24.0, `mthds_models` relays the runner's own reference check, `GET /v1/models/check`, which answers as a validation of the same reference would: `resolved` or `not_found`. A `resolved` answer never carries a sigil hint, while a `not_found` one can carry a sigil hint, a category hint or both, and acting on the resolution first would skip them. On the dev API on 2026-10-10, `$best-gpt` checked as `llm` answered `not_found` with `other_kinds: ["@best-gpt"]`, and `gpt-image-2` checked as `llm` answered `not_found` with `img_gen` in `other_categories` and `gpt-oss-20b` and `gpt-oss-120b` as its suggestions, which read first would have offered two language models for an image model. So the section reads the answer in one order, the hints before the resolution's own branch, and acts on the first case that fits; as separate rules, `$best-gpt` `not_found` with `@best-gpt` beside it was told both to write the alias and to write only what the user picks. A bare name the runtime finds through an alias resolves as a handle (`best-gpt` reached `gpt-6.1-sol` the same day), so the section's `other_kinds` example is a preset's sigil, not a missing one. Before that release, the workshop checked references against the deck with a copy of the runner's parser and answered a third outcome, `unconfirmed`, for a bare handle no alias or waterfall named, which the section wrote only as a pipe's `model` string so that `mthds_validate` would check it; the runner knows every model it can call, so the outcome and its rule were retired on 2026-10-10. A model named together with a setting has no safe form when the model does not resolve, reaches no model or is a preset, since the setting needs an inline table, the table is never validated, and a preset answers `resolved` yet is refused inside one at run time; the skill says so and lets the user keep the setting on an alias the deck lists or the model without the setting, written as the typed-reference case allows.
 - **A resolved reference that reaches no model is written only on the user's word.** Each match of a `resolved` answer carries `resolves_to`, the model a run through the reference calls now, or `null` when its binding reaches no model the runner can call. On the dev API on 2026-10-10, `@default-judgment` checked as `judgment` answered `resolved` with `target: "jev-1.13.0"` and `resolves_to: null`: a method naming it validates, and a run fails at that pipe after the pipes before it have spent credit. The workshop's own summary calls this a warning and says to prefer a reference that reaches a model, so the section says so to the user and writes it only if they still want it, rather than refusing, since `resolves_to` describes the moment of the check and a model can come back; an inline table, which nothing validates, never holds one.
 - **The deck is what the runner can serve, not what the account may use.** On the dev API, a model on the gateway's list was refused with `model_not_allowed_error`. The section says so, and that leaving `model` out stays the safest choice, rather than presenting the listing as the account's; an account-level check belongs to the platform.
 - **A workshop without the tool falls back to the old answer.** `mthds_models` arrived after `@pipelex/mcp` 0.20.0, so a workshop older than the release that brought it answers every other tool: there a model or a reference the user typed is written as a pipe's `model` string, which `mthds_validate` checks, and never in an inline table, which nothing would check, so a setting asked with it is left out and the user told; only when no model was named does the skill offer a preset the reference names, or ask which model, and it never invents a reference. Offering a preset in place of a reference the user typed would throw away an explicit request. It is a narrower answer, not a stop, since no model field is required, and `pipelex-edit`'s requirements say so beside the tool's name, where the stops are. A workshop that has the tool but not a category is the same case for one pipe: `mthds_models` takes its category from a closed list, so a workshop older than the release that brought a category refuses that value as invalid input. `@pipelex/mcp` 0.22.0 knew four categories when the reference added `judgment`, the MTHDS protocol's category for a `PipeJudge`, so the fallback names that case rather than leaving a refused lookup to the agent.