Changeset 0.28.0.1 (#173)

docs/ICD/surfaces.md

@@ -0,0 +1,118 @@
+# Surfaces
+
+Dynamic surface lifecycle. Core surfaces are registered at startup.
+Extension surfaces are uploaded by admins and served from the
+`surface_registry` table.
+
+## User Endpoints
+
+### List Enabled Surfaces
+
+```
+GET /surfaces
+```
+
+Returns surfaces the user can access (enabled in registry).
+
+```json
+{
+  "surfaces": [
+    { "id": "chat", "title": "Chat", "source": "core", "enabled": true },
+    { "id": "editor", "title": "Editor", "source": "core", "enabled": true },
+    { "id": "hello-dashboard", "title": "Hello Dashboard", "source": "extension", "enabled": true }
+  ]
+}
+```
+
+**Auth:** Authenticated.
+
+## Admin Endpoints
+
+### List All Surfaces
+
+```
+GET /admin/surfaces
+```
+
+Returns all surfaces including disabled ones.
+
+**Auth:** Platform admin.
+
+### Get Surface
+
+```
+GET /admin/surfaces/:id
+```
+
+Returns full surface details including manifest.
+
+### Install Surface
+
+```
+POST /admin/surfaces/install
+Content-Type: multipart/form-data
+```
+
+Field: `archive` — a `.surface` archive (tar.gz containing `manifest.json`
++ static assets). The manifest declares `id`, `title`, `route`, required
+data loaders, scripts, and CSS.
+
+**Auth:** Platform admin.
+
+### Enable / Disable
+
+```
+PUT /admin/surfaces/:id/enable
+PUT /admin/surfaces/:id/disable
+```
+
+Disabled surfaces redirect to `/` and hide from navigation.
+
+**Auth:** Platform admin.
+
+### Delete Surface
+
+```
+DELETE /admin/surfaces/:id
+```
+
+Removes the surface and its static assets. Core surfaces cannot be deleted.
+
+**Auth:** Platform admin.
+
+## Surface Registry Object
+
+```json
+{
+  "id": "hello-dashboard",
+  "title": "Hello Dashboard",
+  "manifest": { "route": "/s/hello-dashboard", "scripts": [...], "css": [...] },
+  "enabled": true,
+  "source": "core|extension",
+  "installed_at": "...",
+  "updated_at": "..."
+}
+```
+
+## Page Routes
+
+Extension surfaces are served at `/s/:slug` via `RenderExtensionSurface()`.
+The page engine does a runtime DB lookup — no server restart needed after install.
+
+Static assets are served from `/surfaces/:id/` (nginx location block in
+both unified and split deployment).
+
+## Surface Archive Format
+
+A `.surface` file is a tar.gz containing:
+
+```
+manifest.json     — required
+script.js         — optional
+style.css         — optional
+assets/           — optional (icons, images, etc.)
+```
+
+See [EXTENSION-SURFACES.md](../EXTENSION-SURFACES.md) for the full
+authoring guide including manifest schema, platform API, and CSS
+custom properties.