agentbundle 0.37.2__tar.gz → 0.38.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.37.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,30 +34,70 @@ python -m pip install agentbundle
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
 
-## What's new in 0.37.2
+## What's new in 0.38.1
 
-`agentbundle catalogue verify` now 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
+`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.
+
+## What's new in 0.38.0
+
+`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 now use the same npm-compatible grammar in verify, lint, and
+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` now use normal
-semver compatibility (`^0.2` does not include `0.3.x`).
+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 guide callout contract. The bundled
-authoring reference distinguishes exact quoted wording, which stays a
-blockquote, from guidance that should render as a Starlight `note`, `tip`,
-`caution`, or `danger` aside. Existing catalogues remain unchanged until their
-scaffolded authoring reference is refreshed.
+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
+```
 
 ## Contract discovery
 
-The bundled public contract inventory includes the strict
+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.
 
@@ -160,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.37.2 → agentbundle-0.38.1}/README-pypi.md

@@ -14,30 +14,70 @@ python -m pip install agentbundle
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
 
-## What's new in 0.37.2
+## What's new in 0.38.1
 
-`agentbundle catalogue verify` now 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
+`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.
+
+## What's new in 0.38.0
+
+`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 now use the same npm-compatible grammar in verify, lint, and
+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` now use normal
-semver compatibility (`^0.2` does not include `0.3.x`).
+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 guide callout contract. The bundled
-authoring reference distinguishes exact quoted wording, which stays a
-blockquote, from guidance that should render as a Starlight `note`, `tip`,
-`caution`, or `danger` aside. Existing catalogues remain unchanged until their
-scaffolded authoring reference is refreshed.
+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
+```
 
 ## Contract discovery
 
-The bundled public contract inventory includes the strict
+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.
 
@@ -140,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.37.2 → agentbundle-0.38.1}/agentbundle/_data/catalogue-scaffold/guides/_shared/reference/catalogue-authoring-standards.md

@@ -453,7 +453,112 @@ contracts used for validation by this agentbundle version.
 
 ## Journey format
 
-:::caution
-**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.37.2 → agentbundle-0.38.1}/agentbundle/_data/catalogue-scaffold/manifest.json

@@ -1,6 +1,6 @@
 {
   "files": {
-    "guides/_shared/reference/catalogue-authoring-standards.md": "42d4066e9a0226337268b6ea15fdf983ba0dd5f45bfde861557c2565ea354738",
+    "guides/_shared/reference/catalogue-authoring-standards.md": "d7eb37f3c97179cd30959089e6a26ac76a6c33f9b9b64133a11d967915a4c511",
     "guides/_shared/reference/catalogue-ci-contract.md": "fae793ab47989b6dd3c731afcb0b4cda21c7d08bbe7fa40fca6d3abb3d158141",
     "packs/AGENTS.md": "9bfeda4069826e518a4f4fdae45bd40f4393c1c5aaf146149d3eb4aece30be83",
     "packs/README.md": "d2de5f9556f4c8e521103474bde74636e02cc805f9bf5312a3a61a1f3eb45d8f",

{agentbundle-0.37.2 → agentbundle-0.38.1}/agentbundle/_data/public-contracts.txt

@@ -1,5 +1,6 @@
 adapter.schema.json
 adapter.toml
+catalogue-index.schema.json
 catalogue.schema.json
 guide.schema.json
 knowledge-captured-observation.schema.json

{agentbundle-0.37.2 → agentbundle-0.38.1}/agentbundle/_data/skill.schema.json

@@ -24,7 +24,14 @@
     },
     "compatibility": {
       "type": "object",
-      "description": "Open object — adapter-compatibility constraints declared by the skill."
+      "description": "Adapter-compatibility constraints declared by the skill. Values are bounded to the show JSON discovery-compatible scalar/list subset.",
+      "maxProperties": 256,
+      "propertyNames": {
+        "maxLength": 1024
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/compatibilityValue"
+      }
     },
     "metadata": {
       "type": "object",
@@ -35,5 +42,37 @@
       "items": {"type": "string"},
       "description": "Explicit tool allowlist for this skill."
     }
+  },
+  "$defs": {
+    "compatibilityScalar": {
+      "oneOf": [
+        {
+          "type": "string",
+          "maxLength": 1024
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        }
+      ]
+    },
+    "compatibilityValue": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/compatibilityScalar"
+        },
+        {
+          "type": "array",
+          "maxItems": 256,
+          "items": {
+            "$ref": "#/$defs/compatibilityScalar"
+          }
+        }
+      ]
+    }
   }
 }