Pack manifest

A pack is the unit Recued installs. Its manifest names the recipes and capabilities that arrive together, pins every referenced version, and carries the disclosures shown before installation. Installing a pack copies those definitions to the user's server; it does not give the publisher ongoing control of the install.

Use manifest_version: 2 for new packs. Version 1 remains valid for older, recipe-only bundles.

#Minimal app pack

{
  "manifest_version": 2,
  "artifact_type": "pack",
  "pack_kind": "app_pack",
  "service_kind": "workflow",
  "slug": "sales-review",
  "publisher": "your-handle",
  "name": "Sales Review",
  "description": "Reads CRM opportunities and prepares a weekly review for the owner.",
  "version": 1,
  "contents": [
    {
      "type": "ingredient",
      "slug": "crm-opportunity-reader",
      "version": 2,
      "role": "operation_wrapper"
    },
    {
      "type": "recipe",
      "slug": "weekly-sales-review",
      "version": 1,
      "visible": true
    }
  ],
  "requires": ["install_bulk_pack"],
  "tags": ["pack:sales-review", "crm", "weekly-review"]
}

The example pins one ingredient and one recipe. It grants neither one by itself: the install screen still asks the owner which connection, access tier, and audience the pack may use.

#Envelope fields

The pack version is independent of the versions inside it. Changing a recipe from version 2 to version 3 therefore requires both a new recipe pin and a new pack version.

#Service kinds

service_kind helps Discover and the install review explain what is arriving. It does not change how an operation executes.

#Version 1: recipe-only packs

Version 1 requires a non-empty recipes array and supports at most 50 recipe entries.

{
  "manifest_version": 1,
  "slug": "personal-review",
  "publisher": "your-handle",
  "name": "Personal Review",
  "description": "Installs the weekly review and its two quiet data producers.",
  "version": 1,
  "recipes": [
    { "slug": "collect-review-signals", "version": 1 },
    { "slug": "refresh-review-rollup", "version": 1 },
    { "slug": "weekly-review", "version": 2 }
  ],
  "requires": ["install_bulk_pack"],
  "tags": ["pack:personal-review", "weekly-review"]
}

Recipe order is preserved during installation. Keeping ingestion and producer recipes before their downstream consumers also makes the bundle easier to review. Version 1 ignores contents and dependencies with a warning, so move to version 2 before using either field.

#Version 2: typed contents

Version 2 accepts up to 100 entries in contents. It needs at least one entry in contents or the compatibility recipes array; a pure capability pack does not need to contain a recipe.

An ingredient entry has exactly one of these forms:

{ "type": "ingredient", "slug": "mail-reader", "version": 2, "role": "operation_wrapper" }

{ "type": "ingredient", "ingredient_id": "recued-core/mail", "ingredient_version": 2 }

The optional role on the slug form is entity_schema, operation_wrapper, or producer. Do not combine the two addressing forms in one entry.

A recipe may appear in both contents and the version-2 recipes compatibility array. Recued de-duplicates exact slug and version pairs; the contents entry wins so its visible setting is retained. Prefer one source of truth and put new version-2 recipe pins in contents.

#By-value compositions

Most vendor capability packs carry one composition entry. A composition contains flat ingredients and operations tables, plus optional recipe templates, default grants, work-entity Sources, and embedded recipes. It is validated and decomposed into the same installed ingredient and operation records as separately published artifacts.

Each operation carries its risk, approval and idempotency posture, its argument list with per-argument required and target flags, and an execution binding whose shape depends on the surface — an HTTP method and path template, a GraphQL document, an argument vector for a local command.

The Pack editor is the path to start on. It derives the bindings from the API description or command you point it at, shows the resulting risk and data review, and refuses combinations the validator would reject later. Most authors need nothing else.

If you are generating a pack rather than filling in a form — from an API description, a script, or your own tooling — the tables are specified in Composition, along with what publishing checks and what it deliberately does not.

The pack parser checks the composition discriminant; the authoring validator then checks the composition itself. A manifest passing the envelope parser is therefore not proof that a composition is publishable. See the ingredient manifest for the installed operation and catalog fields produced by decomposition.

#Dependencies

Version 2 can declare prerequisite packs or ingredients. min_version is optional but, when present, must be a positive integer.

"dependencies": [
  { "type": "pack", "slug": "email-outbox-pack", "min_version": 3 },
  { "type": "ingredient", "slug": "contact-search", "min_version": 2 },
  { "type": "ingredient", "ingredient_id": "recued-core/calendar" }
]

An ingredient dependency uses either slug or ingredient_id, never both. The envelope validator checks only this shape. During installation, pack dependencies are walked transitively; missing packs, version mismatches, and cycles fail preflight. An ingredient dependency is a prerequisite declaration, not a substitute for including or resolving the ingredient through contents or a composition.

#Install disclosure and authority

The manifest describes what the install flow must review. It does not bypass the review.

• requires must contain install_bulk_pack. Requirements from constituent recipes are added to the disclosure rather than hidden by the pack.
• Operation risk, approval posture, and editable arguments come from the referenced ingredients or composition. The owner chooses an access tier and audience at install time.
• webhook_requirements may request logical slots backed only by registered webhook profiles. Authors cannot put verifier secrets or arbitrary ingress URLs in this field.
• mcp_body_visibility_grants is a closed allow-list for unusually sensitive body-content access. An unknown value fails validation.

Several fields are reserved for Recued's own release and enrollment plumbing. Third-party packs cannot set pre_install: true or declare non-empty connection_requirements; those capabilities would otherwise auto-install a pack or author a credential-enrollment descriptor. launch_flag and post_substrate_canary are first-party rollout metadata, not general feature flags for pack authors.

transactional_offer is also specialized. It may describe one six-stage paid workflow only on a version-2 app_pack with service_kind: "workflow". The descriptor is marketplace presentation metadata; price, payment proof, customer access, and fulfillment authority live elsewhere. See Selling access.

#Validation checklist

Before submitting a pack, verify all of the following:

1. Every slug is lowercase and URL-safe, and every version is a positive integer.
2. Every recipe and ingredient pin resolves to the intended publisher and version.
3. requires includes install_bulk_pack, and the install preview names every additional permission.
4. The description says what outcome the pack produces, which systems it touches, and whether any producer runs quietly in the background.
5. A version-2 ingredient uses one addressing form; a dependency uses one dependency form.
6. A by-value composition passes its own authoring and decomposition checks.
7. The install preview shows the expected connections, operations, approvals, body-content access, webhook slots, and audience choices.
8. Exercise install and uninstall on a clean server, then inspect recipes, grants, dependencies, and inventory for anything deferred or left behind.

Schema validation is only the first gate. Publication validates the envelope and every by-value composition, but it does not prove that each referenced artifact will resolve for an installer. Installation resolves pinned recipes and preflights pack dependencies and permissions. Constituent recipe writes roll back together on failure; composition and inventory provisioning have their own outcomes, so a successful envelope parse is not proof of a complete install.

#Related

• Recipes and packs — how users discover and install the manifest.
• Authoring recipes — the recipe definitions a pack can pin.
• Authoring ingredient packs — the Kitchen workflow for by-value compositions and local install.
• Ingredient manifest — the operations and catalog surfaces a pack can include.
• Publishing — validation, review, versions, and unpublishing.