feat: add cross-tool orientation, CI schema validation, and Claude Code surfaces

Adds the contributor- and AI-tool-facing infrastructure on top of the
modular docs from the previous commit. Lands AGENTS.md as the canonical
cross-tool orientation (read natively by Cursor, Copilot, Codex, Aider,
Cline, Continue, Cody, Devin, Replit Agent, and Claude Code), flips
CLAUDE.md to a 22-line pointer that uses Claude Code's @-import to
inline AGENTS.md, wires up plugin.json validation in CI, and adds the
Claude-specific automation surfaces under .claude/.

Cross-tool orientation:
  AGENTS.md (178 lines) — single source of truth: architecture, running
    the app, testing, git workflow, versioning, song formats, frontend
    and backend conventions, plugin authoring index, first-hour
    pitfalls, verification, house rules.
  CLAUDE.md (22 lines) — Claude Code memory file. Uses @AGENTS.md
    import (recursion depth 5) so the canonical content is inlined
    without duplication. Lists .claude/ surfaces.
  .github/copilot-instructions.md — Copilot custom instructions
    format; points at AGENTS.md and docs/PLUGIN_AUTHORING.md.
  .cursorrules — not added. Cursor reads AGENTS.md natively in 2026
    and .cursorrules is legacy.

Contribution hygiene (.github/):
  PULL_REQUEST_TEMPLATE.md — summary, linked issue, test plan, DCO
    and conventional-commit reminders. No AI-disclosure section.
  ISSUE_TEMPLATE/bug.yml — version, deployment, OS, plugins enabled,
    repro, logs (linked to docs/diagnostics-bundle-spec.md for
    redaction guidance).
  ISSUE_TEMPLATE/feature.yml — problem, proposed, alternatives,
    surface, plugin-author impact, license check.
  ISSUE_TEMPLATE/config.yml — disables blank issues; redirects
    plugin issues to plugin repos and security to the private
    advisory flow.

CI:
  .github/workflows/validate-plugins.yml — runs on changes to
    plugins/*, schema/, CONTRIBUTING.md, the test file, or the
    workflow itself. Installs jsonschema and pytest, validates every
    plugins/*/plugin.json against schema/plugin.schema.json, and runs
    the license-allowlist subset check.
  tests/test_plugin_schema.py — 8 parametrized tests: schema is
    well-formed, the 3 in-tree manifests validate, manifest id
    matches its parent directory name, schema license enum is a
    subset of CONTRIBUTING's curated allowlist.
  requirements-test.txt — append jsonschema>=4.0.
  .github/workflows/sync-version.yml — comment retargeted to
    AGENTS.md "Versioning" section.

Claude Code surfaces (.claude/):
  README.md — layout explanation. Spec-kit owns skills/speckit-*;
    repo-specific skills sit alongside. Hooks off by default;
    settings.json carries a commented opt-in example.
  skills/plugin-scaffold/SKILL.md — generates a plugin skeleton for
    type in {visualization, overlay, settings-only, routes-only}.
  skills/plugin-validate/SKILL.md — local pre-push check: validates
    plugin.json against schema, asserts declared files exist,
    enforces license allowlist.
  rules/plugin-author.md — globs scoped to plugins/**. Encodes the
    contracts from docs/PLUGIN_AUTHORING.md so AI suggestions don't
    drift from them (manifest required, context[\"log\"] over print,
    load_sibling over bare imports, playSong await discipline,
    settings.server_files conventions).
  agents/slopsmith-reviewer.md — plugin-aware reviewer subagent;
    invoke with @slopsmith-reviewer. 12-item checklist mirrors the
    rule and the schema.
  settings.json — empty hooks block plus a commented PostToolUse
    example for opt-in plugin.json validation on save.

Inbound-ref updates (files we own):
  README.md — \"AI Agent Guide\" points at AGENTS.md and notes
    .claude/ and copilot-instructions are tool-specific.
  CONTRIBUTING.md — \"Plugin System in CLAUDE.md\" -> docs/ and
    schema/; \"Git Workflow\" -> AGENTS.md#git-workflow.
  docs/sloppak-spec.md — plugin-system table cell -> docs/.

Out of scope (intentionally untouched):
  plugins/highway_3d/README.md (gitlink — plugin owns its docs).
  .specify/memory/constitution.md and other spec-kit artefacts
    (spec-kit owns that surface; CLAUDE.md still resolves
    transitively via the @-import).

Verification:
  pytest -q                                     # backend + schema tests pass
  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'))]\"
Signed-off-by: Miguel_LZPF <mgcdreamer@gmail.com>

.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 (PSARC / 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
+- 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`
+- [ ] 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 (skip for chore/docs)
+- [ ] Documentation updated if behaviour or contracts changed

.github/copilot-instructions.md

@@ -0,0 +1,21 @@
+# 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`.
+- **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).

.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,70 @@
+name: Validate plugins
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'plugins/**/plugin.json'
+      - 'schema/plugin.schema.json'
+      - 'CONTRIBUTING.md'
+      - 'tests/test_plugin_schema.py'
+      - '.github/workflows/validate-plugins.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'plugins/**/plugin.json'
+      - 'schema/plugin.schema.json'
+      - 'CONTRIBUTING.md'
+      - '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 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 sanity tests
+        run: pytest tests/test_plugin_schema.py -v