# Project-Scoped State and Activity

## Original Problem

Some Studio state is global by nature, but some state is clearly tied to one opened project.

If project-local state is stored as if it were application-global, the shell starts mixing unrelated histories and the project root stops being the obvious home of Studio-owned project data.

## Consolidated Decision

The stable direction is:

1. project-local Studio state lives under `.studio/` inside the project root;
2. shell activity is restored and persisted per project;
3. persisted activity history is bounded;
4. `.studio/` is the reserved root for future project-local Studio settings.

## Final Model

### 1. Storage Root

- each project owns `.studio/`;
- new-project scaffolding creates that directory;
- `.workspace/` is not the project-local Studio root for this model.

### 2. Activity Persistence

- shell activity is loaded when the project opens;
- new activity is appended to that project's local history;
- history is trimmed to the latest `500` entries.

### 3. Scope Rule

- project-local shell history belongs to the project;
- launcher-global concerns remain outside this storage path;
- future Studio project configuration can live under the same `.studio/` root.

## Examples

### Example: Why activity cannot stay application-global

If two projects have one shared persisted feed, the shell stops teaching the user what happened in the currently opened project.
That destroys causality instead of preserving it.

## Common Pitfalls and Anti-Patterns

- Treating project activity as if it were launcher-global state.
- Mixing unrelated projects into one persisted activity history.
- Leaving project-local Studio files in ad hoc roots instead of `.studio/`.
- Letting unbounded activity persistence grow without a hard cap.

## References

- Specs:
  - [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
- Related learn:
  - [`./mental-model-studio-shell.md`](./mental-model-studio-shell.md)