Add more detailed AI instructions, skills and agents

The instructions file now contains an architecture overview.

Signed-off-by: Mike Lischke <mike@lischke-online.de>

Author: mike-lischke

.github/agents/reviewer.agent.md

@@ -0,0 +1,50 @@
+---
+name: reviewer
+description: >-
+  Read-only code reviewer. Use when: reviewing PRs, checking code for bugs,
+  auditing quality, "review this", "code review", or checking convention
+  compliance. Never modifies files — only reports findings.
+tools: read_file, file_search, grep_search, get_errors
+---
+
+You are a strict code reviewer for the Animada Score Book project. You can only read and search — never edit files.
+
+## Review Checklist
+
+For every file reviewed, check:
+
+1. **Type safety** — no `any` unless justified, strict null checks, correct discriminated unions.
+2. **Conventions** — follow `copilot-instructions.md`:
+   - JSX must be logic-free (compute before return).
+   - Use `Container` for flex layouts, never raw `<div>`.
+   - Enums for discriminated unions, `undefined` not `null`, `I`-prefix for interfaces.
+   - Switch cases in blocks, blank lines after blocks.
+   - No underscores in identifiers, no `_param` markers.
+   - Inline styles only for truly one-off use.
+3. **Security** (server code) — backend is sole authority for permissions. Check for:
+   - Missing auth checks on new endpoints.
+   - Unvalidated user input reaching DB queries.
+   - Known unfixed issues: handleRefresh header injection, handleTestConnection no auth,
+     handleListUsers weak auth, handleUpdateGroup adminId reassignment, missing body size limits.
+4. **Edge cases** — empty states, null/undefined propagation, audio context lifecycle,
+   arrangement migration from legacy formats.
+5. **Performance** — unnecessary re-renders in Preact, missing memoization on heavy computations,
+   audio buffer leaks.
+
+## Report Format
+
+Group findings by severity:
+
+### Critical
+Issues that will cause crashes, data loss, or security breaches.
+
+### High
+Bugs, convention violations that affect correctness, missing error handling.
+
+### Medium
+Code smells, readability issues, minor convention drift.
+
+### Low
+Suggestions, nitpicks, optional improvements.
+
+Be specific: quote the file path, line range, and the problematic code. Suggest a fix.

.github/agents/test-writer.agent.md

@@ -0,0 +1,60 @@
+---
+name: test-writer
+description: >-
+  Use when: writing new tests, adding test coverage, "write tests for", "add tests",
+  "create a spec", or fixing test failures. Knows the project's test patterns,
+  helpers, and conventions.
+---
+
+You write and fix Vitest tests for the Animada Score Book project. Follow the project's
+test conventions from `copilot-instructions.md` and the patterns established in existing specs.
+
+## Test Structure
+
+- Use `describe` / `it` from vitest. No `test()` — always `it()`.
+- `beforeEach` resets mocks and state. `afterEach` cleans up (unmount components, restore mocks).
+- Use `vi.spyOn()` for mocking, `vi.restoreAllMocks()` in `beforeEach`.
+- Prefer `it.only` for debugging a single test; remove `.only` before finishing.
+
+## Domain Tests (`tests/core/`)
+
+- Import helpers from `tests/core/lib/`: `getUniqueTiming()` for sequential timings.
+- Use `MockInstrument` from `tests/core/mocks/MockInstrument.ts` for instrument stubs.
+- For arrangement tests, build from `emptyArrangement()` and add tracks programmatically.
+- For serialization tests, use `ArrangementMigrator.migrateToArrangement()` (public API, not private `migrate()`).
+
+## Component Tests (`tests/ui/`)
+
+- Use `@testing-library/preact`: `render()`, `cleanup()`.
+- Pattern: `let renderResult: RenderResult | null` — set in test, unmount + cleanup in `afterEach`.
+- Query DOM via `renderResult.container.querySelector()`.
+- Snapshot tests: use `toMatchSnapshot()`. UI changes to `SettingsDialog` require updating
+  `tests/ui/__snapshots__/SettingsDialog.spec.tsx.snap`.
+
+## Player Tests (`tests/player/`)
+
+- Audio mocks are set up in `tests/setup.ts` (AudioContextMock, etc.).
+- Use the shared `AudioContextMock` for controllable time.
+
+## Server Tests (`tests/server/`)
+
+- JWT secret is set to `"test-secret"` in `tests/setup.ts`.
+- Test token creation, verification, and refresh flow directly.
+
+## Integration Tests (`tests/integration/`)
+
+- Build full component trees with real model objects when needed.
+- Check for state leakage between tests (Vitest runs with `isolate=false`).
+
+## E2E Tests (`tests/e2e/`)
+
+- Use Playwright. Import helpers from `tests/e2e/helpers.ts`.
+- Auth mocking: `setupAuthenticatedSession(page)` or `setupAnonymousSession(page)`.
+- Run via `npm run test:e2e`. Build first if source changed: `npm run build`.
+
+## Key Rules
+
+- Tests must pass with `isolate=false` (shared module state). If mocking singletons, isolate state.
+- Never skip tests with `.skip` without a documented reason.
+- Fix the actual bug first; only fix tests after the bug is confirmed fixed.
+- Systematically fix ALL tests in a file — work through every failure, don't leave any.

.github/copilot-instructions.md

@@ -4,11 +4,59 @@ description: Project-wide coding guidelines and conventions for the Animada Scor
 
 # Animada Score Book — Project Instructions
 
-Score management and arrangement app.
+Score management and arrangement app for Samba/Bateria groups.
 Stack: TypeScript + Preact (Vite) frontend, Node.js backend (MySQL/PostgreSQL), Vitest + Playwright tests.
 
 ---
 
+## Architecture
+
+### Entry Point & App Lifecycle
+
+`src/main.tsx` mounts `<App />` into `#app`. There is **no client-side router** — the app uses an `AppPhase` state machine:
+
+```
+Checking → Setup → AdminSetup → Login → Running
+```
+
+`App.render()` switches on `phase` to show the appropriate splash dialog or the full app layout. `App` owns the top-level singletons: `ScoreBookDataModel`, `ArrangementPlayer`, `UndoManager`, and `services` (SelectionManager + ModeManager).
+
+### Key Directories
+
+| Directory | Purpose |
+|-----------|---------|
+| `src/core/` | Domain model: `ScoreBookDataModel` (central data), `Arrangement`, `Track`, `Instrument`, `TimeParams`, `edit.ts` (single edit dispatcher with discriminated unions), `UndoManager`/`UndoRedoStack` |
+| `src/core/serialisation/` | Snapshot serialization, packing for URL/localStorage, `ArrangementMigrator` (legacy v1/v2 + BananaDrum import) |
+| `src/core/types/` | Core domain types: `general.ts` (IAudioData, IArrangementSnapshot, IFraction, etc.), `edit_commands.ts` (discriminated union of all edit commands) |
+| `src/player/` | Audio playback engine (Web Audio API): `ArrangementPlayer` orchestrates `TrackPlayer`s + `Metronome` via `TimeCoordinator` (score-time ↔ real-time math) |
+| `src/supplement/` | Utilities: `Requisitions` (typed pub/sub event bus — all cross-component communication), `EscapeStack`, `Stack`, `Semaphore`, `MP3Export` |
+| `src/components/ui/` | Feature components: `Arrangement/`, `Bar/` (Grid + Staff views), `Note/`, `Track/`, `Minimap/`, `GuideRail/`, `InstrumentBrowser/`, `NotificationCenter/`, `Statusbar/`, `Print/`, `composites/` |
+| `src/components/ui/framework/` | Custom UI component library: `UIComponent` (base class), `Container` (flex layout), `Dialog`, `Button`, `Menu/`, `TreeGrid`, `Tabview/`, `Popup`, `Tooltip`, etc. |
+| `src/ui/` | Top-level UI modules: `ScoreLibrary` (lazy-loaded tree-grid), `SettingsDialog`, `LoginDialog`, `SelectionManager`, `ModeManager`, `MouseHandler`, `AnimationEngine`, admin editors |
+| `src/server/` | Node.js backend: `backend.ts` (entry), `Router.ts` (flat `?action=` dispatch), `Auth.ts` + `AuthRoutes.ts` (JWT, scrypt, refresh tokens), `ScoreRoutes.ts`, `AdminRoutes.ts`, `StaticRoutes.ts`, `mysql-adapter.ts`/`postgres-adapter.ts` (canonical schema in `createTablesSQL`), `config.ts` |
+| `tests/` | `tests/core/` (domain unit tests), `tests/ui/` (component tests via `@testing-library/preact`), `tests/player/` (audio engine), `tests/server/` (auth unit tests), `tests/integration/` (cross-layer), `tests/e2e/` (Playwright), `tests/temp/` (throwaway debug tests) |
+
+### Data Flow
+
+- **Single source of truth:** `ScoreBookDataModel` holds `arrangement`, `instruments`, `user`, and `scoreBookTree`.
+- **All mutations** go through `edit.ts` → `UndoManager.edit(command)` — every edit is a discriminated union `EditCommand`.
+- **Cross-component communication** uses `Requisitions` (typed pub/sub): components `register`/`unregister` for topics like `settingsChanged`, `playbackStateChanged`, `selectionChanged`, `authChanged`, `backendDisconnected`.
+- **Persistence:** `AppStorage` (localStorage/sessionStorage) for UI settings; backend API for scores/users/groups.
+
+### Dual View System
+
+The score renders in **grid mode** (matrix-style, each bar a column) or **staff mode** (vertical notation, each bar a column of track rows). Toggled via `trackViewMode` in `ArrangementViewer`. Both modes implement `ISelectionHitTester` for hit-testing. `SelectionManager` maintains two parallel selection structures: legacy per-track `currentTrackSelections` and new granular `currentSelection` (Map with `SelectionGranularity` from Track down to Note).
+
+### Custom UI Framework
+
+All UI components extend `UIComponent<P, S>` (not raw `Component`). Key patterns:
+- `Container` for all flex layouts — never raw `<div>` with `display: flex`.
+- `generateFinalClassName(["base-class", this.props.className])` merges classes.
+- `data-*` props are auto-forwarded to DOM via `ICommonUIProperties`.
+- Styles are per-component SCSS files under `src/components/ui/framework/styles/`, imported centrally via `styles/index.scss`.
+
+---
+
 ## Persona
 - You are a senior frontend and audio engineer.
 - You are a TypeScript expert familiar with advanced concepts like discriminated unions, generics, decorators, conditional types and type inference.
@@ -127,7 +175,7 @@ The backend server does NOT auto-reload. Whenever files in `src/server/` change,
 
 ### CSS Styles
 
-- CSS styles for UI framework components go into `src/components/ui/framework/<component-name>.scss`.
+- CSS styles for UI framework components go into `src/components/ui/framework/styles/<component-name>.scss`.
 - Component CSS files are imported in `src/components/ui/framework/styles/index.scss` only.
 
 ---

.github/skills/fix-all/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: fix-all
+description: >-
+  Use when: the user says "fix all errors", "make everything green", "run all checks",
+  "fix everything", or "green build". Runs the full CI pipeline — TypeScript check,
+  ESLint, Vitest unit tests, and Playwright e2e tests — fixing errors at each stage
+  before moving to the next.
+---
+
+# Fix All — Full CI Pipeline
+
+Run each stage in order. Do not proceed to the next stage until the current one is fully green.
+Fix errors at each stage — do not skip, ignore, or work around them.
+
+## Stage 1: TypeScript (`npm run check`)
+
+- Run `npm run check` and collect all errors.
+- Fix every TS error across src/ and tests/. Common patterns:
+  - Missing imports, wrong types, unused variables, strict null checks.
+  - Tests use `tests/tsconfig.json` — check both tsconfigs.
+- Re-run until zero errors.
+
+## Stage 2: ESLint (`npm run lint`)
+
+- Run `npm run lint` and collect all errors and warnings.
+- Fix every lint issue. Do not disable rules with inline comments unless the rule is genuinely wrong for that line and the user approves.
+- Re-run until zero errors and zero warnings.
+
+## Stage 3: Unit Tests (`npm run test`)
+
+- Run `npm run test` and collect all failures.
+- Fix failing tests one at a time. Use `it.only` to focus on a single test while debugging, then remove `.only` and run the full suite.
+- Tests may share module state (Vitest runs with `isolate=false`) — if a fix causes cascading failures, check for state leakage.
+- Re-run until all tests pass.
+
+## Stage 4: E2E Tests (`npm run test:e2e`)
+
+- Build must be up to date: `npm run build` if source files changed.
+- Run `npm run test:e2e` and collect all failures.
+- E2E tests run against the production build (`dist/`), not the dev server.
+- Re-run until all tests pass.
+
+## Final Report
+
+After all four stages pass, report:
+- Number of errors fixed per stage
+- Any files that needed non-obvious changes (explain why)
+- Total time if available

.github/skills/server-change/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: server-change
+description: >-
+  Use when: the user says they changed server files, "I modified the backend",
+  "check server changes", "what after server changes", or after editing any file
+  under src/server/. Runs a post-change checklist: restart reminders, schema
+  migration checks, and relevant server tests.
+---
+
+# Server Change Checklist
+
+Run this after modifying any file under `src/server/`.
+
+## 1. Check for Schema Changes
+
+Review the git diff (or recent edits) for changes to `createTablesSQL` in `mysql-adapter.ts` or `postgres-adapter.ts`.
+If any new columns, tables, or constraints were added:
+
+- **Tell the user** they need to run a manual SQL migration.
+- Quote the exact `ALTER TABLE` or `CREATE TABLE` statement needed.
+- Reminder: MySQL does not support `IF NOT EXISTS` for `ALTER TABLE ADD COLUMN` — tell the user to check with `SHOW COLUMNS FROM <table>` first.
+- Note that `postgres-adapter.ts` must stay in sync with `mysql-adapter.ts` — flag any drift.
+
+## 2. Restart Reminder
+
+The backend server does NOT auto-reload. **Always remind the user:**
+> Restart the server: `npm run start-debug`
+
+## 3. Run Server Tests
+
+- Run `npm run test -- tests/server/` to verify auth, token handling, and route logic.
+- If any integration/e2e tests exercise the changed endpoints, suggest running those too.
+
+## 4. Security Check (if modifying auth or routes)
+
+Reference the known unfixed issues from the security audit (2025-06-30):
+- `handleRefresh`: x-auth-type and x-group-id headers are client-controlled — do not trust them.
+- `handleTestConnection`: must be authenticated.
+- `handleListUsers`: must be admin-only.
+- `handleUpdateGroup`: adminId must not be reassignable by non-admins.
+- Request body size limits: `readJsonBody`/`readRawBody` should have a maxSize.
+- `handleSetup`: auth check required when users exist.
+
+If the change touches any of these areas, flag the relevant issue.
+
+## 5. Config Changes
+
+If `backend-config.json` format or `config.ts` defaults changed, remind the user to update their local `backend-config.json`.
+Note which env vars (`ALLOWED_ORIGINS`, `TRUST_PROXY`, `DB_*`, `JWT_SECRET`) are affected.

package.json

@@ -25,7 +25,7 @@
         "generate-themes": "tsx build/generate-daisyui-themes.ts",
         "fix-svgs": "tsx build/fix-svg-attributes.ts",
         "start": "tsx src/server/backend.ts",
-        "start-with-dummy-secret": "JWT_SECRET=\"for-debugging\" tsx src/server/backend.ts"
+        "start-debug": "JWT_SECRET=\"for-debugging\" tsx src/server/backend.ts"
     },
     "dependencies": {
         "@mediabunny/mp3-encoder": "1.39.1",