P0: Clearer MCP context layer for local LLM agents

[thunderdew-dawn]

Description

This PR introduces a safer and more explicit MCP context layer for local LLM agents.

Problem

The current MCP surface already exposes useful tools and runtime resources, but recurring agent workflows still rely mostly on documentation and ad-hoc orchestration. This makes it harder for a local LLM agent to consistently choose the right context, respect FL Studio API boundaries, and follow the intended safety sequence for read-only analysis, dry-run planning, and approved writes.

Repeated user pain this addresses:

• Agents need clearer workflow entry points for common production tasks.
• Documentation, safety rules, API limits, and Knowledgebase guidance should be easier to retrieve without dumping large documents into context.
• Local agents need an explicit separation between prompts, resources, and tools.
• Unsupported FL Studio actions should be surfaced early instead of being implied by incomplete tool context.

Desired outcome

A user or local LLM agent should be able to ask in plain language:

• "Scan my mix."
• "Review my routing."
• "Organize this project safely."
• "Check whether this project is ready for export."
• "Plan a plugin chain for this bus."
• "Analyze this reference audio."
• "Write a scale-aware melody, but show me the notes before writing."

The MCP server should guide these requests through a predictable structure:

• Prompts define safe workflow entry points.
• Resources provide compact context, safety rules, capability boundaries, and workflow guidance.
• Tools perform concrete read-only analysis, planning, validation, or explicitly approved rollback-safe actions.

Desired workflow

This PR adds or prepares MCP prompt workflows for:

• mix_review
• routing_review
• project_organizer
• project_preflight
• plugin_chain_planner
• composition_scale_writer
• audio_to_midi_or_reference_analysis
• api_probe
• bug_triage
• implementation_slice
• release_prepare

The workflow prompts are intended to reuse the existing documentation under docs/agents/prompts/ where possible, so runtime behavior and documentation stay aligned.

Current limitation

Without registered MCP prompts and clearer context/capability resources, agents must infer workflow order from scattered documentation and tool descriptions. This increases the risk of:

• unnecessary MCP round trips,
• using low-level tools when a high-level workflow exists,
• missing read-only-first analysis steps,
• implying unsupported FL Studio capabilities,
• or asking for/projecting writes before a dry-run or explicit approval step.

Proposed safe tool path

The implementation should keep existing high-level workflow tools as the preferred execution layer and add prompt/resource guidance around them.

Examples:

Mix review

1. Read fl://agent-briefing.
2. Read fl://status.
3. Read fl://mixer.
4. Run fl_review_mix.
5. Optionally run fl_review_low_end_stereo.
6. For stronger evidence, use fl_mix_watch_start and fl_mix_watch_stop.
7. Do not call fl_apply_mix_adjustment unless the user explicitly approves one rollback-backed change.

Routing review

1. Read session and mixer context.
2. Run fl_review_routing.
3. If cleanup is useful, run fl_plan_routing_cleanup.
4. Apply routing changes only through approved rollback-safe write tools.

Project organization

1. Read channels, mixer, and pattern context.
2. Run fl_plan_project_cleanup.
3. Present the plan first.
4. Apply only one explicitly approved cleanup step at a time.
5. Read back the affected state and report the result.

Composition

1. Use scale/raga lookup tools first.
2. Show the proposed notes or pattern to the user.
3. Write to the Piano Roll only after explicit approval.

Safety class

Primary safety class: read-only

Secondary safety class for optional follow-up actions: write-safe-required

This PR should not introduce new unsafe FL Studio mutations. Any persistent FL Studio write exposed or affected by this work must continue to require explicit user approval, scoped snapshotting, readback verification, changelog/rollback support, and clear user-facing before/after reporting.

FL Studio API evidence

This change is primarily an MCP interface and context-organization improvement. It should rely on existing, already exposed tools and existing documented project safety rules.

Evidence classification:

• Existing safe tools: existing
• Prompt/resource registration: MCP-server-side interface change
• New FL Studio write capabilities: not intended
• Plugin loading, render automation, playlist clip editing: still unsupported/manual/API-limited unless separately proven

Risks and unsupported boundaries

This PR must not imply support for API-limited or prohibited behavior.

Unsupported or manual-only boundaries must remain explicit:

• No automatic plugin loading or insertion.
• No WAV render automation.
• No project open/new/save-as automation.
• No broad UI automation.
• No playlist clip editing, movement, splitting, or deletion.
• No raw API escape hatch.
• No guessed normalized EQ/plugin values.
• No full-project restore claims.

The new prompts/resources should make these boundaries easier for agents to discover, not weaker.

Implementation notes

Expected implementation shape:

• Add src/fls_pilot/prompts.py.

• Register prompt definitions from src/fls_pilot/server.py.

• Reuse existing files under docs/agents/prompts/ where practical.

• Preserve existing tools and resource registrations.

• Add compact context/capability resources such as:

  • fls://docs/safety-contract
  • fls://docs/tool-policy
  • fls://docs/knowledgebase-protocol
  • fls://capabilities/supported
  • fls://capabilities/not-possible
  • fls://capabilities/api-limits
  • fls://capabilities/write-safety

• Improve Knowledgebase lookup behavior only if it can be done as a focused, reviewable slice.

• Add or update FastMCP registration checks where applicable.

Token and tool-surface impact

This PR is intended to reduce tool-selection noise and avoidable context dumping by making common workflows discoverable as prompts and compact resources.

It should not add redundant low-level tools. Any new MCP surface should be high-signal, workflow-oriented, and safety-preserving.

Related Issues

Closes #TODO

Checklist

• My code follows the project's engineering standards (English comments & commits).
• All safety guidelines in AGENTS.md and docs/engineering/standards.md are satisfied.
• Offline unit tests pass successfully locally (pytest).
• Safety audit scripts pass successfully (python scripts/audit_tool_safety.py --fail-on-gaps and python scripts/audit_tool_safety.py --fail-on-missing-safety-docs --format json).
• Anti-vibe check script passes successfully (python scripts/audit_anti_vibe.py).
• I linked the relevant GitHub issue, milestone, or project-board item if feature status changed.
• I have checked GitHub Project P2: Read-only mini-dashboard over MCP resources #7 and release planning issue P0: Release 3.0 readiness checklist #66 when this affects release scope, package naming, or versioning.
• I updated GitHub source metadata rather than manually editing generated roadmap/changelog snapshots.

[thunderdew-dawn]

Closing this PR because it currently represents a broad v3/alpha → main integration with 61 commits and 332 changed files. This is too large and too mixed in scope for a focused P0 PR.

The v3/alpha branch remains the integration branch for ongoing v3 work. Individual changes should be reviewed as small feature/fix/docs PRs into v3/alpha. A new v3/alpha → main release PR should only be opened once the alpha line is stable, tested, documented, and explicitly ready for main.