Changeset 0.28.4 (#190)

surfaces/README.md

@@ -0,0 +1,60 @@
+# surfaces/
+
+Source directories for installable extension surfaces. Each subdirectory
+contains a `manifest.json` plus `js/`, `css/`, and optionally `assets/`
+directories — matching the archive format expected by
+`POST /admin/surfaces/install`.
+
+## Structure
+
+```
+surfaces/
+  build.sh              ← packages each subdir into dist/<name>.surface
+  hello-dashboard/      ← sample surface (verifies /s/:slug pipeline)
+    manifest.json
+    js/main.js
+    css/main.css
+  icd-test-runner/      ← ICD contract test runner (dev/test tool)
+    manifest.json
+    js/
+    css/
+```
+
+## Building
+
+```bash
+# Build all surfaces → dist/*.surface
+./surfaces/build.sh
+
+# Build one
+./surfaces/build.sh icd-test-runner
+```
+
+Output goes to `dist/` (gitignored). Each `.surface` file is a zip
+archive ready for upload via the admin UI or:
+
+```bash
+curl -X POST https://host/api/v1/admin/surfaces/install \
+  -H "Authorization: Bearer $TOKEN" \
+  -F "file=@dist/icd-test-runner.surface"
+```
+
+## Adding a surface
+
+1. Create `surfaces/<id>/manifest.json` with at least `id` and `title`
+2. Add `js/`, `css/`, `assets/` as needed
+3. Run `./surfaces/build.sh <id>` to verify it packages
+4. Install via admin UI or API
+
+See [EXTENSION-SURFACES.md](../docs/EXTENSION-SURFACES.md) for the full
+authoring guide including manifest schema, platform API, and CSS custom
+properties.
+
+## Conventions
+
+- `id` in manifest.json must be unique across all surfaces (core + extension)
+- Core surfaces (`chat`, `admin`, `settings`, `notes`, `editor`) cannot
+  be overridden — the install endpoint returns 409
+- Surface routes are served at `/s/<id>` (auto-derived from manifest)
+- Static assets are served from `/surfaces/<id>/js/`, `/surfaces/<id>/css/`
+- The `dist/` directory is gitignored — archives are build artifacts