# Project-Local Studio State Specification

## Status

Active

## Applies To

- `prometeu-studio`
- Studio project-session persistence under `.studio/`
- project-local Studio session restoration state
- project-local Studio setup configuration

## Purpose

Define the normative contract for Studio project-local persistence under `.studio/`, including the boundary between the main session-restoration store and the dedicated setup configuration file.

## Authority and Precedence

This specification implements the accepted decision for project-local Studio state under `.studio/`.

It extends:

- [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
- [`5. Code Editor Workspace Specification.md`](5.%20Code%20Editor%20Workspace%20Specification.md)

## Core Rules

1. The canonical root for project-local Studio persistence MUST be `.studio/` in the project root.
2. The main project-local Studio session-restoration store MUST be owned by `StudioProjectSession`, or by a service explicitly owned by `StudioProjectSession`.
3. The main session-restoration store MUST remain a single file at `.studio/state.json`.
4. The main session-restoration store MUST be versioned.
5. The main session-restoration store MUST load when the project session opens.
6. Restorable shell and editor state accepted by this wave MUST restore when the project shell mounts.
7. The main session-restoration store MUST save when the project shell or project session closes.
8. Missing, invalid, or schema-incompatible session-restoration state MUST fall back to safe default values and MUST NOT block project open.
9. Project-local setup configuration MUST live in a separate file at `.studio/setup.json`.
10. Project-local setup MUST NOT participate in the `.studio/state.json` snapshot lifecycle.
11. Project-local setup MUST be read through a dedicated DTO/file boundary when a consumer needs it.

## Accepted Wave-1 Categories

The main session-restoration store MUST include:

- `shellLayout`
- `openShellState`
- `editorRestoration`

Wave-1 accepted meaning is:

- `shellLayout`: restorable layout state already accepted by implementation, including divider positions and equivalent layout proportions for accepted workspaces such as `Assets` and `Code Editor`, `Project Navigator` expansion state, and editor dock-panel open/closed plus restored-size configuration;
- `openShellState`: which workspace or equivalent shell-owned project view was open;
- `editorRestoration`: open editor tabs and active tab.

## Project-Local Setup Configuration

Project-local setup is a separate persistence concern under `.studio/`.

Rules:

- project-local setup MUST live in `.studio/setup.json`;
- project-local setup MUST be treated as project configuration rather than session state;
- project-local setup MAY contain runtime-oriented values such as the Prometeu runtime path;
- project-local setup MUST own the project-wide editor indentation policy;
- the editor indentation policy MUST define at least indentation mode and indentation width;
- when setup does not provide an explicit indentation policy, consumers MUST resolve it to `spaces` with width `4`;
- project-local setup MAY grow with additional manual or automatic configuration keys over time;
- consumers such as `Play` MUST read project-local setup from the dedicated setup file rather than from `.studio/state.json`;
- this revision uses a dry format change and MUST NOT preserve compatibility with the obsolete shape where `projectLocalSetup` was embedded in `.studio/state.json`.

## Explicit Exclusions

The main session-restoration store MUST NOT include:

- project-local setup configuration;
- project-local activity history;
- derived cache;
- transient hover-only or equivalent ephemeral UI state;
- heavy operational output;
- recomputable results that do not represent session restoration state.

`Project-local activity` and project-local setup may still live under `.studio/`, but they are separate persistence concerns and not part of the main session-restoration store defined here.

## Ownership Rules

- shell and workspace UI may consume the main session-restoration store through project-session-owned contracts;
- shell and workspace UI must not define competing primary persistence files for accepted wave-1 categories;
- project-local setup may be consumed before a dedicated settings UI exists;
- project-local setup readers must not turn the setup file into another session snapshot by convenience.

## Non-Goals

- defining persistence for project-local activity
- introducing a multi-file main store in this wave
- defining a settings editor UI for project-local setup
- persisting arbitrary transient workspace detail by convenience

## Exit Criteria

This specification is complete enough when:

- the `.studio/` boundary is unambiguous;
- accepted and excluded categories are explicit;
- load, restore, save, and fallback timing are explicit;
- and the ownership boundary with `StudioProjectSession` is normatively locked.