---
id: LSN-0008
ticket: studio-docs-import
title: Project-scoped state and activity legacy lesson
created: 2026-03-26
tags:
  - studio
  - legacy-import
  - project-state
  - activity
---

## Context

Legacy import from `docs/studio/learn/project-scoped-state-and-activity.md`.

This lesson preserves the rule for project-local Studio state and shell activity persistence.

Relevant spec:

- `docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md`

## Key Decisions

### Project-local Studio state should live under `.studio/` inside the project root

**What:** Project-local Studio state should be rooted at `.studio/`, shell activity should be persisted and restored per project, persisted history should be bounded, and `.studio/` should remain the reserved root for future project-local Studio settings.
**Why:** If project-local state is stored as if it were application-global, the shell mixes unrelated histories and stops teaching what happened in the currently opened project.
**Trade-offs:** This design requires project-scoped persistence logic and bounded retention, but it preserves causality and keeps Studio-owned project data in one obvious root.

## Patterns and Algorithms

- Create `.studio/` during new-project scaffolding.
- Load shell activity when the project opens.
- Append new activity to the current project's local history.
- Trim persisted activity to the latest `500` entries.
- Keep launcher-global concerns outside the project-local `.studio/` root.

## Pitfalls

- Treating project activity as launcher-global state.
- Mixing multiple projects into one persisted activity history.
- Leaving project-local Studio files in ad hoc roots instead of `.studio/`.
- Allowing activity persistence to grow without a hard cap.

## Takeaways

- Project-local history must preserve causality for the currently opened project.
- `.studio/` is the reserved home for project-scoped Studio state.
- Legacy source attribution: `docs/studio/learn/project-scoped-state-and-activity.md`.