agentbundle 0.52.1__tar.gz → 0.53.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.52.1
+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,25 @@ 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
+already exists and exits 2; `--force` replaces it on purpose. `--compare
+<archive>` lists the packs and profiles added, removed or changed since a prior
+release, and `--format json` writes that result on stdout. Shortened options
+such as `--forc` are rejected, and each `profiles` entry in the manifest is now
+an object with a `path` and a `digest`.
+
 ## What's new in 0.52.1
 
 The workspace-status engine and MCP tool now route `shape` entries to

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

@@ -14,6 +14,25 @@ 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
+already exists and exits 2; `--force` replaces it on purpose. `--compare
+<archive>` lists the packs and profiles added, removed or changed since a prior
+release, and `--format json` writes that result on stdout. Shortened options
+such as `--forc` are rejected, and each `profiles` entry in the manifest is now
+an object with a `path` and a `digest`.
+
 ## What's new in 0.52.1
 
 The workspace-status engine and MCP tool now route `shape` entries to

{agentbundle-0.52.1 → agentbundle-0.53.1}/agentbundle/_data/catalogue-scaffold/guides/_shared/reference/catalogue-authoring-standards.md

@@ -69,7 +69,7 @@ and `version`; `[pack.adapter-contract]` with `version`.
 marketplace browser, a catalogue listing, or CLI output. It is not read by the model.
 
 That makes it a different artifact from a skill's or agent's `description`, which the
-model reads to decide whether to **activate** the primitive. Length is load-bearing
+model reads to decide whether to **activate** the primitive. Length matters
 there and shortening it degrades activation; per-target caps in
 `contracts/target-vocab.toml` govern it. Do not carry habits from one to the other.
 
@@ -126,7 +126,7 @@ review against the shape and the table above.
 A pack README serves adopters, not contributors. It states the pack's intent and the
 user journey it serves — not a skill inventory. See the `_example` pack for a template.
 
-- [packs/_example/README.md](../../../packs/_example/README.md) — canonical example.
+- [packs/_example/README.md](../../../packs/_example/README.md) — the model example.
 
 ---
 
@@ -224,7 +224,7 @@ archive supports downstream verification, auditing, security review, and
 testing an extracted release.
 
 Catalogue inclusion does not imply runtime installation. Installers and
-projection adapters treat `.apm/` and `seeds/` as the projected surfaces, so
+projection adapters treat `.apm/` and `seeds/` as the projected folders, so
 nothing outside those two — `tests/` included — reaches an installed
 environment.
 
@@ -441,18 +441,18 @@ environment, smoke-test it there, and confirm the projection contains no
 Every skill is a Markdown file with YAML frontmatter. Required frontmatter keys:
 `title`, `description` (≤ 1024 characters), `kind`.
 
-- `guides/_shared/how-to/author-a-skill.md` — frontmatter key list, body structure,
-  naming rules, progressive-disclosure pattern, three-tier dependency policy, and eval
-  coverage. (Available in the full guide library; not bundled in this scaffold.)
+- `guides/_shared/reference/skill-authoring-standards.md` — frontmatter key list, body
+  structure, naming rules, progressive-disclosure pattern, three-tier dependency policy,
+  and eval coverage. (Available in the full guide library; not bundled in this scaffold.)
 
 ---
 
 ## 6. Skill body and progressive disclosure
 
 Long skills use progressive disclosure: a brief required-reading summary at the top,
-with detail sections the agent loads on demand. This keeps context usage bounded.
+with detail sections the agent loads on demand. This keeps context usage small.
 
-See `guides/_shared/how-to/author-a-skill.md` for the full pattern.
+See `guides/_shared/reference/skill-authoring-standards.md` for the full pattern.
 
 ---
 

{agentbundle-0.52.1 → agentbundle-0.53.1}/agentbundle/_data/catalogue-scaffold/guides/_shared/reference/catalogue-ci-contract.md

@@ -113,6 +113,18 @@ is computed over the archive and stored alongside it. The channel descriptor is
 small JSON file that records which release the channel currently points to; it is
 the live pointer consumers use to resolve the latest version.
 
+Packaging refuses to replace a release that already exists. When
+`catalogue-$RELEASE.tar.gz` is already under `$OUTPUT`, the command exits 2,
+prints the existing archive path on stderr, and writes nothing. Publish each
+release once, from a fresh output directory. A CI step never passes `--force`;
+only a publisher replacing a release by hand does.
+
+To see what changed since the last release, pass the prior archive:
+
+```bash
+agentbundle catalogue package ... --compare "/path/to/catalogue-$PRIOR.tar.gz" --format json
+```
+
 Re-run `agentbundle catalogue verify --archive <path>.tar.gz` after packaging to
 confirm the archive is valid before uploading it.
 
@@ -197,10 +209,11 @@ All `agentbundle catalogue` commands follow the same convention:
 |------|---------|
 | `0` | Success |
 | `1` | Validation or operational failure (errors in the catalogue, archive mismatch, internal error) |
-| `2` | CLI usage error (missing required flag, unknown option) |
+| `2` | CLI usage error (missing required flag, unknown or abbreviated option); for `catalogue package`, also a refused replacement of an existing release archive |
 
 These codes are stable. A CI step that treats any non-zero exit as a failure
-gets the correct behaviour.
+gets the correct behaviour. A step that must tell a refused replacement from a
+usage error reads exit 2 together with the `CAT-PKG-002` line on stderr.
 
 ## Credential and network boundaries
 
@@ -277,15 +290,80 @@ agentbundle catalogue package --bundle BUNDLE --release RELEASE
                                [--source-revision SOURCE_REVISION]
                                [--minimum-agentbundle-version VERSION]
                                [--published-at DATETIME]
+                               [--flavor {runtime,source}]
+                               [--force] [--compare PATH]
+                               [--format {table,json}]
 ```
 
 Required flags: `--bundle`, `--release`, `--channel`, `--output`.
-Optional: `--root` (defaults to `.`), `--source-revision`, `--minimum-agentbundle-version`,
-`--published-at`.
+Optional:
+
+| Flag | Meaning |
+|------|---------|
+| `--root` | Catalogue root; defaults to `.` |
+| `--source-revision` | VCS revision recorded as audit metadata |
+| `--minimum-agentbundle-version` | Minimum consumer version required |
+| `--published-at` | ISO-8601 timestamp override |
+| `--flavor` | `runtime` (default) writes the runtime archive; `source` writes the self-hosted source archive |
+| `--force` | Replace an existing release archive instead of refusing. First-party CI never passes it |
+| `--compare PATH` | Prior release archive to compare against; runtime flavour only |
+| `--format` | `table` (default) or `json`; `json` writes one envelope on stdout; runtime flavour only |
+
+`--flavor source` with `--compare` or `--format json` exits 2 with a usage
+message and writes nothing. The subcommand rejects abbreviated options, so
+`--forc` exits 2 rather than selecting `--force`.
+
+**Streams.** Human output and diagnostic lines go to stderr in both formats.
+Each diagnostic is one line, `<code>: <message>`. Stdout carries the JSON
+envelope alone, and nothing when `--format table` is used. Text taken from the
+prior archive is printed with non-printable characters written as escapes.
+
+**`--format json`.** On success and on a failure after argument parsing, stdout
+is one JSON object:
+
+```json
+{
+  "schema_version": 1,
+  "command": "catalogue",
+  "operation": "package",
+  "agentbundle_version": "<version>",
+  "catalogue_schema_version": 1,
+  "ok": true,
+  "diagnostics": []
+}
+```
+
+With `--compare`, a successful run adds a `comparison` object:
+
+```json
+{
+  "comparison": {
+    "prior": {"archive": "<--compare value>", "bundle": "<bundle>", "release": "<release>"},
+    "packs": {"added": [], "removed": [], "changed": [], "unchanged": 0},
+    "profiles": {"added": [], "removed": [], "changed": [], "unchanged": 0}
+  }
+}
+```
+
+Added and removed pack items are `{name, version, digest}`; profile items are
+`{name, digest}`. A changed pack is `{name, version: {from, to}, digest: {from, to}}`;
+a changed profile is `{name, digest: {from, to}}`. Each list is sorted by name and
+`unchanged` is a count. A failed run has `ok` false, the failing codes in
+`diagnostics`, and no `comparison`. The human comparison on stderr marks a pack
+whose content changed under an unchanged version with
+`content changed, version unchanged`.
+
+**Exit codes.**
+
+| Code | Meaning |
+|------|---------|
+| `0` | Packaged; with `--force`, a replaced release also exits 0 |
+| `1` | Failure: verification, an unreadable or invalid `--compare` archive, or an internal error |
+| `2` | Usage error, or a refused replacement of an existing release archive (`CAT-PKG-002`) |
 
-`catalogue package` does not support `--format json`; its result is the output
-directory layout described in [Phase 3](#phase-3--release-packaging). Exits 0
-on success, 1 on failure, 2 on missing required flags.
+The refusal applies to both flavours and runs before any file is written. The
+deprecated top-level `package-catalogue` command is unchanged and exits 1 on the
+same refusal.
 
 ## See also
 

{agentbundle-0.52.1 → agentbundle-0.53.1}/agentbundle/_data/catalogue-scaffold/manifest.json

@@ -1,7 +1,7 @@
 {
   "files": {
-    "guides/_shared/reference/catalogue-authoring-standards.md": "72771324354ff29a4bf9072f48236e537bc680421785d700d2a3308d562777cc",
-    "guides/_shared/reference/catalogue-ci-contract.md": "78994d30da2b0eb9ea9347f397791fafa99ebc92f80410f26b9af93788a6e188",
+    "guides/_shared/reference/catalogue-authoring-standards.md": "0b85918871438d7410f31d5e42eeebdf86892e8156428ed4eebdb7acc1e5f933",
+    "guides/_shared/reference/catalogue-ci-contract.md": "304c149ae6a3bd32b404b3c384b511266eec8e4e6dd58aa26ec4b9dd1d8f06cd",
     "packs/AGENTS.md": "c20af03f72b4c25c032ba5c15299eadaa0b41442c92d1cf621dde042cf9ff8db",
     "packs/CLAUDE.md": "336cc4fbf19beaada7ccf9986414fa91851a8d7a07dfb3ccbe800a69eed0ab49",
     "packs/README.md": "d2de5f9556f4c8e521103474bde74636e02cc805f9bf5312a3a61a1f3eb45d8f",

{agentbundle-0.52.1 → agentbundle-0.53.1}/agentbundle/_data/guide.schema.json

@@ -3,12 +3,17 @@
   "title": "Guide frontmatter",
   "description": "YAML frontmatter schema for catalogue-facing guide files under guides/.",
   "type": "object",
-  "required": ["title", "summary", "pack", "kind"],
+  "required": [
+    "title",
+    "summary",
+    "pack",
+    "kind"
+  ],
   "properties": {
     "title": {
       "type": "string",
       "minLength": 1,
-      "description": "Page title — used by the docs-site renderer as the heading."
+      "description": "Page title \u2014 used by the docs-site renderer as the heading."
     },
     "summary": {
       "type": "string",
@@ -22,8 +27,13 @@
     },
     "kind": {
       "type": "string",
-      "enum": ["tutorial", "how-to", "reference", "explanation"],
-      "description": "Diátaxis kind — a page contract, not a directory requirement."
+      "enum": [
+        "tutorial",
+        "how-to",
+        "reference",
+        "explanation"
+      ],
+      "description": "Di\u00e1taxis kind \u2014 a page contract, not a directory requirement."
     },
     "slug": {
       "type": "string",
@@ -49,8 +59,23 @@
     },
     "status": {
       "type": "string",
-      "enum": ["draft", "review", "stable", "deprecated"],
+      "enum": [
+        "draft",
+        "review",
+        "stable",
+        "deprecated"
+      ],
       "description": "Optional publication status. Defaults to 'stable' when absent."
+    },
+    "uses": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]*$"
+      },
+      "description": "Packs a reader needs for this page, shown as pills above the title. Defaults to `pack` when that is a real pack."
     }
   },
   "additionalProperties": false

{agentbundle-0.52.1 → agentbundle-0.53.1}/agentbundle/catalogue_tooling/archive.py

@@ -9,7 +9,9 @@ from __future__ import annotations
 
 import hashlib
 import json
+import stat
 import tarfile
+from collections.abc import Mapping
 from pathlib import Path
 
 from agentbundle.catalogue import CatalogueError
@@ -36,6 +38,34 @@ def _get_agentbundle_version() -> str:
     return _AGENTBUNDLE_VERSION
 
 
+def unit_digest(file_digests: Mapping[str, str], unit_path: str) -> str | None:
+    """Return the unit digest of ``unit_path`` over ``file_digests`` (AC-0001).
+
+    ``file_digests`` maps archived relative paths to lowercase hex SHA-256.
+    If it holds ``unit_path`` exactly, the unit is that one file, named by its
+    basename; otherwise it is the directory of files under ``unit_path + "/"``.
+    Returns ``None`` when no member file exists.
+    """
+    if unit_path in file_digests:
+        members = {unit_path.rsplit("/", 1)[-1]: file_digests[unit_path]}
+    else:
+        prefix = unit_path + "/"
+        members = {
+            path[len(prefix):]: digest
+            for path, digest in file_digests.items()
+            if path.startswith(prefix)
+        }
+    if not members:
+        return None
+    # Sort by UTF-8 bytes, not code points, to honour "byte order".
+    lines = sorted(
+        (rel.encode("utf-8"), f"{digest}  {rel}\n")
+        for rel, digest in members.items()
+    )
+    preimage = "".join(line for _, line in lines)
+    return "sha256:" + hashlib.sha256(preimage.encode("utf-8")).hexdigest()
+
+
 def _err(code: str, message: str, path: str | None = None) -> Diagnostic:
     return Diagnostic(
         code=code,
@@ -193,7 +223,83 @@ def _parse_manifest(
         return None, [_err("CAT-V-ARC-010", f"{_MANIFEST_NAME} parse error: {exc}")]
 
 
-def _check_manifest_schema(manifest: dict) -> list[Diagnostic]:
+def _entry_label(kind: str, index: int, item: object) -> str:
+    """Name a manifest entry for a diagnostic: its ``name`` when a string, else its index."""
+    if isinstance(item, str):
+        return f"{kind}[{index}] {item!r}"
+    if isinstance(item, dict) and isinstance(item.get("name"), str):
+        return f"{kind}[{index}] {item['name']!r}"
+    return f"{kind}[{index}]"
+
+
+def _check_unit_entry_fields(label: str, item: dict) -> list[Diagnostic]:
+    """AC-0018: ``path`` and ``digest`` must be strings, and ``digest`` needs ``path``."""
+    diags: list[Diagnostic] = []
+    for field in ("path", "digest"):
+        if field in item and not isinstance(item[field], str):
+            diags.append(_err("CAT-V-ARC-019", f"manifest {label} {field!r} must be a string"))
+    if "digest" in item and "path" not in item:
+        diags.append(_err("CAT-V-ARC-019", f"manifest {label} has a 'digest' but no 'path'"))
+    return diags
+
+
+def _check_manifest_shape(manifest: dict) -> list[Diagnostic]:
+    """AC-0018 shape checks over ``files``, ``packs`` and ``profiles``; one diagnostic per item."""
+    diags: list[Diagnostic] = []
+    files = manifest.get("files")
+    if isinstance(files, list):
+        for i, item in enumerate(files):
+            if not (
+                isinstance(item, dict)
+                and isinstance(item.get("path"), str)
+                and isinstance(item.get("sha256"), str)
+            ):
+                diags.append(_err(
+                    "CAT-V-ARC-019",
+                    f"manifest {_entry_label('files', i, item)} must be an object "
+                    "with string 'path' and 'sha256'",
+                ))
+    packs = manifest.get("packs")
+    if isinstance(packs, list):
+        for i, item in enumerate(packs):
+            label = _entry_label("packs", i, item)
+            if not (
+                isinstance(item, dict)
+                and isinstance(item.get("name"), str)
+                and isinstance(item.get("version"), str)
+            ):
+                diags.append(_err(
+                    "CAT-V-ARC-019",
+                    f"manifest {label} must be an object with string 'name' and 'version'",
+                ))
+            if isinstance(item, dict):
+                diags.extend(_check_unit_entry_fields(label, item))
+    if "profiles" in manifest:
+        profiles = manifest["profiles"]
+        if not isinstance(profiles, list):
+            diags.append(_err("CAT-V-ARC-019", "manifest 'profiles' must be a list"))
+        else:
+            for i, item in enumerate(profiles):
+                label = _entry_label("profiles", i, item)
+                if isinstance(item, str):
+                    continue
+                if not (isinstance(item, dict) and isinstance(item.get("name"), str)):
+                    diags.append(_err(
+                        "CAT-V-ARC-019",
+                        f"manifest {label} must be a string or an object with a string 'name'",
+                    ))
+                if isinstance(item, dict):
+                    diags.extend(_check_unit_entry_fields(label, item))
+    return diags
+
+
+def _check_manifest_schema(manifest: object) -> list[Diagnostic]:
+    """Check manifest schema and shape; accepts any parsed JSON value without raising."""
+    if not isinstance(manifest, dict):
+        return [_err(
+            "CAT-V-ARC-019",
+            f"manifest must be a JSON object, got {type(manifest).__name__}",
+        )]
     diags: list[Diagnostic] = []
     schema = manifest.get("schema")
     if schema not in (1, 2):
@@ -208,6 +314,31 @@ def _check_manifest_schema(manifest: dict) -> list[Diagnostic]:
         diags.append(_err("CAT-V-ARC-011", "manifest 'files' must be a list"))
     if not isinstance(manifest.get("packs"), list):
         diags.append(_err("CAT-V-ARC-011", "manifest 'packs' must be a list"))
+    diags.extend(_check_manifest_shape(manifest))
+    return diags
+
+
+def _check_unit_digests(manifest: dict) -> list[Diagnostic]:
+    """AC-0005: each declared unit ``digest`` must equal the unit digest of its ``path``.
+
+    Entries without a ``digest`` (legacy manifests) are skipped (AC-0006). Runs only on
+    manifests that passed ``_check_manifest_schema``, so entries are well typed.
+    """
+    file_digests = {e["path"]: e["sha256"] for e in manifest["files"]}
+    diags: list[Diagnostic] = []
+    for kind in ("packs", "profiles"):
+        for i, item in enumerate(manifest.get(kind, [])):
+            if not isinstance(item, dict) or "digest" not in item:
+                continue
+            expected = item["digest"]
+            actual = unit_digest(file_digests, item["path"])
+            if actual != expected:
+                diags.append(_err(
+                    "CAT-V-ARC-018",
+                    f"unit digest mismatch for {_entry_label(kind, i, item)} "
+                    f"path {item['path']!r}: declared {expected!r}, computed {actual!r}",
+                    path=item["path"],
+                ))
     return diags
 
 
@@ -411,17 +542,43 @@ def verify_archive(archive: Path, sha256_file: Path | None = None) -> VerifyResu
 
         manifest, manifest_diags = _parse_manifest(tf, members)
         diags.extend(manifest_diags)
-        if manifest is None:
+        if manifest_diags:
             return _make_result(diags, "archive")
 
         diags.extend(_check_manifest_schema(manifest))
         if any(d.severity == Severity.ERROR for d in diags):
             return _make_result(diags, "archive")
+        assert isinstance(manifest, dict)  # a non-object manifest yields CAT-V-ARC-019 above
 
         diags.extend(_check_all_manifest_digests(tf, members, manifest))
+        diags.extend(_check_unit_digests(manifest))
         diags.extend(_check_no_undeclared_members(members, manifest))
         diags.extend(_check_catalogue_markers(members))
         diags.extend(_check_marketplace_entries(tf, members))
         diags.extend(_check_min_agentbundle_compat(manifest))
 
     return _make_result(diags, "archive")
+
+
+def read_verified_manifest(archive: Path) -> tuple[dict | None, VerifyResult]:
+    """Return the manifest of ``archive`` only when ``verify_archive`` passes on it.
+
+    A path that is not a regular file is refused before it is opened (AC-0023).
+    The archive is read in memory; nothing is extracted to disk. The manifest is
+    ``None`` whenever the returned result is not ok.
+    """
+    try:
+        is_regular = stat.S_ISREG(archive.stat().st_mode)
+        problem = None if is_regular else f"not a regular file: {archive}"
+    except OSError as exc:
+        problem = f"cannot read archive: {exc}"
+    if problem is not None:
+        return None, _make_result([_err("CAT-V-ARC-002", problem)], "archive")
+    result = verify_archive(archive)
+    if not result.ok:
+        return None, result
+    with tarfile.open(archive, "r:gz") as tf:
+        manifest, diags = _parse_manifest(tf, tf.getmembers())
+    if diags or not isinstance(manifest, dict):
+        return None, _make_result(diags, "archive")
+    return manifest, result

{agentbundle-0.52.1 → 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,
         ))