Publish an extension

1. Anatomy of an extension

An extension is a package with a .punica/config.yaml manifest, a built dist/index.js entry point and, for anything an agent may call, a .punica/capabilities.yaml declaring each capability: its id, its input and output schema, the action it performs from the closed vocabulary, its risk level and whether it asks for a person. A minimal manifest:

name: extension-hello
displayName: Hello
description: A tiny example extension for IVYX Studio
version: 1.0.0
main: dist/index.js
categories: [tools]
tags: [example]
engines:
  punica: "^1.0.0"
marketplace:
  publisher: your-name

2. Build

Compile your source to dist/index.js (the sample extensions use Rollup):

npm install
npm run build

3. What gets packaged

Publishing zips a fixed set from your extension folder, with no package.json globs:

• .punica/, the manifest (required)
• dist/, the built code (required: dist/index.js)
• assets/, examples/, optional (icon/banner/screenshots)
• README.md, CHANGELOG.md, optional (shown in the marketplace)

4. Publish

Publishing is by arrangement today: everything on the registry is first-party, the path is live, and we issue the token. Write to us and you get one.

Recommended: GitHub Actions. Add a publish.yml workflow and the REGISTRY_URL / REGISTRY_TOKEN secrets to your repo; it builds and publishes on a v* tag or a manual run.

Or from the CLI:

REGISTRY_URL=https://registry.ivyx.io \
REGISTRY_TOKEN=the-token-we-issued \
node cli/publish-extension.mjs ./extension-hello --build

Before the upload, the publish gates run: types, copy, permissions, empty states, card shape, drawer escape, capability handlers, duplicate capabilities, instruction classes, registration shape and skills. A dist/ older than src/ is refused, and so is any token or secret in the package, because every secret goes through the Secret Manager's client. The registry then verifies the package, extracts the icon/README, and lists it in the marketplace.

5. Versioning

Published versions are immutable. Re-publishing the same version returns 409. Bump version in .punica/config.yaml to ship an update; the marketplace always serves the newest compatible version for the running editor.