13 APM Handbook as Consumer

Status

Accepted

Context

The calab-handbook serves as the staff-facing marketplace portal for APM packages and agent primitives. Two approaches were considered for populating marketplace content:

1. Handbook as source — maintainers manually author marketplace pages in the handbook alongside editing apm-registry.
2. Handbook as consumer — apm-registry CI generates catalog artifacts (portal-data.json, search index) on every GA release, and the handbook ingests those artifacts to build marketplace pages automatically.

Manual authoring creates duplication risk: metadata would need to be kept in sync between the registry source and the handbook. Any divergence produces inconsistent staff-facing content.

Generated catalog data keeps the registry as the single source of truth. The handbook becomes a rendering and presentation layer, not a second data store.

Decision

calab-handbook is a consumer of catalog data generated by apm-registry CI. It does not own registry source data.

On each GA release, apm-registry CI publishes:

• portal-data.json — structured package and primitive metadata for marketplace page generation
• a search index entry for each released package and primitive

The handbook ingests these artifacts at build time to generate staff marketplace pages. Handbook content files for the marketplace are generated or updated from the catalog data, not hand-authored.

Generated marketplace updates are delivered by the calab-sync-agent-primitives-bot GitHub App. The app reads the calab-ai/apm-registry release catalog artifact as the source of truth, opens PRs against calab-ai/calab-handbook for content/03 Products/Agent Primitives/marketplace/**, and never pushes directly to main. Normal handbook CI gates apply to those PRs before merge.

Consequences

• apm-registry is the single source of truth for package and primitive metadata.
• Marketplace pages in the handbook are always consistent with the latest released registry state.
• The handbook build must have access to the released portal-data.json artifact; the build pipeline must fetch it from the registry release artifacts before rendering.
• Manual edits to generated handbook marketplace pages must not be committed; changes to metadata must be made in apm-registry and propagated via a new release.
• The handbook retains editorial control over non-generated content: architecture documentation, ADRs, guides, and governance pages.
• .github-private remains a parallel distribution target for generated org-level agent files; the handbook sync is a separate PR-based catalog publishing path.