agentbundle 0.4.0__tar.gz → 0.6.0__tar.gz

{agentbundle-0.4.0 → agentbundle-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.4.0
+Version: 0.6.0
 Summary: npm for your coding agent. Install packs of skills, subagents, and hooks into any repo, for every major agent.
 Author-email: eugenelim <eugenelim@users.noreply.github.com>
 License: Apache-2.0 OR MIT
@@ -31,7 +31,7 @@ pip install agentbundle
 agentbundle install --pack core git+https://github.com/eugenelim/agent-ready-repo
 ```
 
-That lands `core`, the flagship pack and the loop itself, in your repo. Claude Code, Codex, Cursor, Copilot, Gemini, and Kiro all read it.
+That lands `core`, the flagship pack and the loop itself, in your repo. Claude Code, Codex, Cursor, Copilot, Gemini, and Kiro — both the CLI and the IDE — all read it, subagents and skills included.
 
 ## Common commands
 
@@ -39,6 +39,12 @@ That lands `core`, the flagship pack and the loop itself, in your repo. Claude C
 # See what's in a catalogue
 agentbundle list-packs git+https://github.com/eugenelim/agent-ready-repo
 
+# See the catalogue's curated install profiles
+agentbundle list-profiles git+https://github.com/eugenelim/agent-ready-repo
+
+# Install a whole curated profile — a single-scope set of packs — in one command
+agentbundle install --profile inception git+https://github.com/eugenelim/agent-ready-repo
+
 # Install the flagship loop into this repo
 agentbundle install --pack core git+https://github.com/eugenelim/agent-ready-repo
 
@@ -52,7 +58,7 @@ agentbundle install --pack core git+https://github.com/eugenelim/agent-ready-rep
 agentbundle upgrade --pack core --to 0.4.0 git+https://github.com/eugenelim/agent-ready-repo
 ```
 
-A catalogue is a git URL or a local path. Installs auto-detect your agent; pass `--adapter` to override.
+A catalogue is a git URL or a local path. Installs auto-detect your agent; pass `--adapter` to override. A **profile** is a catalogue-curated, single-scope set of packs you install in one command — it declares its own scope, so `--scope` doesn't apply.
 
 ## Build your own catalogue
 

{agentbundle-0.4.0 → agentbundle-0.6.0}/README.md

@@ -13,7 +13,7 @@ pip install agentbundle
 agentbundle install --pack core git+https://github.com/eugenelim/agent-ready-repo
 ```
 
-That lands `core`, the flagship pack and the loop itself, in your repo. Claude Code, Codex, Cursor, Copilot, Gemini, and Kiro all read it.
+That lands `core`, the flagship pack and the loop itself, in your repo. Claude Code, Codex, Cursor, Copilot, Gemini, and Kiro — both the CLI and the IDE — all read it, subagents and skills included.
 
 ## Common commands
 
@@ -21,6 +21,12 @@ That lands `core`, the flagship pack and the loop itself, in your repo. Claude C
 # See what's in a catalogue
 agentbundle list-packs git+https://github.com/eugenelim/agent-ready-repo
 
+# See the catalogue's curated install profiles
+agentbundle list-profiles git+https://github.com/eugenelim/agent-ready-repo
+
+# Install a whole curated profile — a single-scope set of packs — in one command
+agentbundle install --profile inception git+https://github.com/eugenelim/agent-ready-repo
+
 # Install the flagship loop into this repo
 agentbundle install --pack core git+https://github.com/eugenelim/agent-ready-repo
 
@@ -34,7 +40,7 @@ agentbundle install --pack core git+https://github.com/eugenelim/agent-ready-rep
 agentbundle upgrade --pack core --to 0.4.0 git+https://github.com/eugenelim/agent-ready-repo
 ```
 
-A catalogue is a git URL or a local path. Installs auto-detect your agent; pass `--adapter` to override.
+A catalogue is a git URL or a local path. Installs auto-detect your agent; pass `--adapter` to override. A **profile** is a catalogue-curated, single-scope set of packs you install in one command — it declares its own scope, so `--scope` doesn't apply.
 
 ## Build your own catalogue
 

{agentbundle-0.4.0 → agentbundle-0.6.0}/agentbundle/_data/adapter.schema.json

@@ -69,6 +69,7 @@
                 "managed-block-delimiter-end": {"type": "string"},
                 "frontmatter-mapping": {"type": "string"},
                 "frontmatter-default": {"type": "string"},
+                "inject-resources": {"type": "array", "items": {"type": "string"}},
                 "info-message": {"type": "string"}
               }
             }

{agentbundle-0.4.0 → agentbundle-0.6.0}/agentbundle/_data/adapter.toml

@@ -71,7 +71,13 @@
 # each pack's README. All new fields are optional — packs pinned below v0.14
 # build and validate unchanged. Declaration + projection only (no @catalogue/pack
 # resolution, no search, no persisted index).
-version = "0.14"
+# docs/specs/kiro-cli-agent-skill-resources (v0.15): kiro-cli agent projection
+# injects a fixed skill-resources glob (both install scopes) so headless
+# `--agent` runs reach the bundle's skills — Kiro custom agents don't inherit
+# the default agent's `.kiro/skills` auto-discovery (RFC-0022 E4; kiro
+# #6887/#6888/#4993). Additive `inject-resources` on BOTH the kiro-cli and
+# kiro-ide agent projections (CLI → agent JSON, IDE → quoted .md frontmatter).
+version = "0.15"
 
 # Sibling schemas this contract references — pack metadata and the
 # per-pack Claude-plugin manifest. Defined by spec AC #3 + #4.
@@ -319,6 +325,13 @@ primitive = "agent"
 mode = "direct-file"
 target-path = ".kiro/agents/"
 frontmatter-mapping = "kiro-ide-agent-frontmatter-v0.9"
+# Skill discovery (RFC-0022 E4): IDE custom agents / subagents do NOT inherit
+# the default agent's `.kiro/skills` auto-discovery either (kiro #6887/#6888,
+# #4993). Inject the same fixed skill-resources glob as kiro-cli; the IDE
+# agent `resources` field is documented and `skill://`-aware, so it does not
+# trip the silent-drop bug (that's for non-schema keys like `hooks`). Emitted
+# into the `.md` YAML frontmatter, quoted. Author override wins.
+inject-resources = ["skill://.kiro/skills/**/SKILL.md", "skill://~/.kiro/skills/**/SKILL.md"]
 on-conflict = "prompt-then-preserve"
 
 [[adapter.kiro-ide.projection]]
@@ -388,6 +401,14 @@ primitive = "agent"
 mode = "direct-file"
 target-path = ".kiro/agents/"
 frontmatter-mapping = "kiro-cli-agent-frontmatter-v1.0"
+# Skill discovery (RFC-0022 E4): Kiro custom agents do NOT inherit the default
+# agent's auto-discovery of `.kiro/skills` (kiro #6887/#6888), so a headless
+# `--agent` run sees zero skills unless the agent declares them. Inject this
+# fixed skill-resources glob (both install scopes) into every projected agent.
+# Skipped when the agent source already declares its own `resources` (author
+# override wins). kiro-ide carries the same field on its own agent projection
+# entry (emitted into `.md` frontmatter rather than JSON).
+inject-resources = ["skill://.kiro/skills/**/SKILL.md", "skill://~/.kiro/skills/**/SKILL.md"]
 on-conflict = "prompt-then-preserve"
 
 [[adapter.kiro-cli.projection]]

agentbundle-0.6.0/agentbundle/_data/profile.schema.json

@@ -0,0 +1,21 @@
+{
+  "type": "object",
+  "required": ["scope", "description", "packs"],
+  "additionalProperties": false,
+  "properties": {
+    "scope": {"enum": ["repo", "user"]},
+    "description": {"type": "string"},
+    "packs": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["pack"],
+        "additionalProperties": false,
+        "properties": {
+          "pack": {"type": "string"}
+        }
+      }
+    }
+  }
+}

{agentbundle-0.4.0 → agentbundle-0.6.0}/agentbundle/build/adapters/kiro.py

@@ -284,6 +284,16 @@ def _project_agent_as_json(
             prompt = body.rstrip("\n")
             if prompt:
                 agent_json["prompt"] = prompt
+        # Skill-resources injection (RFC-0022 E4). The agent projection
+        # declares `inject-resources` so custom agents reach the bundle's
+        # skills — Kiro custom agents don't inherit the default agent's
+        # `.kiro/skills` auto-discovery (kiro #6887/#6888). Author-declared
+        # `resources` win: only inject when the agent set none. This function
+        # handles the CLI (JSON) path; kiro-ide injects the same field in its
+        # own `.md` projector (`_project_agent_as_md`).
+        inject_resources = rule.get("inject-resources")
+        if inject_resources and "resources" not in agent_json:
+            agent_json["resources"] = list(inject_resources)
         destination = target_dir / (entry.stem + ".json")
         destination.write_text(
             json.dumps(agent_json, indent=2, sort_keys=False) + "\n",

{agentbundle-0.4.0 → agentbundle-0.6.0}/agentbundle/build/adapters/kiro_ide.py

@@ -244,6 +244,15 @@ def _project_agent_as_md(
         agent_name = rewritten.get("name") or entry.stem
         rewritten["name"] = agent_name
 
+        # Skill-resources injection (RFC-0022 E4). Same gap as kiro-cli: IDE
+        # custom agents don't inherit the default agent's `.kiro/skills`
+        # auto-discovery, so inject the declared glob unless the agent set its
+        # own `resources` (author override wins). `resources` is a documented
+        # IDE agent field, so it does not trip the silent-drop bug.
+        inject_resources = rule.get("inject-resources")
+        if inject_resources and "resources" not in rewritten:
+            rewritten["resources"] = list(inject_resources)
+
         output_text = _serialize_frontmatter_md(rewritten) + body
         destination = target_dir / entry.name  # preserves .md extension
         destination.write_text(output_text, encoding="utf-8")
@@ -260,16 +269,24 @@ def _serialize_frontmatter_md(fields: dict[str, Any]) -> str:
     lines = ["---"]
     for key, value in fields.items():
         if isinstance(value, list):
-            items = ", ".join(str(v) for v in value)
+            # Flow sequence. Simple tokens (tool ids like `read_file`) stay
+            # unquoted; items with YAML-special chars (e.g. `skill://` URIs
+            # with `**` globs) are quoted so the IDE's parser can't misread them.
+            items = ", ".join(_yaml_scalar(str(v)) for v in value)
             lines.append(f"{key}: [{items}]")
         elif isinstance(value, str):
-            # Quote strings that contain YAML-special characters.
-            if any(c in value for c in ':#{}[]|>&*!,\'"'):
-                escaped = value.replace("\\", "\\\\").replace('"', '\\"')
-                lines.append(f'{key}: "{escaped}"')
-            else:
-                lines.append(f"{key}: {value}")
+            lines.append(f"{key}: {_yaml_scalar(value)}")
         else:
             lines.append(f"{key}: {value}")
     lines.append("---")
     return "\n".join(lines) + "\n"
+
+
+def _yaml_scalar(value: str) -> str:
+    """Render a string as a YAML scalar, double-quoting when it contains a
+    YAML-special character (else a plain scalar). Used for both top-level
+    values and items inside a `[...]` flow sequence."""
+    if any(c in value for c in ':#{}[]|>&*!,\'"'):
+        escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+        return f'"{escaped}"'
+    return value

{agentbundle-0.4.0 → agentbundle-0.6.0}/agentbundle/build/scope_rails.py

@@ -299,6 +299,16 @@ def run_all(
 # ---------------------------------------------------------------------------
 
 
+# Adapters whose hook-wiring projects via `merge-into-agent-json` (a
+# pack-owned `.kiro/agents/<attach-to-agent>.json`): the legacy `kiro`
+# block and the `kiro-cli` adapter. The `attach-to-agent` rails below
+# validate that merge target, so they fire for this family. `kiro-ide`
+# (and the `kiro` *install alias*, which routes to kiro-ide) DROPS
+# hook-wiring and is intentionally absent — there is no merge target to
+# validate. Mirrors install.py's merge dispatch.
+_MERGE_INTO_AGENT_JSON_ADAPTERS = frozenset({"kiro", "kiro-cli"})
+
+
 def check_kiro_attach_to_agent(
     pack_name: str,
     wiring_tomls: dict[str, dict],
@@ -325,7 +335,7 @@ def check_kiro_attach_to_agent(
       target_adapters: iterable of adapter names the pack is being
         validated against. No-op when ``kiro`` is absent.
     """
-    if "kiro" not in set(target_adapters or ()):
+    if not (set(target_adapters or ()) & _MERGE_INTO_AGENT_JSON_ADAPTERS):
         return None
     for wiring_name, body in wiring_tomls.items():
         attach = body.get("attach-to-agent") if isinstance(body, dict) else None
@@ -485,7 +495,7 @@ def check_kiro_wiring(
     would let a pack reach outside its source tree. A wiring TOML that
     fails to parse counts as a refusal on its own.
     """
-    if "kiro" not in set(target_adapters or ()):
+    if not (set(target_adapters or ()) & _MERGE_INTO_AGENT_JSON_ADAPTERS):
         return None
 
     loaded = _load_pack_hook_wiring_safely(pack_path, pack_name)

{agentbundle-0.4.0 → agentbundle-0.6.0}/agentbundle/build/tests/test_adapter_cursor.py

@@ -53,9 +53,10 @@ class CursorContractTests(unittest.TestCase):
     def test_contract_version_is_0_11(self) -> None:
         """AC1 — contract bumped to 0.11 by cursor-full-parity; subsequently
         0.12 (copilot-skills-and-web), 0.13 (docs/specs/gemini-full-parity),
-        then 0.14 (docs/specs/enriched-pack-manifest).
+        0.14 (docs/specs/enriched-pack-manifest), then 0.15
+        (docs/specs/kiro-cli-agent-skill-resources).
         Name preserved to keep the diff small."""
-        self.assertEqual(self.contract["contract"]["version"], "0.14")
+        self.assertEqual(self.contract["contract"]["version"], "0.15")
 
     def test_cursor_block_projects_five_primitives(self) -> None:
         """AC2 — the five standard primitives are in the projection array."""

{agentbundle-0.4.0 → agentbundle-0.6.0}/agentbundle/build/tests/test_adapter_gemini.py

@@ -151,9 +151,9 @@ class GeminiContractTests(unittest.TestCase):
         cls.contract = load_contract(CONTRACT_PATH)
 
     def test_contract_version_is_0_14(self) -> None:
-        """Contract version is 0.14 (docs/specs/enriched-pack-manifest bumped it
-        from gemini-full-parity's 0.13). Renamed from the 0_13 method."""
-        self.assertEqual(self.contract["contract"]["version"], "0.14")
+        """Contract version is 0.15 (docs/specs/kiro-cli-agent-skill-resources
+        bumped it from enriched-pack-manifest's 0.14). Name preserved."""
+        self.assertEqual(self.contract["contract"]["version"], "0.15")
 
     def test_gemini_block_projects_five_primitives(self) -> None:
         """AC2 — five standard primitives with their gemini targets."""

{agentbundle-0.4.0 → agentbundle-0.6.0}/agentbundle/build/tests/test_adapter_kiro_cli.py

@@ -79,6 +79,45 @@ class KiroCliAdapterTests(unittest.TestCase):
             self.assertNotIn("grep_search", tools)
             self.assertNotIn("execute_bash", tools)
 
+    def test_cli_agent_gets_skill_resources(self) -> None:
+        """kiro-cli custom agents must declare the skill-resources glob so
+        they reach the bundle's skills — Kiro custom agents don't inherit the
+        default agent's auto-discovery (RFC-0022 E4; kiro #6887/#6888)."""
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack = _seed_agent_pack(tmp_path)
+            out = tmp_path / "out"
+            project(pack, self.contract, out)
+            data = json.loads(
+                (out / ".kiro" / "agents" / "bar.json").read_text(encoding="utf-8")
+            )
+            self.assertEqual(
+                data.get("resources"),
+                [
+                    "skill://.kiro/skills/**/SKILL.md",
+                    "skill://~/.kiro/skills/**/SKILL.md",
+                ],
+                "kiro-cli agent JSON must inject both repo- and user-scope skill globs",
+            )
+
+    def test_cli_agent_resources_author_override_wins(self) -> None:
+        """An agent that declares its own `resources` keeps it — the default
+        does not clobber an author-supplied value."""
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack = tmp_path / "pack"
+            (pack / ".apm" / "agents").mkdir(parents=True)
+            (pack / ".apm" / "agents" / "bar.md").write_text(
+                "---\nname: bar\nresources: [file://README.md]\n---\nbody\n",
+                encoding="utf-8",
+            )
+            out = tmp_path / "out"
+            project(pack, self.contract, out)
+            data = json.loads(
+                (out / ".kiro" / "agents" / "bar.json").read_text(encoding="utf-8")
+            )
+            self.assertEqual(data.get("resources"), ["file://README.md"])
+
     def test_cli_no_ide_hook_field(self) -> None:
         """kiro-cli projected agent JSON must not contain ide-event-vocabulary
         or kiro-ide-hook sections — those are IDE-only fields that cause the

{agentbundle-0.4.0 → agentbundle-0.6.0}/agentbundle/build/tests/test_adapter_kiro_ide.py

@@ -63,6 +63,44 @@ class KiroIdeAdapterTests(unittest.TestCase):
             for cli_only in ("hooks", "allowedTools", "toolsSettings", "mcpServers"):
                 self.assertNotIn(cli_only, raw, f"kiro-ide agent .md must not contain {cli_only!r}")
 
+    def test_kiro_ide_gets_skill_resources(self) -> None:
+        """kiro-ide custom agents (and IDE subagents) must declare the
+        skill-resources glob so they reach skills — IDE custom agents don't
+        inherit the default agent's auto-discovery either (RFC-0022 E4)."""
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack = _seed_agent_pack(tmp_path)
+            out = tmp_path / "out"
+            project(pack, self.contract, out)
+            raw = (out / ".kiro" / "agents" / "bar.md").read_text(encoding="utf-8")
+            # Assert the exact emitted line: a flow sequence of DOUBLE-QUOTED
+            # scalars. Quoting makes the `skill://` URIs / `**` globs
+            # unambiguous YAML, guarding the IDE's fail-silent frontmatter
+            # parser (kiro #8329). The bytes were confirmed to round-trip
+            # through PyYAML to the two-element list during verification; this
+            # gate is exact-string (the build tree is stdlib-only — no yaml).
+            self.assertIn(
+                'resources: ["skill://.kiro/skills/**/SKILL.md", '
+                '"skill://~/.kiro/skills/**/SKILL.md"]',
+                raw,
+            )
+
+    def test_kiro_ide_resources_author_override_wins(self) -> None:
+        """An IDE agent that declares its own `resources` keeps it."""
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pack = tmp_path / "pack"
+            (pack / ".apm" / "agents").mkdir(parents=True)
+            (pack / ".apm" / "agents" / "bar.md").write_text(
+                "---\nname: bar\nresources: [file://README.md]\n---\nbody\n",
+                encoding="utf-8",
+            )
+            out = tmp_path / "out"
+            project(pack, self.contract, out)
+            raw = (out / ".kiro" / "agents" / "bar.md").read_text(encoding="utf-8")
+            self.assertIn("file://README.md", raw)
+            self.assertNotIn("skill://", raw)
+
     def test_kiro_ide_tools_use_ide_ids(self) -> None:
         """kiro-ide uses IDE tool ids (read_file, grep_search) not CLI short-names."""
         with tempfile.TemporaryDirectory() as tmp:
@@ -134,13 +172,13 @@ class KiroIdeAdapterTests(unittest.TestCase):
         self.assertIn(".kiro.hook", target_repo)
 
     def test_contract_version_is_0_9(self) -> None:
-        """Contract version is 0.14 (docs/specs/enriched-pack-manifest, atop
-        gemini-full-parity's 0.13 and copilot-skills-and-web's 0.12).
+        """Contract version is 0.15 (docs/specs/kiro-cli-agent-skill-resources,
+        atop enriched-pack-manifest's 0.14 and gemini-full-parity's 0.13).
         Name preserved to keep the diff small."""
         self.assertEqual(
             self.contract["contract"]["version"],
-            "0.14",
-            "adapter.toml [contract] version must be '0.14' after enriched-pack-manifest",
+            "0.15",
+            "adapter.toml [contract] version must be '0.15' after kiro-cli-agent-skill-resources",
         )
 
     def test_kiro_ide_hook_projects_with_flat_prefix_path(self) -> None:

{agentbundle-0.4.0 → agentbundle-0.6.0}/agentbundle/build/tests/test_contract.py

@@ -452,17 +452,16 @@ class ContractV05Tests(unittest.TestCase):
         self.schema = _load_schema()
 
     def test_contract_version_is_v05(self) -> None:
-        """tomllib.loads of adapter.toml returns contract.version == "0.14"
-        (bumped from gemini-full-parity's "0.13" by
-        docs/specs/enriched-pack-manifest: pack.toml becomes the rich metadata
-        source of truth and the build projects the projectable subset + READMEs
-        into the claude-plugins + apm routes). Class/method names preserved to
-        avoid churn.
+        """tomllib.loads of adapter.toml returns contract.version == "0.15"
+        (bumped from enriched-pack-manifest's "0.14" by
+        docs/specs/kiro-cli-agent-skill-resources: kiro-cli agents inject a
+        skill-resources glob so headless `--agent` runs reach skills).
+        Class/method names preserved to avoid churn.
         """
         self.assertEqual(
             self.contract["contract"]["version"],
-            "0.14",
-            "adapter.toml [contract] version must be '0.14' after enriched-pack-manifest",
+            "0.15",
+            "adapter.toml [contract] version must be '0.15' after kiro-cli-agent-skill-resources",
         )
 
     def test_claude_code_install_routes_includes_apm(self) -> None:

{agentbundle-0.4.0 → agentbundle-0.6.0}/agentbundle/cli.py

@@ -1,9 +1,11 @@
 """`agentbundle` CLI dispatcher — argparse over the eleven F-cli subcommands.
 
 Subcommand order on the parser matches the canonical install-workflow order
-from the spec (discovery-first): `list-packs`, `list-targets`, `scaffold`,
-`install`, `validate`, `render`, `adapt`, `diff`, `upgrade`, `uninstall`,
-`init-state`.
+from the spec (discovery-first): `list-packs`, `list-profiles`, `list-targets`,
+`scaffold`, `install`, `validate`, `render`, `adapt`, `diff`, `upgrade`,
+`uninstall`, `init-state`, `config`, `reconcile`. `list-profiles` (RFC-0034)
+lists the catalogue's curated single-scope install profiles; `install
+--profile <name>` installs one.
 
 Each subcommand's `run(args) -> int` lives under `agentbundle.commands.*`;
 this module wires `argparse` and prints `--version`. No business logic here.
@@ -192,6 +194,14 @@ def _build_parser() -> argparse.ArgumentParser:
     sp.add_argument("catalogue", help="Catalogue URI (local path or git+https://...).")
     sp.set_defaults(func=_lazy("list_packs"))
 
+    # --- list-profiles --- (catalogue query; profiles declare their own scope)
+    sp = subparsers.add_parser(
+        "list-profiles",
+        help="List curated install profiles available in a catalogue URI.",
+    )
+    sp.add_argument("catalogue", help="Catalogue URI (local path or git+https://...).")
+    sp.set_defaults(func=_lazy("list_profiles"))
+
     # --- list-targets --- (--scope as read-only filter)
     sp = subparsers.add_parser(
         "list-targets",
@@ -215,7 +225,23 @@ def _build_parser() -> argparse.ArgumentParser:
         "install",
         help="Install a pack from a catalogue URI into the adopter repo.",
     )
-    sp.add_argument("--pack", required=True)
+    # pack-profiles: `--pack` and `--profile` are a required mutually-exclusive
+    # group. `--pack` was a bare `required=True` arg; making it a member of a
+    # required mutex group keeps "exactly one of pack/profile" without losing
+    # the requiredness. `--scope` with `--profile` is rejected at the handler
+    # (a profile declares its own scope); argparse can't express that mutex
+    # because `--scope` is valid alongside `--pack`.
+    _pack_or_profile = sp.add_mutually_exclusive_group(required=True)
+    _pack_or_profile.add_argument("--pack")
+    _pack_or_profile.add_argument(
+        "--profile",
+        help=(
+            "Install a curated single-scope set of packs from "
+            "<catalogue>/profiles/<name>.toml in one command (RFC-0034). "
+            "Mutually exclusive with --pack; --scope is not allowed (the "
+            "profile declares its own scope)."
+        ),
+    )
     sp.add_argument("catalogue", help="Catalogue URI (local path or git+https://...).")
     sp.add_argument("--output", default=".")
     sp.add_argument("--scope", choices=("repo", "user"))