update specs studio

2026-03-11 12:11:25 +00:00 · 2026-03-11 12:11:25 +00:00 · 2ee37d7d13
commit 2ee37d7d13
parent 9ed16301ab
14 changed files with 532 additions and 471 deletions
--- a/docs/studio/README.md
+++ b/docs/studio/README.md
@ -45,6 +45,8 @@ Use it to:
 - decide how Studio consumes services and events,
 - define what must be visible, staged, or confirmed in the UI.
 When a topic is fully propagated into specs and learn, the corresponding agenda should leave the retained set.
 ### `decisions/`
 `decisions/` records closed Studio product and UX decisions before they are fully propagated.
@ -55,6 +57,8 @@ Use it to:
 - define invariants for UI behavior,
 - capture what must be implemented in Studio code and service contracts.
 Once their content is fully absorbed into specs and learn, they should not be retained just as historical residue.
 ### `pull-requests/`
 `pull-requests/` contains execution plans for Studio changes.
@ -99,9 +103,11 @@ The preferred Studio documentation flow is:
 ## Practical Rule
 - `agendas/` stores currently open Studio questions.
- `decisions/` stores decisions that still need propagation.
+- `decisions/` stores only decisions that still need propagation.
 - `pull-requests/` stores execution plans.
 - `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.
 If implementation exposes a missing UI or interaction decision, stop and return to `agendas/` or `decisions/`.
--- a/docs/studio/agendas/01.0.
+++ b/docs/studio/agendas/01.0.
@ -1,154 +0,0 @@
 # Studio Shell, Workspace Navigation, and Layout Agenda
 ## Status
 Closed
 ## Purpose
 Define the baseline Studio shell:
 - main window layout,
 - workspace navigation model,
 - shell regions and panel hierarchy,
 - default landing behavior,
 - how future workspaces should fit into the frame.
 ## Domain Owner
 `docs/studio`
 ## Current Code Context
 Current `prometeu-studio` already provides:
 - `MainView` as the root shell;
 - `WorkspaceBar` as left-side workspace navigation;
 - `EditorWorkspace` as the most concrete workspace;
 - placeholder workspaces for `Assets` and `Device`;
 - a `BuilderWorkspace` implementation artifact with logs and toolbar.
 The shell exists, but it is still closer to a scaffold than a documented Studio UX contract.
 This shell may be substantially remodeled in code as long as the resulting Studio preserves:
 - theme support;
 - i18n support;
 - a clear path for custom Studio components instead of ad hoc UI fragments.
 ## Core Questions
 1. What is the long-lived shell structure of the Studio?
 2. Is left-side workspace switching the correct baseline navigation model?
 3. Which shell regions are global and which belong to each workspace?
 4. How should the Assets workspace coexist with Editor, Device, and future shipping flows?
 5. What should the default landing workspace be?
 ## Options
 ### Option A
 Keep the current shell mostly intact and grow workspaces within it.
 ### Option B
 Evolve toward a multi-panel shell with global activity and contextual side panels.
 ### Option C
 Adopt a dock-heavy IDE-style shell from the start.
 ## Tradeoffs
 - Option A is fast and consistent with current code, but may constrain richer workflows later.
 - Option B preserves the current shell while creating room for Studio-grade interaction design.
 - Option C is powerful, but likely too heavy for the current code and service maturity.
 Specific concern with adopting a fully docked shell too early:
 - it forces panel lifecycle and layout-persistence decisions before the core workspace model is stable;
 - it adds implementation weight around focus, restore, drag/drop, and window state without proving that the Studio already needs that flexibility;
 - it increases UX complexity while the Assets workspace and background activity model are still being defined;
 - it risks stabilizing the wrong shell topology too early.
 ## Recommendation
 Prefer Option B.
 Recommended direction:
 - keep workspace switching in the shell,
 - formalize a stable frame with top global menus, left workspace selectors, center workspace body, and right global utility panel,
 - let each workspace own its internal panels, including logs and detailed operational output,
 - avoid a fully dockable IDE model for the first Studio UI wave,
 - revisit dockability only after the shell regions and workspace panel responsibilities are proven in use.
 ## Open Questions
 1. Which shell regions are baseline and always present:
   top global menus, left workspace navigation, right global utility panel, status/progress bar?
 2. Which right-side tabs are baseline in v1, and which are future additions?
 3. Should the Studio land directly in a workspace, restore the last workspace, or open through a project launcher/home surface first?
 4. Does `BuilderWorkspace` remain a first-class shell workspace, or should future shipping/build flows move toward a different Studio surface?
 5. Which parts of the shell must be fixed in v1, and which can remain future extension points without immediate docking support?
 ## Current Direction
 The preferred direction for question 3 is to introduce a lightweight project launcher or home surface before the main workspace shell.
 Target experience:
 - closer to Unity or the IntelliJ family than to direct last-tab restore;
 - show existing projects immediately;
 - make `open project` and `create project` first-class actions;
 - only enter the workspace shell after a concrete project is selected or created.
 This keeps project entry intentional and gives the Studio a stable place for project lifecycle actions without overloading the main workspace shell.
 The current preferred shell model is:
 - top region with global Studio menus such as `File`, `Edit`, `View`, and similar shell-level actions;
 - left-side fixed workspace selector, closer to IntelliJ-style workspace switching than to a free docking system;
 - center region fully owned by the selected workspace;
 - right-side global utility surface implemented as tabs;
 - logs and detailed execution output owned by each workspace instead of a single global bottom console.
 The right-side global utility surface is intended for concerns such as:
 - general activity visibility;
 - contextual inspector or summary views;
 - global shortcuts and shell-level utility surfaces.
 `Run` should not be modeled as a tab.
 It should remain always visible at the top-right portion of the shell so that running the current project or relevant flow is always easy to reach.
 This keeps run/build controls immediately accessible while allowing the right-side tab system to serve broader global concerns.
 Current baseline answers:
 - the initial right-side tab set contains only `Activity`;
 - the right-side panel must remain easy to extend with additional tabs later;
 - `BuilderWorkspace` may remain in the shell temporarily because it is still useful for tests, but it should be treated as a low-investment transitional surface on the path toward a future `Shipper`;
 - the baseline fixed workspace set is:
  - Code Editor
  - Asset Management
  - Debugger/Profiler
  - Shipper, temporarily represented by the current `BuilderWorkspace`
 The shell and workspaces should also evolve with explicit foundations for:
 - clear naming conventions,
 - a Studio event system,
 - reusable custom components such as directory trees and related structured UI controls.
 ## Expected Follow-up
 - a shell decision,
 - a Studio shell spec,
 - a PR/plan for `MainView`, `WorkspaceBar`, and workspace composition.
 - a separate Studio foundations agenda for naming, events, and custom component architecture.
 ## Outcome
 Closed in [`001-studio-shell-workspace-navigation-and-layout-decision.md`](../decisions/001-studio-shell-workspace-navigation-and-layout-decision.md).
--- a/docs/studio/agendas/01.6.
+++ b/docs/studio/agendas/01.6.
@ -1,104 +0,0 @@
 # Studio UI Foundations - Naming, Events, and Custom Components Agenda
 ## Status
 Open
 ## Purpose
 Define the shared UI foundations required before the Studio grows into a larger product surface.
 This agenda exists to keep the Studio from becoming a pile of unrelated JavaFX screens with inconsistent naming, ad hoc event wiring, and one-off controls.
 ## Domain Owner
 `docs/studio`
 ## Context
 The current `prometeu-studio` shell is still small enough to be remodeled.
 Today there is no real Studio-wide event system.
 Current behavior is still largely based on direct wiring between UI elements, workspace hosts, and service calls.
 That is the right moment to establish explicit foundations for:
 - clear naming conventions;
 - a Studio event system;
 - reusable custom components;
 - long-lived support for i18n and themes.
 The immediate driver is the upcoming Assets workspace, but the same foundations will affect Editor, Debugger/Profiler, and the future Shipper surface.
 ## Core Questions
 1. Which naming conventions should apply to Studio shell classes, workspaces, panels, services, and events?
 2. What kind of Studio-wide event system should exist between shell, workspaces, and background services?
 3. Which custom components should become first-class reusable Studio controls instead of one-off implementations?
 4. How should i18n and theme support constrain custom component design from day 1?
 5. Where is the boundary between generic infrastructure and domain-specific workspace UI?
 ## Initial Areas To Close
 ### Naming
 Need clear and stable names for:
 - shell surfaces;
 - workspace types;
 - right-side utility tabs;
 - events and event payloads;
 - reusable controls and component packages.
 ### Events
 Need a Studio event model that can support:
 - shell-level state changes;
 - workspace-local interactions;
 - background service notifications;
 - progress and activity publication;
 - future debugger/profiler integration.
 Current direction:
 - introduce a Studio-owned event system instead of continuing with ad hoc direct coupling;
 - keep it small, local, and strongly typed;
 - model it as a `StudioEventBus` or equivalent typed publish/subscribe surface;
 - avoid stringly-typed event names and avoid overbuilding a large reactive framework too early.
 Illustrative event categories include:
 - project lifecycle events;
 - workspace selection events;
 - run/build intent events;
 - activity publication events;
 - diagnostics and asset-selection events.
 ### Custom Components
 Likely candidates include:
 - directory tree or project tree controls;
 - activity feed views;
 - diagnostics list views;
 - inspector panels;
 - staged action and preview surfaces.
 ## Recommendation
 Close this agenda early, right after the shell decision.
 Recommended direction:
 - establish naming before adding many more UI classes;
 - define a Studio-owned typed event system before workspaces start integrating services ad hoc;
 - invest in reusable components only where the shell or multiple workspaces will truly benefit;
 - require i18n and theme compliance for every Studio-specific control.
 ## Expected Follow-up
 - one or more Studio foundation decisions,
 - a foundational Studio spec,
 - a PR/plan for shared UI infrastructure in `prometeu-studio`.
--- a/docs/studio/agendas/01.7.
+++ b/docs/studio/agendas/01.7.
@ -1,60 +0,0 @@
 # Studio Components Module and Admission Policy Agenda
 ## Status
 Open
 ## Purpose
 Define the role of `prometeu-studio-components` and the rules for what should enter that module.
 The module now exists as a base project, but it should not become a dumping ground for wrappers around JavaFX controls or speculative framework work.
 ## Domain Owner
 `docs/studio`
 ## Context
 The Studio UI is about to be remodeled.
 We want:
 - a consistent Studio UI dialect;
 - reusable JavaFX-based Studio components;
 - easier customization and stronger engineering around shared controls;
 - continued compatibility with i18n and themes.
 At the same time, we explicitly do not want to populate the module prematurely.
 ## Current Direction
 `prometeu-studio-components` should remain empty until concrete Studio UI work requires shared controls.
 The baseline policy is:
 - the module exists now so Studio UI work has a clear home for shared components;
 - components are admitted only when they are needed by the current Studio UI wave;
 - the module should stay focused on real Studio shell and workspace needs, not general JavaFX abstraction for its own sake.
 ## Core Questions
 1. Which kinds of components belong in `prometeu-studio-components` from day 1?
 2. Which controls should remain local to `prometeu-studio` until a second use appears?
 3. What theme and i18n requirements must every admitted component satisfy?
 4. How much infrastructure should live in this module versus in Studio application code?
 5. How do we prevent the module from turning into a speculative component catalog?
 ## Recommendation
 Keep the module intentionally sparse.
 Recommended admission rule:
 - add a component when it is part of the shell or has immediate reuse in the current Studio UI work;
 - otherwise keep it local until the need is proven.
 ## Expected Follow-up
 - a decision on the admission policy for `prometeu-studio-components`;
 - a future spec or learn artifact once the first component wave actually exists.
--- a/docs/studio/agendas/README.md
+++ b/docs/studio/agendas/README.md
@ -11,16 +11,14 @@ The initial Studio UI planning wave is:
 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)
 6. [`01.6. Studio UI Foundations - Naming, Events, and Custom Components Agenda.md`](./01.6.%20Studio%20UI%20Foundations%20-%20Naming,%20Events,%20and%20Custom%20Components%20Agenda.md)
 7. [`01.7. Studio Components Module and Admission Policy Agenda.md`](./01.7.%20Studio%20Components%20Module%20and%20Admission%20Policy%20Agenda.md)
 Recommended discussion order:
-`01.6 -> 01.7 -> 01.1 -> 01.2 -> 01.3 -> 01.4 -> 01.5`
+`01.1 -> 01.2 -> 01.3 -> 01.4 -> 01.5`
-The Studio shell baseline was closed in [`../decisions/001-studio-shell-workspace-navigation-and-layout-decision.md`](../decisions/001-studio-shell-workspace-navigation-and-layout-decision.md).
+The shell, UI foundations, and components admission baselines were already consolidated into [`../specs/`](../specs/) and [`../learn/`](../learn/).
-The remaining order closes the shared UI foundations, then the components admission policy, then the asset workspace structure, and only after that the detailed interaction flows.
+The remaining order closes the asset workspace structure first, and only after that the detailed interaction flows.
 ## Purpose
--- a/docs/studio/decisions/001-studio-shell-workspace-navigation-and-layout-decision.md
+++ b/docs/studio/decisions/001-studio-shell-workspace-navigation-and-layout-decision.md
@ -1,145 +0,0 @@
 # Studio Shell, Workspace Navigation, and Layout Decision
 ## Status
 Accepted
 ## Cycle
 Studio UI Wave 01
 ## Context
 `prometeu-studio` already has a shell scaffold, but it was assembled manually and does not yet define a stable Studio UI contract.
 At the same time, the Studio is about to grow in at least these directions:
 - code editing;
 - asset management;
 - debugger and profiler work;
 - future shipping flows;
 - shared activity and run controls.
 The shell therefore needs to be stabilized before the Assets workspace and broader UI work expand further.
 This decision applies only to the Studio UI layer at this stage.
 It does not reopen unrelated service or domain contracts.
 ## Decision
 The Studio adopts a structured shell, not a fully docked IDE shell, for the current UI wave.
 The baseline shell is:
 - top global menu region;
 - left fixed workspace selector;
 - center workspace host;
 - right global utility panel with tabs;
 - top-right always-visible run surface.
 The shell must open through a lightweight project launcher or home surface before entering the main workspace frame.
 ## Invariants and Constraints
 ### Global Shell Regions
 The baseline mandatory shell regions are:
 - top global menus;
 - left workspace navigation;
 - center workspace host;
 - right global utility panel;
 - top-right run surface.
 Logs and detailed operational output do not belong to the global shell as a single shared console.
 They belong to the active workspace that owns the operation.
 ### Workspace Model
 The left-side workspace selector remains fixed for now.
 The baseline workspace set is:
 - Code Editor;
 - Asset Management;
 - Debugger/Profiler;
 - Shipper, temporarily represented by the current `BuilderWorkspace`.
 `BuilderWorkspace` may remain in the shell for now because it is still useful for testing, but it is a transitional surface and should receive minimal new investment until the future `Shipper` is properly defined.
 ### Right-Side Utility Panel
 The right-side global utility surface is tab-based.
 Baseline rules:
 - the initial tab set contains only `Activity`;
 - the panel must remain easy to extend with additional tabs later;
 - `Run` is not a tab.
 The right-side panel is for general Studio awareness and shell-level utility, not for per-workspace log dumping.
 ### Project Entry
 The Studio must not land directly into a workspace as the primary entry flow.
 Baseline behavior:
 - first show a lightweight project launcher or home surface;
 - show existing or recent projects;
 - expose `Open Project` and `Create Project` as first-class actions;
 - enter the main workspace shell only after a concrete project is selected or created.
 ### UI Remodeling Scope
 The Studio UI may be substantially remodeled in code during this wave.
 That flexibility is limited by these requirements:
 - theme support must be preserved;
 - i18n support must be preserved;
 - the resulting UI should create a clear path for reusable Studio components rather than ad hoc JavaFX fragments.
 ### No Fully Docked Shell Yet
 A fully docked IDE shell is explicitly deferred.
 Reasons:
 - shell topology is still being proven;
 - workspace responsibilities are still being defined;
 - early docking would force layout and lifecycle decisions too soon;
 - the extra complexity is not justified by the current product maturity.
 Dockability may be revisited only after shell regions and workspace panel responsibilities are stable in actual use.
 ## Explicit Non-Decisions
 This decision does not yet define:
 - the full set of future right-side tabs beyond `Activity`;
 - the detailed content model of the `Activity` surface;
 - the Studio event system architecture in detail;
 - custom component admission policy;
 - the internal panel composition of each workspace.
 Those topics remain delegated to follow-up Studio agendas and decisions.
 ## Propagation Targets
 This decision must propagate to:
 - Studio shell specifications under `docs/studio/specs/`;
 - Studio foundation work on naming, events, and custom components;
 - future PR/plan work for `MainView`, workspace switching, project launcher, and shell composition;
 - code implementation in `prometeu-studio` and future shared UI work in `prometeu-studio-components`.
 ## Validation Notes
 A conforming first UI wave should make these behaviors visible:
 - the user enters through a project launcher or home surface;
 - the shell shows a fixed workspace rail on the left;
 - the selected workspace owns its main body and its own logs;
 - the right side exposes `Activity` as a global utility surface;
 - run controls remain immediately visible without opening a tab.
--- a/docs/studio/decisions/README.md
+++ b/docs/studio/decisions/README.md
@ -2,9 +2,12 @@
 This directory contains Studio decision records.
-Current retained Studio decisions:
+There are currently no retained Studio decision records.
-1. [`001-studio-shell-workspace-navigation-and-layout-decision.md`](./001-studio-shell-workspace-navigation-and-layout-decision.md)
+The first Studio decision wave was already consolidated into:
 - normative specifications under [`../specs/`](../specs/)
 - didactic material under [`../learn/`](../learn/)
 ## Purpose
--- a/docs/studio/learn/README.md
+++ b/docs/studio/learn/README.md
@ -41,3 +41,10 @@ If content grows, prefer:
 - overview documents,
 - explicit learning paths,
 - consolidation of duplicated explanations.
 ## Current Learning Path
 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)
--- a/docs/studio/learn/mental-model-studio-events-and-components.md
+++ b/docs/studio/learn/mental-model-studio-events-and-components.md
@ -0,0 +1,76 @@
 # Studio Events and Components Mental Model
 Two things are meant to stop the Studio from becoming messy as it grows:
 - a typed event model;
 - a single authoritative control layer.
 These two rules solve different problems, but they reinforce each other.
 ## Why a Studio-owned event system?
 Without it, the shell, workspaces, and services begin to call each other directly.
 That usually feels fine at first, because the UI is small. Then the application gains:
 - global activity surfaces;
 - background operations;
 - multiple workspaces;
 - status and progress reporting;
 - cross-cutting actions such as run or diagnostics.
 At that point, direct references become the path of least resistance and the UI starts coupling itself in ways that are hard to unwind.
 The Studio event system exists to keep event publication explicit and typed.
 ## Why both a global bus and workspace buses?
 Because the Studio needs both segregation and shared visibility.
 Workspaces should be able to keep their local activity scoped.
 The shell should still be able to observe what is happening globally.
 The chosen rule is therefore:
 - each workspace has its own bus;
 - the Studio has a global bus;
 - every workspace event is automatically republished to the global bus.
 This means callers do not need to decide when to duplicate publication manually.
 ## Why not rely on raw JavaFX controls directly?
 Because raw JavaFX use spreads quickly and creates UI drift.
 When each part of the app consumes JavaFX controls directly, the Studio gradually accumulates:
 - inconsistent naming;
 - inconsistent styling hooks;
 - repeated local wrappers;
 - uneven behavior between screens;
 - more work each time theme or locale behavior needs to change.
 That is why the Studio uses `prometeu-studio-components` as its visual control layer.
 ## Does that mean reimplementing JavaFX?
 No.
 The goal is not to reproduce every JavaFX API.
 The goal is to expose the Studio-facing API the application actually needs.
 That keeps the control layer:
 - opinionated;
 - smaller than JavaFX;
 - aligned with the Studio's own UI dialect.
 ## Practical reading rule
 When adding UI code, ask two questions:
 1. Is this communication really an event?
 2. Is this control part of the Studio's visible dialect?
 If the answer to the first question is yes, it should probably publish a typed Studio event.
 If the answer to the second question is yes, it should probably come through `prometeu-studio-components`.
--- a/docs/studio/learn/mental-model-studio-shell.md
+++ b/docs/studio/learn/mental-model-studio-shell.md
@ -0,0 +1,60 @@
 # Studio Shell Mental Model
 The Studio shell exists to frame workspaces, not to absorb every piece of UI.
 That distinction matters because a lot of early JavaFX applications slowly become a single giant layout where every new concern gets added to the same frame. The shell model chosen here avoids that.
 ## What belongs to the shell?
 The shell owns:
 - project entry through a launcher or home surface;
 - global menus;
 - fixed workspace navigation;
 - the workspace host;
 - the right-side utility surface;
 - the always-visible run surface.
 The shell does not own the full operating detail of every domain workflow.
 ## What belongs to a workspace?
 A workspace owns its main body and its domain-specific detail.
 That includes things like:
 - editor-specific structure;
 - asset-management views;
 - debugger and profiler views;
 - workspace-local logs and detailed operational output.
 This is why the Studio does not define a mandatory single global console as the primary logging model.
 ## Why avoid a fully docked shell right now?
 Because the Studio is still proving its topology.
 If docking is introduced too early, the codebase starts solving these problems before the product actually needs them:
 - panel restore rules;
 - drag-and-drop docking behavior;
 - focus and lifecycle complexity;
 - layout persistence;
 - too many shell-level extension points.
 The structured shell keeps the frame stable without pretending the full IDE model is already known.
 ## Why is `Run` always visible?
 Because run is a primary action, not a secondary panel.
 If running the project requires opening a tab first, the shell is hiding one of the most important actions behind navigation friction. The Studio therefore treats `Run` as a persistent shell control.
 ## Practical reading rule
 When deciding whether something belongs in the shell or in a workspace, ask:
 > “Is this a Studio-wide framing concern, or is it operational detail of one workspace?”
 If it is framing, it belongs in the shell.
 If it is operational detail, it probably belongs in the workspace.
--- a/docs/studio/specs/1.
+++ b/docs/studio/specs/1.
@ -0,0 +1,105 @@
 # Studio Shell and Workspace Layout Specification
 Status: Draft
 Scope: Studio shell, project entry, and workspace frame
 Purpose: Define the normative shell structure of the Studio UI.
 ## Authority and Precedence
 This specification consolidates the accepted Studio shell decision into normative form.
 ## Normative Inputs
 - the Studio application shell
 - project entry or launcher flow
 - shell-level workspace navigation
 - shell-level utility and run surfaces
 ## Core Rules
 1. The Studio must open through a project launcher or home surface before entering the main workspace shell.
 2. The main shell must expose a top global menu region.
 3. The main shell must expose a left fixed workspace selector.
 4. The main shell must expose a center workspace host.
 5. The main shell must expose a right global utility panel.
 6. The main shell must expose an always-visible run surface in the top-right area.
 ## Project Entry
 The Studio must not land directly into a workspace as its primary entry behavior.
 Baseline project entry behavior is:
 - show a lightweight launcher or home surface first;
 - show existing or recent projects;
 - expose `Open Project` and `Create Project` as first-class actions;
 - enter the main workspace shell only after a concrete project is selected or created.
 ## Workspace Model
 The left workspace selector remains fixed in the baseline Studio shell.
 The baseline workspace set includes:
 - Code Editor;
 - Asset Management;
 - Debugger/Profiler;
 - Shipper, temporarily represented by the current `BuilderWorkspace`.
 `BuilderWorkspace` is transitional and must not be treated as a long-term architectural reference for the final shipping surface.
 ## Right Utility Panel
 The right-side global utility surface is tab-based.
 Baseline rules:
 - the initial tab set contains only `Activity`;
 - the panel must be extendable with additional tabs later;
 - `Run` is not a tab.
 The right utility panel exists for shell-level visibility and utility, not for general per-workspace log dumping.
 ## Logs and Operational Detail
 Detailed execution output belongs to the active workspace that owns the operation.
 Rules:
 - the shell must not define a single mandatory global console as the baseline logging model;
 - each workspace may expose its own logs, console, or detailed operational output;
 - shell-level utility surfaces may summarize shared activity, but they do not replace workspace-owned detail.
 ## UI Remodeling Scope
 The Studio UI may be remodeled substantially during this wave.
 That flexibility is constrained by:
 - theme support must remain preserved;
 - i18n support must remain preserved;
 - the resulting shell must keep a clear path for reusable Studio controls.
 ## Deferred Docking
 A fully docked IDE shell is not baseline behavior.
 Rules:
 - docking is explicitly deferred;
 - shell topology and workspace responsibilities must be proven first;
 - future dockability may be revisited only after the baseline shell is stable in actual use.
 ## Non-Goals
 - defining the full internal layout of every workspace
 - defining the final future tab set of the right utility panel
 - defining the detailed activity rendering model
 ## Exit Criteria
 This specification is complete enough when:
 - project entry and shell regions are unambiguous;
 - workspace and shell responsibilities are clearly separated;
 - the baseline Studio frame is stable enough for implementation planning.
--- a/docs/studio/specs/2.
+++ b/docs/studio/specs/2.
@ -0,0 +1,123 @@
 # Studio UI Foundations Specification
 Status: Draft
 Scope: Naming, event publication model, and Studio UI foundations
 Purpose: Define the shared infrastructure rules that all Studio UI work must follow.
 ## Authority and Precedence
 This specification consolidates the accepted Studio UI foundations decision into normative form.
 ## Normative Inputs
 - Studio shell structures
 - workspace UI structures
 - Studio-owned services
 - shell and workspace event publication needs
 - reusable Studio control infrastructure
 ## Core Rules
 1. Studio UI naming must be explicit by role.
 2. The Studio must define its own typed event system.
 3. The Studio event system must include one global bus and one bus per workspace.
 4. Every event published on a workspace bus must also be published on the global bus automatically.
 5. Studio UI must preserve theme and i18n compatibility by construction.
 ## Naming by Role
 Studio naming must follow role-oriented conventions.
 Baseline naming guidance:
 - `StudioShell*` for shell-level structures;
 - `*Workspace` for workspaces;
 - `*Panel` for composed regions or panels;
 - `*View` for focused visual views;
 - `*Item` or `*Row` for list and cell-like elements;
 - `StudioEvent*` for event types;
 - `*Service` for operational services;
 - `*Control` for reusable low-level visual controls.
 Names must communicate responsibility directly.
 Vague naming that hides shell, panel, workspace, or control roles is non-conforming.
 ## Studio Event System
 The Studio must not rely on stringly-typed event routing as its primary contract.
 Baseline event rules:
 - event publication is local to the process;
 - event publication is strongly typed;
 - event payloads are DTOs and should be immutable where practical;
 - the baseline model should remain intentionally small;
 - a large reactive framework is not baseline behavior.
 ## Global and Workspace Buses
 The baseline event topology includes:
 - one global `StudioEventBus`;
 - one workspace-local event bus per workspace.
 Propagation rules:
 - every event published on a workspace bus is automatically republished on the global bus;
 - propagation is workspace to global;
 - global-to-workspace rebroadcast is not baseline behavior.
 This topology exists so callers do not need to duplicate publication decisions manually.
 ## Event Categories
 The exact event catalog may evolve incrementally.
 Illustrative baseline categories include:
 - project lifecycle events;
 - workspace selection events;
 - run and build intent events;
 - activity publication events;
 - progress update events;
 - diagnostics update events;
 - asset selection events.
 ## Theme and i18n Compatibility
 Shared Studio UI foundations must preserve:
 - CSS-based theming;
 - locale-safe user-facing text behavior;
 - safe runtime locale updates where text changes dynamically;
 - no hardcoded user-facing text in reusable Studio controls.
 Theme and i18n compatibility are admission requirements for shared UI infrastructure.
 ## Foundation Boundary
 Shared Studio foundations include:
 - shell-level UI conventions;
 - event publication and observation infrastructure;
 - reusable Studio control conventions.
 Shared Studio foundations do not include:
 - domain-specific workspace business logic;
 - speculative control catalogs;
 - unrelated non-visual infrastructure that does not directly serve Studio UI.
 ## Non-Goals
 - defining the full event catalog in advance
 - defining every future workspace interaction
 - defining the first concrete control implementation wave in detail
 ## Exit Criteria
 This specification is complete enough when:
 - naming rules are stable enough to guide new Studio code;
 - the event topology is explicit;
 - theme and i18n constraints are unambiguous for shared Studio UI work.
--- a/docs/studio/specs/3.
+++ b/docs/studio/specs/3.
@ -0,0 +1,130 @@
 # Studio Components Module Specification
 Status: Draft
 Scope: `prometeu-studio-components` role, admission policy, and JavaFX wrapping boundary
 Purpose: Define the authoritative visual control layer for the Studio.
 ## Authority and Precedence
 This specification consolidates the accepted Studio components module decision into normative form.
 ## Normative Inputs
 - `prometeu-studio-components`
 - Studio shell and workspace UI needs
 - JavaFX controls actively used by the Studio
 ## Core Rules
 1. `prometeu-studio-components` is the official visual control module for Studio UI.
 2. Studio UI should normally consume visual controls from `prometeu-studio-components`, not directly from raw JavaFX.
 3. A control enters the module when it is needed by the current Studio UI wave.
 4. Controls in the module wrap and shape the JavaFX controls the Studio actively uses, but do not clone the full JavaFX API.
 5. Every admitted control must preserve theme and i18n compatibility.
 ## Module Role
 `prometeu-studio-components` is:
 - the authoritative Studio control layer;
 - the home of the Studio visual dialect;
 - the place where Studio-facing controls are shaped for Studio use.
 `prometeu-studio-components` is not:
 - a speculative generic framework;
 - a full reimplementation of JavaFX;
 - a dumping ground for unrelated non-visual infrastructure.
 ## Admission Policy
 A control is admissible when it is needed by the current Studio UI work.
 Rules:
 - immediate current Studio use is sufficient justification;
 - a second use is not required when the control is clearly part of the shell or the current workspace surface;
 - no control should be added without an immediate Studio consumer.
 ## Studio Usage Rule
 The baseline Studio UI should not rely on raw JavaFX controls as its normal visual surface.
 Rules:
 - a visual control used by Studio should normally come from `prometeu-studio-components`;
 - extremely trivial local composition may stay in `prometeu-studio`;
 - local exceptions must remain exceptional rather than becoming the default path.
 ## Wrapping Boundary
 Controls in `prometeu-studio-components` must wrap the JavaFX controls the Studio actively uses.
 Rules:
 - the Studio-layer control should expose the Studio-facing API actually needed;
 - exhaustive mirroring of upstream JavaFX APIs is not required;
 - the goal is consistency and clarity, not a perfect one-to-one mirror of every JavaFX type.
 ## Typical Control Scope
 Typical controls that belong in the module include:
 - shell controls;
 - action controls and buttons;
 - tab systems;
 - tree and list controls;
 - inspector and panel surfaces;
 - activity and feedback surfaces;
 - badges, headers, and related Studio primitives.
 What stays outside the module:
 - workspace-specific composition logic;
 - non-visual domain behavior;
 - speculative controls with no immediate Studio consumer.
 ## Theme and i18n
 Every admitted control must support:
 - CSS-based theming;
 - safe locale-aware text behavior when text is exposed;
 - no hardcoded user-facing text;
 - explicit visual states where state matters.
 ## Organization Guidance
 The module should be organized by Studio role rather than vague technical buckets.
 Illustrative areas include:
 - shell;
 - actions;
 - navigation;
 - feedback;
 - inspection;
 - trees.
 ## Anti-Bloat Rule
 The module must remain:
 - intentional;
 - Studio-driven;
 - small enough to reason about;
 - broad enough to prevent UI entropy in the application.
 ## Non-Goals
 - defining the first concrete component set in full detail
 - defining final package layout exhaustively
 - mirroring the entire JavaFX control hierarchy
 ## Exit Criteria
 This specification is complete enough when:
 - the module role is unambiguous;
 - admission rules are stable enough to guide implementation;
 - the JavaFX wrapping boundary is clear enough to prevent drift.
--- a/docs/studio/specs/README.md
+++ b/docs/studio/specs/README.md
@ -45,3 +45,19 @@ Specs should normally be fed by:
 4. then spec integration.
 If a spec edit would require guessing unresolved UI behavior, stop and surface the missing decision first.
 ## Current Corpus
 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)
 ## Reading Order
 Recommended order:
 1. shell and workspace layout;
 2. shared UI foundations;
 3. components module policy.