---
id: LSN-0033
ticket: studio-editor-indentation-policy-and-project-setup
title: Setup-Owned Indentation Policy and Project Bootstrap Defaults
created: 2026-04-04
tags: [studio, editor, indentation, tabs, setup, dot-studio, project-creation, gitignore]
---

## Historical Status

This lesson documents indentation policy choices made for the removed embedded Studio editor. Keep it as historical context only; do not treat it as current product guidance after `DEC-0031`.

## Context

The Studio editor exposed an indentation chip in the status bar, but that chip was driven by file-content heuristics rather than by a stable editor policy.
At the same time, `Tab` insertion did not obey the displayed value, which made the editor self-contradictory during normal editing.

The work also surfaced a second bootstrap problem: project creation already owned `.studio/` and `.workspace/`, but it was not yet treating project-local setup and baseline ignore rules as first-class bootstrapped assets.

## Key Decisions

### Project-Local Setup Owns Editor Indentation Policy

**What:**
The active indentation policy is now owned by `.studio/setup.json`, loaded into memory once per project session, shown in the status bar, and used directly by editable-document `Tab` handling.

**Why:**
The status bar must show the active policy, not a moving guess.
If `Tab` behavior and the visible chip disagree, the editor loses trust immediately.

**Trade-offs:**
This first wave intentionally stays project-wide.
It does not attempt per-file or per-language precedence, and it does not reformat existing files that already diverge from the configured policy.

### Project Creation Must Bootstrap Real Project-Local Setup

**What:**
The project-creation wizard now includes a dedicated details step before location selection.
That step captures indentation width and Prometeu runtime path and persists them into `.studio/setup.json`.

**Why:**
Indentation policy and runtime path are project-local configuration, so they should exist from project birth rather than appear later as ad hoc repair.

**Trade-offs:**
Project creation becomes a little longer, but the result is a better-initialized project and a cleaner setup boundary.

### New Projects Must Ship With a Baseline `.gitignore`

**What:**
Project bootstrap now writes a root `.gitignore` with Studio-local state and common OS junk excluded by default.

**Why:**
`.studio/` and `.workspace/` are local machine artifacts and should not depend on users remembering to ignore them later.
The same applies to common macOS, Windows, and Linux metadata noise.

**Trade-offs:**
The generated file is intentionally conservative and generic rather than ecosystem-specific.

## Final Implementation

The final state established these rules in code and specs:

- `ProjectLocalStudioSetup` now carries editor indentation configuration with default resolution to `Spaces: 4`.
- `ProjectLocalStudioSetupService` now supports both loading and saving setup data.
- `StudioProjectSession` loads setup once and keeps it available in memory for runtime consumers.
- `EditorStatusBar` now renders configured indentation policy instead of inspecting file contents.
- `EditorWorkspace` converts `Tab` into the configured number of spaces for editable files.
- `NewProjectWizard` now captures indentation width and runtime path on a dedicated details step before location.
- `ProjectCatalogService` persists `.studio/setup.json` and writes a baseline `.gitignore` during project creation.

## Patterns and Algorithms

### Pattern: Policy Chips Must Reflect Runtime Policy, Not Content Heuristics

If a status-bar chip describes how the editor will behave, it must be backed by the same runtime value that input handling uses.
Do not derive policy chips from observed content when the editor behavior is actually driven elsewhere.

### Pattern: Load Setup Once, Use It Repeatedly

Project-local setup is durable configuration, not per-keystroke state.
Load it at project-session time, keep the resolved value in memory, and let editor interactions consume that in-memory representation directly.

### Pattern: Bootstrap Project Hygiene at Creation Time

If a project requires local-only directories such as `.studio/` or `.workspace/`, generate the corresponding `.gitignore` entries when the project is created.
Do not push that responsibility onto users later.

## Pitfalls

- Do not let the status-bar indentation chip switch based on whatever indentation currently exists in the open file.
- Do not make `Tab` obey one rule while the chip displays another.
- Do not reread `.studio/setup.json` on every editing interaction just because the file is durable configuration.
- Do not auto-reformat preexisting file content just because a project now has a configured indentation policy.
- Do not keep `.studio/` and `.workspace/` out of `.gitignore` and expect users to fix repository hygiene manually.

## References

- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md`
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/8. Project-Local Studio State Specification.md`
- `prometeu-studio/src/main/java/p/studio/projectstate/ProjectLocalStudioSetup.java`
- `prometeu-studio/src/main/java/p/studio/projectstate/ProjectLocalStudioSetupService.java`
- `prometeu-studio/src/main/java/p/studio/window/NewProjectWizard.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
- `prometeu-studio/src/main/java/p/studio/projects/ProjectCatalogService.java`

## Takeaways

- Editor policy must be explicit, stable, and shared between UI and input handling.
- `.studio/setup.json` is the right owner for project-local editor configuration such as indentation and runtime path.
- Project creation should bootstrap both configuration and repository hygiene, not leave them as follow-up chores.
