From 3c5f9499104e8f9db54f4e07e5c2c9a6122bc117 Mon Sep 17 00:00:00 2001
From: bQUARKz <bquarkz@gmail.com>
Date: Wed, 11 Mar 2026 16:34:59 +0000
Subject: [PATCH] assets workspace agendas

---
 docs/studio/README.md                         |   2 +-
 ...rkspace Information Architecture Agenda.md | 100 ------
 ...st, Filters, and Selection Model Agenda.md |  50 ---
 ... Diagnostics, and Action Surface Agenda.md |  47 ---
 ...nts, Progress, and Activity Feed Agenda.md |  81 -----
 ...onfirm, and Apply Mutation Flows Agenda.md |  47 ---
 docs/studio/agendas/README.md                 |  19 +-
 ...space-information-architecture-decision.md |  96 ------
 docs/studio/decisions/README.md               |   6 +-
 docs/studio/learn/README.md                   |   2 +
 .../learn/mental-model-asset-mutations.md     | 128 ++++++++
 .../learn/mental-model-assets-workspace.md    | 119 +++++++
 ...-workspace-foundation-and-service-state.md |  71 +++++
 ...-navigator-search-filters-and-selection.md |  72 +++++
 ...cted-asset-details-contract-and-preview.md |  80 +++++
 ...-activity-progress-and-logs-integration.md |  63 ++++
 ...sets-staged-mutations-preview-and-apply.md |  75 +++++
 docs/studio/pull-requests/README.md           |   9 +
 .../4. Assets Workspace Specification.md      | 292 ++++++++++++++++++
 docs/studio/specs/README.md                   |   4 +-
 20 files changed, 919 insertions(+), 444 deletions(-)
 delete mode 100644 docs/studio/agendas/01.1. Asset Workspace Information Architecture Agenda.md
 delete mode 100644 docs/studio/agendas/01.2. Asset List, Filters, and Selection Model Agenda.md
 delete mode 100644 docs/studio/agendas/01.3. Asset Details, Diagnostics, and Action Surface Agenda.md
 delete mode 100644 docs/studio/agendas/01.4. Background Events, Progress, and Activity Feed Agenda.md
 delete mode 100644 docs/studio/agendas/01.5. Preview, Confirm, and Apply Mutation Flows Agenda.md
 delete mode 100644 docs/studio/decisions/004-asset-workspace-information-architecture-decision.md
 create mode 100644 docs/studio/learn/mental-model-asset-mutations.md
 create mode 100644 docs/studio/learn/mental-model-assets-workspace.md
 create mode 100644 docs/studio/pull-requests/PR-05a-assets-workspace-foundation-and-service-state.md
 create mode 100644 docs/studio/pull-requests/PR-05b-asset-navigator-search-filters-and-selection.md
 create mode 100644 docs/studio/pull-requests/PR-05c-selected-asset-details-contract-and-preview.md
 create mode 100644 docs/studio/pull-requests/PR-05d-assets-activity-progress-and-logs-integration.md
 create mode 100644 docs/studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md
 create mode 100644 docs/studio/specs/4. Assets Workspace Specification.md

diff --git a/docs/studio/README.md b/docs/studio/README.md
index 441b63ba..2fd70a41 100644
--- a/docs/studio/README.md
+++ b/docs/studio/README.md
@@ -108,6 +108,6 @@ The preferred Studio documentation flow is:
 - `specs/` stores the normative Studio contract.
 - `learn/` stores teaching-oriented Studio knowledge.
 
-The current Studio core has already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). The `agendas/` and `decisions/` directories remain available for future cycles.
+The current Studio core and first `Assets` workspace wave have already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). The `agendas/` and `decisions/` directories remain available for future cycles.
 
 If implementation exposes a missing UI or interaction decision, stop and return to `agendas/` or `decisions/`.
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
deleted file mode 100644
index 15d2802d..00000000
--- a/docs/studio/agendas/01.1. Asset Workspace Information Architecture Agenda.md	
+++ /dev/null
@@ -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).
diff --git a/docs/studio/agendas/01.2. Asset List, Filters, and Selection Model Agenda.md b/docs/studio/agendas/01.2. Asset List, Filters, and Selection Model Agenda.md
deleted file mode 100644
index cb1b94a6..00000000
--- a/docs/studio/agendas/01.2. Asset List, Filters, and Selection Model Agenda.md	
+++ /dev/null
@@ -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.
diff --git a/docs/studio/agendas/01.3. Asset Details, Diagnostics, and Action Surface Agenda.md b/docs/studio/agendas/01.3. Asset Details, Diagnostics, and Action Surface Agenda.md
deleted file mode 100644
index 0ed6438d..00000000
--- a/docs/studio/agendas/01.3. Asset Details, Diagnostics, and Action Surface Agenda.md	
+++ /dev/null
@@ -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.
diff --git a/docs/studio/agendas/01.4. Background Events, Progress, and Activity Feed Agenda.md b/docs/studio/agendas/01.4. Background Events, Progress, and Activity Feed Agenda.md
deleted file mode 100644
index 81af62e5..00000000
--- a/docs/studio/agendas/01.4. Background Events, Progress, and Activity Feed Agenda.md	
+++ /dev/null
@@ -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.
diff --git a/docs/studio/agendas/01.5. Preview, Confirm, and Apply Mutation Flows Agenda.md b/docs/studio/agendas/01.5. Preview, Confirm, and Apply Mutation Flows Agenda.md
deleted file mode 100644
index 9a4d215f..00000000
--- a/docs/studio/agendas/01.5. Preview, Confirm, and Apply Mutation Flows Agenda.md	
+++ /dev/null
@@ -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.
diff --git a/docs/studio/agendas/README.md b/docs/studio/agendas/README.md
index 432b762e..6207b736 100644
--- a/docs/studio/agendas/README.md
+++ b/docs/studio/agendas/README.md
@@ -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
 
diff --git a/docs/studio/decisions/004-asset-workspace-information-architecture-decision.md b/docs/studio/decisions/004-asset-workspace-information-architecture-decision.md
deleted file mode 100644
index e001f60c..00000000
--- a/docs/studio/decisions/004-asset-workspace-information-architecture-decision.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# 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 a2735648..f215135b 100644
--- a/docs/studio/decisions/README.md
+++ b/docs/studio/decisions/README.md
@@ -2,11 +2,9 @@
 
 This directory contains Studio decision records.
 
-## Active Decision Records
+There are currently no retained Studio 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:
+The first Studio decision wave and the first asset workspace wave were already consolidated into:
 
 - normative specifications under [`../specs/`](../specs/)
 - didactic material under [`../learn/`](../learn/)
diff --git a/docs/studio/learn/README.md b/docs/studio/learn/README.md
index ea37d264..2e4740ec 100644
--- a/docs/studio/learn/README.md
+++ b/docs/studio/learn/README.md
@@ -48,3 +48,5 @@ Start here:
 
 1. [`mental-model-studio-shell.md`](./mental-model-studio-shell.md)
 2. [`mental-model-studio-events-and-components.md`](./mental-model-studio-events-and-components.md)
+3. [`mental-model-assets-workspace.md`](./mental-model-assets-workspace.md)
+4. [`mental-model-asset-mutations.md`](./mental-model-asset-mutations.md)
diff --git a/docs/studio/learn/mental-model-asset-mutations.md b/docs/studio/learn/mental-model-asset-mutations.md
new file mode 100644
index 00000000..15bc82ca
--- /dev/null
+++ b/docs/studio/learn/mental-model-asset-mutations.md
@@ -0,0 +1,128 @@
+# Mental Model: Asset Mutations
+
+## The Problem
+
+Asset mutations are easy to get wrong in a Studio UI.
+
+Why?
+
+Because some actions only update registry state, while others change the physical workspace.
+
+If the Studio hides that difference, users lose trust quickly.
+
+## The Rule
+
+Sensitive asset mutations are `preview-first`.
+
+That is the most important rule.
+
+The Studio must not perform destructive or relocational asset changes as if they were harmless button clicks.
+
+## What The User Must Understand Before Apply
+
+Before applying a mutation, the user should be able to answer:
+
+- Which assets are affected?
+- Is this touching only the registry, or also the workspace?
+- Will something be created, moved, or deleted?
+- Are there blockers?
+- Are there warnings?
+- Is this a safe fix or a risky mutation?
+
+If the UI cannot answer those questions, the mutation flow is not ready.
+
+## Why Inline Review Is The Baseline
+
+The default review surface is an inline staged panel, not a modal.
+
+That keeps the user anchored in the asset and its surrounding context.
+
+It lets the user compare:
+
+- the selected asset,
+- the diagnostics,
+- the proposed changes,
+- and the action consequences
+
+without bouncing between unrelated windows.
+
+## Why Modals Still Exist
+
+Modals are still useful, but only for high-risk final commits.
+
+Examples:
+
+- destructive delete;
+- major relocation;
+- other strongly irreversible actions.
+
+The mistake would be using modals as a substitute for review.
+
+Preview is the review.
+
+Modal confirmation is only the final safety gate when the risk is high enough.
+
+## The Most Important Distinction
+
+The Studio must distinguish:
+
+- registry impact
+- workspace impact
+
+This is one of the most important didactic duties of the asset workspace.
+
+A user should never have to guess whether a button:
+
+- merely forgets an asset from management,
+- or actually deletes or moves files.
+
+## Blockers, Warnings, and Safe Fixes
+
+These categories must stay visually and semantically separate.
+
+They are not interchangeable kinds of “message”.
+
+- `blockers` stop the apply path;
+- `warnings` tell the user the action is still meaningful but risky or noteworthy;
+- `safe fixes` are low-risk corrections and should not be grouped as if they were destructive operations.
+
+If those three collapse into one list, users stop trusting the flow.
+
+## Batch Operations
+
+Batch operations are not just “single asset, repeated many times”.
+
+They need:
+
+- an aggregate summary first,
+- then drill-down detail.
+
+Without that, the flow becomes unreadable and users either miss risk or abandon the tool.
+
+## How Activity Fits In
+
+The preview itself belongs to the workspace.
+
+But the shell should still reflect lifecycle milestones such as:
+
+- preview ready;
+- action applied;
+- action failed.
+
+That way the workspace remains the place of review, while the shell keeps the broader operational timeline visible.
+
+## Common Failure Modes
+
+Avoid these:
+
+- destructive apply without preview;
+- using raw logs as the main explanation surface;
+- mixing safe fixes with deletes;
+- showing technical diff data with no user-facing interpretation;
+- forcing the user into modal-only flows for ordinary review.
+
+## Read With
+
+1. [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
+2. [`mental-model-assets-workspace.md`](./mental-model-assets-workspace.md)
+3. [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
diff --git a/docs/studio/learn/mental-model-assets-workspace.md b/docs/studio/learn/mental-model-assets-workspace.md
new file mode 100644
index 00000000..2a6aa920
--- /dev/null
+++ b/docs/studio/learn/mental-model-assets-workspace.md
@@ -0,0 +1,119 @@
+# Mental Model: Assets Workspace
+
+## Why This Workspace Exists
+
+The `Assets` workspace is not a nicer file browser.
+
+It exists to make the packer model understandable and usable from the Studio.
+
+That means the workspace must help a contributor answer questions like:
+
+- What is the managed asset here?
+- Where does it live?
+- Which files belong to it?
+- What does it produce toward the runtime?
+- Is it managed, orphaned, preload-marked, or diagnostically unhealthy?
+
+If the workspace answered those questions only by showing folders and files, it would teach the wrong mental model.
+
+## The Core Shift
+
+The key shift is:
+
+- not `file-first`
+- but `asset-first`
+
+An asset may contain many files.
+
+Those files still matter, but they matter as inputs of an asset, not as the primary unit of identity.
+
+So the workspace is designed to feel like:
+
+- a structured asset navigator,
+- plus a didactic explanation surface for the currently selected asset.
+
+## Why It Is Still Path-Aware
+
+`Asset-first` does not mean `filesystem-blind`.
+
+People still organize projects by directories.
+
+They still need to know:
+
+- where the asset root lives;
+- which broader folder group it belongs to;
+- how to reason about the project layout.
+
+That is why the workspace remains `path-aware`.
+
+The important nuance is:
+
+- path is supporting context
+- asset identity is primary
+
+## What The Left Side Teaches
+
+The left-side navigator is a custom `Asset Tree` / `Asset Navigator`.
+
+It teaches the model visually:
+
+- groups may reflect location or parent folders,
+- asset nodes are the real unit of navigation,
+- icons and badges tell the story quickly,
+- orphan and managed assets can coexist without becoming ambiguous.
+
+This is better than a raw file tree because the user learns the packer model by looking at the navigation itself.
+
+## What The Main Area Teaches
+
+The selected asset view is intentionally structured in a fixed order:
+
+1. `Summary`
+2. `Runtime Contract`
+3. `Inputs / Preview`
+4. `Diagnostics`
+5. `Actions`
+
+That order matters.
+
+It starts by explaining what the asset is, then what it produces, then what it contains, then what is wrong, and finally what the user can do.
+
+That is a teaching sequence, not just a layout sequence.
+
+## Why Preview Matters
+
+Preview is not decorative.
+
+Preview is part of how the workspace bridges the conceptual asset model with the real materials inside the project.
+
+Examples:
+
+- an image bank should let the user inspect images and palettes;
+- an audio asset should let the user inspect sound inputs;
+- text-like artifacts should be inspectable as text when that helps understanding.
+
+This makes the workspace feel grounded in real project materials while still preserving an asset-first model.
+
+## What To Avoid
+
+Common mistakes:
+
+- turning the workspace into a raw filesystem explorer with extra badges;
+- making path the true identity instead of the asset;
+- showing only diagnostics and forgetting the actual asset model;
+- treating orphan as if it meant broken;
+- hiding runtime-facing information behind technical dumps.
+
+## Practical Read Order
+
+Read these together:
+
+1. [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
+2. [`mental-model-asset-mutations.md`](./mental-model-asset-mutations.md)
+3. [`../../packer/learn/mental-model-packer.md`](../../packer/learn/mental-model-packer.md)
+
+That path explains:
+
+- what the packer believes,
+- how the Studio presents it,
+- and how the user should reason about asset operations.
diff --git a/docs/studio/pull-requests/PR-05a-assets-workspace-foundation-and-service-state.md b/docs/studio/pull-requests/PR-05a-assets-workspace-foundation-and-service-state.md
new file mode 100644
index 00000000..d802187c
--- /dev/null
+++ b/docs/studio/pull-requests/PR-05a-assets-workspace-foundation-and-service-state.md
@@ -0,0 +1,71 @@
+# PR-05a Assets Workspace Foundation and Service State
+
+## Briefing
+
+Implement the first executable slice of the `Assets` workspace based on:
+
+- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
+
+This PR creates the workspace foundation, service-facing state model, and event wiring required by all later `Assets` workspace slices.
+
+## Objective
+
+Replace the current `WorkspaceId.ASSETS` placeholder with a concrete `AssetsWorkspace` foundation that can:
+
+- boot inside the Studio shell,
+- request and refresh asset data from Studio-facing services,
+- maintain stable selection state,
+- surface loading/empty/error states,
+- and expose internal state in a way that later UI slices can reuse.
+
+## Dependencies
+
+- existing Studio shell and event bus foundations
+- existing packer-facing Studio contracts and specifications
+
+## Scope
+
+- create a concrete `AssetsWorkspace`
+- define workspace-local view state models for:
+  - navigator state
+  - selected asset state
+  - loading/error state
+- define service-facing DTO adapters needed by the workspace
+- define workspace event publications for asset refresh and selection updates
+- integrate the workspace into the existing shell/workspace switch flow
+
+## Non-Goals
+
+- no final asset navigator visuals yet
+- no final preview rendering yet
+- no final staged mutation UI yet
+- no production-grade packer backend implementation if stubs or adapters are still required
+
+## Execution Method
+
+1. Replace the placeholder assets workspace with a concrete class and root layout.
+2. Introduce workspace-local state objects for navigator, selection, and detail hydration.
+3. Introduce a Studio-facing service boundary for loading asset collections and selected-asset details.
+4. Wire the workspace into `StudioWorkspaceEventBus` for refresh and selection lifecycle.
+5. Define stable loading, empty, no-results, and error states in code.
+
+## Acceptance Criteria
+
+- selecting `Assets` opens a real workspace rather than a placeholder
+- the workspace can request asset data through a Studio service boundary
+- loading, empty, and error states are visible and distinct
+- selection state is modelled explicitly and can be preserved by identity
+- the workspace has enough state structure to support the later navigator and details PRs without redesign
+
+## Validation
+
+- unit tests for workspace state transitions
+- unit tests for selection retention logic
+- UI smoke validation that the Assets workspace mounts cleanly in the shell
+
+## Affected Artifacts
+
+- `prometeu-studio` workspace classes
+- Studio event wiring
+- Studio-facing asset service abstractions
+- tests for workspace state and selection behavior
diff --git a/docs/studio/pull-requests/PR-05b-asset-navigator-search-filters-and-selection.md b/docs/studio/pull-requests/PR-05b-asset-navigator-search-filters-and-selection.md
new file mode 100644
index 00000000..6135b372
--- /dev/null
+++ b/docs/studio/pull-requests/PR-05b-asset-navigator-search-filters-and-selection.md
@@ -0,0 +1,72 @@
+# PR-05b Asset Navigator Search Filters and Selection
+
+## Briefing
+
+Implement the left-side `Asset Tree` / `Asset Navigator` for the `Assets` workspace.
+
+This PR applies the navigator and selection rules from:
+
+- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
+
+## Objective
+
+Deliver the first concrete asset navigator with:
+
+- asset-first grouped navigation
+- semantic filters
+- textual search
+- stable single selection
+- explicit loading/empty/no-results/error states
+
+## Dependencies
+
+- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
+
+## Scope
+
+- implement the custom visual asset navigator control
+- render group nodes and asset nodes
+- implement baseline filters:
+  - `Managed`
+  - `Orphan`
+  - `Diagnostics`
+  - `Preload`
+- implement textual search over asset name and path context
+- preserve selection by `asset_id` or orphan root path as appropriate
+- allow optional expansion into asset inputs only as supporting inspection
+
+## Non-Goals
+
+- no final selected-asset details composition yet
+- no final mutation staging UI yet
+- no heavy sorting or multi-select support
+
+## Execution Method
+
+1. Implement the navigator control and node rendering model.
+2. Add the baseline filters and search composition logic.
+3. Add stable selection reconciliation during refresh.
+4. Add explicit navigator states for loading, empty, no-results, and workspace error.
+5. Add the visual markers for managed/orphan, diagnostics, preload, and broad asset family.
+
+## Acceptance Criteria
+
+- the `Assets` workspace shows a real asset navigator on the left
+- assets are grouped by path-aware structure without degrading into a raw file tree
+- filters and search work together
+- selection remains stable across refresh when identity is preserved
+- orphan assets appear in the same navigator flow with clearly differentiated styling
+
+## Validation
+
+- unit tests for filter/search composition
+- unit tests for selection preservation rules
+- UI smoke validation for node rendering and navigator states
+
+## Affected Artifacts
+
+- `AssetsWorkspace`
+- custom navigator controls
+- navigator view models
+- selection reconciliation logic
+- tests for filters, search, and selection behavior
diff --git a/docs/studio/pull-requests/PR-05c-selected-asset-details-contract-and-preview.md b/docs/studio/pull-requests/PR-05c-selected-asset-details-contract-and-preview.md
new file mode 100644
index 00000000..8ed623a9
--- /dev/null
+++ b/docs/studio/pull-requests/PR-05c-selected-asset-details-contract-and-preview.md
@@ -0,0 +1,80 @@
+# PR-05c Selected Asset Details Contract and Preview
+
+## Briefing
+
+Implement the selected-asset details surface in the required fixed order:
+
+1. `Summary`
+2. `Runtime Contract`
+3. `Inputs / Preview`
+4. `Diagnostics`
+5. `Actions`
+
+This PR materializes the didactic core of the `Assets` workspace.
+
+## Objective
+
+Deliver the first usable selected-asset details experience, including:
+
+- summary identity/state rendering
+- runtime-facing contract rendering
+- inputs-by-role rendering
+- first previewable input surfaces
+- inline diagnostics
+- action groups with routine vs sensitive separation
+
+## Dependencies
+
+- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
+- [`./PR-05b-asset-navigator-search-filters-and-selection.md`](./PR-05b-asset-navigator-search-filters-and-selection.md)
+
+## Scope
+
+- render the fixed details skeleton
+- render summary metadata and location
+- render runtime contract fields such as `output.format`, `codec`, and `preload`
+- render input groups and input selection
+- implement first preview surfaces for previewable inputs
+- render inline diagnostics by severity
+- render action groups for:
+  - `Doctor`
+  - `Build`
+  - `Adopt`
+  - `Register`
+  - sensitive operations placeholders where needed
+
+## Non-Goals
+
+- no final staged preview/apply workflow yet
+- no final lower log integration yet
+- no exhaustive preview support for every asset family
+
+## Execution Method
+
+1. Build the selected-asset details layout in the mandated section order.
+2. Render summary and runtime contract from workspace state.
+3. Implement inputs-by-role rendering and input selection.
+4. Implement baseline preview handling for previewable types.
+5. Render inline diagnostics and action grouping.
+
+## Acceptance Criteria
+
+- selecting an asset hydrates a full details view in the fixed section order
+- runtime-facing contract fields are visible without raw JSON inspection
+- previewable inputs can be inspected from the details area
+- diagnostics are visible inline and differentiated by severity
+- routine actions and sensitive actions are visibly separated
+
+## Validation
+
+- unit tests for selected-asset detail mapping
+- unit tests for action availability by asset state
+- UI smoke validation for previewable input rendering
+
+## Affected Artifacts
+
+- `AssetsWorkspace` details area
+- preview components
+- diagnostics rendering
+- action surface wiring
+- tests for selected-asset detail behavior
diff --git a/docs/studio/pull-requests/PR-05d-assets-activity-progress-and-logs-integration.md b/docs/studio/pull-requests/PR-05d-assets-activity-progress-and-logs-integration.md
new file mode 100644
index 00000000..99d5c234
--- /dev/null
+++ b/docs/studio/pull-requests/PR-05d-assets-activity-progress-and-logs-integration.md
@@ -0,0 +1,63 @@
+# PR-05d Assets Activity Progress and Logs Integration
+
+## Briefing
+
+Integrate the `Assets` workspace with Studio activity, progress, and logs according to the assets workspace specification.
+
+## Objective
+
+Make the `Assets` workspace operationally legible by wiring:
+
+- structured activity into the shell right-side panel
+- contextual progress into the workspace
+- detailed textual logs into the lower region
+- failure retention and acknowledgement surfaces where required
+
+## Dependencies
+
+- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
+- [`./PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md)
+
+## Scope
+
+- map asset-service events into Studio activity entries
+- aggregate repetitive background events into user-facing summaries
+- wire `progress_updated` into progress surfaces without feed spam
+- expose lower-region textual logs for asset operations
+- retain recent actionable failures until acknowledgement
+- mirror selected-asset failures inline where applicable
+
+## Non-Goals
+
+- no generic all-workspace activity framework redesign beyond what Assets needs now
+- no final cross-workspace logs unification
+
+## Execution Method
+
+1. Define asset-workspace activity mapping rules.
+2. Wire workspace and global bus publications for asset activity.
+3. Implement feed aggregation for repetitive events.
+4. Implement inline progress and lower-region logs integration.
+5. Retain and surface actionable failures across shell and workspace surfaces.
+
+## Acceptance Criteria
+
+- asset events appear in the global `Activity` feed as user-oriented entries
+- progress updates do not spam the feed
+- logs are visible in the lower region for technical drill-down
+- actionable failures remain visible until acknowledged
+- selected-asset failures also appear inline when relevant
+
+## Validation
+
+- unit tests for activity aggregation mapping
+- unit tests for failure retention logic
+- UI smoke validation for shell/workspace activity interplay
+
+## Affected Artifacts
+
+- activity event adapters
+- progress surfaces
+- workspace log region integration
+- failure retention state
+- tests for activity mapping and failure behavior
diff --git a/docs/studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md b/docs/studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md
new file mode 100644
index 00000000..a4cbb35c
--- /dev/null
+++ b/docs/studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md
@@ -0,0 +1,75 @@
+# PR-05e Assets Staged Mutations Preview and Apply
+
+## Briefing
+
+Implement the preview-first mutation flows for the `Assets` workspace.
+
+This PR applies the staged mutation rules from:
+
+- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
+
+## Objective
+
+Deliver inline staged mutation review for sensitive asset operations, including:
+
+- preview generation
+- blockers, warnings, and safe-fix separation
+- registry vs workspace impact explanation
+- apply gating
+- activity integration for preview/apply lifecycle
+
+## Dependencies
+
+- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
+- [`./PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md)
+- [`./PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md)
+
+## Scope
+
+- implement inline staged review panel inside the `Assets` workspace
+- support preview-first handling for:
+  - `Adopt`
+  - `Forget`
+  - `Remove`
+  - `Quarantine`
+  - relocational mutations
+  - batch mutations when available
+- render proposed actions, blockers, warnings, safe fixes, and diff-style effects
+- disable `Apply` while blockers exist
+- use modal confirmation only for high-risk final commits
+
+## Non-Goals
+
+- no fully generic mutation framework for every Studio workspace
+- no speculative batch authoring flows that do not yet exist in services
+
+## Execution Method
+
+1. Define the staged review panel and its state model.
+2. Integrate preview requests and preview-ready responses from services.
+3. Render registry impact and workspace impact separately.
+4. Gate apply on blockers.
+5. Wire `preview_ready`, `action_applied`, and `action_failed` into activity.
+6. Add modal confirmation only where the final commit is high-risk.
+
+## Acceptance Criteria
+
+- sensitive asset mutations do not execute directly from a single click
+- preview clearly shows what will change in registry and workspace
+- blockers prevent apply
+- safe fixes remain visually distinct from destructive actions
+- preview/apply lifecycle events surface correctly in workspace and activity
+
+## Validation
+
+- unit tests for preview state mapping and apply gating
+- unit tests for registry/workspace impact rendering rules
+- UI smoke validation for staged mutation flows
+
+## Affected Artifacts
+
+- staged review panel
+- asset mutation action wiring
+- preview/apply state models
+- activity integration for mutation lifecycle
+- tests for preview and apply behavior
diff --git a/docs/studio/pull-requests/README.md b/docs/studio/pull-requests/README.md
index 2227092a..d9f551e5 100644
--- a/docs/studio/pull-requests/README.md
+++ b/docs/studio/pull-requests/README.md
@@ -38,3 +38,12 @@ A Studio plan should usually include:
 
 The current Studio execution queue is:
 
+1. [`PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
+2. [`PR-05b-asset-navigator-search-filters-and-selection.md`](./PR-05b-asset-navigator-search-filters-and-selection.md)
+3. [`PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md)
+4. [`PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md)
+5. [`PR-05e-assets-staged-mutations-preview-and-apply.md`](./PR-05e-assets-staged-mutations-preview-and-apply.md)
+
+Recommended execution order:
+
+`PR-05a -> PR-05b -> PR-05c -> PR-05d -> PR-05e`
diff --git a/docs/studio/specs/4. Assets Workspace Specification.md b/docs/studio/specs/4. Assets Workspace Specification.md
new file mode 100644
index 00000000..d8e6d1f2
--- /dev/null
+++ b/docs/studio/specs/4. Assets Workspace Specification.md	
@@ -0,0 +1,292 @@
+# Assets Workspace Specification
+
+## Status
+
+Active
+
+## Applies To
+
+- `prometeu-studio`
+- the Studio `Assets` workspace
+- packer-facing Studio service integration for asset browsing, inspection, diagnostics, and staged mutations
+
+## Purpose
+
+Define the normative Studio contract for the `Assets` workspace.
+
+This specification stabilizes:
+
+- the information architecture of the workspace,
+- the navigation and selection model,
+- the selected-asset details structure,
+- the relationship between activity, progress, and logs,
+- and the preview/confirm/apply flow for sensitive mutations.
+
+## Authority and Precedence
+
+This specification extends:
+
+- [`1. Studio Shell and Workspace Layout Specification.md`](./1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
+- [`2. Studio UI Foundations Specification.md`](./2.%20Studio%20UI%20Foundations%20Specification.md)
+- [`3. Studio Components Module Specification.md`](./3.%20Studio%20Components%20Module%20Specification.md)
+
+For packer-facing semantics, this specification must align with:
+
+- [`../../packer/specs/1. Domain and Artifact Boundary Specification.md`](../../packer/specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
+- [`../../packer/specs/2. Workspace, Registry, and Asset Identity Specification.md`](../../packer/specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
+- [`../../packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../../packer/specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
+- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
+
+If this document conflicts with the global Studio shell specifications, the shell specifications control shell-wide behavior and this document controls workspace-local behavior.
+
+## Normative Inputs
+
+The `Assets` workspace is a Studio view over packer services.
+
+The workspace must assume:
+
+- managed assets are the primary unit of identity and operation;
+- orphan declarations may exist and must remain visible;
+- assets may aggregate many internal inputs;
+- runtime-facing output contract data exists for each asset;
+- diagnostics, activity, progress, and staged mutation responses are available from Studio-facing services.
+
+## Workspace Model
+
+The `Assets` workspace is:
+
+- `asset-first`,
+- `path-aware`,
+- didactic toward the packer model,
+- and explicitly not a raw filesystem explorer clone.
+
+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;
+- which operations are safe, staged, blocked, or destructive.
+
+## Baseline Layout
+
+The baseline workspace layout is:
+
+- a custom `Asset Tree` / `Asset Navigator` on the left;
+- a selected-asset details area in the main panel;
+- inline diagnostics and action surfaces attached to the selected asset;
+- global `Activity` in the shell right-side utility area;
+- logs in the lower workspace region.
+
+Filesystem structure may be visible and actionable as supporting context, but it is not the primary identity model of the workspace.
+
+## Asset Navigator Rules
+
+### Primary Navigation Unit
+
+- The primary navigation unit is the asset, not the raw file.
+- The navigator must not degrade into a generic file tree.
+- Grouping may reflect path or parent-folder structure, but asset nodes remain the primary navigable and selectable unit.
+
+### Visual Rules
+
+- The left navigation surface must be a custom `Asset Tree` / `Asset Navigator`.
+- Asset nodes must expose strong visual semantics through icons, badges, and state styling.
+- Asset nodes must surface:
+  - managed/orphan state,
+  - diagnostics presence,
+  - preload intent,
+  - and broad asset family or type where available.
+- Path context may appear as secondary information.
+
+### Filters and Search
+
+- The baseline filters are:
+  - `Managed`
+  - `Orphan`
+  - `Diagnostics`
+  - `Preload`
+- The navigator must support textual search.
+- Baseline search must cover at least:
+  - `asset_name`
+  - asset root path
+  - path context
+
+### Selection Rules
+
+- The baseline navigator is single-select.
+- Managed asset selection must be preserved by `asset_id`.
+- Orphan selection must be preserved by asset root path until the asset becomes managed.
+- If an asset changes state while preserving identity, selection must remain attached to it.
+- If the selected asset is removed from the navigator, selection must clear explicitly.
+- Selection must never silently drift to another asset due to refresh ordering.
+
+### State Rules
+
+- The navigator must define explicit `loading assets` state.
+- The navigator must define explicit `no assets` state.
+- The navigator must define explicit `no results` state.
+- The navigator must define explicit `workspace error` state.
+- Orphan assets must appear in the same navigator flow as managed assets.
+- Orphan styling must communicate `declared, not managed`, not `broken`.
+
+### Inputs Expansion
+
+- Internal inputs may appear only as optional expansion or inspection surfaces.
+- Inputs must not replace asset nodes as the default navigation unit.
+
+## Selected Asset Details Rules
+
+The selected asset view must use this fixed section order:
+
+1. `Summary`
+2. `Runtime Contract`
+3. `Inputs / Preview`
+4. `Diagnostics`
+5. `Actions`
+
+This section order is stable across asset families.
+
+### Summary
+
+- `Summary` must always be present for a selected asset.
+- `Summary` must show:
+  - `asset_name`
+  - managed/orphan state
+  - `asset_id` when available
+  - family/type
+  - asset root path
+
+### Runtime Contract
+
+- `Runtime Contract` must present runtime-facing asset output data in short, didactic form.
+- `Runtime Contract` must surface:
+  - `output.format`
+  - `codec`
+  - `preload`
+- Runtime-facing output information must not require raw JSON inspection.
+
+### Inputs / Preview
+
+- `Inputs / Preview` must expose internal inputs as part of the selected asset.
+- Inputs should be structured by role where that information is available.
+- Preview should be available for previewable materials such as:
+  - images
+  - palettes
+  - audio
+  - text
+  - similar lightweight input artifacts
+- Preview of derived output may exist, but input preview has baseline priority.
+
+### Diagnostics
+
+- Diagnostics for the selected asset must appear inline in the selected asset view.
+- Blockers, warnings, and hints must be distinguishable.
+- Inline diagnostics must not be replaced by raw logs.
+
+### Actions
+
+- Actions must be explicit.
+- Safe and routine actions must be visually separated from sensitive mutations.
+- Hidden or automatic repair behavior is not allowed in the selected-asset view.
+
+## Action Rules
+
+- Primary actions for managed assets include `Doctor` and `Build`.
+- Primary actions for orphan assets include `Adopt`.
+- `Register` must remain available when explicit registration is the correct flow.
+- Sensitive actions such as `Forget`, `Remove`, and quarantine-like actions must be visually separated from routine actions.
+- Sensitive actions must not look interchangeable with routine actions.
+
+## Activity, Progress, and Logs Rules
+
+### Activity
+
+- `Activity` belongs to the global right-side shell panel.
+- `Activity` is the structured operational timeline of the Studio.
+- Activity entries must be user-oriented rather than service-trace-oriented.
+- Repetitive background events must be aggregated or summarized.
+- Significant lifecycle milestones should remain visible in the feed.
+
+### Progress
+
+- Progress must be visible globally in the shell.
+- Progress may also appear inline when the current asset or action clearly owns that progress.
+- Progress tick events must update progress state rather than create feed spam.
+
+### Logs
+
+- Logs belong to the lower workspace region as detailed textual output.
+- Logs are secondary drill-down, not the primary explanation surface.
+- The user must not need raw logs to understand ordinary operational state.
+
+### Failure Retention
+
+- Recent actionable failures must remain visible until acknowledged.
+- Failures tied to the selected asset should also surface inline in the selected asset view.
+- Critical failures must not disappear merely because low-value events continue to arrive.
+
+## Staged Mutation Rules
+
+Sensitive asset mutations are `preview-first`.
+
+The default review surface is an inline staged panel inside the workspace.
+
+Modal confirmation is reserved for high-risk final commits such as destructive delete or major relocation.
+
+### Mutations Requiring Preview
+
+- `Adopt`
+- `Forget`
+- `Remove`
+- `Quarantine`
+- relocational changes such as move or rename of asset roots
+- batch operations
+
+`Doctor` and `Build` remain outside this sensitive mutation staging flow.
+
+### Preview Content
+
+- Preview must show affected assets.
+- Preview must show proposed actions.
+- Preview must distinguish registry impact from workspace impact.
+- Preview must show blockers, warnings, and safe fixes as separate visual sections.
+- Preview must show diff-style effects such as:
+  - create
+  - move
+  - delete
+  - registry update
+
+### Apply Rules
+
+- `Apply` must remain disabled while blockers exist.
+- Batch operations must present an aggregate summary first.
+- Batch operations may expose drill-down detail after the aggregate summary.
+- Destructive or relocational actions must not bypass preview.
+
+### Activity Integration
+
+- `preview_ready` should surface in global `Activity`.
+- `action_applied` should surface in global `Activity`.
+- `action_failed` should surface in global `Activity`.
+- The preview itself remains a workspace-local review surface.
+
+## Non-Goals
+
+This specification does not define:
+
+- the exact JavaFX component tree or control class structure of the `Assets` workspace;
+- final reusable component boundaries for all preview surfaces;
+- cross-workspace reuse beyond the `Assets` workspace;
+- future multi-select or bulk-edit UX beyond the currently defined staged batch summary rules.
+
+## Exit Criteria
+
+This specification is satisfied when the Studio `Assets` workspace:
+
+- navigates by assets rather than raw files;
+- preserves path awareness without collapsing into a file explorer;
+- explains the selected asset through summary, contract, inputs, diagnostics, and actions;
+- keeps activity, progress, and logs clearly separated;
+- stages sensitive mutations through preview-first flows;
+- and behaves as a didactic helper for the packer model.
diff --git a/docs/studio/specs/README.md b/docs/studio/specs/README.md
index f64bb9f9..ffe92743 100644
--- a/docs/studio/specs/README.md
+++ b/docs/studio/specs/README.md
@@ -53,6 +53,7 @@ The current Studio core corpus is:
 1. [`1. Studio Shell and Workspace Layout Specification.md`](./1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
 2. [`2. Studio UI Foundations Specification.md`](./2.%20Studio%20UI%20Foundations%20Specification.md)
 3. [`3. Studio Components Module Specification.md`](./3.%20Studio%20Components%20Module%20Specification.md)
+4. [`4. Assets Workspace Specification.md`](./4.%20Assets%20Workspace%20Specification.md)
 
 ## Reading Order
 
@@ -60,4 +61,5 @@ Recommended order:
 
 1. shell and workspace layout;
 2. shared UI foundations;
-3. components module policy.
+3. components module policy;
+4. assets workspace behavior.