Production composition catalog¶

catalog.json is the closed inventory of production component and recipe authorities available from this composition revision.

Every component ID resolves to components/<component-id>/component.json; every recipe ID resolves to recipes/<recipe-id>.json. Catalog arrays are unique and lexically ordered, and validation requires exact agreement with the physical authority directories/files.

Consumer selection guide¶

Choose the recipe from the artifact you are building, not from the language, framework, rendering strategy, or deployment platform. For browser-facing products, use Choose Website or Web application before selecting optional capabilities.

Website versus Web application is a product-identity choice. Static generation, server rendering, client rendering, CDN hosting, and the presence of a runtime do not select the recipe. Documentation, publishing, institutional information, and other document-navigation products use website; task/state/action-oriented browser products use webapp.

For a concrete zero-to-one Website path, follow the Website product walkthrough. It keeps Website contracts, browser proof, and product evidence separate from Webapp-private surface/state semantics.

Select optional application capabilities according to externally visible behavior. Include the capability you need directly; the Composer resolves its dependencies transitively.

A browser-facing artifact does not imply capability.runtime, capability.web-interface, capability.pwa, or capability.webmcp. A statically generated Website can use the website recipe with no optional components. A CDN-hosted stateful SPA can use the webapp recipe with no runtime component. Selecting capability.webmcp does not imply MCP, MCP Apps, runtime, service, or capability.web-interface. Add runtime-bound, PWA, or WebMCP capabilities only when the product actually exposes those behaviors.

Lifecycle components are selected according to the product workflow. The skill recipe exposes each lifecycle level independently. The website and webapp recipes already include contract evolution and implementation evidence in their baselines, and expose lifecycle.release-bundle as the one top-level release choice. Choose the highest-level lifecycle behavior exposed by the recipe; prerequisites are resolved automatically:

Repository topology selection¶

Select repository topology when the repository requires an explicit multi-branch or projected structure. Its absence selects no explicit repository topology; it says nothing about local checkout or worktree layout:

Workspace / local-checkout selection¶

Select a workspace component when a repository declares how its local checkout is materialized. This is independent of repository topology; no workspace selection implies no declared local-checkout topology, not a default filesystem layout.

A minimal Website uses an empty include list and receives foundation.web, Website contracts, implementation-evidence/contract-evolution support, and no PWA/runtime/release materials:

{
  "schema_version": 1,
  "recipe": "website",
  "components": {"include": [], "exclude": []},
  "parameters": {}
}

A minimal Web application likewise uses an empty include list, but receives Webapp-private application routes, surfaces, and UI states in addition to the shared Web foundation:

{
  "schema_version": 1,
  "recipe": "webapp",
  "components": {"include": [], "exclude": []},
  "parameters": {}
}

A PWA Website selects PWA explicitly without changing artifact identity:

{
  "schema_version": 1,
  "recipe": "website",
  "components": {
    "include": ["capability.pwa"],
    "exclude": []
  },
  "parameters": {}
}

A Webapp that uses the complete Composition release lifecycle selects only the top-level release component; release readiness is established later by the resulting evidence and gates, not by component selection itself:

{
  "schema_version": 1,
  "recipe": "webapp",
  "components": {
    "include": ["lifecycle.release-bundle"],
    "exclude": []
  },
  "parameters": {}
}

A runtime-backed Website or Webapp that does not use the Composition release lifecycle can instead select runtime independently. For example:

{
  "schema_version": 1,
  "recipe": "website",
  "components": {
    "include": ["capability.runtime"],
    "exclude": []
  },
  "parameters": {}
}

A Skill that exposes an MCP Apps UI and uses the complete release workflow can request only the two top-level choices; the resolver adds their prerequisites:

{
  "schema_version": 1,
  "recipe": "skill",
  "components": {
    "include": ["capability.mcp-apps", "lifecycle.release-bundle"],
    "exclude": []
  },
  "parameters": {}
}

Upgrading Webapp v3 to v4¶

artifact.webapp-core v4 changes the artifact dependency closure, so an existing managed Webapp at v3 crosses an explicit component-version compatibility boundary and must use upgrade, not ordinary update.

If the repository should keep the complete release lifecycle that v3 selected transitively, the v4 upgrade configuration must explicitly include lifecycle.release-bundle. If release execution/evidence/bundle behavior is not needed, omit it and review the upgrade plan before apply.

The v3 release contract files were seed material, so an upgrade that deselects the release lifecycle preserves their consumer-owned bytes rather than deleting them. After apply, any preserved contracts/release-execution.json, contracts/release-evidence.json, or contracts/release-bundle.json is no longer registered by the v4 baseline. The contract registry is intentionally closed, so validation fails until the consumer either archives those files outside contracts/ (for example under release-history/) or deletes them after deciding the historical bytes are no longer needed. This cleanup is consumer-owned: perform it after the upgrade apply, then rerun validate.

Deselected lifecycle files do not select validators merely because similarly named files remain in the repository; the resolved component set in .template-composition/lock.json is the selection authority. The cleanup requirement above comes from the closed contract-document inventory, not from release-validator dispatch.

Use plan before apply to inspect the exact resolved component closure and materialized file actions. The recipe descriptors remain the machine-readable source of truth for which direct selections are permitted.

Closure rules¶

Production catalog validation establishes:

• descriptor/recipe/schema validity;
• exact component source-file declaration;
• dependency/conflict target existence and dependency acyclicity;
• generic capability/lifecycle/topology/workspace independence from artifact-specific authorities;
• recipe reference validity and disjoint required/default/optional selections;
• global uniqueness of registered contract IDs, document paths, and schema paths;
• component ownership of every registered contract document/schema/migration;
• a unique generated owner for contracts/manifest.json;
• deterministic manifest rendering from resolved contract_registrations;
• every resolvable production component owns at least one materialized file, because the composition lock requires every resolved component to have a file-ownership witness;
• portable single-owner material destinations; and
• successful materialized validation for production Skill, Website, and Webapp compositions.

The catalog is source authority, not consumer material and not an execution-hook registry.

The composer validates this closed source graph, resolves a recipe plus consumer configuration against one exact clean Git revision, and writes the resulting component/file closure to .template-composition/lock.json after successful initial materialization. Generated materials are dispatched only through allowlisted declarative generator IDs.

For an unmanaged target, initial composition refuses a pre-existing composition lock rather than inferring a managed-state transition. Existing managed repositories instead use explicit operations: update preserves the normalized intent recorded by lock schema v2 while advancing to a descendant Composition source revision, and upgrade accepts an explicit new configuration for changes such as recipe, component selection, parameters, or component versions. Neither operation is a general-purpose merge engine: locally modified managed/generated material and owner/ownership-mode transitions fail closed rather than being overwritten or inferred.

Component roles and direct selection¶

Recipes select one artifact and expose optional capability, lifecycle, topology, or workspace components. Components with the foundation role are dependencies of artifact components: they are resolved automatically, are not listed as recipe options, and are not direct consumer include targets. Repository topology and workspace selection are independent axes, each with at most one selected component. See Composition concepts for the six-role mental model and the provider glossary for canonical terminology.