@williamzujkowski/live-coding-music-mcp 3.0.0 → 4.1.0

package/README.md

@@ -4,7 +4,7 @@
 >
 > **Unofficial fan project.** Not affiliated with, or endorsed by, the [Strudel project](https://codeberg.org/uzu/strudel). This adapter exists to make live-coding music accessible to beginners who want to try pattern-based music without learning the whole ecosystem first.
 >
-> **Status:** Beta | 86% statement coverage | Published to npm | Actively developed
+> **Status:** Beta | 88% statement coverage | Published to npm | Actively developed
 
 <a href="https://glama.ai/mcp/servers/@williamzujkowski/live-coding-music-mcp">
   <img width="380" height="200" src="https://glama.ai/mcp/servers/@williamzujkowski/live-coding-music-mcp/badge" alt="live-coding-music-mcp server" />
@@ -13,12 +13,12 @@
 [![CI](https://github.com/williamzujkowski/live-coding-music-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/williamzujkowski/live-coding-music-mcp/actions)
 [![npm version](https://img.shields.io/npm/v/@williamzujkowski/live-coding-music-mcp.svg)](https://www.npmjs.com/package/@williamzujkowski/live-coding-music-mcp)
 [![Nerq Trust](https://nerq.ai/badge/live-coding-music-mcp)](https://nerq.ai/kya/live-coding-music-mcp)
-[![Tools](https://img.shields.io/badge/tools-84-green.svg)]()
+[![Tools](https://img.shields.io/badge/tools-28-green.svg)]()
 [![License](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE)
 
 A Model Context Protocol (MCP) server that drives [Strudel.cc](https://strudel.cc/) from Claude for AI-assisted live-coding music, pattern generation, and algorithmic composition.
 
-**Current State: Beta.** The core workflow (init → generate → write → play → analyze) works reliably with real audio output. 1771 tests pass, 86.76% statement coverage / 77.32% branch coverage. CI is hardened with OpenSSF Scorecard, SHA-pinned actions, CODEOWNERS, Dependabot, and lint as a blocking gate.
+**Current State: Beta.** The core workflow (init → compose → playback → analyze) works reliably with real audio output. `npm test` reports ~3060 passing tests, <!-- COVERAGE:START -->88.99% statement coverage / 79.99% branch coverage<!-- COVERAGE:END -->. CI is hardened with OpenSSF Scorecard, SHA-pinned actions, CODEOWNERS, Dependabot, and lint as a blocking gate.
 
 **What "Beta" means here:**
 - Tool schemas are stable within minor versions; breaking changes require a major bump
@@ -30,8 +30,8 @@ A Model Context Protocol (MCP) server that drives [Strudel.cc](https://strudel.c
 
 - [Features](#features)
 - [Installation](#installation)
-- [Quick Reference](#quick-reference)
 - [Quick Start](#quick-start)
+- [Quick Reference](#quick-reference)
 - [Available Tools](#available-tools)
 - [Usage Examples](#usage-examples)
 - [Architecture](#architecture)
@@ -44,39 +44,40 @@ A Model Context Protocol (MCP) server that drives [Strudel.cc](https://strudel.c
 
 ## Features
 
-### 🎹 Music control
-- **84 MCP tools** covering pattern editing, playback, audio analysis, generation, history, sessions, and Gemini-backed assists. 26 are the canonical consolidated tools (`pattern_store`, `edit_pattern`, `transform`, `analyze`, `history`, `playback`, `effect`, `shape`, `audio_capture`, `browser_window`, `generate_part`, `generate_rhythm`, `music_theory`, `session`, `ai_assist`, ...); the rest are deprecated aliases kept for one release ([#178](https://github.com/williamzujkowski/live-coding-music-mcp/issues/178)).
+### Music control
+- **28 MCP tools** covering pattern editing, playback, audio analysis, generation, history, sessions, MIDI import/export, and Gemini-backed assists. Each tool is enum-parameterized to keep the protocol surface small: `pattern_store({ action })`, `edit_pattern({ mode })`, `transform({ op })`, `analyze({ include })`, `history({ action })`, `playback({ action })`, `effect({ action })`, `shape({ dimension })`, `audio_capture({ action })`, `browser_window({ action })`, `generate_part({ role })`, `generate_rhythm({ type })`, `music_theory({ query })`, `session({ action })`, `ai_assist({ task })`, ... The 58 legacy single-verb aliases that forwarded to these were removed in v4.0.0 ([#178](https://github.com/williamzujkowski/live-coding-music-mcp/issues/178)).
 - **4 MCP resources** for catalog browsing without burning tool calls: `strudel://examples`, `strudel://patterns`, `strudel://styles`, `strudel://docs/tools`.
 - **Real browser automation** of Strudel.cc through Playwright.
 - **Multi-session support** — every browser-touching tool accepts an optional `session_id`; sessions have isolated browser pages, undo/redo/history stacks, and audio-capture services.
 - **Audio analysis** via Web Audio API (FFT spectrum, tempo detection, key detection, rhythm complexity).
 - **Template-based pattern generation** across 8 genres (techno, house, dnb, ambient, trap, jungle, jazz, experimental); optional Gemini-backed `ai_assist` for feedback, suggestions, and jamming.
-- **Music theory helpers**: 15+ scales, 8+ chord progression styles, euclidean and polyrhythm generation.
+- **Music theory helpers**: 14 scales, 8 chord progression styles, euclidean and polyrhythm generation.
 - **Pattern persistence**: JSON-backed save/load with tags + the in-memory edit history (undo/redo/restore/compare).
 - **Result envelope** on every `tools/call`: clients branch on `{ ok, errorCategory, isRetryable }` instead of parsing free-text.
 
-### 🔧 Testing & CI status
-- **1771 passing tests** across unit, integration, and example-validation suites.
-- **86.76% statement coverage / 77.32% branch coverage**.
-- **Lint blocking in CI**: 0 errors, ~163 warnings (mostly `any` in test mocks).
+### Testing & CI status
+- **~3060 passing tests**: `npm test` runs ~3020 unit/integration/example tests in parallel, then 36 browser-validation tests serially against real Chromium. The coverage figure below is from the first tier, which is the one CI also runs — the browser tier adds ~0.2 points and CI does not execute it, so counting it would document coverage nothing verifies.
+<!-- COVERAGE:START -->
+- **88.99% statement coverage / 79.99% branch coverage** (90.5% functions, 89.75% lines), checked against `coverage/coverage-summary.json` by a drift guard.
+<!-- COVERAGE:END -->
+- **Lint blocking in CI**: 0 errors, ~195 warnings (mostly `any` in test mocks).
 - **OIDC trusted publishing** to npm with SLSA build provenance attestation on every release.
 
-**Not Production-Ready:** This is experimental software under active development. Use for exploration and experimentation. Expect breaking changes, bugs, and incomplete features. See [CONTRIBUTING.md](CONTRIBUTING.md) to help improve it.
+**Not Production-Ready:** This is experimental software under active development. Use for exploration and experimentation. Expect breaking changes, bugs, and incomplete features. See [the Contributing section](#contributing) to help improve it.
 
-### 🎼 Example patterns
+### Example patterns
 
-18 example patterns ship in [`patterns/examples/`](patterns/examples/), grouped by genre:
+7 example patterns ship in [`patterns/examples/`](patterns/examples/), grouped by genre:
 
-- **Techno**: hard-techno, minimal-techno
-- **House**: deep-house, tech-house
-- **Drum & Bass**: liquid-dnb, neurofunk
-- **Ambient**: dark-ambient, drone
-- **Trap**: modern-trap, cloud-trap
-- **Jungle**: classic-jungle, ragga-jungle
-- **Jazz**: bebop, modal-jazz
-- **Longform** (multi-minute pieces): dark-ambient-journey, driving-techno, liquid-dnb-roller, nu-jazz-session
+- **Ambient**: ambient-pad (70 BPM)
+- **Dnb**: dnb-classic (174 BPM)
+- **House**: house-classic (125 BPM)
+- **Jazz**: jazz-ii-v-i (120 BPM)
+- **Jungle**: amen-break (165 BPM)
+- **Techno**: techno-driving (130 BPM)
+- **Trap**: trap-modern (140 BPM)
 
-Each example is a JSON file with pattern code, BPM, key, and a description. See [`patterns/examples/README.md`](patterns/examples/README.md) for details. Agents can also list these via the `strudel://examples` MCP resource without making any tool calls.
+Each example is a JSON file with pattern code, BPM, key, and a description, and each sets the tempo it declares (#367). See [`patterns/examples/README.md`](patterns/examples/README.md) for details. Agents can also list these via the `strudel://examples` MCP resource without making any tool calls.
 
 ## Migrating from `@williamzujkowski/strudel-mcp-server`
 
@@ -151,9 +152,86 @@ npx playwright install chromium
 npm run build
 ```
 
+## Quick Start
+
+Get from install to your first generated pattern in under two minutes.
+
+### 1. Install
+
+```bash
+npm install -g @williamzujkowski/live-coding-music-mcp
+npx playwright install chromium   # one-time
+```
+
+Building from source instead? See [Installation → From Source](#from-source).
+
+### 2. Configure your MCP client
+
+#### Claude Desktop
+
+Edit your Claude Desktop config file:
+
+| OS | Config path |
+|---|---|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+Add the server:
+
+```json
+{
+  "mcpServers": {
+    "live-coding-music": {
+      "command": "live-coding-music-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The server appears under the 🔌 plug icon.
+
+#### Claude Code (CLI)
+
+```bash
+# If installed globally
+claude mcp add strudel live-coding-music-mcp
+
+# If built from source
+claude mcp add strudel node /path/to/live-coding-music-mcp/dist/index.js
+```
+
+### 3. Verify the server responds
+
+```bash
+# From a global install
+echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | live-coding-music-mcp
+
+# From source
+npm run validate
+```
+
+You should see a JSON response listing **28 tools**. If you see fewer, the build is out of date — run `npm run build`.
+
+### 4. Make your first sound
+
+In Claude, ask:
+
+> Initialize Strudel and compose a techno beat.
+
+**What you'll see:** A Chromium window opens (visibly — this is the live editor, not a hidden process) and lands on strudel.cc. Claude calls `init`, then `compose({ style: "techno" })`. A 4-on-the-floor pattern appears in the CodeMirror editor and starts playing through your speakers.
+
+Prefer headless mode (no browser window)? Set `"headless": true` in `config.json` before the first `init` call — see [Configuration](#configuration). Note that tempo detection currently reflects how often the agent polls rather than the audio itself (#322), in headed or headless mode alike.
+
+### 5. Where to go next
+
+- [Quick Reference](#quick-reference) below: tool cheat sheet for common operations.
+- [Usage Examples](#usage-examples): multi-step workflows (composition, audio analysis, AI-assisted jamming).
+- [`patterns/examples/`](patterns/examples/): 18 ready-to-play patterns across 7 genres plus 4 longform pieces. Agents can browse them via the `strudel://examples` MCP resource without burning tool calls.
+
 ## Quick Reference
 
-Common commands for immediate use:
+Common operations as one-line tool calls:
 
 | Action | Tool call |
 |---|---|
@@ -169,39 +247,18 @@ Common commands for immediate use:
 | Edit current pattern | `edit_pattern({ mode: "write", pattern: "..." })` |
 | Create an isolated session | `session({ action: "create", session_id: "live-1" })` |
 
-The legacy single-verb tools (`play`, `stop`, `save`, `undo`, `write`, `generate_pattern`, ...) still work in v3.0 as deprecated aliases. They forward to the consolidated tools and will be removed in v3.1 ([#178](https://github.com/williamzujkowski/live-coding-music-mcp/issues/178)).
+The legacy single-verb tools (`play`, `stop`, `save`, `undo`, `write`, `generate_pattern`, ...) were deprecated aliases during the `3.0.x` line and were removed in v4.0.0 ([#178](https://github.com/williamzujkowski/live-coding-music-mcp/issues/178)). Use the consolidated tools above.
 
 **One-shot workflow:**
 ```
-compose with style: "dnb", key: "Am", bpm: 174, auto_play: true
-```
-
-## Quick Start
-
-### 1. Add to Claude
-```bash
-# If installed globally
-claude mcp add strudel live-coding-music-mcp
-
-# If built from source
-claude mcp add strudel node /path/to/live-coding-music-mcp/dist/index.js
-```
-
-### 2. Start Using
-```bash
-claude chat
+compose with style: "dnb", key: "Am", tempo: 174, auto_play: true
 ```
 
-Then ask Claude:
-- "Initialize Strudel and create a techno beat"
-- "Generate a jazz chord progression in F major"
-- "Create a drum & bass pattern at 174 BPM"
-
 ## Available Tools
 
 <!-- TOOLS:START -->
 
-**84 tools** across 15 categories:
+**28 tools** across 15 categories:
 
 <details><summary><strong>Setup</strong> (1)</summary>
 
@@ -211,127 +268,95 @@ Then ask Claude:
 
 </details>
 
-<details><summary><strong>Pattern Editing</strong> (5)</summary>
+<details><summary><strong>Pattern Editing</strong> (2)</summary>
 
 | Tool | Description |
 |------|-------------|
+| `edit_pattern` | Mutate the current session pattern. mode=write replaces the editor contents (default; mirrors the old write tool exactly, including optional pattern validation and auto_play). mode=append concatenates `code` after the current pattern with a newline. mode=insert places `code` at the given line `position`. mode=replace substitutes `search` with `replace` — the first occurrence only, unless replace_all is true. The response reports how many occurrences matched, were replaced, and remain. mode=clear empties the editor. Example: edit_pattern({ mode: "write", pattern: "s(\"bd\")", auto_play: true }). For reading the editor without mutating it use get_pattern; for the on-disk pattern catalog use pattern_store. |
 | `get_pattern` | Get current pattern code |
-| `write` | [DEPRECATED — use edit_pattern({ mode: "write" }) instead] Write pattern to editor with optional auto-play and validation |
-| `append` | [DEPRECATED — use edit_pattern({ mode: "append" }) instead] Append code to current pattern |
-| `insert` | [DEPRECATED — use edit_pattern({ mode: "insert" }) instead] Insert code at specific line |
-| `replace` | [DEPRECATED — use edit_pattern({ mode: "replace" }) instead] Replace pattern section |
 
 </details>
 
-<details><summary><strong>Playback</strong> (6)</summary>
+<details><summary><strong>Playback</strong> (2)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `status` | [DEPRECATED — use diagnostics({ level: "status" }) instead] Get current browser and playback status (quick state check) |
-| `clear` | [DEPRECATED — use edit_pattern({ mode: "clear" }) instead] Clear the editor |
-| `play` | [DEPRECATED — use playback({ action: "play" }) instead] Start playing pattern |
-| `pause` | [DEPRECATED — use playback({ action: "pause" }) instead] Pause playback |
-| `stop` | [DEPRECATED — use playback({ action: "stop" }) instead] Stop playback |
-| `set_tempo` | Set BPM |
+| `playback` | Control transport on the current session. action=play starts the editor pattern. action=pause halts the clock where it is, so play resumes mid-cycle. action=stop ends playback. Example: playback({ action: "play" }). For pattern editing use edit_pattern; for tempo use set_tempo. |
+| `set_tempo` | Set BPM. Writes setcpm(bpm/4), assuming one bar of 4/4 per cycle. |
 
 </details>
 
-<details><summary><strong>Storage</strong> (3)</summary>
+<details><summary><strong>Storage</strong> (2)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `save` | [DEPRECATED — use pattern_store({ action: "save" }) instead] Save pattern with metadata |
-| `load` | [DEPRECATED — use pattern_store({ action: "load" }) instead] Load saved pattern |
-| `list` | [DEPRECATED — use pattern_store({ action: "list" }) instead] List saved patterns |
+| `pattern_store` | Persist patterns to disk and read them back. Use action=save to write the current session pattern under a name; action=load to restore a named pattern into the current session; action=list to enumerate the on-disk catalog (optionally filtered by tag). Example: pattern_store({ action: "save", name: "my-jam", tags: ["techno"] }). For session lifecycle (create/destroy/list active sessions) use the session tool — pattern_store deals with on-disk patterns, not runtime sessions. |
+| `import_midi` | Convert a .mid file into a playable Strudel pattern (Phase 1: literal transcription, #201). Use source="base64" with data=<base64 string> for inline bytes, or source="path" with data=<basename> to read from the patterns/midi/ directory (path traversal blocked). Drum tracks (MIDI channel 10) emit one s() lane per sample so simultaneous kicks/hats do not collide. Pitched tracks emit note("...").s("piano") with simultaneous notes merged into [a,b,c] chord tokens. Phase 2+ (structural compression, voice separation, LLM idiomatic pass) tracked in separate issues. Example: import_midi({ source: "path", data: "drumloop.mid", steps_per_cycle: 16 }). For the reverse direction (Strudel → MIDI) use the export_midi tool. |
 
 </details>
 
-<details><summary><strong>History</strong> (4)</summary>
+<details><summary><strong>History</strong> (1)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `undo` | [DEPRECATED — use history({ action: "undo" }) instead] Undo last action |
-| `redo` | [DEPRECATED — use history({ action: "redo" }) instead] Redo action |
-| `list_history` | [DEPRECATED — use history({ action: "list" }) instead] List recent pattern history with timestamps and previews |
-| `restore_history` | [DEPRECATED — use history({ action: "restore" }) instead] Restore a previous pattern from history by ID |
+| `history` | Navigate or inspect the pattern edit history. action=undo reverts the last edit on the targeted session. action=redo replays a previously-undone edit. action=list returns recent entries with timestamps and previews (limit defaults to 10). action=restore jumps the editor to a specific entry by id (current pattern goes on the undo stack). action=compare diffs two entries by id (or one entry vs current pattern). Example: history({ action: "list", limit: 5 }) — recent edits, newest first. For on-disk saved patterns use pattern_store — history deals with the in-memory edit timeline of the current session. |
 
 </details>
 
-<details><summary><strong>Generation</strong> (8)</summary>
+<details><summary><strong>Generation</strong> (3)</summary>
 
 | Tool | Description |
 |------|-------------|
 | `compose` | Generate, write, and play a complete pattern in one step. Auto-initializes default browser if needed. |
-| `generate_pattern` | [DEPRECATED — use compose instead, which auto-inits and returns richer metadata] Generate complete pattern from style with optional auto-play. |
-| `generate_drums` | [DEPRECATED — use generate_part({ role: "drums" }) instead] Generate drum pattern |
-| `generate_bassline` | [DEPRECATED — use generate_part({ role: "bass" }) instead] Generate bassline |
-| `generate_melody` | [DEPRECATED — use generate_part({ role: "melody" }) instead] Generate melody from scale |
-| `generate_polyrhythm` | [DEPRECATED — use generate_rhythm({ type: "polyrhythm" }) instead] Generate polyrhythm |
-| `generate_fill` | [DEPRECATED — use generate_part({ role: "fill" }) instead] Generate drum fill |
-| `generate_variation` | [DEPRECATED — use transform({ op: "vary" }) instead] Create pattern variations (mis-named today; it transforms, not generates) |
+| `generate_part` | Generate a single instrumental layer and append it to the current session pattern. role=drums takes `style` (e.g. "techno"/"house") and optional `complexity` 0-1. role=bass takes `key` (e.g. "C") + `style`. role=melody takes `root`/`scale` (e.g. C/minor) and optional `length` (notes). role=fill takes `style` and optional `bars`. Example: generate_part({ role: "drums", style: "techno", complexity: 0.7 }). For full compositions use compose; for rhythmic patterns use generate_rhythm; for music-theory queries use music_theory. |
+| `generate_rhythm` | Generate a rhythmic pattern and append it to the current session. type=euclidean produces a Euclidean rhythm with `hits` evenly distributed across `steps` (optional `sound` param, default "bd"). type=polyrhythm overlays multiple sound layers with given pattern numbers. Example: generate_rhythm({ type: "euclidean", hits: 3, steps: 8, sound: "hh" }). For complete patterns (drums/bass/melody) use generate_part; for whole compositions use compose. |
 
 </details>
 
-<details><summary><strong>Music Theory</strong> (4)</summary>
+<details><summary><strong>Music Theory</strong> (1)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `generate_scale` | [DEPRECATED — use music_theory({ query: "scale" }) instead] Generate scale notes |
-| `generate_chord_progression` | [DEPRECATED — use music_theory({ query: "chord_progression" }) instead] Generate chord progression |
-| `generate_euclidean` | [DEPRECATED — use generate_rhythm({ type: "euclidean" }) instead] Generate Euclidean rhythm |
-| `apply_scale` | [DEPRECATED — use transform({ op: "scale" }) instead] Apply scale to notes |
+| `music_theory` | Music-theory queries. query=scale returns the notes of a scale (e.g. "C major scale: C, D, E, F, G, A, B"). query=chord_progression returns a chord progression for the key/style AND writes the resulting chord pattern into the current session. Example: music_theory({ query: "scale", root: "C", scale: "major" }). For pattern generation (drums/bass/melody) use generate_part; for rhythmic patterns use generate_rhythm. |
 
 </details>
 
-<details><summary><strong>Transform</strong> (9)</summary>
+<details><summary><strong>Transform</strong> (3)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `transpose` | [DEPRECATED — use transform({ op: "transpose" }) instead] Transpose notes by semitones |
-| `reverse` | [DEPRECATED — use transform({ op: "reverse" }) instead] Reverse pattern |
-| `stretch` | [DEPRECATED — use transform({ op: "stretch" }) instead] Time stretch pattern |
-| `quantize` | [DEPRECATED — use transform({ op: "quantize" }) instead] Quantize to grid |
-| `humanize` | [DEPRECATED — use transform({ op: "humanize" }) instead] Add human timing variation |
-| `add_effect` | [DEPRECATED — use effect({ action: "add" }) instead] Add effect to pattern |
-| `remove_effect` | [DEPRECATED — use effect({ action: "remove" }) instead] Remove effect |
-| `add_swing` | [DEPRECATED — use transform({ op: "swing" }) instead] Add swing to pattern |
-| `set_energy` | [DEPRECATED — use shape({ dimension: "energy" }) instead] Adjust energy level 0-10. Auto-plays after applying. |
+| `transform` | Apply a single transform op to the current session pattern. op=transpose shifts notes by `semitones`. op=reverse appends `.rev` to the pattern. op=stretch slows by `factor` (>1 slower, <1 faster). op=quantize snaps to the `grid` (e.g. "1/16"). op=humanize adds rand-nudge timing of `amount` (0-1). op=swing applies `.swing(amount)`. op=scale applies a `root`/`scale` filter to notes. op=vary returns a variation of `type` (subtle/moderate/extreme/glitch/evolving). Example: transform({ op: "transpose", semitones: 7 }). For effects (add/remove) use effect; for mood/energy/refine use shape; for tempo use set_tempo. |
+| `effect` | Add or remove a Strudel effect on the current session pattern. action=add appends `.<effect>(<params>)`. action=remove strips EVERY `.<effect>(...)` call from the pattern, not just the last. Example: effect({ action: "add", effect: "lpf", params: "1000" }). For higher-level effect bundles (mood/energy/refine) use shape; for raw transforms use transform. |
+| `shape` | Shape the current pattern along one of three high-level dimensions. dimension=mood applies a mood profile (dark/euphoric/melancholic/aggressive/dreamy/peaceful/energetic) with optional intensity 0-1. dimension=energy applies an energy level (integer 0-10). dimension=refine applies a directional refinement: faster/slower/louder/quieter/brighter/darker/"more reverb"/drier. All three auto-play by default. Example: shape({ dimension: "mood", target_mood: "dark", intensity: 0.8 }). For raw transform ops use transform; for explicit effects use effect. |
 
 </details>
 
-<details><summary><strong>AI</strong> (4)</summary>
+<details><summary><strong>AI</strong> (1)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `get_pattern_feedback` | [DEPRECATED — use ai_assist({ task: "feedback" }) instead] Get AI-powered creative feedback on the current pattern using Google Gemini. |
-| `jam_with` | [DEPRECATED — use ai_assist({ task: "jam" }) instead] AI generates a complementary layer to jam with your pattern. |
-| `shift_mood` | [DEPRECATED — use shape({ dimension: "mood" }) instead] Transform current pattern to match a different emotional mood. Moods: dark, euphoric, melancholic, aggressive, dreamy, peaceful, energetic. |
-| `refine` | [DEPRECATED — use shape({ dimension: "refine" }) instead] Incrementally refine current pattern: faster/slower/louder/quieter/brighter/darker/"more reverb"/drier. |
+| `ai_assist` | Gemini-backed pattern assistance. task=feedback returns creative critique on the current pattern (optionally with audio analysis). task=suggest analyzes the currently playing audio and suggests a complementary Strudel pattern as text (not auto-executed). task=jam generates a fresh layer (drums/bass/melody/pad/texture) and merges it into the current pattern, then auto-plays. All three share Gemini auth + rate limiting. Example: ai_assist({ task: "jam", layer: "bass" }). Needs GEMINI_API_KEY, or a logged-in claude/agy/codex CLI on PATH (#252). For non-AI pattern generation use generate_part; for full compositions use compose. |
 
 </details>
 
-<details><summary><strong>Analysis</strong> (7)</summary>
+<details><summary><strong>Analysis</strong> (6)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `analyze` | Audio analysis on the currently-playing pattern.  |
-| `analyze_spectrum` | [DEPRECATED — use analyze({ include: ["spectrum"] }) instead] FFT spectrum analysis |
-| `analyze_rhythm` | [DEPRECATED — use analyze({ include: ["rhythm"] }) instead] Rhythm analysis |
-| `detect_tempo` | [DEPRECATED — use analyze({ include: ["tempo"] }) instead] BPM detection |
-| `detect_key` | [DEPRECATED — use analyze({ include: ["key"] }) instead] Key detection |
+| `analyze` | Audio analysis on the currently-playing pattern. include=["all"] (default) returns the full spectrum + features object, matching the pre-consolidation behaviour. include=["tempo"] returns only BPM with confidence. include=["key"] returns detected key + scale + confidence. include=["spectrum"] returns FFT features (bass, mid, treble, brightness, etc.). include=["rhythm"] returns rhythm-only analysis (complexity, density, syncopation). Combining values returns an object keyed by category, e.g. analyze({ include: ["tempo", "key"] }) → { tempo: {...}, key: {...} }. Example: analyze({ include: ["tempo"] }) to cheaply re-check BPM during a session. For static pattern analysis (no browser) use analyze_pattern_local; for runtime validation use validate_pattern_runtime. |
 | `validate_pattern_runtime` | Validate pattern with runtime error checking (monitors Strudel console for errors) |
-| `compare_patterns` | [DEPRECATED — use history({ action: "compare" }) instead] Compare two patterns from history showing differences |
+| `validate_pattern_local` | Validate pattern syntax against the local StrudelEngine, which runs in a sandboxed child process (no browser required) |
+| `analyze_pattern_local` | Static analysis (events/cycle, complexity, optional BPM) without browser playback |
+| `query_pattern_events` | Enumerate events the pattern would emit between two cycle indices (max 16 cycles) |
+| `transpile_pattern` | Transpile pattern source via StrudelEngine; returns transpiled code or syntax error |
 
 </details>
 
-<details><summary><strong>Session</strong> (4)</summary>
+<details><summary><strong>Session</strong> (1)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `create_session` | [DEPRECATED — use session({ action: "create" }) instead] Create a new isolated Strudel browser session. |
-| `destroy_session` | [DEPRECATED — use session({ action: "destroy" }) instead] Close and destroy a Strudel session. |
-| `list_sessions` | [DEPRECATED — use session({ action: "list" }) instead] List all active Strudel sessions. |
-| `switch_session` | [DEPRECATED — use session({ action: "switch" }) instead] Change the default session. |
+| `session` | Manage isolated Strudel browser sessions (multi-session, #108). action=create starts a new named session (sessions share one browser but isolated contexts). action=destroy closes a named session and releases its resources. action=list returns metadata for all active sessions (id, created, last_activity, is_playing, is_default). action=switch changes the default session that subsequent tool calls route to when no session_id is passed. Example: session({ action: "create", session_id: "live-set-1" }). For the on-disk pattern catalog use pattern_store(action=list) — session(action=list) lists *runtime* sessions, not saved patterns. |
 
 </details>
 
@@ -340,59 +365,35 @@ Then ask Claude:
 | Tool | Description |
 |------|-------------|
 | `export_midi` | Export current pattern to MIDI file. Parses note(), n(), and chord() functions. |
-| `screenshot` | [DEPRECATED — use browser_window({ action: "screenshot" }) instead] Take a screenshot of the current Strudel editor state |
+| `browser_window` | Interact with the visible Strudel browser window. action=show brings the window to the foreground. action=screenshot captures the current editor view to disk (optional `filename`). Example: browser_window({ action: "screenshot", filename: "demo.png" }). For diagnostics (status/errors/perf) use diagnostics; for the editor itself use edit_pattern. |
 
 </details>
 
-<details><summary><strong>Audio</strong> (3)</summary>
+<details><summary><strong>Audio</strong> (1)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `start_audio_capture` | [DEPRECATED — use audio_capture({ action: "start" }) instead] Start capturing audio. Audio must be playing. |
-| `stop_audio_capture` | [DEPRECATED — use audio_capture({ action: "stop" }) instead] Stop audio capture and return base64-encoded audio. |
-| `capture_audio_sample` | [DEPRECATED — use audio_capture({ action: "sample" }) instead] Capture a fixed-duration audio sample. |
+| `audio_capture` | Record audio output from the live Strudel session. action=start begins streaming capture (optional `format` webm/opus, default webm). action=stop ends the stream and returns base64-encoded audio. action=sample captures a fixed-`duration` window in one call (100-60000ms, default 5000ms). Example: audio_capture({ action: "sample", duration: 3000 }). Audio must be playing for capture to record meaningful data. For MIDI export use export_midi; for runtime diagnostics use diagnostics. Each session has its own recorder, so captures in different sessions do not interfere (#180). |
 
 </details>
 
-<details><summary><strong>Debug</strong> (5)</summary>
+<details><summary><strong>Debug</strong> (1)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `show_browser` | [DEPRECATED — use browser_window({ action: "show" }) instead] Bring browser window to foreground |
-| `diagnostics` | Inspect server and browser state.  |
-| `show_errors` | [DEPRECATED — use diagnostics({ level: "errors" }) instead] Display captured console errors and warnings from Strudel |
-| `performance_report` | [DEPRECATED — use diagnostics({ level: "perf" }) instead] Get performance metrics and bottlenecks |
-| `memory_usage` | [DEPRECATED — use diagnostics({ level: "memory" }) instead] Get current memory usage statistics |
+| `diagnostics` | Inspect server and browser state. level=status returns a quick state snapshot (cache read, <15ms SLA), plus which config.json was read and any warnings from it. level=full returns detailed browser diagnostics including caches, errors, and performance. level=perf returns server-side timing metrics + top bottlenecks. level=memory returns process memory usage. level=errors returns captured console errors and warnings from Strudel. Default level=full preserves the pre-consolidation behaviour. Example: diagnostics({ level: "status" }) — millisecond-cheap. For screenshots use browser_window; for tool listings use the strudel://docs/tools resource. |
 
 </details>
 
-<details><summary><strong>Other</strong> (19)</summary>
+<details><summary><strong>Other</strong> (1)</summary>
 
 | Tool | Description |
 |------|-------------|
-| `ai_assist` | Gemini-backed pattern assistance.  |
-| `suggest_pattern_from_audio` | [DEPRECATED — use ai_assist({ task: "suggest" }) instead] Analyze playing audio and suggest a complementary Strudel pattern. |
-| `validate_pattern_local` | Validate pattern syntax against the in-process StrudelEngine (no browser required) |
-| `analyze_pattern_local` | Static analysis (events/cycle, complexity, optional BPM) without browser playback |
-| `query_pattern_events` | Enumerate events the pattern would emit between two cycle indices (max 16 cycles) |
-| `transpile_pattern` | Transpile pattern source via StrudelEngine; returns transpiled code or syntax error |
-| `audio_capture` | Record audio output from the live Strudel session.  |
-| `browser_window` | Interact with the visible Strudel browser window.  |
-| `edit_pattern` | Mutate the current session pattern.  |
-| `generate_part` | Generate a single instrumental layer and append it to the current session pattern.  |
-| `music_theory` | Music-theory queries.  |
-| `generate_rhythm` | Generate a rhythmic pattern and append it to the current session.  |
-| `history` | Navigate or inspect the pattern edit history.  |
-| `playback` | Control transport on the current session.  |
-| `session` | Manage isolated Strudel browser sessions (multi-session, #108).  |
-| `pattern_store` | Persist patterns to disk and read them back.  |
-| `transform` | Apply a single transform op to the current session pattern.  |
-| `effect` | Add or remove a Strudel effect on the current session pattern.  |
-| `shape` | Shape the current pattern along one of three high-level dimensions.  |
+| `export_audio` | Record a window of live Strudel audio and write it to a file. Returns a path plus what was actually recorded, not a wall of base64 — prefer this over audio_capture when you want the audio to exist somewhere. format=wav (default) decodes to 16-bit PCM a DAW will open; format=webm writes the raw Opus recording. Reports silent captures instead of writing a silent file and claiming success. Audio must already be playing: call playback({ action: "play" }) first. Example: export_audio({ duration: 4000, filename: "take-01" }). |
 
 </details>
 
-_Auto-generated from source. 84 tools registered._
+_Auto-generated from source. 28 tools registered._
 
 <!-- TOOLS:END -->
 
@@ -409,7 +410,7 @@ Claude: [Initializes browser]
         [Starts playback]
 
 Pattern created:
-setcpm(130)
+setcpm(130/4)
 stack(
   s("bd*4"),
   s("~ cp ~ cp"),
@@ -449,7 +450,7 @@ You: Generate a complete drum & bass track at 174 BPM
 Claude: [Creates multi-layer pattern with drums, bass, and pads]
 
 // dnb pattern in C at 174 BPM
-setcpm(174)
+setcpm(174/4)
 stack(
   // Drums
   s("bd ~ ~ [bd bd] ~ ~ bd ~, ~ ~ cp ~ ~ cp ~ ~").fast(2),
@@ -504,7 +505,7 @@ You: Create an ambient soundscape with multiple layers
 
 Claude: [Generates complex multi-layer pattern]
 
-setcpm(90)
+setcpm(90/4)
 stack(
   // Deep bass drone
   note("c1").s("sine").attack(4).release(8).gain(0.5),
@@ -600,7 +601,7 @@ note("c4 eb4 g4 bb4 c5").struct("1 1 1 1 1 1 1 1")
 
 ## Testing
 
-All tools have been tested with real Strudel.cc interaction:
+Tools are exercised against real Strudel.cc interaction through the browser test suite; those are skipped in CI (require Playwright + audio) but run locally:
 
 ```bash
 # Run integration tests
@@ -620,273 +621,46 @@ node tests/strudel-integration.js
   "headless": false,        // Set true for background operation
   "strudel_url": "https://strudel.cc/",
   "patterns_dir": "./patterns",
+  "exports_dir": "./exports",
+  "viewport": { "width": 1280, "height": 720 },  // or null to track the window size (#514)
+  "block_resources": ["image", "font", "media"], // resource types the page route aborts
   "audio_analysis": {
-    "fft_size": 2048,
-    "smoothing": 0.8
+    "fft_size": 2048,       // power of 2 in [32, 32768]; code default is 1024
+    "smoothing": 0.8        // number in [0, 1]; default 0.8
   }
 }
 ```
 
-## Architecture
-
-### System Overview
-
-The Strudel MCP Server is built with a modular architecture that separates concerns and enables robust music generation:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                       Claude AI                              │
-│                  (MCP Client)                                │
-└───────────────────────┬─────────────────────────────────────┘
-                        │ MCP Protocol (stdio)
-                        │
-┌───────────────────────▼─────────────────────────────────────┐
-│              StrudelMCPServer                          │
-│  ┌────────────────────────────────────────────────────────┐ │
-│  │  Tool Request Handler                                  │ │
-│  │  - Validates inputs                                    │ │
-│  │  - Routes to appropriate service                       │ │
-│  │  - Handles errors gracefully                           │ │
-│  └────────────────────────────────────────────────────────┘ │
-└───────┬────────────┬────────────┬───────────┬──────────────┘
-        │            │            │           │
-   ┌────▼────┐  ┌───▼────┐  ┌───▼────┐  ┌──▼──────┐
-   │ Strudel │  │ Music  │  │Pattern │  │ Pattern │
-   │Controller│  │ Theory │  │Generator│  │  Store  │
-   └────┬────┘  └────────┘  └────────┘  └─────────┘
-        │
-   ┌────▼────────────────────────────┐
-   │   Playwright Browser            │
-   │  ┌──────────────────────────┐   │
-   │  │   Strudel.cc Website     │   │
-   │  │  ┌────────────────────┐  │   │
-   │  │  │  CodeMirror Editor │  │   │
-   │  │  └────────────────────┘  │   │
-   │  │  ┌────────────────────┐  │   │
-   │  │  │  Audio Context     │  │   │
-   │  │  │  + Web Audio API   │  │   │
-   │  │  └────────┬───────────┘  │   │
-   │  └───────────┼──────────────┘   │
-   └──────────────┼──────────────────┘
-                  │
-          ┌───────▼────────┐
-          │ Audio Analyzer │
-          │  - FFT Analysis│
-          │  - Frequency   │
-          │  - Spectral    │
-          └────────────────┘
-```
-
-### Core Components
-
-#### 1. **StrudelMCPServer** (`src/server/server.ts`, ~510 lines)
-
-Thin MCP dispatcher that:
-- Aggregates 84 tool definitions from the per-domain modules in `src/server/tools/` (84 = 26 consolidated tools + 58 deprecated aliases; -58 once #178 lands)
-- Routes `tools/call` requests to the right module's `execute()`
-- Wraps every response in the discriminated result envelope (`{ ok, errorCategory, isRetryable, ... }`)
-- Tracks initialization, per-session history bundles, per-session audio capture services
-- Advertises and serves MCP resources (`strudel://examples`, etc.)
-- Lazy-initializes the default browser controller on first browser-touching call
-
-Key Features:
-```typescript
-- Pattern caching before browser init
-- Undo/redo stack management
-- Session history tracking
-- Generated pattern storage
-- Safe fallback mechanisms
-```
-
-#### 2. **StrudelController** (`src/StrudelController.ts`)
-
-Browser automation layer using Playwright:
-- **Browser Management**: Chromium instance lifecycle
-- **Editor Control**: CodeMirror manipulation via DOM
-- **Playback Control**: Keyboard shortcuts for play/stop
-- **Performance Optimizations**:
-  - Editor content caching (100ms TTL)
-  - Direct CodeMirror API access
-  - Resource blocking (images, fonts)
-  - Fast DOM content loading
-
-```typescript
-// Example: Optimized pattern writing
-async writePattern(pattern: string) {
-  await this.page.evaluate((newPattern) => {
-    const editor = document.querySelector('.cm-content');
-    const view = editor.__view;
-    view.dispatch({
-      changes: { from: 0, to: view.state.doc.length, insert: newPattern }
-    });
-  }, pattern);
-}
-```
-
-#### 3. **AudioAnalyzer** (`src/AudioAnalyzer.ts`)
-
-Real-time audio analysis via Web Audio API injection:
-- **FFT Analysis**: 1024-point FFT for spectral data
-- **Frequency Bands**: Bass, low-mid, mid, high-mid, treble
-- **Analysis Caching**: 50ms TTL for performance
-- **Features Extracted**:
-  - Average amplitude
-  - Peak frequency
-  - Spectral centroid
-  - Playing state detection
-  - Frequency distribution
-
-```typescript
-Features provided:
-- average: Overall amplitude (0-255)
-- peak: Maximum amplitude
-- peakFrequency: Dominant frequency in Hz
-- bass/mid/treble: Band-specific amplitudes
-- brightness: Timbral classification
-- isPlaying: Boolean playback state
-```
-
-#### 4. **MusicTheory** (`src/services/MusicTheory.ts`)
-
-Music theory engine providing:
-- **15+ Scales**: Major, minor, modes, pentatonic, blues, whole-tone
-- **Chord Progressions**: Pop, jazz, blues, rock, folk, EDM
-- **Euclidean Rhythms**: Mathematical rhythm generation
-- **Arpeggio Generation**: Multiple patterns (up, down, random)
-- **Note Transposition**: Semitone-based pitch shifting
-
-Supported scales:
-```typescript
-major, minor, dorian, phrygian, lydian, mixolydian,
-aeolian, locrian, pentatonic, blues, chromatic,
-wholetone, harmonic_minor, melodic_minor
-```
-
-#### 5. **PatternGenerator** (`src/services/PatternGenerator.ts`)
+`strudel_url` is the REPL the browser is pointed at — set it to run against a self-hosted or
+pinned Strudel build. Only `http`/`https` are accepted; anything else falls back to the default
+with a logged warning. `patterns_dir` is where `pattern_store` reads and writes.
 
-AI-powered pattern creation:
-- **Genre Templates**: Techno, house, DnB, trap, ambient, jazz, intelligent_dnb, trip_hop, boom_bap
-- **Drum Patterns**: 4 complexity levels per genre
-- **Basslines**: 8 different styles
-- **Melody Generation**: Scale-based with musical intervals
-- **Variations**: Subtle, moderate, extreme, glitch, evolving
-- **Fills**: 1-4 bar drum fills
+`viewport` pins the Playwright page layout. Set it to `null` in a headed window so dragging the
+window resizes the page and strudel's canvases follow (#514). `block_resources` lists the
+resource types the page route aborts to speed up load; the default blocks `image`, `font`, and
+`media`, which suits headless CI but degrades the live editor (fallback-font button metrics,
+canvases that ignore window resizes). A live-coding setup wants `"block_resources": ["media"]`.
+Both keys fall back to the defaults with a logged warning when invalid.
 
-Example generation:
-```typescript
-generateCompletePattern('techno', 'C', 130)
-→ Multi-layer pattern with drums, bass, chords, melody
-```
-
-#### 6. **PatternStore** (`src/PatternStore.ts`)
-
-Persistent pattern storage:
-- **JSON-based**: Simple file storage
-- **Metadata**: Name, tags, timestamp, audio features
-- **Tag Filtering**: Organize by genre, mood, project
-- **Sorted Retrieval**: Most recent first
-
-### Directory Structure
-
-```
-live-coding-music-mcp/
-├── src/
-│   ├── server/
-│   │   ├── server.ts                    # MCP dispatcher (~510 lines)
-│   │   ├── resources.ts                 # MCP resources (#131)
-│   │   └── tools/
-│   │       ├── ai.ts, analysis.ts, capture.ts, compose.ts,
-│   │       ├── diagnostics.ts, editor.ts, generate.ts, history.ts,
-│   │       ├── playback.ts, session.ts, storage.ts, transform.ts,
-│   │       └── types.ts                 # ToolContext, Envelope, helpers
-│   ├── services/
-│   │   ├── MusicTheory.ts                # Scale/chord/euclidean helpers
-│   │   ├── PatternGenerator.ts           # Template-based generation
-│   │   ├── SessionManager.ts             # Multi-session lifecycle (#108)
-│   │   ├── AudioCaptureService.ts        # Audio recording
-│   │   ├── MIDIExportService.ts          # MIDI export
-│   │   ├── GeminiService.ts              # Gemini API client (ai_assist)
-│   │   ├── StrudelEngine.ts              # @strudel/* wrapper
-│   │   └── StrudelEngineHelpers.ts       # Pure helpers (#107)
-│   ├── utils/
-│   │   ├── Logger.ts
-│   │   ├── PatternValidator.ts           # Syntax + safety checks
-│   │   ├── ErrorRecovery.ts              # Retry / backoff
-│   │   ├── PerformanceMonitor.ts
-│   │   └── InputValidator.ts             # Input bound checks
-│   ├── StrudelController.ts              # Browser automation (~800 lines)
-│   ├── AudioAnalyzer.ts                  # Audio analysis (~800 lines)
-│   ├── PatternStore.ts                   # On-disk pattern persistence
-│   └── index.ts                          # Entry point
-├── src/__tests__/                        # Jest suites (unit + integration + browser)
-├── patterns/
-│   ├── examples/                         # 18 bundled example patterns
-│   └── *.json                            # Saved patterns at runtime
-├── scripts/
-│   ├── generate-tool-docs.ts             # README tool-table generator
-│   └── generate-changelog.ts
-├── config.json                           # Local config (gitignored)
-├── package.json
-└── tsconfig.json
-```
-
-### Data Flow
-
-1. **Tool Invocation**
-   ```
-   Claude → MCP Protocol → StrudelMCPServer
-   ```
-
-2. **Pattern Generation** (without browser)
-   ```
-   Server → PatternGenerator → MusicTheory → Pattern String
-   ```
+`exports_dir` is where `export_midi({format:"file"})` writes. Exported filenames are reduced to a
+basename and confined to this directory — a name containing path separators is sanitized rather
+than honoured, and the response reports the path actually written.
 
-3. **Pattern Execution** (with browser)
-   ```
-   Server → StrudelController → Playwright → Strudel.cc
-   ```
+Unknown top-level keys are logged as warnings at startup rather than silently ignored.
 
-4. **Audio Analysis**
-   ```
-   Strudel.cc → Web Audio API → AudioAnalyzer → Feature Data
-   ```
-
-### Performance Characteristics
-
-| Operation | Latency | Notes |
-|-----------|---------|-------|
-| Pattern Generation | <100ms | Pure computation |
-| Browser Init | ~3s | One-time cost |
-| Pattern Write | ~50ms | With caching |
-| Play/Stop | ~100ms | Keyboard shortcuts |
-| Audio Analysis | ~20ms | With 50ms cache |
-| Pattern Save | ~10ms | File I/O |
-
-### Optimization Strategies
-
-1. **Caching**
-   - Editor content: 100ms TTL
-   - Audio analysis: 50ms TTL
-   - Generated patterns: Until browser init
+`audio_analysis.fft_size` tunes the FFT bin count on the `AnalyserNode` attached to Strudel's audio graph — larger = better frequency resolution at higher CPU cost. `smoothing` is the analyser's `smoothingTimeConstant` (higher = steadier spectrum, more lag). Invalid values fall back to defaults with a warning; the frequency-band boundaries inside `analyze` rescale automatically so band Hz coverage stays consistent across FFT sizes.
 
-2. **Resource Blocking**
-   - Images, fonts, media blocked
-   - Only load essential JavaScript/CSS
+## Architecture
 
-3. **Direct API Access**
-   - CodeMirror view manipulation
-   - Keyboard shortcuts over button clicks
+The server is a thin MCP dispatcher (`src/server/server.ts`, ~520 lines) over twelve per-domain tool modules (`src/server/tools/*.ts`), ten services (MusicTheory, PatternGenerator, SessionManager, AudioCaptureService, AudioExportService, GeminiService, MIDIExportService, MIDIImportService, StrudelEngine, PatternSandbox) plus a provider-agnostic AI transport layer (`src/services/ai/`), two controllers (StrudelController for Playwright, AudioAnalyzer for Web Audio API), and a JSON-on-disk PatternStore. Browser automation drives the editor on strudel.cc through `window.strudelMirror.editor.dispatch(...)` rather than keyboard simulation — about 80% faster.
 
-4. **Lazy Loading**
-   - Browser starts only when needed
-   - Services initialized on-demand
+For the full breakdown — component diagram, per-component responsibilities, directory layout, data flow, and optimization strategies — see **[ARCHITECTURE.md](ARCHITECTURE.md)**.
 
 ## Pattern Examples
 
 ### Minimal Techno (Verified Working)
 ```javascript
-setcpm(130)
+setcpm(130/4)
 stack(
   s("bd*4").gain(0.9),
   s("~ cp ~ cp").room(0.2),
@@ -897,7 +671,7 @@ stack(
 
 ### Drum & Bass (Verified Working)
 ```javascript
-setcpm(174)
+setcpm(174/4)
 stack(
   s("bd ~ ~ [bd bd] ~ ~ bd ~, ~ ~ sn:3 ~ ~ sn:3 ~ ~").fast(2),
   s("hh*16").gain(0.5),
@@ -929,347 +703,15 @@ docker-compose up
 
 ## Development
 
-### Setup Development Environment
-
-```bash
-# Clone the repository
-git clone https://github.com/williamzujkowski/live-coding-music-mcp.git
-cd live-coding-music-mcp
-
-# Install dependencies
-npm install
-
-# Install Playwright browsers
-npx playwright install chromium
-
-# Build the project
-npm run build
-```
-
-### Available Scripts
+For development setup, scripts, debugging, adding new tools, and the release process, see **[DEVELOPMENT.md](DEVELOPMENT.md)**.
 
-```bash
-# Development mode with hot reload
-npm run dev
-
-# Build TypeScript to dist/
-npm run build
-
-# Start production server
-npm start
-
-# Run all tests
-npm test
-
-# Run integration tests with real browser
-npm run test:integration
-
-# Run browser-specific tests
-npm run test:browser
-
-# Validate MCP protocol compliance
-npm run validate
-
-# Lint code
-npm run lint
-
-# Format code
-npm run format
-
-# Clean build artifacts
-npm clean
-```
-
-### Publishing to npm
-
-See [NPM_PUBLISHING.md](NPM_PUBLISHING.md) for complete publishing instructions.
-
-**Quick publish via GitHub Release:**
-```bash
-npm version patch  # or minor, major
-git push && git push --tags
-gh release create v$(node -p "require('./package.json').version") --generate-notes
-```
-
-The package uses OIDC trusted publishing with provenance attestation for supply chain security.
-
-### Adding new tools
-
-Tools live in per-domain modules under `src/server/tools/<domain>.ts`. `server.ts` just dispatches. To add a tool:
-
-1. **Pick the right domain module** (or add a new one). Add the tool definition to that module's `tools` array:
-
-   ```typescript
-   export const tools: Tool[] = [
-     // ...
-     {
-       name: 'my_new_tool',
-       description: 'One-line description; agents read this to pick between adjacent tools',
-       inputSchema: {
-         type: 'object',
-         properties: {
-           param1: { type: 'string', description: 'What it is' },
-           session_id: { type: 'string', description: 'Optional session ID (#108)' },
-         },
-         required: ['param1'],
-       },
-     },
-   ];
-   ```
-
-2. **Add the case** to the module's `execute()` switch:
-
-   ```typescript
-   case 'my_new_tool':
-     return await ctx.getController(args.session_id).doSomething(args.param1);
-   ```
-
-3. **Add a service method** if needed (`MusicTheory`, `PatternGenerator`, etc.) and surface it through `ToolContext` (`src/server/tools/types.ts`) if other modules need it.
-
-4. **Don't hand-edit the README tool table.** It auto-generates via `npm run build` → `scripts/generate-tool-docs.ts`. A Jest test plus a CI step guard against drift.
-
-5. **Use the envelope helpers** for returns: `ok(data)`, `empty(data)`, `err('validation', 'message')` from `src/server/tools/types.ts`. Raw returns still work — the dispatcher normalises them — but native envelope construction is clearer.
-
-6. **Build and test**:
-
-   ```bash
-   npm run build
-   echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"my_new_tool","arguments":{"param1":"test"}},"id":2}' | node dist/index.js
-   ```
-
-### Testing Strategy
-
-#### 1. Unit Tests
-```bash
-# Run with Jest
-npm test
-
-# Watch mode
-npm run test:watch
-```
-
-#### 2. Integration Tests
-```bash
-# Full integration with real browser
-npm run test:integration
-
-# This tests:
-# - Browser initialization
-# - Pattern generation
-# - Audio analysis
-# - Pattern storage
-# - All 84 registered tools
-```
-
-#### 3. Manual Testing
-```bash
-# Development mode
-npm run dev
-
-# In another terminal
-claude mcp add strudel-dev node $(pwd)/dist/index.js
-claude chat
-
-# Then interact with Claude
-```
-
-### Code Quality
-
-**TypeScript Configuration**
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "strict": true,           // Strict type checking
-    "esModuleInterop": true,  // Better module compatibility
-    "target": "ES2020",       // Modern JavaScript
-    "module": "ES2020",       // ES modules
-    "moduleResolution": "node"
-  }
-}
-```
-
-**Linting & Formatting**
-```bash
-# ESLint
-npm run lint
-
-# Prettier
-npm run format
-
-# Pre-commit hooks recommended
-```
-
-### Debugging
-
-**Enable Debug Logging**
-```bash
-# Set DEBUG environment variable
-DEBUG=strudel:* npm start
-
-# Or specific modules
-DEBUG=strudel:controller npm start
-DEBUG=strudel:audio npm start
-```
-
-**VS Code Launch Configuration**
-```json
-{
-  "type": "node",
-  "request": "launch",
-  "name": "Debug MCP Server",
-  "program": "${workspaceFolder}/dist/index.js",
-  "preLaunchTask": "npm: build",
-  "console": "integratedTerminal",
-  "env": {
-    "DEBUG": "strudel:*"
-  }
-}
-```
-
-**Playwright Debugging**
-```typescript
-// In StrudelController.ts
-this.browser = await chromium.launch({
-  headless: false,  // See the browser
-  devtools: true,   // Open DevTools
-  slowMo: 100       // Slow down actions
-});
-```
-
-### Performance Monitoring
-
-The server includes built-in performance monitoring:
-
-```typescript
-// Access performance metrics
-You: Show me performance metrics
-
-Claude: Performance Report:
-{
-  "averageLatency": {
-    "init": "3.2s",
-    "write": "52ms",
-    "play": "105ms",
-    "analyze": "18ms"
-  },
-  "cacheHitRate": "85%",
-  "totalOperations": 1247,
-  "bottlenecks": [
-    {"tool": "init", "avgTime": 3200, "calls": 1},
-    {"tool": "write", "avgTime": 52, "calls": 156}
-  ]
-}
-```
-
-### Contributing Guidelines
-
-1. **Fork the repository**
-   ```bash
-   git clone https://github.com/YOUR_USERNAME/live-coding-music-mcp.git
-   ```
-
-2. **Create a feature branch**
-   ```bash
-   git checkout -b feature/my-new-feature
-   ```
-
-3. **Make your changes**
-   - Follow existing code style
-   - Add tests for new features
-   - Update documentation
-   - Ensure all tests pass
-
-4. **Commit with meaningful messages**
-   ```bash
-   git commit -m "feat: Add support for custom scale generation"
-   ```
-
-   Follow [Conventional Commits](https://www.conventionalcommits.org/):
-   - `feat:` New feature
-   - `fix:` Bug fix
-   - `docs:` Documentation changes
-   - `refactor:` Code refactoring
-   - `test:` Adding tests
-   - `chore:` Maintenance tasks
-
-5. **Push and create PR**
-   ```bash
-   git push origin feature/my-new-feature
-   ```
-
-   Then create a Pull Request on GitHub with:
-   - Clear description of changes
-   - Link to related issues
-   - Screenshots/examples if relevant
-
-### Release Process
+Quick links:
+- [Setup](DEVELOPMENT.md#setup) — `git clone` to `npm test`
+- [Adding new tools](DEVELOPMENT.md#adding-new-tools) — module pattern + envelope helpers
+- [Release process](DEVELOPMENT.md#release-process) — `gh release create` triggers the publish workflow
+- [Contributing](DEVELOPMENT.md#contributing) — commit conventions and PR flow
 
-```bash
-# 1. Update version in package.json
-npm version patch  # or minor/major
-
-# 2. Update CHANGELOG.md
-# Add entry for new version
-
-# 3. Build and test
-npm run build
-npm test
-npm run test:integration
-
-# 4. Commit version bump
-git add .
-git commit -m "chore: Bump version to X.Y.Z"
-
-# 5. Create git tag
-git tag vX.Y.Z
-
-# 6. Push to GitHub
-git push origin main --tags
-
-# 7. Publish to npm (if you have access)
-npm publish --access public
-
-# 8. Create GitHub release
-gh release create vX.Y.Z --generate-notes
-```
-
-### Docker Development
-
-```bash
-# Build development image
-docker build -t live-coding-music-mcp:dev .
-
-# Run with volume mount for hot reload
-docker run -it --rm \
-  -v $(pwd)/src:/app/src \
-  -v $(pwd)/patterns:/app/patterns \
-  live-coding-music-mcp:dev
-
-# Run tests in container
-docker run -it --rm live-coding-music-mcp:dev npm test
-```
-
-### Environment Variables
-
-```bash
-# Logging level
-LOG_LEVEL=debug        # debug, info, warn, error
-
-# Performance monitoring
-ENABLE_PERF_MONITORING=true
-
-# Pattern storage
-PATTERNS_DIR=./patterns
-
-# Browser configuration
-HEADLESS=false
-BROWSER_TIMEOUT=15000
-
-# Audio analysis
-FFT_SIZE=1024
-SMOOTHING=0.8
-```
+The [Configuration](#configuration) section above covers runtime config (`config.json`). [ARCHITECTURE.md](ARCHITECTURE.md) covers the system design.
 
 ## Performance
 
@@ -1282,8 +724,8 @@ Measured against the current `StrudelController` cache + Strudel.cc on a develop
 | Pattern read (cached) | 10–15 ms |
 | Play / pause / stop | 100–150 ms |
 | Audio analysis (single FFT) | 10–15 ms |
-| Tempo detection | <100 ms (onset-based; degraded under headless audio) |
-| Key detection | <100 ms (Krumhansl-Schmuckler) |
+| Tempo detection | <100 ms (onset-based; reports poll cadence, not tempo — #322) |
+| Key detection | <100 ms (Krumhansl-Schmuckler, Pearson; bass-register accuracy depends on `fft_size`) |
 | Pattern generation | <100 ms (template-based) |
 | Process resident memory | ~120–150 MB |
 
@@ -1454,7 +896,7 @@ s("bd*4")
   .every(8, x => x.sometimes(y => y.fast(2)))
 ```
 
-## 🔒 Security
+## Security
 
 ### Pattern Validation
 
@@ -1463,11 +905,23 @@ All patterns are validated before execution:
 - **Eval blocks** are rejected
 - **Path traversal** attacks are blocked in PatternStore
 
-### Browser Sandboxing
+### Browser Isolation
+
+Be precise about what this does and does not give you:
+
+- **The OS-level Chrome sandbox is disabled.** Chromium is launched with `--no-sandbox` and
+  `--disable-setuid-sandbox` ([`src/StrudelController.ts`](src/StrudelController.ts)) for headless
+  and container compatibility, where the sandbox otherwise needs `CAP_SYS_ADMIN` or user namespaces.
+  This is a deliberate trade-off, not a security feature.
+- **The browser context is a fresh, non-persistent Playwright context** — no profile on disk, no
+  cookies or storage carried over between runs, and no `file://` navigation is ever performed.
+- **Resource blocking is a performance optimization, not a security boundary.** Images, fonts, and
+  media are aborted to speed up page load; scripts, stylesheets, and network requests from
+  strudel.cc are allowed through as normal.
+- **Patterns are validated before execution** (see above), which is the actual pre-execution control.
 
-- Playwright runs Chromium in sandbox mode
-- No access to local filesystem from browser context
-- Resource blocking prevents loading external content
+If you need real isolation, run the whole MCP server inside a locked-down container or VM. The
+server does not sandbox itself.
 
 ### Known Limitations
 
@@ -1479,7 +933,7 @@ All patterns are validated before execution:
 
 Found a vulnerability? Please [open a security issue](https://github.com/williamzujkowski/live-coding-music-mcp/security/advisories/new) or email the maintainer directly. Do not disclose publicly until patched.
 
-## 🐛 Troubleshooting
+## Troubleshooting
 
 ### Common Issues
 
@@ -1546,7 +1000,7 @@ npm run build
 # Check if server responds
 echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js
 
-# Should return JSON with 84 tools (post-v3.0; ~26 after #178 alias removal)
+# Should return JSON with 28 tools
 
 # Reinstall MCP server in Claude
 claude mcp remove strudel
@@ -1587,7 +1041,7 @@ claude chat
    - Use resource blocking (enabled by default)
 
 #### Patterns not saving
-**Symptom**: `save` command fails or patterns don't persist
+**Symptom**: `pattern_store({ action: "save" })` fails or patterns don't persist
 
 **Solutions**:
 ```bash
@@ -1655,7 +1109,7 @@ Claude: Browser state:
 - Initialized: true
 - Cached patterns: 2
 - Undo stack depth: 5
-- Last operation: write_pattern (2.5s ago)
+- Last operation: edit_pattern (2.5s ago)
 ```
 
 **Validate Pattern Syntax**
@@ -1678,53 +1132,31 @@ If you encounter issues not covered here:
 4. **Consult Strudel docs**: [Strudel.cc documentation](https://strudel.cc/learn)
 5. **Create new issue**: Include error messages, OS, Node version, and steps to reproduce
 
-## 🤝 Contributing
-
-**We need your help!** This project is actively developed and welcomes contributions of all kinds:
-
-### Ways to Contribute
-- **Report Bugs**: Found an issue? [Open a bug report](https://github.com/williamzujkowski/live-coding-music-mcp/issues/new)
-- **Suggest Features**: Have ideas? [Create a feature request](https://github.com/williamzujkowski/live-coding-music-mcp/issues/new)
-- **Improve Docs**: Fix typos, add examples, clarify confusing sections
-- **Write Tests**: Help us improve test coverage
-- **Fix Issues**: Check [open issues](https://github.com/williamzujkowski/live-coding-music-mcp/issues) for bugs to fix
-- **Add Features**: Implement new tools or improve existing ones
-
-### Quick Start for Contributors
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Make your changes and add tests
-4. Ensure tests pass (`npm test`)
-5. Commit with clear messages (`git commit -m 'fix: resolve audio analysis bug'`)
-6. Push to your fork (`git push origin feature/amazing-feature`)
-7. Open a Pull Request
+## Contributing
 
-**First time contributor?** Look for issues labeled `good-first-issue` or `help-wanted`.
+PRs welcome — bug fixes, docs, tests, new tools. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the contribution guide and **[DEVELOPMENT.md](DEVELOPMENT.md)** for setup and workflow.
 
-### Feedback Welcome
-- Questions? Open a [Discussion](https://github.com/williamzujkowski/live-coding-music-mcp/discussions)
-- Found something confusing? Tell us!
-- Have a use case we haven't considered? Share it!
+For non-trivial work, open a GitHub issue first ([issue policy in CLAUDE.md](CLAUDE.md#github-issues-workflow)). For typos and small fixes, a PR directly is fine.
 
-We review PRs promptly and welcome contributors of all skill levels. See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed setup instructions.
+[GitHub Discussions](https://github.com/williamzujkowski/live-coding-music-mcp/discussions) are open for use-case questions and design conversations.
 
-## 📄 License
+## License
 
 **AGPL-3.0-or-later** — see [LICENSE](LICENSE) for the full text.
 
 This project depends on `@strudel/core`, `@strudel/mini`, `@strudel/tonal`, and `@strudel/transpiler`, which are AGPL-3.0 licensed by the upstream [Strudel project](https://codeberg.org/uzu/strudel). Since we `import` from those packages and redistribute the combined work via npm, this project must be distributed under the same copyleft terms. If you fork or redistribute, you must keep the AGPL license and provide source access to any network-accessible users (AGPL §13).
 
-Earlier versions of this package (including `@williamzujkowski/strudel-mcp-server` prior to deprecation) shipped with an MIT declaration — that was incorrect given the AGPL dependencies. v2.0.0 of `@williamzujkowski/live-coding-music-mcp` corrects the license to AGPL-3.0-or-later. v1.0.0 of this package is deprecated; install v2.0.0 or later.
+Earlier versions of this package (including `@williamzujkowski/strudel-mcp-server` prior to deprecation) shipped with an MIT declaration — that was incorrect given the AGPL dependencies. v2.0.0 of `@williamzujkowski/live-coding-music-mcp` corrects the license to AGPL-3.0-or-later. v1.0.0 of this package is deprecated; install v2.0.0 or later (current: v4.0.0).
 
-## 🙏 Acknowledgments
+## Acknowledgments
 
-- [Strudel.cc](https://strudel.cc) - Amazing live coding environment
-- [TidalCycles](https://tidalcycles.org) - Pattern language inspiration
-- [Anthropic](https://anthropic.com) - Claude AI and MCP protocol
-- [Playwright](https://playwright.dev) - Reliable browser automation
+- [Strudel.cc](https://strudel.cc) — pattern-based live coding environment (this project is a fan adapter, not affiliated)
+- [TidalCycles](https://tidalcycles.org) — original pattern language Strudel descends from
+- [Anthropic](https://anthropic.com) — Claude and the MCP protocol
+- [Playwright](https://playwright.dev) — browser automation
 
 ---
 
-**v3.0.0** — Open source, AGPL-3.0-or-later, experimental | [Report issues](https://github.com/williamzujkowski/live-coding-music-mcp/issues) | [Contribute](https://github.com/williamzujkowski/live-coding-music-mcp/pulls)
+**v4.0.0** — Open source, AGPL-3.0-or-later, experimental | [Report issues](https://github.com/williamzujkowski/live-coding-music-mcp/issues) | [Contribute](https://github.com/williamzujkowski/live-coding-music-mcp/pulls)
 
 *This project is under active development. Core features work, but expect bugs and breaking changes. Not recommended for production use.*