docs: add comprehensive user guide and update API limitations in documentation and server messaging.

Author: thunderdew-dawn

README.md

@@ -78,9 +78,11 @@ Full setup is below.
 - Tempo and key estimation from an audio file.
 - Melody-to-MIDI transcription (CREPE pitch tracking, with a lighter fallback).
 
-The server exposes 117 tools across the production, mixing, composition, safety,
+The server exposes 138 tools across the production, mixing, composition, safety,
 and project-organization surface, plus 6 live resources (project, mixer,
 transport, channels, patterns, status) that the LLM assistant can read directly.
+For a user-facing value overview, workflow examples, and the full tool catalog,
+see [`docs/USER_GUIDE.md`](docs/USER_GUIDE.md).
 
 ## What sets it apart
 
@@ -220,6 +222,9 @@ Plain-language prompts:
 - "Export this arrangement to a MIDI file."
 - "What tempo and key is this track?" (on an audio file)
 
+For examples by module, assistant, and diagnostic check, see the
+[`User Guide`](docs/USER_GUIDE.md).
+
 ## Architecture
 
 A thin controller script runs inside FL Studio and returns only cheap, raw data; all judgement — diagnosis, calibration, planning — happens server-side. A standalone daemon owns the MIDI port so the server works regardless of how the MCP client is launched. Note authoring uses a generated pyscript bridge: the daemon re-triggers the armed `MCP_Apply` script with a keystroke (via pyautogui) after a brief window force-focus. Every project-modifying tool routes through a snapshot → write → readback → rollback safety layer backed by a persisted change log.

ROADMAP.md

@@ -26,6 +26,15 @@ task.
 
 ## Current verification checkpoints
 
+- 2026-06-02: User-facing value, workflow, and tool-reference documentation
+  added.
+  - Verified path: `docs/USER_GUIDE.md` reviewed against
+    `scripts/audit_tool_safety.py --format json` output; README usage entry
+    linked to the guide; stale pattern-creation limit language corrected in
+    server instructions and this roadmap.
+  - Result: public docs now explain the app's production value, natural-language
+    assistant interaction model, module-level examples, MCP resources, safety
+    classes, explicit product boundaries, and the current 138-tool catalog.
 - 2026-06-02: Fork provenance and repository metadata aligned with the
   maintained `thunderdew-dawn/flstudio-mcp` branch.
   - Verified path: README, CONTRIBUTING, package metadata, MCP server metadata,
@@ -759,8 +768,9 @@ gain, not 1.0. The tools accept dB and convert.
 - [x] `fl_arrange_add_marker` (previously implemented in arrangement slice) — Section markers.
 
 API limits worth surfacing in tool docs:
-- New patterns cannot be created from scratch; clone an existing pattern
-  instead (`fl_arrange_clone_pattern`).
+- Playlist clip placement, movement, and deletion remain out of scope; create
+  or clone patterns, write notes into them, add markers, and place clips
+  manually in FL Studio.
 
 ## Phase 4 — Piano Roll pyscript (~6 tools) [x] Completed