---
id: LSN-0004
ticket: studio-docs-import
title: Assets workspace mental model legacy lesson
created: 2026-03-26
tags:
  - 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`.