# Workspace Architecture

Milestone 4.1 introduces Sapling's first filesystem-backed workspace experience.

## Source Of Truth

A workspace is a folder on disk.

Sapling does not create workspace manifests, project registries, content databases, or any other authoritative copy of workspace contents. The application may persist UI and application settings, such as the last opened workspace path, but the filesystem remains the source of truth for folders, files, and projects.

Workspace contents are discovered by scanning the selected root directory and building an in-memory tree. That tree can be rebuilt at any time from the filesystem.

## Filesystem Scanning

`LocalWorkspaceManager` recursively scans the workspace root and derives:

- folders from directories
- files from regular filesystem items
- projects from directories containing `.git`

Hidden files and `.git` internals are excluded from the visible tree. Project directories remain browsable tree nodes, but they are visually distinguished from ordinary folders.

The scanner performs no Git operations. Repository detection is based only on filesystem metadata.

## Workspace Tree

The workspace tree answers:

> What exists?

It represents the current filesystem hierarchy and should not own editor state, cursor position, scroll position, unsaved changes, or tab state.

The sidebar uses the derived tree to display folders, Markdown files, other files, and Git-backed projects. Folder and project nodes are collapsible so large hierarchies can be browsed incrementally.

## Document Sessions

Document sessions answer:

> What is open?

`DocumentSessionStore` owns open Markdown document sessions independently from the workspace tree. Each session owns its `HybridMarkdownEditorViewModel`, which contains editor state for the document.

A file may only have one document session within the active workspace. Opening an already-open Markdown file activates the existing session instead of creating a duplicate editor state.

Opening a new workspace clears document sessions from the previous workspace.

## Persisted State

Sapling persists the last opened workspace URL in `SaplingConfiguration`.

It does not persist workspace contents. Files, folders, and projects are always rediscovered from disk.