redact: replace psarc/Rocksmith/official DLC references with neutral terms

Signed-off-by: barlind <tobias@barlind.se>

.claude/README.md

@@ -0,0 +1,42 @@
+# `.claude/` — Claude Code surfaces
+
+This directory holds [Claude Code](https://claude.ai/code) artifacts: skills, rules, and subagents. **Other AI tools** (Cursor, Copilot, Codex, Aider) should read [`AGENTS.md`](../AGENTS.md) instead — `.claude/` is Claude-Code-specific.
+
+## Layout
+
+```text
+.claude/
+├── agents/                            Subagents (invoked via @<name>)
+│   └── slopsmith-reviewer.md          Plugin-aware code review
+├── rules/                             Globs-scoped behaviour rules
+│   └── plugin-author.md               Rules that fire when editing plugins/**
+├── skills/                            Skills (description triggers auto-invocation)
+│   ├── plugin-scaffold/SKILL.md       Generate a new plugin skeleton
+│   ├── plugin-validate/SKILL.md       Validate a plugin.json against the schema
+│   └── speckit-*/                     Spec-kit skills (auto-generated; don't edit)
+├── settings.json                      Repo defaults (no hooks enabled by default)
+└── README.md                          You are here
+```
+
+## Conventions
+
+- **Spec-kit owns `skills/speckit-*`.** Don't edit those manually — they're regenerated by the spec-kit installer (`.specify/`).
+- **Repo skills live alongside spec-kit skills** in `skills/`. New skills should have a kebab-case directory name and a `SKILL.md` with YAML frontmatter.
+- **Hooks are off by default.** Hooks in `.claude/settings.json` run in every contributor's Claude Code session — enabling one imposes work on everyone. The settings file ships with `hooks: {}` and a commented example so anyone who wants to opt in can copy it locally.
+- **Subagent invocation.** Use `@slopsmith-reviewer` to invoke a subagent explicitly. Plain auto-routing isn't currently configured.
+
+## Adding a new skill
+
+1. Create `.claude/skills/<kebab-name>/SKILL.md`.
+2. YAML frontmatter must include `name` (must match directory) and `description` (must read like a sentence — Claude Code matches the description against user intent for auto-invocation).
+3. Body: instructions Claude follows when the skill triggers. Keep it concrete and short — long skills bit-rot.
+
+## Adding a new rule
+
+1. Create `.claude/rules/<topic>.md`.
+2. Frontmatter may include `globs:` (array of glob patterns scoping when the rule applies). Without `globs`, the rule loads for every session.
+3. Body: terse, imperative guidance — "always do X", "never do Y", "if you see Z, …".
+
+## Why so little here?
+
+The maintainer's personal Claude Code rules (context-mode routing, RTK, `@git-worker`, etc.) deliberately do **not** live in this repo. Those are user-global concerns in `~/.claude/` — keeping them out of the repo keeps the shared surface lean and makes the repo equally useful to contributors using Cursor, Copilot, plain editors, etc.

.claude/agents/slopsmith-reviewer.md

@@ -0,0 +1,68 @@
+---
+name: slopsmith-reviewer
+description: Plugin-aware code reviewer for Slopsmith. USE WHEN reviewing plugin changes, auditing a plugin against the manifest contract, checking that a plugin uses capability metadata / load_sibling / context["log"] correctly, or verifying that a `plugin.json` matches the schema and the directory it lives in. Returns a structured pass/fail report with specific file:line citations.
+tools: Read, Grep, Glob, Bash
+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), including `capability-pipelines.v1` metadata, and `tests/test_plugin_schema.py`.
+
+## When to invoke
+
+Use this agent when the user asks to:
+- "review this plugin"
+- "audit `plugins/<id>/`"
+- "check the manifest"
+- "verify the plugin uses load_sibling / logging correctly"
+- "lint plugin"
+
+Do **not** invoke for general code review — use the built-in `peer-review` skill for that.
+
+## Inputs
+
+The user typically points at a directory: `plugins/<id>/`. If no directory is given, ask which plugin to review.
+
+## Checklist (every review must run these)
+
+Run each item; structure the output as `PASS` / `FAIL` / `N/A` with file:line citations.
+
+1. **Manifest exists and validates.** `plugins/<id>/plugin.json` exists. Run:
+   ```bash
+   python -c "import json,jsonschema; s=json.load(open('schema/plugin.schema.json')); jsonschema.validate(json.load(open('plugins/<id>/plugin.json')), s); print('OK')"
+   ```
+2. **Manifest `id` matches the directory name.** `tests/test_plugin_schema.py::test_in_tree_manifest_id_matches_directory` enforces this — but call it out in review.
+3. **Declared plugin files exist.** For plugin-root-relative file fields (`script`, `routes`, `tour`, `settings.html`), `test -f plugins/<id>/<path>` must succeed.
+4. **License is on the curated allowlist** if present. Cross-check `plugin.json.license` against the SPDX list in [`CONTRIBUTING.md`](../../CONTRIBUTING.md) "Plugin licensing".
+5. **`type: "visualization"` ↔ `window.slopsmithViz_<id>` factory.** If `type == "visualization"`, grep `script` for the factory declaration.
+6. **Backend logging.** Grep `plugins/<id>/*.py` for `print(`, `traceback.print_exc(`, `logging.getLogger(`. Suggest `context["log"]` replacements.
+7. **Sibling imports.** If `routes.py` exists and grep finds bare `from <module> import` for any sibling Python file in the plugin dir, flag and recommend `context["load_sibling"]`.
+8. **Frontend IIFE.** If `script` exists, check the top of the file isn't running top-level statements that leak to global scope. Wrapping in `(function () { 'use strict'; ... })();` is the convention.
+9. **Capability-first frontend integration.** If the script wraps host globals or polls another plugin's globals, flag it as a capability gap unless the PR explicitly documents why no active domain can model the integration yet.
+10. **`localStorage` prefix.** Grep for `localStorage.` usage; keys must start with `<plugin_id>`.
+11. **Server-file allowlists are safe.** `settings.server_files` and `diagnostics.server_files` entries are relpaths under `context["config_dir"]`, not files under the plugin directory. Check for no leading `/`, no `..`, no backslashes, no `//`, no `./`, and no leading dotfiles. The schema enforces this but call it out.
+
+## Output format
+
+```text
+plugin-review: <plugin_id>
+=========================
+1. manifest validates                 PASS
+2. id matches directory               PASS
+3. declared plugin files exist        FAIL — script lists "missing.js" but plugins/<id>/missing.js is absent
+...
+
+Total: 10 PASS / 1 FAIL / 1 N/A
+Action items:
+- Remove the dangling script entry, or create the file.
+- Replace `print(...)` calls at routes.py:42, routes.py:88 with `context["log"].info(...)`.
+```
+
+If everything passes, say so explicitly — silent success is unhelpful in a review context.
+
+## Out of scope
+
+- General code style / formatting — use the built-in `peer-review`.
+- Bug-hunting beyond the plugin contract.
+- Suggesting major refactors. Stay on contract compliance.

.claude/rules/plugin-author.md

@@ -0,0 +1,49 @@
+---
+name: plugin-author
+description: Rules that apply when editing files under plugins/**. Enforces the plugin contracts documented in docs/PLUGIN_AUTHORING.md.
+globs:
+  - "plugins/**"
+---
+
+# Plugin authoring rules
+
+These rules apply only when editing files under `plugins/**`. They encode the contracts described in [`docs/PLUGIN_AUTHORING.md`](../../docs/PLUGIN_AUTHORING.md) so AI suggestions don't drift from them.
+
+## 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).
+- **Plugins declare capability intent** with `standards: ["capability-pipelines.v1"]` and redaction-safe `capabilities` / `ui` metadata. Treat these declarations as the plugin's primary contract with Slopsmith.
+- **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).
+
+## Backend (`routes.py`)
+
+- **Use `context["log"]`, never `print()` or `traceback.print_exc()`.** The CI workflow blocks `print(` and `traceback.print_exc(` in `server.py` / `lib/`; plugin code should follow the same rule. The provided logger is a stdlib `logging.Logger` namespaced to `slopsmith.plugin.<id>` with correlation IDs, JSON mode, and rotation already wired. See [`docs/plugin-logging.md`](../../docs/plugin-logging.md).
+- **Multi-file plugins must use `context["load_sibling"]("<module>")`**, not bare `from <module> import X`. Two plugins shipping a same-named helper collide via `sys.modules`. See [`docs/plugin-sibling-imports.md`](../../docs/plugin-sibling-imports.md).
+- **`setup(app, context)` is the required entry.** Don't run side effects at import time.
+
+## Frontend (`screen.js`)
+
+- **Wrap in an IIFE** — `(function () { 'use strict'; ... })();`. Frontend scripts share global scope; leaking variables collides with other plugins.
+- **Prefer capability commands, events, and provider APIs** for app coordination. Don't add new private global wrappers or cross-plugin polling; if the needed domain is missing, call that out as a capability gap.
+
+## State and config
+
+- **`localStorage` keys must be prefixed with the plugin id** to avoid collisions.
+- **`settings.server_files` declares config-dir paths the plugin wants to include in the Settings export/import flow.** Relpaths only — no `..`, no abs paths, no backslashes. See [`docs/plugin-manifest.md`](../../docs/plugin-manifest.md).
+- **`diagnostics.server_files` / `diagnostics.callable`** declares what enters the Export Diagnostics bundle. Keep payloads under 100 KB and don't include secrets. See [`docs/plugin-diagnostics.md`](../../docs/plugin-diagnostics.md).
+
+## Visualization specifics
+
+When `plugin.json` declares `"type": "visualization"`:
+
+- **Factory must be `window.slopsmithViz_<id>`** where `<id>` matches `plugin.json`.
+- **Factory must return a fresh object on each call** — splitscreen creates N instances.
+- **The renderer owns its `getContext()` call.** Declare `contextType: '2d'` or `'webgl2'` on the returned object so the highway can swap the canvas element when needed (`getContext` is one-shot per canvas).
+- **`draw(bundle)` receives difficulty-filtered arrays** — never read from `_filteredNotes` or other internals.
+
+See [`docs/plugin-visualization-contracts.md`](../../docs/plugin-visualization-contracts.md) for the full lifecycle and the Overlay + Note-state-provider contracts.
+
+## Testing
+
+When changing plugin internals, add or update a test under `tests/` (Python) or `tests/js/` (Node) or `tests/browser/` (Playwright). See [`docs/testing-plugins.md`](../../docs/testing-plugins.md) for fixtures (`isolate_logging`, `reset_plugin_state`).

.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "_comment": "Repo-default Claude Code settings for Slopsmith contributors. Hooks are intentionally empty by default — see commented example below.",
+
+  "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, 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",
+        "command": "if echo \"$CLAUDE_TOOL_INPUT_FILE_PATH\" | grep -qE '^plugins/[^/]+/plugin\\.json$'; then python -c \"import json,sys,jsonschema; s=json.load(open('schema/plugin.schema.json')); m=json.load(open('$CLAUDE_TOOL_INPUT_FILE_PATH')); jsonschema.validate(m,s); print('OK','$CLAUDE_TOOL_INPUT_FILE_PATH')\"; fi"
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,85 @@
+---
+name: plugin-scaffold
+description: Scaffold a Slopsmith plugin skeleton with capability-pipelines metadata. USE WHEN the user asks to create a new plugin, scaffold a plugin, bootstrap a plugin, new visualization plugin, new overlay plugin, new settings-only plugin, plugin starter, plugin skeleton. Args needed - plugin slug (snake_case) and type (visualization / overlay / settings-only / routes-only). Generates plugins/<id>/ with plugin.json, capability-pipelines metadata, screen.js, and optional routes.py / settings.html / Playwright test stub matching the requested type.
+---
+
+# plugin-scaffold
+
+Generates a minimum-viable Slopsmith plugin skeleton matching a requested shape. The output validates against [`schema/plugin.schema.json`](../../../schema/plugin.schema.json).
+
+## When to invoke
+
+The user says one of:
+- "scaffold a new plugin called X"
+- "create a visualization plugin"
+- "new overlay plugin"
+- "plugin starter for settings"
+- "bootstrap a routes-only plugin"
+
+If the plugin slug or type is missing, ask once.
+
+## Inputs
+
+| Arg | Required | Values | Notes |
+|---|---|---|---|
+| `id` | yes | snake_case | Becomes plugin's `id` field and directory name |
+| `name` | optional | string | Defaults to title-case of `id` |
+| `type` | yes | `visualization` / `overlay` / `settings-only` / `routes-only` | Determines which files get scaffolded |
+
+## What to generate
+
+**Common to all types:**
+
+- `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.
+
+**`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": "none", "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": "none", "ownership": "multi-provider", "safety": "safe", "version": 1 } }`
+- a matching `"ui"` contribution with a stable overlay id and redaction-safe label
+- `screen.js` scaffolding an own-canvas + own-rAF loop for the declared overlay contribution, and respecting renderer ownership if it uses highway geometry helpers
+- `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 for the route's Slopsmith-facing workflow; if the domain is unclear, ask what capability domain the route owns, provides, requests, or observes before finalizing the scaffold
+- `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
+
+## After scaffolding
+
+Run validation locally:
+
+```bash
+python -c "import json,jsonschema; s=json.load(open('schema/plugin.schema.json')); jsonschema.validate(json.load(open('plugins/<id>/plugin.json')), s); print('OK')"
+```
+
+Then point the user at [`docs/PLUGIN_AUTHORING.md`](../../../docs/PLUGIN_AUTHORING.md) and the relevant contract doc for the type they chose.
+
+## Don'ts
+
+- 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()`.
+
+## Verification
+
+The scaffolded plugin should pass:
+
+```bash
+pytest tests/test_plugin_schema.py::test_in_tree_manifest_validates -v
+pytest tests/test_plugin_schema.py::test_in_tree_manifest_id_matches_directory -v
+```

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

@@ -0,0 +1,108 @@
+---
+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, capability metadata checks, file-existence checks for declared script/routes/settings.html/tour paths, and license-allowlist check.
+---
+
+# plugin-validate
+
+Runs the same checks `.github/workflows/validate-plugins.yml` + `tests/test_plugin_schema.py` run in CI, but **locally and instantly** — useful for catching errors before push.
+
+## When to invoke
+
+The user says one of:
+- "validate plugins/<id>"
+- "check the manifest for X"
+- "lint this plugin"
+- "verify my plugin.json"
+- "plugin license check"
+
+Works on either a specific plugin (e.g. `plugins/highway_3d/`) or all in-tree plugins if none is specified.
+
+## What to run
+
+```bash
+# All in-tree plugins (default)
+python <<'PY'
+import json, glob, sys, jsonschema, pathlib
+schema = json.load(open('schema/plugin.schema.json'))
+jsonschema.Draft202012Validator.check_schema(schema)
+ok = True
+for path in sorted(glob.glob('plugins/*/plugin.json')):
+    plugin_dir = pathlib.Path(path).parent
+    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, including capability-pipelines.v1 metadata
+    try:
+        jsonschema.validate(m, schema)
+    except jsonschema.ValidationError as e:
+        print(f"FAIL {path}: {e.message} (at {list(e.absolute_path)})")
+        ok = False
+        continue
+    # 2. id == directory name
+    if m['id'] != plugin_id:
+        print(f"FAIL {path}: id={m['id']!r} but directory is {plugin_id!r}")
+        ok = False
+        plugin_ok = False
+    # 3. Declared files exist
+    for field in ('script', 'routes', 'tour'):
+        if field in m and not (plugin_dir / m[field]).exists():
+            print(f"FAIL {path}: {field}={m[field]!r} but file missing")
+            ok = False
+            plugin_ok = False
+    if 'settings' in m and 'html' in m['settings']:
+        h = m['settings']['html']
+        if not (plugin_dir / h).exists():
+            print(f"FAIL {path}: settings.html={h!r} but file missing")
+            ok = False
+            plugin_ok = False
+    for field in ('settings', 'diagnostics'):
+        if field in m and 'server_files' in m[field]:
+            for relpath in m[field]['server_files']:
+                # server_files paths live under context["config_dir"], NOT the
+                # plugin dir, so we don't existence-check them here. We only
+                # confirm the path *looks* safe (already enforced by schema).
+                if '..' in relpath or relpath.startswith('/') or '\\' in relpath:
+                    print(f"FAIL {path}: {field}.server_files contains unsafe path {relpath!r}")
+                    ok = False
+                    plugin_ok = False
+    if plugin_ok:
+        print(f"OK   {path}")
+sys.exit(0 if ok else 1)
+PY
+```
+
+## Targeted invocation
+
+If the user names a specific plugin, swap the glob for `plugins/<id>/plugin.json` and report on just that one.
+
+## License-allowlist check
+
+If the user specifically asks for a license check (or the plugin declares `license` in `plugin.json`), additionally run:
+
+```bash
+pytest tests/test_plugin_schema.py::test_schema_license_enum_subset_of_contributing_allowlist -v --noconftest
+```
+
+(or skip `--noconftest` if `structlog` is installed locally).
+
+## Output
+
+Use the format from the script: `OK <path>` per validated manifest, `FAIL <path>: <reason>` per failure. Add a one-line summary:
+
+```text
+Result: 3/3 plugins valid (OK app_tour_library, app_tour_settings, highway_3d)
+```
+
+or
+
+```text
+Result: 2/3 plugins valid; 1 FAIL (see above)
+```
+
+## Related
+
+- [`schema/plugin.schema.json`](../../../schema/plugin.schema.json)
+- [`tests/test_plugin_schema.py`](../../../tests/test_plugin_schema.py)
+- [`.github/workflows/validate-plugins.yml`](../../../.github/workflows/validate-plugins.yml)
+- [`docs/plugin-manifest.md`](../../../docs/plugin-manifest.md)

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,85 @@
+name: Bug report
+description: Report something broken in Slopsmith core (server, frontend, library, player).
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting! Before submitting:
+        - For **plugin** issues, please open the issue in the plugin's own repository instead — plugins under `plugins/` are separate projects.
+        - For sensitive logs, redact paths/credentials. The `docs/diagnostics-bundle-spec.md` describes the redaction surface used by Export Diagnostics.
+
+  - type: input
+    id: version
+    attributes:
+      label: Slopsmith version
+      description: "Contents of the `VERSION` file at the root, or what the navbar badge shows."
+      placeholder: "e.g. 0.2.8"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: deployment
+    attributes:
+      label: How are you running Slopsmith?
+      options:
+        - Docker Compose (docker-compose.yml)
+        - Bare Python (python main.py)
+        - Proxmox CT (build-proxmox-ct.sh)
+        - slopsmith-desktop bundle
+        - Other (describe below)
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Host OS / browser
+      placeholder: "e.g. macOS 15.4 + Chrome 134; Linux + Firefox 142"
+    validations:
+      required: true
+
+  - type: input
+    id: plugins
+    attributes:
+      label: Plugins enabled
+      description: "List the plugins active when the bug happened. Most bugs reproduce only with certain plugins."
+      placeholder: "highway_3d, fretboard, note_detect"
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction steps
+      description: "Numbered steps. Include song format (legacy archive / sloppak / loose) and arrangement type if relevant."
+      placeholder: |
+        1. ...
+        2. ...
+        3. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected vs. actual behaviour
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / diagnostics
+      description: |
+        Either paste relevant log lines (set `LOG_LEVEL=DEBUG` or `LOG_FORMAT=json` if useful) **or** attach an Export Diagnostics bundle. See `docs/diagnostics-bundle-spec.md` for what's inside the bundle and what's redacted.
+      render: text
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Confirmations
+      options:
+        - label: I searched existing issues and didn't find a duplicate
+          required: true
+        - label: This is a core bug, not a plugin bug
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -1 +1,11 @@
-blank_issues_enabled: true
+blank_issues_enabled: false
+contact_links:
+  - name: Plugin issues
+    url: https://github.com/slopsmith/slopsmith#plugins
+    about: Plugins live in their own repositories. Open plugin bugs/features in the plugin's own repo.
+  - name: Documentation questions
+    url: https://github.com/slopsmith/slopsmith/tree/main/docs
+    about: Plugin contracts, sloppak spec, diagnostics, and note-detect tuning are documented under docs/. Try there first.
+  - name: Security disclosures
+    url: https://github.com/slopsmith/slopsmith/security
+    about: For security issues, please use GitHub's private security advisory flow rather than a public issue.

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,57 @@
+name: Feature request
+description: Propose a feature, behaviour change, or new plugin contract.
+title: "[feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the suggestion! For **plugin features**, open the issue in the plugin's own repository unless the change requires new core API.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: "Lead with the user/contributor pain — the solution shape often falls out of a sharp problem statement."
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: "What you'd like to see. UI mockups, code sketches, config examples all welcome."
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Which surface does this touch?
+      multiple: true
+      options:
+        - Server (FastAPI / lib/)
+        - Frontend (static/)
+        - Plugin contract (new field / event / API)
+        - Sloppak format
+        - WebSocket protocol
+        - Diagnostics
+        - Docs only
+        - Other (describe in proposal)
+
+  - type: textarea
+    id: plugin_impact
+    attributes:
+      label: Plugin author impact
+      description: "Does this require existing plugins to change? Add a new optional field? Break a contract? Be specific so the maintainer can size compatibility work."
+
+  - type: checkboxes
+    id: license
+    attributes:
+      label: License compatibility
+      options:
+        - label: If suggesting third-party code, it's AGPL-3.0-compatible (see CONTRIBUTING.md curated list)
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,38 @@
+<!--
+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, including capability metadata
+- Touching the highway / player UI? Add or update a Playwright test
+  under tests/browser/
+-->
+
+## Summary
+
+<!-- 1–3 bullets describing what changes and why. Link related discussion. -->
+
+## Linked issue
+
+<!-- Closes #1234, or "n/a" if this is a chore/docs change -->
+
+## Test plan
+
+<!-- How did you verify? Tick what applies. -->
+
+- [ ] `pytest -q` passes locally
+- [ ] `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` (including capability metadata)
+- [ ] Not applicable — explain below
+
+## Screenshots / recordings
+
+<!-- For UI changes, paste before/after. Drag-drop into the editor or use a GIF. -->
+
+## Checklist
+
+- [ ] DCO sign-off on every commit (`Signed-off-by:` trailer)
+- [ ] Conventional-commit subject (`feat(scope):`, `fix(scope):`, `docs:`, `chore:`)
+- [ ] `CHANGELOG.md` `[Unreleased]` section updated
+- [ ] Documentation updated if behaviour or contracts changed

.github/copilot-instructions.md

@@ -0,0 +1,22 @@
+# GitHub Copilot instructions
+
+This file customizes GitHub Copilot Chat and Copilot inline suggestions for the Slopsmith repository.
+
+## Read first
+
+- [`AGENTS.md`](../AGENTS.md) — canonical project orientation (architecture, conventions, first-hour pitfalls, verification). This file is a thin pointer; the real content lives there.
+- [`docs/PLUGIN_AUTHORING.md`](../docs/PLUGIN_AUTHORING.md) — plugin work entry point
+
+## House rules
+
+- **License: AGPL-3.0-only.** Inbound contributions are AGPL-compatible. Do not suggest code copied verbatim from incompatible sources.
+- **DCO sign-off required** on every commit (`git commit -s`).
+- **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 plugin integrations, suggest `standards: ["capability-pipelines.v1"]` and redaction-safe `capabilities` / `ui` metadata as the primary contract.
+- **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), including native `capability-pipelines.v1` metadata.

.github/workflows/sync-version.yml

@@ -3,7 +3,7 @@ name: Sync VERSION from desktop release
 # Updates the VERSION file in this repo whenever slopsmith-desktop
 # publishes a new tagged release. slopsmith-desktop's build.yml
 # dispatches the `desktop-released` event at the end of a successful
-# tag build (see docs in CLAUDE.md). A `workflow_dispatch` trigger is
+# tag build (see Versioning section in AGENTS.md). A `workflow_dispatch` trigger is
 # kept for manual testing / recovery.
 #
 # Related issue: #81.

.github/workflows/validate-plugins.yml

@@ -0,0 +1,82 @@
+name: Validate plugins
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'plugins/**/plugin.json'
+      - 'plugins/__init__.py'
+      - 'schema/plugin.schema.json'
+      - 'docs/plugin-manifest.schema.json'
+      - 'static/capabilities.js'
+      - 'CONTRIBUTING.md'
+      - 'requirements-test.txt'
+      - 'tests/test_plugin_schema.py'
+      - '.github/workflows/validate-plugins.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'plugins/**/plugin.json'
+      - 'plugins/__init__.py'
+      - 'schema/plugin.schema.json'
+      - 'docs/plugin-manifest.schema.json'
+      - 'static/capabilities.js'
+      - 'CONTRIBUTING.md'
+      - 'requirements-test.txt'
+      - 'tests/test_plugin_schema.py'
+      - '.github/workflows/validate-plugins.yml'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      - name: Install jsonschema
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-test.txt
+
+      - name: Validate every in-tree plugin.json against capability schema
+        run: |
+          python - <<'PY'
+          import glob, json, sys
+          import jsonschema
+
+          schema_path = "schema/plugin.schema.json"
+          with open(schema_path) as f:
+              schema = json.load(f)
+
+          # Validate the schema itself is a well-formed JSON Schema.
+          jsonschema.Draft202012Validator.check_schema(schema)
+
+          manifests = sorted(glob.glob("plugins/*/plugin.json"))
+          if not manifests:
+              print("No plugin manifests found under plugins/*/plugin.json")
+              sys.exit(0)
+
+          failures = []
+          for path in manifests:
+              with open(path) as f:
+                  manifest = json.load(f)
+              try:
+                  jsonschema.validate(manifest, schema)
+                  print(f"OK   {path}")
+              except jsonschema.ValidationError as e:
+                  failures.append((path, e))
+                  print(f"FAIL {path}: {e.message} (at {list(e.absolute_path)})")
+          if failures:
+              sys.exit(1)
+          PY
+
+      - 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
+        # runtime requirements into a 2 KB schema-validation job.
+        run: pytest tests/test_plugin_schema.py -v --noconftest

.gitignore

@@ -35,8 +35,6 @@ plugins/minigames/__pycache__/
 !plugins/tuner/
 !plugins/tuner/**
 plugins/tuner/__pycache__/
-!plugins/input_setup/
-!plugins/input_setup/**
 node_modules/
 test-results/
 playwright-report/

.specify/memory/constitution.md

@@ -1,13 +1,28 @@
+<!--
+Sync Impact Report
+Version change: 1.1.0 -> 1.2.0
+Modified principles:
+- III. Plugins Are the Extension Point — Isolated by `load_sibling` -> III. Plugins Are the Extension Point — Capability-Declared and Isolated
+Added sections: None
+Removed sections: None
+Templates requiring updates:
+- [updated] .specify/templates/plan-template.md — Constitution Check now names Slopsmith's concrete gates, including plugin capability declarations.
+- [reviewed] .specify/templates/spec-template.md — no structural update required; requirements remain feature-focused.
+- [reviewed] .specify/templates/tasks-template.md — no structural update required; the plan gate drives capability-related tasks.
+- [reviewed] .specify/templates/checklist-template.md — no structural update required.
+Follow-up TODOs: None
+-->
+
 # Slopsmith Constitution
 
 > Slopsmith is a self-hosted, single-user web app for browsing, playing, and
-> practicing interactive music notation, built around its own open `.sloppak`
+practicing interactive music notation, built around its own open `.sloppak`
 > chart format (charts imported from Guitar Pro / MusicXML or authored in the
 > built-in editor). This constitution captures the non-negotiable principles
 > that govern its core (`server.py`, `lib/`, `static/`) and that all in-tree
 > plugins (`plugins/<name>/`) inherit by default. It is a *retrospective*
 > document — the codebase came first, the principles below were distilled from
-> `CLAUDE.md`, `README.md`, and the shape of the existing implementation.
+> `AGENTS.md`, `README.md`, and the shape of the existing implementation.
 
 ## Core Principles
 
@@ -69,28 +84,45 @@ features extend `app.js` and the existing globals (`window.playSong`,
   layout invariants (`#player` flex-column, `#highway` flex:1,
   `#player-controls` at the bottom) MUST be preserved.
 
-### III. Plugins Are the Extension Point — Isolated by `load_sibling`
+### III. Plugins Are the Extension Point — Capability-Declared and Isolated
 
 Functionality that is not part of the irreducible "browse + play charts"
 loop ships as a plugin under `plugins/<name>/`, not as core code. Each
 plugin is its own directory (typically a separate git repo), discovered
 at startup via `plugin.json`, and free to add nav links, screens,
-settings panels, and `/api/plugins/<id>/...` routes. Plugins MUST
-isolate their backend Python imports via `context["load_sibling"]` so
-two plugins shipping a generic `extractor.py` / `util.py` / `client.py`
-do not collide in `sys.modules`.
+settings panels, and `/api/plugins/<id>/...` routes. Slopsmith-facing
+plugin behavior is capability-declared by default: manifests describe
+the domains a plugin owns, provides, requests, observes, validates, or
+contributes to before any runtime script hydrates. Runtime handlers,
+legacy wrappers, and private globals are implementation details or
+compatibility bridges, never the primary integration contract. Plugins
+MUST isolate their backend Python imports via `context["load_sibling"]`
+so two plugins shipping a generic `extractor.py` / `util.py` /
+`client.py` do not collide in `sys.modules`.
 
 **Non-negotiable rules**
 
 - Generic features (practice journal, setlist, metronome, tone player,
   tab view, MIDI control, stem mixing, editors, etc.) belong in a plugin
   repo, not in `lib/` or `server.py`.
+- Plugins with Slopsmith-facing behavior MUST declare
+  `standards: ["capability-pipelines.v1"]` plus redaction-safe
+  `capabilities`, `ui`, or `ui_contributions` metadata for the behavior
+  they expose. Metadata-only or transitional manifests that omit
+  capability participation MUST document why no current domain applies.
+- Runtime participants, event listeners, wrapper hooks, timers, DOM
+  roots, diagnostics contributors, and media nodes MUST be idempotent
+  across repeated script hydration. If a wrapper or private global is
+  still required, it MUST be documented as a compatibility bridge or a
+  missing capability-domain gap.
 - Plugin backend modules MUST use `context["load_sibling"]("name")` for
   sibling imports. Bare `import sibling` works during transition but
   triggers a startup warning when a name collides.
 - Plugins MUST register routes under `/api/plugins/<plugin_id>/...`,
-  use `window.slopsmith.emit/on` for cross-plugin communication, and
-  prefix their `localStorage` keys with their plugin id.
+  use capability commands/events when an active domain exists, and
+  prefix their `localStorage` keys with their plugin id. General
+  `window.slopsmith.emit/on` events remain acceptable for host events or
+  domains that have not yet been promoted.
 - Plugins inherit this constitution and may layer additional rules in
   their own `CLAUDE.md`, but MUST NOT relax core principles (e.g. a
   plugin cannot require a frontend framework in core).
@@ -100,9 +132,7 @@ do not collide in `sys.modules`.
 The whole point of Slopsmith is that a user points it at an existing
 song library folder and it Just Works. The library is scanned and
 indexed in `meta.db` (SQLite via `MetadataDB`). The open Sloppak
-format (`lib/sloppak.py`; specified at
-[got-feedback/feedback-feedpak-spec](https://github.com/got-feedback/feedback-feedpak-spec),
-published as feedpak — same format) is the preferred
+format (`lib/sloppak.py`, `docs/sloppak-spec.md`) is the preferred
 format and the home for new features; loose-folder XML charts
 (`lib/loosefolder.py`) are also discovered and played as a first-class
 format. Both must keep playing across releases.
@@ -209,11 +239,12 @@ no `..`, no absolute paths).
   `flex:1`; `#player-controls` sits at the bottom. Hiding the highway
   collapses the layout — use `margin-top: auto` on controls if you
   need to hide it.
-- **Plugin load order**: alphabetical by directory name. The
-  `playSong` wrapper chain runs outermost-first (last-loaded wrapper
-  runs first). Plugins MUST tolerate dependent globals being absent
-  at load time and check at runtime
-  (`typeof window.X === 'function'`).
+- **Plugin load order**: alphabetical by directory name. Scripts MUST
+  tolerate dependent globals being absent at load time and check at
+  runtime (`typeof window.X === 'function'`). Load order and the
+  `playSong` wrapper chain are implementation details, not integration
+  contracts; plugins declare roles, ownership, compatibility, and UI
+  contributions through capability metadata.
 
 ## Development Workflow
 
@@ -227,8 +258,9 @@ no `..`, no absolute paths).
   After pushing a fix, the CodeRabbit loop
   (`feedback_coderabbit_review.md`) runs to silence.
 - **Testing**: `pytest` for backend (`requirements-test.txt`),
-  Playwright for browser interactions (`tests/browser/`), CI runs both
-  on every push/PR to `main`.
+  Playwright for browser interactions (`tests/browser/`), and plugin
+  manifest schema validation for capability metadata. CI runs these on
+  every relevant push/PR to `main`.
 - **CHANGELOG**: every PR updates `[Unreleased]`. Releases rename
   `[Unreleased]` to `[X.Y.Z] - YYYY-MM-DD` (the VERSION bump itself is
   automated).
@@ -248,12 +280,13 @@ no `..`, no absolute paths).
   explicit constitutional amendment in this file.
 - Amendments require: (a) a PR that updates this file alongside the
   code change, (b) an entry in `CHANGELOG.md` under "Migration notes"
-  if user-visible, and (c) a corresponding update to `CLAUDE.md` so
-  AI agents and humans see the same source of truth.
+  if user-visible, and (c) a corresponding update to `AGENTS.md` and any
+  agent-specific imports or instructions so AI agents and humans see the
+  same source of truth.
 - The principles are listed in priority order. When two principles
   conflict (e.g. "vanilla frontend" vs. a plugin that wants to ship
   React), the lower-numbered principle wins by default; the
   higher-numbered principle's escape hatch is to live in a plugin
   with its own bundled assets.
 
-**Version**: 1.1.0 | **Ratified**: 2026-05-09 | **Last Amended**: 2026-06-01
+**Version**: 1.2.0 | **Ratified**: 2026-05-09 | **Last Amended**: 2026-06-03

.specify/templates/plan-template.md

@@ -31,7 +31,29 @@
 
 *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
 
-[Gates determined based on constitution file]
+Answer each gate with PASS / FAIL / N/A and a short justification:
+
+- **Self-hosted Docker path**: Does the feature keep `DLC_DIR` and
+  `CONFIG_DIR` as the only required runtime inputs, with any new
+  dependency installable in the existing Docker image?
+- **Vanilla/source-served frontend**: Does core remain plain JS and
+  committed CSS, with no framework, runtime CDN/JIT, bundler, or
+  serve-path build step? If plugin CSS is needed, does it ship through
+  `styles`?
+- **Plugin and capability boundary**: If the feature is outside browse +
+  play custom DLC, is it plugin-shaped? Does every Slopsmith-facing plugin
+  behavior declare `capability-pipelines.v1` metadata (`capabilities`,
+  `ui`, or `ui_contributions`) and use `load_sibling` for backend
+  siblings?
+- **Song format compatibility**: Are legacy archive scanning, sloppak manifests,
+  arrangement IDs, and highway WebSocket messages kept backward-
+  compatible, or is a migration note planned?
+- **Pure/testable core**: Are new `lib/` helpers flat-importable,
+  side-effect-light, and covered where practical?
+- **Observability and diagnostics**: Does backend output use logging,
+  and do diagnostics remain redacted and versioned?
+- **Settings/versioning**: Are settings imports/export paths safe,
+  additive/idempotent, and compatible with the `VERSION` workflow?
 
 ## Project Structure
 

AGENTS.md

@@ -0,0 +1,179 @@
+# AGENTS.md
+
+Project orientation for AI coding assistants (Cursor, GitHub Copilot, OpenAI Codex, Aider, Claude Code, Cline, Continue, Cody, Devin, …) and human contributors.
+
+Slopsmith is a self-hosted web app for browsing, playing, and practicing interactive music notation, built around its own open `.sloppak` chart format. Charts come from importing Guitar Pro (GP5/GP8) or MusicXML, or from authoring in the built-in editor. It runs as a Docker container with a FastAPI backend (`server.py`), vanilla JavaScript frontend (`static/`), shared Python libraries (`lib/`), and an extensive plugin system (`plugins/`). No frontend frameworks — plain JS, HTML, Tailwind CSS. AGPL-3.0-only.
+
+This file is the canonical orientation. Tool-specific automation (Claude skills/subagents/rules, Copilot instructions, etc.) lives in [`.claude/`](.claude/) and [`.github/copilot-instructions.md`](.github/copilot-instructions.md); both point back here. For plugin work, start at [`docs/PLUGIN_AUTHORING.md`](docs/PLUGIN_AUTHORING.md).
+
+## Architecture quick reference
+
+```text
+server.py              FastAPI app — library API, WebSocket highway, plugin loading
+main.py                Programmatic uvicorn entrypoint — installs structlog before boot
+logging_setup.py       Structured logging + correlation IDs (LOG_LEVEL/LOG_FORMAT/LOG_FILE)
+static/
+  app.js               Main frontend — screens, library views, player, plugin loader
+  highway.js           Canvas note highway renderer (createHighway factory)
+  diagnostics.js       window.slopsmith.diagnostics namespace (loaded first in <head>)
+  index.html           Single-page app shell
+lib/
+  song.py              Core data models (Note, Chord, Arrangement, Song)
+  sloppak.py           Sloppak format support
+  sloppak_convert.py   Import conversion + Demucs stem split
+  loosefolder.py       Loose-folder XML chart support
+  audio.py             WEM/OGG/MP3 audio handling
+  retune.py            Pitch-shifting logic
+  tunings.py           Tuning name/offset utilities
+  gp2rs.py             Guitar Pro to arrangement XML conversion
+  gp2midi.py           Guitar Pro to MIDI
+plugins/
+  __init__.py          Plugin discovery, loading, requirements install, load_sibling
+  <plugin>/            Each plugin is its own directory (often a git submodule)
+schema/
+  plugin.schema.json   JSON Schema for plugin.json (validated in CI)
+docs/                  Plugin contracts + format specs (see Plugin authoring below)
+tests/                 pytest + tests/js/ (node --test) + tests/browser/ (Playwright)
+specs/                 Active spec-kit features (specs/001-slopsmith-platform/...)
+```
+
+## Running the app
+
+Canonical dev path is Docker Compose — `docker-compose.yml` live-mounts `static/`, `server.py`, `lib/`, `plugins/`, and `VERSION` into the container, so frontend edits are visible on refresh and backend edits trigger uvicorn auto-reload.
+
+```bash
+docker compose up                                     # build + run on :8000
+DLC_PATH=/path/to/dlc docker compose up               # override default Steam DLC path
+```
+
+For host-side runs (tests, scripts, no Docker), the programmatic entry point is `main.py`:
+
+```bash
+python main.py                                        # HOST=0.0.0.0 PORT=8000 default
+HOST=127.0.0.1 PORT=8001 python main.py
+```
+
+`main.py` installs the structlog pipeline via `logging_setup.configure_logging()` **before** uvicorn boots and passes `log_config=None` so uvicorn's `dictConfig` never overwrites it. Do not invoke `uvicorn server:app` directly during development — early lifecycle log lines will bypass the structured pipeline and correlation IDs.
+
+**Logging env vars** (read by `logging_setup`):
+- `LOG_LEVEL` — `DEBUG | INFO | WARNING | ERROR` (default `INFO`)
+- `LOG_FORMAT` — `json | text` (default `text` — coloured console)
+- `LOG_FILE` — optional path for a persistent log file (e.g. `/config/slopsmith.log`)
+
+Plugin backend code receives a pre-configured `context["log"]` logger namespaced to `slopsmith.plugin.<id>` — never use `print()`. See [`docs/plugin-logging.md`](docs/plugin-logging.md).
+
+## Testing
+
+```bash
+pytest                              # All Python tests
+pytest tests/test_plugins.py -v     # Specific file
+pytest -k "load_sibling" -v         # Pattern match
+
+npm run test:js                     # Node-native JS plugin-API contract tests (tests/js/)
+npm run install:playwright          # One-time: install Chromium for Playwright
+npm test                            # Playwright browser tests (tests/browser/)
+```
+
+Pytest config in `pyproject.toml` sets `pythonpath = [".", "lib"]` and `testpaths = ["tests"]`. CI runs `pytest` on every push/PR to `main` (Python 3.12). See [`docs/testing-plugins.md`](docs/testing-plugins.md) for fixtures (`isolate_logging`, `reset_plugin_state`) and Playwright patterns.
+
+## Git workflow
+
+- **Never push directly to `main`** — always create a feature branch and open a PR.
+- **DCO sign-off is mandatory.** `git commit -s` appends `Signed-off-by:`. Forgot? `git commit --amend -s`. See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+- **Upstream remote** — set `upstream` to the canonical Slopsmith repository; `origin` is your fork.
+- **Plugins are gitlinks** — each plugin in `plugins/` is typically its own git repo (submodule or clone). Branch switches on the main repo can clobber plugin directories. Use `git update-index --assume-unchanged` for plugin dirs if needed.
+- **Commit style** — short imperative subject line, blank line, then body explaining *why*. Conventional-commit prefixes (`feat(scope):`, `fix(scope):`, `chore:`, `docs:`) are conventional in the log but not enforced.
+
+## Versioning
+
+- **`VERSION`** (repo root) — single source of truth; plain semver string. Bind-mounted into the container and copied by the Dockerfile so it's always available at `/app/VERSION`.
+- **`GET /api/version`** — returns `{"version", "source_url", "license_url"}`. `source_url` is overridable via `APP_SOURCE_URL` (default `https://github.com/byrongamatos/slopsmith`); `license_url` falls back to `source_url + "/blob/main/LICENSE"` and is overridable via `APP_LICENSE_URL`. Both must be `http(s)`; non-http(s) values are rejected.
+- **Auto-sync** — `.github/workflows/sync-version.yml` rewrites `VERSION` via a `repository_dispatch` (`desktop-released`) from `slopsmith-desktop`'s release job. As an explicit automation-only exception to "Never push directly to main", the sync job commits straight to `main` as `github-actions[bot]`. Humans still go through PRs.
+- **`CHANGELOG.md`** — [Keep a Changelog](https://keepachangelog.com/) format. Update `[Unreleased]` on each PR; release renames it.
+
+## Song formats
+
+Slopsmith supports two:
+
+- **Legacy archive** (encrypted, read-only) — fast metadata scan via `lib/sloppak.py`; full unpack for playback. Audio via `vgmstream-cli` + `ffmpeg`.
+- **Sloppak** (open format) — hand-editable, two interchangeable forms: `.sloppak` zip or `.sloppak/` directory. Preferred for new features. Full spec: [`docs/sloppak-spec.md`](docs/sloppak-spec.md). Key code: `lib/sloppak.py`, `lib/sloppak_convert.py`, `lib/song.py`.
+
+## Frontend conventions
+
+- **No frameworks** — vanilla JS, fetch API, DOM manipulation
+- **Plugin integration** — prefer documented capability domains, provider APIs, and redaction-safe UI contributions over private globals
+- **Storage** — `localStorage` for all user preferences, prefixed with plugin id
+- **Styling** — Tailwind utility classes; dark theme (`bg-dark-600`, `text-gray-300`, accent `#4080e0`, gold `#e8c040`)
+- **Naming** — camelCase for JS, kebab-case for CSS, snake_case for plugin IDs
+- **Player layout** — `#player` is `display:flex; flex-direction:column; position:fixed; inset:0`. `#highway` is `flex:1`. Hiding the highway collapses the layout — use `margin-top: auto` on controls if you must hide it.
+
+## Backend conventions
+
+- **Framework** — FastAPI + uvicorn (boot via `main.py`)
+- **Imports** — flat imports from `lib/` (no `__init__.py`): `from song import Song`
+- **Database** — SQLite via `MetadataDB` class with `threading.Lock`
+- **WebSocket** — JSON frames, try/except `WebSocketDisconnect`. Protocol: [`docs/websocket-protocol.md`](docs/websocket-protocol.md)
+- **Error handling** — graceful fallbacks (audio conversion errors don't crash the song; missing art returns a placeholder)
+- **Type hints** — used sparingly (`Path | None`, `dict`, `list`)
+- **Docstrings** — minimal; code is self-documenting
+
+## 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 that declares its `capability-pipelines.v1` participation. 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 metadata.
+
+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 contracts | [`docs/plugin-visualization-contracts.md`](docs/plugin-visualization-contracts.md)
+Plugin styles (`styles: "assets/plugin.css"`) | [`docs/plugin-styles.md`](docs/plugin-styles.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)
+Multi-file backends (`load_sibling`) | [`docs/plugin-sibling-imports.md`](docs/plugin-sibling-imports.md)
+WebSocket highway protocol | [`docs/websocket-protocol.md`](docs/websocket-protocol.md)
+Testing plugins (pytest + Playwright) | [`docs/testing-plugins.md`](docs/testing-plugins.md)
+Diagnostics bundle layout | [`docs/diagnostics-bundle-spec.md`](docs/diagnostics-bundle-spec.md)
+Sloppak format spec | [`docs/sloppak-spec.md`](docs/sloppak-spec.md)
+Tuning the note_detect plugin | [`docs/note-detect-tuning.md`](docs/note-detect-tuning.md)
+
+## First-hour pitfalls (read these before your first PR)
+
+1. **`load_sibling` for cross-file backend plugins.** Bare `from extractor import X` in `routes.py` collides across plugins because Python caches by module name in `sys.modules`. Use `context["load_sibling"]("extractor")` — gets a per-plugin namespaced module. Full explanation: [`docs/plugin-sibling-imports.md`](docs/plugin-sibling-imports.md).
+
+2. **Capability declarations are the integration map.** Plugin behavior should be visible in `standards`, `capabilities`, and `ui` metadata before runtime code hydrates. If the domain you need is missing, document it as a capability gap instead of adding another private global contract.
+
+3. **Highway flex layout.** `#highway` has `flex:1` in the player. Hiding it with `display:none` removes the flex child and `#player-controls` floats to the top. If you must hide the highway, add `margin-top: auto` to the controls div.
+
+4. **Plugin gitlinks bite on branch switches.** Plugins are separate git repos cloned into `plugins/`. `git checkout` / `git clean` on the main repo can delete or clobber them. Use `git update-index --assume-unchanged plugins/<id>` if needed.
+
+5. **DCO sign-off is mandatory.** Every commit needs `Signed-off-by:`. Add via `git commit -s` (or `git commit --amend -s` if you forgot). PRs without DCO won't merge.
+
+## Verification (run before claiming done)
+
+```bash
+pytest -q                         # backend tests
+npm run test:js                   # JS plugin-API contract tests
+npm test                          # Playwright browser tests (slow; defers to CI)
+```
+
+If you touched `plugins/*/plugin.json` or `schema/`:
+
+```bash
+python -c "import json,glob,jsonschema; s=json.load(open('schema/plugin.schema.json')); [jsonschema.validate(json.load(open(p)), s) for p in sorted(glob.glob('plugins/*/plugin.json'))]"
+```
+
+## House rules
+
+- **AGPL-3.0-only.** Inbound contributions are inbound under the same terms. Don't paste from incompatible sources.
+- **DCO sign-off mandatory** on every commit (`git commit -s`).
+- **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.** Plugin integrations declare `standards: ["capability-pipelines.v1"]` plus redaction-safe `capabilities`/`ui` metadata as the primary integration contract.
+- **Spec-kit owns `.specify/` and `specs/`.** Don't modify those without explicit instruction; the `/speckit-*` skills own that surface.
+
+## Tool-specific surfaces (optional reading)
+
+- [`CLAUDE.md`](CLAUDE.md) — points back here. Exists for Claude Code's auto-loading convention. Claude-specific *automation* lives in [`.claude/`](.claude/) (skills, subagents, rules, settings).
+- [`.github/copilot-instructions.md`](.github/copilot-instructions.md) — points back here. Exists for GitHub Copilot's native instructions format.
+- No `.cursorrules` — Cursor reads `AGENTS.md` natively. Cursor-specific rules, if ever needed, would go under `.cursor/rules/`.

CHANGELOG.md

@@ -51,6 +51,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`highway.getPhrases()` and `highway.getMastery()` public plugin API** — exposes phrase timing windows (`[{ index, start_time, end_time, max_difficulty }]`) and the current mastery slider value (`0..1`) as documented, stable plugin API. Both values were already in memory and reachable via internal names; this surfaces them with intent so plugins can implement section-aware logic (e.g. tracking accuracy per phrase, suppressing difficulty changes during a hard solo) without reaching into undocumented internals. Returns `null` when the song has no phrase data (GP imports, single-difficulty charts). Pair with the existing `hasPhraseData()` to gate phrase-aware code paths.
 - **Tailwind freshness guard + wider plugin scan.** A new `tailwind-fresh` CI job (`.github/workflows/tests.yml`) rebuilds `static/tailwind.min.css` with the pinned `tailwindcss@3.4.19` and hard-fails on any diff, so the committed prebuilt stylesheet can no longer silently lag source (after PR #411 removed the runtime Play CDN, a stale file shipped unstyled elements with no guard). The `tailwind.config.js` plugin content glob is widened to `./plugins/**/*.{js,html}`, which also scans non-`screen.js` plugin JS (e.g. `plugins/app_tour_*/script.js`) that was previously invisible to the build. Regenerating under the wider glob is a no-op for runtime behaviour — it only adds classes that were already used in source. Groundwork for the plugin `styles` capability (constitution 1.1.0, Principle II): runtime-installed plugins ship their own compiled CSS rather than relying on core's build-time scan.
 - **Plugin capability pipelines** — adds the first versioned capability coordination layer for plugin authors and support tooling. `/api/plugins` now exposes validated capability declarations, validation warnings, unsupported-version metadata, UI/runtime domain declarations, and compatibility shim summaries for legacy `nav` / `screen` / `settings` / `routes` / visualization surfaces. The browser runtime now tracks manifest participants separately from live handlers, explicit dispatch outcomes (`no-owner`, `no-handler`, `unsupported-command`, `incompatible-version`), claim lifecycle cleanup, manual override precedence, deterministic ownership conflicts, multi-provider ordering, shim hit counts, and a redaction-safe diagnostics snapshot capped at 64 KB. A bundled Capability Inspector plugin shows the live graph, and new docs cover the manifest schema, recipes, safety matrix, lifecycle cleanup, and diagnostics contract.
+- **Constitution 1.2.0 codifies capability-first plugins.** Principle III now makes `capability-pipelines.v1` manifest declarations the default Slopsmith-facing plugin contract, treats wrappers/private globals as compatibility bridges or capability gaps, and adds a concrete spec-kit Constitution Check gate for plugin capability metadata.
 - **Audio graph/session capability slice** — promotes `audio-mix`, `audio-input`, `audio-monitoring`, and coordinated `stems` diagnostics into the capability runtime. The new audio session host records song route/fader state, redaction-safe input sources, monitoring lifecycle outcomes, stem automation claims/overrides/orphans, and compatibility bridge hits for legacy faders, song volume, Stems master volume, 3D Highway analyser taps, audio startup barriers, and input source handoffs. `core.audio.session` coordinates `stems` without replacing the Stems plugin as the owner of actual stem playback/state.
 - **Audio-mix control plane** — makes `audio-mix` the player mixer source of truth. Core now exposes `list-faders`, `get-fader-value`, `set-fader-value`, `inspect-route`, and `inspect-analyser` through the capability runtime, routes native and compatibility-backed fader provider operations with a 2-second timeout, reports committed values back to the mixer UI, suppresses matching legacy faders when a native participant owns the same logical control, and expands audio-session diagnostics/Capability Inspector rendering for fader availability, source modes, bridge hits, route/analyser summaries, and timeout failures.
 - **Audio-input control plane** — makes `audio-input` the redaction-safe source of truth for instrument input discovery and lifecycle. Core now exposes `list-sources`, `select-source`, `open-source`, and `close-source` through the capability runtime, persists selected logical sources, keeps inspect/list/select prompt-free, routes provider `source.open`/`source.close` operations with bounded outcomes, shares compatible open sessions across requesters, suppresses compatibility-backed duplicate sources when a native provider owns the same logical key, and expands audio-session diagnostics/Capability Inspector rendering for selected input, open sessions, bridge hits, storage status, and permission/device failures without exposing raw device labels or live audio handles.

CLAUDE.md

@@ -1,639 +1,22 @@
-# Slopsmith — AI Agent Guide
+# CLAUDE.md
 
-Slopsmith is a self-hosted web app for browsing, playing, and practicing interactive music notation, built around its own open `.sloppak` chart format. Charts come from importing Guitar Pro (GP5/GP8) or MusicXML, or from authoring in the built-in editor. It runs as a Docker container with a FastAPI backend (`server.py`), vanilla JavaScript frontend (`static/`), shared Python libraries (`lib/`), and an extensive plugin system (`plugins/`). There are no frontend frameworks — everything is plain JS, HTML, and Tailwind CSS.
+Claude Code memory file. This repo's canonical project orientation lives in [`AGENTS.md`](AGENTS.md) - the cross-tool standard read by Cursor, Copilot, Codex, Aider, Cline, and others. The line below uses Claude Code's `@`-import to inline AGENTS.md into this memory file, so there's a single source of truth and no drift between two near-duplicate files.
 
-## Architecture Quick Reference
+@AGENTS.md
 
-```
-server.py              FastAPI app — library API, WebSocket highway, plugin loading
-static/
-  app.js               Main frontend — screens, library views, player, plugin loader
-  highway.js           Canvas note highway renderer (createHighway factory)
-  index.html           Single-page app shell
-  style.css            Custom CSS loaded alongside Tailwind
-lib/
-  song.py              Core data models (Note, Chord, Arrangement, Song)
-  sloppak.py           Sloppak format support
-  loosefolder.py       Loose-folder XML chart support
-  audio.py             OGG/MP3 audio handling
-  retune.py            Pitch-shifting logic
-  tunings.py           Tuning name/offset utilities
-  gp2rs.py             Guitar Pro to arrangement XML conversion
-  gp2midi.py           Guitar Pro to MIDI
-plugins/
-  __init__.py           Plugin discovery, loading, requirements install
-  <plugin_name>/        Each plugin is its own directory (often a git submodule)
-tests/
-  test_*.py             pytest test suite
-```
+## Claude-specific surfaces
 
-## Plugin System
+The rest of this file is content that *only* makes sense for Claude Code (other AI tools have their own incompatible automation mechanisms). Skills, subagent, rule, and settings live under [`.claude/`](.claude/):
 
-Plugins are the primary extension point. Each plugin lives in `plugins/<name>/` with a `plugin.json` manifest. Plugins are typically their own git repositories — see [CONTRIBUTING.md](CONTRIBUTING.md) for the licensing policy (curated plugins should be AGPL-3.0 or AGPL-compatible: MIT, BSD, Apache-2.0).
+- [`.claude/skills/plugin-scaffold/`](.claude/skills/plugin-scaffold/SKILL.md) - generates a plugin skeleton with capability-pipelines metadata.
+- [`.claude/skills/plugin-validate/`](.claude/skills/plugin-validate/SKILL.md) - validates `plugin.json` against `schema/plugin.schema.json` locally before push.
+- [`.claude/skills/speckit-*/`](.claude/skills/) - spec-kit skills (auto-generated from `.specify/`; don't edit manually).
+- [`.claude/rules/plugin-author.md`](.claude/rules/plugin-author.md) - glob-scoped to `plugins/**`; encodes the contracts from `docs/PLUGIN_AUTHORING.md` so suggestions don't drift from them.
+- [`.claude/agents/slopsmith-reviewer.md`](.claude/agents/slopsmith-reviewer.md) - plugin-aware code-review subagent. Invoke with `@slopsmith-reviewer`.
+- [`.claude/settings.json`](.claude/settings.json) - repo defaults (no hooks enabled by default; commented opt-in example for `plugin.json` validation on save).
 
-```json
-{
-  "id": "my_plugin",
-  "name": "My Plugin",
-  "version": "1.0.0",
-  "private": false,
-  "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",
-    "server_files": ["my_plugin.db", "my_plugin_models/"]
-  },
-  "diagnostics": {
-    "server_files": ["my_plugin.diag.json"],
-    "callable": "diagnostics:collect"
-  }
-}
-```
+See [`.claude/README.md`](.claude/README.md) for conventions when adding more.
 
-All fields except `id` and `name` are optional. Plugins can have any combination of frontend (screen/script), backend (routes), and settings.
+## Why this file is short
 
-`version` and `private` are advisory metadata — the plugin loader does not currently consume them, but plugins commonly include them for publishing/tooling purposes.
-
-`description`, `category`, and `icon` are **optional, additive v3 Pedalboard metadata** (surfaced in `/api/plugins`, consumed by the v3 Plugins page `static/v3/plugins-page.js`). `description` is a short one-sentence summary shown under the pedal name. `category` (`audio | creation | practice | game | tools`, free-form; unknown/absent → curated default → `"other"`) picks which pedalboard the plugin sits on. `icon` is an assets-relative thumbnail path (e.g. `"assets/thumb.png"`, ~square ~256×256, same containment rule as `styles`, served via `/api/plugins/<id>/assets/...`); if omitted the loader auto-detects `assets/thumb.png`, and plugins with no thumbnail get a default pedal graphic. All three are backward-compatible — omit them and the plugin still loads. See [docs/plugin-v3-ui.md](docs/plugin-v3-ui.md).
-
-`styles` is the **opt-in** for self-hosted CSS (Principle II — prebuilt Tailwind, no Play CDN). Core's `static/tailwind.min.css` only contains classes scanned from core source at build time, so a plugin installed at runtime (community / NAS) that uses classes core didn't scan — especially arbitrary values like `text-[11px]` — renders unstyled. Declaring `styles` makes the frontend inject one versioned `<link rel="stylesheet">` into `<head>` (covering the plugin's screen *and* its settings panel) pointing at the plugin's own compiled stylesheet. The value is a **plugin-root-relative path that must live under `assets/`** (e.g. `"assets/plugin.css"`) so it serves through the sandboxed `/api/plugins/<id>/assets/...` route. Build it with `corePlugins: { preflight: false }` (utilities only — core ships the single base reset; don't duplicate it) and **never** the Tailwind Play CDN. Plugins that use only core-guaranteed utilities, or ship no Tailwind, omit `styles` and are byte-for-byte unaffected. Full authoring guide + scaffold: [docs/plugin-styles.md](docs/plugin-styles.md).
-
-`settings.server_files` is the **opt-in** for the unified Settings export/import flow (slopsmith#113). It's a list of relpaths under `context["config_dir"]` that the plugin wants included in user-triggered backups. A trailing `/` denotes a directory (recurse). Plugins that omit this field have no server-side files exported; their state lives entirely in browser `localStorage`, which is bundled wholesale on every export. Rules:
-- Relpaths only. Absolute paths, drive letters, `..` segments, and backslashes are rejected at load time with a `[Plugin]` warning.
-- The same allowlist is consulted at both export and import: a bundle that references a file the *importing host*'s manifest no longer declares is skipped with a warning (handles plugin updates between export and import). A bundle that references a file your host's manifest never declared is also skipped — no surprise writes.
-- Files are encoded as `{"encoding": "json", "data": <parsed>}` for `.json` files that parse cleanly (diff-friendly), `{"encoding": "base64", "data": "..."}` otherwise (sqlite, model blobs, IRs).
-- Plugins own their internal data migration. Importing a bundle whose data schema predates your current code restores bytes verbatim — your plugin must cope at next load.
-- Symlinks are skipped on export and never followed on import.
-
-`diagnostics` is the **opt-in** for the troubleshooting bundle (slopsmith#166 — Settings → Export Diagnostics). Two independent fields:
-- `diagnostics.server_files` — same allowlist semantics as `settings.server_files`: relpaths under `context["config_dir"]`, no `..`, no abs paths, no backslashes, no leading dots. Files listed here are copied verbatim into `plugins/<plugin_id>/<relpath>` inside the bundle. Use this for snapshot-style state (small DB excerpts, model lists, last-error files).
-- `diagnostics.callable` — `"<module>:<function>"` (e.g. `"diagnostics:collect"`). Resolved lazily via `load_sibling` when the user clicks Export, then called as `func({"plugin_id": "...", "config_dir": Path(...)})`. Return `dict`/`list` → written to `plugins/<id>/callable.json`; `bytes` → `callable.bin`; `str` → `callable.txt`. Exceptions are caught and appended to the bundle's `manifest.notes` — a buggy plugin never crashes the export.
-
-Plugins that omit the field contribute nothing to the bundle from the backend side. Frontend plugins can independently push state via `window.slopsmith.diagnostics.contribute(plugin_id, payload)` from their `screen.js` before the user hits Export. Bundle layout + per-file schemas: [docs/diagnostics-bundle-spec.md](docs/diagnostics-bundle-spec.md).
-
-Best practices:
-- Embed your own `schema` field (e.g. `"my_plugin.diag.v1"`) in JSON returned by `callable` so future tooling can dispatch by version.
-- Keep payloads small (< 100 KB). Diagnostics are not a backup channel — that's `settings.server_files`.
-- Don't include user secrets, API keys, or session tokens. The bundle is shared with maintainers / posted to GitHub issues.
-
-`type` is an optional role hint (slopsmith#36). Supported values:
-- `"visualization"` — plugin provides a highway renderer. Declaring this makes the plugin eligible for the main-player viz picker AND splitscreen's per-panel picker. Must pair with a `window.slopsmithViz_<id>` factory exporting the setRenderer contract below.
-- Absent → no declared role; plugin is loaded and its script runs, but it doesn't appear in role-specific UIs.
-
-**Backend routes** — `routes.py` must export a `setup(app, context)` function. The `context` dict provides:
-- `config_dir` — persistent config path
-- `get_dlc_dir()` — returns the DLC folder Path
-- `extract_meta()` — metadata extraction callable
-- `meta_db` — shared MetadataDB instance
-- `library_providers` — shared library provider registry for source-aware browsing
-- `register_library_provider(provider)` — register a plugin-provided library source. Providers expose `id`, `label`, optional `kind`/`capabilities`, and callable `query_page`, `query_artists`, `query_stats`, and `tuning_names` methods. Providers with `art.read` may also expose `get_art(song_id)` returning one of: a `Response` object (any media type, served as-is); raw `bytes` or `bytearray` (**assumed PNG** — use a `Response` or a `dict` with `content`+`media_type` keys for JPEG/WebP or other formats); a URL string (http/https → 302 redirect; other schemes are rejected with 400); a filesystem path string or `Path` (served as a file with auto-detected media type); or a `dict` with a `url`, `path`, or `content` key. Providers with `song.sync` may expose `sync_song(song_id)` returning `None` (success with no local file) or a `dict` — the dict is passed through as the JSON response and should include `filename`/`local_filename` if a local playable file was produced.
-- `unregister_library_provider(provider_id)` — remove a plugin-provided library source by id. The built-in `local` provider cannot be removed.
-- `get_sloppak_cache_dir()` — sloppak cache path
-- `load_sibling(name)` — loads a sibling module from this plugin's directory under a unique, namespaced module name. See "Sibling imports" below.
-- `log` — stdlib `logging.Logger` namespaced to `slopsmith.plugin.<id>`. Pre-configured with the app-wide level, format (including JSON mode), and correlation IDs. Use this for all backend plugin output instead of `print()`. See "Backend plugin logging" below.
-
-**Sibling imports — use `load_sibling`, not bare imports** (slopsmith#33). The plugin loader inserts each plugin's directory onto `sys.path` so `from extractor import X` works, but Python caches imports by **module name** in `sys.modules`. Two plugins that each ship a top-level `extractor.py` (or any other generic name — `util.py`, `client.py`, `parser.py`, `config.py`, …) collide: whichever loads first wins, and the other plugin's `from extractor import X` either gets the wrong module or fails with `cannot import name 'X' from 'extractor'`.
-
-The fix is `context["load_sibling"](name)`, which loads the sibling under a namespaced module name (`plugin_<id>.<name>`, where plugin_id is bijectively encoded so reverse-DNS-style ids like `com.example.foo` work without colliding: `_` -> `_5f_`, `.` -> `_2e_`) so each plugin gets its own copy:
-
-```python
-def setup(app, context):
-    helper = context["load_sibling"]("helper")
-    HelperClass = helper.HelperClass
-    # …
-```
-
-Notes:
-- `name` is a bare module name — no `.py` suffix, no slashes, no `.`. The helper raises `ValueError` for path traversal / format issues and `ImportError` for missing files.
-- Both single-file siblings (`extractor.py`) and package-form siblings (`extractor/__init__.py`) work. Package form wins when both exist (matches CPython's import-resolution precedence).
-- Relative imports between siblings work — `from .shared import X` in a top-level helper, `from ..shared import X` from inside a sibling package. The synthetic parent package `plugin_<id>` carries the plugin directory in its `__path__`.
-- `from . import sibling` (attribute-style) also resolves: loaded children are exposed as attributes on the parent package.
-- Repeat calls return the cached module. Concurrent first-time calls are serialized via per-module locks so no caller observes a half-initialized module.
-- Bare `import sibling` from `routes.py` still works during the transition period, but the loader prints a startup warning when it detects two plugins shipping a same-named top-level module — covering both `.py` files and package directories. Migrate to `load_sibling` to silence the warning and immunize your plugin from future ecosystem collisions. (Don't mix bare imports and `load_sibling` for the same module — they'd execute the file twice and split module-level state.)
-
-**Frontend scripts** — `screen.js` runs in the global scope via a `<script>` tag. It can access `window.playSong`, `window.showScreen`, `window.createHighway`, the `<audio>` element, and the `window.slopsmith` event emitter.
-
-**The playSong wrapper chain** — Plugins commonly wrap `window.playSong` to hook into song playback. Plugins load alphabetically, so the last-loaded (alphabetically later) wrapper runs first, while the alphabetically first plugin runs closest to the original. Be aware that `await` calls in inner wrappers yield to the event loop — WebSocket messages can arrive before outer wrappers finish setup.
-
-## Plugin Best Practices
-
-### v3 UI (fee[dB]ack v0.3.0) — player-chrome contract
-
-v0.3.0 ships a redesigned UI behind a flag (`SLOPSMITH_UI=v3` or the `/v3` route);
-the classic UI (v2) stays the default until 0.3.0 ships, so **plugins must work in
-both**. v3 reuses the same engine (`server.py`, `app.js`, `highway.js`, `playSong`,
-`showScreen`, capabilities, library providers, the `window.slopsmithViz_<id>` /
-`setRenderer` contract), so a plugin's **backend, capabilities, `nav`/`screen`,
-visualization renderers, diagnostics, and settings export work unchanged** — v3
-surfaces `nav` in its sidebar and mounts screens exactly as v2 does.
-
-**The only thing that changed is the player chrome.** If your plugin injects a
-control into it, you must adapt:
-
-- v2's wide always-visible `#player-controls` bar is, in v3, a **minimal
-  auto-hiding transport** (fades ~2.5 s after the pointer stills during playback)
-  plus a hover-reveal left icon rail. So injecting into `#player-controls` the
-  legacy way means your control **auto-hides**, and the legacy insertion anchors
-  (`insertBefore` the `span.text-gray-700` separator, or `button:last-child` / ✕
-  Close) **don't exist in v3** → it lands wrong / unreachable.
-- **Detect v3** with `window.slopsmith.uiVersion === 'v3'` and **mount into
-  `window.slopsmith.ui.playerControlSlot()`** (a stable, always-reachable container
-  — the "Plugins" rail popover) instead of `#player-controls`. Drop the dead
-  anchors (append), and guard re-injection against the *actual* container
-  (`controls.contains(myBtn)`), not a hard-coded `#player-controls`.
-- A host `MutationObserver` re-homes legacy `#player-controls` children into the
-  slot as a fallback, but it **breaks plugins that guard on
-  `#player-controls.contains()`** (the moved node fails the check → re-inject every
-  song). Mount into the slot yourself; don't rely on the shim.
-- v3 uses `fb-*` tokens (`fb-card`, `fb-text`, `fb-textDim`, `fb-primary`,
-  `fb-border`) vs v2's `dark-*`/`accent`; legacy classes still render acceptably.
-  Keep `#player` overlay `z-index` ≤ the chrome layers (transport/HUD 20, rail 30,
-  popovers 40).
-
-Full guide + the canonical snippet: **[docs/plugin-v3-ui.md](docs/plugin-v3-ui.md)**.
-Verify any player-injecting plugin in **both** `/` (v2) and `/v3`.
-
-### Performance — never run DOM queries on a per-frame path
-
-Plugins share the main thread with the highway's 60 fps render loop, and during
-playback the highway + note detectors mutate the DOM ~60×/s — so anything that
-*reacts* to DOM changes runs that often too. Work that looks cheap in isolation
-becomes the dominant cost when it runs every frame. A profiled "the 3D highway is
-laggy" report turned out to be **three plugins doing per-frame `querySelectorAll`**
-(~18% of main-thread CPU + NodeList GC churn), not the renderer. The GPU was idle.
-
-- **Never call `querySelector` / `querySelectorAll` inside `draw()`, a
-  `requestAnimationFrame` loop, a short `setInterval`, or a `MutationObserver`
-  callback.** Resolve the element(s) **once** when your UI mounts and cache the
-  references; re-resolve only when the cached node is gone (`!el.isConnected`).
-  `querySelectorAll` also allocates a fresh `NodeList` every call → GC pressure at
-  60 fps. (notedetect #75 — a VU meter that `querySelector`'d its bar every tick.)
-
-- **Scope `MutationObserver`s narrowly — never `observe(document.body, { subtree:
-  true })` just to notice your own UI's container mount.** A body-subtree observer
-  fires on *every* DOM mutation anywhere, including the per-frame highway churn, so
-  a callback that then scans the document is a per-frame full-DOM scan. Observe the
-  specific container; if it's swapped on screen changes, observe a stable parent,
-  or **cheaply early-bail** (one `getElementById` / a screen-state check) *before*
-  the expensive work. (sloppak-converter #32 — a body-subtree observer re-ran
-  whole-document inject sweeps on every frame of playback.)
-
-- **Stop playback-tied loops when their UI is hidden.** An rAF/interval meter (VU,
-  etc.) that keeps drawing while its panel is closed is pure waste — gate it on
-  visibility, or stop and restart it on open/close.
-
-- **Per-instance, not global.** Under splitscreen a viz/detector plugin runs
-  multiple instances. Cache refs and resolve panels against your *own* instance's
-  container, never a global `document.querySelector` that could grab a sibling
-  instance's node. (notedetect #75 follow-up.)
-
-These are cheap to get right up front and expensive to retrofit. Profile the
-**main thread**, not the GPU, when a renderer "feels laggy" — the offender is
-usually an unrelated plugin's per-frame DOM work.
-
-### Visualization plugins — two complementary contracts
-
-Slopsmith supports two ways for a plugin to participate in the main player's visuals. They coexist; the setRenderer contract is the default for any viz that draws a highway-shaped surface, and overlays handle layered decorations on top.
-
-**Pick the right shape:**
-- Replacing the whole highway drawing on the existing highway canvas (your renderer owns its rendering context / resources; `createHighway()` still owns the canvas element and the rAF loop)? → **setRenderer** (section 1). Enters the viz picker. Works in both the main player and per-panel under splitscreen.
-- Adding a layer on top of whichever viz is active? → **Overlay** (section 2). Navbar toggle, not in the picker.
-
-#### 1. setRenderer contract (slopsmith#36) — preferred
-
-Plugins that want to replace the main highway's draw function (per panel, per session) export a renderer factory on `window.slopsmithViz_<id>` where `<id>` matches the `id` in `plugin.json` (`type: "visualization"` required). The factory returns an object matching this shape:
-
-```js
-window.slopsmithViz_my_viz = function () {
-    return {
-        // Required canvas context type. Default '2d' if omitted.
-        // highway.js reads this BEFORE calling init() so it can
-        // replace the underlying <canvas> element if the current
-        // one is locked to a different context type (see "Canvas
-        // context-type swapping" below).
-        contextType: '2d', // or 'webgl2'
-        init(canvas, bundle) {
-            // One-time setup. Own your getContext() call here —
-            // acquire '2d' or 'webgl2' depending on the renderer.
-            // The canvas you receive is guaranteed to either be
-            // unbound or already bound to your declared contextType.
-            this.ctx = canvas.getContext('2d');
-        },
-        draw(bundle) {
-            // Called each requestAnimationFrame tick by the factory.
-            // `bundle` is a snapshot with: currentTime, songInfo, isReady,
-            // notes, chords, anchors (all difficulty-filter-aware),
-            // beats, sections, chordTemplates, stringCount, lyrics,
-            // toneChanges, toneBase, mastery, hasPhraseData, inverted,
-            // lefty, renderScale, lyricsVisible, the 2D coordinate
-            // helpers project and fretX, and getNoteState (see below).
-            // `stringCount` is the active arrangement's string count (4
-            // for bass, 6 for guitar, 7+ for extended-range GP imports —
-            // size string-indexed geometry against this, not a hardcoded
-            // 6). If your renderer needs lefty-aware text rendering, check
-            // bundle.lefty and apply the mirror transform yourself —
-            // a bundle-level helper isn't provided because it would
-            // need your renderer's own context, not the factory's.
-            //
-            // bundle.getNoteState(note, chartTime) (slopsmith#254) — call
-            // this per visible chart note / chord-note to find out whether
-            // a scorer (note_detect) has flagged it 'hit' / 'active' (a
-            // sustain currently being held correctly) / 'miss', so the gem
-            // itself can light up / a held sustain can glow instead of
-            // relying on an overlay ring. Returns null when no provider is
-            // registered or it reports nothing for this note; otherwise
-            // { state: 'hit'|'active'|'miss', alpha: 0..1, color: string|null }.
-            // For chord notes pass the chord's time (note_detect keys its
-            // judgments by `${time}_${string}_${fret}`). 'hit' and 'active'
-            // are both "lit" — a renderer may treat them identically; the
-            // provider owns all fade timing via `alpha` and by simply
-            // ceasing to return state when the effect should end.
-        },
-        resize(w, h) {
-            // Optional. Canvas dims already updated; re-create WebGL
-            // framebuffers / reset 2D transforms here.
-        },
-        destroy() {
-            // Optional. Release resources, remove DOM nodes, null refs.
-            // Called before setRenderer() swaps to another renderer
-            // and on highway.stop().
-        },
-    };
-};
-```
-
-Selecting this plugin in the main-player viz picker — or in splitscreen's per-panel picker — calls `highway.setRenderer(factory())` on the existing highway instance. The built-in 2D highway is the default renderer and is restored by passing nullish — `setRenderer(null)` and `setRenderer(undefined)` both work (the implementation gates on `r == null`). Splitscreen panels create one `createHighway()` per panel and each independently consults the picker, so N panels can run different renderers (or N copies of the same renderer with different arrangements) without coordination.
-
-**Lifecycle contract.** The factory returns a single renderer instance that may go through multiple `init() → ... → destroy()` cycles as the user navigates between songs or screens. Specifically:
-
-- `init(canvas, bundle)` runs when the highway has a canvas and the renderer takes over drawing. This is when to acquire `getContext()`, build shaders / meshes / DOM nodes, and register listeners.
-- `draw(bundle)` runs on every rAF frame once the WebSocket `ready` message has fired and until the renderer is replaced or the highway stops. It is **not** called during the loading / reconnect window (between `api.init()` + `stop()` and the next `ready`) — that would hand the renderer half-populated chart arrays. Renderers that want to show a "loading" state can read `bundle.isReady` inside a future-widened contract, but today the factory gates `draw` behind the ready flag and `isReady` is only informational once it does fire.
-- `destroy()` runs when the renderer is replaced via another `setRenderer(...)` call, OR when `highway.stop()` is called (e.g. the user navigates away from the player). It releases everything `init()` acquired.
-- **After `destroy()`, the same instance may receive another `init()` call** — this happens on `playSong()` which does `stop()` → `init()` to reuse the same canvas element for the next song. Renderers must tolerate `init()` being called again on an instance that was previously destroyed. Practically: null your refs in destroy, re-acquire them in init.
-- `destroy()` is skipped when it would run on an un-init'd renderer — if a caller does `setRenderer(x)` before the highway ever init'd (possible when restoring a saved picker selection at page load), `x.destroy()` is not called until `x.init()` has run at least once.
-- `resize(w, h)` is optional; runs after init and whenever the canvas dimensions change.
-
-**Key rules:**
-- The factory **returns a fresh object on each call** — important for splitscreen, where multiple panels will each get an independent instance.
-- The renderer **owns its own rendering context** (2D or WebGL). Factory will not call getContext for you.
-- **Canvas context-type swapping.** Browsers lock a `<canvas>` to the first context type successfully acquired for its lifetime: once `getContext('2d')` succeeds, `getContext('webgl2')` on that same canvas returns `null`, and vice versa. To let arbitrary 2D ⇄ WebGL renderer swaps work mid-session, `highway.setRenderer()` reads the next renderer's `contextType` before calling its `init()` and, if it differs from the type currently bound, replaces the underlying `<canvas>` element with a fresh one via `oldCanvas.cloneNode(false)` followed by `oldCanvas.replaceWith(newCanvas)`. The factory then calls the renderer's `init(newCanvas, bundle)` with the fresh element so its `getContext()` succeeds. Practical implications:
-  - **What survives the swap.** `cloneNode(false)` preserves *every HTML attribute* on the element — `id`, `class`, inline `style`, all `data-*` and `aria-*` attributes, `role`, `tabindex`, the attribute form of `width`/`height`, and anything else a plugin attached. DOM position is preserved by `replaceWith()`, so siblings, parents, and surrounding layout are unaffected.
-  - **What does NOT survive.** Event listeners attached via `addEventListener` are NOT cloned, and expando properties set imperatively on the JavaScript object (such as the bound rendering context, or any `canvas._myPlugin = …`-style data a plugin attached) are not carried over either. The bound rendering context being left behind on the detached element is exactly what allows the new canvas to start fresh and accept a different `getContext()` call. Note: `canvas.width`/`canvas.height` *are* reflected HTML attributes, so those values do survive the clone; `api.resize()` re-applies the backing-store dimensions on the new element after the swap regardless.
-  - Renderers must **declare `contextType`** on the returned instance (`'2d'` or `'webgl2'`; absent → `'2d'`). Factories may also expose it as a static (`window.slopsmithViz_<id>.contextType = 'webgl2'`) so core can read it before constructing the renderer — used today by Auto-mode evaluation.
-  - Plugins that hold a stale reference to the highway canvas across renderer swaps — including any code that registered listeners directly on the canvas element rather than on `window`/`document` — should listen for the `highway:canvas-replaced` event on `window.slopsmith` and re-acquire / re-register. `window.slopsmith.emit` dispatches a `CustomEvent`, so the payload `{ oldCanvas, newCanvas, contextType }` lives on `event.detail`, not on the event object itself:
-    ```js
-    window.slopsmith.on('highway:canvas-replaced', (event) => {
-        const { oldCanvas, newCanvas, contextType } = event.detail;
-        // re-acquire / re-register against newCanvas
-    });
-    ```
-    Plugins that re-query `document.getElementById('highway')` lazily inside their own event handlers don't need this listener — they pick up the new element automatically (it keeps `id="highway"`).
-  - **`highway:visibility`** — fired on `window.slopsmith` whenever the highway canvas transitions between displayed and hidden. Detection is DOM-based via `canvas.offsetParent === null` (catches `display:none` on the canvas or any ancestor — e.g. splitscreen's `#highway` hide) or whatever a host explicitly sets via `highway.setVisible(bool)`. While `visible === false`, core skips the rAF `renderer.draw(bundle)` call AND the default 2D draw, so renderers don't have to no-op themselves. The event is emitted only on transitions (including the first one after `init()`), not every frame. Payload `{ visible, canvas }` lives on `event.detail`:
-    ```js
-    window.slopsmith.on('highway:visibility', (event) => {
-        const { visible, canvas } = event.detail;
-        // Toggle any sibling DOM your renderer mounts. The 3D Highway
-        // renderer hides its `.h3d-wrap` overlay here so `display:none`
-        // on `#highway` actually hides the visible output.
-    });
-    ```
-    Renderers that only paint to the slopsmith canvas don't need this listener — the rAF skip is enough. Renderers that mount sibling DOM (separate WebGL contexts, overlays, etc.) do.
-  - **`highway.setVisible(bool | null)`** — forces the visibility state regardless of `offsetParent`. Pass `null` to clear the override and resume DOM-based detection. Useful when the host hides the highway via `visibility:hidden`, `opacity:0`, transforms, or clipping rather than `display:none`. The override re-emits any resulting transition immediately rather than waiting for the next rAF tick.
-  - Default-renderer ctx is closure-cached. The replace path nulls the closure ctx so stale draw paths short-circuit; the next default-renderer `init()` re-acquires the 2D context from the new canvas cleanly.
-- `draw(bundle)` receives difficulty-filtered arrays — never read from `_filteredNotes` or other internals.
-- `_drawHooks` fire for the default 2D renderer (the factory calls them at the end of each frame). Custom WebGL renderers that maintain a 2D overlay canvas (like the bundled 3D highway) also call `window.highway.fireDrawHooks(ctx, W, H)` on that overlay so overlay plugins continue to work regardless of which renderer is active. Custom renderers without a 2D overlay context should not attempt to fire hooks.
-
-**Auto mode — `matchesArrangement(songInfo)` (optional).**
-
-The viz picker prepends an "Auto (match arrangement)" entry that is the default selection on fresh installs. When Auto is active, core evaluates registered viz factories on every `song:ready` and swaps the renderer to the first factory whose `matchesArrangement(songInfo)` predicate returns truthy. No match → the built-in 2D highway.
-
-Declare the predicate as a static on the factory (not the instance) so core can evaluate it without constructing a throwaway renderer:
-
-```js
-window.slopsmithViz_piano = function () { /* ... */ };
-window.slopsmithViz_piano.matchesArrangement = function (songInfo) {
-    return /keys|piano|synth/i.test((songInfo && songInfo.arrangement) || '');
-};
-```
-
-- `songInfo` is the highway's live song_info snapshot — `arrangement`, `tuning`, `capo`, `centOffset`, `arrangement_index`, `filename`, `artist`, `title`, etc. May be `{}` before the first song loads.
-- Factories without `matchesArrangement` are skipped during auto-selection — the correct default for arrangement-agnostic viz (tabview, jumpingtab) that only make sense as manual picks.
-- Explicit picker selections override Auto and are persisted to `localStorage.vizSelection`, so the pinned choice survives page reloads until the user switches back to "Auto" (which also persists). Picking "Auto" re-evaluates against the current song immediately. In contexts where `localStorage` is unavailable (private mode, sandboxed iframes, some test runners) persistence falls back to the current picker `<option>` value, which still overrides Auto for as long as the page stays loaded.
-- When an Auto-selected renderer fails and core emits `viz:reverted`, the picker falls back to the built-in default and disables auto-switching until the user re-selects Auto.
-- First match wins (picker order), so the registration order of plugins is the tiebreaker. Keep predicates narrow to avoid stealing songs from more specialized viz.
-
-**WebGL viz in Auto mode.** Auto evaluation runs on every `song:ready` regardless of which renderer is active. Auto-installing a WebGL renderer when the canvas is currently 2D — or reverting from a WebGL Auto pick to the default 2D — works without a reload because `setRenderer` swaps the canvas element when `contextType` differs (see "Canvas context-type swapping" above). WebGL viz can therefore safely declare `matchesArrangement` and rely on Auto. For 3D Highway specifically, `_canRun3D()` in app.js still gates Auto from picking it on machines without WebGL2 — that fallback is independent of canvas swapping.
-
-**Per-instance settings for host plugins (slopsmith#849).** A viz provider may declare per-instance controls a consuming host (e.g. splitscreen's per-panel popover) renders generically, by adding a `settings` array to its `capabilities.visualization` manifest block: `[{ key, label, type: "toggle" | "range" | "select", default, min?, max?, step?, options? }]`. This is the capability-native, declarative replacement for the ad-hoc `factory.panelControls` static. The validated list is surfaced through the visualization host's `list-providers` snapshot, so a host reads it without knowing the plugin. **A provider that declares `settings` MUST implement `applySetting(key, value)` on its renderer instance** — the host calls it on the specific per-panel instance, which is inherently per-panel (no canvas→panel resolution, no shared global localStorage keys). `getSetting(key)` is optional (the host falls back to the declared `default`); the host owns persistence. `factory.panelControls` remains read as a legacy fallback for hosts that still consume it, but new viz should declare `settings` + `applySetting`.
-
-#### 2. Overlay contract — for add-on layers
-
-Plugins that add a layer on top of whichever visualization is active — HUDs, fretboard diagrams, chord labels, practice feedback — don't replace the renderer. They manage their own canvas, their own rAF loop, and a toggle button somewhere visible (typically a navbar pill), reading public highway state via the getters:
-
-- `highway.getTime()` / `highway.getBeats()` — current playback position
-- `highway.getNotes()` / `highway.getChords()` — raw arrays containing every note/chord in the chart regardless of the current difficulty level
-- `highway.getFilteredNotes()` / `highway.getFilteredChords()` — difficulty-filtered variants. Returns the master-difficulty-filtered arrays when the song has phrase-level data (slider active); falls through to the raw arrays for songs with a single difficulty level (slider disabled). Plugins that process only the notes the player is currently expected to play should use these instead of `getNotes()` / `getChords()`
-- `highway.hasPhraseData()` — returns `true` when the current song has phrase-level difficulty ladder data (i.e. the mastery slider is active and `getFilteredNotes()` / `getFilteredChords()` return a filtered subset). Use this to gate logic that only makes sense when difficulty filtering is available
-- `highway.getPhrases()` — phrase timing windows `[{ index, start_time, end_time, max_difficulty }]` for the current song's difficulty ladder. Returns `null` when phrase data is absent (GP imports, single-difficulty charts). Read-only; do not mutate. Pair with `hasPhraseData()` to gate phrase-aware logic.
-- `highway.getMastery()` — current master-difficulty slider value as a fraction `0..1`. Reflects the same value the mastery slider is set to; meaningful only when `hasPhraseData()` is true.
-- `highway.getChordTemplates()` — chord shape lookup table; index by `chord.id` from `getChords()` to get `{ name, fingers, frets }`. `fingers` and `frets` are per-string arrays (length matches the tuning's string count); within `fingers`, `-1` = unused, `0` = open string, `n > 0` = finger number. arrangement XML sources populate real fingerings; GP imports currently emit all `-1` since pre-import sources don't carry finger data. Not filter-aware: templates are static metadata, every `chord_id` referenced by `getChords()` is guaranteed valid
-- `highway.getSongInfo()` — tuning, arrangement, capo
-- `highway.getStringCount()` — number of strings on the active arrangement (4 for bass, 6 for guitar, 7+ for extended-range GP imports). Derived server-side as `max(notes-max-string + 1, name-based fallback, len(tuning))` where the tuning length only contributes when it isn't the arrangement XML padded 6-string form (sloppak / GP-imported sources carry trimmed tuning lengths). The name-based fallback is 4 for arrangements containing "bass" (case-insensitive) and 6 otherwise. This combination handles partial-string-usage charts (a 6-string lead that never plays string 5), extended-range GP imports (5-string bass, 7-string guitar), and sloppaks that explicitly encode the instrument range — without requiring plugins to do their own arrangement-name matching
-- `highway.getLefty()` / `highway.getInverted()` — mirror + invert state
-
-Overlays do NOT appear in the viz picker and do NOT declare `"type": "visualization"` in `plugin.json`. They coexist with whichever renderer (default 2D, 3D highway, piano, ...) the user has picked.
-
-**Key rules:**
-- **Own your rAF + canvas** — don't piggyback on `_drawHooks` or on `createHighway`'s rendering context. Draw hooks fire for the default 2D renderer and for custom renderers that explicitly call `window.highway.fireDrawHooks(ctx, W, H)` (e.g. the bundled 3D highway fires them on its 2D overlay canvas), but not for every custom renderer.
-- **Re-read state every frame** — overlay output must track whatever the current renderer is drawing. Don't cache note positions across frames.
-- **Respect lefty + invert toggles** — if the overlay depicts strings or frets, mirror using the same transforms the active renderer would.
-- **If you position with `highway.project` / `highway.fretX` (the 2D-highway geometry), gate on `highway.isDefaultRenderer()`** — those helpers describe the *built-in 2D* highway's depth curve and fret zoom. When a custom renderer (3D highway, piano, …) is active your draw hook still fires (on that renderer's 2D overlay layer), but those coordinates won't match its scene — markers land in arbitrary places. Skip rendering when `isDefaultRenderer()` is false; the custom renderer owns that feedback. Renderer-agnostic overlays (fretboard diagram, chord-label HUD — they use `getNotes()`/`getChordTemplates()` + their own layout) don't need this guard.
-- **Clean up on toggle-off** — cancel rAF and remove/hide the overlay canvas so inactive overlays aren't wasting frames.
-
-Reference: [fretboard plugin](https://github.com/got-feedback/feedback-plugin-fretboard) — canonical overlay implementation (navbar toggle, own canvas, 80ms active-note window).
-
-**Why two?** setRenderer plugs into an existing highway — main-player or splitscreen-panel — reusing its WebSocket and data parsing, so the common "I want a different look for the same data" case is zero boilerplate AND multi-instance for free. Overlays compose with whatever renderer is active — they decorate rather than replace, so multiple can stack (fretboard + chord labels + practice feedback) without fighting over the canvas.
-
-A previous standalone-pane contract (`window.createMyVisualization({ container })` with its own WebSocket per pane) was used by splitscreen pre-Wave-C. It's been retired now that splitscreen calls `setRenderer` on per-panel `createHighway()` instances; if you find references in older plugin docs or external integration guides, those describe the legacy path.
-
-#### 3. Note-state provider — for scorers that want renderers to "light up" notes (slopsmith#254)
-
-A scoring plugin (note_detect) can publish a per-note judgment so whichever renderer is active draws the **gem itself** lit on a correct hit, and keeps a sustain trail glowing while it's still being played correctly — instead of a separate overlay ring floating near the note.
-
-```js
-// In the plugin (after resolving the highway instance):
-highway.setNoteStateProvider((note, chartTime) => {
-    // `note` is the chart note object ({ t, s, f, sus, ... }); for chord
-    // notes `chartTime` is the chord's time. Return one of:
-    //   - falsy  → no special state (render normally)
-    //   - 'hit'    — struck correctly; renderer lights the gem
-    //   - 'active' — a sustained note is right now being held correctly
-    //   - 'miss'   — missed; renderer may red-wash the gem
-    //   - { state: <one of the above>, alpha?: 0..1, color?: '#rrggbb' }
-    // You own all fade timing: return a decaying `alpha` for a struck-note
-    // glow, `alpha: 1` (or a bare string) for a held sustain, and stop
-    // returning state when the effect should end. Keep it cheap — it's
-    // called per visible note per renderer per frame.
-});
-// On teardown:  highway.setNoteStateProvider(null);
-```
-
-- Only one provider is active at a time (last `setNoteStateProvider` wins). `highway.getNoteStateProvider()` returns the current one (or null).
-- The built-in 2D highway consults it in `drawNote` / `drawSustains` / the chord-frame path: 'hit'/'active' → bright string colour + additive halo + a contained "sizzle" (crackling sparks, throbbing core, a shockwave ring on a fresh strike) on the gem and a bright (vs dim) sustain trail; 'miss' → faint red wash. The bundled **3D highway** reads the same data via `bundle.getNoteState` (bright string-tinted outline + bright body + glowing sustain + a contained sparkle hugging the note rect on hit/active; red outline + suppressed body on miss). Custom renderers that want it call `bundle.getNoteState(note, chartTime)` — it null-guards and returns the normalized `{ state, alpha, color }` (or null).
-- This is orthogonal to the overlay contract: note_detect remains an overlay (HUD, diagnostic miss markers, the "currently detected" indicator) *and* a scorer that feeds this provider. A renderer that ignores `getNoteState` simply doesn't light gems — nothing breaks.
-
-### Audio mixer fader registration (slopsmith#87)
-
-Plugins that produce audio outside the song's `<audio>` element (NAM amp output, synth voices, etc.) can register a labeled fader so users can balance them against the song from one mixer popover in the player controls.
-
-```js
-function _registerFader() {
-    const api = window.slopsmith && window.slopsmith.audio;
-    if (!api) return;
-    api.registerFader({
-        id: 'my_plugin',           // unique key
-        label: 'My Plugin',        // shown above the fader
-        unit: 'dB',                // optional suffix shown next to the value (e.g. '%', 'dB')
-        min: 0, max: 2, step: 0.05,
-        defaultValue: 1.0,
-        getValue: () => _myCurrentVolume,        // read current value
-        setValue: (v) => _setMyVolume(v),         // write + persist + apply
-    });
-}
-
-if (window.slopsmith && window.slopsmith.audio) {
-    _registerFader();
-} else {
-    window.addEventListener('slopsmith:audio:ready', _registerFader, { once: true });
-}
-```
-
-The plugin owns persistence — the registry calls `getValue()` when the popover opens, and also after each `setValue()` during slider drags to re-sync the displayed value. Keep `getValue()` cheap and side-effect-free, and make sure `setValue()` updates whatever backing state `getValue()` reads synchronously. Pair `setValue` with whatever your plugin already does internally (write the GainNode, persist to localStorage, update any in-plugin label). Use `unregisterFader(id)` when your plugin is teardown-able and you want the strip to disappear; otherwise keep it registered so the user's setting persists across toggle states.
-
-### Backend plugin logging
-
-Use `context["log"]` for all backend plugin output. It is a stdlib `logging.Logger` namespaced to `slopsmith.plugin.<id>`, pre-configured with the app-wide level, format (including JSON mode), and correlation IDs. Never use `print()` — it bypasses correlation context and log rotation.
-
-```python
-def setup(app, context):
-    log = context["log"]
-    log.info("plugin ready")
-    log.warning("optional dependency %r not found, feature disabled", dep)
-    try:
-        risky_init()
-    except Exception:
-        log.exception("unhandled error during setup")  # auto-captures traceback
-```
-
-For CLI entry points (scripts that also run as `__main__`), add a stdlib fallback so the logger works without the server pipeline:
-
-```python
-if __name__ == "__main__":
-    import logging
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
-```
-
-### Diagnostics contribution from frontend (slopsmith#166)
-
-Plugins that hold useful debug state in the browser (active model name, last user input, internal counters) can push it into the diagnostics bundle by calling `window.slopsmith.diagnostics.contribute(plugin_id, payload)` at any time. The contribution API is idempotent — repeated calls overwrite the previous value. Whatever was last contributed before the user hits Export Diagnostics is what lands in `plugins/<plugin_id>/client.json`.
-
-```js
-window.slopsmith.diagnostics.contribute('my_plugin', {
-    schema: 'my_plugin.client_diag.v1',
-    active_preset: getActivePreset(),
-    last_error: _lastError,
-});
-```
-
-Loaded from `static/diagnostics.js` ASAP in `<head>` so the console-wrap is in place before any other script runs. Available on the `window.slopsmith.diagnostics` namespace alongside `snapshotConsole()`, `snapshotHardware()`, `snapshotUa()`, `snapshotLocalStorage()`, `snapshotContributions()`. Keep your payload small (< 100 KB) and don't include secrets — bundles are shared with maintainers.
-
-### Keyboard Shortcuts
-
-Plugins can register keyboard shortcuts via the global `window.registerShortcut()` function. Shortcuts appear in the `?` help panel.
-
-```js
-window.registerShortcut({
-    key: 'k',                       // key value (e.key) or key code (e.code)
-    description: 'Toggle my view',  // shown in the help panel
-    scope: 'player',                // 'global' | 'player' | 'library' | 'settings' | 'plugin-{id}'
-    condition: () => _isMyViewActive, // optional guard
-    handler: (e) => _myAction()      // called when shortcut triggers
-});
-```
-
-**Scope** controls when the shortcut is active:
-- `global` — works on any screen
-- `player` — only on the player screen
-- `library` — only on the home/favorites screens
-- `settings` — only on the settings screen
-- `plugin-{id}` — only when your plugin's screen is active
-
-**Panel-scoped shortcuts:** For plugins that create multiple panels (e.g., splitscreen), shortcuts are automatically scoped to the active panel. Use `const panel = window.createShortcutPanel(id)` to create a panel (it returns the panel object — keep the reference so you can call `panel.clearShortcuts()` during cleanup) and `window.setActiveShortcutPanel(id)` to switch between them. Each panel has its own shortcut registry, so multiple panels can have the same key without collisions.
-
-**Condition** is an optional guard function. If it returns false, the shortcut is skipped even if in scope.
-
-**Key matching:** The handler matches against both `e.key` (character produced) and `e.code` (physical key). Use `e.key` for letters/symbols that depend on keyboard layout, and `e.code` for special keys (e.g. `Space`, `ArrowLeft`).
-
-**Built-in shortcuts:**
-
-| Key | Description |
-|-----|-------------|
-| `?` | Show keyboard shortcuts panel (global) |
-| `Space` | Play/Pause (player only) |
-| `←` / `→` | Seek ±5 seconds (player only) |
-| `Escape` | Back to library (player only) |
-| `[` / `]` | Audio offset ±10ms (Shift: ±50ms) (player only) |
-
-**Debugging:** Open browser console and type `_listShortcuts()` to inspect registered shortcuts.
-
-### General plugin guidelines
-
-- Wrap your plugin code in an IIFE: `(function () { 'use strict'; ... })();`
-- 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
-- Use `window.slopsmith.emit()` / `window.slopsmith.on()` for inter-plugin communication
-- Use `window.registerShortcut()` to add keyboard shortcuts. Clean up with `window.unregisterShortcut(key, scope)` — pass the same scope you registered with, since the default is `'global'` and won't match `player`/`library`/`settings`/`plugin-*` bindings. For panel-scoped shortcuts, prefer `panel.clearShortcuts()`.
-
-## Song Formats
-
-Slopsmith supports two song formats:
-
-### Loose folder (XML charts)
-A directory containing arrangement XML plus an audio file (and optional `manifest.json` + album art). Discovered, indexed, and played directly — see `lib/loosefolder.py`. Metadata follows a `manifest.json` → XML tags → folder-name priority chain. Songs are tagged `format: "loose"` in the library.
-
-### Sloppak (open format)
-An open, hand-editable song package designed for Slopsmith. Exists in two interchangeable forms:
-- **Zip archive** (`.sloppak` file) — distribution form
-- **Directory** (`.sloppak/` folder) — authoring form
-
-**Contents:**
-```
-manifest.yaml          Song metadata (title, artist, album, duration, tuning, arrangement IDs, ...)
-arrangements/
-  lead.json            Note/chord/anchor data in wire format (see song.py)
-  rhythm.json          Files here are driven by manifest.yaml arrangement entries
-  ...                  (e.g. arrangements/<arrangement-id>.json)
-stems/
-  full.ogg             Mixed audio (always present)
-  guitar.ogg           Individual stems (optional, from Demucs split)
-  bass.ogg
-  drums.ogg
-  vocals.ogg
-  piano.ogg
-  other.ogg
-cover.jpg              Album art (optional)
-lyrics.json            Syllable-level lyrics (optional)
-```
-
-Sloppak is the preferred format for new features. The [Stems plugin](https://github.com/topkoa/slopsmith-plugin-stems) provides live stem mixing for sloppak songs.
-
-**Full developer reference:** the authoritative format spec now lives in its own repo —
-[got-feedback/feedback-feedpak-spec](https://github.com/got-feedback/feedback-feedpak-spec)
-([`spec/feedpak-v1.md`](https://github.com/got-feedback/feedback-feedpak-spec/blob/main/spec/feedpak-v1.md)):
-manifest schema, arrangement wire format, and how to extend the format with new data types (drum
-tab, key/scale annotations, etc.). Published as **feedpak**; this codebase still uses the legacy
-**sloppak** name internally — same on-disk format. [docs/sloppak-spec.md](docs/sloppak-spec.md) is
-a local pointer + code map.
-
-**Key code:**
-- `lib/sloppak.py` — format detection, zip/directory resolution, metadata extraction, song loading
-- `lib/sloppak_convert.py` — sloppak assembly pipeline, Demucs stem splitting
-- `lib/song.py` — shared data models (`Note`, `Chord`, `Arrangement`, `Song`) and wire format serialization used by both formats
-
-## Frontend Conventions
-
-- **No frameworks** — vanilla JS, fetch API, DOM manipulation
-- **Globals** — `highway`, `audio`, `playSong()`, `showScreen()`, `createHighway()`, `window.slopsmith`
-- **Storage** — `localStorage` for all user preferences
-- **Styling** — Tailwind CSS utility classes, dark theme (`bg-dark-600`, `text-gray-300`, accent `#4080e0`, gold `#e8c040`). Tailwind is served as a **prebuilt** stylesheet (`static/tailwind.min.css`, regenerated by `bash scripts/build-tailwind.sh`), **never** the runtime Play CDN — the CDN's on-the-fly JIT rescanned the DOM on the main thread and dropped ~26% of frames with the 3D highway (slopsmith-desktop#110). The committed CSS only contains classes the build scanner saw, so CI (`tailwind-fresh`) rebuilds and diffs it; run the build script and commit when you add new classes. A plugin that uses classes not guaranteed in core (notably arbitrary values like `w-[37px]`) MUST ship its own compiled stylesheet via the `styles` manifest key, built with `corePlugins.preflight = false` (utilities only — core ships the one base reset). Plugins MUST NOT load the Tailwind Play CDN or any runtime CSS JIT. See constitution Principle II.
-- **Naming** — camelCase for JS functions, kebab-case for CSS classes, snake_case for plugin IDs
-- **Player layout** — `#player` is `display:flex; flex-direction:column; position:fixed; inset:0`. `#highway` is `flex:1`. `#player-controls` sits at the bottom. Hiding the highway collapses the layout — use `margin-top: auto` on controls if you need to hide it.
-
-## Backend Conventions
-
-- **Framework** — FastAPI with uvicorn
-- **Imports** — flat imports from `lib/` (no package `__init__.py`): `from song import Song`
-- **Database** — SQLite via MetadataDB class with `threading.Lock` for thread safety
-- **WebSocket** — JSON frames, try/except `WebSocketDisconnect`
-- **Error handling** — graceful fallbacks (audio conversion errors don't crash the song, missing art returns placeholder)
-- **Type hints** — used sparingly (`Path | None`, `dict`, `list`)
-- **Docstrings** — minimal; code is self-documenting
-
-## Testing
-
-```bash
-pytest                         # Run all tests
-pytest tests/test_song.py -v   # Specific file
-pytest -k "round_trip" -v      # Pattern match
-```
-
-- Framework: pytest
-- Config: `pyproject.toml` sets `pythonpath = [".", "lib"]` and `testpaths = ["tests"]`
-- CI: GitHub Actions runs pytest on push/PR to main (Python 3.12)
-- Test dependencies: `requirements-test.txt`
-
-## Tuning the note_detect plugin
-
-Detection quality is hard to judge by eye — a player UI that "feels worse" after a code change isn't a regression you can defend in review. The plugin ships with a record-replay-sweep workflow so changes to the detector, the matcher, or the user's environment (A/V offset, latency, channel) can be measured against a single reference take.
-
-Quick orientation:
-- **Reference recording** lives in the gear popover on the player (gated behind Settings → Note Detection → "Detection tuning (advanced)"). Arm before pressing Play; auto-saves a WAV to `static/note_detect_recordings/` on song-end. The directory is bind-mounted, so the host-side harness can read it without a copy step.
-- **Benchmark sloppak** ships in-tree at [docs/benchmarks/note_detect_v1/note_detect_benchmark_v1.sloppak](docs/benchmarks/note_detect_v1/note_detect_benchmark_v1.sloppak) — 8 sections each isolating a different failure mode (low-freq mono, sustained holds, hammer/pull, power chords, dense open chords, bends). Drop it directly into your sloppak DLC folder to install (don't rename — slopsmith keys off the `.sloppak` suffix even though the file is a zip under the hood). The unzipped form lands at `static/sloppak_cache/note_detect_benchmark_v1.sloppak/` after first play. Builder: [docs/benchmarks/note_detect_v1/build_benchmark.py](docs/benchmarks/note_detect_v1/build_benchmark.py).
-- **Headless harness** at [`tools/harness.js`](https://github.com/got-feedback/feedback-plugin-notedetect/blob/main/tools/harness.js) in the note_detect plugin's own repo (cloned into `plugins/note_detect/` locally) runs the same `processFrame` / `matchNotes` / `checkMisses` code path off Node, in seconds per run. Same `note_detect.diagnostic.v1` schema as the in-app Download Diagnostic button.
-- **A/V auto-calibrate** (Settings → Note Detection) reads `timing_error_ms_hits.median` and proposes the av-offset that drives it to zero. Iterative: usually converges in 2–3 Apply rounds.
-
-**Always record at 1.0× playback speed** — half-speed takes produce all-miss garbage because chart times are absolute. **Always use `timing_error_ms_hits` (not all-matched) as a calibration signal** — the all-matched median pins near a constant when the offset is wrong, because the matcher silently snaps to neighbouring chart notes.
-
-Full developer reference (workflow recipes, harness flag table, diagnostic schema, common pitfalls): [docs/note-detect-tuning.md](docs/note-detect-tuning.md).
-
-## Versioning
-
-- **`VERSION`** (repo root) — single source of truth; plain semver string (e.g. `0.2.4`). Bind-mounted into the container and copied by the Dockerfile so it's always available at `/app/VERSION`.
-- **`GET /api/version`** — returns `{"version": "<contents of VERSION>", "source_url": "...", "license_url": "..."}`. The version drives the navbar badge; `source_url` / `license_url` populate the Settings → About links. `source_url` is configurable via the `APP_SOURCE_URL` env var (default `https://github.com/got-feedback/feedback`); `license_url` falls back to `source_url + "/blob/main/LICENSE"` (GitHub-style, default branch `main`) and is overridable via the `APP_LICENSE_URL` env var — set it explicitly when the source is hosted on a non-GitHub forge (GitLab/Gitea/self-hosted) or under a non-`main` default branch. Both env values must be `http(s)`; non-http(s) values are rejected and fall back to the safe default to prevent `javascript:`/`data:` hrefs.
-- **Auto-sync** — `.github/workflows/sync-version.yml` rewrites `VERSION` via a `repository_dispatch` (`desktop-released`) fired from `slopsmith-desktop`'s release job. As an explicit automation-only exception to the "Never push directly to main" rule in Git Workflow below, the sync job commits straight to `main` as `github-actions[bot]` (version bumps are mechanical; the PR round-trip adds no signal). Human contributors must still go through feature branches + PRs. No manual VERSION edits needed. Use the workflow's `workflow_dispatch` trigger with `version: X.Y.Z` for manual runs (recovery / out-of-band bumps).
-- **`CHANGELOG.md`** — follows [Keep a Changelog](https://keepachangelog.com/) format. Update the `[Unreleased]` section with each PR; when `slopsmith-desktop` cuts a release, rename `[Unreleased]` to the new version + date (the VERSION bump itself is automated).
-
-## Git Workflow
-
-- **Never push directly to main** — always create a feature branch and open a PR
-- **Upstream remote** — set `upstream` to the canonical Slopsmith repository; `origin` is your fork
-- **Plugins are gitlinks** — each plugin in `plugins/` is typically its own git repo (submodule or clone). Branch switches on the main repo can clobber plugin directories. Use `git update-index --assume-unchanged` for plugin dirs if needed.
-- **Commit style** — short imperative subject line, blank line, then body explaining *why*
-
-## WebSocket Protocol Reference
-
-The highway WebSocket at `/ws/highway/{filename}?arrangement={index}` streams these messages in order:
-
-| Message | Shape | Description |
-|---------|-------|-------------|
-| `loading` | `{ type: 'loading', stage }` | Status/progress message during extraction or conversion |
-| `song_info` | `{ type, title, artist, arrangement, arrangement_index, arrangements, duration, tuning, capo, centOffset, format, audio_url, audio_error, stems }` | Song metadata. `arrangements` is the full list for the switcher. `audio_url` is `null` when audio is unavailable, in which case `audio_error` is non-null; otherwise `audio_error` is `null`. `stems` is always present — an empty array for non-sloppak songs or sloppak songs with no split stems. `tuning` is an array (6 for guitar, 4 for bass). `centOffset` is a float (cents) from the RS2014 `<centOffset>` field — commonly `-1200.0` for extended-range bass (one octave down), small non-zero values for true-tuned content (e.g. A443 ≈ +11.8 cents), `0.0` when absent. Available via `getSongInfo().centOffset`. |
-| `beats` | `{ type, data: [{ time, measure }] }` | Beat timestamps with measure numbers |
-| `sections` | `{ type, data: [{ time, name }] }` | Named sections (Intro, Verse, Chorus, etc.) |
-| `anchors` | `{ type, data: [{ time, fret, width }] }` | Fret zoom anchors |
-| `chord_templates` | `{ type, data: [{ name, frets: [6] }] }` | Named chord shapes |
-| `lyrics` | `{ type, data: [{ w, t, d }], source }` | Syllables: `w`=word, `t`=time, `d`=duration. `-` joins to previous, `+` = line break. `source` is one of `"xml"`, `"whisperx"`, `"user"` — UI can use it to render an "auto-transcribed" badge for `whisperx`. Sloppaks always include `source` (legacy sloppaks without a `lyrics_source` manifest key default to `"xml"` at load time). Loose folders set it based on which extractor matched. Absent only when no lyrics fired the message at all |
-| `tone_changes` | `{ type: 'tone_changes', base, data: [{ time, name }] }` | Optional — tone change events relative to the arrangement base tone; only sent if tones were found |
-| `notes` | `{ type, data: [{ t, s, f, sus, ho, po, sl, bn, ... }] }` | Single notes |
-| `chords` | `{ type, data: [{ t, notes: [{ s, f, sus, ... }] }] }` | Chord events |
-| `phrases` | `{ type, data: [{ start_time, end_time, max_difficulty, levels: [{ difficulty, notes, chords, anchors, handshapes }] }], total }` | Optional — per-phrase difficulty ladder for master-difficulty slider (slopsmith#48). Only sent when the source chart carries multi-level phrase data (phrase-aware sloppak). Sent in chunks (`data` is a batch, `total` is the full count across messages) to avoid multi-MB single frames. Absent for GP imports and legacy sloppak; consumers must treat missing message as "single fixed difficulty — slider disabled". |
-| `ready` | `{ type: 'ready' }` | All data sent — safe to finalize and start rendering |
-
-Message delivery is incremental. You may receive `loading` updates and `lyrics` before note/chord payloads; `tone_changes` comes after `lyrics` when present and may be omitted entirely. Do not finalize rendering until you receive `ready`.
-
-## Common Pitfalls
-
-1. **playSong wrapper race condition** — The wrapper chain runs outermost-first (last-loaded wrapper runs first). If an inner plugin (e.g. `3dhighway`) does `await import(CDN)`, it yields to the event loop. WebSocket messages (`song_info`, `ready`) can arrive before outer plugins set their callbacks. Use `getSongInfo()` as a fallback rather than relying solely on `_onReady`.
-
-2. **Plugin gitlinks** — Plugins are separate git repos cloned into `plugins/`. Switching branches on the main repo can delete or clobber these directories. Be careful with `git checkout` and `git clean`.
-
-3. **Highway flex layout** — `#highway` has `flex:1` in the player. Hiding it with `display:none` removes the flex child, causing `#player-controls` to float to the top. If you hide the highway, add `margin-top: auto` to the controls div to keep it at the bottom.
-
-4. **Multiple WebSocket connections** — The server supports many simultaneous WebSocket connections to the same song. Split screen panels, lyrics panes, and jumping tab panes each open their own. This is by design — don't try to multiplex.
-
-5. **Plugin load order** — Plugins load alphabetically by directory name. This determines the `playSong` wrapper chain order and which plugin's UI elements appear first. If your plugin depends on another's globals, check at runtime (`typeof window.X === 'function'`), not at load time.
+Everything you'd expect to find here - architecture, running the app, testing, conventions, plugin authoring, first-hour pitfalls - is imported above via `@AGENTS.md`. Updates go in `AGENTS.md`. This file only carries Claude-Code-specific automation references.

CONTRIBUTING.md

@@ -26,7 +26,7 @@ If you forget to sign off, amend the most recent commit with `git commit --amend
 
 ## Plugin licensing
 
-Plugins live in their own repositories and are loaded at runtime — see the [Plugin System section in CLAUDE.md](CLAUDE.md) for the technical contract, and [Plugin Best Practices](CLAUDE.md) for the conventions every plugin should follow (v2/v3 player chrome, the visualization contracts, and the **performance rules** — no per-frame DOM queries or broad `document.body` `MutationObserver`s — that keep the 60 fps highway smooth). Plugins are not subject to AGPL by being loaded into Slopsmith (the loader runs them as separate Python modules / browser scripts), but for the **curated plugin list** to accept your plugin we ask that it be released under an AGPL-3.0-compatible license:
+Plugins live in their own repositories and are loaded at runtime — see [`docs/PLUGIN_AUTHORING.md`](docs/PLUGIN_AUTHORING.md) for the technical contract and [`schema/plugin.schema.json`](schema/plugin.schema.json) for the manifest schema. Plugins are not subject to AGPL by being loaded into Slopsmith (the loader runs them as separate Python modules / browser scripts), but for the **curated plugin list** to accept your plugin we ask that it be released under an AGPL-3.0-compatible license:
 
 - AGPL-3.0-only or AGPL-3.0-or-later
 - GPL-3.0-only or GPL-3.0-or-later
@@ -41,7 +41,7 @@ Plugins under GPL-2.0-only, LGPL-2.1-only, CDDL, EPL, or proprietary terms will
 
 ## Workflow
 
-Standard PR workflow described in [CLAUDE.md → Git Workflow](CLAUDE.md):
+Standard PR workflow described in [AGENTS.md → Git workflow](AGENTS.md#git-workflow):
 - Never push directly to `main`.
 - Create a feature branch on your fork.
 - Open a PR against `got-feedback/feedback:main`.

docs/PLUGIN_AUTHORING.md

@@ -0,0 +1,61 @@
+# Plugin Authoring Guide
+
+Slopsmith's plugin system is the primary extension point. Each plugin lives in `plugins/<name>/` with a `plugin.json` manifest that declares the capability domains, UI contributions, settings metadata, diagnostics, and runtime files the plugin participates in.
+
+This guide is the entry point. Each topic below has a dedicated doc — read what's relevant to what you're building.
+
+## Quickstart
+
+```text
+plugins/my_plugin/
+├── plugin.json          Manifest (required) — see docs/plugin-manifest.md
+├── screen.html          Optional — UI declared through `ui` contributions
+├── screen.js            Optional — hydrates declared frontend capabilities
+├── routes.py            Optional — backend provider/requester implementation
+├── settings.html        Optional — settings UI declared through `ui.settings`
+└── requirements.txt     Optional — pip deps auto-installed on load
+```
+
+Start every plugin by describing its Slopsmith-facing behavior in the manifest with `standards: ["capability-pipelines.v1"]`, native `capabilities`, and redaction-safe `ui` metadata. A plugin with no app-facing behavior beyond metadata can still be this small:
+
+```json
+{
+  "id": "my_plugin",
+  "name": "My Plugin",
+  "version": "0.1.0"
+}
+```
+
+Capability declarations are the source of truth for diagnostics, the Capability Inspector, and plugin tooling. Treat missing capability metadata as an intentional exception for metadata-only or transitional plugin manifests.
+
+## 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`. |
+| **Capability domains** | [capability-domains.md](capability-domains.md) | Active domains, planned domains, and promotion rules. |
+| **Capability recipes** | [capability-recipes.md](capability-recipes.md) | Copyable manifest patterns for provider/requester/observer plugins. |
+| **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"`. |
+| **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. |
+| **Sibling Python imports** | [plugin-sibling-imports.md](plugin-sibling-imports.md) | Multi-file backend plugins. Use `context["load_sibling"]`. |
+| **WebSocket protocol** | [websocket-protocol.md](websocket-protocol.md) | Plugins that read the highway stream directly. |
+| **Testing plugins** | [testing-plugins.md](testing-plugins.md) | Conftest fixtures and Playwright patterns for plugin tests. |
+| **Diagnostics bundle spec** | [diagnostics-bundle-spec.md](diagnostics-bundle-spec.md) | Existing in-depth spec — what's inside a diagnostics export. |
+| **Sloppak format spec** | [sloppak-spec.md](sloppak-spec.md) | Existing in-depth spec — for plugins that read/write sloppaks. |
+
+## General guidelines
+
+- Wrap your plugin code in an IIFE: `(function () { 'use strict'; ... })();`
+- Declare `standards: ["capability-pipelines.v1"]` and native `capabilities` for the plugin's Slopsmith-facing behavior.
+- Use `ui` / `ui_contributions` for plugin-owned UI surfaces so the host can attribute them in diagnostics and support bundles.
+- Use `localStorage` for user-facing settings, prefixed with your plugin id.
+- Prefer native capability commands, events, and provider registration over private globals. If a domain you need is not active yet, document the gap in the PR instead of baking in a new private integration.
+
+## Licensing for curated plugins
+
+Plugins submitted for inclusion in Slopsmith must use AGPL-3.0-only. See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full policy. The `plugin.json` schema enforces this via the `license` field enum — see [plugin-manifest.md](plugin-manifest.md).
+
+Add an `SPDX-License-Identifier: AGPL-3.0-only` comment to plugin source files (`screen.js`, `routes.py`, helper modules, and similar authored code) so the manifest license and source-file metadata stay aligned.

docs/capability-domains.md

@@ -16,7 +16,7 @@ Only declare `plugin-runtime-idempotent.v1` when repeated script hydration canno
 
 ## UI Contributions
 
-Legacy `nav`, `screen`, and `settings` fields still work through the existing plugin loader. PR1 keeps UI capability domains out of the runtime graph, so migrated plugins should not treat `ui.navigation`, `ui.plugin-screens`, or `settings` as active capability contracts yet. Their candidate manifest shape is reserved for a future UI-host PR:
+New plugin UI should declare stable `ui` contribution metadata so diagnostics and support tools can attribute surfaces before runtime code hydrates. The runtime host for UI placement is still promoted by a future UI-host PR, but manifests can use the candidate shape now:
 
 ```json
 {
@@ -28,25 +28,30 @@ Legacy `nav`, `screen`, and `settings` fields still work through the existing pl
 }
 ```
 
-Core continues to load legacy UI fields normally. It does not emit PR1 compatibility shim entries for UI placement or visualization `type`; the PR that promotes those domains will own their shim accounting and tests.
-
 ## Runtime Domains
 
-Declare non-UI runtime surfaces under `domains` or `runtime_domains`:
+Declare non-UI runtime surfaces under `capabilities`:
 
 ```json
 {
-  "domains": {
-    "library": { "role": "provider" }
+  "capabilities": {
+    "library": {
+      "roles": ["provider"],
+      "operations": ["query-page", "query-artists", "query-stats"],
+      "mode": "active",
+      "compatibility": "none",
+      "safety": "safe",
+      "version": 1
+    }
   }
 }
 ```
 
-If a plugin still uses `routes`, the backend loader continues to load `routes.py` normally. PR1 does not expose that legacy surface as `backend.routes`; the backend route domain is deferred until a future PR has a concrete route/provider workflow and privilege review.
+Backend route metadata should support a declared capability domain. A generic `backend.routes` domain is deferred until a future PR has a concrete route/provider workflow and privilege review.
 
 Plugins that call `context["register_library_provider"](...)` are attributed to the loading plugin id in `/api/library/providers` as `owner_plugin_id`. The browser library capability module at [static/capabilities/library.js](../static/capabilities/library.js) owns the `library` domain as a `provider-coordinator`: it refreshes `/api/library/providers`, registers the built-in `local` provider as `core.library.local`, and registers plugin-backed providers under their `owner_plugin_id` when one is known. Provider manifests should still declare the `library` capability so diagnostics and the bundled inspector can show intended relationships before the backend route code runs.
 
-Route-only external plugins that participate in library workflows without registering a browsable provider should declare requester/observer intent instead of provider ownership when they adopt this contract in their own repositories. This PR documents the generic shape only: such plugins use `library` requester/observer `requests` and `observes` declarations and do not appear as providers, owners, or separate `backend.routes` domains.
+Route-only external plugins that participate in library workflows without registering a browsable provider declare requester/observer intent instead of provider ownership when they adopt this contract in their own repositories. This PR documents the generic shape only: such plugins use `library` requester/observer `requests` and `observes` declarations and do not appear as providers, owners, or separate `backend.routes` domains.
 
 ```json
 {
@@ -69,21 +74,19 @@ Capability declarations may include a short `description`. The bundled Capabilit
 
 ## Audio Graph/Session Domains
 
-The audio graph/session slice promotes four player-audio domains into the runtime graph: `audio-mix`, `audio-input`, `audio-monitoring`, and `stems`. The browser module at [static/capabilities/audio-session.js](../static/capabilities/audio-session.js) owns the active session boundary, contributes diagnostics under `slopsmith.audio_session.diagnostics.v1`, and records compatibility bridge hits for legacy audio surfaces.
+The audio graph/session slice promotes four player-audio domains into the runtime graph: `audio-mix`, `audio-input`, `audio-monitoring`, and `stems`. The browser module at [static/capabilities/audio-session.js](../static/capabilities/audio-session.js) owns the active session boundary, contributes diagnostics under `slopsmith.audio_session.diagnostics.v1`, and records compatibility bridge hits for older audio surfaces.
 
-`audio-mix`, `audio-input`, and `audio-monitoring` are core-owned provider-coordinator domains. They expose bounded inspect/register/start/stop style commands, redaction-safe diagnostics, and bridge accounting for legacy fader, analyser, input, and monitoring handshakes.
+`audio-mix`, `audio-input`, and `audio-monitoring` are core-owned provider-coordinator domains. They expose bounded inspect/register/start/stop style commands, redaction-safe diagnostics, and bridge accounting for older fader, analyser, input, and monitoring handshakes.
 
 For `audio-mix`, native fader providers register mix participants with stable `participantId`, `kind`, `sourceMode`, optional `logicalFaderKey`, and `fader` metadata. The public command surface is `inspect`, `list-faders`, `get-fader-value`, `set-fader-value`, `inspect-route`, `inspect-analyser`, `register-participant`, and `unregister-participant`; provider operations are `fader.get-value`, `fader.set-value`, `route.get-current`, and `analyser.get-summary`. Providers own persistence for plugin faders and must return committed values from set operations so the player mixer can display the value that actually applied.
 
-Legacy `window.slopsmith.audio.registerFader(...)` remains supported as an audio-mix compatibility bridge. The bridge registers a compatibility-backed participant, wraps legacy `getValue`/`setValue` callbacks as provider operations, and preserves `window.slopsmith.audio.getFaders()` for external callers. If a native participant and a legacy fader share the same logical fader key, the native participant owns the visible control; the legacy participant is retained for diagnostics with `supersededBy` and an `overshadowed` bridge hit. Removal gates for the bridge are: native providers cover bundled mixer integrations, diagnostics show no unexpected legacy hits in normal playback, and repeated plugin hydration does not create duplicate faders.
-
 Audio-mix diagnostics live under `slopsmith.audio_session.diagnostics.v1`. The `audio-mix` domain snapshot includes session state, participants, visible fader summaries, required participant-kind coverage, route summary, analyser summary, bridge hits, and bounded recent outcomes. Fader outcomes include operation name, participant id, fader id, status such as `committed`, `normalized`, `unavailable`, or `timeout`, and a bounded reason. Diagnostics must not include raw audio buffers, FFT arrays, device labels, stable hardware identifiers, secrets, or unredacted local paths; route/analyser payloads are summaries only.
 
 For `audio-input`, native providers register source summaries with `sourceId`, `providerId`, `logicalSourceKey`, `kind`, redaction-safe label/pseudonym, `availability`, `channelSummary`, `sourceMode`, and provider operations. The public command surface is `inspect`, `list-sources`, `register-source`, `unregister-source`, `select-source`, `open-source`, and `close-source`; provider operations are `source.enumerate`, `source.describe`, `source.open`, and `source.close`. `inspect`, `list-sources`, and `select-source` are prompt-free and never open live input or call enumeration. `source.enumerate` runs only when explicitly requested by provider/user discovery. `open-source` is the permission boundary: it routes to `source.open`, attributes the requester, checks the selected source and requested channel shape, and records `handled`, `denied`, `degraded`, `failed`, `no-owner`, `no-handler`, `unsupported-command`, or `incompatible-version` outcomes.
 
 Selected input is persisted by `logicalSourceKey` when browser storage is available. If storage is unavailable, the in-memory selection remains usable for the current session and diagnostics report the storage status. Start/stop/song switches preserve selected input independently of playback transport while clearing live open sessions. Compatible requesters share one open session per logical source and channel shape; requester references are released via `close-source`, and the provider receives `source.close` only after the last requester releases.
 
-Compatibility-backed input sources should record `sourceMode: "compatibility"` plus `compatibilitySource` and, when applicable, an `audio-input.legacy-source` bridge hit. If a native provider and a compatibility-backed source share the same logical source key, the native source owns the visible source list and the compatibility source is retained in diagnostics with `supersededBy`. Removal gates for input bridges are: native providers cover bundled source discovery/open flows, diagnostics show no unexpected compatibility hits in normal playback, denied/unavailable/failure outcomes are distinguishable, repeated hydration does not create duplicate sources, and support snapshots contain no raw device labels, hardware ids, paths, secrets, live handles, buffers, samples, or waveform data.
+Compatibility-backed input sources are retained for diagnostics only when a native provider supersedes the same logical source key. Removal gates for input bridges are: native providers cover bundled source discovery/open flows, diagnostics show no unexpected compatibility hits in normal playback, denied/unavailable/failure outcomes are distinguishable, repeated hydration does not create duplicate sources, and support snapshots contain no raw device labels, hardware ids, paths, secrets, live handles, buffers, samples, or waveform data.
 
 For `audio-monitoring`, native providers register monitoring summaries with `providerId`, `logicalMonitoringKey`, redaction-safe label/pseudonym, `availability`, `sourceMode`, provider operations, `directMonitor`, and `latencySummary`. The public command surface is `inspect`, `list-providers`, `register-provider`, `unregister-provider`, `select-provider`, `start`, `stop`, and `set-direct-monitor`; provider operations are `monitoring.start`, `monitoring.stop`, `monitoring.status`, and `monitoring.set-direct-monitor`. `inspect`, `list-providers`, `select-provider`, and `monitoring.status` are prompt-free and must not open audio input or start monitoring.
 
@@ -93,25 +96,11 @@ Monitoring sessions are keyed by provider, selected source, required channel sha
 
 Direct-monitor state is user-authoritative. `set-direct-monitor` updates the user's/default preference and applies provider control to active sessions only when the provider supports it. Requester `directMonitorRequirement` values are advisory constraints: when they conflict with the user's preference or provider support, the requester/session is marked degraded or unsupported, but the stored user/default preference is not changed.
 
-Compatibility-backed monitoring providers should record `sourceMode: "compatibility"` plus `compatibilitySource` (which becomes the bridge id, defaulting to `audio-monitoring.legacy-provider` when unset) and, when applicable, the `audio-monitoring.audio-barrier` startup-barrier bridge hit. If a native provider and compatibility-backed provider share a logical monitoring key, the native provider owns the visible provider list and the compatibility provider is retained in diagnostics with `supersededBy`. Removal gates for monitoring bridges are: native providers cover bundled start/stop/status/direct-monitor flows, normal playback shows no unexpected legacy hits, background requesters cannot silently start live monitoring, repeated hydration does not duplicate providers or sessions, and support snapshots contain no raw device labels, hardware ids, paths, secrets, live handles, buffers, samples, waveform data, recordings, or provider-private payloads.
+Compatibility-backed monitoring providers are retained for diagnostics only when a native provider supersedes the same logical monitoring key. Removal gates for monitoring bridges are: native providers cover bundled start/stop/status/direct-monitor flows, normal playback shows no unexpected compatibility hits, background requesters cannot silently start live monitoring, repeated hydration does not duplicate providers or sessions, and support snapshots contain no raw device labels, hardware ids, paths, secrets, live handles, buffers, samples, waveform data, recordings, or provider-private payloads.
 
 `stems` is different: `core.audio.session` is a coordinator, not the semantic owner of stem playback. The Stems plugin, or another active stem provider, remains the provider/owner of actual stem state, mute/restore mechanics, and per-song availability. The session coordinator records the active provider via `registerStemOwner(...)`, brokers claim/override/orphan diagnostics, and returns `no-owner` when no stem provider is available.
 
-New bundled audio code should use the session host or native capability dispatch instead of adding new globals, private stem-state reads, direct analyser ownership, or plugin-specific handshakes. Existing legacy paths remain supported through named compatibility bridges until their migration notes and removal gates are satisfied.
-
-## Audio Effects Domain
-
-The audio-effects slice promotes `audio-effects` as a core-owned provider-coordinator domain implemented by [static/capabilities/audio-effects.js](../static/capabilities/audio-effects.js). The host owns provider selection, compatible executor selection, route state, fallback accounting, redaction-safe diagnostics, and the constrained chain-plan schema. Providers do not call executors. Provider code proposes plans and, for execution requests, returns a provider-private trusted asset map to the host; the host immediately hands that private request to a compatible executor such as trusted Desktop native audio or NAM Tone's browser/WASM executor.
-
-The public command surface is `inspect`, `list-providers`, `list-executors`, `register-provider`, `unregister-provider`, `register-executor`, `unregister-executor`, `select-chain`, `resolve-plan`, `load-plan`, `inspect-route`, `list-mappings`, `upsert-mapping`, `delete-mapping`, `activate-mapping`, `clear-active-mapping`, `bypass`, `restore`, `fallback`, `activate-segment`, `set-stage-bypass`, `set-stage-parameter`, and `record-bridge-hit`. Provider operations are `chain.resolve`, `chain.inspect`, `mapping.list`, `mapping.upsert`, `mapping.delete`, `mapping.activate`, `mapping.clear-active`, `segment.activate`, `stage.set-bypass`, `stage.set-parameter`, `route.bypass`, and `route.restore`; executor operations are `loadChainPlan`, `activateSegment`, `setStageBypass`, and `setStageParameter`. Fresh chain selection and route bypass/restore require `authorization: "user-action"` or `authorization: "restore-selection"`; physical loading through `load-plan` requires `authorization: "user-action"`, `authorization: "restore-selection"`, or `authorization: "playback-session"`. Background requesters may inspect the current route and resolve an already selected compatible provider.
-
-Core also owns the durable public mapping index at `/api/audio-effects/mappings`. A mapping answers "for this song/tone, this provider has an addressable effect plan"; it does not contain the provider's preset or chain data. Rows are keyed by `song_key + tone_key + provider_id`, carry an opaque `provider_ref`, and may be marked as the active mapping for that song/tone. Providers CRUD their own rows through the audio-effects host and resolve `provider_ref` inside their own storage when `chain.resolve` runs. This lets NAM Tone and Rig Builder coexist for the same song/tone while core owns arbitration and fallback order. `song_key` should be the playback domain's redaction-safe settings key when available; `filename` is optional legacy/debug context for migration and display.
-
-Providers register stable `providerId`, `pluginId`, `routeKey`, priority, availability, source mode, operations, and operation handlers. Executors register stable `executorId`, `pluginId`, `routeKey`, priority, availability, source mode, supported provider ids, supported stage kinds, optional maximum stage count, operations, and handlers. The host chooses the highest-priority enabled provider for a route unless the caller requests a specific provider, then chooses the highest-priority compatible executor for that provider and resolved plan. Compatibility means both provider-compatible and plan-compatible: a browser/WASM NAM executor can advertise `providerIds: ["nam-tone"]`, `supportedKinds: ["nam", "ir"]`, and `maxStages: 2`, so it will not be asked to execute a Rig Builder VST/full-chain plan. If a selected provider has no compatible executor and the caller supplies a fallback provider, the host may fall back to that provider; if the caller explicitly requested the original provider, the host reports `unavailable` instead of silently changing providers. The initial default route is `desktop-main`, matching the desktop native executor path planned for full-chain NAM/IR/VST playback while still allowing browser executors for non-Desktop runtimes.
-
-`chain.resolve` returns schema `slopsmith.audio_effects.chain_plan.v1`. A valid plan includes `planId`, `routeKey`, `providerId`, `stages`, optional `segments`, and optional redaction-safe summaries. Each stage exposes only stable opaque `stageId`, `kind` (`nam`, `ir`, `vst`, `utility`, or `bypass`), `role` (`pre-pedal`, `amp`, `cab`, `rack`, `master-pre`, etc.), opaque `assetRef`, optional opaque `stateRef`, bypass state, gain summary, and safe summary metadata. Raw file paths, URLs, model filenames, IR filenames, VST state blobs, native preset JSON, callbacks, handles, DOM nodes, audio buffers, samples, and waveform data are rejected or omitted.
-
-Diagnostics live under `slopsmith.audio_effects.diagnostics.v1`. The snapshot includes provider summaries, executor summaries, route summaries, bridge hits, bounded recent outcomes, limits, and redaction notes. It intentionally omits full chain plans, stage asset references, provider-private mapping payloads, raw filenames, and song keys; diagnostics should explain which provider/executor/route failed without leaking local library structure or licensed asset names. Legacy NAM Tone/Rig Builder fetch interception, direct Desktop `loadPreset` calls, legacy tone controls, old `nam_tone.db` `tone_mappings` access, and MIDI/external effect handoffs are attributed through `audio-effects.legacy-nam-routing`, `audio-effects.legacy-native-load`, `audio-effects.legacy-tone-controls`, `audio-effects.legacy-tone-db`, and `audio-effects.legacy-midi-amp` bridge records while providers migrate.
+New bundled audio code should use the session host or native capability dispatch instead of adding new globals, private stem-state reads, direct analyser ownership, or plugin-specific handshakes.
 
 ## Playback Control Plane
 
@@ -119,51 +108,7 @@ The playback slice promotes `playback` as a core-owned command domain implemente
 
 `static/app.js` remains the transport data plane. It registers a private playback adapter that can start songs, pause/resume/stop, seek, and manage loops, but the capability snapshot never exposes the `<audio>` element, JUCE player object, raw audio buffers, native route handles, samples, waveforms, recordings, local file paths, or URL payloads. Exported diagnostics use pseudonymous `target-*` ids for arrangement-scoped identity and hashed `settings-*` keys for per-song plugin settings; the local Capability Inspector may show visible title, artist, and arrangement labels for the active song.
 
-Legacy playback surfaces remain supported during migration and are attributed through bridges such as `playback.window-play-song`, `playback.song-events`, `playback.window-slopsmith-transport`, `playback.loop-api`, and native route handoff records. Fresh audible `start` commands require `authorization: "user-action"`; background requesters may inspect or control an existing session, but user-priority pause/stop decisions block lower-priority automation until a user action resumes or starts a new session.
-
-## Progression Domain
-
-The progression slice (spec 010) promotes `progression` as a core-owned command domain implemented by [static/v3/progression-core.js](../static/v3/progression-core.js). Core owns the player's mastery rank (onboarding calibration + instrument-path levels), the challenge/quest engine, the Decibels wallet, and the cosmetics shop; all definitions are bundled content under `data/progression/` so new paths, levels, challenges, quests, and shop items are JSON edits, never code.
-
-The public command surface is `inspect`, `record-event`, `list-shop`, `buy-item`, and `equip-item`. `record-event` accepts only whitelisted externally-postable event types (`minigame_run` in v1); `song_completed` is server-derived inside `/api/stats` so scored-session authority stays in one place and is denied at this surface. `buy-item` and `equip-item` require `authorization: "user-action"`. Backend plugins use the symmetric plugin-context hook `record_progression_event` (the minigames hub reports runs through it), which trusts backend code and skips the HTTP whitelist.
-
-The domain emits `challenge-completed`, `quest-completed`, `path-level-up`, `rank-changed`, `db-changed`, `calibration-completed`, and `cosmetic-equipped` on the capability surface, mirrored as `progression:*` events on `window.slopsmith` for non-capability consumers. Diagnostics live under `slopsmith.progression.diag.v1` and contain content-load warnings, rank/path-level/quest counts, and wallet totals only — no song filenames or display names.
-
-Decibels are earned exclusively by playing (songs, minigame runs, quest rewards); there is no real-money acquisition path and none may be added. The wallet tracks spend separately from the monotonic lifetime-earned total, so per-source XP resets and `db_earned` goals stay correct. A deferred release slice adds a `contributor` role so plugins can ship their own challenge/quest content (e.g. a drums plugin contributing drums challenges); content stays core-bundled until then.
-
-## Visualization Domain
-
-The visualization slice (cap:6) promotes `visualization` as a core-owned provider-coordinator implemented by [static/capabilities/visualization.js](../static/capabilities/visualization.js). Viz plugins are providers of the highway renderer surface; the core picker/auto-match machinery in `static/app.js` stays the selection workflow and attributes every renderer change into the domain.
-
-The public command surface is `inspect`, `list-providers`, `select-renderer`, and `clear-renderer`. Selection delegates to the existing picker (`setViz`) so localStorage persistence, WebGL2 gating, and fallback semantics have exactly one implementation. The domain emits `providers-refreshed`, `renderer-changed` (with a `source` of `auto-match`, `user-select`, `fallback`, or `command:<requester>`), `renderer-ready`, and `renderer-failed`.
-
-Provider discovery is still the legacy surface — `type: "visualization"` manifests populate the picker and `window.slopsmithViz_*` factory globals carry the renderer contract — and both are registered as compatibility shims (`visualization:type-visualization-manifest`, `visualization:window.slopsmithViz_*`) with hit accounting, so the Inspector shows exactly how much of the domain still rides the bridge. Plugins migrate by declaring a `visualization` provider capability in their manifests; the renderer factory contract (`init`/`draw`/`resize`/`destroy`, `contextType`, `matchesArrangement`) is unchanged.
-
-**Per-instance provider settings (#849).** A provider may declare a `settings` array on its `visualization` capability — generic control descriptors (`{ key, label, type: "toggle" | "range" | "select", default, min/max/step, options }`) the capability-pipelines schema validates on *any* domain (the field lives on the shared `capabilityDeclaration`, not a visualization-only spot — see `docs/plugin-manifest.schema.json`). Descriptors flow through the **generic participant model**: the backend validates them for `/api/plugins` (`plugins/__init__.py`), `static/capabilities.js` normalizes + preserves them on the registered participant (so generic `inspect('visualization')` carries them), and the visualization owner reads them back from the participant by id — no app.js/picker side channel. They surface in the `list-providers` snapshot (each provider's `settings`, deep-frozen) plus a `provider_policy.hasSettings` flag in diagnostics, so a consuming host — splitscreen's per-panel control popover — can render the controls generically without per-plugin hardcoding. The visualization domain's **apply contract**: a provider that declares `settings` MUST implement `applySetting(key, value)` on its renderer instance (the host calls it on the specific per-panel instance, which is inherently per-panel — no canvas→panel resolution, no shared global keys); `getSetting(key)` is optional (the host falls back to the declared `default`). The host owns persistence. **This core slice lands the declarative surface + participant plumbing only** — no bundled provider declares `settings` yet (`highway_3d` still ships the legacy `factory.panelControls` static). The `highway_3d` migration and the splitscreen generic consumer are the remaining #849 follow-ups.
-
-Diagnostics live under `slopsmith.visualization_capability.v1` and contain provider ids/labels/context types, the active renderer id and its selection source, the last auto-match outcome (resolved id + whether any predicate claimed the song), and the last failure (provider id + reason) — never song filenames, titles, or arrangement names. Per-panel selection (splitscreen #90) and per-panel provider settings (#849) are tracked follow-ups; the domain currently models the primary highway surface.
-
-## Note-Detection Domain
-
-The note-detection slice (spec 009, issues #727/#728) promotes `note-detection` as a core-owned provider-coordinator implemented by [static/capabilities/note-detection.js](../static/capabilities/note-detection.js). Doctrine per [specs/009-note-detection-domain/spec.md](../specs/009-note-detection-domain/spec.md): the domain exposes detection PRIMITIVES through requester-owned, context-scoped bindings — a monophonic pitch estimate and a polyphonic "is this note set ringing now?" verification — and consumers own all judgment semantics (hit windows, streaks, accuracy, tiers). Hit/miss/verdict results flow through the domain as observability events, never as domain-owned scoring.
-
-The public command surface is `inspect`, `register-provider`, `unregister-provider`, `open-binding`, `close-binding`, `set-target`, and `clear-target`. Providers declare a kind — `midi` (a digital instrument producing exact verdicts, e.g. the keys highway's Web-MIDI input), `engine` (the desktop JUCE verifier), or `js` (the browser harmonic-comb / YIN fallback) — and the primitives they serve (`pitch.estimate`, `verify.target`). Each binding carries its requester's own redacted context summary (arrangement kind, string count, capo, MIDI range), independent of whatever song the host highway has loaded; concurrent bindings never perturb one another (spec 009 FR-003). With no provider registered, `open-binding` reports `unavailable` — consumers degrade, never block.
-
-The legacy chart-coupled surface — `highway.setNoteStateProvider(fn)`, the single-global-detector path spec 009 retires — keeps working unchanged and is wrapped for compatibility-shim hit accounting (`note-detection:highway.setNoteStateProvider`). Migrating the chart `note_detect` consumer, Step Mode verify, minigames YIN scoring, and the `setVerifyTarget` bridge onto real bindings — and wiring per-binding tuning contexts into the engine verifier — is the remainder of the spec-009 slice and lands behind the Spec 003 migration gate.
-
-Diagnostics live under `slopsmith.note_detection_capability.v1` and contain provider ids/labels/kinds, binding summaries (requester, provider, redacted context, target size), availability, and the last bounded outcome (event, binding, provider, MIDI number, hit flag) — never raw audio buffers, sample data, device labels, or song identity.
-
-## MIDI-Input Domain
-
-The MIDI-input slice (spec 012, issues #873/#880) promotes `midi-input` as a **core-owned** provider-coordinator implemented by [static/capabilities/midi-input.js](../static/capabilities/midi-input.js) — the MIDI analog of `audio-input`. It is deliberately separate from `audio-input` (whose source/`open` contract is audio-frame-centric: channel shapes, sample buffers) because MIDI carries discrete messages, not audio; and it is **not** owned by any feature plugin, so the device-access boundary outlives the input-setup wizard (exactly as `audio-input` is `core.audio.session`-owned). Consumers — the `input_setup` onboarding wizard, the `piano`/keys and `drums` plugins, and (as a follow-up, #881) note-detection's Web-MIDI provider — converge here on ONE device-access boundary: one permission prompt, one source list, one redaction boundary, retiring private per-plugin `navigator.requestMIDIAccess()` calls.
-
-Native providers register source summaries with `providerId`, a stable `sourceId`, a derived redaction-safe `logicalSourceKey` (`providerId::sourceId`), `kind: "midi"`, a label, and `availability`. The public command surface is `inspect`, `list-sources`, `discover`, `select-source`, `open-source`, and `close-source`; provider operations are `source.enumerate`, `source.describe`, `source.open`, and `source.close`. `inspect`, `list-sources`, and `select-source` are prompt-free and never request MIDI access. Unlike audio (where `getUserMedia` gates labels and `open-source` is the prompt), Web-MIDI's `requestMIDIAccess()` gates the whole input list, so **`discover` is the permission boundary** and records `denied`/`unavailable` outcomes; `open-source` then attaches a shared listener session and never re-prompts.
-
-Selected input is persisted by `logicalSourceKey` (`slopsmith.midiInput.selectedLogicalSourceKey`) when browser storage is available. Compatible requesters share one open session per source; each later calls `close-source`, and the provider receives `source.close` only after the last requester releases. Live MIDI message delivery (for the "play a note / hit a pad" calibration check) is exposed to in-page consumers through the public `window.slopsmith.midiInput` session handle only — never as raw capability events or diagnostics.
-
-The reserved `midi-control` domain is the planned **sibling** for control mappings (CC/pitchbend/note → action routing) and will consume `midi-input` for device access (spec 013 / #882); this slice carves the device control plane out so `midi-control` can stay mappings-only. `midi-control` stays RESERVED (documentation-only) until a concrete mapping consumer + tests exist, per the future-domain governance.
-
-Diagnostics live under `slopsmith.midi_input.diagnostics.v1` and contain provider ids, source ids/keys/kinds/availability, the selected key, and open-session keys — **device labels are redacted** and no raw MIDI messages are ever included.
+Fresh audible `start` commands require `authorization: "user-action"`; background requesters may inspect or control an existing session, but user-priority pause/stop decisions block lower-priority automation until a user action resumes or starts a new session.
 
 ## Capability Roles
 
@@ -192,9 +137,9 @@ Core domains include review metadata in diagnostics:
 - `active`: wired to current Slopsmith behavior and expected to work as an integration point.
 - `diagnostic`: support/inspection-only runtime surfaces.
 
-PR1 includes only the delivered domains listed in [capability-roadmap.md](capability-roadmap.md): `pipeline`, `diagnostics`, and `library`. The follow-up audio graph/session slice promotes `audio-mix`, `audio-input`, `audio-monitoring`, and a coordinated `stems` surface. The playback slice promotes `playback` as an active transport control plane. The audio-effects slice promotes provider-selected effect-chain planning while leaving physical processor loading to compatible executors such as trusted Desktop native audio or a browser/WASM executor. The visualization slice promotes `visualization` as the highway renderer provider-coordinator, and the note-detection slice (spec 009) promotes `note-detection` as the detection-binding control plane. Backend routes, app UI, settings, and other hardware-facing domains remain documented in the roadmap and safety matrix until their own host workflow/provider slice exists.
+PR1 includes only the delivered domains listed in [capability-roadmap.md](capability-roadmap.md): `pipeline`, `diagnostics`, and `library`. The follow-up audio graph/session slice promotes `audio-mix`, `audio-input`, `audio-monitoring`, and a coordinated `stems` surface. The playback slice promotes `playback` as an active transport control plane. Backend routes, app UI, settings, visualization, note-detection, and other hardware-facing domains remain documented in the roadmap and safety matrix until their own host workflow/provider slice exists.
 
-Capability metadata is versioned by the `capability-pipelines.v1` standard. Invalid roles, commands, operations, requests, observes, emits, events, owner kinds, compatibility modes, ownership policies, safety classes, or version fields are excluded from the capability graph and surfaced through `capability_validation_warnings`; legacy plugin fields continue to load through their existing app paths. Plugins that declare a future `capability-pipelines` version are reported through `capability_unsupported_versions` and their runtime handlers are marked incompatible.
+Capability metadata is versioned by the `capability-pipelines.v1` standard. Invalid roles, commands, operations, requests, observes, emits, events, owner kinds, compatibility modes, ownership policies, safety classes, or version fields are excluded from the capability graph and surfaced through `capability_validation_warnings`. Plugins that declare a future `capability-pipelines` version are reported through `capability_unsupported_versions` and their runtime handlers are marked incompatible.
 
 `diagnostics` and `pipeline` are adjacent support domains. `diagnostics` is the read-only snapshot/export surface: `snapshot` returns the redaction-safe state used by support bundles and the Capability Inspector. `pipeline` is the graph operations surface: `inspect`, `validate`, and `participant.set-enabled` operate on the capability graph itself and emit graph lifecycle events such as `resolved`, `runtime.validated`, and `participant.state-changed`.
 
@@ -229,7 +174,7 @@ Owner participants use a `kind` that describes how the domain is coordinated:
 - `diagnostic`: read-only support and inspector surfaces.
 - `privileged`: command execution needs an explicit enforcement plan before shipping.
 
-Legacy `ownership` remains accepted in manifests for compatibility and diagnostics, but new domains should prefer `kind` plus participant roles. Ownership is derived for core owners where possible: `provider-coordinator` behaves like a multi-provider domain, diagnostics are diagnostic-only, privileged owners are privileged, and command/event owners are exclusive by default.
+New domains should prefer `kind` plus participant roles. Ownership is derived for core owners where possible: `provider-coordinator` behaves like a multi-provider domain, diagnostics are diagnostic-only, privileged owners are privileged, and command/event owners are exclusive by default.
 
 The compatibility ownership vocabulary remains:
 
@@ -244,9 +189,9 @@ Dispatch results use explicit outcomes: `handled`, `transformed`, `denied`, `fai
 
 ## Deferred Core Adapters
 
-UI placement and settings contributions are real Slopsmith surfaces, but they are not PR1 capability contracts (visualization is active as of the cap:6 slice; note-detection as of the spec-009 slice). Audio mixer/session domains are active as of the audio graph/session slice, playback is active as of the playback control-plane slice, and audio-effects is active as a provider/route/chain-plan coordinator; plugins should keep using current documented APIs for remaining areas until the corresponding domain PR ships the host workflow, command/event contract, compatibility shims, diagnostics fields, and tests.
+UI placement, settings contributions, visualization, and note-detection are real Slopsmith surfaces, but they are not PR1 capability contracts. Audio mixer/session domains are active as of the audio graph/session slice, and playback is active as of the playback control-plane slice. For remaining areas, document the capability gap and avoid adding new private integration surfaces until the corresponding domain PR ships the host workflow, command/event contract, diagnostics fields, and tests.
 
-The library provider workflow is the PR1 core adapter and is implemented natively as the `library` capability module. Provider refresh, selection, and sync run through `library` owner commands; backend provider registration remains the way providers enter the library registry, and the browser module turns that registry into provider participants. The app event bus continues to dispatch local `window.slopsmith` events for legacy listeners; playback now mirrors song transport, route, seek, and loop lifecycle into `playback`, and visualization attributes renderer selection/failure, while navigation, note, and route-only surfaces remain outside capability domains until their own slices land.
+The library provider workflow is the PR1 core adapter and is implemented natively as the `library` capability module. Provider refresh, selection, and sync run through `library` owner commands; backend provider registration remains the way providers enter the library registry, and the browser module turns that registry into provider participants. Playback mirrors song transport, route, seek, and loop lifecycle into `playback`, while navigation, note, visualization, route-only, and highway rendering surfaces remain outside capability domains until their own slices land.
 
 The direct `window.highway` object remains the renderer data plane. Per-frame reads such as notes, chords, beats, and renderer hooks should not be moved behind asynchronous capability commands until there is a dedicated chart/render facade.
 
@@ -254,13 +199,13 @@ The direct `window.highway` object remains the renderer data plane. Per-frame re
 
 Large management surfaces should prefer plugin-owned UI over crowding normal Settings. First-party management plugins can contribute screens and settings panels while core keeps shared services and diagnostics contracts centralized.
 
-The bundled Capability Inspector plugin is the support surface for the current graph. It reads `window.slopsmith.capabilities.snapshotDiagnostics()`, filters by domain, and summarizes manifest participants, runtime participants, conflicts, unsupported versions, safety classes, expected legacy event surfaces, and compatibility shim hits without rendering raw runtime objects. Domains are grouped in review order: application/library, player/audio runtime, plugin-defined surfaces, then capability runtime. In the all-domains view, each domain starts collapsed with a domain-specific icon plus compact summary badges for participant-lane count, endpoint count, observed links, shimmed links, and status; badge labels live in tooltips/ARIA labels so the header stays scannable. Clicking the domain label expands or collapses the domain, opening the same graph view used by the single-domain filter. The graph places owner details and right-aligned command/event groups on the left, with short owner descriptions bottom-aligned as the final part of that pane. Participant usage is grouped the same way on the right, with observed or shimmed links between border-aligned endpoint ports. In multi-provider domains, links to provider participants use provider-family colors: purple for owner-to-provider command delegation and a lighter violet for provider events. Provider participants, including `library` sources, stay on the right lane and show a provider icon in their header. Headers show role-aware core/non-core origin badges such as Core owner, Core provider, or Non-core participant; owner headers place the origin badge directly after the owner icon, and the built-in local library provider is marked as core-origin. Observer and requester roles are implied by the command/event links rather than separate header badges. Participant cards are shown only when the plugin or runtime source has visible command or event usage for the current graph filter; domains with no such usage show zero participants, and attribution-only shims with no matching endpoint stay out of the lane. Command and event groups can collapse; when collapsed, all links for that side and group converge on the single group port. Hovering a participant, endpoint, or command/event group emphasizes the matching links and dims unrelated links; owner-side labels outside the current focus de-emphasize so the active source endpoints are easy to track. Expanded domain graphs progressively enhance to Cytoscape.js overlays that route bezier links between measured DOM endpoint ports, while keeping the HTML lanes as the fallback and readable data surface. Its Plugins-menu entry is hidden by default; enable **Capability Inspector → Show in Plugins menu** from Settings when reviewing or debugging capability behavior.
+The bundled Capability Inspector plugin is the support surface for the current graph. It reads `window.slopsmith.capabilities.snapshotDiagnostics()`, filters by domain, and summarizes manifest participants, runtime participants, conflicts, unsupported versions, safety classes, expected compatibility event surfaces, and compatibility shim hits without rendering raw runtime objects. Domains are grouped in review order: application/library, player/audio runtime, plugin-defined surfaces, then capability runtime. In the all-domains view, each domain starts collapsed with a domain-specific icon plus compact summary badges for participant-lane count, endpoint count, observed links, shimmed links, and status; badge labels live in tooltips/ARIA labels so the header stays scannable. Clicking the domain label expands or collapses the domain, opening the same graph view used by the single-domain filter. The graph places owner details and right-aligned command/event groups on the left, with short owner descriptions bottom-aligned as the final part of that pane. Participant usage is grouped the same way on the right, with observed or shimmed links between border-aligned endpoint ports. In multi-provider domains, links to provider participants use provider-family colors: purple for owner-to-provider command delegation and a lighter violet for provider events. Provider participants, including `library` sources, stay on the right lane and show a provider icon in their header. Headers show role-aware core/non-core origin badges such as Core owner, Core provider, or Non-core participant; owner headers place the origin badge directly after the owner icon, and the built-in local library provider is marked as core-origin. Observer and requester roles are implied by the command/event links rather than separate header badges. Participant cards are shown only when the plugin or runtime source has visible command or event usage for the current graph filter; domains with no such usage show zero participants, and attribution-only shims with no matching endpoint stay out of the lane. Command and event groups can collapse; when collapsed, all links for that side and group converge on the single group port. Hovering a participant, endpoint, or command/event group emphasizes the matching links and dims unrelated links; owner-side labels outside the current focus de-emphasize so the active source endpoints are easy to track. Expanded domain graphs progressively enhance to Cytoscape.js overlays that route bezier links between measured DOM endpoint ports, while keeping the HTML lanes as the fallback and readable data surface. Its Plugins-menu entry is hidden by default; enable **Capability Inspector → Show in Plugins menu** from Settings when reviewing or debugging capability behavior.
 
 ## Diagnostics Contract
 
 Capability diagnostics use schema `slopsmith.capabilities.diagnostics.v1`. Snapshots are redaction-safe and capped at 64 KB by trimming older `recentDecisions` first while preserving current participants, active or orphaned claims, conflicts, domain review metadata, shim summaries, safety notes, and unsupported-version reports. Server diagnostics bundles include plugin manifest capability metadata, validation warnings, unsupported-version metadata, and compatibility shim summaries.
 
-Compatibility shim entries include `shimId`, `source`, `capability`, `legacySurface`, `status`, `reason`, and optional hit fields. A shim with `hitCount > 0` means legacy behavior was observed, not merely declared. The `library` domain no longer uses compatibility shims for provider registration or source selection; provider attribution comes from `owner_plugin_id` and runtime provider participants. Future domains should add expected shim entries only in the PR that implements their actual legacy bridge.
+Compatibility shim entries include `shimId`, `source`, `capability`, `legacySurface`, `status`, `reason`, and optional hit fields. A shim with `hitCount > 0` means compatibility behavior was observed, not merely declared. The `library` domain no longer uses compatibility shims for provider registration or source selection; provider attribution comes from `owner_plugin_id` and runtime provider participants. Future domains should add expected shim entries only in the PR that implements their actual compatibility bridge.
 
 ## Expected Future Domains
 
@@ -272,20 +217,31 @@ Release slices should stay reviewable. The domain-level roadmap, PR1 domain set,
 
 Future privileged domains must state user value, included and excluded commands, safety class, diagnostics fields, failure recovery, and tests proving disabled or incompatible participants cannot execute handlers before implementation begins.
 
-## Rehydration Pattern
+## Runtime Idempotency Pattern
 
-Plugins that wrap shared functions such as `window.playSong` or `window.showScreen` should store wrapper state on a stable `window.__slopsmith...Hooks` object. Re-running the script should replace the implementation object and return before installing another wrapper.
+Plugins that declare `plugin-runtime-idempotent.v1` must tolerate repeated script hydration without duplicating participants, listeners, timers, DOM roots, jobs, media nodes, or diagnostics contributors. Use stable ids and replace the current implementation behind the participant instead of registering a second copy.
 
 ```js
-const hookState = window.__slopsmithMyPluginHooks || (window.__slopsmithMyPluginHooks = {});
-hookState.impl = { afterPlaySong(filename) { /* current implementation */ } };
-if (hookState.installed) return;
-hookState.installed = true;
-hookState.basePlaySong = window.playSong;
-window.playSong = async function(filename, arrangement) {
-  await hookState.basePlaySong.call(this, filename, arrangement);
-  hookState.impl?.afterPlaySong?.(filename, arrangement);
+const runtime = window.__slopsmithMyPluginRuntime || (window.__slopsmithMyPluginRuntime = {});
+runtime.impl = {
+  async inspect() {
+    return { ready: true };
+  },
 };
+
+if (!runtime.registered) {
+  runtime.registered = true;
+  window.slopsmith.capabilities.registerParticipant('my_plugin.runtime', {
+    'example.plugin-domain': {
+      roles: ['provider'],
+      commands: ['inspect'],
+      handlers: {
+        inspect: () => runtime.impl.inspect(),
+      },
+      runtime: true,
+    },
+  });
+}
 ```
 
 ## Validation Commands

docs/capability-recipes.md

@@ -100,7 +100,7 @@ A plugin that registers a remote client or generated library source declares its
 
 ## Library Requester And Observer
 
-A route-only wrapper that uses the library capability without registering a browsable provider should declare requester/observer intent instead of provider ownership. This is a generic manifest shape for external plugins to adopt in their own repositories; it does not make the wrapper part of this PR's delivered domain set.
+A route-only wrapper that uses the library capability without registering a browsable provider declares requester/observer intent instead of provider ownership. This is a generic manifest shape for external plugins to adopt in their own repositories; it does not make the wrapper part of this PR's delivered domain set.
 
 ```json
 {
@@ -147,121 +147,9 @@ Existing plugins can keep using `window.slopsmith.audio.registerFader(spec)` whi
 
 Native audio-mix fader providers should register a stable participant id and fader id, return the committed value from every set operation, and settle get/set operations within two seconds. The player mixer displays the committed value rather than the raw requested value. If the fader is temporarily unavailable, keep the participant registered with unavailable/disabled state so the mixer can render a disabled control and diagnostics can explain why it cannot be changed.
 
-During migration, a plugin may still call `window.slopsmith.audio.registerFader(spec)`. Core maps that legacy fader into a compatibility-backed audio-mix participant and records bridge hits. If a native participant and a legacy fader represent the same logical source, the native participant owns the visible control and the legacy path is reported as compatibility-backed/overshadowed.
-
-## Audio Effects Provider
-
-Plugins that can provide guitar/bass processing chains should declare `audio-effects` as a provider and register at runtime with `window.slopsmith.audioEffects.registerProvider(...)`. The provider returns opaque chain plans; it must not expose local filenames, URLs, native preset JSON, VST state blobs, or raw handles through diagnostics or public route state.
-
-```json
-{
-  "id": "rig_builder",
-  "name": "Rig Builder",
-  "standards": ["capability-pipelines.v1", "plugin-runtime-idempotent.v1"],
-  "capabilities": {
-    "audio-effects": {
-      "roles": ["provider"],
-      "operations": ["chain.resolve", "chain.inspect", "segment.activate", "stage.set-bypass", "stage.set-parameter"],
-      "events": ["provider-registered", "route-selected", "plan-resolved", "changed", "fallback", "bridge-hit"],
-      "mode": "active",
-      "compatibility": "shim-allowed",
-      "safety": "sensitive",
-      "version": 1
-    }
-  }
-}
-```
-
-```js
-const effects = window.slopsmith && window.slopsmith.audioEffects;
-effects.registerProvider({
-  providerId: 'rig-builder',
-  pluginId: 'rig_builder',
-  routeKey: 'desktop-main',
-  priority: 40,
-  operations: ['chain.resolve', 'segment.activate', 'stage.set-bypass', 'stage.set-parameter'],
-  operationHandlers: {
-    'chain.resolve': request => ({
-      outcome: 'handled',
-      plan: {
-        schema: 'slopsmith.audio_effects.chain_plan.v1',
-        planId: 'song-tone-plan',
-        routeKey: request.routeKey,
-        providerId: 'rig-builder',
-        stages: [
-          { stageId: 'amp', kind: 'nam', role: 'amp', assetRef: 'rig-builder:asset:amp-main' },
-          { stageId: 'cab', kind: 'ir', role: 'cab', assetRef: 'rig-builder:asset:cab-main' }
-        ],
-        segments: [{ segmentId: 'base', stageIds: ['amp', 'cab'] }],
-        summary: { stageCount: 2 }
-      }
-    })
-  }
-});
-```
-
-User-facing controls should dispatch through the domain instead of mutating another plugin's private state:
-
-```js
-await window.slopsmith.capabilities.dispatch({
-  capability: 'audio-effects',
-  command: 'select-chain',
-  source: 'rig_builder',
-  payload: { routeKey: 'desktop-main', providerId: 'rig-builder', authorization: 'user-action' }
-});
-
-const resolved = await window.slopsmith.capabilities.dispatch({
-  capability: 'audio-effects',
-  command: 'resolve-plan',
-  source: 'nam_tone',
-  payload: { routeKey: 'desktop-main', target: { settingsKey: 'settings-v1-...' } }
-});
-```
-
-Providers should store public song/tone routing through the host-owned mapping index and keep their own preset or chain rows private. The mapping's `provider_ref` is opaque to core: NAM Tone can use a preset id, Rig Builder can use a chain/preset id, and each provider resolves that reference in `chain.resolve`.
-
-```js
-await window.slopsmith.audioEffects.upsertMapping({
-  song_key: playbackTarget.settingsKey,
-  filename: playbackTarget.filename, // optional migration/debug context
-  tone_key: 'Dist',
-  provider_id: 'rig-builder',
-  provider_ref: 'chain:99',
-  label: 'Full Rig Builder chain',
-  source: 'manual',
-  active: true
-});
-
-const mappings = await window.slopsmith.audioEffects.listMappings({
-  song_key: playbackTarget.settingsKey,
-  tone_key: 'Dist'
-});
-```
-
-Only one mapping is active for a `song_key + tone_key` at a time, but multiple providers may have rows for the same song/tone. The active row decides which provider core asks first; provider fallback remains explicit through provider priority and `fallbackProviderId` during `loadPlan(...)`.
-
-Browser or native executors should declare both provider scope and plan scope. A NAM-only browser executor should not claim Rig Builder plans just because it can load NAM files:
-
-```js
-window.slopsmith.audioEffects.registerExecutor({
-  executorId: 'nam-tone-browser-wasm',
-  pluginId: 'nam_tone',
-  routeKey: 'desktop-main',
-  providerIds: ['nam-tone'],
-  supportedKinds: ['nam', 'ir'],
-  maxStages: 2,
-  sourceMode: 'browser',
-  loadChainPlan: request => loadNamToneWasmPlan(request)
-});
-```
-
-Trusted Desktop can advertise broader support, while provider-specific browser executors should keep their `providerIds`, `supportedKinds`, and `maxStages` as narrow as the runtime actually supports.
-
-The desktop executor is the trust boundary for physical loading. It should treat `assetRef` and `stateRef` values as opaque provider references, validate them through provider-owned lookup code, enforce local policy, then load or reject processor stages. Browser diagnostics should report route/provider/outcome summaries only.
-
 ## Audio Input And Monitoring Requester
 
-Plugins that need live instrument input should declare requester/observer intent and let the host expose redaction-safe source identity. Diagnostics must not contain raw device labels, stable hardware ids, or audio buffers.
+Plugins that need live instrument input declare requester/observer intent and let the host expose redaction-safe source identity. Diagnostics must not contain raw device labels, stable hardware ids, or audio buffers.
 
 ```json
 {
@@ -274,7 +162,7 @@ Plugins that need live instrument input should declare requester/observer intent
       "requests": ["inspect", "list-sources", "select-source", "open-source", "close-source"],
       "observes": ["source-registered", "source-selected", "source-opened", "source-open-degraded", "source-closed", "permission-denied"],
       "mode": "active",
-      "compatibility": "shim-allowed",
+      "compatibility": "none",
       "ownership": "requester-only",
       "safety": "sensitive",
       "version": 1
@@ -284,7 +172,7 @@ Plugins that need live instrument input should declare requester/observer intent
       "requests": ["inspect", "list-providers", "select-provider", "start", "stop", "set-direct-monitor"],
       "observes": ["provider-registered", "provider-selected", "provider-selection-required", "monitoring-started", "monitoring-degraded", "monitoring-unavailable", "monitoring-failed", "monitoring-denied", "monitoring-stopped", "direct-monitor-changed"],
       "mode": "active",
-      "compatibility": "shim-allowed",
+      "compatibility": "none",
       "ownership": "requester-only",
       "safety": "sensitive",
       "version": 1
@@ -400,7 +288,7 @@ The Stems plugin remains the provider/owner of actual stem playback state. `core
       "operations": ["stem.get-state", "stem.apply-automation", "stem.restore-automation"],
       "events": ["owner-available", "automation-applied", "automation-restored", "automation-overridden", "claim-orphaned"],
       "mode": "active",
-      "compatibility": "shim-allowed",
+      "compatibility": "none",
       "ownership": "exclusive-owner",
       "safety": "safe",
       "version": 1
@@ -411,7 +299,7 @@ The Stems plugin remains the provider/owner of actual stem playback state. `core
 
 ## Playback Requester And Observer
 
-Plugins that need to inspect or coordinate song transport should declare `playback` requester/observer intent and use the capability dispatch surface instead of wrapping `window.playSong` or scraping the `<audio>` element. Raw media handles stay private to core; diagnostics expose only pseudonymous targets, sanitized timing, route, loop, requester, observer, and recent outcome summaries.
+Plugins that need to inspect or coordinate song transport declare `playback` requester/observer intent and use the capability dispatch surface. Raw media handles stay private to core; diagnostics expose only pseudonymous targets, sanitized timing, route, loop, requester, observer, and recent outcome summaries.
 
 ```json
 {
@@ -424,7 +312,7 @@ Plugins that need to inspect or coordinate song transport should declare `playba
       "requests": ["inspect", "pause", "resume", "seek", "set-loop", "clear-loop"],
       "observes": ["ready", "started", "paused", "resumed", "seeking", "seeked", "stopped", "loop-set", "loop-cleared"],
       "mode": "active",
-      "compatibility": "shim-allowed",
+      "compatibility": "none",
       "ownership": "requester-only",
       "safety": "safe",
       "version": 1
@@ -455,106 +343,10 @@ if (state.status !== 'idle') {
 }
 ```
 
-During migration, legacy uses of `window.playSong`, `song:*` events, `window.slopsmith.seek`, and loop helpers remain available and are recorded as playback bridge hits. Treat bridge hits as migration telemetry: native capability requests should eventually cover normal plugin workflows so unexpected legacy hits disappear from diagnostics.
-
-## Progression Requester And Observer
-
-Plugins that report gameplay outcomes or react to player progression (spec 010) should declare `progression` requester/observer intent and use capability dispatch instead of private fetches. Externally postable event types are whitelisted (`minigame_run` in v1); `song_completed` is server-derived inside `/api/stats` and is denied at this surface. Backend plugin code can use the plugin-context hook `record_progression_event` instead (the minigames hub does).
-
-```json
-{
-  "id": "my_minigame",
-  "name": "My Minigame",
-  "standards": ["capability-pipelines.v1"],
-  "capabilities": {
-    "progression": {
-      "roles": ["requester", "observer"],
-      "requests": ["inspect", "record-event"],
-      "observes": ["challenge-completed", "quest-completed", "path-level-up", "rank-changed", "db-changed"],
-      "mode": "active",
-      "compatibility": "none",
-      "ownership": "requester-only",
-      "safety": "safe",
-      "version": 1
-    }
-  }
-}
-```
-
-`buy-item` and `equip-item` require a visible user gesture (`authorization: "user-action"`). Decibels are play-earned only; plugins must not present any purchase path.
-
-```js
-const api = window.slopsmith.capabilities;
-
-const result = await api.dispatch({
-  capability: 'progression',
-  command: 'record-event',
-  source: 'my_minigame',
-  payload: { type: 'minigame_run', payload: { game_id: 'my-minigame', score: 420 } },
-});
-// result.payload lists challenges/quests completed by this event (toast UX).
-
-window.slopsmith.on('progression:quest-completed', (e) => {
-  console.log('quest done:', e.detail.title, '+' + e.detail.reward_db + ' dB');
-});
-```
-
 ## Future Expansion Domains
 
 Some domain names are reserved for expected future contracts, but they are not registered in the runtime graph yet. For example, `ui.player-panels` is documented as a likely panel-host surface, but Slopsmith does not currently expose a capability command for panel contributions. See [capability-roadmap.md](capability-roadmap.md) for the PR1 domain set and deferred-domain checklist.
 
-Plugins should not declare future expansion domains until the corresponding host workflow ships. For current integrations, prefer active domains such as `library`, `playback`, `audio-mix`, `audio-input`, `audio-monitoring`, or `stems` intent matching the recipes above.
+Do not declare future expansion domains until the corresponding host workflow ships. For current integrations, use active domains such as `library`, `playback`, `audio-mix`, `audio-input`, `audio-monitoring`, or `stems` intent matching the recipes above.
 
-Invalid capability metadata is excluded from the capability graph, but legacy manifest fields still load through their existing app paths. The `library` workflow is native in PR1 and does not use compatibility shim metadata. Unsupported `capability-pipelines` versions are reported as incompatible and their runtime handlers must not execute.
-
-## Library Card Action (`ui.library-card-injection`)
-
-Delivered in fee[dB]ack v0.3.0 (frontend host). Plugins add per-song actions to
-the library cards by REGISTERING them instead of DOM-injecting onto
-`.song-card`. The library renders applicable actions in each card's action
-menu, dispatches the handler on click, and emits `action-result` events;
-the owner is visible in the Capability Inspector.
-
-```json
-{
-  "id": "my_card_action",
-  "name": "My Card Action",
-  "standards": ["capability-pipelines.v1"],
-  "capabilities": {
-    "ui.library-card-injection": {
-      "roles": ["provider"],
-      "operations": ["action.run"],
-      "events": ["action-registered", "action-result"],
-      "mode": "active",
-      "compatibility": "none",
-      "safety": "safe",
-      "version": 1
-    }
-  }
-}
-```
-
-Register the action from the plugin's `screen.js`:
-
-```js
-window.slopsmith.libraryCardActions.register({
-  id: 'my_card_action.run',
-  pluginId: 'my_card_action',
-  label: 'Do the thing',
-  placement: 'menu',                 // 'menu' | 'inline' | 'overlay'
-  order: 50,
-  applies: (song) => song.format === 'sloppak',  // shown only when relevant
-  enabled: (song) => true,
-  run: async (song, ctx) => {        // ctx.source identifies the surface
-    await fetch('/api/plugins/my_card_action/run', {
-      method: 'POST', headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ filename: song.filename }),
-    });
-  },
-});
-```
-
-`register(spec)` returns an `unregister()` fn. The host owns rendering,
-applicability, enabled state, and `action-result` events — plugins do not touch
-library DOM. Legacy `.song-card` DOM injection still works in the 0.2.x UI;
-migrate to this for the v0.3.0 native library.
+Invalid capability metadata is excluded from the capability graph. The `library` workflow is native in PR1 and does not use compatibility shim metadata. Unsupported `capability-pipelines` versions are reported as incompatible and their runtime handlers must not execute.

docs/capability-roadmap.md

@@ -108,7 +108,7 @@ These domains are planned but should stay out of the runtime graph until a host
 | `ui.player-overlays` | exclusive-owner | safe | Overlay contributions layered over player or highway surfaces. | Overlay placement and z-order rules that coexist with legacy overlays. |
 | `plugins` | exclusive-owner | privileged | Plugin enable/disable/install/update workflows. | Visible user confirmation, rollback, and disabled-handler enforcement. |
 | `jobs` | multi-provider | privileged | Long-running jobs, cancellation, status, failures. | Scheduling limits, cancellation semantics, and user-visible failures. |
-| `midi-control` | multi-provider | sensitive | MIDI control mappings only (CC/pitchbend/note → action routing), consuming `midi-input` for device access. Device discovery/selection/open is split out to the delivered `midi-input` domain (spec 012). | A concrete mapping/routing workflow on top of the `midi-input` device plane (#882). |
+| `midi-control` | multi-provider | sensitive | MIDI device providers and control mappings. | Device consent and redacted diagnostics. |
 | `audio-input` | multi-provider | sensitive | Audio input device providers, source selection, open/close lifecycle, shared sessions, and redacted failure diagnostics. | Promoted by the audio graph/session slice and implemented by the audio-input control-plane slice. |
 | `tempo-clock` | multi-provider | safe | Tempo/clock provider registration and consumers. | A concrete tempo source and consumer workflow. |
 

docs/capability-safety-matrix.md

@@ -21,8 +21,6 @@ Core domains also have a review scope. **Active contract** domains are wired to
 
 | note-detection | provider-coordinator | sensitive | inspect, register-provider, unregister-provider, open-binding, close-binding, set-target, clear-target | pitch.estimate, verify.target | Detection-binding control plane (spec 009): providers (midi/engine/js) serve primitives; each requester binds its own redacted tuning context; consumers own judgment, hit/miss flow as observability events. Legacy `highway.setNoteStateProvider` is an accounted shim. Diagnostics carry provider/binding summaries and bounded outcomes — no raw audio, sample data, device labels, or song identity. |
 
-| midi-input | provider-coordinator | sensitive | inspect, list-sources, discover, select-source, open-source, close-source | source.enumerate, source.describe, source.open, source.close | Core-owned MIDI device control plane (spec 012), the MIDI analog of `audio-input`. Inspect/list/select are prompt-free; `discover` is the Web-MIDI permission boundary (`requestMIDIAccess()` gates the whole input list) and records denied/unavailable outcomes; `open-source` attaches a shared listener session and never re-prompts. Selection persists by redaction-safe `logicalSourceKey`. Diagnostics redact device labels and never include raw MIDI messages or live handles. |
-
 Privileged commands are roadmap-only until they have: a visible user confirmation path, diagnostics redaction rules, failure recovery, and tests that prove disabled or incompatible participants cannot execute handlers.
 
 ## Expected Future Domains
@@ -40,7 +38,7 @@ These domains are expected future capability contracts, not current runtime grap
 | ui.player-overlays | exclusive-owner | safe | register-contribution, mount, unmount, set-visible, reorder-by-policy, inspect | Needs overlay placement rules that coexist with legacy highway overlays. |
 | plugins | exclusive-owner | privileged | enable, disable, install-missing, update, inspect | Needs explicit user confirmation for writes/install/update. |
 | jobs | multi-provider | privileged | register, inspect, cancel | Needs scheduling limits, cancellation semantics, and user-visible failures. |
-| midi-control | multi-provider | sensitive | list-mappings, get-mapping, set-mapping, delete-mapping, activate-mapping, inspect | Mappings ONLY — CC/pitchbend/note → semantic action routing (spec 013). Device discovery/selection/open is NOT this domain's job: it consumes the delivered `midi-input` domain for device access. Needs a concrete mapping consumer (the MIDI control plugin / drums learn-mode) + redacted diagnostics (no raw MIDI streams) before promotion. |
+| midi-control | multi-provider | sensitive | register, inspect | Needs device consent and redacted diagnostics. |
 | tempo-clock | multi-provider | safe | register, inspect | Needs a concrete provider and consumer workflow. |
 
 Planned domains should also stay out of the runtime graph until Slopsmith ships the corresponding user-facing workflows.

docs/plugin-audio-mixer.md

@@ -0,0 +1,45 @@
+# Audio mixer fader registration
+
+Plugins that produce audio outside the song's `<audio>` element (NAM amp output, synth voices, etc.) can register a labeled fader so users can balance them against the song from one mixer popover in the player controls.
+
+This is the slopsmith#87 contract.
+
+## Registration
+
+```js
+function _registerFader() {
+    const api = window.slopsmith && window.slopsmith.audio;
+    if (!api) return;
+    api.registerFader({
+        id: 'my_plugin',           // unique key
+        label: 'My Plugin',        // shown above the fader
+        unit: 'dB',                // optional suffix shown next to the value (e.g. '%', 'dB')
+        min: 0, max: 2, step: 0.05,
+        defaultValue: 1.0,
+        getValue: () => _myCurrentVolume,        // read current value
+        setValue: (v) => _setMyVolume(v),         // write + persist + apply
+    });
+}
+
+if (window.slopsmith && window.slopsmith.audio) {
+    _registerFader();
+} else {
+    window.addEventListener('slopsmith:audio:ready', _registerFader, { once: true });
+}
+```
+
+## Contract
+
+- **Persistence is the plugin's responsibility.** The registry calls `getValue()` when the popover opens and after each `setValue()` during slider drags to re-sync the displayed value.
+- **`getValue()` must be cheap and side-effect-free.**
+- **`setValue()` must update whatever backing state `getValue()` reads synchronously** — pair it with whatever your plugin already does internally (write the GainNode, persist to `localStorage`, update any in-plugin label).
+- **Use `unregisterFader(id)`** when your plugin is teardown-able and you want the strip to disappear; otherwise keep it registered so the user's setting persists across toggle states.
+
+## Lifecycle event
+
+`slopsmith:audio:ready` fires once on `window` when the audio mixer registry is ready. Guard registration against this event for plugins that load before the mixer.
+
+## Related
+
+- [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) — guide index
+- [plugin-visualization-contracts.md](plugin-visualization-contracts.md) — visualization counterpart

docs/plugin-diagnostics.md

@@ -0,0 +1,86 @@
+# Plugin diagnostics contribution
+
+Slopsmith ships an **Export Diagnostics** feature (Settings → Export Diagnostics) that bundles a redacted set of host + plugin state into a zip the user can share with maintainers. Plugins have three independent opt-ins for contributing to this bundle.
+
+The bundle layout and per-file schemas are documented in [diagnostics-bundle-spec.md](diagnostics-bundle-spec.md). This doc covers how plugins integrate.
+
+## 1. `manifest.diagnostics.server_files` — opt-in file capture
+
+Declare files under `context["config_dir"]` to copy verbatim into the bundle:
+
+```json
+{
+  "diagnostics": {
+    "server_files": ["my_plugin.diag.json", "my_plugin_models/active.json"]
+  }
+}
+```
+
+Rules (same as `settings.server_files`):
+- Relpaths only. No `..`, no abs paths, no backslashes, no leading dots.
+- Files land at `plugins/<plugin_id>/<relpath>` inside the bundle.
+- Encoded as `{"encoding": "json", "data": <parsed>}` if `.json` parses cleanly, base64 otherwise.
+
+Use this for **snapshot-style state** — small DB excerpts, model lists, last-error files. Don't use it for backups (that's `settings.server_files`).
+
+## 2. `manifest.diagnostics.callable` — opt-in dynamic capture
+
+Declare a Python entry point that produces diagnostics at export time:
+
+```json
+{
+  "diagnostics": {
+    "callable": "diagnostics:collect"
+  }
+}
+```
+
+The form is `"<module>:<function>"`. The module is resolved lazily via `load_sibling` when the user clicks Export, then called as:
+
+```python
+# plugins/my_plugin/diagnostics.py
+def collect(ctx):
+    """ctx is {"plugin_id": str, "config_dir": Path}."""
+    return {
+        "schema": "my_plugin.diag.v1",
+        "active_preset": _read_active_preset(ctx["config_dir"]),
+        "model_count": len(list((ctx["config_dir"] / "models").glob("*.pt"))),
+    }
+```
+
+Return-type handling:
+- `dict` / `list` → written to `plugins/<id>/callable.json`
+- `bytes` → `callable.bin`
+- `str` → `callable.txt`
+
+Exceptions are caught and appended to the bundle's `manifest.notes` — a buggy plugin never crashes the export.
+
+## 3. Frontend contribution (slopsmith#166)
+
+Plugins that hold useful debug state in the browser (active model name, last user input, internal counters) can push it into the bundle from `screen.js`:
+
+```js
+window.slopsmith.diagnostics.contribute('my_plugin', {
+    schema: 'my_plugin.client_diag.v1',
+    active_preset: getActivePreset(),
+    last_error: _lastError,
+});
+```
+
+- **Idempotent.** Repeated calls overwrite the previous value.
+- Whatever was last contributed before the user hits Export Diagnostics is what lands in `plugins/<plugin_id>/client.json`.
+- Available namespace: `window.slopsmith.diagnostics.{contribute, snapshotConsole, snapshotHardware, snapshotUa, snapshotLocalStorage, snapshotContributions}`.
+- Loaded from `static/diagnostics.js` ASAP in `<head>` so the console-wrap is in place before any other script runs.
+
+## Best practices
+
+- **Embed a `schema` field** (e.g. `"my_plugin.diag.v1"`) in JSON returned by `callable` so future tooling can dispatch by version.
+- **Keep payloads small (< 100 KB).** Diagnostics are not a backup channel — that's `settings.server_files`.
+- **Don't include secrets, API keys, or session tokens.** Bundles are shared with maintainers / posted to GitHub issues.
+
+## Related
+
+- [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) — guide index
+- [diagnostics-bundle-spec.md](diagnostics-bundle-spec.md) — full bundle layout + per-file schemas
+- [plugin-manifest.md](plugin-manifest.md) — declaring `diagnostics` fields
+- [plugin-logging.md](plugin-logging.md) — `log.exception()` writes traceback into the diagnostics log capture

docs/plugin-keyboard-shortcuts.md

@@ -0,0 +1,64 @@
+# Plugin keyboard shortcuts
+
+Plugins can register keyboard shortcuts via the global `window.registerShortcut()` function. Shortcuts appear in the `?` help panel.
+
+## Registration
+
+```js
+window.registerShortcut({
+    key: 'k',                       // key value (e.key) or key code (e.code)
+    description: 'Toggle my view',  // shown in the help panel
+    scope: 'player',                // 'global' | 'player' | 'library' | 'settings' | 'plugin-{id}'
+    condition: () => _isMyViewActive, // optional guard
+    handler: (e) => _myAction()      // called when shortcut triggers
+});
+```
+
+## Scope
+
+Scope controls when the shortcut is active:
+
+- **`global`** — works on any screen
+- **`player`** — only on the player screen
+- **`library`** — only on the home/favorites screens
+- **`settings`** — only on the settings screen
+- **`plugin-{id}`** — only when your plugin's screen is active
+
+## Panel-scoped shortcuts
+
+For plugins that create multiple panels (e.g., splitscreen), shortcuts are automatically scoped to the active panel. Use `const panel = window.createShortcutPanel(id)` to create a panel (keep the returned reference so you can call `panel.clearShortcuts()` during cleanup) and `window.setActiveShortcutPanel(id)` to switch between them. Each panel has its own shortcut registry, so multiple panels can have the same key without collisions.
+
+## Condition
+
+`condition` is an optional guard function. If it returns false, the shortcut is skipped even if in scope.
+
+## Key matching
+
+The handler matches against both `e.key` (character produced) and `e.code` (physical key). Use `e.key` for letters/symbols that depend on keyboard layout, and `e.code` for special keys (e.g. `Space`, `ArrowLeft`).
+
+## Cleanup
+
+Clean up with `window.unregisterShortcut(key, scope)`. **You must pass the same scope you registered with** — the default is `'global'` and won't match `player`/`library`/`settings`/`plugin-*` bindings.
+
+For panel-scoped shortcuts, prefer `panel.clearShortcuts()` over per-key unregister calls.
+
+## Built-in shortcuts
+
+| Key | Description |
+|-----|-------------|
+| `?` | Show keyboard shortcuts panel (global) |
+| `Space` | Play/Pause (player only) |
+| `←` / `→` | Seek ±5 seconds (player only) |
+| `Escape` | Back to library (player only) |
+| `[` / `]` | Audio offset ±10ms (Shift: ±50ms) (player only) |
+
+Don't override these. The `?` panel is the canonical reference for users.
+
+## Debugging
+
+Open the browser console and type `_listShortcuts()` to inspect every registered shortcut, its scope, and its source plugin.
+
+## Related
+
+- [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) — guide index
+- [testing-plugins.md](testing-plugins.md) — Playwright tests for shortcut behaviour

docs/plugin-logging.md

@@ -0,0 +1,67 @@
+# Plugin logging
+
+Use `context["log"]` for all backend plugin output. It is a stdlib `logging.Logger` namespaced to `slopsmith.plugin.<id>`, pre-configured with the app-wide level, format (including JSON mode), and correlation IDs. **Never use `print()`** — it bypasses correlation context and log rotation.
+
+## Backend usage
+
+```python
+def setup(app, context):
+    log = context["log"]
+    log.info("plugin ready")
+    log.warning("optional dependency %r not found, feature disabled", dep)
+    try:
+        risky_init()
+    except Exception:
+        log.exception("unhandled error during setup")  # auto-captures traceback
+```
+
+## CLI entry-point fallback
+
+For helper scripts that also run as `__main__`, add a stdlib fallback so the logger works without the server pipeline:
+
+```python
+if __name__ == "__main__":
+    import logging
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
+```
+
+## How it's wired
+
+The plugin loader assigns each plugin a logger before calling `setup()`:
+
+```python
+context["log"] = logging.getLogger(f"slopsmith.plugin.{plugin_id}")
+```
+
+That logger inherits from the root `slopsmith` logger, which is configured by `logging_setup.configure_logging()` (called from `main.py` before uvicorn boots). It respects:
+
+- **`LOG_LEVEL`** — `DEBUG | INFO | WARNING | ERROR` (default `INFO`)
+- **`LOG_FORMAT`** — `json | text` (default `text` — coloured console)
+- **`LOG_FILE`** — optional path for a persistent log file (e.g. `/config/slopsmith.log`)
+- **Correlation IDs** — each HTTP request carries `X-Request-ID`; structlog injects it into every log line during that request's lifetime. WebSocket sessions get their own `ws_conn_id` contextvar bound at accept time.
+
+## Verifying
+
+Look for your plugin's logger name in the console output:
+
+```text
+INFO     slopsmith.plugin.my_plugin: plugin ready
+```
+
+Switch `LOG_FORMAT=json` to see structured output:
+
+```json
+{"timestamp": "...", "level": "info", "logger": "slopsmith.plugin.my_plugin", "event": "plugin ready", "request_id": "..."}
+```
+
+## Common mistakes
+
+- **Using `print()` inside `setup()` or request handlers.** `print()` goes to stdout, bypasses level filtering, log rotation, JSON formatting, and correlation IDs. Audit your plugin with `grep -nR 'print(' plugins/<id>/`.
+- **Creating a new logger with `logging.getLogger("my_plugin")`.** This creates an unparented logger that doesn't inherit slopsmith's configuration. Always use the one passed via `context["log"]`.
+- **Logging at `INFO` in hot paths.** Default `LOG_LEVEL` is `INFO`, so `log.info(...)` inside a per-frame or per-message loop floods output. Use `log.debug(...)` for hot-path tracing.
+
+## Related
+
+- [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) — guide index
+- [plugin-manifest.md](plugin-manifest.md) — the `routes.py` / `setup(app, context)` contract
+- [plugin-diagnostics.md](plugin-diagnostics.md) — capturing logs into the diagnostics bundle

docs/plugin-manifest.md

@@ -0,0 +1,234 @@
+# `plugin.json` manifest reference
+
+Every plugin lives in `plugins/<name>/` and must declare a `plugin.json` manifest. JSON Schema for this format ships at [`schema/plugin.schema.json`](../schema/plugin.schema.json) and is enforced in CI for in-tree plugins.
+
+## Full example
+
+```json
+{
+  "id": "my_plugin",
+  "name": "My Plugin",
+  "version": "1.0.0",
+  "private": false,
+  "standards": ["capability-pipelines.v1", "plugin-runtime-idempotent.v1"],
+  "screen": "screen.html",
+  "script": "screen.js",
+  "styles": "assets/plugin.css",
+  "routes": "routes.py",
+  "settings": {
+    "html": "settings.html",
+    "server_files": ["my_plugin.db", "my_plugin_models/"]
+  },
+  "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" }],
+    "ui.plugin-screens": [{ "id": "my-plugin-screen", "region": "plugin.main", "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
+    }
+  }
+}
+```
+
+All fields except `id` and `name` are optional. Runtime files such as `screen`, `script`, `routes`, and `settings.html` should correspond to declared `capabilities`, `ui`, diagnostics, or settings metadata.
+
+## Fields
+
+### `id` (required, string)
+
+Snake-case identifier. Used to namespace `localStorage` keys, build the plugin's screen id (`plugin-<id>`), namespace the backend logger (`slopsmith.plugin.<id>`), and as the directory name in diagnostics bundles. Cannot contain slashes, dots are encoded by the sibling-import loader (see [plugin-sibling-imports.md](plugin-sibling-imports.md)).
+
+### `name` (required, string)
+
+Human-readable name shown in UI surfaces.
+
+### `version` (string, optional)
+
+Plain semver string. Advisory only — the plugin loader does not consume this. Plugins commonly include it for publishing/tooling purposes.
+
+### `private` (boolean, optional)
+
+Advisory metadata for plugin authors. Not consumed by the loader.
+
+### `standards` (string[], expected)
+
+Versioned contracts the plugin participates in. Plugin manifests are expected to declare `"capability-pipelines.v1"` for Slopsmith-facing behavior and metadata. Omit it only for metadata-only or transitional manifests with no capability participation yet.
+
+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 } }
+```
+
+### `screen` (string, optional)
+
+Path to HTML file (relative to plugin dir). Mounted at `#plugin-<id>` in the SPA.
+
+### `script` (string, optional)
+
+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.
+
+### `settings` (object, optional)
+
+`{ "html": string, "server_files": string[] }`
+
+- **`settings.html`** — settings-panel HTML.
+- **`settings.server_files`** — **opt-in** for the unified Settings export/import flow (slopsmith#113). List of relpaths under `context["config_dir"]` that the plugin wants included in user-triggered backups. A trailing `/` denotes a directory (recurse).
+
+  Rules:
+  - Relpaths only. Absolute paths, drive letters, `..` segments, and backslashes are rejected at load time with a `[Plugin]` warning.
+  - The same allowlist is consulted at both export and import: a bundle that references a file the *importing host*'s manifest no longer declares is skipped with a warning (handles plugin updates between export and import). A bundle that references a file your host's manifest never declared is also skipped — no surprise writes.
+  - Files are encoded as `{"encoding": "json", "data": <parsed>}` for `.json` files that parse cleanly (diff-friendly), `{"encoding": "base64", "data": "..."}` otherwise (sqlite, model blobs, IRs).
+  - Plugins own their internal data migration. Importing a bundle whose data schema predates your current code restores bytes verbatim — your plugin must cope at next load.
+  - Symlinks are skipped on export and never followed on import.
+
+  Plugins that omit this field have no server-side files exported; their state lives entirely in browser `localStorage`, which is bundled wholesale on every export.
+
+### `diagnostics` (object, optional)
+
+`{ "server_files": string[], "callable": string }`
+
+**Opt-in** for the troubleshooting bundle (slopsmith#166 — Settings → Export Diagnostics). Two independent fields:
+
+- **`diagnostics.server_files`** — same allowlist semantics as `settings.server_files`: relpaths under `context["config_dir"]`, no `..`, no abs paths, no backslashes, no leading dots. Files listed here are copied verbatim into `plugins/<plugin_id>/<relpath>` inside the bundle. Use this for snapshot-style state (small DB excerpts, model lists, last-error files).
+- **`diagnostics.callable`** — `"<module>:<function>"` (e.g. `"diagnostics:collect"`). Resolved lazily via `load_sibling` when the user clicks Export, then called as `func({"plugin_id": "...", "config_dir": Path(...)})`. Return `dict`/`list` → written to `plugins/<id>/callable.json`; `bytes` → `callable.bin`; `str` → `callable.txt`. Exceptions are caught and appended to the bundle's `manifest.notes` — a buggy plugin never crashes the export.
+
+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. Use these whenever a plugin contributes settings panels, plugin screens, player controls, overlays, tours, or other host-visible UI so Slopsmith can attribute UI to stable contribution records.
+
+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, expected for app-facing behavior)
+
+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, and are the default way plugin behavior is made visible to Slopsmith.
+
+```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 through playback capability events.",
+      "mode": "active",
+      "compatibility": "none",
+      "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`: prefer `none` for new declarations
+- `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. Fix invalid metadata rather than relying on undocumented runtime behavior.
+
+### `license` (string, optional but recommended)
+
+SPDX identifier. Contributions must use `AGPL-3.0-only`. See [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+## Backend routes — `setup(app, context)`
+
+`routes.py` must export `setup(app, context)`. The `context` dict provides:
+
+- `config_dir` — persistent config path (`Path`)
+- `get_dlc_dir()` — returns the DLC folder `Path`
+- `extract_meta()` — metadata extraction callable
+- `meta_db` — shared `MetadataDB` instance
+- `get_sloppak_cache_dir()` — sloppak cache `Path`
+- `load_sibling(name)` — loads a sibling module from this plugin's directory under a unique, namespaced module name. See [plugin-sibling-imports.md](plugin-sibling-imports.md).
+- `log` — stdlib `logging.Logger` namespaced to `slopsmith.plugin.<id>`. Pre-configured with the app-wide level, format (including JSON mode), and correlation IDs. Use this for all backend plugin output instead of `print()`. See [plugin-logging.md](plugin-logging.md).
+
+Prefer native capability declarations and provider registration for Slopsmith-facing behavior. Backend plugins should not open ad hoc SQLite connections to core databases or treat database tables as a public integration surface. If a legacy or core-provided route path already needs metadata access through `context["meta_db"]`, use the shared `MetadataDB` instance and its synchronized methods only; do not bypass its `threading.Lock` protection with direct SQLite access.
+
+Example:
+
+```python
+def setup(app, context):
+    log = context["log"]
+    extractor = context["load_sibling"]("extractor")
+
+    @app.get("/api/my_plugin/status")
+    def status():
+        return {"ready": True}
+
+    log.info("my_plugin ready")
+```
+
+## 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), including capability-pipelines metadata.
+
+## Related
+
+- [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) — guide index
+- [plugin-logging.md](plugin-logging.md) — `context["log"]` pattern
+- [plugin-sibling-imports.md](plugin-sibling-imports.md) — `load_sibling`
+- [plugin-diagnostics.md](plugin-diagnostics.md) — diagnostics opt-in details
+- [diagnostics-bundle-spec.md](diagnostics-bundle-spec.md) — full diagnostics bundle layout

docs/plugin-manifest.schema.json

@@ -3,62 +3,396 @@
   "$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_.-]+$" },
-    "name": { "type": "string", "minLength": 1 },
-    "version": { "type": ["string", "null"] },
-    "private": { "type": "boolean" },
-    "standards": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[A-Za-z0-9_.-]+$"
+    },
+    "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" },
-      "additionalProperties": { "$ref": "#/$defs/capabilityDeclaration" }
+      "propertyNames": {
+        "$ref": "#/$defs/domainName"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/capabilityDeclaration"
+      }
     },
-    "ui_contributions": { "type": "object", "propertyNames": { "$ref": "#/$defs/domainName" }, "additionalProperties": { "$ref": "#/$defs/contributionList" } },
-    "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, or query/fragment. See docs/plugin-styles.md." }
+    "ui_contributions": {
+      "type": "object",
+      "propertyNames": {
+        "$ref": "#/$defs/domainName"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/contributionList"
+      }
+    },
+    "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": {
+      "$ref": "#/$defs/pluginRelpath"
+    },
+    "script": {
+      "$ref": "#/$defs/pluginRelpath"
+    },
+    "routes": {
+      "$ref": "#/$defs/pluginRelpath"
+    },
+    "settings": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "html": {
+          "$ref": "#/$defs/pluginRelpath"
+        },
+        "server_files": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "not": {
+              "pattern": "^/|^[a-zA-Z]:|\\\\|(^|/)\\.\\.(/|$)|//|(^|/)\\.(/|$)|^\\."
+            }
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "diagnostics": {},
+    "type": {
+      "type": "string"
+    },
+    "tour": {
+      "$ref": "#/$defs/pluginRelpath"
+    },
+    "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_.:-]+$" },
+    "pluginRelpath": {
+      "type": "string",
+      "minLength": 1,
+      "not": {
+        "pattern": "^/|^[a-zA-Z]:|\\\\|(^|/)\\.\\.(/|$)|//|(^|/)\\.(/|$)|^\\.|[?#]"
+      }
+    },
+    "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 },
-        "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" },
-        "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" },
-        "version": { "const": 1 }
+        "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 } }
+    "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
+      }
+    }
   }
 }

docs/plugin-sibling-imports.md

@@ -0,0 +1,48 @@
+# Plugin sibling imports — `load_sibling`
+
+When a backend plugin spans multiple Python files, **use `context["load_sibling"]`** rather than bare `import` statements. This is the slopsmith#33 contract.
+
+## The problem
+
+The plugin loader inserts each plugin's directory onto `sys.path` so `from extractor import X` works. But Python caches imports by **module name** in `sys.modules`. Two plugins that each ship a top-level `extractor.py` (or any other generic name — `util.py`, `client.py`, `parser.py`, `config.py`, …) collide: whichever loads first wins, and the other plugin's `from extractor import X` either gets the wrong module or fails with `cannot import name 'X' from 'extractor'`.
+
+## The fix
+
+`context["load_sibling"](name)` loads the sibling under a namespaced module name `plugin_<id>.<name>`, so each plugin gets its own copy. The `<id>` portion is bijectively encoded so reverse-DNS-style ids like `com.example.foo` work without colliding: `_` → `_5f_`, `.` → `_2e_`.
+
+```python
+def setup(app, context):
+    extractor = context["load_sibling"]("extractor")
+    ArchiveReader = extractor.ArchiveReader
+    # …
+```
+
+## Notes
+
+- **`name` is a bare module name** — no `.py` suffix, no slashes, no `.`. The helper raises `ValueError` for path traversal / format issues and `ImportError` for missing files.
+- **Both single-file siblings (`extractor.py`) and package-form siblings (`extractor/__init__.py`) work.** Package form wins when both exist (matches CPython's import-resolution precedence).
+- **Relative imports between siblings work** — `from .shared import X` in a top-level helper, `from ..shared import X` from inside a sibling package. The synthetic parent package `plugin_<id>` carries the plugin directory in its `__path__`.
+- **`from . import sibling` (attribute-style) also resolves**: loaded children are exposed as attributes on the parent package.
+- **Repeat calls return the cached module.** Concurrent first-time calls are serialized via per-module locks so no caller observes a half-initialized module.
+- **Don't mix `load_sibling` and bare `import` for the same module** — they'd execute the file twice and split module-level state.
+
+## Migration
+
+Bare `import sibling` from `routes.py` still works during the transition period, but the loader prints a startup warning when it detects two plugins shipping a same-named top-level module — covering both `.py` files and package directories. Migrate to `load_sibling` to silence the warning and immunize your plugin from future ecosystem collisions.
+
+## Verification
+
+The collision-detection logic is encoded in `tests/test_plugins.py`. Run:
+
+```bash
+pytest tests/test_plugins.py -v
+```
+
+If you're authoring a plugin with a top-level helper, add a test that imports your plugin under a `reset_plugin_state` fixture to confirm clean import behaviour. See [testing-plugins.md](testing-plugins.md).
+
+## Related
+
+- [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) — guide index
+- [plugin-manifest.md](plugin-manifest.md) — declaring `routes.py`
+- [plugin-logging.md](plugin-logging.md) — `context["log"]` (also exposed via `context`)
+- [testing-plugins.md](testing-plugins.md) — `reset_plugin_state` fixture

docs/plugin-visualization-contracts.md

@@ -0,0 +1,198 @@
+# Plugin visualization contracts
+
+Slopsmith supports two ways for a plugin to participate in the main player's visuals. They coexist; the **setRenderer** contract is the default for any viz that draws a highway-shaped surface, and **overlays** handle layered decorations on top. A third orthogonal contract — **note-state provider** — lets scorers feed per-note judgments back into whichever renderer is active.
+
+**Pick the right shape:**
+- Replacing the whole highway drawing on the existing highway canvas (your renderer owns its rendering context / resources; `createHighway()` still owns the canvas element and the rAF loop)? → **setRenderer** (section 1). Enters the viz picker. Works in both the main player and per-panel under splitscreen.
+- Adding a layer on top of whichever viz is active? → **Overlay** (section 2). Navbar toggle, not in the picker.
+- Scoring plugin that wants renderers to "light up" notes on correct hits? → **Note-state provider** (section 3). Orthogonal — can coexist with overlay HUDs.
+
+## 1. setRenderer contract (slopsmith#36) — preferred
+
+Plugins that want to replace the main highway's draw function (per panel, per session) export a renderer factory on `window.slopsmithViz_<id>` where `<id>` matches the `id` in `plugin.json` (`type: "visualization"` required). The factory returns an object matching this shape:
+
+```js
+window.slopsmithViz_my_viz = function () {
+    return {
+        // Required canvas context type. Default '2d' if omitted.
+        // highway.js reads this BEFORE calling init() so it can
+        // replace the underlying <canvas> element if the current
+        // one is locked to a different context type (see "Canvas
+        // context-type swapping" below).
+        contextType: '2d', // or 'webgl2'
+        init(canvas, bundle) {
+            // One-time setup. Own your getContext() call here —
+            // acquire '2d' or 'webgl2' depending on the renderer.
+            // The canvas you receive is guaranteed to either be
+            // unbound or already bound to your declared contextType.
+            this.ctx = canvas.getContext('2d');
+        },
+        draw(bundle) {
+            // Called each requestAnimationFrame tick by the factory.
+            // `bundle` is a snapshot with: currentTime, songInfo, isReady,
+            // notes, chords, anchors (all difficulty-filter-aware),
+            // beats, sections, chordTemplates, stringCount, lyrics,
+            // toneChanges, toneBase, mastery, hasPhraseData, inverted,
+            // lefty, renderScale, lyricsVisible, the 2D coordinate
+            // helpers project and fretX, and getNoteState (see below).
+            // `stringCount` is the active arrangement's string count (4
+            // for bass, 6 for guitar, 7+ for extended-range GP imports —
+            // size string-indexed geometry against this, not a hardcoded
+            // 6). If your renderer needs lefty-aware text rendering, check
+            // bundle.lefty and apply the mirror transform yourself —
+            // a bundle-level helper isn't provided because it would
+            // need your renderer's own context, not the factory's.
+            //
+            // bundle.getNoteState(note, chartTime) (slopsmith#254) — call
+            // this per visible chart note / chord-note to find out whether
+            // a scorer (note_detect) has flagged it 'hit' / 'active' (a
+            // sustain currently being held correctly) / 'miss', so the gem
+            // itself can light up / a held sustain can glow instead of
+            // relying on an overlay ring. Returns null when no provider is
+            // registered or it reports nothing for this note; otherwise
+            // { state: 'hit'|'active'|'miss', alpha: 0..1, color: string|null }.
+            // For chord notes pass the chord's time (note_detect keys its
+            // judgments by `${time}_${string}_${fret}`). 'hit' and 'active'
+            // are both "lit" — a renderer may treat them identically; the
+            // provider owns all fade timing via `alpha` and by simply
+            // ceasing to return state when the effect should end.
+        },
+        resize(w, h) {
+            // Optional. Canvas dims already updated; re-create WebGL
+            // framebuffers / reset 2D transforms here.
+        },
+        destroy() {
+            // Optional. Release resources, remove DOM nodes, null refs.
+            // Called before setRenderer() swaps to another renderer
+            // and on highway.stop().
+        },
+    };
+};
+```
+
+Selecting this plugin in the main-player viz picker — or in splitscreen's per-panel picker — calls `highway.setRenderer(factory())` on the existing highway instance. The built-in 2D highway is the default renderer and is restored by passing nullish — `setRenderer(null)` and `setRenderer(undefined)` both work (the implementation gates on `r == null`). Splitscreen panels create one `createHighway()` per panel and each independently consults the picker, so N panels can run different renderers (or N copies of the same renderer with different arrangements) without coordination.
+
+### Lifecycle contract
+
+The factory returns a single renderer instance that may go through multiple `init() → ... → destroy()` cycles as the user navigates between songs or screens. Specifically:
+
+- `init(canvas, bundle)` runs when the highway has a canvas and the renderer takes over drawing. This is when to acquire `getContext()`, build shaders / meshes / DOM nodes, and register listeners.
+- `draw(bundle)` runs on every rAF frame once the WebSocket `ready` message has fired and until the renderer is replaced or the highway stops. It is **not** called during the loading / reconnect window (between `api.init()` + `stop()` and the next `ready`) — that would hand the renderer half-populated chart arrays. Renderers that want to show a "loading" state can read `bundle.isReady` inside a future-widened contract, but today the factory gates `draw` behind the ready flag and `isReady` is only informational once it does fire.
+- `destroy()` runs when the renderer is replaced via another `setRenderer(...)` call, OR when `highway.stop()` is called (e.g. the user navigates away from the player). It releases everything `init()` acquired.
+- **After `destroy()`, the same instance may receive another `init()` call** — this happens on `playSong()` which does `stop()` → `init()` to reuse the same canvas element for the next song. Renderers must tolerate `init()` being called again on an instance that was previously destroyed. Practically: null your refs in destroy, re-acquire them in init.
+- `destroy()` is skipped when it would run on an un-init'd renderer — if a caller does `setRenderer(x)` before the highway ever init'd (possible when restoring a saved picker selection at page load), `x.destroy()` is not called until `x.init()` has run at least once.
+- `resize(w, h)` is optional; runs after init and whenever the canvas dimensions change.
+
+### Key rules
+
+- The factory **returns a fresh object on each call** — important for splitscreen, where multiple panels will each get an independent instance.
+- The renderer **owns its own rendering context** (2D or WebGL). Factory will not call getContext for you.
+- **Canvas context-type swapping.** Browsers lock a `<canvas>` to the first context type successfully acquired for its lifetime: once `getContext('2d')` succeeds, `getContext('webgl2')` on that same canvas returns `null`, and vice versa. To let arbitrary 2D ⇄ WebGL renderer swaps work mid-session, `highway.setRenderer()` reads the next renderer's `contextType` before calling its `init()` and, if it differs from the type currently bound, replaces the underlying `<canvas>` element with a fresh one via `oldCanvas.cloneNode(false)` followed by `oldCanvas.replaceWith(newCanvas)`. The factory then calls the renderer's `init(newCanvas, bundle)` with the fresh element so its `getContext()` succeeds. Practical implications:
+  - **What survives the swap.** `cloneNode(false)` preserves *every HTML attribute* on the element — `id`, `class`, inline `style`, all `data-*` and `aria-*` attributes, `role`, `tabindex`, the attribute form of `width`/`height`, and anything else a plugin attached. DOM position is preserved by `replaceWith()`, so siblings, parents, and surrounding layout are unaffected.
+  - **What does NOT survive.** Event listeners attached via `addEventListener` are NOT cloned, and expando properties set imperatively on the JavaScript object (such as the bound rendering context, or any `canvas._myPlugin = …`-style data a plugin attached) are not carried over either. The bound rendering context being left behind on the detached element is exactly what allows the new canvas to start fresh and accept a different `getContext()` call. Note: `canvas.width`/`canvas.height` *are* reflected HTML attributes, so those values do survive the clone; `api.resize()` re-applies the backing-store dimensions on the new element after the swap regardless.
+  - Renderers must **declare `contextType`** on the returned instance (`'2d'` or `'webgl2'`; absent → `'2d'`). Factories may also expose it as a static (`window.slopsmithViz_<id>.contextType = 'webgl2'`) so core can read it before constructing the renderer — used today by Auto-mode evaluation.
+  - Plugins that hold a stale reference to the highway canvas across renderer swaps — including any code that registered listeners directly on the canvas element rather than on `window`/`document` — should listen for the `highway:canvas-replaced` event on `window.slopsmith` and re-acquire / re-register. `window.slopsmith.emit` dispatches a `CustomEvent`, so the payload `{ oldCanvas, newCanvas, contextType }` lives on `event.detail`, not on the event object itself:
+    ```js
+    window.slopsmith.on('highway:canvas-replaced', (event) => {
+        const { oldCanvas, newCanvas, contextType } = event.detail;
+        // re-acquire / re-register against newCanvas
+    });
+    ```
+    Plugins that re-query `document.getElementById('highway')` lazily inside their own event handlers don't need this listener — they pick up the new element automatically (it keeps `id="highway"`).
+  - **`highway:visibility`** — fired on `window.slopsmith` whenever the highway canvas transitions between displayed and hidden. Detection is DOM-based via `canvas.offsetParent === null` (catches `display:none` on the canvas or any ancestor — e.g. splitscreen's `#highway` hide) or whatever a host explicitly sets via `highway.setVisible(bool)`. While `visible === false`, core skips the rAF `renderer.draw(bundle)` call AND the default 2D draw, so renderers don't have to no-op themselves. The event is emitted only on transitions (including the first one after `init()`), not every frame. Payload `{ visible, canvas }` lives on `event.detail`:
+    ```js
+    window.slopsmith.on('highway:visibility', (event) => {
+        const { visible, canvas } = event.detail;
+        // Toggle any sibling DOM your renderer mounts. The 3D Highway
+        // renderer hides its `.h3d-wrap` overlay here so `display:none`
+        // on `#highway` actually hides the visible output.
+    });
+    ```
+    Renderers that only paint to the slopsmith canvas don't need this listener — the rAF skip is enough. Renderers that mount sibling DOM (separate WebGL contexts, overlays, etc.) do.
+  - **`highway.setVisible(bool | null)`** — forces the visibility state regardless of `offsetParent`. Pass `null` to clear the override and resume DOM-based detection. Useful when the host hides the highway via `visibility:hidden`, `opacity:0`, transforms, or clipping rather than `display:none`. The override re-emits any resulting transition immediately rather than waiting for the next rAF tick.
+  - Default-renderer ctx is closure-cached. The replace path nulls the closure ctx so stale draw paths short-circuit; the next default-renderer `init()` re-acquires the 2D context from the new canvas cleanly.
+- `draw(bundle)` receives difficulty-filtered arrays — never read from `_filteredNotes` or other internals.
+- `_drawHooks` fire for the default 2D renderer (the factory calls them at the end of each frame). Custom WebGL renderers that maintain a 2D overlay canvas (like the bundled 3D highway) also call `window.highway.fireDrawHooks(ctx, W, H)` on that overlay so overlay plugins continue to work regardless of which renderer is active. Custom renderers without a 2D overlay context should not attempt to fire hooks.
+
+### Auto mode — `matchesArrangement(songInfo)` (optional)
+
+The viz picker prepends an "Auto (match arrangement)" entry that is the default selection on fresh installs. When Auto is active, core evaluates registered viz factories on every `song:ready` and swaps the renderer to the first factory whose `matchesArrangement(songInfo)` predicate returns truthy. No match → the built-in 2D highway.
+
+Declare the predicate as a static on the factory (not the instance) so core can evaluate it without constructing a throwaway renderer:
+
+```js
+window.slopsmithViz_piano = function () { /* ... */ };
+window.slopsmithViz_piano.matchesArrangement = function (songInfo) {
+    return /keys|piano|synth/i.test((songInfo && songInfo.arrangement) || '');
+};
+```
+
+- `songInfo` is the highway's live song_info snapshot — `arrangement`, `tuning`, `capo`, `arrangement_index`, `filename`, `artist`, `title`, etc. May be `{}` before the first song loads.
+- Factories without `matchesArrangement` are skipped during auto-selection — the correct default for arrangement-agnostic viz (tabview, jumpingtab) that only make sense as manual picks.
+- Explicit picker selections override Auto and are persisted to `localStorage.vizSelection`, so the pinned choice survives page reloads until the user switches back to "Auto" (which also persists). Picking "Auto" re-evaluates against the current song immediately. In contexts where `localStorage` is unavailable (private mode, sandboxed iframes, some test runners) persistence falls back to the current picker `<option>` value, which still overrides Auto for as long as the page stays loaded.
+- When an Auto-selected renderer fails and core emits `viz:reverted`, the picker falls back to the built-in default and disables auto-switching until the user re-selects Auto.
+- First match wins (picker order), so the registration order of plugins is the tiebreaker. Keep predicates narrow to avoid stealing songs from more specialized viz.
+
+**WebGL viz in Auto mode.** Auto evaluation runs on every `song:ready` regardless of which renderer is active. Auto-installing a WebGL renderer when the canvas is currently 2D — or reverting from a WebGL Auto pick to the default 2D — works without a reload because `setRenderer` swaps the canvas element when `contextType` differs (see "Canvas context-type swapping" above). WebGL viz can therefore safely declare `matchesArrangement` and rely on Auto. For 3D Highway specifically, `_canRun3D()` in app.js still gates Auto from picking it on machines without WebGL2 — that fallback is independent of canvas swapping.
+
+## 2. Overlay contract — for add-on layers
+
+Plugins that add a layer on top of whichever visualization is active — HUDs, fretboard diagrams, chord labels, practice feedback — don't replace the renderer. They manage their own canvas, their own rAF loop, and a toggle button somewhere visible (typically a navbar pill), reading public highway state via the getters:
+
+- `highway.getTime()` / `highway.getBeats()` — current playback position
+- `highway.getNotes()` / `highway.getChords()` — difficulty-filter-aware arrays
+- `highway.getChordTemplates()` — chord shape lookup table; index by `chord.id` from `getChords()` to get `{ name, fingers, frets }`. `fingers` and `frets` are per-string arrays (length matches the tuning's string count); within `fingers`, `-1` = unused, `0` = open string, `n > 0` = finger number. RS XML sources populate real fingerings; GP imports currently emit all `-1` since pre-import sources don't carry finger data. Not filter-aware: templates are static metadata, every `chord_id` referenced by `getChords()` is guaranteed valid.
+- `highway.getSongInfo()` — tuning, arrangement, capo
+- `highway.getStringCount()` — number of strings on the active arrangement (4 for bass, 6 for guitar, 7+ for extended-range GP imports). Derived server-side as `max(notes-max-string + 1, name-based fallback, len(tuning))` where the tuning length only contributes when it isn't the RS-XML padded 6-string form (sloppak / GP-imported sources carry trimmed tuning lengths). The name-based fallback is 4 for arrangements containing "bass" (case-insensitive) and 6 otherwise. This combination handles partial-string-usage charts (a 6-string lead that never plays string 5), extended-range GP imports (5-string bass, 7-string guitar), and sloppaks that explicitly encode the instrument range — without requiring plugins to do their own arrangement-name matching.
+- `highway.getLefty()` / `highway.getInverted()` — mirror + invert state
+
+Overlays do NOT appear in the viz picker and do NOT declare `"type": "visualization"` in `plugin.json`. They coexist with whichever renderer (default 2D, 3D highway, piano, ...) the user has picked.
+
+### Key rules
+
+- **Own your rAF + canvas** — don't piggyback on `_drawHooks` or on `createHighway`'s rendering context. Draw hooks fire for the default 2D renderer and for custom renderers that explicitly call `window.highway.fireDrawHooks(ctx, W, H)` (e.g. the bundled 3D highway fires them on its 2D overlay canvas), but not for every custom renderer.
+- **Re-read state every frame** — overlay output must track whatever the current renderer is drawing. Don't cache note positions across frames.
+- **Respect lefty + invert toggles** — if the overlay depicts strings or frets, mirror using the same transforms the active renderer would.
+- **If you position with `highway.project` / `highway.fretX` (the 2D-highway geometry), gate on `highway.isDefaultRenderer()`** — those helpers describe the *built-in 2D* highway's depth curve and fret zoom. When a custom renderer (3D highway, piano, …) is active your draw hook still fires (on that renderer's 2D overlay layer), but those coordinates won't match its scene — markers land in arbitrary places. Skip rendering when `isDefaultRenderer()` is false; the custom renderer owns that feedback. Renderer-agnostic overlays (fretboard diagram, chord-label HUD — they use `getNotes()`/`getChordTemplates()` + their own layout) don't need this guard.
+- **Clean up on toggle-off** — cancel rAF and remove/hide the overlay canvas so inactive overlays aren't wasting frames.
+
+Reference: [fretboard plugin](https://github.com/byrongamatos/slopsmith-plugin-fretboard) — canonical overlay implementation (navbar toggle, own canvas, 80ms active-note window).
+
+### Why two contracts?
+
+setRenderer plugs into an existing highway — main-player or splitscreen-panel — reusing its WebSocket and data parsing, so the common "I want a different look for the same data" case is zero boilerplate AND multi-instance for free. Overlays compose with whatever renderer is active — they decorate rather than replace, so multiple can stack (fretboard + chord labels + practice feedback) without fighting over the canvas.
+
+A previous standalone-pane contract (`window.createMyVisualization({ container })` with its own WebSocket per pane) was used by splitscreen pre-Wave-C. It's been retired now that splitscreen calls `setRenderer` on per-panel `createHighway()` instances; if you find references in older plugin docs or external integration guides, those describe the legacy path.
+
+## 3. Note-state provider — for scorers that want renderers to "light up" notes (slopsmith#254)
+
+A scoring plugin (note_detect) can publish a per-note judgment so whichever renderer is active draws the **gem itself** lit on a correct hit, and keeps a sustain trail glowing while it's still being played correctly — instead of a separate overlay ring floating near the note.
+
+```js
+// In the plugin (after resolving the highway instance):
+highway.setNoteStateProvider((note, chartTime) => {
+    // `note` is the chart note object ({ t, s, f, sus, ... }); for chord
+    // notes `chartTime` is the chord's time. Return one of:
+    //   - falsy  → no special state (render normally)
+    //   - 'hit'    — struck correctly; renderer lights the gem
+    //   - 'active' — a sustained note is right now being held correctly
+    //   - 'miss'   — missed; renderer may red-wash the gem
+    //   - { state: <one of the above>, alpha?: 0..1, color?: '#rrggbb' }
+    // You own all fade timing: return a decaying `alpha` for a struck-note
+    // glow, `alpha: 1` (or a bare string) for a held sustain, and stop
+    // returning state when the effect should end. Keep it cheap — it's
+    // called per visible note per renderer per frame.
+});
+// On teardown:  highway.setNoteStateProvider(null);
+```
+
+- Only one provider is active at a time (last `setNoteStateProvider` wins). `highway.getNoteStateProvider()` returns the current one (or null).
+- The built-in 2D highway consults it in `drawNote` / `drawSustains` / the chord-frame path: 'hit'/'active' → bright string colour + additive halo + a contained "sizzle" (crackling sparks, throbbing core, a shockwave ring on a fresh strike) on the gem and a bright (vs dim) sustain trail; 'miss' → faint red wash. The bundled **3D highway** reads the same data via `bundle.getNoteState` (bright string-tinted outline + bright body + glowing sustain + a contained sparkle hugging the note rect on hit/active; red outline + suppressed body on miss). Custom renderers that want it call `bundle.getNoteState(note, chartTime)` — it null-guards and returns the normalized `{ state, alpha, color }` (or null).
+- This is orthogonal to the overlay contract: note_detect remains an overlay (HUD, diagnostic miss markers, the "currently detected" indicator) *and* a scorer that feeds this provider. A renderer that ignores `getNoteState` simply doesn't light gems — nothing breaks.
+
+## Related
+
+- [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) — guide index
+- [plugin-manifest.md](plugin-manifest.md) — declaring `"type": "visualization"`
+- [websocket-protocol.md](websocket-protocol.md) — the WebSocket stream that drives `bundle`
+- [plugin-audio-mixer.md](plugin-audio-mixer.md) — companion contract for audio-producing plugins

docs/sloppak-hand-editing.md

@@ -4,7 +4,7 @@ A `.sloppak` is just a zip of plain files: some YAML, some JSON, some OGG audio,
 
 This guide walks through the most common edits, aimed at musicians who are comfortable with a text editor and Audacity but don't live on the command line.
 
-> For the format **schema** (what every field means, how the wire format works, how to extend the format with new data types), see the authoritative [feedpak spec](https://github.com/got-feedback/feedback-feedpak-spec/blob/main/spec/feedpak-v1.md) (the local [sloppak-spec.md](sloppak-spec.md) is now a pointer to it). This document is the **how-do-I-actually-edit-mine** companion.
+> For the format **schema** (what every field means, how the wire format works, how to extend the format with new data types), see [sloppak-spec.md](sloppak-spec.md). This document is the **how-do-I-actually-edit-mine** companion.
 
 ---
 
@@ -242,7 +242,7 @@ For 4-string bass, only indices 0–3 are meaningful; leave 4 and 5 at `0`.
 
 ### What *not* to put in `manifest.yaml`
 
-Don't add per-machine settings (audio device picks, MIDI port IDs), UI state, or your own play counts. The sloppak holds the song's authored data — anything that varies by user or machine lives in Slopsmith's config dir or the metadata DB. See [feedpak spec §9.5](https://github.com/got-feedback/feedback-feedpak-spec/blob/main/spec/feedpak-v1.md#95-what-does-not-belong-in-a-feedpak) for the full list.
+Don't add per-machine settings (audio device picks, MIDI port IDs), UI state, or your own play counts. The sloppak holds the song's authored data — anything that varies by user or machine lives in Slopsmith's config dir or the metadata DB. See [sloppak-spec.md §5.7](sloppak-spec.md#57-dont-break-the-manifest-contract) for the full list.
 
 ---
 
@@ -261,6 +261,6 @@ For your own use, you can skip this entirely — Slopsmith reads the directory f
 
 ## Out of scope (for now)
 
-- **Authoring a sloppak from scratch** (no Guitar Pro / MusicXML source file) — that's a developer task. Start at [feedpak spec §8 (Reading and writing)](https://github.com/got-feedback/feedback-feedpak-spec/blob/main/spec/feedpak-v1.md#8-reading-and-writing).
-- **Editing notes / chords in `arrangements/*.json`** — technically possible but extremely tedious by hand: hundreds of objects with short field names per song. The fields are documented in [feedpak spec §6 (Arrangement JSON)](https://github.com/got-feedback/feedback-feedpak-spec/blob/main/spec/feedpak-v1.md#6-arrangement-json), but for any real chart edit you want the [Arrangement Editor plugin](https://github.com/got-feedback/feedback-plugin-editor).
+- **Authoring a sloppak from scratch** (no Guitar Pro / MusicXML source file) — that's a developer task. Start at [sloppak-spec.md §4.2](sloppak-spec.md#42-writing-python-server-side).
+- **Editing notes / chords in `arrangements/*.json`** — technically possible but extremely tedious by hand: hundreds of objects with short field names per song. The fields are documented in [sloppak-spec.md §3](sloppak-spec.md#3-arrangement-json--the-wire-format), but for any real chart edit you want the [Arrangement Editor plugin](https://github.com/got-feedback/feedback-plugin-editor).
 - **Loudness normalization / advanced stem processing** — out of scope here; standard Audacity or ffmpeg workflows apply to any OGG file before you drop it into `stems/`.

docs/sloppak-spec.md

@@ -1,49 +1,939 @@
-# Sloppak / feedpak Format — moved
+# Sloppak Format — Developer Guide
 
-The full format specification that used to live here has moved to its own repository and is now
-the **authoritative, versioned reference**:
+Sloppak is Slopsmith's open, hand-editable song format. This guide is for developers who want to **read**, **write**, or **extend** the format — including adding new data types like drum tabs, vocal pitches, lighting cues, key/scale annotations, or anything else a future visualization plugin might need.
 
-> **📖 https://github.com/got-feedback/feedback-feedpak-spec**
-> — normative spec ([`spec/feedpak-v1.md`](https://github.com/got-feedback/feedback-feedpak-spec/blob/main/spec/feedpak-v1.md)),
-> JSON Schemas, examples, and a reference validator.
+> If you're a **user** wanting to modify an existing sloppak — record your own rhythm stem, fix metadata, swap cover art, replace a Demucs split — see [sloppak-hand-editing.md](sloppak-hand-editing.md). That guide is the practical, step-by-step companion to this developer reference.
 
-Update bookmarks to point there. This page is a thin pointer kept at the original path so existing
-links keep resolving.
+The authoritative format reference lives in code (`lib/sloppak.py`, `lib/song.py`); this doc explains the why, the how, and the conventions you should follow when adding to it.
 
-## Naming: `sloppak` here, `feedpak` in the spec
+---
 
-The published format is named **feedpak** (extension `.feedpak`, manifest key `feedpak_version`).
-This codebase still uses the legacy **sloppak** name internally — `lib/sloppak.py`, the
-`.sloppak` extension, `SLOPSMITH_*` env vars, etc. **They describe the same on-disk format.** The
-rename is repo/public-facing only for now (see the top-level workspace `CLAUDE.md`), so when the
-spec says `feedpak` / `feedpak_version`, the packs this server reads and writes today are the same
-structure under the `.sloppak` name. The internal rename is a separate, later effort.
+## 1. Format at a glance
 
-## Hand-editing a pack
+A sloppak exists in **two interchangeable forms**:
 
-For the practical "how do I edit my own pack" walkthrough (record your own stem, fix metadata,
-swap cover art, replace a stem split), see the companion guide that stays in this repo:
-[sloppak-hand-editing.md](sloppak-hand-editing.md).
+| Form | What it is | Used for |
+|---|---|---|
+| **Directory** | A folder named `*.sloppak/` containing the files below | Authoring, hand editing, plugin development |
+| **Zip archive** | A `.sloppak` file (zip with the same files inside) | Distribution |
 
-## Where the format maps to code (this repo)
+Both forms hold identical contents. Slopsmith resolves either transparently — zip files are unpacked to a cache the first time they're opened (see `resolve_source_dir()` in [lib/sloppak.py](../lib/sloppak.py)).
 
-The spec is implementation-independent; this table is the feedback-specific bridge from format
-concepts to the code that reads and writes them. It is **not** part of the format.
+### Directory layout
+
+```
+my-song.sloppak/
+├── manifest.yaml             # Required — all metadata + file index
+├── arrangements/
+│   ├── lead.json             # One JSON per playable arrangement
+│   ├── rhythm.json
+│   └── bass.json
+├── stems/
+│   ├── full.ogg              # Mixed audio (initial single-stem output; may be absent after stem splitting)
+│   ├── guitar.ogg            # Optional individual stems
+│   ├── bass.ogg
+│   ├── drums.ogg
+│   ├── vocals.ogg
+│   └── other.ogg
+├── lyrics.json               # Optional — syllable-level lyrics
+└── cover.jpg                 # Optional — album art
+```
+
+Three rules to remember:
+
+1. **`manifest.yaml` is the index.** Nothing inside the sloppak is auto-discovered — every file path is listed in the manifest. This makes the format predictable: no scanning, no guessing. (One historical exception: the cover-art handler in `server.py` falls back to `cover.jpg` when `manifest.cover` is missing. New code should not add similar filename fallbacks.)
+2. **Filenames in `manifest.yaml` are POSIX paths**, relative to the sloppak root (forward slashes, no leading `/`).
+3. **YAML for the manifest, JSON for everything else.** YAML is hand-editable for users; JSON is fast-parsed and easy to round-trip in code.
+
+---
+
+## 2. `manifest.yaml` reference
+
+Minimal valid manifest:
+
+```yaml
+title: "Black Hole Sun"
+artist: "Soundgarden"
+duration: 320.5
+arrangements:
+  - id: lead
+    name: Lead
+    file: arrangements/lead.json
+    tuning: [0, 0, 0, 0, 0, 0]
+    capo: 0
+stems:
+  - id: full
+    file: stems/full.ogg
+    default: true
+```
+
+Full set of currently-recognized top-level keys:
+
+| Key | Type | Required | Description |
+|---|---|---|---|
+| `title` | string | yes | Song title |
+| `artist` | string | yes | Artist name |
+| `album` | string | no | Album |
+| `year` | int | no | Release year |
+| `duration` | float | yes | Song length in seconds |
+| `arrangements` | list | yes | Playable arrangements (see §2.1) |
+| `stems` | list | yes | Audio stems (see §2.2) |
+| `stem_separation` | object | no | Structured metadata when stems were produced by an automated separation engine (currently `demucs`). Shape: `{engine, model, version}`. See §2.2 for fields + semver semantics per [slopsmith#357](https://github.com/got-feedback/feedback/issues/357). Omitted for single-stem sloppaks (`stems: [{id: full, ...}]`) and for hand-edited / user-recorded stems |
+| `lyrics` | string | no | Path to lyrics JSON |
+| `lyrics_source` | string | no | Where the lyrics came from: `xml` (vocals XML from the chart source), `whisperx` (auto-transcribed), or `user` (hand-edited). Absent on legacy sloppaks — readers should treat missing as `xml` |
+| `lyric_transcription` | object | no | Structured metadata when lyrics came from an automated engine (currently `whisperx`). Same shape as the parent `stem_separation` block defined by [slopsmith#357](https://github.com/got-feedback/feedback/issues/357) — see §2.3 for fields and semver semantics. Omitted for authored lyrics (`xml`/`user`) |
+| `vocal_pitch` | string | no | Path to per-syllable pitch JSON (`{"version": 1, "notes": [{t, d, midi}, ...]}`). Consumed by [slopsmith-plugin-lyrics-karaoke](https://github.com/got-feedback/feedback-plugin-lyrics-karaoke) to render karaoke note bars. See §2.4 |
+| `pitch_extraction` | object | no | Structured metadata when pitch was extracted by an automated engine (currently `crepe` via the demucs server's `/pitch` endpoint). Same shape as `stem_separation` / `lyric_transcription`. Omitted for hand-edited pitch tracks |
+| `cover` | string | no | Path to cover image |
+| `preview` | string | no | Path to a short preview audio clip (OGG) at the sloppak root. Populated when the source carries a separate short browser-preview clip (decoded to `preview.ogg`); absent otherwise. Consumed by [`slopsmith-plugin-song-preview`](https://github.com/got-feedback/feedback-plugin-song-preview) for hover-to-listen previews in the library |
+| `song_timeline` | string | no | Path to a `song_timeline.json` file carrying song-wide beats and sections (see §5.3). When present, its data takes priority over any beats/sections embedded in arrangement JSONs. Older readers ignore the key and fall back to reading beats/sections from the first arrangement JSON as before |
+| `drum_tab` | string | no | Path to `drum_tab.json` — per-piece drum hits (see §5.3). Implemented end-to-end as of slopsmith#344 |
+
+Unknown keys are **silently ignored** by the loader. This is deliberate — it's the extensibility hook (see §5).
+
+### 2.1. `arrangements[]`
+
+Each entry describes one playable arrangement and points at its JSON file:
+
+```yaml
+arrangements:
+  - id: lead              # filesystem-safe stable ID, used for filenames
+    name: Lead            # display name (Lead/Rhythm/Bass/Combo are sorted first)
+    file: arrangements/lead.json
+    tuning: [0, 0, 0, 0, 0, 0]   # six semitone offsets from E A D G B E
+    capo: 0
+    centOffset: 0.0              # optional float, cents; default 0.0
+```
+
+- `tuning` is a list of semitone offsets from standard `E2 A2 D2 G3 B3 E4`. **Six elements is the standard six-string convention** and the only length `lib/tunings.py` produces friendly names for; 5- and 7-string content is accepted by the loader and falls through to a numeric label. For bass, the four bass strings are at indices 0–3; the other two slots are `0`. Consumers should not hard-code `len(tuning) == 6`.
+- `name` controls the sort order in the UI: `Lead > Combo > Rhythm > Bass > everything else`.
+- `centOffset` is a pitch-shift value in cents. Commonly `-1200.0` for extended-range bass arrangements tuned one octave down; small non-zero values for songs mastered at a non-A440 reference pitch (e.g. A443 ≈ +11.8 cents). Absent / `0.0` means no shift. Exposed to plugins via `getSongInfo().centOffset`.
+- Manifest-level `tuning`, `capo`, and `centOffset` **override** anything embedded in the arrangement JSON. The arrangement JSON's own values are fallbacks.
+- `notation` (optional string) — path to a `notation_<id>.json` file carrying standard musical notation data for this arrangement (see §5.3). When present, the loader surfaces it on `LoadedSloppak.notation_by_id[id]` and the highway WS streams `notation_info` + `notation_measures` messages. The `file:` key may be omitted when `notation:` is present — the loader creates a stub arrangement so the notation file can be the sole data source.
+
+### 2.2. `stems[]`
+
+```yaml
+stems:
+  - id: full
+    file: stems/full.ogg
+    default: true        # plays by default when the song opens
+  - id: guitar
+    file: stems/guitar.ogg
+    default: true
+  - id: drums
+    file: stems/drums.ogg
+    default: false
+```
+
+- `id` is referenced by the Stems plugin and any other consumer; keep it stable.
+- `default` accepts `true`/`false`, or strings (`"on"`/`"off"`/`"true"`/etc.) for hand-edited manifests.
+- A freshly converted sloppak from `lib/sloppak_convert.py` starts with a single `{id: full, file: stems/full.ogg, ...}` entry. After stem-splitting (Demucs), `full.ogg` is removed and the manifest is rewritten with per-instrument entries (`guitar`, `bass`, `drums`, `vocals`, `other`). The format requires only that `stems` is non-empty — there's no specific filename or id that must always be present.
+
+When stems were produced by an automated separation engine (Demucs), an optional `stem_separation` block records which engine + model produced them. Per [slopsmith#357](https://github.com/got-feedback/feedback/issues/357):
+
+```yaml
+stem_separation:
+  engine: demucs           # stable engine id; only `demucs` today
+  model: htdemucs_6s       # specific model name (htdemucs_6s / htdemucs_ft / htdemucs / mdx_extra / ...)
+  version: 1.0.0           # semver for slopsmith's stem-artifact contract
+```
+
+Fields:
+- `engine` — stable identifier for the separation engine. Currently always `demucs`. New engines (e.g. a hypothetical `spleeter`) would get their own stable id.
+- `model` — the engine-specific model id used for this split. For Demucs this is the `-n` flag value.
+- `version` — semver for Slopsmith's stem-artifact contract (independent of upstream Demucs / model versions). Bump per the same semantics #357 defines: patch = metadata-only fixes, minor = backward-compatible additions, major = stem set / packing / post-processing changed and existing splits should be regenerated.
+
+Omitted for single-stem sloppaks (`stems: [{id: full, ...}]` — no automated separation ran) and for hand-edited / user-recorded stems. The RFC reserves a separate `stem_authoring` sibling block for the hand-edit case; that's deferred to a follow-up.
+
+A remote Demucs server can use this block as part of a cache key so that changing the model or major version naturally produces a cache miss. Local plugin jobs should preserve this metadata in job state and in any copied/downloaded manifests.
+
+### 2.3. `lyrics`
+
+If present, points at a JSON file containing a flat list of syllable objects:
+
+```json
+[
+  {"t": 12.34, "d": 0.18, "w": "Hel"},
+  {"t": 12.52, "d": 0.22, "w": "lo-"},
+  {"t": 13.10, "d": 0.30, "w": "world"}
+]
+```
+
+| Field | Meaning |
+|---|---|
+| `t` | Time in seconds |
+| `d` | Duration in seconds |
+| `w` | Syllable text. Trailing `-` joins to the next syllable as one word; trailing `+` marks the last syllable of a line (renderer wraps after it). Both are suffixes on a real syllable — not standalone entries. See `static/highway.js` for the rendering: `raw.endsWith('+')` flags end-of-line, and `sylText` strips the trailing marker before drawing |
+
+When lyrics are present, the optional top-level `lyrics_source` key records where they came from. The assembler sets it to `xml` when the lyrics were parsed from the source chart's vocals XML; the WhisperX auto-transcription fallback (`scripts/transcribe_lyrics.py`, or `--auto-lyrics` on the split scripts) sets it to `whisperx`. Hand-edited lyrics should bump it to `user` so UI consumers can render a different badge (or no badge) than for machine-generated lyrics. The key is absent on sloppaks produced before this field existed — readers should treat missing as `xml` for backward compatibility.
+
+When `lyrics_source` is `whisperx` (or any future automated engine), an optional `lyric_transcription` block records which engine + model produced the file. Shape mirrors the parent `stem_separation` RFC ([slopsmith#357](https://github.com/got-feedback/feedback/issues/357)):
+
+```yaml
+lyric_transcription:
+  engine: whisperx     # stable engine id
+  model: medium        # the WhisperX model size that ran (tiny/base/small/medium/large-v2/large-v3)
+  version: 1.0.0       # semver for slopsmith's lyric-transcription artifact contract
+```
+
+Fields:
+- `engine` — stable identifier for the transcription engine; currently always `whisperx`.
+- `model` — the engine-specific model id used for this transcription.
+- `version` — semver for Slopsmith's lyric-transcription artifact contract (independent of upstream Whisper / WhisperX versions). Bump per the same semantics #357 defines for stems: patch = metadata-only fixes, minor = backward-compatible additions, major = output shape changed and existing transcriptions should be regenerated.
+
+Omitted for authored lyrics (`xml` / `user`). A remote WhisperX server can use this block as part of a cache key the same way #357 envisions for stems — caches should miss whenever any of the three fields change, ensuring stale transcriptions don't get returned after a model bump.
+
+### 2.4. `vocal_pitch`
+
+If present, points at a JSON file holding per-syllable pitch data — the karaoke companion to `lyrics`. Consumed by [slopsmith-plugin-lyrics-karaoke](https://github.com/got-feedback/feedback-plugin-lyrics-karaoke) to render karaoke-style note bars over the lyric text. Shape:
+
+```json
+{
+  "version": 1,
+  "notes": [
+    {"t": 12.34, "d": 0.40, "midi": 64},
+    {"t": 12.78, "d": 0.55, "midi": 67}
+  ]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `version` | Schema version of this `vocal_pitch.json` file (currently the integer `1`). Bump on a breaking change to the `notes` entry shape. This is *not* the same as the top-level `pitch_extraction.version` block below, which is a semver string used as a cache-key for the extractor engine |
+| `notes` | List of pitch entries, one per syllable that the extractor could lock onto. `t` + `d` mirror the matching `lyrics.json` entry; `midi` is the MIDI note number (60 = middle C). Syllables the extractor couldn't pitch (silent / sub-confidence) are omitted from this list — it may be shorter than `lyrics.json` |
+
+When pitch came from an automated engine (the demucs server's `/pitch` endpoint, which runs CREPE), the optional top-level `pitch_extraction` block records which engine + model produced the file. Same shape and semver-string semantics as `stem_separation` / `lyric_transcription` — distinct from the in-file integer `version` field above:
+
+```yaml
+pitch_extraction:
+  engine: crepe
+  model: v1
+  version: 1.0.0
+```
+
+Omitted for hand-edited pitch tracks. As with the other two automated-artifact blocks, a remote pitch server can use this for cache-key invalidation.
+
+The sloppak assembler runs pitch extraction automatically when `pitch_extraction.enabled` is set in its config AND a server URL is configured (either `pitch_extraction.server_url` or the shared `demucs_server_url`) AND the sloppak has lyrics + a `stems/vocals.ogg` after the split pass — either because `_maybe_transcribe_lyrics` just produced them via WhisperX OR because they were already on disk (from the source chart's vocals XML, hand-authoring, or an earlier build). Pitch is *not* coupled to `whisperx.enabled` — setting `pitch_extraction.enabled=true` alone (with WhisperX off) is enough to retro-generate pitch over any existing on-disk lyrics. Sloppaks built before this field existed simply don't carry it — readers should treat missing `vocal_pitch` as "no pitch data, fall back to whatever the karaoke plugin's local-extraction path produces (if any)".
+
+---
+
+## 3. Arrangement JSON — the wire format
+
+Arrangement JSON files use the **wire format** produced by `arrangement_to_wire()` — the on-disk representation of a complete arrangement. Slopsmith's `/ws/highway/{filename}` endpoint transports similar data as a sequence of typed messages (`notes`, `chords`, `anchors`, `chord_templates`, `phrases`, …) rather than as one identical top-level JSON object. In practice, the WebSocket stream reuses the same per-object field names where applicable, but it should not be treated as a byte-for-byte match for `arrangements/*.json`.
+
+The authoritative serializer/deserializer is in [lib/song.py](../lib/song.py):
+
+- `arrangement_to_wire(arr) → dict` — write
+- `arrangement_from_wire(dict) → Arrangement` — read
+
+### 3.1. Top-level shape
+
+```json
+{
+  "name": "Lead",
+  "tuning": [0, 0, 0, 0, 0, 0],
+  "capo": 0,
+  "centOffset": 0.0,            /* optional, float cents, default 0.0 */
+  "notes":      [ /* see 3.2 */ ],
+  "chords":     [ /* see 3.3 */ ],
+  "anchors":    [ /* see 3.4 */ ],
+  "handshapes": [ /* see 3.5 */ ],
+  "templates":  [ /* see 3.6 */ ],
+  "phrases":    [ /* optional, see 3.7 */ ],
+  "tones":      { /* optional, see 3.9 */ },
+  "beats":      [ /* see 3.8, only on first arrangement */ ],
+  "sections":   [ /* see 3.8, only on first arrangement */ ]
+}
+```
+
+`beats` and `sections` are **song-level** but live on the first arrangement's JSON for legacy reasons — `lib/sloppak.py` hoists them to the `Song` object on load. If you author multiple arrangements, only put them in one file. **New sloppaks should use `song_timeline.json` instead** (see §2 and §5.3) — when the manifest carries a `song_timeline:` key pointing at a schema-valid file, its beats/sections **replace** whatever the arrangement JSONs loaded (the override is applied after arrangement loading, so a valid `song_timeline.json` always wins). Arrangement-JSON beats/sections remain supported for backward compatibility with all existing sloppaks and are the fallback when the file is absent or invalid.
+
+### 3.2. Notes
+
+Field names are short on purpose — these get streamed thousands of times per song. Don't expand them.
+
+```json
+{
+  "t": 12.345,    // time (s)
+  "s": 2,         // string (0 = lowest)
+  "f": 7,         // fret (0 = open, 24 = max)
+  "sus": 0.5,     // sustain (s, 0 = none)
+  "sl": 9,        // pitched slide-to fret (-1 = no slide)
+  "slu": -1,      // unpitched slide-to fret (-1 = no slide)
+  "bn": 1.0,      // bend amount in semitones
+  "ho": false,    // hammer-on
+  "po": false,    // pull-off
+  "hm": false,    // natural harmonic
+  "hp": false,    // pinch harmonic
+  "pm": false,    // palm mute
+  "mt": false,    // string mute
+  "vb": false,    // vibrato
+  "tr": false,    // tremolo
+  "ac": false,    // accent
+  "tp": false,    // tap
+  "ln": false,    // link-next (chord linking metadata; renderers may ignore — runtime linking is derived from proximity)
+  "fhm": false,   // fret-hand mute
+  "plk": false,   // pluck (pop, bass)
+  "slp": false,   // slap (bass)
+  "rh": -1,       // right-hand fingering (-1 = unset)
+  "pkd": -1,      // pick direction (-1 = unset, 0 = down, 1 = up)
+  "ig": false     // ignore (chart-author flag — note is rendered but not scored / sequenced)
+}
+```
+
+Default values: numbers → `0` or `-1` (slides / `rh` / `pkd`), bools → `false`. Omit fields equal to their default if you're authoring by hand — the parser fills them in. **Encoders should default-omit the newer technique keys** (`ln`, `fhm`, `plk`, `slp`, `rh`, `pkd`, `ig`) — the highway streams notes thousands of times per song, so trimming the common case keeps the WebSocket payload tight. The pre-existing keys are still emitted unconditionally to preserve the legacy wire contract.
+
+### 3.3. Chords
+
+A chord groups note-shaped objects under a single time:
+
+```json
+{
+  "t": 30.0,
+  "id": 12,           // index into templates[]
+  "hd": false,        // high-density flag
+  "notes": [
+    {"s": 0, "f": 3, "sus": 0.0, ...},
+    {"s": 1, "f": 5, "sus": 0.0, ...}
+  ]
+}
+```
+
+Chord notes use the same field set as standalone notes, **except `t` is omitted** (the chord carries the time). The fingering / shape lookup is `chord.id → templates[id]`.
+
+### 3.4. Anchors
+
+Where the fretting hand sits. Drives the highway zoom box.
+
+```json
+{"time": 12.0, "fret": 5, "width": 4}
+```
+
+### 3.5. Hand shapes
+
+Spans during which a chord shape is held:
+
+```json
+{"chord_id": 12, "start_time": 30.0, "end_time": 31.5, "arp": false}
+```
+
+- `chord_id` (`int`, default `0`) — index into `templates[]`; identifies which chord template the span is holding.
+- `start_time` (`float`, default `0.0`) — start of the span in seconds.
+- `end_time` (`float`, default `0.0`) — end of the span in seconds.
+- `arp` (`bool`, default `false`, allowed values `true`/`false`) — whether this hand shape should be treated as an arpeggio span rather than a fully-strummed chord hold.
+
+### 3.6. Chord templates
+
+Named shapes referenced by `chord.id` and `handshape.chord_id`:
+
+```json
+{
+  "name": "Em7",
+  "displayName": "Em7",
+  "arp": false,
+  "fingers": [-1,  2,  1, -1, -1, -1],
+  "frets":   [ 0,  2,  2,  0,  0,  0]
+}
+```
+
+- `name` (`string`, default `""`) — canonical template name used by the parser / authoring data.
+- `displayName` (`string`, default `name`) — label shown in the UI; source XML may use this for display-specific variants such as `-arp`.
+- `arp` (`bool`, default `false`, allowed values `true`/`false`) — whether the template is flagged as arpeggiated. Parsed from explicit XML attributes (`arpeggio` / `arp`, any common casing) or inferred from `displayName` markers such as `-arp`.
+- `fingers` (`int[6]`, default `[-1, -1, -1, -1, -1, -1]`) — fretting-hand finger numbers, lowest string first. `-1` = unused string, `0` = open string / no fretting finger, `1..4` = index/middle/ring/pinky.
+- `frets` (`int[6]`, default `[-1, -1, -1, -1, -1, -1]`) — fret numbers, lowest string first. `-1` = unused string, `0` = open string, positive values = fretted note.
+
+### 3.7. Phrases (optional, multi-difficulty data)
+
+Sources that carry per-phrase difficulty ladders (phrase-aware arrangement XML) include this. GP imports and legacy sloppaks omit it:
+
+```json
+"phrases": [
+  {
+    "start_time": 0.0,
+    "end_time":   12.5,
+    "max_difficulty": 4,
+    "levels": [
+      { "difficulty": 0, "notes": [...], "chords": [...], "anchors": [...], "handshapes": [...] },
+      { "difficulty": 1, "notes": [...], "chords": [...], "anchors": [...], "handshapes": [...] },
+      ...
+    ]
+  }
+]
+```
+
+If you're writing a converter that doesn't have multi-difficulty data, **omit the `phrases` key entirely** (don't emit `"phrases": []`). A missing key signals "no ladder, disable the master-difficulty slider"; an empty list is the same in current code but reads ambiguously.
+
+### 3.8. Beats and sections
+
+```json
+"beats":    [{"time": 0.5, "measure": 1}, {"time": 1.0, "measure": -1}, ...],
+"sections": [{"name": "verse", "number": 1, "time": 12.5}, ...]
+```
+
+`measure: -1` = sub-beat (not a downbeat). Section `name` follows the usual song-structure conventions (`intro`, `verse`, `chorus`, `bridge`, `solo`, `outro`, …).
+
+### 3.9. Tones (optional)
+
+`tones` carries the arrangement's guitar tones — the amp/pedal/cabinet gear and the in-song tone switches. It's populated when the source chart carries tone data (`lib/tones.py`); a sloppak authored from scratch may omit it entirely.
+
+```json
+"tones": {
+  "base": "Clean Rhythm",
+  "changes": [
+    {"t": 12.5, "name": "Lead Drive"},
+    {"t": 48.0, "name": "Clean Rhythm"}
+  ],
+  "definitions": [
+    {
+      "Name": "Clean Rhythm",
+      "Key": "Tone_A",
+      "GearList": { /* raw gear blocks: Amp, PrePedal1-4, … */ }
+    }
+  ]
+}
+```
+
+- `base` (string) — the tone in effect before the first change.
+- `changes` (list, time-sorted) — `{"t": seconds, "name": str}` tone switches. The highway draws a marker at each. Omit when the arrangement never switches tone.
+- `definitions` (list) — the **raw tone objects** (`Name`, `Key`, `GearList`), copied verbatim from the source chart's tone manifest. The Tones plugin parses these into the rendered signal chain (it owns the gear-name/image map, so the data is stored unparsed here).
+
+All three sub-keys are individually optional; an arrangement with none of them simply omits `tones`. Readers that don't know about tones ignore the key (the loader preserves it verbatim).
+
+---
+
+## 4. Reading and writing sloppaks programmatically
+
+### 4.1. Reading (Python, server-side)
+
+```python
+from pathlib import Path
+from sloppak import load_song, load_manifest
+
+# Quick metadata only (parses manifest, skips arrangement JSONs)
+manifest = load_manifest(Path("song.sloppak"))
+
+# Full song load (manifest + all arrangements + lyrics)
+loaded = load_song("song.sloppak", dlc_root=Path("/dlc"), unpack_cache_root=Path("/cache"))
+print(loaded.song.title, len(loaded.song.arrangements))
+print(loaded.stems)        # [{"id": "full", "file": "stems/full.ogg", "default": True}]
+print(loaded.manifest)     # raw dict — read your custom keys here
+```
+
+### 4.2. Writing (Python, server-side)
+
+There's no general-purpose writer in `lib/` yet. The current writer lives in [lib/sloppak_convert.py](../lib/sloppak_convert.py) inside the sloppak assembly function — it's the single source of truth for "how a sloppak gets built." If you need to write sloppaks from a new source, copy the structure of that function:
+
+1. Build a `work_dir/` in temp.
+2. Write `arrangements/{id}.json` per arrangement using `arrangement_to_wire()`.
+3. Encode audio to OGG into `stems/`.
+4. Optionally write `lyrics.json`, `cover.jpg`.
+5. Compose the `manifest` dict and dump as YAML with `yaml.safe_dump(manifest, sort_keys=False, allow_unicode=True)`.
+6. Either `shutil.copytree(work_dir, out)` for directory form, or `_zip_dir(work_dir, out)` for zip form.
+
+Always use `yaml.safe_dump` (not `yaml.dump`) and pass `sort_keys=False` so the human-readable order is preserved.
+
+### 4.3. Reading (JavaScript, plugin-side)
+
+Plugins typically don't read the sloppak file directly — they consume the `/ws/highway/{filename}` WebSocket stream (see [`websocket-protocol.md`](websocket-protocol.md) for the message protocol), which produces the same shapes. If you specifically need raw manifest access from the browser, expose it through a custom backend route in your plugin's `routes.py` and fetch it.
+
+---
+
+## 5. Extending the format — adding new data
+
+Sloppak is designed to be extended without breaking older readers. The conventions below come from how `lyrics`, `stems`, and the optional `phrases` ladder were each added.
+
+### 5.1. The golden rule: **manifest opt-in, file off to the side**
+
+New data types should follow this pattern:
+
+1. **Drop a new file** alongside the standard ones (e.g., `drums.json`, `keys.json`, `lighting.json`).
+2. **Add a manifest key** that *points at* that file (e.g., `drum_tab: drums.json`).
+3. **Make consumers gate on the manifest key**: if the key is absent, do nothing. Never auto-discover by filename — that breaks the "manifest is the index" rule.
+
+So a sloppak with drum tabs would look like:
+
+```yaml
+# manifest.yaml
+title: "Song"
+artist: "Band"
+duration: 240.0
+arrangements: [...]
+stems: [...]
+drum_tab: drum_tab.json     # ← new key
+```
+
+```
+my-song.sloppak/
+├── manifest.yaml
+├── arrangements/...
+├── stems/...
+└── drum_tab.json           # ← new file
+```
+
+Older Slopsmith readers ignore the unknown `drum_tab` key (the loader uses `manifest.get("drum_tab")` / unknown keys pass through). Your plugin checks for it and renders accordingly. **Zero coordination needed with core.**
+
+### 5.2. Naming conventions for new keys and files
+
+- **Manifest keys**: `snake_case`, descriptive, singular when the value is one thing (`lyrics`, `cover`, `drum_tab`), plural when it's a list (`stems`, `arrangements`).
+- **File names**: lowercase, hyphenated or underscored, JSON for structured data, OGG for audio, JPG/PNG for images.
+- **Inside JSON**: short field names for hot-path data that gets streamed thousands of times (`t`, `s`, `f` — see §3.2). Long names are fine for one-off metadata.
+- **Time fields**: always `t` or `time` (not `start`, not `timestamp`) — and always **seconds as floats**, not ms or ticks. Be consistent with the existing wire format.
+- **Indexes / IDs**: stable, filesystem-safe, lowercase. Don't reuse a source format's internal numeric IDs unless you have to.
+
+### 5.3. Worked examples for the kinds of additions you mentioned
+
+#### Drum tab
+
+`drum_tab.json` carries per-piece hits authored on top of the song's audio.
+Implemented end-to-end as of slopsmith#344 (drums-from-scratch): the loader
+in `lib/sloppak.py` parses it, `lib/drums.py` defines the canonical piece-id
+vocabulary, and `/ws/highway/{filename}` streams it as `drum_tab` + chunked
+`drum_hits` messages.
+
+```json
+{
+  "version": 1,
+  "name": "Drums",
+  "kit": [
+    {"id": "kick",      "name": "Kick"},
+    {"id": "snare",     "name": "Snare"},
+    {"id": "hh_closed", "name": "Hi-hat (closed)"},
+    {"id": "hh_open",   "name": "Hi-hat (open)"},
+    {"id": "crash_r",   "name": "Crash (right)"},
+    {"id": "ride",      "name": "Ride"}
+  ],
+  "hits": [
+    {"t": 0.500, "p": "kick",      "v": 110},
+    {"t": 0.750, "p": "snare",     "v":  92},
+    {"t": 0.750, "p": "hh_closed", "v":  70},
+    {"t": 1.000, "p": "snare",     "v":  60, "g": true},
+    {"t": 1.250, "p": "snare",     "v": 105, "f": true},
+    {"t": 4.000, "p": "crash_r",   "v": 120, "k": 0.080}
+  ]
+}
+```
+
+Manifest:
+
+```yaml
+drum_tab: drum_tab.json
+```
+
+##### Hit fields
+
+| key | type | meaning |
+| --- | --- | --- |
+| `t` | float seconds | hit time, required, monotonic in `hits[]` |
+| `p` | string | piece-id from the closed list below; required |
+| `v` | int 1-127 | velocity (default 100) |
+| `g` | bool | ghost note (renders smaller / outline-only) |
+| `f` | bool | flam (renders a small leading ghost glyph 30 ms early) |
+| `k` | float seconds | cymbal-choke tail duration (renders a fade-out) |
+
+##### Canonical piece-id vocabulary
+
+A closed list lives in `lib/drums.py::PIECES`. Open/closed hi-hat are
+**distinct piece-ids**, not articulation flags — hit detection must reject
+a closed-hat strike on an open-hat note, which it can only do if the
+articulation is part of the piece-id.
+
+| piece-id | category | default GM MIDI | default shape |
+| --- | --- | --- | --- |
+| `kick` | kick | 35, 36 | bar (full-width across all non-kick lanes) |
+| `snare` | drum | 38, 40 | rectangle |
+| `snare_xstick` | drum | 37 | hatched rectangle |
+| `tom_hi` | drum | 50, 48 | rectangle |
+| `tom_mid` | drum | 47, 45 | rectangle |
+| `tom_low` | drum | 43 | rectangle |
+| `tom_floor` | drum | 41 | rectangle |
+| `hh_closed` | cymbal | 42 | filled circle |
+| `hh_open` | cymbal | 46 | ring (outline) circle |
+| `hh_pedal` | cymbal | 44 | small circle with × |
+| `stack` | cymbal | 30 | jagged circle (no GM standard — reuses 30 from extended-percussion range) |
+| `crash_l` | cymbal | 49 | circle |
+| `crash_r` | cymbal | 57 | circle |
+| `splash` | cymbal | 55 | small circle |
+| `china` | cymbal | 52 | jagged circle |
+| `ride` | cymbal | 51, 59 | circle |
+| `ride_bell` | cymbal | 53 | circle with centre dot |
+| `bell` | cymbal | 80 | circle with centre dot (no GM standard — reuses "Mute Triangle") |
+
+Unknown piece-ids round-trip through the loader (forward-compat); the
+client just renders them as a default rectangle.
+
+##### Wire format
+
+Streamed as two highway-WS message types:
+
+```json
+{ "type": "drum_tab", "version": 1, "name": "Drums",
+  "kit": [{"id": "kick", "name": "Kick"}, ...], "total": 1234 }
+```
+
+…followed by one or more chunks of 500 hits:
+
+```json
+{ "type": "drum_hits", "data": [{"t": 0.5, "p": "kick", "v": 110}, ...],
+  "total": 1234 }
+```
+
+##### Design notes
+
+- `kit[]` is the legend — fixed metadata, separated from hot-path data.
+- `hits[]` uses short field names because this list can be thousands long.
+- `v` defaults to 100; ghost / flam / choke flags are all optional.
+- Older sloppaks whose drums are encoded as guitar notes (`midi = string*24 + fret`) still play — the drums plugin keeps a legacy decoder that reads the standard `notes` stream and synthesises `drum_hits` from it.
+
+#### Song timeline (beats and sections as a top-level file)
+
+`song_timeline.json` moves song-wide beats and sections out of the first
+arrangement JSON and into a dedicated file. Implemented in `lib/sloppak.py`
+alongside the notation format: the loader reads the manifest's optional
+`song_timeline:` key, validates the file, and populates `Song.beats` /
+`Song.sections` from it, taking priority over any beats/sections embedded
+in arrangement JSONs.
+
+```json
+{
+  "version": 1,
+  "beats": [
+    {"time": 0.500, "measure": 1},
+    {"time": 1.000, "measure": -1},
+    {"time": 1.500, "measure": -1},
+    {"time": 2.000, "measure": 2}
+  ],
+  "sections": [
+    {"name": "intro",  "number": 1, "time": 0.0},
+    {"name": "verse",  "number": 1, "time": 16.0},
+    {"name": "chorus", "number": 1, "time": 32.0}
+  ]
+}
+```
+
+Manifest:
+
+```yaml
+song_timeline: song_timeline.json
+```
+
+| Field in `beats[]` | Type | Notes |
+|---|---|---|
+| `time` | float seconds | Beat timestamp. Matches the existing arrangement-JSON wire convention |
+| `measure` | int | 1-based downbeat number. `-1` = sub-beat (not a downbeat) |
+
+| Field in `sections[]` | Type | Notes |
+|---|---|---|
+| `name` | string | song-structure convention: `intro`, `verse`, `chorus`, `bridge`, `solo`, `outro`, … |
+| `number` | int | Section repeat number |
+| `time` | float seconds | Section start |
+
+**Backward compatibility.** Sloppaks without `song_timeline:` continue to
+work — the loader falls through to reading beats/sections from the first
+arrangement JSON exactly as before. No migration is needed.
+
+**New sloppaks** should put beats/sections here and leave arrangement JSONs
+free of timeline data. This is especially important for notation-only
+arrangements (see below) where there may be no arrangement JSON at all.
+
+---
+
+#### Notation format (standard musical notation per arrangement)
+
+The notation format promotes keys, piano, violin, and any other
+staff-notation instrument to first-class status with their own data
+structure, separate from the guitar wire format. Implemented in
+`lib/sloppak.py` and `lib/notation.py`; the highway WS streams
+`notation_info` + `notation_measures` messages when notation data is
+present for the active arrangement.
+
+**Architecture: per-arrangement, not song-wide.** Unlike `drum_tab`
+(one drum track per song, top-level manifest key), notation is
+per-instrument. A song could carry both `notation_keys.json` and
+`notation_violin.json`. The manifest key lives on the **arrangement
+entry**, not at the top level.
+
+```yaml
+arrangements:
+  - id: keys
+    name: Keys
+    type: piano
+    notation: notation_keys.json   # per-arrangement sub-key
+    # file: is optional when notation: is present
+```
+
+```text
+my-song.sloppak/
+├── manifest.yaml
+├── song_timeline.json
+├── notation_keys.json
+└── stems/
+    └── full.ogg
+```
+
+**`notation_<id>.json` — file schema:**
+
+```json
+{
+  "version": 1,
+  "instrument": "piano",
+  "staves": [
+    {"id": "rh", "clef": "G2", "label": "Right Hand"},
+    {"id": "lh", "clef": "F4", "label": "Left Hand"}
+  ],
+  "measures": [
+    {
+      "idx": 1,
+      "t": 0.0,
+      "ts": [4, 4],
+      "ks": 0,
+      "tempo": 120.0,
+      "staves": {
+        "rh": {
+          "voices": [{"v": 1, "beats": [
+            {"t": 0.000, "dur": 4, "notes": [{"midi": 64}]},
+            {"t": 0.500, "dur": 4, "notes": [{"midi": 67}]}
+          ]}]
+        },
+        "lh": {
+          "voices": [{"v": 1, "beats": [
+            {"t": 0.000, "dur": 1, "notes": [{"midi": 52}, {"midi": 60}]}
+          ]}]
+        }
+      }
+    }
+  ]
+}
+```
+
+**Top-level fields:**
+
+| Field | Type | Notes |
+|---|---|---|
+| `version` | int | Always `1`. Bump on breaking schema change |
+| `instrument` | string | Mirrors arrangement `type`: `piano`, `violin`, `guitar`, etc. Makes the file self-describing |
+| `rights` | string | Optional copyright / rights text (MusicXML `<rights>`). Omit when absent |
+| `lyricist` | string | Optional lyricist credit (MusicXML `<creator type="lyricist">`). Omit when absent |
+| `arranger` | string | Optional arranger credit (MusicXML `<creator type="arranger">`). Omit when absent |
+| `staves` | list | Static staff definitions. Each has `id` (stable, referenced by `measures[].staves` keys), `clef` (see below), and optional `label` |
+| `measures` | list | Ordered measure data — the hot path |
+
+**Clef vocabulary** (defined in `lib/notation.py::CLEFS`):
+
+| Value | Meaning |
+|---|---|
+| `G2` | Treble clef — guitar, violin, flute, piano RH |
+| `F4` | Bass clef — bass guitar, cello, piano LH |
+| `C3` | Alto clef — viola |
+| `C4` | Tenor clef — cello upper register, trombone |
+| `neutral` | Unpitched / percussion staff |
+
+**Measure fields:**
+
+| Field | Type | Notes |
+|---|---|---|
+| `idx` | int | 1-based measure number |
+| `t` | float | Time in seconds at measure downbeat |
+| `ts` | int[2] | Time signature `[numerator, denominator]`. Omit if unchanged |
+| `beat_groups` | int[] | Beat grouping for compound and irregular meters, as a list of integers. Each integer is the count of time-signature denominator units in that primary beat group. The sum must equal the time-signature numerator. E.g. 6/8 → `[3, 3]`; 9/8 → `[3, 3, 3]`; 7/8 → `[2, 2, 3]`; 5/8 → `[2, 3]` or `[3, 2]`. Omit for simple meters (2/4, 3/4, 4/4) where grouping is unambiguous. Renderers translate this to their own beam-grouping API at render time — this field is renderer-agnostic. |
+| `ks` | int | Key signature: semitones from C, −7 to +7 (negative = flats, positive = sharps). Omit if unchanged |
+| `tempo` | float | BPM. Omit if unchanged |
+| `pickup` | bool | `true` when this measure is an anacrusis (pickup / upbeat) shorter than the time signature implies (MusicXML `implicit="yes"`). Renderers suppress the measure number and start counting from the next full measure. Omit when false |
+| `staves` | object | Keyed by staff `id`. Each staff has optional `clef` (omit if unchanged) and `voices` |
+
+**Beat fields** (inside `staves → voices → beats`):
+
+| Field | Default | Notes |
+|---|---|---|
+| `t` | required | Time in seconds |
+| `dur` | required | Duration denominator: `1`=whole, `2`=half, `4`=quarter, `8`=eighth, `16`=sixteenth, `32`=thirty-second |
+| `dot` | omit | Augmentation dots: `1`=dotted, `2`=double-dotted |
+| `rest` | omit | `true` if this beat is a rest; `notes` is omitted |
+| `tu` | omit | Tuplet: `[numerator, denominator]`, e.g. `[3, 2]` for triplet |
+| `beat_pos` | omit | Exact position within the measure as a rational `[numerator, denominator]` pair, where the denominator is the time-signature denominator. E.g. beat 2 in 6/8 (the second dotted quarter) = `[3, 8]`. Avoids floating-point imprecision when deriving beat position from tempo and absolute time. Omit if not set by the importer. Renderers that do not recognise this field derive position from `t` and the tempo map as before. |
+| `notes` | omit | List of note objects (omit for rests) |
+| `dyn` | omit | Dynamic: `ppp`, `pp`, `p`, `mp`, `mf`, `f`, `ff`, `fff` |
+| `slr` | omit | Slur start |
+| `slre` | omit | Slur end |
+| `grace` | omit | Grace-note beat, typed: `"a"` = acciaccatura (slashed, steals time from the previous note; MusicXML `<grace slash="yes">`), `"p"` = appoggiatura (unslashed, steals time from the following note; `<grace>`). The beat's `dur` is the grace note's written duration. Vocabulary in `lib/notation.py::GRACE_TYPES` |
+| `arp` | omit | `true` when the beat's chord is arpeggiated (rolled; MusicXML `<arpeggiate>`) |
+| `ferm` | omit | `true` when the beat carries a fermata (MusicXML `<fermata>`) |
+| `spd` / `sph` / `spu` | omit | Sustain pedal: pedal **d**own / **h**old-through-this-beat / **u**p. This is the only pedal encoding — there is deliberately no separate `ped` field. MusicXML mapping: `<pedal type="start">` → `spd`, `<pedal type="change">` → `spu` + `spd` on the same beat (re-pedal), `<pedal type="stop">` → `spu`; beats inside an active pedal span carry `sph` |
+| Additional beat effects | omit | `cre`, `dec`, `vib`, `vibw`, `fade`, `pm`, `lr`, `slap`, `pop`, `tap`, `su`, `sd`, `rasg`, `golpe`, `wah`, `txt`, `chrd` — all optional, omit when absent |
+
+**Note fields** (inside `beats → notes`):
+
+| Field | Default | Notes |
+|---|---|---|
+| `midi` | required | MIDI pitch 0–127. Unambiguous — no string/fret/tuning indirection |
+| `tied` | omit | Tied from the previous beat |
+| `acc` | omit | Accidental override: `null`/omit = derive from key sig; `0` = force natural (♮); `−2`/`−1`/`1`/`2` = double-flat/flat/sharp/double-sharp |
+| `stem` | omit | Force stem direction: `"up"` or `"down"` (MusicXML `<stem>`). Omit to let the renderer decide. Vocabulary in `lib/notation.py::STEM_DIRECTIONS` |
+| Additional note effects | omit | `stc`, `ten`, `ac`, `hac`, `vib`, `vibw`, `dead`, `ghost`, `fng`, `rfng`, `str`, `harm`, `bend`, `slide`, `trill`, `ho`, `po`, `tp`, `barre` — all optional |
+
+**Wire format.** `song_info` carries `has_notation: bool`. Notation data
+is streamed as two highway-WS message types after `sections`, before `anchors`:
+
+```json
+{"type": "notation_info", "version": 1, "instrument": "piano",
+ "staves": [...], "total": 64}
+```
+
+…followed by one or more chunks of 32 measures:
+
+```json
+{"type": "notation_measures", "data": [...], "total": 64}
+```
+
+`total` is the measure count across **all** chunks. Clients accumulate `data` arrays until the accumulated measure count reaches `total` (an individual chunk's `data.length` says nothing — every full chunk of a multi-chunk stream is shorter than `total`). The `anchors` frame that follows the notation block is a secondary end-of-block signal.
+
+**`lib/notation.py`** is the vocabulary library: `SCHEMA_VERSION`, `CLEFS`, `DURATIONS`, `validate_notation()`, `measure_to_wire()`, `measures_to_wire()`.
+
+**Legacy fallback.** Sloppaks that carry keys as guitar wire format (Clone Hero converted content) continue to work — the notation plugin checks for the `notation` key on the arrangement entry. When absent, it falls back to decoding guitar wire format notes via `midi = s * 24 + f`.
+
+**v1 non-features (accepted limitations).** The following are deliberately
+out of schema v1; they ship, if ever, as **additive v1.x patches** (new
+optional fields old consumers ignore — the permissive validator passes
+unknown fields through by design):
+
+- Microtonal pitch (anything finer than the ±2 semitone `acc` vocabulary).
+- Figured bass.
+- Mid-measure key-signature, time-signature, or clef changes (all three are
+  measure-granular in v1).
+- Ottava lines (`ott`), repeat/volta barline semantics (`barline`),
+  ornaments beyond trills (mordents, turns), tremolo (`trem`), and notated
+  glissando lines (`glis`).
+
+Importers MUST drop these source features with a logged warning rather than
+approximate them into wrong notation; renderers MUST NOT invent semantics
+for field names from this list before a v1.x patch specifies them.
+
+---
+
+#### Key / scale annotations (for theory-aware visualizations)
+
+`keys.json` mirroring the `sections[]` shape:
+
+```json
+{
+  "version": 1,
+  "events": [
+    {"t":   0.0, "key": "Em",     "scale": "natural_minor"},
+    {"t":  64.5, "key": "G",      "scale": "major"},
+    {"t": 142.0, "key": "Em",     "scale": "natural_minor"}
+  ]
+}
+```
+
+Manifest:
+
+```yaml
+keys: keys.json
+```
+
+Each entry implicitly applies until the next event. Same model as `sections[]`.
+
+#### Vocal pitch contour (a different shape, a different key)
+
+The canonical `vocal_pitch` key + file (defined in §2.4) is the
+per-syllable note format consumed by the karaoke plugin —
+`{version: 1, notes: [{t, d, midi}]}`. If you want to ship a finer-
+grained pitch *contour* (one sample every 20 ms, Hz instead of MIDI),
+that's a different shape and should ride on its own manifest key so
+the two don't collide:
+
+```yaml
+vocal_pitch_contour: vocal_pitch_contour.json
+```
+
+```json
+{
+  "version": 1,
+  "samples": [
+    {"t": 0.000, "hz": 220.5},
+    {"t": 0.020, "hz": 222.1}
+  ]
+}
+```
+
+Per §5.1, manifest keys are cheap — reach for a new one when the
+schema diverges, don't overload an existing key with a second shape.
+
+### 5.4. `version` field — always include it
+
+Every new file should have `"version": 1` at the top. It's free insurance: when you change the schema later, `version: 2` consumers can branch on it. Old consumers without that branch ignore the file (or fall back gracefully).
+
+### 5.5. Stay backward-compatible
+
+If you change a field that already shipped:
+
+- **Adding fields** is always safe (older readers ignore them).
+- **Removing fields** breaks older readers. Don't.
+- **Repurposing fields** (changing meaning or units) is the worst — bump `version` and branch.
+
+If you're tempted to remove or repurpose: leave the old field, add a new one, and sunset the old one over a release or two.
+
+### 5.6. When to put data inside an arrangement vs. its own file
+
+- **Inside arrangement JSON** (`arrangements/lead.json`):
+  - Data that is *per-arrangement* and *per-instrument* (notes, chords, anchors, hand-shapes — guitar specifics).
+  - Data that meaningfully differs between Lead and Rhythm versions of the same song.
+- **Its own file** (and pointed-at via manifest key):
+  - Data that is *song-wide* (lyrics, beats, sections, tempo map, drum tab, lighting, key/scale changes).
+  - Data that may be authored or generated independently of the playable arrangement (a stem split, an AI-generated drum tab).
+
+Beats and sections historically lived inside the first arrangement JSON (early arrangement XML put them there). The `song_timeline.json` file (see §5.3) is the correct home for new sloppaks — the loader reads it first and it takes priority. New song-wide data should always be its own file.
+
+### 5.7. Don't break the manifest contract
+
+A few things that should *not* end up in `manifest.yaml`:
+
+- **Per-machine settings** (DMX universes, IPs, output device picks) — those go in `${CONFIG_DIR}/...json`, not the sloppak.
+- **UI state** (last zoom level, panel sizes) — `localStorage` only.
+- **User progress / play counts** — Slopsmith stores these in its metadata DB, not in the sloppak.
+
+The sloppak holds **the song's authored data**. Anything that varies by user or by machine is out.
+
+---
+
+## 6. Quick reference — file types you'll touch
+
+| File | Format | Schema lives in | Authority |
+|---|---|---|---|
+| `manifest.yaml` | YAML | `lib/sloppak.py` (`load_manifest`, `extract_meta`) | This doc + the loader |
+| `arrangements/*.json` | JSON | `lib/song.py` (`arrangement_to_wire`, `arrangement_from_wire`) | The wire-format functions |
+| `lyrics.json` | JSON (flat list) | `lib/sloppak.py` (passed through to `Song.lyrics`) | This doc §2.3 |
+| `song_timeline.json` | JSON | `lib/sloppak.py` (loader) | This doc §5.3 |
+| `notation_<id>.json` | JSON | `lib/notation.py` (`validate_notation`, `measures_to_wire`) | This doc §5.3 |
+| `stems/*.ogg` | OGG Vorbis | — | Convention: `q:a 5` for size/quality balance |
+| `cover.jpg` | JPEG | — | Convention: square, 500–1500 px on a side |
+| Your new file | JSON (preferred) | Your plugin's spec doc | You |
+
+---
+
+## 7. Testing your extension
+
+If you add a new file type or manifest key:
+
+1. **Round-trip test**: write a sample, load it, write it back, compare. Add to `tests/test_sloppak.py`.
+2. **Backward-compat test**: load a sloppak that *doesn't* have your new key — your code must not crash, and the song must still play.
+3. **Hand-edit test**: open the directory form in a text editor, change a field by hand, reload Slopsmith. The format is meant to be hand-editable; your additions should preserve that.
+4. **Both forms**: test with both the directory form and the zipped form. The unpack cache is invalidated based on mtime and size, so you can repackage and reload without restarting the server.
+
+The full pytest suite (`pytest`) must stay green before any PR.
+
+---
+
+## 8. Where to look in the code
 
 | For… | Read |
 |---|---|
 | Format detection, source resolution, zip unpacking | [lib/sloppak.py](../lib/sloppak.py) |
 | Data classes (`Note`, `Chord`, `Arrangement`, `Song`, `Phrase`) | [lib/song.py](../lib/song.py) |
 | Wire-format helpers (`*_to_wire` / `*_from_wire`) | [lib/song.py](../lib/song.py) |
-| The reference pack writer (assembly pipeline) | [lib/sloppak_convert.py](../lib/sloppak_convert.py) |
-| Drum-tab vocabulary and wire helpers | [lib/drums.py](../lib/drums.py) |
+| The reference sloppak writer | [lib/sloppak_convert.py](../lib/sloppak_convert.py) |
+| Drum tab vocabulary and wire helpers | [lib/drums.py](../lib/drums.py) |
 | Notation vocabulary and wire helpers | [lib/notation.py](../lib/notation.py) |
 | Live streaming over WebSocket (consumes the same shapes) | `server.py` (`/ws/highway/{filename}`) |
-| The plugin system (where new visualization consumers go) | [CLAUDE.md](../CLAUDE.md) |
+| The plugin system (where new viz consumers go) | [docs/PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) + [docs/plugin-visualization-contracts.md](plugin-visualization-contracts.md) |
 | Tests | [tests/test_sloppak.py](../tests/test_sloppak.py), [tests/test_sloppak_convert.py](../tests/test_sloppak_convert.py) |
-
-> **Note on older section references.** Some inline code comments in this repo cite section
-> numbers from the previous version of this document (e.g. "sloppak-spec §5.3"). The external spec
-> renumbered its sections, so those citations are approximate — find the topic by name in the
-> [feedpak spec](https://github.com/got-feedback/feedback-feedpak-spec/blob/main/spec/feedpak-v1.md)
-> rather than by the old number.

docs/testing-plugins.md

@@ -0,0 +1,104 @@
+# Testing plugins
+
+Slopsmith has three test surfaces — Python unit/integration tests (pytest), JS plugin-API contract tests (Node), and end-to-end browser tests (Playwright). This doc covers what to use when.
+
+## Test layout
+
+```text
+tests/
+├── conftest.py          Shared pytest fixtures (isolate_logging)
+├── test_plugins.py      Plugin loader + load_sibling + collision tests (includes reset_plugin_state)
+├── test_song.py         Wire-format serialization round-trips
+├── test_*.py            Per-feature backend tests
+├── js/                  Node --test JS plugin-API contract tests
+└── browser/             Playwright end-to-end tests
+```
+
+## Running tests
+
+```bash
+pytest                              # All Python tests
+pytest tests/test_plugins.py -v     # Specific file
+pytest -k "load_sibling" -v         # Pattern match
+
+npm run test:js                     # Node-native JS contract tests
+npm run install:playwright          # One-time: install Chromium
+npm test                            # Playwright browser tests
+npm run test:headed                 # Playwright with visible browser
+npm run test:debug                  # Playwright inspector
+```
+
+CI runs `pytest` on every push/PR to `main` (Python 3.12).
+
+## Shared fixtures
+
+### `isolate_logging` (in `conftest.py`)
+
+Saves and restores handlers, level, and `propagate` flag on the `slopsmith`, `uvicorn`, `uvicorn.error`, and `uvicorn.access` loggers, plus calls `structlog.reset_defaults()`. **Import into any test module that calls `configure_logging()`** so mutations don't bleed across tests.
+
+```python
+def test_my_log_thing(isolate_logging):
+    configure_logging()
+    # ... assertions
+```
+
+### `reset_plugin_state` (in `test_plugins.py`)
+
+Local fixture used by plugin-loader tests. Saves and restores:
+- `plugins.LOADED_PLUGINS`
+- any `plugin_*` keys in `sys.modules`
+- the bare names the tests simulate (`util`, `extractor`) in `sys.modules`
+- `sys.path` (the loader mutates it)
+
+Also unsets `SLOPSMITH_PLUGINS_DIR` for the test's duration via `monkeypatch` so a CI env that pre-sets it can't leak real user plugins into a tmp-path-driven test.
+
+If you're authoring a plugin that ships top-level helper modules, model new tests on the patterns in `test_plugins.py` — use `reset_plugin_state` to guarantee a clean import slate.
+
+## Backend test patterns
+
+- **Wire-format round-trips.** `test_song.py` is the model: pure serialization tests, no fixtures, narrative docstring. Pattern: build a `Song`/`Arrangement`/`Note`, serialize, deserialize, assert equal.
+- **Loader behaviour.** `test_plugins.py` uses tmp-path-driven plugin roots + `reset_plugin_state` + `_make_plugin` / `_run_load_plugins` helpers. Adopt these helpers for any new loader-touching tests.
+- **Async / WebSocket.** Tests for FastAPI WebSocket endpoints use `httpx.AsyncClient` and `app.websocket_connect()`. See `test_audio.py` and `test_highway_3d_routes.py` for examples.
+
+## JS contract tests (`tests/js/`)
+
+Plain `node --test` files. No browser, no server. Cover the plugin-API surface as exposed on `window.slopsmith` and related globals. Run with `npm run test:js`.
+
+Use these when a plugin needs to assert against the API contract without spinning up a real browser. They run in seconds; CI can grow these without slowing.
+
+## Browser tests (`tests/browser/`)
+
+Playwright + Chromium. `playwright.config.ts` runs serially (`workers: 1`) and boots a real Slopsmith instance via Docker Compose. Traces / video on failure.
+
+What's currently covered: page load and keyboard shortcuts. **No plugin E2E patterns yet** — if you're adding the first one for your plugin, set the precedent. Suggested structure:
+
+```ts
+import { test, expect } from '@playwright/test';
+
+test('my plugin loads its navbar entry', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.getByRole('link', { name: 'My Plugin' })).toBeVisible();
+});
+
+test('my plugin shortcut fires', async ({ page }) => {
+    await page.goto('/#plugin-my_plugin');
+    await page.keyboard.press('k');
+    await expect(page.getByTestId('my-plugin-toggle')).toHaveAttribute('aria-pressed', 'true');
+});
+```
+
+Prefer `data-testid` over text-based selectors so refactors don't break tests.
+
+## Debugging
+
+- **Browser console shortcut inventory.** `_listShortcuts()` prints every registered shortcut, its scope, and source.
+- **`LOG_FORMAT=json pytest`** — get machine-readable test logs.
+- **`pytest -s`** — disable output capture (handy for `print()`-style debug, though prefer `log.debug()` in production code).
+- **Playwright trace viewer** — `npx playwright show-trace test-results/.../trace.zip` after a failure.
+
+## Related
+
+- [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) — guide index
+- [plugin-logging.md](plugin-logging.md) — `context["log"]` and why `print()` breaks the logging pipeline
+- [plugin-sibling-imports.md](plugin-sibling-imports.md) — `load_sibling` and the collision tests
+- [plugin-keyboard-shortcuts.md](plugin-keyboard-shortcuts.md) — `window.registerShortcut` and `_listShortcuts()`

docs/websocket-protocol.md

@@ -0,0 +1,44 @@
+# Highway WebSocket protocol reference
+
+The highway WebSocket at `/ws/highway/{filename}?arrangement={index}` streams a song's chart data to the player. Plugins that drive their own highway, replace the renderer (see [plugin-visualization-contracts.md](plugin-visualization-contracts.md)), or consume the stream directly all read these frames.
+
+## Message order
+
+Each connection receives the following JSON frames, roughly in this order:
+
+| Message | Shape | Description |
+|---------|-------|-------------|
+| `loading` | `{ type: 'loading', stage }` | Status/progress message during extraction or conversion. |
+| `song_info` | `{ type, title, artist, arrangement, arrangement_index, arrangements, duration, tuning, capo, format, audio_url, audio_error, stems }` | Song metadata. `arrangements` is the full list for the switcher. `audio_url` is `null` when audio is unavailable, in which case `audio_error` is non-null; otherwise `audio_error` is `null`. `stems` is always present — an empty array for non-sloppak songs or sloppak songs with no split stems. `tuning` is an array whose length depends on the source arrangement (typically 6 for guitar, 4 for bass, but extended-range GP imports can be 7/8 for guitar or 5/6 for bass — use `highway.getStringCount()` for the authoritative count). |
+| `beats` | `{ type, data: [{ time, measure }] }` | Beat timestamps with measure numbers. |
+| `sections` | `{ type, data: [{ time, name }] }` | Named sections (Intro, Verse, Chorus, etc.). |
+| `anchors` | `{ type, data: [{ time, fret, width }] }` | Fret zoom anchors. |
+| `chord_templates` | `{ type, data: [{ name, frets: [6] }] }` | Named chord shapes. |
+| `lyrics` | `{ type, data: [{ w, t, d }] }` | Syllables: `w`=word, `t`=time, `d`=duration. `-` joins to previous, `+` = line break. |
+| `tone_changes` | `{ type: 'tone_changes', base, data: [{ time, name }] }` | Optional — tone change events relative to the arrangement base tone; only sent if tones were found. |
+| `notes` | `{ type, data: [{ t, s, f, sus, ho, po, sl, bn, ... }] }` | Single notes. |
+| `chords` | `{ type, data: [{ t, notes: [{ s, f, sus, ... }] }] }` | Chord events. |
+| `phrases` | `{ type, data: [{ start_time, end_time, max_difficulty, levels: [...] }], total }` | Optional — per-phrase difficulty ladder for master-difficulty slider (slopsmith#48). Only sent when the source chart carries multi-level phrase data (legacy archive / phrase-aware sloppak). Sent in chunks (`data` is a batch, `total` is the full count across messages) to avoid multi-MB single frames. Absent for GP imports and legacy sloppak; consumers must treat missing message as "single fixed difficulty — slider disabled". |
+| `ready` | `{ type: 'ready' }` | All data sent — safe to finalize and start rendering. |
+
+## Delivery guarantees
+
+Message delivery is **incremental**. You may receive `loading` updates and `lyrics` before note/chord payloads. `tone_changes` comes after `lyrics` when present and may be omitted entirely. **Do not finalize rendering until you receive `ready`.**
+
+## Consumer notes
+
+- **Tuning array length follows arrangement.** 6 strings for guitar, 4 for bass, more for extended-range GP imports. Use `highway.getStringCount()` for the authoritative count rather than `tuning.length` (which can be the RS-XML padded 6-string form).
+- **Chord templates are static.** Every `chord_id` referenced by `chords` is guaranteed to be present in `chord_templates`.
+- **Notes carry technique fields.** `ho` = hammer-on, `po` = pull-off, `sl` = slide target, `bn` = bend amount. The full set is defined in `lib/song.py`.
+- **Multiple connections are supported.** Split-screen panels, lyrics panes, and jumping-tab panes each open their own WebSocket. By design — don't try to multiplex.
+
+## Phrase payload (slopsmith#48)
+
+`phrases.data` is an array of phrase objects. Each phrase has `start_time`, `end_time`, `max_difficulty`, and `levels`. Each `level` has `difficulty`, `notes`, `chords`, `anchors`, `handshapes` — fully scoped to that phrase. The master-difficulty slider applies a single difficulty across all phrases by selecting the matching level.
+
+## Related
+
+- [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) — guide index
+- [plugin-visualization-contracts.md](plugin-visualization-contracts.md) — bundle shape passed to `draw()`
+- [sloppak-spec.md](sloppak-spec.md) — sloppak format these messages are derived from
+- `lib/song.py` — server-side `Note`, `Chord`, `Arrangement`, `Song` data models

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"}

plugins/input_setup/plugin.json

@@ -1,46 +0,0 @@
-{
-  "id": "input_setup",
-  "name": "Input Setup",
-  "version": "0.1.0",
-  "bundled": true,
-  "private": false,
-  "standards": ["capability-pipelines.v1", "plugin-runtime-idempotent.v1"],
-  "script": "screen.js",
-  "settings": { "html": "settings.html" },
-  "description": "Per-instrument input-device selection and calibration, used during onboarding and re-launchable from Settings.",
-  "category": "practice",
-  "capabilities": {
-    "input-calibration": {
-      "roles": ["owner"],
-      "commands": ["run", "status", "inspect"],
-      "events": ["calibration-started", "calibration-done", "calibration-skipped"],
-      "kind": "command",
-      "mode": "active",
-      "compatibility": "none",
-      "ownership": "exclusive-owner",
-      "safety": "safe",
-      "description": "Owns the per-instrument input-setup wizard workflow; onboarding and Settings dispatch through the runtime.",
-      "version": 1
-    },
-    "audio-input": {
-      "roles": ["requester"],
-      "requests": ["list-sources", "select-source", "open-source"],
-      "mode": "active",
-      "compatibility": "degrade-noop",
-      "ownership": "requester-only",
-      "safety": "sensitive",
-      "description": "Picks the guitar/bass audio input device through the core audio-input domain.",
-      "version": 1
-    },
-    "midi-input": {
-      "roles": ["requester"],
-      "requests": ["discover", "list-sources", "select-source", "open-source", "close-source"],
-      "mode": "active",
-      "compatibility": "degrade-noop",
-      "ownership": "requester-only",
-      "safety": "sensitive",
-      "description": "Picks the keys/drums MIDI device through the core midi-input domain (Web-MIDI provider ships built-in with the domain).",
-      "version": 1
-    }
-  }
-}

plugins/input_setup/screen.js

@@ -1,353 +0,0 @@
-/*
- * input_setup — per-instrument input-device selection & calibration.
- *
- * Bundled core plugin (constitution P-II vanilla JS). It:
- *  1. supplies a Web-MIDI source provider to the core `midi-input` domain;
- *  2. owns the `input-calibration` capability domain (run / status / inspect);
- *  3. renders the onboarding input-setup wizard (one pass per instrument):
- *       - guitar/bass → pick via `audio-input`, then launch note_detect's
- *         Calibration Wizard (note-detection is a deferred surface — JS API);
- *       - keys/drums  → pick via `midi-input`, then a live "play a note /
- *         hit a pad" confirmation.
- *
- * Idempotent (plugin-runtime-idempotent.v1): re-hydration is a no-op.
- */
-(function () {
-    'use strict';
-
-    window.slopsmith = window.slopsmith || {};
-    if (window.slopsmithInputSetup && window.slopsmithInputSetup.version === 1) return;
-
-    const capabilities = window.slopsmith.capabilities;
-    const DONE_KEY = (inst) => `input_setup.done.${inst}`;
-    const INSTRUMENTS = {
-        guitar: { label: 'Guitar', mode: 'audio' },
-        bass: { label: 'Bass', mode: 'audio' },
-        keys: { label: 'Keys / Piano', mode: 'midi' },
-        piano: { label: 'Keys / Piano', mode: 'midi' },
-        drums: { label: 'Drums', mode: 'midi' },
-    };
-
-    const esc = (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => (
-        { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
-
-    function _isDone(inst) { try { return window.localStorage.getItem(DONE_KEY(inst)) === '1'; } catch (_) { return false; } }
-    function _markDone(inst, v) { try { if (v) window.localStorage.setItem(DONE_KEY(inst), '1'); else window.localStorage.removeItem(DONE_KEY(inst)); } catch (_) { /* private mode */ } }
-
-    // The Web-MIDI source provider now ships built-in with the core midi-input
-    // domain (static/capabilities/midi-input.js), so input_setup is a pure
-    // consumer — it just discovers/selects/opens through `window.slopsmith.midiInput`.
-
-    // ── audio-input helper (guitar/bass device context) ─────────────────────
-    async function _audioSources() {
-        if (!capabilities || typeof capabilities.command !== 'function') return { sources: [], selected: null };
-        try {
-            const r = await capabilities.command('audio-input', 'list-sources', { requester: 'input_setup' });
-            const p = (r && r.payload) || {};
-            let sources = Array.isArray(p.sources) ? p.sources : [];
-            // Exclude MIDI devices some plugins export into audio-input
-            // (e.g. keys-highway-3d's pseudonymized 'midi-input-N'): they aren't
-            // audio inputs and the cryptic labels confuse this guitar/bass picker.
-            sources = sources.filter((s) => s
-                && !/midi/i.test(String(s.providerId || ''))
-                && !/^midi-input/i.test(String(s.label || '')));
-            // De-dupe by display label — the desktop engine enumerates the same
-            // device under several driver types, so the same name can repeat.
-            const seen = new Set();
-            sources = sources.filter((s) => {
-                const key = String(s.label || '').toLowerCase();
-                if (seen.has(key)) return false;
-                seen.add(key);
-                return true;
-            });
-            const selected = sources.find((s) => s && s.selected) || null;
-            return { sources, selected };
-        } catch (_) { return { sources: [], selected: null }; }
-    }
-
-    // ── Wizard UI ────────────────────────────────────────────────────────────
-    // Renders sequential per-instrument panels into `host`. Resolves the
-    // returned promise to { completed:[...], skipped:[...] } when finished.
-    function _runWizard(opts) {
-        opts = opts || {};
-        const instruments = (Array.isArray(opts.instruments) ? opts.instruments : [])
-            .map((i) => String(i).toLowerCase()).filter((i) => INSTRUMENTS[i]);
-        // De-dupe keys/piano (same MIDI flow under one label).
-        const seen = new Set();
-        const queue = instruments.filter((i) => { const k = INSTRUMENTS[i].label; if (seen.has(k)) return false; seen.add(k); return true; });
-
-        const completed = [];
-        const skipped = [];
-        let idx = 0;
-
-        return new Promise((resolve) => {
-            const host = opts.host;
-            if (!host) { resolve({ completed, skipped }); return; }
-
-            function finish() {
-                _emitOwner('calibration-done', { completed: completed.slice(), skipped: skipped.slice() });
-                if (typeof opts.onComplete === 'function') { try { opts.onComplete({ completed, skipped }); } catch (_) {} }
-                resolve({ completed, skipped });
-            }
-            // Per-panel teardown run on EVERY exit (Continue or the generic "Skip
-            // for now"), so an opened MIDI session/listener never leaks past the
-            // panel that opened it.
-            let _activeCleanup = null;
-            function next() {
-                if (idx >= queue.length) { finish(); return; }
-                renderPanel(queue[idx]);
-            }
-            function advance(inst, didComplete) {
-                if (_activeCleanup) { try { _activeCleanup(); } catch (_) {} _activeCleanup = null; }
-                if (didComplete) { _markDone(inst, true); if (!completed.includes(inst)) completed.push(inst); }
-                else { if (!skipped.includes(inst)) skipped.push(inst); }
-                idx += 1;
-                next();
-            }
-
-            function shell(inst, bodyHtml, footHtml) {
-                const meta = INSTRUMENTS[inst];
-                host.innerHTML =
-                    '<div class="space-y-4">' +
-                    '<div><div class="text-xs uppercase tracking-wider text-fb-textDim">Input setup — step ' + (idx + 1) + ' of ' + queue.length + '</div>' +
-                    '<h3 class="text-lg font-bold text-fb-text mt-0.5">Set up your ' + esc(meta.label) + '</h3></div>' +
-                    '<div data-is-body>' + bodyHtml + '</div>' +
-                    '<div class="flex justify-between items-center pt-1">' +
-                    '<button type="button" data-is-skip class="text-sm text-fb-textDim hover:text-fb-text">Skip for now</button>' +
-                    '<div data-is-foot>' + (footHtml || '') + '</div></div></div>';
-                host.querySelector('[data-is-skip]').addEventListener('click', () => advance(inst, false));
-            }
-
-            // ── per-instrument panels ───────────────────────────────────────
-            async function renderPanel(inst) {
-                const meta = INSTRUMENTS[inst];
-                if (meta.mode === 'audio') return renderAudioPanel(inst);
-                return renderMidiPanel(inst);
-            }
-
-            // Guitar/bass: show the audio source (audio-input) and launch the
-            // note_detect Calibration Wizard for the deep work.
-            async function renderAudioPanel(inst) {
-                const { sources, selected } = await _audioSources();
-                const opts2 = sources.map((s) =>
-                    '<option value="' + esc(s.logicalSourceKey || s.sourceId || '') + '"' + (s.selected ? ' selected' : '') + '>' + esc(s.label || 'Input') + '</option>').join('');
-                const hasDetector = !!(window.noteDetect && typeof window.noteDetect.launchCalibration === 'function');
-                const body =
-                    '<p class="text-sm text-fb-textDim">Pick your audio input, then run the calibration to set levels, channel and latency.</p>' +
-                    (sources.length
-                        ? '<label class="block text-xs uppercase tracking-wider text-fb-textDim mt-3 mb-1">Audio input</label>' +
-                          '<select data-is-audio class="w-full bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1.5 text-sm text-fb-text outline-none">' + opts2 + '</select>'
-                        : '<p class="text-sm text-fb-accent mt-2">No audio input detected yet — plug in your interface, or skip and set this up later.</p>') +
-                    (hasDetector ? '' : '<p class="text-xs text-fb-textDim mt-3">The note detector isn’t loaded here — you can calibrate later from the player.</p>');
-                const foot =
-                    '<button type="button" data-is-cal class="bg-fb-primary hover:bg-fb-primaryHi text-white px-5 py-2 rounded-md font-medium">' +
-                    (hasDetector ? 'Calibrate' : 'Continue') + '</button>';
-                shell(inst, body, foot);
-
-                const sel = host.querySelector('[data-is-audio]');
-                const commitAudio = (key) => {
-                    if (!capabilities || !key) return;
-                    capabilities.command('audio-input', 'select-source', { requester: 'input_setup', payload: { logicalSourceKey: key } }).catch(() => {});
-                };
-                if (sel) {
-                    sel.addEventListener('change', () => commitAudio(sel.value));
-                    // The <select> shows its first option by default, but no `change`
-                    // fires for that implicit pick — so on a first run with nothing yet
-                    // selected, audio-input would calibrate against the wrong/no source.
-                    // Commit the shown option up-front so the displayed device is the
-                    // one calibrated (idempotent if it was already selected).
-                    if (!selected) commitAudio(sel.value);
-                }
-                // Tell the tuner tables / note_detect which instrument this is.
-                try { fetch('/api/settings', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ instrument: inst }) }); } catch (_) {}
-
-                host.querySelector('[data-is-cal]').addEventListener('click', () => {
-                    if (hasDetector) {
-                        window.noteDetect.launchCalibration({
-                            instrument: inst,
-                            onDone: () => advance(inst, true),
-                            onCancel: () => { /* stay on this panel; user can skip or retry */ },
-                        });
-                    } else {
-                        advance(inst, true);
-                    }
-                });
-            }
-
-            // Keys/drums: pick a MIDI device via midi-input and confirm a live hit.
-            async function renderMidiPanel(inst) {
-                const mi = window.slopsmith.midiInput;
-                // Availability is the midi-input DOMAIN being present, not the
-                // Web-MIDI browser API — the domain coordinates providers (the
-                // built-in Web-MIDI one, plus any native/desktop adapter), so
-                // gating on navigator.requestMIDIAccess would hide a usable
-                // non-Web-MIDI provider before discover() is ever called.
-                const midiAvailable = !!(mi && mi.version === 1);
-                if (!midiAvailable) {
-                    shell(inst,
-                        '<p class="text-sm text-fb-accent">MIDI input isn’t available here. Connect a MIDI keyboard/e-kit in a supported environment, or skip for now.</p>',
-                        '<button type="button" data-is-skip2 class="bg-fb-primary hover:bg-fb-primaryHi text-white px-5 py-2 rounded-md font-medium">Continue</button>');
-                    host.querySelector('[data-is-skip2]').addEventListener('click', () => advance(inst, false));
-                    return;
-                }
-                const verb = inst === 'drums' ? 'hit a pad' : 'play a note';
-                shell(inst,
-                    '<p class="text-sm text-fb-textDim">Connect your MIDI device, pick it below, then ' + verb + ' to confirm it’s working.</p>' +
-                    '<div class="mt-3 flex items-center gap-2">' +
-                    '<button type="button" data-is-scan class="text-sm text-fb-primary hover:text-fb-primaryHi">Scan for MIDI devices</button></div>' +
-                    '<div data-is-midi-wrap class="hidden mt-2">' +
-                    '<select data-is-midi class="w-full bg-gray-800/50 border border-gray-700 rounded-md px-2 py-1.5 text-sm text-fb-text outline-none"></select>' +
-                    '<p data-is-test class="text-sm text-fb-textDim mt-2">Waiting for input…</p></div>',
-                    '<button type="button" data-is-next disabled class="bg-fb-primary disabled:opacity-40 text-white px-5 py-2 rounded-md font-medium">Continue</button>');
-
-                const wrap = host.querySelector('[data-is-midi-wrap]');
-                const select = host.querySelector('[data-is-midi]');
-                const testEl = host.querySelector('[data-is-test]');
-                const nextBtn = host.querySelector('[data-is-next]');
-                let activeKey = null;
-                let listener = null;
-                let activeHandle = null;
-                let openSeq = 0;
-
-                async function openSelected() {
-                    // Tear down the previous device + RESET the confirmation
-                    // state, so a hit on a prior device can't leave Continue
-                    // enabled for a newly-selected device that hasn't been heard.
-                    const myGen = ++openSeq;
-                    if (activeHandle && listener) { try { activeHandle.removeListener(listener); } catch (_) {} }
-                    if (activeKey) { try { mi.close({ requester: 'input_setup', logicalSourceKey: activeKey }); } catch (_) {} }
-                    activeHandle = null;
-                    listener = null;
-                    nextBtn.disabled = true;
-                    _markDone(inst, false);
-                    // Capture the requested key in a local: a newer openSelected()
-                    // overwrites the shared `activeKey`, so comparing it after the
-                    // awaits would let a stale open bind the wrong device.
-                    const requestedKey = select.value;
-                    activeKey = requestedKey;
-                    if (!requestedKey) { testEl.textContent = ''; return; }
-                    testEl.textContent = 'Waiting for input…';
-                    await mi.select(requestedKey);
-                    const res = await mi.open({ requester: 'input_setup', logicalSourceKey: requestedKey });
-                    // Discard a stale open if a newer openSelected() superseded us.
-                    if (myGen !== openSeq) { try { if (res) mi.close({ requester: 'input_setup', logicalSourceKey: requestedKey }); } catch (_) {} return; }
-                    if (!res || !res.handle) { testEl.textContent = 'Could not open this device.'; activeKey = null; return; }
-                    activeHandle = res.handle;
-                    listener = (data) => {
-                        // 0x90 = note-on (any channel); velocity > 0.
-                        if (data && (data[0] & 0xf0) === 0x90 && data[2] > 0) {
-                            testEl.innerHTML = '<span class="text-fb-primary font-semibold">✓ Got it</span> — device is working.';
-                            nextBtn.disabled = false;
-                            _markDone(inst, true);
-                        }
-                    };
-                    activeHandle.addListener(listener);
-                }
-
-                host.querySelector('[data-is-scan]').addEventListener('click', async () => {
-                    await mi.discover();
-                    // Show every source the midi-input domain surfaces — not just
-                    // the built-in Web-MIDI provider — so a native/desktop MIDI
-                    // adapter registered with the domain is selectable too.
-                    const sources = window.slopsmith.midiInput.listSources() || [];
-                    if (!sources.length) { testEl && (testEl.textContent = ''); wrap.classList.remove('hidden'); select.innerHTML = '<option>No MIDI devices found</option>'; select.disabled = true; return; }
-                    wrap.classList.remove('hidden');
-                    select.disabled = false;
-                    select.innerHTML = sources.map((s) => '<option value="' + esc(s.logicalSourceKey) + '"' + (s.selected ? ' selected' : '') + '>' + esc(s.label) + '</option>').join('');
-                    openSelected();
-                });
-                select.addEventListener('change', openSelected);
-                // Close the open session/listener on ANY exit (Continue or the
-                // generic Skip), so a scanned+selected device doesn't keep its
-                // Web-MIDI input live after the panel advances.
-                _activeCleanup = () => {
-                    if (activeHandle && listener) { try { activeHandle.removeListener(listener); } catch (_) {} }
-                    if (activeKey) { try { mi.close({ requester: 'input_setup', logicalSourceKey: activeKey }); } catch (_) {} }
-                    activeHandle = null; listener = null; activeKey = null;
-                };
-                nextBtn.addEventListener('click', () => advance(inst, true));
-            }
-
-            _emitOwner('calibration-started', { instruments: queue.slice() });
-            next();
-        });
-    }
-
-    function _emitOwner(event, detail) {
-        try { capabilities && capabilities.emitEvent && capabilities.emitEvent('input-calibration', event, detail || {}); } catch (_) {}
-    }
-
-    // ── input-calibration owner domain ───────────────────────────────────────
-    function _statusPayload(instruments) {
-        const list = (Array.isArray(instruments) && instruments.length ? instruments : Object.keys(INSTRUMENTS))
-            .map((i) => String(i).toLowerCase());
-        const status = {};
-        list.forEach((i) => { if (INSTRUMENTS[i]) status[i] = _isDone(i) ? 'done' : 'needs-setup'; });
-        return status;
-    }
-
-    if (capabilities && typeof capabilities.registerOwner === 'function') {
-        capabilities.registerOwner('input-calibration', {
-            pluginId: 'input_setup',
-            kind: 'command',
-            safety: 'safe',
-            commands: ['run', 'status', 'inspect'],
-            events: ['calibration-started', 'calibration-done', 'calibration-skipped'],
-            description: 'Per-instrument input-setup wizard workflow (audio via audio-input + note_detect; MIDI via midi-input).',
-            handlers: {
-                inspect: () => ({ outcome: 'handled', payload: { available: true, status: _statusPayload() } }),
-                status: (ctx) => ({ outcome: 'handled', payload: { status: _statusPayload((ctx.payload || {}).instruments) } }),
-                // `run` is fire-and-launch: an interactive wizard far exceeds the
-                // ~250ms handler timeout, so it starts the overlay and returns
-                // immediately. Completion is signaled by the `calibration-done`
-                // event (mirrors audio-monitoring `start`). A second `run` while
-                // one is open is a no-op (single overlay).
-                run: (ctx) => {
-                    const instruments = ((ctx.payload || {}).instruments) || [];
-                    if (!document.getElementById('input-setup-overlay')) launch(instruments);
-                    return { outcome: 'handled', payload: { started: true, instruments } };
-                },
-            },
-        });
-    }
-
-    // ── public surface (onboarding + Settings re-entry) ──────────────────────
-    function mount(container, options) {
-        options = options || {};
-        return _runWizard({ host: container, instruments: options.instruments || [], onComplete: options.onComplete, onSkip: options.onSkip });
-    }
-
-    function launch(instruments) {
-        const overlay = document.createElement('div');
-        overlay.id = 'input-setup-overlay';
-        overlay.className = 'fixed inset-0 z-[210] bg-black/60 backdrop-blur-sm flex items-center justify-center p-4';
-        overlay.innerHTML = '<div class="bg-fb-card rounded-xl border border-fb-border/50 w-full max-w-lg p-6" data-is-host></div>';
-        document.body.appendChild(overlay);
-        const host = overlay.querySelector('[data-is-host]');
-        return _runWizard({ host, instruments: instruments || [] }).then((r) => { overlay.remove(); return r; });
-    }
-
-    window.slopsmithInputSetup = {
-        version: 1,
-        mount,
-        launch,
-        status: (instruments) => _statusPayload(instruments),
-    };
-
-    // Settings-panel re-entry (settings.html "Set up input devices" button).
-    // Re-runs the wizard for the player's selected instrument paths, falling
-    // back to all instruments when progression isn't available.
-    window._inputSetupRelaunch = async function () {
-        let instruments = [];
-        try {
-            const r = await fetch('/api/progression');
-            if (r.ok) {
-                const d = await r.json();
-                const paths = Array.isArray(d.paths) ? d.paths : [];
-                instruments = paths.map((p) => (typeof p === 'string' ? p : (p && p.id))).filter(Boolean);
-            }
-        } catch (_) { /* offline — fall back below */ }
-        if (!instruments.length) instruments = ['guitar', 'bass', 'keys', 'drums'];
-        launch(instruments);
-    };
-})();

plugins/input_setup/settings.html

@@ -1,16 +0,0 @@
-<div class="space-y-4 py-2">
-    <div class="bg-dark-900/50 p-3 rounded-xl border border-gray-800/50">
-        <h3 class="text-sm font-medium text-gray-200">Input devices &amp; calibration</h3>
-        <p class="text-[11px] text-gray-500 mt-1">
-            Re-run the input setup wizard for your instrument paths — pick your audio
-            input or MIDI device and confirm it's working. Guitar/bass also opens the
-            calibration wizard.
-        </p>
-        <button type="button"
-            onclick="window._inputSetupRelaunch &amp;&amp; window._inputSetupRelaunch()"
-            class="mt-3 px-4 py-2 bg-accent hover:bg-accent-light text-white text-sm font-medium rounded-lg">
-            Set up input devices
-        </button>
-        <p id="input-setup-settings-status" class="text-[11px] text-gray-500 mt-2"></p>
-    </div>
-</div>

requirements-test.txt

@@ -1,5 +1,6 @@
 pytest>=8.0
 httpx>=0.27.0
+jsonschema>=4.0
 # Required by tests/test_lyrics_transcribe.py for the vocals_has_signal
 # RMS-gate tests (silent vs loud WAV generation). Without these the
 # soundfile-backed tests are silently skipped via pytest.importorskip

schema/plugin.schema.json

@@ -0,0 +1,261 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$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. Contributions must use AGPL-3.0-only. Capability metadata follows capability-pipelines.v1 and is intentionally additive.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["id", "name"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_.-]+$",
+      "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",
+      "minLength": 1,
+      "description": "Human-readable name shown in UI surfaces."
+    },
+    "version": {
+      "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."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["visualization"],
+      "description": "Role hint (slopsmith#36). 'visualization' makes the plugin eligible for the viz picker; must pair with a window.slopsmithViz_<id> factory."
+    },
+    "license": {
+      "type": "string",
+      "description": "SPDX identifier. Contributions must use AGPL-3.0-only.",
+      "enum": ["AGPL-3.0-only"]
+    },
+    "nav": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label", "screen"],
+      "properties": {
+        "label": { "type": "string", "minLength": 1 },
+        "screen": { "type": "string", "pattern": "^[a-z][a-z0-9_-]*$" }
+      },
+      "description": "Optional navigation metadata. Plugin UI declares stable ui contributions for attribution."
+    },
+    "screen": {
+      "$ref": "#/$defs/pluginRelpath",
+      "description": "Relative path to HTML mounted at #plugin-<id>."
+    },
+    "script": {
+      "$ref": "#/$defs/pluginRelpath",
+      "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": {
+      "$ref": "#/$defs/pluginRelpath",
+      "description": "Relative path to Python module exporting setup(app, context). See docs/plugin-manifest.md."
+    },
+    "tour": {
+      "$ref": "#/$defs/pluginRelpath",
+      "description": "Relative path to tour JSON for the in-app onboarding tour."
+    },
+    "settings": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "html": {
+          "$ref": "#/$defs/pluginRelpath",
+          "description": "Relative path to settings-panel HTML."
+        },
+        "server_files": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "not": { "pattern": "^/|^[a-zA-Z]:|\\\\|(^|/)\\.\\.(/|$)|//|(^|/)\\.(/|$)|^\\." },
+            "description": "Relpath under context['config_dir']. No abs paths, no '..', no '//', no './', no leading dotfiles, no backslashes. Mirrors the runtime _validate_relpath rules in plugins/__init__.py so a schema-valid manifest is also load-time-valid. Trailing '/' denotes a directory (recurse)."
+          },
+          "uniqueItems": true,
+          "description": "Opt-in for Settings export/import (slopsmith#113). Files included in user-triggered backups. See docs/plugin-manifest.md."
+        }
+      }
+    },
+    "diagnostics": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "server_files": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "not": { "pattern": "^/|^[a-zA-Z]:|\\\\|(^|/)\\.\\.(/|$)|//|(^|/)\\.(/|$)|^\\." }
+          },
+          "uniqueItems": true,
+          "description": "Files copied verbatim into plugins/<id>/<relpath> inside the diagnostics bundle. Path rules match the settings.server_files pattern (no abs paths, no '..', no '//', no './', no leading dotfiles, no backslashes)."
+        },
+        "callable": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*:[A-Za-z_][A-Za-z0-9_]*$",
+          "description": "<module>:<function> resolved via load_sibling at export time. Called with {'plugin_id', 'config_dir'} dict; return dict/list/bytes/str."
+        }
+      },
+      "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": "Reserved runtime-domain metadata. New native declarations use capabilities."
+    },
+    "domains": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/domainName" },
+      "additionalProperties": { "$ref": "#/$defs/domainDeclaration" },
+      "description": "Runtime-domain declaration alias. New native declarations use capabilities."
+    },
+    "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 bridge declarations for privileged compatibility surfaces."
+    }
+  },
+  "allOf": [
+    {
+      "$comment": "type=visualization requires a script (the window.slopsmithViz_<id> factory)",
+      "if": { "properties": { "type": { "const": "visualization" } }, "required": ["type"] },
+      "then": { "required": ["script"] }
+    }
+  ],
+  "$defs": {
+    "pluginRelpath": {
+      "type": "string",
+      "minLength": 1,
+      "not": { "pattern": "^/|^[a-zA-Z]:|\\\\|(^|/)\\.\\.(/|$)|//|(^|/)\\.(/|$)|^\\.|[?#]" }
+    },
+    "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
+      }
+    }
+  }
+}

specs/012-midi-input-domain/spec.md

@@ -1,110 +0,0 @@
-# Spec 012 — MIDI-Input Control-Plane Capability Domain
-
-**Status:** active (control-plane slice) · **Issues:** #873 (impl), #880 (this spec) · **Base:** `release/v0.3.0`
-
-## Summary
-
-`midi-input` is a **core-owned provider-coordinator** capability domain for MIDI
-device discovery, selection, and open/close session lifecycle — the MIDI analog
-of `audio-input` (spec 006). It gives every MIDI consumer in Slopsmith (the
-`input_setup` onboarding wizard, the `piano`/keys and `drums` plugins, and — as
-a follow-up — note-detection's Web-MIDI provider) **one device-access boundary**:
-one permission prompt, one source list, one redaction boundary.
-
-## Motivation
-
-Today each MIDI consumer calls `navigator.requestMIDIAccess()` privately
-(piano, drums, plugin-midi, note-detection's `midi` provider kind), so there is
-no shared source list, no single permission prompt, and no common redaction of
-device labels. The onboarding input-setup step (#874/#876/#877) needs a single
-governed surface to pick and verify a MIDI device per instrument.
-
-## Why not reuse `audio-input`
-
-`audio-input`'s source/`source.open` contract is audio-frame-centric:
-`channelSummary`/`channelCount`/`channelShape`, `requiredChannelShape`, and
-redaction keyed to audio handles/buffers/samples. MIDI carries discrete messages
-and has no channel shape. Folding MIDI in would overload the audio contract and
-its redaction boundary. A sibling domain keeps both contracts clean and lets
-each evolve independently — the same reasoning that made `audio-input` and
-`audio-monitoring` siblings rather than one domain.
-
-## Why core-owned (not plugin-owned)
-
-An input control plane outlives any one feature; `audio-input` is
-`core.audio.session`-owned, not owned by a feature plugin. If `input_setup`
-owned `midi-input`, the domain's lifetime would be coupled to the wizard, and
-migrating ownership later (every consumer, persistence key, diagnostics schema
-references the owner) is costly. The domain is `core.midi-input`.
-
-## Contract
-
-- **Owner:** `core.midi-input`, kind `provider-coordinator`, safety `sensitive`.
-- **Public commands:** `inspect`, `list-sources`, `discover`, `select-source`,
-  `open-source`, `close-source`.
-- **Provider operations:** `source.enumerate`, `source.describe`, `source.open`,
-  `source.close`.
-- **Events:** `provider-registered`, `provider-unregistered`,
-  `availability-changed`, `sources-changed`, `source-selected`, `source-opened`,
-  `source-closed`.
-
-### Sources & identity
-
-Providers register source summaries with `providerId`, a stable `sourceId`, a
-derived **redaction-safe** `logicalSourceKey` (`providerId::sourceId`),
-`kind: "midi"`, a label, and `availability`. Persistence and diagnostics use the
-`logicalSourceKey`, never the human device label.
-
-### Permission model (Web-MIDI nuance)
-
-`requestMIDIAccess()` gates the **whole input list**, so **`discover` is the
-permission boundary** (not `open-source`, as it is for audio). `inspect` /
-`list-sources` / `select-source` are **prompt-free** and never request access.
-`discover` records `denied` / `unavailable` outcomes; `open-source` attaches a
-shared listener session to an already-discovered source and never re-prompts.
-
-### Sessions
-
-One shared open session per source across requesters (refcounted); the provider
-receives `source.close` only after the last requester releases. Live MIDI
-message delivery (for the "play a note / hit a pad" calibration check) is exposed
-to in-page consumers via the public `window.slopsmith.midiInput` session handle
-**only** — never as raw capability events or in diagnostics.
-
-### Persistence & redaction
-
-Selected source persists under `slopsmith.midiInput.selectedLogicalSourceKey`.
-Diagnostics (`slopsmith.midi_input.diagnostics.v1`) carry provider ids, source
-ids/keys/kinds/availability, the selected key, and open-session keys; device
-**labels are redacted** and **no raw MIDI messages** are ever included.
-
-## Split from `midi-control`
-
-The reserved `midi-control` domain is narrowed to **control mappings only**
-(CC/pitchbend/note → action routing) and will consume `midi-input` for device
-access. This spec carves out the device control plane so `midi-control` can stay
-mappings-only (#882).
-
-## Consumers (separate issues)
-
-- `input_setup` onboarding wizard — keys/drums device pick + verify (#876/#877).
-- `piano` / `drums` plugins — consume `midi-input` instead of private
-  `requestMIDIAccess()` (via the sub-flow issues; legacy retired through bridges).
-- note-detection's Web-MIDI provider migrates onto `midi-input` (#881).
-
-## Acceptance
-
-- Owner registers; appears in the Capability Inspector with the commands above.
-- `discover` is the only command that triggers `requestMIDIAccess()`;
-  `inspect`/`list-sources`/`select-source` never prompt.
-- Selection persists across reload by `logicalSourceKey`.
-- Diagnostics contain no device labels or raw MIDI messages.
-- A consumer can `discover` → `select-source` → `open-source` → receive live
-  note-on for the calibration check → `close-source` (session refcount releases).
-
-## Out of scope (follow-ups)
-
-- `midi-control` mapping/routing domain (#882).
-- note-detection provider migration onto `midi-input` (#881).
-- Retiring per-plugin `requestMIDIAccess()` in piano/drums via compatibility
-  bridges (tracked with the sub-flow issues).

specs/013-midi-control-mappings/spec.md

@@ -1,75 +0,0 @@
-# Spec 013 — `midi-control` Mappings Domain (the midi-input/midi-control split)
-
-**Status:** documented future contract (RESERVED — not in the runtime graph) ·
-**Issue:** #882 · **Depends on:** spec 012 (`midi-input`, delivered) · **Base:** `feedback/main`
-
-## Summary
-
-`midi-control` is the planned sibling of `midi-input`: it owns **MIDI control
-mappings** — routing CC / pitchbend / note messages to *semantic actions* (drum
-lane, transport command, effect parameter, etc.) — and **consumes `midi-input`**
-for device access. It does **not** discover, select, or open devices; that is
-`midi-input`'s job (spec 012, delivered).
-
-This spec records the **split** so the boundary is unambiguous and the contract
-is ready for whoever builds the runtime slice. Per project governance
-(`docs/capability-safety-matrix.md`, `docs/capability-roadmap.md`), a future
-domain stays **documentation-only until a PR ships its host workflow, a concrete
-consumer, and tests** — so `midi-control` remains `RESERVED` in
-`static/capabilities.js` `RESERVED_FUTURE_DOMAINS` until then. This spec does not
-register a runtime domain.
-
-## Why split it out
-
-Before `midi-input` existed, "MIDI" meant two conflated concerns: getting bytes
-from a device, and mapping those bytes to actions. The reserved `midi-control`
-entry originally covered both. With `midi-input` delivered as the device control
-plane, `midi-control` is narrowed to **mappings only** — mirroring how
-`audio-input` (devices) is separate from `audio-effects`/`audio-mix` (what you do
-with the signal). Keeping them separate prevents a future god-domain and lets the
-device plane stabilize independently of mapping semantics.
-
-## Boundary (normative)
-
-- **`midi-input` owns:** device discovery (`discover`), source list, selection,
-  open/close sessions, the Web-MIDI permission boundary, redacted device
-  diagnostics. The raw MIDI message stream is delivered to in-page consumers via
-  its session handle.
-- **`midi-control` will own:** named mappings from MIDI events (note / CC /
-  pitchbend, optionally channel-scoped) to semantic actions, mapping persistence,
-  active-mapping selection, and "learn" capture. It **consumes** a `midi-input`
-  session for the live stream; it never calls `requestMIDIAccess` or enumerates
-  devices.
-
-## Proposed contract (for the future implementation slice)
-
-- **Owner:** `core.midi-control` (or a first-party MIDI-control plugin),
-  `multi-provider`, safety `sensitive`.
-- **Commands:** `list-mappings`, `get-mapping`, `set-mapping`, `delete-mapping`,
-  `activate-mapping`, `inspect`.
-- **Mapping shape (sketch):** `{ id, label, trigger: { type: 'note'|'cc'|'pitchbend',
-  number?, channel? }, action: { domain?, command?|actionId, params? } }`.
-- **Learn mode:** open a `midi-input` session, capture the next matching event,
-  and bind it to the pending action (the per-plugin "learn" UIs in drums today
-  are the reference behaviour to generalise).
-- **Diagnostics:** `slopsmith.midi_control.diagnostics.v1` — mapping summaries +
-  bounded recent activations; **no raw MIDI streams, no device labels**.
-
-## Intended consumers (promotion trigger)
-
-The domain should be promoted out of RESERVED when a concrete consumer needs
-shared mappings, e.g.:
-- the generic **MIDI control plugin** (`feedback-plugin-midi`) — today an ad-hoc
-  event→action mapper; the canonical first adopter.
-- **drums** note→lane mapping + "learn mode" (`feedback-plugin-drums`,
-  `feedback-plugin-drum-highway-3d`) — currently per-plugin; could adopt
-  `midi-control` to share mapping logic once the contract is proven.
-
-Until such a consumer-driven slice exists (with host workflow + tests), this
-remains a documented contract only.
-
-## Out of scope
-
-- Any runtime registration / handlers (governance: no premature domain).
-- Migrating the drums/keys per-plugin mapping now — deferred to the consumer slice.
-- The device plane — owned by `midi-input` (spec 012, done).

static/capabilities.js

@@ -79,19 +79,6 @@
     const MAX_DECISIONS = 100;
     const MAX_SNAPSHOT_BYTES = 64 * 1024;
     const DEFAULT_HANDLER_TIMEOUT_MS = 250;
-    // Per-(capability, command) handler-timeout overrides. A few commands front a
-    // user-action / OS-permission prompt (fader reads that await a UI; MIDI/mic
-    // device access) that legitimately runs far longer than the default budget,
-    // so the dispatch/command surface must not fail them at 250 ms while the
-    // operation is still completing through the provider.
-    const COMMAND_TIMEOUTS_MS = {
-        'audio-mix': { 'get-fader-value': 2100, 'set-fader-value': 2100 },
-        'midi-input': { 'discover': 15000, 'open-source': 15000 },
-    };
-    function _commandTimeoutFor(capability, commandName) {
-        const byCap = COMMAND_TIMEOUTS_MS[capability];
-        return byCap ? byCap[commandName] : undefined;
-    }
     const RESERVED_FUTURE_DOMAINS = new Set([
         'ui.navigation',
         'ui.plugin-screens',
@@ -816,18 +803,15 @@
     }
 
     function _withTimeout(promise, timeoutMs, participant) {
-        // Capture + clear the timer once the race settles — otherwise a handler
-        // that resolves first leaves a live setTimeout (up to timeoutMs) that
-        // keeps the event loop alive and, for long overrides (MIDI permission
-        // commands at 15s), accumulates delayed callbacks across repeated calls.
-        let timer;
-        const timeout = new Promise(resolve => {
-            timer = setTimeout(() => resolve({
-                outcome: 'failed',
-                reason: `Handler ${participant.pluginId} timed out after ${timeoutMs} ms`,
-            }), timeoutMs);
-        });
-        return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+        return Promise.race([
+            promise,
+            new Promise(resolve => {
+                setTimeout(() => resolve({
+                    outcome: 'failed',
+                    reason: `Handler ${participant.pluginId} timed out after ${timeoutMs} ms`,
+                }), timeoutMs);
+            }),
+        ]);
     }
 
     function _normalizeDecision(participant, result) {
@@ -976,7 +960,7 @@
             if (typeof handler !== 'function') continue;
             let decision;
             try {
-                const timeoutMs = Number(commandContext.timeoutMs || _commandTimeoutFor(capabilityName, commandName) || DEFAULT_HANDLER_TIMEOUT_MS);
+                const timeoutMs = Number(commandContext.timeoutMs || DEFAULT_HANDLER_TIMEOUT_MS);
                 const result = await _withTimeout(Promise.resolve(handler(commandContext)), timeoutMs, participant);
                 decision = _normalizeDecision(participant, result);
             } catch (err) {
@@ -1392,7 +1376,7 @@
             target: source.target || source.args?.target || null,
             payload: source.args || source.payload || {},
             claim: source.claim,
-            timeoutMs: source.timeoutMs || _commandTimeoutFor(capability, commandName),
+            timeoutMs: source.timeoutMs || (capability === 'audio-mix' && (commandName === 'get-fader-value' || commandName === 'set-fader-value') ? 2100 : undefined),
         });
         const status = _dispatchStatus(result);
         _emitEvent(capability, 'dispatched', { command: commandName, status, result, source: source.source || source.requester || 'dispatch' });

static/capabilities/midi-input.js

@@ -1,408 +0,0 @@
-// Core MIDI-input capability domain (spec 012 control plane).
-//
-// The MIDI analog of `audio-input`: a core-owned provider-coordinator over MIDI
-// device discovery, selection, and open/close session lifecycle. It is NOT
-// owned by any feature plugin (an input plane outlives any feature, exactly as
-// `audio-input` is `core.audio.session`-owned), and it is deliberately separate
-// from `audio-input` (whose source/open contract is audio-frame-centric:
-// channel shapes, sample buffers) — MIDI carries discrete messages, not audio.
-//
-// Consumers (the input_setup wizard, the piano/keys and drums plugins, and —
-// later — note-detection's Web-MIDI provider) converge on ONE device-access
-// boundary here: one permission prompt, one source list, one redaction
-// boundary, replacing private per-plugin `navigator.requestMIDIAccess()` calls.
-//
-// Web-MIDI nuance vs audio: `requestMIDIAccess()` gates the whole input LIST, so
-// `discover` (not `open-source`) is the permission boundary for MIDI. `inspect`
-// / `list-sources` / `select-source` stay prompt-free and never request access.
-//
-// Live message delivery (needed by the "play a note / hit a pad" calibration
-// check) is exposed to in-page consumers through the public global's session
-// handle, never as raw capability events or diagnostics.
-(function () {
-    'use strict';
-
-    window.slopsmith = window.slopsmith || {};
-    const capabilities = window.slopsmith.capabilities;
-    if (!capabilities || capabilities.version !== 1) return;
-    if (window.slopsmith.midiInput && window.slopsmith.midiInput.version === 1) return;
-
-    const STORAGE_KEY = 'slopsmith.midiInput.selectedLogicalSourceKey';
-
-    // providerId → { id, label, participantId, handlers:{ enumerate, open, close } }
-    // handlers are LIVE functions supplied in-page via the public global; they
-    // never travel through the capability `command` payload.
-    const providers = new Map();
-    // logicalSourceKey → { sourceId, providerId, logicalSourceKey, kind, label, availability }
-    const sources = new Map();
-    // logicalSourceKey → { refs:Set<requester>, handle } — one shared open
-    // session per source; the provider is closed only after the last release.
-    const sessions = new Map();
-    // logicalSourceKey → Promise — in-flight provider.open() calls, so concurrent
-    // opens for the same source coalesce onto one provider session instead of each
-    // calling provider.open() (which, for Web-MIDI, would overwrite the shared
-    // input.onmidimessage handler and orphan the earlier session/handle).
-    const opening = new Map();
-    let selectedKey = _readStorage();
-    let lastOutcome = null;
-
-    // ── outcome helpers (mirror note-detection.js) ──────────────────────────
-    function _handled(payload = {}) { lastOutcome = { outcome: 'handled' }; return { outcome: 'handled', payload }; }
-    function _degraded(reason, payload = {}) { lastOutcome = { outcome: 'degraded', reason }; return { outcome: 'degraded', reason, payload }; }
-    function _denied(reason, payload = {}) { lastOutcome = { outcome: 'denied', reason }; return { outcome: 'denied', reason, payload }; }
-    function _unavailable(reason, payload = {}) { lastOutcome = { outcome: 'unavailable', reason }; return { outcome: 'unavailable', reason, payload }; }
-
-    function _emit(name, detail) {
-        try { capabilities.emitEvent('midi-input', name, detail || {}); }
-        catch (_) { /* eventing must not break input */ }
-    }
-
-    function _readStorage() {
-        try { return window.localStorage.getItem(STORAGE_KEY) || null; }
-        catch (_) { return null; }
-    }
-    function _writeStorage(key) {
-        try { if (key) window.localStorage.setItem(STORAGE_KEY, key); else window.localStorage.removeItem(STORAGE_KEY); return true; }
-        catch (_) { return false; }
-    }
-
-    function _str(v, fallback) { const s = (v == null ? '' : String(v)).trim(); return s || fallback; }
-
-    // A stable, redaction-safe key for persistence: provider + a stable source
-    // id, NOT the human device label.
-    function _logicalKey(providerId, sourceId) { return `${providerId}::${sourceId}`; }
-
-    // ── snapshots ───────────────────────────────────────────────────────────
-    // listShape keeps labels (this feeds the picker UI); diagShape strips them
-    // (device labels are PII-adjacent).
-    function _sourceListShape() {
-        return Array.from(sources.values()).map((s) => ({
-            logicalSourceKey: s.logicalSourceKey,
-            sourceId: s.sourceId,
-            providerId: s.providerId,
-            kind: s.kind,
-            label: s.label,
-            availability: s.availability,
-            selected: s.logicalSourceKey === selectedKey,
-            open: sessions.has(s.logicalSourceKey),
-        }));
-    }
-
-    function _snapshot(extra = {}) {
-        return {
-            available: providers.size > 0,
-            providers: Array.from(providers.values()).map((p) => ({ id: p.id, label: p.label })),
-            sources: _sourceListShape(),
-            selected: selectedKey,
-            openSessions: Array.from(sessions.keys()),
-            lastOutcome: lastOutcome ? { ...lastOutcome } : null,
-            ...extra,
-        };
-    }
-
-    function _contributeDiagnostics() {
-        const diagnostics = window.slopsmith && window.slopsmith.diagnostics;
-        if (!diagnostics || typeof diagnostics.contribute !== 'function') return;
-        try {
-            const snap = _snapshot();
-            // Redact device labels everywhere — keep ids/kind/availability for
-            // operational observability only. No raw MIDI messages ever.
-            const redacted = {
-                ...snap,
-                providers: snap.providers.map(({ label: _l, ...safe }) => safe),
-                sources: snap.sources.map(({ label: _l, ...safe }) => safe),
-            };
-            diagnostics.contribute('midi-input-capability', {
-                schema: 'slopsmith.midi_input.diagnostics.v1',
-                ...redacted,
-            });
-        } catch (_) { /* diagnostics must not break input */ }
-    }
-
-    // ── provider registry (live handlers via the public global) ─────────────
-    function _registerProvider(input = {}) {
-        const providerId = _str(input.providerId || input.id, '');
-        if (!providerId) return null;
-        const handlers = {
-            enumerate: typeof input.enumerate === 'function' ? input.enumerate : null,
-            open: typeof input.open === 'function' ? input.open : null,
-            close: typeof input.close === 'function' ? input.close : null,
-        };
-        const participantId = _str(input.participantId, providerId);
-        const wasAvailable = providers.size > 0;
-        providers.set(providerId, { id: providerId, label: _str(input.label, providerId), participantId, handlers });
-        // Mirror a serializable declaration into the capability graph so the
-        // Inspector/diagnostics can reason about the provider relationship.
-        try {
-            capabilities.registerParticipant(participantId, {
-                'midi-input': {
-                    roles: ['provider'],
-                    operations: ['source.enumerate', 'source.describe', 'source.open', 'source.close'],
-                    mode: 'active',
-                    safety: 'sensitive',
-                    runtime: true,
-                    description: `MIDI input provider ${_str(input.label, providerId)}.`,
-                    provider_policy: { providerId },
-                },
-            });
-        } catch (_) { /* declaration is best-effort */ }
-        _emit('provider-registered', { providerId });
-        if (!wasAvailable) _emit('availability-changed', { available: true });
-        _contributeDiagnostics();
-        return { providerId };
-    }
-
-    function _unregisterProvider(providerId) {
-        providerId = _str(providerId, '');
-        const provider = providers.get(providerId);
-        if (!provider) return false;
-        // Drop the provider's sources + any open sessions.
-        for (const [key, s] of Array.from(sources.entries())) {
-            if (s.providerId === providerId) {
-                _closeSessionInternal(key, 'provider-unregistered');
-                sources.delete(key);
-            }
-        }
-        providers.delete(providerId);
-        if (typeof capabilities.unregisterParticipant === 'function') {
-            try { capabilities.unregisterParticipant(provider.participantId, 'midi-input'); } catch (_) { /* best-effort */ }
-        }
-        _emit('provider-unregistered', { providerId });
-        if (providers.size === 0) _emit('availability-changed', { available: false });
-        _contributeDiagnostics();
-        return true;
-    }
-
-    // ── discovery (the Web-MIDI permission boundary) ────────────────────────
-    async function _discover() {
-        if (providers.size === 0) return _unavailable('No MIDI provider registered', _snapshot());
-        let found = 0;
-        for (const provider of providers.values()) {
-            if (!provider.handlers.enumerate) continue;
-            let list;
-            try { list = await provider.handlers.enumerate(); }
-            catch (e) {
-                // requestMIDIAccess rejection = permission denied / unsupported.
-                return _denied(_str(e && e.message, 'MIDI access denied'), _snapshot());
-            }
-            const fresh = new Set();
-            for (const raw of (Array.isArray(list) ? list : [])) {
-                const sourceId = _str(raw.sourceId || raw.id, '');
-                if (!sourceId) continue;
-                const key = _logicalKey(provider.id, sourceId);
-                fresh.add(key);
-                sources.set(key, {
-                    sourceId,
-                    providerId: provider.id,
-                    logicalSourceKey: key,
-                    kind: 'midi',
-                    label: _str(raw.label || raw.name, 'MIDI input'),
-                    availability: _str(raw.availability, 'available'),
-                });
-                found += 1;
-            }
-            // Reconcile: drop this provider's sources that vanished since the
-            // last enumeration (e.g. a device unplugged, firing statechange).
-            // Without this, list-sources keeps showing disconnected devices and
-            // selecting/opening them later fails on stale state.
-            for (const [key, s] of Array.from(sources.entries())) {
-                if (s.providerId === provider.id && !fresh.has(key)) {
-                    // Close any live session but KEEP the selectedKey preference
-                    // — the device may be replugged and should re-select.
-                    _closeSessionInternal(key, 'device-removed');
-                    sources.delete(key);
-                }
-            }
-        }
-        // Restore a previously-selected source if it reappeared.
-        if (selectedKey && !sources.has(selectedKey)) { /* keep the preference; it may return later */ }
-        _emit('sources-changed', { count: found });
-        _contributeDiagnostics();
-        return _handled(_snapshot({ discovered: found }));
-    }
-
-    function _selectSource(ctx = {}) {
-        const payload = ctx.payload || {};
-        const key = _str(payload.logicalSourceKey, '');
-        if (!key) return _degraded('select-source requires a logicalSourceKey', _snapshot());
-        if (!sources.has(key)) return _degraded(`Unknown MIDI source: ${key}`, _snapshot());
-        selectedKey = key;
-        _writeStorage(key);
-        _emit('source-selected', { logicalSourceKey: key });
-        _contributeDiagnostics();
-        return _handled(_snapshot({ selected: key }));
-    }
-
-    async function _openSource(ctx = {}) {
-        const payload = ctx.payload || {};
-        const requester = _str(ctx.source || ctx.requester || payload.requester, 'unknown');
-        const key = _str(payload.logicalSourceKey, selectedKey || '');
-        if (!key) return _degraded('No MIDI source selected', _snapshot());
-        const source = sources.get(key);
-        if (!source) return _degraded(`Unknown MIDI source: ${key}`, _snapshot());
-        const provider = providers.get(source.providerId);
-        if (!provider || !provider.handlers.open) return _unavailable('Provider cannot open MIDI input', _snapshot());
-
-        // Share one open session per source across requesters.
-        let session = sessions.get(key);
-        if (session) {
-            session.refs.add(requester);
-            return _handled(_snapshot({ sessionId: session.sessionId, shared: true }));
-        }
-        // Coalesce concurrent opens for the same source: if a provider.open() is
-        // already in flight for this key, await it and adopt the resulting session
-        // rather than opening the device a second time.
-        if (opening.has(key)) {
-            try { await opening.get(key); } catch (_) { /* fall through to retry below */ }
-            session = sessions.get(key);
-            if (session) {
-                session.refs.add(requester);
-                return _handled(_snapshot({ sessionId: session.sessionId, shared: true }));
-            }
-        }
-        let handle;
-        const openPromise = provider.handlers.open(source.sourceId, { requester });
-        opening.set(key, openPromise);
-        try { handle = await openPromise; }
-        catch (e) { return _denied(_str(e && e.message, 'Could not open MIDI input'), _snapshot()); }
-        finally { if (opening.get(key) === openPromise) opening.delete(key); }
-        // A concurrent open may have won the race while we awaited; adopt its
-        // session and release our redundant handle so we don't orphan a device.
-        const existing = sessions.get(key);
-        if (existing) {
-            if (provider.handlers.close) {
-                try { provider.handlers.close(source.sourceId, handle); } catch (_) { /* best-effort */ }
-            }
-            existing.refs.add(requester);
-            return _handled(_snapshot({ sessionId: existing.sessionId, shared: true }));
-        }
-        session = { sessionId: `mis-${key}`, refs: new Set([requester]), handle };
-        sessions.set(key, session);
-        _emit('source-opened', { logicalSourceKey: key, requester });
-        _contributeDiagnostics();
-        return _handled(_snapshot({ sessionId: session.sessionId }));
-    }
-
-    function _closeSessionInternal(key, reason) {
-        const session = sessions.get(key);
-        if (!session) return;
-        const source = sources.get(key);
-        const provider = source && providers.get(source.providerId);
-        if (provider && provider.handlers.close) {
-            try { provider.handlers.close(source.sourceId, session.handle); } catch (_) { /* best-effort */ }
-        }
-        sessions.delete(key);
-        _emit('source-closed', { logicalSourceKey: key, reason: reason || 'closed' });
-    }
-
-    function _closeSource(ctx = {}) {
-        const payload = ctx.payload || {};
-        const requester = _str(ctx.source || ctx.requester || payload.requester, 'unknown');
-        const key = _str(payload.logicalSourceKey, selectedKey || '');
-        const session = sessions.get(key);
-        if (!session) return _handled(_snapshot({ closed: key, alreadyClosed: true }));
-        session.refs.delete(requester);
-        if (session.refs.size === 0) {
-            _closeSessionInternal(key, 'released');
-            _contributeDiagnostics();
-        }
-        return _handled(_snapshot({ closed: key }));
-    }
-
-    capabilities.registerOwner('midi-input', {
-        pluginId: 'core.midi-input',
-        kind: 'provider-coordinator',
-        safety: 'sensitive',
-        commands: [
-            'inspect', 'list-sources', 'discover',
-            'select-source', 'open-source', 'close-source',
-        ],
-        operations: ['source.enumerate', 'source.describe', 'source.open', 'source.close'],
-        events: [
-            'provider-registered', 'provider-unregistered', 'availability-changed',
-            'sources-changed', 'source-selected', 'source-opened', 'source-closed',
-        ],
-        description: 'Core-owned MIDI device control plane: discovery, selection, and shared open/close sessions. `discover` is the Web-MIDI permission boundary.',
-        handlers: {
-            inspect: () => _handled(_snapshot()),
-            'list-sources': () => _handled(_snapshot()),       // prompt-free; never requests access
-            discover: (ctx) => _discover(ctx),                 // permission boundary
-            'select-source': (ctx) => _selectSource(ctx),      // prompt-free
-            'open-source': (ctx) => _openSource(ctx),
-            'close-source': (ctx) => _closeSource(ctx),
-        },
-    });
-
-    // ── public global (live surface for in-page consumers) ──────────────────
-    // Providers register live handlers here; consumers (input_setup, piano,
-    // drums) get a live session handle for the "play a note" check.
-    window.slopsmith.midiInput = {
-        version: 1,
-        snapshot: _snapshot,
-        listSources: () => _sourceListShape(),
-        getSelected: () => selectedKey,
-        registerProvider: _registerProvider,
-        unregisterProvider: _unregisterProvider,
-        discover: () => _discover(),
-        select: (logicalSourceKey) => _selectSource({ payload: { logicalSourceKey } }),
-        // Returns { outcome, sessionId, handle } where handle is the provider's
-        // live MIDI input wrapper (exposes addListener/removeListener). The live
-        // handle is surfaced ONLY through this in-page global, never through the
-        // serializable `open-source` command payload. Use for calibration
-        // note/pad checks.
-        open: async (opts = {}) => {
-            const result = await _openSource({ source: opts.requester || 'in-page', payload: opts });
-            const key = _str(opts.logicalSourceKey, selectedKey || '');
-            const session = sessions.get(key);
-            return { ...result, handle: session ? session.handle : null, sessionId: session ? session.sessionId : null };
-        },
-        close: (opts = {}) => _closeSource({ source: opts.requester || 'in-page', payload: opts }),
-    };
-
-    // ── built-in Web-MIDI provider ──────────────────────────────────────────
-    // Ship a default Web-MIDI source provider so every consumer (piano, drums,
-    // input_setup, …) gets MIDI devices from the domain without any one plugin
-    // having to register the provider. Guarded by Web-MIDI support;
-    // requestMIDIAccess() is the permission boundary, called lazily on discover.
-    (function _registerBuiltinWebMidiProvider() {
-        if (typeof navigator === 'undefined' || typeof navigator.requestMIDIAccess !== 'function') return;
-        const BLOCK = /(midi through|thru|iac)/i;   // loopback / passthrough ports
-        let access = null;
-        _registerProvider({
-            providerId: 'web-midi',
-            label: 'Web MIDI',
-            // Distinct from the domain owner's participant id ('core.midi-input').
-            // unregisterProvider() unregisters the provider's participant, so
-            // sharing the owner's id would tear the whole domain's owner down on
-            // a provider swap/hot-reload, leaving midi-input with no owner.
-            participantId: 'core.midi-input.web-midi',
-            enumerate: async () => {
-                access = await navigator.requestMIDIAccess({ sysex: false });
-                try { access.onstatechange = () => { _discover(); }; } catch (_) { /* best-effort */ }
-                const out = [];
-                access.inputs.forEach((input) => {
-                    if (BLOCK.test(input.name || '')) return;
-                    out.push({ sourceId: input.id, label: input.name || 'MIDI input', availability: 'available' });
-                });
-                return out;
-            },
-            open: async (sourceId) => {
-                if (!access) access = await navigator.requestMIDIAccess({ sysex: false });
-                const input = access.inputs.get(sourceId);
-                if (!input) throw new Error('MIDI input not found');
-                const listeners = new Set();
-                input.onmidimessage = (e) => { listeners.forEach((fn) => { try { fn(e.data); } catch (_) { /* listener isolation */ } }); };
-                return {
-                    addListener: (fn) => { if (typeof fn === 'function') listeners.add(fn); },
-                    removeListener: (fn) => listeners.delete(fn),
-                    _input: input,
-                };
-            },
-            close: (sourceId, handle) => {
-                if (handle && handle._input) { try { handle._input.onmidimessage = null; } catch (_) { /* best-effort */ } }
-            },
-        });
-    })();
-
-    _contributeDiagnostics();
-})();

static/index.html

@@ -31,7 +31,6 @@
     <script src="/static/capabilities/library-card-actions.js"></script>
     <script src="/static/capabilities/visualization.js"></script>
     <script src="/static/capabilities/note-detection.js"></script>
-    <script src="/static/capabilities/midi-input.js"></script>
 </head>
 <body class="bg-dark-900 text-gray-200 font-display">
 

static/tour-engine.css

@@ -1,9 +1,7 @@
 /* ── Consolidated tour menu — one floating button + popover for all tours ── */
-/* Palette aligned with the v3 fee[dB]ack design tokens (tailwind.config.js):
-   fb-card #1e293b surfaces, fb-cardMuted #0b1220 wells, fb-primary #0ea5e9
-   accent, fb-border #334155 hairlines, fb-text #f8fafc / fb-textDim #94a3b8
-   text, fb-gold #e8c040 badge. Plain CSS (no Tailwind classes) so it needs no
-   stylesheet rebuild. Per CLAUDE.md → Frontend Conventions. */
+/* Palette aligned with the app's dark theme: #4080e0 accent, #e8c040 gold,
+   #181830 dark background, #cbd5e1 / #94a3b8 / #64748b text scale. Per
+   CLAUDE.md → Frontend Conventions. */
 
 .slopsmith-tour-menu-btn {
     position: fixed;
@@ -16,20 +14,20 @@
     width: 32px;
     height: 32px;
     border-radius: 50%;
-    background: #1e293b;
-    border: 1.5px solid #0ea5e9;
-    color: #f8fafc;
+    background: #181830;
+    border: 1.5px solid #4080e0;
+    color: #cbd5e1;
     font-size: 15px;
     font-weight: bold;
     cursor: pointer;
-    box-shadow: 0 0 6px #0ea5e966;
+    box-shadow: 0 0 6px #4080e066;
     display: flex;
     align-items: center;
     justify-content: center;
     transition: box-shadow 0.2s, transform 0.15s;
 }
 .slopsmith-tour-menu-btn:hover {
-    box-shadow: 0 0 12px #0ea5e9aa;
+    box-shadow: 0 0 12px #4080e0aa;
     transform: translateY(-1px);
 }
 .slopsmith-tour-menu-btn.has-unseen {
@@ -43,12 +41,12 @@
     width: 10px;
     height: 10px;
     background: #e8c040;
-    border: 2px solid #1e293b;
+    border: 2px solid #181830;
     border-radius: 50%;
 }
 @keyframes tour-pulse {
-    0%, 100% { box-shadow: 0 0 6px #0ea5e966; }
-    50% { box-shadow: 0 0 16px #0ea5e9cc; }
+    0%, 100% { box-shadow: 0 0 6px #4080e066; }
+    50% { box-shadow: 0 0 16px #4080e0cc; }
 }
 
 .slopsmith-tour-menu-popover {
@@ -64,12 +62,12 @@
        room for the trigger button + its bottom inset. */
     max-height: calc(100vh - 80px);
     overflow-y: auto;
-    background: #1e293b;
-    border: 1px solid #0ea5e944;
+    background: #181830;
+    border: 1px solid #4080e044;
     border-radius: 8px;
     padding: 6px;
     font-size: 13px;
-    color: #f8fafc;
+    color: #cbd5e1;
     box-shadow: 0 4px 16px rgba(0, 0, 0, 0.5);
 }
 .slopsmith-tour-menu-popover .tour-menu-header {
@@ -77,13 +75,13 @@
     font-size: 11px;
     text-transform: uppercase;
     letter-spacing: 0.08em;
-    color: #94a3b8;
-    border-bottom: 1px solid #334155;
+    color: #64748b;
+    border-bottom: 1px solid #1e1e3a;
     margin-bottom: 4px;
 }
 .slopsmith-tour-menu-popover .tour-menu-empty {
     padding: 10px;
-    color: #94a3b8;
+    color: #64748b;
     font-style: italic;
     text-align: center;
 }
@@ -97,23 +95,23 @@
     background: transparent;
     border: none;
     border-radius: 4px;
-    color: #f8fafc;
+    color: #cbd5e1;
     font-size: 13px;
     text-align: left;
     cursor: pointer;
     transition: background 0.12s;
 }
 .slopsmith-tour-menu-popover .tour-menu-item:hover {
-    background: #334155;
-    color: #f8fafc;
+    background: #1a1a30;
+    color: #fff;
 }
 /* Keyboard focus gets an explicit ring instead of relying on the hover
    background — matches the :focus-visible treatment elsewhere in the
    app (style.css). Pointer focus is left alone. */
 .slopsmith-tour-menu-popover .tour-menu-item:focus-visible {
-    background: #334155;
-    color: #f8fafc;
-    outline: 2px solid #0ea5e9;
+    background: #1a1a30;
+    color: #fff;
+    outline: 2px solid #4080e0;
     outline-offset: -2px;
 }
 .slopsmith-tour-menu-popover .tour-menu-item-label {
@@ -129,11 +127,11 @@
 }
 .slopsmith-tour-menu-popover .tour-menu-item-status.is-new {
     background: #e8c040;
-    color: #0f172a;
+    color: #181830;
 }
 .slopsmith-tour-menu-popover .tour-menu-item-status.is-seen {
-    background: #0b1220;
-    color: #94a3b8;
+    background: #1e1e3a;
+    color: #64748b;
 }
 
 /* ── First-visit toast — anchored above the menu button ── */
@@ -143,12 +141,12 @@
     bottom: 56px;
     right: 12px;
     z-index: 202;
-    background: #1e293b;
-    border: 1px solid #0ea5e944;
+    background: #181830;
+    border: 1px solid #4080e044;
     border-radius: 8px;
     padding: 10px 14px;
     font-size: 13px;
-    color: #f8fafc;
+    color: #cbd5e1;
     max-width: 240px;
     line-height: 1.4;
     box-shadow: 0 4px 16px rgba(0, 0, 0, 0.5);
@@ -161,7 +159,7 @@
 .slopsmith-tour-prompt .tour-prompt-more {
     margin-top: 4px;
     font-size: 11px;
-    color: #94a3b8;
+    color: #64748b;
 }
 .slopsmith-tour-prompt .tour-prompt-buttons {
     display: flex;
@@ -180,92 +178,11 @@
     opacity: 0.85;
 }
 .slopsmith-tour-prompt button[data-action="start"] {
-    background: #0ea5e9;
+    background: #4080e0;
     color: #fff;
     font-weight: 600;
 }
 .slopsmith-tour-prompt button[data-action="dismiss"] {
-    background: #334155;
+    background: #1e1e3a;
     color: #94a3b8;
 }
-
-/* ── Shepherd bubble theme — override the vendored light default ──────────── */
-/* The vendored static/vendor/shepherd.css ships Shepherd's stock LIGHT theme
-   (white bubble, black text, blue buttons), which clashes with the dark v3 UI.
-   These overrides load after it (index.html order) and recolor the spotlight
-   bubbles to the fb-* tokens. The vendored file is left untouched so it stays
-   upgradable. */
-.shepherd-element {
-    background: #1e293b;
-    border: 1px solid #334155;
-    border-radius: 10px;
-    box-shadow: 0 8px 28px rgba(0, 0, 0, 0.55);
-    max-width: 360px;
-}
-.shepherd-content {
-    background: #1e293b;
-    border-radius: 10px;
-}
-.shepherd-text {
-    color: #cbd5e1;
-    font-size: 0.9rem;
-    line-height: 1.45;
-    padding: 0.85em 0.9em;
-}
-.shepherd-title {
-    color: #f8fafc;
-    font-size: 0.95rem;
-    font-weight: 700;
-}
-/* Title row: drop the light-grey header fill the stock theme paints behind a
-   titled step, so the header blends into the card. */
-.shepherd-has-title .shepherd-content .shepherd-header {
-    background: transparent;
-    padding: 0.85em 0.9em 0;
-}
-/* Arrow must match the bubble surface (stock paints it white, and grey behind
-   a bottom-placed titled step). */
-.shepherd-arrow:before {
-    background: #1e293b;
-}
-.shepherd-element.shepherd-has-title[data-popper-placement^="bottom"] > .shepherd-arrow:before {
-    background-color: #1e293b;
-}
-.shepherd-footer {
-    padding: 0 0.75rem 0.75rem;
-}
-/* Primary button (Next / Done) → fb-primary. */
-.shepherd-button {
-    background: #0ea5e9;
-    color: #fff;
-    border-radius: 6px;
-    font-weight: 600;
-    padding: 0.4rem 1.1rem;
-}
-.shepherd-button:not(:disabled):hover {
-    background: #38bdf8;
-    color: #fff;
-}
-/* Secondary button (Back / Skip) → muted slate. */
-.shepherd-button.shepherd-button-secondary {
-    background: #334155;
-    color: #f8fafc;
-}
-.shepherd-button.shepherd-button-secondary:not(:disabled):hover {
-    background: #475569;
-    color: #f8fafc;
-}
-.shepherd-cancel-icon {
-    color: #94a3b8;
-}
-.shepherd-cancel-icon:hover,
-.shepherd-has-title .shepherd-content .shepherd-cancel-icon:hover {
-    color: #f8fafc;
-}
-.shepherd-has-title .shepherd-content .shepherd-cancel-icon {
-    color: #94a3b8;
-}
-/* Dim the page a touch more, matching the onboarding overlay (bg-black/60). */
-.shepherd-modal-overlay-container.shepherd-modal-is-visible {
-    opacity: 0.6;
-}

static/tour-engine.js

@@ -127,13 +127,7 @@
     }
 
     function _unseenRelevant(screenId) {
-        // Drives the toast prompt + button "has-unseen" pulse. A tour registered
-        // with autoPrompt:false is excluded — it's started programmatically by
-        // its owner (e.g. the first-run home tour), so nagging via toast/pulse
-        // would double up. It still lists in the menu and runs on demand.
-        return _relevantPlugins(screenId).filter(p =>
-            !hasSeen(p.id) && !hasDismissed(p.id) &&
-            (_registry[p.id] ? _registry[p.id].autoPrompt !== false : true));
+        return _relevantPlugins(screenId).filter(p => !hasSeen(p.id) && !hasDismissed(p.id));
     }
 
     // ── Menu UI ────────────────────────────────────────────────────────────
@@ -621,24 +615,7 @@
             onStart: opts.onStart || null,
             onComplete: opts.onComplete || null,
             screens: Array.isArray(opts.screens) ? opts.screens.slice() : null,
-            // autoPrompt:false opts the tour OUT of the unseen toast + button
-            // pulse (it's driven programmatically by its owner, e.g. the
-            // first-run home tour started from onboarding). It still lists in the
-            // menu and runs via start(). Defaults to the legacy always-prompt.
-            autoPrompt: opts.autoPrompt !== false,
         };
-        // A `name` registers a CLIENT/CORE-owned tour — one that isn't a
-        // server-discovered plugin with a tour.json — into the consolidated menu
-        // catalog so it appears in the "?" menu. Never clobber a richer entry the
-        // /api/plugins pass already supplied for a real plugin of the same id.
-        if (opts.name && !_tourPlugins[pluginId]) {
-            _tourPlugins[pluginId] = {
-                id: pluginId,
-                name: opts.name,
-                has_screen: true,
-                is_viz: false,
-            };
-        }
         // If the override changes the relevance for the current screen, refresh.
         _updateMenuVisibility();
     }

static/v3/badges.js

@@ -291,7 +291,7 @@
         const host = document.getElementById('v3-badge-instrument');
         if (!host) return;
         host.innerHTML =
-            '<div id="v3-instrument-wrap" class="relative">' +
+            '<div class="relative">' +
             '<button type="button" data-inst-toggle title="Instrument: ' + esc(settings.string_count + '-str ' + tuningLabel()) + '" ' +
             'class="bg-fb-card border border-fb-border/50 rounded-2xl h-[92px] w-16 flex flex-col items-center justify-center gap-2 hover:ring-1 hover:ring-fb-primary/40 transition">' +
             guitarIcon +

static/v3/dashboard.js

@@ -134,7 +134,7 @@
             const bars = Array.from({ length: segs }, (_, i) =>
                 '<span class="flex-1 h-1.5 rounded-full ' + (i < filled ? 'bg-fb-primary' : 'bg-gray-500/40') + '"></span>').join('');
             continueCard =
-                '<button id="v3-continue" data-tour="continue" class="group relative text-left rounded-xl overflow-hidden border border-fb-border/50 bg-fb-card aspect-square self-start flex flex-col justify-end">' +
+                '<button id="v3-continue" class="group relative text-left rounded-xl overflow-hidden border border-fb-border/50 bg-fb-card aspect-square self-start flex flex-col justify-end">' +
                 songArt(cont.art_url, 'absolute inset-0 w-full h-full object-cover opacity-60 group-hover:opacity-70 transition') +
                 '<div class="absolute inset-0 bg-gradient-to-t from-black/90 via-black/40 to-transparent"></div>' +
                 tuningChip(cont.tuning_name, 'absolute top-3 right-3') +
@@ -146,7 +146,7 @@
                 '<span class="absolute top-3 left-3 text-fb-text/80 group-hover:text-fb-text">▶</span></button>';
         } else if (pick) {
             continueCard =
-                '<button id="v3-pick" data-tour="continue" data-fn="' + esc(pick.filename) + '" class="group relative text-left rounded-xl overflow-hidden border border-fb-border/50 bg-fb-card aspect-square self-start flex flex-col justify-end">' +
+                '<button id="v3-pick" data-fn="' + esc(pick.filename) + '" class="group relative text-left rounded-xl overflow-hidden border border-fb-border/50 bg-fb-card aspect-square self-start flex flex-col justify-end">' +
                 songArt(libArtUrl(pick), 'absolute inset-0 w-full h-full object-cover opacity-60 group-hover:opacity-70 transition') +
                 '<div class="absolute inset-0 bg-gradient-to-t from-black/90 via-black/40 to-transparent"></div>' +
                 tuningChip(pick.tuning_name, 'absolute top-3 right-3') +
@@ -157,7 +157,7 @@
                 '<span class="absolute top-3 left-3 text-fb-text/80 group-hover:text-fb-text">▶</span></button>';
         } else {
             continueCard =
-                '<div data-tour="continue" class="rounded-xl border border-fb-border/50 bg-fb-card/60 aspect-square self-start flex flex-col items-center justify-center text-center p-4">' +
+                '<div class="rounded-xl border border-fb-border/50 bg-fb-card/60 aspect-square self-start flex flex-col items-center justify-center text-center p-4">' +
                 '<div class="text-fb-textDim text-sm mb-3">Pick a song to get started</div>' +
                 '<button id="v3-continue-pick" class="bg-fb-card hover:bg-fb-card/70 border border-fb-border/50 text-fb-text text-sm px-4 py-2 rounded-md">Browse library</button></div>';
         }
@@ -188,7 +188,7 @@
                 '<a href="' + esc(changelogUrl) + '" target="_blank" rel="noopener" class="text-fb-primary hover:text-fb-primaryHi">Patch Notes for ' + esc(ver) + '</a>?</p>' : '') +
             // Featured grid: hero + continue
             '<div class="grid lg:grid-cols-3 gap-6 mt-6">' +
-            '<div id="v3-hero" class="lg:col-span-2 relative rounded-xl overflow-hidden min-h-[480px] flex items-center bg-fb-bg">' +
+            '<div class="lg:col-span-2 relative rounded-xl overflow-hidden min-h-[480px] flex items-center bg-fb-bg">' +
             // Hero artwork (neon note-highway), right-anchored. Placeholder
             // cropped from the design mock — swap static/v3/brand/hero.png for
             // the designer's high-res original (same path) when available.

static/v3/index.html

@@ -94,7 +94,6 @@
     <script src="/static/capabilities/library-card-actions.js"></script>
     <script src="/static/capabilities/visualization.js"></script>
     <script src="/static/capabilities/note-detection.js"></script>
-    <script src="/static/capabilities/midi-input.js"></script>
 </head>
 <body class="h-screen flex overflow-hidden bg-fb-sidebar text-fb-text font-display">
 
@@ -875,10 +874,6 @@
     <script src="/static/v3/songs.js"></script>
     <script src="/static/v3/lessons.js"></script>
     <script src="/static/v3/dashboard.js"></script>
-    <!-- First-run home tour: spotlights the home cards via the shared tour
-         engine (tour-engine.js, loaded above). Auto-runs once after onboarding
-         (triggered from profile.js finish()); replayable from the "?" menu. -->
-    <script src="/static/v3/onboarding-tour.js"></script>
     <script src="/static/v3/feedbarcade.js"></script>
     <script src="/static/v3/player-chrome.js"></script>
     <script>

static/v3/onboarding-tour.js

@@ -1,115 +0,0 @@
-/*
- * fee[dB]ack v0.3.0 — first-run home tour.
- *
- * Registers a spotlight tour over the home-page cards with the shared tour
- * engine (window.slopsmithTour / Shepherd) and auto-runs it once, the first
- * time the user lands on the home page after completing onboarding. It stays
- * replayable forever from the per-screen "?" tour menu (registered with
- * screens: ['v3-home']).
- *
- * Anchors (all stable, on-screen while #v3-home is active):
- *   #v3-hero               hero / Start Playing      (dashboard.js)
- *   [data-tour="continue"] continue / pick a song    (dashboard.js, 3 variants)
- *   #v3-instrument-wrap    instrument selector badge (badges.js, topbar)
- *   #v3-tuner-wrap         tuner badge               (badges.js, topbar)
- *   #v3-audio-routing      audio routing card        (dashboard.js)
- *   [data-v3-open-profile] profile badge             (profile.js, topbar)
- *   #v3-nav                left sidebar navigation    (index.html)
- */
-(function () {
-    'use strict';
-
-    var TOUR_ID = 'home-onboarding';
-
-    // Each step dims the page and spotlights one element (shape: 'spotlight').
-    // waitFor blocks the step until its target exists, so the async dashboard
-    // re-render kicked off by 'v3:profile-updated' can't race the first step.
-    function buildSteps() {
-        return [
-            {
-                id: 'hero', shape: 'spotlight', position: 'bottom',
-                selector: '#v3-hero', waitFor: '#v3-hero',
-                title: 'Welcome to fee[dB]ack',
-                content: 'This is your home base. Hit Start Playing to drop straight into a song from your library.',
-            },
-            {
-                id: 'continue', shape: 'spotlight', position: 'left',
-                selector: '[data-tour="continue"]', waitFor: '[data-tour="continue"]',
-                title: 'Pick up where you left off',
-                content: 'Your last song resumes right here in one click. Before you’ve played anything, it’s a quick random pick to get you going.',
-            },
-            {
-                id: 'instrument', shape: 'spotlight', position: 'bottom',
-                selector: '#v3-instrument-wrap', waitFor: '#v3-instrument-wrap',
-                title: 'Choose your instrument',
-                content: 'Set your instrument, string count and tuning here. The highway, tuner and scoring all adapt to this selection.',
-            },
-            {
-                id: 'tuner', shape: 'spotlight', position: 'bottom',
-                selector: '#v3-tuner-wrap', waitFor: '#v3-tuner-wrap',
-                title: 'Tune up first',
-                content: 'Open the tuner and match each string until the meter centers — accurate tuning means accurate scoring.',
-            },
-            {
-                id: 'audio', shape: 'spotlight', position: 'top',
-                selector: '#v3-audio-routing', waitFor: '#v3-audio-routing',
-                title: 'Your signal path',
-                content: 'Input → amp / NAM / IR → output, at a glance. Set up and monitor your gear from this card.',
-            },
-            {
-                id: 'profile', shape: 'spotlight', position: 'bottom',
-                selector: '[data-v3-open-profile]', waitFor: '[data-v3-open-profile]',
-                title: 'Track your progress',
-                content: 'Your profile, avatar and rank live here. Watch your accuracy climb and level up as you play.',
-            },
-            {
-                id: 'nav', shape: 'spotlight', position: 'right',
-                selector: '#v3-nav', waitFor: '#v3-nav',
-                title: 'Find everything here',
-                content: 'Browse your full library, lessons and plugins anytime. You can replay this tour from the ? button in the corner.',
-            },
-        ];
-    }
-
-    function register() {
-        var t = window.slopsmithTour;
-        if (!t || typeof t.register !== 'function') return false;
-        t.register(TOUR_ID, {
-            name: 'Welcome tour',     // label in the "?" tour menu
-            screens: ['v3-home'],     // relevant only on the home screen
-            autoPrompt: false,        // we auto-run it from onboarding; no toast nag
-            buildSteps: buildSteps,
-        });
-        return true;
-    }
-
-    // Auto-run once after a genuine onboarding completion. profile.js gates the
-    // call on !editing (a profile edit must not relaunch it); we additionally
-    // honour the engine's own seen/dismissed state so it never repeats and a
-    // dismissal isn't nagged. Stays replayable from the "?" menu either way.
-    function startFirstRun() {
-        var t = window.slopsmithTour;
-        if (!t || typeof t.start !== 'function') return;
-        try {
-            if (t.hasSeen(TOUR_ID) || t.hasDismissed(TOUR_ID)) return;
-        } catch (e) { /* private mode — fall through and attempt once */ }
-        // Make sure the home screen is in view so the spotlight targets exist;
-        // the per-step waitFor handles the async dashboard render.
-        if (typeof window.showScreen === 'function') {
-            try { window.showScreen('v3-home'); } catch (e) { /* best-effort */ }
-        }
-        // Defer a frame so the 'v3:profile-updated' dashboard re-render has a
-        // chance to begin before Shepherd starts polling for the first target.
-        var raf = window.requestAnimationFrame || function (fn) { return setTimeout(fn, 16); };
-        raf(function () { try { t.start(TOUR_ID); } catch (e) { /* degrade */ } });
-    }
-
-    window.v3OnboardingTour = { startFirstRun: startFirstRun };
-
-    // tour-engine.js assigns window.slopsmithTour at script-eval time, so if it
-    // is loaded before us register() succeeds immediately; otherwise retry once
-    // the DOM (and the engine) are ready.
-    if (!register()) {
-        document.addEventListener('DOMContentLoaded', register, { once: true });
-    }
-})();

static/v3/profile.js

@@ -153,55 +153,6 @@
     // diagnostic sloppak at 100% — or skip and reach Mastery Rank 1 anyway).
     // The profile POST always lands before the step-3 choice so onboarded=1 is
     // never blocked by the calibration decision. Editing keeps the single form.
-    // Run the input-device setup wizard (the input_setup plugin's
-    // `input-calibration` domain) for the chosen instrument paths — BETWEEN path
-    // selection and the calibration challenge — so the diagnostic runs against a
-    // calibrated input. Capability-idiomatic: dispatch `run` (fire-and-launch)
-    // and await the `calibration-done` event. Degrades gracefully when the
-    // plugin/runtime is absent so onboarding can never be stranded.
-    // Wait (bounded) for the bundled input_setup plugin to finish registering
-    // its input-calibration owner. Plugins load asynchronously, so onboarding
-    // can reach this step before the plugin is ready — without this wait the
-    // mandatory wizard is skipped by a load-order race (it dispatches, gets a
-    // no-owner outcome, and falls through to the calibration challenge). The
-    // public global is set at the end of the plugin's screen.js, after the
-    // owner is registered, so it is a reliable readiness signal.
-    function waitForInputSetup(timeoutMs) {
-        const ready = () => !!(window.slopsmithInputSetup && typeof window.slopsmithInputSetup.launch === 'function');
-        return new Promise((resolve) => {
-            if (ready()) { resolve(true); return; }
-            const t0 = Date.now();
-            const iv = setInterval(() => {
-                if (ready()) { clearInterval(iv); resolve(true); }
-                else if (Date.now() - t0 >= timeoutMs) { clearInterval(iv); resolve(false); }
-            }, 100);
-        });
-    }
-
-    async function runInputSetup(paths) {
-        const instruments = (Array.isArray(paths) ? paths : []).map((p) => String(p).toLowerCase());
-        if (!instruments.length) return;
-        // Don't let a plugin-load race skip the mandatory input-setup step.
-        if (!(await waitForInputSetup(8000))) return;
-        const caps = window.slopsmith && window.slopsmith.capabilities;
-        if (!caps || typeof caps.command !== 'function') {
-            try { await window.slopsmithInputSetup.launch(instruments); } catch (e) { /* proceed */ }
-            return;
-        }
-        await new Promise((resolve) => {
-            let settled = false;
-            let unsub = null;
-            const done = () => { if (settled) return; settled = true; try { unsub && unsub(); } catch (e) { /* noop */ } resolve(); };
-            try { unsub = typeof caps.subscribe === 'function' ? caps.subscribe('input-calibration:calibration-done', done) : null; } catch (e) { unsub = null; }
-            // `run` is fire-and-launch; completion arrives via the event above.
-            // A non-handled outcome (no owner / plugin absent / error) means
-            // nothing was launched, so proceed immediately.
-            caps.command('input-calibration', 'run', { requester: 'onboarding', payload: { instruments } })
-                .then((r) => { if (!r || r.outcome !== 'handled') done(); })
-                .catch(() => done());
-        });
-    }
-
     function show(profile, opts) {
         opts = opts || {};
         const editing = !!opts.editing;
@@ -209,7 +160,7 @@
 
         const stepDots = editing ? '' :
             '<div class="flex justify-center gap-1.5 mt-3" id="v3-ob-dots">' +
-            [1, 2, 3, 4].map((n) => '<span data-dot="' + n + '" class="w-2 h-2 rounded-full bg-fb-border"></span>').join('') +
+            [1, 2, 3].map((n) => '<span data-dot="' + n + '" class="w-2 h-2 rounded-full bg-fb-border"></span>').join('') +
             '</div>';
 
         const overlay = document.createElement('div');
@@ -233,24 +184,15 @@
             '<button type="button" id="v3-ob-upload-btn" class="text-sm text-fb-primary hover:text-fb-primaryHi">Upload your own</button>' +
             '<input type="file" id="v3-ob-upload" accept="image/*" class="hidden">' +
             '<span id="v3-ob-preview"></span></div></div></div>' +
-            // Step 2 — song directory (where the user's songs live).
+            // Step 2 — instrument paths (first-run only; tiles filled on entry).
             '<div id="v3-ob-step2" class="hidden">' +
-            '<label class="block text-xs uppercase tracking-wider text-fb-textDim mb-2">Song directory</label>' +
-            '<p class="text-sm text-fb-textDim mb-3">Choose the folder where your songs are stored. We’ll scan it to build your library. You can change this later in Settings.</p>' +
-            '<div class="flex gap-2">' +
-            '<input id="v3-ob-songdir" type="text" placeholder="Path to your songs folder" ' +
-            'class="flex-1 bg-gray-800/50 border border-gray-700 rounded-md px-3 py-2 text-sm text-fb-text outline-none focus:border-fb-primary focus:ring-1 focus:ring-fb-primary">' +
-            '<button type="button" id="v3-ob-songdir-browse" class="hidden px-3 py-2 rounded-md text-sm bg-gray-800/50 border border-gray-700 text-fb-text hover:border-fb-primary whitespace-nowrap">Browse…</button>' +
-            '</div></div>' +
-            // Step 3 — instrument paths (first-run only; tiles filled on entry).
-            '<div id="v3-ob-step3" class="hidden">' +
             '<label class="block text-xs uppercase tracking-wider text-fb-textDim mb-2">Pick your instrument path(s)</label>' +
             '<p class="text-sm text-fb-textDim mb-3">Each path levels up by completing challenges — together they make up your Mastery Rank. You can add more later.</p>' +
             '<div id="v3-ob-paths" class="grid grid-cols-3 gap-2"></div></div>' +
-            // Step 4 — calibration offer (first-run only).
-            '<div id="v3-ob-step4" class="hidden">' +
+            // Step 3 — calibration offer (first-run only).
+            '<div id="v3-ob-step3" class="hidden">' +
             '<label class="block text-xs uppercase tracking-wider text-fb-textDim mb-2">Calibration challenge</label>' +
-            '<p class="text-sm text-fb-textDim">Prove your setup: play the <span class="text-fb-text">fee[dB]ack Diagnostic</span> with note detection and finish at <span class="text-fb-text font-semibold">100% accuracy</span> to reach <span class="text-fb-text font-semibold">Mastery Rank 1</span>.</p>' +
+            '<p class="text-sm text-fb-textDim">Prove your setup: play the <span class="text-fb-text">Slopsmith Diagnostic</span> with note detection and finish at <span class="text-fb-text font-semibold">100% accuracy</span> to reach <span class="text-fb-text font-semibold">Mastery Rank 1</span>.</p>' +
             '<p class="text-sm text-fb-textDim mt-2">Not ready? Skip it and you’ll start at Rank 1 anyway — you can still play it later from the Progress screen.</p></div>' +
             '<p id="v3-ob-error" class="text-sm text-fb-accent hidden"></p>' +
             '<div class="flex justify-end gap-3">' +
@@ -269,12 +211,9 @@
         const skipBtn = overlay.querySelector('#v3-ob-skip');
         let selected = null;      // { type:'default', value } | { type:'upload', value:url }
         let step = 1;             // first-run wizard step (editing stays on 1)
-        let songDir = '';         // step-2 song directory pick
-        let selectedPaths = [];   // step-3 picks
+        let selectedPaths = [];   // step-2 picks
         let pathsAvailable = false;      // any tiles rendered? (false → don't strand the user)
-        let diagnosticFilename = null;   // from /api/progression (step-4 "Play it now")
-        const songDirEl = overlay.querySelector('#v3-ob-songdir');
-        const songDirBrowse = overlay.querySelector('#v3-ob-songdir-browse');
+        let diagnosticFilename = null;   // from /api/progression (step-3 "Play it now")
 
         if (editing && profile) {
             nameEl.value = profile.display_name || '';
@@ -290,10 +229,6 @@
                 const haveAvatar = !!selected || (editing && profile && !!profile.avatar_url);
                 submit.disabled = !(nameEl.value.trim().length >= 1 && haveAvatar);
             } else if (step === 2) {
-                // Song directory — require a non-empty path to proceed; "Skip
-                // for now" is available for users who'll set it later.
-                submit.disabled = !songDir.trim();
-            } else if (step === 3) {
                 // ≥1 path required — unless none could be offered (offline /
                 // empty content), where blocking would strand onboarding.
                 submit.disabled = pathsAvailable && selectedPaths.length < 1;
@@ -305,7 +240,7 @@
         function setStep(n) {
             step = n;
             errEl.classList.add('hidden');
-            for (let i = 1; i <= 4; i++) {
+            for (let i = 1; i <= 3; i++) {
                 overlay.querySelector('#v3-ob-step' + i).classList.toggle('hidden', i !== n);
             }
             overlay.querySelectorAll('#v3-ob-dots [data-dot]').forEach((d) => {
@@ -315,14 +250,11 @@
             const subtitle = overlay.querySelector('#v3-ob-subtitle');
             if (subtitle) {
                 subtitle.textContent = n === 1 ? 'Set up your player profile'
-                    : n === 2 ? 'Point us at your songs'
-                    : n === 3 ? 'Choose your instrument paths'
+                    : n === 2 ? 'Choose your instrument paths'
                     : 'One last thing — calibrate your setup';
             }
-            submit.textContent = n === 4 ? 'Play it now' : 'Next';
-            // Skip is offered on the song-directory step (configure later) and
-            // the calibration challenge.
-            skipBtn.classList.toggle('hidden', !(n === 2 || n === 4));
+            submit.textContent = n === 3 ? 'Play it now' : 'Next';
+            skipBtn.classList.toggle('hidden', n !== 3);
             refreshSubmit();
         }
 
@@ -415,43 +347,6 @@
 
         if (editing) overlay.querySelector('#v3-ob-cancel')?.addEventListener('click', () => overlay.remove());
 
-        // ── Song directory (step 2) ──────────────────────────────────────────
-        if (songDirEl) {
-            songDirEl.addEventListener('input', () => { songDir = songDirEl.value.trim(); refreshSubmit(); });
-        }
-        // Native folder picker on desktop; web users type/paste the path.
-        const _desktop = window.slopsmithDesktop;
-        if (songDirBrowse && _desktop && typeof _desktop.pickDirectory === 'function') {
-            songDirBrowse.classList.remove('hidden');
-            songDirBrowse.addEventListener('click', async () => {
-                try {
-                    const picked = await _desktop.pickDirectory();
-                    if (picked) { songDirEl.value = picked; songDir = picked; refreshSubmit(); }
-                } catch (e) { /* user cancelled / unavailable */ }
-            });
-        }
-        // Save the song directory to settings + kick a library scan so the
-        // user's songs appear. Throws (with a message) on an invalid folder.
-        async function saveSongDir() {
-            const dir = ((songDirEl && songDirEl.value) || '').trim();
-            if (!dir) return;   // skipped — leave unconfigured (settable later)
-            const res = await fetch('/api/settings', {
-                method: 'POST', headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ dlc_dir: dir }),
-            });
-            // /api/settings reports an invalid folder as a 200 with an `error`
-            // field (a bare dict return, not a non-2xx status), so a res.ok-only
-            // check would treat the failure as success and advance without saving.
-            // Inspect the body too.
-            let data = null;
-            try { data = await res.json(); } catch (e) { /* non-JSON body */ }
-            if (!res.ok || (data && data.error)) {
-                throw new Error((data && data.error) || 'That folder couldn’t be set — check the path and try again.');
-            }
-            // Non-fatal: scan kicks off the library build in the background.
-            try { await fetch('/api/rescan', { method: 'POST' }); } catch (e) { /* best-effort */ }
-        }
-
         async function postProfile() {
             const res = await fetch('/api/profile', {
                 method: 'POST', headers: { 'Content-Type': 'application/json' },
@@ -462,8 +357,7 @@
             return body;
         }
 
-        async function finish(finishOpts) {
-            finishOpts = finishOpts || {};
+        async function finish() {
             overlay.remove();
             await fetchProgress();
             if (window.v3Progression && typeof window.v3Progression.refresh === 'function') {
@@ -472,16 +366,6 @@
             renderBadge();
             renderProfileScreen();
             if (window.slopsmith && window.slopsmith.emit) window.slopsmith.emit('v3:profile-updated', _profile);
-            // First-run only: after a genuine onboarding completion (not a
-            // profile edit), kick off the one-time home tour — but NOT when we're
-            // about to launch the diagnostic ("Play it now"), which navigates to
-            // the player; the tour would otherwise spotlight hidden home elements
-            // and steal focus. The Skip path stays on home, so it runs there.
-            // The engine's seen/dismissed state keeps it once; replayable from "?".
-            if (!editing && !finishOpts.launchingSong &&
-                window.v3OnboardingTour && typeof window.v3OnboardingTour.startFirstRun === 'function') {
-                try { window.v3OnboardingTour.startFirstRun(); } catch (e) { /* never block onboarding */ }
-            }
         }
 
         submit.addEventListener('click', async () => {
@@ -496,23 +380,12 @@
             }
             if (step === 1) {
                 setStep(2);
-                setTimeout(() => { try { songDirEl && songDirEl.focus(); } catch (e) { /* noop */ } }, 50);
+                loadPathTiles();
                 return;
             }
             if (step === 2) {
-                // Save the song directory + kick a library scan, then continue
-                // to instrument paths. "Skip for now" leaves it unconfigured.
-                submit.disabled = true;
-                try {
-                    await saveSongDir();
-                    setStep(3);
-                    loadPathTiles();
-                } catch (e) { showErr(e.message || 'Could not set the song directory.'); refreshSubmit(); }
-                return;
-            }
-            if (step === 3) {
                 // Create the profile (onboarded=1) BEFORE the calibration choice
-                // so closing the overlay at the challenge can never lose the profile.
+                // so closing the overlay at step 3 can never lose the profile.
                 submit.disabled = true;
                 try {
                     _profile = await postProfile();
@@ -530,29 +403,19 @@
                             throw new Error(msg);
                         }
                     }
-                    // New step: input-device selection + calibration, between
-                    // path selection and the note-detect calibration challenge.
-                    await runInputSetup(selectedPaths);
-                    setStep(4);
+                    setStep(3);
                 } catch (e) { showErr(e.message || 'Could not save profile.'); refreshSubmit(); }
                 return;
             }
-            // Step 4 — "Play it now": leave calibration pending (it completes
+            // Step 3 — "Play it now": leave calibration pending (it completes
             // through the normal scored-stats path) and launch the diagnostic.
             const target = diagnosticFilename;
-            await finish({ launchingSong: !!target });
+            await finish();
             if (target && typeof window.playSong === 'function') window.playSong(target);
         });
 
         skipBtn.addEventListener('click', async () => {
-            // Step 2 — skip the song directory (the user can set it later in
-            // Settings). Proceed straight to instrument paths.
-            if (step === 2) {
-                setStep(3);
-                loadPathTiles();
-                return;
-            }
-            // Step 4 — skip: Mastery Rank 1 immediately, calibration stays
+            // Step 3 — skip: Mastery Rank 1 immediately, calibration stays
             // replayable from the Progress screen.
             skipBtn.disabled = true;
             try {

static/v3/progress.js

@@ -103,7 +103,7 @@
             '<div class="flex items-center justify-between gap-3 flex-wrap">' +
             '<div class="min-w-0">' +
             '<h3 class="text-lg font-bold text-fb-text">Calibration challenge</h3>' +
-            '<p class="text-sm text-fb-textDim mt-1">Play the <span class="text-fb-text">fee[dB]ack Diagnostic</span> with note detection and finish at ' +
+            '<p class="text-sm text-fb-textDim mt-1">Play the <span class="text-fb-text">Slopsmith Diagnostic</span> with note detection and finish at ' +
             '<span class="text-fb-text font-semibold">100% accuracy</span>' +
             (pending ? ' to reach Mastery Rank 1.' : ' to prove your setup (you skipped this — rank already granted).') + '</p></div>' +
             '<div class="flex items-center gap-2 shrink-0">' +

tests/js/midi_input_domain.test.js

@@ -1,216 +0,0 @@
-const { test } = require('node:test');
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const path = require('node:path');
-const vm = require('node:vm');
-const { createWindow, ROOT } = require('./capabilities_test_harness');
-
-const CAPABILITIES_JS = path.join(ROOT, 'static', 'capabilities.js');
-const MIDI_INPUT_JS = path.join(ROOT, 'static', 'capabilities', 'midi-input.js');
-
-function loadMidiInput(options = {}) {
-    const window = createWindow(options);
-    const context = vm.createContext(window);
-    vm.runInContext(fs.readFileSync(CAPABILITIES_JS, 'utf8'), context, { filename: CAPABILITIES_JS });
-    vm.runInContext(fs.readFileSync(MIDI_INPUT_JS, 'utf8'), context, { filename: MIDI_INPUT_JS });
-    return window;
-}
-
-// A fake provider whose enumerate/open/close are observable by the test.
-function fakeProvider(window, overrides = {}) {
-    const calls = { enumerate: 0, open: [], close: [] };
-    window.slopsmith.midiInput.registerProvider({
-        providerId: 'web-midi',
-        label: 'Web MIDI',
-        participantId: 'input_setup',
-        enumerate: async () => { calls.enumerate += 1; return overrides.sources || [{ sourceId: 'dev1', label: 'My Keyboard' }]; },
-        open: async (sourceId) => { calls.open.push(sourceId); return { addListener() {}, removeListener() {}, _id: sourceId }; },
-        close: (sourceId, handle) => { calls.close.push(sourceId); },
-        ...overrides.handlers,
-    });
-    return calls;
-}
-
-test('midi-input registers an active sensitive provider-coordinator', () => {
-    const window = loadMidiInput();
-    const api = window.slopsmith.capabilities;
-    const pipeline = api.inspect('midi-input');
-    assert.ok(pipeline, 'midi-input pipeline exists');
-    const owner = (pipeline.participants || []).find(p => p.pluginId === 'core.midi-input');
-    assert.ok(owner, 'core.midi-input owner registered');
-    assert.equal(owner.safety, 'sensitive');
-    assert.equal(owner.kind, 'provider-coordinator');
-    for (const cmd of ['inspect', 'list-sources', 'discover', 'select-source', 'open-source', 'close-source']) {
-        assert.ok(owner.commands.includes(cmd), `owner exposes ${cmd}`);
-    }
-    assert.equal(window.slopsmith.midiInput.version, 1);
-});
-
-test('list-sources and select-source are prompt-free (never enumerate)', async () => {
-    const window = loadMidiInput();
-    const api = window.slopsmith.capabilities;
-    const calls = fakeProvider(window);
-    const listed = await api.dispatch({ capability: 'midi-input', command: 'list-sources', source: 'tester' });
-    assert.equal(listed.outcome, 'handled');
-    assert.equal(calls.enumerate, 0, 'list-sources must not request MIDI access');
-});
-
-test('discover is the permission boundary and surfaces sources', async () => {
-    const window = loadMidiInput();
-    const api = window.slopsmith.capabilities;
-    const calls = fakeProvider(window);
-    const r = await api.dispatch({ capability: 'midi-input', command: 'discover', source: 'tester' });
-    assert.equal(r.outcome, 'handled');
-    assert.equal(calls.enumerate, 1, 'discover requests MIDI access exactly once');
-    const sources = window.slopsmith.midiInput.listSources();
-    assert.equal(sources.length, 1);
-    assert.equal(sources[0].logicalSourceKey, 'web-midi::dev1');
-    assert.equal(sources[0].kind, 'midi');
-});
-
-test('re-discovery drops sources for devices that vanished', async () => {
-    const window = loadMidiInput();
-    let devices = [{ sourceId: 'dev1', label: 'A' }, { sourceId: 'dev2', label: 'B' }];
-    window.slopsmith.midiInput.registerProvider({
-        providerId: 'web-midi', label: 'Web MIDI',
-        enumerate: async () => devices,
-        open: async () => ({ addListener() {}, removeListener() {} }),
-        close: () => {},
-    });
-    await window.slopsmith.midiInput.discover();
-    assert.equal(window.slopsmith.midiInput.listSources().length, 2);
-    devices = [{ sourceId: 'dev1', label: 'A' }];   // dev2 unplugged
-    await window.slopsmith.midiInput.discover();
-    const keys = window.slopsmith.midiInput.listSources().map((s) => s.logicalSourceKey);
-    assert.equal(keys.length, 1, 'vanished device is dropped from the source list');
-    assert.equal(keys[0], 'web-midi::dev1');
-});
-
-test('discover with no provider reports unavailable', async () => {
-    const window = loadMidiInput();
-    const api = window.slopsmith.capabilities;
-    const r = await api.dispatch({ capability: 'midi-input', command: 'discover', source: 'tester' });
-    assert.equal(r.outcome, 'unavailable');
-});
-
-test('discover surfaces denied when MIDI access is rejected', async () => {
-    const window = loadMidiInput();
-    const api = window.slopsmith.capabilities;
-    fakeProvider(window, { handlers: { enumerate: async () => { throw new Error('SecurityError: permission denied'); } } });
-    const r = await api.dispatch({ capability: 'midi-input', command: 'discover', source: 'tester' });
-    assert.equal(r.outcome, 'denied');
-    assert.match(r.reason, /denied/i);
-});
-
-test('select-source persists by logicalSourceKey', async () => {
-    const window = loadMidiInput();
-    const api = window.slopsmith.capabilities;
-    fakeProvider(window);
-    await api.dispatch({ capability: 'midi-input', command: 'discover', source: 'tester' });
-    const sel = await api.dispatch({ capability: 'midi-input', command: 'select-source', source: 'tester', payload: { logicalSourceKey: 'web-midi::dev1' } });
-    assert.equal(sel.outcome, 'handled');
-    assert.equal(window.__storage.get('slopsmith.midiInput.selectedLogicalSourceKey'), 'web-midi::dev1');
-    assert.ok(window.slopsmith.midiInput.listSources()[0].selected);
-});
-
-test('open/close share one session and release on the last requester', async () => {
-    const window = loadMidiInput();
-    const api = window.slopsmith.capabilities;
-    const calls = fakeProvider(window);
-    await window.slopsmith.midiInput.discover();
-    await window.slopsmith.midiInput.select('web-midi::dev1');
-    const a = await api.dispatch({ capability: 'midi-input', command: 'open-source', source: 'reqA', payload: { logicalSourceKey: 'web-midi::dev1' } });
-    const b = await api.dispatch({ capability: 'midi-input', command: 'open-source', source: 'reqB', payload: { logicalSourceKey: 'web-midi::dev1' } });
-    assert.equal(a.outcome, 'handled');
-    assert.equal(b.outcome, 'handled');
-    assert.equal(calls.open.length, 1, 'provider.open called once for a shared session');
-    // First release keeps the session open; second closes it.
-    await api.dispatch({ capability: 'midi-input', command: 'close-source', source: 'reqA', payload: { logicalSourceKey: 'web-midi::dev1' } });
-    assert.equal(calls.close.length, 0, 'session stays open while a requester holds it');
-    await api.dispatch({ capability: 'midi-input', command: 'close-source', source: 'reqB', payload: { logicalSourceKey: 'web-midi::dev1' } });
-    assert.equal(calls.close.length, 1, 'provider.close after the last release');
-});
-
-test('concurrent opens for one source coalesce onto a single provider.open', async () => {
-    const window = loadMidiInput();
-    const api = window.slopsmith.capabilities;
-    // A provider whose open() stays pending until we release it, so both
-    // dispatches are genuinely in flight at the same time.
-    let release;
-    const gate = new Promise((r) => { release = r; });
-    const calls = { open: 0, close: 0 };
-    window.slopsmith.midiInput.registerProvider({
-        providerId: 'web-midi', label: 'Web MIDI',
-        enumerate: async () => [{ sourceId: 'dev1', label: 'My Keyboard' }],
-        open: async () => { calls.open += 1; await gate; return { addListener() {}, removeListener() {} }; },
-        close: () => { calls.close += 1; },
-    });
-    await window.slopsmith.midiInput.discover();
-    await window.slopsmith.midiInput.select('web-midi::dev1');
-    const p1 = api.dispatch({ capability: 'midi-input', command: 'open-source', source: 'reqA', payload: { logicalSourceKey: 'web-midi::dev1' } });
-    const p2 = api.dispatch({ capability: 'midi-input', command: 'open-source', source: 'reqB', payload: { logicalSourceKey: 'web-midi::dev1' } });
-    release();
-    const [a, b] = await Promise.all([p1, p2]);
-    assert.equal(a.outcome, 'handled');
-    assert.equal(b.outcome, 'handled');
-    assert.equal(calls.open, 1, 'provider.open called exactly once despite concurrent opens');
-    // Both requesters joined the single shared session: it survives the first
-    // release and only closes on the last, with exactly one provider.close.
-    await api.dispatch({ capability: 'midi-input', command: 'close-source', source: 'reqA', payload: { logicalSourceKey: 'web-midi::dev1' } });
-    assert.equal(calls.close, 0, 'shared session stays open while reqB holds it');
-    await api.dispatch({ capability: 'midi-input', command: 'close-source', source: 'reqB', payload: { logicalSourceKey: 'web-midi::dev1' } });
-    assert.equal(calls.close, 1, 'provider.close once after the last requester releases');
-});
-
-test('public open() surfaces the live handle (in-page only)', async () => {
-    const window = loadMidiInput();
-    fakeProvider(window);
-    await window.slopsmith.midiInput.discover();
-    await window.slopsmith.midiInput.select('web-midi::dev1');
-    const res = await window.slopsmith.midiInput.open({ requester: 'input_setup', logicalSourceKey: 'web-midi::dev1' });
-    assert.equal(res.outcome, 'handled');
-    assert.ok(res.handle && typeof res.handle.addListener === 'function', 'live handle exposed via public global');
-});
-
-// Load the domain with a Web-MIDI-capable navigator so the built-in provider
-// self-registers (the shared harness has no navigator, so it normally skips).
-function loadWithWebMidi(inputs) {
-    const window = createWindow();
-    window.navigator = {
-        requestMIDIAccess: async () => ({
-            onstatechange: null,
-            inputs: new Map(inputs.map((i) => [i.id, { id: i.id, name: i.name, onmidimessage: null }])),
-        }),
-    };
-    const context = vm.createContext(window);
-    vm.runInContext(fs.readFileSync(CAPABILITIES_JS, 'utf8'), context, { filename: CAPABILITIES_JS });
-    vm.runInContext(fs.readFileSync(MIDI_INPUT_JS, 'utf8'), context, { filename: MIDI_INPUT_JS });
-    return window;
-}
-
-test('built-in Web-MIDI provider self-registers + discovers, filtering loopback ports', async () => {
-    const window = loadWithWebMidi([
-        { id: 'kb1', name: 'My Keyboard' },
-        { id: 'thru', name: 'Midi Through Port-0' }, // loopback → filtered out
-    ]);
-    const api = window.slopsmith.capabilities;
-    assert.ok(api.inspect('midi-input').participants.some(p => p.pluginId === 'core.midi-input'),
-        'built-in provider registered without any plugin');
-    const r = await api.dispatch({ capability: 'midi-input', command: 'discover', source: 'tester' });
-    assert.equal(r.outcome, 'handled');
-    const sources = window.slopsmith.midiInput.listSources();
-    assert.equal(sources.length, 1, 'loopback/passthrough ports are filtered');
-    assert.equal(sources[0].logicalSourceKey, 'web-midi::kb1');
-});
-
-test('diagnostics are redaction-safe (no device labels, no raw messages)', async () => {
-    const window = loadMidiInput();
-    fakeProvider(window);
-    await window.slopsmith.midiInput.discover();
-    const contrib = window.slopsmith.diagnostics.snapshotContributions()['midi-input-capability'];
-    assert.ok(contrib, 'midi-input contributes diagnostics');
-    assert.equal(contrib.schema, 'slopsmith.midi_input.diagnostics.v1');
-    const serialized = JSON.stringify(contrib);
-    assert.ok(!serialized.includes('My Keyboard'), 'device labels are redacted from diagnostics');
-    for (const s of contrib.sources) assert.ok(!('label' in s), 'source entries carry no label');
-});

tests/test_plugin_schema.py

@@ -0,0 +1,247 @@
+"""Plugin manifest schema sanity tests.
+
+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`.
+2. Each in-tree manifest's `id` matches its parent directory name —
+   the loader assumes this and silent drift would break plugin
+   discovery.
+3. The `license` enum in the schema enforces AGPL-3.0-only for
+    contributed manifests.
+4. The schema accepts capability-pipelines.v1 manifest metadata so
+    native capability declarations stay first-class in tooling.
+"""
+
+from __future__ import annotations
+
+import ast
+import glob
+import json
+import re
+from pathlib import Path
+
+import jsonschema
+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")
+def schema() -> dict:
+    with SCHEMA_PATH.open() as f:
+        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/")
+    assert "pluginRelpath" in schema["$defs"]
+
+
+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", "screen", "script", "routes", "tour", "settings"):
+        assert without_descriptions(docs_schema["properties"][key]) == without_descriptions(schema["properties"][key])
+    assert without_descriptions(docs_schema["$defs"]["pluginRelpath"]) == without_descriptions(schema["$defs"]["pluginRelpath"])
+    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."""
+    with open(manifest_path) as f:
+        manifest = json.load(f)
+    jsonschema.validate(manifest, schema)
+
+
+@pytest.mark.parametrize("manifest_path", sorted(glob.glob(PLUGINS_GLOB)))
+def test_in_tree_manifest_id_matches_directory(manifest_path: str) -> None:
+    """The `id` field must match the parent directory name."""
+    with open(manifest_path) as f:
+        manifest = json.load(f)
+    expected = Path(manifest_path).parent.name
+    assert manifest["id"] == expected, (
+        f"Plugin id {manifest['id']!r} in {manifest_path} does not match "
+        f"directory name {expected!r}. The loader keys plugin lookup by "
+        f"directory; drift would silently break discovery."
+    )
+
+
+def test_capability_manifest_metadata_validates(schema: dict) -> None:
+    """Capability-declared manifests should validate alongside runtime loader fields."""
+    manifest = {
+        "id": "capability_example",
+        "name": "Capability Example",
+        "version": "0.1.0",
+        "license": "AGPL-3.0-only",
+        "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": "none",
+                "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 test_schema_license_enum_requires_agpl_only(schema: dict) -> None:
+    """Contributed manifests must not validate with non-AGPL licenses."""
+    assert schema["properties"]["license"]["enum"] == ["AGPL-3.0-only"]
+
+    manifest = {"id": "license_example", "name": "License Example", "license": "MIT"}
+    with pytest.raises(jsonschema.ValidationError):
+        jsonschema.validate(manifest, schema)
+
+
+def test_plugin_runtime_paths_are_plugin_relative(schema: dict) -> None:
+    """Runtime file path fields must reject escapes and URL suffixes."""
+    valid = {
+        "id": "path_example",
+        "name": "Path Example",
+        "screen": "screen.html",
+        "script": "assets/screen.js",
+        "routes": "routes.py",
+        "tour": "tours/intro.json",
+        "settings": {"html": "settings/settings.html"},
+    }
+    jsonschema.validate(valid, schema)
+
+    for field in ("screen", "script", "routes", "tour"):
+        for bad_path in ("../escape.html", "safe/../escape.html", "/abs.html", "C:/abs.html", "dir\\file.js", "screen.html?x=1", "screen.html#frag", "./screen.html", ".hidden"):
+            manifest = {"id": "bad_path_example", "name": "Bad Path Example", field: bad_path}
+            with pytest.raises(jsonschema.ValidationError):
+                jsonschema.validate(manifest, schema)
+
+    for bad_path in ("../settings.html", "settings/../settings.html", "/settings.html", "settings\\settings.html", "settings.html?x=1", "settings.html#frag", "./settings.html", ".settings.html"):
+        manifest = {"id": "bad_settings_path", "name": "Bad Settings Path", "settings": {"html": bad_path}}
+        with pytest.raises(jsonschema.ValidationError):
+            jsonschema.validate(manifest, schema)