> ## Documentation Index > Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt > Use this file to discover all available pages before exploring further. # Template Manifest Reference > Every attribute of an Agent Template manifest — authored, frozen, and served — with types, defaults, constraints, and the publish lints that guard them This is the complete attribute reference for Agent Template manifests. For the concepts and lifecycle, read [Agent Templates](/marketplace/agent-templates); for the authoring journey, [Publishing Templates](/marketplace/publishing-templates); for the installer's experience, [Deploying Templates](/marketplace/deploying-templates). ## Where the manifest lives A template's manifest exists in three forms. Knowing which form an attribute belongs to tells you where you set it, where it's stored, and where an installer reads it: 1. **The authored sections** — what you write. The `template:` section of your project's `lua.skill.yaml` carries the six authored sections (`connections`, `personaTemplate`, `triggerPresets`, `paramsMeta`, `onInstall`, `onUninstall`). The publish request can additionally carry sections that have no yaml home yet: the env contract (declared with `--env-contract`), connection-event triggers (`declaredTriggers`), `outcomes`, `channels`, `features`, and marketplace-skill composition refs. The publish request also carries three version-level fields: `sourceAgentVersion` (which promoted agent version to freeze; defaults to the active one), `changelog`, and `referenceEvalRunId` (the eval run satisfying the publish gate, when an eval set exists). 2. **The frozen published version** — what publish produces. An immutable, integer-numbered version that combines your promoted agent's primitives (skills, webhooks, jobs, processors, triggers, model — frozen **by value**) with your authored sections (validated, normalized, and stored alongside), plus derived integrity digests: `contentHash`, and the `codeHash` / `consentSurfaceHash` pair that powers update diffing and re-consent (creator-side version reads only — the two are never in the public manifest). 3. **The served manifest** — what installers read. `GET /marketplace/templates/:id/versions/:v/manifest` serves a **safe projection** of the frozen version: display metadata and requirements only, never source code, trigger instructions, or values. Fields are lifted by an explicit allow-list — anything not deliberately made public never serves. The serving layer also *enriches* it at read time: platform display names and auth modes from the live integration catalog, scope display copy, next run times, the per-caller `reconciliation` block, and the org `policy` block. | Attribute group | Authored by you | Frozen at publish | In the served manifest | | ---------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------- | | Metadata (`name`, `displayName`, …) | at `create` / `patch` | header, not per-version | yes | | `agent.model`, `agent.modelSettings` | no — frozen from the source agent | yes | `model` only | | `personaTemplate` | yes (yaml) | yes (normalized) | yes — the template text is part of the consent surface | | `skills[]` (and webhooks, jobs, processors, triggers) | no — frozen from the source agent | yes, by value | display metadata only (skills; schedule/webhook triggers) | | `connections[]` | yes (yaml) | yes | yes, platform entries enriched | | `triggerPresets` | yes (yaml) | yes (normalized over the full trigger key-space) | merged into `triggers[]` | | `declaredTriggers[]` | yes (publish request) | yes | display fields only — `event` and `instruction` never serve | | `envContract` + `paramsMeta` | yes (`--env-contract` + yaml) | yes | merged into `params[]` | | `onInstall` / `onUninstall` | yes (yaml) | yes (normalized) | yes, verbatim — the hooks are part of the consent surface | | `channels[]`, `features[]` | yes (publish request) | yes | yes | | `outcomes` | yes (publish request) | yes | creator/version reads and outcome summaries (not the deploy-screen manifest in V1) | | `contentHash`, `installable`, `deprecated`, `reconciliation`, `policy`, `nextRuns` | never | derived | yes — served-only, see [below](#served-manifest-only-fields) | **Inheritance vs. clearing.** On the publish API, an *omitted* authored section inherits the previous version's (re-validated against the new content); an explicit empty value (`[]`, `{}`, `{ units: [] }` for `outcomes`, or `null` for `personaTemplate`) **clears** it. The CLI is stricter: when a `template:` section exists in `lua.skill.yaml`, all six yaml sections are always sent — an absent or empty subsection is an explicit clear, never "keep the previous version's". Omitting `--env-contract` inherits the previous contract. `onInstall` and `onUninstall` follow the same rule: on the publish API an omitted section inherits and an explicit `null` clears; from the CLI, deleting the section from your yaml clears it. **Keys are identity.** Every keyed entry — a skill key, connection key, trigger key, param name, persona var name, outcome unit key — is its stable identity across versions. Renaming a key means *remove + add*: installers lose their binding, toggle, or setting for the old key. Keep keys stable. *** ## metadata Template-level, not per-version: set at `lua marketplace template create`, editable later (except `name`). | Field | Type | Required | Default | Constraints | Description | | ------------------------------------- | --------------------- | -------- | --------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `name` | string | yes | — | unique per creator organization | Machine name of the template, e.g. `sales-followup`. | | `displayName` | string | yes | — | — | Catalog and deploy-screen title. | | `description` | string | no | `''` | — | Catalog card copy. | | `visibility` | `public` \| `private` | no | `private` | flipping to `public` enqueues platform review | Private templates are org-only; public templates list in the catalog once a version is approved. | | `id` | string (UUID) | derived | — | server-assigned | Opaque template id, no prefix. | | `listed` | boolean | derived | `true` | — | `false` after unlisting (soft retire). | | `latestVersion` | integer | derived | — | monotonic | Highest published version number. | | `latestApprovedVersion` | integer | derived | — | absent = no approved version | Highest *approved* version — what public installers resolve "latest" to. | | `installCount` / `activeInstallCount` | integer | derived | `0` | — | Lifetime installs / currently-installed count. | Versions are **integers** (v1, v2, v3 — not semver), monotonic per template. A rejected publish burns no version number. Catalog categories and icons are not part of the V1 manifest. ## agent | Field | Type | Required | Default | Constraints | Description | | ----------------- | ------ | -------- | ------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `model` | string | frozen | — | validated against the installer org's model catalog at install pre-flight | The model frozen from the source agent, e.g. `anthropic/claude-sonnet-4`. The only `agent` field in the served manifest. | | `modelSettings` | object | frozen | — | — | The source agent's model settings, frozen by value. Applied at install; not served in the public manifest. | | `personaTemplate` | object | no | absent | see below | The persona section — authored, not frozen from the source agent. | ### agent.personaTemplate The system prompt as a template with `{{VAR}}` slots, each declared, typed, and explained. Authored in the yaml `template:` section. | Field | Type | Required | Default | Constraints | Description | | ---------- | ------------------------------------ | -------- | ------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `template` | string \| `{ base?, voice?, text? }` | yes | — | must keep ≥ 40 literal (non-slot) characters across all branches | The prompt text. The object form matches the persona's channel-aware branches. | | `vars` | array | yes | — | exact bijection with `{{TOKEN}}`s (see below) | One declaration per `{{slot}}`. | | `editable` | boolean | yes | `false` | enforced server-side at install | When `true`, the installer may edit the resolved prompt at deploy; the edited text wins over substitution and is stored verbatim, never re-expanded. | Each entry of `vars[]`: | Field | Type | Required | Default | Constraints | Description | | ------------- | ------------------------------------------------------ | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | | `name` | string | yes | — | `[A-Za-z_][A-Za-z0-9_]*`; `persona` is reserved (case-insensitive); must not collide with any declared param name | The `{{TOKEN}}` this declares. | | `displayName` | string | yes | — | non-empty | Form label — the installer never sees a bare token. | | `description` | string | yes | — | non-empty | Help copy under the field. | | `type` | `string` \| `number` \| `boolean` \| `enum` \| `model` | yes | — | `model` holds a provider-prefixed model code; `enum` and `maxLength` are illegal on it, and a `default` must be a string | Drives the input control and value validation. | | `required` | boolean | no | `false` | a non-required var **must** carry a `default` | Whether the installer must answer. | | `default` | string \| number \| boolean | no | — | must satisfy its own `type`; for `enum`, must be a member | Pre-filled answer. | | `enum` | string\[] | when `type: enum` | — | non-empty, unique, strings; illegal on other types | The choices. | | `placeholder` | string | no | — | — | Input placeholder, e.g. `Acme Inc.`. | | `maxLength` | integer | no | `256` | strings only; 1–2000 | Length cap on the supplied value (injection floor). | **Substitution rules** (what happens to `{{vars}}` at deploy): * **Single-pass.** The template is scanned once; each declared token is replaced with the installer's answer. Substituted values are never re-scanned — a value containing `{{OTHER_VAR}}` lands as inert text, not a new slot. * **Brace-escaped.** Inside supplied values, `{{` becomes `{ {` and `}}` becomes `} }` — a value can never mint a slot or reach runtime substitution targets. * **The bijection lint.** Every `{{TOKEN}}` in any branch (`base`/`voice`/`text`) must have a `vars[]` entry, and every declared var must appear in at least one branch. Publish rejects both directions. * **Values are never stored in the manifest.** Answers land on the installed agent's persona; the manifest carries only the declarations. ```yaml theme={null} template: personaTemplate: template: | You are the sales assistant for {{COMPANY_NAME}}. Chase deals in the {{PIPELINE}} pipeline. Never discount past {{MAX_DISCOUNT}}%. editable: true vars: - name: COMPANY_NAME displayName: Your company description: Used in the agent's replies and signatures. type: string required: true placeholder: Acme Inc. - name: PIPELINE displayName: Pipeline to work description: Which sales pipeline the agent chases. type: string default: Enterprise - name: MAX_DISCOUNT displayName: Max discount % description: The agent never offers more than this. type: number default: 15 ``` ## skills\[] Skills (like webhooks, jobs, processors, and code triggers) are **frozen from your promoted agent version, by value** — you never author these entries. The served manifest lifts display metadata only; source code, tool schemas, and gating conditions never serve publicly. Webhooks and processors serve nothing in the V1 manifest at all — they're internal wiring, not an installer decision surface. Served shape per entry: | Field | Type | Required | Default | Constraints | Description | | -------------------- | ------------------------ | -------------------------- | ------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `key` | string | always | — | stable identity; rename = remove + add | The skill's name on the source agent. | | `displayName` | string | always | derived from `key` | — | The skill's title; when none was set, the key is humanized (`crm-sync` → `Crm sync`). | | `description` | string | always | `''` | — | "What this agent can do" copy on the deploy screen. | | `version` | string | always | — | — | The frozen skill version. | | `source` | `agent` \| `marketplace` | when present | `agent` | — | Provenance: frozen from the source agent, or composed from a published marketplace skill. | | `marketplaceSkillId` | string | `source: marketplace` only | — | — | The referenced marketplace skill's id. | | `versionId` | string | `source: marketplace` only | — | an immutable version-document id — never a semver, never "latest" | The exact pinned marketplace skill version. | Marketplace composition is authored on the publish request as `marketplaceSkills: [{ marketplaceSkillId, versionId }]` (max 50) — content is still frozen by value into the version; the refs record where it came from and pin the exact version. ## connections\[] Declared runtime connection requirements — "this agent needs a CRM" — authored in the yaml `template:` section. Each entry is a **capability** satisfiable by any platform in its allow-list. | Field | Type | Required | Default | Constraints | Description | | ------------- | --------------- | -------- | ------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key` | string | yes | — | non-empty, unique; stable identity | The capability key. Referenced by `boundSkills`-owning outcomes evidence (`match.connectionKey`), connection-event triggers (`connectionKey`), and the install's binding ledger. | | `capability` | string | yes | — | must equal the **primary** catalog category of every declared platform | Discovery label ("crm", "calendar", "chat"). The `platforms[]` allow-list, not this label, is what decides satisfiability. | | `required` | boolean | yes | — | — | `true`: install blocks until satisfied. `false`: offered at deploy, never blocking — primitives depending on a declined optional connection are materialized inert, fail-closed. | | `ownerType` | `user` \| `org` | no | either | — | Constrains which grant identity may satisfy the capability — declare `org` when the connection must be the organization's (finance systems), never someone's personal key. | | `displayName` | string | yes | — | non-empty | The connect chip label ("Your CRM"). | | `description` | string | yes | — | non-empty | The *why*, shown under the chip ("Used to read deals and write follow-up notes."). | | `platforms` | array | yes | — | at least one; unique `type`s | The ANY-OF allow-list — any one platform satisfies the capability. | | `boundSkills` | string\[] | no | — | every entry must be a skill key in this version | Which of the template's skills depend on this connection. Drives the portability lint and outcome attribution. | Each entry of `platforms[]`: | Field | Type | Required | Default | Constraints | Description | | ------------- | --------- | ------------------- | ------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | yes | — | must be a live integration in the catalog | Integration type, e.g. `salesforce`, `hubspot`, `slack`. | | `oauthScopes` | string\[] | for OAuth platforms | — | scope names must exist in the platform's scope-copy vocabulary | The scopes this template needs on that platform — what the installer consents to. **Currently disabled at publish** while granted-scope capture rolls out; a declaration is rejected with a message saying so. | **In the served manifest**, each platform entry is enriched from the live integration catalog at read time — the frozen declaration stores only `{type, oauthScopes}`: ```json theme={null} { "type": "salesforce", "name": "Salesforce", "authSupport": "oauth", "oauthScopes": [ { "scope": "crm_contact_read", "displayName": "Read contacts" }, { "scope": "crm_deal_write", "displayName": "Create & edit deals" } ] } ``` Raw scope tokens never reach a screen — `oauthScopes` (and `missingScopes` in reconciliation) always serve as `{scope, displayName, description?}` objects with platform-owned display copy. **Reconciliation semantics, per attribute.** At deploy, the platform reconciles each capability against the connections the installer already holds (personal + the target org's shared ones): a connection whose `type` is in `platforms[]` and whose granted scopes cover the declared `oauthScopes` → `satisfied`, bound without asking; several matches → `multiple-matches`, the installer picks (never auto-picked); a match lacking scopes → `insufficient-scope` with the exact missing scopes; a pre-scope-capture row whose live scope query failed → `verify-access` (informational, resolved at pre-flight); no match → `unmet-required` (blocks) or `unmet-optional` (offered). `ownerType` filters which grants qualify at all. Install proceeds only when every `required` capability is satisfied — re-verified server-side, never trusted from the client. **The portability lint.** A capability may list *multiple* platforms only when its `boundSkills` reach the connection through the capability itself. A bound skill that calls platform-native tools (e.g. `salesforce_*`-prefixed calls, or a platform-typed integration helper) pins the entry: publish rejects with a migration hint — narrow `platforms[]` to that platform, or migrate the skill to capability-level access. Single-platform entries lint nothing; narrowing is the author's escape hatch. ```yaml theme={null} template: connections: - key: crm capability: crm required: true displayName: Your CRM description: Used to read deals and write follow-up notes. platforms: - type: salesforce - type: hubspot boundSkills: [crm-sync] - key: notify capability: chat required: false displayName: Notifications channel description: "Optional: where follow-up alerts get posted." platforms: - type: slack ``` ## triggerPresets and the served triggers\[] Schedules and code triggers are frozen from the source agent; **triggerPresets** is your authored layer over them — recommended defaults, installer-facing copy, and which schedule fields the installer may edit. It's a map keyed by trigger key, covering the union of the version's job, webhook, code-trigger, and connection-event keys. Keys you don't author get defaults at publish: `{ enabled: true }` for job/webhook/code-trigger keys, always-off for connection-event keys. | Field | Type | Required | Default | Constraints | Description | | ---------------- | ------- | -------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | yes | `true` (schedule/webhook) / `false` (connection-event, immutable) | connection-event keys may never author `true` | A **recommended default**, pre-checked in the configure step — confirmed at deploy, never silently applied. Nothing arms without the installer's explicit confirmation. | | `displayName` | string | no | the primitive's name, else humanized key | — | Deploy-screen title for the automation. | | `description` | string | no | the primitive's description | — | What enabling *does* ("Looks for deals needing a follow-up and drafts one."). | | `editableParams` | array | no | — | not allowed on connection-event keys; timezone auto-declared on every cron job | Which schedule fields the installer may adjust. | Each entry of `editableParams[]`: | Field | Type | Required | Default | Constraints | Description | | ------- | ------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `path` | `preset.seconds` \| `preset.timezone` | yes | — | closed allow-list; `preset.seconds` only on interval presets, `preset.timezone` only on cron; one declaration per path | The schedule field this exposes. Cron *expressions* are never editable — no client-side cron math, ever. | | `label` | string | yes | — | non-empty | Form label ("Check every") — a raw path is never rendered. | | `help` | string | no | — | — | Copy under the field. | | `unit` | string | no | — | display only | e.g. `minutes`. | | `min` | number | no | `60` | ≥ 60 and a multiple of 60 (`preset.seconds`) | Lower bound. | | `max` | number | no | — | ≥ `min` | Upper bound. | | `step` | number | no | `60` | multiple of 60 (`preset.seconds`) | Input step. | **The whole-minutes constraint.** Interval schedules run on whole minutes only: `seconds` must be ≥ 60 and a multiple of 60, both in the frozen schedule and in any authored envelope — a fractional-minute interval would silently never fire, so publish rejects it. Frozen `once` schedules are rejected too (a frozen instant is stale by construction), and a frozen schedule must satisfy its *own* declared envelope. **The timezone override.** Cron presets carry an IANA timezone — but a frozen cron carries the *creator's* timezone, so every cron job automatically gets a `preset.timezone` editable param (label "Timezone", defaulting to the installer's profile timezone) even if you don't declare one. A Stockholm-authored 08:00 job must not run at Stockholm time for a Nairobi installer. ```yaml theme={null} template: triggerPresets: poll-crm: enabled: true displayName: Check for new deals description: Looks for deals needing a follow-up and drafts one. editableParams: - path: preset.seconds label: Check every help: How often the agent looks for new deals. unit: minutes min: 60 step: 60 ``` **The served `triggers[]`** merges the frozen schedules, your presets, and the declared connection-event triggers into one list: | Field | Type | Present | Description | | ----------------------------- | -------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key` | string | always | The trigger key. | | `type` | `schedule` \| `webhook` \| `connection-event` | always | Scheduled job, webhook-source code trigger, or connection event. | | `displayName` / `description` | string | always / when set | Authored preset copy, falling back to the primitive's name/description, then the humanized key. | | `enabled` | boolean | always | The recommended default. Connection-event entries always serve `false`. | | `preset` | `{ type: cron \| interval, expression?, seconds?, timezone? }` | schedule only | The frozen schedule. | | `connectionKey` | string | connection-event only | The capability the event arrives on. | | `editableParams` | array | when declared | Verbatim from the authored preset (plus the auto-declared timezone param). | | `nextRuns` | `{ at, timezone }[]` | schedule only | The next fire times — **computed at read time by the serving layer**, never authored, so the UI can say "runs 2:00 AM New York — 8:00 AM your time" without doing cron math. | At install, the deploy request answers this section with `triggerOverrides: { : { enabled?, params? } }` — e.g. `params: { "preset.seconds": 600, "preset.timezone": "Africa/Nairobi" }`. ## declaredTriggers\[] Connection-event triggers — "when a deal is won" — are **authored declarations** (publish request only; no yaml home in V1), since no frozen primitive can carry them. Each materializes at install as a managed trigger plus a webhook subscription on the bound connection. | Field | Type | Required | Default | Constraints | Description | | ------------------ | ----------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `key` | string | yes | — | shares the one trigger key-space (clash-checked) | Stable identity. | | `connectionKey` | string | yes | — | must be a declared `connections[]` key | Which capability's bound connection emits the event. | | `displayName` | string | yes | — | non-empty | Deploy-screen title ("When a deal is won"). | | `description` | string | yes | — | non-empty | What enabling does. | | `event.objectType` | string | yes | — | provider object vocabulary | e.g. `deal`. | | `event.event` | `created` \| `updated` \| `deleted` | yes | — | — | The change type. | | `event.filters` | object (string → string) | no | — | — | Field filters, e.g. `{ "stage": "won" }`. | | `instruction` | string | yes | — | non-empty, ≤ 2000 chars, must not interpolate event-payload fields (the fencing lint); part of the consent surface — changing it forces re-consent | The instruction prepended to the fired agent turn ("A deal was won — send a thank-you follow-up."). | **The event-support join.** Each declared `{objectType, event}` must be deliverable on **every** platform in the referenced capability's `platforms[]` — checked at publish against the live webhook-event listing, with each `filters` key limited to that event's available filters on that platform. A listing fetch failure fails the publish loudly (`could not verify event support — try again`) — never publish-unverified. Two fences apply everywhere: * **Never armed by default.** A connection-event trigger always serves (and materializes) disabled; authoring `enabled: true` in its preset is rejected. The installer must switch it on explicitly. * **`event` and `instruction` never serve publicly.** The served manifest lifts only `key`, `connectionKey`, `displayName`, `description` (as a `triggers[]` entry with `type: "connection-event"`). Event payloads are untrusted input at runtime and instruction text is consent-surface material — it's shown through consent flows, not the anonymous catalog. ## Lifecycle hooks: onInstall and onUninstall The two optional **lifecycle hooks** are symmetric: `onInstall` runs right after a successful deploy or install-onto-agent; `onUninstall` runs at the start of an uninstall, **before** any teardown — while the template's skills, connection bindings, and injected trigger URLs all still work. Both take the same shape, with **at least one** of the two fields: | Field | Type | Required | Default | Constraints | Description | | ------------- | ------ | ----------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `tool` | string | at least one of the two | — | the bare name of a tool that exists in **this version's frozen skills** — never live agent state | A tool executed **directly** (input `{}`), without an agent turn: the deterministic half of the hook. | | `instruction` | string | at least one of the two | — | 1–2000 chars after trimming; plain text — `{{var}}` tokens are rejected (nothing is substituted); part of the consent surface | One background agent turn: the conversational half. | ```yaml theme={null} template: onInstall: tool: setup_github_watch instruction: 'Report what setup_github_watch just wired, briefly.' onUninstall: tool: unwire_github_watch instruction: 'Tell the user which webhooks were removed and say goodbye.' ``` **Execution order is tool, then instruction.** The recommended split: **the tool does the work, the instruction is the conversation.** A tool run is deterministic — no model in the loop — executed as the acting user (the installer for `onInstall`, the removing user for `onUninstall`) with the same runtime context as a chat-turn tool call and a 180-second budget, and its outcome (success or failure, with a result summary) is recorded on the install. The instruction fires as one background agent turn, prefixed so the agent knows why it woke: ``` [Install: