prometeu-studio/docs/studio/learn/mental-model-assets-workspace.md

Mental Model: Assets Workspace

Why This Workspace Exists

The Assets workspace is not a nicer file browser.

It exists to make the packer model understandable and usable from the Studio.

That means the workspace must help a contributor answer questions like:

• What is the managed asset here?
• Where does it live?
• Which files belong to it?
• What does it produce toward the runtime?
• Is it managed, orphaned, preload-marked, or diagnostically unhealthy?

If the workspace answered those questions only by showing folders and files, it would teach the wrong mental model.

The Core Shift

The key shift is:

• not file-first
• but asset-first

An asset may contain many files.

Those files still matter, but they matter as inputs of an asset, not as the primary unit of identity.

So the workspace is designed to feel like:

• a structured asset navigator,
• plus a didactic explanation surface for the currently selected asset.

Why It Is Still Path-Aware

Asset-first does not mean filesystem-blind.

People still organize projects by directories.

They still need to know:

• where the asset root lives;
• which broader folder group it belongs to;
• how to reason about the project layout.

That is why the workspace remains path-aware.

The important nuance is:

• path is supporting context
• asset identity is primary

What The Left Side Teaches

The left-side navigator is a custom Asset Tree / Asset Navigator.

It teaches the model visually:

• groups may reflect location or parent folders,
• asset nodes are the real unit of navigation,
• icons and badges tell the story quickly,
• orphan and managed assets can coexist without becoming ambiguous.

This is better than a raw file tree because the user learns the packer model by looking at the navigation itself.

What The Main Area Teaches

The selected asset view is intentionally structured in a fixed order:

1. Summary
2. Runtime Contract
3. Inputs / Preview
4. Diagnostics
5. Actions

That order matters.

It starts by explaining what the asset is, then what it produces, then what it contains, then what is wrong, and finally what the user can do.

That is a teaching sequence, not just a layout sequence.

Why Preview Matters

Preview is not decorative.

Preview is part of how the workspace bridges the conceptual asset model with the real materials inside the project.

Examples:

• an image bank should let the user inspect images and palettes;
• an audio asset should let the user inspect sound inputs;
• text-like artifacts should be inspectable as text when that helps understanding.

This makes the workspace feel grounded in real project materials while still preserving an asset-first model.

What To Avoid

Common mistakes:

• turning the workspace into a raw filesystem explorer with extra badges;
• making path the true identity instead of the asset;
• showing only diagnostics and forgetting the actual asset model;
• treating orphan as if it meant broken;
• hiding runtime-facing information behind technical dumps.

Practical Read Order

Read these together:

1. ../specs/4. Assets Workspace Specification.md
2. mental-model-asset-mutations.md
3. ../../packer/learn/mental-model-packer.md

That path explains:

• what the packer believes,
• how the Studio presents it,
• and how the user should reason about asset operations.