chore: update PR 332 tooling for capability model

.claude/agents/slopsmith-reviewer.md

@@ -7,7 +7,7 @@ model: sonnet
 
 # slopsmith-reviewer
 
-Plugin-aware reviewer for Slopsmith. Use when reviewing a plugin's code or manifest. Does **not** duplicate the built-in `peer-review` skill — focus is narrow: the plugin contract surface defined in [`docs/PLUGIN_AUTHORING.md`](../../docs/PLUGIN_AUTHORING.md) and enforced by [`schema/plugin.schema.json`](../../schema/plugin.schema.json) and `tests/test_plugin_schema.py`.
+Plugin-aware reviewer for Slopsmith. Use when reviewing a plugin's code or manifest. Does **not** duplicate the built-in `peer-review` skill — focus is narrow: the plugin contract surface defined in [`docs/PLUGIN_AUTHORING.md`](../../docs/PLUGIN_AUTHORING.md) and enforced by [`schema/plugin.schema.json`](../../schema/plugin.schema.json), including `capability-pipelines.v1` metadata, and `tests/test_plugin_schema.py`.
 
 ## When to invoke
 

.claude/rules/plugin-author.md

@@ -12,6 +12,7 @@ These rules apply only when editing files under `plugins/**`. They encode the co
 ## Manifest
 
 - **`plugin.json` is required** and must validate against [`schema/plugin.schema.json`](../../schema/plugin.schema.json). Required fields: `id`, `name`. The `id` must match the parent directory name (the loader keys discovery by directory; drift breaks plugin lookup).
+- **Capability-aware plugins declare intent** with `standards: ["capability-pipelines.v1"]` and redaction-safe `capabilities` / `ui` metadata. Legacy fields still work, but don't strip or reject native metadata when editing manifests.
 - **License must come from the curated allowlist** if the plugin is intended for the curated list. See [`CONTRIBUTING.md`](../../CONTRIBUTING.md) "Plugin licensing".
 - **`type: "visualization"`** requires a `script` field exporting `window.slopsmithViz_<id>`. See [`docs/plugin-visualization-contracts.md`](../../docs/plugin-visualization-contracts.md).
 

.claude/settings.json

@@ -5,7 +5,7 @@
   "hooks": {},
 
   "_commented_example_hooks": {
-    "_comment": "Copy the block below into the empty `hooks` object above if you want plugin.json edits to be auto-validated against schema/plugin.schema.json on save. Per-user opt-in; not enabled by default because hooks run in every Claude Code session that loads this repo.",
+    "_comment": "Copy the block below into the empty `hooks` object above if you want plugin.json edits to be auto-validated against schema/plugin.schema.json, including capability metadata, on save. Per-user opt-in; not enabled by default because hooks run in every Claude Code session that loads this repo.",
     "PostToolUse": [
       {
         "matcher": "Write|Edit",

.claude/skills/plugin-scaffold/SKILL.md

@@ -30,25 +30,31 @@ If the plugin slug or type is missing, ask once.
 
 **Common to all types:**
 
-- `plugins/<id>/plugin.json` — minimum schema-valid manifest. Set `id`, `name`, `version: "0.1.0"`, and `license: "AGPL-3.0-only"` by default (ask if a different license is desired).
+- `plugins/<id>/plugin.json` — schema-valid manifest. Set `id`, `name`, `version: "0.1.0"`, `license: "AGPL-3.0-only"`, and `standards: ["capability-pipelines.v1", "plugin-runtime-idempotent.v1"]` by default (ask if a different license is desired).
 
 **`type=visualization`** — adds:
 - `"type": "visualization"` and `"script": "screen.js"` to manifest
+- `"capabilities": { "visualization": { "roles": ["provider"], "operations": ["renderer.create", "renderer.destroy", "renderer.inspect"], "mode": "active", "compatibility": "shim-allowed", "ownership": "multi-provider", "safety": "safe", "version": 1 } }`
 - `screen.js` exporting `window.slopsmithViz_<id> = function () { return { contextType: '2d', init(canvas, bundle) { this.ctx = canvas.getContext('2d'); }, draw(bundle) { /* TODO */ }, destroy() {} }; };` plus a static `matchesArrangement` example commented out
 - `tests/browser/<id>.spec.ts` — Playwright stub that loads the app and asserts the plugin's factory is registered
 
 **`type=overlay`** — adds:
 - `"script": "screen.js"` to manifest (no `type` declared — overlays don't use the picker)
+- `"capabilities": { "ui.player-overlays": { "roles": ["provider"], "mode": "active", "compatibility": "shim-allowed", "ownership": "multi-provider", "safety": "safe", "version": 1 } }`
+- a matching `"ui"` contribution with a stable overlay id and redaction-safe label
 - `screen.js` scaffolding a navbar toggle, an own-canvas + own-rAF loop reading `highway.getNotes()` / `getChords()` / `getTime()`, and respecting `highway.isDefaultRenderer()` if using `highway.project` / `fretX`
 - `tests/browser/<id>.spec.ts` — toggle on / off test
 
 **`type=settings-only`** — adds:
 - `"settings": { "html": "settings.html" }` to manifest
+- `"settings_schema"` with a schema version and an empty `packable_keys` list
+- a `"ui"` settings contribution with a stable id
 - `settings.html` — empty form skeleton with explanatory comments
 - `screen.js` reading/writing `localStorage` keys prefixed with `<id>_`
 
 **`type=routes-only`** — adds:
 - `"routes": "routes.py"` to manifest
+- a conservative `"capabilities"` declaration only when the route participates in a known domain such as `library`, `jobs`, or `privileged-capabilities`; otherwise leave capability participation out and ask what workflow the route owns
 - `routes.py` with `def setup(app, context):` that registers one example route and uses `context["log"].info("plugin ready")` (never `print()`)
 - `tests/test_<id>_routes.py` — FastAPI TestClient stub
 
@@ -64,7 +70,7 @@ Then point the user at [`docs/PLUGIN_AUTHORING.md`](../../../docs/PLUGIN_AUTHORI
 
 ## Don'ts
 
-- Don't add fields to the manifest that aren't in the schema. If the user wants something custom, ask whether it should become a real field — that's a `schema/plugin.schema.json` change, not a plugin-local convention.
+- Don't invent plugin-local manifest conventions. If the user wants something custom, either express it through existing `capability-pipelines.v1` metadata or ask whether it should become a real schema field.
 - Don't scaffold a `requirements.txt` without confirming the deps. The plugin loader installs them on first load; an accidental dep slows everyone's startup.
 - Don't pre-fill `localStorage` keys without a prefix. Collisions across plugins are real.
 - Don't generate hidden side effects at import time (`screen.js` top level or `routes.py` top level). Keep all wiring inside the IIFE / `setup()`.

.claude/skills/plugin-validate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plugin-validate
-description: Validate a Slopsmith plugin's plugin.json against the schema and run structural checks. USE WHEN the user asks to validate a plugin, check the manifest, plugin.json errors, lint plugin, verify plugin structure, plugin license check, or audit plugin contract. Runs JSON Schema validation, file-existence checks for declared script/routes/settings.html/tour paths, and license-allowlist check.
+description: Validate a Slopsmith plugin's plugin.json against the schema and run structural checks. USE WHEN the user asks to validate a plugin, check the manifest, plugin.json errors, lint plugin, verify plugin structure, plugin license check, or audit plugin contract. Runs JSON Schema validation, capability metadata checks, file-existence checks for declared script/routes/settings.html/tour paths, and license-allowlist check.
 ---
 
 # plugin-validate
@@ -32,7 +32,7 @@ for path in sorted(glob.glob('plugins/*/plugin.json')):
     plugin_id = plugin_dir.name
     m = json.load(open(path))
     plugin_ok = True  # per-iteration flag so we don't print OK after a later FAIL
-    # 1. Schema
+    # 1. Schema, including capability-pipelines.v1 metadata
     try:
         jsonschema.validate(m, schema)
     except jsonschema.ValidationError as e:

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,7 +2,7 @@
 Thanks for the PR! A few quick reminders before you hit submit:
 - DCO sign-off on every commit (git commit -s; --amend -s to fix)
 - Plugin work? Check docs/PLUGIN_AUTHORING.md and validate plugin.json
-  against schema/plugin.schema.json
+  against schema/plugin.schema.json, including capability metadata
 - Touching the highway / player UI? Add or update a Playwright test
   under tests/browser/
 -->
@@ -23,7 +23,7 @@ Thanks for the PR! A few quick reminders before you hit submit:
 - [ ] `npm run test:js` passes locally
 - [ ] `npm test` (Playwright) passes locally — *or* CI will run it
 - [ ] Verified in `docker compose up` (live-reload working directory)
-- [ ] Plugin manifest validates against `schema/plugin.schema.json`
+- [ ] Plugin manifest validates against `schema/plugin.schema.json` (legacy fields + capability metadata)
 - [ ] Not applicable — explain below
 
 ## Screenshots / recordings

.github/copilot-instructions.md

@@ -14,8 +14,9 @@ This file customizes GitHub Copilot Chat and Copilot inline suggestions for the
 - **No frontend frameworks.** Vanilla JS, Canvas, Tailwind classes. Do not suggest React/Vue/Svelte additions.
 - **Plugin backend logging.** Suggest `context["log"]`, never `print()`.
 - **Plugin Python imports.** For cross-file backend plugins, suggest `context["load_sibling"]("module_name")` instead of bare `from module_name import X`.
+- **Capability metadata.** For new plugin integrations, suggest `standards: ["capability-pipelines.v1"]` and redaction-safe `capabilities` / `ui` metadata instead of legacy globals alone.
 - **DCO/license headers.** When creating a new file in the main repo, no license header is needed (the LICENSE file at root governs). Plugin authors should add an SPDX-License-Identifier comment to their plugin's source files; the `license` field in `plugin.json` must match the allowlist in [`CONTRIBUTING.md`](../CONTRIBUTING.md).
 
 ## Validation
 
-When suggesting changes to a `plugin.json`, validate against [`schema/plugin.schema.json`](../schema/plugin.schema.json).
+When suggesting changes to a `plugin.json`, validate against [`schema/plugin.schema.json`](../schema/plugin.schema.json). The schema accepts current legacy fields and native `capability-pipelines.v1` metadata.

.github/workflows/validate-plugins.yml

@@ -34,7 +34,7 @@ jobs:
           python -m pip install --upgrade pip
           pip install -r requirements-test.txt
 
-      - name: Validate every in-tree plugin.json against schema
+      - name: Validate every in-tree plugin.json against capability-aware schema
         run: |
           python - <<'PY'
           import glob, json, sys
@@ -66,7 +66,7 @@ jobs:
               sys.exit(1)
           PY
 
-      - name: Run schema sanity tests
+      - name: Run schema and capability contract tests
         # --noconftest skips tests/conftest.py, which imports structlog
         # (not in requirements-test.txt). The schema tests don't use
         # shared fixtures, so this is safe and avoids dragging the full

AGENTS.md

@@ -119,12 +119,14 @@ Slopsmith supports two:
 
 ## Plugin authoring — see [`docs/PLUGIN_AUTHORING.md`](docs/PLUGIN_AUTHORING.md)
 
-Plugins are the primary extension point. Each lives in `plugins/<name>/` with a `plugin.json` manifest. Curated plugins must be AGPL-3.0 or AGPL-compatible — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the allowlist. Manifest is validated in CI against [`schema/plugin.schema.json`](schema/plugin.schema.json).
+Plugins are the primary extension point. Each lives in `plugins/<name>/` with a `plugin.json` manifest. Curated plugins must be AGPL-3.0 or AGPL-compatible — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the allowlist. Manifest is validated in CI against [`schema/plugin.schema.json`](schema/plugin.schema.json), including `capability-pipelines.v1` metadata for native capability declarations.
 
 Topic | Doc
 --- | ---
 Manifest reference (`plugin.json` fields) | [`docs/plugin-manifest.md`](docs/plugin-manifest.md)
+Capability declarations (`standards`, `capabilities`, `ui`) | [`docs/plugin-manifest.md#capabilities`](docs/plugin-manifest.md#capabilities)
 Visualization (setRenderer / overlay / note-state) | [`docs/plugin-visualization-contracts.md`](docs/plugin-visualization-contracts.md)
+Plugin styles (`styles: "assets/plugin.css"`) | [`docs/plugin-styles.md`](docs/plugin-styles.md)
 Audio mixer fader registration | [`docs/plugin-audio-mixer.md`](docs/plugin-audio-mixer.md)
 Backend `context["log"]` logging | [`docs/plugin-logging.md`](docs/plugin-logging.md)
 Diagnostics opt-in (export bundle) | [`docs/plugin-diagnostics.md`](docs/plugin-diagnostics.md)
@@ -169,6 +171,7 @@ python -c "import json,glob,jsonschema; s=json.load(open('schema/plugin.schema.j
 - **No frontend frameworks.** Vanilla JS, fetch API, Tailwind classes. Don't add React/Vue/Svelte.
 - **Backend logging.** Plugin `routes.py` must use `context["log"]`, never `print()`. See [`docs/plugin-logging.md`](docs/plugin-logging.md).
 - **Plugin Python imports.** Multi-file backends use `context["load_sibling"]("<module>")`, not bare `from <module> import`. See [`docs/plugin-sibling-imports.md`](docs/plugin-sibling-imports.md).
+- **Capability metadata.** New plugin integrations should declare `standards: ["capability-pipelines.v1"]` plus redaction-safe `capabilities`/`ui` metadata rather than relying only on private globals.
 - **Spec-kit owns `.specify/` and `specs/`.** Don't modify those without explicit instruction; the `/speckit-*` skills own that surface.
 
 ## Tool-specific surfaces (optional reading)

docs/PLUGIN_AUTHORING.md

@@ -26,12 +26,16 @@ The minimum viable plugin is a `plugin.json` with just `id` and `name`. Everythi
 }
 ```
 
+Capability-aware plugins should also declare the `capability-pipelines.v1` standard and the domains they participate in. Legacy fields such as `nav`, `screen`, `settings`, `type: "visualization"`, shortcuts, overlays, and mixer faders still work, but native metadata lets diagnostics, the Capability Inspector, and migration tooling explain plugin behavior without scraping private globals.
+
 ## Topics
 
 | Topic | Doc | When to read |
 |---|---|---|
 | **Manifest reference** | [plugin-manifest.md](plugin-manifest.md) | Field-by-field reference for `plugin.json`. Read first. |
+| **Capability declarations** | [plugin-manifest.md#capabilities](plugin-manifest.md#capabilities) | Declaring provider/requester/observer intent with `capability-pipelines.v1`. |
 | **Visualization contracts** | [plugin-visualization-contracts.md](plugin-visualization-contracts.md) | Building a highway renderer (setRenderer), an overlay layer, or a note-state provider. |
+| **Plugin styles** | [plugin-styles.md](plugin-styles.md) | Shipping a plugin-owned prebuilt stylesheet via `styles: "assets/plugin.css"`. |
 | **Audio mixer faders** | [plugin-audio-mixer.md](plugin-audio-mixer.md) | Plugin produces audio outside the song `<audio>` element. |
 | **Backend logging** | [plugin-logging.md](plugin-logging.md) | Plugin has a `routes.py`. Use `context["log"]`, never `print()`. |
 | **Diagnostics contribution** | [plugin-diagnostics.md](plugin-diagnostics.md) | Adding plugin state to the Export Diagnostics bundle. |
@@ -45,6 +49,7 @@ The minimum viable plugin is a `plugin.json` with just `id` and `name`. Everythi
 ## General guidelines
 
 - Wrap your plugin code in an IIFE: `(function () { 'use strict'; ... })();`
+- Declare `standards: ["capability-pipelines.v1"]` and native `capabilities` when your plugin participates in a Slopsmith capability domain.
 - Use `localStorage` for user-facing settings, prefixed with your plugin id.
 - If hooking `window.playSong`, always call the original and `await` it.
 - If hooking `window.showScreen`, clean up your state when leaving the player screen.

docs/plugin-manifest.md

@@ -10,10 +10,12 @@ Every plugin lives in `plugins/<name>/` and must declare a `plugin.json` manifes
   "name": "My Plugin",
   "version": "1.0.0",
   "private": false,
+  "standards": ["capability-pipelines.v1", "plugin-runtime-idempotent.v1"],
   "type": "visualization",
   "nav": { "label": "My Plugin", "screen": "plugin-my_plugin" },
   "screen": "screen.html",
   "script": "screen.js",
+  "styles": "assets/plugin.css",
   "routes": "routes.py",
   "settings": {
     "html": "settings.html",
@@ -22,6 +24,24 @@ Every plugin lives in `plugins/<name>/` and must declare a `plugin.json` manifes
   "diagnostics": {
     "server_files": ["my_plugin.diag.json"],
     "callable": "diagnostics:collect"
+  },
+  "settings_schema": {
+    "schema_version": "1",
+    "packable_keys": ["enabled"]
+  },
+  "ui": {
+    "settings": [{ "id": "my-plugin-settings", "region": "plugin-settings", "label": "My Plugin" }]
+  },
+  "capabilities": {
+    "library": {
+      "roles": ["provider"],
+      "operations": ["query-page", "query-artists", "query-stats"],
+      "mode": "active",
+      "compatibility": "none",
+      "ownership": "multi-provider",
+      "safety": "safe",
+      "version": 1
+    }
   }
 }
 ```
@@ -46,6 +66,20 @@ Plain semver string. Advisory only — the plugin loader does not consume this.
 
 Advisory metadata for plugin authors. Not consumed by the loader.
 
+### `standards` (string[], optional)
+
+Versioned contracts the plugin participates in. New capability-aware plugins should declare `"capability-pipelines.v1"` when they include native `capabilities`, `ui`, `runtime_domains`, or related metadata.
+
+Declare `"plugin-runtime-idempotent.v1"` only when repeated script hydration cannot duplicate wrappers, listeners, timers, DOM roots, diagnostics contributors, jobs, media nodes, or capability participants.
+
+### `capability_api` (object, optional)
+
+Explicit capability API marker. Most plugins can use the compact `standards` form instead:
+
+```json
+{ "capability_api": { "standard": "capability-pipelines.v1", "version": 1 } }
+```
+
 ### `type` (string, optional — role hint, slopsmith#36)
 
 Supported values:
@@ -64,6 +98,10 @@ Path to HTML file (relative to plugin dir). Mounted at `#plugin-<id>` in the SPA
 
 Path to JS file (relative to plugin dir). Loaded via `<script>` tag in global scope. Wrap in an IIFE.
 
+### `styles` (string, optional)
+
+Path to a plugin-owned compiled stylesheet under `assets/`, for example `"assets/plugin.css"`. Use this when a plugin ships Tailwind utilities that core's prebuilt stylesheet cannot know about, especially arbitrary-value classes in runtime-installed plugins. The stylesheet must be built ahead of time with Tailwind `preflight: false`; Slopsmith injects one versioned `<link>` for the plugin. See [plugin-styles.md](plugin-styles.md).
+
 ### `routes` (string, optional)
 
 Path to Python file exporting `setup(app, context)`. See "Backend routes" below.
@@ -95,6 +133,77 @@ Path to Python file exporting `setup(app, context)`. See "Backend routes" below.
 
 See [plugin-diagnostics.md](plugin-diagnostics.md) for full diagnostics integration patterns.
 
+### `settings_schema` (object, optional)
+
+Redaction-safe settings metadata for support tooling and capability diagnostics. Use this to describe schema/version and packable key names; do not store user settings values, paths, tokens, or plugin-private payloads here.
+
+### `ui` / `ui_contributions` (object, optional)
+
+Native UI contribution declarations keyed by UI domain or surface. These let Slopsmith attribute plugin UI to stable contribution records while legacy `nav`, `screen`, `settings`, visualization picker entries, shortcuts, overlays, player panels, and tours continue to work through compatibility bridges.
+
+Example:
+
+```json
+{
+  "ui": {
+    "settings": [{ "id": "my-plugin-settings", "region": "plugin-settings", "label": "My Plugin" }],
+    "ui.player-overlays": [{ "id": "my-plugin-overlay", "region": "player.overlays.highway", "label": "My Overlay" }]
+  }
+}
+```
+
+Contribution ids must be stable and unique per plugin. Keep metadata redaction-safe: no settings values, DOM handles, local paths, callbacks, or private payloads.
+
+### `capabilities` (object, optional)
+
+Native `capability-pipelines.v1` declarations keyed by capability domain. They describe what the plugin owns, provides, requests, observes, or emits before the runtime script hydrates.
+
+```json
+{
+  "standards": ["capability-pipelines.v1"],
+  "capabilities": {
+    "library": {
+      "roles": ["provider"],
+      "operations": ["query-page", "query-artists", "query-stats", "tuning-names", "get-art", "sync-song"],
+      "description": "Adds a browsable library source.",
+      "mode": "active",
+      "compatibility": "none",
+      "ownership": "multi-provider",
+      "safety": "safe",
+      "version": 1
+    },
+    "playback": {
+      "roles": ["observer"],
+      "observes": ["loading", "ready", "stopped", "ended"],
+      "description": "Observes playback lifecycle without wrapping window.playSong.",
+      "mode": "active",
+      "compatibility": "shim-allowed",
+      "ownership": "observer-only",
+      "safety": "safe",
+      "version": 1
+    }
+  }
+}
+```
+
+Supported declaration fields include:
+
+- `roles`: `owner`, `coordinator`, `provider`, `observer`, `requester`, `transformer`, `handler`, `validator`, `short-circuiter`, `contributor`
+- `commands`, `operations`, `requests`, `observes`, `emits`, `events`: string arrays naming public commands, provider operations, or events
+- `kind`: `command`, `provider-coordinator`, `event`, `diagnostic`, `privileged`
+- `mode`: `active`, `optional`, `legacy-shim`, `disabled`
+- `compatibility`: `none`, `shim-allowed`, `degrade-noop`, `required`, `legacy-window-shim`
+- `ownership`: `exclusive-owner`, `multi-provider`, `observer-only`, `requester-only`, `privileged`, `diagnostic-only`
+- `safety`: `safe`, `privileged`, `sensitive`, `diagnostic-only`
+- `description` / `summary`: short redaction-safe text for local tooling
+- `version`: `1`
+
+Invalid capability metadata is rejected by schema validation and ignored by runtime capability tooling; legacy plugin fields still load through their existing app paths.
+
+### `runtime_domains` / `domains` (object, optional)
+
+Legacy bridge declarations for older runtime-domain metadata. Prefer `capabilities` for new native declarations.
+
 ### `license` (string, optional but recommended)
 
 SPDX identifier. For curated plugins, must be AGPL-3.0-or-later or AGPL-compatible (MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0). See [CONTRIBUTING.md](../CONTRIBUTING.md).
@@ -127,7 +236,7 @@ def setup(app, context):
 
 ## Validation
 
-Run the local validator skill `/plugin-validate` (Claude Code) or the CI workflow `.github/workflows/validate-plugins.yml`. Both consume [`schema/plugin.schema.json`](../schema/plugin.schema.json).
+Run the local validator skill `/plugin-validate` (Claude Code) or the CI workflow `.github/workflows/validate-plugins.yml`. Both consume [`schema/plugin.schema.json`](../schema/plugin.schema.json), including capability-pipelines metadata.
 
 ## Related
 

docs/plugin-manifest.schema.json

@@ -3,62 +3,363 @@
   "$id": "https://slopsmith.local/contracts/plugin-manifest-capabilities.schema.json",
   "title": "Slopsmith Plugin Manifest Capability Contract",
   "type": "object",
-  "required": ["id", "name"],
+  "required": [
+    "id",
+    "name"
+  ],
   "properties": {
-    "id": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9_.-]+$" },
+    "id": {
-    "name": { "type": "string", "minLength": 1 },
+      "type": "string",
-    "version": { "type": ["string", "null"] },
+      "minLength": 1,
-    "private": { "type": "boolean" },
+      "pattern": "^[A-Za-z0-9_.-]+$"
-    "standards": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "version": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "private": {
+      "type": "boolean"
+    },
+    "standards": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
     "capability_api": {
       "type": "object",
-      "properties": { "standard": { "const": "capability-pipelines.v1" }, "version": { "const": 1 } },
+      "properties": {
+        "standard": {
+          "const": "capability-pipelines.v1"
+        },
+        "version": {
+          "const": 1
+        }
+      },
       "additionalProperties": false
     },
     "capabilities": {
       "type": "object",
-      "propertyNames": { "$ref": "#/$defs/domainName" },
+      "propertyNames": {
-      "additionalProperties": { "$ref": "#/$defs/capabilityDeclaration" }
+        "$ref": "#/$defs/domainName"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/capabilityDeclaration"
+      }
     },
-    "ui_contributions": { "type": "object", "propertyNames": { "$ref": "#/$defs/domainName" }, "additionalProperties": { "$ref": "#/$defs/contributionList" } },
+    "ui_contributions": {
-    "ui": { "type": "object", "propertyNames": { "$ref": "#/$defs/domainName" }, "additionalProperties": { "$ref": "#/$defs/contributionList" } },
+      "type": "object",
-    "runtime_domains": { "type": "object", "propertyNames": { "$ref": "#/$defs/domainName" }, "additionalProperties": { "$ref": "#/$defs/domainDeclaration" } },
+      "propertyNames": {
-    "domains": { "type": "object", "propertyNames": { "$ref": "#/$defs/domainName" }, "additionalProperties": { "$ref": "#/$defs/domainDeclaration" } },
+        "$ref": "#/$defs/domainName"
-    "settings_schema": { "type": "object" },
+      },
-    "nav": {}, "screen": {}, "script": {}, "routes": {}, "settings": {}, "diagnostics": {}, "type": { "type": "string" }, "tour": {},
+      "additionalProperties": {
-    "description": { "type": "string", "description": "Short one-sentence summary of the plugin, surfaced on the v3 Pedalboard Plugins page (clamped to ~2 lines). Optional and additive." },
+        "$ref": "#/$defs/contributionList"
-    "category": { "type": "string", "description": "Which pedalboard the plugin sits on in the v3 Plugins page. Suggested values: 'audio', 'creation', 'practice', 'game', 'tools'. Free-form; unknown/absent values fall back to a curated default then 'other'. Optional and additive." },
+      }
-    "icon": { "type": "string", "minLength": 1, "pattern": "^assets/(?!.*\\.\\.)[^\\\\?#]+$", "description": "Plugin-root-relative path under assets/ (e.g. 'assets/thumb.png') to a thumbnail (~square, ~256x256 PNG/SVG) shown as the pedal graphic on the v3 Plugins page. Same containment rule as `styles`. If omitted, the loader auto-detects assets/thumb.png; failing that the UI shows a default pedal graphic. Optional and additive." },
+    },
-    "styles": { "type": "string", "minLength": 1, "pattern": "^assets/(?!.*\\.\\.)[^\\\\?#]+$", "description": "Plugin-root-relative path under assets/ (e.g. 'assets/plugin.css') to a compiled, preflight-off Tailwind stylesheet the frontend injects as a <link>. Must stay under assets/ with no '..', backslash, or query/fragment. See docs/plugin-styles.md." }
+    "ui": {
+      "type": "object",
+      "propertyNames": {
+        "$ref": "#/$defs/domainName"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/contributionList"
+      }
+    },
+    "runtime_domains": {
+      "type": "object",
+      "propertyNames": {
+        "$ref": "#/$defs/domainName"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/domainDeclaration"
+      }
+    },
+    "domains": {
+      "type": "object",
+      "propertyNames": {
+        "$ref": "#/$defs/domainName"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/domainDeclaration"
+      }
+    },
+    "settings_schema": {
+      "type": "object"
+    },
+    "nav": {},
+    "screen": {},
+    "script": {},
+    "routes": {},
+    "settings": {},
+    "diagnostics": {},
+    "type": {
+      "type": "string"
+    },
+    "tour": {},
+    "description": {
+      "type": "string",
+      "description": "Short one-sentence summary of the plugin, surfaced on the v3 Pedalboard Plugins page (clamped to ~2 lines). Optional and additive."
+    },
+    "category": {
+      "type": "string",
+      "description": "Which pedalboard the plugin sits on in the v3 Plugins page. Suggested values: 'audio', 'creation', 'practice', 'game', 'tools'. Free-form; unknown/absent values fall back to a curated default then 'other'. Optional and additive."
+    },
+    "icon": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^assets/(?!.*\\.\\.)[^\\\\?#]+$",
+      "description": "Plugin-root-relative path under assets/ (e.g. 'assets/thumb.png') to a thumbnail (~square, ~256x256 PNG/SVG) shown as the pedal graphic on the v3 Plugins page. Same containment rule as `styles`. If omitted, the loader auto-detects assets/thumb.png; failing that the UI shows a default pedal graphic. Optional and additive."
+    },
+    "styles": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^assets/(?!.*\\.\\.)[^\\\\?#]+$",
+      "description": "Plugin-root-relative path under assets/ (e.g. 'assets/plugin.css') to a compiled, preflight-off Tailwind stylesheet the frontend injects as a <link>. Must stay under assets/ with no '..', backslash, query, or fragment. See docs/plugin-styles.md."
+    }
   },
   "additionalProperties": true,
   "$defs": {
-    "domainName": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9_.:-]+$" },
+    "domainName": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[A-Za-z0-9_.:-]+$"
+    },
     "capabilityDeclaration": {
       "type": "object",
       "properties": {
-        "roles": { "type": "array", "items": { "enum": ["owner", "provider", "observer", "requester", "transformer", "handler", "validator", "short-circuiter", "contributor"] }, "uniqueItems": true },
+        "roles": {
-        "commands": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+          "type": "array",
-        "operations": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+          "items": {
-        "requests": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+            "enum": [
-        "observes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+              "owner",
-        "emits": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+              "coordinator",
-        "events": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+              "provider",
-        "kind": { "enum": ["command", "provider-coordinator", "event", "diagnostic", "privileged"] },
+              "observer",
-        "mode": { "enum": ["active", "optional", "legacy-shim", "disabled"] },
+              "requester",
-        "compatibility": { "enum": ["none", "shim-allowed", "degrade-noop", "required", "legacy-window-shim"] },
+              "transformer",
-        "ownership": { "enum": ["exclusive-owner", "multi-provider", "observer-only", "requester-only", "privileged", "diagnostic-only"] },
+              "handler",
-        "safety": { "enum": ["safe", "privileged", "sensitive", "diagnostic-only"] },
+              "validator",
-        "order": { "type": "object", "properties": { "fixed": { "type": "boolean" }, "before": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true }, "after": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true } }, "additionalProperties": false },
+              "short-circuiter",
-        "provider_policy": { "type": "object" },
+              "contributor"
-        "settings": { "type": "array", "description": "Declarative per-instance control descriptors (toggle / range / select) a participant exposes for a consuming host to render generically. Domain-agnostic in shape; how a host applies a chosen value is defined by each capability domain's contract (the visualization domain requires an applySetting(key, value) method on the renderer instance).", "items": { "type": "object", "required": ["key", "type"], "properties": { "key": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "type": { "enum": ["toggle", "range", "select"] }, "default": {}, "min": { "type": "number" }, "max": { "type": "number" }, "step": { "type": "number" }, "options": { "type": "array", "items": { "type": "object", "required": ["id"], "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } },
+            ]
-        "description": { "type": "string" },
+          },
-        "summary": { "type": "string" },
+          "uniqueItems": true
-        "version": { "const": 1 }
+        },
+        "commands": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "operations": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "requests": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "observes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "emits": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "events": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "kind": {
+          "enum": [
+            "command",
+            "provider-coordinator",
+            "event",
+            "diagnostic",
+            "privileged"
+          ]
+        },
+        "mode": {
+          "enum": [
+            "active",
+            "optional",
+            "legacy-shim",
+            "disabled"
+          ]
+        },
+        "compatibility": {
+          "enum": [
+            "none",
+            "shim-allowed",
+            "degrade-noop",
+            "required",
+            "legacy-window-shim"
+          ]
+        },
+        "ownership": {
+          "enum": [
+            "exclusive-owner",
+            "multi-provider",
+            "observer-only",
+            "requester-only",
+            "privileged",
+            "diagnostic-only"
+          ]
+        },
+        "safety": {
+          "enum": [
+            "safe",
+            "privileged",
+            "sensitive",
+            "diagnostic-only"
+          ]
+        },
+        "order": {
+          "type": "object",
+          "properties": {
+            "fixed": {
+              "type": "boolean"
+            },
+            "before": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              },
+              "uniqueItems": true
+            },
+            "after": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              },
+              "uniqueItems": true
+            }
+          },
+          "additionalProperties": false
+        },
+        "provider_policy": {
+          "type": "object"
+        },
+        "description": {
+          "type": "string"
+        },
+        "summary": {
+          "type": "string"
+        },
+        "version": {
+          "const": 1
+        }
       },
       "additionalProperties": false
     },
-    "domainDeclaration": { "oneOf": [{ "type": "object", "properties": { "role": { "type": "string", "minLength": 1 }, "roles": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "ownership": { "enum": ["exclusive-owner", "multi-provider", "observer-only", "requester-only", "privileged", "diagnostic-only"] }, "safety": { "enum": ["safe", "privileged", "sensitive", "diagnostic-only"] }, "legacy_source": { "type": "string", "minLength": 1 } }, "additionalProperties": true }, { "type": "array" }] },
+    "domainDeclaration": {
-    "contributionList": { "type": "array", "items": { "type": "object", "required": ["id"], "properties": { "id": { "type": "string", "minLength": 1 }, "region": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "order": { "type": ["number", "integer", "string"] } }, "additionalProperties": true } }
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "role": {
+              "type": "string",
+              "minLength": 1
+            },
+            "roles": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "ownership": {
+              "enum": [
+                "exclusive-owner",
+                "multi-provider",
+                "observer-only",
+                "requester-only",
+                "privileged",
+                "diagnostic-only"
+              ]
+            },
+            "safety": {
+              "enum": [
+                "safe",
+                "privileged",
+                "sensitive",
+                "diagnostic-only"
+              ]
+            },
+            "legacy_source": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": true
+        },
+        {
+          "type": "array"
+        }
+      ]
+    },
+    "contributionList": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "region": {
+            "type": "string",
+            "minLength": 1
+          },
+          "label": {
+            "type": "string"
+          },
+          "order": {
+            "type": [
+              "number",
+              "integer",
+              "string"
+            ]
+          }
+        },
+        "additionalProperties": true
+      }
+    }
   }
 }

plugins/__init__.py

@@ -238,7 +238,7 @@ def _normalize_manifest_sequence(value) -> list:
 
 _CAPABILITY_STANDARD = "capability-pipelines.v1"
 _VALID_CAPABILITY_ROLES = {
-    "owner", "provider", "observer", "requester", "transformer", "handler",
+    "owner", "coordinator", "provider", "observer", "requester", "transformer", "handler",
     "validator", "short-circuiter", "contributor",
 }
 _VALID_CAPABILITY_MODES = {"active", "optional", "legacy-shim", "disabled"}

schema/plugin.schema.json

@@ -1,16 +1,16 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/byrongamatos/slopsmith/blob/main/schema/plugin.schema.json",
+  "$id": "https://github.com/slopsmith/slopsmith/blob/main/schema/plugin.schema.json",
   "title": "Slopsmith plugin manifest",
-  "description": "Schema for plugins/<id>/plugin.json. See docs/plugin-manifest.md for prose. License enum mirrors the curated-plugin allowlist in CONTRIBUTING.md (keep them in sync; tests/test_plugin_schema.py asserts subset).",
+  "description": "Schema for plugins/<id>/plugin.json. See docs/plugin-manifest.md for prose. License enum mirrors the curated-plugin allowlist in CONTRIBUTING.md (keep them in sync; tests/test_plugin_schema.py asserts subset). Capability metadata follows capability-pipelines.v1 and is intentionally additive.",
   "type": "object",
-  "additionalProperties": false,
+  "additionalProperties": true,
   "required": ["id", "name"],
   "properties": {
     "id": {
       "type": "string",
-      "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$",
+      "pattern": "^[A-Za-z0-9_.-]+$",
-      "description": "Snake-case identifier. Used to namespace localStorage, the plugin screen id (plugin-<id>), the backend logger (slopsmith.plugin.<id>), and the diagnostics bundle directory. Reverse-DNS form (com.example.foo) is supported via the load_sibling encoding."
+      "description": "Plugin identifier. Snake_case is preferred for bundled plugins. Used to namespace localStorage, the plugin screen id (plugin-<id>), the backend logger (slopsmith.plugin.<id>), and the diagnostics bundle directory. Reverse-DNS form (com.example.foo) is supported via the load_sibling encoding."
     },
     "name": {
       "type": "string",
@@ -18,13 +18,28 @@
       "description": "Human-readable name shown in UI surfaces."
     },
     "version": {
-      "type": "string",
+      "type": ["string", "null"],
       "description": "Plain semver string. Advisory only; the plugin loader does not consume this."
     },
     "private": {
       "type": "boolean",
       "description": "Advisory metadata for plugin authors. Not consumed by the loader."
     },
+    "standards": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "Versioned standards the plugin participates in. Use capability-pipelines.v1 for native capability metadata and plugin-runtime-idempotent.v1 only when repeated hydration cannot duplicate runtime work."
+    },
+    "capability_api": {
+      "type": "object",
+      "properties": {
+        "standard": { "const": "capability-pipelines.v1" },
+        "version": { "const": 1 }
+      },
+      "additionalProperties": false,
+      "description": "Optional explicit capability API version marker. The standards array is the preferred compact form."
+    },
     "bundled": {
       "type": "boolean",
       "description": "True for plugins shipped in-tree with Slopsmith. Used by tooling that distinguishes built-in plugins from user-installed ones."
@@ -72,6 +87,12 @@
       "type": "string",
       "description": "Relative path to JS loaded in global scope on page load. Wrap your code in an IIFE."
     },
+    "styles": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^assets/(?!.*\\.\\.)[^\\\\?#]+$",
+      "description": "Plugin-root-relative path under assets/ (e.g. 'assets/plugin.css') to a compiled, preflight-off Tailwind stylesheet the frontend injects as a <link>. Must stay under assets/ with no '..', backslash, query, or fragment. See docs/plugin-styles.md."
+    },
     "routes": {
       "type": "string",
       "description": "Relative path to Python module exporting setup(app, context). See docs/plugin-manifest.md."
@@ -120,6 +141,50 @@
         }
       },
       "description": "Opt-in for the Export Diagnostics bundle (slopsmith#166). See docs/plugin-diagnostics.md."
+    },
+    "settings_schema": {
+      "type": "object",
+      "description": "Redaction-safe settings metadata used by capability diagnostics and backup/import tooling. Do not store actual settings values here."
+    },
+    "capabilities": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/domainName" },
+      "additionalProperties": { "$ref": "#/$defs/capabilityDeclaration" },
+      "description": "Native capability-pipelines.v1 declarations keyed by capability domain."
+    },
+    "ui_contributions": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/domainName" },
+      "additionalProperties": { "$ref": "#/$defs/contributionList" },
+      "description": "Native UI contribution declarations keyed by UI domain."
+    },
+    "ui": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/domainName" },
+      "additionalProperties": { "$ref": "#/$defs/contributionList" },
+      "description": "Alias for UI contribution declarations used by current first-party plugin manifests."
+    },
+    "runtime_domains": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/domainName" },
+      "additionalProperties": { "$ref": "#/$defs/domainDeclaration" },
+      "description": "Legacy-to-capability bridge declarations for runtime domains. Prefer capabilities for new native declarations."
+    },
+    "domains": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/domainName" },
+      "additionalProperties": { "$ref": "#/$defs/domainDeclaration" },
+      "description": "Legacy runtime-domain declaration alias. Prefer capabilities for new native declarations."
+    },
+    "privileged_capabilities": {
+      "type": "array",
+      "items": { "type": "object" },
+      "description": "Manifest-derived privileged workflow summaries. The privileged-capabilities host validates detailed semantics at runtime."
+    },
+    "privileged_compatibility_bridges": {
+      "type": "array",
+      "items": { "type": "object" },
+      "description": "Diagnostics-only compatibility bridge declarations for privileged legacy surfaces."
     }
   },
   "allOf": [
@@ -128,5 +193,79 @@
       "if": { "properties": { "type": { "const": "visualization" } }, "required": ["type"] },
       "then": { "required": ["script"] }
     }
-  ]
+  ],
+  "$defs": {
+    "domainName": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[A-Za-z0-9_.:-]+$"
+    },
+    "capabilityDeclaration": {
+      "type": "object",
+      "properties": {
+        "roles": {
+          "type": "array",
+          "items": {
+            "enum": ["owner", "coordinator", "provider", "observer", "requester", "transformer", "handler", "validator", "short-circuiter", "contributor"]
+          },
+          "uniqueItems": true
+        },
+        "commands": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "operations": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "requests": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "observes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "emits": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "events": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "kind": { "enum": ["command", "provider-coordinator", "event", "diagnostic", "privileged"] },
+        "mode": { "enum": ["active", "optional", "legacy-shim", "disabled"] },
+        "compatibility": { "enum": ["none", "shim-allowed", "degrade-noop", "required", "legacy-window-shim"] },
+        "ownership": { "enum": ["exclusive-owner", "multi-provider", "observer-only", "requester-only", "privileged", "diagnostic-only"] },
+        "safety": { "enum": ["safe", "privileged", "sensitive", "diagnostic-only"] },
+        "order": {
+          "type": "object",
+          "properties": {
+            "fixed": { "type": "boolean" },
+            "before": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+            "after": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true }
+          },
+          "additionalProperties": false
+        },
+        "provider_policy": { "type": "object" },
+        "description": { "type": "string" },
+        "summary": { "type": "string" },
+        "version": { "const": 1 }
+      },
+      "additionalProperties": false
+    },
+    "domainDeclaration": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "role": { "type": "string", "minLength": 1 },
+            "roles": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+            "ownership": { "enum": ["exclusive-owner", "multi-provider", "observer-only", "requester-only", "privileged", "diagnostic-only"] },
+            "safety": { "enum": ["safe", "privileged", "sensitive", "diagnostic-only"] },
+            "legacy_source": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": true
+        },
+        { "type": "array" }
+      ]
+    },
+    "contributionList": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "region": { "type": "string", "minLength": 1 },
+          "label": { "type": "string" },
+          "order": { "type": ["number", "integer", "string"] }
+        },
+        "additionalProperties": true
+      }
+    }
+  }
 }

tests/test_plugin_schema.py

@@ -1,6 +1,6 @@
 """Plugin manifest schema sanity tests.
 
-Three independent guarantees:
+Four independent guarantees:
 
 1. `schema/plugin.schema.json` is itself a well-formed JSON Schema
    (Draft 2020-12) and accepts every in-tree `plugins/*/plugin.json`.
@@ -13,10 +13,13 @@ Three independent guarantees:
    and update the schema enum to match — these two files must stay in
    sync because the same allowlist is referenced from both human-facing
    docs and from CI manifest validation.
+4. The schema accepts capability-pipelines.v1 manifest metadata so
+    native capability declarations are not blocked by legacy-only tooling.
 """
 
 from __future__ import annotations
 
+import ast
 import glob
 import json
 import re
@@ -28,8 +31,11 @@ import pytest
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 SCHEMA_PATH = REPO_ROOT / "schema" / "plugin.schema.json"
+DOCS_SCHEMA_PATH = REPO_ROOT / "docs" / "plugin-manifest.schema.json"
 CONTRIBUTING_PATH = REPO_ROOT / "CONTRIBUTING.md"
 PLUGINS_GLOB = str(REPO_ROOT / "plugins" / "*" / "plugin.json")
+BACKEND_CAPABILITIES_PATH = REPO_ROOT / "plugins" / "__init__.py"
+FRONTEND_CAPABILITIES_PATH = REPO_ROOT / "static" / "capabilities.js"
 
 
 @pytest.fixture(scope="module")
@@ -38,11 +44,83 @@ def schema() -> dict:
         return json.load(f)
 
 
+@pytest.fixture(scope="module")
+def docs_schema() -> dict:
+    with DOCS_SCHEMA_PATH.open() as f:
+        return json.load(f)
+
+
 def test_schema_is_well_formed(schema: dict) -> None:
     """The schema file must itself validate as a Draft 2020-12 schema."""
     jsonschema.Draft202012Validator.check_schema(schema)
 
 
+def test_schema_contains_capability_contract(schema: dict) -> None:
+    """The published schema must keep capability-pipelines.v1 fields first-class."""
+    assert schema["properties"]["standards"]["items"]["type"] == "string"
+    assert schema["properties"]["capabilities"]["additionalProperties"]["$ref"] == "#/$defs/capabilityDeclaration"
+    declaration = schema["$defs"]["capabilityDeclaration"]
+    assert "owner" in declaration["properties"]["roles"]["items"]["enum"]
+    assert "provider-coordinator" in declaration["properties"]["kind"]["enum"]
+    assert declaration["properties"]["operations"]["items"]["type"] == "string"
+    assert declaration["properties"]["requests"]["items"]["type"] == "string"
+    assert declaration["properties"]["observes"]["items"]["type"] == "string"
+    assert "exclusive-owner" in declaration["properties"]["ownership"]["enum"]
+    assert "diagnostic-only" in declaration["properties"]["safety"]["enum"]
+    assert "styles" in schema["properties"]
+    assert schema["properties"]["styles"]["pattern"].startswith("^assets/")
+
+
+def test_docs_schema_capability_contract_matches_ci_schema(schema: dict, docs_schema: dict) -> None:
+    """The docs copy and CI schema must not drift on capability vocabulary."""
+    def without_descriptions(value):
+        if isinstance(value, dict):
+            return {key: without_descriptions(item) for key, item in value.items() if key != "description"}
+        if isinstance(value, list):
+            return [without_descriptions(item) for item in value]
+        return value
+
+    for key in ("standards", "capability_api", "capabilities", "ui", "ui_contributions", "runtime_domains", "domains", "settings_schema", "styles"):
+        assert without_descriptions(docs_schema["properties"][key]) == without_descriptions(schema["properties"][key])
+    assert without_descriptions(docs_schema["$defs"]["domainName"]) == without_descriptions(schema["$defs"]["domainName"])
+    assert without_descriptions(docs_schema["$defs"]["capabilityDeclaration"]) == without_descriptions(schema["$defs"]["capabilityDeclaration"])
+    assert without_descriptions(docs_schema["$defs"]["domainDeclaration"]) == without_descriptions(schema["$defs"]["domainDeclaration"])
+    assert without_descriptions(docs_schema["$defs"]["contributionList"]) == without_descriptions(schema["$defs"]["contributionList"])
+
+
+def _python_constant_set(name: str) -> set[str]:
+    module = ast.parse(BACKEND_CAPABILITIES_PATH.read_text(encoding="utf-8"))
+    for node in module.body:
+        if isinstance(node, ast.Assign) and any(isinstance(target, ast.Name) and target.id == name for target in node.targets):
+            value = ast.literal_eval(node.value)
+            return set(value)
+    pytest.fail(f"Backend capability constant {name} not found")
+
+
+def _frontend_constant_set(name: str) -> set[str]:
+    text = FRONTEND_CAPABILITIES_PATH.read_text(encoding="utf-8")
+    match = re.search(rf"const\s+{re.escape(name)}\s*=\s*new\s+Set\(\s*\[(.*?)\]\s*\)", text, re.S)
+    if not match:
+        pytest.fail(f"Frontend capability constant {name} not found")
+    return set(re.findall(r"['\"]([^'\"]+)['\"]", match.group(1)))
+
+
+def test_capability_schema_vocabulary_matches_runtime_constants(schema: dict) -> None:
+    """Schema enums should evolve with backend and frontend capability validators."""
+    declaration = schema["$defs"]["capabilityDeclaration"]["properties"]
+    checks = [
+        (set(declaration["roles"]["items"]["enum"]), "_VALID_CAPABILITY_ROLES", "VALID_ROLES"),
+        (set(declaration["mode"]["enum"]), "_VALID_CAPABILITY_MODES", "VALID_MODES"),
+        (set(declaration["compatibility"]["enum"]), "_VALID_CAPABILITY_COMPATIBILITY", "VALID_COMPATIBILITY"),
+        (set(declaration["ownership"]["enum"]), "_VALID_CAPABILITY_OWNERSHIP", "VALID_OWNERSHIP"),
+        (set(declaration["kind"]["enum"]), "_VALID_CAPABILITY_KINDS", "VALID_DOMAIN_KINDS"),
+        (set(declaration["safety"]["enum"]), "_VALID_CAPABILITY_SAFETY", "VALID_SAFETY"),
+    ]
+    for schema_values, backend_name, frontend_name in checks:
+        assert schema_values == _python_constant_set(backend_name)
+        assert schema_values == _frontend_constant_set(frontend_name)
+
+
 @pytest.mark.parametrize("manifest_path", sorted(glob.glob(PLUGINS_GLOB)))
 def test_in_tree_manifest_validates(manifest_path: str, schema: dict) -> None:
     """Every plugin.json under plugins/ must pass schema validation."""
@@ -64,6 +142,78 @@ def test_in_tree_manifest_id_matches_directory(manifest_path: str) -> None:
     )
 
 
+def test_capability_manifest_metadata_validates(schema: dict) -> None:
+    """Capability-aware manifests should validate alongside legacy plugin fields."""
+    manifest = {
+        "id": "capability_example",
+        "name": "Capability Example",
+        "version": "0.1.0",
+        "standards": ["capability-pipelines.v1", "plugin-runtime-idempotent.v1"],
+        "script": "screen.js",
+        "settings": {"html": "settings.html"},
+        "settings_schema": {
+            "schema_version": "1",
+            "packable_keys": ["enabled"],
+        },
+        "ui": {
+            "settings": [{"id": "capability-example-settings", "region": "plugin-settings", "label": "Capability Example"}],
+        },
+        "capabilities": {
+            "library": {
+                "roles": ["provider"],
+                "kind": "provider-coordinator",
+                "operations": ["query-page", "query-artists", "query-stats"],
+                "description": "Provides a browsable library source.",
+                "mode": "active",
+                "compatibility": "none",
+                "ownership": "multi-provider",
+                "safety": "safe",
+                "version": 1,
+            },
+            "playback": {
+                "roles": ["observer"],
+                "observes": ["ready", "stopped"],
+                "mode": "active",
+                "compatibility": "shim-allowed",
+                "ownership": "observer-only",
+                "safety": "safe",
+                "version": 1,
+            },
+        },
+    }
+    jsonschema.validate(manifest, schema)
+
+
+def test_current_capability_and_styles_manifests_validate(schema: dict) -> None:
+    """Validate real manifests that exercise the capability and styles surfaces."""
+    for relpath in [
+        "plugins/capability_inspector/plugin.json",
+        "plugins/highway_3d/plugin.json",
+    ]:
+        with (REPO_ROOT / relpath).open() as f:
+            jsonschema.validate(json.load(f), schema)
+
+
+def test_invalid_capability_metadata_fails_schema(schema: dict) -> None:
+    """Schema validation should still catch malformed native declarations."""
+    manifest = {
+        "id": "bad_capability_example",
+        "name": "Bad Capability Example",
+        "standards": ["capability-pipelines.v1"],
+        "capabilities": {
+            "library": {
+                "roles": ["admin"],
+                "mode": "active",
+                "compatibility": "none",
+                "safety": "safe",
+                "version": 1,
+            },
+        },
+    }
+    with pytest.raises(jsonschema.ValidationError):
+        jsonschema.validate(manifest, schema)
+
+
 def _extract_allowlist_from_contributing() -> set[str]:
     """Pull the curated-license allowlist out of CONTRIBUTING.md.