# Pack Wizard Shell

## Original Problem

The `Assets` workspace already had a reserved `Pack` action, but that did not answer the real product question:

How should Studio behave when the developer wants to pack the current build set?

The risk was building a visually plausible modal that quietly reimplemented packer semantics or hid the real operational phases.

## Consolidated Decision

The stable first-wave rule is:

`Pack` is a Studio-owned wizard shell over packer-owned operations.

The wizard is phase-based:

1. `Summary`
2. `Validation`
3. `Packing`
4. `Result`

Studio owns presentation and state binding.
Packer owns summary, validation, execution, progress, and result semantics.

## Final Model

### 1. Workspace-Level Entry Point

- `Pack` is a workspace action, not a selected-asset action;
- the user is operating on the current pack set, not on one asset in isolation.

### 2. Summary

- the wizard asks packer for the current build-set summary;
- Studio does not count navigator rows and pretend that is the build set;
- the canonical runtime artifact is explicitly `assets.pa`.

### 3. Validation

- validation runs only on `registered + included in build`;
- blocking diagnostics stop the flow before execution;
- warnings may be visible, but they do not become blockers unless packer classifies them that way.

### 4. Packing

- execution is operational and non-editable;
- progress comes from packer-owned progress state or events;
- the UI does not simulate progress with timers;
- the first wave is non-cancelable.

### 5. Result

- the primary summary shows final status, packed asset count, elapsed time, and `assets.pa`;
- companion artifacts are supporting detail, not the headline of the result screen;
- the UI must distinguish blocked, failed, and successful outcomes.

## Examples

### Example: Why validation is a separate phase

If the wizard jumps straight from summary into execution, the user loses the explicit gate that explains why packing is blocked.
Validation exists to make the gate understandable before byte emission begins.

### Example: Why Studio must not fake progress

A fake progress bar may look smoother, but it lies about operational ownership.
If the packer is the owner of execution semantics, the UI must reflect packer-owned progress honestly.

## Common Pitfalls and Anti-Patterns

- Treating pack summary as a local Studio recomputation.
- Using one opaque modal state instead of explicit operational phases.
- Letting unrelated assets influence wizard validation.
- Exposing fake cancel behavior that the packer does not actually support.
- Making companion artifacts dominate the main result summary.

## References

- Specs:
  - [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
- Cross-domain:
  - [`../../packer/learn/pack-wizard-summary-validation-and-pack-execution.md`](../../packer/learn/pack-wizard-summary-validation-and-pack-execution.md)
  - [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
- Related learn:
  - [`./assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md)