docs: define default safe UX contract (#89)

closes #56 P0: Define default safe UX contract

Author: thunderdew-dawn

docs/agents/prompts/mix-review.md

@@ -8,6 +8,7 @@ Use this when the user wants to review the current FL Studio mix.
 - `fl://status`
 - `docs/agents/runtime-usage.md`
 - `docs/concepts/safety-contract.md`
+- `docs/concepts/default-safe-ux.md`
 
 ## Workflow
 
@@ -19,9 +20,11 @@ Use this when the user wants to review the current FL Studio mix.
    - critical mix risks
    - low-end/stereo issues
    - routing or gain-staging problems
-   - safe next actions
-6. Do not mutate FL Studio state unless the user explicitly approves a
-   rollback-backed write.
+   - exactly one safest reversible next action
+6. Include the risk level for the proposed next action.
+7. Ask for explicit confirmation before calling any write tool.
+8. If confirmed, apply at most one small reversible change, read back where
+   supported, report before/after plus rollback or `change_id`, then stop.
 
 ## Stop Conditions
 
@@ -40,5 +43,6 @@ Return:
 1. Session/bridge status.
 2. Mix review summary.
 3. Top risks in priority order.
-4. Safe next actions.
-5. Any unsupported or unverified behavior that must not be implied as complete.
+4. One proposed reversible next action with risk level.
+5. Confirmation request, or applied before/after plus rollback or `change_id`.
+6. Any unsupported or unverified behavior that must not be implied as complete.

docs/agents/prompts/project-organizer.md

@@ -9,16 +9,21 @@ project cleanup plan.
 - `fl://status`
 - `docs/agents/runtime-usage.md`
 - `docs/concepts/safety-contract.md`
+- `docs/concepts/default-safe-ux.md`
 
 ## Workflow
 
 1. Confirm bridge/session health.
 2. Read current channels, mixer, and playlist metadata through capped resources
    or domain tools.
 3. Run `fl_plan_project_cleanup`.
-4. Present the plan before mutation.
-5. Apply only one approved cleanup step at a time with
+4. Present a ranked plan, then propose exactly one safest reversible cleanup
+   step with a risk level.
+5. Ask for explicit confirmation before mutation.
+6. Apply only one approved cleanup step at a time with
    `fl_apply_project_cleanup_step`, and only when rollback/readback are clear.
+7. After the write, read back where supported, report before/after plus rollback
+   or `change_id`, then stop.
 
 ## Stop Conditions
 
@@ -32,5 +37,6 @@ Return:
 
 1. Current organization summary.
 2. Proposed groups/routes/colors/names.
-3. Safe step queue.
-4. Rollback/readback notes for any write-safe-required step.
+3. One proposed reversible step with risk level.
+4. Confirmation request, or applied before/after plus rollback or `change_id`.
+5. Rollback/readback notes for any write-safe-required step.

docs/agents/prompts/routing-review.md

@@ -9,15 +9,19 @@ or send/return structure in the current FL Studio project.
 - `fl://status`
 - `docs/agents/runtime-usage.md`
 - `docs/concepts/safety-contract.md`
+- `docs/concepts/default-safe-ux.md`
 
 ## Workflow
 
 1. Confirm bridge/session health.
 2. Use read-only state first.
 3. Run `fl_review_routing`.
 4. If cleanup is requested, run `fl_plan_routing_cleanup` before any mutation.
-5. Treat cleanup as a plan unless the user explicitly approves a rollback-backed
-   write step.
+5. Treat cleanup as a plan unless the user explicitly approves one exact
+   rollback-backed write step.
+6. Include a risk level for the proposed routing change.
+7. After one approved write, read back where supported, report before/after plus
+   rollback or `change_id`, then stop.
 
 ## Stop Conditions
 
@@ -30,5 +34,6 @@ Return:
 
 1. Current routing risks.
 2. Bus/send/grouping issues.
-3. Proposed cleanup steps.
-4. Which steps are read-only, dry-run, or write-safe-required.
+3. One proposed cleanup step with risk level.
+4. Whether the step is read-only, dry-run, or write-safe-required.
+5. Confirmation request, or applied before/after plus rollback or `change_id`.

docs/agents/runtime-usage.md

@@ -14,7 +14,11 @@ checks.
    or large tool calls.
 4. Choose a current workflow/domain tool. Avoid raw FL API calls and removed
    one-off aliases.
-5. For writes, plan the rollback unit before mutation.
+5. For write-capable workflows, scan/read-only first, propose exactly one
+   reversible next action with a risk level, and ask for explicit confirmation
+   before mutation.
+6. After one approved write, read back where supported, report before/after plus
+   rollback or `change_id`, then stop and wait for user direction.
 
 ## Tool-Choice Matrix
 
@@ -50,6 +54,9 @@ checks.
 
 - The selected tool path is current and Knowledgebase-informed.
 - Writes, if any, are rollback-backed and verified by readback where supported.
+- Write-capable workflows presented a risk level, asked for explicit
+  confirmation, applied only one reversible change per confirmation, and stopped
+  after the before/after report.
 - Unsupported API behavior is stated as a limit, not implied as completed work.
 - Docs, roadmap/API audit, and Knowledgebase are updated when public MCP
   behavior changes.

docs/concepts/default-safe-ux.md

@@ -0,0 +1,74 @@
+# Default Safe UX
+
+This policy defines the default assistant behavior for user-facing workflows
+that may mutate an FL Studio project. It is the product-level expression of the
+write-safety contract, not a second write layer.
+
+## Default Sequence
+
+For every workflow that could lead to a persistent FL Studio write, the
+assistant must:
+
+1. Scan/read-only first.
+2. Explain findings in normal user language.
+3. Propose exactly one safest reversible next action.
+4. Include a risk level for that proposal.
+5. Ask for explicit confirmation before any write.
+6. Apply at most one small reversible change per confirmation.
+7. Read back the affected state where supported.
+8. Show before/after plus rollback or `change_id` where available.
+9. Stop and wait for user direction.
+
+Dry-run and planning tools are the default for broad cleanup, export readiness,
+routing restructuring, project organization, or any request that could require
+several persistent writes.
+
+## Risk Levels
+
+| Risk level | Meaning | Default behavior |
+|---|---|---|
+| `read-only` | Reads state, files, or server context only. | Safe to run without write confirmation. |
+| `low` | One small rollback-backed write with clear target, readback, and restore path. | Propose one action, ask for confirmation, apply one change only. |
+| `medium` | Rollback-backed write, but the target is broader, grouped, or depends on state-sensitive API behavior. | Prefer dry-run; require explicit confirmation and stop after one rollback unit. |
+| `high` | Technically supported only with substantial project impact, weak readback, or risky target selection. | Do not apply by default; offer manual guidance or a smaller lower-risk alternative. |
+| `unsupported` | No safe API path, no rollback path, forbidden surface, or unclear evidence. | Do not write; explain the capability boundary and offer read-only, probe-only, or manual steps. |
+
+## Proposal Shape
+
+Every proposed write should include:
+
+- Finding: the observed problem and evidence.
+- Proposed action: one concrete reversible change.
+- Risk level: `low`, `medium`, `high`, or `unsupported`.
+- Safety basis: why rollback and readback are or are not available.
+- Confirmation request: ask the user to approve that exact change.
+
+Do not offer a queue of writes as the default next action. If a workflow finds
+many issues, rank them and propose only the safest reversible next step.
+
+## Applied Write Report Shape
+
+After an approved write, report:
+
+- What changed.
+- Before/after state.
+- Readback result, or the explicit readback limit.
+- `change_id`, rollback command, or rollback limitation.
+- What was skipped.
+- Stop state: the assistant is waiting for the user's next instruction.
+
+## Unsupported Capability Wording
+
+Unsupported operations should be described as product/API boundaries, not raw
+failures. Use wording like:
+
+```text
+I cannot apply that safely through fls-pilot because FL Studio does not expose a
+verified rollback/readback path for this operation. I can give you manual steps
+or run a read-only/probe-only check instead.
+```
+
+Forbidden user-facing surfaces remain forbidden even when a user asks for them:
+plugin loading/insertion, playlist clip editing, pattern or clip deletion,
+project open/new/save-as/render automation, raw API escape hatches, broad UI
+automation, unsafe automation recording, and full-FLP restore claims.

docs/concepts/safety-contract.md

@@ -43,6 +43,22 @@ Persistent writes may enter through only:
 - `safety.safe_piano_roll_write(...)` for undo-backed Piano Roll generated
   scripts with explicit readback limits.
 
+## Default Safe UX
+
+User-facing workflows must expose the write-safety contract as a conservative
+assistant flow:
+
+1. Scan/read-only first.
+2. Explain findings in normal user language.
+3. Propose exactly one safest reversible next action with a risk level.
+4. Ask for explicit confirmation before any persistent write.
+5. Apply at most one reversible change or one named rollback unit.
+6. Read back affected state where supported.
+7. Report before/after plus rollback or `change_id` where available.
+8. Stop and wait for user direction.
+
+See [Default Safe UX](default-safe-ux.md) for the risk levels and report shape.
+
 ## Stop And Fallback Rules
 
 - Do not guess normalized values, dB/Hz mappings, REC event IDs, track indices,

docs/user-guide/prompts.md

@@ -5,8 +5,10 @@ This page collects useful user prompts for working with fls-pilot. Users do not
 ## Module Examples
 
 Each example is a user prompt. The assistant may call several tools behind the
-scenes, and write tools should be described before execution when the change is
-not trivial.
+scenes. For workflows that may write to FL Studio, the default behavior is to
+scan/read-only first, propose one reversible action with a risk level, ask for
+explicit confirmation, apply at most one approved change, read back where
+supported, report before/after plus rollback or `change_id`, then stop.
 
 ### Transport And Bridge
 
@@ -37,8 +39,8 @@ Typical tools: `fl_get_project_state`, `fl_mixer`,
 Prompt:
 
 ```text
-Find channels that are not routed to mixer tracks, assign the kick to a free
-track, and write a four-on-the-floor kick pattern.
+Find channels that are not routed to mixer tracks. Propose the safest one-track
+routing fix with a risk level, but do not apply it until I confirm.
 ```
 
 Typical tools: `fl_detect_unassigned_channels`,
@@ -49,8 +51,8 @@ Typical tools: `fl_detect_unassigned_channels`,
 Prompt:
 
 ```text
-Create a named intro pattern, clone my main groove for the drop, color the drop
-pattern red, and add section markers at bars 1, 17, and 33.
+Review my pattern and playlist metadata first. Propose one low-risk reversible
+organization change, ask for confirmation, then stop.
 ```
 
 Typical tools: `fl_arrange_new_pattern`, `fl_arrange_clone_pattern`,
@@ -61,8 +63,8 @@ Typical tools: `fl_arrange_new_pattern`, `fl_arrange_clone_pattern`,
 Prompt:
 
 ```text
-Write an 8-bar melody in D Dorian to the selected channel, then quantize it to
-1/16 notes.
+Prepare an 8-bar D Dorian melody plan for the selected channel. Tell me the
+risk level and wait for confirmation before writing to the Piano Roll.
 ```
 
 Typical tools: `fl_scale_get`, `fl_piano_roll`, or the higher-level
@@ -73,8 +75,8 @@ Typical tools: `fl_scale_get`, `fl_piano_roll`, or the higher-level
 Prompt:
 
 ```text
-Find the EQ on the lead vocal, reduce harshness around 3 kHz, then show the
-before and after parameter values.
+Find the EQ on the lead vocal and propose one rollback-safe harshness reduction
+around 3 kHz. Include the risk level and wait for confirmation.
 ```
 
 Typical tools: `fl_plugin`, `fl_apply_eq_intent`.
@@ -87,7 +89,7 @@ Prompt:
 
 ```text
 Run Mix Review, explain the top three problems, and apply only the safest
-headroom fix first.
+headroom fix first after I confirm the exact proposed change.
 ```
 
 Typical tools: `fl_review_mix`, `fl_review_low_end_stereo`, `fl_gain_stage`,
@@ -98,8 +100,8 @@ Typical tools: `fl_review_mix`, `fl_review_low_end_stereo`, `fl_gain_stage`,
 Prompt:
 
 ```text
-Group all drum tracks into a Drums bus, mute the bass group for comparison,
-then undo the mute when I say so.
+Review routing first. Propose one low-risk rollback-safe routing change with a
+risk level and wait for confirmation before applying it.
 ```
 
 Typical tools: `fl_detect_cleanup_candidates`, `fl_group_tracks`,
@@ -131,6 +133,23 @@ Typical tools: `fl_analyze_audio`, `fl_suggest_preset`,
 
 ## Useful Prompt Patterns
 
+### Safety-First Examples
+
+```text
+Scan my mix first. Do not change anything yet. Tell me the safest next action,
+its risk level, and offer only one reversible fix.
+```
+
+```text
+Review the routing first. Give me a read-only diagnosis and one low-risk
+rollback-safe routing change to approve.
+```
+
+```text
+Prepare this project for export. Report blockers first, use dry-run planning,
+and stop before applying anything.
+```
+
 ```text
 Scan first, do not change anything yet.
 ```

docs/user-guide/workflows.md

@@ -10,21 +10,24 @@ The normal workflow is conversational:
    headroom issue".
 2. The assistant reads `fl://agent-briefing`, checks `fl://status`, and uses
    relevant resources such as `fl://mixer`, `fl://channels`, or specific tools.
-3. For risky or multi-step work, the assistant explains what it plans to do and
-   which changes are reversible.
-4. The assistant applies one approved change or one named rollback unit.
-5. The assistant reports what changed, what was skipped, and how to roll it
-   back.
+3. The assistant scans/read-only first and explains findings in normal user
+   language.
+4. The assistant proposes exactly one safest reversible next action with a risk
+   level and asks for explicit confirmation.
+5. After confirmation, the assistant applies at most one reversible change or
+   one named rollback unit.
+6. The assistant reads back where supported, reports before/after plus rollback
+   or `change_id`, then stops and waits.
 
 Users do not need to know tool names, but direct tool names are available for
 precision. These are both valid:
 
 ```text
-Please rename mixer track 8 to Drums and color it blue.
+Please rename mixer track 8 to Drums.
 ```
 
 ```text
-Use fl_mixer with action set_name on track 8, then fl_mixer with action set_color on track 8.
+Use fl_mixer with action set_name on track 8.
 ```
 
 ## Safety Classes
@@ -48,14 +51,28 @@ For any persistent FL Studio write, the assistant should follow this sequence:
 5. Log restore data.
 6. Report what changed and how it can be rolled back.
 
+## Default Safe UX
+
+The default assistant posture is scan/read-only first. A write-capable workflow
+should propose one reversible action at a time, include a risk level
+(`read-only`, `low`, `medium`, `high`, or `unsupported`), and ask for explicit
+confirmation before calling a write tool.
+
+After an approved write, the assistant should show before/after, readback status
+where supported, and rollback or `change_id` information. It should then stop
+instead of continuing through a cleanup queue.
+
 ## Recommended Assistant Behavior
 
 - Prefer diagnosis before mutation.
 - Use dry-run mode for broad cleanup or export-readiness work.
-- Apply only one approved change or one named rollback unit at a time when risk is non-trivial.
+- Apply only one approved reversible change or one named rollback unit per
+  confirmation.
 - Clearly state skipped actions when FL Studio API boundaries prevent safe automation.
 
 ## Related Pages
 
 - [Prompts](prompts.md) for practical examples.
+- [Default Safe UX](../concepts/default-safe-ux.md) for the risk levels and
+  response shape.
 - [Tool Reference](tool-reference.md) for exact tool names and safety annotations.

mkdocs.yml

@@ -31,6 +31,7 @@ nav:
   - Concepts:
       - Architecture: concepts/architecture.md
       - Safety Contract: concepts/safety-contract.md
+      - Default Safe UX: concepts/default-safe-ux.md
       - API Capability and Safety Audit: concepts/api-capability-audit.md
       - Senior Developer Audit Criteria: concepts/senior-dev-audit-criteria.md
   - Engineering: