Feat v0.9.8 conditional routing SDK primitive

Promote workflow branch-rule evaluation to a generic Starlark
routing.evaluate(rules, data) module available to all extensions.
10 operators, first-match-wins, no permission gate. 8 new tests.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -2,6 +2,626 @@
 
 All notable changes to Armature are documented here.
 
+## v0.9.8 — Conditional Routing → SDK Primitive
+
+Promotes the workflow branch-rule engine to a generic Starlark SDK
+module available to all extensions — no permission required.
+
+**New Starlark module: `routing`**
+
+- `routing.evaluate(rules, data)` — evaluates an ordered list of
+  condition rules against a data dict; returns the first matching
+  rule's `target` string, or `None` if no rule matches
+- 10 operators: `exists`, `not_exists`, `eq`, `neq`, `gt`, `lt`,
+  `gte`, `lte`, `in`, `contains`
+- First-match-wins semantics
+- Domain-agnostic: uses `target` (not `target_stage`) so any
+  extension can use it for feature flags, content routing, approval
+  logic, etc.
+- Always available — pure computation, no I/O, no permission gate
+
+**Tests:** 8 new unit tests covering all operators, type coercion,
+first-match-wins, empty/missing/bad input
+
+## v0.9.7 — Full Read/Write Workflow Starlark Module
+
+Extensions with `workflow.access` permission can now start, advance,
+cancel, and signoff workflow instances directly from Starlark scripts.
+
+**WorkflowEngine interface**
+
+- Defined in `sandbox` package to break the `workflow ↔ sandbox` circular
+  import (follows `NotificationSender` / `ConnectionResolver` pattern)
+- 4 methods: `Start`, `Advance`, `Cancel`, `SubmitSignoff`
+- `workflow.Engine` satisfies the interface implicitly — zero changes to
+  the engine package
+
+**New Starlark builtins**
+
+- `workflow.start(workflow_id, data={})` → instance dict
+- `workflow.advance(instance_id, data={})` → instance dict
+- `workflow.cancel(instance_id)` → None
+- `workflow.submit_signoff(instance_id, decision, comment="")` → signoff dict
+- All write ops require authenticated user context (`RunContext.UserID`)
+- Graceful errors when engine or user context unavailable
+
+**Refactors**
+
+- `instanceToDict` helper extracted — shared by `get_instance`, `start`,
+  `advance`
+- `signoffToDict` helper for signoff return values
+- `dictToJSON` helper for Starlark dict → `json.RawMessage` conversion
+
+**Tests:** 6 new unit tests (mock engine, happy path + error guards)
+
+## v0.9.6 — Deprecate stage_type, Collapse stage_mode
+
+Simplifies the workflow stage classification model by removing
+redundant fields.
+
+**stage_type deprecated**
+
+- No longer validated on input; any value accepted, defaults to "simple"
+- Existing manifests parsed for backward compatibility
+- DB column retained; export no longer includes the field
+- `starlark_hook` presence (not `stage_type`) determines automation
+
+**stage_mode collapsed (4 → 3 values)**
+
+- "review" removed as valid mode; mapped to "form" on input
+- Existing DB rows migrated: review → form
+- Review surface removed from workflow.html (~110 lines); signoff system
+  in `stage_config.validation` handles review behavior
+- Valid modes: form, delegated, automated
+
+**DB migration 018**
+
+- Postgres: UPDATE + CHECK constraint replacement
+- SQLite: UPDATE only (CHECK stays broad)
+
+**Package manifests updated**
+
+- bug-report-triage, content-approval, employee-onboarding,
+  webhook-notifier: review → form, stage_type removed
+
+## v0.9.5 — Typed Forms → SDK Primitive
+
+Promotes the typed form system from a workflow-only model to a reusable
+SDK primitive. Any package can now declare and validate forms — not just
+workflow stages.
+
+**Backend — `server/forms/` package**
+
+- Extracted `TypedFormTemplate`, `FormField`, `FormFieldset`, `FormOption`,
+  `FormValidation`, `FieldCondition`, `FormHooks`, `FieldError` from
+  `models/workflow.go` into standalone `forms` package.
+- `ParseTypedFormTemplate()`, `ValidateFormData()`, `EvaluateFieldCondition()`
+  exported for use by any consumer.
+- ~317 lines removed from `models/workflow.go` (no external imports existed).
+
+**REST endpoint**
+
+- `POST /api/v1/forms/validate` — authenticated endpoint. Accepts
+  `{template, data}`, returns `{valid: bool, errors: [{key, message}]}`.
+
+**Starlark module**
+
+- `forms.validate(template, data)` — gated by `forms.validate` permission.
+  Returns dict with `valid` (bool) and `errors` (list of dicts).
+
+**Frontend SDK**
+
+- `sw.forms.render(container, template, opts)` — Preact component rendering
+  flat and progressive (fieldset) forms. Returns `{getData, setErrors, destroy}`.
+- `sw.forms.validate(template, data)` — client-side validation (mirrors Go logic).
+- `sw.forms.validateRemote(template, data)` — server-side validation via REST.
+- SDK version bumped to `0.9.5`.
+
+**Manifest validation**
+
+- `form_template` accepted at package level. Validated via
+  `forms.ParseTypedFormTemplate()` at install time.
+- `ManifestInfo.HasFormTemplate` flag added.
+
+**Tests**
+
+- 16 new tests: 12 forms package unit tests (parse, validate by type,
+  conditions, fieldsets), 4 Starlark module tests (valid, required,
+  type errors, conditions).
+
+---
+
+## v0.9.4 — Package Adoption + Roles
+
+Packages can now declare `adoptable: true` in their manifest. When a team
+adopts an adoptable package, a team-scoped copy is created that references
+the original (shared assets, no disk duplication). The package's
+`requires_roles` auto-populate into a new `team_role_catalog` table so
+team admins know which roles to assign.
+
+**Schema**
+
+- Migration 017: `adoptable` and `adopted_from` columns on `packages`.
+  `team_role_catalog` table (team_id, role, source_package_id) with
+  unique constraint. Both Postgres and SQLite dialects.
+
+**Store + Models**
+
+- `PackageRegistration`: `Adoptable bool`, `AdoptedFrom *string`.
+- `PackageStore`: `ListAdoptable()`, `GetByAdoptedFrom()`.
+- `TeamRoleCatalogEntry` model struct.
+- `TeamStore`: `AddRoleToCatalog`, `ListRoleCatalog`,
+  `RemoveRoleCatalogBySource`.
+
+**Handlers**
+
+- `POST /teams/:teamId/packages/:id/adopt` — adopt a global adoptable
+  package into the team. Creates team-scoped registration, clones
+  workflow if applicable, populates role catalog. Idempotent.
+- `GET /teams/:teamId/packages/adoptable` — list available packages
+  with adoption status per team.
+- `DELETE /teams/:teamId/packages/:id/unadopt` — remove adopted package
+  and clean up role catalog entries.
+- `GET /teams/:teamId/roles/catalog` — list known roles for a team.
+
+**Manifest Validation**
+
+- `adoptable: true` parsed as `ManifestInfo.Adoptable`.
+- Rejected on `library` and `test-runner` types.
+- Persisted to DB on package install.
+
+**Deprecation**
+
+- `POST /teams/:teamId/workflows/:id/adopt` (`AdoptTeamWorkflow`) now
+  returns `X-Deprecated` header and logs a deprecation warning.
+  Use the package-level adoption endpoint instead.
+
+**Tests**
+
+- 11 new tests: 5 manifest validation, 3 role catalog store, 3 handler
+  integration (adopt success, idempotent, non-adoptable rejection).
+
+---
+
+## v0.9.3 — Team User Roles
+
+Promotes the team role system from a single-role-per-member model to a
+many-to-many relationship, enabling users to hold multiple roles within
+a team simultaneously.
+
+**Schema**
+
+- Migration 016: `team_user_roles` table (team_id, user_id, role) with
+  unique constraint and compound index. Both Postgres and SQLite dialects.
+
+**Store + Models**
+
+- `TeamUserRole` model struct.
+- 6 new `TeamStore` methods: `AddUserRole`, `RemoveUserRole`,
+  `ListUserRoles`, `GetMemberRoles` (union of primary + additional),
+  `HasRole`, `RemoveAllUserRoles`.
+- Implementations for both Postgres and SQLite stores.
+
+**Middleware**
+
+- `RequireRole(teams, roles, stores)` — kernel middleware that checks
+  whether the user holds at least one of the required roles (OR semantics).
+  System admin bypass via permissions.
+
+**Handlers**
+
+- `GET /teams/:teamId/members/:memberId/roles` — list full role set.
+- `POST /teams/:teamId/members/:memberId/roles` — assign additional role.
+- `DELETE /teams/:teamId/members/:memberId/roles/:role` — remove role.
+- `RemoveMember` handler now cleans up `team_user_roles` on member removal.
+
+**Manifest**
+
+- `requires_roles` field parsed from package manifests (advisory in v0.9.3;
+  extensions gate via `teams.has_role()` in Starlark).
+
+**Starlark SDK**
+
+- New `teams` module wired into sandbox runner:
+  - `teams.get_member_roles(team_id, user_id)` → list of strings.
+  - `teams.has_role(team_id, user_id, role)` → True/False.
+
+**Admin UI**
+
+- Team-admin members page: removable badge chips for additional roles,
+  "+ Role" dropdown for assignment.
+- Fixed pre-existing SDK auto-unwrap bug in `loadRoles` / `loadMemberRoles`.
+
+**Tests**
+
+- 10 new tests: store CRUD (add, idempotent, has_role, remove, removeAll),
+  middleware (allowed, denied), manifest parsing (valid, empty, invalid).
+
+## v0.9.2 — Starlark Converter Consolidation + Snapshot Cleanup
+
+Consolidates duplicated Go↔Starlark conversion code and snapshot
+parsers into canonical locations, removing ~350 lines of copy-paste
+across 8 files.
+
+**Converter consolidation**
+
+- New `sandbox/convert.go` with four exported functions:
+  `GoToStarlark`, `StarlarkToGo`, `DictToMap`, `MapToDict`.
+- Superset implementation handles all Go primitive types (nil, bool,
+  int, int64, float64, string), containers (map, slice), and Starlark
+  Tuple — covering every variant that previously existed.
+- Deleted duplicate converters from `workflow/automated.go`,
+  `handlers/starlark_helpers.go`, `handlers/workflow_hooks.go`,
+  `sandbox/workflow_module.go`, `sandbox/realtime_module.go`,
+  `sandbox/files_module.go`, `triggers/event.go`, `triggers/webhook.go`.
+- SQL-specific converters in `db_module.go` (error-returning, `[]byte`
+  handling) intentionally excluded — different semantics.
+
+**Snapshot parser consolidation**
+
+- New `models/snapshot.go` with `ParseSnapshotStages()` handling both
+  wrapped `{"stages":[...]}` and legacy flat `[...]` formats.
+- Deleted three identical parsers from `workflow/engine.go`,
+  `handlers/workflow_instance_handlers.go`, and
+  `handlers/workflow_assignment_handlers.go`.
+
+**Snapshot format standardization**
+
+- `workflow_packages.go` publish path now emits wrapped format,
+  matching `workflows.go`. All snapshot creation is consistent.
+
+**Tests:** 7 new converter tests with round-trip coverage. Existing
+engine, handler, and workflow tests updated and passing.
+
+---
+
+## v0.9.1 — Server-Side Sub-Path Routing
+
+Hardens multi-surface routing so full-page refreshes on sub-paths work
+correctly server-side, with early auth optimization and back-button
+resilience.
+
+**Route consolidation**
+
+- Root (`/s/:slug`) and catch-all (`/s/:slug/*path`) handlers now share
+  a single `dispatch` function. The root handler injects `path="/"` and
+  delegates, eliminating the separate code path.
+
+**Early auth short-circuit**
+
+- New `aggregateAccess()` function scans all surfaces to determine
+  whether a package is all-public, all-authenticated, or mixed.
+- All-authenticated packages redirect to login before surface matching,
+  skipping `matchSurface()` + `evaluateAccess()` overhead.
+- Mixed-access packages fall through to per-surface checks as before.
+
+**SDK back-button fix**
+
+- On boot, `history.replaceState()` seeds the initial history entry
+  with `__SURFACE_PATH__` and `__SURFACE_PARAMS__`. This fixes
+  back-button navigation from `sw.navigate()` to the initial
+  server-rendered view.
+- SDK version bumped to `0.9.1`.
+
+**Tests: 13 new**
+
+- 5 `aggregateAccess` unit tests (all-public, all-auth, mixed,
+  default-access, single-public).
+- 8 handler integration tests covering root refresh, sub-path static
+  and param refresh, unauth redirect, public anonymous, mixed-access,
+  non-matching sub-path, and early auth short-circuit.
+
+**Modified files:**
+
+- `server/pages/pages.go` — `aggregateAccess()`, route consolidation,
+  early auth short-circuit in `RenderExtensionSurface`
+- `server/pages/pages_surface_match_test.go` — 5 new unit tests
+- `server/pages/pages_handler_test.go` — 8 new integration tests
+- `src/js/sw/sdk/index.js` — `history.replaceState()` seed, version bump
+
+## v0.9.0 — Multi-Surface Packages
+
+Packages can now declare multiple surfaces — each with its own path, access
+level, title, and layout. A single package can serve a public submission
+form, an authenticated dashboard, and an admin settings page. The kernel
+resolves incoming requests to the correct surface and enforces access
+server-side.
+
+**Manifest: `surfaces` array**
+
+- Packages declare a `surfaces` array with entries like
+  `{ "path": "/submit", "access": "public", "title": "Report a Bug" }`.
+- Each surface has independent `path`, `access`, `title`, `layout`, and
+  `nav` fields. Package-level `auth` and `layout` serve as defaults.
+- Supported access levels: `public`, `authenticated`, `admin`, `group:{name}`.
+- Packages without `surfaces` get auto-synthesis from legacy `auth`/`layout`
+  fields — no existing packages break.
+
+**Kernel: unified route tree**
+
+- Surface handler and ext API handler share a single `/s/:slug` route tree
+  via `RegisterExtensionRoutes`. The dispatcher checks the path prefix:
+  `/api/*` → ext API handler with JWT auth; everything else → surface
+  handler with per-surface access checks.
+- `matchSurface()` resolves request paths against surface patterns with
+  Gin-style `:param` support. Static segments preferred over params.
+- `evaluateAccess()` checks access requirements per-surface, with login
+  redirect for unauthenticated users and 403 for insufficient permissions.
+
+**Frontend: `__SURFACE_PATH__` + `sw.navigate()`**
+
+- `window.__SURFACE_PATH__` and `window.__SURFACE_PARAMS__` injected into
+  every extension surface page. Packages use these to decide which view to
+  render.
+- `sw.navigate(path, params)` for SPA-style intra-package routing via
+  `pushState`. Emits `surface.navigate` events. Handles back/forward via
+  `popstate`.
+- SDK version bumped to `0.9.0`.
+
+**Navigation**
+
+- `extensionNavItems` reads the `surfaces` array to find the nav entry
+  (first `nav: true`, or root `/`).
+- Fix: packages with `status: pending_review` no longer appear in the
+  sidebar navigation.
+
+**Validation**
+
+- `ValidateManifest` validates `surfaces` entries: path required, must
+  start with `/`, no duplicates, access level must be recognized.
+- Empty `surfaces` array rejected. Non-array `surfaces` rejected.
+
+**Tests: 22 new**
+
+- 11 manifest validation tests (surfaces valid/invalid, auto-synthesis,
+  group access, duplicate paths).
+- 11 route matching tests (static paths, param extraction, specificity
+  ordering, nav resolution).
+
+**Modified files:**
+
+- `server/handlers/package_validate.go` — surfaces validation + auto-synthesis
+- `server/handlers/package_validate_test.go` — 11 new tests
+- `server/main.go` — unified extension route registration
+- `server/pages/pages.go` — matchSurface, evaluateAccess, findNavSurface,
+  RegisterExtensionRoutes, nav status filter
+- `server/pages/pages_surface_match_test.go` — 11 new tests
+- `server/pages/templates/base.html` — surface path/params injection
+- `src/js/sw/sdk/index.js` — sw.navigate, popstate, version bump
+- `docs/PACKAGE-FORMAT.md` — surfaces field documentation
+- `docs/MULTI-SURFACE-GUIDE.md` — developer guide
+
+## v0.8.5 — Extension Composability
+
+Extensions can now compose with each other through declared slots, UI
+contributions, and cross-package function calls. This is the last kernel
+feature before 1.0 — the platform now supports the "extensions extending
+extensions" pattern.
+
+**Manifest declarations**
+
+- Surfaces declare named `slots` in their manifest (e.g., `toolbar-actions`,
+  `note-footer`) with context documentation for extension authors.
+- Extensions declare `contributes` entries targeting `{host}:{slot}` names
+  (e.g., `notes:toolbar-actions`). Coupling is soft — install order doesn't
+  matter.
+- The kernel validates slot/contribution conventions at install time.
+
+**Backend: `lib.require()` relaxation**
+
+- `lib.require()` now works with any package that declares `exports`, not
+  just `type: "library"` packages. A full package (with surfaces, settings,
+  UI) can export callable functions for cross-package use.
+- The existing `depends` and permission model is unchanged — the called
+  function runs with the target package's permissions.
+
+**Admin slots endpoint**
+
+- `GET /api/v1/admin/slots` returns an aggregated map of all declared slots
+  across installed packages with their contributors.
+- Uninstalling a package that declares slots warns about orphaned
+  contributions in other packages.
+
+**SDK additions**
+
+- `sw.slots.renderAll(name, context)` — convenience helper for host surfaces
+  to render all components in a slot with error isolation.
+- `sw.slots.declare(name, description)` — runtime slot declaration for
+  discoverability and debugging.
+
+**Documentation**
+
+- `PACKAGE-FORMAT.md` — added `slots`, `contributes`, `depends` field docs.
+- `EXTENSION-GUIDE.md` — new "Extension Composability" section with slot
+  naming conventions, contribution patterns, and cross-package call examples.
+- `STARLARK-REFERENCE.md` — updated `lib` module to reflect exports-based
+  calling (not library-type-only).
+
+**Modified files:**
+
+- `server/sandbox/lib_module.go` — type check → exports check
+- `server/handlers/extensions.go` — composability field validation
+- `server/handlers/packages.go` — orphaned contribution warning
+- `server/main.go` — admin slots route registration
+- `src/js/sw/sdk/slots.js` — `renderAll()`, `declare()`, `declarations()`
+- `docs/PACKAGE-FORMAT.md` — slots, contributes, depends
+- `docs/EXTENSION-GUIDE.md` — composability section
+- `docs/STARLARK-REFERENCE.md` — lib module update
+- `docs/DESIGN-extension-composability.md` — status Draft → Implemented
+
+**New files:**
+
+- `server/handlers/admin_slots.go` — admin slot aggregation endpoint
+
+## v0.8.4 — Documentation Refresh + Surface Sizing Fix
+
+Eight versions of module additions (v0.7.5–v0.8.3) shipped without a
+docs pass. This release brings the public-facing guides up to date and
+fixes a CSS layout bug affecting all surfaces.
+
+**Documentation refresh**
+
+- `STARLARK-REFERENCE.md` — added `workspace` module section (5 builtins),
+  `permissions` module section, and `settings.has_capability()` documentation.
+- `EXTENSION-GUIDE.md` — added `capabilities` manifest block, `vector(N)`
+  column type, `user_permissions` and `gate_permission` manifest fields,
+  updated sandbox permissions list with v0.8.0+ additions (`files.read`,
+  `files.write`, `workspace.manage`).
+- `TUTORIAL-FIRST-EXTENSION.md` — reviewed for v0.7+ accuracy (no changes needed).
+
+**Surface sizing fix**
+
+All surfaces using the shell topbar had scroll content clipped at the
+bottom by ~44px (the topbar height). Root cause: surface containers were
+siblings of `#shell-topbar` inside `.surface-inner`, which used
+`height: 100%` without flex layout — the surface div claimed the full
+parent height, ignoring the topbar sibling.
+
+- Fix: `.surface-inner` now uses `display: flex; flex-direction: column`
+  so the topbar and surface share vertical space via flex layout.
+- All surface containers (`.surface-docs`, `.surface-admin`,
+  `.surface-settings`, `.surface-editor`, `.extension-surface`) changed
+  from `height: 100%` to `flex: 1; min-height: 0`.
+- Inline styles on `surface-team-admin` and `welcome-mount` templates
+  updated to match.
+
+**Modified files:**
+
+- `server/pages/templates/base.html` — `.surface-inner` gains flex column layout
+- `src/css/surfaces.css` — `.surface-docs`, `.surface-admin`, `.surface-settings`, `.surface-editor`
+- `src/css/extension-surface.css` — `.extension-surface`
+- `server/pages/templates/surfaces/team-admin.html` — inline style fix
+- `server/pages/templates/surfaces/welcome.html` — inline style fix
+- `docs/STARLARK-REFERENCE.md` — workspace, permissions, has_capability
+- `docs/EXTENSION-GUIDE.md` — capabilities, vector, user_permissions, gate_permission
+
+## v0.8.3 — Vector Column Type
+
+Extensions can now declare vector columns and perform similarity search.
+Three-tier progressive enhancement: native pgvector on Postgres, JSONB
+fallback without pgvector, TEXT fallback on SQLite.
+
+**Manifest: `db_tables` vector columns**
+
+- Declare `"vector(N)"` as a column type (N = dimension, 1–4096).
+- On Postgres with pgvector: native `vector(N)` type with auto-created
+  HNSW index (`vector_cosine_ops`).
+- On Postgres without pgvector: `JSONB` column.
+- On SQLite: `TEXT` column (JSON-encoded float arrays).
+
+**Starlark API**
+
+- `db.query_similar(table, column, vector=[], limit=10, filters={}, metric="cosine")`
+  — returns rows ordered by ascending cosine distance with injected `_distance` key.
+- `db.insert()` now accepts list values (serialized as JSON strings) for
+  vector column storage.
+
+**Internal**
+
+- Modified: `handlers/ext_db_schema.go` — `parseVectorDim`, `mapColType`
+  gains `hasPgvector` parameter, HNSW index creation for vector columns.
+- Modified: `sandbox/db_module.go` — `HasPgvector` in `DBModuleConfig`,
+  list support in `starlarkToGoValue`, `dbQuerySimilar` with pgvector and
+  fallback paths, `cosineDistance` helper.
+- Modified: `sandbox/runner.go` — wire `HasPgvector` from capabilities.
+- Modified: `handlers/extensions.go` — `SetCapabilities` on `ExtensionHandler`.
+- Modified: `server/main.go` — wire capabilities to extension handler.
+- Updated: `docs/STARLARK-REFERENCE.md` — vector similarity section.
+- New tests: 5 schema tests + 8 db module tests (13 total).
+
+## v0.8.2 — Capability Negotiation
+
+Extensions declare environment requirements in their manifest. The kernel
+validates at install time and exposes a runtime query for graceful degradation.
+
+**Manifest: `capabilities` block**
+
+- `capabilities.required` — array of capability names. Install is rejected
+  (HTTP 422) if any are unavailable. Rollback deletes the package row.
+- `capabilities.optional` — array of capability names. Install succeeds
+  regardless; extensions query at runtime via `settings.has_capability()`.
+
+**Detected capabilities:** `postgres`, `pgvector`, `object_storage`, `s3`,
+`workspace`.
+
+**Starlark API**
+
+- `settings.has_capability(name)` — returns `True` or `False`. Always
+  available (no permission required).
+
+**Admin API**
+
+- `GET /api/v1/admin/capabilities` — re-probes and returns current state.
+
+**Internal**
+
+- New: `handlers/capabilities.go` (detection, parsing, validation, admin handler).
+- New: `handlers/capabilities_test.go` (14 tests).
+- New: `sandbox/settings_module_test.go` (4 tests).
+- Modified: `handlers/packages.go` — replaced stub `checkCapabilities` with
+  real validation; `SetCapabilities` setter.
+- Modified: `handlers/packages_bundled.go` — bundled packages with unmet
+  required capabilities are skipped on startup.
+- Modified: `sandbox/settings_module.go` — `has_capability` builtin.
+- Modified: `sandbox/runner.go` — `capabilities` field + `SetCapabilities` setter.
+- Modified: `server/main.go` — `DetectCapabilities` at startup, wired to
+  runner and package handler, admin route registered.
+
+---
+
+## v0.8.1 — Workspace Module
+
+New `workspace` sandbox module. Managed disk directories for extensions
+that need a real filesystem (git, compilers, media tools).
+
+**workspace module (permission: `workspace.manage`)**
+
+- `workspace.create(name)` — create a workspace directory (idempotent). Returns absolute path. Enforces quota if `WORKSPACE_QUOTA_MB` > 0.
+- `workspace.path(name)` — get the absolute path of an existing workspace. Returns None if not found.
+- `workspace.list()` — list workspace names for this extension.
+- `workspace.delete(name)` — recursively remove a workspace (idempotent).
+- `workspace.usage(name)` — disk usage in bytes (10-second timeout on directory walk).
+
+**Configuration**
+
+- `WORKSPACE_ROOT` — mount point for extension workspaces (default `/data/workspaces`).
+- `WORKSPACE_QUOTA_MB` — per-extension quota in MB (default `0` = unlimited).
+
+**Internal**
+
+- New file: `sandbox/workspace_module.go`.
+- New permission constant: `ExtPermWorkspaceManage`.
+- Config: `WorkspaceRoot`, `WorkspaceQuotaMB` fields.
+- Runner wiring: `SetWorkspaceRoot()` setter, `buildModulesWithLibCtx` creates workspace module when permission granted.
+- Startup: `main.go` creates workspace root directory if writable, graceful degradation if not.
+- All directories scoped to `{WORKSPACE_ROOT}/{packageID}/{name}/`.
+- Security: name regex (`^[a-z][a-z0-9_]{0,62}$`), `filepath.Clean` + prefix check, `filepath.EvalSymlinks` for symlink escape detection.
+- 16 new tests (create, path, list, delete, usage, name validation, quota enforcement).
+
+## v0.8.0 — Files Module
+
+New `files` sandbox module. Bridges the existing ObjectStore (PVC/S3) into
+the Starlark sandbox with extension-scoped key namespacing.
+
+**files module (permissions: `files.read`, `files.write`)**
+
+- `files.put(name, content, content_type, metadata)` — store a file with optional metadata companion. Accepts string or bytes content. 50 MB default limit (configurable via `EXT_FILES_MAX_SIZE`).
+- `files.get(name)` — read a file. Returns dict with `content` (bytes), `content_type`, `size`, `metadata`. Returns None if not found.
+- `files.meta(name)` — read metadata only (no content transfer).
+- `files.list(prefix, limit)` — list files by prefix. Returns list of dicts. Filters out internal `_meta/` companions.
+- `files.delete(name)` — delete a file and its metadata companion. Idempotent.
+- `files.delete_prefix(prefix)` — delete all files under a prefix.
+- `files.exists(name)` — check existence without reading.
+
+**Internal**
+
+- New file: `sandbox/files_module.go`.
+- New permission constants: `ExtPermFilesRead`, `ExtPermFilesWrite`.
+- `ObjectStore` interface gains `List(ctx, prefix, limit)` method; implemented for PVC and S3.
+- Runner wiring: `SetObjectStore()` setter, `buildModulesWithLibCtx` creates files module when permission granted.
+- All keys scoped to `ext/{packageID}/`. Metadata stored as companion JSON at `ext/{packageID}/_meta/{name}`.
+- 16 new tests (15 files module + 1 PVC list).
+
 ## v0.7.12 — Concurrent Execution Primitive
 
 New `batch` sandbox module. Enables extensions to parallelize arbitrary

ROADMAP.md

@@ -1,6 +1,6 @@
 # Armature — Roadmap
 
-## Current: v0.7.12 — Concurrent Execution Primitive
+## Current: v0.9.x — Workflow Redesign + Multi-Surface Packages
 
 Self-hosted extensible platform kernel. Auth, identity, packages, Starlark
 sandbox, storage, realtime, and ops are kernel primitives. Everything else
@@ -9,548 +9,295 @@ is an extension.
 **Kernel capabilities:** Auth (builtin/mTLS/OIDC) · Users/teams/groups/RBAC ·
 Surfaces/extensions/libraries/workflows · Starlark sandbox (capability-gated) ·
 Object storage (PVC/S3) + ext_data tables · WebSocket hub + realtime pub/sub ·
-Audit log · Notifications · Scheduled tasks · Cluster registry + HA
+Audit log · Notifications · Scheduled tasks · Cluster registry + HA ·
-
+Extension composability (slots/contributes/cross-package calls)
-**Completed history:** v0.2.x–v0.5.x fully documented in `CHANGELOG.md`.
-Highlights: RBAC + settings cascade, event bus + triggers, SDK stabilization,
-workflow engine (multi-stage, team roles, signoff gate, public entry, SLA),
-package distribution, Notes surface (CM6, folders, tags, backlinks, graph),
-realtime primitive, Chat surface (chat-core library + surface + polish),
-upgrade test harness, cluster registry + HA.
 
 ---
 
-## v0.6.x — Completed (MVP + Hardening)
+## Completed — v0.6.x through v0.8.x
-
+
-All v0.6.x work is shipped and documented in `CHANGELOG.md`. Summary:
+All completed work is documented in `CHANGELOG.md`.
-
+
-| Version | Title | Key Deliverables |
+### v0.6.x — MVP + Hardening
-|---------|-------|-----------------|
+
-| v0.6.0 | Cluster Registry + HA | PG-backed node registry, heartbeat sweep, LISTEN/NOTIFY routing, self-eviction |
+| Version | Title |
-| v0.6.1 | Backup/Restore + Docs | `.swb` archive format, server-side backups, docs surface + 5 guides |
+|---------|-------|
-| v0.6.2 | Docs Polish + OpenAPI | Dark mode fix, topbar nav, `api_schema` manifest field, dynamic spec builder |
+| v0.6.0 | Cluster Registry + HA |
-| v0.6.3 | Dead Code Sweep | Registry install fix, dead Go/JS/HTML deletion, narrowed default bundle |
+| v0.6.1 | Backup/Restore + Docs |
-| v0.6.4 | Admin Health/Metrics | Cluster dashboard merged into Admin tab, block renderer `requires` removed |
+| v0.6.2 | Docs Polish + Dynamic OpenAPI |
-| v0.6.5 | Renderer Pipeline | `sw.renderers.register()` kernel primitive, unified markdown, docs rewrite |
+| v0.6.3 | Dead Code Sweep + Registry Fix |
-| v0.6.6 | Final Hardening | Dependency auto-activation, `ValidateManifest()`, OIDC nonce, ICD/SDK update |
+| v0.6.4 | Admin Health/Metrics + Cluster Merge |
-| v0.6.7 | Native mTLS | `TLS_MODE` config, `MTLSNativeProvider`, node-to-node mTLS, `armature-ca.sh` |
+| v0.6.5 | Renderer Pipeline + Docs Rewrite |
-| v0.6.8 | Cookie Fix + UI Roadmap | Cookie SameSite fix, UI hardening roadmap published |
+| v0.6.6 | Final Hardening |
-| v0.6.9 | Session Lifetime Config | Admin-configurable TTLs, idle timeout, "keep me logged in" |
+| v0.6.7 | Native mTLS |
-| v0.6.10 | Viewport Foundation | Single layout model, CSS zoom, 100dvh, dead shell deprecated |
+| v0.6.8 | Rebrand + Cookie Fix |
-| v0.6.11 | CSS Deduplication | Old primitive system retired, one class per concept |
+| v0.6.9 | Session Lifetime Config |
-| v0.6.12 | Extension CSS Isolation | Prefix enforcement via linter, all 12 in-tree packages migrated |
+| v0.6.10 | Viewport Foundation |
-| v0.6.13 | Responsive & Spacing | Spacing token scale (4px grid), tablet breakpoint |
+| v0.6.11 | CSS Deduplication |
-| v0.6.14 | Visual Polish | Stale fallback colors purged, fonts self-hosted, radius tokens |
+| v0.6.12 | Extension CSS Isolation |
-| v0.6.15 | User Display Audit | Batch user resolve API, `sw.users` SDK module |
+| v0.6.13 | Responsive & Spacing |
-| v0.6.16 | Usability Survey Gate | Four audit scripts, contrast/touch-target fixes |
+| v0.6.14 | Visual Polish |
-| v0.6.17 | Bug Fixes & Welcome | Notes folder fix, team member add fix, welcome auto-disable, zero default bundle |
+| v0.6.15 | User Display Audit |
-| v0.6.18 | CI Bundle Wiring | `BUNDLED_PACKAGES` env var wired into Gitea CI pipeline |
+| v0.6.16 | Usability Survey Gate |
-
+| v0.6.17 | Bug Fixes & Welcome |
----
+| v0.6.18 | CI Bundle Wiring |
-
+
-## v0.7.x — Test Infrastructure + Quality Gate
+### v0.7.x — Test Infrastructure + Quality Gate
-
+
-The v0.6.x series built the kernel. v0.7.x makes it provably correct.
+| Version | Title |
-
+|---------|-------|
-A full surface audit (docs/AUDIT-surfaces.md) found 7 cross-surface issues
+| v0.7.0 | Shell Contract + Surface Audit + Rebrand |
-and 18 surface-specific issues across Settings, Admin, Team Admin, and Docs.
+| v0.7.1 | Surface Runner Framework |
-Only Docs is properly built. The fix is three phases: (1) establish a shell
+| v0.7.2 | Package Runners + CI Gate |
-contract and bring all four primary surfaces to parity, (2) build a runner
+| v0.7.3 | Extension Shell Migration |
-framework for end-to-end browser tests, (3) automate those runners headlessly
+| v0.7.4 | Documentation + Surface Work |
-in CI.
+| v0.7.5 | Headless E2E + CI Gate |
-
+| v0.7.6 | Code Hygiene + Test Coverage |
-Design docs:
+| v0.7.7 | API Tokens + Extension Permissions |
-- `docs/DESIGN-shell-contract.md` — two-slot topbar, three navigation patterns, surface migrations
+| v0.7.8 | Bug Fixes & Admin Gaps |
-- `docs/DESIGN-surface-runners.md` — runner framework, requires declarations, headless E2E
+| v0.7.9 | Workflow Independence Audit |
-- `docs/AUDIT-surfaces.md` — full audit findings
+| v0.7.10 | Workflow Handoff + Assignment UI |
-
+| v0.7.11 | Query & HTTP Ergonomics |
-### v0.7.0 — Shell Contract + Surface Audit + Rebrand Cleanup
+| v0.7.12 | Concurrent Execution Primitive |
-
+
-Design doc: `docs/DESIGN-shell-contract.md`
+### v0.8.x — Storage Primitives + Composability (Kernel Complete)
-
+
-**Shell Infrastructure**
+| Version | Title |
-
+|---------|-------|
-| Step | Status | Description |
+| v0.8.0 | `files` Module |
-|------|--------|-------------|
+| v0.8.1 | `workspace` Module |
-| Shell topbar (two-slot model) | done | Kernel injects topbar into `surface-extension` template. Two named slots: **left** (defaults to manifest title) and **center** (`flex: 1`, for tabs/pickers/search). Home link, notification bell, and user menu always present. |
+| v0.8.2 | Capability Negotiation |
-| Topbar customization API | done | `sw.shell.topbar.setLeft(vnode)` overrides left slot. `sw.shell.topbar.setSlot(vnode)` sets center slot. `sw.shell.topbar.setTitle(str)` shorthand for text-only left. `sw.shell.topbar.hide()` / `.show()` for full-bleed surfaces. |
+| v0.8.3 | Vector Column Type |
-| Kernel tab CSS | done | `.sw-topbar__tabs` and `.sw-topbar__tab` classes for consistent tab styling in the center slot. Surfaces use these for free or style their own slot content. |
+| v0.8.4 | Documentation Refresh + Surface Sizing Fix |
-| Notification read broadcast | done | Backend emits `notification.read` and `notification.all_read` WS events. Bell listens for `.created`, `.read`, `.all_read`. Cross-surface sync without refetch. |
+| v0.8.5 | Extension Composability |
-| User menu reactivity | done | Emit `package.changed` (install/uninstall/enable/disable) and `auth.changed` (role/membership) WS events. UserMenu listens and re-fetches surface list. Most impactful single fix. |
-| Shell announcement global dismiss | done | Dismissed state persisted to localStorage keyed by content hash. Dismiss once, dismissed everywhere. |
-
-**Surface Migrations**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Settings → Pattern B (flat tabs) | done | Delete custom topbar + sidebar nav. 6 sections become flat tabs in topbar center slot. Content full-width. Fix Teams section: add team admin link, role display, leave action. Remove sessionStorage return URL logic. |
-| Admin → Pattern C (category tabs + sidebar) | done | Delete custom `admin-topbar`. `setLeft()` for favicon + "Administration". `setSlot()` for category tabs (People / Workflows / System / Monitoring). Admin sidebar (sub-navigation) unchanged — surface-owned, below the topbar. Bell + user menu come free from shell. Delete bespoke CatIcon renderer if using standard SVGs. |
-| Team Admin → Pattern B (flat tabs) | done | Delete custom topbar + sidebar nav. 5 sections (Members / Connections / Workflows / Settings / Activity — Groups removed) become flat tabs. Content full-width. `setTitle()` for team-specific name. Remove sessionStorage return URL. Fix signoff user display (`user_id` → `sw.users.displayName()`). |
-| Team Admin: remove Groups tab | done | 37-line dead-end. Read-only "No groups" with no create/docs/link. Remove until team-scoped group management is properly designed. |
-| Docs → Pattern A (default) | done | Delete explicit Topbar import. Shell topbar auto-renders with manifest title. Docs sidebar (document list) is in content area, unaffected. |
-
-**Error Handling + UX Pass**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Inline error states | done | Replace `catch { toast }` with inline error + retry on all list endpoints. New `.sw-inline-error` CSS primitive. Systematic pass across Settings, Admin, Team Admin. |
-| Empty state guidance | done | Every "No X" message gets one-line explanation + primary action (create button or doc link). Admin Groups, Workflows, Teams; Team Admin Workflows; Settings Notifications. |
-
-**Bug Fixes**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| evil-chat cleanup | done | ICD security tier: `finally` cleanup block + tighten `409` assertion. |
-| Workflow demo error surfacing | done | Replace silent `catch` with inline error + retry. |
-| Hello dashboard removal | done | Delete `packages/hello-dashboard/`. |
-
-**Rebrand**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Light-mode icon SVG | done | New `favicon-light.svg` — square icon, transparent bg, dark node fills. Rename current `favicon-light.svg` (wordmark) to `wordmark.svg`. |
-| Dark-mode wordmark SVG | done | New `wordmark-dark.svg` — light text for dark backgrounds. |
-| Light-mode raster assets | done | `favicon-light-32.png`, `favicon-light-256.png`. |
-| PWA manifest description | done | "Self-hosted extension platform — build, compose, and run extensions." |
-| REBRAND-SPEC.md | | Land into `docs/`. Find/replace patterns, validation checklist, asset inventory. |
-| base.html favicon swap | done | Verify theme swap works with new square light icon. |
-
-**Tests**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Shell topbar renders for extensions | done | Home, left slot, center slot, bell, user menu present. |
-| Topbar API (setLeft, setSlot, hide) | done | Custom content renders. Hide removes topbar. |
-| All 4 surfaces use shell topbar | done | No double topbars. Each pattern (A/B/C) renders correctly. |
-| User menu reactive to package install | | Install → menu updates without reload. |
-| Notification bell cross-surface sync | | Dismiss on Notes → clears on Chat. |
-| Inline error on API failure | | Error + retry shown, not empty list. |
-
-### v0.7.1 — Surface Runner Framework
-
-Design doc: `docs/DESIGN-surface-runners.md`
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Runner framework (`sw.testing`) | done | SDK module: suite/test/assert, lifecycle hooks, structured JSON results. |
-| `requires` declarations | done | Runner manifests declare dependencies. Missing packages → clean skip. |
-| Cleanup enforcement | done | `s.track(type, id)` auto-deletes in `afterAll`. No leaked state. |
-| Warning tier | done | pass / fail / warning. No silent catch swallowing. |
-| ICD runner migration | done | Refactor to `sw.testing`. Test logic preserved. |
-| SDK runner migration | done | Refactor to `sw.testing`. Domain suites preserved. |
-| Runner registry surface | done | `/s/test-runners` — list runners, run-all, results dashboard. |
-
-### v0.7.2 — Package Runners + CI Gate
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Notes runner | done | `requires: ["notes"]`. 3 suites (crud, folders, tags-search), 12 tests. |
-| Chat runner | done | `requires: ["chat", "chat-core"]`. 2 suites (conversations, messaging), 9 tests. |
-| Schedules runner | done | `requires: ["schedules"]`. 1 suite (crud), 5 tests. |
-| Workflow runner | done | `requires: ["content-approval"]`. 1 suite (lifecycle), 5 tests. |
-| Renderer runner | done | `requires: ["mermaid-renderer"]`. 1 suite (contract), 4 tests. |
-| Runner result API | done | `POST/GET /api/v1/admin/test-runners/results`. In-memory store, 4 Go tests. |
-| CI integration | done | `test-runners` stage in Gitea CI. Playwright driver, `wait-for-healthy.sh`. |
-| CI DinD networking fix | done | Resolve container IP via `docker inspect` — DinD port mapping doesn't expose to runner localhost. |
-
-### v0.7.3 — Extension Shell Migration
-
-Chat, Notes, and Schedules still use the old `sw.shell.Topbar` component,
-producing a double topbar (shell-injected + surface-owned). Migrate all
-three to the v0.7.0 shell contract (`sw.shell.topbar.setTitle/setSlot`),
-same pattern as the kernel surface migrations.
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Chat → shell topbar | done | Delete `<Topbar>`, use `setTitle('Chat')` + `setSlot()` for thread title/people button. |
-| Notes → shell topbar | done | Delete `<Topbar>`, use `setTitle('Notes')` + `setSlot()` for action buttons. |
-| Schedules → shell topbar | done | Delete `<Topbar>`, use `setTitle('Schedules')` + `setSlot()` for count/new button. |
-| Update package runner tests | done | Shell-topbar test suite in each runner — assert no legacy Topbar, uses shell API. |
-
-### v0.7.4 — Documentation + Deferred Surface Work
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Docs category grouping | done | Backend `Category` field on doc entries. Frontend groups sidebar by category with headings. Four categories: Getting Started, Platform, Extension Development, Operations. |
-| Permissions & Groups guide | done | RBAC model, 7 permission slugs, system/custom groups, settings cascade, extension permissions. |
-| Workflows user guide | done | Entry modes, stages, team roles, signoff gates, SLA, public forms, branch rules, Starlark hooks. |
-| Starlark Reference | done | Sandbox constraints, 10 modules with function signatures, permission gates, example hook script. |
-| Frontend JS Guide | done | Preact+htm runtime, 16 SDK modules with API reference, shell topbar patterns, CSS contract. |
-| Extension config_section docs | done | Manifest schema, backend discovery, frontend contract, example component. Added to Extension Guide. |
-| Docs content refresh | done | All 10 user-facing docs reviewed for v0.7.x accuracy: rebrand volume names, stale CSS vars, TLS_MODE env, self-hosted font notes, Architecture frontend section. |
-| Team Admin Workflows split | done | 722-line `workflows.js` split into 3 modules: `workflows.js` (router+CRUD), `workflow-editor.js` (editor+stages), `workflow-monitor.js` (assignments+monitor+signoff). |
-| Stale CSS variable fix | done | `--bg-2` references in `sw-shell.css` and `sw-primitives.css` replaced with `--bg-secondary`. |
-
-### v0.7.5 — Headless E2E + CI Gate
-
-| Step | Status | Description |
-|------|--------|-------------|
-| CI gating redesign | done | Fix path rules: `VERSION`/`scripts/*` deploy-only, `docs/*` no longer skips deploy, test-runners trigger on any code change. |
-| E2E smoke test harness | done | `ci/e2e-smoke-test.sh` + `ci/e2e-smoke-driver.js` — Playwright visits every surface, asserts topbar, no JS errors, home link. |
-| Screenshot-on-failure | done | Full-page screenshot + console log saved as CI artifacts. |
-| CI pipeline integration | done | Re-enable `test-runners` stage, add `e2e-smoke` stage. Failure blocks merge. |
-| Design docs landed | done | `docs/DESIGN-storage-primitives.md`, `docs/DESIGN-extension-composability.md`. Roadmap expanded through v1.0. |
-
-### v0.7.6 — Code Hygiene + Test Coverage
-
-Codebase analysis (April 2026) found 9 code smells from the chat gut and
-a test coverage gap in the store layer. Fix before v0.8.x kernel expansion.
-
-**Critical Fixes**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Remove channels from allowedViews | done | `db_module.go` — `ext_view_channels` does not exist. `db.view("channels")` crashes. |
-| Fix workflow.html dead routes | done | Template calls `/api/v1/channels/{id}/workflow/*` — routes moved to `/api/v1/public/workflows/`. Update template to match. Also fixed `RenderWorkflow` handler to use route param as entry token. |
-
-**Dead Code Removal**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Delete SeedTestChannel() | done | `database/testhelper.go` — inserts into nonexistent channels table. |
-| Remove RunContext.ChannelID | done | `sandbox/runner.go` — vestigial field, unused by any module. |
-| Remove webhook.ChannelID | done | `webhook/webhook.go` — vestigial struct field from chat era. |
-| Fix stale comments | done | `storage.go` key format, `prometheus.go` route pattern, `workflow_module.go` param name — reference dead `/channels` paths. |
-
-**Migration Hygiene**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Align SQLite migration numbering | done | SQLite 013 placeholder + renumber test_runner_type to 014. Compat rename in migrate.go. |
-| Document missing 008 | done | Comment in both 009 files explaining the gap (merged into 007). |
-
-**Test Gap Closure**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| store/ unit tests | done | Moved to v0.7.9. 17 SQLite store tests: workflow CRUD, stages, instances, lifecycle, tokens, users, groups. |
-| workflow/ routing unit tests | done | 82 tests: ResolveNextStage, ResolveStageByName, ParseStageConfig, evaluateCondition (all operators). |
-| middleware/ unit tests | done | 10 tests: RequirePermission, RequireAdmin, permission caching, RateLimiter (allow/deny/fail-open). |
-| InstallPackage decomposition | done | Moved to v0.7.9. Split into 7 phases: receiveUpload, parseAndValidateArchive, extractPackageAssets, registerPackage, applySchemaAndPermissions, resolveDependencies, checkCapabilities. |
-
-**Bug Fixes**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Remove Admin Storage tab | done | Dead weight under System — backend endpoint preserved for future Monitoring use. |
-| Fix backup download | done | `sw.auth.token()` → `sw.auth._getToken()`. Both "Download Backup" and server backup download buttons now work. |
-
-### v0.7.7 — API Tokens + Extension Permissions
-
-Personal access tokens (PATs) for programmatic API access, plus
-extension-declared user permissions for backend RBAC enforcement.
-Unblocks: E2E test auth, CI automation, extension permission gating,
-sidecar auth (v0.10.x).
-
-**API Tokens (PATs)**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| `api_tokens` table + migration | done | `id`, `user_id`, `name`, `token_hash`, `permissions` (JSON array), `expires_at`, `last_used_at`, `created_at`. PG + SQLite. |
-| Token store interface | done | `Create`, `GetByHash`, `ListForUser`, `Revoke`, `CleanExpired`, `UpdateLastUsed`. |
-| Token generation endpoint | done | `POST /api/v1/auth/tokens` — name, permissions (subset of user's), expires_at. Returns token once (plain text), stored as SHA-256 hash. |
-| Token management endpoints | done | `GET /api/v1/auth/tokens` (list mine), `DELETE /api/v1/auth/tokens/:id` (revoke). |
-| Admin token endpoint | done | `POST /api/v1/admin/tokens` — creates token for any user. Explicit admin action, audit logged. |
-| Auth middleware update | done | Accept `Bearer arm_pat_...` tokens alongside JWTs. Resolve user + scoped permissions from token. PAT requests skip refresh token flow. |
-| Permission scoping | done | Token permissions ⊆ creating user's resolved permissions at creation time. Validated on create. If user loses a permission later, token retains it until revoked (git model). |
-| Settings UI | done | Settings → API Tokens tab. Create, list, revoke. Show permissions, expiry, last used. Token value shown once on creation. |
-| Admin UI | done | Admin → People → user detail → "Create API Token" action. |
-| E2E test migration | done | Replace `ci/e2e-smoke-test.sh` login flow with PAT-based auth. Seed token via `ARMATURE_BOOTSTRAP_PAT=true`. |
-
-**Extension-Declared User Permissions**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| `user_permissions` manifest field | done | Extensions declare permissions users need: `"user_permissions": ["image-gen.use", "image-gen.admin"]`. |
-| Dynamic permission registry | done | On install: merge into valid permission set. On uninstall: remove. `AllPermissions` becomes `KernelPermissions + ExtensionPermissions`. |
-| Group UI update | done | Admin → Groups → permission checkboxes include extension-registered permissions, grouped by source package. |
-| `permissions` Starlark module | done | `permissions.check(user_id, "image-gen.use")` → resolves user's groups, returns bool. New permission: none required (read-only check against kernel data). |
-| `gate_permission` manifest field | done | Optional. If set, `ext_api.go` checks this permission before calling `on_request`. Extension doesn't execute for unauthorized users. |
-| `req["permissions"]` in request dict | done | `ext_api.go` resolves user permissions and includes them in the request dict. Extensions can check inline without the module. |
-
-### v0.7.8 — Bug Fixes & Admin Gaps
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Workflow landing page Start | done | Added `StartBySlug` handler + `/api/v1/workflow-entry/:scope/:slug` route. Landing page Start button now resolves scope/slug → workflow ID and creates instance. |
-| Workflow delete guard | done | Admin `DELETE /api/v1/workflows/:id` rejects team-scoped workflows (403). Team workflows must use team endpoint. Prevents accidental global template deletion. |
-| Package button cleanup | done | Delete button hidden for `bundled` packages via `IMMUTABLE_SOURCES` guard, matching Export/Update. |
-| Package export fetch | done | Export uses `fetch()` with auth token instead of `window.open()`. Handles errors, shows toast on missing assets. |
-| Settings CSS fix | done | Bottom padding increased to `--sp-12` on `.admin-settings-form`. Save button no longer cut off. |
-| Admin stage builder + links | done | Shared `StageForm` component between admin and team-admin. Public entry URL with copy button in admin workflow editor. |
-
-### v0.7.9 — Workflow Independence Audit
-
-Workflows must work end-to-end without chat or any 3rd-party package
-dependency. Chat, notifications, and other packages should *enhance*
-workflows but never be required for core operation.
-
-**RenderWorkflow Fix (critical)**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Fix RenderWorkflow() handler | done | Was a stub (always `stageMode = "custom"`, no data loaded). Now loads instance by token/ID, resolves current stage, populates all template data. |
-| Rename WorkflowPageData fields | done | `ChannelID` → `EntryToken`, `ChannelTitle` → `WorkflowTitle`, `ChannelDescription` → `WorkflowDescription`. Vestigial chat-era names removed. |
-| Align stage mode values | done | Template now uses Go constants (`form`, `review`, `delegated`, `automated`) instead of legacy names (`form_only`, `form_chat`). |
-| Remove dead chat UI | done | Chat CSS, split layout, `sendMessage()` function, and fallback chat branch all removed from `workflow.html`. Replaced with clean form/review/unsupported modes. |
-| Fix landing page mode mapping | done | `workflow-landing.html` conditionals updated to match Go stage mode constants. |
-| Update OpenAPI spec | done | `stage_mode` enum changed from `[custom, form_only, form_chat, review]` to `[form, review, delegated, automated]`. |
-
-**Verification & Testing**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Admin/team-admin UI audit | done | All workflow CRUD, monitoring, stage builder verified clean — zero chat/chat-core references. |
-| E2E workflow test | done | `ci/e2e-workflow-nochat.sh` — creates workflow via API, adds form+review stages, starts instance via public entry, verifies landing + execution pages. |
-| Store unit tests (SQLite) | done | 17 tests: workflow CRUD, stages, instances, lifecycle (advance/complete/cancel/stale), team scope, API tokens, users, groups. Carried from v0.7.6. |
-| InstallPackage decomposition | done | Split 400-line handler into 7 private methods: `receiveUpload`, `parseAndValidateArchive`, `extractPackageAssets`, `registerPackage`, `applySchemaAndPermissions`, `resolveDependencies`, `checkCapabilities`. Carried from v0.7.6. |
-
-**Bug Fixes (found during verification)**
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Entry token resolution | done | `RenderWorkflow()` passed route param (instance ID) as entry token. JS then sent instance ID to the advance API which expects entry token. Fixed: resolve actual token from `inst.EntryToken` + check `?token=` query param. |
-| Fieldset submit guard | done | `submitForm()` checked `FORM_TPL.fields` but not `.fieldsets` — progressive forms silently no-op'd on submit. Fixed: accept either. |
-| Stage advance status check | done | Template JS checked `result.status === 'advanced'` but API returns instance status (`active`/`completed`). Fixed: on 200 OK with `active` status, reload to render next stage. |
-
-**Discovered issues (deferred)**
-
-The audit uncovered deeper workflow UX gaps that are out of scope for v0.7.9:
-
-1. **Public→authenticated stage handoff** — After a public visitor completes their stages, the workflow advances to an authenticated stage (e.g. "classify"). The visitor sees the next stage's form + an auth error instead of a "thank you, we'll take it from here" message. The page should detect audience mismatch and show a completion/waiting screen.
-2. **Team member pickup UI** — No surface exists for team members to see workflow instances assigned to their team and claim/work on them. Currently only visible in team-admin monitoring.
-3. **Assignment flow** — No mechanism for team admins to assign a specific instance to a specific team member. The `workflow_assignments` table exists but has no admin UI for manual assignment.
-
-These will be addressed in a future version (see v0.7.10 below).
-
-### v0.7.10 — Workflow Handoff + Assignment UI
-
-Addresses the three UX gaps found during the v0.7.9 independence audit.
-The workflow engine and data model already support these flows — the
-missing pieces are page-level audience detection and team-facing UI.
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Public stage completion screen | done | `RenderWorkflow()` detects audience mismatch (team/system stage + unauthenticated visitor) and renders "Submitted Successfully" screen with reference ID. |
-| Team workflow inbox | done | Enhanced `AssignmentsTab` in team-admin: claim/unclaim/work actions, time-ago display, WS live updates. Fixed vestigial `channel_id` references. |
-| Manual assignment UI | done | "Assign" button on unassigned rows with team member dropdown. New `POST /api/v1/assignments/:id/assign` endpoint (requires `workflow.create` permission). |
-| Assignment notifications | done | Engine calls `notifyAssignment()` on assignment creation — notifies specific user or all team members via notification system. |
-| Team workflow instances endpoint | done | `GET /api/v1/teams/:teamId/workflow-instances` + cancel endpoint. `ListInstancesByTeam` store method (SQLite + PG). SDK methods added. |
-| API response enrichment | done | `ListByTeam` and `ListMine` handlers enrich assignments with `workflow_name`, `stage_name`, `sla_breached` by joining instance → workflow → version snapshot. Cached per-request. Same for `ListTeamInstances` with `instanceView` struct. |
-| Team middleware fix | done | `RequireTeamAdmin` / `RequireTeamMember` system-admin bypass was dead code (`c.Get("role")` never set). Fixed to check `PermSurfaceAdminAccess` via `resolveAndCachePerms`. |
-| SDK gap closure | done | Added `workflowAssignments` domain (claim/unclaim/complete/cancel/assign/mine), `teams.assignments`, `teams.workflowInstances`, `teams.cancelWorkflowInstance`. Fixed dead `workflows.cancel` route. |
-| E2E multi-stage test | done | `ci/e2e-workflow-handoff.sh`: public form → team review → claim → complete. Verifies audience mismatch screen, assignment creation, full lifecycle. |
-
-### v0.7.11 — Query & HTTP Ergonomics (was v0.7.10)
-
-Four additions to existing sandbox modules. No new files beyond tests,
-no schema changes. Motivated by real-world extension porting feedback:
-complex SQL decomposition and synchronous HTTP fan-out are the two
-remaining friction points for extensions migrating from native Go/Python.
-
-| Step | Status | Description |
-|------|--------|-------------|
-| `db.count()` | done | `db.count(table, filters={})` → int. `SELECT count(*) FROM ext_{pkg}_{table} WHERE ...`. Uses existing `starlarkFiltersToSQL` builder. Permission: `db.read`. |
-| `db.aggregate()` | done | `db.aggregate(table, column, op, filters={})` → single value. `op` ∈ {`count`, `sum`, `avg`, `min`, `max`}. Column name validated same as filter keys. Returns int/float/None. Permission: `db.read`. |
-| `db.query_batch()` | done | `db.query_batch(queries)` → list of result sets. Each query spec is a dict with `table` (required), `filters`, `order`, `limit`, `before`, `after`, `search_like` (all optional, same as `db.query`). Loops extracted `buildSelectQuery` helper internally. Permission: `db.read`. |
-| `http.batch()` | done | `http.batch(requests)` → list of response dicts (ordered). Each request dict: `method`, `url`, `body`, `headers`. Concurrent dispatch via goroutines capped at 10, `sync.WaitGroup` collection. Reuses existing `executeHTTPRequest` plumbing (SSRF checks, domain allowlist, body cap, timeout). Individual failures return error response dicts, don't abort batch. Permission: `api.http`. |
-| Tests | done | 21 new tests (14 db, 7 http). `db.count`/`db.aggregate` test empty table, filtered, type coercion, invalid op/column. `db.query_batch` test mixed specs, empty list, cap, missing table. `http.batch` test blocked domains, partial failure, mixed results, input validation. |
-
-### v0.7.12 — Concurrent Execution Primitive (was v0.7.11)
-
-New `batch` sandbox module. Enables extensions to parallelize arbitrary
-Starlark callables — including library function calls via `lib.require()`.
-The kernel manages concurrency (multiple `starlark.Thread` instances in
-goroutines); extensions stay single-threaded and synchronous from the
-author's perspective.
-
-Key insight: library exports loaded via `lib.require()` are frozen structs
-(immutable, safe to share across threads). Each concurrent branch gets
-fresh module instances (`db`, `http`, etc.) — same pattern as
-`buildRestrictedModules` in `triggers/schedule.go`.
-
-| Step | Status | Description |
-|------|--------|-------------|
-| Design doc | done | `docs/DESIGN-batch-exec.md`. Thread isolation model, module construction, error semantics (partial results on failure), permission model, concurrency cap. |
-| `batch.exec()` | done | `batch.exec(callables)` → `(results, errors)` tuple. List of Starlark callables (lambdas, function refs). Each runs in its own `starlark.Thread` with fresh modules. Concurrent goroutines capped at 8. Ordered results. Errors are per-callable (None on success, string on failure). Permission: `batch.exec` (new). New file: `sandbox/batch_module.go`. |
-| Runner wiring | done | `buildModulesWithLibCtx` creates `batch` module when `batch.exec` permission granted. Module receives runner reference for per-branch module construction. |
-| Tests | done | 12 unit tests: parallel execution ordering, partial failure, timeout per-branch, parent cancellation, cap enforcement, empty list, non-callable, permission gating, frozen struct sharing, nested batch.exec, default timeout, timeout clamping. All pass with `-race`. |
 
 ---
 
 ## Planned
 
-### v0.8.x — Storage Primitives
+### v0.9.x — Multi-Surface Packages + Workflow Redesign
 
-Design doc: `docs/DESIGN-storage-primitives.md`
+**v0.9.0 — Multi-Surface Packages** *(completed)*
 
-The last major kernel expansion. Completes the primitive set that the
+Packages declare a `surfaces` array with per-path access controls,
-entire extension ecosystem builds on. After v0.8.x, the kernel is
+titles, and layouts. Unified route tree dispatches between surface
-feature-complete for 1.0 — all new capabilities are extensions.
+rendering and ext API calls. `sw.navigate()` for client-side sub-path
+routing. Design doc: `docs/DESIGN-multi-surface.md`.
 
-**v0.8.0 — `files` Module**
+**v0.9.1 — Server-Side Sub-Path Routing** *(completed)*
 
-Bridge `ObjectStore` (PVC/S3) into the Starlark sandbox. Extension-scoped
+Consolidated root and catch-all route handlers into a unified dispatcher.
-key namespacing (`ext/{packageID}/`). Permissions: `files.read`,
+Added `aggregateAccess()` for early auth short-circuit on all-authenticated
-`files.write`. Metadata companions stored as sibling objects.
+packages. SDK seeds initial history state for back-button resilience.
+8 handler integration tests + 5 aggregateAccess unit tests.
 
-New: `sandbox/files_module.go`. Modified: runner wiring, permission
+**v0.9.2 — Starlark Converter Consolidation + Snapshot Cleanup** *(completed)*
-constants.
 
-**v0.8.1 — `workspace` Module**
+Consolidated duplicate Go↔Starlark converters into `sandbox/convert.go`
+(4 exported functions) and snapshot parsers into `models/snapshot.go`.
+Standardized on wrapped snapshot format. ~350 lines of duplication removed.
+Design doc: `docs/DESIGN-workflow-redesign.md`.
 
-Managed disk directories for tools that need a real filesystem (git,
+**v0.9.3 — Team User Roles** *(completed)*
-compilers, media tools). `workspace.create(name)` → scoped path.
-Permission: `workspace.manage`. Quota enforcement via `WORKSPACE_QUOTA_MB`.
 
-New: `sandbox/workspace_module.go`. Modified: runner wiring, permission
+Many-to-many `team_user_roles` table. `RequireRole()` middleware.
-constants.
+Manifest `requires_roles` field (advisory). Starlark `teams` module
+with `get_member_roles()` and `has_role()`. Team-admin UI with role
+badge chips and assignment dropdown. 10 new tests.
 
-**v0.8.2 — Capability Negotiation**
+**v0.9.4 — Package Adoption + Roles** *(completed)*
 
-Extensions declare environment requirements in manifest (`capabilities.required`,
+`adoptable` manifest field + `team_role_catalog` table. When a team
-`capabilities.optional`). Kernel validates at install time. Runtime query
+adopts an adoptable package, the package's `requires_roles` auto-populate
-via `settings.has_capability()`. Admin endpoint: `GET /admin/capabilities`.
+into the team's role catalog. Adopted packages reference the original via
+`adopted_from` column (shared assets, no disk duplication).
+`AdoptTeamWorkflow` deprecated in favor of package-level adoption.
+4 new endpoints, migration 017, 11 new tests.
 
-Detected capabilities: `pgvector`, `workspace`, `object_storage`, `s3`,
+**v0.9.5 — Typed Forms → SDK Primitive** *(completed)*
-`postgres`.
 
-New: `handlers/capabilities.go`. Modified: install handler, settings module.
+Extracted `TypedFormTemplate`, `FormField`, `FormFieldset`, etc. from
+`models/workflow.go` into a standalone `forms` package. REST endpoint
+`POST /api/v1/forms/validate`. Starlark `forms.validate()` module.
+FE SDK: `sw.forms.render()`, `sw.forms.validate()`, `sw.forms.validateRemote()`.
+Manifest `form_template` accepted at package level. 16 new tests.
 
-**v0.8.3 — Vector Column Type**
+**v0.9.6 — Deprecate `stage_type`, Collapse `stage_mode`** *(completed)*
 
-`"vector(N)"` in `db_tables` manifest. Maps to native `vector(N)` on
+`stage_type` deprecated (no longer validated, defaults to "simple").
-PG+pgvector, `JSONB` on PG without, `TEXT` on SQLite. New `db.query_similar()`
+`stage_mode` collapsed from 4→3 values: form / delegated / automated.
-with dual-path dispatch (native operator vs Go-side brute force).
+"review" mapped to "form" on input; review surface removed (~110 lines).
+Migration 018. 4 package manifests updated.
 
-Modified: `ext_db_schema.go`, `db_module.go`.
+**v0.9.7 — Full Read/Write Workflow Starlark Module** *(completed)*
 
-**v0.8.4 — Extension Composability**
+`WorkflowEngine` interface extracted in sandbox package to break
+circular import. Four write builtins added: `workflow.start()`,
+`workflow.advance()`, `workflow.cancel()`, `workflow.submit_signoff()`.
+`instanceToDict` and `signoffToDict` helpers shared by read+write paths.
+6 new tests.
 
-Design doc: `docs/DESIGN-extension-composability.md`
+**v0.9.8 — Conditional Routing → SDK Primitive** *(completed)*
 
-Manifest declarations for `slots` (host surfaces declare injection points)
+`routing.evaluate(rules, data)` Starlark builtin — a generic decision
-and `contributes` (extensions declare UI contributions to other packages'
+engine reusable by any extension. 10 operators (exists, not_exists, eq,
-slots). `lib.require()` relaxed from library-only to any package with
+neq, gt, lt, gte, lte, in, contains), first-match-wins, returns target
-`exports` — enables full packages (with surfaces, settings, UI) to also
+string or None. Always available (pure computation, no permission).
-expose callable backend functions. `sw.slots.renderAll()` SDK helper.
+8 new tests.
-Admin slot aggregation endpoint.
 
-The composability primitive that enables: LLM tool registration, UI
+**v0.9.9 — Surface Access via Roles**
-contribution (toolbar buttons, image actions), and cross-extension
-function calls. No new tables, migrations, or permissions.
 
-Modified: `sandbox/lib_module.go` (~1 line), `handlers/extensions.go`,
+Wire team roles (v0.9.3) into surface access declarations:
-`src/js/sw/sdk/slots.js`. New: `handlers/admin_slots.go`.
+`access: role:approver`. Kernel middleware checks role membership.
+Completes the workflow→package access story.
 
 ---
 
-### v0.9.x — Reference Extensions
+### v0.10.x — Panels + Composable Layout
 
-The kernel is complete. This series proves the platform by shipping
+Panels are a new kernel rendering tier between surfaces (full-page) and
-first-party extensions that exercise every primitive. These are
+block renderers (inline). They solve composable companion views — e.g.,
-**extensions, not kernel code** — they ship as `.pkg` files and can be
+a notes reference panel inside chat. Design doc: `docs/DESIGN-panels.md`.
-uninstalled.
 
-**v0.9.0 — `vector-store` Library**
+| Version | Title |
-
+|---------|-------|
-Library extension: document ingestion, chunk storage, embedding persistence,
+| v0.10.0 | Panel Manifest + Lifecycle |
-semantic similarity search. Three-tier vector strategy (pgvector → JSONB
+| v0.10.1 | FloatingPanel Primitive |
-fallback → TEXT fallback). Consumes: `db.write`, `files.read`.
+| v0.10.2 | Docked Panels + Mode Transitions |
-
+| v0.10.3 | Panel Communication Patterns |
-**v0.9.1 — `llm-bridge` Library**
+| v0.10.4 | Reference Panel: Notes (basic) |
-
-Library extension: model abstraction, tool-use routing, provider BYOK via
-connections. Exposes `complete()`, `embed()`, `classify()`, `register_tool()`
-to consumer extensions. Tool extensions (image-gen, code-exec, web-search)
-register at load time — LLM discovers available tools automatically.
-Consumes: `connections.read`, `api.http`, `db.write`.
-
-**v0.9.2 — `file-share` Extension**
-
-File upload via `api_routes`, storage via `files` module, download links,
-optional team/group ACLs via resource grants. First extension to exercise
-the full `files` primitive end-to-end.
-
-**v0.9.3 — `code-workspace` Extension**
-
-Managed code repositories via `workspace` module. Git clone/pull via
-`api.http` to Gitea/GitHub API. File browser surface. Structural indexing
-(AST-aware) for code navigation. Consumes: `workspace.manage`, `files.write`,
-`api.http`.
-
-**v0.9.4 — `image-gen` + `image-edit` Extensions**
-
-Image generation via external APIs (DALL-E, Stable Diffusion). Registers
-as LLM tool with `llm-bridge`. Contributes regen/edit buttons to
-`chat:image-actions` slot. Image-edit extends with inpaint, outpaint,
-upscale, and style transfer — each contributing action buttons to the
-same slot independently. First full demonstration of the composability
-pattern: three extensions contributing UI to a fourth's surface.
-
-**v0.9.5 — Chat System**
-
-Generic 1-to-N human messaging. `chat-core` library (conversation/message
-CRUD) + `chat` surface. Declares `chat:message-actions`, `chat:image-actions`,
-`chat:composer-tools` slots for extension contribution. LLM participation
-as a follow-on consuming `llm-bridge`. Consumes: `db.write`,
-`realtime.publish`, `files.write` (attachments).
 
 ---
 
-### v0.10.x — Sidecar Tier + Polish
+### v0.11.x — Notes Reference Extension
 
-**v0.10.0 — Sidecar Tier**
+Notes becomes the first reference extension — a production-quality
+knowledge base that exercises every kernel primitive. The UI/UX redesign
+is front-loaded as v0.11.0 so every subsequent feature version builds on
+a clean visual foundation. Design doc: `docs/DESIGN-notes-v011x.md`.
 
-Autonomous out-of-process extensions for workloads that can't run in
+| Version | Title |
-Starlark: ML inference, media transcoding, language servers, local git
+|---------|-------|
-operations. The kernel does NOT manage container lifecycle — sidecars
+| v0.11.0 | UI/UX Foundation — visual redesign |
-are independent processes (Docker, systemd, bare binary) that connect
+| v0.11.1 | Deep Folders + Navigation |
-inward to the kernel, following the cluster registry pattern:
+| v0.11.2 | Wikilinks + Backlinks |
+| v0.11.3 | Live Preview + Rich Editing |
+| v0.11.4 | Note Sharing + Permissions |
+| v0.11.5 | Graph + Outline Hardening |
+| v0.11.6 | Quick Switcher + Commands |
+| v0.11.7 | Daily Notes + Templates |
+| v0.11.8 | Transclusion + Embeds |
+| v0.11.9 | Composability: Slots + Actions |
+| v0.11.10 | Panel Enhancement + Quality Gate |
 
-- Sidecar boots with cluster config (instance URLs, credentials).
+---
-- Connects and self-registers, declaring capabilities ("sklearn",
-  "gpu", "ffmpeg", "sentence-transformers").
-- Goes inert until an admin authorizes (same flow as extension permissions).
-- Kernel dispatches work; sidecar returns results.
-- Heartbeat keeps registration alive; missed heartbeat = eviction.
 
-Communication channel TBD (WebSocket over existing event bus, gRPC, or
+### v0.12.x — Chat Reference Extension
-HTTP callback model — design doc required). Authentication via mTLS
-certs or registration tokens.
 
-This model eliminates k8s RBAC dependency for local deployments. The
+Chat becomes the second reference extension — human-to-human messaging
-kernel stays thin — it accepts registrations and dispatches work. The
+built entirely on Armature's extension architecture. Where notes proved
-sidecar brings its own compute and manages its own lifecycle.
+surfaces, panels, and storage, chat proves **realtime**, **cross-package
+composition**, and **extensible data models**. Chat is human-to-human
+first; AI participants arrive via `llm-bridge` (v0.13.x) extending chat
+through folder attributes and slot contributions.
+Design doc: `docs/DESIGN-chat-v012x.md`.
 
-**v0.10.1 — Native Dialog Audit**
+| Version | Title |
+|---------|-------|
+| v0.12.0 | UI/UX Foundation |
+| v0.12.1 | Conversation Folders + Attributes |
+| v0.12.2 | Reactions + Threads + Pins |
+| v0.12.3 | Rich Compose + Attachments |
+| v0.12.4 | @Mentions + Notifications |
+| v0.12.5 | Link Previews + Message Formatting |
+| v0.12.6 | Conversation Themes + Personality |
+| v0.12.7 | Composability: Slots + Actions |
+| v0.12.8 | Panels + Quality Gate |
 
-Replace `prompt()`/`confirm()`/`alert()` with `sw.dialog` SDK primitives.
+---
-Accessible, themed, promise-based. Small kernel SDK change that improves
-every surface.
 
-**v0.10.2 — Stability + Migration Tooling**
+### v0.13.x — Reference Libraries + Extensions
 
-Proper versioned migrations (post-MVP discipline). `armature migrate`
+Custom public root surface unblocks everything — anonymous visitors,
-CLI command. Backup/restore validation against reference dataset.
+landing pages, and the package registry. `llm-bridge` is the key
-Pre-1.0 schema freeze.
+library delivery — extends both notes and chat through composability
+primitives, and introduces the **tool meta-tool** pattern:
+`sw.actions.list()` becomes the LLM tool registry, so installing an
+extension = granting AI a new capability. Zero configuration.
+`armature.run` deployment is the dogfood gate at the end of the series.
+
+| Version | Title |
+|---------|-------|
+| v0.13.0 | Custom Public Root Surface |
+| v0.13.1 | `vector-store` Library |
+| v0.13.2 | `llm-bridge` Core Library |
+| v0.13.3 | `llm-bridge` → Chat: Multi-Persona Context + Tool Meta-Tool |
+| v0.13.4 | `llm-bridge` → Notes: AI Toolbar Actions |
+| v0.13.5 | `file-share` Extension |
+| v0.13.6 | Package Registry Extension |
+| v0.13.7 | `code-workspace` Extension |
+| v0.13.8 | `image-gen` + `image-edit` Extensions |
+| v0.13.9 | Tool Meta-Tool Hardening + Scoping |
+| v0.13.10 | `armature.run` Deployment |
+| v0.13.11 | Integration Quality Gate |
+
+---
+
+### v0.14.x — Sidecar Tier
+
+Connect-inward model: sidecars connect TO the kernel (no K8s RBAC, no
+service mesh, no DNS discovery). Instance sidecars (shared infrastructure)
+and user sidecars (personal local tools). Design doc:
+`docs/DESIGN-sidecar-v014x.md`.
+
+| Version | Title |
+|---------|-------|
+| v0.14.0 | Sidecar Registry + Auth |
+| v0.14.1 | Capability Registration + Execution |
+| v0.14.2 | Kernel API Access + Event Bus |
+| v0.14.3 | Manifest Integration + Admin Polish |
+| v0.14.4 | Reference Sidecar (`armature-embed`) + Instance Gate |
+| v0.14.5 | User Sidecars + Reference (`user-bridge`) + User Gate |
+
+---
+
+### v0.15.x — Polish + Stability
+
+| Version | Title |
+|---------|-------|
+| v0.15.0 | Native Dialog Audit |
+| v0.15.1 | Versioned Migrations + `armature migrate` CLI |
+| v0.15.2 | Pre-1.0 Schema Freeze + Upgrade Path Validation |
 
 ---
 
 ### v1.0.0 — Stable Release
 
-The kernel API surface is frozen. Extensions are the product.
+Kernel API surface frozen. Extensions are the product.
 
 Gate criteria:
 
 - All kernel Starlark modules documented with examples
 - All `api_routes` covered by OpenAPI spec
 - Upgrade path tested from v0.8.0 → v1.0.0
-- At least 3 reference extensions shipped and tested (vector-store, llm-bridge, chat)
+- Notes reference extension shipped with all v0.11.x features
-- At least 1 cross-extension composability demo (image-gen → chat:image-actions)
+- Notes UI/UX reviewed against v0.11.0 design principles — no placeholder UI
+- Chat reference extension shipped with all v0.12.x features
+- `llm-bridge` extends both notes and chat through composability
+- Tool meta-tool demonstrated: AI uses 3+ extension actions in a
+  single conversation turn
+- Multi-persona context archetypes demonstrated
+- Admin safety rails validated
+- At least 2 panels consumed cross-package
+- At least 2 slot contributions per host surface demonstrated
+- Note and conversation sharing functional end-to-end
 - Headless E2E green on PG + SQLite
 - `armature-ca.sh` + mTLS deployment guide
 - Single-binary + Docker + K8s deployment paths documented
+- Instance sidecar (`armature-embed`) deployed and functional
+- User sidecar (`user-bridge`) functional on macOS/Linux/Windows
+- Token + mTLS sidecar auth both tested
+- `armature migrate` CLI functional
 
 ---
 
@@ -592,28 +339,33 @@ These are candidates, not commitments. Each requires a design doc.
 | Single Docker image | Go binary + assets + migrations. |
 | Admin → RBAC group | Grant check replaces role check. |
 | Settings cascade | Scope auth + `user_overridable`. Two orthogonal axes. |
-| No new migrations pre-MVP | Proper versioned migrations post-MVP. |
 | Chat as extension, not kernel | Zero kernel awareness. Proves extensibility thesis. |
 | PG as consensus layer | UNLOGGED node_registry + LISTEN/NOTIFY. No etcd/Consul/Redis. |
 | Two trigger tiers | Extension-declared (full sandbox) vs user ad-hoc (restricted). |
-| Builtin package rationale | Must enhance kernel surfaces or demonstrate platform capabilities. |
+| Two-slot topbar model | Left slot (title/branding) + center slot (`flex: 1`, tabs/pickers). |
-| Two-slot topbar model | Left slot (title/branding) + center slot (`flex: 1`, tabs/pickers). Two named slots cover every navigation pattern: simple title (Pattern A), flat tabs full-width (Pattern B), category tabs + surface-owned sidebar (Pattern C). Surfaces without sub-items get full content width; surfaces with hierarchical navigation add their own sidebar below the topbar. Shell provides the stage; surface decides the theater. |
+| `db` module is the structured store | No separate KV primitive. Extensions declare tables. |
-| All four primary surfaces migrate to shell topbar | Admin was "keep custom topbar" initially. The two-slot model makes it unnecessary — category tabs fit in the center slot, sidebar is surface-owned below. One topbar implementation replaces four. Bell + user menu + reactivity come free on every surface. |
+| `files` module rides ObjectStore | No new kernel tables. Metadata as companion objects. |
-| Settings / Team Admin → flat tabs (Pattern B) | Both had thin sidebars (~140px) that consumed width without justification. 5–6 sections fit cleanly in topbar tabs. Full-width content is a better use of space for these surfaces. |
+| `workspace` for real filesystem | Flat blob store can't serve git/compilers/ffmpeg. Managed disk paths. |
-| Team Admin Groups removed | 37-line read-only dead-end. Admin Groups has full CRUD. Restore when properly designed. |
-| Docs is the reference surface | Only surface with shell Topbar, bell, user menu, inline errors. Others converge. |
-| Surface runners over expanding ICD | Different test tier, different failure class. |
-| Headless E2E via Playwright | Runners produce structured JSON; Playwright navigates and reads output. |
-| `db` module is the structured store | No separate KV primitive. Extensions declare tables — infrastructure exists. |
-| `files` module rides ObjectStore | No new kernel tables. Metadata as companion objects. Works on PVC and S3 identically. |
-| `workspace` for real filesystem | Flat blob store can't serve git/compilers/ffmpeg. Managed disk paths are the explicit escape hatch. |
 | Capability negotiation at install | Fail loud with actionable message, not silently at runtime. |
-| Vector column with three-tier fallback | Works everywhere, works fast with pgvector. Documentation > hard gates. |
+| Vector column with three-tier fallback | Works everywhere, works fast with pgvector. |
-| Sidecar deferred to v0.10.x | HTTP module covers external APIs. Local compute is a v0.10.x concern. Sidecars connect inward (like cluster nodes), not spawned outward (no k8s RBAC needed). |
+| Sidecar deferred to v0.14.x | HTTP module covers external APIs. Sidecars connect inward (no k8s RBAC needed). |
-| No second scripting runtime | Starlark for glue, HTTP for external compute, sidecars for local compute. Three tiers with clear boundaries. Lua/WASM middle tier rejected — Turing-complete enough to be dangerous, not isolated enough to be trustworthy. |
+| Workflow redesign before reference extensions | Clean up debt and promote primitives before building on top. |
-| Reference extensions prove the platform | First-party `.pkg` files, not kernel code. Uninstallable. Dogfooding. |
+| Panels as kernel primitive (v0.10.x) | Z-index coordination, drag/resize, layout negotiation are kernel concerns. |
-| Composability via slots + exports, not kernel | `sw.slots` + `sw.actions` + `lib.require()` are the composition primitives. Manifest declarations add admin visibility. No inter-extension message bus — too complex, too fragile. |
+| UI/UX redesign as first version in each reference series | Every feature builds on the visual foundation. Front-loading avoids double work. |
-| Gut cleanup before kernel expansion | Codebase analysis found 9 smells from the chat gut. Fix before adding new primitives — dead views and broken templates compound when new code builds on them. |
+| Notes as dedicated v0.11.x series (11 versions) | Complex enough to need changeset discipline. Each version independently shippable. |
-| PATs over OAuth client credentials | PATs are simpler (one table, one middleware check), cover all use cases (E2E tests, CI, sidecars, user automation), and follow the git hosting convention users already understand. OAuth adds client registration, token exchange, scopes — complexity without benefit for a self-hosted platform. |
+| Notes before chat | Notes is simpler (no realtime) and proves storage/rendering/composability. Chat adds realtime + llm-bridge story. |
-| Extension-declared user permissions | Extensions register custom permissions in the kernel's group system. Admin assigns them to groups. Backend enforces via `permissions.check()` or `gate_permission`. Frontend hides via `sw.can()`. The kernel owns the permission registry; extensions contribute to it. |
+| Chat human-to-human first (v0.12.x) | AI is an extension concern. Keeps chat testable and usable standalone. |
-| Admin token as explicit action | Following Venice.ai pattern — admin token creation is a separate endpoint, audit logged, requires `surface.admin.access`. No ambiguity about the privilege level. |
+| Chat as dedicated v0.12.x series (9 versions) | Second reference extension. Proves realtime, extensible data models, cross-package composition. |
+| Folder attributes as extension bridge | Chat stores attributes it doesn't understand. llm-bridge contributes definitions. Zero coupling. |
+| Action registry as tool registry (meta-tool) | Dynamic, zero-config AI tool-use. Installed extensions = AI capabilities. Uniquely Armature. |
+| Layered prompt architecture (6 layers) | Admin safety not overridable. Clear separation: platform → space → character → context → tools → user. |
+| Personas in llm-bridge, not chat | Chat sees AI as just another participant_type. Persona identity is llm-bridge's concern. |
+| llm-bridge after notes + chat (v0.13.x) | Proves the composability hooks work without being designed for a specific consumer. |
+| Custom public root first in v0.13.x | Unblocks registry, landing page, and armature.run. Small kernel change, high leverage. |
+| Package registry as reference extension | Proves public surfaces work. Needs files module for .pkg storage. Self-referential: Armature's registry runs on Armature. |
+| armature.run as dogfood gate | If armature.run can't run on Armature, the platform isn't ready. Issues feed into quality gate fixes. |
+| Sidecar connect-inward | No K8s RBAC, no service mesh, no DNS discovery. Works on any deployment target. |
+| Sidecar HTTP/JSON, not gRPC | KISS. 4-endpoint contract. Every language has HTTP. |
+| User sidecars in v0.14.5 | Prove instance contract first, extend to users with same mechanism. |
+| Three-layer user sidecar RBAC | Admin controls who + what, user controls visibility. Defense in depth. |
+| Separate polish (v0.15.x) | Security-critical sidecar infra and quality-of-life polish shouldn't share focus. |

VERSION

@@ -1 +1 @@
-0.7.11
+0.9.8

ci/e2e-workflow-handoff.sh

@@ -127,7 +127,7 @@ STAGE2_RESP=$(curl -sf -X POST "${SERVER_URL}/api/v1/workflows/${WF_ID}/stages"
   -H "$AUTH" -H "Content-Type: application/json" \
   -d "{
     \"name\": \"Team Review\",
-    \"stage_mode\": \"review\",
+    \"stage_mode\": \"form\",
     \"audience\": \"team\",
     \"ordinal\": 1,
     \"assignment_team_id\": \"${TEAM_ID}\"

ci/e2e-workflow-nochat.sh

@@ -125,7 +125,7 @@ REVIEW_RESP=$(curl -sf -X POST "${SERVER_URL}/api/v1/workflows/${WF_ID}/stages"
   -H "$AUTH" -H "Content-Type: application/json" \
   -d '{
     "name": "Manager Review",
-    "stage_mode": "review",
+    "stage_mode": "form",
     "ordinal": 1
   }' 2>/dev/null || echo '{"error":"failed"}')
 

docs/API-REFERENCE.md

@@ -184,3 +184,30 @@ Kernel event prefixes: `user.*`, `team.*`, `workflow.*`, `notification.*`, `pres
 | POST | `/presence/heartbeat` | Update presence status |
 | GET | `/presence` | Query online users |
 | GET | `/users/search` | Search users |
+
+### Forms (v0.9.5)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/forms/validate` | Validate form data against a typed template |
+
+**Request body:**
+
+```json
+{
+  "template": {
+    "fields": [
+      {"key": "name", "type": "text", "label": "Name", "required": true}
+    ]
+  },
+  "data": {"name": "Alice"}
+}
+```
+
+**Response:**
+
+```json
+{"valid": true, "errors": []}
+```
+
+On validation failure, `errors` contains `[{"key": "name", "message": "Name is required"}]`.

docs/AUDIT-surfaces.md

@@ -1,209 +0,0 @@
-# Surface Audit — Settings, Admin, Team Admin, Docs
-
-## Audit Methodology
-
-For each surface: read the index.js (tab/section structure), read every
-section module, check the HTML template, trace the topbar/navigation
-pattern, identify bugs, missing features, dead ends, and legacy baggage.
-
----
-
-## 1. Settings Surface
-
-**Files:** `src/js/sw/surfaces/settings/` (7 files, ~868 lines)
-**Template:** `surfaces/settings.html` — mounts into `#settings-mount`
-**Topbar:** Custom — back arrow + user icon + "Settings" title. No bell. No user menu.
-
-### Sections
-
-| Section | Lines | Status | Notes |
-|---------|-------|--------|-------|
-| General | 62 | ✅ OK | Default surface picker. Clean. |
-| Appearance | 78 | ✅ OK | Theme toggle (light/dark/system) + UI scale slider. |
-| Profile | 180 | ✅ OK | Display name, email, avatar upload, password change. |
-| Teams | 47 | ⚠️ Thin | Read-only list of your teams. No actions. No link to team admin. |
-| Connections | 222 | ✅ OK | Personal BYOK connection CRUD. Functional. |
-| Notifications | 96 | ✅ OK | Toggle notification types on/off. |
-
-### Issues Found
-
-| # | Severity | Issue |
-|---|----------|-------|
-| S1 | **P1** | **No notification bell.** Custom topbar renders back arrow + icon + "Settings" — no bell, no user menu dropdown. User can't see notifications or navigate to other surfaces without using the back button. |
-| S2 | **P2** | **Teams section is a dead-end.** Lists your teams with no actions — can't leave team, can't navigate to team admin, can't see team details. Just names. Should either link to team admin or show useful info. |
-| S3 | **P2** | **Back button uses sessionStorage return URL.** `sb_settings_return` stash means: open settings in a new tab → back goes to `/` (correct). But open settings from a deep link → back goes to referrer, which might be unexpected. Shell topbar with consistent home link would fix this. |
-| S4 | **P3** | **Extension config sections.** `__CONFIG_SECTIONS__` injection works but has no documentation. Extension authors don't know they can add settings sections. Needs a docs entry. |
-
-### Shell Topbar Migration
-
-Settings renders its own `settings-topbar`. With shell topbar injection:
-- **Option A (simple):** `sw.shell.topbar.hide()` and keep custom topbar. Works immediately.
-- **Option B (ideal):** Remove custom topbar. Shell topbar provides back + title + bell + user menu. Settings nav stays in the sidebar.
-- **Recommendation:** Option B. Settings topbar adds nothing the shell topbar doesn't. The back arrow just navigates to `/`.
-
----
-
-## 2. Admin Surface
-
-**Files:** `src/js/sw/surfaces/admin/` (13 files, ~2,522 lines)
-**Template:** `surfaces/admin.html` — mounts into `#admin-mount`
-**Topbar:** Custom — favicon + "Administration" + category tabs (People/Workflows/System/Monitoring) + UserMenu component. No notification bell.
-
-### Sections
-
-| Section | Category | Lines | Status | Notes |
-|---------|----------|-------|--------|-------|
-| Users | People | 152 | ✅ OK | User list, create, edit status/role. Functional. |
-| Teams | People | 178 | ✅ OK | Team list, create, member management. |
-| Groups | People | 207 | ✅ OK | Full CRUD — create, delete, permission toggles, member add/remove. Functional but **undocumented** (see issues). |
-| Workflows | Workflows | 163 | ⚠️ | CRUD + stage editor. `sw.api.workflows.list()` — needs same error-surfacing treatment as workflow-demo. |
-| Settings | System | 242 | ✅ OK | Comprehensive: default surface, registration, banner, message bar, footer, session TTLs, vault, package registry, email test. Actually solid. |
-| Storage | System | 76 | ✅ OK | Status cards, orphan cleanup. Clean. |
-| Packages | System | 391 | ⚠️ | Core feature. Large. Package list, install, uninstall, registry browse. **User menu doesn't update after install/uninstall** (main bug Jeff reported). |
-| Connections | System | 210 | ✅ OK | Global connection CRUD. |
-| Broadcast | System | 44 | ✅ OK | Send broadcast. Minimal. |
-| Backup | System | 162 | ✅ OK | Create/restore/download/delete. Works. |
-| Health | Monitoring | 209 | ✅ OK | Runtime, DB pool, cluster, extension metrics. |
-| Audit | Monitoring | 88 | ✅ OK | Audit log viewer with pagination. |
-
-### Issues Found
-
-| # | Severity | Issue |
-|---|----------|-------|
-| A1 | **P1** | **User menu not reactive to package changes.** `UserMenu` fetches surface list once on mount (`useEffect([authenticated])`). Installing/uninstalling a package doesn't trigger re-fetch. User must refresh the page to see new surfaces in the menu. Same for role changes (adding as team-admin). |
-| A2 | **P1** | **No notification bell.** Admin topbar has category tabs + UserMenu but no NotificationBell component. |
-| A3 | **P2** | **Groups: no documentation or inline help.** Admin Groups has full CRUD but zero explanation of what groups are, what permissions mean, or how the RBAC model works. "No groups" → user creates one → sees a list of permission slugs like `surface.admin.access` with no description. Every permission should have a human-readable description. |
-| A4 | **P2** | **Workflows: silent error potential.** `sw.api.workflows.list()` — if this fails, `catch (e) { sw.toast(e.message, 'error'); }` fires a toast but leaves the list empty. Better than workflow-demo's silent swallow, but the toast disappears and the user is left with an empty list + no context. Should show inline error state. |
-| A5 | **P2** | **Packages: no post-install feedback.** After installing a package, the package list refreshes (good) but the user menu doesn't update (bad — A1). User installs Notes, doesn't see it in the menu, thinks it's broken. |
-| A6 | **P3** | **Admin topbar favicon is hardcoded.** Line 142: `<img src="${BASE}/favicon.svg">`. Should respect light/dark theme favicon swap. |
-| A7 | **P3** | **Category icon rendering is fragile.** Custom compact SVG format (`C12 12 3\|M19.4 15...`) in `CatIcon`. Works but is unmaintainable — any icon change requires understanding the custom format. Should use standard SVG paths or lucide/feather icons. |
-
-### Shell Topbar Migration
-
-Admin has the most complex custom topbar — category tabs are genuinely useful navigation. Options:
-- **Option A (recommended):** `sw.shell.topbar.hide()`. Admin keeps its custom topbar but adds NotificationBell component to its existing right-side area next to UserMenu.
-- **Option B:** Shell topbar with `sw.shell.topbar.setSlot()` for category tabs. Works but requires rethinking the layout since shell topbar has fixed structure (home | title | slot | bell | user).
-- **Recommendation:** Option A for v0.7.0. Admin's custom topbar is bespoke enough to warrant keeping. Just wire in the bell.
-
----
-
-## 3. Team Admin Surface
-
-**Files:** `src/js/sw/surfaces/team-admin/` (7 files, ~1,119 lines)
-**Template:** `surfaces/team-admin.html` — mounts into `#team-admin-mount`
-**Topbar:** Custom — back arrow + "Team Admin: {team name}" title. No bell. No user menu.
-
-### Sections
-
-| Section | Lines | Status | Notes |
-|---------|-------|--------|-------|
-| Members | ~90 | ✅ OK | Member list, add, remove. Functional. |
-| Groups | 37 | ❌ Dead-end | Read-only "No groups" display. No create, no docs, no link to admin. |
-| Connections | ~120 | ✅ OK | Team-scoped connections. Same pattern as user/admin connections. |
-| Workflows | 723 | ⚠️ Massive | Three tabs: Workflows (CRUD + inline stage editor), Assignments (claim/release/complete), Monitor (active instances + signoff). This is 65% of the surface's code. |
-| Settings | 72 | ✅ OK | Team name + description. Clean. |
-| Activity | ~80 | ✅ OK | Audit log. Works. |
-
-### Issues Found
-
-| # | Severity | Issue |
-|---|----------|-------|
-| T1 | **P1** | **Groups is a dead-end.** 37 lines. Read-only list of team groups. No "Create Group" button. No explanation of what groups are. No link to Admin > Groups where creation actually happens. A team admin user who isn't a platform admin literally cannot create team groups. The Admin groups page supports `scope: team` but that creates a global group with team scope — it's unclear if team-admin should even see groups at all. |
-| T2 | **P1** | **Workflows "Adopt Global" — same silent-error class.** `sw.api.teams.availableWorkflows(teamId)` — if this fails, the catch fires a toast but the adopt panel shows "No global workflows available" — indistinguishable from "there genuinely aren't any" vs "the API errored." |
-| T3 | **P1** | **Workflows is disproportionately complex.** 723 lines — inline stage editor with mode/type selectors, SLA fields, stage reordering, team role assignment per stage. This is a full workflow designer embedded in a tab. It works but it's a maintenance burden and the UX is dense. Question: should this complexity live here or be a separate workflow-designer surface? |
-| T4 | **P1** | **No notification bell.** Same as Settings — custom topbar with no bell. |
-| T5 | **P2** | **No user menu.** Unlike Admin (which renders UserMenu), Team Admin has no user menu in its topbar. User can't navigate to other surfaces except via the back button. |
-| T6 | **P2** | **Signoff panel shows raw user_id.** Line 714: `<span>${s.user_id}</span>` — shows UUID instead of display name. Should use `sw.users.displayName(s.user_id)`. |
-| T7 | **P3** | **Back button uses sessionStorage.** Same pattern as Settings (`sb_team_admin_return`). Shell topbar would fix. |
-
-### Shell Topbar Migration
-
-Team Admin has a simple topbar (back + title). Direct replacement:
-- Shell topbar provides: home link + "Team Admin: {name}" title + bell + user menu.
-- Team name from `sw.api.teams.get(teamId)` → `sw.shell.topbar.setTitle('Team Admin: ' + team.name)`.
-- Delete the custom topbar entirely.
-
----
-
-## 4. Docs Surface
-
-**Files:** `src/js/sw/surfaces/docs/` (1 file, 313 lines)
-**Template:** `surfaces/docs.html` — mounts into `#docs-mount`
-**Topbar:** Imports and renders `shell/topbar.js` (the SDK Topbar component). **Only surface that uses the shell Topbar.**
-
-### Features
-
-| Feature | Status | Notes |
-|---------|--------|-------|
-| Document list sidebar | ✅ OK | Fetches from `/api/v1/docs`, renders nav links. |
-| Markdown rendering | ✅ OK | Uses `sw.markdown.renderSync()` + post-renderers (mermaid, katex). |
-| Document outline | ✅ OK | Parses H1-H4 from markdown, renders table of contents. |
-| Search | ✅ OK | Filters documents in sidebar. |
-| URL updates | ✅ OK | `history.replaceState` on doc change. |
-| Topbar | ✅ OK | Uses shell `Topbar` component — has title, bell, user menu. |
-
-### Issues Found
-
-| # | Severity | Issue |
-|---|----------|-------|
-| D1 | **P2** | **Stale content.** The docs themselves may be outdated — GETTING-STARTED, EXTENSION-GUIDE, API-REFERENCE, DEPLOYMENT, PACKAGE-FORMAT were written in v0.6.1. 18 versions later, some content is likely stale. Needs a content review pass. |
-| D2 | **P3** | **No docs for RBAC/Groups.** Admin Groups exists with full CRUD but there's no documentation explaining the permission model, what each permission slug means, how groups interact with teams, or how the settings cascade works. This directly causes the "groups WTF" reaction. |
-| D3 | **P3** | **No docs for Workflows.** The workflow engine is complex (multi-stage, team roles, signoff gates, SLA, public entry) but has no user-facing documentation. `DESIGN-WORKFLOWS.md` exists but is a design doc, not a user guide. |
-| D4 | **P3** | **Shell topbar migration.** Docs already imports `shell/topbar.js` — when shell topbar injection lands, Docs will get a double topbar. Needs migration: delete the import, let shell topbar handle it. Docs currently passes no custom slot content, so it's a pure delete. |
-
----
-
-## Cross-Surface Issues
-
-These affect multiple or all surfaces:
-
-| # | Severity | Issue | Surfaces |
-|---|----------|-------|----------|
-| X1 | **P0** | **User menu not reactive.** Package install/uninstall, role changes, team membership changes — none trigger a menu refresh. User must reload the page. | All (via UserMenu component) |
-| X2 | **P1** | **No notification bell on 3/4 surfaces.** Only Docs has a bell (via Topbar import). Settings, Admin, and Team Admin all lack it. | Settings, Admin, Team Admin |
-| X3 | **P1** | **No user menu on 2/4 surfaces.** Settings and Team Admin have no user menu at all. Admin and Docs have one. | Settings, Team Admin |
-| X4 | **P2** | **Every surface has its own topbar.** Four different topbar implementations. None use the (not-yet-existing) shell topbar injection. Shell topbar (v0.7.0) eliminates this duplication. | All |
-| X5 | **P2** | **Silent error swallowing.** Multiple sections use `catch (e) { toast }` which fires a toast and leaves an empty/stale UI. Toast disappears after seconds; user is left confused. Every list endpoint needs an inline error state with retry. | Admin Workflows, Team Admin Workflows, Packages |
-| X6 | **P2** | **Empty states provide no guidance.** "No groups", "No workflows", "No notifications" — no explanation of what the feature is, why it's empty, or what action to take. Every empty state should have a one-line explanation and a primary action (create, link to docs, etc.). | Admin Groups, Team Admin Groups, Workflows |
-| X7 | **P3** | **Raw IDs in UI.** Team Admin signoff panel shows `user_id` UUIDs. Any surface showing IDs should resolve via `sw.users.displayName()`. | Team Admin Workflows |
-
----
-
-## Recommendations
-
-### Immediate (fold into v0.7.0)
-
-1. **User menu reactivity** — emit `package.changed` and `auth.changed` events over WS + local custom events. UserMenu listens and re-fetches surface list. This is the single most impactful fix.
-
-2. **Shell topbar migration for Settings + Team Admin** — both have simple topbars that the shell topbar directly replaces. Docs deletes its Topbar import. Admin keeps its custom topbar but adds NotificationBell.
-
-3. **Remove Team Admin Groups tab** — it's 37 lines of dead-end. Team-scoped group management should either (a) be added properly with create/edit/delete or (b) removed until it's properly designed. Showing "No groups" with no path forward is worse than not showing the tab.
-
-4. **Error states** — replace `catch { toast }` with inline error + retry UI on every list endpoint. Systematic pass across all four surfaces.
-
-5. **Empty state copy** — every "No X" message gets a one-line explanation + primary action button or doc link.
-
-### Deferred (v0.7.1+ / runner coverage)
-
-6. **Admin Groups documentation** — write a "Permissions & Groups" doc for the docs surface. Explain the RBAC model, list all permission slugs with descriptions, explain group scoping.
-
-7. **Workflow user guide** — write a "Workflows" doc. Entry modes, stage types, team roles, signoff gates, SLA.
-
-8. **Team Admin Workflows simplification** — the 723-line inline stage editor is the most complex piece of UI in the entire application. Consider extracting to a dedicated workflow-designer surface or at minimum breaking into separate files.
-
-9. **Docs content refresh** — review all 5 docs for accuracy at v0.6.18+.
-
-10. **Settings Teams section** — either add useful actions (link to team admin, show team role, leave team) or remove the tab.
-
----
-
-## Asset Inventory
-
-| Surface | Lines (total) | Sections | Custom Topbar | Bell | UserMenu | Error Handling |
-|---------|--------------|----------|---------------|------|----------|---------------|
-| Settings | 868 | 6 | Yes (back+icon) | ❌ | ❌ | Toast only |
-| Admin | 2,522 | 12 | Yes (tabs+menu) | ❌ | ✅ | Toast only |
-| Team Admin | 1,119 | 6 | Yes (back+title) | ❌ | ❌ | Toast only |
-| Docs | 313 | 1 | Shell Topbar ✅ | ✅ | ✅ | Inline error ✅ |
-
-Docs is the gold standard. The other three need to converge toward its pattern.

docs/DESIGN-extension-composability.md

@@ -1,7 +1,7 @@
 # DESIGN — Extension Composability
 
-**Version:** v0.8.4
+**Version:** v0.8.5
-**Status:** Draft
+**Status:** Implemented
 **Author:** Jeff / Claude session 2026-04-02
 
 ---

docs/DESIGN-notes-v011x.md

@@ -0,0 +1,744 @@
+# DESIGN: Notes Reference Extension — v0.11.x
+
+## Status: Proposed
+
+## Purpose
+
+Notes becomes the first **reference extension** — a first-party package
+that exercises every kernel primitive and proves the platform is capable
+of delivering a production-quality application. This is not a toy demo;
+it is the answer to "what can you build on Armature?"
+
+The v0.11.x series takes the existing notes package (folders, tags,
+wikilinks, graph, CM6 editor, three view modes) and builds it into a
+full-featured knowledge base comparable to Obsidian, Notion, or Logseq —
+but running on Armature's extension architecture.
+
+**The UI must be clean, inviting, and genuinely enjoyable to use.** The
+current notes surface is functional but visually mechanical — no
+personality, no micro-interactions, no sense of craft. If the reference
+extension feels like a developer prototype, the platform pitch fails
+regardless of how many kernel primitives it exercises. v0.11.0 is a
+full visual redesign before any feature work begins, and every subsequent
+version ships with UX quality built in, not bolted on.
+
+### What Notes Exercises
+
+| Kernel Primitive | How Notes Uses It |
+|-----------------|-------------------|
+| `db.write` | Notes, folders, tags, links, shares tables |
+| `sw.renderers` | Markdown rendering pipeline, custom block renderers |
+| `sw.panels` | `notes.reference` panel (from v0.10.4) |
+| `sw.slots` | Declares `notes:toolbar-actions`, `notes:note-footer` for extension composition |
+| `sw.events` | Realtime updates, panel ↔ surface communication |
+| `sw.markdown` | Unified markdown rendering with wikilink extensions |
+| `sw.shell.topbar` | Topbar slots for navigation context |
+| `sw.storage` | Editor state, sidebar collapse, preferences |
+| `sw.actions` | Exports `notes.create`, `notes.search` for cross-package calls |
+| Resource grants | Note and folder sharing via kernel permission model |
+| Starlark sandbox | All backend logic in `script.star` |
+| Settings cascade | Per-user editor mode, default view, daily note folder |
+| Surfaces | Multi-surface: full editor + public read-only surface |
+
+---
+
+## What Already Exists (v0.9.0)
+
+### Frontend (1,806 lines — `js/main.js`)
+
+- **NotesApp** — main shell with sidebar + editor layout
+- **FolderTree / FolderNode** — tree with expand/collapse, context menu,
+  drag-and-drop note→folder, rename, create sub-folder (schema has
+  `parent_id`, UI renders depth)
+- **NoteCard** — list items with title, snippet, date, tags, drag handle
+- **TagInput / TagFilter** — tag CRUD with autocomplete
+- **EditorPane** — three view modes (rendered / edit / split), CodeMirror
+  6 integration with textarea fallback, auto-save, frontmatter parsing
+- **BacklinksPanel** — lists notes that link to the current note
+- **SidebarTabs** — Notes / Outline tabs
+- **SidebarOutline** — heading tree parsed from markdown body
+- **GraphPane** — canvas-based force-directed graph with folder coloring,
+  orphan hiding, focus mode, pan/zoom
+- **Export** — download note as `.md` with frontmatter
+
+### Backend (23K — `script.star`)
+
+- Full CRUD: notes, folders, tags
+- Wikilink extraction (`_extract_wikilinks`) and link resolution
+  (`_sync_links`) on every note save
+- Links / backlinks queries
+- Graph data endpoint (nodes + edges)
+- Search (title + body substring)
+- Stats endpoint
+- Folder CRUD with `parent_id`
+
+### Schema (4 tables)
+
+- `notes` — title, body, folder_id, creator_id, updated_at, pinned, archived
+- `tags` — note_id, tag
+- `links` — source_id, target_id, link_text
+- `folders` — name, parent_id, creator_id, sort_order
+
+### Current CSS (795 lines — `css/main.css`)
+
+Functional but visually flat. No animations, no keyframes, no
+micro-interactions. Identical `transition: var(--transition)` on every
+hover. No typographic hierarchy beyond font-size/weight. No visual
+rhythm. Sidebar and editor feel like admin panels, not a writing tool.
+
+---
+
+## Version Plan
+
+### v0.11.0 — UI/UX Foundation
+
+**Goal:** Complete visual redesign of the notes surface. Every pixel
+intentional. Every interaction feels crafted. This is the foundation
+that all subsequent feature versions build on.
+
+This is NOT a "make it pretty" pass on the existing CSS. It is a
+ground-up rethink of the notes UI with the understanding that this is
+the first thing people see when evaluating what Armature can do.
+
+**Design principles for notes:**
+
+- **Writing-first.** The editor area dominates. Generous whitespace.
+  Nothing competes for attention with the content the user is writing.
+- **Quiet chrome, loud content.** Sidebar, toolbar, and navigation fade
+  into the background. The note body is the visual anchor — clean
+  typography, comfortable line height, readable measure (60–80 chars).
+- **Progressive disclosure.** Folder tree, tags, backlinks, graph — all
+  there but not all visible simultaneously. Contextual — show what's
+  relevant to what the user is doing right now.
+- **Micro-interactions that feel alive.** Folder expand/collapse with
+  rotation animation. Note cards with subtle lift on hover. Smooth
+  sidebar resize. Mode transitions that animate, not snap. Save
+  indicator that pulses, not just appears.
+- **Personality without kitsch.** The UI should feel like a well-designed
+  indie app, not a Material Design template and not a Bootstrap theme.
+
+**Specific deliverables:**
+
+**Typography overhaul:**
+- Rendered note body: system serif stack for body text (Georgia, serif
+  fallback) at 16px/1.7 line height. Headings in the system sans stack.
+  Comfortable reading measure — `max-width: 720px` centered in the
+  editor area with generous padding. Code blocks with distinct
+  background and a monospace stack.
+- Editor (CM6): matching font size and line height so switching between
+  rendered/edit mode doesn't jar. CM6 theme tokens aligned with note
+  design tokens.
+- Sidebar text: smaller (13px), tighter, utility font. Clear hierarchy
+  between folder names, note titles, snippet text, dates.
+
+**Sidebar redesign:**
+- **Resizable** — drag handle between sidebar and editor. Width persisted.
+  Smooth resize with no layout jank.
+- **Collapsible** — collapse to a thin icon strip (folder + search +
+  graph icons) on narrow viewports or by user choice. Expand on hover
+  or click. Collapse state persisted.
+- **Folder tree polish:** Indent guides (subtle vertical lines connecting
+  parent→child). Folder icons that change on expand (open folder / closed
+  folder, not just a triangle). Drop target highlighting with animation
+  (not just background color change). Smooth height animation on
+  expand/collapse.
+- **Note cards:** Subtle left border color-coded by folder (pulls from a
+  soft palette, not harsh primaries). Title, snippet, relative date
+  ("3h ago" not "2026-04-03T12:34"). Tag pills with rounded, muted
+  styling. Pin indicator as a subtle icon, not a text label.
+- **Search:** Inline search with clear button. Results highlight matching
+  text. Smooth appear/disappear.
+
+**Editor redesign:**
+- **Header:** Title input styled as a large heading (not an input field
+  with a border). Folder breadcrumb below title in muted text. Toolbar
+  actions as icon buttons with tooltips — no text labels cluttering the
+  header. Save status indicator (saved ✓ / saving… / unsaved •) as a
+  small, elegant badge.
+- **Mode switcher:** Segmented control (Read / Edit / Split) replacing
+  the cycling button. Clear visual state.
+- **Rendered view:** Clean markdown rendering with proper spacing between
+  elements. Block quotes with a left accent border. Tables with subtle
+  borders and alternating row tinting. Inline code with pill-style
+  background. Links with underline on hover only.
+- **Empty editor state:** "Select a note or create a new one" with a
+  softly illustrated empty state — not a plain text message.
+
+**Graph visual refresh:**
+- Dark-on-light node rendering with soft shadows (not flat circles with
+  outlines). Node labels that appear on hover with smooth fade-in.
+  Edge rendering with slight curves (not straight lines). Background
+  subtle dot grid.
+
+**Transitions and animations:**
+- Sidebar expand/collapse: 200ms ease-out slide.
+- Folder tree expand/collapse: 150ms height animation with children
+  fading in.
+- Note card hover: subtle translateY(-1px) + box-shadow lift.
+- View mode switch: crossfade (100ms fade out → swap → 100ms fade in).
+- Save indicator: pulse animation on "saving", check mark with brief
+  scale-up on "saved".
+- Graph node hover: scale(1.2) with spring easing.
+- Panel/dialog open: 150ms slide-up + fade-in (consistent with kernel
+  Dialog animation).
+
+**Color and theming:**
+- Notes should work beautifully in both light and dark themes.
+  Use CSS custom properties (already the pattern via `var(--bg-surface)`,
+  etc.) but add notes-specific tokens for accent colors, folder palette,
+  and typography:
+  ```css
+  --notes-body-font: Georgia, 'Times New Roman', serif;
+  --notes-body-size: 16px;
+  --notes-body-line-height: 1.7;
+  --notes-body-measure: 720px;
+  --notes-accent: var(--accent);
+  --notes-folder-1: #6366f1;  /* indigo */
+  --notes-folder-2: #8b5cf6;  /* violet */
+  --notes-folder-3: #ec4899;  /* pink */
+  --notes-folder-4: #f59e0b;  /* amber */
+  --notes-folder-5: #10b981;  /* emerald */
+  --notes-folder-6: #06b6d4;  /* cyan */
+  ```
+
+**Responsive:**
+- Below 768px: sidebar collapses to overlay (slide-in from left).
+  Editor goes full-width. Split view disabled. Touch-friendly tap
+  targets (44px minimum on all interactive elements).
+- Between 768px and 1024px: sidebar narrower (220px). Editor gets
+  remaining space.
+- Above 1024px: full layout with comfortable sidebar width.
+
+**What this version does NOT change:**
+- No new features. Same note CRUD, same folders, same tags, same
+  wikilinks, same graph, same three view modes.
+- No backend changes. No schema changes.
+- The existing JS components are restructured for the new layout but
+  retain their current behavior.
+
+**Deliverable:** Complete CSS rewrite (`css/main.css`), targeted JS
+changes for new layout structure (resizable sidebar, collapsible sidebar,
+mode switcher component, animation hooks), and updated component
+templates where the HTML structure needs to change for the new design.
+
+---
+
+### v0.11.1 — Deep Folders + Navigation
+
+**Goal:** Folders become a real hierarchy with breadcrumbs, not just a
+flat tree with parent_id.
+
+**Features:**
+
+- **Breadcrumb navigation** in editor header showing the folder path.
+  Click any segment to navigate to that folder's note list. Styled
+  consistently with the v0.11.0 muted-text breadcrumb design.
+- **Drag folder→folder** to reparent. Animated drop indicator shows
+  nesting target with indent guide preview. Depth limit: 5 levels.
+- **Folder sort** — drag to reorder within a level. Smooth reorder
+  animation. Persists via `sort_order` column (already in schema).
+- **Collapse/expand persistence** — expanded folder set stored in
+  `sw.storage` keyed by user.
+- **Move dialog** — select destination folder from a tree picker when
+  moving notes (alternative to drag for accessibility / many folders).
+  Uses `sw.ui.Dialog` with the new folder tree component inside.
+
+**UX standard:** All folder interactions use the animation language
+established in v0.11.0. Drop targets highlight with the folder color
+from the palette. Reparent shows a brief connection-line animation.
+
+**Backend changes:**
+
+- Validate `parent_id` chain on create/update (no cycles, depth ≤ 5).
+- Folder delete: require empty or offer cascade (move children to parent,
+  or move contained notes to Unfiled).
+- `_list_folders()` returns full tree with `children_count` and
+  `note_count` for each folder.
+
+**Schema:** No changes.
+
+---
+
+### v0.11.2 — Wikilinks + Backlinks
+
+**Goal:** `[[wikilinks]]` become a first-class editing and navigation
+primitive with autocomplete, previews, and unresolved link handling.
+
+**Features:**
+
+- **CM6 autocomplete** — typing `[[` triggers a fuzzy note title picker
+  with a clean dropdown styled consistently with the notes design
+  language (not browser-default autocomplete). Shows note title, folder
+  path, and snippet preview. Keyboard navigable.
+- **Wikilink rendering** — rendered markdown converts `[[Title]]` to
+  internal links with a subtle notes-specific style (dotted underline,
+  small link icon). Distinct from external URLs.
+- **Hover preview** — hovering a wikilink shows a floating card with
+  the target note's title, first ~200 chars rendered as markdown, and
+  folder/tag metadata. Smooth fade-in, positioned to avoid viewport
+  overflow. Same visual language as graph node hover cards.
+- **Unresolved links** — `[[Nonexistent Note]]` renders with a dashed
+  styling and a muted color. Click to create the note with that title
+  (pre-filled). Small "+" indicator on hover.
+- **Backlinks panel improvements:**
+  - Show context snippet (surrounding text with the `[[link]]`
+    highlighted).
+  - Group by folder with folder color indicators.
+  - Count badge in sidebar tab (animated increment on new backlinks).
+  - Navigate to the linking note and scroll to the link location.
+- **Aliases** — new `aliases` column on `notes` table. Autocomplete
+  searches both title and aliases.
+
+**UX standard:** Autocomplete dropdown uses the notes card styling.
+Hover preview card shares visual language with graph tooltips. Unresolved
+link creation is a smooth inline experience, not a navigate-away-and-back.
+
+**Backend changes:**
+
+- `_sync_links()` resolves aliases as well as titles.
+- New endpoint: `GET /autocomplete?q=...` — fast title+alias prefix
+  search (limit 10).
+- Backlinks response includes `context_snippet` field.
+
+**Schema changes:**
+
+- `notes` table: add `aliases` column (text, comma-separated).
+
+---
+
+### v0.11.3 — Live Preview + Rich Editing
+
+**Goal:** The editor becomes genuinely pleasant to write in — live
+preview that scrolls in sync, or an optional inline-formatted mode.
+
+**Features:**
+
+- **Split pane scroll sync** — scrolling the CM6 editor scrolls the
+  rendered preview to the corresponding position. Uses heading anchors
+  for coarse sync and line-height interpolation for fine sync.
+- **Live preview debounce** — rendered pane updates as you type with
+  150ms debounce. Smooth content transitions (no jarring reflow).
+- **Inline preview** (Obsidian-style) — optional mode where markdown
+  syntax hides and formatting appears inline while editing. CM6
+  decorations for bold, italic, headings, links, code blocks.
+  Syntax reappears when cursor enters the formatted region. This is
+  the "fourth mode" alongside rendered / edit / split — a true
+  WYSIWYG-ish editing experience without leaving markdown.
+- **Image paste** — paste from clipboard, upload via `files` module,
+  insert `![](url)` at cursor. Progress indicator during upload.
+  Fallback: base64 inline if `files` module unavailable.
+- **Table editing** — tab-to-next-cell, auto-expand columns, add
+  row/column with floating buttons on hover. Markdown tables become
+  usable instead of a formatting chore.
+
+**UX standard:** Split pane has an animated gutter with a subtle drag
+handle. Mode switcher expands to accommodate the fourth option (or
+becomes a dropdown if space is tight). Image paste shows a smooth
+inline loading skeleton.
+
+**Backend changes:**
+
+- Image upload endpoint: `POST /images` — receives multipart, stores
+  via `files` module, returns URL.
+
+**Schema:** No changes.
+
+---
+
+### v0.11.4 — Note Sharing + Permissions
+
+**Goal:** Notes become collaborative. Share a note or folder with
+a team, group, individual, or the public — with read-only or read-write
+permissions.
+
+**Share Model:**
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Share Scope              │ Granularity │ Permissions │
+├──────────────────────────┼─────────────┼─────────────┤
+│ Public (anonymous URL)   │ note only   │ read-only   │
+│ Team                     │ note/folder │ ro / rw     │
+│ Group                    │ note/folder │ ro / rw     │
+│ Individual (user)        │ note/folder │ ro / rw     │
+└──────────────────────────┴─────────────┴─────────────┘
+```
+
+**Folder sharing inherits:** sharing a folder grants access to all notes
+in that folder (and sub-folders). Individual note shares override folder
+permissions (higher wins).
+
+**Features:**
+
+- **Share dialog** — clean modal (using `sw.ui.Dialog`) with scope
+  selector, user/team/group picker (using `sw.ui.UserPicker` or new
+  entity picker), permission toggle, and copy-link button. Share URL
+  preview with visual indicator.
+- **Public notes surface** — new surface at `/s/notes/public/:share_id`.
+  Renders a single note in read-only mode with clean, minimal chrome.
+  Uses the v0.11.0 typography and rendered view styling. Armature
+  branding footer. No authentication required.
+- **Shared-with-me view** — sidebar section (new tab) showing notes/folders
+  shared by others. Grouped by owner with avatar. Visual distinction
+  from your own notes.
+- **Share indicators** — shared notes show a subtle share icon on the
+  note card. Folder tree shows share badge on shared folders. Hover
+  reveals share scope.
+- **Permission enforcement** — Starlark backend checks share permissions
+  on every read/write.
+- **Share revocation** — remove access from share dialog with
+  confirmation.
+
+**UX standard:** Share dialog is the most complex new UI in the series
+and must feel simple. One-click sharing for common cases (share with
+team, make public). Advanced options (specific users, groups) are
+available but not in the way. Copy-link button shows a brief "Copied!"
+toast. Public note surface is a showcase — the best the notes rendering
+can look.
+
+**Backend changes:**
+
+- New `note_shares` table.
+- New `folder_shares` table.
+- Access check function: `_can_access(user_id, note_id, permission)`.
+- `_list_notes()` includes shared notes with `shared_by` metadata.
+- Public note endpoint: unauthenticated GET by share_token.
+
+**Schema changes:**
+
+- New table: `note_shares` — note_id, share_type, target_id, permission,
+  share_token, created_by, created_at.
+- New table: `folder_shares` — folder_id, share_type, target_id,
+  permission, share_token, created_by, created_at.
+
+**Manifest changes:**
+
+- New surface: `/notes/public/:share_id` with `auth: "public"`.
+
+---
+
+### v0.11.5 — Graph + Outline Hardening
+
+**Goal:** The graph becomes a genuine navigation and discovery tool.
+The outline becomes a reliable TOC.
+
+**Graph improvements:**
+
+- **d3-force layout** — replace hand-rolled force sim with d3-force.
+  Better convergence, collision avoidance, centering. ~15KB optional
+  vendor (same pattern as CM6).
+- **Zoom controls** — explicit +/- buttons (styled as floating pills) plus
+  scroll-to-zoom. Reset-to-fit button.
+- **Minimap** — small overview in corner with viewport rectangle.
+  Draggable to navigate large graphs.
+- **Cluster by folder** — visual grouping with soft convex hulls in
+  folder colors (from the v0.11.0 palette). Toggle on/off.
+- **Filter by tag** — highlight matching nodes, dim others. Smooth
+  opacity transition.
+- **Search in graph** — highlight and smooth-pan to matching nodes.
+- **Hover card** — note title, snippet, folder, tag count. Same visual
+  language as wikilink hover preview (v0.11.2).
+
+**Outline improvements:**
+
+- **Scroll sync** — active heading highlights as user scrolls. Uses
+  `IntersectionObserver`. Smooth highlight transition.
+- **Click-to-scroll** — smooth scroll with brief heading highlight pulse.
+- **Indent levels** — h1→h6 with subtle indent guides matching the
+  folder tree style.
+- **Collapse/expand** — heading sections collapsible in outline.
+  Animated, consistent with folder tree animations.
+
+**UX standard:** The graph should feel like a discovery tool, not a tech
+demo. Interactions should be fluid — pan, zoom, hover, click — with no
+jank. The outline should feel like a table of contents in a well-typeset
+book.
+
+---
+
+### v0.11.6 — Quick Switcher + Commands
+
+**Goal:** Keyboard-driven navigation. Power users never touch the mouse.
+
+**Features:**
+
+- **Quick switcher** (`Cmd+O` / `Ctrl+O`) — centered overlay with fuzzy
+  search. Clean design: large input field, results below with note
+  title, folder path, and snippet. Recent notes above search results.
+  Arrow keys + Enter. Smooth open/close animation. Matches the visual
+  language of command palettes in VS Code / Raycast.
+- **Command palette** (`Cmd+Shift+P`) — same overlay style, listing all
+  available note actions as searchable commands. Extensible via
+  `sw.actions`.
+- **Keyboard shortcuts:** Registered via a central keymap.
+
+  | Shortcut | Action |
+  |----------|--------|
+  | `Cmd+O` | Quick switcher |
+  | `Cmd+Shift+P` | Command palette |
+  | `Cmd+N` | New note |
+  | `Cmd+S` | Save (in edit mode) |
+  | `Cmd+E` | Toggle edit/rendered |
+  | `Cmd+Shift+E` | Toggle split view |
+  | `Cmd+D` | Open today's daily note |
+  | `Cmd+G` | Toggle graph view |
+  | `Cmd+B` | Toggle backlinks panel |
+  | `Escape` | Close active panel/dialog |
+
+**UX standard:** The quick switcher is a high-frequency interaction —
+it must open instantly (no perceptible delay), search results must
+appear as-you-type, and the whole flow (Cmd+O → type → Enter) should
+take under 2 seconds for a user who knows what they want.
+
+---
+
+### v0.11.7 — Daily Notes + Templates
+
+**Goal:** Recurring note patterns that lower friction.
+
+**Daily notes:**
+
+- Auto-created daily note — navigating to "today" creates a note titled
+  `YYYY-MM-DD` in a configurable daily notes folder.
+- Daily note template — configurable template body.
+- **Calendar picker** — small, beautiful calendar widget in the sidebar.
+  Days with notes dot-marked. Styled as a subtle, compact component
+  (not a full-page calendar). Click a date to open that day's note.
+- Previous/next day nav arrows in editor header for daily notes.
+
+**Templates:**
+
+- Notes in a "Templates" folder are templates. No special type.
+- "New Note" dropdown offers template selection with preview.
+- Template variables: `{{date}}`, `{{time}}`, `{{title}}`, `{{folder}}` —
+  simple string replacement.
+- **Slash commands** in CM6 — typing `/` at line start shows a styled
+  command menu: `/template`, `/date`, `/time`, `/todo`, `/callout`,
+  `/table`, `/code`, `/divider`. Extensible via `sw.slots`.
+
+**UX standard:** The calendar picker should feel like a subtle,
+integrated part of the sidebar — not a jarring widget. Template
+selection should show a live preview of the template content.
+Slash commands should appear fast and be keyboard navigable.
+
+**Settings additions:**
+
+- `daily_note_folder` — folder name for daily notes.
+- `daily_note_template` — template body.
+- `template_folder` — folder name for templates.
+
+---
+
+### v0.11.8 — Transclusion + Embeds
+
+**Goal:** Notes reference and embed each other's content.
+
+**Features:**
+
+- **Transclusion** (`![[Note Title]]`) — embeds referenced note content
+  inline in a clean bordered container with source title as header link.
+- **Section transclusion** (`![[Note Title#Heading]]`) — embeds content
+  under specified heading only.
+- **Block transclusion** (`![[Note Title^block-id]]`) — single paragraph
+  by block ID.
+- **Recursion guard** — depth limited to 3. Circular references show
+  a clean warning card, not an error.
+- **File attachments** — drag-and-drop files onto editor to upload.
+  Non-image files render as styled download cards (file icon, name,
+  size).
+- **Embed preview in editor** — CM6 decoration shows read-only preview
+  below `![[...]]` line. Collapsible with smooth animation.
+
+**UX standard:** Transclusions should feel like natural parts of the
+document, not foreign inclusions. The border and header link should be
+subtle. Embedded content uses the same typography as the host note.
+Collapse animation is smooth.
+
+---
+
+### v0.11.9 — Composability: Slots + Actions
+
+**Goal:** Notes becomes a host surface that other extensions enhance.
+
+**Slot declarations:**
+
+```json
+{
+  "slots": {
+    "notes:toolbar-actions": {
+      "description": "Action buttons in the note editor toolbar",
+      "context": {
+        "noteId": "string",
+        "getContent": "function — returns markdown body",
+        "setContent": "function — replaces markdown body",
+        "getTitle": "function — returns title"
+      }
+    },
+    "notes:note-footer": {
+      "description": "Content rendered below the note body",
+      "context": { "noteId": "string", "content": "string — HTML" }
+    },
+    "notes:sidebar-tabs": {
+      "description": "Additional tabs in the notes sidebar",
+      "context": { "activeNoteId": "string or null" }
+    },
+    "notes:slash-commands": {
+      "description": "Additional slash commands in the editor",
+      "context": { "insertText": "function(text)" }
+    }
+  }
+}
+```
+
+**Exported actions:**
+
+```json
+{
+  "exports": {
+    "actions": {
+      "notes.create": "Create note (params: title, body, folder_id)",
+      "notes.search": "Search notes (params: query, limit)",
+      "notes.get": "Get note by ID (params: note_id)"
+    }
+  }
+}
+```
+
+**UX standard:** Slot contributions must fit visually. Toolbar action
+buttons contributed by other extensions inherit the notes icon-button
+styling. Sidebar tabs contributed by extensions match the built-in tab
+design. The notes surface should not look different when extensions
+contribute to its slots.
+
+---
+
+### v0.11.10 — Panel Enhancement + Quality Gate
+
+**Goal:** The `notes.reference` panel (shipped in v0.10.4) inherits
+the v0.11.x features. Final quality gate.
+
+**Panel updates:**
+
+- Reference panel gets the v0.11.0 visual design language.
+- Search, folder filter, tag filter in panel.
+- Preview pane shows rendered note content (v0.11.0 typography).
+- Click-to-insert: emits `panel.notes.reference.selected` for host.
+- Wikilink resolution works within panel preview.
+
+**Quality gate criteria:**
+
+- All v0.11.x features exercised in SDK test runner.
+- Notes-runner surface tests cover: CRUD, sharing, wikilinks, daily
+  notes, templates, transclusion.
+- Graph renders correctly with 200+ nodes at 60fps.
+- Public note surface renders without authentication.
+- At least one slot contribution demonstrated.
+- Panel reference works in at least one other surface.
+- **UX review:** every screen, every interaction, every empty state
+  reviewed against v0.11.0 design principles. No "placeholder" UI
+  surviving to this point.
+- **Responsive:** full experience on mobile (sidebar overlay, touch
+  targets, no horizontal scroll).
+- **Accessibility:** keyboard navigation through all views. ARIA labels.
+  Focus management on panel/dialog open/close.
+- **Performance:** virtual scrolling on note list for 1000+ notes.
+  Graph 60fps with 500+ nodes. Lazy-load graph and CM6.
+
+---
+
+## Uniquely Armature
+
+| Feature | Obsidian/Notion | Armature Notes |
+|---------|-----------------|----------------|
+| Extension slots | Plugin API (Obsidian) | Kernel-level composability — any package contributes to any slot without coupling |
+| Sharing | Obsidian Publish (paid), Notion sharing | Built on kernel resource model — same permission patterns as every other extension |
+| Panels | N/A | Notes is a panel provider — embed a notes view inside chat, dashboard, or any surface |
+| Multi-surface | Single window | Full surface + public surface + reference panel, all from one package |
+| Server-side logic | Local only (Obsidian) | Starlark backend — search, link resolution, access control run server-side |
+| Realtime | N/A (Obsidian), built-in (Notion) | Via `sw.realtime` — same primitive available to all extensions |
+| Cross-extension actions | Plugin API | `sw.actions` — any package can call `notes.create` or `notes.search` |
+| Self-hosted | Obsidian Sync (paid) | Runs on your infrastructure, your data, your rules |
+
+The thesis: **Notes isn't just a note-taking app — it's proof that
+Armature's extension architecture can deliver a production-quality
+knowledge base that competes with purpose-built SaaS tools, while
+remaining decomposable and extensible.** And it has to *look and feel*
+like it competes, not just architecturally compete.
+
+---
+
+## Schema Summary
+
+### Existing tables (no changes)
+
+- `notes` — title, body, folder_id, creator_id, updated_at, pinned, archived
+- `tags` — note_id, tag
+- `links` — source_id, target_id, link_text
+- `folders` — name, parent_id, creator_id, sort_order
+
+### New columns
+
+- `notes.aliases` (text) — comma-separated aliases (v0.11.2)
+
+### New tables
+
+- `note_shares` — note_id, share_type, target_id, permission, share_token, created_by, created_at (v0.11.4)
+- `folder_shares` — folder_id, share_type, target_id, permission, share_token, created_by, created_at (v0.11.4)
+
+---
+
+## Settings Summary
+
+### Existing
+
+- `default_view` — "recent" or "pinned"
+- `editor_mode` — "rendered", "edit", or "split"
+
+### New
+
+| Setting | Type | Default | Version |
+|---------|------|---------|---------|
+| `daily_note_folder` | string | "Daily Notes" | v0.11.7 |
+| `daily_note_template` | string | `"# {{date}}\n\n"` | v0.11.7 |
+| `template_folder` | string | "Templates" | v0.11.7 |
+| `inline_preview` | boolean | false | v0.11.3 |
+| `graph_hide_orphans` | boolean | false | v0.11.5 |
+| `graph_cluster_by` | string | "folder" | v0.11.5 |
+
+---
+
+## Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| UI redesign as v0.11.0, before features | Every subsequent version builds on the visual foundation. Shipping features on an ugly base means reworking the UI of every feature when the redesign eventually happens. Front-loading avoids double work and ensures every version screenshot looks like a real product. |
+| Notes as first reference extension | Exercises more kernel primitives than any other candidate. Complex enough to prove the platform; familiar enough to be immediately useful. |
+| Dedicated v0.11.x series (11 versions) | Notes is too large for a single version. Each v0.11.x is independently shippable and CI-green. |
+| UX quality threaded through every version | Each version specifies its UX standard, not just functionality. No "make it pretty later" — every feature ships with its final visual quality. |
+| Share model via new tables | Notes sharing needs note/folder-specific semantics (inheritance, public URLs, share tokens). Purpose-built tables beat generic resource grants for this use case. |
+| Aliases as comma-separated text | Small set (1–3 per note). Separate table adds join complexity for marginal normalization benefit. |
+| d3-force for graph | Existing hand-rolled sim has poor convergence at 100+ nodes. d3-force is battle-tested, ~15KB. |
+| Transclusion rendered on view, not live-synced | Live-sync requires WebSocket subs per embedded note. Disproportionate complexity pre-MVP. |
+| Templates are just notes in a folder | No template schema. KISS. |
+| Inline preview as fourth editing mode | Obsidian's killer UX feature. Users who want WYSIWYG-ish editing without leaving markdown get it without a ProseMirror dependency — CM6 decorations handle it. |
+
+---
+
+## Dependency Chain
+
+```
+v0.11.0   UI/UX Foundation     ← EVERYTHING depends on this
+v0.11.1   Deep Folders         ← foundation for folder sharing (v0.11.4)
+v0.11.2   Wikilinks            ← foundation for transclusion (v0.11.8)
+v0.11.3   Live Preview         ← foundation for inline preview + embeds (v0.11.8)
+v0.11.4   Sharing              ← depends on deep folders (v0.11.1)
+v0.11.5   Graph + Outline      ← independent (hardening existing features)
+v0.11.6   Quick Switcher       ← independent (keyboard navigation)
+v0.11.7   Daily Notes          ← depends on deep folders (v0.11.1) for daily folder
+v0.11.8   Transclusion         ← depends on wikilinks (v0.11.2) + live preview (v0.11.3)
+v0.11.9   Composability        ← independent (slot/action declarations)
+v0.11.10  Polish + Gate        ← depends on all above
+```
+
+Versions v0.11.5, v0.11.6, and v0.11.9 are independent and can be
+reordered if priorities shift.

docs/DESIGN-panels.md

@@ -0,0 +1,743 @@
+# DESIGN: Panels — v0.10.x
+
+## Status: Proposed
+
+## Problem
+
+Packages export one rendering granularity today: a **surface** — a
+full-page application that owns `#extension-mount`. There is no way
+for a package to offer a lightweight, composable view of itself that
+another surface can pull in.
+
+Concrete example: the `notes` package provides a full note editor
+surface at `/s/notes`. When a user is in the `chat` surface and wants
+to reference their notes, the only option is to navigate away. There is
+no mechanism to embed a notes panel alongside chat, whether as a
+floating window, a docked sidebar, or a bottom strip.
+
+This forces users into one-thing-at-a-time workflows and prevents the
+"extensions extending extensions" composability story from reaching the
+UI layer. Slots and actions allow injection of buttons and menu items,
+but not entire companion views.
+
+Without kernel coordination, package authors who need this will roll
+their own floating containers, producing:
+
+- **Z-index wars** between packages and kernel overlays (Dialog at 1000,
+  debug at 9999, toast in between).
+- **Inconsistent drag/resize** behavior (touch support, bounds clamping,
+  accessibility).
+- **No position persistence** — panels reset on every navigation.
+- **No layout negotiation** — docked panels can't tell the host surface
+  to shrink.
+
+## Non-Goals
+
+- **Window management system.** This is not a tiling WM. The kernel
+  provides a small set of presentation modes (floating, docked). Complex
+  layouts are post-1.0 horizon.
+- **Cross-surface panel sharing at runtime.** A panel runs inside one
+  host surface's page context. It is not an iframe or a separate
+  browsing context.
+- **Panel-to-panel communication.** Panels communicate with their host
+  surface (and each other) via `sw.events`. No new IPC mechanism.
+- **Server-side panel rendering.** Panels are frontend-only. The kernel
+  resolves dependencies and serves JS; rendering happens in the browser.
+
+## What Already Exists
+
+**Three rendering tiers exist today; panels fill the gap between the
+first two:**
+
+| Tier | Scope | Example |
+|------|-------|---------|
+| **Surface** | Full-page app, owns `#extension-mount` | Notes editor, Chat, Admin |
+| *(gap)* | *Composable companion view* | *Notes reference panel in Chat* |
+| **Block renderer** | Inline content unit in markdown | Mermaid diagram, KaTeX formula |
+
+**Kernel primitives that panels build on:**
+
+- `sw.ui.Dialog` — centered modal with focus trap, backdrop, z-index 1000.
+- `sw.ui.Drawer` — slide-in side panel (left/right), backdrop, z-index 1000.
+- `sw.events` — pub/sub event bus, local and realtime. Already the
+  communication channel between surfaces and slot contributors.
+- `sw.storage` — per-user localStorage wrapper with namespaced keys.
+- `sw.slots` — named UI injection points with manifest declarations.
+- Manifest `depends` field — package dependency resolution at install time.
+
+**What panels add:** A second rendering granularity between surfaces and
+block renderers, with kernel-managed presentation modes and lifecycle.
+
+---
+
+## Architecture
+
+### 1. Three-Tier Rendering Hierarchy
+
+After this change, every package can export up to three things:
+
+```
+Surface   — full-page app, owns the mount, has shell topbar slots
+Panel     — composable view, kernel-managed container, presentation-agnostic
+Renderer  — inline content block (sw.renderers)
+```
+
+The key architectural property: **the panel component does not know its
+presentation mode.** It renders into whatever container the kernel
+provides. Floating, docked-right, docked-bottom — that is a shell/layout
+concern. The panel receives a mount element and a size. Nothing else.
+
+### 2. Manifest Schema
+
+#### Provider: `panels` field
+
+The package that provides a panel declares it in its manifest:
+
+```json
+{
+  "id": "notes",
+  "surfaces": ["/notes"],
+  "panels": {
+    "reference": {
+      "entry": "js/panels/reference.js",
+      "title": "Notes",
+      "icon": "📝",
+      "description": "Searchable note list with quick preview",
+      "min_width": 280,
+      "min_height": 200,
+      "default_width": 400,
+      "default_height": 350
+    }
+  }
+}
+```
+
+Panel IDs are namespaced: `<package_id>.<panel_key>`. The notes
+reference panel above is addressed as `notes.reference` everywhere
+in the SDK and in consumer manifests.
+
+A package may declare multiple panels:
+
+```json
+{
+  "id": "notes",
+  "panels": {
+    "reference": { "entry": "js/panels/reference.js", ... },
+    "graph":     { "entry": "js/panels/graph.js", ... }
+  }
+}
+```
+
+#### Consumer: `panels` dependency
+
+The consuming surface declares which panels it wants available:
+
+```json
+{
+  "id": "chat",
+  "surfaces": ["/chat"],
+  "panels": ["notes.reference"]
+}
+```
+
+This is a **soft dependency**: the panel is available if the providing
+package is installed and enabled. If not, `sw.panels.open()` returns
+`false` and the consuming surface can degrade gracefully (hide the
+button, show a tooltip explaining the missing package).
+
+This is distinct from `depends` (hard dependency — install fails without
+it). A consumer does not need the provider installed to function; the
+panel is an enhancement.
+
+### 3. Panel Entry Point Contract
+
+The panel JS module exports a single `mount` function. The kernel calls
+it with a DOM element and a context object. It returns a cleanup function.
+
+```js
+// notes/js/panels/reference.js
+const { html } = window;
+const { render } = preact;
+
+export function mount(el, ctx) {
+    // ctx.sw       — SDK instance
+    // ctx.params   — optional params from sw.panels.open()
+    // ctx.panelId  — 'notes.reference'
+    // ctx.close    — function to request close
+    // ctx.resize   — function(width, height) to request resize
+
+    render(html`<${NotesReference} sw=${ctx.sw} />`, el);
+
+    // Return cleanup
+    return () => render(null, el);
+}
+```
+
+**Rules:**
+
+- The panel must not assume any particular container size. Use CSS
+  `width: 100%; height: 100%` and let the kernel container control
+  dimensions.
+- The panel must not create its own overlay, backdrop, or drag handle.
+  The kernel wraps the panel in the appropriate chrome.
+- The panel must not set `z-index` on anything. The kernel manages
+  stacking.
+- The panel may use `ctx.close()` to request its own dismissal (e.g.
+  user clicks an "X" inside the panel content area).
+- The panel may use `ctx.resize(w, h)` to suggest a new size, but the
+  kernel may clamp or ignore the request.
+- Communication with the host surface is via `sw.events` — the same
+  bus surfaces and slot contributors already use.
+
+### 4. SDK API — `sw.panels`
+
+New SDK module: `src/js/sw/sdk/panels.js`
+
+```js
+export function createPanels(events, storage) {
+    const _registry = new Map();   // panelId → manifest entry
+    const _active   = new Map();   // panelId → { el, cleanup, mode, ... }
+
+    return {
+        /**
+         * Register a panel from manifest data. Called by the kernel
+         * during surface load — not by package code directly.
+         */
+        _register(panelId, manifest) { ... },
+
+        /**
+         * Open a panel. Lazy-loads the JS entry if not yet loaded.
+         *
+         * @param {string} panelId — e.g. 'notes.reference'
+         * @param {object} opts
+         * @param {string} opts.mode — 'floating' | 'docked-right' | 'docked-left' | 'docked-bottom'
+         * @param {object} opts.params — passed to mount(el, ctx)
+         * @param {number} opts.width — override default width
+         * @param {number} opts.height — override default height
+         * @returns {Promise<boolean>} — false if panel not available
+         */
+        async open(panelId, opts = {}) { ... },
+
+        /**
+         * Close a panel. Calls cleanup, removes container.
+         */
+        close(panelId) { ... },
+
+        /**
+         * Toggle open/close.
+         */
+        toggle(panelId, opts = {}) { ... },
+
+        /**
+         * Check if a panel is currently open.
+         */
+        isOpen(panelId) { ... },
+
+        /**
+         * Check if a panel is available (provider installed + enabled).
+         */
+        isAvailable(panelId) { ... },
+
+        /**
+         * List available panel IDs for the current surface.
+         */
+        list() { ... },
+
+        /**
+         * List currently open panel IDs.
+         */
+        active() { ... },
+    };
+}
+```
+
+**Exposed on `sw` as:**
+
+```js
+sw.panels.open('notes.reference', { mode: 'floating' });
+sw.panels.open('notes.reference', { mode: 'docked-right' });
+sw.panels.close('notes.reference');
+sw.panels.toggle('notes.reference');
+sw.panels.isOpen('notes.reference');    // boolean
+sw.panels.isAvailable('notes.reference'); // boolean
+sw.panels.list();     // ['notes.reference', 'notes.graph']
+sw.panels.active();   // ['notes.reference']
+```
+
+### 5. Presentation Modes
+
+#### Floating (v0.10.1)
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  ←  │ Chat                              │  🔔 │ 👤      │
+├──────────────────────────────────────────────────────────┤
+│                                                          │
+│         Host surface (interactive)                       │
+│                              ┌───────────────────┐       │
+│                              │ ≡ Notes       ─ ✕ │       │
+│                              │                   │       │
+│                              │  [panel content]  │       │
+│                              │                   │       │
+│                              │              ◢    │       │
+│                              └───────────────────┘       │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+- Draggable via title bar (pointer + touch events).
+- Resize via bottom-right handle.
+- Viewport bounds clamping — panel cannot be dragged fully offscreen
+  (at least 48px of title bar must remain visible).
+- No backdrop — host surface remains fully interactive.
+- Z-index above surfaces, below Dialog/Drawer overlays.
+- On focus or drag-start, panel gets next-z (multiple floating panels
+  stack correctly).
+- Escape key: configurable — close panel or do nothing (default: close).
+- Position and size persisted in `sw.storage` keyed by panel ID.
+
+**Title bar chrome (kernel-provided):**
+
+```
+┌────────────────────────────────────┐
+│ ≡  │ {icon} {title}        │ ─ ✕  │
+└────────────────────────────────────┘
+  │                             │  │
+  drag handle              minimize close
+```
+
+- **≡** Drag handle / grip indicator.
+- **─** Minimize: collapses to a small pill at the bottom of the viewport.
+  Click to restore. Minimized state persisted.
+- **✕** Close: calls cleanup, removes panel.
+- Title and icon from manifest.
+
+#### Docked (v0.10.2)
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  ←  │ Chat                              │  🔔 │ 👤      │
+├──────────────────────────────┬──┬────────────────────────┤
+│                              │▐▐│ 📝 Notes          ✕   │
+│    Host surface              │▐▐│                        │
+│    (shrinks to fit)          │▐▐│  [panel content]       │
+│                              │▐▐│                        │
+│                              │▐▐│                        │
+└──────────────────────────────┴──┴────────────────────────┘
+                              resize
+                              gutter
+```
+
+- Docked panels consume space from the host surface. The
+  `#extension-mount` area shrinks via CSS flex or grid.
+- Resize gutter between host and panel (drag to adjust split).
+- Three dock positions: right (default), left, bottom.
+- No z-index concerns — docked panels are in normal flow.
+- Split ratio persisted in `sw.storage` keyed by panel ID + mode.
+- Close button removes panel, host surface reclaims full width/height.
+
+#### Mode Transitions (v0.10.2)
+
+A floating panel can be dragged to a dock zone (edge highlight on
+hover). A docked panel's title bar can be dragged away to float.
+The panel component is never unmounted during a mode transition — only
+the wrapping container changes.
+
+The user controls presentation mode. Surfaces can suggest a default
+mode in `sw.panels.open()`, but the user's last-used mode (persisted)
+takes precedence.
+
+### 6. Z-Index Strategy
+
+Panels slot into the existing stacking context:
+
+| Layer | Z-Index | Contents |
+|-------|---------|----------|
+| Base | 0 | Surface content, docked panels (in flow) |
+| Floating panels | 100–199 | `sw.panels` floating mode (auto-incrementing) |
+| Shell overlays | 200–299 | Dropdowns, tooltips, menus |
+| Drawer | 1000 | `sw.ui.Drawer` |
+| Dialog | 1000 | `sw.ui.Dialog` + confirm/prompt |
+| Toast | 1100 | `sw.ui.toast` |
+| Debug | 9999 | Debug panel |
+
+Floating panels start at z-index 100. Each panel that receives focus
+or drag-start gets `max(current panel z-indexes) + 1`, capped at 199.
+If the cap is hit, all floating panels are renumbered starting from 100
+(maintaining relative order). This prevents unbounded z-index growth.
+
+When a Dialog or Drawer opens, floating panels remain visible beneath
+the overlay — they do not auto-hide. This preserves the "see while
+doing" property.
+
+### 7. Dependency Resolution + Loading
+
+**At install time:** The kernel validates that panel dependencies
+reference valid `<package>.<panel>` identifiers. Invalid references
+are warnings (soft deps), not errors.
+
+**At surface load time:**
+
+1. Kernel reads the surface's `panels` array from its manifest.
+2. For each declared panel, check if the providing package is installed
+   and enabled. Build the available panel list.
+3. Register available panels into `sw.panels._register()` with their
+   manifest metadata (entry path, title, icon, size constraints).
+4. Panel JS is **not** loaded yet — lazy loading on first
+   `sw.panels.open()`.
+
+**On `sw.panels.open(panelId)`:**
+
+1. If panel JS not yet loaded: `import()` the entry module from the
+   package's static asset path
+   (`/api/v1/ext/<package>/static/js/panels/<name>.js`).
+2. Call `module.mount(el, ctx)` where `el` is the content area of the
+   kernel-provided container (FloatingPanel or DockedPanel component).
+3. Store the cleanup function returned by `mount()`.
+4. Emit `panels.opened` event with `{ panelId, mode }`.
+
+**On `sw.panels.close(panelId)`:**
+
+1. Call stored cleanup function.
+2. Remove kernel container from DOM.
+3. Emit `panels.closed` event with `{ panelId }`.
+
+### 8. Panel Communication
+
+No new mechanism. Panels and their host surface share the same
+`sw.events` bus and `sw` SDK instance. Convention-based event
+namespacing:
+
+```js
+// Host surface requests the notes panel to show a specific note
+sw.emit('panel.notes.reference.show', { noteId: '...' });
+
+// Panel listens
+sw.on('panel.notes.reference.show', (data) => {
+    navigateToNote(data.noteId);
+});
+
+// Panel notifies the host that a note was selected
+sw.emit('panel.notes.reference.selected', { noteId: '...', title: '...' });
+
+// Host listens
+sw.on('panel.notes.reference.selected', (data) => {
+    insertNoteLink(data);
+});
+```
+
+The `params` object in `sw.panels.open()` provides initial state:
+
+```js
+sw.panels.open('notes.reference', {
+    mode: 'floating',
+    params: { folderId: 'inbox', highlight: noteId }
+});
+```
+
+Params are passed to `mount(el, ctx)` as `ctx.params`. This avoids
+the need for an event round-trip on first open.
+
+### 9. CSS
+
+New file: `src/css/panels.css`
+
+**Floating panel:**
+
+```css
+.sw-panel-floating {
+    position: fixed;
+    display: flex;
+    flex-direction: column;
+    border: 1px solid var(--border);
+    border-radius: var(--radius-lg);
+    background: var(--bg-surface);
+    box-shadow: var(--shadow-lg);
+    overflow: hidden;
+    /* z-index set dynamically by JS */
+}
+
+.sw-panel-floating__titlebar {
+    display: flex;
+    align-items: center;
+    gap: var(--sp-2);
+    padding: var(--sp-2) var(--sp-3);
+    background: var(--bg-raised);
+    border-bottom: 1px solid var(--border);
+    cursor: grab;
+    user-select: none;
+    flex-shrink: 0;
+}
+
+.sw-panel-floating__titlebar:active {
+    cursor: grabbing;
+}
+
+.sw-panel-floating__title {
+    flex: 1;
+    font-size: 13px;
+    font-weight: 600;
+    color: var(--text);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.sw-panel-floating__actions {
+    display: flex;
+    gap: var(--sp-1);
+}
+
+.sw-panel-floating__action {
+    background: none;
+    border: none;
+    color: var(--text-3);
+    cursor: pointer;
+    padding: 2px 4px;
+    border-radius: var(--radius-sm);
+    font-size: 14px;
+    line-height: 1;
+}
+
+.sw-panel-floating__action:hover {
+    color: var(--text);
+    background: var(--bg-hover);
+}
+
+.sw-panel-floating__body {
+    flex: 1;
+    overflow: auto;
+}
+
+.sw-panel-floating__resize {
+    position: absolute;
+    bottom: 0;
+    right: 0;
+    width: 16px;
+    height: 16px;
+    cursor: nwse-resize;
+}
+
+/* Minimized pill */
+.sw-panel-pill {
+    position: fixed;
+    bottom: var(--sp-3);
+    display: flex;
+    align-items: center;
+    gap: var(--sp-2);
+    padding: var(--sp-2) var(--sp-3);
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    box-shadow: var(--shadow);
+    cursor: pointer;
+    font-size: 12px;
+    color: var(--text-2);
+    z-index: 100;
+}
+
+.sw-panel-pill:hover {
+    color: var(--text);
+    background: var(--bg-raised);
+}
+```
+
+**Docked panel:**
+
+```css
+.sw-panel-dock-container {
+    display: flex;
+    height: 100%;
+    overflow: hidden;
+}
+
+.sw-panel-dock-container--bottom {
+    flex-direction: column;
+}
+
+.sw-panel-dock-gutter {
+    flex-shrink: 0;
+    background: var(--bg-raised);
+    border: 1px solid var(--border);
+    cursor: col-resize;
+    width: 5px;
+}
+
+.sw-panel-dock-container--bottom .sw-panel-dock-gutter {
+    cursor: row-resize;
+    width: auto;
+    height: 5px;
+}
+
+.sw-panel-docked {
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    background: var(--bg-surface);
+}
+
+.sw-panel-docked__header {
+    display: flex;
+    align-items: center;
+    gap: var(--sp-2);
+    padding: var(--sp-2) var(--sp-3);
+    border-bottom: 1px solid var(--border);
+    background: var(--bg-raised);
+    flex-shrink: 0;
+}
+
+.sw-panel-docked__body {
+    flex: 1;
+    overflow: auto;
+}
+```
+
+**Touch targets (mobile):**
+
+```css
+@media (max-width: 768px) {
+    .sw-panel-floating__action {
+        min-width: 44px;
+        min-height: 44px;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+    }
+
+    .sw-panel-floating__titlebar {
+        padding: var(--sp-3) var(--sp-4);
+    }
+
+    .sw-panel-dock-gutter {
+        width: 10px;
+    }
+
+    .sw-panel-dock-container--bottom .sw-panel-dock-gutter {
+        height: 10px;
+    }
+}
+```
+
+### 10. Backend Changes
+
+**Minimal.** The kernel backend already serves extension static assets
+and reads manifests. Changes:
+
+1. **Manifest parsing** (`server/extensions/manifest.go`): Parse the
+   `panels` field from provider manifests (map of panel key → entry
+   metadata). Parse the `panels` field from consumer manifests (array
+   of panel ID strings). Store in the existing `PackageRecord` struct.
+
+2. **Surface load endpoint** (`/api/v1/surfaces/:id`): Include resolved
+   panel metadata in the response — for each panel declared by the
+   surface, include the provider's panel manifest entry (title, icon,
+   entry path, size constraints) if the provider is installed and
+   enabled. This lets the frontend `sw.panels._register()` at surface
+   boot without additional API calls.
+
+3. **Static asset serving**: Already works — panels are served from
+   the same package static path as surface JS
+   (`/api/v1/ext/<package>/static/...`).
+
+**No new tables.** No new migrations. Panel metadata lives in the
+existing manifest JSON stored in the packages table.
+
+### 11. Admin Visibility
+
+The admin packages page already shows package manifests. With panels:
+
+- The package detail view shows declared panels with their metadata.
+- The dependency view shows which surfaces consume which panels.
+- Panel availability warnings surface when a provider package is
+  disabled but consumers reference its panels.
+
+This falls out naturally from the existing manifest introspection —
+no new admin surfaces needed.
+
+---
+
+## Event Inventory
+
+| Event | Emitted by | Payload |
+|-------|-----------|---------|
+| `panels.opened` | Kernel (sw.panels) | `{ panelId, mode }` |
+| `panels.closed` | Kernel (sw.panels) | `{ panelId }` |
+| `panels.mode_changed` | Kernel (sw.panels) | `{ panelId, from, to }` |
+| `panels.focused` | Kernel (sw.panels) | `{ panelId }` |
+| `panel.<id>.*` | Convention (package code) | Package-defined |
+
+All panel events are `localOnly: true` — they do not broadcast over
+the WebSocket. Panels are a frontend-only concern.
+
+---
+
+## Persistence
+
+Panel state persisted in `sw.storage` (localStorage wrapper):
+
+| Key | Value | Scope |
+|-----|-------|-------|
+| `panel_pos_<panelId>` | `{ x, y, w, h }` | Floating position + size |
+| `panel_mode_<panelId>` | `'floating' \| 'docked-right' \| ...` | Last-used presentation mode |
+| `panel_split_<panelId>` | `{ ratio: 0.3 }` | Docked split ratio |
+| `panel_minimized_<panelId>` | `true` | Minimized state |
+
+Persisted per-user (sw.storage is already user-scoped). Cleared when
+the providing package is uninstalled.
+
+---
+
+## Version Plan
+
+| Version | Title | Scope |
+|---------|-------|-------|
+| v0.10.0 | Panel Manifest + Lifecycle | Manifest `panels` field (provider + consumer). Backend parsing. `sw.panels` SDK module (register, open, close, toggle, isOpen, isAvailable, list). Lazy JS loading pipeline. No presentation UI yet — panels render into a plain unstyled container for contract validation. |
+| v0.10.1 | FloatingPanel Primitive | `FloatingPanel` Preact component with drag, resize, minimize, z-index stacking, viewport bounds, position persistence. `panels.css` floating section. Touch support. |
+| v0.10.2 | Docked Panels + Mode Transitions | `DockedPanel` component. Layout negotiation (flex resize of `#extension-mount`). Resize gutter. Drag-to-dock / drag-to-float transitions. `panels.css` docked section. Split ratio persistence. |
+| v0.10.3 | Panel Communication Patterns | Event namespace conventions documented. `ctx.params` for initial state. SDK helper: `sw.panels.send(panelId, event, data)` as sugar over `sw.emit('panel.' + panelId + '.' + event, data)`. Panel communication section in extension developer guide. |
+| v0.10.4 | Reference Panel: Notes | Notes package ships `panels.reference` — searchable note list with quick preview. Chat declares it as a consumer. End-to-end proof: open notes panel in chat, select a note, insert link. Test runner coverage. |
+
+Each version independently CI-green. v0.10.0 is the foundation that
+all subsequent versions build on.
+
+---
+
+## Changeset Plan — v0.10.0
+
+| CS | Scope | Description |
+|----|-------|-------------|
+| CS-1 | Backend (Go) | Manifest parsing: `panels` field on provider + consumer manifests. `PackageRecord` struct update. Surface load endpoint includes resolved panel metadata. |
+| CS-2 | Frontend (JS) | `sw.panels` SDK module: `createPanels()`, register, open, close, toggle, isOpen, isAvailable, list, active. Lazy `import()` loader. Unstyled container mount. |
+| CS-3 | Frontend (JS) | SDK boot integration: wire `sw.panels` into SDK boot sequence. Register panels from `__MANIFEST__` surface data. |
+| CS-4 | Frontend (JS) | Panel lifecycle events: `panels.opened`, `panels.closed`, `panels.focused`. |
+| CS-5 | Tests | SDK test runner: panel registration, open/close lifecycle, lazy loading, availability checks, event emission. |
+
+---
+
+## Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Kernel primitive, not package-level | Z-index coordination, drag/resize consistency, layout negotiation, and position persistence are all kernel concerns. Multiple packages need this. |
+| Soft dependency (not `depends`) | Chat should work without notes installed. Panel availability is a runtime check, not an install-time requirement. |
+| Presentation-agnostic panel contract | `mount(el, ctx)` / cleanup is the entire API surface. Panels never know if they are floating or docked. This lets us add new modes without touching panel code. |
+| Lazy loading | Panel JS is not loaded until first `sw.panels.open()`. Surfaces that declare panels but the user never opens them pay zero cost. |
+| Event bus for communication | `sw.events` already exists and is the established pattern for cross-package communication. No new mechanism needed. |
+| No new backend tables | Panel metadata is manifest data stored in the existing packages table JSON. No schema changes. |
+| Z-index band 100–199 | Above surface content, below shell overlays and Dialog/Drawer. Renumber on cap to prevent unbounded growth. |
+| User controls mode, surface suggests | The surface can pass `mode: 'docked-right'` as a default, but the user's persisted mode preference wins. Users know their own workflow. |
+
+---
+
+## Future Considerations (post-v0.10.x)
+
+- **User-composable layouts.** Power users drag panels from different
+  packages into a persistent workspace layout. Requires a layout
+  persistence model beyond per-panel position.
+- **Panel marketplace metadata.** Panels become a discoverability
+  feature: "this package provides 2 surfaces and 3 panels."
+- **Multi-monitor.** Pop a floating panel into a separate browser
+  window via `window.open()` + `SharedWorker` for event bus. Very
+  post-1.0.
+- **Keyboard shortcuts.** `Ctrl+Shift+N` opens the notes panel.
+  Requires a keybinding registry (not yet a kernel primitive).

docs/DESIGN-shell-contract.md

@@ -5,7 +5,7 @@
 ## Problem
 
 Extension surfaces render into `#extension-mount` with no shell chrome.
-A full audit (docs/AUDIT-surfaces.md) found: 3/4 primary surfaces lack a
+A full audit (v0.7.0 surface audit) found: 3/4 primary surfaces lack a
 notification bell, 2/4 lack a user menu, 4 different topbar implementations,
 user menu never updates on package/role changes, toast-and-forget error
 handling, and empty states that explain nothing.

docs/DESIGN-sidecar-v014x.md

@@ -0,0 +1,922 @@
+# DESIGN: Sidecar Tier — v0.14.x
+
+## Status: Proposed
+
+## Problem
+
+Starlark is the right sandbox for most extension logic: declarative,
+safe, fast to start, no deployment pipeline. But some workloads cannot
+run in Starlark:
+
+- **ML inference** — Python + PyTorch/TF model loading, GPU access.
+- **Media transcoding** — ffmpeg, ImageMagick, Whisper.
+- **Language servers** — LSP processes for code-workspace.
+- **Local git** — clone, diff, merge operations on workspace directories.
+- **Custom runtimes** — anything needing system libraries, native code,
+  or long-running processes.
+- **Personal local bridges** — a user's laptop exposing filesystem,
+  terminal, clipboard, or local compute to the Armature instance.
+
+Today, the `http` module lets Starlark call external APIs (`api.http`
+permission, domain allowlists, SSRF protection). This covers cloud
+services (OpenAI, S3, external webhooks) but not **co-located processes**
+that need access to Armature's data, events, and workspace filesystem,
+nor **personal processes** on a user's own machine.
+
+The sidecar tier bridges this gap: out-of-process extensions that
+connect inward to the kernel, authenticate, register capabilities, and
+participate in the extension ecosystem as first-class citizens — at both
+the **instance level** (shared infrastructure) and the **user level**
+(personal local tools).
+
+**If done wrong, the consequences are severe:**
+
+- Wrong auth model → arbitrary processes access kernel APIs.
+- Wrong lifecycle → resource leaks, zombie processes, orphaned
+  registrations.
+- Wrong API surface → every sidecar extension inherits the debt.
+- Wrong isolation → a runaway sidecar takes down the cluster.
+- Wrong discovery → fragile deployments that break on restart.
+- Wrong scoping → user sidecars see other users' data.
+
+This is invisible infrastructure. Users never see it. But every
+extension that needs native code depends on the contract being right.
+
+## Non-Goals
+
+- **Kernel manages sidecar processes.** The kernel does not start, stop,
+  or restart sidecars. That's the deployment layer's job (K8s, Docker
+  Compose, systemd, or a human running a binary). The kernel discovers
+  sidecars that connect to it.
+- **Sidecar marketplace.** Sidecar packages are installed like any other
+  `.pkg` file. The sidecar binary ships separately (container image,
+  standalone binary, pip package). The manifest declares the sidecar
+  endpoint; the operator deploys it.
+- **Arbitrary bidirectional streaming.** Sidecars communicate via
+  HTTP/JSON request-response and WebSocket events. No gRPC, no custom
+  binary protocols. KISS.
+- **Hot code reload.** Sidecar updates require process restart. The
+  kernel detects the reconnection and re-registers capabilities.
+- **Multi-tenant sidecar isolation.** Instance-level sidecars run at the
+  instance level, not per-user. User-level isolation is handled by
+  user sidecars (v0.14.5), which are scoped to the owning user's
+  identity.
+
+---
+
+## Architecture
+
+### Connect-Inward Model
+
+The defining property: **sidecars connect TO the kernel, not the other
+way around.** The kernel never reaches outward to discover or contact
+a sidecar. This eliminates:
+
+- K8s RBAC for the kernel to discover pods.
+- Service mesh configuration.
+- DNS-based service discovery.
+- Any notion of the kernel "managing" external processes.
+
+A sidecar is just a process that knows the kernel's address and has
+credentials to authenticate. It could be a container in the same pod, a
+separate deployment, a systemd service on the same machine, or a process
+on a developer's laptop connected via tunnel.
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Deployment Layer (K8s / Docker / systemd / manual) │
+│                                                     │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
+│  │ instance │  │ instance │  │ instance │          │
+│  │ sidecar: │  │ sidecar: │  │ sidecar: │          │
+│  │ ml-infer │  │ ffmpeg   │  │ git-ops  │          │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘          │
+│       │              │              │                │
+│       │     connect inward          │                │
+│       ▼              ▼              ▼                │
+│  ┌──────────────────────────────────────────┐       │
+│  │           Armature Kernel                 │       │
+│  │  ┌─────────────────────────────────────┐ │       │
+│  │  │     Sidecar Registry (PG)           │ │       │
+│  │  │  ml-infer:  instance, 3 caps        │ │       │
+│  │  │  ffmpeg:    instance, 2 caps        │ │       │
+│  │  │  git-ops:   instance, 4 caps        │ │       │
+│  │  │  jeff-local: user:jeff, 3 caps      │ │       │
+│  │  └─────────────────────────────────────┘ │       │
+│  └────────────────────────────────▲─────────┘       │
+│                                   │                  │
+└───────────────────────────────────┼──────────────────┘
+                                    │ connect inward
+                              ┌─────┴──────┐
+                              │ user       │
+                              │ sidecar:   │
+                              │ jeff-local │
+                              │ (laptop)   │
+                              └────────────┘
+```
+
+### Two Scopes
+
+**Instance sidecars** — shared infrastructure. Deployed by the operator.
+Any user's requests can invoke their capabilities. An ML inference
+sidecar, a transcoding service, a git operations worker.
+
+**User sidecars** — personal processes. Run by an individual user on
+their own machine. Only the owning user's requests can invoke their
+capabilities. A local file bridge, a personal Ollama instance, a
+script that reacts to Armature events.
+
+Both use the same connect-inward mechanism, same registration flow,
+same capability contract. The difference is the identity binding and
+access scoping.
+
+### Two Authentication Modes
+
+#### Mode A: Registration Token
+
+For simple deployments (Docker Compose, single machine, dev/test).
+
+1. Admin generates an instance sidecar token:
+   `armature sidecar token create --package ml-inference`
+   User generates a personal sidecar token (from settings UI or CLI):
+   `armature sidecar token create --personal`
+2. Token is a signed JWT with claims: `{package_id, scope, user_id, exp}`.
+   Instance tokens: `scope: "instance"`, `user_id: null`.
+   User tokens: `scope: "user"`, `user_id: "<owner>"`.
+3. Sidecar starts with the token as env: `ARMATURE_TOKEN=ey...`
+4. Sidecar calls `POST /api/v1/sidecar/register`.
+5. Kernel validates JWT, creates registry entry with appropriate scope.
+
+#### Mode B: mTLS
+
+For production deployments with certificate infrastructure.
+
+1. Certificate CN encodes identity:
+   Instance: `sidecar:ml-inference`
+   User: `sidecar-user:jeff:local-bridge`
+2. Kernel's `MTLSNativeProvider` parses the CN prefix and resolves to
+   the appropriate sidecar identity.
+
+Both modes produce the same internal identity: a `SidecarIdentity`
+struct with `{package_id, scope, user_id, node_id, registered_at}`.
+
+### Sidecar Registry
+
+```sql
+CREATE TABLE IF NOT EXISTS sidecar_registry (
+    sidecar_id    TEXT PRIMARY KEY,
+    package_id    TEXT NOT NULL,
+    scope         TEXT NOT NULL DEFAULT 'instance',
+    user_id       TEXT,
+    endpoint      TEXT NOT NULL,
+    heartbeat     TIMESTAMPTZ DEFAULT now(),
+    capabilities  JSONB DEFAULT '[]',
+    stats         JSONB DEFAULT '{}',
+    registered_at TIMESTAMPTZ DEFAULT now()
+);
+
+CREATE INDEX idx_sidecar_pkg ON sidecar_registry (package_id);
+CREATE INDEX idx_sidecar_user ON sidecar_registry (user_id)
+    WHERE user_id IS NOT NULL;
+```
+
+`scope` is `'instance'` or `'user'`. `user_id` is NULL for instance
+sidecars, set for user sidecars.
+
+**Lifecycle (mirrors cluster registry):**
+
+- **Register:** `POST /api/v1/sidecar/register` with capability
+  manifest. Kernel creates/updates registry row.
+- **Heartbeat:** `POST /api/v1/sidecar/heartbeat` every N seconds.
+- **Sweep:** Kernel's heartbeat loop sweeps stale sidecar entries
+  alongside node entries. 3× heartbeat interval = stale.
+- **Self-eviction:** Heartbeat returns 404 → re-register or exit.
+- **Deregister:** `DELETE /api/v1/sidecar/deregister` on graceful
+  shutdown.
+
+### Capability Registration
+
+On registration, the sidecar declares capabilities:
+
+```json
+POST /api/v1/sidecar/register
+{
+  "package_id": "ml-inference",
+  "endpoint": "http://ml-inference:8080",
+  "capabilities": [
+    {
+      "name": "embed",
+      "description": "Generate text embeddings",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "text": { "type": "string" },
+          "model": { "type": "string", "default": "all-MiniLM-L6-v2" }
+        },
+        "required": ["text"]
+      },
+      "timeout_seconds": 30
+    },
+    {
+      "name": "classify",
+      "description": "Zero-shot text classification",
+      "input_schema": { ... },
+      "timeout_seconds": 60
+    }
+  ]
+}
+```
+
+### Sidecar SDK (Starlark)
+
+New `sidecar` Starlark module. Permission: `sidecar.call`.
+
+```python
+# Call an instance sidecar capability
+result = sidecar.call("ml-inference", "embed", {"text": "Hello"})
+
+# Check availability
+available = sidecar.available("ml-inference")
+
+# List capabilities
+caps = sidecar.capabilities("ml-inference")
+```
+
+User sidecar calls are routed automatically. When a request originates
+from user Jeff, `sidecar.call("user-bridge", "fs.search", {...})` hits
+Jeff's personal sidecar. The same call from user Alice would hit Alice's
+personal `user-bridge` sidecar (or fail if she doesn't have one). The
+Starlark caller doesn't specify the user — the kernel resolves it from
+the request context.
+
+### Sidecar SDK (Frontend)
+
+```js
+const result = await sw.sidecar.call('ml-inference', 'embed', {
+    text: 'Hello, world'
+});
+const available = await sw.sidecar.available('user-bridge');
+```
+
+Frontend calls go through the kernel API. The kernel proxies to the
+appropriate sidecar based on scope + user identity.
+
+### Sidecar API Contract (Inbound to Kernel)
+
+| Endpoint | Purpose | Auth |
+|----------|---------|------|
+| `POST /api/v1/sidecar/register` | Register + declare capabilities | Token or mTLS |
+| `POST /api/v1/sidecar/heartbeat` | Heartbeat + stats | Token or mTLS |
+| `DELETE /api/v1/sidecar/deregister` | Graceful shutdown | Token or mTLS |
+| `GET /api/v1/ext/{pkg}/*` | Read extension data (scoped) | Token or mTLS |
+| `POST /api/v1/ext/{pkg}/*` | Write extension data (scoped) | Token or mTLS |
+| `POST /api/v1/sidecar/emit` | Emit events | Token or mTLS |
+| `GET /api/v1/sidecar/subscribe` | WebSocket event subscription | Token or mTLS |
+| `POST /api/v1/sidecar/lib/{pkg}/{fn}` | Cross-package function call | Token or mTLS |
+
+**Scoping rules:**
+
+- Instance sidecars: can access `/api/v1/ext/{own_package}/*` only.
+- User sidecars: can access `/api/v1/ext/{own_package}/*` scoped to
+  the owning user's data within that package. The sidecar sees the
+  same data the user would see through the UI.
+- Event emission scoped to the sidecar's package prefix.
+
+### Sidecar API Contract (Outbound from Kernel)
+
+| Endpoint | Purpose |
+|----------|---------|
+| `POST {sidecar_endpoint}/api/v1/exec/{capability}` | Execute a capability |
+| `GET {sidecar_endpoint}/api/v1/health` | Health check |
+
+The `/exec/{capability}` endpoint receives:
+
+```json
+{
+  "input": { ... },
+  "context": {
+    "user_id": "...",
+    "package_id": "...",
+    "request_id": "..."
+  }
+}
+```
+
+Returns:
+
+```json
+{
+  "output": { ... },
+  "error": null
+}
+```
+
+### Resource Limits
+
+What the kernel enforces at the proxy layer:
+
+- **Timeout:** Per-capability, from capability declaration.
+- **Request rate:** Per-sidecar, configurable in admin.
+- **Response size:** Default 10MB, configurable per-sidecar.
+- **Concurrent calls:** Default 10, configurable per-sidecar.
+
+User sidecars have separate (typically lower) defaults:
+
+- **User sidecar rate limit:** Default 30/min (vs 100/min instance).
+- **User sidecar concurrency:** Default 3 (vs 10 instance).
+- **User sidecar response size:** Default 5MB (vs 10MB instance).
+
+Admin can adjust user sidecar defaults globally. Individual users
+cannot override admin limits.
+
+### Manifest Integration
+
+Instance sidecar manifest:
+
+```json
+{
+  "id": "ml-inference",
+  "type": "full",
+  "tier": "sidecar",
+  "version": "1.0.0",
+
+  "sidecar": {
+    "image": "gobha/armature-ml-inference:latest",
+    "required": true,
+    "health_endpoint": "/api/v1/health",
+    "env_hints": {
+      "ARMATURE_URL": "Kernel URL (auto-populated)",
+      "ARMATURE_TOKEN": "Registration token",
+      "MODEL_PATH": "Path to model files"
+    }
+  }
+}
+```
+
+User sidecar manifest (installed as a regular package, sidecar runs
+on user's machine):
+
+```json
+{
+  "id": "user-bridge",
+  "type": "full",
+  "tier": "sidecar",
+  "version": "1.0.0",
+
+  "sidecar": {
+    "scope": "user",
+    "required": false,
+    "download_url": "https://github.com/armature/user-bridge/releases",
+    "env_hints": {
+      "ARMATURE_URL": "Your Armature instance URL",
+      "ARMATURE_TOKEN": "Generate from Settings → Sidecars"
+    }
+  },
+
+  "surfaces": ["/user-bridge/settings"]
+}
+```
+
+`sidecar.scope: "user"` tells the kernel this is a user sidecar
+package. The package installs normally (admin or self-install depending
+on permissions), but the sidecar binary runs on the user's machine.
+
+### Tool Meta-Tool Integration
+
+When `llm-bridge` assembles tools for a completion:
+
+1. Instance-level actions from `sw.actions.list()` → available to all.
+2. Instance sidecar capabilities → available to all.
+3. **Requesting user's personal sidecar capabilities** → available to
+   that user only.
+
+This means different users get different tool sets. Jeff has
+`user-bridge` running with `fs.search`, `terminal.exec`, and
+`clipboard.get`. Alice doesn't. When Jeff asks "Hey Max, find the auth
+file on my desktop," Max has `user-bridge.fs.search` in his tool set.
+When Alice asks the same, that tool doesn't exist — Max tells her he
+can't access her local files.
+
+The same AI persona, different capabilities per user, zero configuration.
+
+### Admin UI
+
+**Instance sidecar management:**
+- Sidecar health status per registered instance sidecar.
+- Capabilities list with call counts, error rates, latency.
+- Token management: generate, revoke, list.
+- Per-sidecar rate limit and concurrency configuration.
+
+**User sidecar admin controls:**
+- Permission: `sidecar.connect_personal` — admin grants to specific
+  users or groups.
+- Capability allowlist for user sidecars — admin restricts which
+  capabilities user sidecars can declare.
+- Global user sidecar resource limits (rate, concurrency, response
+  size).
+- Monitoring: list of all connected user sidecars with owner, endpoint,
+  capabilities, last heartbeat.
+- Kill switch: admin can revoke any user sidecar token or sweep a
+  specific user's sidecars.
+
+**User settings (for users with `sidecar.connect_personal`):**
+- Generate personal sidecar token.
+- List personal connected sidecars with health status.
+- Revoke own tokens.
+- Download link / instructions for user sidecar binaries (from package
+  manifest `download_url`).
+
+### Monitoring
+
+Kernel-side metrics:
+
+- `sidecar_call_total{package, capability, scope, status}` — counter.
+- `sidecar_call_duration_seconds{package, capability, scope}` — histogram.
+- `sidecar_heartbeat_age_seconds{package, scope}` — gauge.
+- `sidecar_active{package, scope}` — gauge.
+- `sidecar_user_count` — gauge (number of connected user sidecars).
+
+---
+
+## User Sidecar Use Cases
+
+### Local Bridge (Desktop Commander Pattern)
+
+A thin agent on the user's laptop that exposes local capabilities:
+
+```json
+{
+  "capabilities": [
+    {
+      "name": "fs.search",
+      "description": "Search local filesystem by filename or content",
+      "input_schema": {
+        "properties": {
+          "query": { "type": "string" },
+          "path": { "type": "string", "default": "~" },
+          "content_search": { "type": "boolean", "default": false }
+        },
+        "required": ["query"]
+      },
+      "timeout_seconds": 15
+    },
+    {
+      "name": "fs.read",
+      "description": "Read a local file",
+      "input_schema": {
+        "properties": {
+          "path": { "type": "string" },
+          "max_bytes": { "type": "integer", "default": 1048576 }
+        },
+        "required": ["path"]
+      },
+      "timeout_seconds": 10
+    },
+    {
+      "name": "terminal.exec",
+      "description": "Execute a shell command",
+      "input_schema": {
+        "properties": {
+          "command": { "type": "string" },
+          "cwd": { "type": "string", "default": "~" },
+          "timeout": { "type": "integer", "default": 30 }
+        },
+        "required": ["command"]
+      },
+      "timeout_seconds": 60
+    },
+    {
+      "name": "clipboard.get",
+      "description": "Read clipboard contents",
+      "input_schema": {},
+      "timeout_seconds": 5
+    }
+  ]
+}
+```
+
+**Tool meta-tool flow:**
+
+```
+User: "Hey Max, find the database migration script I was
+       working on yesterday and add it to my notes"
+
+llm-bridge assembles (for this user):
+  Layer 5 tools: [...instance tools..., user-bridge.fs.search,
+                  user-bridge.fs.read, notes.create, ...]
+
+LLM:
+  1. Tool: user-bridge.fs.search({query: "migration", path: "~/code"})
+  2. Result: [{path: "~/code/armature/migrations/015_sidecar.sql", ...}]
+  3. Tool: user-bridge.fs.read({path: "~/code/armature/migrations/015_sidecar.sql"})
+  4. Result: {content: "CREATE TABLE IF NOT EXISTS sidecar_registry..."}
+  5. Tool: notes.create({title: "Migration 015 - Sidecar Registry",
+                         body: "```sql\nCREATE TABLE..."})
+  6. Text: "Found your sidecar migration script and saved it to Notes."
+```
+
+Three extensions orchestrated: user's local filesystem, instance-level
+notes, all through the same tool meta-tool pattern.
+
+### Personal Compute (Local Ollama)
+
+User runs Ollama on their workstation with a GPU:
+
+```json
+{
+  "capabilities": [
+    {
+      "name": "complete",
+      "description": "LLM completion via local Ollama",
+      "input_schema": {
+        "properties": {
+          "prompt": { "type": "string" },
+          "model": { "type": "string", "default": "llama3" }
+        },
+        "required": ["prompt"]
+      },
+      "timeout_seconds": 120
+    },
+    {
+      "name": "embed",
+      "description": "Local embedding via Ollama",
+      "input_schema": {
+        "properties": {
+          "text": { "type": "string" },
+          "model": { "type": "string", "default": "nomic-embed-text" }
+        },
+        "required": ["text"]
+      },
+      "timeout_seconds": 30
+    }
+  ]
+}
+```
+
+`llm-bridge` can be configured (per-user setting or persona preference)
+to route completions through the user's local Ollama instead of the
+instance-level provider. BYOK taken to the extreme — bring your own
+hardware.
+
+### Personal Automation
+
+A script that reacts to Armature events:
+
+```python
+# Personal deploy watcher — connects to Armature, subscribes to
+# events in the #deploys conversation, runs kubectl locally
+
+ws = connect(f'{KERNEL_URL}/api/v1/sidecar/subscribe',
+             token=TOKEN)
+
+for event in ws:
+    if event['type'] == 'chat.message' and 'deploy' in event['content']:
+        result = subprocess.run(['kubectl', 'get', 'pods', '-n', 'prod'],
+                               capture_output=True, text=True)
+        # Post result back to chat
+        requests.post(f'{KERNEL_URL}/api/v1/sidecar/lib/chat-core/send',
+            json={'conversation_id': event['conversation_id'],
+                  'content': f'```\n{result.stdout}\n```'},
+            headers={'Authorization': f'Bearer {TOKEN}'})
+```
+
+Personal workflow glue. No instance-level deployment required.
+
+---
+
+## RBAC for User Sidecars
+
+Three-layer permission model:
+
+### Layer 1: Admin Controls WHO
+
+New permission: `sidecar.connect_personal`.
+
+Admin grants to specific users, groups, or roles. Most users don't
+need it. Developers, power users, AI-heavy workflows — they get the
+permission.
+
+Default: not granted. Opt-in only.
+
+### Layer 2: Admin Controls WHAT
+
+**Capability allowlist for user sidecars.**
+
+Admin setting: `SIDECAR_USER_ALLOWED_CAPABILITIES`
+
+Default: `["fs.search", "fs.read", "clipboard.get"]` — safe read-only
+operations.
+
+To enable terminal access: admin adds `"terminal.exec"` to the
+allowlist. This is a deliberate escalation requiring admin action.
+
+A user sidecar that attempts to register a capability not on the
+allowlist gets a clear error: "Capability 'terminal.exec' not permitted
+for user sidecars. Contact your administrator."
+
+### Layer 3: User Controls VISIBILITY
+
+User sidecar capabilities are **private by default** — only the owning
+user's requests invoke them.
+
+Optional: user can share a specific capability with their team via the
+settings UI. Shared capabilities appear in team members' tool sets
+(with attribution: "via Jeff's local bridge").
+
+User sidecars are never instance-wide. That's what instance sidecars
+are for.
+
+---
+
+## Security Considerations
+
+### Instance Sidecars
+
+1. **Compromised binary** → can read/write own package data, call
+   exported functions. Mitigation: package-scoped access, audit logging,
+   token revocation.
+2. **Token theft** → impersonate sidecar. Mitigation: package-scoped
+   tokens, mTLS eliminates theft, revocable.
+3. **SSRF via sidecar.call** → Mitigation: endpoints validated at
+   registration, no runtime changes.
+4. **Resource exhaustion** → Mitigation: per-sidecar concurrency and
+   rate limits, timeout enforcement, response size limits.
+5. **Privilege escalation via lib.require** → Mitigation: calls
+   attributed to sidecar identity, target permission checks apply.
+
+### User Sidecars (Additional Concerns)
+
+6. **User deploys malicious sidecar** → registers capabilities that
+   exfiltrate data when called. Mitigation: capability allowlist (admin
+   controls what capabilities can be declared), private-by-default
+   (only the user's own requests trigger it — they're exfiltrating
+   from themselves).
+
+7. **User shares malicious capability with team** → team members
+   invoke it, sidecar captures their request data. Mitigation: shared
+   capabilities are clearly attributed ("via Jeff's local bridge").
+   Admin can disable capability sharing entirely. Shared capabilities
+   run with the CALLING user's permissions, not the sidecar owner's.
+
+8. **User sidecar as pivot** → user's laptop compromised, attacker uses
+   connected sidecar to access Armature data. Mitigation: user sidecar
+   can only access data the user could already access through the UI.
+   No privilege escalation. User can revoke own tokens. Admin kill
+   switch.
+
+9. **Stale user sidecars** → user's laptop goes offline, sidecar
+   becomes stale. Mitigation: same sweep mechanism as instance
+   sidecars. 3× heartbeat interval = swept. User reconnects when
+   laptop comes back online.
+
+### Principle of Least Privilege
+
+- Instance sidecar: access own package data only, middleware-enforced.
+- User sidecar: access own package data scoped to owning user only.
+- Event emission scoped to package prefix.
+- Capability allowlist for user sidecars (admin-controlled).
+- Shared capabilities run with caller's permissions.
+
+---
+
+## Version Plan
+
+### v0.14.0 — Sidecar Registry + Auth
+
+**Goal:** Sidecars can register, authenticate, and heartbeat.
+
+- Sidecar registry table with `scope` and `user_id` columns.
+- Registration endpoint with JWT token validation.
+- Heartbeat + sweep integration.
+- Token generation (instance tokens via admin, user tokens via settings).
+- `SIDECAR_AUTH_MODE` config: `token` or `mtls`.
+- mTLS auth: `sidecar:` and `sidecar-user:` CN prefixes.
+- Admin UI: sidecar health on packages page.
+
+**Instance sidecars only in this version.** User sidecar plumbing
+exists in the schema but user token generation and RBAC gating land
+in v0.14.5.
+
+### v0.14.1 — Capability Registration + Execution
+
+**Goal:** Sidecars declare capabilities. Starlark extensions call them.
+
+- Capability manifest in registration payload.
+- `sidecar` Starlark module: `call()`, `available()`, `capabilities()`.
+- Kernel proxy: `sidecar.call()` → `POST {endpoint}/exec/{cap}`.
+- Input validation against declared schema.
+- Timeout, response size, concurrent call limits.
+- Error propagation.
+- `sidecar.call` permission.
+- Audit logging.
+
+### v0.14.2 — Kernel API Access + Event Bus
+
+**Goal:** Sidecars read/write their own data and participate in events.
+
+- Sidecar middleware: authenticate, scope to own package routes.
+- `/api/v1/sidecar/lib/{pkg}/{fn}` — cross-package function calls.
+- `/api/v1/sidecar/emit` — event emission (package-scoped).
+- `/api/v1/sidecar/subscribe` — WebSocket event subscription.
+- Frontend `sw.sidecar` SDK module.
+
+### v0.14.3 — Manifest Integration + Admin Polish
+
+**Goal:** Sidecar packages are first-class in install/admin flow.
+
+- `tier: "sidecar"` manifest support.
+- `sidecar` manifest field (image, required, scope, env_hints,
+  download_url).
+- Admin UI: deployment instructions from manifest.
+- Admin UI: capability list with metrics.
+- Admin UI: per-sidecar rate limit configuration.
+- Token management UI.
+- Monitoring metrics.
+
+### v0.14.4 — Reference Sidecar + Instance Quality Gate
+
+**Goal:** Ship one real instance sidecar. Prove the contract.
+
+**`armature-embed`** — minimal Python sidecar running
+sentence-transformers for local embedding generation. One capability:
+`embed(text) → float[]`.
+
+`vector-store` calls `sidecar.call('armature-embed', 'embed', {...})`
+for local embedding without an external API. Completes the local-first
+RAG story.
+
+**Instance sidecar quality gate:**
+
+- Registration, heartbeat, sweep lifecycle tested.
+- Token and mTLS auth both functional.
+- Capability execution with limits enforced.
+- Package-scoped API access enforced.
+- Event emission/subscription functional.
+- `sw.sidecar` frontend module functional.
+- Reference sidecar runs in Docker and K8s.
+- Admin UI complete.
+- Monitoring metrics in Grafana.
+
+### v0.14.5 — User Sidecars
+
+**Goal:** Users connect personal processes to Armature.
+
+- `sidecar.connect_personal` permission (admin-granted).
+- User token generation in Settings → Sidecars.
+- Capability allowlist for user sidecars (admin setting:
+  `SIDECAR_USER_ALLOWED_CAPABILITIES`).
+- User sidecar registration with `scope: "user"`, `user_id` binding.
+- Execution routing: `sidecar.call()` resolves user sidecars based
+  on request context (calling user gets their own sidecar).
+- Capability sharing: user can share specific capabilities with team.
+  Shared caps attributed ("via Jeff's local bridge").
+- Separate resource limits for user sidecars (lower defaults).
+- User settings UI: connected sidecars, token management, sidecar
+  instructions from package manifests.
+- Admin UI: user sidecar monitoring, kill switch.
+- Tool meta-tool integration: `llm-bridge` includes user's personal
+  sidecar capabilities in tool set assembly.
+
+**Reference user sidecar: `user-bridge`** — thin agent binary with
+`fs.search`, `fs.read`, `clipboard.get` capabilities. Published as a
+package with `sidecar.scope: "user"`. Binary as a GitHub release.
+
+**User sidecar quality gate:**
+
+- RBAC: user without `sidecar.connect_personal` cannot register.
+- Capability allowlist enforced.
+- User A cannot invoke user B's sidecar.
+- Shared capabilities run with caller's permissions.
+- Admin can revoke any user sidecar.
+- Tool meta-tool assembles per-user tool sets correctly.
+- `user-bridge` reference sidecar runs on macOS, Linux, Windows.
+
+---
+
+## Schema Summary
+
+### New tables
+
+- `sidecar_registry` — sidecar_id, package_id, scope, user_id,
+  endpoint, heartbeat, capabilities (JSON), stats (JSON),
+  registered_at. (v0.14.0)
+- `sidecar_tokens` — id, package_id, scope, user_id, token_hash,
+  created_by, expires_at, revoked_at. (v0.14.0)
+
+---
+
+## Configuration
+
+| Setting | Default | Purpose |
+|---------|---------|---------|
+| `SIDECAR_AUTH_MODE` | `token` | `token` or `mtls` |
+| `SIDECAR_HEARTBEAT_INTERVAL` | `10s` | Expected heartbeat frequency |
+| `SIDECAR_STALE_THRESHOLD` | `30s` | 3× heartbeat = stale |
+| `SIDECAR_MAX_RESPONSE_SIZE` | `10485760` (10MB) | Instance default |
+| `SIDECAR_DEFAULT_CONCURRENCY` | `10` | Instance default |
+| `SIDECAR_DEFAULT_RATE_LIMIT` | `100/min` | Instance default |
+| `SIDECAR_USER_MAX_RESPONSE_SIZE` | `5242880` (5MB) | User default |
+| `SIDECAR_USER_CONCURRENCY` | `3` | User default |
+| `SIDECAR_USER_RATE_LIMIT` | `30/min` | User default |
+| `SIDECAR_USER_ALLOWED_CAPABILITIES` | `["fs.search","fs.read","clipboard.get"]` | Admin-controlled allowlist |
+
+---
+
+## Sidecar Author Contract
+
+### Minimum Viable Sidecar (Python)
+
+```python
+from flask import Flask, request, jsonify
+import requests, os, threading, time
+
+app = Flask(__name__)
+KERNEL = os.environ['ARMATURE_URL']
+TOKEN = os.environ['ARMATURE_TOKEN']
+
+def register():
+    requests.post(f'{KERNEL}/api/v1/sidecar/register',
+        json={
+            'package_id': 'my-sidecar',
+            'endpoint': f'http://localhost:8080',
+            'capabilities': [{
+                'name': 'echo',
+                'description': 'Echo input back',
+                'input_schema': {
+                    'type': 'object',
+                    'properties': {'text': {'type': 'string'}},
+                    'required': ['text']
+                },
+                'timeout_seconds': 10
+            }]
+        },
+        headers={'Authorization': f'Bearer {TOKEN}'})
+
+def heartbeat():
+    while True:
+        time.sleep(10)
+        r = requests.post(f'{KERNEL}/api/v1/sidecar/heartbeat',
+            json={'stats': {}},
+            headers={'Authorization': f'Bearer {TOKEN}'})
+        if r.status_code == 404:
+            register()
+
+@app.route('/api/v1/exec/echo', methods=['POST'])
+def exec_echo():
+    return jsonify({
+        'output': {'text': request.json['input']['text']},
+        'error': None
+    })
+
+@app.route('/api/v1/health')
+def health():
+    return jsonify({'status': 'ok'})
+
+register()
+threading.Thread(target=heartbeat, daemon=True).start()
+app.run(port=8080)
+```
+
+Four things: register, heartbeat, `/exec/`, `/health`. That's the
+contract.
+
+---
+
+## Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Connect-inward | Eliminates K8s RBAC, service mesh, DNS discovery. Works on any deployment target. |
+| Two auth modes | Token for simple. mTLS for production. Same internal identity. |
+| Cluster registry pattern | Proven heartbeat/sweep. No new coordination mechanism. |
+| HTTP/JSON, no gRPC | KISS. 4-endpoint contract. Every language has HTTP. |
+| Kernel proxies all calls | Auth, rate limits, audit, timeouts at single control point. |
+| Package-scoped access | Compromised sidecar can't read other packages. |
+| User sidecars as v0.14.5 | Prove instance contract first (v0.14.0–v0.14.4), then extend to users. Same mechanism, new scope. |
+| Three-layer user RBAC | Admin controls who (permission), what (capability allowlist), user controls visibility (private/shared). Defense in depth. |
+| Capability allowlist for user sidecars | Admin decides what user processes can expose. `terminal.exec` is a deliberate escalation. |
+| Private-by-default user capabilities | User sidecar can't affect other users unless explicitly shared. |
+| Shared caps run with caller's perms | Prevents privilege escalation through shared capabilities. |
+| Reference instance sidecar: embedding | Simpler than LLM. Proves contract. Completes local RAG story. |
+| Reference user sidecar: file bridge | Most compelling user sidecar demo. "Find a file on my laptop and save it to notes" is visceral. |
+| Lower resource limits for user sidecars | User sidecars are less trusted (running on personal devices). Lower defaults, admin can't be overridden by users. |
+| Separate from polish (v0.15.x) | Sidecar is security-critical infrastructure. Polish is quality-of-life. Don't mix. |
+
+---
+
+## Future Considerations
+
+- **Streaming responses.** LLM sidecar needs token streaming. SSE or
+  chunked transfer. Deferred — batch covers embedding, classification,
+  transcoding.
+- **SDK libraries.** Thin wrappers in Python, Go, Node, Rust for
+  registration + heartbeat + parsing. Convenience, not requirement.
+- **Auto-scaling.** Multiple instances of same sidecar, kernel
+  load-balances. No schema change needed — registry supports multiple
+  rows per package.
+- **GPU detection.** Kernel capability for manifest negotiation.
+- **Sidecar-to-sidecar.** Direct calls for performance pipelines.
+  Currently goes through kernel.
+- **User sidecar desktop app.** Electron/Tauri tray app that wraps the
+  user-bridge agent with a GUI for capability management and connection
+  status. Post-1.0.

docs/DESIGN-vector-column.md

@@ -0,0 +1,97 @@
+# Design: Vector Column Type (v0.8.3)
+
+## Problem
+
+Extensions building semantic search, RAG, or recommendation features need to
+store and query high-dimensional vectors (embeddings). Without kernel-level
+support, each extension would need to reinvent storage, serialization, and
+similarity search — duplicating effort and missing the pgvector optimization
+path.
+
+## Design
+
+### Three-tier progressive enhancement
+
+| Backend | Column DDL | Storage | Search |
+|---------|-----------|---------|--------|
+| Postgres + pgvector | `vector(N)` + HNSW index | Native vector type | `<=>` operator (index-backed) |
+| Postgres (no pgvector) | `JSONB` | JSON array | Go-side cosine distance |
+| SQLite | `TEXT` | JSON string | Go-side cosine distance |
+
+Extensions declare `"vector(N)"` in their manifest `db_tables` block.
+The kernel maps this to the appropriate SQL type at install time based on
+detected capabilities.
+
+### Manifest example
+
+```json
+{
+  "db_tables": {
+    "documents": {
+      "columns": {
+        "title": "text",
+        "embedding": "vector(384)"
+      }
+    }
+  },
+  "capabilities": {
+    "optional": ["pgvector"]
+  }
+}
+```
+
+### API surface
+
+```python
+# Insert (vector as list)
+db.insert("documents", {"title": "hello", "embedding": [0.1, 0.2, ...]})
+
+# Similarity search
+rows = db.query_similar(
+    "documents", "embedding",
+    vector=[0.1, 0.2, ...],
+    limit=10,
+    filters={"active": True},
+    metric="cosine"
+)
+# → [{..., "_distance": 0.023}, ...]
+```
+
+### Dispatch paths
+
+**pgvector path** — SQL-side computation with index:
+```sql
+SELECT *, (embedding <=> $1::vector) AS _distance
+FROM ext_pkg_documents
+WHERE ... ORDER BY embedding <=> $1::vector LIMIT $2
+```
+
+**Fallback path** — Go-side computation:
+1. `SELECT * FROM table WHERE filters LIMIT 1000`
+2. Parse each row's vector column from JSON
+3. Compute cosine distance in Go
+4. Sort by distance, return top N with `_distance` injected
+
+### Dimension validation
+
+- Manifest: 1 ≤ N ≤ 4096 (validated by `parseVectorDim`)
+- Insert-time: no dimension validation (store whatever list is given)
+- Query-time: dimension mismatches produce distance = 1.0 (treated as unrelated)
+
+### Performance characteristics
+
+| Path | 1K rows | 10K rows | 100K rows |
+|------|---------|----------|-----------|
+| pgvector (HNSW) | <1ms | <5ms | <10ms |
+| Fallback (Go) | <10ms | ~100ms | Not recommended |
+
+Fallback caps at 1000 rows fetched. Extensions needing large-scale similarity
+search should declare `capabilities.optional: ["pgvector"]` and degrade
+gracefully.
+
+## Limitations
+
+- Only cosine distance metric (v0.8.3). L2 / inner product can be added later.
+- No dimension validation at insert time.
+- Fallback path fetches at most 1000 rows — not suitable for large datasets.
+- HNSW index is only created for pgvector backends.

docs/DESIGN-workflow-redesign.md

@@ -0,0 +1,126 @@
+# DESIGN — Workflow System Redesign (0.9.x)
+
+**Version:** v0.9.0
+**Status:** Draft
+**Author:** Jeff / Claude session 2026-04-03
+
+---
+
+## Problem
+
+The workflow system spans ~7,600 lines across 25+ files and was built
+incrementally from v0.3.x through v0.7.10. It works, but several
+concepts are redundant, primitives are buried, and the Starlark module
+is read-only. Before shipping reference extensions (v0.10.x) that
+build on workflows, the system needs cleanup and promotion of reusable
+primitives.
+
+## Audit Summary
+
+Full audit in `/config/Downloads/AUDIT-workflow-0.9.md`. Classification:
+
+### KEEP — Core primitives that survive
+
+| Component | File(s) | Lines | Rationale |
+|-----------|---------|-------|-----------|
+| Engine core | `workflow/engine.go` | ~400 | Stateless state machine — Start, Advance, Cancel, version-pinned execution |
+| Conditional routing | `workflow/routing.go` | ~500 | Pure functions, 8 operators, well-tested (497 lines of tests) |
+| Automated processing | `workflow/automated.go` | ~300 | Starlark hook execution, cycle guard (max 10) |
+| Scanner | `workflow/scanner.go` | ~200 | Background SLA + staleness checks, 5-minute interval |
+| Signoff system | engine.go + handlers | ~400 | Multi-party approve/reject with quorum, role-gated |
+| Assignment queue | handlers | ~300 | Claim/unclaim/complete/cancel lifecycle |
+| Version snapshots | store + models | ~200 | Immutable snapshots, version-pinned instances |
+| Typed form system | `models/workflow.go` | ~300 | 8 field types, fieldsets, conditional visibility |
+| Store interface | `store/workflow_iface.go` | 61 methods | Complete lifecycle coverage |
+
+### OBE — Superseded by new design
+
+| Concept | Superseded by |
+|---------|---------------|
+| Per-stage `audience` field | Multi-page packages with mixed access declarations |
+| `entry_mode` (public_link/team_only) | Package-level `scope: adoptable` + per-page access |
+| `stage_mode` proliferation (4 values) | Collapse to 3: form / delegated / automated |
+| `stage_type` (simple/dynamic/automated) | Redundant with `starlark_hook` presence check |
+| `AdoptTeamWorkflow` clone | Package adoption model |
+| `ExportWorkflowPackage` endpoint | Standard package export |
+
+### PROMOTE — Buried features to expose as kernel primitives
+
+1. **Roles → kernel primitive**: `team_user_roles` table, manifest `requires_roles`,
+   team admin UI, kernel middleware, Starlark SDK
+2. **Typed forms → SDK primitive**: Move from workflow models to `forms` package,
+   FE SDK `sw.forms.render()` / `sw.forms.validate()`
+3. **Conditional routing → SDK primitive**: Starlark `routing.evaluate(rules, data)`
+4. **Workflow Starlark module → full read/write**: `workflow.start()`, `.advance()`,
+   `.cancel()`, `.submit_signoff()`
+
+---
+
+## Technical Debt
+
+### Starlark Converter Duplication
+
+Three files contain nearly identical Go↔Starlark conversion functions:
+
+| File | Functions |
+|------|-----------|
+| `workflow/automated.go` | `goToStarlark`, `starlarkDictToMap`, `starlarkToGo` |
+| `handlers/workflow_hooks.go` | `starlarkDictToMap`, `starlarkToGo`, `jsonToStarlark` |
+| `sandbox/workflow_module.go` | `goValToStarlark` |
+
+**Fix:** Consolidate into `sandbox/convert.go`.
+
+### Snapshot Format Inconsistency
+
+Two formats exist (wrapped `{stages, workflow}` vs legacy flat array).
+Three copies of the parser across engine, instance handlers, and
+assignment handlers.
+
+**Fix:** Consolidate into one exported function. Standardize on wrapped format.
+
+---
+
+## Sequencing
+
+| Version | Feature | Dependencies |
+|---------|---------|-------------|
+| **v0.9.0** | Starlark converter consolidation + snapshot format cleanup | None |
+| **v0.9.1** | `team_user_roles` table + management API + admin UI | None |
+| **v0.9.2** | `scope: adoptable` manifest field + adoption flow with role auto-populate | v0.9.1 |
+| **v0.9.3** | Promote typed forms to SDK primitive (`sw.forms`) | None |
+| **v0.9.4** | Deprecate `stage_type`, collapse `stage_mode` to 3 values | None |
+| **v0.9.5** | Full read/write workflow Starlark module | v0.9.0 |
+| **v0.9.6** | Conditional routing as SDK primitive | v0.9.5 |
+| **v0.9.7** | Multi-surface manifest + kernel route resolution | None |
+| **v0.9.8** | Wire roles into surface access (`access: role:X`) + kernel middleware | v0.9.1, v0.9.7 |
+
+Each step is CI-green independently. The first four are the high-value items.
+
+---
+
+## Files Affected (by component)
+
+### Converter Consolidation (v0.9.0)
+- New: `sandbox/convert.go`
+- Modified: `workflow/automated.go`, `handlers/workflow_hooks.go`, `sandbox/workflow_module.go`
+
+### Team Roles (v0.9.1)
+- New: migration (PG + SQLite), `store/team_roles.go`, `handlers/team_roles.go`
+- Modified: manifest validation, adoption flow, team admin UI
+
+### Typed Forms (v0.9.3)
+- New: `forms/` package (extracted from `models/workflow.go`)
+- New: `sw.forms` SDK module
+- Modified: workflow engine to import from `forms/` instead of inline
+
+### Workflow Starlark Module (v0.9.5)
+- Modified: `sandbox/workflow_module.go` — add start/advance/cancel/signoff
+- Modified: `workflow/engine.go` — extract interface to break circular import
+
+---
+
+## Non-Goals
+
+- Rewriting the workflow engine. The state machine is correct and stays.
+- Adding a visual workflow builder. That's an extension concern, not kernel.
+- Multi-tenancy changes. Team scoping works as designed.

docs/EXTENSION-GUIDE.md

@@ -72,19 +72,34 @@ Every package has a `manifest.json` at its root. Example for a surface:
 | `icon` | no | Emoji icon for sidebar/menu |
 | `route` | surfaces | URL path (e.g., `/s/my-surface`) |
 | `auth` | no | `authenticated` (default) or `public` |
-| `permissions` | no | Capabilities requested: `db.write`, `http`, `notifications`, `secrets`, `realtime.publish` |
+| `permissions` | no | Sandbox capabilities: `db.write`, `db.read`, `api.http`, `notifications`, `secrets`, `realtime.publish`, `connections.read`, `workflow.access`, `batch.exec`, `files.read`, `files.write`, `workspace.manage` |
 | `api_routes` | no | Array of `{method, path}` for extension HTTP endpoints |
 | `api_schema` | no | OpenAPI documentation for extension API routes (see below) |
 | `db_tables` | no | Table definitions (see below) |
 | `settings` | no | User-configurable settings schema |
-| `exports` | libraries | Functions exported for other packages |
+| `exports` | no | Functions exported for cross-package calls via `lib.require()` |
+| `depends` | no | Array of package IDs this package depends on |
+| `slots` | no | Named UI injection points for host surfaces |
+| `contributes` | no | Slot contributions into other surfaces |
 | `hooks` | no | Event bus subscriptions |
 | `config_section` | no | Settings/Admin panel injection (see below) |
+| `capabilities` | no | Environment requirements (see below) |
+| `user_permissions` | no | Permissions this extension registers for users (see below) |
+| `gate_permission` | no | Permission checked before `on_request` executes |
 | `schema_version` | no | Integer for additive schema migrations |
 
 ## db_tables Schema
 
-Tables are automatically namespaced as `ext_{package_id}_{table_name}`. Column types: `text`, `int`. Every table gets an auto-generated `id` primary key and `created_at` timestamp.
+Tables are automatically namespaced as `ext_{package_id}_{table_name}`.
+Every table gets an auto-generated `id` primary key and `created_at` timestamp.
+
+Column types: `text`, `int`, `vector(N)`.
+
+The `vector(N)` type stores N-dimensional float vectors for similarity
+search via `db.query_similar()`. Storage adapts to the backend:
+Postgres + pgvector uses native `vector(N)` with HNSW indexes,
+Postgres without pgvector uses `JSONB`, SQLite uses `TEXT`. N can be
+1–4096. See the [Starlark Reference](STARLARK-REFERENCE) for query API.
 
 ```json
 "db_tables": {
@@ -137,6 +152,162 @@ Extensions can optionally declare an `api_schema` array in their manifest to pro
 
 Only `path` and `method` are required. All other fields are optional. Malformed entries are logged and skipped without blocking extension loading.
 
+## Capabilities
+
+Extensions can declare environment requirements via the `capabilities`
+manifest field. The kernel validates these at install time.
+
+```json
+{
+  "capabilities": {
+    "required": ["postgres"],
+    "optional": ["pgvector", "workspace"]
+  }
+}
+```
+
+- **required** — install is rejected (HTTP 422) if any capability is missing.
+- **optional** — install succeeds with a logged warning. Query at runtime
+  with `settings.has_capability("pgvector")` to adapt behavior.
+
+Detected capabilities: `pgvector`, `workspace`, `object_storage`, `s3`,
+`postgres`. The admin can view detected capabilities at
+**Admin > System > Capabilities** or via `GET /admin/capabilities`.
+
+## User Permissions
+
+Extensions can register custom permissions that the admin assigns to
+user groups. This controls access to extension features beyond the
+sandbox permission model.
+
+```json
+{
+  "user_permissions": ["image-gen.use", "image-gen.admin"],
+  "gate_permission": "image-gen.use"
+}
+```
+
+- **user_permissions** — on install, these are merged into the kernel's
+  permission registry. On uninstall, they are removed. The admin assigns
+  them to groups in **Admin > Groups**.
+- **gate_permission** — if set, the kernel checks this permission before
+  calling `on_request`. Unauthorized users get a 403 without the
+  extension code executing.
+
+In Starlark, check permissions inline via `req["permissions"]` or call
+`permissions.check(user_id, "image-gen.use")`.
+
+## Extension Composability
+
+Extensions compose with each other through three mechanisms: manifest-declared
+**slots** (UI injection points), **contributions** (UI components injected into
+those slots), and cross-package **function calls** via `lib.require()`.
+
+### Slots — Host Surfaces Declare Injection Points
+
+A surface declares named slots in its manifest where other extensions can
+inject UI components:
+
+```json
+{
+  "id": "notes",
+  "type": "surface",
+  "slots": {
+    "toolbar-actions": {
+      "description": "Toolbar action buttons",
+      "context": {
+        "noteId": "string",
+        "getContent": "function — returns note body",
+        "setContent": "function — replaces note body"
+      }
+    }
+  }
+}
+```
+
+The surface renders slot contents using the SDK helper:
+
+```javascript
+html`<div class="toolbar">
+    ${sw.slots.renderAll('notes:toolbar-actions', {
+        noteId: note.id,
+        getContent: () => editor.getValue(),
+        setContent: (text) => editor.setValue(text),
+    })}
+</div>`
+```
+
+### Contributions — Extensions Inject UI
+
+An extension declares which slots it contributes to:
+
+```json
+{
+  "id": "note-dictate",
+  "type": "extension",
+  "contributes": {
+    "notes:toolbar-actions": {
+      "label": "Dictate",
+      "icon": "🎤",
+      "description": "Voice-to-text dictation"
+    }
+  }
+}
+```
+
+In its JavaScript, it registers the component:
+
+```javascript
+sw.slots.register('notes:toolbar-actions', {
+    id: 'note-dictate',
+    priority: 200,
+    component: ({ noteId, setContent, getContent }) => {
+        // ... component implementation
+        return html`<button class="sw-btn sw-btn--ghost">🎤</button>`;
+    }
+});
+```
+
+Contributions are soft-coupled — install order doesn't matter. The admin
+can view all slots and contributors at **Admin > Packages** or via
+`GET /api/v1/admin/slots`.
+
+### Cross-Package Function Calls
+
+Any package that declares `exports` in its manifest can be called by other
+packages via `lib.require()`. The caller declares the dependency:
+
+```json
+{
+  "id": "note-ai",
+  "depends": ["llm-bridge"],
+  "permissions": ["api.http"]
+}
+```
+
+In Starlark:
+
+```python
+llm = lib.require("llm-bridge")
+result = llm.complete([{"role": "user", "content": prompt}])
+```
+
+The called function runs with the *target* package's permissions, not the
+caller's. This is the same security model as library packages.
+
+### Slot Naming Convention
+
+Slot names follow `{host-package-id}:{slot-name}`. The colon separates the
+namespace from the slot. Standard slots for first-party packages:
+
+| Slot | Host | Use Case |
+|------|------|----------|
+| `notes:toolbar-actions` | notes | Dictation, AI tools, formatting |
+| `notes:note-footer` | notes | Related items, AI summary |
+| `chat:composer-tools` | chat | Image gen, file attach |
+| `chat:message-actions` | chat | Reactions, translate, bookmark |
+| `chat:image-actions` | chat | Regen, edit, upscale |
+
 ## Starlark Sandbox API
 
 Starlark scripts run server-side with a 1M operation budget and no

docs/FRONTEND-JS-GUIDE.md

@@ -248,6 +248,44 @@ Every surface uses one of three patterns:
 The shell provides the home link, notification bell, and user menu
 on every surface for free.
 
+## `sw.forms` — Typed Forms (v0.9.5)
+
+Any extension can render and validate typed forms using the `sw.forms` module.
+
+### `sw.forms.render(container, template, opts)`
+
+Renders a typed form into a DOM container. Supports flat forms and progressive
+multi-step forms (fieldsets). Returns a control handle.
+
+```js
+const handle = sw.forms.render(document.getElementById('my-form'), template, {
+    values: { name: 'prefilled' },
+    onSubmit: (data) => { console.log('submitted', data); },
+});
+
+// Programmatic access
+const data = handle.getData();
+handle.setErrors([{ key: 'name', message: 'Name is taken' }]);
+handle.destroy();
+```
+
+### `sw.forms.validate(template, data)`
+
+Client-side validation (no network call). Returns `{ valid, errors }`.
+
+```js
+const { valid, errors } = sw.forms.validate(template, { name: '' });
+// valid === false, errors === [{ key: 'name', message: 'Name is required' }]
+```
+
+### `sw.forms.validateRemote(template, data)`
+
+Server-side validation via `POST /api/v1/forms/validate`. Returns a Promise.
+
+```js
+const result = await sw.forms.validateRemote(template, data);
+```
+
 ## Extension CSS contract
 
 Extensions must prefix all CSS classes with `.ext-{slug}-` to avoid

docs/MULTI-SURFACE-GUIDE.md

@@ -0,0 +1,201 @@
+# Multi-Surface Packages
+
+A multi-surface package serves multiple pages from a single package, each
+with its own URL path, access level, and layout. Before v0.9.0, a package
+got one route (`/s/{id}`), one auth posture, and one layout. Now a single
+package can serve a public submission form alongside an authenticated
+dashboard and an admin settings page.
+
+## When to Use Multi-Surface
+
+Use multi-surface when your package has logically related pages that share
+the same backend (Starlark hooks, ext API, database tables) but need:
+
+- **Different access levels** — public intake form + authenticated dashboard
+- **Multiple views** — list view, detail view, edit view, monitor view
+- **Sub-pages** — settings, admin, or debug pages within the package
+
+If your pages don't share backend state, use separate packages instead.
+
+## Manifest Setup
+
+Add a `surfaces` array to your manifest. Each entry declares a page:
+
+```json
+{
+  "id": "workflow-builder",
+  "title": "Workflow Builder",
+  "type": "full",
+  "version": "0.1.0",
+  "icon": "🔧",
+  "auth": "authenticated",
+  "layout": "single",
+
+  "surfaces": [
+    { "path": "/",                "title": "Workflows" },
+    { "path": "/new",             "title": "New Workflow",    "nav": false },
+    { "path": "/:id/edit",        "title": "Edit Workflow",   "nav": false },
+    { "path": "/monitor",         "title": "Monitor",         "nav": true },
+    { "path": "/monitor/:id",     "title": "Instance Detail", "nav": false }
+  ],
+
+  "hooks": ["surface"],
+  "permissions": ["workflow.access"]
+}
+```
+
+This generates five server routes, all under `/s/workflow-builder/`:
+
+| Route | Access | Nav |
+|-------|--------|-----|
+| `/s/workflow-builder/` | authenticated | yes |
+| `/s/workflow-builder/new` | authenticated | no |
+| `/s/workflow-builder/:id/edit` | authenticated | no |
+| `/s/workflow-builder/monitor` | authenticated | yes |
+| `/s/workflow-builder/monitor/:id` | authenticated | no |
+
+### Surface Entry Fields
+
+| Field    | Default        | Description |
+|----------|----------------|-------------|
+| `path`   | **required**   | URL path relative to `/s/{id}`. Supports `:param` segments. |
+| `access` | package `auth` | `public`, `authenticated`, `admin`, or `group:{name}`. |
+| `title`  | package `title`| Label shown in nav and page title. |
+| `layout` | package `layout`| `single` or `editor`. |
+| `nav`    | `true` for `/`, `false` otherwise | Whether this surface appears in the sidebar. |
+
+### Mixed Access Levels
+
+A package can mix public and authenticated surfaces:
+
+```json
+{
+  "id": "bug-tracker",
+  "auth": "authenticated",
+  "surfaces": [
+    { "path": "/submit", "access": "public",  "title": "Report a Bug" },
+    { "path": "/",       "title": "Dashboard" },
+    { "path": "/:id",    "title": "Bug Detail", "nav": false },
+    { "path": "/admin",  "access": "admin",   "title": "Settings", "nav": false }
+  ]
+}
+```
+
+The kernel enforces access per-surface. Unauthenticated visitors can reach
+`/submit` but are redirected to login if they try `/` or `/:id`.
+
+## Frontend: Routing Within Your Package
+
+### Reading the Current Surface
+
+When your package JS loads, two globals tell you which surface was matched:
+
+```js
+const path   = window.__SURFACE_PATH__   || '/';
+const params = window.__SURFACE_PARAMS__ || {};
+```
+
+Use these to decide which view to render:
+
+```js
+function render() {
+    const path   = window.__SURFACE_PATH__ || '/';
+    const params = window.__SURFACE_PARAMS__ || {};
+
+    const root = document.getElementById('surface-root');
+
+    switch (path) {
+        case '/':           return renderList(root);
+        case '/new':        return renderEditor(root, null);
+        case '/:id/edit':   return renderEditor(root, params.id);
+        case '/monitor':    return renderMonitor(root);
+        case '/monitor/:id':return renderDetail(root, params.id);
+        default:            return render404(root);
+    }
+}
+
+render();
+```
+
+### SPA Navigation with `sw.navigate()`
+
+Navigate between surfaces without a full page reload:
+
+```js
+// Navigate to a static path
+sw.navigate('/new');
+
+// Navigate with params
+sw.navigate('/:id/edit', { id: 'wf-42' });
+
+// Navigate to monitor sub-page
+sw.navigate('/monitor/:id', { id: 'inst-7' });
+```
+
+`sw.navigate()` does three things:
+1. Updates `window.__SURFACE_PATH__` and `window.__SURFACE_PARAMS__`
+2. Calls `history.pushState()` to update the URL
+3. Emits a `surface.navigate` event
+
+### Listening for Navigation Events
+
+Re-render when the user navigates (including browser back/forward):
+
+```js
+sw.on('surface.navigate', ({ path, params }) => {
+    window.__SURFACE_PATH__   = path;
+    window.__SURFACE_PARAMS__ = params;
+    render();
+});
+```
+
+### Links Between Surfaces
+
+For simple `<a>` links that do full page loads:
+
+```html
+<a href="/s/workflow-builder/monitor">Monitor</a>
+```
+
+For SPA-style navigation:
+
+```js
+button.onclick = () => sw.navigate('/monitor');
+```
+
+## API Routes
+
+All surfaces in a package share the same ext API. API calls go through
+`/s/{id}/api/*` regardless of which surface is active:
+
+```js
+// These work from any surface in the package
+const items = await sw.api.get('/items');
+const item  = await sw.api.get(`/items/${id}`);
+await sw.api.post('/items', { title: 'New item' });
+```
+
+The ext API handler checks `package.status == "active"` — if the package
+is in `pending_review`, all API calls return 403.
+
+## Backward Compatibility
+
+Packages without a `surfaces` array continue to work. The kernel
+synthesizes a single-entry array from the legacy `auth` and `layout`
+fields:
+
+```
+auth: "authenticated" + layout: "single"
+  →  surfaces: [{ "path": "/", "access": "authenticated", "layout": "single" }]
+```
+
+No migration is required for existing packages.
+
+## Constraints
+
+- **No cross-package routing.** Surface paths are relative to the package
+  mount point. A package cannot claim arbitrary top-level routes.
+- **No per-surface Starlark hooks.** All surfaces share the same backend
+  hooks. Use the surface path in your hook logic to differentiate.
+- **No SSR.** Surface rendering is client-side. The kernel serves the
+  shell template; your JS renders the content.

docs/PACKAGE-FORMAT.md

@@ -60,16 +60,140 @@ Only `manifest.json` is required. All other directories are optional and include
 | `description` | Short description |
 | `icon` | Emoji for sidebar/menu display |
 | `author` | Package author |
-| `route` | URL path for surfaces (e.g., `/s/my-package`) |
+| `surfaces` | Array of surface entries with per-path access, title, layout (see below) |
-| `auth` | `authenticated` or `public` |
+| `route` | *(deprecated — use `surfaces`)* URL path for surfaces |
-| `layout` | Surface layout mode (e.g., `single`) |
+| `auth` | Default access level for all surfaces: `authenticated`, `public`, `admin` |
+| `layout` | Default layout for all surfaces: `single`, `editor` |
 | `permissions` | Array of required capabilities (`db.write`, `http`, `notifications`, `secrets`, `realtime.publish`) |
 | `api_routes` | Array of `{"method": "GET", "path": "/items"}` |
 | `db_tables` | Table definitions with columns and indexes |
 | `settings` | User-configurable settings with type, label, description, default |
 | `hooks` | Event bus subscription patterns |
-| `exports` | Functions exported by library packages |
+| `exports` | Functions exported for cross-package calls via `lib.require()` |
+| `depends` | Array of package IDs this package depends on |
+| `slots` | Named UI injection points (host surfaces declare these) |
+| `contributes` | Slot contributions this package injects into other surfaces |
+| `capabilities` | Environment requirements: `{"required": [...], "optional": [...]}` |
 | `schema_version` | Integer for additive schema migrations |
+| `form_template` | Typed form template (v0.9.5). Fields array or fieldsets for progressive forms. Validated at install. |
+
+## Multi-Surface Packages
+
+A package can serve multiple pages, each with its own path, access level,
+title, and layout. Declare a `surfaces` array in the manifest:
+
+```json
+{
+  "id": "bug-tracker",
+  "title": "Bug Tracker",
+  "type": "full",
+  "auth": "authenticated",
+  "layout": "single",
+  "surfaces": [
+    { "path": "/",       "title": "Dashboard" },
+    { "path": "/submit", "access": "public", "title": "Report a Bug" },
+    { "path": "/:id",    "title": "Bug Detail", "nav": false },
+    { "path": "/admin",  "access": "admin",  "title": "Settings", "nav": false }
+  ]
+}
+```
+
+### Surface Entry Fields
+
+| Field    | Type   | Default        | Description |
+|----------|--------|----------------|-------------|
+| `path`   | string | **required**   | Relative to `/s/{pkg-id}`. Supports `:param` segments. |
+| `access` | string | package `auth` | `public`, `authenticated`, `admin`, `group:{name}`. |
+| `title`  | string | package `title`| Human label. Used in nav if `nav: true`. |
+| `layout` | string | package `layout`| `single`, `editor`, or future layouts. |
+| `nav`    | bool   | see rules      | Show in sidebar navigation. |
+
+### Nav Visibility Rules
+
+- `path: "/"` defaults to `nav: true` (primary entry point)
+- All others default to `nav: false` (sub-pages)
+- Explicit `"nav": true` overrides — a package can put multiple entries in nav
+- The sidebar links to the first surface with `nav: true`
+
+### Backward Compatibility
+
+If `surfaces` is absent, the kernel synthesizes one entry from the legacy
+`auth` and `layout` fields. No existing packages break.
+
+### Client-Side Navigation
+
+Within a multi-surface package, use `sw.navigate()` for SPA-style routing:
+
+```js
+const path = window.__SURFACE_PATH__ || '/';
+const params = window.__SURFACE_PARAMS__ || {};
+
+if (path === '/')           renderDashboard();
+if (path === '/submit')     renderSubmitForm();
+if (path === '/:id')        renderDetail(params.id);
+
+// Navigate to another surface within the package
+sw.navigate('/submit');
+sw.navigate('/:id', { id: 'bug-42' });
+
+// Listen for navigation events (including back/forward)
+sw.on('surface.navigate', ({ path, params }) => {
+    renderView(path, params);
+});
+```
+
+## Composability: Slots and Contributions
+
+Packages compose with each other through named UI injection points (**slots**) and **contributions**.
+
+### Declaring Slots (Host Surfaces)
+
+Surfaces declare slots where other extensions can inject UI:
+
+```json
+{
+  "slots": {
+    "toolbar-actions": {
+      "description": "Toolbar action buttons",
+      "context": {
+        "noteId": "string — current note ID",
+        "getContent": "function — returns note body text"
+      }
+    }
+  }
+}
+```
+
+Slot names are namespaced at runtime as `{package-id}:{slot-name}` (e.g., `notes:toolbar-actions`). The `context` field documents what data the slot provides — it is not enforced at runtime.
+
+### Contributing to Slots
+
+Extensions declare which slots they inject into:
+
+```json
+{
+  "contributes": {
+    "notes:toolbar-actions": {
+      "label": "Dictate",
+      "icon": "🎤",
+      "description": "Voice-to-text dictation"
+    }
+  }
+}
+```
+
+Contributing extensions can be installed before or after their host surface — the coupling is soft. The admin can view all slots and their contributors at `GET /api/v1/admin/slots`.
+
+### Cross-Package Function Calls
+
+Any package that declares `exports` can be called via `lib.require()`, not just library-type packages. The caller must declare the target in its `depends` array:
+
+```json
+{
+  "depends": ["image-gen"],
+  "permissions": ["api.http"]
+}
+```
 
 ## Package Lifecycle
 

docs/ROADMAP-v010x-shift.md

@@ -0,0 +1,171 @@
+# ROADMAP — v0.10.x+ Version Shift (Final)
+
+## Summary
+
+Four new series inserted after v0.9.x. Panels (kernel primitive), Notes
+(first reference extension), Chat (second reference extension), and the
+remaining reference libraries/extensions including `llm-bridge` with
+the tool meta-tool pattern.
+
+## Full Roadmap
+
+| Series | Title | Versions | Design Doc |
+|--------|-------|----------|------------|
+| v0.9.x | Multi-Surface + Workflow Redesign | 10 | — |
+| **v0.10.x** | **Panels + Composable Layout** | 5 | `DESIGN-panels.md` |
+| **v0.11.x** | **Notes Reference Extension** | 11 | `DESIGN-notes-v011x.md` |
+| **v0.12.x** | **Chat Reference Extension** | 9 | `DESIGN-chat-v012x.md` |
+| **v0.13.x** | **Reference Libraries + Extensions** | 9 | — |
+| v0.14.x | Sidecar Tier + Polish | 3 | — |
+| v1.0.0 | Stable Release | — | — |
+
+---
+
+## v0.10.x — Panels + Composable Layout
+
+| Version | Title |
+|---------|-------|
+| v0.10.0 | Panel Manifest + Lifecycle |
+| v0.10.1 | FloatingPanel Primitive |
+| v0.10.2 | Docked Panels + Mode Transitions |
+| v0.10.3 | Panel Communication Patterns |
+| v0.10.4 | Reference Panel: Notes (basic) |
+
+---
+
+## v0.11.x — Notes Reference Extension
+
+| Version | Title |
+|---------|-------|
+| v0.11.0 | UI/UX Foundation |
+| v0.11.1 | Deep Folders + Navigation |
+| v0.11.2 | Wikilinks + Backlinks |
+| v0.11.3 | Live Preview + Rich Editing |
+| v0.11.4 | Note Sharing + Permissions |
+| v0.11.5 | Graph + Outline Hardening |
+| v0.11.6 | Quick Switcher + Commands |
+| v0.11.7 | Daily Notes + Templates |
+| v0.11.8 | Transclusion + Embeds |
+| v0.11.9 | Composability: Slots + Actions |
+| v0.11.10 | Panel Enhancement + Quality Gate |
+
+---
+
+## v0.12.x — Chat Reference Extension
+
+Human-to-human first. AI via `llm-bridge` (v0.13.x).
+
+| Version | Title |
+|---------|-------|
+| v0.12.0 | UI/UX Foundation |
+| v0.12.1 | Conversation Folders + Attributes |
+| v0.12.2 | Reactions + Threads + Pins |
+| v0.12.3 | Rich Compose + Attachments |
+| v0.12.4 | @Mentions + Notifications |
+| v0.12.5 | Link Previews + Message Formatting |
+| v0.12.6 | Conversation Themes + Personality |
+| v0.12.7 | Composability: Slots + Actions |
+| v0.12.8 | Panels + Quality Gate |
+
+---
+
+## v0.13.x — Reference Libraries + Extensions
+
+Core libraries and remaining extensions. `llm-bridge` is the key
+delivery — extends both notes and chat through composability primitives,
+and introduces the tool meta-tool pattern.
+
+| Version | Title |
+|---------|-------|
+| v0.13.0 | `vector-store` Library |
+| v0.13.1 | `llm-bridge` Core Library |
+| v0.13.2 | `llm-bridge` → Chat: Multi-Persona Context + Tool Meta-Tool |
+| v0.13.3 | `llm-bridge` → Notes: AI Toolbar Actions |
+| v0.13.4 | `file-share` Extension |
+| v0.13.5 | `code-workspace` Extension |
+| v0.13.6 | `image-gen` + `image-edit` Extensions |
+| v0.13.7 | Tool Meta-Tool Hardening + Scoping |
+| v0.13.8 | Integration Quality Gate |
+
+**v0.13.1 — `llm-bridge` Core:**
+Model abstraction, provider BYOK via connections, `complete()`,
+`embed()`, `classify()`. Persona CRUD (name, avatar, system_prompt,
+visibility). Layered prompt architecture (6 layers: admin safety →
+folder context → persona identity → conversation → tools → user).
+Admin safety rails as non-overridable platform setting.
+
+**v0.13.2 — Chat Integration:**
+Contributes folder attributes (system_prompt, context_policy,
+model_override, allowed_tools) to chat. Contributes "Invite AI" /
+"Dismiss AI" to `chat:participant-actions`. Contributes "AI Reply" /
+"AI Summarize" to `chat:message-actions`. Contributes "Ask AI" to
+`chat:composer-tools`. Context archetype implementation (resident /
+scoped / stateless). Session tracking, gap handling, memory extraction
+on dismiss. **Tool meta-tool v1:** `sw.actions.list()` → LLM tool
+definitions. AI calls extension actions, results flow back into chat.
+
+**v0.13.3 — Notes Integration:**
+Contributes "AI Summarize" / "AI Translate" / "AI Fix Grammar" to
+`notes:toolbar-actions`. Contributes `/ai` to `notes:slash-commands`.
+Uses `notes.get` / `notes.search` actions for context.
+
+**v0.13.7 — Tool Meta-Tool Hardening:**
+Three-tier tool scoping: admin blocklist (global), folder allowed_tools
+(space-level), persona allow/deny (character-level). Tool result
+rendering through `sw.renderers`. Rate limiting on tool calls. Audit
+logging of tool use. Error handling (tool failure → graceful message).
+
+**v0.13.8 — Integration Quality Gate:**
+AI participant lifecycle tested end-to-end. Tool meta-tool demonstrated
+with 3+ extensions. All three context archetypes tested. Persona
+creation/sharing across visibility levels. Admin safety rails validated
+(prompt injection resistance). Performance: completion latency measured.
+
+---
+
+## v0.14.x — Sidecar Tier + Polish
+
+| Version | Title |
+|---------|-------|
+| v0.14.0 | Sidecar Tier |
+| v0.14.1 | Native Dialog Audit |
+| v0.14.2 | Stability + Migration Tooling |
+
+---
+
+## v1.0.0 Gate Criteria
+
+- Notes reference extension shipped (all v0.11.x)
+- Chat reference extension shipped (all v0.12.x)
+- `llm-bridge` extends both notes and chat through composability
+- Tool meta-tool demonstrated: AI uses 3+ extension actions in a
+  single conversation turn
+- Notes and chat UI reviewed against design principles
+- At least 2 panels consumed cross-package
+- At least 2 slot contributions per host surface demonstrated
+- Multi-persona context archetypes demonstrated
+- Admin safety rails validated
+- Note and conversation sharing functional end-to-end
+- Headless E2E green on PG + SQLite
+- All kernel Starlark modules documented
+- All API routes covered by OpenAPI spec
+- Upgrade path tested from v0.8.0 → v1.0.0
+- Single-binary + Docker + K8s deployment paths documented
+
+---
+
+## Design Decisions Log
+
+| Decision | Rationale |
+|----------|-----------|
+| Panels as kernel primitive (v0.10.x) | Z-index coordination, drag/resize, layout negotiation are kernel concerns. |
+| UI/UX redesign as first version in each reference series | Every feature builds on the visual foundation. |
+| Notes before chat | Notes is simpler (no realtime) and proves storage/rendering/composability. Chat adds realtime + llm-bridge story. |
+| Chat human-to-human first | AI is an extension concern. Keeps chat testable and usable standalone. |
+| Folder attributes as extension bridge | Chat stores attributes it doesn't understand. llm-bridge contributes definitions. Zero coupling. |
+| Action registry as tool registry (meta-tool) | Dynamic, zero-config AI tool-use. Installed extensions = AI capabilities. Uniquely Armature. |
+| Layered prompt architecture (6 layers) | Admin safety not overridable. Clear separation: platform → space → character → context → tools → user. |
+| Personas in llm-bridge, not chat | Chat sees AI as just another participant_type. Persona identity is llm-bridge's concern. |
+| Background images via CSS filter | No server-side processing. `filter: blur() brightness() saturate()` + `opacity` handles any image. |
+| Soft panel deps for notes↔chat | Runtime-resolved, no circular dependency. Both function independently. |
+| llm-bridge after notes + chat | Proves the composability hooks work without being designed for a specific consumer. |

docs/ROADMAP-v010x-v100.md

@@ -0,0 +1,157 @@
+# ROADMAP — v0.10.x → v1.0.0 (Final)
+
+## Full Roadmap
+
+| Series | Title | Versions | Design Doc |
+|--------|-------|----------|------------|
+| v0.9.x | Multi-Surface + Workflow Redesign | 10 | — |
+| **v0.10.x** | **Panels + Composable Layout** | 5 | `DESIGN-panels.md` |
+| **v0.11.x** | **Notes Reference Extension** | 11 | `DESIGN-notes-v011x.md` |
+| **v0.12.x** | **Chat Reference Extension** | 9 | `DESIGN-chat-v012x.md` |
+| **v0.13.x** | **Reference Libraries + Extensions** | 9 | — |
+| **v0.14.x** | **Sidecar Tier** | 6 | `DESIGN-sidecar-v014x.md` |
+| **v0.15.x** | **Polish + Stability** | 3 | — |
+| **v1.0.0** | **Stable Release** | — | — |
+
+**Total: ~53 versions from v0.10.0 to v1.0.0**
+
+---
+
+## v0.10.x — Panels + Composable Layout
+
+| Version | Title |
+|---------|-------|
+| v0.10.0 | Panel Manifest + Lifecycle |
+| v0.10.1 | FloatingPanel Primitive |
+| v0.10.2 | Docked Panels + Mode Transitions |
+| v0.10.3 | Panel Communication Patterns |
+| v0.10.4 | Reference Panel: Notes (basic) |
+
+---
+
+## v0.11.x — Notes Reference Extension
+
+| Version | Title |
+|---------|-------|
+| v0.11.0 | UI/UX Foundation |
+| v0.11.1 | Deep Folders + Navigation |
+| v0.11.2 | Wikilinks + Backlinks |
+| v0.11.3 | Live Preview + Rich Editing |
+| v0.11.4 | Note Sharing + Permissions |
+| v0.11.5 | Graph + Outline Hardening |
+| v0.11.6 | Quick Switcher + Commands |
+| v0.11.7 | Daily Notes + Templates |
+| v0.11.8 | Transclusion + Embeds |
+| v0.11.9 | Composability: Slots + Actions |
+| v0.11.10 | Panel Enhancement + Quality Gate |
+
+---
+
+## v0.12.x — Chat Reference Extension
+
+| Version | Title |
+|---------|-------|
+| v0.12.0 | UI/UX Foundation |
+| v0.12.1 | Conversation Folders + Attributes |
+| v0.12.2 | Reactions + Threads + Pins |
+| v0.12.3 | Rich Compose + Attachments |
+| v0.12.4 | @Mentions + Notifications |
+| v0.12.5 | Link Previews + Message Formatting |
+| v0.12.6 | Conversation Themes + Personality |
+| v0.12.7 | Composability: Slots + Actions |
+| v0.12.8 | Panels + Quality Gate |
+
+---
+
+## v0.13.x — Reference Libraries + Extensions
+
+| Version | Title |
+|---------|-------|
+| v0.13.0 | `vector-store` Library |
+| v0.13.1 | `llm-bridge` Core Library |
+| v0.13.2 | `llm-bridge` → Chat: Multi-Persona + Tool Meta-Tool |
+| v0.13.3 | `llm-bridge` → Notes: AI Toolbar Actions |
+| v0.13.4 | `file-share` Extension |
+| v0.13.5 | `code-workspace` Extension |
+| v0.13.6 | `image-gen` + `image-edit` Extensions |
+| v0.13.7 | Tool Meta-Tool Hardening + Scoping |
+| v0.13.8 | Integration Quality Gate |
+
+---
+
+## v0.14.x — Sidecar Tier
+
+Connect-inward model. Instance sidecars (shared infrastructure) and
+user sidecars (personal local tools).
+
+| Version | Title |
+|---------|-------|
+| v0.14.0 | Sidecar Registry + Auth |
+| v0.14.1 | Capability Registration + Execution |
+| v0.14.2 | Kernel API Access + Event Bus |
+| v0.14.3 | Manifest Integration + Admin Polish |
+| v0.14.4 | Reference Sidecar (`armature-embed`) + Instance Gate |
+| v0.14.5 | User Sidecars + Reference (`user-bridge`) + User Gate |
+
+---
+
+## v0.15.x — Polish + Stability
+
+| Version | Title |
+|---------|-------|
+| v0.15.0 | Native Dialog Audit |
+| v0.15.1 | Versioned Migrations + `armature migrate` CLI |
+| v0.15.2 | Pre-1.0 Schema Freeze + Upgrade Path Validation |
+
+---
+
+## v1.0.0 Gate Criteria
+
+**Reference extensions:**
+- Notes shipped (all v0.11.x) with UI quality review
+- Chat shipped (all v0.12.x) with UI quality review
+- At least 3 reference extensions beyond notes/chat
+
+**Composability:**
+- `llm-bridge` extends both notes and chat through slots/actions
+- Tool meta-tool: AI uses 3+ extension actions in a single turn
+- At least 2 panels consumed cross-package
+- At least 2 slot contributions per host surface
+
+**Sidecar:**
+- Instance sidecar (`armature-embed`) deployed and functional
+- User sidecar (`user-bridge`) functional on macOS/Linux/Windows
+- Token + mTLS auth both tested
+- User sidecar RBAC enforced (permission, capability allowlist, scoping)
+- Tool meta-tool includes user sidecar capabilities per-user
+
+**Infrastructure:**
+- Admin safety rails validated
+- Multi-persona context archetypes demonstrated
+- Sharing functional (notes + conversations)
+- Headless E2E green on PG + SQLite
+- All kernel Starlark modules documented
+- All API routes covered by OpenAPI spec
+- `armature migrate` CLI functional
+- Upgrade path tested v0.8.0 → v1.0.0
+- Single-binary + Docker + K8s deployment paths documented
+- Monitoring dashboard with kernel + sidecar metrics
+
+---
+
+## Design Decisions Log
+
+| Decision | Rationale |
+|----------|-----------|
+| Panels as kernel primitive | Z-index, drag, layout are kernel concerns |
+| UI/UX-first for reference extensions | Every feature builds on visual foundation |
+| Notes → Chat → Libraries → Sidecar | Each builds on proven patterns from previous |
+| Chat human-to-human first | AI is llm-bridge's job |
+| Folder attributes as extension bridge | Zero coupling between chat and llm-bridge |
+| Action registry as tool registry | Installed extensions = AI capabilities |
+| 6-layer prompt architecture | Admin safety not overridable |
+| Sidecar connect-inward | No K8s RBAC, no service mesh, no DNS discovery |
+| Sidecar HTTP/JSON, not gRPC | KISS. 4-endpoint contract |
+| User sidecars in v0.14.5 | Prove instance contract first, extend to users with same mechanism |
+| Three-layer user sidecar RBAC | Admin controls who + what, user controls visibility |
+| Separate polish (v0.15.x) | Security-critical infra and quality-of-life shouldn't share focus |

docs/STARLARK-REFERENCE.md

@@ -37,9 +37,20 @@ val = settings.get("theme", "light")
 The cascade respects the `user_overridable` flag from the package manifest.
 See [Permissions & Groups](PERMISSIONS-AND-GROUPS) for details.
 
+```python
+# Check if a runtime capability is available
+if settings.has_capability("pgvector"):
+    # Use native vector search
+    ...
+```
+
+`has_capability(name)` returns `True` if the named environment capability
+is detected by the kernel. Detected capabilities: `pgvector`, `workspace`,
+`object_storage`, `s3`, `postgres`.
+
 ### lib
 
-Load exported functions from library packages.
+Load exported functions from other packages.
 
 ```python
 helpers = lib.require("my-utils")
@@ -47,11 +58,49 @@ result = helpers.format_date("2026-01-15")
 ```
 
 Requirements:
-- The library must be declared in your package manifest's `dependencies`.
+- The target package must be declared in your manifest's `depends` array.
-- The library must be type `library`, status `active`, tier `starlark`.
+- The target package must declare `exports` in its manifest.
+- The target package must be status `active`, tier `starlark`.
+- Any package type (`library`, `extension`, `full`) can be called as long
+  as it declares exports. This enables full packages to expose callable
+  functions alongside their UI and API routes.
 - Circular dependencies are detected and rejected.
 - Results are cached per execution (calling `require` twice returns the
   same object).
+- The called function runs with the *target* package's permissions, not
+  the caller's.
+
+### permissions
+
+Check whether a user has a specific permission.
+
+```python
+if permissions.check(user_id, "image-gen.use"):
+    # User is authorized
+    ...
+```
+
+Returns `True` if the user has the permission, `False` otherwise (including
+when the user is not found). Resolves the user's groups and merges granted
+permissions — works for both kernel and extension-declared permissions.
+
+### routing
+
+Generic rule-based decision engine. Evaluates an ordered list of conditions
+against a data dict, returning the first matching rule's target string.
+
+```python
+result = routing.evaluate([
+    {"field": "priority", "op": "eq",  "value": "critical", "target": "escalation"},
+    {"field": "amount",   "op": "gt",  "value": 10000,      "target": "manager_review"},
+    {"field": "region",   "op": "in",  "value": ["EU", "UK"], "target": "gdpr_flow"},
+], stage_data)
+# Returns "escalation", "manager_review", "gdpr_flow", or None
+```
+
+Each rule is a dict with `field`, `op`, `value`, and `target`. Operators:
+`exists`, `not_exists`, `eq`, `neq`, `gt`, `lt`, `gte`, `lte`, `in`,
+`contains`. First-match-wins; returns `None` if no rule matches.
 
 ## Permission-gated modules
 
@@ -136,6 +185,33 @@ results = db.query_batch([
 # Each query spec supports: table (required), filters, order, limit, before, after, search_like
 ```
 
+#### Vector similarity search
+
+```python
+# Find rows with the most similar embeddings (cosine distance)
+rows = db.query_similar(
+    "documents",        # table name
+    "embedding",        # vector column name
+    vector=[0.1, 0.2, ...],  # query vector (list of floats)
+    limit=10,           # max results (default 10, max 100)
+    filters={"active": True},  # optional equality filters
+    metric="cosine",    # only "cosine" supported
+)
+# Returns rows ordered by ascending _distance (0.0 = identical, 1.0 = orthogonal)
+# Each row dict includes an injected "_distance" float key.
+```
+
+Vector columns are declared as `"vector(N)"` in the manifest `db_tables` block
+(N = dimension, 1–4096). Storage varies by backend:
+
+| Backend | Column type | Search |
+|---------|-------------|--------|
+| Postgres + pgvector | `vector(N)` with HNSW index | Native `<=>` operator |
+| Postgres (no pgvector) | `JSONB` | Go-side cosine computation |
+| SQLite | `TEXT` | Go-side cosine computation |
+
+Insert vectors as lists: `db.insert("docs", {"embedding": [0.1, 0.2, 0.3]})`.
+
 #### Write operations
 
 ```python
@@ -275,6 +351,83 @@ results, errors = batch.exec([
 
 ---
 
+### files
+
+**Permissions:** `files.read`, `files.write`
+
+Store and retrieve files via the kernel ObjectStore (PVC or S3).
+All keys are scoped to `ext/{packageID}/` — extensions cannot access
+each other's files.
+
+```python
+# Store a file with optional metadata
+files.put("reports/q1.pdf", pdf_bytes,
+          content_type="application/pdf",
+          metadata={"quarter": "Q1", "year": 2026})
+
+# Read a file
+result = files.get("reports/q1.pdf")
+# result = {"content": b"...", "content_type": "application/pdf",
+#           "size": 12345, "metadata": {"quarter": "Q1", "year": 2026}}
+
+# Metadata only (no content transfer)
+meta = files.meta("reports/q1.pdf")
+
+# List files by prefix
+entries = files.list(prefix="reports/", limit=50)
+# entries = [{"name": "reports/q1.pdf", "size": 12345, "content_type": "..."}]
+
+# Check existence
+if files.exists("reports/q1.pdf"):
+    files.delete("reports/q1.pdf")
+
+# Bulk delete
+files.delete_prefix("temp/")
+```
+
+**Notes:**
+- `content` accepts string or bytes; `get()` returns bytes.
+- Maximum file size: 50 MB (configurable via `EXT_FILES_MAX_SIZE`).
+- Metadata is stored as a companion JSON object, not in the file itself.
+- `files.list()` automatically filters out internal metadata companions.
+
+---
+
+### workspace
+
+**Permission:** `workspace.manage`
+
+Managed disk directories for extensions that need a real filesystem
+(git clones, compilers, media tools). Each workspace is scoped to
+`{WORKSPACE_ROOT}/{packageID}/{name}/`.
+
+```python
+# Create a workspace (idempotent)
+path = workspace.create("my-repo")
+# Returns the absolute path to the directory
+
+# Get the path (None if workspace doesn't exist)
+path = workspace.path("my-repo")
+
+# List all workspaces owned by this extension
+names = workspace.list()  # ["my-repo", "cache"]
+
+# Delete a workspace and all its contents
+workspace.delete("my-repo")
+
+# Get disk usage in bytes (10-second timeout)
+size = workspace.usage("my-repo")  # 1048576
+```
+
+**Constraints:**
+- Names must match `^[a-z][a-z0-9_]{0,62}$` (lowercase, no spaces or separators).
+- Path traversal and symlink escape are blocked.
+- Quota enforcement via `WORKSPACE_QUOTA_MB` env var (0 = unlimited).
+- Module not available if `WORKSPACE_ROOT` is unset or not writable.
+  Use `settings.has_capability("workspace")` to check availability.
+
+---
+
 ## Example: automated stage hook
 
 A simple hook that reads a setting, queries data, and advances:
@@ -294,3 +447,30 @@ def on_run(ctx):
 
     return {"advance": True, "data": {"needs_review": False}}
 ```
+
+---
+
+## `forms` Module (v0.9.5)
+
+**Permission:** `forms.validate`
+
+Validates form data against a typed form template.
+
+### `forms.validate(template, data)`
+
+Validates `data` (a dict) against a `template` (a dict matching the TypedFormTemplate schema).
+
+Returns a dict: `{"valid": True/False, "errors": [{"key": "...", "message": "..."}]}`.
+
+```python
+result = forms.validate(
+    {"fields": [{"key": "name", "type": "text", "label": "Name", "required": True}]},
+    {"name": "Alice"},
+)
+# result["valid"] == True
+# result["errors"] == []
+```
+
+Field types: `text`, `email`, `select`, `number`, `date`, `textarea`, `checkbox`, `file`.
+
+Supports: required checks, min/max length, pattern (regex), number range, date range, select option whitelist, conditional visibility (`condition.when`/`op`/`value`).

docs/USABILITY-SURVEY.md

@@ -1,227 +0,0 @@
-# Armature Usability Survey — Automated Checklist
-
-> **Purpose**: Machine-auditable quality gate for the Armature UI.
-> Run all scripts first, then walk each section. A FAIL in any section blocks release.
-
----
-
-## Prerequisites
-
-Run these scripts from the project root and save their output:
-
-```bash
-bash scripts/generate-ui-inventory.sh > ui-inventory.json
-bash scripts/check-contrast.sh > contrast-report.txt
-bash scripts/generate-coverage-matrix.sh > coverage-matrix.md
-bash scripts/audit-touch-targets.sh > touch-targets-report.txt
-```
-
----
-
-## Section 1: Viewport Correctness
-
-**Pass criteria:**
-- No CSS file uses `100vh` (should be `100%` or `100dvh`)
-- `.sw-shell` uses `height: 100%`, not `100vh`
-- All extension surfaces use `height: 100%`
-- No `transform: scale()` for zoom (should use CSS `zoom`)
-
-**Files to inspect:**
-- `src/css/sw-shell.css`
-- `src/css/layout.css`
-- `packages/*/css/main.css`
-
-**How to check:**
-```bash
-grep -rn '100vh' src/css/ packages/*/css/ --include='*.css'
-grep -rn 'transform.*scale' src/css/ packages/*/css/ --include='*.css'
-```
-
-**Result:** PASS if zero matches. FAIL if any `100vh` or `transform: scale()` for layout sizing.
-
----
-
-## Section 2: Banner Integration
-
-**Pass criteria:**
-- Banners are in-flow (no `position: fixed` on banner elements)
-- `--banner-top-height` and `--banner-bottom-height` are defined in `:root`
-- Shell layout accounts for banner height via CSS variables, not hardcoded px
-- No surface hardcodes `28px` or other banner height values
-
-**Files to inspect:**
-- `src/css/sw-shell.css`
-- `src/css/variables.css` (`:root` block)
-- `src/js/sw/shell/app-shell.js`
-
-**How to check:**
-```bash
-grep -n 'position.*fixed' src/css/sw-shell.css | grep -i banner
-grep -n '28px' src/css/ -r --include='*.css'
-grep -n 'banner-top-height\|banner-bottom-height' src/css/variables.css
-```
-
-**Result:** PASS if banners are in-flow and height is variable-driven. FAIL if fixed positioning or hardcoded heights.
-
----
-
-## Section 3: Responsive Behavior
-
-**Pass criteria:**
-- Kernel CSS uses `768px` (mobile) and `1024px` (tablet) breakpoints
-- No hardcoded widths that break below 768px (except intentional min-widths on dialogs)
-- Sidebar collapses on mobile
-- Extension surfaces adapt to narrow viewports
-
-**Files to inspect:**
-- `src/css/layout.css`
-- `src/css/surfaces.css`
-- `packages/*/css/main.css`
-
-**How to check:**
-```bash
-# Verify breakpoints used
-grep -rn '@media.*max-width' src/css/ --include='*.css' | grep -v '768\|1024'
-# Check for hardcoded widths
-grep -rn 'width:.*[0-9]\+px' src/css/layout.css | grep -v 'max-width\|min-width\|--'
-```
-
-**Result:** PASS if only 768px and 1024px breakpoints. WARN if other breakpoints exist but are justified. FAIL if layout breaks below 768px.
-
----
-
-## Section 4: Styling Consistency
-
-**Pass criteria:**
-- All spacing uses `--sp-*` tokens (no raw px for padding/margin/gap > 3px)
-- All `border-radius` uses `--radius-sm`, `--radius`, or `--radius-lg`
-- All `font-family` uses `var(--font)` or `var(--mono)`
-- No external font CDN imports (`@import url(` or Google Fonts references)
-- No stale fallback colors (`#b38a4e` or other non-token hex in property values)
-
-**Files to inspect:**
-- All `src/css/*.css`
-- `packages/*/css/main.css`
-
-**How to check:**
-```bash
-# Raw px spacing (padding/margin/gap > 3px, not inside var())
-grep -rnE '(padding|margin|gap):\s*[0-9]+(px|rem)' src/css/ packages/*/css/ --include='*.css' | grep -v 'var(--' | grep -v '0px\|1px\|2px\|3px'
-# Raw border-radius
-grep -rn 'border-radius:' src/css/ packages/*/css/ --include='*.css' | grep -v 'var(--radius'
-# External fonts
-grep -rn '@import url\|fonts.googleapis' src/css/ --include='*.css'
-# Stale fallback gold color
-grep -rn '#b38a4e' src/css/ packages/*/css/ --include='*.css'
-```
-
-**Result:** PASS if zero non-token values (excluding reset/keyframe contexts). WARN for 1-3 edge cases with justification. FAIL for systematic violations.
-
----
-
-## Section 5: Accessibility — Contrast
-
-**Pass criteria:**
-- `contrast-report.txt` shows all PASS for normal text (4.5:1 ratio)
-- No FAIL results in either dark or light theme
-
-**Files to inspect:**
-- `contrast-report.txt` (generated above)
-
-**How to check:**
-```bash
-grep 'FAIL' contrast-report.txt
-```
-
-**Result:** PASS if zero FAIL lines. FAIL if any contrast violation.
-
----
-
-## Section 6: Accessibility — Touch Targets
-
-**Pass criteria:**
-- `touch-targets-report.txt` shows zero violations
-- All close buttons have `min-width: 44px; min-height: 44px` in `@media (max-width: 768px)`
-- Menu items have `min-height: 44px` on mobile (already done in `sw-primitives.css`)
-
-**Files to inspect:**
-- `touch-targets-report.txt` (generated above)
-- `src/css/sw-primitives.css` — close button rules
-
-**How to check:**
-```bash
-grep 'FAIL\|MISSING' touch-targets-report.txt
-```
-
-**Result:** PASS if zero violations. FAIL if any close button lacks mobile touch target.
-
----
-
-## Section 7: Accessibility — Focus Indicators
-
-**Pass criteria:**
-- All interactive primitives have `:focus-visible` styles
-- No `outline: none` without a replacement focus indicator
-- Focus ring is visible on both dark and light themes
-
-**Files to inspect:**
-- `src/css/sw-primitives.css`
-- `src/css/primitives.css`
-- `src/css/variables.css`
-
-**How to check:**
-```bash
-# Check for focus-visible on key primitives
-for cls in sw-btn sw-input sw-dropdown__trigger sw-menu__item sw-tabs__tab; do
-  echo -n "$cls: "
-  grep -c "\.${cls}.*:focus-visible\|\.${cls}:focus-visible" src/css/sw-primitives.css src/css/primitives.css 2>/dev/null || echo "0"
-done
-# Check for outline:none without replacement
-grep -n 'outline.*none\|outline.*0' src/css/*.css | grep -v 'focus-visible\|focus-within'
-```
-
-**Result:** PASS if all 5 key primitives have `:focus-visible`. WARN if outline:none exists with adequate replacement. FAIL if missing focus indicators.
-
----
-
-## Section 8: Component Uniformity
-
-**Pass criteria:**
-- `coverage-matrix.md` shows no deprecated component usage (no ⚠ in the deprecated row)
-- All surfaces use `sw-*` primitives, not old `.btn-*`, `.toast`, `.popup-menu`
-
-**Files to inspect:**
-- `coverage-matrix.md` (generated above)
-
-**How to check:**
-```bash
-grep '⚠' coverage-matrix.md
-```
-
-**Result:** PASS if zero ⚠ markers. FAIL if any deprecated component still in use.
-
----
-
-## Scoring
-
-| Section | Weight | Result |
-|---------|--------|--------|
-| 1. Viewport Correctness | Required | |
-| 2. Banner Integration | Required | |
-| 3. Responsive Behavior | Required | |
-| 4. Styling Consistency | Required | |
-| 5. Contrast | Required | |
-| 6. Touch Targets | Required | |
-| 7. Focus Indicators | Required | |
-| 8. Component Uniformity | Required | |
-
-**Overall:** PASS requires all sections PASS or WARN. Any FAIL blocks the release.
-
----
-
-## After the Survey
-
-1. Fix all FAIL items
-2. Re-run affected scripts to confirm fixes
-3. Re-run the full survey
-4. Tag `v0.6.16` only after a clean survey pass

packages/bug-report-triage/manifest.json

@@ -19,7 +19,6 @@
         "ordinal": 0,
         "stage_mode": "form",
         "audience": "public",
-        "stage_type": "simple",
         "auto_transition": false,
         "form_template": {
           "fieldsets": [
@@ -48,7 +47,6 @@
         "ordinal": 1,
         "stage_mode": "form",
         "audience": "team",
-        "stage_type": "simple",
         "auto_transition": false,
         "form_template": {
           "fieldsets": [
@@ -71,7 +69,6 @@
         "ordinal": 2,
         "stage_mode": "form",
         "audience": "team",
-        "stage_type": "simple",
         "auto_transition": false,
         "sla_seconds": 3600,
         "form_template": {
@@ -91,7 +88,6 @@
         "ordinal": 3,
         "stage_mode": "form",
         "audience": "team",
-        "stage_type": "simple",
         "auto_transition": false,
         "form_template": {
           "fieldsets": [
@@ -108,9 +104,8 @@
       {
         "name": "verify",
         "ordinal": 4,
-        "stage_mode": "review",
+        "stage_mode": "form",
         "audience": "team",
-        "stage_type": "simple",
         "auto_transition": false,
         "form_template": {
           "fieldsets": [

packages/content-approval/manifest.json

@@ -19,7 +19,6 @@
         "ordinal": 0,
         "stage_mode": "form",
         "audience": "team",
-        "stage_type": "simple",
         "auto_transition": false,
         "form_template": {
           "fieldsets": [
@@ -37,9 +36,8 @@
       {
         "name": "review",
         "ordinal": 1,
-        "stage_mode": "review",
+        "stage_mode": "form",
         "audience": "team",
-        "stage_type": "simple",
         "auto_transition": false,
         "stage_config": {
           "validation": {
@@ -53,7 +51,6 @@
         "ordinal": 2,
         "stage_mode": "form",
         "audience": "team",
-        "stage_type": "simple",
         "auto_transition": false,
         "form_template": {
           "fieldsets": [
@@ -76,7 +73,6 @@
         "ordinal": 3,
         "stage_mode": "form",
         "audience": "team",
-        "stage_type": "simple",
         "auto_transition": false,
         "form_template": {
           "fieldsets": [

packages/employee-onboarding/manifest.json

@@ -40,7 +40,6 @@
         "ordinal": 0,
         "stage_mode": "form",
         "audience": "team",
-        "stage_type": "simple",
         "auto_transition": false,
         "form_template": {
           "fieldsets": [
@@ -69,16 +68,14 @@
         "ordinal": 1,
         "stage_mode": "automated",
         "audience": "system",
-        "stage_type": "automated",
         "auto_transition": true,
         "starlark_hook": "employee-onboarding:on_provision"
       },
       {
         "name": "manager-signoff",
         "ordinal": 2,
-        "stage_mode": "review",
+        "stage_mode": "form",
         "audience": "team",
-        "stage_type": "simple",
         "auto_transition": false,
         "stage_config": {
           "validation": {
@@ -93,7 +90,6 @@
         "ordinal": 3,
         "stage_mode": "form",
         "audience": "team",
-        "stage_type": "simple",
         "auto_transition": false,
         "form_template": {
           "fieldsets": [
@@ -113,7 +109,6 @@
         "ordinal": 4,
         "stage_mode": "automated",
         "audience": "system",
-        "stage_type": "automated",
         "auto_transition": true,
         "starlark_hook": "employee-onboarding:on_welcome"
       }

packages/icd-test-runner/js/crud/team-workflows.js

@@ -82,7 +82,7 @@
         name: 'Team Intake',
         ordinal: 0,
         history_mode: 'full',
-        stage_mode: 'chat_only'
+        stage_mode: 'form'
       });
       T.assertShape(d, T.S.workflowStage, 'stage');
       T.assert(d.name === 'Team Intake', 'name mismatch');
@@ -94,7 +94,7 @@
         name: 'Team Review',
         ordinal: 1,
         history_mode: 'summary',
-        stage_mode: 'review'
+        stage_mode: 'form'
       });
       T.assertShape(d, T.S.workflowStage, 'stage');
       stageIds.push(d.id);
@@ -111,7 +111,7 @@
         name: 'Team Intake (updated)',
         ordinal: 0,
         history_mode: 'full',
-        stage_mode: 'form_chat',
+        stage_mode: 'form',
         form_template: { fields: [{ key: 'name', type: 'text', label: 'Name', required: true }] }
       });
       T.assert(typeof d === 'object', 'expected object');

packages/icd-test-runner/js/crud/workflows.js

@@ -408,7 +408,7 @@
         var fwfSlug = testTag + '-form-wf';
         var fChannelId = null;
 
-        await T.test('crud', 'workflows', 'form: create form_only workflow', async function () {
+        await T.test('crud', 'workflows', 'form: create form workflow', async function () {
           var wf = await T.apiPost('/workflows', {
             name: testTag + ' Form WF',
             slug: fwfSlug,
@@ -422,7 +422,7 @@
             name: 'Contact Info',
             ordinal: 0,
             history_mode: 'full',
-            stage_mode: 'form_only',
+            stage_mode: 'form',
             form_template: {
               fields: [
                 { key: 'name', type: 'text', label: 'Full Name', required: true, validation: { min_length: 2 } },
@@ -436,7 +436,7 @@
           });
 
           await T.apiPost('/workflows/' + fwfId + '/stages', {
-            name: 'Done', ordinal: 1, history_mode: 'full', stage_mode: 'chat_only'
+            name: 'Done', ordinal: 1, history_mode: 'full', stage_mode: 'form'
           });
 
           await T.apiPatch('/workflows/' + fwfId, { is_active: true });
@@ -456,7 +456,7 @@
               var d = await T.sessionGet('/w/' + fChannelId + '/form');
               T.assert(d._status === 200, 'expected 200, got ' + d._status);
               T.assertHasKey(d, 'stage_mode', 'form response');
-              T.assert(d.stage_mode === 'form_only', 'expected form_only, got ' + d.stage_mode);
+              T.assert(d.stage_mode === 'form', 'expected form, got ' + d.stage_mode);
               T.assertHasKey(d, 'form_template', 'form response');
               T.assert(d.form_template.fields && d.form_template.fields.length === 3,
                 'expected 3 fields, got ' + (d.form_template.fields ? d.form_template.fields.length : 0));
@@ -520,7 +520,7 @@
         var xwfSlug = testTag + '-xvisitor';
         var chA = null, chB = null;
 
-        await T.test('crud', 'workflows', 'xvisitor: setup form_only workflow', async function () {
+        await T.test('crud', 'workflows', 'xvisitor: setup form workflow', async function () {
           var wf = await T.apiPost('/workflows', {
             name: testTag + ' XVisitor',
             slug: xwfSlug,
@@ -530,7 +530,7 @@
           T.registerCleanup(function () { if (xwfId) return T.safeDelete('/workflows/' + xwfId); });
 
           await T.apiPost('/workflows/' + xwfId + '/stages', {
-            name: 'Form', ordinal: 0, stage_mode: 'form_only', history_mode: 'full',
+            name: 'Form', ordinal: 0, stage_mode: 'form', history_mode: 'full',
             form_template: {
               fields: [{ key: 'name', type: 'text', label: 'Name', required: true }]
             }
@@ -627,7 +627,7 @@
             var s1 = await T.apiPost('/workflows/' + wpWfId + '/stages', {
               name: 'Intake',
               ordinal: 0,
-              stage_mode: 'form_only',
+              stage_mode: 'form',
               history_mode: 'full',
               form_template: { fields: [{ key: 'name', type: 'text', label: 'Full Name', required: true }] }
             });
@@ -637,7 +637,7 @@
             var s2 = await T.apiPost('/workflows/' + wpWfId + '/stages', {
               name: 'Review',
               ordinal: 1,
-              stage_mode: 'review',
+              stage_mode: 'form',
               history_mode: 'summary'
             });
             T.assertShape(s2, T.S.workflowStage, 'stage2');
@@ -650,7 +650,7 @@
             // Use the ICD test runner's own package ID (always installed when tests run).
             var realPkgId = 'icd-test-runner';
             var stageBase = {
-              name: 'Intake', ordinal: 0, stage_mode: 'form_only', history_mode: 'full',
+              name: 'Intake', ordinal: 0, stage_mode: 'form', history_mode: 'full',
               form_template: { fields: [{ key: 'name', type: 'text', label: 'Full Name', required: true }] }
             };
 
@@ -720,8 +720,8 @@
               T.assert(stList.length === 2, 'should have 2 stages, got ' + stList.length);
               T.assert(stList[0].name === 'Intake', 'stage 0 name should be Intake');
               T.assert(stList[1].name === 'Review', 'stage 1 name should be Review');
-              T.assert(stList[0].stage_mode === 'form_only', 'stage 0 mode should be form_only');
+              T.assert(stList[0].stage_mode === 'form', 'stage 0 mode should be form');
-              T.assert(stList[1].stage_mode === 'review', 'stage 1 mode should be review');
+              T.assert(stList[1].stage_mode === 'form', 'stage 1 mode should be form');
             });
           }
 

packages/webhook-notifier/manifest.json

@@ -30,7 +30,6 @@
         "ordinal": 0,
         "stage_mode": "form",
         "audience": "team",
-        "stage_type": "simple",
         "auto_transition": false,
         "form_template": {
           "fieldsets": [
@@ -50,16 +49,14 @@
         "ordinal": 1,
         "stage_mode": "automated",
         "audience": "system",
-        "stage_type": "automated",
         "auto_transition": true,
         "starlark_hook": "webhook-notifier:on_fire"
       },
       {
         "name": "result",
         "ordinal": 2,
-        "stage_mode": "review",
+        "stage_mode": "form",
         "audience": "team",
-        "stage_type": "simple",
         "auto_transition": false,
         "form_template": {
           "fieldsets": [

server/config/config.go

@@ -47,6 +47,12 @@ type Config struct {
 	S3Prefix         string // optional key prefix within bucket (e.g. "armature/")
 	S3ForcePathStyle bool   // use path-style URLs (required for MinIO, most self-hosted)
 
+	// Extension workspaces
+	// WORKSPACE_ROOT: mount point for extension-managed directories (default /data/workspaces).
+	// WORKSPACE_QUOTA_MB: per-extension quota in MB (default 0 = unlimited).
+	WorkspaceRoot    string
+	WorkspaceQuotaMB int
+
 	// Structured logging
 	// LOG_FORMAT: "text" (default, backward-compatible) or "json" (structured).
 	// LOG_LEVEL: "debug", "info" (default), "warn", "error".
@@ -143,6 +149,9 @@ func Load() *Config {
 		S3Prefix:              getEnv("S3_PREFIX", ""),
 		S3ForcePathStyle:      getEnv("S3_FORCE_PATH_STYLE", "true") == "true",
 
+		WorkspaceRoot:    getEnv("WORKSPACE_ROOT", "/data/workspaces"),
+		WorkspaceQuotaMB: getEnvInt("WORKSPACE_QUOTA_MB", 0),
+
 		SkipBundledPackages: getEnvBool("SKIP_BUNDLED_PACKAGES", false),
 		BundledPackagesDir:  getEnv("BUNDLED_PACKAGES_DIR", "/app/bundled-packages"),
 		BundledPackages:     getEnv("BUNDLED_PACKAGES", ""),

server/database/migrations/postgres/016_team_user_roles.sql

@@ -0,0 +1,17 @@
+-- ==========================================
+-- Armature — 016 Team User Roles (many-to-many)
+-- ==========================================
+
+CREATE TABLE IF NOT EXISTS team_user_roles (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    team_id     UUID NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
+    user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    role        VARCHAR(50) NOT NULL,
+    assigned_by UUID REFERENCES users(id) ON DELETE SET NULL,
+    assigned_at TIMESTAMPTZ DEFAULT NOW(),
+    UNIQUE(team_id, user_id, role)
+);
+
+CREATE INDEX IF NOT EXISTS idx_team_user_roles_team_user ON team_user_roles(team_id, user_id);
+CREATE INDEX IF NOT EXISTS idx_team_user_roles_team ON team_user_roles(team_id);
+CREATE INDEX IF NOT EXISTS idx_team_user_roles_user ON team_user_roles(user_id);

server/database/migrations/postgres/017_package_adoption.sql

@@ -0,0 +1,21 @@
+-- ==========================================
+-- Armature — 017 Package Adoption + Role Catalog
+-- ==========================================
+
+-- Add adoptable flag and adoption lineage to packages
+ALTER TABLE packages ADD COLUMN IF NOT EXISTS adoptable   BOOLEAN NOT NULL DEFAULT false;
+ALTER TABLE packages ADD COLUMN IF NOT EXISTS adopted_from TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_packages_adoptable ON packages(adoptable) WHERE adoptable = true;
+
+-- Team role catalog: known roles sourced from adopted packages
+CREATE TABLE IF NOT EXISTS team_role_catalog (
+    id                UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    team_id           UUID NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
+    role              VARCHAR(50) NOT NULL,
+    source_package_id TEXT REFERENCES packages(id) ON DELETE SET NULL,
+    created_at        TIMESTAMPTZ DEFAULT NOW(),
+    UNIQUE(team_id, role)
+);
+
+CREATE INDEX IF NOT EXISTS idx_team_role_catalog_team ON team_role_catalog(team_id);

server/database/migrations/postgres/018_stage_mode_collapse.sql

@@ -0,0 +1,13 @@
+-- Armature — 018 Stage Mode Collapse
+-- Deprecate stage_type validation. Collapse stage_mode: review → form.
+
+-- 1. Migrate existing review rows to form
+UPDATE workflow_stages SET stage_mode = 'form' WHERE stage_mode = 'review';
+
+-- 2. Replace CHECK constraint on stage_mode (drop review)
+ALTER TABLE workflow_stages DROP CONSTRAINT IF EXISTS workflow_stages_stage_mode_check;
+ALTER TABLE workflow_stages ADD CONSTRAINT workflow_stages_stage_mode_check
+    CHECK (stage_mode IN ('form', 'delegated', 'automated'));
+
+-- 3. Drop CHECK constraint on stage_type (any value accepted)
+ALTER TABLE workflow_stages DROP CONSTRAINT IF EXISTS workflow_stages_stage_type_check;

server/database/migrations/sqlite/016_team_user_roles.sql

@@ -0,0 +1,17 @@
+-- ==========================================
+-- Armature — 016 Team User Roles (many-to-many, SQLite)
+-- ==========================================
+
+CREATE TABLE IF NOT EXISTS team_user_roles (
+    id          TEXT PRIMARY KEY,
+    team_id     TEXT NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
+    user_id     TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    role        TEXT NOT NULL,
+    assigned_by TEXT REFERENCES users(id) ON DELETE SET NULL,
+    assigned_at TEXT DEFAULT (datetime('now')),
+    UNIQUE(team_id, user_id, role)
+);
+
+CREATE INDEX IF NOT EXISTS idx_team_user_roles_team_user ON team_user_roles(team_id, user_id);
+CREATE INDEX IF NOT EXISTS idx_team_user_roles_team ON team_user_roles(team_id);
+CREATE INDEX IF NOT EXISTS idx_team_user_roles_user ON team_user_roles(user_id);

server/database/migrations/sqlite/017_package_adoption.sql

@@ -0,0 +1,21 @@
+-- ==========================================
+-- Armature — 017 Package Adoption + Role Catalog (SQLite)
+-- ==========================================
+
+-- Add adoptable flag and adoption lineage to packages
+ALTER TABLE packages ADD COLUMN adoptable   INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE packages ADD COLUMN adopted_from TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_packages_adoptable ON packages(adoptable);
+
+-- Team role catalog: known roles sourced from adopted packages
+CREATE TABLE IF NOT EXISTS team_role_catalog (
+    id                TEXT PRIMARY KEY,
+    team_id           TEXT NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
+    role              TEXT NOT NULL,
+    source_package_id TEXT REFERENCES packages(id) ON DELETE SET NULL,
+    created_at        TEXT DEFAULT (datetime('now')),
+    UNIQUE(team_id, role)
+);
+
+CREATE INDEX IF NOT EXISTS idx_team_role_catalog_team ON team_role_catalog(team_id);

server/database/migrations/sqlite/018_stage_mode_collapse.sql

@@ -0,0 +1,5 @@
+-- Armature — 018 Stage Mode Collapse
+-- Deprecate stage_type validation. Collapse stage_mode: review → form.
+-- SQLite cannot ALTER CHECK constraints; app layer prevents new "review" inserts.
+
+UPDATE workflow_stages SET stage_mode = 'form' WHERE stage_mode = 'review';

server/forms/forms.go

@@ -0,0 +1,347 @@
+package forms
+
+// forms.go
+//
+// Standalone typed form system extracted from models/workflow.go (v0.9.5).
+// Any package can declare and validate forms — not just workflow stages.
+//
+// Schema:
+//   TypedFormTemplate → []FormField | []FormFieldset
+//   FormField         → key, type, label, validation, condition, …
+//   FormValidation    → type-specific rules (length, pattern, range, date, file)
+//   FieldCondition    → conditional visibility (eq, neq, in, exists)
+//   FormHooks         → Starlark validate / on_submit entry points
+//
+// Functions:
+//   ParseTypedFormTemplate(raw) → *TypedFormTemplate
+//   ValidateFormData(tpl, data) → []FieldError
+
+import (
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"strings"
+	"time"
+)
+
+// ── Types ────────────────────────────────────
+
+// TypedFormTemplate is the structured form_template schema.
+type TypedFormTemplate struct {
+	Fields    []FormField    `json:"fields"`
+	Fieldsets []FormFieldset `json:"fieldsets,omitempty"`
+	Hooks     *FormHooks     `json:"hooks,omitempty"`
+}
+
+// FormFieldset groups fields into a labelled step for progressive forms.
+// When fieldsets is present, top-level fields is ignored.
+type FormFieldset struct {
+	Label  string      `json:"label"`
+	Fields []FormField `json:"fields"`
+}
+
+// FieldCondition controls conditional visibility of a form field.
+// When set, the field is shown/validated only if the condition is met.
+type FieldCondition struct {
+	When  string `json:"when"`            // key of the field to check
+	Op    string `json:"op,omitempty"`    // eq (default) | neq | in | exists
+	Value any    `json:"value,omitempty"` // value to compare against
+}
+
+// FormField is a single field in a typed form template.
+type FormField struct {
+	Key         string          `json:"key"`
+	Type        string          `json:"type"` // text | email | select | number | date | textarea | checkbox | file
+	Label       string          `json:"label"`
+	Placeholder string          `json:"placeholder,omitempty"`
+	Required    bool            `json:"required,omitempty"`
+	Default     interface{}     `json:"default,omitempty"`
+	Options     []FormOption    `json:"options,omitempty"`
+	Validation  *FormValidation `json:"validation,omitempty"`
+	Condition   *FieldCondition `json:"condition,omitempty"`
+}
+
+// FormOption is a choice for select fields.
+type FormOption struct {
+	Value string `json:"value"`
+	Label string `json:"label"`
+}
+
+// FormValidation holds type-specific validation rules.
+type FormValidation struct {
+	MinLength *int     `json:"min_length,omitempty"` // text, textarea, email
+	MaxLength *int     `json:"max_length,omitempty"` // text, textarea, email
+	Pattern   string   `json:"pattern,omitempty"`    // text, email (regex)
+	Min       *float64 `json:"min,omitempty"`        // number
+	Max       *float64 `json:"max,omitempty"`        // number
+	Step      *float64 `json:"step,omitempty"`       // number
+	MinDate   string   `json:"min_date,omitempty"`   // date (YYYY-MM-DD)
+	MaxDate   string   `json:"max_date,omitempty"`   // date (YYYY-MM-DD)
+	Accept    string   `json:"accept,omitempty"`     // file (MIME types)
+	MaxSize   *int64   `json:"max_size_bytes,omitempty"` // file
+}
+
+// FormHooks wires Starlark validation/submission hooks for a form.
+type FormHooks struct {
+	PackageID string `json:"package_id"`
+	Validate  string `json:"validate,omitempty"`  // entry point name
+	OnSubmit  string `json:"on_submit,omitempty"` // entry point name
+}
+
+// ValidFormFieldTypes is the set of recognized field types.
+var ValidFormFieldTypes = map[string]bool{
+	"text": true, "email": true, "select": true, "number": true,
+	"date": true, "textarea": true, "checkbox": true, "file": true,
+}
+
+// ── Parsing ──────────────────────────────────
+
+// ParseTypedFormTemplate parses a raw JSON form_template into the typed schema.
+// Returns nil if the template is empty, legacy format, or not a typed template.
+func ParseTypedFormTemplate(raw json.RawMessage) *TypedFormTemplate {
+	if len(raw) == 0 || string(raw) == "{}" || string(raw) == "null" {
+		return nil
+	}
+	var tpl TypedFormTemplate
+	if err := json.Unmarshal(raw, &tpl); err != nil {
+		return nil
+	}
+
+	if len(tpl.Fieldsets) > 0 {
+		var allFields []FormField
+		for _, fs := range tpl.Fieldsets {
+			allFields = append(allFields, fs.Fields...)
+		}
+		if len(allFields) > 0 {
+			tpl.Fields = allFields
+			return &tpl
+		}
+	}
+
+	if len(tpl.Fields) == 0 {
+		return nil
+	}
+	// Verify this is actually the typed format (first field must have key+type)
+	if tpl.Fields[0].Key == "" || tpl.Fields[0].Type == "" {
+		return nil
+	}
+	return &tpl
+}
+
+// AllFields returns all fields from the template, whether from top-level fields or fieldsets.
+func (t *TypedFormTemplate) AllFields() []FormField {
+	return t.Fields // ParseTypedFormTemplate already flattens fieldsets into Fields
+}
+
+// ── Validation ───────────────────────────────
+
+// FieldError is a validation error for a specific form field.
+type FieldError struct {
+	Key     string `json:"key"`
+	Message string `json:"message"`
+}
+
+// ValidateFormData validates submitted data against a typed form template.
+func ValidateFormData(tpl *TypedFormTemplate, data map[string]interface{}) []FieldError {
+	var errs []FieldError
+	for _, f := range tpl.Fields {
+		if f.Condition != nil && !evaluateFieldCondition(f.Condition, data) {
+			continue
+		}
+
+		val, present := data[f.Key]
+
+		// Required check
+		if f.Required && (!present || val == nil || val == "") {
+			errs = append(errs, FieldError{Key: f.Key, Message: f.Label + " is required"})
+			continue
+		}
+		if !present || val == nil {
+			continue
+		}
+
+		switch f.Type {
+		case "text", "textarea":
+			errs = append(errs, validateString(f, val)...)
+		case "email":
+			errs = append(errs, validateEmail(f, val)...)
+		case "number":
+			errs = append(errs, validateNumber(f, val)...)
+		case "date":
+			errs = append(errs, validateDate(f, val)...)
+		case "select":
+			errs = append(errs, validateSelect(f, val)...)
+		case "checkbox":
+			if _, ok := val.(bool); !ok {
+				errs = append(errs, FieldError{Key: f.Key, Message: f.Label + " must be true or false"})
+			}
+		}
+	}
+	return errs
+}
+
+func validateString(f FormField, val interface{}) []FieldError {
+	s, ok := val.(string)
+	if !ok {
+		return []FieldError{{Key: f.Key, Message: f.Label + " must be text"}}
+	}
+	var errs []FieldError
+	v := f.Validation
+	if v == nil {
+		return nil
+	}
+	if v.MinLength != nil && len(s) < *v.MinLength {
+		errs = append(errs, FieldError{Key: f.Key, Message: fmt.Sprintf("%s must be at least %d characters", f.Label, *v.MinLength)})
+	}
+	if v.MaxLength != nil && len(s) > *v.MaxLength {
+		errs = append(errs, FieldError{Key: f.Key, Message: fmt.Sprintf("%s must be at most %d characters", f.Label, *v.MaxLength)})
+	}
+	if v.Pattern != "" {
+		if re, err := regexp.Compile(v.Pattern); err == nil && !re.MatchString(s) {
+			errs = append(errs, FieldError{Key: f.Key, Message: f.Label + " does not match the required pattern"})
+		}
+	}
+	return errs
+}
+
+var emailRe = regexp.MustCompile(`^[^@\s]+@[^@\s]+\.[^@\s]+$`)
+
+func validateEmail(f FormField, val interface{}) []FieldError {
+	s, ok := val.(string)
+	if !ok {
+		return []FieldError{{Key: f.Key, Message: f.Label + " must be text"}}
+	}
+	if !emailRe.MatchString(s) {
+		return []FieldError{{Key: f.Key, Message: f.Label + " must be a valid email address"}}
+	}
+	var errs []FieldError
+	if f.Validation != nil {
+		if f.Validation.Pattern != "" {
+			if re, err := regexp.Compile(f.Validation.Pattern); err == nil && !re.MatchString(s) {
+				errs = append(errs, FieldError{Key: f.Key, Message: f.Label + " does not match the required pattern"})
+			}
+		}
+	}
+	return errs
+}
+
+func validateNumber(f FormField, val interface{}) []FieldError {
+	var n float64
+	switch v := val.(type) {
+	case float64:
+		n = v
+	case int:
+		n = float64(v)
+	case json.Number:
+		var err error
+		n, err = v.Float64()
+		if err != nil {
+			return []FieldError{{Key: f.Key, Message: f.Label + " must be a number"}}
+		}
+	case string:
+		return []FieldError{{Key: f.Key, Message: f.Label + " must be a number"}}
+	default:
+		return []FieldError{{Key: f.Key, Message: f.Label + " must be a number"}}
+	}
+	var errs []FieldError
+	if f.Validation != nil {
+		if f.Validation.Min != nil && n < *f.Validation.Min {
+			errs = append(errs, FieldError{Key: f.Key, Message: fmt.Sprintf("%s must be at least %g", f.Label, *f.Validation.Min)})
+		}
+		if f.Validation.Max != nil && n > *f.Validation.Max {
+			errs = append(errs, FieldError{Key: f.Key, Message: fmt.Sprintf("%s must be at most %g", f.Label, *f.Validation.Max)})
+		}
+	}
+	return errs
+}
+
+func validateDate(f FormField, val interface{}) []FieldError {
+	s, ok := val.(string)
+	if !ok {
+		return []FieldError{{Key: f.Key, Message: f.Label + " must be a date string (YYYY-MM-DD)"}}
+	}
+	_, err := time.Parse("2006-01-02", s)
+	if err != nil {
+		return []FieldError{{Key: f.Key, Message: f.Label + " must be a valid date (YYYY-MM-DD)"}}
+	}
+	if f.Validation != nil {
+		if f.Validation.MinDate != "" {
+			if minD, e := time.Parse("2006-01-02", f.Validation.MinDate); e == nil {
+				if d, _ := time.Parse("2006-01-02", s); d.Before(minD) {
+					return []FieldError{{Key: f.Key, Message: fmt.Sprintf("%s must be on or after %s", f.Label, f.Validation.MinDate)}}
+				}
+			}
+		}
+		if f.Validation.MaxDate != "" {
+			if maxD, e := time.Parse("2006-01-02", f.Validation.MaxDate); e == nil {
+				if d, _ := time.Parse("2006-01-02", s); d.After(maxD) {
+					return []FieldError{{Key: f.Key, Message: fmt.Sprintf("%s must be on or before %s", f.Label, f.Validation.MaxDate)}}
+				}
+			}
+		}
+	}
+	return nil
+}
+
+func validateSelect(f FormField, val interface{}) []FieldError {
+	s, ok := val.(string)
+	if !ok {
+		return []FieldError{{Key: f.Key, Message: f.Label + " must be a string"}}
+	}
+	if len(f.Options) == 0 {
+		return nil
+	}
+	for _, o := range f.Options {
+		if strings.EqualFold(o.Value, s) {
+			return nil
+		}
+	}
+	return []FieldError{{Key: f.Key, Message: f.Label + " is not a valid option"}}
+}
+
+// ── Field Condition Evaluator ─────
+
+// EvaluateFieldCondition checks if a conditional field should be visible/validated.
+func EvaluateFieldCondition(cond *FieldCondition, data map[string]interface{}) bool {
+	return evaluateFieldCondition(cond, data)
+}
+
+func evaluateFieldCondition(cond *FieldCondition, data map[string]interface{}) bool {
+	val, exists := data[cond.When]
+	op := cond.Op
+	if op == "" {
+		op = "eq"
+	}
+
+	switch op {
+	case "exists":
+		return exists
+	case "eq":
+		if !exists {
+			return false
+		}
+		return fmt.Sprintf("%v", val) == fmt.Sprintf("%v", cond.Value)
+	case "neq":
+		if !exists {
+			return true
+		}
+		return fmt.Sprintf("%v", val) != fmt.Sprintf("%v", cond.Value)
+	case "in":
+		if !exists {
+			return false
+		}
+		arr, ok := cond.Value.([]interface{})
+		if !ok {
+			return false
+		}
+		vs := fmt.Sprintf("%v", val)
+		for _, item := range arr {
+			if fmt.Sprintf("%v", item) == vs {
+				return true
+			}
+		}
+		return false
+	default:
+		return true
+	}
+}

server/forms/forms_test.go

@@ -0,0 +1,322 @@
+package forms
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+// ── Parse Tests ──────────────────────────────
+
+func TestParseTypedFormTemplate_Empty(t *testing.T) {
+	for _, input := range []string{"", "{}", "null"} {
+		if tpl := ParseTypedFormTemplate(json.RawMessage(input)); tpl != nil {
+			t.Errorf("expected nil for %q, got %+v", input, tpl)
+		}
+	}
+}
+
+func TestParseTypedFormTemplate_InvalidJSON(t *testing.T) {
+	if tpl := ParseTypedFormTemplate(json.RawMessage(`{bad`)); tpl != nil {
+		t.Fatal("expected nil for invalid JSON")
+	}
+}
+
+func TestParseTypedFormTemplate_FlatFields(t *testing.T) {
+	raw := json.RawMessage(`{
+		"fields": [
+			{"key": "name", "type": "text", "label": "Name"},
+			{"key": "email", "type": "email", "label": "Email"}
+		]
+	}`)
+	tpl := ParseTypedFormTemplate(raw)
+	if tpl == nil {
+		t.Fatal("expected non-nil template")
+	}
+	if len(tpl.Fields) != 2 {
+		t.Fatalf("expected 2 fields, got %d", len(tpl.Fields))
+	}
+}
+
+func TestParseTypedFormTemplate_Fieldsets(t *testing.T) {
+	raw := json.RawMessage(`{
+		"fieldsets": [
+			{"label": "Step 1", "fields": [{"key": "a", "type": "text", "label": "A"}]},
+			{"label": "Step 2", "fields": [{"key": "b", "type": "number", "label": "B"}]}
+		]
+	}`)
+	tpl := ParseTypedFormTemplate(raw)
+	if tpl == nil {
+		t.Fatal("expected non-nil template")
+	}
+	if len(tpl.Fields) != 2 {
+		t.Fatalf("expected 2 flattened fields, got %d", len(tpl.Fields))
+	}
+	if len(tpl.Fieldsets) != 2 {
+		t.Fatalf("expected 2 fieldsets, got %d", len(tpl.Fieldsets))
+	}
+}
+
+func TestParseTypedFormTemplate_LegacyFormat(t *testing.T) {
+	// Legacy format: fields present but missing key/type → returns nil
+	raw := json.RawMessage(`{"fields": [{"label": "Name"}]}`)
+	if tpl := ParseTypedFormTemplate(raw); tpl != nil {
+		t.Fatal("expected nil for legacy format")
+	}
+}
+
+// ── Validation Tests ─────────────────────────
+
+func tpl(fields ...FormField) *TypedFormTemplate {
+	return &TypedFormTemplate{Fields: fields}
+}
+
+func intPtr(n int) *int          { return &n }
+func floatPtr(n float64) *float64 { return &n }
+
+func TestValidateFormData_Required(t *testing.T) {
+	template := tpl(FormField{Key: "name", Type: "text", Label: "Name", Required: true})
+
+	// Missing
+	errs := ValidateFormData(template, map[string]interface{}{})
+	if len(errs) != 1 || errs[0].Key != "name" {
+		t.Fatalf("expected 1 error for missing required field, got %+v", errs)
+	}
+
+	// Present
+	errs = ValidateFormData(template, map[string]interface{}{"name": "Alice"})
+	if len(errs) != 0 {
+		t.Fatalf("expected 0 errors, got %+v", errs)
+	}
+
+	// Empty string counts as missing
+	errs = ValidateFormData(template, map[string]interface{}{"name": ""})
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error for empty required field, got %+v", errs)
+	}
+}
+
+func TestValidateFormData_Text(t *testing.T) {
+	template := tpl(FormField{
+		Key: "bio", Type: "text", Label: "Bio",
+		Validation: &FormValidation{MinLength: intPtr(3), MaxLength: intPtr(10), Pattern: `^[a-z]+$`},
+	})
+
+	// Too short
+	errs := ValidateFormData(template, map[string]interface{}{"bio": "ab"})
+	if len(errs) != 1 {
+		t.Fatalf("expected min_length error, got %+v", errs)
+	}
+
+	// Too long
+	errs = ValidateFormData(template, map[string]interface{}{"bio": "abcdefghijk"})
+	if len(errs) != 1 {
+		t.Fatalf("expected max_length error, got %+v", errs)
+	}
+
+	// Pattern mismatch
+	errs = ValidateFormData(template, map[string]interface{}{"bio": "ABC"})
+	if len(errs) != 1 {
+		t.Fatalf("expected pattern error, got %+v", errs)
+	}
+
+	// Valid
+	errs = ValidateFormData(template, map[string]interface{}{"bio": "hello"})
+	if len(errs) != 0 {
+		t.Fatalf("expected 0 errors, got %+v", errs)
+	}
+}
+
+func TestValidateFormData_Email(t *testing.T) {
+	template := tpl(FormField{Key: "email", Type: "email", Label: "Email"})
+
+	errs := ValidateFormData(template, map[string]interface{}{"email": "bad"})
+	if len(errs) != 1 {
+		t.Fatalf("expected email error, got %+v", errs)
+	}
+
+	errs = ValidateFormData(template, map[string]interface{}{"email": "a@b.c"})
+	if len(errs) != 0 {
+		t.Fatalf("expected 0 errors, got %+v", errs)
+	}
+}
+
+func TestValidateFormData_Number(t *testing.T) {
+	template := tpl(FormField{
+		Key: "age", Type: "number", Label: "Age",
+		Validation: &FormValidation{Min: floatPtr(0), Max: floatPtr(150)},
+	})
+
+	// Below min
+	errs := ValidateFormData(template, map[string]interface{}{"age": float64(-1)})
+	if len(errs) != 1 {
+		t.Fatalf("expected min error, got %+v", errs)
+	}
+
+	// Above max
+	errs = ValidateFormData(template, map[string]interface{}{"age": float64(200)})
+	if len(errs) != 1 {
+		t.Fatalf("expected max error, got %+v", errs)
+	}
+
+	// Non-number
+	errs = ValidateFormData(template, map[string]interface{}{"age": "thirty"})
+	if len(errs) != 1 {
+		t.Fatalf("expected type error, got %+v", errs)
+	}
+
+	// Valid
+	errs = ValidateFormData(template, map[string]interface{}{"age": float64(25)})
+	if len(errs) != 0 {
+		t.Fatalf("expected 0 errors, got %+v", errs)
+	}
+}
+
+func TestValidateFormData_Date(t *testing.T) {
+	template := tpl(FormField{
+		Key: "start", Type: "date", Label: "Start",
+		Validation: &FormValidation{MinDate: "2024-01-01", MaxDate: "2024-12-31"},
+	})
+
+	// Invalid format
+	errs := ValidateFormData(template, map[string]interface{}{"start": "Jan 1"})
+	if len(errs) != 1 {
+		t.Fatalf("expected format error, got %+v", errs)
+	}
+
+	// Before min
+	errs = ValidateFormData(template, map[string]interface{}{"start": "2023-12-31"})
+	if len(errs) != 1 {
+		t.Fatalf("expected min_date error, got %+v", errs)
+	}
+
+	// After max
+	errs = ValidateFormData(template, map[string]interface{}{"start": "2025-01-01"})
+	if len(errs) != 1 {
+		t.Fatalf("expected max_date error, got %+v", errs)
+	}
+
+	// Valid
+	errs = ValidateFormData(template, map[string]interface{}{"start": "2024-06-15"})
+	if len(errs) != 0 {
+		t.Fatalf("expected 0 errors, got %+v", errs)
+	}
+}
+
+func TestValidateFormData_Select(t *testing.T) {
+	template := tpl(FormField{
+		Key: "color", Type: "select", Label: "Color",
+		Options: []FormOption{{Value: "red", Label: "Red"}, {Value: "blue", Label: "Blue"}},
+	})
+
+	errs := ValidateFormData(template, map[string]interface{}{"color": "green"})
+	if len(errs) != 1 {
+		t.Fatalf("expected invalid option error, got %+v", errs)
+	}
+
+	// Case-insensitive match
+	errs = ValidateFormData(template, map[string]interface{}{"color": "Red"})
+	if len(errs) != 0 {
+		t.Fatalf("expected 0 errors (case-insensitive), got %+v", errs)
+	}
+}
+
+func TestValidateFormData_Checkbox(t *testing.T) {
+	template := tpl(FormField{Key: "agree", Type: "checkbox", Label: "Agree"})
+
+	errs := ValidateFormData(template, map[string]interface{}{"agree": "yes"})
+	if len(errs) != 1 {
+		t.Fatalf("expected type error, got %+v", errs)
+	}
+
+	errs = ValidateFormData(template, map[string]interface{}{"agree": true})
+	if len(errs) != 0 {
+		t.Fatalf("expected 0 errors, got %+v", errs)
+	}
+}
+
+func TestValidateFormData_Condition(t *testing.T) {
+	template := tpl(
+		FormField{Key: "type", Type: "select", Label: "Type", Options: []FormOption{{Value: "normal", Label: "Normal"}, {Value: "other", Label: "Other"}}},
+		FormField{
+			Key: "details", Type: "text", Label: "Details", Required: true,
+			Condition: &FieldCondition{When: "type", Op: "eq", Value: "other"},
+		},
+	)
+
+	// Condition not met → required field skipped
+	errs := ValidateFormData(template, map[string]interface{}{"type": "normal"})
+	if len(errs) != 0 {
+		t.Fatalf("expected 0 errors (condition not met), got %+v", errs)
+	}
+
+	// Condition met → required enforced
+	errs = ValidateFormData(template, map[string]interface{}{"type": "other"})
+	if len(errs) != 1 || errs[0].Key != "details" {
+		t.Fatalf("expected 1 error for conditional required field, got %+v", errs)
+	}
+
+	// Condition met + value provided
+	errs = ValidateFormData(template, map[string]interface{}{"type": "other", "details": "More info"})
+	if len(errs) != 0 {
+		t.Fatalf("expected 0 errors, got %+v", errs)
+	}
+}
+
+func TestEvaluateFieldCondition_Operators(t *testing.T) {
+	data := map[string]interface{}{"status": "active", "role": "admin"}
+
+	tests := []struct {
+		name   string
+		cond   FieldCondition
+		expect bool
+	}{
+		{"eq match", FieldCondition{When: "status", Op: "eq", Value: "active"}, true},
+		{"eq mismatch", FieldCondition{When: "status", Op: "eq", Value: "inactive"}, false},
+		{"neq match", FieldCondition{When: "status", Op: "neq", Value: "inactive"}, true},
+		{"neq mismatch", FieldCondition{When: "status", Op: "neq", Value: "active"}, false},
+		{"exists present", FieldCondition{When: "status", Op: "exists"}, true},
+		{"exists absent", FieldCondition{When: "missing", Op: "exists"}, false},
+		{"in match", FieldCondition{When: "role", Op: "in", Value: []interface{}{"admin", "mod"}}, true},
+		{"in mismatch", FieldCondition{When: "role", Op: "in", Value: []interface{}{"user", "guest"}}, false},
+		{"default op is eq", FieldCondition{When: "status", Value: "active"}, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := EvaluateFieldCondition(&tt.cond, data)
+			if got != tt.expect {
+				t.Errorf("expected %v, got %v", tt.expect, got)
+			}
+		})
+	}
+}
+
+func TestAllFields(t *testing.T) {
+	raw := json.RawMessage(`{
+		"fieldsets": [
+			{"label": "A", "fields": [{"key": "x", "type": "text", "label": "X"}]},
+			{"label": "B", "fields": [{"key": "y", "type": "text", "label": "Y"}, {"key": "z", "type": "text", "label": "Z"}]}
+		]
+	}`)
+	tpl := ParseTypedFormTemplate(raw)
+	if tpl == nil {
+		t.Fatal("expected non-nil template")
+	}
+	all := tpl.AllFields()
+	if len(all) != 3 {
+		t.Fatalf("expected 3 fields, got %d", len(all))
+	}
+}
+
+func TestValidateFormData_OptionalSkipped(t *testing.T) {
+	template := tpl(FormField{
+		Key: "note", Type: "text", Label: "Note",
+		Validation: &FormValidation{MinLength: intPtr(5)},
+	})
+
+	// Not present and not required → no error
+	errs := ValidateFormData(template, map[string]interface{}{})
+	if len(errs) != 0 {
+		t.Fatalf("expected 0 errors for absent optional field, got %+v", errs)
+	}
+}

server/handlers/admin_slots.go

@@ -0,0 +1,96 @@
+package handlers
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+// slotInfo describes a declared slot and its contributors.
+type slotInfo struct {
+	Host         string           `json:"host"`
+	Description  string           `json:"description"`
+	Context      map[string]any   `json:"context,omitempty"`
+	Contributors []slotContributor `json:"contributors"`
+}
+
+// slotContributor describes one package's contribution to a slot.
+type slotContributor struct {
+	Package     string `json:"package"`
+	Label       string `json:"label,omitempty"`
+	Icon        string `json:"icon,omitempty"`
+	Description string `json:"description,omitempty"`
+}
+
+// ListSlots returns an aggregated map of all declared slots across installed
+// packages together with their contributors. Built on-the-fly from manifests.
+// GET /api/v1/admin/slots
+func (h *PackageHandler) ListSlots(c *gin.Context) {
+	pkgs, err := h.stores.Packages.List(c.Request.Context())
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list packages"})
+		return
+	}
+
+	slots := map[string]*slotInfo{}
+
+	// Pass 1: collect declared slots from host surfaces
+	for _, pkg := range pkgs {
+		slotsRaw, ok := pkg.Manifest["slots"].(map[string]any)
+		if !ok {
+			continue
+		}
+		for name, v := range slotsRaw {
+			fullName := pkg.ID + ":" + name
+			entry, ok := v.(map[string]any)
+			if !ok {
+				continue
+			}
+			desc, _ := entry["description"].(string)
+			var ctx map[string]any
+			if c, ok := entry["context"].(map[string]any); ok {
+				ctx = c
+			}
+			slots[fullName] = &slotInfo{
+				Host:         pkg.ID,
+				Description:  desc,
+				Context:      ctx,
+				Contributors: []slotContributor{},
+			}
+		}
+	}
+
+	// Pass 2: collect contributions
+	for _, pkg := range pkgs {
+		if !pkg.Enabled {
+			continue
+		}
+		contribs, ok := pkg.Manifest["contributes"].(map[string]any)
+		if !ok {
+			continue
+		}
+		for slotKey, v := range contribs {
+			// Ensure the slot entry exists (contributor can arrive before host)
+			if _, exists := slots[slotKey]; !exists {
+				host := slotKey
+				if idx := strings.Index(slotKey, ":"); idx >= 0 {
+					host = slotKey[:idx]
+				}
+				slots[slotKey] = &slotInfo{
+					Host:         host,
+					Contributors: []slotContributor{},
+				}
+			}
+			contrib := slotContributor{Package: pkg.ID}
+			if m, ok := v.(map[string]any); ok {
+				contrib.Label, _ = m["label"].(string)
+				contrib.Icon, _ = m["icon"].(string)
+				contrib.Description, _ = m["description"].(string)
+			}
+			slots[slotKey].Contributors = append(slots[slotKey].Contributors, contrib)
+		}
+	}
+
+	c.JSON(http.StatusOK, gin.H{"data": slots})
+}

server/handlers/capabilities.go

@@ -0,0 +1,146 @@
+package handlers
+
+import (
+	"context"
+	"database/sql"
+	"log"
+
+	"github.com/gin-gonic/gin"
+
+	"armature/storage"
+)
+
+// ── Capability detection ────────────────────────────────────────────
+
+// DetectCapabilities probes the runtime environment and returns a map
+// of capability name → available.  Called once at startup and again on
+// each admin GET /capabilities request.
+func DetectCapabilities(db *sql.DB, isPostgres bool, objStore storage.ObjectStore, workspaceRoot string) map[string]bool {
+	caps := map[string]bool{
+		"postgres":       false,
+		"pgvector":       false,
+		"object_storage": false,
+		"s3":             false,
+		"workspace":      false,
+	}
+
+	// postgres: dialect check
+	if isPostgres {
+		caps["postgres"] = true
+	}
+
+	// pgvector: query pg_extension (PG only)
+	if isPostgres && db != nil {
+		var one int
+		err := db.QueryRow("SELECT 1 FROM pg_extension WHERE extname = 'vector'").Scan(&one)
+		caps["pgvector"] = err == nil
+	}
+
+	// object_storage: configured and healthy
+	if objStore != nil {
+		if err := objStore.Healthy(context.Background()); err == nil {
+			caps["object_storage"] = true
+		}
+	}
+
+	// s3: specific backend check
+	if objStore != nil && objStore.Backend() == "s3" {
+		caps["s3"] = true
+	}
+
+	// workspace: root exists and is writable
+	if workspaceRoot != "" && storage.IsPathWritable(workspaceRoot) {
+		caps["workspace"] = true
+	}
+
+	return caps
+}
+
+// ── Manifest parsing ────────────────────────────────────────────────
+
+// Capabilities holds the parsed capabilities block from a package manifest.
+type Capabilities struct {
+	Required []string
+	Optional []string
+}
+
+// ParseCapabilities extracts capabilities.required and capabilities.optional
+// from a manifest map.  Returns zero value + false if no capabilities block.
+func ParseCapabilities(manifest map[string]any) (Capabilities, bool) {
+	capsRaw, ok := manifest["capabilities"].(map[string]any)
+	if !ok {
+		return Capabilities{}, false
+	}
+
+	var caps Capabilities
+	if req, ok := capsRaw["required"].([]any); ok {
+		for _, v := range req {
+			if s, ok := v.(string); ok && s != "" {
+				caps.Required = append(caps.Required, s)
+			}
+		}
+	}
+	if opt, ok := capsRaw["optional"].([]any); ok {
+		for _, v := range opt {
+			if s, ok := v.(string); ok && s != "" {
+				caps.Optional = append(caps.Optional, s)
+			}
+		}
+	}
+
+	return caps, true
+}
+
+// CheckRequiredCapabilities returns the subset of required capabilities
+// that are not present in the detected set.
+func CheckRequiredCapabilities(required []string, detected map[string]bool) []string {
+	var missing []string
+	for _, r := range required {
+		if !detected[r] {
+			missing = append(missing, r)
+		}
+	}
+	return missing
+}
+
+// capabilityHelpText returns operator-facing remediation hints keyed by
+// capability name.
+func capabilityHelpText(missing []string) map[string]string {
+	hints := map[string]string{
+		"postgres":       "Switch DB_DRIVER to postgres and configure DATABASE_URL.",
+		"pgvector":       "Run `CREATE EXTENSION vector;` in your PostgreSQL database.",
+		"object_storage": "Configure STORAGE_BACKEND (pvc or s3) and ensure the backend is healthy.",
+		"s3":             "Set STORAGE_BACKEND=s3 and configure S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY.",
+		"workspace":      "Set WORKSPACE_ROOT to a writable directory path.",
+	}
+	result := make(map[string]string, len(missing))
+	for _, m := range missing {
+		if h, ok := hints[m]; ok {
+			result[m] = h
+		} else {
+			result[m] = "Unknown capability — check package documentation."
+		}
+	}
+	return result
+}
+
+// ── Admin endpoint ──────────────────────────────────────────────────
+
+// CapabilitiesHandler serves the admin capabilities endpoint.
+type CapabilitiesHandler struct {
+	detect func() map[string]bool
+}
+
+// NewCapabilitiesHandler creates a handler that re-probes capabilities on
+// each request so the response reflects current state.
+func NewCapabilitiesHandler(detect func() map[string]bool) *CapabilitiesHandler {
+	return &CapabilitiesHandler{detect: detect}
+}
+
+// GetCapabilities returns detected environment capabilities.
+// GET /api/v1/admin/capabilities
+func (h *CapabilitiesHandler) GetCapabilities(c *gin.Context) {
+	caps := h.detect()
+	log.Printf("[capabilities] probed: %v", caps)
+	c.JSON(200, caps)
+}

server/handlers/capabilities_test.go

@@ -0,0 +1,205 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+// ── ParseCapabilities ───────────────────────────────────────────────
+
+func TestParseCapabilities_Full(t *testing.T) {
+	manifest := map[string]any{
+		"id": "test-pkg",
+		"capabilities": map[string]any{
+			"required": []any{"postgres", "pgvector"},
+			"optional": []any{"s3"},
+		},
+	}
+	caps, ok := ParseCapabilities(manifest)
+	if !ok {
+		t.Fatal("expected ok=true")
+	}
+	if len(caps.Required) != 2 || caps.Required[0] != "postgres" || caps.Required[1] != "pgvector" {
+		t.Errorf("required = %v, want [postgres pgvector]", caps.Required)
+	}
+	if len(caps.Optional) != 1 || caps.Optional[0] != "s3" {
+		t.Errorf("optional = %v, want [s3]", caps.Optional)
+	}
+}
+
+func TestParseCapabilities_Missing(t *testing.T) {
+	manifest := map[string]any{"id": "test-pkg"}
+	_, ok := ParseCapabilities(manifest)
+	if ok {
+		t.Error("expected ok=false when no capabilities block")
+	}
+}
+
+func TestParseCapabilities_EmptyArrays(t *testing.T) {
+	manifest := map[string]any{
+		"capabilities": map[string]any{
+			"required": []any{},
+			"optional": []any{},
+		},
+	}
+	caps, ok := ParseCapabilities(manifest)
+	if !ok {
+		t.Fatal("expected ok=true")
+	}
+	if len(caps.Required) != 0 {
+		t.Errorf("required should be empty, got %v", caps.Required)
+	}
+	if len(caps.Optional) != 0 {
+		t.Errorf("optional should be empty, got %v", caps.Optional)
+	}
+}
+
+func TestParseCapabilities_IgnoresEmpty(t *testing.T) {
+	manifest := map[string]any{
+		"capabilities": map[string]any{
+			"required": []any{"pgvector", "", "postgres"},
+		},
+	}
+	caps, _ := ParseCapabilities(manifest)
+	if len(caps.Required) != 2 {
+		t.Errorf("expected 2 entries (empty filtered), got %v", caps.Required)
+	}
+}
+
+// ── CheckRequiredCapabilities ───────────────────────────────────────
+
+func TestCheckRequired_AllMet(t *testing.T) {
+	detected := map[string]bool{"postgres": true, "pgvector": true, "s3": true}
+	missing := CheckRequiredCapabilities([]string{"postgres", "pgvector"}, detected)
+	if len(missing) != 0 {
+		t.Errorf("expected no missing, got %v", missing)
+	}
+}
+
+func TestCheckRequired_SomeUnmet(t *testing.T) {
+	detected := map[string]bool{"postgres": true, "pgvector": false, "s3": false}
+	missing := CheckRequiredCapabilities([]string{"postgres", "pgvector", "s3"}, detected)
+	if len(missing) != 2 {
+		t.Errorf("expected 2 missing, got %v", missing)
+	}
+}
+
+func TestCheckRequired_EmptyRequired(t *testing.T) {
+	detected := map[string]bool{"postgres": true}
+	missing := CheckRequiredCapabilities(nil, detected)
+	if len(missing) != 0 {
+		t.Errorf("expected no missing for nil required, got %v", missing)
+	}
+}
+
+func TestCheckRequired_UnknownCap(t *testing.T) {
+	detected := map[string]bool{"postgres": true}
+	missing := CheckRequiredCapabilities([]string{"gpu"}, detected)
+	if len(missing) != 1 || missing[0] != "gpu" {
+		t.Errorf("expected [gpu], got %v", missing)
+	}
+}
+
+// ── capabilityHelpText ──────────────────────────────────────────────
+
+func TestCapabilityHelpText_KnownCaps(t *testing.T) {
+	hints := capabilityHelpText([]string{"pgvector", "s3"})
+	if len(hints) != 2 {
+		t.Fatalf("expected 2 hints, got %d", len(hints))
+	}
+	if hints["pgvector"] == "" {
+		t.Error("pgvector hint is empty")
+	}
+	if hints["s3"] == "" {
+		t.Error("s3 hint is empty")
+	}
+}
+
+func TestCapabilityHelpText_UnknownCap(t *testing.T) {
+	hints := capabilityHelpText([]string{"gpu"})
+	if hints["gpu"] == "" {
+		t.Error("expected fallback hint for unknown cap")
+	}
+}
+
+// ── DetectCapabilities (SQLite path — no real DB) ───────────────────
+
+func TestDetectCapabilities_SQLite_NilStore(t *testing.T) {
+	caps := DetectCapabilities(nil, false, nil, "")
+	if caps["postgres"] {
+		t.Error("postgres should be false on SQLite")
+	}
+	if caps["pgvector"] {
+		t.Error("pgvector should be false on SQLite")
+	}
+	if caps["object_storage"] {
+		t.Error("object_storage should be false with nil store")
+	}
+	if caps["s3"] {
+		t.Error("s3 should be false with nil store")
+	}
+	if caps["workspace"] {
+		t.Error("workspace should be false with empty root")
+	}
+}
+
+func TestDetectCapabilities_WorkspaceWritable(t *testing.T) {
+	tmpDir := t.TempDir()
+	caps := DetectCapabilities(nil, false, nil, tmpDir)
+	if !caps["workspace"] {
+		t.Error("workspace should be true for writable temp dir")
+	}
+}
+
+func TestDetectCapabilities_WorkspaceUnwritable(t *testing.T) {
+	caps := DetectCapabilities(nil, false, nil, "/nonexistent/path/xyz")
+	if caps["workspace"] {
+		t.Error("workspace should be false for nonexistent path")
+	}
+}
+
+// ── Admin endpoint ──────────────────────────────────────────────────
+
+func TestGetCapabilities_HTTP(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	h := NewCapabilitiesHandler(func() map[string]bool {
+		return map[string]bool{
+			"postgres":       false,
+			"pgvector":       false,
+			"object_storage": true,
+			"s3":             false,
+			"workspace":      true,
+		}
+	})
+
+	r := gin.New()
+	r.GET("/api/v1/admin/capabilities", h.GetCapabilities)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/capabilities", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != 200 {
+		t.Fatalf("status = %d, want 200", w.Code)
+	}
+
+	var result map[string]bool
+	if err := json.Unmarshal(w.Body.Bytes(), &result); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+
+	if result["postgres"] {
+		t.Error("postgres should be false")
+	}
+	if !result["object_storage"] {
+		t.Error("object_storage should be true")
+	}
+	if !result["workspace"] {
+		t.Error("workspace should be true")
+	}
+}

server/handlers/composability_test.go

@@ -0,0 +1,97 @@
+package handlers
+
+import (
+	"testing"
+)
+
+func TestValidateComposabilityFields_ValidSlots(t *testing.T) {
+	m := map[string]any{
+		"slots": map[string]any{
+			"toolbar-actions": map[string]any{
+				"description": "Toolbar action buttons",
+				"context": map[string]any{
+					"noteId": "string",
+				},
+			},
+		},
+	}
+	if err := ValidateComposabilityFields(m); err != "" {
+		t.Errorf("expected valid, got: %s", err)
+	}
+}
+
+func TestValidateComposabilityFields_SlotMissingDescription(t *testing.T) {
+	m := map[string]any{
+		"slots": map[string]any{
+			"toolbar": map[string]any{
+				"context": map[string]any{},
+			},
+		},
+	}
+	if err := ValidateComposabilityFields(m); err == "" {
+		t.Error("expected error for slot missing description")
+	}
+}
+
+func TestValidateComposabilityFields_SlotsNotObject(t *testing.T) {
+	m := map[string]any{
+		"slots": "bad",
+	}
+	if err := ValidateComposabilityFields(m); err == "" {
+		t.Error("expected error for non-object slots")
+	}
+}
+
+func TestValidateComposabilityFields_ValidContributes(t *testing.T) {
+	m := map[string]any{
+		"contributes": map[string]any{
+			"notes:toolbar-actions": map[string]any{
+				"label": "Dictate",
+				"icon":  "🎤",
+			},
+		},
+	}
+	if err := ValidateComposabilityFields(m); err != "" {
+		t.Errorf("expected valid, got: %s", err)
+	}
+}
+
+func TestValidateComposabilityFields_ContributesMissingColon(t *testing.T) {
+	m := map[string]any{
+		"contributes": map[string]any{
+			"toolbar-actions": map[string]any{
+				"label": "Bad",
+			},
+		},
+	}
+	if err := ValidateComposabilityFields(m); err == "" {
+		t.Error("expected error for contributes key without colon")
+	}
+}
+
+func TestValidateComposabilityFields_Empty(t *testing.T) {
+	m := map[string]any{
+		"id": "test",
+	}
+	if err := ValidateComposabilityFields(m); err != "" {
+		t.Errorf("expected valid for manifest without slots/contributes, got: %s", err)
+	}
+}
+
+func TestValidateComposabilityFields_BothValid(t *testing.T) {
+	m := map[string]any{
+		"slots": map[string]any{
+			"my-slot": map[string]any{
+				"description": "A slot",
+			},
+		},
+		"contributes": map[string]any{
+			"other:their-slot": map[string]any{
+				"label": "Hello",
+			},
+		},
+	}
+	if err := ValidateComposabilityFields(m); err != "" {
+		t.Errorf("expected valid, got: %s", err)
+	}
+}

server/handlers/ext_db_schema.go

@@ -13,20 +13,38 @@ import (
 	"fmt"
 	"log"
 	"regexp"
+	"strconv"
 	"strings"
 
 	"armature/store"
 )
 
+// vectorDimRegex matches manifest type strings like "vector(384)".
+var vectorDimRegex = regexp.MustCompile(`^vector\((\d+)\)$`)
+
 // validSchemaIdentifier matches safe SQL identifiers for table and column names.
 var validSchemaIdentifier = regexp.MustCompile(`^[a-z][a-z0-9_]{0,62}$`)
 
 // TableDef describes a single extension-owned table as declared in a manifest.
 type TableDef struct {
-	Columns map[string]string // colName → manifest type ("text","int","real","bool","timestamp")
+	Columns map[string]string // colName → manifest type ("text","int","real","bool","timestamp","vector(N)")
 	Indexes [][]string        // each inner slice is an ordered list of column names for one index
 }
 
+// parseVectorDim extracts the dimension N from a "vector(N)" type string.
+// Returns (N, true) for valid dimensions 1..4096, or (0, false) otherwise.
+func parseVectorDim(typStr string) (int, bool) {
+	m := vectorDimRegex.FindStringSubmatch(strings.ToLower(typStr))
+	if m == nil {
+		return 0, false
+	}
+	n, err := strconv.Atoi(m[1])
+	if err != nil || n < 1 || n > 4096 {
+		return 0, false
+	}
+	return n, true
+}
+
 // ParseDBTables extracts the "db_tables" key from a package manifest map.
 // Returns the map of logicalName→TableDef and ok=true when the key is present
 // and produces at least one valid table definition.
@@ -93,8 +111,22 @@ func ParseDBTables(manifest map[string]any) (map[string]TableDef, bool) {
 }
 
 // mapColType maps a manifest type string to a SQL column type for the given dialect.
-func mapColType(typStr string, isPostgres bool) string {
+// hasPgvector indicates whether the pgvector extension is available on Postgres.
-	switch strings.ToLower(typStr) {
+func mapColType(typStr string, isPostgres bool, hasPgvector bool) string {
+	lower := strings.ToLower(typStr)
+
+	// Check for vector type first.
+	if _, ok := parseVectorDim(lower); ok {
+		if isPostgres && hasPgvector {
+			return lower // native pgvector type, e.g. "vector(384)"
+		}
+		if isPostgres {
+			return "JSONB" // structured fallback without pgvector
+		}
+		return "TEXT" // SQLite fallback — JSON string
+	}
+
+	switch lower {
 	case "int", "integer":
 		return "INTEGER"
 	case "real", "float":
@@ -133,6 +165,8 @@ func createdAtColDef(isPostgres bool) string {
 // in the provided map.  Each successfully created table is registered in the
 // ext_data_tables catalog via stores.ExtData.
 //
+// hasPgvector enables native pgvector column types and HNSW indexes when true.
+//
 // Errors from individual table creation are returned immediately (fail-fast).
 // Index creation failures are logged but non-fatal.
 // Catalog registration failures are logged but non-fatal.
@@ -143,6 +177,7 @@ func CreateExtTables(
 	stores store.Stores,
 	packageID string,
 	tables map[string]TableDef,
+	hasPgvector bool,
 ) error {
 	if db == nil {
 		return nil
@@ -153,7 +188,7 @@ func CreateExtTables(
 		// Build column list: id first, user columns, created_at last.
 		cols := []string{"id TEXT PRIMARY KEY"}
 		for col, typ := range td.Columns {
-			cols = append(cols, col+" "+mapColType(typ, isPostgres))
+			cols = append(cols, col+" "+mapColType(typ, isPostgres, hasPgvector))
 		}
 		cols = append(cols, createdAtColDef(isPostgres))
 
@@ -174,6 +209,21 @@ func CreateExtTables(
 			}
 		}
 
+		// Create HNSW indexes for vector columns when pgvector is available.
+		if isPostgres && hasPgvector {
+			for col, typ := range td.Columns {
+				if _, ok := parseVectorDim(strings.ToLower(typ)); ok {
+					hnswName := fmt.Sprintf("idx_%s_%s_hnsw", physical, col)
+					hnswDDL := fmt.Sprintf(
+						"CREATE INDEX IF NOT EXISTS %s ON %s USING hnsw (%s vector_cosine_ops)",
+						hnswName, physical, col)
+					if _, err := db.ExecContext(ctx, hnswDDL); err != nil {
+						log.Printf("[ext-db] hnsw index create failed (%s): %v", hnswName, err)
+					}
+				}
+			}
+		}
+
 		// Record logical name in catalog.
 		if stores.ExtData != nil {
 			if err := stores.ExtData.RegisterTable(ctx, packageID, logicalName); err != nil {
@@ -245,6 +295,7 @@ func MigrateExtTables(
 	stores store.Stores,
 	packageID string,
 	newTables map[string]TableDef,
+	hasPgvector bool,
 ) ([]string, error) {
 	if db == nil {
 		return nil, nil
@@ -270,7 +321,7 @@ func MigrateExtTables(
 		if !existingTableNames[logicalName] {
 			// New table — full creation
 			if err := CreateExtTables(ctx, db, isPostgres, stores, packageID,
-				map[string]TableDef{logicalName: td}); err != nil {
+				map[string]TableDef{logicalName: td}, hasPgvector); err != nil {
 				return changes, fmt.Errorf("create new table %s: %w", physical, err)
 			}
 			changes = append(changes, fmt.Sprintf("created table %s", physical))
@@ -287,7 +338,7 @@ func MigrateExtTables(
 			if existingCols[col] {
 				continue
 			}
-			sqlType := mapColType(typ, isPostgres)
+			sqlType := mapColType(typ, isPostgres, hasPgvector)
 			alterDDL := fmt.Sprintf("ALTER TABLE %s ADD COLUMN %s %s", physical, col, sqlType)
 			if _, err := db.ExecContext(ctx, alterDDL); err != nil {
 				return changes, fmt.Errorf("add column %s.%s: %w", physical, col, err)

server/handlers/ext_db_schema_test.go

@@ -145,7 +145,7 @@ func TestMapColType_SQLite(t *testing.T) {
 		{"unknown", "TEXT"},
 	}
 	for _, c := range cases {
-		got := mapColType(c.in, false)
+		got := mapColType(c.in, false, false)
 		if got != c.want {
 			t.Errorf("mapColType(%q, sqlite) = %q, want %q", c.in, got, c.want)
 		}
@@ -153,13 +153,13 @@ func TestMapColType_SQLite(t *testing.T) {
 }
 
 func TestMapColType_Postgres(t *testing.T) {
-	if mapColType("bool", true) != "BOOLEAN" {
+	if mapColType("bool", true, false) != "BOOLEAN" {
 		t.Error("expected BOOLEAN for bool in postgres")
 	}
-	if mapColType("timestamp", true) != "TIMESTAMPTZ" {
+	if mapColType("timestamp", true, false) != "TIMESTAMPTZ" {
 		t.Error("expected TIMESTAMPTZ for timestamp in postgres")
 	}
-	if mapColType("int", true) != "INTEGER" {
+	if mapColType("int", true, false) != "INTEGER" {
 		t.Error("expected INTEGER for int in postgres")
 	}
 }
@@ -189,7 +189,7 @@ func TestCreateExtTables_CreatesTable(t *testing.T) {
 			Columns: map[string]string{"message": "text", "count": "int"},
 		},
 	}
-	if err := CreateExtTables(ctx, db, false, storesWithExtData(m), "test-pkg", tables); err != nil {
+	if err := CreateExtTables(ctx, db, false, storesWithExtData(m), "test-pkg", tables, false); err != nil {
 		t.Fatalf("CreateExtTables: %v", err)
 	}
 
@@ -212,7 +212,7 @@ func TestCreateExtTables_WithIndexes(t *testing.T) {
 			Indexes: [][]string{{"user_id"}, {"user_id", "kind"}},
 		},
 	}
-	if err := CreateExtTables(ctx, db, false, storesWithExtData(m), "idx-pkg", tables); err != nil {
+	if err := CreateExtTables(ctx, db, false, storesWithExtData(m), "idx-pkg", tables, false); err != nil {
 		t.Fatalf("CreateExtTables: %v", err)
 	}
 
@@ -243,7 +243,7 @@ func TestCreateExtTables_CatalogRegistration(t *testing.T) {
 		"logs":   {Columns: map[string]string{"msg": "text"}},
 		"errors": {Columns: map[string]string{"detail": "text"}},
 	}
-	if err := CreateExtTables(ctx, db, false, storesWithExtData(m), "cat-pkg", tables); err != nil {
+	if err := CreateExtTables(ctx, db, false, storesWithExtData(m), "cat-pkg", tables, false); err != nil {
 		t.Fatalf("CreateExtTables: %v", err)
 	}
 
@@ -259,7 +259,7 @@ func TestCreateExtTables_NilDBIsNoop(t *testing.T) {
 	// Should not panic or error.
 	err := CreateExtTables(ctx, nil, false, storesWithExtData(m), "pkg", map[string]TableDef{
 		"t": {Columns: map[string]string{"x": "text"}},
-	})
+	}, false)
 	if err != nil {
 		t.Errorf("expected nil error for nil db, got: %v", err)
 	}
@@ -276,7 +276,7 @@ func TestDropExtTables_DropsAndClearsCatalog(t *testing.T) {
 	tables := map[string]TableDef{
 		"items": {Columns: map[string]string{"name": "text"}},
 	}
-	if err := CreateExtTables(ctx, db, false, storesWithExtData(m), "drop-pkg", tables); err != nil {
+	if err := CreateExtTables(ctx, db, false, storesWithExtData(m), "drop-pkg", tables, false); err != nil {
 		t.Fatalf("CreateExtTables: %v", err)
 	}
 
@@ -309,7 +309,7 @@ func TestDropExtTables_MultipleTables(t *testing.T) {
 		"alpha": {Columns: map[string]string{"v": "text"}},
 		"beta":  {Columns: map[string]string{"v": "text"}},
 	}
-	CreateExtTables(ctx, db, false, storesWithExtData(m), "multi-pkg", tables)
+	CreateExtTables(ctx, db, false, storesWithExtData(m), "multi-pkg", tables, false)
 	DropExtTables(ctx, db, storesWithExtData(m), "multi-pkg")
 
 	for _, name := range []string{"ext_multi_pkg_alpha", "ext_multi_pkg_beta"} {
@@ -331,7 +331,7 @@ func TestCreateExtTables_DDLContainsAutoColumns(t *testing.T) {
 	ctx := context.Background()
 
 	tables := map[string]TableDef{"empty": {Columns: map[string]string{}}}
-	if err := CreateExtTables(ctx, db, false, storesWithExtData(m), "auto-pkg", tables); err != nil {
+	if err := CreateExtTables(ctx, db, false, storesWithExtData(m), "auto-pkg", tables, false); err != nil {
 		t.Fatalf("CreateExtTables: %v", err)
 	}
 
@@ -348,3 +348,77 @@ func TestCreateExtTables_DDLContainsAutoColumns(t *testing.T) {
 		t.Error("expected created_at to be populated by default")
 	}
 }
+
+// ── parseVectorDim ──────────────────────────────────────────────────────────
+
+func TestParseVectorDim(t *testing.T) {
+	cases := []struct {
+		input string
+		dim   int
+		ok    bool
+	}{
+		{"vector(384)", 384, true},
+		{"vector(1)", 1, true},
+		{"vector(4096)", 4096, true},
+		{"Vector(128)", 128, true}, // case insensitive
+		{"vector(0)", 0, false},
+		{"vector(5000)", 0, false},   // exceeds 4096
+		{"vector()", 0, false},
+		{"vector(abc)", 0, false},
+		{"text", 0, false},
+		{"vector", 0, false},
+	}
+	for _, c := range cases {
+		dim, ok := parseVectorDim(c.input)
+		if ok != c.ok || dim != c.dim {
+			t.Errorf("parseVectorDim(%q) = (%d, %v), want (%d, %v)", c.input, dim, ok, c.dim, c.ok)
+		}
+	}
+}
+
+// ── mapColType vector ───────────────────────────────────────────────────────
+
+func TestMapColType_VectorSQLite(t *testing.T) {
+	got := mapColType("vector(384)", false, false)
+	if got != "TEXT" {
+		t.Errorf("vector on SQLite: got %q, want TEXT", got)
+	}
+}
+
+func TestMapColType_VectorPgNoPgvector(t *testing.T) {
+	got := mapColType("vector(384)", true, false)
+	if got != "JSONB" {
+		t.Errorf("vector on PG without pgvector: got %q, want JSONB", got)
+	}
+}
+
+func TestMapColType_VectorPgvector(t *testing.T) {
+	got := mapColType("vector(384)", true, true)
+	if got != "vector(384)" {
+		t.Errorf("vector on PG with pgvector: got %q, want vector(384)", got)
+	}
+}
+
+// ── CreateExtTables with vector column ──────────────────────────────────────
+
+func TestCreateExtTables_VectorColumn(t *testing.T) {
+	db := newSchemaTestDB(t)
+	m := newMemExtDataStore()
+	ctx := context.Background()
+
+	tables := map[string]TableDef{
+		"docs": {
+			Columns: map[string]string{"title": "text", "embedding": "vector(384)"},
+		},
+	}
+	if err := CreateExtTables(ctx, db, false, storesWithExtData(m), "vec-pkg", tables, false); err != nil {
+		t.Fatalf("CreateExtTables: %v", err)
+	}
+
+	// Verify table exists and embedding is TEXT (SQLite fallback).
+	_, err := db.ExecContext(ctx,
+		`INSERT INTO ext_vec_pkg_docs (id, title, embedding) VALUES ('1', 'test', '[0.1,0.2]')`)
+	if err != nil {
+		t.Errorf("table not created or wrong schema: %v", err)
+	}
+}

server/handlers/extensions.go

@@ -17,13 +17,19 @@ import (
 
 // ExtensionHandler serves extension management endpoints.
 type ExtensionHandler struct {
-	stores store.Stores
+	stores       store.Stores
+	capabilities map[string]bool
 }
 
 func NewExtensionHandler(stores store.Stores) *ExtensionHandler {
 	return &ExtensionHandler{stores: stores}
 }
 
+// SetCapabilities stores the detected environment capabilities map.
+func (h *ExtensionHandler) SetCapabilities(caps map[string]bool) {
+	h.capabilities = caps
+}
+
 // validTiers is the set of accepted extension tier values.
 var validTiers = map[string]bool{
 	models.ExtTierBrowser:  true,
@@ -31,6 +37,44 @@ var validTiers = map[string]bool{
 	models.ExtTierSidecar:  true,
 }
 
+// ValidateComposabilityFields checks that manifest slots and contributes
+// fields follow the expected conventions. Slots values must have a
+// "description" string. Contributes keys must follow "pkg:slot" naming.
+// Returns nil if valid or missing; returns an error string otherwise.
+func ValidateComposabilityFields(manifest map[string]any) string {
+	// Validate slots: map of name → {description, ...}
+	if slotsRaw, ok := manifest["slots"]; ok {
+		slots, ok := slotsRaw.(map[string]any)
+		if !ok {
+			return "slots must be an object"
+		}
+		for name, v := range slots {
+			entry, ok := v.(map[string]any)
+			if !ok {
+				return "slots." + name + " must be an object"
+			}
+			if _, ok := entry["description"]; !ok {
+				return "slots." + name + " must have a description"
+			}
+		}
+	}
+
+	// Validate contributes: map of "pkg:slot" → {label, ...}
+	if contribRaw, ok := manifest["contributes"]; ok {
+		contribs, ok := contribRaw.(map[string]any)
+		if !ok {
+			return "contributes must be an object"
+		}
+		for key := range contribs {
+			if !strings.Contains(key, ":") {
+				return "contributes key " + key + " must follow pkg:slot convention"
+			}
+		}
+	}
+
+	return ""
+}
+
 // ── User endpoints ──────────────────────────────
 
 // ListUserExtensions returns all enabled extensions for the current user,
@@ -202,6 +246,12 @@ func (h *ExtensionHandler) AdminInstallExtension(c *gin.Context) {
 		manifestMap = map[string]any{}
 	}
 
+	// Validate composability fields (slots / contributes)
+	if errMsg := ValidateComposabilityFields(manifestMap); errMsg != "" {
+		c.JSON(400, gin.H{"error": "manifest: " + errMsg})
+		return
+	}
+
 	pkg := &store.PackageRegistration{
 		ID:          body.ExtID,
 		Title:       body.Name,
@@ -231,7 +281,7 @@ func (h *ExtensionHandler) AdminInstallExtension(c *gin.Context) {
 	SyncManifestPermissions(c, h.stores, pkg.ID, manifestMap)
 
 	if tables, ok := ParseDBTables(manifestMap); ok {
-		if err := CreateExtTables(c.Request.Context(), database.DB, database.IsPostgres(), h.stores, pkg.ID, tables); err != nil {
+		if err := CreateExtTables(c.Request.Context(), database.DB, database.IsPostgres(), h.stores, pkg.ID, tables, h.capabilities["pgvector"]); err != nil {
 			log.Printf("[ext-db] schema create failed for %s: %v", pkg.ID, err)
 		}
 	}

server/handlers/forms.go

@@ -0,0 +1,63 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"armature/forms"
+)
+
+// FormsHandler provides REST endpoints for the standalone forms system.
+type FormsHandler struct{}
+
+// formsValidateRequest is the request body for POST /api/v1/forms/validate.
+type formsValidateRequest struct {
+	Template json.RawMessage        `json:"template"`
+	Data     map[string]interface{} `json:"data"`
+}
+
+// formsValidateResponse is the response body for POST /api/v1/forms/validate.
+type formsValidateResponse struct {
+	Valid  bool              `json:"valid"`
+	Errors []forms.FieldError `json:"errors"`
+}
+
+// Validate validates form data against a typed form template.
+//
+//	POST /api/v1/forms/validate
+//	Body: { "template": {...}, "data": {...} }
+//	Response: { "valid": true/false, "errors": [...] }
+func (h *FormsHandler) Validate(c *gin.Context) {
+	var req formsValidateRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"})
+		return
+	}
+
+	if len(req.Template) == 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "template is required"})
+		return
+	}
+
+	tpl := forms.ParseTypedFormTemplate(req.Template)
+	if tpl == nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "template is invalid or empty"})
+		return
+	}
+
+	if req.Data == nil {
+		req.Data = make(map[string]interface{})
+	}
+
+	errs := forms.ValidateFormData(tpl, req.Data)
+	if errs == nil {
+		errs = []forms.FieldError{}
+	}
+
+	c.JSON(http.StatusOK, formsValidateResponse{
+		Valid:  len(errs) == 0,
+		Errors: errs,
+	})
+}

server/handlers/package_adopt.go

@@ -0,0 +1,284 @@
+package handlers
+
+import (
+	"log"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"armature/store"
+)
+
+// PackageAdoptHandler manages team package adoption endpoints.
+type PackageAdoptHandler struct {
+	stores store.Stores
+}
+
+func NewPackageAdoptHandler(s store.Stores) *PackageAdoptHandler {
+	return &PackageAdoptHandler{stores: s}
+}
+
+// AdoptPackage clones a global adoptable package into the team.
+// POST /api/v1/teams/:teamId/packages/:id/adopt
+func (h *PackageAdoptHandler) AdoptPackage(c *gin.Context) {
+	ctx := c.Request.Context()
+	teamID := c.Param("teamId")
+	sourceID := c.Param("id")
+	userID := c.GetString("user_id")
+
+	// Load source package
+	src, err := h.stores.Packages.Get(ctx, sourceID)
+	if err != nil || src == nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "package not found"})
+		return
+	}
+
+	// Verify adoptable + global
+	if !src.Adoptable {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "package is not adoptable"})
+		return
+	}
+	if src.Scope != "global" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "only global packages can be adopted"})
+		return
+	}
+
+	// Idempotency: check if already adopted
+	existing, err := h.stores.Packages.GetByAdoptedFrom(ctx, sourceID, teamID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to check adoption"})
+		return
+	}
+	if existing != nil {
+		// Already adopted — return the existing record
+		roles, _ := h.stores.Teams.ListRoleCatalog(ctx, teamID)
+		c.JSON(http.StatusOK, gin.H{
+			"package":      existing,
+			"roles_added":  filterRolesBySource(roles, existing.ID),
+			"already_adopted": true,
+		})
+		return
+	}
+
+	// Generate adopted package ID: {sourceID}--{teamID[:8]}
+	shortTeam := teamID
+	if len(shortTeam) > 8 {
+		shortTeam = shortTeam[:8]
+	}
+	adoptedID := sourceID + "--" + shortTeam
+
+	// Create team-scoped package row referencing the original
+	adoptedPkg := &store.PackageRegistration{
+		ID:          adoptedID,
+		Title:       src.Title,
+		Type:        src.Type,
+		Version:     src.Version,
+		Description: src.Description,
+		Author:      src.Author,
+		Tier:        src.Tier,
+		IsSystem:    false,
+		Scope:       "team",
+		TeamID:      &teamID,
+		InstalledBy: &userID,
+		Manifest:    src.Manifest,
+		Enabled:     true,
+		Status:      "active",
+		SchemaVersion:   src.SchemaVersion,
+		PackageSettings: src.PackageSettings,
+		Source:          "extension",
+		Adoptable:       false,
+		AdoptedFrom:     &sourceID,
+	}
+
+	if err := h.stores.Packages.Create(ctx, adoptedPkg); err != nil {
+		log.Printf("[packages] adopt: failed to create adopted package %s: %v", adoptedID, err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to adopt package"})
+		return
+	}
+
+	// Auto-populate role catalog from requires_roles
+	var rolesAdded []string
+	if rr, ok := src.Manifest["requires_roles"].([]any); ok {
+		for _, v := range rr {
+			if role, ok := v.(string); ok && role != "" {
+				if err := h.stores.Teams.AddRoleToCatalog(ctx, teamID, role, adoptedID); err != nil {
+					log.Printf("[packages] adopt: failed to add role %q to catalog: %v", role, err)
+					continue
+				}
+				rolesAdded = append(rolesAdded, role)
+			}
+		}
+	}
+
+	// If source is a workflow package, clone the workflow + stages
+	if src.Type == "workflow" {
+		h.cloneWorkflowForAdoption(c, src, adoptedPkg)
+	}
+
+	log.Printf("[packages] adopted %s → %s for team %s (roles: %v)", sourceID, adoptedID, teamID, rolesAdded)
+	c.JSON(http.StatusCreated, gin.H{
+		"package":     adoptedPkg,
+		"roles_added": rolesAdded,
+	})
+}
+
+// cloneWorkflowForAdoption copies the workflow definition from the source
+// package into a team-scoped workflow. Best-effort — logs errors but does
+// not abort the adoption.
+func (h *PackageAdoptHandler) cloneWorkflowForAdoption(c *gin.Context, src, adopted *store.PackageRegistration) {
+	ctx := c.Request.Context()
+	teamID := *adopted.TeamID
+
+	// Extract workflow_definition from manifest
+	wfDef, ok := src.Manifest["workflow_definition"].(map[string]any)
+	if !ok {
+		log.Printf("[packages] adopt: no workflow_definition in manifest for %s", src.ID)
+		return
+	}
+
+	// Use the InstallWorkflowFromManifest path if available, or
+	// fall back to looking up the workflow by package ID
+	wfSlug, _ := wfDef["slug"].(string)
+	if wfSlug == "" {
+		wfSlug = src.ID
+	}
+
+	// Find the global workflow installed from this package
+	wf, err := h.stores.Workflows.GetBySlug(ctx, nil, wfSlug)
+	if err != nil || wf == nil {
+		log.Printf("[packages] adopt: source workflow %q not found, skipping clone", wfSlug)
+		return
+	}
+
+	stages, err := h.stores.Workflows.ListStages(ctx, wf.ID)
+	if err != nil {
+		log.Printf("[packages] adopt: failed to load stages for %s: %v", wf.ID, err)
+		return
+	}
+
+	// Clone workflow into team scope
+	clone := *wf
+	clone.ID = ""
+	clone.TeamID = &teamID
+	clone.IsActive = false
+	clone.Version = 0
+	clone.CreatedBy = c.GetString("user_id")
+
+	if err := h.stores.Workflows.Create(ctx, &clone); err != nil {
+		// Slug conflict — append short ID
+		clone.Slug = wfSlug + "-" + store.NewID()[:6]
+		if err2 := h.stores.Workflows.Create(ctx, &clone); err2 != nil {
+			log.Printf("[packages] adopt: failed to clone workflow: %v", err2)
+			return
+		}
+	}
+
+	// Clone stages
+	for _, st := range stages {
+		cloneSt := st
+		cloneSt.ID = ""
+		cloneSt.WorkflowID = clone.ID
+		if err := h.stores.Workflows.CreateStage(ctx, &cloneSt); err != nil {
+			log.Printf("[packages] adopt: failed to clone stage %s: %v", st.Name, err)
+		}
+	}
+	log.Printf("[packages] adopt: cloned workflow %s → %s for team %s", wf.ID, clone.ID, teamID)
+}
+
+// ListAdoptablePackages returns global adoptable packages, annotating which
+// ones have already been adopted by this team.
+// GET /api/v1/teams/:teamId/packages/adoptable
+func (h *PackageAdoptHandler) ListAdoptablePackages(c *gin.Context) {
+	ctx := c.Request.Context()
+	teamID := c.Param("teamId")
+
+	pkgs, err := h.stores.Packages.ListAdoptable(ctx)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list packages"})
+		return
+	}
+
+	type adoptableItem struct {
+		store.PackageRegistration
+		Adopted bool `json:"adopted"`
+	}
+
+	var result []adoptableItem
+	for _, pkg := range pkgs {
+		item := adoptableItem{PackageRegistration: pkg}
+		existing, _ := h.stores.Packages.GetByAdoptedFrom(ctx, pkg.ID, teamID)
+		item.Adopted = existing != nil
+		result = append(result, item)
+	}
+	if result == nil {
+		result = []adoptableItem{}
+	}
+	c.JSON(http.StatusOK, gin.H{"data": result})
+}
+
+// UnadoptPackage removes a team's adopted package and cleans up role catalog.
+// DELETE /api/v1/teams/:teamId/packages/:id/unadopt
+func (h *PackageAdoptHandler) UnadoptPackage(c *gin.Context) {
+	ctx := c.Request.Context()
+	teamID := c.Param("teamId")
+	pkgID := c.Param("id")
+
+	pkg, err := h.stores.Packages.Get(ctx, pkgID)
+	if err != nil || pkg == nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "package not found"})
+		return
+	}
+
+	// Verify it's an adopted package belonging to this team
+	if pkg.AdoptedFrom == nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "package was not adopted"})
+		return
+	}
+	if pkg.TeamID == nil || *pkg.TeamID != teamID {
+		c.JSON(http.StatusForbidden, gin.H{"error": "package does not belong to this team"})
+		return
+	}
+
+	// Clean up role catalog entries sourced from this package
+	if err := h.stores.Teams.RemoveRoleCatalogBySource(ctx, teamID, pkgID); err != nil {
+		log.Printf("[packages] unadopt: failed to clean role catalog: %v", err)
+	}
+
+	// Delete the adopted package row
+	if err := h.stores.Packages.Delete(ctx, pkgID); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to remove package"})
+		return
+	}
+
+	log.Printf("[packages] unadopted %s from team %s", pkgID, teamID)
+	c.JSON(http.StatusOK, gin.H{"message": "package unadopted"})
+}
+
+// ListRoleCatalog returns all known roles for a team.
+// GET /api/v1/teams/:teamId/roles/catalog
+func (h *PackageAdoptHandler) ListRoleCatalog(c *gin.Context) {
+	ctx := c.Request.Context()
+	teamID := c.Param("teamId")
+
+	roles, err := h.stores.Teams.ListRoleCatalog(ctx, teamID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to list role catalog"})
+		return
+	}
+	if roles == nil {
+		roles = []store.TeamRoleCatalogEntry{}
+	}
+	c.JSON(http.StatusOK, gin.H{"data": roles})
+}
+
+// filterRolesBySource returns only roles from a specific package.
+func filterRolesBySource(roles []store.TeamRoleCatalogEntry, pkgID string) []string {
+	var result []string
+	for _, r := range roles {
+		if r.SourcePackageID == pkgID {
+			result = append(result, r.Role)
+		}
+	}
+	return result
+}
+

server/handlers/package_adopt_test.go

@@ -0,0 +1,353 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+
+	"armature/database"
+	"armature/store"
+)
+
+// ── Manifest: adoptable parsing ──────────────
+
+func TestValidateManifest_Adoptable(t *testing.T) {
+	m := map[string]any{
+		"id":        "adopt-wf",
+		"title":     "Adoptable Workflow",
+		"type":      "workflow",
+		"adoptable": true,
+		"workflow_definition": map[string]any{
+			"slug": "adopt-wf",
+		},
+	}
+	info, err := ValidateManifest(m)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !info.Adoptable {
+		t.Error("expected Adoptable to be true")
+	}
+}
+
+func TestValidateManifest_Adoptable_Default(t *testing.T) {
+	m := map[string]any{
+		"id":    "plain-surface",
+		"title": "Plain Surface",
+		"type":  "surface",
+	}
+	info, err := ValidateManifest(m)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if info.Adoptable {
+		t.Error("expected Adoptable to be false by default")
+	}
+}
+
+func TestValidateManifest_Adoptable_LibraryRejected(t *testing.T) {
+	m := map[string]any{
+		"id":        "adopt-lib",
+		"title":     "Adoptable Library",
+		"type":      "library",
+		"adoptable": true,
+		"exports":   []any{"module_a"},
+	}
+	_, err := ValidateManifest(m)
+	if err == nil {
+		t.Fatal("expected error for adoptable library")
+	}
+}
+
+func TestValidateManifest_Adoptable_TestRunnerRejected(t *testing.T) {
+	m := map[string]any{
+		"id":        "adopt-runner",
+		"title":     "Adoptable Runner",
+		"type":      "test-runner",
+		"adoptable": true,
+	}
+	_, err := ValidateManifest(m)
+	if err == nil {
+		t.Fatal("expected error for adoptable test-runner")
+	}
+}
+
+func TestValidateManifest_Adoptable_SurfaceAllowed(t *testing.T) {
+	m := map[string]any{
+		"id":        "adopt-surface",
+		"title":     "Adoptable Surface",
+		"type":      "surface",
+		"adoptable": true,
+	}
+	info, err := ValidateManifest(m)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !info.Adoptable {
+		t.Error("expected Adoptable to be true for surface")
+	}
+}
+
+// ── Store: role catalog CRUD ──────────────
+
+// seedMinimalPackage creates a minimal package for FK references in tests.
+func seedMinimalPackage(t *testing.T, stores store.Stores, id string) {
+	t.Helper()
+	pkg := &store.PackageRegistration{
+		ID: id, Title: id, Type: "surface", Version: "1.0.0",
+		Scope: "global", Tier: "browser", Manifest: map[string]any{"id": id, "title": id},
+		Enabled: true, Status: "active", Source: "extension",
+	}
+	if err := stores.Packages.Create(context.Background(), pkg); err != nil {
+		t.Fatalf("seed minimal package %s: %v", id, err)
+	}
+}
+
+func TestRoleCatalog_AddAndList(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+	ctx := context.Background()
+
+	teamID, _, _ := seedTeamAndMember(t, stores)
+	pkgID := "rc-pkg-" + store.NewID()[:6]
+	seedMinimalPackage(t, stores, pkgID)
+
+	// Add two roles
+	if err := stores.Teams.AddRoleToCatalog(ctx, teamID, "approver", pkgID); err != nil {
+		t.Fatalf("AddRoleToCatalog: %v", err)
+	}
+	if err := stores.Teams.AddRoleToCatalog(ctx, teamID, "reviewer", pkgID); err != nil {
+		t.Fatalf("AddRoleToCatalog: %v", err)
+	}
+
+	roles, err := stores.Teams.ListRoleCatalog(ctx, teamID)
+	if err != nil {
+		t.Fatalf("ListRoleCatalog: %v", err)
+	}
+	if len(roles) != 2 {
+		t.Fatalf("expected 2 roles, got %d: %v", len(roles), roles)
+	}
+}
+
+func TestRoleCatalog_AddIdempotent(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+	ctx := context.Background()
+
+	teamID, _, _ := seedTeamAndMember(t, stores)
+	pkgA := "rc-idem-a-" + store.NewID()[:6]
+	pkgB := "rc-idem-b-" + store.NewID()[:6]
+	seedMinimalPackage(t, stores, pkgA)
+	seedMinimalPackage(t, stores, pkgB)
+
+	if err := stores.Teams.AddRoleToCatalog(ctx, teamID, "approver", pkgA); err != nil {
+		t.Fatalf("first add: %v", err)
+	}
+	// Same role from different source — should be idempotent (unique on team_id, role)
+	if err := stores.Teams.AddRoleToCatalog(ctx, teamID, "approver", pkgB); err != nil {
+		t.Fatalf("idempotent add should not error: %v", err)
+	}
+
+	roles, _ := stores.Teams.ListRoleCatalog(ctx, teamID)
+	if len(roles) != 1 {
+		t.Errorf("expected 1 role after idempotent add, got %d", len(roles))
+	}
+}
+
+func TestRoleCatalog_RemoveBySource(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+	ctx := context.Background()
+
+	teamID, _, _ := seedTeamAndMember(t, stores)
+	pkgRm := "rc-rm-" + store.NewID()[:6]
+	pkgKeep := "rc-keep-" + store.NewID()[:6]
+	seedMinimalPackage(t, stores, pkgRm)
+	seedMinimalPackage(t, stores, pkgKeep)
+
+	stores.Teams.AddRoleToCatalog(ctx, teamID, "approver", pkgRm)
+	stores.Teams.AddRoleToCatalog(ctx, teamID, "reviewer", pkgRm)
+	stores.Teams.AddRoleToCatalog(ctx, teamID, "admin-role", pkgKeep)
+
+	if err := stores.Teams.RemoveRoleCatalogBySource(ctx, teamID, pkgRm); err != nil {
+		t.Fatalf("RemoveRoleCatalogBySource: %v", err)
+	}
+
+	roles, _ := stores.Teams.ListRoleCatalog(ctx, teamID)
+	if len(roles) != 1 {
+		t.Fatalf("expected 1 role remaining, got %d: %v", len(roles), roles)
+	}
+	if roles[0].Role != "admin-role" {
+		t.Errorf("expected 'admin-role' remaining, got %q", roles[0].Role)
+	}
+}
+
+// ── Store: package adoption ──────────────
+
+func seedAdoptablePackage(t *testing.T, stores store.Stores, id string, roles []string) {
+	t.Helper()
+	manifest := map[string]any{
+		"id":    id,
+		"title": "Adoptable " + id,
+		"type":  "surface",
+	}
+	if len(roles) > 0 {
+		rr := make([]any, len(roles))
+		for i, r := range roles {
+			rr[i] = r
+		}
+		manifest["requires_roles"] = rr
+	}
+	pkg := &store.PackageRegistration{
+		ID:       id,
+		Title:    "Adoptable " + id,
+		Type:     "surface",
+		Version:  "1.0.0",
+		Tier:     "browser",
+		Scope:    "global",
+		Manifest: manifest,
+		Enabled:  true,
+		Status:   "active",
+		Source:   "extension",
+		Adoptable: true,
+	}
+	if err := stores.Packages.Create(context.Background(), pkg); err != nil {
+		t.Fatalf("seed adoptable package: %v", err)
+	}
+}
+
+func TestAdoptPackage_Success(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+	ctx := context.Background()
+
+	teamID, userID, _ := seedTeamAndMember(t, stores)
+	pkgID := "adopt-test-" + store.NewID()[:6]
+	seedAdoptablePackage(t, stores, pkgID, []string{"approver", "reviewer"})
+
+	// Set up handler
+	h := NewPackageAdoptHandler(stores)
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, r := gin.CreateTestContext(w)
+	r.POST("/teams/:teamId/packages/:id/adopt", func(c *gin.Context) {
+		c.Set("user_id", userID)
+		h.AdoptPackage(c)
+	})
+
+	req := httptest.NewRequest("POST", "/teams/"+teamID+"/packages/"+pkgID+"/adopt", nil)
+	c.Request = req
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusCreated {
+		t.Fatalf("expected 201, got %d: %s", w.Code, w.Body.String())
+	}
+
+	var resp map[string]any
+	json.NewDecoder(w.Body).Decode(&resp)
+
+	// Verify roles_added
+	rolesAdded, ok := resp["roles_added"].([]any)
+	if !ok || len(rolesAdded) != 2 {
+		t.Errorf("expected 2 roles_added, got %v", resp["roles_added"])
+	}
+
+	// Verify team package was created
+	shortTeam := teamID
+	if len(shortTeam) > 8 {
+		shortTeam = shortTeam[:8]
+	}
+	adopted, _ := stores.Packages.Get(ctx, pkgID+"--"+shortTeam)
+	if adopted == nil {
+		t.Fatal("adopted package not found in DB")
+	}
+	if adopted.Scope != "team" {
+		t.Errorf("expected scope 'team', got %q", adopted.Scope)
+	}
+	if adopted.AdoptedFrom == nil || *adopted.AdoptedFrom != pkgID {
+		t.Errorf("expected adopted_from=%q, got %v", pkgID, adopted.AdoptedFrom)
+	}
+
+	// Verify role catalog populated
+	roles, _ := stores.Teams.ListRoleCatalog(ctx, teamID)
+	found := 0
+	for _, r := range roles {
+		if r.SourcePackageID == pkgID+"--"+shortTeam {
+			found++
+		}
+	}
+	if found != 2 {
+		t.Errorf("expected 2 catalog roles from adoption, got %d", found)
+	}
+}
+
+func TestAdoptPackage_Idempotent(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+
+	teamID, userID, _ := seedTeamAndMember(t, stores)
+	pkgID := "adopt-idem-" + store.NewID()[:6]
+	seedAdoptablePackage(t, stores, pkgID, nil)
+
+	h := NewPackageAdoptHandler(stores)
+	gin.SetMode(gin.TestMode)
+
+	doAdopt := func() int {
+		w := httptest.NewRecorder()
+		_, r := gin.CreateTestContext(w)
+		r.POST("/teams/:teamId/packages/:id/adopt", func(c *gin.Context) {
+			c.Set("user_id", userID)
+			h.AdoptPackage(c)
+		})
+		req := httptest.NewRequest("POST", "/teams/"+teamID+"/packages/"+pkgID+"/adopt", nil)
+		r.ServeHTTP(w, req)
+		return w.Code
+	}
+
+	code1 := doAdopt()
+	if code1 != http.StatusCreated {
+		t.Fatalf("first adopt: expected 201, got %d", code1)
+	}
+	code2 := doAdopt()
+	if code2 != http.StatusOK {
+		t.Fatalf("second adopt: expected 200, got %d", code2)
+	}
+}
+
+func TestAdoptPackage_NotAdoptable(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+
+	teamID, userID, _ := seedTeamAndMember(t, stores)
+
+	// Seed a non-adoptable package
+	pkg := &store.PackageRegistration{
+		ID: "no-adopt-" + store.NewID()[:6], Title: "Not Adoptable",
+		Type: "surface", Version: "1.0.0", Tier: "browser", Scope: "global",
+		Manifest: map[string]any{"id": "no-adopt", "title": "Not Adoptable"},
+		Enabled: true, Status: "active", Source: "extension",
+		Adoptable: false,
+	}
+	if err := stores.Packages.Create(context.Background(), pkg); err != nil {
+		t.Fatalf("seed non-adoptable: %v", err)
+	}
+
+	h := NewPackageAdoptHandler(stores)
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	_, r := gin.CreateTestContext(w)
+	r.POST("/teams/:teamId/packages/:id/adopt", func(c *gin.Context) {
+		c.Set("user_id", userID)
+		h.AdoptPackage(c)
+	})
+	req := httptest.NewRequest("POST", "/teams/"+teamID+"/packages/"+pkg.ID+"/adopt", nil)
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400 for non-adoptable, got %d", w.Code)
+	}
+}

server/handlers/package_validate.go

@@ -4,6 +4,9 @@ import (
 	"encoding/json"
 	"fmt"
 	"regexp"
+	"strings"
+
+	"armature/forms"
 )
 
 // validManifestID matches lowercase alphanumeric slugs with optional hyphens.
@@ -21,6 +24,7 @@ type ManifestInfo struct {
 	Tier          string
 	SchemaVersion int
 	HasRoute      bool
+	HasSurfaces   bool
 	HasTools      bool
 	HasPipes      bool
 	HasHooks      bool
@@ -31,6 +35,9 @@ type ManifestInfo struct {
 	Signature       string // reserved for future package signing
 	UserPermissions []string // user-facing permissions declared by the extension
 	GatePermission  string   // if set, checks this user permission before calling on_request
+	RequiresRoles   []string // team roles needed to access this package (advisory, OR semantics)
+	Adoptable       bool     // if true, teams can adopt this package to get a team-scoped copy
+	HasFormTemplate bool     // if true, package declares a form_template at the top level
 }
 
 // ValidateManifest parses a manifest map and validates all required fields,
@@ -81,7 +88,64 @@ func ValidateManifest(manifest map[string]any) (*ManifestInfo, error) {
 	}
 	info.Signature, _ = manifest["signature"].(string)
 
-	info.HasRoute = manifest["route"] != nil || manifest["routes"] != nil
+	// ── Surfaces validation ─────────────────────────────────────
+	if rawSurfaces, ok := manifest["surfaces"].([]any); ok {
+		if len(rawSurfaces) == 0 {
+			return nil, fmt.Errorf("surfaces array cannot be empty")
+		}
+		seen := map[string]bool{}
+		for i, raw := range rawSurfaces {
+			s, ok := raw.(map[string]any)
+			if !ok {
+				return nil, fmt.Errorf("surfaces[%d] must be an object", i)
+			}
+			path, _ := s["path"].(string)
+			if path == "" {
+				return nil, fmt.Errorf("surfaces[%d] requires a path", i)
+			}
+			if !strings.HasPrefix(path, "/") {
+				return nil, fmt.Errorf("surfaces[%d] path must start with /", i)
+			}
+			if seen[path] {
+				return nil, fmt.Errorf("duplicate surface path: %s", path)
+			}
+			seen[path] = true
+			if access, ok := s["access"].(string); ok {
+				if !validAccessLevels(access) {
+					return nil, fmt.Errorf("surfaces[%d] invalid access: %s", i, access)
+				}
+			}
+		}
+		info.HasSurfaces = true
+		info.HasRoute = true
+	} else if manifest["surfaces"] != nil {
+		// surfaces key present but not an array
+		return nil, fmt.Errorf("surfaces must be an array")
+	} else {
+		// No surfaces declared — synthesize from legacy fields.
+		// This ensures every routable package always has a surfaces array.
+		if info.Type == "surface" || info.Type == "full" {
+			auth, _ := manifest["auth"].(string)
+			if auth == "" {
+				auth = "authenticated"
+			}
+			layout, _ := manifest["layout"].(string)
+			if layout == "" {
+				layout = "single"
+			}
+			manifest["surfaces"] = []any{
+				map[string]any{
+					"path":   "/",
+					"access": auth,
+					"layout": layout,
+					"title":  info.Title,
+				},
+			}
+			info.HasSurfaces = true
+		}
+		info.HasRoute = manifest["route"] != nil || manifest["routes"] != nil || info.HasSurfaces
+	}
+
 	info.HasTools = manifest["tools"] != nil
 	info.HasPipes = manifest["pipes"] != nil
 	info.HasHooks = manifest["hooks"] != nil
@@ -109,6 +173,32 @@ func ValidateManifest(manifest map[string]any) (*ManifestInfo, error) {
 	}
 	info.GatePermission, _ = manifest["gate_permission"].(string)
 
+	// v0.9.3: requires_roles — team roles needed to access this package (advisory)
+	if rr, ok := manifest["requires_roles"].([]any); ok {
+		for _, v := range rr {
+			if s, ok := v.(string); ok && s != "" && len(s) <= 50 {
+				info.RequiresRoles = append(info.RequiresRoles, s)
+			}
+		}
+	}
+
+	// v0.9.4: adoptable — teams can adopt this package to get a team-scoped copy
+	if v, ok := manifest["adoptable"].(bool); ok {
+		info.Adoptable = v
+	}
+
+	// v0.9.5: form_template — any package can declare a typed form template
+	if manifest["form_template"] != nil {
+		raw, err := json.Marshal(manifest["form_template"])
+		if err != nil {
+			return nil, fmt.Errorf("form_template is invalid JSON")
+		}
+		if tpl := forms.ParseTypedFormTemplate(raw); tpl == nil {
+			return nil, fmt.Errorf("form_template is invalid or empty")
+		}
+		info.HasFormTemplate = true
+	}
+
 	info.SchemaVersion = ParseSchemaVersion(manifest)
 
 	// ── Type-specific constraints ────────────────────────────────
@@ -147,15 +237,33 @@ func ValidateManifest(manifest map[string]any) (*ManifestInfo, error) {
 		if info.HasRoute {
 			return nil, fmt.Errorf("library packages cannot have a route")
 		}
+		if info.Adoptable {
+			return nil, fmt.Errorf("library packages cannot be adoptable")
+		}
 	case "test-runner":
 		// Test runners are surface-like packages discovered by type.
 		// They are not shown in navigation (extensionNavItems filters for surface/full).
 		// They may have a route but it's optional — the registry surface provides access.
+		if info.Adoptable {
+			return nil, fmt.Errorf("test-runner packages cannot be adoptable")
+		}
 	}
 
 	return info, nil
 }
 
+// validAccessLevels checks whether an access string is a recognized value.
+func validAccessLevels(access string) bool {
+	switch {
+	case access == "public", access == "authenticated", access == "admin":
+		return true
+	case strings.HasPrefix(access, "group:"):
+		return strings.TrimPrefix(access, "group:") != ""
+	default:
+		return false
+	}
+}
+
 // ValidateManifestJSON parses raw JSON bytes into a manifest map and validates.
 func ValidateManifestJSON(data []byte) (map[string]any, *ManifestInfo, error) {
 	var manifest map[string]any

server/handlers/package_validate_test.go

@@ -198,3 +198,154 @@ func TestValidateManifest_WorkflowNoDef(t *testing.T) {
 		t.Fatal("expected error for workflow without workflow_definition")
 	}
 }
+
+// ── Surfaces validation ─────────────────────────────────────
+
+func TestValidateManifest_ValidSurfaces(t *testing.T) {
+	m := map[string]any{
+		"id":    "bug-tracker",
+		"title": "Bug Tracker",
+		"type":  "full",
+		"hooks": []any{"surface"},
+		"surfaces": []any{
+			map[string]any{"path": "/", "title": "Dashboard"},
+			map[string]any{"path": "/submit", "access": "public", "title": "Report a Bug"},
+			map[string]any{"path": "/:id", "title": "Bug Detail", "nav": false},
+			map[string]any{"path": "/admin", "access": "admin", "title": "Settings"},
+		},
+	}
+	info, err := ValidateManifest(m)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !info.HasSurfaces {
+		t.Error("expected HasSurfaces to be true")
+	}
+	if !info.HasRoute {
+		t.Error("expected HasRoute to be true")
+	}
+}
+
+func TestValidateManifest_EmptySurfaces(t *testing.T) {
+	m := map[string]any{
+		"id":       "my-pkg",
+		"title":    "My Package",
+		"type":     "surface",
+		"surfaces": []any{},
+	}
+	_, err := ValidateManifest(m)
+	if err == nil {
+		t.Fatal("expected error for empty surfaces array")
+	}
+}
+
+func TestValidateManifest_SurfaceMissingPath(t *testing.T) {
+	m := map[string]any{
+		"id":    "my-pkg",
+		"title": "My Package",
+		"type":  "surface",
+		"surfaces": []any{
+			map[string]any{"title": "No Path"},
+		},
+	}
+	_, err := ValidateManifest(m)
+	if err == nil {
+		t.Fatal("expected error for surface without path")
+	}
+}
+
+func TestValidateManifest_SurfacePathNoSlash(t *testing.T) {
+	m := map[string]any{
+		"id":    "my-pkg",
+		"title": "My Package",
+		"type":  "surface",
+		"surfaces": []any{
+			map[string]any{"path": "submit"},
+		},
+	}
+	_, err := ValidateManifest(m)
+	if err == nil {
+		t.Fatal("expected error for path not starting with /")
+	}
+}
+
+func TestValidateManifest_SurfaceDuplicatePath(t *testing.T) {
+	m := map[string]any{
+		"id":    "my-pkg",
+		"title": "My Package",
+		"type":  "surface",
+		"surfaces": []any{
+			map[string]any{"path": "/"},
+			map[string]any{"path": "/"},
+		},
+	}
+	_, err := ValidateManifest(m)
+	if err == nil {
+		t.Fatal("expected error for duplicate surface path")
+	}
+}
+
+func TestValidateManifest_SurfaceInvalidAccess(t *testing.T) {
+	m := map[string]any{
+		"id":    "my-pkg",
+		"title": "My Package",
+		"type":  "surface",
+		"surfaces": []any{
+			map[string]any{"path": "/", "access": "superuser"},
+		},
+	}
+	_, err := ValidateManifest(m)
+	if err == nil {
+		t.Fatal("expected error for invalid access level")
+	}
+}
+
+func TestValidateManifest_SurfaceGroupAccess(t *testing.T) {
+	m := map[string]any{
+		"id":    "my-pkg",
+		"title": "My Package",
+		"type":  "surface",
+		"surfaces": []any{
+			map[string]any{"path": "/", "access": "group:engineering"},
+		},
+	}
+	info, err := ValidateManifest(m)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !info.HasSurfaces {
+		t.Error("expected HasSurfaces to be true")
+	}
+}
+
+func TestValidateManifest_AutoSynthesizeSurfaces(t *testing.T) {
+	m := map[string]any{
+		"id":     "legacy-pkg",
+		"title":  "Legacy Package",
+		"type":   "surface",
+		"auth":   "public",
+		"layout": "editor",
+	}
+	info, err := ValidateManifest(m)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !info.HasSurfaces {
+		t.Error("expected HasSurfaces after auto-synthesis")
+	}
+	// Verify the synthesized surfaces array was injected into the manifest
+	surfaces, ok := m["surfaces"].([]any)
+	if !ok || len(surfaces) != 1 {
+		t.Fatalf("expected 1 synthesized surface, got %v", m["surfaces"])
+	}
+	s := surfaces[0].(map[string]any)
+	if s["path"] != "/" {
+		t.Errorf("expected path '/', got %q", s["path"])
+	}
+	if s["access"] != "public" {
+		t.Errorf("expected access 'public', got %q", s["access"])
+	}
+	if s["layout"] != "editor" {
+		t.Errorf("expected layout 'editor', got %q", s["layout"])
+	}
+}

server/handlers/packages.go

@@ -38,6 +38,7 @@ type PackageHandler struct {
 	sandbox        *sandbox.Sandbox
 	runner         *sandbox.Runner
 	hub            *events.Hub
+	capabilities   map[string]bool  // detected environment capabilities
 }
 
 func NewPackageHandler(s store.Stores, packagesDir ...string) *PackageHandler {
@@ -69,6 +70,12 @@ func (h *PackageHandler) SetHub(hub *events.Hub) {
 	h.hub = hub
 }
 
+// SetCapabilities stores the detected environment capabilities map.
+// Used at install time to validate manifest capabilities.required.
+func (h *PackageHandler) SetCapabilities(caps map[string]bool) {
+	h.capabilities = caps
+}
+
 // broadcastPackageChanged emits a package.changed event to all clients.
 func (h *PackageHandler) broadcastPackageChanged(action, id string) {
 	if h.hub == nil {
@@ -205,10 +212,48 @@ func (h *PackageHandler) DeletePackage(c *gin.Context) {
 		}
 	}
 
-	c.JSON(http.StatusOK, gin.H{"id": id, "deleted": true})
+	resp := gin.H{"id": id, "deleted": true}
+
+	// Warn about orphaned slot contributions
+	if orphaned := findOrphanedContributors(c, h.stores, id); len(orphaned) > 0 {
+		resp["warning"] = "slot contributions orphaned in: " + strings.Join(orphaned, ", ")
+	}
+
+	c.JSON(http.StatusOK, resp)
 	h.broadcastPackageChanged("deleted", id)
 }
 
+// findOrphanedContributors returns package IDs that declare contributes
+// targeting slots owned by the given package (e.g. "notes:toolbar-actions"
+// targets the "notes" package). This is a warning, not a blocker.
+func findOrphanedContributors(c *gin.Context, stores store.Stores, deletedPkgID string) []string {
+	allPkgs, err := stores.Packages.List(c.Request.Context())
+	if err != nil {
+		return nil
+	}
+	prefix := deletedPkgID + ":"
+	seen := map[string]bool{}
+	for _, p := range allPkgs {
+		if p.ID == deletedPkgID || !p.Enabled {
+			continue
+		}
+		contribs, ok := p.Manifest["contributes"].(map[string]any)
+		if !ok {
+			continue
+		}
+		for key := range contribs {
+			if strings.HasPrefix(key, prefix) {
+				seen[p.ID] = true
+			}
+		}
+	}
+	result := make([]string, 0, len(seen))
+	for id := range seen {
+		result = append(result, id)
+	}
+	return result
+}
+
 // InstallPackage uploads and installs a .pkg/.surface archive.
 // POST /api/v1/admin/packages/install
 //
@@ -286,8 +331,23 @@ func (h *PackageHandler) InstallPackage(c *gin.Context) {
 		}
 	}
 
-	// Phase 10: Check capabilities → mark dormant if unmet
+	// Phase 10: Validate required capabilities
-	isDormant := h.checkCapabilities(c, pkgID, manifest, &preservedEnabled)
+	if caps, ok := ParseCapabilities(manifest); ok {
+		missing := CheckRequiredCapabilities(caps.Required, h.capabilities)
+		if len(missing) > 0 {
+			h.stores.Packages.Delete(c.Request.Context(), pkgID)
+			c.JSON(http.StatusUnprocessableEntity, gin.H{
+				"error":   "missing required capabilities",
+				"missing": missing,
+				"help":    capabilityHelpText(missing),
+			})
+			return
+		}
+		unmetOpt := CheckRequiredCapabilities(caps.Optional, h.capabilities)
+		if len(unmetOpt) > 0 {
+			log.Printf("[packages] %s: optional capabilities unavailable: %v", pkgID, unmetOpt)
+		}
+	}
 
 	resp := gin.H{
 		"id":      pkgID,
@@ -297,9 +357,6 @@ func (h *PackageHandler) InstallPackage(c *gin.Context) {
 		"source":  pkgSource,
 		"enabled": preservedEnabled,
 	}
-	if isDormant {
-		resp["status"] = "dormant"
-	}
 	c.JSON(http.StatusOK, resp)
 	h.broadcastPackageChanged("installed", pkgID)
 }
@@ -447,6 +504,13 @@ func (h *PackageHandler) parseAndValidateArchive(c *gin.Context, tmpPath string)
 		return nil, nil, nil, err
 	}
 
+	// Validate composability fields (slots / contributes)
+	if errMsg := ValidateComposabilityFields(manifest); errMsg != "" {
+		zr.Close()
+		c.JSON(http.StatusBadRequest, gin.H{"error": "manifest: " + errMsg})
+		return nil, nil, nil, fmt.Errorf("invalid composability fields")
+	}
+
 	// Signing hook (reserved)
 	if os.Getenv("PACKAGE_VERIFY_SIGNATURES") == "true" {
 		if mInfo.Signature != "" {
@@ -527,6 +591,18 @@ func (h *PackageHandler) registerPackage(c *gin.Context, pkgID string, mInfo *Ma
 	if err := h.stores.Packages.Update(c.Request.Context(), pkgID, pkg); err != nil {
 		log.Printf("[packages] Failed to update package metadata for %s: %v", pkgID, err)
 	}
+
+	// v0.9.4: persist adoptable flag (Update doesn't cover it — separate column)
+	if mInfo.Adoptable {
+		q := `UPDATE packages SET adoptable = true WHERE id = $1`
+		if !database.IsPostgres() {
+			q = `UPDATE packages SET adoptable = 1 WHERE id = ?`
+		}
+		if _, err := database.DB.ExecContext(c.Request.Context(), q, pkgID); err != nil {
+			log.Printf("[packages] Failed to set adoptable for %s: %v", pkgID, err)
+		}
+	}
+
 	return preservedEnabled, nil
 }
 
@@ -534,7 +610,7 @@ func (h *PackageHandler) registerPackage(c *gin.Context, pkgID string, mInfo *Ma
 // and runs schema migrations.
 func (h *PackageHandler) applySchemaAndPermissions(c *gin.Context, pkgID string, mInfo *ManifestInfo, manifest map[string]any, existing *store.PackageRegistration) error {
 	if tables, ok := ParseDBTables(manifest); ok {
-		if err := CreateExtTables(c.Request.Context(), database.DB, database.IsPostgres(), h.stores, pkgID, tables); err != nil {
+		if err := CreateExtTables(c.Request.Context(), database.DB, database.IsPostgres(), h.stores, pkgID, tables, h.capabilities["pgvector"]); err != nil {
 			log.Printf("[ext-db] schema create failed for %s: %v", pkgID, err)
 		}
 	}
@@ -591,7 +667,7 @@ func (h *PackageHandler) resolveDependencies(c *gin.Context, pkgID string, manif
 				pkgPath := filepath.Join(h.bundledDir, libID+".pkg")
 				if _, statErr := os.Stat(pkgPath); statErr == nil {
 					log.Printf("[packages] auto-installing bundled dependency %s for %s", libID, pkgID)
-					if _, installErr := installBundledPackage(pkgPath, h.packagesDir, h.stores, h.runner, c.GetString("user_id")); installErr != nil {
+					if _, installErr := installBundledPackage(pkgPath, h.packagesDir, h.stores, h.runner, c.GetString("user_id"), h.capabilities); installErr != nil {
 						c.JSON(http.StatusBadRequest, gin.H{
 							"error": fmt.Sprintf("dependency %s auto-install failed: %v", libID, installErr),
 						})
@@ -634,27 +710,6 @@ func (h *PackageHandler) resolveDependencies(c *gin.Context, pkgID string, manif
 	return nil
 }
 
-// checkCapabilities marks a package dormant if it declares unmet `requires` entries.
-func (h *PackageHandler) checkCapabilities(c *gin.Context, pkgID string, manifest map[string]any, preservedEnabled *bool) bool {
-	knownCaps := map[string]bool{}
-	var unmetReqs []string
-	if reqs, ok := manifest["requires"].([]any); ok && len(reqs) > 0 {
-		for _, r := range reqs {
-			req, _ := r.(string)
-			if req != "" && !knownCaps[req] {
-				unmetReqs = append(unmetReqs, req)
-			}
-		}
-	}
-	if len(unmetReqs) == 0 {
-		return false
-	}
-	h.stores.Packages.SetStatus(c.Request.Context(), pkgID, "dormant")
-	h.stores.Packages.SetEnabled(c.Request.Context(), pkgID, false)
-	*preservedEnabled = false
-	log.Printf("[packages] %s: dormant (unmet requires: %v)", pkgID, unmetReqs)
-	return true
-}
 
 // extractableRelPath returns the relative path for a zip entry if it
 // belongs to an extractable directory (js/, css/, assets/, star/) or
@@ -874,7 +929,7 @@ func (h *PackageHandler) TestTool(c *gin.Context) {
 	}
 
 	// Build a call dict identical to what executeExtensionTool sends.
-	// Build the arguments as an interface{} map for jsonToStarlark.
+	// Build the arguments as an interface{} map for GoToStarlark.
 	var args interface{}
 	if req.Arguments != nil {
 		argsJSON, _ := json.Marshal(req.Arguments)
@@ -884,7 +939,7 @@ func (h *PackageHandler) TestTool(c *gin.Context) {
 	callDict := starlark.NewDict(3)
 	_ = callDict.SetKey(starlark.String("tool_name"), starlark.String(req.ToolName))
 	_ = callDict.SetKey(starlark.String("tool_call_id"), starlark.String("test-"+pkgID))
-	_ = callDict.SetKey(starlark.String("arguments"), jsonToStarlark(args))
+	_ = callDict.SetKey(starlark.String("arguments"), sandbox.GoToStarlark(args))
 
 	userID, _ := c.Get("user_id")
 	rc := &sandbox.RunContext{UserID: fmt.Sprintf("%v", userID)}
@@ -902,7 +957,7 @@ func (h *PackageHandler) TestTool(c *gin.Context) {
 	}
 
 	// Serialize the Starlark return value to Go types.
-	result := starlarkValueToGo(val)
+	result := sandbox.StarlarkToGo(val)
 	c.JSON(http.StatusOK, gin.H{
 		"result": result,
 		"output": output,
@@ -1049,7 +1104,7 @@ func (h *PackageHandler) UpdatePackage(c *gin.Context) {
 	// 6. Additive schema migration
 	var schemaChanges []string
 	if tables, ok := ParseDBTables(manifest); ok {
-		changes, err := MigrateExtTables(ctx, database.DB, database.IsPostgres(), h.stores, pkgID, tables)
+		changes, err := MigrateExtTables(ctx, database.DB, database.IsPostgres(), h.stores, pkgID, tables, h.capabilities["pgvector"])
 		if err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": "schema migration failed: " + err.Error()})
 			return

server/handlers/packages_bundled.go

@@ -40,7 +40,7 @@ var defaultBundledPackages = map[string]bool{}
 //
 // Design: install-once, skip-if-present. If an admin uninstalls a bundled
 // package, it won't be re-installed on the next restart.
-func InstallBundledPackages(bundledDir, packagesDir, allowlist string, stores store.Stores, runner *sandbox.Runner) {
+func InstallBundledPackages(bundledDir, packagesDir, allowlist string, stores store.Stores, runner *sandbox.Runner, detectedCaps map[string]bool) {
 	entries, err := os.ReadDir(bundledDir)
 	if err != nil {
 		if os.IsNotExist(err) {
@@ -82,7 +82,7 @@ func InstallBundledPackages(bundledDir, packagesDir, allowlist string, stores st
 		}
 
 		pkgPath := filepath.Join(bundledDir, entry.Name())
-		result, err := installBundledPackage(pkgPath, packagesDir, stores, runner, adminUserID)
+		result, err := installBundledPackage(pkgPath, packagesDir, stores, runner, adminUserID, detectedCaps)
 		if err != nil {
 			log.Printf("[bundled] ⚠️ Failed to install %s: %v", entry.Name(), err)
 			continue
@@ -129,7 +129,7 @@ func parseBundleAllowlist(s string) map[string]bool {
 
 // installBundledPackage installs a single .pkg archive if its package ID
 // doesn't already exist in the database. Returns "installed" or "skipped".
-func installBundledPackage(pkgPath, packagesDir string, stores store.Stores, runner *sandbox.Runner, adminUserID string) (string, error) {
+func installBundledPackage(pkgPath, packagesDir string, stores store.Stores, runner *sandbox.Runner, adminUserID string, detectedCaps map[string]bool) (string, error) {
 	ctx := context.Background()
 
 	// Open as zip
@@ -196,7 +196,7 @@ func installBundledPackage(pkgPath, packagesDir string, stores store.Stores, run
 
 	// Create namespaced DB tables declared in the manifest
 	if tables, ok := ParseDBTables(manifest); ok {
-		if err := CreateExtTables(ctx, database.DB, database.IsPostgres(), stores, pkgID, tables); err != nil {
+		if err := CreateExtTables(ctx, database.DB, database.IsPostgres(), stores, pkgID, tables, detectedCaps["pgvector"]); err != nil {
 			log.Printf("[bundled] [ext-db] schema create failed for %s: %v", pkgID, err)
 		}
 	}
@@ -237,20 +237,17 @@ func installBundledPackage(pkgPath, packagesDir string, stores store.Stores, run
 		}
 	}
 
-	// Handle dormant status for packages with unmet requires
+	// Validate required capabilities — skip package if unmet
-	knownCaps := map[string]bool{}
+	if caps, ok := ParseCapabilities(manifest); ok {
-	if reqs, ok := manifest["requires"].([]any); ok && len(reqs) > 0 {
+		missing := CheckRequiredCapabilities(caps.Required, detectedCaps)
-		var unmetReqs []string
+		if len(missing) > 0 {
-		for _, r := range reqs {
+			stores.Packages.Delete(ctx, pkgID)
-			req, _ := r.(string)
+			log.Printf("[bundled] %s: skipped (missing required capabilities: %v)", pkgID, missing)
-			if req != "" && !knownCaps[req] {
+			return "skipped", nil
-				unmetReqs = append(unmetReqs, req)
-			}
 		}
-		if len(unmetReqs) > 0 {
+		unmetOpt := CheckRequiredCapabilities(caps.Optional, detectedCaps)
-			stores.Packages.SetStatus(ctx, pkgID, "dormant")
+		if len(unmetOpt) > 0 {
-			stores.Packages.SetEnabled(ctx, pkgID, false)
+			log.Printf("[bundled] %s: optional capabilities unavailable: %v", pkgID, unmetOpt)
-			log.Printf("[bundled] %s: dormant (unmet requires: %v)", pkgID, unmetReqs)
 		}
 	}
 

server/handlers/packages_bundled_test.go

@@ -88,7 +88,7 @@ func TestBundledInstall_FreshDB(t *testing.T) {
 		"route": "/s/test-b",
 	})
 
-	InstallBundledPackages(bundledDir, packagesDir, "*", stores, nil)
+	InstallBundledPackages(bundledDir, packagesDir, "*", stores, nil, nil)
 
 	// Both packages should be installed and enabled
 	for _, id := range []string{"test-surface-a", "test-surface-b"} {
@@ -127,7 +127,7 @@ func TestBundledInstall_SkipsExisting(t *testing.T) {
 		"type":  "surface",
 	})
 
-	InstallBundledPackages(bundledDir, packagesDir, "*", stores, nil)
+	InstallBundledPackages(bundledDir, packagesDir, "*", stores, nil, nil)
 
 	// Package should retain original title (not overwritten)
 	pkg, err := stores.Packages.Get(ctx, "pre-existing")
@@ -145,7 +145,7 @@ func TestBundledInstall_MissingDir(t *testing.T) {
 	stores := newTestStores(t)
 
 	// Should not panic or error — just log and return
-	InstallBundledPackages("/nonexistent/path", "", "", stores, nil)
+	InstallBundledPackages("/nonexistent/path", "", "", stores, nil, nil)
 }
 
 // TestBundledInstall_EmptyDir verifies no-op when directory exists but is empty.
@@ -155,12 +155,12 @@ func TestBundledInstall_EmptyDir(t *testing.T) {
 	bundledDir := t.TempDir()
 
 	// Should not panic or error
-	InstallBundledPackages(bundledDir, "", "", stores, nil)
+	InstallBundledPackages(bundledDir, "", "", stores, nil, nil)
 }
 
-// TestBundledInstall_DormantPackage verifies that bundled packages with
+// TestBundledInstall_SkippedOnUnmetRequiredCaps verifies that bundled
-// unmet requires are marked dormant.
+// packages with unmet capabilities.required are skipped (not registered).
-func TestBundledInstall_DormantPackage(t *testing.T) {
+func TestBundledInstall_SkippedOnUnmetRequiredCaps(t *testing.T) {
 	stores := newTestStores(t)
 	ctx := context.Background()
 
@@ -168,24 +168,21 @@ func TestBundledInstall_DormantPackage(t *testing.T) {
 	packagesDir := t.TempDir()
 
 	buildTestPkg(t, bundledDir, map[string]any{
-		"id":       "dormant-pkg",
+		"id":    "needs-pgvector",
-		"title":    "Dormant Package",
+		"title": "Needs pgvector",
-		"type":     "extension",
+		"type":  "extension",
-		"hooks":    []string{"on_install"},
+		"hooks": []string{"on_install"},
-		"requires": []string{"chat"},
+		"capabilities": map[string]any{
+			"required": []string{"pgvector"},
+		},
 	})
 
-	InstallBundledPackages(bundledDir, packagesDir, "*", stores, nil)
+	// No capabilities detected → pgvector is unavailable
+	InstallBundledPackages(bundledDir, packagesDir, "*", stores, nil, nil)
 
-	pkg, err := stores.Packages.Get(ctx, "dormant-pkg")
+	pkg, _ := stores.Packages.Get(ctx, "needs-pgvector")
-	if err != nil || pkg == nil {
+	if pkg != nil {
-		t.Fatal("dormant package not found after install")
+		t.Error("package with unmet required capabilities should not be registered")
-	}
-	if pkg.Status != "dormant" {
-		t.Errorf("status = %q, want %q", pkg.Status, "dormant")
-	}
-	if pkg.Enabled {
-		t.Error("dormant package should not be enabled")
 	}
 }
 
@@ -209,7 +206,7 @@ func TestBundledInstall_Allowlist(t *testing.T) {
 	})
 
 	// Only allow alpha and gamma
-	InstallBundledPackages(bundledDir, packagesDir, "pkg-alpha,pkg-gamma", stores, nil)
+	InstallBundledPackages(bundledDir, packagesDir, "pkg-alpha,pkg-gamma", stores, nil, nil)
 
 	// Alpha and gamma should be installed
 	for _, id := range []string{"pkg-alpha", "pkg-gamma"} {

server/handlers/packages_update_test.go

@@ -267,7 +267,7 @@ func TestUpdatePackage_SchemaAddColumn(t *testing.T) {
 			},
 		},
 	})
-	CreateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "schema-pkg", tables)
+	CreateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "schema-pkg", tables, false)
 
 	// Insert a row to verify data preservation
 	physical := extPhysicalTable("schema-pkg", "items")
@@ -459,7 +459,7 @@ func TestBundledInstall_DefaultAllowlist(t *testing.T) {
 	})
 
 	// Empty allowlist → empty default set → nothing installed
-	InstallBundledPackages(bundledDir, packagesDir, "", stores, nil)
+	InstallBundledPackages(bundledDir, packagesDir, "", stores, nil, nil)
 
 	pkg, _ := stores.Packages.Get(ctx, "notes")
 	if pkg != nil {
@@ -484,7 +484,7 @@ func TestBundledInstall_WildcardAllowlist(t *testing.T) {
 		"id": "any-pkg", "title": "Any", "type": "surface", "version": "1.0.0",
 	})
 
-	InstallBundledPackages(bundledDir, packagesDir, "*", stores, nil)
+	InstallBundledPackages(bundledDir, packagesDir, "*", stores, nil, nil)
 
 	pkg, err := stores.Packages.Get(ctx, "any-pkg")
 	if err != nil || pkg == nil {

server/handlers/starlark_helpers.go

@@ -2,77 +2,9 @@ package handlers
 
 import (
 	"encoding/json"
-	"fmt"
 	"log"
-
-	"go.starlark.net/starlark"
 )
 
-// jsonToStarlark converts an arbitrary Go value (typically from JSON unmarshal)
-// to a Starlark value for passing into extension scripts.
-func jsonToStarlark(v any) starlark.Value {
-	switch val := v.(type) {
-	case nil:
-		return starlark.None
-	case bool:
-		return starlark.Bool(val)
-	case float64:
-		if val == float64(int64(val)) {
-			return starlark.MakeInt64(int64(val))
-		}
-		return starlark.Float(val)
-	case string:
-		return starlark.String(val)
-	case []any:
-		elems := make([]starlark.Value, len(val))
-		for i, e := range val {
-			elems[i] = jsonToStarlark(e)
-		}
-		return starlark.NewList(elems)
-	case map[string]any:
-		d := starlark.NewDict(len(val))
-		for k, v := range val {
-			_ = d.SetKey(starlark.String(k), jsonToStarlark(v))
-		}
-		return d
-	default:
-		return starlark.String(fmt.Sprintf("%v", val))
-	}
-}
-
-// starlarkValueToGo converts a Starlark value back to a Go value suitable
-// for JSON serialization.
-func starlarkValueToGo(v starlark.Value) any {
-	switch val := v.(type) {
-	case starlark.NoneType:
-		return nil
-	case starlark.Bool:
-		return bool(val)
-	case starlark.Int:
-		i, _ := val.Int64()
-		return i
-	case starlark.Float:
-		return float64(val)
-	case starlark.String:
-		return string(val)
-	case *starlark.List:
-		out := make([]any, val.Len())
-		for i := 0; i < val.Len(); i++ {
-			out[i] = starlarkValueToGo(val.Index(i))
-		}
-		return out
-	case *starlark.Dict:
-		out := make(map[string]any)
-		for _, item := range val.Items() {
-			k, _ := item[0].(starlark.String)
-			out[string(k)] = starlarkValueToGo(item[1])
-		}
-		return out
-	default:
-		return v.String()
-	}
-}
-
 // ParseSchemaVersion extracts the schema_version from a package manifest.
 func ParseSchemaVersion(manifest any) int {
 	switch m := manifest.(type) {

server/handlers/team_roles_test.go

@@ -0,0 +1,273 @@
+package handlers
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+
+	"armature/database"
+	"armature/middleware"
+	"armature/models"
+	"armature/store"
+)
+
+// ── Manifest: requires_roles parsing ──────────
+
+func TestValidateManifest_RequiresRoles(t *testing.T) {
+	m := map[string]any{
+		"id":             "role-gated",
+		"title":          "Role Gated Ext",
+		"type":           "surface",
+		"requires_roles": []any{"approver", "reviewer"},
+	}
+	info, err := ValidateManifest(m)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(info.RequiresRoles) != 2 {
+		t.Fatalf("expected 2 requires_roles, got %d", len(info.RequiresRoles))
+	}
+	if info.RequiresRoles[0] != "approver" || info.RequiresRoles[1] != "reviewer" {
+		t.Errorf("unexpected roles: %v", info.RequiresRoles)
+	}
+}
+
+func TestValidateManifest_RequiresRoles_Empty(t *testing.T) {
+	m := map[string]any{
+		"id":    "no-roles",
+		"title": "No Roles",
+		"type":  "surface",
+	}
+	info, err := ValidateManifest(m)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(info.RequiresRoles) != 0 {
+		t.Errorf("expected empty requires_roles, got %v", info.RequiresRoles)
+	}
+}
+
+func TestValidateManifest_RequiresRoles_SkipsInvalid(t *testing.T) {
+	m := map[string]any{
+		"id":             "bad-roles",
+		"title":          "Bad Roles",
+		"type":           "surface",
+		"requires_roles": []any{"ok", "", 42, "also-ok"},
+	}
+	info, err := ValidateManifest(m)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(info.RequiresRoles) != 2 {
+		t.Fatalf("expected 2 valid roles, got %d: %v", len(info.RequiresRoles), info.RequiresRoles)
+	}
+}
+
+// ── Store: team_user_roles CRUD ──────────────
+
+func seedTeamAndMember(t *testing.T, stores store.Stores) (teamID, userID, memberID string) {
+	t.Helper()
+	ctx := context.Background()
+
+	userID = seedRoleUser(t, "roleuser", "roleuser@test.com")
+	creatorID := seedRoleUser(t, "creator", "creator@test.com")
+
+	team := &models.Team{Name: "role-test-" + store.NewID()[:8], CreatedBy: creatorID, IsActive: true}
+	if err := stores.Teams.Create(ctx, team); err != nil {
+		t.Fatalf("create team: %v", err)
+	}
+	teamID = team.ID
+
+	mid, err := stores.Teams.AddMemberReturningID(ctx, teamID, userID, "member")
+	if err != nil {
+		t.Fatalf("add member: %v", err)
+	}
+	memberID = mid
+	return
+}
+
+func TestUserRoles_AddAndList(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+	ctx := context.Background()
+
+	teamID, userID, _ := seedTeamAndMember(t, stores)
+
+	// Initially: only the primary role
+	roles, err := stores.Teams.GetMemberRoles(ctx, teamID, userID)
+	if err != nil {
+		t.Fatalf("GetMemberRoles: %v", err)
+	}
+	if len(roles) != 1 || roles[0] != "member" {
+		t.Errorf("expected [member], got %v", roles)
+	}
+
+	// Add two additional roles
+	if err := stores.Teams.AddUserRole(ctx, teamID, userID, "reviewer", userID); err != nil {
+		t.Fatalf("AddUserRole: %v", err)
+	}
+	if err := stores.Teams.AddUserRole(ctx, teamID, userID, "approver", userID); err != nil {
+		t.Fatalf("AddUserRole: %v", err)
+	}
+
+	roles, _ = stores.Teams.GetMemberRoles(ctx, teamID, userID)
+	if len(roles) != 3 {
+		t.Fatalf("expected 3 roles, got %d: %v", len(roles), roles)
+	}
+
+	// ListUserRoles returns only additional
+	extra, _ := stores.Teams.ListUserRoles(ctx, teamID, userID)
+	if len(extra) != 2 {
+		t.Fatalf("expected 2 extra roles, got %d: %v", len(extra), extra)
+	}
+}
+
+func TestUserRoles_AddIdempotent(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+	ctx := context.Background()
+
+	teamID, userID, _ := seedTeamAndMember(t, stores)
+
+	// Add same role twice — should not error
+	if err := stores.Teams.AddUserRole(ctx, teamID, userID, "reviewer", userID); err != nil {
+		t.Fatalf("first add: %v", err)
+	}
+	if err := stores.Teams.AddUserRole(ctx, teamID, userID, "reviewer", userID); err != nil {
+		t.Fatalf("idempotent add should not error: %v", err)
+	}
+
+	extra, _ := stores.Teams.ListUserRoles(ctx, teamID, userID)
+	if len(extra) != 1 {
+		t.Errorf("expected 1 extra role after idempotent add, got %d", len(extra))
+	}
+}
+
+func TestUserRoles_HasRole(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+	ctx := context.Background()
+
+	teamID, userID, _ := seedTeamAndMember(t, stores)
+
+	// Primary role
+	has, _ := stores.Teams.HasRole(ctx, teamID, userID, "member")
+	if !has {
+		t.Error("expected HasRole=true for primary role 'member'")
+	}
+
+	// Non-existent role
+	has, _ = stores.Teams.HasRole(ctx, teamID, userID, "reviewer")
+	if has {
+		t.Error("expected HasRole=false for unassigned role")
+	}
+
+	// Add and check
+	stores.Teams.AddUserRole(ctx, teamID, userID, "reviewer", userID)
+	has, _ = stores.Teams.HasRole(ctx, teamID, userID, "reviewer")
+	if !has {
+		t.Error("expected HasRole=true after adding role")
+	}
+}
+
+func TestUserRoles_Remove(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+	ctx := context.Background()
+
+	teamID, userID, _ := seedTeamAndMember(t, stores)
+
+	stores.Teams.AddUserRole(ctx, teamID, userID, "reviewer", userID)
+	stores.Teams.RemoveUserRole(ctx, teamID, userID, "reviewer")
+
+	extra, _ := stores.Teams.ListUserRoles(ctx, teamID, userID)
+	if len(extra) != 0 {
+		t.Errorf("expected 0 extra roles after remove, got %d", len(extra))
+	}
+}
+
+func TestUserRoles_RemoveAllOnMemberDelete(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+	ctx := context.Background()
+
+	teamID, userID, _ := seedTeamAndMember(t, stores)
+
+	stores.Teams.AddUserRole(ctx, teamID, userID, "reviewer", userID)
+	stores.Teams.AddUserRole(ctx, teamID, userID, "approver", userID)
+
+	// Cleanup (as the handler does)
+	stores.Teams.RemoveAllUserRoles(ctx, teamID, userID)
+
+	extra, _ := stores.Teams.ListUserRoles(ctx, teamID, userID)
+	if len(extra) != 0 {
+		t.Errorf("expected 0 extra roles after RemoveAll, got %d", len(extra))
+	}
+}
+
+// ── Middleware: RequireRole ───────────────────
+
+func TestRequireRole_Allowed(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+	ctx := context.Background()
+
+	teamID, userID, _ := seedTeamAndMember(t, stores)
+	stores.Teams.AddUserRole(ctx, teamID, userID, "reviewer", userID)
+
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	_, r := gin.CreateTestContext(w)
+
+	called := false
+	r.Use(func(c *gin.Context) { c.Set("user_id", userID); c.Next() })
+	r.GET("/teams/:teamId/test",
+		middleware.RequireRole(stores.Teams, []string{"reviewer"}, stores),
+		func(c *gin.Context) {
+			called = true
+			c.Status(http.StatusOK)
+		},
+	)
+	req := httptest.NewRequest("GET", "/teams/"+teamID+"/test", nil)
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK || !called {
+		t.Errorf("expected 200 + handler called, got %d called=%v", w.Code, called)
+	}
+}
+
+func TestRequireRole_Denied(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+
+	teamID, userID, _ := seedTeamAndMember(t, stores)
+
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, r := gin.CreateTestContext(w)
+
+	r.Use(func(c *gin.Context) { c.Set("user_id", userID); c.Next() })
+	r.GET("/teams/:teamId/test",
+		middleware.RequireRole(stores.Teams, []string{"approver"}, stores),
+		func(c *gin.Context) { c.Status(http.StatusOK) },
+	)
+	c.Request = httptest.NewRequest("GET", "/teams/"+teamID+"/test", nil)
+	r.ServeHTTP(w, c.Request)
+
+	if w.Code != http.StatusForbidden {
+		t.Errorf("expected 403 for missing role, got %d", w.Code)
+	}
+}
+
+// ── helpers ──────────────────────────────────
+
+func seedRoleUser(t *testing.T, username, email string) string {
+	t.Helper()
+	uname := username + store.NewID()[:6]
+	q := `INSERT INTO users (username, email, password_hash, display_name, is_active, auth_source, handle)
+		VALUES ($1, $2, 'hash', $3, true, 'builtin', $4) RETURNING id`
+	return seedInsertReturningID(t, q, uname, email+store.NewID()[:6], uname, uname)
+}

server/handlers/teams.go

@@ -360,6 +360,11 @@ func (h *TeamHandler) RemoveMember(c *gin.Context) {
 		return
 	}
 
+	// Clean up additional roles from team_user_roles
+	if affectedUID != "" {
+		_ = h.stores.Teams.RemoveAllUserRoles(c.Request.Context(), teamID, affectedUID)
+	}
+
 	c.JSON(http.StatusOK, gin.H{"ok": true})
 	if affectedUID != "" {
 		h.notifyAuthChanged(affectedUID, "team_member_removed")
@@ -449,6 +454,106 @@ func (h *TeamHandler) ListTeamAuditActions(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"actions": actions})
 }
 
+// ── Member User Roles (many-to-many) ─────────
+
+// ListMemberRoles returns the full effective role set for a team member.
+// GET /api/v1/teams/:teamId/members/:memberId/roles
+func (h *TeamHandler) ListMemberRoles(c *gin.Context) {
+	teamID := getTeamID(c)
+	memberID := c.Param("memberId")
+
+	uid := h.memberUserID(c.Request.Context(), teamID, memberID)
+	if uid == "" {
+		c.JSON(http.StatusNotFound, gin.H{"error": "member not found"})
+		return
+	}
+
+	roles, err := h.stores.Teams.GetMemberRoles(c.Request.Context(), teamID, uid)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "query failed"})
+		return
+	}
+
+	// Also fetch the primary role for the response
+	member, _ := h.stores.Teams.GetMember(c.Request.Context(), teamID, uid)
+	primary := ""
+	if member != nil {
+		primary = member.Role
+	}
+
+	c.JSON(http.StatusOK, gin.H{"data": roles, "primary": primary})
+}
+
+// AddMemberRole assigns an additional role to a team member.
+// POST /api/v1/teams/:teamId/members/:memberId/roles
+func (h *TeamHandler) AddMemberRole(c *gin.Context) {
+	teamID := getTeamID(c)
+	memberID := c.Param("memberId")
+
+	var req struct {
+		Role string `json:"role" binding:"required,min=1,max=50"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if err := validateTeamRole(c.Request.Context(), h.stores, teamID, req.Role); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	uid := h.memberUserID(c.Request.Context(), teamID, memberID)
+	if uid == "" {
+		c.JSON(http.StatusNotFound, gin.H{"error": "member not found"})
+		return
+	}
+
+	assignedBy := getUserID(c)
+	if err := h.stores.Teams.AddUserRole(c.Request.Context(), teamID, uid, req.Role, assignedBy); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to add role"})
+		return
+	}
+
+	c.JSON(http.StatusCreated, gin.H{"ok": true})
+	h.notifyAuthChanged(uid, "team_role_added")
+	AuditLog(h.stores.Audit, c, "team.add_member_role", "team", teamID, map[string]interface{}{
+		"member_id": memberID, "user_id": uid, "role": req.Role,
+	})
+}
+
+// RemoveMemberRole removes an additional role from a team member.
+// DELETE /api/v1/teams/:teamId/members/:memberId/roles/:role
+func (h *TeamHandler) RemoveMemberRole(c *gin.Context) {
+	teamID := getTeamID(c)
+	memberID := c.Param("memberId")
+	role := c.Param("role")
+
+	uid := h.memberUserID(c.Request.Context(), teamID, memberID)
+	if uid == "" {
+		c.JSON(http.StatusNotFound, gin.H{"error": "member not found"})
+		return
+	}
+
+	// Don't allow removing the primary role via this endpoint
+	member, _ := h.stores.Teams.GetMember(c.Request.Context(), teamID, uid)
+	if member != nil && member.Role == role {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "cannot remove primary role; use member update instead"})
+		return
+	}
+
+	if err := h.stores.Teams.RemoveUserRole(c.Request.Context(), teamID, uid, role); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to remove role"})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"ok": true})
+	h.notifyAuthChanged(uid, "team_role_removed")
+	AuditLog(h.stores.Audit, c, "team.remove_member_role", "team", teamID, map[string]interface{}{
+		"member_id": memberID, "user_id": uid, "role": role,
+	})
+}
+
 // ── Team Roles API ─────────────────
 
 // builtinRoles are always present in every team's role list.

server/handlers/upgrade_test.go

@@ -42,7 +42,7 @@ func TestUpgrade_SchemaAddIndex(t *testing.T) {
 			},
 		},
 	})
-	CreateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "idx-pkg", tables)
+	CreateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "idx-pkg", tables, false)
 
 	// Insert a row
 	physical := extPhysicalTable("idx-pkg", "events")
@@ -116,7 +116,7 @@ func TestUpgrade_SchemaAddColumnIdempotent(t *testing.T) {
 			},
 		},
 	})
-	CreateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "idem-pkg", tables)
+	CreateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "idem-pkg", tables, false)
 
 	// Insert a row
 	physical := extPhysicalTable("idem-pkg", "items")
@@ -183,7 +183,7 @@ func TestUpgrade_SchemaMultiColumnAdd(t *testing.T) {
 			},
 		},
 	})
-	CreateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "multi-pkg", tables)
+	CreateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "multi-pkg", tables, false)
 
 	// Insert a row
 	physical := extPhysicalTable("multi-pkg", "records")
@@ -411,7 +411,7 @@ func TestUpgrade_BundledSkipExistingOnRestart(t *testing.T) {
 	})
 
 	// First install
-	InstallBundledPackages(bundledDir, packagesDir, "*", stores, nil)
+	InstallBundledPackages(bundledDir, packagesDir, "*", stores, nil, nil)
 
 	pkg, _ := stores.Packages.Get(ctx, "restart-pkg")
 	if pkg == nil {
@@ -427,7 +427,7 @@ func TestUpgrade_BundledSkipExistingOnRestart(t *testing.T) {
 	})
 
 	// Second install — should skip because package exists
-	InstallBundledPackages(bundledDir, packagesDir, "*", stores, nil)
+	InstallBundledPackages(bundledDir, packagesDir, "*", stores, nil, nil)
 
 	pkg, _ = stores.Packages.Get(ctx, "restart-pkg")
 	if pkg.Version != "1.0.0" {
@@ -438,7 +438,7 @@ func TestUpgrade_BundledSkipExistingOnRestart(t *testing.T) {
 	}
 }
 
-func TestUpgrade_PackageDormantOnUnmetRequires(t *testing.T) {
+func TestUpgrade_PackageSkippedOnUnmetRequiredCaps(t *testing.T) {
 	stores := newTestStores(t)
 	ctx := context.Background()
 
@@ -447,25 +447,22 @@ func TestUpgrade_PackageDormantOnUnmetRequires(t *testing.T) {
 
 	// Package requires a capability that doesn't exist
 	buildTestPkg(t, bundledDir, map[string]any{
-		"id":       "future-pkg",
+		"id":      "future-pkg",
-		"title":    "Future",
+		"title":   "Future",
-		"type":     "extension",
+		"type":    "extension",
-		"version":  "1.0.0",
+		"version": "1.0.0",
-		"hooks":    []string{"on_install"},
+		"hooks":   []string{"on_install"},
-		"requires": []string{"kernel>=99.0.0"},
+		"capabilities": map[string]any{
+			"required": []string{"pgvector"},
+		},
 	})
 
-	InstallBundledPackages(bundledDir, packagesDir, "*", stores, nil)
+	// No capabilities detected → pgvector is unavailable
+	InstallBundledPackages(bundledDir, packagesDir, "*", stores, nil, nil)
 
 	pkg, _ := stores.Packages.Get(ctx, "future-pkg")
-	if pkg == nil {
+	if pkg != nil {
-		t.Fatal("package should still be registered")
+		t.Error("package with unmet required capabilities should not be registered")
-	}
-	if pkg.Status != "dormant" {
-		t.Errorf("status = %q, want %q", pkg.Status, "dormant")
-	}
-	if pkg.Enabled {
-		t.Error("dormant package should not be enabled")
 	}
 }
 
@@ -524,7 +521,7 @@ func TestUpgrade_MigrateExtTables_NewTable(t *testing.T) {
 		},
 	}
 
-	changes, err := MigrateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "migrate-new", newTables)
+	changes, err := MigrateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "migrate-new", newTables, false)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -562,7 +559,7 @@ func TestUpgrade_MigrateExtTables_AddColumnPreservesRows(t *testing.T) {
 			},
 		},
 	})
-	CreateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "migrate-col", tables)
+	CreateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "migrate-col", tables, false)
 
 	physical := extPhysicalTable("migrate-col", "records")
 	_, err := database.TestDB.ExecContext(ctx,
@@ -577,7 +574,7 @@ func TestUpgrade_MigrateExtTables_AddColumnPreservesRows(t *testing.T) {
 			Columns: map[string]string{"title": "text", "status": "text"},
 		},
 	}
-	changes, err := MigrateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "migrate-col", newTables)
+	changes, err := MigrateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "migrate-col", newTables, false)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -629,7 +626,7 @@ func TestUpgrade_MigrateExtTables_IndexIdempotent(t *testing.T) {
 			},
 		},
 	})
-	CreateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "migrate-idx", tables)
+	CreateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "migrate-idx", tables, false)
 
 	// Migrate with same index — should not fail
 	newTables := map[string]TableDef{
@@ -638,13 +635,13 @@ func TestUpgrade_MigrateExtTables_IndexIdempotent(t *testing.T) {
 			Indexes: [][]string{{"category"}},
 		},
 	}
-	_, err := MigrateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "migrate-idx", newTables)
+	_, err := MigrateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "migrate-idx", newTables, false)
 	if err != nil {
 		t.Fatal("idempotent index migration should not fail:", err)
 	}
 
 	// Run again — still no error
-	_, err = MigrateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "migrate-idx", newTables)
+	_, err = MigrateExtTables(ctx, database.TestDB, database.IsPostgres(), stores, "migrate-idx", newTables, false)
 	if err != nil {
 		t.Fatal("second idempotent index migration should not fail:", err)
 	}

server/handlers/workflow_assignment_handlers.go

@@ -262,7 +262,7 @@ func (h *WorkflowAssignmentHandler) enrichAssignments(ctx context.Context, assig
 			// Resolve stage name and SLA from the published version snapshot
 			ver, _ := h.stores.Workflows.GetVersion(ctx, inst.WorkflowID, inst.WorkflowVersion)
 			if ver != nil {
-				stages := parseSnapshotStagesForEnrich(ver.Snapshot)
+				stages, _ := models.ParseSnapshotStages(ver.Snapshot)
 				for _, s := range stages {
 					if s.Name == a.Stage {
 						v.StageName = s.Name
@@ -287,15 +287,3 @@ func (h *WorkflowAssignmentHandler) enrichAssignments(ctx context.Context, assig
 	return views
 }
 
-// parseSnapshotStagesForEnrich is a lightweight stage parser for enrichment.
-func parseSnapshotStagesForEnrich(snapshot json.RawMessage) []models.WorkflowStage {
-	var wrapped struct {
-		Stages []models.WorkflowStage `json:"stages"`
-	}
-	if err := json.Unmarshal(snapshot, &wrapped); err == nil && len(wrapped.Stages) > 0 {
-		return wrapped.Stages
-	}
-	var stages []models.WorkflowStage
-	json.Unmarshal(snapshot, &stages)
-	return stages
-}

server/handlers/workflow_engine_test.go

@@ -18,7 +18,7 @@ func testEngine(t *testing.T) *workflow.Engine {
 	return workflow.NewEngine(s, nil, nil)
 }
 
-// seedEngineFixture creates a 3-stage workflow (form → review → form),
+// seedEngineFixture creates a 3-stage workflow (form → form → form),
 // publishes it, and returns (workflowID, userID, teamID).
 func seedEngineFixture(t *testing.T, slug string) (string, string, string) {
 	t.Helper()
@@ -42,7 +42,7 @@ func seedEngineFixture(t *testing.T, slug string) (string, string, string) {
 
 	stages := []models.WorkflowStage{
 		{WorkflowID: wf.ID, Ordinal: 0, Name: "intake", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple},
-		{WorkflowID: wf.ID, Ordinal: 1, Name: "review", StageMode: models.StageModeReview, Audience: models.AudienceTeam, StageType: models.StageTypeSimple, AssignmentTeamID: &teamID},
+		{WorkflowID: wf.ID, Ordinal: 1, Name: "review", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple, AssignmentTeamID: &teamID},
 		{WorkflowID: wf.ID, Ordinal: 2, Name: "final", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple},
 	}
 	for i := range stages {
@@ -51,7 +51,7 @@ func seedEngineFixture(t *testing.T, slug string) (string, string, string) {
 		}
 	}
 
-	snapshot, _ := json.Marshal(stages)
+	snapshot, _ := json.Marshal(map[string]any{"stages": stages})
 	ver := &models.WorkflowVersion{WorkflowID: wf.ID, VersionNumber: 1, Snapshot: snapshot}
 	if err := s.Workflows.Publish(ctx, ver); err != nil {
 		t.Fatalf("publish: %v", err)
@@ -134,13 +134,13 @@ func TestEngine_BranchRouting(t *testing.T) {
 
 	stages := []models.WorkflowStage{
 		{WorkflowID: wf.ID, Ordinal: 0, Name: "intake", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple, BranchRules: branchRules},
-		{WorkflowID: wf.ID, Ordinal: 1, Name: "normal-review", StageMode: models.StageModeReview, Audience: models.AudienceTeam, StageType: models.StageTypeSimple},
+		{WorkflowID: wf.ID, Ordinal: 1, Name: "normal-review", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple},
-		{WorkflowID: wf.ID, Ordinal: 2, Name: "escalation", StageMode: models.StageModeReview, Audience: models.AudienceTeam, StageType: models.StageTypeSimple},
+		{WorkflowID: wf.ID, Ordinal: 2, Name: "escalation", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple},
 	}
 	for i := range stages {
 		s.Workflows.CreateStage(ctx, &stages[i])
 	}
-	snapshot, _ := json.Marshal(stages)
+	snapshot, _ := json.Marshal(map[string]any{"stages": stages})
 	s.Workflows.Publish(ctx, &models.WorkflowVersion{WorkflowID: wf.ID, VersionNumber: 1, Snapshot: snapshot})
 
 	// Test: priority=high → escalation
@@ -184,12 +184,12 @@ func TestEngine_PublicEntry(t *testing.T) {
 
 	stages := []models.WorkflowStage{
 		{WorkflowID: wf.ID, Ordinal: 0, Name: "public-form", StageMode: models.StageModeForm, Audience: models.AudiencePublic, StageType: models.StageTypeSimple},
-		{WorkflowID: wf.ID, Ordinal: 1, Name: "team-review", StageMode: models.StageModeReview, Audience: models.AudienceTeam, StageType: models.StageTypeSimple},
+		{WorkflowID: wf.ID, Ordinal: 1, Name: "team-review", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple},
 	}
 	for i := range stages {
 		s.Workflows.CreateStage(ctx, &stages[i])
 	}
-	snapshot, _ := json.Marshal(stages)
+	snapshot, _ := json.Marshal(map[string]any{"stages": stages})
 	s.Workflows.Publish(ctx, &models.WorkflowVersion{WorkflowID: wf.ID, VersionNumber: 1, Snapshot: snapshot})
 
 	// StartPublic
@@ -253,13 +253,13 @@ func TestEngine_SignoffGate(t *testing.T) {
 		"validation": map[string]any{"required_approvals": 2},
 	})
 	stages := []models.WorkflowStage{
-		{WorkflowID: wf.ID, Ordinal: 0, Name: "gated-stage", StageMode: models.StageModeReview, Audience: models.AudienceTeam, StageType: models.StageTypeSimple, StageConfig: validationCfg},
+		{WorkflowID: wf.ID, Ordinal: 0, Name: "gated-stage", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple, StageConfig: validationCfg},
 		{WorkflowID: wf.ID, Ordinal: 1, Name: "done", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple},
 	}
 	for i := range stages {
 		s.Workflows.CreateStage(ctx, &stages[i])
 	}
-	snapshot, _ := json.Marshal(stages)
+	snapshot, _ := json.Marshal(map[string]any{"stages": stages})
 	s.Workflows.Publish(ctx, &models.WorkflowVersion{WorkflowID: wf.ID, VersionNumber: 1, Snapshot: snapshot})
 
 	inst, _ := eng.Start(ctx, wf.ID, json.RawMessage(`{}`), user1)
@@ -307,13 +307,13 @@ func TestEngine_SignoffRejection(t *testing.T) {
 		"validation": map[string]any{"required_approvals": 1, "reject_action": "cancel"},
 	})
 	stages := []models.WorkflowStage{
-		{WorkflowID: wf.ID, Ordinal: 0, Name: "review", StageMode: models.StageModeReview, Audience: models.AudienceTeam, StageType: models.StageTypeSimple, StageConfig: validationCfg},
+		{WorkflowID: wf.ID, Ordinal: 0, Name: "review", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple, StageConfig: validationCfg},
 		{WorkflowID: wf.ID, Ordinal: 1, Name: "approved", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple},
 	}
 	for i := range stages {
 		s.Workflows.CreateStage(ctx, &stages[i])
 	}
-	snapshot, _ := json.Marshal(stages)
+	snapshot, _ := json.Marshal(map[string]any{"stages": stages})
 	s.Workflows.Publish(ctx, &models.WorkflowVersion{WorkflowID: wf.ID, VersionNumber: 1, Snapshot: snapshot})
 
 	inst, _ := eng.Start(ctx, wf.ID, json.RawMessage(`{}`), userID)
@@ -495,7 +495,7 @@ func TestEngine_AutomatedStageContextIncludesStartedBy(t *testing.T) {
 	for i := range stages {
 		s.Workflows.CreateStage(ctx, &stages[i])
 	}
-	snapshot, _ := json.Marshal(stages)
+	snapshot, _ := json.Marshal(map[string]any{"stages": stages})
 	s.Workflows.Publish(ctx, &models.WorkflowVersion{WorkflowID: wf.ID, VersionNumber: 1, Snapshot: snapshot})
 
 	// Engine with no runner — automated stage silently skips, instance stays at auto-stage
@@ -590,7 +590,7 @@ func TestPackageInstall_ManifestRoundtrip(t *testing.T) {
 		{WorkflowID: wf.ID, Ordinal: 1, Name: "classify", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple, BranchRules: branchRules},
 		{WorkflowID: wf.ID, Ordinal: 2, Name: "fix-critical", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple, SLASeconds: &sla},
 		{WorkflowID: wf.ID, Ordinal: 3, Name: "fix-normal", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple},
-		{WorkflowID: wf.ID, Ordinal: 4, Name: "verify", StageMode: models.StageModeReview, Audience: models.AudienceTeam, StageType: models.StageTypeSimple},
+		{WorkflowID: wf.ID, Ordinal: 4, Name: "verify", StageMode: models.StageModeForm, Audience: models.AudienceTeam, StageType: models.StageTypeSimple},
 	}
 	for i := range stages {
 		if err := s.Workflows.CreateStage(ctx, &stages[i]); err != nil {

server/handlers/workflow_hooks.go

@@ -78,7 +78,7 @@ func FireOnAdvanceHook(
 	// Parse stage_data into Starlark dict
 	var dataMap map[string]interface{}
 	if json.Unmarshal(stageData, &dataMap) == nil {
-		_ = ctxDict.SetKey(starlark.String("stage_data"), jsonToStarlark(dataMap))
+		_ = ctxDict.SetKey(starlark.String("stage_data"), sandbox.GoToStarlark(dataMap))
 	} else {
 		_ = ctxDict.SetKey(starlark.String("stage_data"), starlark.NewDict(0))
 	}
@@ -117,7 +117,7 @@ func parseOnAdvanceResult(val starlark.Value) *OnAdvanceResult {
 	// Check for enriched stage_data
 	if sdVal, found, _ := d.Get(starlark.String("stage_data")); found {
 		if sd, ok := sdVal.(*starlark.Dict); ok {
-			goMap := starlarkDictToMap(sd)
+			goMap := sandbox.DictToMap(sd)
 			if data, err := json.Marshal(goMap); err == nil {
 				result.EnrichedData = data
 				return result
@@ -128,44 +128,3 @@ func parseOnAdvanceResult(val starlark.Value) *OnAdvanceResult {
 	return nil
 }
 
-// starlarkDictToMap converts a Starlark dict to a Go map.
-func starlarkDictToMap(d *starlark.Dict) map[string]any {
-	result := make(map[string]any, d.Len())
-	for _, item := range d.Items() {
-		k, ok := item[0].(starlark.String)
-		if !ok {
-			continue
-		}
-		result[string(k)] = starlarkToGo(item[1])
-	}
-	return result
-}
-
-// starlarkToGo converts a Starlark value to a Go value.
-func starlarkToGo(v starlark.Value) any {
-	switch val := v.(type) {
-	case starlark.NoneType:
-		return nil
-	case starlark.Bool:
-		return bool(val)
-	case starlark.Int:
-		if i, ok := val.Int64(); ok {
-			return i
-		}
-		return val.String()
-	case starlark.Float:
-		return float64(val)
-	case starlark.String:
-		return string(val)
-	case *starlark.List:
-		result := make([]any, val.Len())
-		for i := 0; i < val.Len(); i++ {
-			result[i] = starlarkToGo(val.Index(i))
-		}
-		return result
-	case *starlark.Dict:
-		return starlarkDictToMap(val)
-	default:
-		return v.String()
-	}
-}

server/handlers/workflow_hooks_test.go

@@ -5,6 +5,8 @@ import (
 	"testing"
 
 	"go.starlark.net/starlark"
+
+	"armature/sandbox"
 )
 
 // ── parseOnAdvanceResult ────────────────────
@@ -82,7 +84,7 @@ func TestParseOnAdvanceResult_EmptyDict(t *testing.T) {
 	}
 }
 
-// ── starlarkDictToMap ───────────────────────
+// ── DictToMap ───────────────────────
 
 func TestStarlarkDictToMap_NestedStructure(t *testing.T) {
 	inner := starlark.NewDict(1)
@@ -98,7 +100,7 @@ func TestStarlarkDictToMap_NestedStructure(t *testing.T) {
 	_ = outer.SetKey(starlark.String("nested"), inner)
 	_ = outer.SetKey(starlark.String("members"), members)
 
-	m := starlarkDictToMap(outer)
+	m := sandbox.DictToMap(outer)
 
 	if m["title"] != "Test" {
 		t.Errorf("expected title='Test', got %v", m["title"])

server/handlers/workflow_instance_handlers.go

@@ -199,7 +199,7 @@ func (h *WorkflowInstanceHandler) enrichInstances(ctx context.Context, instances
 		// SLA check from version snapshot
 		ver, _ := h.stores.Workflows.GetVersion(ctx, inst.WorkflowID, inst.WorkflowVersion)
 		if ver != nil {
-			stages := parseSnapshotStagesForView(ver.Snapshot)
+			stages, _ := models.ParseSnapshotStages(ver.Snapshot)
 			for _, s := range stages {
 				if s.Name == inst.CurrentStage {
 					v.StageName = s.Name
@@ -217,18 +217,6 @@ func (h *WorkflowInstanceHandler) enrichInstances(ctx context.Context, instances
 	return views
 }
 
-func parseSnapshotStagesForView(snapshot json.RawMessage) []models.WorkflowStage {
-	var wrapped struct {
-		Stages []models.WorkflowStage `json:"stages"`
-	}
-	if err := json.Unmarshal(snapshot, &wrapped); err == nil && len(wrapped.Stages) > 0 {
-		return wrapped.Stages
-	}
-	var stages []models.WorkflowStage
-	json.Unmarshal(snapshot, &stages)
-	return stages
-}
-
 // CancelTeamInstance cancels an instance belonging to a team workflow.
 // POST /api/v1/teams/:teamId/workflow-instances/:iid/cancel
 func (h *WorkflowInstanceHandler) CancelTeamInstance(c *gin.Context) {

server/handlers/workflow_packages.go

@@ -55,7 +55,6 @@ func (h *WorkflowPackageHandler) ExportWorkflowPackage(c *gin.Context) {
 			"ordinal":         s.Ordinal,
 			"stage_mode":      s.StageMode,
 			"audience":        s.Audience,
-			"stage_type":      s.StageType,
 			"auto_transition": s.AutoTransition,
 		}
 		if s.AssignmentTeamID != nil {
@@ -230,6 +229,7 @@ func InstallWorkflowFromManifest(ctx *gin.Context, stores store.Stores, pkgID st
 			StarlarkHook:     s.StarlarkHook,
 			SLASeconds:       s.SLASeconds,
 		}
+		st.StageMode = models.NormalizeStageModeInput(st.StageMode)
 		if st.StageMode == "" {
 			st.StageMode = models.StageModeDelegated
 		}
@@ -256,7 +256,7 @@ func InstallWorkflowFromManifest(ctx *gin.Context, stores store.Stores, pkgID st
 	// Publish version 1 (snapshot of stages) and activate the workflow
 	// so it's immediately usable after install.
 	stages, _ := stores.Workflows.ListStages(reqCtx, workflowID)
-	snapshot, _ := json.Marshal(stages)
+	snapshot, _ := json.Marshal(map[string]any{"stages": stages})
 	ver := &models.WorkflowVersion{
 		WorkflowID:    workflowID,
 		VersionNumber: 1,
@@ -284,7 +284,7 @@ type workflowPkgStage struct {
 	Ordinal          int     `json:"ordinal"`
 	StageMode        string  `json:"stage_mode"`
 	Audience         string  `json:"audience"`
-	StageType        string  `json:"stage_type"`
+	StageType        string  `json:"stage_type"` // deprecated — kept for backward-compat deserialization
 	AutoTransition   bool    `json:"auto_transition"`
 	AssignmentTeamID *string `json:"assignment_team_id,omitempty"`
 	SurfacePkgID     *string `json:"surface_pkg_id,omitempty"`

server/handlers/workflow_store_test.go

@@ -69,7 +69,7 @@ func seedWorkflowFixture(t *testing.T, s store.Stores, userID, teamID string) (s
 		WorkflowID:       wf.ID,
 		Ordinal:          1,
 		Name:             "review",
-		StageMode:        models.StageModeReview,
+		StageMode:        models.StageModeForm,
 		Audience:         models.AudienceTeam,
 		StageType:        models.StageTypeSimple,
 		AssignmentTeamID: &teamID,
@@ -82,7 +82,7 @@ func seedWorkflowFixture(t *testing.T, s store.Stores, userID, teamID string) (s
 	}
 
 	// Publish version 1
-	snapshot, _ := json.Marshal([]models.WorkflowStage{*s1, *s2})
+	snapshot, _ := json.Marshal(map[string]any{"stages": []models.WorkflowStage{*s1, *s2}})
 	ver := &models.WorkflowVersion{
 		WorkflowID:    wf.ID,
 		VersionNumber: 1,

server/handlers/workflow_team.go

@@ -45,7 +45,13 @@ func (h *WorkflowHandler) requireTeamWorkflow(c *gin.Context) bool {
 // AdoptTeamWorkflow clones a global (team_id=NULL) workflow into this team.
 // The global original is left untouched so other teams can also adopt it.
 // POST /api/v1/teams/:teamId/workflows/:id/adopt
+//
+// Deprecated: Use POST /api/v1/teams/:teamId/packages/:id/adopt instead.
+// This endpoint will be removed in a future version.
 func (h *WorkflowHandler) AdoptTeamWorkflow(c *gin.Context) {
+	c.Header("X-Deprecated", "Use POST /api/v1/teams/:teamId/packages/:id/adopt instead")
+	log.Printf("[workflows] DEPRECATED: AdoptTeamWorkflow called for team %s — use POST /teams/:teamId/packages/:id/adopt", c.Param("teamId"))
+
 	ctx := c.Request.Context()
 	teamID := c.Param("teamId")
 	srcID := c.Param("id")

server/handlers/workflows.go

@@ -202,11 +202,12 @@ func (h *WorkflowHandler) CreateStage(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "name is required"})
 		return
 	}
+	st.StageMode = models.NormalizeStageModeInput(st.StageMode)
 	if st.StageMode == "" {
 		st.StageMode = models.StageModeDelegated
 	}
 	if !models.ValidStageModes[st.StageMode] {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "stage_mode must be form, review, delegated, or automated"})
+		c.JSON(http.StatusBadRequest, gin.H{"error": "stage_mode must be form, delegated, or automated"})
 		return
 	}
 	if st.Audience == "" {
@@ -219,18 +220,10 @@ func (h *WorkflowHandler) CreateStage(c *gin.Context) {
 	if st.StageType == "" {
 		st.StageType = models.StageTypeSimple
 	}
-	if !models.ValidStageTypes[st.StageType] {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "stage_type must be simple, dynamic, or automated"})
-		return
-	}
 	if st.StageMode == models.StageModeDelegated && st.SurfacePkgID == nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "delegated mode requires surface_pkg_id"})
 		return
 	}
-	if (st.StageType == models.StageTypeDynamic || st.StageType == models.StageTypeAutomated) && st.StarlarkHook == nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "dynamic/automated stage_type requires starlark_hook"})
-		return
-	}
 	if st.Ordinal == 0 {
 		existing, _ := h.stores.Workflows.ListStages(c.Request.Context(), st.WorkflowID)
 		st.Ordinal = len(existing)
@@ -252,26 +245,19 @@ func (h *WorkflowHandler) UpdateStage(c *gin.Context) {
 	}
 	st.ID = c.Param("sid")
 	st.WorkflowID = c.Param("id")
+	st.StageMode = models.NormalizeStageModeInput(st.StageMode)
 	if st.StageMode != "" && !models.ValidStageModes[st.StageMode] {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "stage_mode must be form, review, delegated, or automated"})
+		c.JSON(http.StatusBadRequest, gin.H{"error": "stage_mode must be form, delegated, or automated"})
 		return
 	}
 	if st.Audience != "" && !models.ValidAudiences[st.Audience] {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "audience must be team, public, or system"})
 		return
 	}
-	if st.StageType != "" && !models.ValidStageTypes[st.StageType] {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "stage_type must be simple, dynamic, or automated"})
-		return
-	}
 	if st.StageMode == models.StageModeDelegated && st.SurfacePkgID == nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "delegated mode requires surface_pkg_id"})
 		return
 	}
-	if (st.StageType == models.StageTypeDynamic || st.StageType == models.StageTypeAutomated) && st.StarlarkHook == nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "dynamic/automated stage_type requires starlark_hook"})
-		return
-	}
 	if err := h.stores.Workflows.UpdateStage(c.Request.Context(), &st); err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to update stage"})
 		return

server/main.go

@@ -169,10 +169,28 @@ func main() {
 		starlarkRunner.SetPackagesDir(cfg.StoragePath + "/packages")
 	}
 	starlarkRunner.SetBus(bus)
+	if objStore != nil {
+		starlarkRunner.SetObjectStore(objStore)
+	}
 	if os.Getenv("EXT_ALLOW_PRIVATE_IPS") == "true" {
 		starlarkRunner.SetAllowPrivateIPs(true)
 		log.Printf("  ⚠️  Extension SSRF protection relaxed: private IPs allowed")
 	}
+	if cfg.WorkspaceRoot != "" {
+		if err := os.MkdirAll(cfg.WorkspaceRoot, 0755); err == nil {
+			starlarkRunner.SetWorkspaceRoot(cfg.WorkspaceRoot, cfg.WorkspaceQuotaMB)
+			log.Printf("  workspace root: %s", cfg.WorkspaceRoot)
+		} else {
+			log.Printf("  workspace root %s not writable, workspace module disabled", cfg.WorkspaceRoot)
+		}
+	}
+
+	// ── Capability Detection ──────────
+	// Probe the runtime environment to discover available capabilities.
+	// Used by install validation and the settings.has_capability() Starlark API.
+	detectedCaps := handlers.DetectCapabilities(database.DB, database.IsPostgres(), objStore, cfg.WorkspaceRoot)
+	starlarkRunner.SetCapabilities(detectedCaps)
+	log.Printf("  capabilities: %v", detectedCaps)
 
 	// ── Bundled Packages ───────────────
 	// Auto-install bundled .pkg archives on first run.
@@ -182,7 +200,7 @@ func main() {
 		if cfg.StoragePath != "" {
 			bundledPkgDir = cfg.StoragePath + "/packages"
 		}
-		handlers.InstallBundledPackages(cfg.BundledPackagesDir, bundledPkgDir, cfg.BundledPackages, stores, starlarkRunner)
+		handlers.InstallBundledPackages(cfg.BundledPackagesDir, bundledPkgDir, cfg.BundledPackages, stores, starlarkRunner, detectedCaps)
 	}
 
 	// ── Register extension user permissions ─────
@@ -433,6 +451,7 @@ func main() {
 
 		// ── Workflow Engine (shared by public + protected routes) ──
 		wfEngine := workflow.NewEngine(stores, bus, starlarkRunner)
+		starlarkRunner.SetWorkflowEngine(wfEngine)
 
 		// ── Public Workflow Entry ─────
 		publicWfH := handlers.NewWorkflowPublicHandler(wfEngine, stores)
@@ -527,6 +546,10 @@ func main() {
 			protected.POST("/instances/:iid/signoffs", wfSignoffH.Submit)
 			protected.GET("/instances/:iid/signoffs", wfSignoffH.List)
 
+			// Forms validation
+			formsH := &handlers.FormsHandler{}
+			protected.POST("/forms/validate", formsH.Validate)
+
 			// Surface discovery
 			pkgH := handlers.NewPackageHandler(stores)
 			protected.GET("/surfaces", pkgH.ListEnabledSurfaces)
@@ -622,6 +645,9 @@ func main() {
 				teamScoped.POST("/members", teams.AddMember)
 				teamScoped.PUT("/members/:memberId", teams.UpdateMember)
 				teamScoped.DELETE("/members/:memberId", teams.RemoveMember)
+				teamScoped.GET("/members/:memberId/roles", teams.ListMemberRoles)
+				teamScoped.POST("/members/:memberId/roles", teams.AddMemberRole)
+				teamScoped.DELETE("/members/:memberId/roles/:role", teams.RemoveMemberRole)
 				teamScoped.GET("/roles", teams.ListRoles)
 				teamScoped.PUT("/roles", teams.UpdateRoles)
 
@@ -639,6 +665,13 @@ func main() {
 				teamScoped.POST("/packages/install", teamPkgH.InstallTeamPackage)
 				teamScoped.DELETE("/packages/:id", teamPkgH.DeleteTeamPackage)
 
+				// Team package adoption
+				adoptH := handlers.NewPackageAdoptHandler(stores)
+				teamScoped.POST("/packages/:id/adopt", adoptH.AdoptPackage)
+				teamScoped.GET("/packages/adoptable", adoptH.ListAdoptablePackages)
+				teamScoped.DELETE("/packages/:id/unadopt", adoptH.UnadoptPackage)
+				teamScoped.GET("/roles/catalog", adoptH.ListRoleCatalog)
+
 				// Team package settings — cascade overrides
 				teamPkgSettingsH := handlers.NewTeamPackageSettingsHandler(stores)
 				teamScoped.GET("/packages/:id/settings", teamPkgSettingsH.GetTeamPackageSettings)
@@ -791,6 +824,7 @@ func main() {
 
 			// Extensions (admin)
 			extAdm := handlers.NewExtensionHandler(stores)
+			extAdm.SetCapabilities(detectedCaps)
 			admin.GET("/extensions", extAdm.AdminListExtensions)
 			admin.POST("/extensions", extAdm.AdminInstallExtension)
 			admin.PUT("/extensions/:id", extAdm.AdminUpdateExtension)
@@ -819,6 +853,7 @@ func main() {
 			pkgAdm.SetSandbox(sandbox.New(sandbox.DefaultConfig()))
 			pkgAdm.SetBundledDir(cfg.BundledPackagesDir)
 			pkgAdm.SetHub(hub)
+			pkgAdm.SetCapabilities(detectedCaps)
 
 			// Package registry — must be registered before /packages/:id
 			registryH := handlers.NewRegistryHandler(stores, packagesDir, pkgAdm)
@@ -839,6 +874,7 @@ func main() {
 			admin.POST("/packages/:id/update", pkgAdm.UpdatePackage)
 			admin.GET("/packages/:id/export", pkgAdm.ExportPackage)
 			admin.GET("/dependencies", pkgAdm.ListAllDependencies)
+			admin.GET("/slots", pkgAdm.ListSlots)
 
 			// Workflow package export
 			wfPkgH := handlers.NewWorkflowPackageHandler(stores)
@@ -883,6 +919,12 @@ func main() {
 			metricsH := handlers.NewMetricsHandler(metricsCollector)
 			admin.GET("/metrics", metricsH.GetMetrics)
 
+			// ── Capabilities ──────────
+			capsH := handlers.NewCapabilitiesHandler(func() map[string]bool {
+				return handlers.DetectCapabilities(database.DB, database.IsPostgres(), objStore, cfg.WorkspaceRoot)
+			})
+			admin.GET("/capabilities", capsH.GetCapabilities)
+
 			// ── Backup/Restore ─────────
 			backupH := handlers.NewBackupHandler(stores, packagesDir, cfg.StoragePath)
 			admin.POST("/backup", backupH.CreateBackup)
@@ -931,12 +973,16 @@ func main() {
 		Session: middleware.OptionalAuth(cfg, stores.Users, userCache),
 	})
 
-	// Mounted at /s/:slug/api/* with JWT auth (returns 401, not redirect).
+	// Extension surface + API routes: /s/:slug/* dispatches between
+	// surface rendering (GET) and ext API calls (all methods, /api/* prefix).
 	{
 		extAPIH := handlers.NewExtAPIHandler(stores, starlarkRunner)
-		extAPI := base.Group("/s/:slug/api")
+		pageEngine.RegisterExtensionRoutes(
-		extAPI.Use(middleware.Auth(cfg, stores.Users, userCache, stores.APITokens))
+			base,
-		extAPI.Any("/*path", extAPIH.Handle)
+			middleware.OptionalAuth(cfg, stores.Users, userCache),
+			middleware.Auth(cfg, stores.Users, userCache, stores.APITokens),
+			extAPIH.Handle,
+		)
 	}
 
 	bp := cfg.BasePath

server/middleware/team.go

@@ -54,6 +54,51 @@ func RequireTeamAdmin(teams store.TeamStore, allStores ...store.Stores) gin.Hand
 	}
 }
 
+// RequireRole returns middleware that restricts access to users holding at least
+// one of the specified roles in the team identified by :teamId.
+// Checks both the primary role (team_members.role) and additional roles
+// (team_user_roles). System admins are always allowed through.
+func RequireRole(teams store.TeamStore, roles []string, allStores ...store.Stores) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if len(allStores) > 0 && isSystemAdmin(c, allStores[0]) {
+			c.Next()
+			return
+		}
+
+		userID := c.GetString("user_id")
+		teamID := c.Param("teamId")
+		if teamID == "" {
+			c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{
+				"error": "team ID required",
+			})
+			return
+		}
+
+		memberRoles, err := teams.GetMemberRoles(c.Request.Context(), teamID, userID)
+		if err != nil || len(memberRoles) == 0 {
+			c.AbortWithStatusJSON(http.StatusForbidden, gin.H{
+				"error": "required role not held",
+			})
+			return
+		}
+
+		roleSet := make(map[string]bool, len(memberRoles))
+		for _, r := range memberRoles {
+			roleSet[r] = true
+		}
+		for _, required := range roles {
+			if roleSet[required] {
+				c.Next()
+				return
+			}
+		}
+
+		c.AbortWithStatusJSON(http.StatusForbidden, gin.H{
+			"error": "required role not held",
+		})
+	}
+}
+
 // RequireTeamMember returns middleware that restricts access to users who
 // belong to the team identified by :teamId (any role).
 // System admins are always allowed through.

server/models/models.go

@@ -80,6 +80,16 @@ type TeamMember struct {
 	Username    string `json:"username,omitempty"`
 }
 
+// TeamUserRole is a many-to-many join: one user can hold multiple roles in a team.
+type TeamUserRole struct {
+	ID         string `json:"id" db:"id"`
+	TeamID     string `json:"team_id" db:"team_id"`
+	UserID     string `json:"user_id" db:"user_id"`
+	Role       string `json:"role" db:"role"`
+	AssignedBy string `json:"assigned_by,omitempty" db:"assigned_by"`
+	AssignedAt string `json:"assigned_at" db:"assigned_at"`
+}
+
 // PLATFORM POLICIES
 
 var PolicyDefaults = map[string]string{

server/models/models_extension_perm.go

@@ -37,6 +37,9 @@ const (
 	ExtPermTriggersRegister     = "triggers.register"
 	ExtPermRealtimePublish      = "realtime.publish"
 	ExtPermBatchExec            = "batch.exec"
+	ExtPermFilesRead            = "files.read"
+	ExtPermFilesWrite           = "files.write"
+	ExtPermWorkspaceManage      = "workspace.manage"
 )
 
 // ValidExtensionPermissions is the set of recognized permission keys.
@@ -52,6 +55,9 @@ var ValidExtensionPermissions = map[string]bool{
 	ExtPermTriggersRegister:     true,
 	ExtPermRealtimePublish:      true,
 	ExtPermBatchExec:            true,
+	ExtPermFilesRead:            true,
+	ExtPermFilesWrite:           true,
+	ExtPermWorkspaceManage:      true,
 }
 
 // ── Extension Permission Model ───────────────

server/models/snapshot.go

@@ -0,0 +1,25 @@
+package models
+
+import (
+	"encoding/json"
+	"fmt"
+)
+
+// ParseSnapshotStages parses a version snapshot into a slice of
+// WorkflowStage.  It handles both the wrapped format
+// {"stages": [...], "workflow": {...}} and the legacy flat array [...].
+func ParseSnapshotStages(raw json.RawMessage) ([]WorkflowStage, error) {
+	// Try wrapped format first
+	var wrapped struct {
+		Stages []WorkflowStage `json:"stages"`
+	}
+	if err := json.Unmarshal(raw, &wrapped); err == nil && len(wrapped.Stages) > 0 {
+		return wrapped.Stages, nil
+	}
+	// Fallback to flat array
+	var stages []WorkflowStage
+	if err := json.Unmarshal(raw, &stages); err != nil {
+		return nil, fmt.Errorf("corrupt version snapshot: %w", err)
+	}
+	return stages, nil
+}

server/models/workflow.go

@@ -2,9 +2,6 @@ package models
 
 import (
 	"encoding/json"
-	"fmt"
-	"regexp"
-	"strings"
 	"time"
 )
 
@@ -59,9 +56,9 @@ type WorkflowStage struct {
 	Name             string          `json:"name"`
 	AssignmentTeamID *string         `json:"assignment_team_id,omitempty"`
 	FormTemplate     json.RawMessage `json:"form_template"`
-	StageMode        string          `json:"stage_mode"`  // form | review | delegated | automated
+	StageMode        string          `json:"stage_mode"`  // form | delegated | automated
 	Audience         string          `json:"audience"`    // team | public | system
-	StageType        string          `json:"stage_type"`  // simple | dynamic | automated
+	StageType        string          `json:"stage_type"`  // deprecated — retained for backward compatibility
 	AutoTransition   bool            `json:"auto_transition"`
 	StageConfig      json.RawMessage `json:"stage_config"`
 	BranchRules      json.RawMessage `json:"branch_rules"`
@@ -75,7 +72,6 @@ type WorkflowStage struct {
 
 const (
 	StageModeForm      = "form"
-	StageModeReview    = "review"
 	StageModeDelegated = "delegated"
 	StageModeAutomated = "automated"
 )
@@ -83,12 +79,22 @@ const (
 // ValidStageModes is the set of valid stage_mode values.
 var ValidStageModes = map[string]bool{
 	StageModeForm:      true,
-	StageModeReview:    true,
 	StageModeDelegated: true,
 	StageModeAutomated: true,
 }
 
-// ── Stage Type Constants ────────────────────
+// NormalizeStageModeInput maps deprecated stage_mode values to their
+// replacements. "review" → "form"; all others pass through unchanged.
+func NormalizeStageModeInput(mode string) string {
+	if mode == "review" {
+		return StageModeForm
+	}
+	return mode
+}
+
+// ── Stage Type Constants (deprecated) ───────
+// stage_type is redundant with starlark_hook presence and is no longer
+// validated. Constants are retained for backward-compatible references.
 
 const (
 	StageTypeSimple    = "simple"
@@ -96,13 +102,6 @@ const (
 	StageTypeAutomated = "automated"
 )
 
-// ValidStageTypes is the set of valid stage_type values.
-var ValidStageTypes = map[string]bool{
-	StageTypeSimple:    true,
-	StageTypeDynamic:   true,
-	StageTypeAutomated: true,
-}
-
 // ── Audience Constants ──────────────────────
 
 const (
@@ -118,320 +117,6 @@ var ValidAudiences = map[string]bool{
 	AudienceSystem: true,
 }
 
-// ── Typed Form Template ─────────────────────
-
-// TypedFormTemplate is the structured form_template schema.
-type TypedFormTemplate struct {
-	Fields    []FormField    `json:"fields"`
-	Fieldsets []FormFieldset `json:"fieldsets,omitempty"`
-	Hooks     *FormHooks     `json:"hooks,omitempty"`
-}
-
-// FormFieldset groups fields into a labelled step for progressive forms.
-// When fieldsets is present, top-level fields is ignored.
-type FormFieldset struct {
-	Label  string      `json:"label"`
-	Fields []FormField `json:"fields"`
-}
-
-// FieldCondition controls conditional visibility of a form field.
-// When set, the field is shown/validated only if the condition is met.
-type FieldCondition struct {
-	When  string `json:"when"`            // key of the field to check
-	Op    string `json:"op,omitempty"`    // eq (default) | neq | in | exists
-	Value any    `json:"value,omitempty"` // value to compare against
-}
-
-// FormField is a single field in a typed form template.
-type FormField struct {
-	Key         string           `json:"key"`
-	Type        string           `json:"type"` // text | email | select | number | date | textarea | checkbox | file
-	Label       string           `json:"label"`
-	Placeholder string           `json:"placeholder,omitempty"`
-	Required    bool             `json:"required,omitempty"`
-	Default     interface{}      `json:"default,omitempty"`
-	Options     []FormOption     `json:"options,omitempty"`
-	Validation  *FormValidation  `json:"validation,omitempty"`
-	Condition   *FieldCondition  `json:"condition,omitempty"`
-}
-
-// FormOption is a choice for select fields.
-type FormOption struct {
-	Value string `json:"value"`
-	Label string `json:"label"`
-}
-
-// FormValidation holds type-specific validation rules.
-type FormValidation struct {
-	MinLength *int     `json:"min_length,omitempty"` // text, textarea, email
-	MaxLength *int     `json:"max_length,omitempty"` // text, textarea, email
-	Pattern   string   `json:"pattern,omitempty"`    // text, email (regex)
-	Min       *float64 `json:"min,omitempty"`        // number
-	Max       *float64 `json:"max,omitempty"`        // number
-	Step      *float64 `json:"step,omitempty"`       // number
-	MinDate   string   `json:"min_date,omitempty"`   // date (YYYY-MM-DD)
-	MaxDate   string   `json:"max_date,omitempty"`   // date (YYYY-MM-DD)
-	Accept    string   `json:"accept,omitempty"`     // file (MIME types)
-	MaxSize   *int64   `json:"max_size_bytes,omitempty"` // file
-}
-
-// FormHooks wires Starlark validation/submission hooks for a stage's form.
-type FormHooks struct {
-	PackageID string `json:"package_id"`
-	Validate  string `json:"validate,omitempty"`  // entry point name
-	OnSubmit  string `json:"on_submit,omitempty"` // entry point name
-}
-
-// ValidFormFieldTypes is the set of recognized field types.
-var ValidFormFieldTypes = map[string]bool{
-	"text": true, "email": true, "select": true, "number": true,
-	"date": true, "textarea": true, "checkbox": true, "file": true,
-}
-
-// ParseTypedFormTemplate parses a raw JSON form_template into the typed schema.
-// Returns nil if the template is empty, legacy format, or not a typed template.
-func ParseTypedFormTemplate(raw json.RawMessage) *TypedFormTemplate {
-	if len(raw) == 0 || string(raw) == "{}" || string(raw) == "null" {
-		return nil
-	}
-	var tpl TypedFormTemplate
-	if err := json.Unmarshal(raw, &tpl); err != nil {
-		return nil
-	}
-
-	if len(tpl.Fieldsets) > 0 {
-		var allFields []FormField
-		for _, fs := range tpl.Fieldsets {
-			allFields = append(allFields, fs.Fields...)
-		}
-		if len(allFields) > 0 {
-			tpl.Fields = allFields
-			return &tpl
-		}
-	}
-
-	if len(tpl.Fields) == 0 {
-		return nil
-	}
-	// Verify this is actually the typed format (first field must have key+type)
-	if tpl.Fields[0].Key == "" || tpl.Fields[0].Type == "" {
-		return nil
-	}
-	return &tpl
-}
-
-// AllFields returns all fields from the template, whether from top-level fields or fieldsets.
-func (t *TypedFormTemplate) AllFields() []FormField {
-	return t.Fields // ParseTypedFormTemplate already flattens fieldsets into Fields
-}
-
-// FieldError is a validation error for a specific form field.
-type FieldError struct {
-	Key     string `json:"key"`
-	Message string `json:"message"`
-}
-
-// ValidateFormData validates submitted data against a typed form template.
-func ValidateFormData(tpl *TypedFormTemplate, data map[string]interface{}) []FieldError {
-	var errs []FieldError
-	for _, f := range tpl.Fields {
-		if f.Condition != nil && !evaluateFieldCondition(f.Condition, data) {
-			continue
-		}
-
-		val, present := data[f.Key]
-
-		// Required check
-		if f.Required && (!present || val == nil || val == "") {
-			errs = append(errs, FieldError{Key: f.Key, Message: f.Label + " is required"})
-			continue
-		}
-		if !present || val == nil {
-			continue
-		}
-
-		switch f.Type {
-		case "text", "textarea":
-			errs = append(errs, validateString(f, val)...)
-		case "email":
-			errs = append(errs, validateEmail(f, val)...)
-		case "number":
-			errs = append(errs, validateNumber(f, val)...)
-		case "date":
-			errs = append(errs, validateDate(f, val)...)
-		case "select":
-			errs = append(errs, validateSelect(f, val)...)
-		case "checkbox":
-			if _, ok := val.(bool); !ok {
-				errs = append(errs, FieldError{Key: f.Key, Message: f.Label + " must be true or false"})
-			}
-		}
-	}
-	return errs
-}
-
-func validateString(f FormField, val interface{}) []FieldError {
-	s, ok := val.(string)
-	if !ok {
-		return []FieldError{{Key: f.Key, Message: f.Label + " must be text"}}
-	}
-	var errs []FieldError
-	v := f.Validation
-	if v == nil {
-		return nil
-	}
-	if v.MinLength != nil && len(s) < *v.MinLength {
-		errs = append(errs, FieldError{Key: f.Key, Message: fmt.Sprintf("%s must be at least %d characters", f.Label, *v.MinLength)})
-	}
-	if v.MaxLength != nil && len(s) > *v.MaxLength {
-		errs = append(errs, FieldError{Key: f.Key, Message: fmt.Sprintf("%s must be at most %d characters", f.Label, *v.MaxLength)})
-	}
-	if v.Pattern != "" {
-		if re, err := regexp.Compile(v.Pattern); err == nil && !re.MatchString(s) {
-			errs = append(errs, FieldError{Key: f.Key, Message: f.Label + " does not match the required pattern"})
-		}
-	}
-	return errs
-}
-
-var emailRe = regexp.MustCompile(`^[^@\s]+@[^@\s]+\.[^@\s]+$`)
-
-func validateEmail(f FormField, val interface{}) []FieldError {
-	s, ok := val.(string)
-	if !ok {
-		return []FieldError{{Key: f.Key, Message: f.Label + " must be text"}}
-	}
-	if !emailRe.MatchString(s) {
-		return []FieldError{{Key: f.Key, Message: f.Label + " must be a valid email address"}}
-	}
-	var errs []FieldError
-	if f.Validation != nil {
-		if f.Validation.Pattern != "" {
-			if re, err := regexp.Compile(f.Validation.Pattern); err == nil && !re.MatchString(s) {
-				errs = append(errs, FieldError{Key: f.Key, Message: f.Label + " does not match the required pattern"})
-			}
-		}
-	}
-	return errs
-}
-
-func validateNumber(f FormField, val interface{}) []FieldError {
-	var n float64
-	switch v := val.(type) {
-	case float64:
-		n = v
-	case int:
-		n = float64(v)
-	case json.Number:
-		var err error
-		n, err = v.Float64()
-		if err != nil {
-			return []FieldError{{Key: f.Key, Message: f.Label + " must be a number"}}
-		}
-	case string:
-		return []FieldError{{Key: f.Key, Message: f.Label + " must be a number"}}
-	default:
-		return []FieldError{{Key: f.Key, Message: f.Label + " must be a number"}}
-	}
-	var errs []FieldError
-	if f.Validation != nil {
-		if f.Validation.Min != nil && n < *f.Validation.Min {
-			errs = append(errs, FieldError{Key: f.Key, Message: fmt.Sprintf("%s must be at least %g", f.Label, *f.Validation.Min)})
-		}
-		if f.Validation.Max != nil && n > *f.Validation.Max {
-			errs = append(errs, FieldError{Key: f.Key, Message: fmt.Sprintf("%s must be at most %g", f.Label, *f.Validation.Max)})
-		}
-	}
-	return errs
-}
-
-func validateDate(f FormField, val interface{}) []FieldError {
-	s, ok := val.(string)
-	if !ok {
-		return []FieldError{{Key: f.Key, Message: f.Label + " must be a date string (YYYY-MM-DD)"}}
-	}
-	_, err := time.Parse("2006-01-02", s)
-	if err != nil {
-		return []FieldError{{Key: f.Key, Message: f.Label + " must be a valid date (YYYY-MM-DD)"}}
-	}
-	if f.Validation != nil {
-		if f.Validation.MinDate != "" {
-			if minD, e := time.Parse("2006-01-02", f.Validation.MinDate); e == nil {
-				if d, _ := time.Parse("2006-01-02", s); d.Before(minD) {
-					return []FieldError{{Key: f.Key, Message: fmt.Sprintf("%s must be on or after %s", f.Label, f.Validation.MinDate)}}
-				}
-			}
-		}
-		if f.Validation.MaxDate != "" {
-			if maxD, e := time.Parse("2006-01-02", f.Validation.MaxDate); e == nil {
-				if d, _ := time.Parse("2006-01-02", s); d.After(maxD) {
-					return []FieldError{{Key: f.Key, Message: fmt.Sprintf("%s must be on or before %s", f.Label, f.Validation.MaxDate)}}
-				}
-			}
-		}
-	}
-	return nil
-}
-
-func validateSelect(f FormField, val interface{}) []FieldError {
-	s, ok := val.(string)
-	if !ok {
-		return []FieldError{{Key: f.Key, Message: f.Label + " must be a string"}}
-	}
-	if len(f.Options) == 0 {
-		return nil
-	}
-	for _, o := range f.Options {
-		if strings.EqualFold(o.Value, s) {
-			return nil
-		}
-	}
-	return []FieldError{{Key: f.Key, Message: f.Label + " is not a valid option"}}
-}
-
-// ── Field Condition Evaluator ─────
-
-// evaluateFieldCondition checks if a conditional field should be visible/validated.
-func evaluateFieldCondition(cond *FieldCondition, data map[string]interface{}) bool {
-	val, exists := data[cond.When]
-	op := cond.Op
-	if op == "" {
-		op = "eq"
-	}
-
-	switch op {
-	case "exists":
-		return exists
-	case "eq":
-		if !exists {
-			return false
-		}
-		return fmt.Sprintf("%v", val) == fmt.Sprintf("%v", cond.Value)
-	case "neq":
-		if !exists {
-			return true
-		}
-		return fmt.Sprintf("%v", val) != fmt.Sprintf("%v", cond.Value)
-	case "in":
-		if !exists {
-			return false
-		}
-		arr, ok := cond.Value.([]interface{})
-		if !ok {
-			return false
-		}
-		vs := fmt.Sprintf("%v", val)
-		for _, item := range arr {
-			if fmt.Sprintf("%v", item) == vs {
-				return true
-			}
-		}
-		return false
-	default:
-		return true
-	}
-}
-
 // ── Instance Status Constants ───────────────
 
 const (

server/pages/pages.go

@@ -99,7 +99,9 @@ type PageData struct {
 	Theme           string // "dark", "light", or "" (= use default)
 	SurfaceSettings any    // JSON-serialized to window.__SETTINGS__
 
-	Manifest *SurfaceManifest `json:"manifest,omitempty"`
+	Manifest      *SurfaceManifest `json:"manifest,omitempty"`
+	SurfacePath   string          `json:"-"` // matched surface path pattern, e.g. "/monitor"
+	SurfaceParams map[string]string `json:"-"` // extracted params, e.g. {"id": "abc"}
 
 	EnabledSurfaces []string `json:"-"`
 
@@ -158,29 +160,60 @@ func (e *Engine) extensionNavItems() []ExtensionNavItem {
 
 	var items []ExtensionNavItem
 	for _, sr := range surfaces {
-		if sr.Source == "core" || !sr.Enabled {
+		if sr.Source == "core" || !sr.Enabled || sr.Status != "active" {
 			continue
 		}
 		// Only surface and full types have routes — extensions are headless
 		if sr.Type != "surface" && sr.Type != "full" {
 			continue
 		}
-		route := ""
+
+		basePath := "/s/" + sr.ID
+		title := sr.Title
+
+		// Multi-surface: find the nav entry from surfaces array
 		if sr.Manifest != nil {
-			route, _ = sr.Manifest["route"].(string)
+			if rawSurfaces, ok := sr.Manifest["surfaces"].([]any); ok {
-		}
+				navEntry := findNavSurface(rawSurfaces)
-		if route == "" {
+				if navEntry != nil {
-			route = "/s/" + sr.ID
+					if p, ok := navEntry["path"].(string); ok && p != "/" {
+						basePath = "/s/" + sr.ID + p
+					}
+					if t, ok := navEntry["title"].(string); ok && t != "" {
+						title = t
+					}
+				}
+			}
 		}
+
 		items = append(items, ExtensionNavItem{
 			ID:    sr.ID,
-			Title: sr.Title,
+			Title: title,
-			Route: route,
+			Route: basePath,
 		})
 	}
 	return items
 }
 
+// findNavSurface returns the surface entry to use for navigation.
+// Returns the first entry with nav:true, falling back to the entry with path "/".
+func findNavSurface(surfaces []any) map[string]any {
+	var root map[string]any
+	for _, raw := range surfaces {
+		s, ok := raw.(map[string]any)
+		if !ok {
+			continue
+		}
+		if nav, ok := s["nav"].(bool); ok && nav {
+			return s
+		}
+		if p, ok := s["path"].(string); ok && p == "/" {
+			root = s
+		}
+	}
+	return root
+}
+
 // browserExtensionIDs returns IDs of enabled browser-tier extensions.
 // These extensions have JS scripts that should be injected into every page
 // so they can register renderers with the SDK.
@@ -401,8 +434,10 @@ func (e *Engine) RenderSurface(surfaceID string) gin.HandlerFunc {
 	}
 }
 
-// RenderExtensionSurface handles /s/:slug — dynamic DB lookup for extension surfaces.
+// RenderExtensionSurface handles extension surface rendering with multi-surface
-// No restart required after installing a surface via admin API.
+// support. Each surface entry in the manifest can have its own path, access
+// level, title, and layout. Called by RegisterExtensionRoutes for both root
+// requests (/s/:slug) and sub-path requests (/s/:slug/monitor).
 func (e *Engine) RenderExtensionSurface() gin.HandlerFunc {
 	return func(c *gin.Context) {
 		slug := c.Param("slug")
@@ -410,6 +445,10 @@ func (e *Engine) RenderExtensionSurface() gin.HandlerFunc {
 			c.String(http.StatusNotFound, "Surface not found")
 			return
 		}
+		reqPath := c.Param("path")
+		if reqPath == "" {
+			reqPath = "/"
+		}
 
 		if e.stores.Packages == nil {
 			c.String(http.StatusNotFound, "Surface registry not available")
@@ -427,28 +466,80 @@ func (e *Engine) RenderExtensionSurface() gin.HandlerFunc {
 			return
 		}
 		if sr.Source == "core" {
-			// Core surfaces have their own routes — don't serve them here
 			c.String(http.StatusNotFound, "Surface not found: "+slug)
 			return
 		}
 
+		// ── Early auth short-circuit ─────────────────────────────
+		// For all-authenticated packages, redirect before surface matching.
+		if rawSurfaces, ok := sr.Manifest["surfaces"].([]any); ok && len(rawSurfaces) > 0 {
+			profile := aggregateAccess(rawSurfaces)
+			if profile == "authenticated" && c.GetString("user_id") == "" {
+				c.Redirect(http.StatusTemporaryRedirect, e.cfg.BasePath+"/login")
+				return
+			}
+		}
+
+		// ── Multi-surface resolution ─────────────────────────────
+		var surfacePath string
+		var surfaceParams map[string]string
+		surfaceTitle := sr.Title
+		surfaceAccess := "authenticated"
+		surfaceLayout := "single"
+
+		// Read package-level defaults
+		if pkgAuth, ok := sr.Manifest["auth"].(string); ok && pkgAuth != "" {
+			surfaceAccess = pkgAuth
+		}
+		if pkgLayout, ok := sr.Manifest["layout"].(string); ok && pkgLayout != "" {
+			surfaceLayout = pkgLayout
+		}
+
+		if rawSurfaces, ok := sr.Manifest["surfaces"].([]any); ok && len(rawSurfaces) > 0 {
+			matched, params := matchSurface(rawSurfaces, reqPath)
+			if matched == nil {
+				c.String(http.StatusNotFound, "Page not found")
+				return
+			}
+			surfacePath, _ = matched["path"].(string)
+			surfaceParams = params
+			if t, ok := matched["title"].(string); ok && t != "" {
+				surfaceTitle = t
+			}
+			if a, ok := matched["access"].(string); ok && a != "" {
+				surfaceAccess = a
+			}
+			if l, ok := matched["layout"].(string); ok && l != "" {
+				surfaceLayout = l
+			}
+		} else {
+			// Legacy package without surfaces — only serve root path
+			if reqPath != "/" {
+				c.String(http.StatusNotFound, "Page not found")
+				return
+			}
+			surfacePath = "/"
+		}
+
+		// ── Access check ─────────────────────────────────────────
+		if !evaluateAccess(c, surfaceAccess) {
+			// Redirect unauthenticated users to login; deny others with 403
+			if c.GetString("user_id") == "" {
+				c.Redirect(http.StatusTemporaryRedirect, e.cfg.BasePath+"/login")
+			} else {
+				c.String(http.StatusForbidden, "Access denied")
+			}
+			return
+		}
+
 		user := e.getUserContext(c)
 
-		// Build manifest from DB record
-		route, _ := sr.Manifest["route"].(string)
-		if route == "" {
-			route = "/s/" + sr.ID
-		}
-		layout, _ := sr.Manifest["layout"].(string)
-		if layout == "" {
-			layout = "single"
-		}
 		manifest := &SurfaceManifest{
 			ID:       sr.ID,
-			Route:    route,
+			Route:    "/s/" + sr.ID,
-			Title:    sr.Title,
+			Title:    surfaceTitle,
 			Template: "surface-extension",
-			Layout:   layout,
+			Layout:   surfaceLayout,
 			Source:   "extension",
 		}
 
@@ -456,6 +547,8 @@ func (e *Engine) RenderExtensionSurface() gin.HandlerFunc {
 			Surface:           sr.ID,
 			User:              user,
 			Manifest:          manifest,
+			SurfacePath:       surfacePath,
+			SurfaceParams:     surfaceParams,
 			EnabledSurfaces:   e.EnabledSurfaceIDs(),
 			ExtensionSurfaces: e.extensionNavItems(),
 			BrowserExtensions: e.browserExtensionIDs(),
@@ -463,6 +556,127 @@ func (e *Engine) RenderExtensionSurface() gin.HandlerFunc {
 	}
 }
 
+// matchSurface finds the best-matching surface entry for a request path.
+// Supports Gin-style param segments (/:id matches /abc). Static segments
+// are preferred over param segments. Returns nil if no surface matches.
+func matchSurface(surfaces []any, reqPath string) (map[string]any, map[string]string) {
+	reqParts := splitPath(reqPath)
+
+	type candidate struct {
+		surface map[string]any
+		params  map[string]string
+		score   int // higher = more static segments = better match
+	}
+
+	var best *candidate
+	for _, raw := range surfaces {
+		s, ok := raw.(map[string]any)
+		if !ok {
+			continue
+		}
+		pattern, _ := s["path"].(string)
+		if pattern == "" {
+			continue
+		}
+		patParts := splitPath(pattern)
+		if len(patParts) != len(reqParts) {
+			continue
+		}
+
+		params := map[string]string{}
+		score := 0
+		matched := true
+		for i, pp := range patParts {
+			if strings.HasPrefix(pp, ":") {
+				params[pp[1:]] = reqParts[i]
+			} else if pp == reqParts[i] {
+				score++
+			} else {
+				matched = false
+				break
+			}
+		}
+		if !matched {
+			continue
+		}
+		if best == nil || score > best.score {
+			best = &candidate{surface: s, params: params, score: score}
+		}
+	}
+	if best == nil {
+		return nil, nil
+	}
+	return best.surface, best.params
+}
+
+// splitPath splits a URL path into non-empty segments.
+// "/" → [], "/monitor" → ["monitor"], "/monitor/:id" → ["monitor", ":id"]
+func splitPath(p string) []string {
+	var parts []string
+	for _, s := range strings.Split(p, "/") {
+		if s != "" {
+			parts = append(parts, s)
+		}
+	}
+	return parts
+}
+
+// aggregateAccess scans surfaces to determine the package's access profile.
+// Returns "public" (all public), "authenticated" (all require auth), or "mixed".
+func aggregateAccess(surfaces []any) string {
+	hasPublic := false
+	hasAuth := false
+	for _, raw := range surfaces {
+		s, ok := raw.(map[string]any)
+		if !ok {
+			continue
+		}
+		access, _ := s["access"].(string)
+		if access == "" {
+			access = "authenticated" // default
+		}
+		if access == "public" {
+			hasPublic = true
+		} else {
+			hasAuth = true
+		}
+		if hasPublic && hasAuth {
+			return "mixed"
+		}
+	}
+	if hasPublic {
+		return "public"
+	}
+	return "authenticated"
+}
+
+// evaluateAccess checks whether the current request meets an access requirement.
+func evaluateAccess(c *gin.Context, access string) bool {
+	switch {
+	case access == "public":
+		return true
+	case access == "authenticated":
+		return c.GetString("user_id") != ""
+	case access == "admin":
+		return c.GetBool("is_admin")
+	case strings.HasPrefix(access, "group:"):
+		// Group membership check — look for groups set by auth middleware
+		group := strings.TrimPrefix(access, "group:")
+		if groups, exists := c.Get("user_groups"); exists {
+			if gs, ok := groups.([]string); ok {
+				for _, g := range gs {
+					if g == group {
+						return true
+					}
+				}
+			}
+		}
+		return false
+	default:
+		return false
+	}
+}
+
 // PageRouteMiddleware holds middleware handlers for each auth level.
 // Passed to RegisterPageRoutes by main.go.
 type PageRouteMiddleware struct {
@@ -502,8 +716,9 @@ func (e *Engine) RegisterPageRoutes(base *gin.RouterGroup, mw PageRouteMiddlewar
 			registerRoutes(group, s, handler)
 		}
 
-		// No restart needed after installing new surfaces via admin API.
+		// Extension surfaces are registered separately via
-		group.GET("/s/:slug", e.RenderExtensionSurface())
+		// RegisterExtensionRoutes (called from main.go) to unify
+		// the /s/:slug route tree with the ext API dispatcher.
 	}
 
 	// Admin surfaces — auth + admin role middleware
@@ -553,6 +768,75 @@ func (e *Engine) RegisterPageRoutes(base *gin.RouterGroup, mw PageRouteMiddlewar
 	log.Printf("[pages] Registered routes for %d surfaces", len(e.surfaces))
 }
 
+// RegisterExtensionRoutes registers the combined extension surface and ext API
+// routes. A single /s/:slug/*path catch-all dispatches between:
+//   - /s/:slug/api/* → apiAuth middleware + extAPIHandler (JSON API)
+//   - /s/:slug/*     → surface handler with per-surface access checks (HTML)
+//
+// This avoids Gin route conflicts between the catch-all and the API sub-path.
+// Must be called AFTER RegisterPageRoutes (which handles core surfaces).
+func (e *Engine) RegisterExtensionRoutes(
+	base *gin.RouterGroup,
+	optAuth gin.HandlerFunc,
+	apiAuth gin.HandlerFunc,
+	extAPIHandler gin.HandlerFunc,
+) {
+	surfaceHandler := e.RenderExtensionSurface()
+
+	sGroup := base.Group("/s/:slug")
+	sGroup.Use(optAuth) // populate user context if token present; don't require it
+
+	// Dispatcher handles both root and sub-path requests.
+	// API requests (/s/:slug/api/*) go to extAPIHandler with JWT auth.
+	// Everything else goes to the surface handler with per-surface access checks.
+	dispatch := func(c *gin.Context) {
+		subPath := c.Param("path")
+		if subPath == "" {
+			subPath = "/"
+		}
+
+		// API requests: /s/:slug/api/*
+		if strings.HasPrefix(subPath, "/api/") || subPath == "/api" {
+			apiAuth(c)
+			if c.IsAborted() {
+				return
+			}
+			// Rewrite the path param so the ext API handler sees the
+			// API-relative path, e.g. "/api/items" → "/items"
+			apiPath := strings.TrimPrefix(subPath, "/api")
+			if apiPath == "" {
+				apiPath = "/"
+			}
+			for i := range c.Params {
+				if c.Params[i].Key == "path" {
+					c.Params[i].Value = apiPath
+					break
+				}
+			}
+			extAPIHandler(c)
+			return
+		}
+
+		// Surface requests: GET only
+		if c.Request.Method != http.MethodGet {
+			c.String(http.StatusMethodNotAllowed, "Method not allowed")
+			return
+		}
+
+		surfaceHandler(c)
+	}
+
+	// Root path: /s/:slug (Gin requires a separate registration since
+	// /*path doesn't match the bare group path)
+	sGroup.GET("", func(c *gin.Context) {
+		c.Params = append(c.Params, gin.Param{Key: "path", Value: "/"})
+		dispatch(c)
+	})
+
+	// Sub-paths: /s/:slug/*path — API and surface dispatch
+	sGroup.Any("/*path", dispatch)
+}
+
 // surfaceHandler returns the appropriate Gin handler for a surface.
 func (e *Engine) surfaceHandler(s SurfaceManifest) gin.HandlerFunc {
 	if s.ID == "workflow" {
@@ -637,7 +921,7 @@ type WorkflowPageData struct {
 	WorkflowDescription  string
 	SessionID            string
 	SessionName          string
-	StageMode            string // form | review | delegated | automated
+	StageMode            string // form | delegated | automated
 	StageName            string
 	FormTemplateJSON     string // typed form template JSON (empty if delegated)
 	TotalStages          int
@@ -664,7 +948,7 @@ type WorkflowLandingPageData struct {
 	PersonaName string
 	PersonaIcon string
 	StageCount     int
-	FirstStageMode string // form | review | delegated | automated
+	FirstStageMode string // form | delegated | automated
 	ResumeURL      string // non-empty if visitor has an active session
 }
 

server/pages/pages_handler_test.go

@@ -0,0 +1,295 @@
+package pages
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+
+	"armature/config"
+	"armature/store"
+)
+
+// ── mock PackageStore ────────────────────────────────────────
+
+// mockPackageStore implements store.PackageStore with in-memory data.
+// Only Get and List are wired; everything else is a no-op stub.
+type mockPackageStore struct {
+	pkgs map[string]*store.PackageRegistration
+}
+
+func newMockPackageStore(pkgs ...*store.PackageRegistration) *mockPackageStore {
+	m := &mockPackageStore{pkgs: make(map[string]*store.PackageRegistration)}
+	for _, p := range pkgs {
+		m.pkgs[p.ID] = p
+	}
+	return m
+}
+
+func (m *mockPackageStore) Get(_ context.Context, id string) (*store.PackageRegistration, error) {
+	if p, ok := m.pkgs[id]; ok {
+		return p, nil
+	}
+	return nil, nil
+}
+
+func (m *mockPackageStore) List(_ context.Context) ([]store.PackageRegistration, error) {
+	var out []store.PackageRegistration
+	for _, p := range m.pkgs {
+		out = append(out, *p)
+	}
+	return out, nil
+}
+
+func (m *mockPackageStore) ListEnabled(_ context.Context) ([]string, error) {
+	var ids []string
+	for id, p := range m.pkgs {
+		if p.Enabled {
+			ids = append(ids, id)
+		}
+	}
+	return ids, nil
+}
+
+// Stubs — not exercised by the pages handler tests.
+func (m *mockPackageStore) Seed(context.Context, string, string, string, map[string]any) error { return nil }
+func (m *mockPackageStore) SetEnabled(context.Context, string, bool) error       { return nil }
+func (m *mockPackageStore) SetStatus(context.Context, string, string) error      { return nil }
+func (m *mockPackageStore) Delete(context.Context, string) error                 { return nil }
+func (m *mockPackageStore) Create(context.Context, *store.PackageRegistration) error { return nil }
+func (m *mockPackageStore) Update(context.Context, string, *store.PackageRegistration) error { return nil }
+func (m *mockPackageStore) ListByType(context.Context, string) ([]store.PackageRegistration, error) { return nil, nil }
+func (m *mockPackageStore) ListEnabledByType(context.Context, string) ([]store.PackageRegistration, error) { return nil, nil }
+func (m *mockPackageStore) ListForUser(context.Context, string) ([]store.UserPackage, error) { return nil, nil }
+func (m *mockPackageStore) GetUserSettings(context.Context, string, string) (*store.PackageUserSettings, error) { return nil, nil }
+func (m *mockPackageStore) SetUserSettings(context.Context, *store.PackageUserSettings) error { return nil }
+func (m *mockPackageStore) DeleteUserSettings(context.Context, string, string) error { return nil }
+func (m *mockPackageStore) ListVisiblePackages(context.Context, string) ([]store.PackageRegistration, error) { return nil, nil }
+func (m *mockPackageStore) SetSchemaVersion(context.Context, string, int) error { return nil }
+func (m *mockPackageStore) GetPackageSettings(context.Context, string) (json.RawMessage, error) { return nil, nil }
+func (m *mockPackageStore) SetPackageSettings(context.Context, string, json.RawMessage) error { return nil }
+func (m *mockPackageStore) GetTeamSettings(context.Context, string, string) (json.RawMessage, error) { return nil, nil }
+func (m *mockPackageStore) SetTeamSettings(context.Context, string, string, json.RawMessage) error { return nil }
+func (m *mockPackageStore) DeleteTeamSettings(context.Context, string, string) error { return nil }
+func (m *mockPackageStore) ListAdoptable(context.Context) ([]store.PackageRegistration, error) { return nil, nil }
+func (m *mockPackageStore) GetByAdoptedFrom(context.Context, string, string) (*store.PackageRegistration, error) { return nil, nil }
+
+// ── test helpers ─────────────────────────────────────────────
+
+// testEngine creates a minimal Engine with parsed templates and mock stores.
+func testEngine(t *testing.T, pkgs ...*store.PackageRegistration) *Engine {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	e := &Engine{
+		cfg:     &config.Config{BasePath: ""},
+		stores:  store.Stores{Packages: newMockPackageStore(pkgs...)},
+		loaders: make(map[string]DataLoaderFunc),
+	}
+	e.parseTemplates()
+	e.registerCoreSurfaces()
+	return e
+}
+
+// testRouter builds a Gin router with extension routes registered.
+func testRouter(t *testing.T, pkgs ...*store.PackageRegistration) *gin.Engine {
+	t.Helper()
+	engine := testEngine(t, pkgs...)
+	r := gin.New()
+
+	// OptionalAuth — set user_id if "X-User-ID" header is present (test shortcut)
+	optAuth := func(c *gin.Context) {
+		if uid := c.GetHeader("X-User-ID"); uid != "" {
+			c.Set("user_id", uid)
+			c.Set("role", "user")
+		}
+		c.Next()
+	}
+
+	// API auth — for ext API sub-paths (not exercised in surface tests)
+	apiAuth := func(c *gin.Context) { c.Next() }
+
+	// Ext API handler stub
+	apiHandler := func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) }
+
+	engine.RegisterExtensionRoutes(r.Group(""), optAuth, apiAuth, apiHandler)
+	return r
+}
+
+func doGet(r *gin.Engine, path string, headers ...string) *httptest.ResponseRecorder {
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("GET", path, nil)
+	for i := 0; i+1 < len(headers); i += 2 {
+		req.Header.Set(headers[i], headers[i+1])
+	}
+	r.ServeHTTP(w, req)
+	return w
+}
+
+// ── handler integration tests ───────────────────────────────
+
+func TestHandler_RootPathRefresh(t *testing.T) {
+	pkg := &store.PackageRegistration{
+		ID: "test-pkg", Title: "Test", Type: "surface", Source: "extension",
+		Enabled: true, Status: "active",
+		Manifest: map[string]any{
+			"surfaces": []any{
+				map[string]any{"path": "/", "access": "authenticated", "title": "Dashboard"},
+			},
+		},
+	}
+	r := testRouter(t, pkg)
+	w := doGet(r, "/s/test-pkg", "X-User-ID", "user-1")
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200, got %d", w.Code)
+	}
+}
+
+func TestHandler_SubPathStaticRefresh(t *testing.T) {
+	pkg := &store.PackageRegistration{
+		ID: "test-pkg", Title: "Test", Type: "surface", Source: "extension",
+		Enabled: true, Status: "active",
+		Manifest: map[string]any{
+			"surfaces": []any{
+				map[string]any{"path": "/", "access": "authenticated", "title": "Dashboard"},
+				map[string]any{"path": "/monitor", "access": "authenticated", "title": "Monitor"},
+			},
+		},
+	}
+	r := testRouter(t, pkg)
+	w := doGet(r, "/s/test-pkg/monitor", "X-User-ID", "user-1")
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200, got %d", w.Code)
+	}
+}
+
+func TestHandler_SubPathParamRefresh(t *testing.T) {
+	pkg := &store.PackageRegistration{
+		ID: "test-pkg", Title: "Test", Type: "surface", Source: "extension",
+		Enabled: true, Status: "active",
+		Manifest: map[string]any{
+			"surfaces": []any{
+				map[string]any{"path": "/", "access": "authenticated", "title": "Dashboard"},
+				map[string]any{"path": "/:id", "access": "authenticated", "title": "Detail"},
+			},
+		},
+	}
+	r := testRouter(t, pkg)
+	w := doGet(r, "/s/test-pkg/abc123", "X-User-ID", "user-1")
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200, got %d", w.Code)
+	}
+	body := w.Body.String()
+	if !strings.Contains(body, `"id":"abc123"`) {
+		t.Errorf("expected __SURFACE_PARAMS__ to contain id=abc123")
+	}
+}
+
+func TestHandler_UnauthRedirect(t *testing.T) {
+	pkg := &store.PackageRegistration{
+		ID: "test-pkg", Title: "Test", Type: "surface", Source: "extension",
+		Enabled: true, Status: "active",
+		Manifest: map[string]any{
+			"surfaces": []any{
+				map[string]any{"path": "/dashboard", "access": "authenticated", "title": "Dashboard"},
+			},
+		},
+	}
+	r := testRouter(t, pkg)
+	w := doGet(r, "/s/test-pkg/dashboard") // no auth header
+	if w.Code != http.StatusTemporaryRedirect {
+		t.Errorf("expected 307, got %d", w.Code)
+	}
+	loc := w.Header().Get("Location")
+	if !strings.Contains(loc, "/login") {
+		t.Errorf("expected redirect to /login, got %s", loc)
+	}
+}
+
+func TestHandler_PublicSurfaceAnonymous(t *testing.T) {
+	pkg := &store.PackageRegistration{
+		ID: "test-pkg", Title: "Test", Type: "surface", Source: "extension",
+		Enabled: true, Status: "active",
+		Manifest: map[string]any{
+			"surfaces": []any{
+				map[string]any{"path": "/submit", "access": "public", "title": "Submit"},
+			},
+		},
+	}
+	r := testRouter(t, pkg)
+	w := doGet(r, "/s/test-pkg/submit") // no auth
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200 for public surface, got %d", w.Code)
+	}
+}
+
+func TestHandler_MixedAccessPackage(t *testing.T) {
+	pkg := &store.PackageRegistration{
+		ID: "test-pkg", Title: "Test", Type: "surface", Source: "extension",
+		Enabled: true, Status: "active",
+		Manifest: map[string]any{
+			"surfaces": []any{
+				map[string]any{"path": "/submit", "access": "public", "title": "Submit"},
+				map[string]any{"path": "/dashboard", "access": "authenticated", "title": "Dashboard"},
+			},
+		},
+	}
+	r := testRouter(t, pkg)
+
+	// Public surface — anonymous OK
+	w1 := doGet(r, "/s/test-pkg/submit")
+	if w1.Code != http.StatusOK {
+		t.Errorf("public surface: expected 200, got %d", w1.Code)
+	}
+
+	// Authenticated surface — anonymous gets redirect
+	w2 := doGet(r, "/s/test-pkg/dashboard")
+	if w2.Code != http.StatusTemporaryRedirect {
+		t.Errorf("auth surface: expected 307, got %d", w2.Code)
+	}
+}
+
+func TestHandler_NonMatchingSubPath(t *testing.T) {
+	pkg := &store.PackageRegistration{
+		ID: "test-pkg", Title: "Test", Type: "surface", Source: "extension",
+		Enabled: true, Status: "active",
+		Manifest: map[string]any{
+			"surfaces": []any{
+				map[string]any{"path": "/", "access": "authenticated", "title": "Dashboard"},
+			},
+		},
+	}
+	r := testRouter(t, pkg)
+	w := doGet(r, "/s/test-pkg/nonexistent", "X-User-ID", "user-1")
+	if w.Code != http.StatusNotFound {
+		t.Errorf("expected 404, got %d", w.Code)
+	}
+}
+
+func TestHandler_EarlyAuthShortCircuit(t *testing.T) {
+	// All surfaces require auth → early short-circuit before surface matching
+	pkg := &store.PackageRegistration{
+		ID: "test-pkg", Title: "Test", Type: "surface", Source: "extension",
+		Enabled: true, Status: "active",
+		Manifest: map[string]any{
+			"surfaces": []any{
+				map[string]any{"path": "/", "access": "authenticated", "title": "Dashboard"},
+				map[string]any{"path": "/settings", "access": "admin", "title": "Settings"},
+			},
+		},
+	}
+	r := testRouter(t, pkg)
+
+	// Any path — should redirect before even matching surfaces
+	w := doGet(r, "/s/test-pkg/anything") // no auth
+	if w.Code != http.StatusTemporaryRedirect {
+		t.Errorf("expected 307 (early short-circuit), got %d", w.Code)
+	}
+	loc := w.Header().Get("Location")
+	if !strings.Contains(loc, "/login") {
+		t.Errorf("expected redirect to /login, got %s", loc)
+	}
+}

server/pages/pages_surface_match_test.go

@@ -0,0 +1,226 @@
+package pages
+
+import (
+	"testing"
+)
+
+// ── matchSurface tests ──────────────────────────────────────
+
+func TestMatchSurface_StaticRoot(t *testing.T) {
+	surfaces := []any{
+		map[string]any{"path": "/", "title": "Dashboard"},
+		map[string]any{"path": "/submit", "title": "Submit"},
+	}
+	s, params := matchSurface(surfaces, "/")
+	if s == nil {
+		t.Fatal("expected match for /")
+	}
+	if s["title"] != "Dashboard" {
+		t.Errorf("expected Dashboard, got %v", s["title"])
+	}
+	if len(params) != 0 {
+		t.Errorf("expected no params, got %v", params)
+	}
+}
+
+func TestMatchSurface_StaticPath(t *testing.T) {
+	surfaces := []any{
+		map[string]any{"path": "/", "title": "Dashboard"},
+		map[string]any{"path": "/submit", "title": "Submit"},
+		map[string]any{"path": "/monitor", "title": "Monitor"},
+	}
+	s, _ := matchSurface(surfaces, "/submit")
+	if s == nil {
+		t.Fatal("expected match for /submit")
+	}
+	if s["title"] != "Submit" {
+		t.Errorf("expected Submit, got %v", s["title"])
+	}
+}
+
+func TestMatchSurface_ParamPath(t *testing.T) {
+	surfaces := []any{
+		map[string]any{"path": "/", "title": "Dashboard"},
+		map[string]any{"path": "/:id", "title": "Detail"},
+	}
+	s, params := matchSurface(surfaces, "/abc123")
+	if s == nil {
+		t.Fatal("expected match for /:id")
+	}
+	if s["title"] != "Detail" {
+		t.Errorf("expected Detail, got %v", s["title"])
+	}
+	if params["id"] != "abc123" {
+		t.Errorf("expected id=abc123, got %v", params["id"])
+	}
+}
+
+func TestMatchSurface_MultiSegmentParam(t *testing.T) {
+	surfaces := []any{
+		map[string]any{"path": "/monitor", "title": "Monitor"},
+		map[string]any{"path": "/monitor/:id", "title": "Instance Detail"},
+	}
+	s, params := matchSurface(surfaces, "/monitor/inst-42")
+	if s == nil {
+		t.Fatal("expected match for /monitor/:id")
+	}
+	if s["title"] != "Instance Detail" {
+		t.Errorf("expected Instance Detail, got %v", s["title"])
+	}
+	if params["id"] != "inst-42" {
+		t.Errorf("expected id=inst-42, got %v", params["id"])
+	}
+}
+
+func TestMatchSurface_NoMatch(t *testing.T) {
+	surfaces := []any{
+		map[string]any{"path": "/", "title": "Dashboard"},
+		map[string]any{"path": "/submit", "title": "Submit"},
+	}
+	s, _ := matchSurface(surfaces, "/nonexistent/deep")
+	if s != nil {
+		t.Errorf("expected no match, got %v", s)
+	}
+}
+
+func TestMatchSurface_StaticPreferredOverParam(t *testing.T) {
+	surfaces := []any{
+		map[string]any{"path": "/:id", "title": "Detail"},
+		map[string]any{"path": "/new", "title": "New"},
+	}
+	s, params := matchSurface(surfaces, "/new")
+	if s == nil {
+		t.Fatal("expected match for /new")
+	}
+	if s["title"] != "New" {
+		t.Errorf("expected static match 'New', got %v", s["title"])
+	}
+	if len(params) != 0 {
+		t.Errorf("expected no params for static match, got %v", params)
+	}
+}
+
+func TestMatchSurface_EmptySurfaces(t *testing.T) {
+	s, _ := matchSurface([]any{}, "/")
+	if s != nil {
+		t.Errorf("expected no match for empty surfaces, got %v", s)
+	}
+}
+
+// ── splitPath tests ─────────────────────────────────────────
+
+func TestSplitPath(t *testing.T) {
+	tests := []struct {
+		input string
+		want  int
+	}{
+		{"/", 0},
+		{"/submit", 1},
+		{"/monitor/:id", 2},
+		{"/:id/edit", 2},
+	}
+	for _, tt := range tests {
+		parts := splitPath(tt.input)
+		if len(parts) != tt.want {
+			t.Errorf("splitPath(%q) = %d parts, want %d", tt.input, len(parts), tt.want)
+		}
+	}
+}
+
+// ── findNavSurface tests ────────────────────────────────────
+
+func TestFindNavSurface_ExplicitNav(t *testing.T) {
+	surfaces := []any{
+		map[string]any{"path": "/", "title": "Dashboard"},
+		map[string]any{"path": "/monitor", "title": "Monitor", "nav": true},
+	}
+	s := findNavSurface(surfaces)
+	if s == nil {
+		t.Fatal("expected nav surface")
+	}
+	if s["title"] != "Monitor" {
+		t.Errorf("expected Monitor, got %v", s["title"])
+	}
+}
+
+func TestFindNavSurface_FallbackRoot(t *testing.T) {
+	surfaces := []any{
+		map[string]any{"path": "/submit", "title": "Submit"},
+		map[string]any{"path": "/", "title": "Dashboard"},
+	}
+	s := findNavSurface(surfaces)
+	if s == nil {
+		t.Fatal("expected nav surface")
+	}
+	if s["title"] != "Dashboard" {
+		t.Errorf("expected Dashboard, got %v", s["title"])
+	}
+}
+
+func TestFindNavSurface_NoMatch(t *testing.T) {
+	surfaces := []any{
+		map[string]any{"path": "/submit", "title": "Submit"},
+		map[string]any{"path": "/admin", "title": "Admin"},
+	}
+	s := findNavSurface(surfaces)
+	if s != nil {
+		t.Errorf("expected nil, got %v", s)
+	}
+}
+
+// ── aggregateAccess tests ──────────────────────────────────
+
+func TestAggregateAccess_AllPublic(t *testing.T) {
+	surfaces := []any{
+		map[string]any{"path": "/", "access": "public"},
+		map[string]any{"path": "/submit", "access": "public"},
+	}
+	if got := aggregateAccess(surfaces); got != "public" {
+		t.Errorf("expected public, got %s", got)
+	}
+}
+
+func TestAggregateAccess_AllAuthenticated(t *testing.T) {
+	surfaces := []any{
+		map[string]any{"path": "/", "access": "authenticated"},
+		map[string]any{"path": "/admin", "access": "admin"},
+	}
+	if got := aggregateAccess(surfaces); got != "authenticated" {
+		t.Errorf("expected authenticated, got %s", got)
+	}
+}
+
+func TestAggregateAccess_Mixed(t *testing.T) {
+	surfaces := []any{
+		map[string]any{"path": "/submit", "access": "public"},
+		map[string]any{"path": "/dashboard", "access": "authenticated"},
+	}
+	if got := aggregateAccess(surfaces); got != "mixed" {
+		t.Errorf("expected mixed, got %s", got)
+	}
+}
+
+func TestAggregateAccess_DefaultAccess(t *testing.T) {
+	// No access field → defaults to "authenticated"
+	surfaces := []any{
+		map[string]any{"path": "/"},
+	}
+	if got := aggregateAccess(surfaces); got != "authenticated" {
+		t.Errorf("expected authenticated (default), got %s", got)
+	}
+}
+
+func TestAggregateAccess_SinglePublic(t *testing.T) {
+	surfaces := []any{
+		map[string]any{"path": "/", "access": "public"},
+	}
+	if got := aggregateAccess(surfaces); got != "public" {
+		t.Errorf("expected public, got %s", got)
+	}
+}
+
+// ── evaluateAccess tests ────────────────────────────────────
+// Note: evaluateAccess depends on gin.Context which is hard to unit test
+// without a full Gin setup. These are covered via handler integration tests.
+// The matchSurface + splitPath + findNavSurface functions above are the
+// pure-logic components that benefit most from unit testing.

server/pages/templates/base.html

@@ -29,7 +29,7 @@
     <style>
         body { margin: 0; background: var(--bg); color: var(--text); display: flex; flex-direction: column; height: 100vh; height: 100dvh; overflow: hidden; padding: env(safe-area-inset-top, 0) env(safe-area-inset-right, 0) env(safe-area-inset-bottom, 0) env(safe-area-inset-left, 0); }
         .surface { flex: 1; min-height: 0; overflow: hidden; }
-        .surface-inner { width: 100%; height: 100%; overflow: hidden; }
+        .surface-inner { width: 100%; height: 100%; overflow: hidden; display: flex; flex-direction: column; }
         .banner { flex-shrink: 0; }
     </style>
     <meta name="theme-color" content="#0e0e10" id="metaThemeColor">
@@ -122,6 +122,8 @@
         {{/* __PAGE_DATA__ and __USER__ removed in v0.37.19 — SDK boot
              populates sw.auth.user and sw.auth.policies from API. */}}
         {{if .Manifest}}window.__MANIFEST__ = {{.Manifest | toJSON}};{{end}}
+        {{if .SurfacePath}}window.__SURFACE_PATH__ = '{{.SurfacePath}}';{{end}}
+        {{if .SurfaceParams}}window.__SURFACE_PARAMS__ = {{.SurfaceParams | toJSON}};{{end}}
     </script>
 
     {{/* All surfaces use Preact SDK boot(). Legacy script includes removed.

server/pages/templates/surfaces/team-admin.html

@@ -6,7 +6,7 @@
 
 {{define "surface-team-admin"}}
 <div id="shell-topbar"></div>
-<div id="team-admin-mount" class="surface-team-admin" style="height:100%;overflow:hidden;">
+<div id="team-admin-mount" class="surface-team-admin" style="flex:1;min-height:0;overflow:hidden;">
     <div class="settings-placeholder" style="padding:40px;text-align:center;">Loading team admin&hellip;</div>
 </div>
 {{end}}

server/pages/templates/surfaces/welcome.html

@@ -4,7 +4,7 @@
 */}}
 
 {{define "surface-welcome"}}
-<div id="welcome-mount" style="display:flex;flex-direction:column;height:100%;"></div>
+<div id="welcome-mount" style="display:flex;flex-direction:column;flex:1;min-height:0;"></div>
 {{end}}
 
 {{define "scripts-welcome"}}

server/pages/templates/workflow-landing.html

@@ -154,7 +154,7 @@
         {{end}}
 
         <button class="wf-start-btn" id="startBtn" onclick="startWorkflow()">
-            {{if eq .Data.FirstStageMode "form"}}Fill Out Form{{else if eq .Data.FirstStageMode "review"}}Start Review{{else}}Start{{end}}
+            {{if eq .Data.FirstStageMode "form"}}Fill Out Form{{else}}Start{{end}}
         </button>
 
         {{if .Data.ResumeURL}}

server/pages/templates/workflow.html

@@ -178,7 +178,7 @@
     </div>
     {{end}}
 
-    <!-- Stage surface: form, review, delegated (custom surface), or automated -->
+    <!-- Stage surface: form, delegated (custom surface), or automated -->
 
     {{if .Data.AudienceMismatch}}
     <div class="wf-submitted">
@@ -195,11 +195,6 @@
     <div id="customSurfaceMount" style="flex:1;overflow-y:auto"></div>
     {{else if eq .Data.StageMode "form"}}
     <div class="wf-form" id="formArea"></div>
-    {{else if eq .Data.StageMode "review"}}
-    <div id="reviewArea" style="flex:1;overflow-y:auto;display:flex">
-        <div id="reviewDataPanel" style="flex:1;overflow-y:auto;border-right:1px solid var(--border)"></div>
-        <div id="reviewActionPanel" style="flex:1;overflow-y:auto;display:flex;flex-direction:column"></div>
-    </div>
     {{else if eq .Data.Status "completed"}}
     <div class="wf-form-success" style="flex:1;display:flex;flex-direction:column;justify-content:center">
         <h3>Completed</h3>
@@ -212,7 +207,7 @@
     {{end}}
 
     <div class="wf-session-info">
-        {{if .Data.SurfacePkgID}}Session:{{else if eq .Data.StageMode "form"}}Submitting as{{else if eq .Data.StageMode "review"}}Reviewing as{{else}}Session:{{end}} <strong>{{.Data.SessionName}}</strong>
+        {{if .Data.SurfacePkgID}}Session:{{else if eq .Data.StageMode "form"}}Submitting as{{else}}Session:{{end}} <strong>{{.Data.SessionName}}</strong>
     </div>
 </div>
 
@@ -542,116 +537,6 @@
         });
     }
 
-    // ── Review surface (structured review with side-by-side + comments) ──
-    if (STAGE_MODE === 'review') {
-        var dataPanel = document.getElementById('reviewDataPanel');
-        var actionPanel = document.getElementById('reviewActionPanel');
-        if (dataPanel && actionPanel) {
-            loadReviewSurface(dataPanel, actionPanel);
-        }
-    }
-
-    async function loadReviewSurface(dataPanel, actionPanel) {
-        dataPanel.innerHTML = '<div style="padding:24px;text-align:center;color:var(--text-3)">Loading\u2026</div>';
-
-        // Left panel: structured data card
-        var html = '<div style="padding:24px">';
-        html += '<h3 style="margin-bottom:16px">Collected Data</h3>';
-
-        try {
-            var resp = await fetch(BASE + '/api/v1/public/workflows/resume/' + API_ID, {
-                headers: { 'Content-Type': 'application/json' },
-            });
-            if (resp.ok) {
-                var status = await resp.json();
-                if (status.stage_data && typeof status.stage_data === 'object') {
-                    html += '<table style="width:100%;border-collapse:collapse">';
-                    for (var key in status.stage_data) {
-                        if (!status.stage_data.hasOwnProperty(key) || key.startsWith('_')) continue;
-                        html += '<tr style="border-bottom:1px solid var(--border)">';
-                        html += '<td style="padding:8px;font-weight:600;font-size:13px;width:30%;vertical-align:top">' + escHtml(key) + '</td>';
-                        var val = status.stage_data[key];
-                        var display = typeof val === 'object' ? JSON.stringify(val, null, 2) : String(val);
-                        html += '<td style="padding:8px;font-size:13px;white-space:pre-wrap">' + escHtml(display) + '</td>';
-                        html += '</tr>';
-                    }
-                    html += '</table>';
-                } else {
-                    html += '<p style="color:var(--text-3)">No data collected yet.</p>';
-                }
-            }
-        } catch(e) {
-            html += '<p style="color:var(--danger)">Failed to load review data.</p>';
-        }
-        html += '</div>';
-        dataPanel.innerHTML = html;
-
-        // Right panel: comment input + approve/reject buttons
-        var actHtml = '<div style="padding:24px;flex:1;display:flex;flex-direction:column">';
-        actHtml += '<h3 style="margin-bottom:16px">Review Actions</h3>';
-        actHtml += '<div style="margin-bottom:16px">';
-        actHtml += '<label style="font-size:13px;font-weight:600;display:block;margin-bottom:4px">Add Comment</label>';
-        actHtml += '<textarea id="reviewComment" rows="3" style="width:100%;padding:8px;font-size:14px;border:1px solid var(--border);border-radius:6px;background:var(--input-bg);color:var(--text);font-family:var(--font);resize:vertical" placeholder="Optional comment\u2026"></textarea>';
-        actHtml += '</div>';
-        actHtml += '<div style="display:flex;gap:8px">';
-        actHtml += '<button id="reviewAdvanceBtn" style="background:var(--accent);color:#fff;border:none;border-radius:8px;padding:10px 24px;font-weight:600;cursor:pointer;font-size:14px">Approve &amp; Advance</button>';
-        actHtml += '<button id="reviewRejectBtn" style="background:var(--danger,#e74c3c);color:#fff;border:none;border-radius:8px;padding:10px 24px;font-weight:600;cursor:pointer;font-size:14px">Reject</button>';
-        actHtml += '</div>';
-        actHtml += '<div style="font-size:12px;color:var(--text-3);margin-top:8px">Ctrl+Enter: Approve &middot; Ctrl+Shift+Enter: Reject</div>';
-        actHtml += '</div>';
-        actionPanel.innerHTML = actHtml;
-
-        // Keyboard shortcuts
-        document.addEventListener('keydown', function(e) {
-            if (e.ctrlKey && e.key === 'Enter') {
-                e.preventDefault();
-                if (e.shiftKey) {
-                    document.getElementById('reviewRejectBtn').click();
-                } else {
-                    document.getElementById('reviewAdvanceBtn').click();
-                }
-            }
-        });
-
-        document.getElementById('reviewAdvanceBtn').addEventListener('click', async function() {
-            this.disabled = true;
-            try {
-                var r = await fetch(BASE + '/api/v1/public/workflows/advance/' + API_ID, {
-                    method: 'POST', headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify({ data: {} }),
-                });
-                if (r.ok) {
-                    actionPanel.innerHTML = '<div style="padding:40px;text-align:center"><h3>Approved</h3><p style="color:var(--text-2)">Stage advanced.</p></div>';
-                    setTimeout(function() { window.location.reload(); }, 1500);
-                } else {
-                    var err = await r.json().catch(function() { return {}; });
-                    alert('Failed: ' + (err.error || 'unknown'));
-                    document.getElementById('reviewAdvanceBtn').disabled = false;
-                }
-            } catch(e) { alert('Error: ' + e.message); }
-        });
-
-        document.getElementById('reviewRejectBtn').addEventListener('click', async function() {
-            var comment = document.getElementById('reviewComment').value;
-            var reason = comment || prompt('Rejection reason:');
-            if (!reason) return;
-            this.disabled = true;
-            try {
-                var r = await fetch(BASE + '/api/v1/public/workflows/advance/' + API_ID, {
-                    method: 'POST', headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify({ data: { _action: 'reject', reason: reason } }),
-                });
-                if (r.ok) {
-                    actionPanel.innerHTML = '<div style="padding:40px;text-align:center"><h3>Rejected</h3><p style="color:var(--text-2)">Sent back for revision.</p></div>';
-                    setTimeout(function() { window.location.reload(); }, 1500);
-                } else {
-                    var err = await r.json().catch(function() { return {}; });
-                    alert('Failed: ' + (err.error || 'unknown'));
-                    document.getElementById('reviewRejectBtn').disabled = false;
-                }
-            } catch(e) { alert('Error: ' + e.message); }
-        });
-    }
 })();
 </script>
 </body>

server/sandbox/convert.go

@@ -0,0 +1,101 @@
+package sandbox
+
+import (
+	"fmt"
+
+	"go.starlark.net/starlark"
+)
+
+// GoToStarlark converts a Go value (typically from JSON unmarshal) to a
+// starlark.Value.  Handles nil, bool, int, int64, float64, string,
+// map[string]any, []any, and their interface{} equivalents.  Unknown
+// types are stringified.
+func GoToStarlark(v any) starlark.Value {
+	switch val := v.(type) {
+	case nil:
+		return starlark.None
+	case bool:
+		return starlark.Bool(val)
+	case int:
+		return starlark.MakeInt(val)
+	case int64:
+		return starlark.MakeInt64(val)
+	case float64:
+		if val == float64(int64(val)) {
+			return starlark.MakeInt64(int64(val))
+		}
+		return starlark.Float(val)
+	case string:
+		return starlark.String(val)
+	case map[string]any:
+		return MapToDict(val)
+	case []any:
+		elems := make([]starlark.Value, len(val))
+		for i, e := range val {
+			elems[i] = GoToStarlark(e)
+		}
+		return starlark.NewList(elems)
+	default:
+		return starlark.String(fmt.Sprintf("%v", val))
+	}
+}
+
+// StarlarkToGo converts a starlark.Value to a Go value suitable for
+// JSON serialization.  Handles None, Bool, Int, Float, String, List,
+// Dict, and Tuple.
+func StarlarkToGo(v starlark.Value) any {
+	switch val := v.(type) {
+	case starlark.NoneType:
+		return nil
+	case starlark.Bool:
+		return bool(val)
+	case starlark.Int:
+		if i, ok := val.Int64(); ok {
+			return i
+		}
+		return val.String()
+	case starlark.Float:
+		return float64(val)
+	case starlark.String:
+		return string(val)
+	case *starlark.List:
+		result := make([]any, val.Len())
+		for i := 0; i < val.Len(); i++ {
+			result[i] = StarlarkToGo(val.Index(i))
+		}
+		return result
+	case *starlark.Dict:
+		return DictToMap(val)
+	case starlark.Tuple:
+		result := make([]any, len(val))
+		for i, e := range val {
+			result[i] = StarlarkToGo(e)
+		}
+		return result
+	default:
+		return v.String()
+	}
+}
+
+// DictToMap converts a *starlark.Dict to map[string]any.
+// Non-string keys are silently skipped.
+func DictToMap(d *starlark.Dict) map[string]any {
+	result := make(map[string]any, d.Len())
+	for _, item := range d.Items() {
+		k, ok := starlark.AsString(item[0])
+		if !ok {
+			continue
+		}
+		result[k] = StarlarkToGo(item[1])
+	}
+	return result
+}
+
+// MapToDict converts a map[string]any to *starlark.Dict.
+func MapToDict(m map[string]any) *starlark.Dict {
+	d := starlark.NewDict(len(m))
+	for k, v := range m {
+		_ = d.SetKey(starlark.String(k), GoToStarlark(v))
+	}
+	return d
+}

server/sandbox/convert_test.go

@@ -0,0 +1,150 @@
+package sandbox
+
+import (
+	"testing"
+
+	"go.starlark.net/starlark"
+)
+
+func TestGoToStarlark_Primitives(t *testing.T) {
+	tests := []struct {
+		name string
+		in   any
+		want string // starlark.Value.String()
+	}{
+		{"nil", nil, "None"},
+		{"bool true", true, "True"},
+		{"bool false", false, "False"},
+		{"int", 42, "42"},
+		{"int64", int64(99), "99"},
+		{"float64 integer", float64(5), "5"},
+		{"float64 fractional", 3.14, "3.14"},
+		{"string", "hello", `"hello"`},
+		{"unknown type", struct{}{}, `"{}"`},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := GoToStarlark(tt.in)
+			if got.String() != tt.want {
+				t.Errorf("GoToStarlark(%v) = %s, want %s", tt.in, got.String(), tt.want)
+			}
+		})
+	}
+}
+
+func TestGoToStarlark_Containers(t *testing.T) {
+	// map[string]any
+	m := map[string]any{"a": 1.0, "b": "two"}
+	d := GoToStarlark(m)
+	if _, ok := d.(*starlark.Dict); !ok {
+		t.Fatalf("expected *starlark.Dict, got %T", d)
+	}
+
+	// []any
+	s := []any{1.0, "x", true}
+	l := GoToStarlark(s)
+	if list, ok := l.(*starlark.List); !ok || list.Len() != 3 {
+		t.Fatalf("expected *starlark.List len 3, got %T", l)
+	}
+
+}
+
+func TestStarlarkToGo_Primitives(t *testing.T) {
+	tests := []struct {
+		name string
+		in   starlark.Value
+		want any
+	}{
+		{"None", starlark.None, nil},
+		{"True", starlark.True, true},
+		{"Int", starlark.MakeInt(7), int64(7)},
+		{"Float", starlark.Float(2.5), 2.5},
+		{"String", starlark.String("hi"), "hi"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := StarlarkToGo(tt.in)
+			if got != tt.want {
+				t.Errorf("StarlarkToGo(%s) = %v (%T), want %v (%T)", tt.in, got, got, tt.want, tt.want)
+			}
+		})
+	}
+}
+
+func TestStarlarkToGo_Tuple(t *testing.T) {
+	tup := starlark.Tuple{starlark.MakeInt(1), starlark.String("a")}
+	got := StarlarkToGo(tup)
+	arr, ok := got.([]any)
+	if !ok || len(arr) != 2 {
+		t.Fatalf("expected []any len 2, got %T", got)
+	}
+	if arr[0] != int64(1) {
+		t.Errorf("arr[0] = %v, want 1", arr[0])
+	}
+}
+
+func TestRoundTrip(t *testing.T) {
+	original := map[string]any{
+		"name":   "test",
+		"count":  float64(42),
+		"active": true,
+		"tags":   []any{"a", "b"},
+		"nested": map[string]any{
+			"x": float64(1),
+		},
+	}
+
+	sv := GoToStarlark(original)
+	back := StarlarkToGo(sv)
+	m, ok := back.(map[string]any)
+	if !ok {
+		t.Fatalf("round-trip produced %T, want map[string]any", back)
+	}
+
+	if m["name"] != "test" {
+		t.Errorf("name = %v", m["name"])
+	}
+	if m["count"] != int64(42) {
+		t.Errorf("count = %v (%T)", m["count"], m["count"])
+	}
+	if m["active"] != true {
+		t.Errorf("active = %v", m["active"])
+	}
+	tags, ok := m["tags"].([]any)
+	if !ok || len(tags) != 2 {
+		t.Fatalf("tags = %v (%T)", m["tags"], m["tags"])
+	}
+	nested, ok := m["nested"].(map[string]any)
+	if !ok {
+		t.Fatalf("nested = %T", m["nested"])
+	}
+	if nested["x"] != int64(1) {
+		t.Errorf("nested.x = %v", nested["x"])
+	}
+}
+
+func TestDictToMap(t *testing.T) {
+	d := starlark.NewDict(2)
+	_ = d.SetKey(starlark.String("k"), starlark.String("v"))
+	_ = d.SetKey(starlark.MakeInt(1), starlark.String("skip")) // non-string key
+
+	m := DictToMap(d)
+	if len(m) != 1 {
+		t.Errorf("expected 1 entry (non-string key skipped), got %d", len(m))
+	}
+	if m["k"] != "v" {
+		t.Errorf("m[k] = %v", m["k"])
+	}
+}
+
+func TestMapToDict(t *testing.T) {
+	m := map[string]any{"a": "b", "n": float64(3)}
+	d := MapToDict(m)
+	if d.Len() != 2 {
+		t.Errorf("expected 2 entries, got %d", d.Len())
+	}
+	v, found, _ := d.Get(starlark.String("a"))
+	if !found || v.(starlark.String) != "b" {
+		t.Errorf("dict[a] = %v", v)
+	}
+}

server/sandbox/db_module.go

@@ -30,7 +30,10 @@ import (
 	"crypto/rand"
 	"database/sql"
 	"encoding/hex"
+	"encoding/json"
 	"fmt"
+	"math"
+	"sort"
 	"strings"
 
 	"go.starlark.net/starlark"
@@ -39,10 +42,11 @@ import (
 
 // DBModuleConfig holds configuration for a db module instance.
 type DBModuleConfig struct {
-	PackageID  string
+	PackageID   string
-	CanWrite   bool // true when db.write permission is granted
+	CanWrite    bool // true when db.write permission is granted
-	DB         *sql.DB
+	DB          *sql.DB
-	IsPostgres bool
+	IsPostgres  bool
+	HasPgvector bool // true when pgvector extension is available on Postgres
 }
 
 // allowedViews is the set of platform views extensions may query via db.view().
@@ -55,12 +59,13 @@ var allowedViews = map[string]bool{
 // prefixed with ext_{packageID}_. Write operations are guarded by CanWrite.
 func BuildDBModule(ctx context.Context, cfg DBModuleConfig) *starlarkstruct.Module {
 	fns := starlark.StringDict{
-		"query":       starlark.NewBuiltin("db.query", dbQuery(ctx, cfg)),
+		"query":         starlark.NewBuiltin("db.query", dbQuery(ctx, cfg)),
-		"count":       starlark.NewBuiltin("db.count", dbCount(ctx, cfg)),
+		"count":         starlark.NewBuiltin("db.count", dbCount(ctx, cfg)),
-		"aggregate":   starlark.NewBuiltin("db.aggregate", dbAggregate(ctx, cfg)),
+		"aggregate":     starlark.NewBuiltin("db.aggregate", dbAggregate(ctx, cfg)),
-		"query_batch": starlark.NewBuiltin("db.query_batch", dbQueryBatch(ctx, cfg)),
+		"query_batch":   starlark.NewBuiltin("db.query_batch", dbQueryBatch(ctx, cfg)),
-		"view":        starlark.NewBuiltin("db.view", dbView(ctx, cfg)),
+		"query_similar": starlark.NewBuiltin("db.query_similar", dbQuerySimilar(ctx, cfg)),
-		"list_tables": starlark.NewBuiltin("db.list_tables", dbListTables(ctx, cfg)),
+		"view":          starlark.NewBuiltin("db.view", dbView(ctx, cfg)),
+		"list_tables":   starlark.NewBuiltin("db.list_tables", dbListTables(ctx, cfg)),
 	}
 
 	if cfg.CanWrite {
@@ -160,6 +165,20 @@ func starlarkToGoValue(v starlark.Value) (any, error) {
 		return bool(val), nil
 	case starlark.NoneType:
 		return nil, nil
+	case *starlark.List:
+		goSlice := make([]any, val.Len())
+		for i := 0; i < val.Len(); i++ {
+			elem, err := starlarkToGoValue(val.Index(i))
+			if err != nil {
+				return nil, fmt.Errorf("list[%d]: %w", i, err)
+			}
+			goSlice[i] = elem
+		}
+		b, err := json.Marshal(goSlice)
+		if err != nil {
+			return nil, fmt.Errorf("list marshal: %w", err)
+		}
+		return string(b), nil
 	default:
 		return nil, fmt.Errorf("unsupported type %s", v.Type())
 	}
@@ -926,3 +945,271 @@ func dbDelete(ctx context.Context, cfg DBModuleConfig) func(*starlark.Thread, *s
 		return starlark.True, nil
 	}
 }
+
+// ── Vector Similarity ─────────────────────────
+
+// starlarkListToFloats converts a Starlark list to a Go float64 slice.
+func starlarkListToFloats(list *starlark.List) ([]float64, error) {
+	n := list.Len()
+	if n == 0 {
+		return nil, fmt.Errorf("vector must not be empty")
+	}
+	out := make([]float64, n)
+	for i := 0; i < n; i++ {
+		switch v := list.Index(i).(type) {
+		case starlark.Float:
+			out[i] = float64(v)
+		case starlark.Int:
+			i64, _ := v.Int64()
+			out[i] = float64(i64)
+		default:
+			return nil, fmt.Errorf("vector[%d]: expected number, got %s", i, list.Index(i).Type())
+		}
+	}
+	return out, nil
+}
+
+// floatsToVectorString serializes a float64 slice as a JSON array string.
+// e.g. [0.1, 0.2, 0.3] → "[0.1,0.2,0.3]"
+func floatsToVectorString(v []float64) string {
+	b, _ := json.Marshal(v)
+	return string(b)
+}
+
+// parseVectorJSON parses a JSON array string (or pgvector text) into float64 slice.
+func parseVectorJSON(s string) ([]float64, error) {
+	var out []float64
+	if err := json.Unmarshal([]byte(s), &out); err != nil {
+		return nil, fmt.Errorf("parse vector: %w", err)
+	}
+	return out, nil
+}
+
+// cosineDistance computes cosine distance between two vectors.
+// Returns 0.0 for identical vectors, 1.0 for orthogonal, 2.0 for opposite.
+func cosineDistance(a, b []float64) float64 {
+	if len(a) != len(b) || len(a) == 0 {
+		return 1.0
+	}
+	var dot, normA, normB float64
+	for i := range a {
+		dot += a[i] * b[i]
+		normA += a[i] * a[i]
+		normB += b[i] * b[i]
+	}
+	if normA == 0 || normB == 0 {
+		return 1.0
+	}
+	return 1.0 - (dot / (math.Sqrt(normA) * math.Sqrt(normB)))
+}
+
+// dbQuerySimilar implements db.query_similar(table, column, vector=[], limit=10, filters=None, metric="cosine").
+// Returns rows ordered by distance with an injected _distance float.
+//
+// Three dispatch paths:
+//   - pgvector: native <=> operator with HNSW index
+//   - fallback: fetch rows, compute cosine distance in Go, sort, return top N
+func dbQuerySimilar(ctx context.Context, cfg DBModuleConfig) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(thread *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var table, column string
+		var vectorVal *starlark.List
+		var limit starlark.Int = starlark.MakeInt(10)
+		var filters starlark.Value = starlark.None
+		var metric starlark.String = "cosine"
+
+		if err := starlark.UnpackArgs(b.Name(), args, kwargs,
+			"table", &table,
+			"column", &column,
+			"vector", &vectorVal,
+			"limit?", &limit,
+			"filters?", &filters,
+			"metric?", &metric,
+		); err != nil {
+			return nil, err
+		}
+
+		if string(metric) != "cosine" {
+			return nil, fmt.Errorf("db.query_similar: unsupported metric %q (only \"cosine\" is supported)", string(metric))
+		}
+
+		queryVec, err := starlarkListToFloats(vectorVal)
+		if err != nil {
+			return nil, fmt.Errorf("db.query_similar: %w", err)
+		}
+
+		lim, ok := limit.Int64()
+		if !ok || lim < 1 {
+			lim = 10
+		}
+		if lim > 100 {
+			lim = 100
+		}
+
+		if strings.ContainsAny(column, " \t\n\"';-") {
+			return nil, fmt.Errorf("db.query_similar: invalid column name %q", column)
+		}
+
+		physTable, err := cfg.physicalTable(table)
+		if err != nil {
+			return nil, err
+		}
+
+		if cfg.HasPgvector {
+			return querySimilarPgvector(ctx, cfg, physTable, column, queryVec, int(lim), filters)
+		}
+		return querySimilarFallback(ctx, cfg, physTable, column, queryVec, int(lim), filters)
+	}
+}
+
+// querySimilarPgvector uses the native pgvector <=> operator.
+func querySimilarPgvector(ctx context.Context, cfg DBModuleConfig, physTable, column string, queryVec []float64, limit int, filters starlark.Value) (starlark.Value, error) {
+	vecStr := floatsToVectorString(queryVec)
+
+	whereClause, whereArgs, err := cfg.starlarkFiltersToSQL(filters, 1)
+	if err != nil {
+		return nil, err
+	}
+
+	nextIdx := len(whereArgs) + 1
+	vecPH := cfg.ph(nextIdx)
+	limitPH := cfg.ph(nextIdx + 1)
+
+	query := fmt.Sprintf("SELECT *, (%s <=> %s::vector) AS _distance FROM %s",
+		column, vecPH, physTable)
+	if whereClause != "" {
+		query += " " + whereClause
+	}
+	query += fmt.Sprintf(" ORDER BY %s <=> %s::vector LIMIT %s", column, vecPH, limitPH)
+
+	allArgs := append(whereArgs, vecStr, limit)
+
+	rows, err := cfg.DB.QueryContext(ctx, query, allArgs...)
+	if err != nil {
+		return nil, fmt.Errorf("db.query_similar: %w", err)
+	}
+	defer rows.Close()
+
+	return rowsToStarlark(rows)
+}
+
+// querySimilarFallback fetches rows and computes cosine distance in Go.
+// Used for SQLite (TEXT) and Postgres without pgvector (JSONB).
+func querySimilarFallback(ctx context.Context, cfg DBModuleConfig, physTable, column string, queryVec []float64, limit int, filters starlark.Value) (starlark.Value, error) {
+	whereClause, whereArgs, err := cfg.starlarkFiltersToSQL(filters, 1)
+	if err != nil {
+		return nil, err
+	}
+
+	// Fetch up to 1000 rows for distance computation.
+	fetchLimit := limit * 10
+	if fetchLimit > 1000 {
+		fetchLimit = 1000
+	}
+	if fetchLimit < limit {
+		fetchLimit = limit
+	}
+
+	limitPH := cfg.ph(len(whereArgs) + 1)
+	query := fmt.Sprintf("SELECT * FROM %s", physTable)
+	if whereClause != "" {
+		query += " " + whereClause
+	}
+	query += " LIMIT " + limitPH
+	allArgs := append(whereArgs, fetchLimit)
+
+	rows, err := cfg.DB.QueryContext(ctx, query, allArgs...)
+	if err != nil {
+		return nil, fmt.Errorf("db.query_similar: %w", err)
+	}
+	defer rows.Close()
+
+	cols, err := rows.Columns()
+	if err != nil {
+		return nil, err
+	}
+
+	// Find the vector column index.
+	vecColIdx := -1
+	for i, c := range cols {
+		if c == column {
+			vecColIdx = i
+			break
+		}
+	}
+	if vecColIdx == -1 {
+		return nil, fmt.Errorf("db.query_similar: column %q not found in table", column)
+	}
+
+	type scoredRow struct {
+		vals     []any
+		distance float64
+	}
+	var scored []scoredRow
+
+	for rows.Next() {
+		vals := make([]any, len(cols))
+		ptrs := make([]any, len(cols))
+		for i := range vals {
+			ptrs[i] = &vals[i]
+		}
+		if err := rows.Scan(ptrs...); err != nil {
+			return nil, err
+		}
+
+		// Parse the vector column value.
+		var vecStr string
+		switch v := vals[vecColIdx].(type) {
+		case string:
+			vecStr = v
+		case []byte:
+			vecStr = string(v)
+		default:
+			continue // skip rows with unparseable vectors
+		}
+
+		rowVec, err := parseVectorJSON(vecStr)
+		if err != nil {
+			continue // skip malformed vectors
+		}
+
+		dist := cosineDistance(queryVec, rowVec)
+		scored = append(scored, scoredRow{vals: vals, distance: dist})
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+
+	// Sort by distance ascending.
+	sort.Slice(scored, func(i, j int) bool {
+		return scored[i].distance < scored[j].distance
+	})
+
+	// Take top N and build Starlark dicts.
+	if len(scored) > limit {
+		scored = scored[:limit]
+	}
+
+	var result []starlark.Value
+	for _, sr := range scored {
+		d := starlark.NewDict(len(cols) + 1)
+		for i, col := range cols {
+			sv, err := goToStarlark(sr.vals[i])
+			if err != nil {
+				return nil, fmt.Errorf("column %q: %w", col, err)
+			}
+			if err := d.SetKey(starlark.String(col), sv); err != nil {
+				return nil, err
+			}
+		}
+		// Inject _distance.
+		if err := d.SetKey(starlark.String("_distance"), starlark.Float(sr.distance)); err != nil {
+			return nil, err
+		}
+		result = append(result, d)
+	}
+
+	if result == nil {
+		result = []starlark.Value{}
+	}
+	return starlark.NewList(result), nil
+}

server/sandbox/db_module_test.go

@@ -3,6 +3,7 @@ package sandbox
 import (
 	"context"
 	"database/sql"
+	"math"
 	"strings"
 	"testing"
 
@@ -684,3 +685,252 @@ func TestDBQueryBatch_MissingTable(t *testing.T) {
 	}
 }
 
+// ── starlarkToGoValue list ──────────────────
+
+func TestStarlarkToGoValue_List(t *testing.T) {
+	list := starlark.NewList([]starlark.Value{
+		starlark.Float(0.1), starlark.Float(0.2), starlark.Float(0.3),
+	})
+	got, err := starlarkToGoValue(list)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	s, ok := got.(string)
+	if !ok {
+		t.Fatalf("expected string, got %T", got)
+	}
+	if s != "[0.1,0.2,0.3]" {
+		t.Errorf("got %q, want %q", s, "[0.1,0.2,0.3]")
+	}
+}
+
+// ── cosineDistance ───────────────────────────
+
+func TestCosineDistance(t *testing.T) {
+	// Identical vectors → distance 0
+	d := cosineDistance([]float64{1, 0, 0}, []float64{1, 0, 0})
+	if math.Abs(d) > 1e-9 {
+		t.Errorf("identical vectors: got %f, want 0", d)
+	}
+
+	// Orthogonal vectors → distance 1
+	d = cosineDistance([]float64{1, 0}, []float64{0, 1})
+	if math.Abs(d-1.0) > 1e-9 {
+		t.Errorf("orthogonal vectors: got %f, want 1", d)
+	}
+
+	// Opposite vectors → distance 2
+	d = cosineDistance([]float64{1, 0}, []float64{-1, 0})
+	if math.Abs(d-2.0) > 1e-9 {
+		t.Errorf("opposite vectors: got %f, want 2", d)
+	}
+
+	// Empty/mismatched → distance 1
+	d = cosineDistance([]float64{}, []float64{})
+	if d != 1.0 {
+		t.Errorf("empty vectors: got %f, want 1", d)
+	}
+	d = cosineDistance([]float64{1}, []float64{1, 2})
+	if d != 1.0 {
+		t.Errorf("mismatched vectors: got %f, want 1", d)
+	}
+}
+
+// ── vector helper: newVectorTestDB ──────────
+
+func newVectorTestDB(t *testing.T) (*sql.DB, DBModuleConfig) {
+	t.Helper()
+	db, err := sql.Open("sqlite", ":memory:")
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	t.Cleanup(func() { db.Close() })
+
+	// Create a table with a TEXT column for vector storage (SQLite fallback).
+	_, err = db.Exec(`CREATE TABLE ext_test_ext_embeddings (
+		id         TEXT PRIMARY KEY,
+		embedding  TEXT,
+		category   TEXT,
+		created_at TEXT DEFAULT (datetime('now'))
+	)`)
+	if err != nil {
+		t.Fatalf("create test table: %v", err)
+	}
+
+	cfg := DBModuleConfig{
+		PackageID:   "test-ext",
+		CanWrite:    true,
+		DB:          db,
+		IsPostgres:  false,
+		HasPgvector: false,
+	}
+	return db, cfg
+}
+
+// ── db.query_similar ────────────────────────
+
+func TestDBQuerySimilar_Basic(t *testing.T) {
+	db, cfg := newVectorTestDB(t)
+
+	// Insert 5 rows with known vectors.
+	db.Exec(`INSERT INTO ext_test_ext_embeddings (id, embedding, category) VALUES ('a', '[1,0,0]', 'x')`)
+	db.Exec(`INSERT INTO ext_test_ext_embeddings (id, embedding, category) VALUES ('b', '[0,1,0]', 'x')`)
+	db.Exec(`INSERT INTO ext_test_ext_embeddings (id, embedding, category) VALUES ('c', '[0,0,1]', 'x')`)
+	db.Exec(`INSERT INTO ext_test_ext_embeddings (id, embedding, category) VALUES ('d', '[0.9,0.1,0]', 'x')`)
+	db.Exec(`INSERT INTO ext_test_ext_embeddings (id, embedding, category) VALUES ('e', '[0,0.9,0.1]', 'x')`)
+
+	// Query similar to [1,0,0] — should return 'a' first (identical), then 'd' (close).
+	result, err := execScript(t, cfg, `
+rows = db.query_similar("embeddings", "embedding", vector=[1.0, 0.0, 0.0], limit=3)
+`)
+	if err != nil {
+		t.Fatalf("script error: %v", err)
+	}
+
+	rows, ok := result.Globals["rows"].(*starlark.List)
+	if !ok {
+		t.Fatalf("rows is %T, want *starlark.List", result.Globals["rows"])
+	}
+	if rows.Len() != 3 {
+		t.Fatalf("got %d rows, want 3", rows.Len())
+	}
+
+	// First row should be 'a' (distance ≈ 0).
+	first := rows.Index(0).(*starlark.Dict)
+	idVal, _, _ := first.Get(starlark.String("id"))
+	if string(idVal.(starlark.String)) != "a" {
+		t.Errorf("first row id = %s, want 'a'", idVal)
+	}
+
+	// Verify _distance is present and near 0.
+	distVal, _, _ := first.Get(starlark.String("_distance"))
+	dist := float64(distVal.(starlark.Float))
+	if dist > 0.01 {
+		t.Errorf("first row _distance = %f, want ≈ 0", dist)
+	}
+
+	// Second row should be 'd' (closest after identical).
+	second := rows.Index(1).(*starlark.Dict)
+	idVal2, _, _ := second.Get(starlark.String("id"))
+	if string(idVal2.(starlark.String)) != "d" {
+		t.Errorf("second row id = %s, want 'd'", idVal2)
+	}
+}
+
+func TestDBQuerySimilar_WithFilters(t *testing.T) {
+	db, cfg := newVectorTestDB(t)
+
+	db.Exec(`INSERT INTO ext_test_ext_embeddings (id, embedding, category) VALUES ('a', '[1,0,0]', 'alpha')`)
+	db.Exec(`INSERT INTO ext_test_ext_embeddings (id, embedding, category) VALUES ('b', '[0.9,0.1,0]', 'beta')`)
+	db.Exec(`INSERT INTO ext_test_ext_embeddings (id, embedding, category) VALUES ('c', '[0,1,0]', 'alpha')`)
+
+	// Filter to alpha only — should exclude 'b' even though it's close.
+	result, err := execScript(t, cfg, `
+rows = db.query_similar("embeddings", "embedding", vector=[1.0, 0.0, 0.0], filters={"category": "alpha"})
+`)
+	if err != nil {
+		t.Fatalf("script error: %v", err)
+	}
+
+	rows := result.Globals["rows"].(*starlark.List)
+	for i := 0; i < rows.Len(); i++ {
+		d := rows.Index(i).(*starlark.Dict)
+		idVal, _, _ := d.Get(starlark.String("id"))
+		if string(idVal.(starlark.String)) == "b" {
+			t.Error("filtered query should not include row 'b' (category=beta)")
+		}
+	}
+}
+
+func TestDBQuerySimilar_EmptyTable(t *testing.T) {
+	_, cfg := newVectorTestDB(t)
+
+	result, err := execScript(t, cfg, `
+rows = db.query_similar("embeddings", "embedding", vector=[1.0, 0.0, 0.0])
+`)
+	if err != nil {
+		t.Fatalf("script error: %v", err)
+	}
+	rows := result.Globals["rows"].(*starlark.List)
+	if rows.Len() != 0 {
+		t.Errorf("expected 0 rows for empty table, got %d", rows.Len())
+	}
+}
+
+func TestDBQuerySimilar_InvalidMetric(t *testing.T) {
+	_, cfg := newVectorTestDB(t)
+
+	_, err := execScript(t, cfg, `
+rows = db.query_similar("embeddings", "embedding", vector=[1.0], metric="l2")
+`)
+	if err == nil {
+		t.Fatal("expected error for unsupported metric")
+	}
+	if !strings.Contains(err.Error(), "unsupported metric") {
+		t.Errorf("unexpected error: %v", err)
+	}
+}
+
+func TestDBQuerySimilar_LimitCap(t *testing.T) {
+	db, cfg := newVectorTestDB(t)
+
+	// Insert 5 rows
+	for i := 0; i < 5; i++ {
+		db.Exec(`INSERT INTO ext_test_ext_embeddings (id, embedding) VALUES (?, '[1,0,0]')`,
+			generateID())
+	}
+
+	result, err := execScript(t, cfg, `
+rows = db.query_similar("embeddings", "embedding", vector=[1.0, 0.0, 0.0], limit=2)
+`)
+	if err != nil {
+		t.Fatalf("script error: %v", err)
+	}
+	rows := result.Globals["rows"].(*starlark.List)
+	if rows.Len() != 2 {
+		t.Errorf("expected 2 rows with limit=2, got %d", rows.Len())
+	}
+}
+
+func TestDBInsert_VectorColumn(t *testing.T) {
+	db, cfg := newVectorTestDB(t)
+
+	_, err := execScript(t, cfg, `
+row = db.insert("embeddings", {"embedding": [0.1, 0.2, 0.3], "category": "test"})
+`)
+	if err != nil {
+		t.Fatalf("script error: %v", err)
+	}
+
+	// Verify the stored value is valid JSON.
+	var stored string
+	db.QueryRow(`SELECT embedding FROM ext_test_ext_embeddings WHERE category = 'test'`).Scan(&stored)
+	if stored != "[0.1,0.2,0.3]" {
+		t.Errorf("stored vector = %q, want %q", stored, "[0.1,0.2,0.3]")
+	}
+}
+
+func TestDBQuerySimilar_InsertThenQuery(t *testing.T) {
+	_, cfg := newVectorTestDB(t)
+
+	// Full round-trip: insert via db.insert, then query_similar.
+	result, err := execScript(t, cfg, `
+db.insert("embeddings", {"embedding": [1.0, 0.0, 0.0], "category": "a"})
+db.insert("embeddings", {"embedding": [0.0, 1.0, 0.0], "category": "b"})
+rows = db.query_similar("embeddings", "embedding", vector=[1.0, 0.0, 0.0], limit=1)
+`)
+	if err != nil {
+		t.Fatalf("script error: %v", err)
+	}
+
+	rows := result.Globals["rows"].(*starlark.List)
+	if rows.Len() != 1 {
+		t.Fatalf("expected 1 row, got %d", rows.Len())
+	}
+	first := rows.Index(0).(*starlark.Dict)
+	catVal, _, _ := first.Get(starlark.String("category"))
+	if string(catVal.(starlark.String)) != "a" {
+		t.Errorf("closest match should be category=a, got %s", catVal)
+	}
+}
+

server/sandbox/files_module.go

@@ -0,0 +1,408 @@
+// Package sandbox — files_module.go
+//
+// Permissions: files.read, files.write
+//
+// Starlark API:
+//   files.put(name, content, content_type="application/octet-stream", metadata={})
+//   result = files.get(name)         → dict or None
+//   meta   = files.meta(name)        → dict or None
+//   entries = files.list(prefix="", limit=100)
+//   files.delete(name)
+//   files.delete_prefix(prefix)
+//   exists = files.exists(name)
+//
+// Bridges the ObjectStore (PVC/S3) into Starlark. All keys are scoped
+// to ext/{packageID}/ — extensions cannot access each other's files.
+// Metadata is stored as companion JSON at ext/{packageID}/_meta/{name}.
+package sandbox
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"strconv"
+	"strings"
+	"unicode"
+
+	"go.starlark.net/starlark"
+	"go.starlark.net/starlarkstruct"
+
+	"armature/storage"
+)
+
+const (
+	filesDefaultMaxSize = 50 * 1024 * 1024 // 50 MB
+	filesDefaultLimit   = 100
+	filesMaxNameLen     = 512
+	filesMetaPrefix     = "_meta/"
+)
+
+// FilesModuleConfig holds the configuration for the files module.
+type FilesModuleConfig struct {
+	PackageID string
+	CanWrite  bool
+	Store     storage.ObjectStore
+}
+
+// BuildFilesModule creates the "files" module.
+func BuildFilesModule(ctx context.Context, cfg FilesModuleConfig) *starlarkstruct.Module {
+	fns := starlark.StringDict{
+		"get":    starlark.NewBuiltin("files.get", filesGet(ctx, cfg)),
+		"meta":   starlark.NewBuiltin("files.meta", filesMeta(ctx, cfg)),
+		"list":   starlark.NewBuiltin("files.list", filesList(ctx, cfg)),
+		"exists": starlark.NewBuiltin("files.exists", filesExists(ctx, cfg)),
+	}
+
+	if cfg.CanWrite {
+		fns["put"] = starlark.NewBuiltin("files.put", filesPut(ctx, cfg))
+		fns["delete"] = starlark.NewBuiltin("files.delete", filesDelete(ctx, cfg))
+		fns["delete_prefix"] = starlark.NewBuiltin("files.delete_prefix", filesDeletePrefix(ctx, cfg))
+	}
+
+	return MakeModule("files", fns)
+}
+
+// ── Builtins ──────────────────────────────────
+
+func filesPut(ctx context.Context, cfg FilesModuleConfig) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(thread *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var name string
+		var content starlark.Value
+		var contentType string = "application/octet-stream"
+		var metadata *starlark.Dict
+
+		if err := starlark.UnpackArgs(b.Name(), args, kwargs,
+			"name", &name,
+			"content", &content,
+			"content_type?", &contentType,
+			"metadata?", &metadata,
+		); err != nil {
+			return nil, err
+		}
+
+		if err := validateFileName(name); err != nil {
+			return nil, fmt.Errorf("files.put: %w", err)
+		}
+
+		// Extract raw bytes from content (accept String or Bytes).
+		var raw []byte
+		switch v := content.(type) {
+		case starlark.String:
+			raw = []byte(string(v))
+		case starlark.Bytes:
+			raw = []byte(v)
+		default:
+			return nil, fmt.Errorf("files.put: content must be string or bytes, got %s", content.Type())
+		}
+
+		// Enforce size limit.
+		maxSize := filesMaxSize()
+		if int64(len(raw)) > maxSize {
+			return nil, fmt.Errorf("files.put: content size %d exceeds limit %d", len(raw), maxSize)
+		}
+
+		// Write main object.
+		key := cfg.scopedKey(name)
+		if err := cfg.Store.Put(ctx, key, bytes.NewReader(raw), int64(len(raw)), contentType); err != nil {
+			return nil, fmt.Errorf("files.put: %w", err)
+		}
+
+		// Write metadata companion if provided.
+		if metadata != nil && metadata.Len() > 0 {
+			metaMap, err := starlarkDictToMap(metadata)
+			if err != nil {
+				return nil, fmt.Errorf("files.put: metadata: %w", err)
+			}
+			metaJSON, err := json.Marshal(metaMap)
+			if err != nil {
+				return nil, fmt.Errorf("files.put: marshal metadata: %w", err)
+			}
+			metaKey := cfg.metaKey(name)
+			if err := cfg.Store.Put(ctx, metaKey, bytes.NewReader(metaJSON), int64(len(metaJSON)), "application/json"); err != nil {
+				return nil, fmt.Errorf("files.put: write metadata: %w", err)
+			}
+		}
+
+		return starlark.True, nil
+	}
+}
+
+func filesGet(ctx context.Context, cfg FilesModuleConfig) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(thread *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var name string
+		if err := starlark.UnpackPositionalArgs(b.Name(), args, kwargs, 1, &name); err != nil {
+			return nil, err
+		}
+
+		if err := validateFileName(name); err != nil {
+			return nil, fmt.Errorf("files.get: %w", err)
+		}
+
+		key := cfg.scopedKey(name)
+		rc, size, ct, err := cfg.Store.Get(ctx, key)
+		if err == storage.ErrNotFound {
+			return starlark.None, nil
+		}
+		if err != nil {
+			return nil, fmt.Errorf("files.get: %w", err)
+		}
+		defer rc.Close()
+
+		data, err := io.ReadAll(rc)
+		if err != nil {
+			return nil, fmt.Errorf("files.get: read: %w", err)
+		}
+
+		// Load metadata companion.
+		metaDict := starlark.NewDict(0)
+		metaKey := cfg.metaKey(name)
+		if metaRC, _, _, metaErr := cfg.Store.Get(ctx, metaKey); metaErr == nil {
+			metaBytes, _ := io.ReadAll(metaRC)
+			metaRC.Close()
+			var m map[string]any
+			if json.Unmarshal(metaBytes, &m) == nil {
+				metaDict = MapToDict(m)
+			}
+		}
+
+		result := starlark.NewDict(4)
+		result.SetKey(starlark.String("content"), starlark.Bytes(data))
+		result.SetKey(starlark.String("content_type"), starlark.String(ct))
+		result.SetKey(starlark.String("size"), starlark.MakeInt64(size))
+		result.SetKey(starlark.String("metadata"), metaDict)
+
+		return result, nil
+	}
+}
+
+func filesMeta(ctx context.Context, cfg FilesModuleConfig) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(thread *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var name string
+		if err := starlark.UnpackPositionalArgs(b.Name(), args, kwargs, 1, &name); err != nil {
+			return nil, err
+		}
+
+		if err := validateFileName(name); err != nil {
+			return nil, fmt.Errorf("files.meta: %w", err)
+		}
+
+		// Check the main object exists.
+		key := cfg.scopedKey(name)
+		exists, err := cfg.Store.Exists(ctx, key)
+		if err != nil {
+			return nil, fmt.Errorf("files.meta: %w", err)
+		}
+		if !exists {
+			return starlark.None, nil
+		}
+
+		// Load metadata companion.
+		metaDict := starlark.NewDict(0)
+		metaKey := cfg.metaKey(name)
+		if metaRC, _, _, metaErr := cfg.Store.Get(ctx, metaKey); metaErr == nil {
+			metaBytes, _ := io.ReadAll(metaRC)
+			metaRC.Close()
+			var m map[string]any
+			if json.Unmarshal(metaBytes, &m) == nil {
+				metaDict = MapToDict(m)
+			}
+		}
+
+		return metaDict, nil
+	}
+}
+
+func filesList(ctx context.Context, cfg FilesModuleConfig) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(thread *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var prefix string
+		var limit int = filesDefaultLimit
+
+		if err := starlark.UnpackArgs(b.Name(), args, kwargs,
+			"prefix?", &prefix,
+			"limit?", &limit,
+		); err != nil {
+			return nil, err
+		}
+
+		if limit <= 0 || limit > 1000 {
+			limit = filesDefaultLimit
+		}
+
+		// Build the full scoped prefix.
+		scopedPrefix := cfg.scopedPrefix()
+		if prefix != "" {
+			// Validate the user-supplied prefix portion.
+			if strings.Contains(prefix, "..") {
+				return nil, fmt.Errorf("files.list: path traversal not allowed")
+			}
+			scopedPrefix += prefix
+		}
+
+		// Request more than limit to account for _meta/ entries we'll filter out.
+		entries, err := cfg.Store.List(ctx, scopedPrefix, limit*2)
+		if err != nil {
+			return nil, fmt.Errorf("files.list: %w", err)
+		}
+
+		// Filter out _meta/ companions and strip the package prefix.
+		pkgPrefix := cfg.scopedPrefix()
+		var results []starlark.Value
+		for _, e := range entries {
+			// Strip package prefix to get the extension-relative key.
+			relKey := strings.TrimPrefix(e.Key, pkgPrefix)
+
+			// Skip metadata companions.
+			if strings.HasPrefix(relKey, filesMetaPrefix) {
+				continue
+			}
+
+			d := starlark.NewDict(3)
+			d.SetKey(starlark.String("name"), starlark.String(relKey))
+			d.SetKey(starlark.String("size"), starlark.MakeInt64(e.Size))
+			d.SetKey(starlark.String("content_type"), starlark.String(e.ContentType))
+			results = append(results, d)
+
+			if len(results) >= limit {
+				break
+			}
+		}
+
+		return starlark.NewList(results), nil
+	}
+}
+
+func filesDelete(ctx context.Context, cfg FilesModuleConfig) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(thread *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var name string
+		if err := starlark.UnpackPositionalArgs(b.Name(), args, kwargs, 1, &name); err != nil {
+			return nil, err
+		}
+
+		if err := validateFileName(name); err != nil {
+			return nil, fmt.Errorf("files.delete: %w", err)
+		}
+
+		// Delete main object.
+		key := cfg.scopedKey(name)
+		if err := cfg.Store.Delete(ctx, key); err != nil {
+			return nil, fmt.Errorf("files.delete: %w", err)
+		}
+
+		// Delete metadata companion (best-effort, idempotent).
+		metaKey := cfg.metaKey(name)
+		cfg.Store.Delete(ctx, metaKey)
+
+		return starlark.True, nil
+	}
+}
+
+func filesDeletePrefix(ctx context.Context, cfg FilesModuleConfig) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(thread *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var prefix string
+		if err := starlark.UnpackPositionalArgs(b.Name(), args, kwargs, 1, &prefix); err != nil {
+			return nil, err
+		}
+
+		if strings.Contains(prefix, "..") {
+			return nil, fmt.Errorf("files.delete_prefix: path traversal not allowed")
+		}
+
+		scopedPrefix := cfg.scopedPrefix() + prefix
+		if err := cfg.Store.DeletePrefix(ctx, scopedPrefix); err != nil {
+			return nil, fmt.Errorf("files.delete_prefix: %w", err)
+		}
+
+		// Also delete metadata companions under this prefix.
+		metaPrefix := cfg.scopedPrefix() + filesMetaPrefix + prefix
+		cfg.Store.DeletePrefix(ctx, metaPrefix)
+
+		return starlark.True, nil
+	}
+}
+
+func filesExists(ctx context.Context, cfg FilesModuleConfig) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(thread *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var name string
+		if err := starlark.UnpackPositionalArgs(b.Name(), args, kwargs, 1, &name); err != nil {
+			return nil, err
+		}
+
+		if err := validateFileName(name); err != nil {
+			return nil, fmt.Errorf("files.exists: %w", err)
+		}
+
+		key := cfg.scopedKey(name)
+		exists, err := cfg.Store.Exists(ctx, key)
+		if err != nil {
+			return nil, fmt.Errorf("files.exists: %w", err)
+		}
+
+		return starlark.Bool(exists), nil
+	}
+}
+
+// ── Helpers ──────────────────────────────────
+
+// scopedKey returns the full ObjectStore key for a file name.
+func (cfg FilesModuleConfig) scopedKey(name string) string {
+	return fmt.Sprintf("ext/%s/%s", cfg.PackageID, name)
+}
+
+// metaKey returns the ObjectStore key for a file's metadata companion.
+func (cfg FilesModuleConfig) metaKey(name string) string {
+	return fmt.Sprintf("ext/%s/%s%s", cfg.PackageID, filesMetaPrefix, name)
+}
+
+// scopedPrefix returns the ObjectStore key prefix for this package.
+func (cfg FilesModuleConfig) scopedPrefix() string {
+	return fmt.Sprintf("ext/%s/", cfg.PackageID)
+}
+
+// validateFileName checks that a file name is safe.
+func validateFileName(name string) error {
+	if name == "" {
+		return fmt.Errorf("file name is required")
+	}
+	if len(name) > filesMaxNameLen {
+		return fmt.Errorf("file name exceeds %d characters", filesMaxNameLen)
+	}
+	if strings.HasPrefix(name, "/") || strings.HasPrefix(name, "\\") {
+		return fmt.Errorf("absolute paths not allowed: %q", name)
+	}
+	if strings.Contains(name, "..") {
+		return fmt.Errorf("path traversal not allowed: %q", name)
+	}
+	if strings.HasPrefix(name, filesMetaPrefix) {
+		return fmt.Errorf("names starting with %q are reserved", filesMetaPrefix)
+	}
+	for _, r := range name {
+		if unicode.IsControl(r) {
+			return fmt.Errorf("control characters not allowed in file name")
+		}
+	}
+	return nil
+}
+
+// filesMaxSize returns the maximum file size from env or default.
+func filesMaxSize() int64 {
+	if v := os.Getenv("EXT_FILES_MAX_SIZE"); v != "" {
+		if n, err := strconv.ParseInt(v, 10, 64); err == nil && n > 0 {
+			return n
+		}
+	}
+	return filesDefaultMaxSize
+}
+
+// starlarkDictToMap converts a *starlark.Dict to map[string]any, validating
+// that all keys are strings.  Returns an error if a non-string key is found.
+func starlarkDictToMap(d *starlark.Dict) (map[string]any, error) {
+	for _, item := range d.Items() {
+		if _, ok := starlark.AsString(item[0]); !ok {
+			return nil, fmt.Errorf("metadata keys must be strings, got %s", item[0].Type())
+		}
+	}
+	return DictToMap(d), nil
+}

server/sandbox/files_module_test.go

@@ -0,0 +1,410 @@
+package sandbox
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+	"testing"
+
+	"go.starlark.net/starlark"
+
+	"armature/storage"
+)
+
+// memStore is an in-memory ObjectStore for testing.
+type memStore struct {
+	objects map[string]memObject
+}
+
+type memObject struct {
+	data        []byte
+	contentType string
+}
+
+func newMemStore() *memStore {
+	return &memStore{objects: make(map[string]memObject)}
+}
+
+func (m *memStore) Put(_ context.Context, key string, r io.Reader, size int64, contentType string) error {
+	data, err := io.ReadAll(r)
+	if err != nil {
+		return err
+	}
+	m.objects[key] = memObject{data: data, contentType: contentType}
+	return nil
+}
+
+func (m *memStore) Get(_ context.Context, key string) (io.ReadCloser, int64, string, error) {
+	obj, ok := m.objects[key]
+	if !ok {
+		return nil, 0, "", storage.ErrNotFound
+	}
+	return io.NopCloser(&memReader{data: obj.data}), int64(len(obj.data)), obj.contentType, nil
+}
+
+func (m *memStore) Delete(_ context.Context, key string) error {
+	delete(m.objects, key)
+	return nil
+}
+
+func (m *memStore) DeletePrefix(_ context.Context, prefix string) error {
+	for k := range m.objects {
+		if strings.HasPrefix(k, prefix) {
+			delete(m.objects, k)
+		}
+	}
+	return nil
+}
+
+func (m *memStore) Exists(_ context.Context, key string) (bool, error) {
+	_, ok := m.objects[key]
+	return ok, nil
+}
+
+func (m *memStore) Healthy(_ context.Context) error { return nil }
+
+func (m *memStore) Stats(_ context.Context) (*storage.StorageStats, error) {
+	return &storage.StorageStats{Backend: "mem", Configured: true, Healthy: true}, nil
+}
+
+func (m *memStore) Backend() string { return "mem" }
+
+func (m *memStore) List(_ context.Context, prefix string, limit int) ([]storage.ObjectEntry, error) {
+	if limit <= 0 {
+		limit = 100
+	}
+	var entries []storage.ObjectEntry
+	for k, obj := range m.objects {
+		if strings.HasPrefix(k, prefix) {
+			entries = append(entries, storage.ObjectEntry{
+				Key:         k,
+				Size:        int64(len(obj.data)),
+				ContentType: obj.contentType,
+			})
+			if len(entries) >= limit {
+				break
+			}
+		}
+	}
+	return entries, nil
+}
+
+// memReader wraps a byte slice as io.ReadCloser.
+type memReader struct {
+	data []byte
+	pos  int
+}
+
+func (r *memReader) Read(p []byte) (int, error) {
+	if r.pos >= len(r.data) {
+		return 0, io.EOF
+	}
+	n := copy(p, r.data[r.pos:])
+	r.pos += n
+	if r.pos >= len(r.data) {
+		return n, io.EOF
+	}
+	return n, nil
+}
+
+func (r *memReader) Close() error { return nil }
+
+// ── Test helpers ──────────────────────────────
+
+func execWithFiles(t *testing.T, canWrite bool, script string) (*Result, error) {
+	t.Helper()
+	ctx := context.Background()
+	store := newMemStore()
+	mod := BuildFilesModule(ctx, FilesModuleConfig{
+		PackageID: "test-pkg",
+		CanWrite:  canWrite,
+		Store:     store,
+	})
+	sb := New(DefaultConfig())
+	return sb.Exec(ctx, "test.star", script, map[string]starlark.Value{
+		"files": mod,
+	})
+}
+
+func execWithFilesStore(t *testing.T, store *memStore, canWrite bool, script string) (*Result, error) {
+	t.Helper()
+	ctx := context.Background()
+	mod := BuildFilesModule(ctx, FilesModuleConfig{
+		PackageID: "test-pkg",
+		CanWrite:  canWrite,
+		Store:     store,
+	})
+	sb := New(DefaultConfig())
+	return sb.Exec(ctx, "test.star", script, map[string]starlark.Value{
+		"files": mod,
+	})
+}
+
+// ── Put + Get round-trip ──────────────────────
+
+func TestFilesPut_StringContent(t *testing.T) {
+	_, err := execWithFiles(t, true, `
+files.put("hello.txt", "hello world", content_type="text/plain")
+result = files.get("hello.txt")
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+}
+
+func TestFilesPut_BytesContent(t *testing.T) {
+	result, err := execWithFiles(t, true, `
+files.put("bin.dat", b"\x00\x01\x02\xff")
+got = files.get("bin.dat")
+size = got["size"]
+ct = got["content_type"]
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+
+	size, _ := starlark.AsInt32(result.Globals["size"])
+	if size != 4 {
+		t.Errorf("size = %d, want 4", size)
+	}
+	ct := string(result.Globals["ct"].(starlark.String))
+	if ct != "application/octet-stream" {
+		t.Errorf("content_type = %q, want application/octet-stream", ct)
+	}
+}
+
+func TestFilesPut_WithMetadata(t *testing.T) {
+	result, err := execWithFiles(t, true, `
+files.put("doc.pdf", "pdf content", content_type="application/pdf", metadata={"author": "test", "pages": 5})
+meta = files.meta("doc.pdf")
+author = meta["author"]
+pages = meta["pages"]
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+
+	author := string(result.Globals["author"].(starlark.String))
+	if author != "test" {
+		t.Errorf("author = %q, want %q", author, "test")
+	}
+	pages, _ := starlark.AsInt32(result.Globals["pages"])
+	if pages != 5 {
+		t.Errorf("pages = %d, want 5", pages)
+	}
+}
+
+func TestFilesPut_SizeLimit(t *testing.T) {
+	// Set a small limit for testing.
+	t.Setenv("EXT_FILES_MAX_SIZE", "10")
+	_, err := execWithFiles(t, true, `
+files.put("big.bin", "this content is longer than ten bytes")
+`)
+	if err == nil {
+		t.Fatal("expected size limit error")
+	}
+	if !strings.Contains(err.Error(), "exceeds limit") {
+		t.Errorf("unexpected error: %v", err)
+	}
+}
+
+// ── Get ───────────────────────────────────────
+
+func TestFilesGet_NotFound(t *testing.T) {
+	result, err := execWithFiles(t, false, `
+got = files.get("nonexistent.txt")
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+	if result.Globals["got"] != starlark.None {
+		t.Errorf("expected None, got %v", result.Globals["got"])
+	}
+}
+
+func TestFilesGet_ReturnsAllFields(t *testing.T) {
+	result, err := execWithFiles(t, true, `
+files.put("test.txt", "data", content_type="text/plain", metadata={"k": "v"})
+got = files.get("test.txt")
+has_content = "content" in got
+has_ct = "content_type" in got
+has_size = "size" in got
+has_meta = "metadata" in got
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+	for _, key := range []string{"has_content", "has_ct", "has_size", "has_meta"} {
+		if result.Globals[key] != starlark.True {
+			t.Errorf("%s = False, want True", key)
+		}
+	}
+}
+
+// ── Meta ──────────────────────────────────────
+
+func TestFilesMeta_NotFound(t *testing.T) {
+	result, err := execWithFiles(t, false, `
+got = files.meta("nonexistent.txt")
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+	if result.Globals["got"] != starlark.None {
+		t.Errorf("expected None, got %v", result.Globals["got"])
+	}
+}
+
+func TestFilesMeta_NoCompanion(t *testing.T) {
+	result, err := execWithFiles(t, true, `
+files.put("plain.txt", "data")
+meta = files.meta("plain.txt")
+count = len(meta)
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+	count, _ := starlark.AsInt32(result.Globals["count"])
+	if count != 0 {
+		t.Errorf("meta length = %d, want 0", count)
+	}
+}
+
+// ── List ──────────────────────────────────────
+
+func TestFilesList_PrefixFilter(t *testing.T) {
+	result, err := execWithFiles(t, true, `
+files.put("images/a.png", "a")
+files.put("images/b.png", "b")
+files.put("docs/c.pdf", "c")
+all_entries = files.list()
+img_entries = files.list(prefix="images/")
+all_count = len(all_entries)
+img_count = len(img_entries)
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+
+	allCount, _ := starlark.AsInt32(result.Globals["all_count"])
+	imgCount, _ := starlark.AsInt32(result.Globals["img_count"])
+
+	if allCount != 3 {
+		t.Errorf("all_count = %d, want 3", allCount)
+	}
+	if imgCount != 2 {
+		t.Errorf("img_count = %d, want 2", imgCount)
+	}
+}
+
+func TestFilesList_ExcludesMeta(t *testing.T) {
+	result, err := execWithFiles(t, true, `
+files.put("file.txt", "data", metadata={"key": "val"})
+entries = files.list()
+count = len(entries)
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+
+	count, _ := starlark.AsInt32(result.Globals["count"])
+	if count != 1 {
+		t.Errorf("count = %d, want 1 (should exclude _meta/ companion)", count)
+	}
+}
+
+// ── Delete ────────────────────────────────────
+
+func TestFilesDelete_Idempotent(t *testing.T) {
+	_, err := execWithFiles(t, true, `
+files.put("temp.txt", "temp")
+files.delete("temp.txt")
+files.delete("temp.txt")
+exists = files.exists("temp.txt")
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+}
+
+func TestFilesDeletePrefix(t *testing.T) {
+	result, err := execWithFiles(t, true, `
+files.put("uploads/a.txt", "a")
+files.put("uploads/b.txt", "b")
+files.put("keep.txt", "keep")
+files.delete_prefix("uploads/")
+a_exists = files.exists("uploads/a.txt")
+b_exists = files.exists("uploads/b.txt")
+keep_exists = files.exists("keep.txt")
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+
+	if result.Globals["a_exists"] != starlark.False {
+		t.Error("uploads/a.txt should be deleted")
+	}
+	if result.Globals["b_exists"] != starlark.False {
+		t.Error("uploads/b.txt should be deleted")
+	}
+	if result.Globals["keep_exists"] != starlark.True {
+		t.Error("keep.txt should be preserved")
+	}
+}
+
+// ── Exists ────────────────────────────────────
+
+func TestFilesExists(t *testing.T) {
+	result, err := execWithFiles(t, true, `
+files.put("exists.txt", "yes")
+yes = files.exists("exists.txt")
+no = files.exists("nope.txt")
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+
+	if result.Globals["yes"] != starlark.True {
+		t.Error("exists should be True")
+	}
+	if result.Globals["no"] != starlark.False {
+		t.Error("nope should be False")
+	}
+}
+
+// ── Name Validation ──────────────────────────
+
+func TestFilesNameValidation(t *testing.T) {
+	badNames := []string{
+		"../escape",
+		"/absolute",
+		"_meta/reserved",
+		"",
+	}
+
+	for _, name := range badNames {
+		t.Run(name, func(t *testing.T) {
+			script := fmt.Sprintf(`files.exists(%q)`, name)
+			_, err := execWithFiles(t, false, script)
+			if err == nil {
+				t.Errorf("expected error for name %q", name)
+			}
+		})
+	}
+}
+
+// ── Write Permission Gate ────────────────────
+
+func TestFilesWritePermission(t *testing.T) {
+	// Read-only mode: put/delete/delete_prefix should not be available.
+	_, err := execWithFiles(t, false, `
+files.put("test.txt", "data")
+`)
+	if err == nil {
+		t.Fatal("expected error: put should not be available in read-only mode")
+	}
+	if !strings.Contains(err.Error(), "no .put field") && !strings.Contains(err.Error(), "has no .put") {
+		t.Errorf("unexpected error: %v", err)
+	}
+}

server/sandbox/forms_module.go

@@ -0,0 +1,86 @@
+package sandbox
+
+// forms_module.go
+//
+// Starlark forms module — validates form data against typed form templates.
+// Gated by the forms.validate extension permission.
+//
+// Starlark API:
+//   result = forms.validate(template, data)
+//   # result["valid"]  → True/False
+//   # result["errors"] → [{"key": "...", "message": "..."}, ...]
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"go.starlark.net/starlark"
+	"go.starlark.net/starlarkstruct"
+
+	"armature/forms"
+)
+
+// BuildFormsModule creates the "forms" Starlark module.
+// Requires the forms.validate permission.
+func BuildFormsModule(_ context.Context) *starlarkstruct.Module {
+	return MakeModule("forms", starlark.StringDict{
+		"validate": starlark.NewBuiltin("forms.validate", formsValidateBuiltin()),
+	})
+}
+
+func formsValidateBuiltin() func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(_ *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var templateVal, dataVal starlark.Value
+		if err := starlark.UnpackPositionalArgs(b.Name(), args, kwargs, 2, &templateVal, &dataVal); err != nil {
+			return nil, err
+		}
+
+		// Convert template dict → Go map → JSON → TypedFormTemplate
+		templateDict, ok := templateVal.(*starlark.Dict)
+		if !ok {
+			return nil, fmt.Errorf("forms.validate: template must be a dict, got %s", templateVal.Type())
+		}
+		templateMap := DictToMap(templateDict)
+		templateJSON, err := json.Marshal(templateMap)
+		if err != nil {
+			return nil, fmt.Errorf("forms.validate: failed to marshal template: %w", err)
+		}
+
+		tpl := forms.ParseTypedFormTemplate(json.RawMessage(templateJSON))
+		if tpl == nil {
+			return nil, fmt.Errorf("forms.validate: template is invalid or empty")
+		}
+
+		// Convert data dict → Go map
+		dataDict, ok := dataVal.(*starlark.Dict)
+		if !ok {
+			return nil, fmt.Errorf("forms.validate: data must be a dict, got %s", dataVal.Type())
+		}
+		dataMap := DictToMap(dataDict)
+
+		// Coerce to map[string]interface{}
+		data := make(map[string]interface{}, len(dataMap))
+		for k, v := range dataMap {
+			data[k] = v
+		}
+
+		// Validate
+		errs := forms.ValidateFormData(tpl, data)
+
+		// Build result dict
+		errList := make([]starlark.Value, len(errs))
+		for i, e := range errs {
+			d := starlark.NewDict(2)
+			_ = d.SetKey(starlark.String("key"), starlark.String(e.Key))
+			_ = d.SetKey(starlark.String("message"), starlark.String(e.Message))
+			errList[i] = d
+		}
+
+		result := starlark.NewDict(2)
+		_ = result.SetKey(starlark.String("valid"), starlark.Bool(len(errs) == 0))
+		_ = result.SetKey(starlark.String("errors"), starlark.NewList(errList))
+
+		return result, nil
+	}
+}

server/sandbox/forms_module_test.go

@@ -0,0 +1,116 @@
+package sandbox
+
+import (
+	"context"
+	"testing"
+
+	"go.starlark.net/starlark"
+)
+
+func runFormsScript(t *testing.T, script string) starlark.StringDict {
+	t.Helper()
+	mod := BuildFormsModule(context.Background())
+	predeclared := starlark.StringDict{"forms": mod}
+	globals, err := starlark.ExecFile(&starlark.Thread{Name: "test"}, "test.star", script, predeclared)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return globals
+}
+
+func TestFormsModule_ValidateValid(t *testing.T) {
+	globals := runFormsScript(t, `
+tpl = {
+    "fields": [
+        {"key": "name", "type": "text", "label": "Name", "required": True},
+        {"key": "email", "type": "email", "label": "Email"},
+    ]
+}
+result = forms.validate(tpl, {"name": "Alice", "email": "alice@example.com"})
+`)
+	result := globals["result"].(*starlark.Dict)
+	valid, _, _ := result.Get(starlark.String("valid"))
+	if valid != starlark.True {
+		t.Fatalf("expected valid=True, got %v", valid)
+	}
+	errors, _, _ := result.Get(starlark.String("errors"))
+	errList := errors.(*starlark.List)
+	if errList.Len() != 0 {
+		t.Fatalf("expected 0 errors, got %d", errList.Len())
+	}
+}
+
+func TestFormsModule_ValidateRequired(t *testing.T) {
+	globals := runFormsScript(t, `
+tpl = {
+    "fields": [
+        {"key": "name", "type": "text", "label": "Name", "required": True},
+    ]
+}
+result = forms.validate(tpl, {})
+`)
+	result := globals["result"].(*starlark.Dict)
+	valid, _, _ := result.Get(starlark.String("valid"))
+	if valid != starlark.False {
+		t.Fatalf("expected valid=False, got %v", valid)
+	}
+	errors, _, _ := result.Get(starlark.String("errors"))
+	errList := errors.(*starlark.List)
+	if errList.Len() != 1 {
+		t.Fatalf("expected 1 error, got %d", errList.Len())
+	}
+	errDict := errList.Index(0).(*starlark.Dict)
+	key, _, _ := errDict.Get(starlark.String("key"))
+	if key.(starlark.String).GoString() != "name" {
+		t.Fatalf("expected error key 'name', got %v", key)
+	}
+}
+
+func TestFormsModule_ValidateTypeErrors(t *testing.T) {
+	globals := runFormsScript(t, `
+tpl = {
+    "fields": [
+        {"key": "age", "type": "number", "label": "Age", "validation": {"min": 0, "max": 150}},
+        {"key": "email", "type": "email", "label": "Email"},
+    ]
+}
+result = forms.validate(tpl, {"age": -5, "email": "bad"})
+`)
+	result := globals["result"].(*starlark.Dict)
+	valid, _, _ := result.Get(starlark.String("valid"))
+	if valid != starlark.False {
+		t.Fatalf("expected valid=False, got %v", valid)
+	}
+	errors, _, _ := result.Get(starlark.String("errors"))
+	errList := errors.(*starlark.List)
+	if errList.Len() != 2 {
+		t.Fatalf("expected 2 errors, got %d", errList.Len())
+	}
+}
+
+func TestFormsModule_ValidateCondition(t *testing.T) {
+	globals := runFormsScript(t, `
+tpl = {
+    "fields": [
+        {"key": "type", "type": "text", "label": "Type"},
+        {"key": "details", "type": "text", "label": "Details", "required": True,
+         "condition": {"when": "type", "op": "eq", "value": "other"}},
+    ]
+}
+# Condition not met — details not required
+result1 = forms.validate(tpl, {"type": "normal"})
+# Condition met — details required
+result2 = forms.validate(tpl, {"type": "other"})
+`)
+	result1 := globals["result1"].(*starlark.Dict)
+	valid1, _, _ := result1.Get(starlark.String("valid"))
+	if valid1 != starlark.True {
+		t.Fatalf("result1: expected valid=True, got %v", valid1)
+	}
+
+	result2 := globals["result2"].(*starlark.Dict)
+	valid2, _, _ := result2.Get(starlark.String("valid"))
+	if valid2 != starlark.False {
+		t.Fatalf("result2: expected valid=False, got %v", valid2)
+	}
+}

server/sandbox/lib_module.go

@@ -79,19 +79,21 @@ func BuildLibModule(ctx context.Context, r *Runner, consumerPkgID string, rc *Ru
 				return nil, fmt.Errorf("lib.require: package %q does not declare dependency on %q", consumerPkgID, libraryID)
 			}
 
-			// 4. Load library's PackageRegistration
+			// 4. Load target PackageRegistration
 			libPkg, err := r.stores.Packages.Get(ctx, libraryID)
 			if err != nil {
-				return nil, fmt.Errorf("lib.require: library %q not found: %w", libraryID, err)
+				return nil, fmt.Errorf("lib.require: package %q not found: %w", libraryID, err)
 			}
-			if libPkg.Type != "library" {
+			// Any package with exports is callable — not just type "library"
-				return nil, fmt.Errorf("lib.require: package %q is type %q, not library", libraryID, libPkg.Type)
+			exports := extractExports(libPkg.Manifest)
+			if len(exports) == 0 {
+				return nil, fmt.Errorf("lib.require: package %q declares no exports", libraryID)
 			}
 			if libPkg.Status != models.PackageStatusActive {
-				return nil, fmt.Errorf("lib.require: library %q is %s, not active", libraryID, libPkg.Status)
+				return nil, fmt.Errorf("lib.require: package %q is %s, not active", libraryID, libPkg.Status)
 			}
 			if libPkg.Tier != models.ExtTierStarlark {
-				return nil, fmt.Errorf("lib.require: library %q is tier %s, not starlark", libraryID, libPkg.Tier)
+				return nil, fmt.Errorf("lib.require: package %q is tier %s, not starlark", libraryID, libPkg.Tier)
 			}
 
 			// 5. Build library's module set (library's own permissions)
@@ -113,12 +115,7 @@ func BuildLibModule(ctx context.Context, r *Runner, consumerPkgID string, rc *Ru
 				return nil, fmt.Errorf("lib.require: error executing library %q: %w", libraryID, err)
 			}
 
-			// 8. Extract exports from manifest
+			// 8. Build exported members (exports already extracted above)
-			exports := extractExports(libPkg.Manifest)
-			if len(exports) == 0 {
-				return nil, fmt.Errorf("lib.require: library %q declares no exports", libraryID)
-			}
-
 			members := make(starlark.StringDict, len(exports))
 			for _, name := range exports {
 				val, ok := result.Globals[name]

server/sandbox/realtime_module.go

@@ -83,7 +83,7 @@ func realtimePublish(ctx context.Context, bus *events.Bus, packageID string) fun
 				if k == "_pkg" {
 					continue // reserved field
 				}
-				payload[k] = starlarkToGoVal(item[1])
+				payload[k] = StarlarkToGo(item[1])
 			}
 		}
 
@@ -108,46 +108,3 @@ func realtimePublish(ctx context.Context, bus *events.Bus, packageID string) fun
 	}
 }
 
-// starlarkToGoVal converts a Starlark value to a Go value for JSON marshaling.
-func starlarkToGoVal(v starlark.Value) any {
-	switch val := v.(type) {
-	case starlark.NoneType:
-		return nil
-	case starlark.Bool:
-		return bool(val)
-	case starlark.Int:
-		if i, ok := val.Int64(); ok {
-			return i
-		}
-		return val.String()
-	case starlark.Float:
-		return float64(val)
-	case starlark.String:
-		return string(val)
-	case *starlark.Dict:
-		m := make(map[string]any, val.Len())
-		for _, item := range val.Items() {
-			k, ok := starlark.AsString(item[0])
-			if !ok {
-				k = item[0].String()
-			}
-			m[k] = starlarkToGoVal(item[1])
-		}
-		return m
-	case *starlark.List:
-		n := val.Len()
-		s := make([]any, n)
-		for i := 0; i < n; i++ {
-			s[i] = starlarkToGoVal(val.Index(i))
-		}
-		return s
-	case starlark.Tuple:
-		s := make([]any, len(val))
-		for i, v := range val {
-			s[i] = starlarkToGoVal(v)
-		}
-		return s
-	default:
-		return v.String()
-	}
-}

server/sandbox/realtime_module_test.go

@@ -133,7 +133,7 @@ realtime.publish("ch:1", "big.event", {"data": big})
 	}
 }
 
-func TestStarlarkToGoVal(t *testing.T) {
+func TestStarlarkToGo_Realtime(t *testing.T) {
 	tests := []struct {
 		name string
 		val  starlark.Value
@@ -149,9 +149,9 @@ func TestStarlarkToGoVal(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			got := starlarkToGoVal(tt.val)
+			got := StarlarkToGo(tt.val)
 			if got != tt.want {
-				t.Errorf("starlarkToGoVal(%s) = %v (%T), want %v (%T)", tt.val, got, got, tt.want, tt.want)
+				t.Errorf("StarlarkToGo(%s) = %v (%T), want %v (%T)", tt.val, got, got, tt.want, tt.want)
 			}
 		})
 	}

server/sandbox/routing_module.go

@@ -0,0 +1,190 @@
+package sandbox
+
+// routing_module.go
+//
+// Starlark routing module — a generic rule-based decision engine.
+// Always available (pure computation, no I/O).
+//
+// Starlark API:
+//   result = routing.evaluate(rules, data)
+//   # result → "target_string" or None
+
+import (
+	"fmt"
+	"strings"
+
+	"go.starlark.net/starlark"
+	"go.starlark.net/starlarkstruct"
+)
+
+// BuildRoutingModule creates the "routing" Starlark module.
+// No permission required — pure computation.
+func BuildRoutingModule() *starlarkstruct.Module {
+	return MakeModule("routing", starlark.StringDict{
+		"evaluate": starlark.NewBuiltin("routing.evaluate", routingEvaluateBuiltin()),
+	})
+}
+
+// routingRule is the generic equivalent of workflow.Condition.
+// Uses "target" instead of "target_stage" to be domain-agnostic.
+type routingRule struct {
+	Field  string
+	Op     string
+	Value  any
+	Target string
+}
+
+func routingEvaluateBuiltin() func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(_ *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var rulesVal, dataVal starlark.Value
+		if err := starlark.UnpackPositionalArgs(b.Name(), args, kwargs, 2, &rulesVal, &dataVal); err != nil {
+			return nil, err
+		}
+
+		// Convert rules list → []routingRule
+		rulesList, ok := rulesVal.(*starlark.List)
+		if !ok {
+			return nil, fmt.Errorf("routing.evaluate: rules must be a list, got %s", rulesVal.Type())
+		}
+
+		rules := make([]routingRule, rulesList.Len())
+		for i := 0; i < rulesList.Len(); i++ {
+			ruleDict, ok := rulesList.Index(i).(*starlark.Dict)
+			if !ok {
+				return nil, fmt.Errorf("routing.evaluate: rules[%d] must be a dict, got %s", i, rulesList.Index(i).Type())
+			}
+			m := DictToMap(ruleDict)
+
+			field, _ := m["field"].(string)
+			op, _ := m["op"].(string)
+			target, _ := m["target"].(string)
+			if field == "" || op == "" || target == "" {
+				return nil, fmt.Errorf("routing.evaluate: rules[%d] must have field, op, and target", i)
+			}
+			rules[i] = routingRule{
+				Field:  field,
+				Op:     op,
+				Value:  m["value"],
+				Target: target,
+			}
+		}
+
+		// Convert data dict → Go map
+		dataDict, ok := dataVal.(*starlark.Dict)
+		if !ok {
+			return nil, fmt.Errorf("routing.evaluate: data must be a dict, got %s", dataVal.Type())
+		}
+		data := DictToMap(dataDict)
+
+		// Evaluate rules — first match wins
+		for _, rule := range rules {
+			if evaluateRoutingCondition(rule, data) {
+				return starlark.String(rule.Target), nil
+			}
+		}
+
+		return starlark.None, nil
+	}
+}
+
+// ── Evaluation helpers (mirrored from workflow/routing.go) ─────────
+//
+// These are pure functions copied from the workflow package to avoid
+// a sandbox → workflow import cycle. The workflow package continues
+// using its own copy for ResolveNextStage.
+
+// evaluateRoutingCondition checks if a single rule matches against data.
+func evaluateRoutingCondition(rule routingRule, data map[string]any) bool {
+	val, exists := data[rule.Field]
+
+	switch rule.Op {
+	case "exists":
+		return exists
+	case "not_exists":
+		return !exists
+	}
+
+	if !exists {
+		return false
+	}
+
+	switch rule.Op {
+	case "eq":
+		return routingCompareEq(val, rule.Value)
+	case "neq":
+		return !routingCompareEq(val, rule.Value)
+	case "gt":
+		return routingCompareNum(val, rule.Value) > 0
+	case "lt":
+		return routingCompareNum(val, rule.Value) < 0
+	case "gte":
+		return routingCompareNum(val, rule.Value) >= 0
+	case "lte":
+		return routingCompareNum(val, rule.Value) <= 0
+	case "in":
+		return routingCompareIn(val, rule.Value)
+	case "contains":
+		return routingCompareContains(val, rule.Value)
+	default:
+		return false
+	}
+}
+
+func routingCompareEq(a, b any) bool {
+	return fmt.Sprintf("%v", a) == fmt.Sprintf("%v", b)
+}
+
+func routingCompareNum(a, b any) int {
+	af := routingToFloat(a)
+	bf := routingToFloat(b)
+	if af == nil || bf == nil {
+		return 0
+	}
+	switch {
+	case *af < *bf:
+		return -1
+	case *af > *bf:
+		return 1
+	default:
+		return 0
+	}
+}
+
+func routingToFloat(v any) *float64 {
+	switch n := v.(type) {
+	case float64:
+		return &n
+	case int:
+		f := float64(n)
+		return &f
+	case int64:
+		f := float64(n)
+		return &f
+	case string:
+		var f float64
+		if _, err := fmt.Sscanf(n, "%f", &f); err == nil {
+			return &f
+		}
+	}
+	return nil
+}
+
+func routingCompareIn(val, list any) bool {
+	arr, ok := list.([]any)
+	if !ok {
+		return false
+	}
+	vs := fmt.Sprintf("%v", val)
+	for _, item := range arr {
+		if fmt.Sprintf("%v", item) == vs {
+			return true
+		}
+	}
+	return false
+}
+
+func routingCompareContains(val, target any) bool {
+	s := fmt.Sprintf("%v", val)
+	t := fmt.Sprintf("%v", target)
+	return strings.Contains(s, t)
+}

server/sandbox/routing_module_test.go

@@ -0,0 +1,162 @@
+package sandbox
+
+import (
+	"testing"
+
+	"go.starlark.net/starlark"
+)
+
+func runRoutingScript(t *testing.T, script string) starlark.StringDict {
+	t.Helper()
+	mod := BuildRoutingModule()
+	predeclared := starlark.StringDict{"routing": mod}
+	globals, err := starlark.ExecFile(&starlark.Thread{Name: "test"}, "test.star", script, predeclared)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return globals
+}
+
+func runRoutingScriptErr(t *testing.T, script string) error {
+	t.Helper()
+	mod := BuildRoutingModule()
+	predeclared := starlark.StringDict{"routing": mod}
+	_, err := starlark.ExecFile(&starlark.Thread{Name: "test"}, "test.star", script, predeclared)
+	return err
+}
+
+func TestRoutingEvaluate_SingleMatch(t *testing.T) {
+	globals := runRoutingScript(t, `
+result = routing.evaluate([
+    {"field": "priority", "op": "eq", "value": "high", "target": "escalation"},
+], {"priority": "high"})
+`)
+	result := globals["result"]
+	if s, ok := result.(starlark.String); !ok || string(s) != "escalation" {
+		t.Fatalf("expected 'escalation', got %v", result)
+	}
+}
+
+func TestRoutingEvaluate_FirstMatchWins(t *testing.T) {
+	globals := runRoutingScript(t, `
+result = routing.evaluate([
+    {"field": "amount", "op": "gt", "value": 100, "target": "big"},
+    {"field": "amount", "op": "gt", "value": 50,  "target": "medium"},
+], {"amount": 200})
+`)
+	result := globals["result"]
+	if s, ok := result.(starlark.String); !ok || string(s) != "big" {
+		t.Fatalf("expected 'big', got %v", result)
+	}
+}
+
+func TestRoutingEvaluate_NoMatch(t *testing.T) {
+	globals := runRoutingScript(t, `
+result = routing.evaluate([
+    {"field": "status", "op": "eq", "value": "done", "target": "finish"},
+], {"status": "pending"})
+`)
+	if globals["result"] != starlark.None {
+		t.Fatalf("expected None, got %v", globals["result"])
+	}
+}
+
+func TestRoutingEvaluate_EmptyRules(t *testing.T) {
+	globals := runRoutingScript(t, `
+result = routing.evaluate([], {"x": 1})
+`)
+	if globals["result"] != starlark.None {
+		t.Fatalf("expected None, got %v", globals["result"])
+	}
+}
+
+func TestRoutingEvaluate_AllOperators(t *testing.T) {
+	globals := runRoutingScript(t, `
+# exists
+r1 = routing.evaluate([{"field": "x", "op": "exists", "value": "", "target": "yes"}], {"x": 1})
+# not_exists
+r2 = routing.evaluate([{"field": "x", "op": "not_exists", "value": "", "target": "yes"}], {"y": 1})
+# eq
+r3 = routing.evaluate([{"field": "s", "op": "eq", "value": "abc", "target": "yes"}], {"s": "abc"})
+# neq
+r4 = routing.evaluate([{"field": "s", "op": "neq", "value": "abc", "target": "yes"}], {"s": "xyz"})
+# gt
+r5 = routing.evaluate([{"field": "n", "op": "gt", "value": 10, "target": "yes"}], {"n": 20})
+# lt
+r6 = routing.evaluate([{"field": "n", "op": "lt", "value": 10, "target": "yes"}], {"n": 5})
+# gte
+r7 = routing.evaluate([{"field": "n", "op": "gte", "value": 10, "target": "yes"}], {"n": 10})
+# lte
+r8 = routing.evaluate([{"field": "n", "op": "lte", "value": 10, "target": "yes"}], {"n": 10})
+# in
+r9 = routing.evaluate([{"field": "s", "op": "in", "value": ["a", "b", "c"], "target": "yes"}], {"s": "b"})
+# contains
+r10 = routing.evaluate([{"field": "s", "op": "contains", "value": "ell", "target": "yes"}], {"s": "hello"})
+`)
+	for _, name := range []string{"r1", "r2", "r3", "r4", "r5", "r6", "r7", "r8", "r9", "r10"} {
+		v := globals[name]
+		if s, ok := v.(starlark.String); !ok || string(s) != "yes" {
+			t.Errorf("%s: expected 'yes', got %v", name, v)
+		}
+	}
+}
+
+func TestRoutingEvaluate_TypeCoercion(t *testing.T) {
+	globals := runRoutingScript(t, `
+# Numeric string vs int
+r1 = routing.evaluate([
+    {"field": "n", "op": "gt", "value": 10, "target": "yes"},
+], {"n": "20"})
+
+# Int equality via string normalization
+r2 = routing.evaluate([
+    {"field": "n", "op": "eq", "value": 42, "target": "yes"},
+], {"n": 42})
+`)
+	for _, name := range []string{"r1", "r2"} {
+		v := globals[name]
+		if s, ok := v.(starlark.String); !ok || string(s) != "yes" {
+			t.Errorf("%s: expected 'yes', got %v", name, v)
+		}
+	}
+}
+
+func TestRoutingEvaluate_BadInput(t *testing.T) {
+	// rules must be a list
+	err1 := runRoutingScriptErr(t, `routing.evaluate("bad", {})`)
+	if err1 == nil {
+		t.Fatal("expected error for non-list rules")
+	}
+
+	// data must be a dict
+	err2 := runRoutingScriptErr(t, `routing.evaluate([], "bad")`)
+	if err2 == nil {
+		t.Fatal("expected error for non-dict data")
+	}
+
+	// rule missing required fields
+	err3 := runRoutingScriptErr(t, `routing.evaluate([{"field": "x"}], {})`)
+	if err3 == nil {
+		t.Fatal("expected error for incomplete rule")
+	}
+}
+
+func TestRoutingEvaluate_MissingFields(t *testing.T) {
+	globals := runRoutingScript(t, `
+# Field not in data — eq should not match
+r1 = routing.evaluate([
+    {"field": "absent", "op": "eq", "value": "x", "target": "bad"},
+], {"other": "y"})
+
+# not_exists matches when field is absent
+r2 = routing.evaluate([
+    {"field": "absent", "op": "not_exists", "value": "", "target": "good"},
+], {"other": "y"})
+`)
+	if globals["r1"] != starlark.None {
+		t.Fatalf("r1: expected None for missing field, got %v", globals["r1"])
+	}
+	if s, ok := globals["r2"].(starlark.String); !ok || string(s) != "good" {
+		t.Fatalf("r2: expected 'good', got %v", globals["r2"])
+	}
+}

server/sandbox/runner.go

@@ -33,6 +33,7 @@ import (
 	"armature/events"
 	"armature/metrics"
 	"armature/models"
+	"armature/storage"
 	"armature/store"
 )
 
@@ -77,6 +78,11 @@ type Runner struct {
 	dbPostgres      bool                 // true = use $N placeholders; false = use ?
 	allowPrivateIPs bool
 	bus             *events.Bus
+	objectStore     storage.ObjectStore  // nil = files module unavailable
+	workspaceRoot   string               // empty = workspace module unavailable
+	workspaceQuota  int                  // MB, 0 = unlimited
+	capabilities    map[string]bool      // detected environment capabilities
+	wfEngine        WorkflowEngine       // nil = workflow write ops unavailable
 }
 
 // NewRunner creates a runner with the given sandbox and dependencies.
@@ -116,6 +122,30 @@ func (r *Runner) SetBus(bus *events.Bus) {
 	r.bus = bus
 }
 
+// SetObjectStore attaches the blob storage backend for the files module.
+func (r *Runner) SetObjectStore(s storage.ObjectStore) {
+	r.objectStore = s
+}
+
+// SetWorkspaceRoot sets the base directory for extension workspaces.
+// quotaMB is the per-extension quota in MB (0 = unlimited).
+func (r *Runner) SetWorkspaceRoot(root string, quotaMB int) {
+	r.workspaceRoot = root
+	r.workspaceQuota = quotaMB
+}
+
+// SetCapabilities stores the detected environment capabilities map.
+// Passed to the settings module so extensions can call has_capability().
+func (r *Runner) SetCapabilities(caps map[string]bool) {
+	r.capabilities = caps
+}
+
+// SetWorkflowEngine attaches the workflow engine for write operations
+// (start/advance/cancel/submit_signoff) in the workflow Starlark module.
+func (r *Runner) SetWorkflowEngine(e WorkflowEngine) {
+	r.wfEngine = e
+}
+
 // SetAllowPrivateIPs disables the SSRF check that blocks connections to
 // private/loopback IPs. For self-hosted environments where extensions
 // reach internal services. Controlled by EXT_ALLOW_PRIVATE_IPS env var.
@@ -336,8 +366,9 @@ func (r *Runner) buildModulesWithLibCtx(ctx context.Context, packageID string, m
 
 	modules := make(map[string]starlark.Value)
 
-	// Track db permission level: 0=none, 1=read, 2=write
+	// Track tiered permission levels: 0=none, 1=read, 2=write
 	dbLevel := 0
+	filesLevel := 0
 	hasBatchExec := false
 
 	for _, perm := range granted {
@@ -363,8 +394,16 @@ func (r *Runner) buildModulesWithLibCtx(ctx context.Context, packageID string, m
 		case models.ExtPermDBWrite:
 			dbLevel = 2
 
+		case models.ExtPermFilesRead:
+			if filesLevel < 1 {
+				filesLevel = 1
+			}
+
+		case models.ExtPermFilesWrite:
+			filesLevel = 2
+
 		case models.ExtPermWorkflowAccess:
-			modules["workflow"] = BuildWorkflowModule(ctx, r.stores)
+			modules["workflow"] = BuildWorkflowModule(ctx, r.stores, r.wfEngine, rc)
 
 		case models.ExtPermConnectionsRead:
 			if r.connResolver != nil && rc != nil && rc.UserID != "" {
@@ -376,6 +415,18 @@ func (r *Runner) buildModulesWithLibCtx(ctx context.Context, packageID string, m
 				modules["realtime"] = BuildRealtimeModule(ctx, r.bus, packageID)
 			}
 
+		case models.ExtPermWorkspaceManage:
+			if r.workspaceRoot != "" {
+				modules["workspace"] = BuildWorkspaceModule(ctx, WorkspaceModuleConfig{
+					PackageID:     packageID,
+					WorkspaceRoot: r.workspaceRoot,
+					QuotaMB:       r.workspaceQuota,
+				})
+			}
+
+		case models.ExtPermFormValidate:
+			modules["forms"] = BuildFormsModule(ctx)
+
 		case models.ExtPermBatchExec:
 			hasBatchExec = true
 		}
@@ -384,10 +435,20 @@ func (r *Runner) buildModulesWithLibCtx(ctx context.Context, packageID string, m
 	// Wire db module at the highest granted level.
 	if dbLevel > 0 && r.db != nil {
 		modules["db"] = BuildDBModule(ctx, DBModuleConfig{
-			PackageID:  packageID,
+			PackageID:   packageID,
-			CanWrite:   dbLevel == 2,
+			CanWrite:    dbLevel == 2,
-			DB:         r.db,
+			DB:          r.db,
-			IsPostgres: r.dbPostgres,
+			IsPostgres:  r.dbPostgres,
+			HasPgvector: r.capabilities["pgvector"],
+		})
+	}
+
+	// Wire files module at the highest granted level.
+	if filesLevel > 0 && r.objectStore != nil {
+		modules["files"] = BuildFilesModule(ctx, FilesModuleConfig{
+			PackageID: packageID,
+			CanWrite:  filesLevel == 2,
+			Store:     r.objectStore,
 		})
 	}
 
@@ -398,11 +459,17 @@ func (r *Runner) buildModulesWithLibCtx(ctx context.Context, packageID string, m
 		userID = rc.UserID
 		teamID = rc.TeamID
 	}
-	modules["settings"] = BuildSettingsModule(ctx, r.stores, packageID, userID, teamID)
+	modules["settings"] = BuildSettingsModule(ctx, r.stores, packageID, userID, teamID, r.capabilities)
 
 	// Always available — read-only check against kernel permission data
 	modules["permissions"] = BuildPermissionsModule(ctx, r.stores)
 
+	// Always available — read-only team role queries
+	modules["teams"] = BuildTeamsModule(ctx, r.stores)
+
+	// Always available — pure-computation routing decision engine
+	modules["routing"] = BuildRoutingModule()
+
 	// Allows any starlark package to load declared library dependencies.
 	if lc != nil {
 		modules["lib"] = BuildLibModule(ctx, r, packageID, rc, lc)

server/sandbox/settings_module.go

@@ -11,6 +11,7 @@ package sandbox
 // Starlark API:
 //   val = settings.get("key")            # returns string, number, bool, or None
 //   val = settings.get("key", "default") # returns default if key not set
+//   ok  = settings.has_capability("pgvector")  # returns True or False
 
 import (
 	"context"
@@ -24,12 +25,28 @@ import (
 // BuildSettingsModule creates the "settings" Starlark module for a package.
 // It resolves the three-tier cascade (global → team → user) respecting
 // the user_overridable flag from the package manifest.
-func BuildSettingsModule(ctx context.Context, stores store.Stores, packageID, userID, teamID string) *starlarkstruct.Module {
+func BuildSettingsModule(ctx context.Context, stores store.Stores, packageID, userID, teamID string, capabilities map[string]bool) *starlarkstruct.Module {
 	return MakeModule("settings", starlark.StringDict{
-		"get": starlark.NewBuiltin("settings.get", settingsGet(ctx, stores, packageID, userID, teamID)),
+		"get":            starlark.NewBuiltin("settings.get", settingsGet(ctx, stores, packageID, userID, teamID)),
+		"has_capability": starlark.NewBuiltin("settings.has_capability", hasCapability(capabilities)),
 	})
 }
 
+// hasCapability returns a Starlark builtin that checks whether a named
+// environment capability is available.  Read-only, no permission needed.
+func hasCapability(caps map[string]bool) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var name string
+		if err := starlark.UnpackPositionalArgs("settings.has_capability", args, kwargs, 1, &name); err != nil {
+			return nil, err
+		}
+		if caps == nil {
+			return starlark.False, nil
+		}
+		return starlark.Bool(caps[name]), nil
+	}
+}
+
 func settingsGet(ctx context.Context, stores store.Stores, packageID, userID, teamID string) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
 	return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
 		var key string

server/sandbox/settings_module_test.go

@@ -0,0 +1,75 @@
+package sandbox
+
+import (
+	"context"
+	"testing"
+
+	"go.starlark.net/starlark"
+
+	"armature/store"
+)
+
+func execWithSettings(t *testing.T, caps map[string]bool, script string) (*Result, error) {
+	t.Helper()
+	ctx := context.Background()
+	mod := BuildSettingsModule(ctx, store.Stores{}, "", "", "", caps)
+	sb := New(DefaultConfig())
+	return sb.Exec(ctx, "test.star", script, map[string]starlark.Value{
+		"settings": mod,
+	})
+}
+
+func TestHasCapability_True(t *testing.T) {
+	caps := map[string]bool{"postgres": true, "pgvector": true}
+	result, err := execWithSettings(t, caps, `
+result = settings.has_capability("pgvector")
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+	v := result.Globals["result"]
+	if v != starlark.True {
+		t.Errorf("has_capability('pgvector') = %v, want True", v)
+	}
+}
+
+func TestHasCapability_False(t *testing.T) {
+	caps := map[string]bool{"postgres": true, "pgvector": false}
+	result, err := execWithSettings(t, caps, `
+result = settings.has_capability("pgvector")
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+	v := result.Globals["result"]
+	if v != starlark.False {
+		t.Errorf("has_capability('pgvector') = %v, want False", v)
+	}
+}
+
+func TestHasCapability_UnknownCap(t *testing.T) {
+	caps := map[string]bool{"postgres": true}
+	result, err := execWithSettings(t, caps, `
+result = settings.has_capability("gpu")
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+	v := result.Globals["result"]
+	if v != starlark.False {
+		t.Errorf("has_capability('gpu') = %v, want False", v)
+	}
+}
+
+func TestHasCapability_NilCaps(t *testing.T) {
+	result, err := execWithSettings(t, nil, `
+result = settings.has_capability("postgres")
+`)
+	if err != nil {
+		t.Fatalf("exec error: %v", err)
+	}
+	v := result.Globals["result"]
+	if v != starlark.False {
+		t.Errorf("has_capability with nil caps = %v, want False", v)
+	}
+}

server/sandbox/teams_module.go

@@ -0,0 +1,62 @@
+// Package sandbox — teams_module.go
+//
+// Read-only module for querying team role membership from Starlark scripts.
+// No sandbox permission required — extensions can check roles without special grants.
+//
+// Starlark API:
+//   teams.get_member_roles(team_id, user_id)  → ["admin", "reviewer", ...]
+//   teams.has_role(team_id, user_id, role)     → True/False
+package sandbox
+
+import (
+	"context"
+
+	"go.starlark.net/starlark"
+	"go.starlark.net/starlarkstruct"
+
+	"armature/store"
+)
+
+// BuildTeamsModule creates the "teams" module.
+// Always available to all extensions (no permission gate).
+func BuildTeamsModule(ctx context.Context, stores store.Stores) *starlarkstruct.Module {
+	return MakeModule("teams", starlark.StringDict{
+
+		"get_member_roles": starlark.NewBuiltin("teams.get_member_roles", func(
+			thread *starlark.Thread, b *starlark.Builtin,
+			args starlark.Tuple, kwargs []starlark.Tuple,
+		) (starlark.Value, error) {
+			var teamID, userID string
+			if err := starlark.UnpackPositionalArgs(b.Name(), args, kwargs, 2, &teamID, &userID); err != nil {
+				return nil, err
+			}
+
+			roles, err := stores.Teams.GetMemberRoles(ctx, teamID, userID)
+			if err != nil {
+				return starlark.NewList(nil), nil
+			}
+
+			elems := make([]starlark.Value, len(roles))
+			for i, r := range roles {
+				elems[i] = starlark.String(r)
+			}
+			return starlark.NewList(elems), nil
+		}),
+
+		"has_role": starlark.NewBuiltin("teams.has_role", func(
+			thread *starlark.Thread, b *starlark.Builtin,
+			args starlark.Tuple, kwargs []starlark.Tuple,
+		) (starlark.Value, error) {
+			var teamID, userID, role string
+			if err := starlark.UnpackPositionalArgs(b.Name(), args, kwargs, 3, &teamID, &userID, &role); err != nil {
+				return nil, err
+			}
+
+			has, err := stores.Teams.HasRole(ctx, teamID, userID, role)
+			if err != nil || !has {
+				return starlark.False, nil
+			}
+			return starlark.True, nil
+		}),
+	})
+}

server/sandbox/workflow_module.go

@@ -6,12 +6,13 @@ package sandbox
 // manage instances, and programmatically advance workflow stages.
 //
 // Starlark API:
-//   wf = workflow.get_definition(workflow_id)         # returns dict
+//   wf = workflow.get_definition(workflow_id)                            # returns dict
-//   inst = workflow.get_instance(instance_id)         # returns dict
+//   inst = workflow.get_instance(instance_id)                           # returns dict
-//   inst = workflow.start(workflow_id, data={})        # start new instance
+//   instances = workflow.list_instances(workflow_id)                     # list instances
-//   inst = workflow.advance(instance_id, data={})      # advance to next stage
+//   inst = workflow.start(workflow_id, data={})                          # start new instance
-//   workflow.cancel(instance_id)                       # cancel instance
+//   inst = workflow.advance(instance_id, data={})                        # advance to next stage
-//   instances = workflow.list_instances(workflow_id)    # list instances
+//   workflow.cancel(instance_id)                                         # cancel instance
+//   signoff = workflow.submit_signoff(instance_id, decision, comment="") # submit signoff
 
 import (
 	"context"
@@ -21,21 +22,37 @@ import (
 	"go.starlark.net/starlark"
 	"go.starlark.net/starlarkstruct"
 
+	"armature/models"
 	"armature/store"
 )
 
+// WorkflowEngine is the subset of the workflow engine needed by Starlark
+// write operations. Defined here (not in the workflow package) to avoid
+// circular imports — workflow imports sandbox for the Runner.
+type WorkflowEngine interface {
+	Start(ctx context.Context, workflowID string, initialData json.RawMessage, userID string) (*models.WorkflowInstance, error)
+	Advance(ctx context.Context, instanceID string, stageData json.RawMessage, userID string) (*models.WorkflowInstance, error)
+	Cancel(ctx context.Context, instanceID string, userID string) error
+	SubmitSignoff(ctx context.Context, instanceID, userID, decision, comment string) (*models.WorkflowSignoff, error)
+}
+
 // BuildWorkflowModule creates the "workflow" Starlark module for a package.
 // Requires the workflow.access permission.
 //
-// Mutating operations (start/advance/cancel) are available via HTTP API;
+// Read operations use stores directly. Write operations delegate to the
-// Starlark builtins for them will be added when the engine interface is
+// WorkflowEngine interface (engine may be nil if not wired — write builtins
-// extracted to a shared package to avoid circular imports.
+// return an error in that case).
-func BuildWorkflowModule(ctx context.Context, stores store.Stores) *starlarkstruct.Module {
+func BuildWorkflowModule(ctx context.Context, stores store.Stores, engine WorkflowEngine, rc *RunContext) *starlarkstruct.Module {
-	return MakeModule("workflow", starlark.StringDict{
+	members := starlark.StringDict{
 		"get_definition": starlark.NewBuiltin("workflow.get_definition", workflowGetDef(ctx, stores)),
 		"get_instance":   starlark.NewBuiltin("workflow.get_instance", workflowGetInstance(ctx, stores)),
 		"list_instances": starlark.NewBuiltin("workflow.list_instances", workflowListInstances(ctx, stores)),
-	})
+		"start":          starlark.NewBuiltin("workflow.start", workflowStart(ctx, engine, rc)),
+		"advance":        starlark.NewBuiltin("workflow.advance", workflowAdvance(ctx, engine, rc)),
+		"cancel":         starlark.NewBuiltin("workflow.cancel", workflowCancel(ctx, engine, rc)),
+		"submit_signoff": starlark.NewBuiltin("workflow.submit_signoff", workflowSubmitSignoff(ctx, engine, rc)),
+	}
+	return MakeModule("workflow", members)
 }
 
 func workflowGetDef(ctx context.Context, stores store.Stores) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
@@ -60,7 +77,7 @@ func workflowGetDef(ctx context.Context, stores store.Stores) func(*starlark.Thr
 			d.SetKey(starlark.String("ordinal"), starlark.MakeInt(s.Ordinal))
 			d.SetKey(starlark.String("stage_mode"), starlark.String(s.StageMode))
 			d.SetKey(starlark.String("audience"), starlark.String(s.Audience))
-			d.SetKey(starlark.String("stage_type"), starlark.String(s.StageType))
+			d.SetKey(starlark.String("stage_type"), starlark.String(s.StageType)) // deprecated — kept for backward compat
 			d.SetKey(starlark.String("auto_transition"), starlark.Bool(s.AutoTransition))
 			if s.StarlarkHook != nil {
 				d.SetKey(starlark.String("starlark_hook"), starlark.String(*s.StarlarkHook))
@@ -98,35 +115,51 @@ func workflowGetInstance(ctx context.Context, stores store.Stores) func(*starlar
 		if err != nil {
 			return starlark.None, fmt.Errorf("workflow.get_instance: %w", err)
 		}
-
+		return instanceToDict(inst), nil
-		d := starlark.NewDict(8)
-		d.SetKey(starlark.String("id"), starlark.String(inst.ID))
-		d.SetKey(starlark.String("workflow_id"), starlark.String(inst.WorkflowID))
-		d.SetKey(starlark.String("workflow_version"), starlark.MakeInt(inst.WorkflowVersion))
-		d.SetKey(starlark.String("current_stage"), starlark.String(inst.CurrentStage))
-		d.SetKey(starlark.String("status"), starlark.String(inst.Status))
-		d.SetKey(starlark.String("started_by"), starlark.String(inst.StartedBy))
-
-		// Parse stage_data into Starlark dict
-		var dataMap map[string]interface{}
-		if json.Unmarshal(inst.StageData, &dataMap) == nil {
-			starlarkData := starlark.NewDict(len(dataMap))
-			for k, v := range dataMap {
-				starlarkData.SetKey(starlark.String(k), goValToStarlark(v))
-			}
-			d.SetKey(starlark.String("stage_data"), starlarkData)
-		} else {
-			d.SetKey(starlark.String("stage_data"), starlark.NewDict(0))
-		}
-
-		if inst.EntryToken != nil {
-			d.SetKey(starlark.String("entry_token"), starlark.String(*inst.EntryToken))
-		}
-
-		return d, nil
 	}
 }
 
+// instanceToDict converts a WorkflowInstance to a Starlark dict.
+func instanceToDict(inst *models.WorkflowInstance) *starlark.Dict {
+	d := starlark.NewDict(8)
+	d.SetKey(starlark.String("id"), starlark.String(inst.ID))
+	d.SetKey(starlark.String("workflow_id"), starlark.String(inst.WorkflowID))
+	d.SetKey(starlark.String("workflow_version"), starlark.MakeInt(inst.WorkflowVersion))
+	d.SetKey(starlark.String("current_stage"), starlark.String(inst.CurrentStage))
+	d.SetKey(starlark.String("status"), starlark.String(inst.Status))
+	d.SetKey(starlark.String("started_by"), starlark.String(inst.StartedBy))
+
+	// Parse stage_data into Starlark dict
+	var dataMap map[string]interface{}
+	if json.Unmarshal(inst.StageData, &dataMap) == nil {
+		starlarkData := starlark.NewDict(len(dataMap))
+		for k, v := range dataMap {
+			starlarkData.SetKey(starlark.String(k), GoToStarlark(v))
+		}
+		d.SetKey(starlark.String("stage_data"), starlarkData)
+	} else {
+		d.SetKey(starlark.String("stage_data"), starlark.NewDict(0))
+	}
+
+	if inst.EntryToken != nil {
+		d.SetKey(starlark.String("entry_token"), starlark.String(*inst.EntryToken))
+	}
+	return d
+}
+
+// signoffToDict converts a WorkflowSignoff to a Starlark dict.
+func signoffToDict(s *models.WorkflowSignoff) *starlark.Dict {
+	d := starlark.NewDict(7)
+	d.SetKey(starlark.String("id"), starlark.String(s.ID))
+	d.SetKey(starlark.String("instance_id"), starlark.String(s.InstanceID))
+	d.SetKey(starlark.String("stage"), starlark.String(s.Stage))
+	d.SetKey(starlark.String("user_id"), starlark.String(s.UserID))
+	d.SetKey(starlark.String("decision"), starlark.String(s.Decision))
+	d.SetKey(starlark.String("comment"), starlark.String(s.Comment))
+	d.SetKey(starlark.String("created_at"), starlark.String(s.CreatedAt.Format("2006-01-02T15:04:05Z07:00")))
+	return d
+}
+
 func workflowListInstances(ctx context.Context, stores store.Stores) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
 	return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
 		var workflowID string
@@ -155,36 +188,113 @@ func workflowListInstances(ctx context.Context, stores store.Stores) func(*starl
 	}
 }
 
-// goValToStarlark converts a Go value to a Starlark value.
+// ── Instance Write API ──────────────
-func goValToStarlark(v interface{}) starlark.Value {
+
-	switch val := v.(type) {
+// workflowWriteGuard checks that the engine and user context are available.
-	case nil:
+func workflowWriteGuard(engine WorkflowEngine, rc *RunContext) error {
-		return starlark.None
+	if engine == nil {
-	case bool:
+		return fmt.Errorf("workflow engine not available")
-		return starlark.Bool(val)
+	}
-	case float64:
+	if rc == nil || rc.UserID == "" {
-		if val == float64(int(val)) {
+		return fmt.Errorf("workflow write operations require an authenticated user context")
-			return starlark.MakeInt(int(val))
+	}
+	return nil
+}
+
+// dictToJSON converts a Starlark dict to json.RawMessage.
+func dictToJSON(d *starlark.Dict) (json.RawMessage, error) {
+	m := DictToMap(d)
+	b, err := json.Marshal(m)
+	if err != nil {
+		return nil, err
+	}
+	return json.RawMessage(b), nil
+}
+
+func workflowStart(ctx context.Context, engine WorkflowEngine, rc *RunContext) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var workflowID string
+		data := starlark.NewDict(0)
+		if err := starlark.UnpackArgs("workflow.start", args, kwargs,
+			"workflow_id", &workflowID,
+			"data?", &data,
+		); err != nil {
+			return nil, err
 		}
-		return starlark.Float(val)
+		if err := workflowWriteGuard(engine, rc); err != nil {
-	case string:
+			return nil, fmt.Errorf("workflow.start: %w", err)
-		return starlark.String(val)
-	case map[string]interface{}:
-		d := starlark.NewDict(len(val))
-		for k, v := range val {
-			d.SetKey(starlark.String(k), goValToStarlark(v))
 		}
-		return d
+		dataJSON, err := dictToJSON(data)
-	case []interface{}:
+		if err != nil {
-		elems := make([]starlark.Value, len(val))
+			return nil, fmt.Errorf("workflow.start: marshal data: %w", err)
-		for i, v := range val {
-			elems[i] = goValToStarlark(v)
 		}
-		return starlark.NewList(elems)
+		inst, err := engine.Start(ctx, workflowID, dataJSON, rc.UserID)
-	default:
+		if err != nil {
-		return starlark.String(fmt.Sprintf("%v", v))
+			return nil, fmt.Errorf("workflow.start: %w", err)
+		}
+		return instanceToDict(inst), nil
 	}
 }
 
-// workflowRoute routes the workflow to a named stage.
+func workflowAdvance(ctx context.Context, engine WorkflowEngine, rc *RunContext) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
-// Starlark: workflow.route(instance_id, target_stage, reason)
+	return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var instanceID string
+		data := starlark.NewDict(0)
+		if err := starlark.UnpackArgs("workflow.advance", args, kwargs,
+			"instance_id", &instanceID,
+			"data?", &data,
+		); err != nil {
+			return nil, err
+		}
+		if err := workflowWriteGuard(engine, rc); err != nil {
+			return nil, fmt.Errorf("workflow.advance: %w", err)
+		}
+		dataJSON, err := dictToJSON(data)
+		if err != nil {
+			return nil, fmt.Errorf("workflow.advance: marshal data: %w", err)
+		}
+		inst, err := engine.Advance(ctx, instanceID, dataJSON, rc.UserID)
+		if err != nil {
+			return nil, fmt.Errorf("workflow.advance: %w", err)
+		}
+		return instanceToDict(inst), nil
+	}
+}
+
+func workflowCancel(ctx context.Context, engine WorkflowEngine, rc *RunContext) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var instanceID string
+		if err := starlark.UnpackPositionalArgs("workflow.cancel", args, kwargs, 1, &instanceID); err != nil {
+			return nil, err
+		}
+		if err := workflowWriteGuard(engine, rc); err != nil {
+			return nil, fmt.Errorf("workflow.cancel: %w", err)
+		}
+		if err := engine.Cancel(ctx, instanceID, rc.UserID); err != nil {
+			return nil, fmt.Errorf("workflow.cancel: %w", err)
+		}
+		return starlark.None, nil
+	}
+}
+
+func workflowSubmitSignoff(ctx context.Context, engine WorkflowEngine, rc *RunContext) func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var instanceID, decision string
+		comment := ""
+		if err := starlark.UnpackArgs("workflow.submit_signoff", args, kwargs,
+			"instance_id", &instanceID,
+			"decision", &decision,
+			"comment?", &comment,
+		); err != nil {
+			return nil, err
+		}
+		if err := workflowWriteGuard(engine, rc); err != nil {
+			return nil, fmt.Errorf("workflow.submit_signoff: %w", err)
+		}
+		signoff, err := engine.SubmitSignoff(ctx, instanceID, rc.UserID, decision, comment)
+		if err != nil {
+			return nil, fmt.Errorf("workflow.submit_signoff: %w", err)
+		}
+		return signoffToDict(signoff), nil
+	}
+}

server/sandbox/workflow_module_test.go

@@ -0,0 +1,262 @@
+package sandbox
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+	"time"
+
+	"go.starlark.net/starlark"
+
+	"armature/models"
+	"armature/store"
+)
+
+// ── Mock Engine ──────────────────────
+
+type mockWorkflowEngine struct {
+	startResult   *models.WorkflowInstance
+	advanceResult *models.WorkflowInstance
+	signoffResult *models.WorkflowSignoff
+
+	lastMethod     string
+	lastWorkflowID string
+	lastInstanceID string
+	lastUserID     string
+	lastData       json.RawMessage
+	lastDecision   string
+	lastComment    string
+}
+
+func (m *mockWorkflowEngine) Start(_ context.Context, workflowID string, data json.RawMessage, userID string) (*models.WorkflowInstance, error) {
+	m.lastMethod = "Start"
+	m.lastWorkflowID = workflowID
+	m.lastData = data
+	m.lastUserID = userID
+	return m.startResult, nil
+}
+
+func (m *mockWorkflowEngine) Advance(_ context.Context, instanceID string, data json.RawMessage, userID string) (*models.WorkflowInstance, error) {
+	m.lastMethod = "Advance"
+	m.lastInstanceID = instanceID
+	m.lastData = data
+	m.lastUserID = userID
+	return m.advanceResult, nil
+}
+
+func (m *mockWorkflowEngine) Cancel(_ context.Context, instanceID string, userID string) error {
+	m.lastMethod = "Cancel"
+	m.lastInstanceID = instanceID
+	m.lastUserID = userID
+	return nil
+}
+
+func (m *mockWorkflowEngine) SubmitSignoff(_ context.Context, instanceID, userID, decision, comment string) (*models.WorkflowSignoff, error) {
+	m.lastMethod = "SubmitSignoff"
+	m.lastInstanceID = instanceID
+	m.lastUserID = userID
+	m.lastDecision = decision
+	m.lastComment = comment
+	return m.signoffResult, nil
+}
+
+// ── Helpers ──────────────────────────
+
+func testInstance() *models.WorkflowInstance {
+	return &models.WorkflowInstance{
+		ID:              "inst-1",
+		WorkflowID:      "wf-1",
+		WorkflowVersion: 2,
+		CurrentStage:    "review",
+		Status:          "active",
+		StartedBy:       "user-1",
+		StageData:       json.RawMessage(`{"key":"val"}`),
+	}
+}
+
+func testSignoff() *models.WorkflowSignoff {
+	return &models.WorkflowSignoff{
+		ID:         "sig-1",
+		InstanceID: "inst-1",
+		Stage:      "review",
+		UserID:     "user-1",
+		Decision:   "approve",
+		Comment:    "LGTM",
+		CreatedAt:  time.Date(2026, 4, 3, 12, 0, 0, 0, time.UTC),
+	}
+}
+
+func runWorkflowScript(t *testing.T, engine WorkflowEngine, rc *RunContext, script string) (starlark.StringDict, error) {
+	t.Helper()
+	mod := BuildWorkflowModule(context.Background(), store.Stores{}, engine, rc)
+	predeclared := starlark.StringDict{"workflow": mod}
+	globals, err := starlark.ExecFile(&starlark.Thread{Name: "test"}, "test.star", script, predeclared)
+	return globals, err
+}
+
+// ── Tests ────────────────────────────
+
+func TestWorkflowStart(t *testing.T) {
+	mock := &mockWorkflowEngine{startResult: testInstance()}
+	rc := &RunContext{UserID: "user-1"}
+
+	globals, err := runWorkflowScript(t, mock, rc, `
+result = workflow.start("wf-1", data={"key": "val"})
+`)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if mock.lastMethod != "Start" {
+		t.Fatalf("expected Start, got %s", mock.lastMethod)
+	}
+	if mock.lastWorkflowID != "wf-1" {
+		t.Fatalf("expected wf-1, got %s", mock.lastWorkflowID)
+	}
+	if mock.lastUserID != "user-1" {
+		t.Fatalf("expected user-1, got %s", mock.lastUserID)
+	}
+
+	// Verify data was marshaled
+	var d map[string]interface{}
+	if err := json.Unmarshal(mock.lastData, &d); err != nil {
+		t.Fatal(err)
+	}
+	if d["key"] != "val" {
+		t.Fatalf("expected data key=val, got %v", d)
+	}
+
+	// Verify returned dict
+	result := globals["result"].(*starlark.Dict)
+	id, _, _ := result.Get(starlark.String("id"))
+	if id.(starlark.String).GoString() != "inst-1" {
+		t.Fatalf("expected id=inst-1, got %v", id)
+	}
+	status, _, _ := result.Get(starlark.String("status"))
+	if status.(starlark.String).GoString() != "active" {
+		t.Fatalf("expected status=active, got %v", status)
+	}
+}
+
+func TestWorkflowAdvance(t *testing.T) {
+	inst := testInstance()
+	inst.CurrentStage = "complete"
+	mock := &mockWorkflowEngine{advanceResult: inst}
+	rc := &RunContext{UserID: "user-1"}
+
+	globals, err := runWorkflowScript(t, mock, rc, `
+result = workflow.advance("inst-1", data={"step": 2})
+`)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if mock.lastMethod != "Advance" {
+		t.Fatalf("expected Advance, got %s", mock.lastMethod)
+	}
+	if mock.lastInstanceID != "inst-1" {
+		t.Fatalf("expected inst-1, got %s", mock.lastInstanceID)
+	}
+
+	result := globals["result"].(*starlark.Dict)
+	stage, _, _ := result.Get(starlark.String("current_stage"))
+	if stage.(starlark.String).GoString() != "complete" {
+		t.Fatalf("expected current_stage=complete, got %v", stage)
+	}
+}
+
+func TestWorkflowCancel(t *testing.T) {
+	mock := &mockWorkflowEngine{}
+	rc := &RunContext{UserID: "user-1"}
+
+	globals, err := runWorkflowScript(t, mock, rc, `
+result = workflow.cancel("inst-1")
+`)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if mock.lastMethod != "Cancel" {
+		t.Fatalf("expected Cancel, got %s", mock.lastMethod)
+	}
+	if mock.lastInstanceID != "inst-1" {
+		t.Fatalf("expected inst-1, got %s", mock.lastInstanceID)
+	}
+	if mock.lastUserID != "user-1" {
+		t.Fatalf("expected user-1, got %s", mock.lastUserID)
+	}
+
+	if globals["result"] != starlark.None {
+		t.Fatalf("expected None, got %v", globals["result"])
+	}
+}
+
+func TestWorkflowSubmitSignoff(t *testing.T) {
+	mock := &mockWorkflowEngine{signoffResult: testSignoff()}
+	rc := &RunContext{UserID: "user-1"}
+
+	globals, err := runWorkflowScript(t, mock, rc, `
+result = workflow.submit_signoff("inst-1", "approve", comment="LGTM")
+`)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if mock.lastMethod != "SubmitSignoff" {
+		t.Fatalf("expected SubmitSignoff, got %s", mock.lastMethod)
+	}
+	if mock.lastDecision != "approve" {
+		t.Fatalf("expected approve, got %s", mock.lastDecision)
+	}
+	if mock.lastComment != "LGTM" {
+		t.Fatalf("expected LGTM, got %s", mock.lastComment)
+	}
+
+	result := globals["result"].(*starlark.Dict)
+	decision, _, _ := result.Get(starlark.String("decision"))
+	if decision.(starlark.String).GoString() != "approve" {
+		t.Fatalf("expected decision=approve, got %v", decision)
+	}
+	comment, _, _ := result.Get(starlark.String("comment"))
+	if comment.(starlark.String).GoString() != "LGTM" {
+		t.Fatalf("expected comment=LGTM, got %v", comment)
+	}
+}
+
+func TestWorkflowWrite_NoUser(t *testing.T) {
+	mock := &mockWorkflowEngine{startResult: testInstance()}
+
+	_, err := runWorkflowScript(t, mock, nil, `
+result = workflow.start("wf-1")
+`)
+	if err == nil {
+		t.Fatal("expected error for nil RunContext")
+	}
+	if got := err.Error(); !contains(got, "authenticated user context") {
+		t.Fatalf("unexpected error: %s", got)
+	}
+}
+
+func TestWorkflowWrite_NoEngine(t *testing.T) {
+	rc := &RunContext{UserID: "user-1"}
+
+	_, err := runWorkflowScript(t, nil, rc, `
+result = workflow.start("wf-1")
+`)
+	if err == nil {
+		t.Fatal("expected error for nil engine")
+	}
+	if got := err.Error(); !contains(got, "engine not available") {
+		t.Fatalf("unexpected error: %s", got)
+	}
+}
+
+// contains is a test helper — strings.Contains without importing strings.
+func contains(s, substr string) bool {
+	for i := 0; i <= len(s)-len(substr); i++ {
+		if s[i:i+len(substr)] == substr {
+			return true
+		}
+	}
+	return false
+}