insightfactory-cli 1.1.1.dev25__tar.gz → 1.1.2.dev29__tar.gz

{insightfactory_cli-1.1.1.dev25 → insightfactory_cli-1.1.2.dev29}/CHANGELOG.md

@@ -7,8 +7,37 @@ project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 The release job reads the section whose heading matches the version in
 `pyproject.toml` and makes it the body of the GitHub Release. CI holds both ends of
-that: a PR into `develop` or `main` must raise the version and add its section here,
-and a tag whose version has no section fails rather than releasing an empty page.
+that: every PR into `develop` must add an entry here, and a tag whose version has no
+section fails rather than releasing an empty page. The version only moves when the
+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
+  for a version bump only when `develop` is still on the version `main` is on. One
+  bump opens a release cycle and the PRs after it add to the section it opened,
+  rather than each minting a version that is never tagged.
+- The guard now measures a version against `main` as well as the base branch. A bump
+  has to land above the released version, not merely above the base, and a PR into an
+  open cycle has to add a line rather than reword one.
 
 ## 1.1.1
 

{insightfactory_cli-1.1.1.dev25 → insightfactory_cli-1.1.2.dev29}/CLAUDE.md

@@ -34,9 +34,13 @@ uv run ty check
   match `pyproject.toml`. Pushing `develop` publishes a `.dev{run_number}`
   pre-release. Creating the release tag is a deliberate human act — do not create
   or push one unless asked to cut a release.
-- **Every PR into `develop` or `main` raises `version` in `pyproject.toml` and
-  documents that version in `CHANGELOG.md`.** The `release-guard` job runs
-  `tools/check_release.py` and fails the PR otherwise. Put user-visible changes in
-  the Added/Changed/Fixed group that fits; for internal-only work (tests, CI, a
-  refactor nothing observes) a one-line entry saying so is enough. The section
-  becomes the body of that version's GitHub Release.
+- **Every PR into `develop` adds a `CHANGELOG.md` entry**, in the Added/Changed/Fixed
+  group that fits. For internal-only work (tests, CI, a refactor nothing observes) a
+  one-line entry saying so is enough. The section becomes the body of that version's
+  GitHub Release.
+- **Raise `version` in `pyproject.toml` only when `develop` is on the same version as
+  `main`.** That version is released, so a new entry under it would describe a change
+  it does not contain: bump, and open a section for the new version. While `develop`
+  is ahead of `main` the cycle is open and PRs add to the section already there. A PR
+  into `main` always raises the version. The `release-guard` job runs
+  `tools/check_release.py` and fails the PR otherwise.

{insightfactory_cli-1.1.1.dev25 → insightfactory_cli-1.1.2.dev29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: insightfactory-cli
-Version: 1.1.1.dev25
+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
@@ -354,20 +412,32 @@ artifact, so its notes belong on that Release. A checkout with no tags falls bac
 to the tagged version's section alone.
 
 `develop` therefore carries the version the next release will use, and the
-`release-guard` job holds it there. A PR into `develop` must raise `version` in
-`pyproject.toml` above what `develop` already has, and must add that version's
-`CHANGELOG.md` section. `tools/check_release.py` runs both checks and is what
-fails the PR:
+`release-guard` job holds it there. `tools/check_release.py` runs the checks and
+is what fails the PR:
 
 ```bash
-BASE=origin/develop python3 tools/check_release.py
+BASE=origin/develop RELEASED=origin/main python3 tools/check_release.py
 ```
 
-One version per PR, then. The instinct is to let a second change join the
-section the first one opened, and the guard refuses that: the version would be
-tagged with notes that do not describe everything in it, and nothing stops the
-tag going out between the two merges. Bump the patch number again, or fold the
-second change into the first PR.
+**Every PR into `develop` adds a `CHANGELOG.md` entry.** That is the whole point
+of the file, and a change with no entry reaches users with no line anywhere
+saying it happened.
+
+**The version moves once per release cycle, not once per PR.** The first PR after
+a release raises `version` in `pyproject.toml` and opens that version's section;
+the rest of the cycle adds to the section it opened. The guard asks for the bump
+only while `develop` is still on the version `main` is on, because that version
+is released and its notes describe something your change is not in.
+
+The comparison is against `main` rather than against the tag, which matters in
+the window where the release PR has merged but the tag is not pushed yet. What a
+version contains is fixed when it reaches `main`, so a change landing after that
+belongs to the next version, whatever the tags say.
+
+A PR into `main` always needs the bump. It carries no new entries, only the
+version they were written under, and `main` exists to be tagged: leaving it on
+`main`'s own version makes it un-taggable, since that version is on PyPI and any
+other tag matches no file.
 
 Verify and build live in the reusable workflow
 [`if_s_insightfactory_cli.yml`](https://github.com/insightfactory-ai/if_sre_github_actions/blob/main/.github/workflows/if_s_insightfactory_cli.yml)

{insightfactory_cli-1.1.1.dev25 → 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
@@ -330,20 +388,32 @@ artifact, so its notes belong on that Release. A checkout with no tags falls bac
 to the tagged version's section alone.
 
 `develop` therefore carries the version the next release will use, and the
-`release-guard` job holds it there. A PR into `develop` must raise `version` in
-`pyproject.toml` above what `develop` already has, and must add that version's
-`CHANGELOG.md` section. `tools/check_release.py` runs both checks and is what
-fails the PR:
+`release-guard` job holds it there. `tools/check_release.py` runs the checks and
+is what fails the PR:
 
 ```bash
-BASE=origin/develop python3 tools/check_release.py
+BASE=origin/develop RELEASED=origin/main python3 tools/check_release.py
 ```
 
-One version per PR, then. The instinct is to let a second change join the
-section the first one opened, and the guard refuses that: the version would be
-tagged with notes that do not describe everything in it, and nothing stops the
-tag going out between the two merges. Bump the patch number again, or fold the
-second change into the first PR.
+**Every PR into `develop` adds a `CHANGELOG.md` entry.** That is the whole point
+of the file, and a change with no entry reaches users with no line anywhere
+saying it happened.
+
+**The version moves once per release cycle, not once per PR.** The first PR after
+a release raises `version` in `pyproject.toml` and opens that version's section;
+the rest of the cycle adds to the section it opened. The guard asks for the bump
+only while `develop` is still on the version `main` is on, because that version
+is released and its notes describe something your change is not in.
+
+The comparison is against `main` rather than against the tag, which matters in
+the window where the release PR has merged but the tag is not pushed yet. What a
+version contains is fixed when it reaches `main`, so a change landing after that
+belongs to the next version, whatever the tags say.
+
+A PR into `main` always needs the bump. It carries no new entries, only the
+version they were written under, and `main` exists to be tagged: leaving it on
+`main`'s own version makes it un-taggable, since that version is on PyPI and any
+other tag matches no file.
 
 Verify and build live in the reusable workflow
 [`if_s_insightfactory_cli.yml`](https://github.com/insightfactory-ai/if_sre_github_actions/blob/main/.github/workflows/if_s_insightfactory_cli.yml)

{insightfactory_cli-1.1.1.dev25 → insightfactory_cli-1.1.2.dev29}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "insightfactory-cli"
-version = "1.1.1.dev25"
+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.1.dev25 → 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.1.dev25 → 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: