prometeu-studio/discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md

id	ticket	title	created	tags
LSN-0004	studio-docs-import	Assets workspace mental model legacy lesson	2026-03-26	studio legacy-import assets-workspace asset-first

Context

Legacy import from docs/studio/learn/mental-model-assets-workspace.md.

This lesson keeps the didactic framing for the Assets workspace as an asset-first, path-aware Studio surface over the packer model.

Relevant specs:

• docs/studio/specs/4. Assets Workspace Specification.md
• docs/packer/learn/mental-model-packer.md

Key Decisions

The assets workspace exists to teach the asset model, not to act as a nicer file browser

What: The Assets workspace should treat asset identity as primary, path as supporting context, and the selected-asset view as a didactic explanation surface ordered around what the asset is, what it produces, what it contains, what is wrong, and what actions are available. Why: A raw file-tree framing teaches the wrong mental model for packer-backed assets. The Studio needs to make managed assets, runtime-facing output, previewable inputs, and operational state understandable from the UI itself. Trade-offs: Asset-first navigation requires custom navigator semantics and stronger didactic structure, but it produces a clearer and more accurate Studio view over the project.

Patterns and Algorithms

• Use a custom asset navigator rather than a generic file explorer.
• Keep grouping/path visible as supporting context while preserving asset identity as primary.
• Present the selected asset in a fixed teaching order: Summary, Runtime Contract, Inputs / Preview, Diagnostics, Actions.
• Treat preview as part of the bridge between the conceptual asset model and real project materials.

Pitfalls

• Turning the workspace into a filesystem explorer with badges.
• Making path the true identity instead of the asset.
• Showing only diagnostics and forgetting the asset model itself.
• Treating orphan as equivalent to broken.
• Hiding runtime-facing information behind technical dumps.

Takeaways

• The key durable rule is asset-first, not file-first.
• Path-awareness is supporting context, not the primary identity model.
• Legacy source attribution: docs/studio/learn/mental-model-assets-workspace.md.