From fcfe732eacaf651f84e824f811a4166813a0e893 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 11 Mar 2026 16:16:02 +0000 Subject: [PATCH] assets workspace agendas --- ...rkspace Information Architecture Agenda.md | 30 +++++- docs/studio/agendas/README.md | 15 +-- ...space-information-architecture-decision.md | 96 +++++++++++++++++++ docs/studio/decisions/README.md | 4 +- 4 files changed, 135 insertions(+), 10 deletions(-) create mode 100644 docs/studio/decisions/004-asset-workspace-information-architecture-decision.md diff --git a/docs/studio/agendas/01.1. Asset Workspace Information Architecture Agenda.md b/docs/studio/agendas/01.1. Asset Workspace Information Architecture Agenda.md index 3dbd8264..15d2802d 100644 --- a/docs/studio/agendas/01.1. Asset Workspace Information Architecture Agenda.md +++ b/docs/studio/agendas/01.1. Asset Workspace Information Architecture Agenda.md @@ -2,7 +2,7 @@ ## Status -Open +Closed ## Purpose @@ -62,13 +62,39 @@ Prefer Option A. Recommended baseline: -- asset list or registry-aware browser on the left, +- 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 activity/progress outside the asset details body when possible. +The Assets workspace must remain asset-first, but it must not hide physical organization. + +Baseline path and structure rules: + +- the primary navigation unit is the managed asset, not the raw file; +- the left navigation surface should not be a generic file tree; it should be an asset-aware tree that teaches the packer model; +- asset root path must remain visible for the selected asset; +- the asset list may be grouped by path or parent folder to preserve project structure awareness; +- the selected asset view should include a location section for asset root and relocational actions; +- the selected asset view should 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. + +Baseline visual navigation rules: + +- the Assets workspace should use a custom `Asset Tree` / `Asset Navigator` component rather than a plain `TreeView` clone; +- asset nodes should carry strong visual semantics such as icons, badges, and state styling; +- the navigator should clearly surface managed/orphan state, preload intent, diagnostics presence, and broad asset family where available; +- grouping nodes may reflect path structure, but asset nodes remain the primary navigable unit; +- optional expansion of an asset into internal inputs is allowed as supporting inspection, not as a replacement for asset-first navigation. + +This exists so the Assets workspace teaches the packer model while still letting users understand and organize the project's directory layout. + ## Expected Follow-up - an information architecture decision, - a workspace spec, - a PR/plan for the first concrete `AssetsWorkspace`. + +## Resolution + +Closed by [`../decisions/004-asset-workspace-information-architecture-decision.md`](../decisions/004-asset-workspace-information-architecture-decision.md). diff --git a/docs/studio/agendas/README.md b/docs/studio/agendas/README.md index 587e28bb..432b762e 100644 --- a/docs/studio/agendas/README.md +++ b/docs/studio/agendas/README.md @@ -6,19 +6,20 @@ This directory contains active Studio discussion agendas. The initial Studio UI planning wave is: -1. [`01.1. Asset Workspace Information Architecture Agenda.md`](./01.1.%20Asset%20Workspace%20Information%20Architecture%20Agenda.md) -2. [`01.2. Asset List, Filters, and Selection Model Agenda.md`](./01.2.%20Asset%20List,%20Filters,%20and%20Selection%20Model%20Agenda.md) -3. [`01.3. Asset Details, Diagnostics, and Action Surface Agenda.md`](./01.3.%20Asset%20Details,%20Diagnostics,%20and%20Action%20Surface%20Agenda.md) -4. [`01.4. Background Events, Progress, and Activity Feed Agenda.md`](./01.4.%20Background%20Events,%20Progress,%20and%20Activity%20Feed%20Agenda.md) -5. [`01.5. Preview, Confirm, and Apply Mutation Flows Agenda.md`](./01.5.%20Preview,%20Confirm,%20and%20Apply%20Mutation%20Flows%20Agenda.md) +1. [`01.2. Asset List, Filters, and Selection Model Agenda.md`](./01.2.%20Asset%20List,%20Filters,%20and%20Selection%20Model%20Agenda.md) +2. [`01.3. Asset Details, Diagnostics, and Action Surface Agenda.md`](./01.3.%20Asset%20Details,%20Diagnostics,%20and%20Action%20Surface%20Agenda.md) +3. [`01.4. Background Events, Progress, and Activity Feed Agenda.md`](./01.4.%20Background%20Events,%20Progress,%20and%20Activity%20Feed%20Agenda.md) +4. [`01.5. Preview, Confirm, and Apply Mutation Flows Agenda.md`](./01.5.%20Preview,%20Confirm,%20and%20Apply%20Mutation%20Flows%20Agenda.md) Recommended discussion order: -`01.1 -> 01.2 -> 01.3 -> 01.4 -> 01.5` +`01.2 -> 01.3 -> 01.4 -> 01.5` The shell, UI foundations, and components admission baselines were already consolidated into [`../specs/`](../specs/) and [`../learn/`](../learn/). -The remaining order closes the asset workspace structure first, and only after that the detailed interaction flows. +The asset workspace information architecture baseline is already closed in [`../decisions/004-asset-workspace-information-architecture-decision.md`](../decisions/004-asset-workspace-information-architecture-decision.md). + +The remaining order closes the detailed interaction model on top of that structure. ## Purpose diff --git a/docs/studio/decisions/004-asset-workspace-information-architecture-decision.md b/docs/studio/decisions/004-asset-workspace-information-architecture-decision.md new file mode 100644 index 00000000..e001f60c --- /dev/null +++ b/docs/studio/decisions/004-asset-workspace-information-architecture-decision.md @@ -0,0 +1,96 @@ +# 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. diff --git a/docs/studio/decisions/README.md b/docs/studio/decisions/README.md index d857a03b..a2735648 100644 --- a/docs/studio/decisions/README.md +++ b/docs/studio/decisions/README.md @@ -2,7 +2,9 @@ This directory contains Studio decision records. -There are currently no retained Studio decision records. +## Active Decision Records + +1. [`004-asset-workspace-information-architecture-decision.md`](./004-asset-workspace-information-architecture-decision.md) The first Studio decision wave was already consolidated into: