core/packages/README.md

Packages

Installable .pkg archives for Chat Switchboard. 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 for the complete manifest schema and authoring guide. For workflow packages, see docs/WORKFLOW-PACKAGES.md.

Building

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

Installing

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.