# Mental Model: Asset Mutations

## The Problem

Asset mutations are easy to get wrong in a Studio UI.

Why?

Because some actions only update registry state, while others change the physical workspace.

If the Studio hides that difference, users lose trust quickly.

## The Rule

Sensitive asset mutations are `preview-first`.

That is the most important rule.

The Studio must not perform destructive or relocational asset changes as if they were harmless button clicks.

## What The User Must Understand Before Apply

Before applying a mutation, the user should be able to answer:

- Which assets are affected?
- Is this touching only the registry, or also the workspace?
- Will something be created, moved, or deleted?
- Are there blockers?
- Are there warnings?
- Is this a safe fix or a risky mutation?

If the UI cannot answer those questions, the mutation flow is not ready.

## Why Inline Review Is The Baseline

The default review surface is an inline staged panel, not a modal.

That keeps the user anchored in the asset and its surrounding context.

It lets the user compare:

- the selected asset,
- the diagnostics,
- the proposed changes,
- and the action consequences

without bouncing between unrelated windows.

## Why Modals Still Exist

Modals are still useful, but only for high-risk final commits.

Examples:

- destructive delete;
- major relocation;
- other strongly irreversible actions.

The mistake would be using modals as a substitute for review.

Preview is the review.

Modal confirmation is only the final safety gate when the risk is high enough.

## The Most Important Distinction

The Studio must distinguish:

- registry impact
- workspace impact

This is one of the most important didactic duties of the asset workspace.

A user should never have to guess whether a button:

- merely forgets an asset from management,
- or actually deletes or moves files.

## Blockers, Warnings, and Safe Fixes

These categories must stay visually and semantically separate.

They are not interchangeable kinds of “message”.

- `blockers` stop the apply path;
- `warnings` tell the user the action is still meaningful but risky or noteworthy;
- `safe fixes` are low-risk corrections and should not be grouped as if they were destructive operations.

If those three collapse into one list, users stop trusting the flow.

## Batch Operations

Batch operations are not just “single asset, repeated many times”.

They need:

- an aggregate summary first,
- then drill-down detail.

Without that, the flow becomes unreadable and users either miss risk or abandon the tool.

## How Activity Fits In

The preview itself belongs to the workspace.

But the shell should still reflect lifecycle milestones such as:

- preview ready;
- action applied;
- action failed.

That way the workspace remains the place of review, while the shell keeps the broader operational timeline visible.

## Common Failure Modes

Avoid these:

- destructive apply without preview;
- using raw logs as the main explanation surface;
- mixing safe fixes with deletes;
- showing technical diff data with no user-facing interpretation;
- forcing the user into modal-only flows for ordinary review.

## Read With

1. [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
2. [`mental-model-assets-workspace.md`](./mental-model-assets-workspace.md)
3. [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)