docs(decisions): separate workspace tree from document sessions

decisions.md

@@ -778,3 +778,123 @@ Users should own their notes, projects, attachments, and repositories without de
 A workspace should remain a normal directory that can be understood and manipulated using standard operating system tools.
 
 Sapling should adapt to the filesystem rather than requiring the filesystem to adapt to Sapling.
+
+---
+
+# D-016 — Workspace Tree and Document Sessions Are Separate Concepts
+
+## Status
+
+Accepted
+
+## Date
+
+2026-06-02
+
+## Context
+
+A filesystem-backed workspace naturally describes what exists on disk.
+
+However, the user interface must also represent documents that are currently open for editing.
+
+These concerns are related but distinct.
+
+Historically many editors conflate:
+
+* selected file
+* open file
+* visible editor
+
+This makes future features such as tabs, split views, and multiple windows difficult to implement.
+
+## Decision
+
+Sapling separates:
+
+### Workspace Tree
+
+Represents:
+
+* folders
+* projects
+* files
+
+derived from the filesystem.
+
+The workspace tree answers:
+
+"What exists?"
+
+### Document Sessions
+
+Represents:
+
+* open documents
+* editor state
+* cursor position
+* scroll position
+* unsaved state
+
+The document session answers:
+
+"What is currently being edited?"
+
+## Principles
+
+Selecting a file does not imply ownership of editor state.
+
+A document may exist in:
+
+* the workspace tree
+* a tab
+* a split view
+* a separate window
+
+without changing its identity.
+
+Document state belongs to the document session.
+
+Not the workspace tree.
+
+## Tab Model
+
+Tabs are a presentation of document sessions.
+
+A file may only have one document session within a workspace.
+
+Opening an already-open document should activate its existing session rather than creating a duplicate.
+
+## Future Compatibility
+
+This decision intentionally supports:
+
+* tabs
+* split views
+* multiple windows
+* session restoration
+
+without requiring changes to the workspace model.
+
+These features are presentation concerns built on top of document sessions rather than filesystem discovery.
+
+## Consequences
+
+### Positive
+
+* Clear separation of responsibilities.
+* Simplifies workspace discovery.
+* Enables future UI layouts.
+* Prevents duplicated editor state.
+
+### Negative
+
+* Introduces an additional abstraction layer.
+* Requires explicit session management.
+
+## Rationale
+
+The filesystem should describe what exists.
+
+Document sessions should describe what is being edited.
+
+Keeping these concerns separate allows Sapling to evolve its user interface without revisiting the workspace architecture.