---
id: LSN-0003
ticket: studio-docs-import
title: Asset mutations legacy lesson
created: 2026-03-26
tags:
  - studio
  - legacy-import
  - asset-mutations
  - preview-first
---

## Context

Legacy import from `docs/studio/learn/mental-model-asset-mutations.md`.

This lesson preserves the didactic rule for how Studio must present asset mutations in the `Assets` workspace, aligned with `docs/studio/specs/4. Assets Workspace Specification.md` and packer integration boundaries.

## Key Decisions

### Sensitive asset mutations must be preview-first

**What:** Studio should treat destructive or relocational asset mutations as preview-first workflows, keep registry impact and workspace impact distinct, and reserve modal confirmation for high-risk final commits rather than using modals as a substitute for review.
**Why:** Users lose trust quickly when the UI hides whether a mutation affects only registry state or also the physical workspace. Inline staged review keeps the user anchored in the selected asset and its consequences.
**Trade-offs:** Inline review takes more UI structure than a modal-only flow, but it produces a clearer and safer operational model for both single-asset and batch mutations.

## Patterns and Algorithms

- Show affected assets, scope of impact, creations/moves/deletions, blockers, warnings, and safe fixes before apply.
- Use an inline staged panel as the default review surface.
- Keep `blockers`, `warnings`, and `safe fixes` visually and semantically distinct.
- For batch operations, show an aggregate summary first and drill-down detail second.
- Reflect lifecycle milestones such as `preview ready`, `action applied`, and `action failed` at shell scope while keeping review inside the workspace.

## Pitfalls

- Destructive apply without preview.
- Using raw logs as the main explanation surface.
- Mixing safe fixes with deletes as if they were the same class of action.
- Showing technical diff data without user-facing interpretation.
- Forcing modal-only review for ordinary mutation flows.

## Takeaways

- Preview is the review; modal confirmation is only the final safety gate for high-risk commits.
- Registry impact and workspace impact must never blur in Studio mutation UX.
- Legacy source attribution: `docs/studio/learn/mental-model-asset-mutations.md`.