Bundle Format

A plugin is distributed as a `.sweater` bundle — a folder you zip and push via the CLI (`cableknit push`). The `.sweater` extension is CableKnit's native plugin format.

## Folder structure

```
my-plugin.sweater/
  plugin.json          ← required: plugin manifest
  skills/              ← optional: one JSON file per skill
    skill-name.json
  automations/         ← optional: one JSON file per automation
    automation-name.json
  blueprints/          ← optional: one JSON file per artifact blueprint
    report-template.json
  tools/               ← optional: one JSON file per data tool
    crm-lookup.json
  docs/                ← optional: Markdown files, supports subfolders
    getting-started.md
    advanced/
      custom-config.md
  images/              ← optional: screenshots for Marketplace listing
    screenshot-1.png
  README.md            ← optional: shown in Marketplace listing
```

Convention-based — no manifest list required. The server picks up every file in each folder automatically. Order within a folder is determined by the `position` field inside each file.

### Automation trigger types

| Type | Description |
|---|---|
| `schedule` | Runs on a cron schedule |
| `event` | Triggered by a connector event (e.g. Procore webhook, Slack event) |
| `webhook` | Triggered by an external HTTP POST to a unique URL. Each installed automation gets a dedicated webhook URL shown in the API response. External systems POST JSON to this URL to start a run. Optional HMAC verification via `trigger_config.webhook_secret`. |
| `inbound_email` | Triggered by an email sent to a provisioned address |

## plugin.json

The root manifest for your plugin.

```json
{
  "name": "Subcontractor Onboarding",
  "slug": "subcontractor-onboarding",
  "version": "1.0.0",
  "description": "Automates subcontractor intake, document collection, and compliance verification.",
  "author": {
    "name": "Acme Consulting",
    "email": "dev@acme.com",
    "website": "https://acme.com"
  },
  "industry": "construction",
  "tier": "industry",
  "visibility": "public",
  "pricing": {
    "model": "monthly",
    "price_cents": 4900
  },
  "requirements": {
    "connectors": ["procore"]
  },
  "nav": {
    "show_in_nav": false,
    "icon": "briefcase",
    "label": "Onboarding"
  }
}
```

### Field reference

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Display name shown in the Marketplace |
| `slug` | string | Yes | Unique identifier. Lowercase letters, numbers, and hyphens only. |
| `version` | string | Yes | Semver format: `1.0.0` |
| `description` | string | Yes | Short description shown in Marketplace listings |
| `author.name` | string | Yes | Your name or company name |
| `author.email` | string | No | Contact email |
| `author.website` | string | No | Your website |
| `industry` | string | No | Industry this plugin targets (e.g. `construction`, `food_distribution`, `logistics`) |
| `tier` | enum | Yes | `starter`, `industry`, or `custom` |
| `visibility` | enum | Yes | `private`, `unlisted`, or `public` |
| `pricing.model` | enum | Yes | `monthly` |
| `pricing.price_cents` | integer | Yes | Monthly price in cents. Must be at or above the calculated cost floor. |
| `platform_version` | string | No | CableKnit platform version this plugin targets. Defaults to `"1"` if omitted. |
| `requirements.connectors` | array | No | Connector slugs required for the plugin to function |
| `nav.show_in_nav` | boolean | No | Show plugin as a tab in the Mac app sidebar. Defaults to `false`. |
| `nav.icon` | string | No | SF Symbol name for the nav icon. Required if `show_in_nav` is `true`. |
| `nav.label` | string | No | Sidebar label. Required if `show_in_nav` is `true`. |

### Visibility options

| Value | Description | Review required |
|---|---|---|
| `private` | Only installable by companies you explicitly grant access to | No |
| `unlisted` | Installable via direct link, not shown in Marketplace | No |
| `public` | Listed in the Marketplace, available to all companies | Yes |

### Pricing and the cost floor

CableKnit calculates a minimum price for your plugin based on the estimated API cost of running your automations. The calculation counts AI steps (`ai_assess` actions) across all your automation templates and estimates the monthly cost at 500 runs.

If your `price_cents` is below the floor, the push will be rejected with a message explaining exactly what the floor is and why. Set your price at or above the floor — you are free to charge more.

### Connector requirements

If your plugin depends on a connector being configured (for example, your automation listens for Procore events), declare it in `requirements.connectors`. When a company tries to install your plugin without the required connector, they'll be prompted to connect it first.

Available connector slugs: `salesforce`, `hubspot`, `google`, `quickbooks`, `xero`, `docusign`, `slack`, `procore`, `microsoft`

### Settings schema

Define configuration fields that companies fill out when installing your plugin. Values are available to the AI in prompt context.

```json
"settings_schema": [
  {
    "key": "api-key",
    "label": "API Key",
    "type": "string",
    "required": true
  },
  {
    "key": "notify-email",
    "label": "Notification Email",
    "type": "email",
    "required": false,
    "default": ""
  }
]
```

| Field | Type | Required | Description |
|---|---|---|---|
| `key` | string | Yes | Lowercase alphanumeric and hyphens |
| `label` | string | Yes | Display label shown to the company |
| `type` | enum | Yes | `string`, `email`, `number`, `boolean`, `url` |
| `required` | boolean | No | If true, company must fill before installing |
| `default` | any | No | Default value |

Add `settings_schema` as a top-level field in your `plugin.json`. Companies fill these settings at install time.

## Limits

| Resource | Limit |
|---|---|
| Bundle size | 10MB |
| Skills | 20 |
| Automations | 10 |
| Blueprints | 20 |
| Data tools | 10 |
| Documentation pages | 50 |
| Images | 5 (max 2MB each, PNG/JPG/WEBP) |
| Blueprint content schema | 4KB |
| Static tool data | 64KB |

## Updating your bundle

Re-pushing a bundle with the same `slug` updates the plugin in place. All existing records are updated to match the new bundle. Files you remove from the bundle are deleted from the database.

If your plugin has already been submitted or approved, re-pushing resets it to `draft` and requires re-submission. Plan your updates accordingly — batch changes before re-submitting rather than submitting individual small changes.

A plugin is distributed as a .sweater bundle — a folder you zip and push via the CLI (cableknit push). The .sweater extension is CableKnit’s native plugin format.

Folder structure

my-plugin.sweater/
  plugin.json          ← required: plugin manifest
  skills/              ← optional: one JSON file per skill
    skill-name.json
  automations/         ← optional: one JSON file per automation
    automation-name.json
  blueprints/          ← optional: one JSON file per artifact blueprint
    report-template.json
  tools/               ← optional: one JSON file per data tool
    crm-lookup.json
  docs/                ← optional: Markdown files, supports subfolders
    getting-started.md
    advanced/
      custom-config.md
  images/              ← optional: screenshots for Marketplace listing
    screenshot-1.png
  README.md            ← optional: shown in Marketplace listing

Convention-based — no manifest list required. The server picks up every file in each folder automatically. Order within a folder is determined by the position field inside each file.

Automation trigger types

Type	Description
`schedule`	Runs on a cron schedule
`event`	Triggered by a connector event (e.g. Procore webhook, Slack event)
`webhook`	Triggered by an external HTTP POST to a unique URL. Each installed automation gets a dedicated webhook URL shown in the API response. External systems POST JSON to this URL to start a run. Optional HMAC verification via `trigger_config.webhook_secret`.
`inbound_email`	Triggered by an email sent to a provisioned address

plugin.json

The root manifest for your plugin.

{
  "name": "Subcontractor Onboarding",
  "slug": "subcontractor-onboarding",
  "version": "1.0.0",
  "description": "Automates subcontractor intake, document collection, and compliance verification.",
  "author": {
    "name": "Acme Consulting",
    "email": "dev@acme.com",
    "website": "https://acme.com"
  },
  "industry": "construction",
  "tier": "industry",
  "visibility": "public",
  "pricing": {
    "model": "monthly",
    "price_cents": 4900
  },
  "requirements": {
    "connectors": ["procore"]
  },
  "nav": {
    "show_in_nav": false,
    "icon": "briefcase",
    "label": "Onboarding"
  }
}

Field reference

Field	Type	Required	Description
`name`	string	Yes	Display name shown in the Marketplace
`slug`	string	Yes	Unique identifier. Lowercase letters, numbers, and hyphens only.
`version`	string	Yes	Semver format: `1.0.0`
`description`	string	Yes	Short description shown in Marketplace listings
`author.name`	string	Yes	Your name or company name
`author.email`	string	No	Contact email
`author.website`	string	No	Your website
`industry`	string	No	Industry this plugin targets (e.g. `construction`, `food_distribution`, `logistics`)
`tier`	enum	Yes	`starter`, `industry`, or `custom`
`visibility`	enum	Yes	`private`, `unlisted`, or `public`
`pricing.model`	enum	Yes	`monthly`
`pricing.price_cents`	integer	Yes	Monthly price in cents. Must be at or above the calculated cost floor.
`platform_version`	string	No	CableKnit platform version this plugin targets. Defaults to `"1"` if omitted.
`requirements.connectors`	array	No	Connector slugs required for the plugin to function
`nav.show_in_nav`	boolean	No	Show plugin as a tab in the Mac app sidebar. Defaults to `false`.
`nav.icon`	string	No	SF Symbol name for the nav icon. Required if `show_in_nav` is `true`.
`nav.label`	string	No	Sidebar label. Required if `show_in_nav` is `true`.

Visibility options

Value	Description	Review required
`private`	Only installable by companies you explicitly grant access to	No
`unlisted`	Installable via direct link, not shown in Marketplace	No
`public`	Listed in the Marketplace, available to all companies	Yes

Pricing and the cost floor

CableKnit calculates a minimum price for your plugin based on the estimated API cost of running your automations. The calculation counts AI steps (ai_assess actions) across all your automation templates and estimates the monthly cost at 500 runs.

If your price_cents is below the floor, the push will be rejected with a message explaining exactly what the floor is and why. Set your price at or above the floor — you are free to charge more.

Connector requirements

If your plugin depends on a connector being configured (for example, your automation listens for Procore events), declare it in requirements.connectors. When a company tries to install your plugin without the required connector, they’ll be prompted to connect it first.

Available connector slugs: salesforce, hubspot, google, quickbooks, xero, docusign, slack, procore, microsoft

Settings schema

Define configuration fields that companies fill out when installing your plugin. Values are available to the AI in prompt context.

"settings_schema": [
  {
    "key": "api-key",
    "label": "API Key",
    "type": "string",
    "required": true
  },
  {
    "key": "notify-email",
    "label": "Notification Email",
    "type": "email",
    "required": false,
    "default": ""
  }
]

Field	Type	Required	Description
`key`	string	Yes	Lowercase alphanumeric and hyphens
`label`	string	Yes	Display label shown to the company
`type`	enum	Yes	`string`, `email`, `number`, `boolean`, `url`
`required`	boolean	No	If true, company must fill before installing
`default`	any	No	Default value

Add settings_schema as a top-level field in your plugin.json. Companies fill these settings at install time.

Limits

Resource	Limit
Bundle size	10MB
Skills	20
Automations	10
Blueprints	20
Data tools	10
Documentation pages	50
Images	5 (max 2MB each, PNG/JPG/WEBP)
Blueprint content schema	4KB
Static tool data	64KB

Updating your bundle

Re-pushing a bundle with the same slug updates the plugin in place. All existing records are updated to match the new bundle. Files you remove from the bundle are deleted from the database.

If your plugin has already been submitted or approved, re-pushing resets it to draft and requires re-submission. Plan your updates accordingly — batch changes before re-submitting rather than submitting individual small changes.