# Packages

Installable `.pkg` archives for Chat Armature. Each subdirectory is a
package — either a surface (routable UI), an extension (hooks/tools/pipes),
or both (`full` type).

v0.28.7: Renamed from `surfaces/`. The `.pkg` format replaces `.surface`.

See [docs/PACKAGES.md](../docs/PACKAGES.md) for the complete manifest schema and authoring guide.
For workflow packages, see [docs/WORKFLOW-PACKAGES.md](../docs/WORKFLOW-PACKAGES.md).

## Building

```bash
./packages/build.sh                   # build all → dist/*.pkg
./packages/build.sh icd-test-runner   # build one
```

## Installing

```bash
curl -X POST http://localhost:8080/api/v1/admin/packages/install \
  -H "Authorization: Bearer $TOKEN" \
  -F file=@dist/icd-test-runner.pkg
```

Or use the admin UI → System → Packages → Upload.

## Archive Format

A `.pkg` file is a zip containing:

```
manifest.json     — required (must have "id" and "title")
js/               — optional JavaScript assets
css/              — optional stylesheets
assets/           — optional images, icons, etc.
```

The manifest `type` field determines behavior:
- `surface` (default) — routable page at `/s/:slug`
- `extension` — hooks, tools, and/or pipe filters
- `full` — both a surface and an extension

`.surface` archives are accepted as a backward-compatible alias.