agentbundle 0.53.0__tar.gz → 0.53.1__tar.gz

{agentbundle-0.53.0/agentbundle.egg-info → agentbundle-0.53.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.53.0
+Version: 0.53.1
 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-Expression: Apache-2.0 OR MIT
@@ -35,6 +35,16 @@ python -m pip install agentbundle
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
 
+## What's new in 0.53.1
+
+`agentbundle catalogue init` now writes a root `AGENTS.md` and a `CLAUDE.md`, so
+a new catalogue packages and verifies with no hand edits. A bad
+`[catalogue.package].include` entry fails with a `CAT-PKG-001` message, not a
+traceback. An `include` entry that names a `_` directory under `packs/`, such as
+`packs/_example`, now fails too and must be removed; an empty `include` packages
+every non-`_` pack, so list the packs to ship instead. A catalogue made by an
+earlier release needs a root `AGENTS.md` added by hand.
+
 ## What's new in 0.53.0
 
 `agentbundle catalogue package` now refuses to replace a release archive that

{agentbundle-0.53.0 → agentbundle-0.53.1}/README-pypi.md

@@ -14,6 +14,16 @@ python -m pip install agentbundle
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
 
+## What's new in 0.53.1
+
+`agentbundle catalogue init` now writes a root `AGENTS.md` and a `CLAUDE.md`, so
+a new catalogue packages and verifies with no hand edits. A bad
+`[catalogue.package].include` entry fails with a `CAT-PKG-001` message, not a
+traceback. An `include` entry that names a `_` directory under `packs/`, such as
+`packs/_example`, now fails too and must be removed; an empty `include` packages
+every non-`_` pack, so list the packs to ship instead. A catalogue made by an
+earlier release needs a root `AGENTS.md` added by hand.
+
 ## What's new in 0.53.0
 
 `agentbundle catalogue package` now refuses to replace a release archive that

{agentbundle-0.53.0 → agentbundle-0.53.1}/agentbundle/catalogue_tooling/initialise.py

@@ -79,7 +79,7 @@ def _derive_name(basename: str) -> str | None:
     cleaned = _UNSAFE_NAME_CHARS_RE.sub("-", basename.lower())
     # Collapse multiple dashes, strip leading/trailing dashes
     cleaned = re.sub(r"-{2,}", "-", cleaned).strip("-")
-    if _SAFE_NAME_RE.match(cleaned):
+    if _SAFE_NAME_RE.fullmatch(cleaned):
         return cleaned
     return None
 
@@ -151,6 +151,43 @@ def generate_empty_marketplace(
     return text.encode("utf-8")
 
 
+_CLAUDE_SHIM = b"@AGENTS.md\n"
+
+# Root files init keeps when the author already has their own copy.
+_KEEP_EXISTING_PATHS: frozenset[str] = frozenset({"AGENTS.md", "CLAUDE.md"})
+
+
+def generate_root_agents_md(name: str) -> bytes:
+    """Pure function. Return UTF-8 bytes for the catalogue's root ``AGENTS.md``.
+
+    Only the validated catalogue *name* is interpolated, so no free-text flag
+    reaches Markdown. Deterministic, final newline.
+    """
+    standards = "guides/_shared/reference/catalogue-authoring-standards.md"
+    package_cmd = (
+        "agentbundle catalogue package --root . --bundle <bundle> "
+        "--release <version> --channel <channel> --output dist/"
+    )
+    text = (
+        f"# {name} catalogue\n\n"
+        "This is an AgentBundle catalogue. Packs live in `packs/` and profiles live in\n"
+        "`profiles/`. Directories that start with `_` are templates: discovery, builds\n"
+        "and packaging skip them.\n\n"
+        "Read these next:\n\n"
+        "- [`packs/AGENTS.md`](packs/AGENTS.md)\n"
+        "- [`profiles/AGENTS.md`](profiles/AGENTS.md)\n"
+        f"- [`{standards}`]({standards})\n\n"
+        "```bash\n"
+        "agentbundle catalogue verify --root .\n"
+        "agentbundle catalogue lint --root .\n"
+        f"{package_cmd}\n"
+        "```\n\n"
+        "`catalogue package` ships this file at the archive root as the "
+        "installable-catalogue marker, so keep it.\n"
+    )
+    return text.encode("utf-8")
+
+
 # ---------------------------------------------------------------------------
 # Metadata resolution
 # ---------------------------------------------------------------------------
@@ -182,7 +219,7 @@ def resolve_metadata(
     # --- name ---
     resolved_name: str
     if name:
-        if not _SAFE_NAME_RE.match(name):
+        if not _SAFE_NAME_RE.fullmatch(name):
             errors.append(
                 f"--name {name!r} is not a valid catalogue name. "
                 "Use only letters, digits, hyphens, and underscores, "
@@ -312,6 +349,17 @@ def _build_plan(
         content=marketplace_bytes,
     ))
 
+    planned.append(PlannedFile(
+        rel_path="AGENTS.md",
+        kind="generated",
+        content=generate_root_agents_md(meta.name),
+    ))
+    planned.append(PlannedFile(
+        rel_path="CLAUDE.md",
+        kind="generated",
+        content=_CLAUDE_SHIM,
+    ))
+
     # Scaffold files in manifest order (already sorted)
     for rel, content in sorted(scaffold_files.items()):
         planned.append(PlannedFile(rel_path=rel, kind="scaffold", content=content))
@@ -380,6 +428,7 @@ def classify_conflicts(
         existing = target / pf.rel_path
         action: FileAction
         conflict_reason: str | None = None
+        plan_sha256 = _sha256_bytes(pf.content)
 
         if existing.is_symlink():
             action = FileAction.CONFLICT
@@ -403,6 +452,10 @@ def classify_conflicts(
             else:
                 if current_content == pf.content:
                     action = FileAction.ALREADY_PRESENT
+                elif pf.rel_path in _KEEP_EXISTING_PATHS:
+                    # Author's own root guidance file: keep it, report its hash.
+                    action = FileAction.ALREADY_PRESENT
+                    plan_sha256 = _sha256_bytes(current_content)
                 else:
                     action = FileAction.CONFLICT
                     if pf.rel_path == "catalogue.toml":
@@ -423,7 +476,7 @@ def classify_conflicts(
             path=pf.rel_path,
             kind=pf.kind,
             action=action,
-            sha256=_sha256_bytes(pf.content),
+            sha256=plan_sha256,
             conflict_reason=conflict_reason,
         ))
 

{agentbundle-0.53.0 → agentbundle-0.53.1}/agentbundle/catalogue_tooling/package.py

@@ -157,6 +157,10 @@ def _scan_content(root: Path, pack_include: list[str] | None = None) -> list[Pat
     When pack_include is non-empty, only the listed pack directories are walked;
     non-pack dirs (profiles/, contracts/, .claude-plugin/) are always included.
     An empty or absent pack_include includes all packs (default behavior).
+
+    Raises ValueError for an include entry that is not under ``packs/``, contains
+    path traversal, does not exist as a directory, names build residue, or names a
+    ``_`` template directory directly under ``packs/``.
     """
     collected: list[Path] = []
 
@@ -178,6 +182,11 @@ def _scan_content(root: Path, pack_include: list[str] | None = None) -> list[Pat
                     f"pack_include entry {entry!r} names build residue; "
                     f"it is never packaged"
                 )
+            if len(parts) > 1 and parts[1].startswith("_"):
+                raise ValueError(
+                    f"pack_include entry {entry!r} names a '_' directory; "
+                    f"'_' directories are templates that are never packaged"
+                )
             for dirpath, dirnames, filenames in os.walk(str(d), followlinks=False):
                 dp = Path(dirpath)
                 _prune(dp, dirnames)
@@ -790,7 +799,10 @@ def package_catalogue(
         pass
 
     # --- Scan and validate content ---
-    content_paths = _scan_content(root, pack_include=pack_include)
+    try:
+        content_paths = _scan_content(root, pack_include=pack_include)
+    except ValueError as exc:
+        return _err(f"invalid [catalogue.package].include: {exc}")
 
     req_err = _check_required_files(root, content_paths, required_override=required_override)
     if req_err is not None:

{agentbundle-0.53.0 → agentbundle-0.53.1}/agentbundle/commands/catalogue_sync.py

@@ -83,9 +83,10 @@ _APPLY_FAILED = 4
 
 # The two digest-bearing schemes fetch_catalogue_archive_with_provenance
 # handles; every other URI (local path or git+https://) goes through
-# resolve_catalogue instead. Whose digest each form verifies differs — see
-# docs/specs/catalogue-sync-dry-run/notes/grounding/probe-digest-provenance.py —
-# which is why the two get distinct fidelity tokens rather than one shared
+# resolve_catalogue instead. Whose digest each form verifies differs: an
+# archive+https URI carries the adopter's own `#sha256=` fragment, while
+# catalogue+https takes the sha256 from the resolved channel descriptor. That
+# is why the two get distinct fidelity tokens rather than one shared
 # "verified-digest" token.
 _DIGEST_BEARING_PREFIXES = ("archive+https://", "catalogue+https://")
 

{agentbundle-0.53.0 → agentbundle-0.53.1}/agentbundle/version.py

@@ -14,7 +14,7 @@ import tomllib
 from importlib.resources import files
 from pathlib import Path
 
-CLI_VERSION = "0.53.0"
+CLI_VERSION = "0.53.1"
 
 _HERE = Path(__file__).resolve().parent
 

{agentbundle-0.53.0 → agentbundle-0.53.1/agentbundle.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.53.0
+Version: 0.53.1
 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-Expression: Apache-2.0 OR MIT
@@ -35,6 +35,16 @@ python -m pip install agentbundle
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
 
+## What's new in 0.53.1
+
+`agentbundle catalogue init` now writes a root `AGENTS.md` and a `CLAUDE.md`, so
+a new catalogue packages and verifies with no hand edits. A bad
+`[catalogue.package].include` entry fails with a `CAT-PKG-001` message, not a
+traceback. An `include` entry that names a `_` directory under `packs/`, such as
+`packs/_example`, now fails too and must be removed; an empty `include` packages
+every non-`_` pack, so list the packs to ship instead. A catalogue made by an
+earlier release needs a root `AGENTS.md` added by hand.
+
 ## What's new in 0.53.0
 
 `agentbundle catalogue package` now refuses to replace a release archive that

{agentbundle-0.53.0 → agentbundle-0.53.1}/agentbundle.egg-info/SOURCES.txt

@@ -448,6 +448,7 @@ tests/integration/test_build_check_drift_gates.py
 tests/integration/test_build_derivation_apm.py
 tests/integration/test_build_derivation_claude_plugins.py
 tests/integration/test_catalogue_init.py
+tests/integration/test_catalogue_init_packageable.py
 tests/integration/test_catalogue_verify_adapter_compat.py
 tests/integration/test_catalogue_verify_dependencies.py
 tests/integration/test_catalogue_verify_external_portability.py
@@ -540,6 +541,7 @@ tests/unit/test_catalogue_fetch_jfrog.py
 tests/unit/test_catalogue_init_cli_self_hosted.py
 tests/unit/test_catalogue_pack_defaults.py
 tests/unit/test_catalogue_package_compare.py
+tests/unit/test_catalogue_package_include_diagnostic.py
 tests/unit/test_catalogue_package_refusal.py
 tests/unit/test_catalogue_self_hosted_export_removal.py
 tests/unit/test_catalogue_skill_spec_lint.py

{agentbundle-0.53.0 → agentbundle-0.53.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentbundle"
-version = "0.53.0"
+version = "0.53.1"
 description = "npm for your coding agent. Install packs of skills, subagents, and hooks into any repo, for every major agent."
 requires-python = ">=3.11"
 dependencies = ["credbroker>=0.7,<0.8"]

{agentbundle-0.53.0 → agentbundle-0.53.1}/tests/integration/test_catalogue_init.py

@@ -398,7 +398,12 @@ def test_dogfood_no_host_files_leaked(tmp_path):
 
     scaffold_paths = set(list_files())
     # Generated files
-    generated_paths = {"catalogue.toml", ".claude-plugin/marketplace.json"}
+    generated_paths = {
+        "catalogue.toml",
+        ".claude-plugin/marketplace.json",
+        "AGENTS.md",
+        "CLAUDE.md",
+    }
     allowed = scaffold_paths | generated_paths
 
     # Walk target and collect all files

agentbundle-0.53.1/tests/integration/test_catalogue_init_packageable.py

@@ -0,0 +1,165 @@
+"""A blank catalogue from `catalogue init` packages and verifies with no hand edits."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tarfile
+from pathlib import Path
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _cli(*args: str) -> subprocess.CompletedProcess[str]:
+    env = os.environ.copy()
+    env["PYTHONPATH"] = os.pathsep.join(filter(None, [str(PACKAGE_ROOT), env.get("PYTHONPATH")]))
+    env["PYTHONIOENCODING"] = "utf-8"
+    return subprocess.run(
+        [sys.executable, "-m", "agentbundle", *args],
+        env=env,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+    )
+
+
+def test_init_creates_root_agents_md_and_claude_shim(tmp_path: Path) -> None:
+    from agentbundle.catalogue_tooling.initialise import init_catalogue
+    from agentbundle.catalogue_tooling.results import FileAction
+
+    target = tmp_path / "cat"
+    result = init_catalogue(target=target, name="demo-cat")
+
+    assert result.ok, result.diagnostics
+    assert (target / "AGENTS.md").is_file()
+    assert (target / "CLAUDE.md").read_bytes() == b"@AGENTS.md\n"
+    actions = {fp.path: fp.action for fp in result.files}
+    assert actions["AGENTS.md"] == FileAction.CREATE
+    assert actions["CLAUDE.md"] == FileAction.CREATE
+
+
+def test_blank_catalogue_inits_verifies_packages_and_verifies_archive(tmp_path: Path) -> None:
+    cat = tmp_path / "cat"
+    out = tmp_path / "out"
+
+    steps = [
+        ("catalogue", "init", str(cat), "--name", "demo-cat"),
+        ("catalogue", "verify", "--root", str(cat)),
+        (
+            "catalogue", "package", "--root", str(cat), "--bundle", "demo",
+            "--release", "0.1.0", "--channel", "stable", "--output", str(out),
+        ),
+    ]
+    for step in steps:
+        proc = _cli(*step)
+        assert proc.returncode == 0, (step, proc.stdout, proc.stderr)
+
+    archive = out / "catalogues" / "demo" / "releases" / "0.1.0" / "catalogue-0.1.0.tar.gz"
+    sidecar = archive.with_name(archive.name + ".sha256")
+    proc = _cli("catalogue", "verify", "--archive", str(archive), "--sha256-file", str(sidecar))
+    assert proc.returncode == 0, (proc.stdout, proc.stderr)
+
+    with tarfile.open(archive, "r:gz") as tf:
+        names = tf.getnames()
+    assert "AGENTS.md" in names
+    assert not [n for n in names if n.startswith(("packs/_example/", "profiles/_example/"))]
+
+
+def _snapshot(root: Path) -> dict[str, bytes]:
+    return {
+        p.relative_to(root).as_posix(): p.read_bytes()
+        for p in root.rglob("*")
+        if p.is_file() and not p.is_symlink()
+    }
+
+
+def test_root_agents_md_names_catalogue_and_links_exactly_three_files(tmp_path: Path) -> None:
+    import re
+
+    from agentbundle.catalogue_tooling.initialise import init_catalogue
+
+    target = tmp_path / "cat"
+    assert init_catalogue(target=target, name="demo-cat").ok
+    text = (target / "AGENTS.md").read_text(encoding="utf-8")
+
+    assert "demo-cat" in text
+    links = re.findall(r"\]\(([^)]*)\)", text)
+    assert sorted(links) == sorted([
+        "packs/AGENTS.md",
+        "profiles/AGENTS.md",
+        "guides/_shared/reference/catalogue-authoring-standards.md",
+    ])
+
+
+def test_existing_root_files_are_kept_and_reported_already_present(tmp_path: Path) -> None:
+    import hashlib
+
+    from agentbundle.catalogue_tooling.initialise import init_catalogue
+    from agentbundle.catalogue_tooling.results import FileAction
+
+    target = tmp_path / "cat"
+    target.mkdir()
+    agents = b"# my own rules\n"
+    claude = b"my own claude notes\n"
+    (target / "AGENTS.md").write_bytes(agents)
+    (target / "CLAUDE.md").write_bytes(claude)
+
+    result = init_catalogue(target=target, name="demo-cat")
+
+    assert result.ok, result.diagnostics
+    assert (target / "AGENTS.md").read_bytes() == agents
+    assert (target / "CLAUDE.md").read_bytes() == claude
+    by_path = {fp.path: fp for fp in result.files}
+    for rel, data in (("AGENTS.md", agents), ("CLAUDE.md", claude)):
+        assert by_path[rel].action == FileAction.ALREADY_PRESENT
+        assert by_path[rel].sha256 == hashlib.sha256(data).hexdigest()
+
+
+def test_symlinked_root_agents_md_is_a_conflict_and_writes_nothing(tmp_path: Path) -> None:
+    import pytest
+    from agentbundle.catalogue_tooling.initialise import init_catalogue
+
+    target = tmp_path / "cat"
+    target.mkdir()
+    real = tmp_path / "real.md"
+    real.write_bytes(b"x\n")
+    try:
+        (target / "AGENTS.md").symlink_to(real)
+    except OSError:
+        pytest.skip("symlinks unavailable")
+    before = _snapshot(target)
+
+    result = init_catalogue(target=target, name="demo-cat")
+
+    assert not result.ok
+    assert any(d.code == "CAT-INIT-007" and d.path == "AGENTS.md" for d in result.diagnostics)
+    assert _snapshot(target) == before
+
+
+def test_changed_nested_guidance_file_still_conflicts(tmp_path: Path) -> None:
+    from agentbundle.catalogue_tooling.initialise import init_catalogue
+
+    for rel in ("packs/AGENTS.md", "profiles/CLAUDE.md"):
+        target = tmp_path / rel.replace("/", "-")
+        (target / rel).parent.mkdir(parents=True)
+        (target / rel).write_bytes(b"custom\n")
+        before = _snapshot(target)
+
+        result = init_catalogue(target=target, name="demo-cat")
+
+        assert not result.ok, rel
+        assert any(d.code == "CAT-INIT-007" and d.path == rel for d in result.diagnostics), rel
+        assert _snapshot(target) == before, rel
+
+
+def test_name_with_trailing_newline_is_refused(tmp_path: Path) -> None:
+    """`$` matches before a final newline, so the name check must be a full match."""
+    from agentbundle.catalogue_tooling.initialise import init_catalogue
+
+    target = tmp_path / "cat"
+    result = init_catalogue(target=target, name="foo\n")
+
+    assert not result.ok
+    assert [d.code for d in result.diagnostics] == ["CAT-INIT-003"]
+    assert not target.exists()

agentbundle-0.53.1/tests/unit/test_catalogue_package_include_diagnostic.py

@@ -0,0 +1,154 @@
+"""An invalid [catalogue.package].include entry is a CAT-PKG-001 diagnostic, not a traceback."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _blank_catalogue(tmp_path: Path) -> Path:
+    from agentbundle.catalogue_tooling.initialise import init_catalogue
+
+    root = tmp_path / "cat"
+    assert init_catalogue(target=root, name="demo-cat").ok
+    return root
+
+
+def test_include_entry_outside_packs_is_a_diagnostic(tmp_path: Path) -> None:
+    from agentbundle.catalogue_tooling.package import package_catalogue
+
+    root = _blank_catalogue(tmp_path)
+    toml = root / "catalogue.toml"
+    toml.write_text(
+        toml.read_text(encoding="utf-8").replace("include  = []", 'include  = ["AGENTS.md"]'),
+        encoding="utf-8",
+    )
+    out = tmp_path / "out"
+
+    result = package_catalogue(
+        root=root, bundle="demo", release="0.1.0", channel="stable", output=out,
+    )
+
+    assert not result.ok
+    assert [d.code for d in result.diagnostics] == ["CAT-PKG-001"]
+    assert "AGENTS.md" in result.diagnostics[0].message
+    assert not out.exists()
+
+
+def _set_include(root: Path, entries: list[str]) -> None:
+    toml = root / "catalogue.toml"
+    rendered = "[" + ", ".join(f'"{e}"' for e in entries) + "]"
+    toml.write_text(
+        toml.read_text(encoding="utf-8").replace("include  = []", f"include  = {rendered}"),
+        encoding="utf-8",
+    )
+
+
+def _assert_single_diagnostic(tmp_path: Path, root: Path, entry: str) -> None:
+    from agentbundle.catalogue_tooling.package import package_catalogue
+
+    out = tmp_path / "out"
+    result = package_catalogue(
+        root=root, bundle="demo", release="0.1.0", channel="stable", output=out,
+    )
+
+    assert not result.ok
+    assert [d.code for d in result.diagnostics] == ["CAT-PKG-001"]
+    assert entry in result.diagnostics[0].message
+    assert not out.exists()
+
+
+def test_missing_include_entry_is_a_diagnostic(tmp_path: Path) -> None:
+    root = _blank_catalogue(tmp_path)
+    _set_include(root, ["packs/nope"])
+    _assert_single_diagnostic(tmp_path, root, "packs/nope")
+
+
+def test_build_residue_include_entry_is_a_diagnostic(tmp_path: Path) -> None:
+    root = _blank_catalogue(tmp_path)
+    (root / "packs" / "__pycache__").mkdir()
+    _set_include(root, ["packs/__pycache__"])
+    _assert_single_diagnostic(tmp_path, root, "packs/__pycache__")
+
+
+def test_scaffold_template_include_entry_is_a_diagnostic(tmp_path: Path) -> None:
+    root = _blank_catalogue(tmp_path)
+    _set_include(root, ["packs/_example"])
+    _assert_single_diagnostic(tmp_path, root, "packs/_example")
+
+
+def test_bare_packs_include_entry_still_packages(tmp_path: Path) -> None:
+    """`packs/` names the whole packs directory, so it walks every pack as before."""
+    from agentbundle.catalogue_tooling.package import package_catalogue
+
+    root = _blank_catalogue(tmp_path)
+    _set_include(root, ["packs/"])
+
+    result = package_catalogue(
+        root=root, bundle="demo", release="0.1.0", channel="stable", output=tmp_path / "out",
+    )
+
+    assert result.ok, result.diagnostics
+
+
+def test_cli_reports_bad_include_without_a_traceback(tmp_path: Path) -> None:
+    import os
+    import subprocess
+    import sys
+
+    root = _blank_catalogue(tmp_path)
+    _set_include(root, ["packs/nope"])
+    env = os.environ.copy()
+    package_root = Path(__file__).resolve().parents[2]
+    env["PYTHONPATH"] = os.pathsep.join(filter(None, [str(package_root), env.get("PYTHONPATH")]))
+    env["PYTHONIOENCODING"] = "utf-8"
+
+    proc = subprocess.run(
+        [
+            sys.executable, "-m", "agentbundle", "catalogue", "package",
+            "--root", str(root), "--bundle", "demo", "--release", "0.1.0",
+            "--channel", "stable", "--output", str(tmp_path / "out"),
+        ],
+        env=env, capture_output=True, text=True, encoding="utf-8",
+    )
+
+    assert proc.returncode == 1, (proc.stdout, proc.stderr)
+    assert "CAT-PKG-001" in proc.stderr
+    assert "Traceback" not in proc.stderr
+    assert "Traceback" not in proc.stdout
+
+
+def test_underscore_directory_inside_a_real_pack_is_packaged(tmp_path: Path) -> None:
+    import json
+    import shutil
+    import tarfile
+
+    from agentbundle.catalogue_tooling.package import package_catalogue
+
+    root = _blank_catalogue(tmp_path)
+    pack = root / "packs" / "demo-pack"
+    shutil.copytree(root / "packs" / "_example", pack)
+    for rel in ("pack.toml", ".claude-plugin/plugin.json"):
+        f = pack / rel
+        if f.is_file():
+            f.write_text(f.read_text(encoding="utf-8").replace("example-pack", "demo-pack"), encoding="utf-8")
+    plugin = pack / ".claude-plugin" / "plugin.json"
+    if plugin.is_file():
+        assert json.loads(plugin.read_text(encoding="utf-8"))["name"] == "demo-pack"
+    (pack / "_sub").mkdir()
+    (pack / "_sub" / "note.md").write_text("note\n", encoding="utf-8")
+    _set_include(root, ["packs/demo-pack"])
+    out = tmp_path / "out"
+
+    result = package_catalogue(
+        root=root, bundle="demo", release="0.1.0", channel="stable", output=out,
+    )
+
+    assert result.ok, result.diagnostics
+    archive = out / "catalogues" / "demo" / "releases" / "0.1.0" / "catalogue-0.1.0.tar.gz"
+    with tarfile.open(archive, "r:gz") as tf:
+        names = set(tf.getnames())
+    expected = {
+        p.relative_to(root).as_posix() for p in pack.rglob("*") if p.is_file() and not p.is_symlink()
+    }
+    assert "packs/demo-pack/_sub/note.md" in expected
+    assert expected <= names