agentbundle 0.35.2__tar.gz → 0.38.1__tar.gz

{agentbundle-0.35.2/agentbundle.egg-info → agentbundle-0.38.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.35.2
+Version: 0.38.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
@@ -34,42 +34,89 @@ python -m pip install agentbundle
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
 
-## What's new in 0.35.0
+## What's new in 0.38.1
 
-**Installs now work on corporate networks that inspect TLS.** If your employer
-runs a proxy that re-signs HTTPS traffic, an install used to fail like this and
-leave you nothing to act on:
+`agentbundle catalogue self-host --check --windows` gained a stage that verifies
+a source catalogue's declared knowledge bundles against their committed output.
+The verification itself is performed by the catalogue's own tooling, so this
+changes nothing for installing or using a pack.
 
-```
-install: Failed to fetch catalogue archive: … —
-  [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:
-  unable to get local issuer certificate
-```
+## What's new in 0.38.0
 
-The certificate authority your IT team installed is in the operating system's
-trust store, and Python does not read that store on macOS. AgentBundle now
-recovers on its own:
+`agentbundle show <pack> --format json` now emits the additive pre-release rich
+discovery fields `pack_metadata`, `skill_metadata`, and `knowledge` when the
+pack is read from a live catalogue. The existing fields keep their current
+meaning and ordering; installed-state fallback cannot prove rich metadata, so
+those three fields are exactly `null` there.
 
+The rich discovery surface is deliberately one-pack-at-a-time. It does not add
+OKF data to `list-packs`, Claude marketplace output, `catalogue-index.json`, or
+installed state, and it does not run compilers, network fetches, or pack code.
+
+## Catalogue verification
+
+`agentbundle catalogue verify` performs all 19 advertised checks. It validates
+profile schemas and pack references, dependency ranges and cycles, adapter
+compatibility, generated-output drift, pack preflight metadata, and skill
+evaluation manifests. The verifier remains read-only and portable across
+external catalogues.
+
+Dependency ranges use the same npm-compatible grammar in verify, lint, and
+install: caret, tilde, comparator, compound, and prerelease forms agree across
+all three commands. In particular, caret ranges below `1.0.0` use normal semver
+compatibility (`^0.2` does not include `0.3.x`).
+
+`agentbundle catalogue index` now generates a deterministic, adapter-neutral
+`catalogue-index.json` from catalogue, pack, profile, and optional journey
+metadata. The command validates against its bundled public schema before an
+atomic no-follow write; `--dry-run` writes nothing, and `--format json` emits one
+closed result document for automation.
+
+The generated index exposes content-addressable pack digests, structural content
+and execution inventory, profile composition, declared external effects, and
+forward and inverse pack integrations without relying on one agent host's
+marketplace format.
+
+## Catalogue authoring
+
+New catalogue scaffolds document the `JOURNEY.md` convention: required and
+optional frontmatter, external-effect declarations, reader-facing body sections,
+and migration guidance. Existing packs without a journey remain valid and appear
+with an empty `journeys` array.
+
+The same authoring reference retains the guide callout contract: exact quoted
+wording remains a blockquote, while guidance uses the documented typed aside.
+
+Generate and validate a neutral index with:
+
+```bash
+agentbundle catalogue index . --dry-run
+agentbundle catalogue index . --output catalogue-index.json
 ```
-agentbundle: certificate verification failed for github.com;
-  retrying with operating-system trust anchors
-```
 
-Verification stays strict throughout — the retry *adds* trust anchors and never
-removes one, and no flag or environment variable can disable verification. Only
-the administrator keychain is read; your login keychain never is, because it is
-writable without administrator rights. Set `AGENTBUNDLE_NO_SYSTEM_TRUST=1` to
-opt out and see the underlying error.
+## Contract discovery
+
+The bundled public contract inventory includes `catalogue-index.schema.json` as
+the closed contract for generated neutral indexes. It also includes the strict
+`knowledge-captured-observation.schema.json` contract used by the core pack's
+project-knowledge capture handoff.
+
+You can inspect the exact public contracts bundled with the installed
+AgentBundle version without network access:
+
+```bash
+agentbundle catalogue contracts list
+agentbundle catalogue contracts show pack.schema.json
+agentbundle catalogue contracts export --output ./reference-contracts
+```
 
-`AGENTBUNDLE_CA_BUNDLE` also works on `git+https://` sources now — previously
-only the `catalogue+https://` and `archive+https://` forms read it, so following
-the documentation did not help. `SSL_CERT_FILE`, `SSL_CERT_DIR`, and
-`REQUESTS_CA_BUNDLE` are honoured there too. See
-[Corporate networks](#corporate-networks) below.
+`list` and `show` are read-only. `export` writes reference copies through a
+no-follow, preflighted batch writer; those copies do not override the contracts
+AgentBundle uses for validation.
 
-When a fetch still fails, the error names the likely cause and ordered next
-steps, and the request now carries a 30-second timeout so a proxy that accepts
-the connection and never answers fails instead of hanging.
+Successful `agentbundle catalogue init` output points to the scaffolded
+`guides/_shared/reference/catalogue-authoring-standards.md`, contract discovery,
+and catalogue verification. JSON init output remains unchanged.
 
 **Install into a repo** — so everyone who clones it gets the pack. `core` is the flagship pack, the loop itself:
 
@@ -153,7 +200,7 @@ agentbundle uninstall --pack core --yes
 
 **`list-installed`** reads your state files (not the catalogue) and reports every installed `(pack, adapter)` at each scope with its version and a four-value status — `up-to-date`, `upgrade-available`, `ahead` (installed version is newer than catalogue), or `unknown`; it degrades to `unknown` (never an error) when the catalogue can't be resolved, and `--no-check` skips the check entirely. `--format json` emits a stable JSON contract (`schema_version: 1`) to stdout — useful for CI automation of upgrade decisions. `--updates-only` hides `up-to-date` rows.
 
-**`show <pack>`** answers "what skills and agents does this pack contain?" by walking the pack's source tree live on each call — so the answer can't drift, and nothing is persisted. `--format json` emits a stable object (`name`, `version`, `description`, `skills`, `agents`, `source`) for scripts and agents. When the catalogue can't be resolved, an *installed* pack still reports its inventory from your state files (marked `source: installed-state`); a not-installed pack errors.
+**`show <pack>`** answers "what skills and agents does this pack contain?" by walking the pack's source tree live on each call — so the answer can't drift, and nothing is persisted. `--format json` emits a stable object (`name`, `version`, `description`, `skills`, `agents`, `integrations`, `source`, `pack_metadata`, `skill_metadata`, `knowledge`) for scripts and agents. The three rich metadata fields are pre-release: they are source-backed only for live catalogue reads and are not a cross-pack OKF index. When the catalogue can't be resolved, an *installed* pack still reports its inventory from your state files (marked `source: installed-state`), with `pack_metadata`, `skill_metadata`, and `knowledge` set to `null`; a not-installed pack errors.
 
 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. **Upgrade takes no version** — the target is whatever the catalogue you point at declares; to pin a past version, point the catalogue at that git ref. Install a pack that's **already there** and `agentbundle` offers to `upgrade` it instead (`--yes` runs it straight away).
 

{agentbundle-0.35.2 → agentbundle-0.38.1}/README-pypi.md

@@ -14,42 +14,89 @@ python -m pip install agentbundle
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
 
-## What's new in 0.35.0
+## What's new in 0.38.1
 
-**Installs now work on corporate networks that inspect TLS.** If your employer
-runs a proxy that re-signs HTTPS traffic, an install used to fail like this and
-leave you nothing to act on:
+`agentbundle catalogue self-host --check --windows` gained a stage that verifies
+a source catalogue's declared knowledge bundles against their committed output.
+The verification itself is performed by the catalogue's own tooling, so this
+changes nothing for installing or using a pack.
 
-```
-install: Failed to fetch catalogue archive: … —
-  [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:
-  unable to get local issuer certificate
-```
+## What's new in 0.38.0
 
-The certificate authority your IT team installed is in the operating system's
-trust store, and Python does not read that store on macOS. AgentBundle now
-recovers on its own:
+`agentbundle show <pack> --format json` now emits the additive pre-release rich
+discovery fields `pack_metadata`, `skill_metadata`, and `knowledge` when the
+pack is read from a live catalogue. The existing fields keep their current
+meaning and ordering; installed-state fallback cannot prove rich metadata, so
+those three fields are exactly `null` there.
 
+The rich discovery surface is deliberately one-pack-at-a-time. It does not add
+OKF data to `list-packs`, Claude marketplace output, `catalogue-index.json`, or
+installed state, and it does not run compilers, network fetches, or pack code.
+
+## Catalogue verification
+
+`agentbundle catalogue verify` performs all 19 advertised checks. It validates
+profile schemas and pack references, dependency ranges and cycles, adapter
+compatibility, generated-output drift, pack preflight metadata, and skill
+evaluation manifests. The verifier remains read-only and portable across
+external catalogues.
+
+Dependency ranges use the same npm-compatible grammar in verify, lint, and
+install: caret, tilde, comparator, compound, and prerelease forms agree across
+all three commands. In particular, caret ranges below `1.0.0` use normal semver
+compatibility (`^0.2` does not include `0.3.x`).
+
+`agentbundle catalogue index` now generates a deterministic, adapter-neutral
+`catalogue-index.json` from catalogue, pack, profile, and optional journey
+metadata. The command validates against its bundled public schema before an
+atomic no-follow write; `--dry-run` writes nothing, and `--format json` emits one
+closed result document for automation.
+
+The generated index exposes content-addressable pack digests, structural content
+and execution inventory, profile composition, declared external effects, and
+forward and inverse pack integrations without relying on one agent host's
+marketplace format.
+
+## Catalogue authoring
+
+New catalogue scaffolds document the `JOURNEY.md` convention: required and
+optional frontmatter, external-effect declarations, reader-facing body sections,
+and migration guidance. Existing packs without a journey remain valid and appear
+with an empty `journeys` array.
+
+The same authoring reference retains the guide callout contract: exact quoted
+wording remains a blockquote, while guidance uses the documented typed aside.
+
+Generate and validate a neutral index with:
+
+```bash
+agentbundle catalogue index . --dry-run
+agentbundle catalogue index . --output catalogue-index.json
 ```
-agentbundle: certificate verification failed for github.com;
-  retrying with operating-system trust anchors
-```
 
-Verification stays strict throughout — the retry *adds* trust anchors and never
-removes one, and no flag or environment variable can disable verification. Only
-the administrator keychain is read; your login keychain never is, because it is
-writable without administrator rights. Set `AGENTBUNDLE_NO_SYSTEM_TRUST=1` to
-opt out and see the underlying error.
+## Contract discovery
+
+The bundled public contract inventory includes `catalogue-index.schema.json` as
+the closed contract for generated neutral indexes. It also includes the strict
+`knowledge-captured-observation.schema.json` contract used by the core pack's
+project-knowledge capture handoff.
+
+You can inspect the exact public contracts bundled with the installed
+AgentBundle version without network access:
+
+```bash
+agentbundle catalogue contracts list
+agentbundle catalogue contracts show pack.schema.json
+agentbundle catalogue contracts export --output ./reference-contracts
+```
 
-`AGENTBUNDLE_CA_BUNDLE` also works on `git+https://` sources now — previously
-only the `catalogue+https://` and `archive+https://` forms read it, so following
-the documentation did not help. `SSL_CERT_FILE`, `SSL_CERT_DIR`, and
-`REQUESTS_CA_BUNDLE` are honoured there too. See
-[Corporate networks](#corporate-networks) below.
+`list` and `show` are read-only. `export` writes reference copies through a
+no-follow, preflighted batch writer; those copies do not override the contracts
+AgentBundle uses for validation.
 
-When a fetch still fails, the error names the likely cause and ordered next
-steps, and the request now carries a 30-second timeout so a proxy that accepts
-the connection and never answers fails instead of hanging.
+Successful `agentbundle catalogue init` output points to the scaffolded
+`guides/_shared/reference/catalogue-authoring-standards.md`, contract discovery,
+and catalogue verification. JSON init output remains unchanged.
 
 **Install into a repo** — so everyone who clones it gets the pack. `core` is the flagship pack, the loop itself:
 
@@ -133,7 +180,7 @@ agentbundle uninstall --pack core --yes
 
 **`list-installed`** reads your state files (not the catalogue) and reports every installed `(pack, adapter)` at each scope with its version and a four-value status — `up-to-date`, `upgrade-available`, `ahead` (installed version is newer than catalogue), or `unknown`; it degrades to `unknown` (never an error) when the catalogue can't be resolved, and `--no-check` skips the check entirely. `--format json` emits a stable JSON contract (`schema_version: 1`) to stdout — useful for CI automation of upgrade decisions. `--updates-only` hides `up-to-date` rows.
 
-**`show <pack>`** answers "what skills and agents does this pack contain?" by walking the pack's source tree live on each call — so the answer can't drift, and nothing is persisted. `--format json` emits a stable object (`name`, `version`, `description`, `skills`, `agents`, `source`) for scripts and agents. When the catalogue can't be resolved, an *installed* pack still reports its inventory from your state files (marked `source: installed-state`); a not-installed pack errors.
+**`show <pack>`** answers "what skills and agents does this pack contain?" by walking the pack's source tree live on each call — so the answer can't drift, and nothing is persisted. `--format json` emits a stable object (`name`, `version`, `description`, `skills`, `agents`, `integrations`, `source`, `pack_metadata`, `skill_metadata`, `knowledge`) for scripts and agents. The three rich metadata fields are pre-release: they are source-backed only for live catalogue reads and are not a cross-pack OKF index. When the catalogue can't be resolved, an *installed* pack still reports its inventory from your state files (marked `source: installed-state`), with `pack_metadata`, `skill_metadata`, and `knowledge` set to `null`; a not-installed pack errors.
 
 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. **Upgrade takes no version** — the target is whatever the catalogue you point at declares; to pin a past version, point the catalogue at that git ref. Install a pack that's **already there** and `agentbundle` offers to `upgrade` it instead (`--yes` runs it straight away).
 

agentbundle-0.38.1/agentbundle/_data/catalogue-index.schema.json

@@ -0,0 +1,180 @@
+{
+  "x-spec": "docs/specs/catalogue-wave4-semantic-contracts-index",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "catalogue-index.schema.json",
+  "title": "Neutral catalogue index",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "catalogue", "packs", "profiles"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "enum": ["1"]
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "catalogue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": {"type": "string"},
+        "description": {"type": "string"}
+      }
+    },
+    "packs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "name",
+          "version",
+          "scope",
+          "integrations",
+          "integrations_inverse",
+          "journeys",
+          "effects",
+          "digest"
+        ],
+        "properties": {
+          "name": {"type": "string"},
+          "version": {"type": "string"},
+          "scope": {"type": "string", "enum": ["repo", "user"]},
+          "description": {"type": "string"},
+          "categories": {"type": "array", "items": {"type": "string"}},
+          "adapters": {"type": "array", "items": {"type": "string"}},
+          "integrations": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["id", "pack", "kind", "role"],
+              "properties": {
+                "id": {"type": "string"},
+                "pack": {"type": "string"},
+                "kind": {
+                  "type": "string",
+                  "enum": ["input", "augment", "review", "handoff"]
+                },
+                "role": {"type": "string"}
+              }
+            }
+          },
+          "integrations_inverse": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["id", "pack", "kind", "role"],
+              "properties": {
+                "id": {"type": "string"},
+                "pack": {"type": "string"},
+                "kind": {
+                  "type": "string",
+                  "enum": ["input", "augment", "review", "handoff"]
+                },
+                "role": {"type": "string"}
+              }
+            }
+          },
+          "journeys": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "journey_id",
+                "pack",
+                "start_state",
+                "end_state",
+                "scope",
+                "tagline",
+                "contract"
+              ],
+              "properties": {
+                "journey_id": {"type": "string"},
+                "pack": {"type": "string"},
+                "start_state": {
+                  "type": "string",
+                  "enum": ["read-only", "proposed-write", "confirmed-write"]
+                },
+                "end_state": {
+                  "type": "string",
+                  "enum": ["read-only", "proposed-write", "confirmed-write"]
+                },
+                "scope": {"type": "string", "enum": ["repo", "user"]},
+                "tagline": {"type": "string"},
+                "contract": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["useItWhen", "youProvide", "youReceive", "yourDecisions"],
+                  "properties": {
+                    "useItWhen": {"type": "string"},
+                    "youProvide": {"type": "string"},
+                    "youReceive": {"type": "string"},
+                    "yourDecisions": {"type": "array", "items": {"type": "string"}}
+                  }
+                }
+              }
+            }
+          },
+          "effects": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind", "description"],
+              "properties": {
+                "kind": {
+                  "type": "string",
+                  "enum": [
+                    "file-write",
+                    "git-push",
+                    "network-call",
+                    "shell-exec",
+                    "credential-read"
+                  ]
+                },
+                "description": {"type": "string"}
+              }
+            }
+          },
+          "content": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "skills": {"type": "array", "items": {"type": "string"}},
+              "agents": {"type": "array", "items": {"type": "string"}},
+              "commands": {"type": "array", "items": {"type": "string"}},
+              "scripts": {"type": "array", "items": {"type": "string"}},
+              "hooks": {"type": "array", "items": {"type": "string"}},
+              "seeds": {"type": "array", "items": {"type": "string"}},
+              "shared-libs": {"type": "array", "items": {"type": "string"}},
+              "user-libs": {"type": "array", "items": {"type": "string"}}
+            }
+          },
+          "execution": {"type": "array", "items": {"type": "string"}},
+          "documentation": {"type": "string"},
+          "digest": {"type": "string", "pattern": "^[a-f0-9]{64}$"}
+        }
+      }
+    },
+    "profiles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "scope"],
+        "properties": {
+          "name": {"type": "string"},
+          "scope": {"type": "string", "enum": ["user", "repo"]},
+          "description": {"type": "string"},
+          "packs": {"type": "array", "items": {"type": "string"}}
+        }
+      }
+    }
+  }
+}

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

@@ -13,6 +13,33 @@ Machine contracts in `contracts/` are normative. These guides explain how to use
 Each section below names the authoritative contract and points to the guide that
 explains it. When a guide and its contract disagree, the contract is right.
 
+## Guide asides and quotations
+
+Use a Starlight aside when a passage does work beyond the surrounding narrative.
+Choose the type by what the reader needs to do with it:
+
+| Type | Use it for |
+| --- | --- |
+| `note` | Scope, orientation, or background the reader must notice |
+| `tip` | An optional technique that improves the result or route |
+| `caution` | A pitfall, limitation, or recovery step with reversible consequences |
+| `danger` | A risk of severe or irreversible harm |
+
+Use only those four types. Keep the default visible title unless a specific title
+helps the reader act. Put the complete guidance inside the directive:
+
+```md
+:::caution
+Confirm the generated paths before replacing an existing projection.
+:::
+```
+
+A blockquote has a different job: it preserves someone else's words or exact text
+the reader must recognize, such as a prompt, transcript, sample response, or rubric
+wording. Leave those passages as `>` blockquotes. Do not turn prose into a quotation
+just to make it visually prominent, and do not turn genuine quoted wording into an
+aside.
+
 ---
 
 ## 1. Catalogue manifest
@@ -426,5 +453,112 @@ contracts used for validation by this agentbundle version.
 
 ## Journey format
 
-> **Not yet available.** Wave 4 of the catalogue-contracts initiative will define the
-> journey format and its contract. This section will be filled in when that wave ships.
+A `JOURNEY.md` describes the outcome a pack helps someone reach. Put it beside
+`pack.toml` at `packs/<pack-name>/JOURNEY.md`. The file is optional: catalogues and
+packs created before this convention remain valid, and their generated index contains
+an empty `journeys` array.
+
+The YAML frontmatter is the machine-readable contract. The Markdown body is for
+readers; the index command does not extract structured data from it.
+
+### Required frontmatter
+
+```yaml
+---
+journey_id: catalogue-authoring
+pack: example-pack
+start_state: read-only
+end_state: confirmed-write
+scope: repo
+tagline: Build a catalogue pack that passes its published contracts.
+contract:
+  useItWhen: You need to add or revise a catalogue pack.
+  youProvide: The intended outcome, scope, and pack contents.
+  youReceive: A validated pack with clear author and adopter documentation.
+  yourDecisions:
+    - Which adapters and installation scopes the pack supports.
+---
+```
+
+Use these fields:
+
+- `journey_id`: a string that is unique within the catalogue.
+- `pack`: the exact pack name from `pack.toml`.
+- `start_state` and `end_state`: one of `read-only`, `proposed-write`, or
+  `confirmed-write`.
+- `scope`: `repo` or `user`.
+- `tagline`: a plain-language summary of at most 120 characters.
+- `contract`: a closed object. `useItWhen`, `youProvide`, and `youReceive` are
+  strings; `yourDecisions` is an array of strings.
+
+Malformed YAML, a missing required field, or a field with the wrong type stops index
+generation before any output is replaced.
+
+### Optional frontmatter
+
+The following fields add richer discovery information without changing the required
+contract:
+
+- `prerequisitePacks`: pack-name strings.
+- `whatChanges`: a reader-facing description.
+- `skills`: objects with `name`, `description`, and `humanTouches`.
+- `humanGates`: gate objects with `id`, `label`, `trigger`, `duration`,
+  `whatToCheck`, `whatGoodLooksLike`, `whatBadLooksLike`, and `consequence`;
+  `globalGate` is optional.
+- `typicalSession`: an object with `agentTurns`, `humanTouches`, and
+  `wallClockMinutes`.
+- `docsUrl` and `packUrl`: documentation links.
+- `relatedJourneys`: other journey identifiers.
+- `effects`: external effects declared by the author.
+
+Each `effects` entry is a closed object with string fields `kind` and `description`:
+
+```yaml
+effects:
+  - kind: file-write
+    description: Writes generated files after the user confirms the destination.
+```
+
+Effects describe externally observable outcomes such as writing files, using a
+network service, or publishing an artifact. Do not infer them from pack structure,
+and do not list internal computation as an effect.
+
+### Reader-facing body
+
+The first body element after frontmatter must be an **Arrival trigger** quick-reference
+table that maps activation phrases to outcomes. Follow it with these sections:
+
+1. `Orient`: explain how the user establishes the starting context for a session.
+2. `Primary workflow`: use numbered steps. Every step names what the user says or does,
+   what the agent produces, any human decision required, and the resulting state.
+3. `Persist and collaborate`: explain how state is carried between sessions or handed
+   off; a brief statement is enough when the pack has no multi-session state.
+4. `Next steps`: suggest follow-on journeys named by `relatedJourneys` frontmatter.
+
+Explain the outcome and choices in product language. Avoid repository-maintainer
+commands, publication machinery, or internal decision records; adopters should not
+need the catalogue's own development environment to understand a journey.
+
+The generated journey data conforms to the machine contract at
+`contracts/catalogue-index.schema.json`.
+
+### Generate the neutral index
+
+Run this from a catalogue checkout:
+
+```console
+agentbundle catalogue index . --dry-run
+agentbundle catalogue index . --output catalogue-index.json
+```
+
+The dry run parses every present `JOURNEY.md`, builds the index in memory, validates it,
+and writes nothing. The second command publishes the validated JSON atomically. Add
+`--format json` when another tool needs the command result as one JSON document.
+
+### Migrating an existing pack
+
+You do not need to add placeholder journeys to old packs. Add `JOURNEY.md` when the pack
+has a real end-to-end outcome to describe, then start with the required frontmatter and
+the arrival table and body sections above. Keep `pack` equal to the manifest name and
+choose states from the documented enums. Verify the complete catalogue with a dry run
+before publishing its index.

{agentbundle-0.35.2 → agentbundle-0.38.1}/agentbundle/_data/catalogue-scaffold/manifest.json

@@ -1,6 +1,6 @@
 {
   "files": {
-    "guides/_shared/reference/catalogue-authoring-standards.md": "3217e6bfcc15dc116d40e1b327b6bf19b66212c7e13553e42966f9982b3c3487",
+    "guides/_shared/reference/catalogue-authoring-standards.md": "d7eb37f3c97179cd30959089e6a26ac76a6c33f9b9b64133a11d967915a4c511",
     "guides/_shared/reference/catalogue-ci-contract.md": "fae793ab47989b6dd3c731afcb0b4cda21c7d08bbe7fa40fca6d3abb3d158141",
     "packs/AGENTS.md": "9bfeda4069826e518a4f4fdae45bd40f4393c1c5aaf146149d3eb4aece30be83",
     "packs/README.md": "d2de5f9556f4c8e521103474bde74636e02cc805f9bf5312a3a61a1f3eb45d8f",
@@ -9,7 +9,7 @@
     "packs/_example/.claude-plugin/plugin.json": "7f94084a56260eed225ec47ac82042fe9029c594557cca760a459885d03ccc26",
     "packs/_example/README.md": "ef130c9c1f97a75a07cc59fc55fc5b3bf71846dd2f06c3cddf5a1154023b6ef6",
     "packs/_example/pack.toml": "f19a0be9fca99a6a0e3ce2d5cd188bf98000f0a4f186954fb42a0c99c6859701",
-    "profiles/AGENTS.md": "8950438d9e0f57c13613104c88c90b598b53196c91bfdced6d63e4e01b5e9254",
+    "profiles/AGENTS.md": "794e7f8bdccc0479cf1ac45f864e1cb829ab739b3cdd15c66baad7ee1c894329",
     "profiles/README.md": "a0b0268edc57fc575f7fea08f3363ba7da9f6e67dc4a0a6f8bd38c9668c97922",
     "profiles/_example/README.md": "164494df049ddce3e57cb44ed604cb3d39be0a6ec2072e609ea3fa4bbfc74c72",
     "profiles/_example/profile.toml": "68af18cf50fa0327a9776b029c92bb1cf82710c649691b3ac889eb8537b8eac7",

{agentbundle-0.35.2 → agentbundle-0.38.1}/agentbundle/_data/catalogue-scaffold/profiles/AGENTS.md

@@ -14,6 +14,10 @@ The profile **id** is the filename stem. It must match `^[a-z0-9][a-z0-9-]*$`.
 
 ## Current schema fields
 
+The machine source of truth for profile TOML format is
+[`contracts/profile.schema.json`](../contracts/profile.schema.json). The table
+below is a reading aid; where the two disagree, the schema wins.
+
 | Field | Required | Type | Description |
 |-------|----------|------|-------------|
 | `scope` | yes | `"repo"` or `"user"` | Installation scope |