prometeu-studio/docs/studio/decisions/004-asset-workspace-information-architecture-decision.md

Asset Workspace Information Architecture Decision

Status

Accepted

Date or Cycle

Studio asset workspace wave 01.1

Context

The Studio shell, UI foundations, and component rules are already defined in the Studio specifications.

The remaining open issue is how the Assets workspace should present packer-managed assets to the user.

The packer domain already establishes that:

• the managed unit is the asset, not the raw file;
• each managed asset has a root and a declaration contract;
• assets may aggregate many internal inputs;
• diagnostics, preview/apply flows, and runtime-facing output contracts already exist at the domain level.

The Studio must therefore present the Assets workspace as a didactic view over the packer model, not as a generic filesystem explorer.

Decision

The Studio Assets workspace is asset-first, path-aware, and taught through a custom visual Asset Tree / Asset Navigator.

The baseline workspace layout is:

• a custom visual Asset Tree / Asset Navigator on the left;
• asset details in the main panel;
• diagnostics and action surfaces attached to the selected asset;
• broader Studio activity and progress outside the asset details body when possible.

The primary navigation unit is the managed asset, not the raw file.

Filesystem organization remains visible and usable as supporting context, but it is not the primary identity model of the workspace.

Invariants and Constraints

• The left navigation surface must not be a generic file tree or a plain filesystem browser clone.
• The navigator must be asset-aware and must teach the packer model.
• Asset root path must remain visible for the selected asset.
• The navigator may group assets by path or parent folder to preserve spatial awareness of the project.
• Grouping nodes may reflect path structure, but asset nodes remain the primary navigable unit.
• The selected asset view must include a location section for asset root and relocational actions.
• The selected asset view must include an inputs/preview section that exposes internal files and folders as part of the asset.
• Filesystem structure is supporting context, not the primary identity model.

Visual Navigation Rules

• The Assets workspace must use a custom Asset Tree / Asset Navigator component.
• Asset nodes must carry strong visual semantics such as icons, badges, and explicit state styling.
• The navigator must clearly surface managed/orphan state, preload intent, diagnostics presence, and broad asset family where available.
• Optional expansion of an asset into internal inputs is allowed as supporting inspection, not as a replacement for asset-first navigation.

Didactic Requirement

The Assets workspace must act as a didactic helper for the packer.

This means the workspace must help the user understand:

• what the managed asset is;
• where the asset root lives;
• which internal inputs belong to that asset;
• what the asset declares toward the runtime-facing contract.

The workspace must therefore explain the packer model through structure and presentation, not only through diagnostics text.

Explicit Non-Decisions

This decision does not yet define:

• the exact filter and selection model of the asset list;
• the exact action layout of the selected asset;
• the detailed event, progress, and logging surfaces of the workspace;
• the preview/confirm/apply flow for mutating operations.

Those belong to the follow-up decisions for 01.2 through 01.5.

Propagation Targets

• docs/studio/agendas/01.2. Asset List, Filters, and Selection Model Agenda.md
• docs/studio/agendas/01.3. Asset Details, Diagnostics, and Action Surface Agenda.md
• docs/studio/specs/ for the eventual Asset Workspace specification
• the first implementation plan for a concrete AssetsWorkspace

Validation Notes or Examples

A good baseline outcome is:

• a user can browse the project through asset-aware groups;
• a selected asset clearly shows identity, location, inputs, and previewable materials;
• the workspace feels like a visual helper for the packer rather than a raw file explorer with extra buttons.