insightfactory-cli 1.1.2.dev28__tar.gz → 1.1.2.dev29__tar.gz

{insightfactory_cli-1.1.2.dev28 → insightfactory_cli-1.1.2.dev29}/CHANGELOG.md

@@ -13,6 +13,22 @@ last one has been released, so a cycle's PRs share a section.
 
 ## 1.1.2
 
+### Added
+
+- The MCP router serves resources, prompts and completion as well as tools, so a
+  factory's hosted skills reach a client through `if-cli mcp` instead of only through a
+  direct connection. `skill://` bodies come from the `--catalog` environment as
+  published; a resource template is republished with an `environment` variable added so
+  the client picks the factory when it expands the URI; a prompt gains the same required
+  `environment` argument a tool gets, plus a line naming the chosen environment in the
+  rendered text.
+- `--skills` / `--no-skills`, and `skills = true` in a `[factory <name>]` section,
+  advertise the experimental skills extension (SEP-2640). Off by default: the handshake
+  is answered before any factory has been reached, so the claim is made only when
+  someone asks for it. The resources themselves are served either way, and only a
+  client on protocol 2026-07-28 or later can see the advertisement, since the
+  `initialize` handshake predates `capabilities.extensions`.
+
 ### Changed
 
 - `release-guard` asks every PR into `develop` for a `CHANGELOG.md` entry, and asks

{insightfactory_cli-1.1.2.dev28 → insightfactory_cli-1.1.2.dev29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: insightfactory-cli
-Version: 1.1.2.dev28
+Version: 1.1.2.dev29
 Summary: Profile-based authentication CLI for the InsightFactory Interfaces API
 Project-URL: Homepage, https://insightfactory.ai
 Author-email: "insightfactory.ai Support" <support@insightfactory.ai>
@@ -255,9 +255,10 @@ tst = example-tst
 writable = dev
 ```
 
-Every key except `writable` and `catalog` is `<environment code> = <profile name>`; file
-order is the environment order. `writable` is a comma-separated list of codes (default
-none); `catalog` is one code (default the first environment). Then:
+Every key except `writable`, `catalog` and `skills` is `<environment code> = <profile name>`;
+file order is the environment order. `writable` is a comma-separated list of codes (default
+none); `catalog` is one code (default the first environment); `skills` is `true` or `false`
+(default false). Then:
 
 ```bash
 uv tool install 'insightfactory-cli[mcp]'
@@ -290,6 +291,7 @@ passed at all, replace the section's value outright, and `--allow-tool` is alway
 | `--read-only` | Forces every environment read-only, overriding both the section's `writable` and any `--writable`. Cannot be combined with `--writable`. |
 | `--catalog CODE` (default: the first environment) | Whose tool list is published; its schemas are the reference every environment is checked against. |
 | `--allow-tool NAME` (repeatable) | Extra tool names treated as read-only, beyond the shipped list. |
+| `--skills` / `--no-skills` | Whether to advertise the experimental skills extension. Off unless the section says `skills = true` or `--skills` is passed. The two cannot be combined. |
 | `--timeout SECONDS` (default `120`) | Per upstream request; higher than the `api` command's default because some tools are slow. |
 
 `mcp`'s `--timeout` does not read `INSIGHTFACTORY_REQUEST_TIMEOUT`: it parses the flag with
@@ -304,6 +306,62 @@ Passing dev-only writes to production means changing an argument value, not
 connecting to a different server, so keep `--writable` scoped to the
 environments meant to be written by hand.
 
+### Resources, prompts and completion
+
+Resources and prompts are not merged across environments the way tools are, because
+a factory's non-tool content splits in two.
+
+`skill://` bodies are documentation that belongs to a release, identical on every
+environment running it, and they cross-reference each other by bare URI. So they are
+served from the `--catalog` environment exactly as published. Rewriting those URIs to
+carry an environment would leave every link inside them pointing at nothing.
+
+A resource template is the other half: `if://task-config-schemas/{taskType}` resolves
+to one factory's own activity catalogue, not to a shared document. The router
+republishes each template with its own variable appended, so the client chooses the
+environment when it expands the URI:
+
+```text
+if://task-config-schemas/{taskType}{?environment}
+```
+
+A template that already opens a query gets `{&environment}` instead, and one that
+ends in a fragment gets the variable in front of it, because a `?` after a `#` is an
+ordinary character rather than a query. A template that already declares an
+`environment` variable is skipped with a line on stderr, so one nonconforming item
+does not hide the rest of the list.
+
+Reading a URI with no `?environment=` is answered by the catalogue environment,
+unless the URI could be an expansion of a published template, which is refused
+naming the codes to choose from. Membership of `resources/list` is deliberately not
+the test: a skill body may link to a sibling document the factory never advertised,
+and such a link carries no `environment` and could not be given one.
+`completion/complete` reads the environment from the request's context arguments,
+then from the reference URI, and falls back to the catalogue environment for anything
+it does not recognise, because a half-typed context value is the normal state of a
+completion request and completion should degrade rather than fail. The router answers
+for the `environment` variable itself rather than asking a factory about an argument
+it has never heard of.
+
+Prompts gain a required `environment` argument like tools. The router also prepends a
+line to every rendered prompt naming the environment chosen, because a factory writes
+its prompts for a client talking to one factory and they tell the model to call tools
+without one. Prepended rather than appended, and marked `[if-cli router]`: the
+factory's own last turn may be an assistant prefill, which a trailing user turn would
+silently end.
+
+`--skills` only controls the advertisement. The handshake is answered before any
+factory has been reached, so the router cannot ask the catalogue environment whether
+it serves skills in time to repeat the claim, and an experimental capability is not
+worth guessing at. The `skill://` resources are served either way.
+
+The advertisement reaches only a client on MCP protocol 2026-07-28 or later.
+`capabilities.extensions` was added in that revision, and the `initialize` handshake
+every current client opens with negotiates a 2025 revision whose capability schema
+has no such field, so the SDK strips it before it reaches the wire. Against
+`foundryaz-dev` with `--skills` on, Claude Code sees no extension and still finds
+every skill through `resources/list`, which is how clients discover them today.
+
 A tool the factory will not run until someone finishes a step in a browser, such
 as linking a personal Databricks identity, comes back as a failed call naming the
 page to visit rather than as a prompt. The router never relays the factory's

{insightfactory_cli-1.1.2.dev28 → insightfactory_cli-1.1.2.dev29}/README.md

@@ -231,9 +231,10 @@ tst = example-tst
 writable = dev
 ```
 
-Every key except `writable` and `catalog` is `<environment code> = <profile name>`; file
-order is the environment order. `writable` is a comma-separated list of codes (default
-none); `catalog` is one code (default the first environment). Then:
+Every key except `writable`, `catalog` and `skills` is `<environment code> = <profile name>`;
+file order is the environment order. `writable` is a comma-separated list of codes (default
+none); `catalog` is one code (default the first environment); `skills` is `true` or `false`
+(default false). Then:
 
 ```bash
 uv tool install 'insightfactory-cli[mcp]'
@@ -266,6 +267,7 @@ passed at all, replace the section's value outright, and `--allow-tool` is alway
 | `--read-only` | Forces every environment read-only, overriding both the section's `writable` and any `--writable`. Cannot be combined with `--writable`. |
 | `--catalog CODE` (default: the first environment) | Whose tool list is published; its schemas are the reference every environment is checked against. |
 | `--allow-tool NAME` (repeatable) | Extra tool names treated as read-only, beyond the shipped list. |
+| `--skills` / `--no-skills` | Whether to advertise the experimental skills extension. Off unless the section says `skills = true` or `--skills` is passed. The two cannot be combined. |
 | `--timeout SECONDS` (default `120`) | Per upstream request; higher than the `api` command's default because some tools are slow. |
 
 `mcp`'s `--timeout` does not read `INSIGHTFACTORY_REQUEST_TIMEOUT`: it parses the flag with
@@ -280,6 +282,62 @@ Passing dev-only writes to production means changing an argument value, not
 connecting to a different server, so keep `--writable` scoped to the
 environments meant to be written by hand.
 
+### Resources, prompts and completion
+
+Resources and prompts are not merged across environments the way tools are, because
+a factory's non-tool content splits in two.
+
+`skill://` bodies are documentation that belongs to a release, identical on every
+environment running it, and they cross-reference each other by bare URI. So they are
+served from the `--catalog` environment exactly as published. Rewriting those URIs to
+carry an environment would leave every link inside them pointing at nothing.
+
+A resource template is the other half: `if://task-config-schemas/{taskType}` resolves
+to one factory's own activity catalogue, not to a shared document. The router
+republishes each template with its own variable appended, so the client chooses the
+environment when it expands the URI:
+
+```text
+if://task-config-schemas/{taskType}{?environment}
+```
+
+A template that already opens a query gets `{&environment}` instead, and one that
+ends in a fragment gets the variable in front of it, because a `?` after a `#` is an
+ordinary character rather than a query. A template that already declares an
+`environment` variable is skipped with a line on stderr, so one nonconforming item
+does not hide the rest of the list.
+
+Reading a URI with no `?environment=` is answered by the catalogue environment,
+unless the URI could be an expansion of a published template, which is refused
+naming the codes to choose from. Membership of `resources/list` is deliberately not
+the test: a skill body may link to a sibling document the factory never advertised,
+and such a link carries no `environment` and could not be given one.
+`completion/complete` reads the environment from the request's context arguments,
+then from the reference URI, and falls back to the catalogue environment for anything
+it does not recognise, because a half-typed context value is the normal state of a
+completion request and completion should degrade rather than fail. The router answers
+for the `environment` variable itself rather than asking a factory about an argument
+it has never heard of.
+
+Prompts gain a required `environment` argument like tools. The router also prepends a
+line to every rendered prompt naming the environment chosen, because a factory writes
+its prompts for a client talking to one factory and they tell the model to call tools
+without one. Prepended rather than appended, and marked `[if-cli router]`: the
+factory's own last turn may be an assistant prefill, which a trailing user turn would
+silently end.
+
+`--skills` only controls the advertisement. The handshake is answered before any
+factory has been reached, so the router cannot ask the catalogue environment whether
+it serves skills in time to repeat the claim, and an experimental capability is not
+worth guessing at. The `skill://` resources are served either way.
+
+The advertisement reaches only a client on MCP protocol 2026-07-28 or later.
+`capabilities.extensions` was added in that revision, and the `initialize` handshake
+every current client opens with negotiates a 2025 revision whose capability schema
+has no such field, so the SDK strips it before it reaches the wire. Against
+`foundryaz-dev` with `--skills` on, Claude Code sees no extension and still finds
+every skill through `resources/list`, which is how clients discover them today.
+
 A tool the factory will not run until someone finishes a step in a browser, such
 as linking a personal Databricks identity, comes back as a failed call naming the
 page to visit rather than as a prompt. The router never relays the factory's

{insightfactory_cli-1.1.2.dev28 → insightfactory_cli-1.1.2.dev29}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "insightfactory-cli"
-version = "1.1.2.dev28"
+version = "1.1.2.dev29"
 description = "Profile-based authentication CLI for the InsightFactory Interfaces API"
 readme = "README.md"
 requires-python = ">=3.10"

{insightfactory_cli-1.1.2.dev28 → insightfactory_cli-1.1.2.dev29}/src/if_cli/commands/mcp.py

@@ -15,12 +15,15 @@ MCP_OPTIONS: Options = {
     "catalog": {"type": "string"},
     "allow-tool": {"type": "string", "repeat": True},
     "timeout": {"type": "string", "default": "120"},
+    "skills": {"type": "boolean"},
+    "no-skills": {"type": "boolean"},
 }
 
 MCP_USAGE = (
     "usage: if-cli mcp [FACTORY] [--env CODE=PROFILE ...]\n"
     "                   [--writable CODE ... | --read-only] [--catalog CODE]\n"
     "                   [--allow-tool NAME ...] [--timeout SECONDS]\n"
+    "                   [--skills | --no-skills]\n"
     "\n"
     "Runs one MCP server over stdio that fronts several factory environments: every\n"
     "tool gets a required 'environment' argument, routed to that environment's own\n"
@@ -29,7 +32,9 @@ MCP_USAGE = (
     "section. Without FACTORY, --env is required at least once. --catalog defaults\n"
     "to the first environment; environments not passed to --writable are read-only;\n"
     "--read-only forces every environment read-only and cannot be combined with\n"
-    "--writable.\n"
+    "--writable. --skills advertises the experimental skills extension; the\n"
+    "catalog environment's skill:// resources are served either way. It is off\n"
+    "unless the factory section says 'skills = true' or --skills is passed.\n"
 )
 
 MISSING_MCP_EXTRA = (
@@ -91,6 +96,9 @@ def mcp_command(argv: list[str]) -> None:
     if read_only and raw_writable is not None:
         die(f"--read-only cannot be combined with --writable\n\n{MCP_USAGE}")
 
+    if values["skills"] and values["no-skills"]:
+        die(f"--skills cannot be combined with --no-skills\n\n{MCP_USAGE}")
+
     config = load_config()
 
     # A dict, not a list of pairs: --env "adds or replaces that code's profile"
@@ -102,12 +110,14 @@ def mcp_command(argv: list[str]) -> None:
     mappings: dict[str, str] = {}
     writable_codes: frozenset[str] = frozenset()
     catalog_source: str | None = None
+    skills = False
 
     if factory_name is not None:
         factory = parse_factory_section(config, factory_name)
         mappings.update(factory["environments"])
         writable_codes = factory["writable"]
         catalog_source = factory["catalog"]
+        skills = factory["skills"]
 
     for raw in raw_envs:
         code, profile_name = _parse_env_mapping(raw)
@@ -125,6 +135,10 @@ def mcp_command(argv: list[str]) -> None:
         writable_codes = frozenset(raw_writable)
     if values["catalog"] is not None:
         catalog_source = values["catalog"]
+    if values["skills"]:
+        skills = True
+    elif values["no-skills"]:
+        skills = False
     if catalog_source is None:
         catalog_source = codes[0]
 
@@ -153,7 +167,7 @@ def mcp_command(argv: list[str]) -> None:
         f"{code}={mappings[code]} {profiles[code]['host']}{' (writable)' if code in writable_codes else ''}"
         for code in codes
     ]
-    log(f"{label}: {'; '.join(parts)}; catalog={catalog_source}")
+    log(f"{label}: {'; '.join(parts)}; catalog={catalog_source}; skills={'on' if skills else 'off'}")
 
     router = build_router(
         profiles=profiles,
@@ -161,5 +175,6 @@ def mcp_command(argv: list[str]) -> None:
         catalog_source=catalog_source,
         extra_read_only=extra_read_only,
         timeout=timeout,
+        skills=skills,
     )
     run_server(router)

{insightfactory_cli-1.1.2.dev28 → insightfactory_cli-1.1.2.dev29}/src/if_cli/config.py

@@ -28,10 +28,13 @@ class Factory(TypedDict):
     environments: list[tuple[str, str]]
     writable: frozenset[str]
     catalog: str
+    skills: bool
 
 
 FACTORY_SECTION_PREFIX = "factory "
-FACTORY_RESERVED_KEYS = {"writable", "catalog"}
+FACTORY_RESERVED_KEYS = {"writable", "catalog", "skills"}
+FACTORY_TRUE = {"true", "yes", "on", "1"}
+FACTORY_FALSE = {"false", "no", "off", "0", ""}
 
 
 def config_dir() -> str:
@@ -217,7 +220,18 @@ def parse_factory_section(config: dict[str, dict[str, str]], name: str) -> Facto
     catalog_value = section.get("catalog")
     catalog = catalog_value.strip() if catalog_value is not None and catalog_value.strip() else codes[0]
 
-    return {"name": name, "environments": environments, "writable": writable, "catalog": catalog}
+    skills_value = section.get("skills", "").strip().lower()
+    if skills_value not in FACTORY_TRUE and skills_value not in FACTORY_FALSE:
+        die(f"factory '{name}' in {config_file()}: skills must be true or false (found '{skills_value}')")
+    skills = skills_value in FACTORY_TRUE
+
+    return {
+        "name": name,
+        "environments": environments,
+        "writable": writable,
+        "catalog": catalog,
+        "skills": skills,
+    }
 
 
 def get_factory(config: dict[str, dict[str, str]], name: str) -> Factory:

insightfactory_cli-1.1.2.dev29/src/if_cli/router/content.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+from urllib.parse import unquote, unquote_plus, urlsplit, urlunsplit
+
+from if_cli.router.catalog import ENV_ARG, EnvironmentSpec
+
+# RFC 6570 query expansion. A client that expands the published template fills
+# `environment` like any other variable, so selecting the factory reads the same
+# way for a resource as the spliced enum does for a tool. Form style opens a
+# query with `?`; continuation style adds to one that is already open, and a
+# template carrying its own query needs the second (see `scope_template`).
+TEMPLATE_SUFFIX = "{?" + ENV_ARG + "}"
+TEMPLATE_CONTINUATION = "{&" + ENV_ARG + "}"
+
+# The variable expression inside a URI template, for reading its variable list
+# and for turning the template into a matcher.
+_EXPRESSION = re.compile(r"\{[^}]*\}")
+
+# The operator an expression may open with, and the modifiers a varspec may
+# carry: `{+path}`, `{?a,b}`, `{#frag}`, `{x:3}`, `{y*}`.
+_OPERATORS = "+#./;?&=,!@|"
+
+# An expression that expands into the fragment, where a `?` is no longer a query.
+_FRAGMENT = re.compile(r"\{#[^}]*\}")
+
+# An expression that continues a query rather than opening one.
+_CONTINUATION = re.compile(r"\{&[^}]*\}")
+
+
+class ContentError(Exception):
+    """A routing decision this router cannot make, reported to the client as an error.
+
+    Distinct from `CliError`: that ends the process at startup, this one answers
+    a single request and leaves the server running.
+    """
+
+
+def _variable_names(expression: str) -> list[str]:
+    """The variable names one RFC 6570 expression declares.
+
+    `{?deploy.environment}` declares `deploy.environment`, not `environment`:
+    a dot is legal in a varname, so matching on a word boundary would refuse a
+    template that never names ours. Modifiers are stripped, because `{x:3}` and
+    `{x*}` are both the variable `x`.
+
+    Names are decoded before they are compared, because a varname may be
+    percent-encoded and `split_environment` decodes the field name it reads.
+    The two have to agree about that, or a name claims our field without
+    tripping the guard.
+    """
+    body = expression[1:-1].lstrip(_OPERATORS)
+    return [unquote(name.split(":", 1)[0].rstrip("*")) for name in body.split(",") if name]
+
+
+def _literal_query_names(uri_template: str) -> list[str]:
+    """The names of the query fields a template spells out for itself.
+
+    `if://search?environment=fixed{&q}` declares no variable at all, so reading
+    the expressions alone would miss that it has already taken our field.
+    """
+    stem = _EXPRESSION.sub("", _split_fragment(uri_template)[0])
+    # Split on both delimiters: `if://x{?a}&environment=fixed` opens its query
+    # inside an expression, so partitioning on `?` alone would see no query at
+    # all. Neither character can appear in a path, so the first segment is the
+    # only one that is not a field.
+    return [unquote_plus(field.split("=", 1)[0]) for field in re.split(r"[?&]", stem)[1:] if field]
+
+
+def declares_environment(uri_template: str) -> bool:
+    if ENV_ARG in _literal_query_names(uri_template):
+        return True
+    return any(ENV_ARG in _variable_names(expression) for expression in _EXPRESSION.findall(uri_template))
+
+
+def _environment_list(environments: Sequence[EnvironmentSpec]) -> str:
+    return "; ".join(f"{env.code} = {env.label}{'' if env.writable else ' (read-only)'}" for env in environments)
+
+
+def split_environment(uri: str) -> tuple[str, str | None]:
+    """Peel `?environment=<code>` off a resource URI, returning the rest and the code.
+
+    Only this router's own parameter is removed, and every other field is
+    carried across as the exact bytes the client sent: the URI belongs to the
+    factory, which may parse or sign it, so decoding and re-encoding it would
+    hand upstream something the client never wrote. Only the field *name* is
+    decoded, and only to compare it.
+
+    A blank `environment=` is what an RFC 6570 client emits when it expands the
+    variable with nothing, so it counts as unset, but it is still stripped: it
+    is our field either way and the factory has no use for it.
+    """
+    parts = urlsplit(uri)
+    if not parts.query:
+        return uri, None
+    fields = parts.query.split("&")
+    # Last wins, and exactly one field is ours. The router appends its own
+    # variable after whatever the factory published, so when a URI carries two
+    # the later one is the client's and the earlier one belongs to the factory:
+    # removing both would delete a field this module exists to forward intact.
+    ours = [at for at, field in enumerate(fields) if unquote_plus(field.split("=", 1)[0]) == ENV_ARG]
+    if not ours:
+        return uri, None
+    mine = ours[-1]
+    _, _, value = fields[mine].partition("=")
+    kept = [field for at, field in enumerate(fields) if at != mine]
+    bare = urlunsplit((parts.scheme, parts.netloc, parts.path, "&".join(kept), parts.fragment))
+    # The blank is read after the pick, not used to choose: a client that
+    # expanded the variable with nothing has said "unset", and saying it last
+    # does not hand the choice back to an earlier field.
+    return bare, unquote_plus(value) if value else None
+
+
+def scope_template(template: Mapping[str, Any], environments: Sequence[EnvironmentSpec]) -> dict[str, Any]:
+    """Publish one resource template with `environment` appended as a variable.
+
+    A template is the only resource shape whose contents are per-environment:
+    `if://task-config-schemas/{taskType}` resolves to that factory's own
+    activity catalogue. Concrete resources are not scoped this way (see
+    `resolve_resource`), because `skill://` bodies cross-reference each other by
+    bare URI and rewriting them would leave those links pointing at nothing.
+    """
+    uri_template = template.get("uriTemplate") or ""
+    if not uri_template:
+        raise ContentError("resource template has no uriTemplate.")
+    if declares_environment(uri_template):
+        raise ContentError(
+            f'resource template "{uri_template}" already declares an "{ENV_ARG}" variable, which the router '
+            "reserves to select the factory environment."
+        )
+    # A template that already opens a query gets the continuation operator;
+    # a second `{?...}` would expand to a second literal `?` and the parameter
+    # would be read as part of the previous value.
+    stem, fragment = _split_fragment(uri_template)
+    suffix = TEMPLATE_CONTINUATION if _opens_a_query(stem) else TEMPLATE_SUFFIX
+    description = (template.get("description") or "").rstrip()
+    note = f"Set {ENV_ARG} to choose which factory environment answers: {_environment_list(environments)}."
+    return {
+        **template,
+        "uriTemplate": f"{stem}{suffix}{fragment}",
+        "description": f"{description}\n\n{note}" if description else note,
+    }
+
+
+def _split_fragment(uri_template: str) -> tuple[str, str]:
+    """Split a template before whatever expands into its fragment.
+
+    Everything after a `#` is the fragment, where a `?` is an ordinary
+    character rather than a query opener, so the router's own variable has to
+    go in front of it or it never reaches `split_environment`.
+    """
+    match = _FRAGMENT.search(uri_template)
+    cuts = [at for at in (match.start() if match else -1, uri_template.find("#")) if at >= 0]
+    if not cuts:
+        return uri_template, ""
+    cut = min(cuts)
+    return uri_template[:cut], uri_template[cut:]
+
+
+def _opens_a_query(uri_template: str) -> bool:
+    """Whether expanding this template can already have produced a `?`.
+
+    `{&x}` counts only alongside a reserved expansion, which is the one way a
+    query can be open without the template text saying so. On its own, `{&x}`
+    with no `?` anywhere is a template whose expansion has no query at all, and
+    there form style is right: it opens one rather than continuing it, so
+    `if://x{&q}{?environment}` expands to `if://x&q=1?environment=prd`, which
+    routes and hands the factory back exactly what its own template produces.
+    """
+    reduced = _EXPRESSION.sub(lambda match: match.group(0)[:2], uri_template)
+    return "?" in reduced or ("{&" in reduced and "{+" in reduced)
+
+
+def unscope_template(uri_template: str) -> str:
+    """Remove the variable `scope_template` added, wherever it was put.
+
+    Not a suffix strip: a template with a fragment carries it in the middle,
+    and the factory has never heard of it in any position.
+    """
+    return uri_template.replace(TEMPLATE_SUFFIX, "", 1).replace(TEMPLATE_CONTINUATION, "", 1)
+
+
+def template_matcher(uri_template: str) -> re.Pattern[str]:
+    """A matcher for URIs that are expansions of `uri_template`.
+
+    Deliberately loose: every variable expression becomes "any characters,
+    including none", because an undefined RFC 6570 variable expands to nothing
+    and `{id}{?format}` with no format is still an expansion. It is only ever
+    asked whether a URI *could* be one, and being loose makes it fail towards
+    refusing to guess an environment rather than towards silently answering
+    from the wrong factory.
+
+    A template of nothing but variables matches every URI, so it discriminates
+    nothing and is given a matcher that matches nothing instead. That guard is
+    for "matches literally everything", not for "too loose to be useful":
+    `if://{path}` keeps its scheme literal and so still claims the whole
+    `if://` space, which makes every static `if://` resource need an
+    environment. Refusing is the safe direction, but it is a real cost.
+
+    A reserved expansion (`{+var}`, `{#var}`) can expand into `?` and `#`
+    itself, so whether a URI opens a query is not decidable from the template
+    text. Everything here is a heuristic over the literal characters.
+
+    The matcher is built from the catalogue source's templates alone, so a
+    template only another environment publishes is invisible here. A client can
+    only learn of one out of band, since `resources/templates/list` publishes
+    the catalogue source's, so the gap is narrow; it is the reason this is a
+    routing hint rather than a guarantee.
+    """
+    literals = _EXPRESSION.split(uri_template)
+    if not any(literals):
+        return re.compile(r"(?!)")
+    return re.compile(".*".join(re.escape(literal) for literal in literals))
+
+
+def resolve_resource(
+    uri: str,
+    *,
+    templates: Sequence[str],
+    catalog_source: str,
+    codes: Sequence[str],
+    reserved: Sequence[str] = (),
+) -> tuple[str, str]:
+    """Which environment answers `uri`, and the URI to ask it for.
+
+    Two cases, and the URI itself says which. A template expansion is
+    per-environment content (`if://task-config-schemas/AZSQL` is that factory's
+    own activity catalogue), so it is read from the environment its query names
+    and refused without one rather than answered from the wrong factory.
+    Anything else is static content the release publishes identically
+    everywhere (the `skill://` bodies), so it is read from the catalogue source.
+
+    Membership of `resources/list` is deliberately not the test: a skill body
+    may link to a sibling document the factory never advertised, and such a link
+    carries no `environment` and could not be given one.
+    """
+    bare, chosen = split_environment(uri)
+    if chosen is not None:
+        if chosen not in codes:
+            # A template this router refused to publish takes the field for
+            # itself, so what looks like a bad environment code is the
+            # factory's own value. The operator reads that on stderr when the
+            # listing skips it; the client deserves the same sentence.
+            claimed = next((template for template in reserved if template_matcher(template).fullmatch(uri)), None)
+            if claimed is not None:
+                raise ContentError(
+                    f'"{uri}" expands the resource template "{claimed}", which takes the "{ENV_ARG}" field for '
+                    "itself. This router reserves that field to select the factory environment, so it cannot "
+                    "route this template and does not publish it."
+                )
+            raise ContentError(f'Unknown environment "{chosen}". Choose one of: {", ".join(codes)}')
+        return bare, chosen
+    matched = next((template for template in templates if template_matcher(template).fullmatch(bare)), None)
+    if matched is not None:
+        raise ContentError(
+            f'"{bare}" expands the resource template "{matched}", whose contents differ per factory, so it needs '
+            f"an environment: append ?{ENV_ARG}=<code> to the URI. Choose one of: {', '.join(codes)}"
+        )
+    return bare, catalog_source
+
+
+def splice_prompt_environment(prompt: Mapping[str, Any], environments: Sequence[EnvironmentSpec]) -> dict[str, Any]:
+    """Publish one prompt with `environment` added as a required argument."""
+    arguments = [dict(argument) for argument in (prompt.get("arguments") or [])]
+    if any(argument.get("name") == ENV_ARG for argument in arguments):
+        raise ContentError(
+            f'prompt "{prompt.get("name")}" already declares an "{ENV_ARG}" argument, which the router reserves '
+            "to select the factory environment."
+        )
+    arguments.append(
+        {
+            "name": ENV_ARG,
+            "description": f"Which factory environment to run this against. {_environment_list(environments)}.",
+            "required": True,
+        }
+    )
+    return {**prompt, "arguments": arguments}
+
+
+def environment_instruction(code: str, label: str) -> str:
+    """The line the router prepends to a rendered prompt.
+
+    The factory writes its prompts for a client talking to one factory, so they
+    name tools without an environment. Through the router every one of those
+    calls needs the argument, and a model following the prompt verbatim would
+    omit it on the first call and be told off for it.
+
+    Prepended rather than appended, and attributed: the factory's own last turn
+    may be an assistant prefill, which a trailing user turn would silently end,
+    and a bare instruction in the factory's voice is indistinguishable from the
+    prompt it is wrapping.
+    """
+    return (
+        f'[if-cli router] Every tool call while following this prompt must pass {ENV_ARG}="{code}" ({label}). '
+        "This router fronts several factory environments and the instructions below do not name one."
+    )