Manifest Reference

Every component package contains two files in a warmhub/ directory:

• component.json — Component identity (id, name, version)
• manifest.json — Declarative resource definitions

Both are validated at install time. You can also validate offline with wh component validate <path>.

JSON Schema

Add the $schema field to get IDE autocomplete and inline validation:

{
  "$schema": "https://docs.warmhub.ai/schema/component-manifest.v1.json",
  "component": { ... },
  ...
}

Published schema versions are immutable — breaking changes always move to a new versioned URL (e.g. component-manifest.v2.json), so it is safe to pin the URL above.

component.json

{
  "id": "com.warmhub.MyComponent",
  "name": "my-component",
  "version": "1.0.0",
  "description": "Optional description",
  "author": "Your Name",
  "tags": ["research", "ai"]
}

Field	Type	Required	Description
id	string	Yes	Reverse-DNS identifier (e.g., com.warmhub.MyComponent); manifest metadata, not a CLI argument.
name	string	Yes	Installed component name, typically kebab-case. Must be unique within the target repo — the installer rejects an install when another component already uses the same name. This is the name CLI invocation resolves against: wh component exec <name> <method> (and the wh <name> <method> shorthand) look up the install by this value, so it is not merely a display label.
version	string	Yes	Semver version string.
description	string	No	Human-readable description.
author	string	No	Author or organization.
tags	string[]	No	Discovery tags.

The id must match the pattern: one or more lowercase domain segments, followed by one or more PascalCase segments. Examples: com.warmhub.ResearchKnowledge, io.example.MyTool.

manifest.json

Top-level structure

Every manifest needs a component object (id, name, version) plus the shapes, credentials, subscriptions, seeds, health, and teardown sections — those six may be empty arrays or objects. $schema, runtimeAccess, and cli are optional.

Earlier manifests also had an actions section. It has been removed from the manifest format: an actions key in an older manifest is ignored — install and reconcile never read it.

{
  "$schema": "https://docs.warmhub.ai/schema/component-manifest.v1.json",
  "component": {
    "id": "com.warmhub.MyComponent",
    "name": "my-component",
    "version": "1.0.0"
  },
  "shapes": [],
  "credentials": [],
  "subscriptions": [],
  "seeds": [],
  "health": {},
  "teardown": {}
}

The component section must match the corresponding fields in component.json.

runtimeAccess

Declare the WarmHub runtime scopes the component’s minted runtime token needs at execution time. This is used only for registered-component setup flows that mint tokens; local installs can still include the field for portability.

"runtimeAccess": {
  "reads": ["Paper", "ComponentConfig"],
  "writes": ["Consensus"]
}

Field	Type	Required	Description
reads	string[]	Yes	Shape names the runtime token may read.
writes	string[]	Yes	Shape names the runtime token may write.

Rules:

• Every shape must be declared in shapes[] or be a known built-in (ComponentInstall, ComponentConfig).
• A shape may appear in both reads and writes when the runtime needs read-before-write behavior, such as revising existing component-owned assertions.
• Omitting runtimeAccess is equivalent to no minted runtime token.

Provisioning modes

shapes, credentials, and subscriptions support a per-resource provisioning field:

• manifest — default. The normal manifest installer creates the resource in the target repo.
• setup — the registered component’s setup endpoint creates the resource. When minted tokens are enabled, WarmHub includes a setup token the endpoint can use for those writes.

This allows a manifest to mix installer-created and setup-created resources in one package.

Setup token scope

A minted setup token does more than authorize the initial create-time writes. Its scope also covers:

• Scoped reads on setup-owned resources: the token may read any Subscription/<name>, CredentialSet/<name>, or Shape/<name> that is declared with provisioning: "setup" in the current manifest. The token cannot read resources outside those names.

• Credential binding between setup-owned resources: the token may bind a setup-owned CredentialSet/<name> onto a setup-owned Subscription/<name>, provided the subscription’s manifest declaration lists that credential set in its credentials array. Both refs must be within the token’s setup-owned scope, and a credential set that is declared in the manifest but not listed by the target subscription’s credentials array will be rejected with an error. This lets your setup endpoint wire credentials to subscriptions during install or update without requiring any broader token.

• Update paths on those same named resources: wh component update replays registered setup against existing setup-provisioned resources. During a replay, the setup token may update a matching subscription (e.g. change its webhookUrl), set keys on a matching credential set, and reconcile a matching shape — without requiring a full teardown and recreate.

  Replay validation: a setup replay may only touch setup-owned resources that still match the current manifest. Anything that disagrees with the manifest is rejected before it persists, so write your setup endpoint to submit what the manifest declares rather than what it remembers from a previous run. Specifically:

  • Shapes must match the manifest declaration exactly — the field map and the description, if one is declared. Changing or dropping a declared description fails even with the fields untouched.

  • Subscriptions must keep the declared event type, shape, and filter criteria. Webhook URLs have their own rules:

    • The origin must match; everything after it — path, query string — may change. Origin here means scheme, host and port, so https://hooks.example.com/a and https://hooks.example.com/b?v=2 are interchangeable, while a different host, or the same host on a different port (https://hooks.example.com:8443/a), is rejected.
    • A {setup-supplied:...} placeholder accepts any concrete URL whose path fits its template.
    • fallbackWebhookUrl follows the same origin rule, and its presence must match the manifest — adding or removing a fallback is rejected even when the primary URL is untouched.

    Two things a setup-managed subscription may never do, regardless of the manifest: point at another repository as its source (sourceRepoRef), or enable allowTraceReentry. Both are rejected even when everything else matches.

  • Credential sets must keep their name and scope, and you may only set key names listed in requiredKeys.

  • Credential bindings require both resources to be declared in the manifest, with the subscription’s declaration listing that credential set in its credentials array.

In practice this means your setup endpoint can be written idempotently: on a first run it creates the subscriptions, credential sets, and shapes, and binds credentials to subscriptions; on a subsequent wh component update replay it reads the existing resources, compares them to the desired state, and reconciles in place. Each install or update run issues a fresh setup token scoped to the current manifest. What happens after a failure depends on whether WarmHub had already called you:

• Failed before the call reached you — safe to retry. Do not count on holding a usable token in the meantime: a dispatch failure revokes the tokens minted for that run, so on an update you fall back to the live tokens from the existing install, and on a first install there may be none yet. Take the token from the next run rather than caching one across attempts.
• Failed after the call may have reached you — retry is blocked rather than replayed, because your endpoint may already have acted. Recovering means reconciling your side by hand, then re-running deliberately.

The token’s scope is derived from the latest published manifest resolved for the current install or update run — not from the names that were provisioned during the original install. This means that if you rename a setup-owned resource or add a new one between releases, the replay token for wh component update is bounded to the current manifest’s setup-owned names, and the updated or newly added resources are part of the replay scope.

shapes

Shapes the component needs in the target repo. Created at install time if they don’t exist.

"shapes": [
  {
    "name": "Paper",
    "fields": { "title": "string", "url": "string", "score": "number" }
  }
]

Field	Type	Required	Description
name	string	Yes	Shape name.
fields	object	Yes	Field definitions mapping names to WarmHub type descriptors.
description	string	No	Human-readable description of the shape.
provisioning	"manifest" | "setup"	No	Which side creates the shape. Defaults to manifest.

Field types: string, number, boolean, wref (a WarmHub reference string such as Shape/name or Shape/name@v3), arrays, nested objects. See Shapes for details.

credentials

Credential sets the component needs for external API access. With the default provisioning: "manifest", the installer creates the set and the user populates its required keys afterward. With provisioning: "setup", the registered component’s setup endpoint creates and fills the set.

"credentials": [
  {
    "name": "github-creds-<org-name>-<repo-name>",
    "description": "GitHub API access for fetching repos",
    "provisioning": "manifest",
    "requiredKeys": [
      { "key": "github_token", "description": "Personal access token with repo scope" }
    ]
  }
]

Field	Type	Required	Description
name	string	Yes	Credential set name.
description	string	No	What these credentials are for.
requiredKeys	array	Yes	Keys that must be set.
provisioning	"manifest" | "setup"	No	Which side creates the credential set. Defaults to manifest.
requiredKeys[].key	string	Yes	Key name.
requiredKeys[].description	string	No	What the key is used for.

Credential names may include the template tokens:

• <org-name>
• <repo-name>

These are resolved at install/setup time. For example, veritas-webhook-<org-name>-<repo-name> becomes veritas-webhook-acme-world.

After install, populate keys with:

wh credential set github-creds-acme-world github_token --value ghp_... --repo acme/world

subscriptions

Subscriptions that trigger webhooks on write events.

"subscriptions": [
  {
    "name": "rk/on-paper-add",
    "trigger": { "kind": "event", "shape": "Paper" },
    "kind": "webhook",
    "webhookUrl": "https://handler.example.com/on-paper",
    "credentials": ["github-creds-<org-name>-<repo-name>"]
  }
]

Field	Type	Required	Description
name	string	Yes	Subscription name. Convention: <prefix>/<description>.
trigger	object	Yes	What fires the subscription.
kind	"webhook"	No	Optional advisory field retained for readability. The CLI derives the effective subscription kind from trigger.kind and ignores this field at install time.
webhookUrl	string	Yes	Destination URL for deliveries.
credentials	string[]	No	Credential sets to bind. Currently limited to one.
fallbackWebhookUrl	string	No	Optional fallback delivery target.
provisioning	"manifest" | "setup"	No	Which side creates the subscription. Defaults to manifest.

Event trigger:

Field	Type	Required	Description
kind	"event"	Yes
shape	string	Yes	Shape to watch for changes. Must be declared in shapes[] or be a subscription-trigger built-in (ComponentInstall, ComponentConfig); validation rejects an undeclared shape.
filter	object	No	Additional filter criteria.

seeds

Initial data created at install time.

"seeds": [
  {
    "kind": "thing",
    "shape": "ComponentConfig",
    "name": "my-component",
    "data": { "version": "1.0.0", "enabled": true }
  }
]

Field	Type	Required	Description
kind	"thing"	Yes	Currently only "thing" is supported.
shape	string	Yes	Shape name. Must be declared in shapes or be a built-in (ComponentConfig).
name	string	Yes	Thing name within the shape.
data	object	Yes	Field values. Must conform to the shape’s field definitions.

ComponentConfig is a built-in shared shape — you can seed things into it without declaring it in shapes.

health

Configuration reserved for richer wh component doctor diagnostics in a future CLI version.

"health": {
  "requires": {
    "shapes": ["Paper", "PaperSummary"],
    "things": ["ComponentConfig/my-component"],
    "subscriptions": ["rk/on-paper-add"]
  }
}

Field	Type	Description
requires.shapes	string[]	Reserved for future doctor checks.
requires.things	string[]	Reserved for future doctor checks.
requires.subscriptions	string[]	Reserved for future doctor checks.

All fields are optional. The current CLI accepts this section in the manifest schema, but wh component doctor does not read health.requires.* yet. Today, doctor checks the shapes, subscriptions, credentials, and seeds declared elsewhere in the manifest.

teardown

Behavior when the component is disabled. The current CLI teardown flow reads subscriptions.onDisable; onUninstall is schema-valid but not executed yet.

"teardown": {
  "subscriptions": {
    "onDisable": "pause",
    "onUninstall": "delete"
  }
}

Field	Type	Description
subscriptions.onDisable	"pause"	Action when component is disabled.
subscriptions.onUninstall	"pause" | "delete"	Reserved for a future uninstall flow.

cli

Optional. Declares a CLI surface the component exposes to operators. When present, the listed methods become invokable through wh component exec <component> <method> (or the shorthand wh <component> <method>) once the component is installed. Omit the section if the component has no operator-facing commands.

The example below is the get-reputation method from the shipping Veritas manifest:

"cli": {
  "description": "Read and adjust Veritas source reputations from the install repo.",
  "methods": [
    {
      "name": "get-reputation",
      "description": "Get a single Veritas source reputation by wref and scope.",
      "credentialSet": "veritas-webhook-<org-name>-<repo-name>",
      "method": "GET",
      "path": "reputation",
      "requiresPermission": "repo:read",
      "args": [
        { "name": "wref", "type": "string", "required": true, "description": "Source Thing wref whose reputation to read." },
        { "name": "scope", "type": "string", "required": true, "description": "Scope the reputation is held under." }
      ]
    }
  ]
}

Field	Type	Required	Description
description	string	No	One-line summary of the CLI surface, shown in wh --help.
methods	array	Yes	The invokable methods. May be empty.
methods[].name	string	Yes	Method name (lowercase kebab, unique within methods).
methods[].description	string	No	What the method does.
methods[].credentialSet	string	Yes	Name of an entry in this manifest’s credentials[] that holds the method’s auth. The referenced set must declare a supported CLI auth scheme.
methods[].args	array	Yes	Declared arguments (see below). May be empty.
methods[].method	"GET" | "POST" | "PUT" | "PATCH" | "DELETE"	No	Defaults to POST. Use GET for read-only lookups.
methods[].path	string	No	URL path the method routes to, decoupling the route from the method name. One or more lowercase-kebab segments joined by / (e.g. reputations/get). Defaults to the method name. Two methods may share a path only if their method (verb) differs.
methods[].requiresPermission	"repo:read" | "repo:checkpoint-read" | "repo:checkpoint-generate" | "repo:write" | "repo:configure" | "repo:admin" | "repo:action-callback"	No	The repo-level scope the operator must hold on the install repo to call this method. Defaults to repo:read. See Method permissions for how the scopes combine and what they do not cover.
methods[].args[].name	string	Yes	Arg name (lowercase kebab, unique within the method).
methods[].args[].type	"string" | "integer" | "number" | "boolean"	Yes	Arg type.
methods[].args[].required	boolean	No	Whether the arg must be supplied.
methods[].args[].default	string | number | boolean	No	Default value when the arg is omitted.
methods[].args[].min / max	number	No	Numeric bounds for integer/number args.
methods[].args[].pattern	string	No	Regex the value must match, for string args.
methods[].args[].description	string	No	What the arg is for.

Method permissions

methods[].requiresPermission names the repo scope a caller must hold on the install repo before the method runs:

• Every method requires repo:read at minimum. Setting a higher value — repo:write, for example — adds that scope on top of repo:read.
• Use repo:checkpoint-read for methods that read existing portable checkpoints, repo:checkpoint-generate for methods that create or trigger generation of a new checkpoint, and repo:action-callback for repo-scoped action-run callback delivery.
• The field is a coarse repo-scope gate only. Any finer-grained authorization — object-level or action-level checks, for instance — remains the component service’s responsibility to enforce in its handler, using the caller identity and context it is given.

When methods is non-empty, runtimeAccess.writes must include ComponentConfig. Without it, the component’s CLI methods won’t be callable after install.

Complete example

{
  "$schema": "https://docs.warmhub.ai/schema/component-manifest.v1.json",
  "component": {
    "id": "com.warmhub.E2eEcho",
    "name": "e2e-echo",
    "version": "1.0.0"
  },
  "shapes": [
    { "name": "EchoInput", "fields": { "message": "string", "priority": "number" } },
    { "name": "EchoOutput", "fields": { "echo": "string", "processedAt": "string" } }
  ],
  "credentials": [
    {
      "name": "echo-api-creds",
      "description": "API credentials for echo service",
      "requiredKeys": [{ "key": "api_key", "description": "Echo API key" }]
    }
  ],
  "subscriptions": [
    {
      "name": "echo/process-input",
      "trigger": { "kind": "event", "shape": "EchoInput" },
      "kind": "webhook",
      "webhookUrl": "https://echo.example.com/process",
      "credentials": ["echo-api-creds"]
    }
  ],
  "seeds": [
    {
      "kind": "thing",
      "shape": "EchoInput",
      "name": "welcome",
      "data": { "message": "Hello from e2e-echo component", "priority": 1 }
    }
  ],
  "health": {},
  "teardown": { "subscriptions": { "onDisable": "pause" } }
}

Validation

Run offline validation before installing:

wh component validate ./my-component

This checks:

• JSON syntax and required fields
• Cross-references (subscriptions reference valid credentials, seeds reference valid shapes)
• Duplicate names within sections
• Subscription trigger and webhook validation
• Component ID format (reverse-DNS)
• Consistency between component.json and manifest.json