assets workspace agendas

This commit is contained in:
2026-03-24 13:42:40 +00:00
parent fcfe732eac
commit 3c5f949910
20 changed files with 919 additions and 444 deletions
@@ -1,100 +0,0 @@
# Asset Workspace Information Architecture Agenda
## Status
Closed
## Purpose
Define the baseline information architecture of the Assets workspace.
The goal is to decide which panels and data views the user needs in order to manage assets through Studio services rather than through ad hoc file inspection.
## Domain Owner
`docs/studio`
## Current Code Context
`WorkspaceId.ASSETS` is still backed by a placeholder workspace.
Meanwhile, the packer domain already defines:
- managed assets,
- diagnostics,
- preview/apply mutation flows,
- an asset event lane,
- structured service responses.
The Assets workspace must therefore be designed as a Studio view over those services, not as a file browser clone.
## Core Questions
1. Which panels are baseline for the Assets workspace?
2. What should the primary unit of navigation be: asset list, tree, or diagnostic inbox?
3. Which information should always be visible for the selected asset?
4. How should diagnostics, preload, and managed/orphan state surface in the workspace?
5. What belongs in the workspace body versus a global Studio activity region?
## Options
### Option A
List-first asset workspace with details panel and diagnostics section.
### Option B
File-tree-first asset workspace with asset details as a secondary mode.
### Option C
Dashboard-first asset workspace focused on diagnostics and actions.
## Tradeoffs
- Option A aligns best with the managed asset model already defined by the packer.
- Option B is familiar, but risks collapsing the Studio into a glorified file explorer.
- Option C is useful for operations, but weak as a day-to-day authoring workspace.
## Recommendation
Prefer Option A.
Recommended baseline:
- 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).
@@ -1,50 +0,0 @@
# Asset List, Filters, and Selection Model Agenda
## Status
Open
## Purpose
Define how users navigate and select assets inside the Assets workspace.
## Domain Owner
`docs/studio`
## Current Code Context
The Studio shell already has workspace switching, but no concrete Assets workspace.
The packer model already distinguishes:
- managed assets,
- orphan declarations,
- diagnostics,
- preload intent,
- stable `asset_id` and logical `asset_name`.
The list model should make those distinctions visible without forcing users into raw registry inspection.
## Core Questions
1. Should the main asset view be flat, grouped, or tree-based?
2. Which filters are baseline?
3. How should the current selection be preserved across refreshes and background events?
4. How should empty, loading, and error states appear?
5. How much of the filesystem path should be exposed in the primary list?
## Recommendation
Baseline direction:
- registry-aware flat or grouped asset list,
- lightweight filters for `managed`, `orphan`, `diagnostics`, and `preload`,
- selection preserved by stable identity when possible,
- path treated as supporting information, not primary identity.
## Expected Follow-up
- a decision on the asset list model,
- a UI state spec for selection and filtering,
- a plan for list rendering and refresh behavior.
@@ -1,47 +0,0 @@
# Asset Details, Diagnostics, and Action Surface Agenda
## Status
Open
## Purpose
Define what the selected asset view shows and which actions are directly available there.
## Domain Owner
`docs/studio`
## Current Code Context
The packer service model already expects:
- structured diagnostics,
- preview/apply mutation flows,
- operations such as `register_asset`, `adopt_asset`, `forget_asset`, `remove_asset`, `doctor`, and `build`.
The selected asset view should therefore be designed around explicit state and explicit actions.
## Core Questions
1. What summary information is always visible for the selected asset?
2. Which diagnostics belong inline versus in a separate panel?
3. Which actions should be primary, secondary, or hidden behind confirmation?
4. How should managed and orphan assets differ visually?
5. How should runtime-facing information such as preload and output format appear?
## Recommendation
Baseline direction:
- a summary card for identity and state,
- explicit diagnostics panel,
- explicit action group,
- clear differentiation between safe actions and sensitive mutations,
- no hidden automatic repair behavior.
## Expected Follow-up
- a decision on asset details composition,
- a spec for diagnostics and actions in the workspace,
- a plan for Studio service integration in the asset details view.
@@ -1,81 +0,0 @@
# Background Events, Progress, and Activity Feed Agenda
## Status
Open
## Purpose
Define how Studio surfaces background asset activity, progress, and logs coming from the packer event lane.
## Domain Owner
`docs/studio`
## Current Code Context
The packer already defines a Studio-facing asset event lane with events such as:
- `asset_discovered`
- `asset_changed`
- `diagnostics_updated`
- `build_started`
- `build_finished`
- `cache_hit`
- `cache_miss`
- `preview_ready`
- `action_applied`
- `action_failed`
- `progress_updated`
Current `BuilderWorkspace` already contains a logs area, which is a useful signal but not yet a coherent Studio-wide activity model.
## Core Questions
1. Should activity be global to the Studio shell or local to the Assets workspace?
2. How should progress, logs, and state changes be distinguished?
3. What should persist in history versus only appear transiently?
4. How noisy should automatic background reporting be?
5. How should action failures and blockers surface?
## Recommendation
Baseline direction:
- global activity region in the Studio shell,
- structured event rendering rather than raw log dumping,
- progress visible both inline and in the activity surface,
- recent actionable failures retained until acknowledged,
- normal background noise summarized rather than streamed endlessly,
- use the right-side panel for structured activity and progress,
- reserve the bottom region for logs and detailed textual output,
- support a tabbed right-side panel so activity can coexist with other contextual surfaces such as diagnostics or inspector views.
## Distinction Between Activity and Logs
Baseline distinction:
- `activity` is the structured operational timeline of the Studio;
- `logs` are detailed textual outputs from compiler, packer, and other services.
Examples of `activity`:
- project opened;
- asset scan started;
- diagnostics updated;
- build started or finished;
- preview ready;
- action applied or failed.
Examples of `logs`:
- compiler output;
- packer trace output;
- stack traces;
- detailed technical diagnostics and execution text.
## Expected Follow-up
- a decision on activity feed and progress UX,
- a shell or integration spec,
- a plan for event rendering and background updates.
@@ -1,47 +0,0 @@
# Preview, Confirm, and Apply Mutation Flows Agenda
## Status
Open
## Purpose
Define how Studio stages sensitive asset mutations before applying them.
## Domain Owner
`docs/studio`
## Current Code Context
The packer model already requires:
- preview/apply for sensitive mutations,
- explicit consent for destructive or relocational changes,
- structured responses with blockers, proposed actions, and applied actions.
The Studio must turn that into clear interaction flows instead of accidental one-click mutations.
## Core Questions
1. Which actions require preview by default?
2. What should a preview surface show before confirmation?
3. How should blockers, warnings, and safe fixes be separated?
4. When does the user see a modal confirmation versus an inline staged action panel?
5. How should batch operations differ from single-asset mutations?
## Recommendation
Baseline direction:
- use preview-first flows for sensitive mutations,
- show proposed actions and blockers explicitly,
- keep safe fixes distinct from destructive actions,
- favor inline staged review where possible,
- reserve modal confirmation for high-risk commits such as delete or relocation.
## Expected Follow-up
- a mutation-flow decision,
- a Studio interaction spec,
- a plan for preview/apply service integration.
+2 -17
View File
@@ -2,24 +2,9 @@
This directory contains active Studio discussion agendas.
## Active Agendas
There are currently no active Studio agendas.
The initial Studio UI planning wave is:
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.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 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.
The shell, UI foundations, components admission baselines, and the first asset workspace wave were already consolidated into [`../specs/`](../specs/) and [`../learn/`](../learn/).
## Purpose