docs: correct concepts the redesign made false

Three claims had drifted from the code, and a stale document is worse
than a missing one because it is trusted.

MEMORY #8 and STACK.md both said the CodeEditSourceEditor exposure was
contained to two files. Three import it: EditorState.swift has imported
it for IndentOption all along. Counted, corrected, and the rule is now
'keep it at three' with the third named and the reason it is thin.

STACK.md and ARCHITECTURE.md both described a UI-to-App notification
seam. There was no seam left. The sidebar lost its Open Folder button
when the empty state moved to the canvas, which left
.codeEditorOpenFolder with a subscriber and no publisher; and
.codeEditorOpenFiles posted and observed inside CodeEditorApp, a round
trip to nowhere. Both names are deleted and presentOpenFilePanel calls
AppState directly.

Session restore was described as restoring 'the workspace and tabs',
which reads as resuming work. It persists paths and never buffer
content, so quitting with unsaved changes loses them silently while the
tab still reopens. Stated plainly in CURRENT_STATE, README and the type's
own MEMORY entry.

Also: PROCESS and PROJECT_PLAN still claimed 35 tests, README's module
table predated the Core and Themes additions, ARCHITECTURE had no
account of the find-panel sync, session restore or quick open flows, and
two anchors in AGENTS.md pointed at headings that do not exist.

Author: yan

AGENTS.md

@@ -94,7 +94,8 @@ Never imply in a commit message or PR that CI verified the build. It did not.
 - **No magic numbers in chrome.** Spacing, radii and fixed heights come from `Metrics`
   (`CodeEditorCore`); the 4pt grid is enforced by a test. Chrome type comes from
   `Typography` — semantic styles only, so it scales with the user's text size. Code keeps a
-  fixed-size SF Mono. See [MEMORY.md](docs/MEMORY.md#11) for why these rules exist.
+  fixed-size SF Mono. See [MEMORY.md](docs/MEMORY.md#11-never-derive-appearance-from-colour-arithmetic)
+  for why these rules exist.
 
 ## Traps that will bite
 
@@ -108,7 +109,8 @@ Never imply in a commit message or PR that CI verified the build. It did not.
 - A `.onTapGesture` on a row inside a `List(selection:)` never fires. Drive row behaviour
   from the selection change. See [MEMORY.md #12](docs/MEMORY.md#12-a-tap-gesture-inside-a-selection-list-is-swallowed).
 - Do not put a `.frame` on a `NavigationSplitView` column; `.navigationSplitViewColumnWidth`
-  already sizes it. See [MEMORY.md #13](docs/MEMORY.md).
+  already sizes it. See
+  [MEMORY.md #13](docs/MEMORY.md#13-navigationsplitview-columns-are-sized-in-one-place).
 
 ## Before you call it done
 

PROJECT_PLAN.md

@@ -30,7 +30,7 @@ tracked in GitHub, ordered in [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md).
 ## Quality gates
 
 - [x] Builds with no warnings
-- [x] `swift test` passes (35 tests)
+- [x] `swift test` passes (68 tests)
 - [x] `swift-format lint --strict` clean
 - [ ] CI builds the package — blocked, see [docs/MEMORY.md](docs/MEMORY.md#1-ci-cannot-build-this-package-do-not-try-to-make-it)
 - [ ] Completion works for Swift

README.md

@@ -29,8 +29,9 @@ an embedded shell in the same window.
   the divider above it to resize; the height is remembered.
 - **Themes** — Dark, Light and High Contrast, persisted across launches along with font
   size, tab width, word wrap, minimap, folding ribbon and invisibles.
-- **Session restore** — reopens your workspace and tabs on launch. Untitled documents are
-  not restored.
+- **Session restore** — reopens your workspace and tabs on launch. It restores *what you
+  had open*, not your edits: unsaved buffers are not persisted, and untitled documents
+  have no path to replay.
 - **Menu commands** — ⌘N, ⌘O, ⇧⌘O, ⌘F, ⌘P, ⌘S, ⌥⌘S, ⌘W, ⌘B, ⌃`, ⇧⌘L for theme.
 
 ### Interface notes
@@ -118,12 +119,12 @@ add a `build` job and drop the caveat.
 
 | Module | Responsibility |
 |---|---|
-| `CodeEditorCore` | `Document`, `DocumentManager`, `TextSelectionManager`, `FileSystemManager`. No UI. |
-| `CodeEditorThemes` | `Theme`, `EditorColor`, `ThemeManager` with persisted selection. |
+| `CodeEditorCore` | `Document`, `DocumentManager`, `TextSelectionManager`, `FileSystemManager`, `FileOutline`, `QuickOpenMatcher`, `QuickOpenIndex`, `SessionStore`, `Metrics`. No UI — Foundation only. |
+| `CodeEditorThemes` | `Theme`, `Chrome`, `Semantic`, `Typography`, `EditorColor`, `ThemeManager` with persisted selection. |
 | `CodeEditorTerminal` | `TerminalSession`: shell subprocess, line-buffered scrollback, history. |
 | `CodeEditorLSP` | `JSONRPCTransport` (Content-Length framing) and `LSPClient`. Not yet wired into the UI. |
-| `CodeEditorUI` | SwiftUI views: editor, sidebar, terminal, plus `AppState`. |
-| `CodeEditorApp` | The `@main` App, menu commands, window layout. |
+| `CodeEditorUI` | SwiftUI views: editor, sidebar, tabs, status bar, empty state, quick open, terminal, plus `AppState`. |
+| `CodeEditorApp` | The `@main` App, menu commands, window layout, toolbar. |
 
 Dependencies flow one way: `Core` ← `UI` ← `App`. `Themes`, `Terminal` and `LSP` are
 leaves that `UI` composes.

Sources/CodeEditorApp/Sources/CodeEditorApp.swift

@@ -14,19 +14,6 @@ struct CodeEditorApp: App {
         Window("Code Editor", id: "main-window") {
             MainWindowView(appState: appState)
                 .frame(minWidth: 720, minHeight: 480)
-                .onReceive(
-                    NotificationCenter.default.publisher(for: .codeEditorOpenFolder)
-                ) { _ in
-                    appState.openFolder()
-                }
-                .onReceive(
-                    NotificationCenter.default.publisher(for: .codeEditorOpenFiles)
-                ) { notification in
-                    guard let urls = notification.object as? [URL] else { return }
-                    for url in urls {
-                        appState.openFile(url)
-                    }
-                }
         }
         .defaultSize(width: 1200, height: 800)
         .commands { commands }
@@ -182,9 +169,8 @@ struct CodeEditorApp: App {
         panel.prompt = "Open"
 
         guard panel.runModal() == .OK else { return }
-        NotificationCenter.default.post(
-            name: .codeEditorOpenFiles,
-            object: panel.urls
-        )
+        for url in panel.urls {
+            appState.openFile(url)
+        }
     }
 }

Sources/CodeEditorUI/Sources/Sidebar/FileExplorerView.swift

@@ -264,13 +264,3 @@ public struct FileExplorerView: View {
         }
     }
 }
-
-// MARK: - Notifications
-
-extension Notification.Name {
-    /// Posted by the sidebar to ask the app to present an open-folder panel.
-    public static let codeEditorOpenFolder = Notification.Name("CodeEditor.openFolder")
-
-    /// Posted by the app with an array of `URL`s to open in the editor.
-    public static let codeEditorOpenFiles = Notification.Name("CodeEditor.openFiles")
-}

docs/ARCHITECTURE.md

@@ -81,6 +81,26 @@ would need a re-entrancy guard against the text view writing while SwiftUI is mi
 **Consequence:** `Document` mutations that originate outside the text view (nothing today)
 would fight the binding. If you add one, route it through the view, not around it.
 
+## Three more flows worth knowing
+
+**Find panel.** One flag, two owners. `EditorState.isFindVisible` is ours;
+`SourceEditorState.findPanelVisible` is the editor's. `CodeEditorView` syncs them both ways,
+and the panel is the authority: when the user dismisses the panel, the coordinator writes
+`findPanelVisible = false`, which we mirror back onto `EditorState`. ⌘F only ever sets our
+flag. Nothing in the app draws a find UI.
+
+**Session restore.** `AppState` is the `DocumentManagerDelegate`, so opening and closing a
+document persists a `SessionSnapshot` — workspace root, open tab paths, active path — to
+`UserDefaults` via `SessionStore`. On launch it replays it. Untitled documents are skipped
+because they have no path to replay. A vanished root clears the snapshot rather than leaving
+a window that restores nothing.
+
+**Quick open.** `QuickOpenIndex` walks the workspace off the main actor in batches and
+publishes each batch only if its generation is still current, so a superseded walk is
+dropped rather than interleaved. `QuickOpenMatcher` scores candidates per keystroke against
+what is already indexed; the palette renders and nothing else. It is a snapshot — see
+[CURRENT_STATE.md](CURRENT_STATE.md).
+
 ## Caching and identity
 
 `FileSystemManager` keys its directory cache on `url.standardizedFileURL.path`, not `URL`.
@@ -166,8 +186,12 @@ Anything that grows a filesystem dependency should use it.
   state disagrees with it. The panel stays the authority on its own visibility.
 - `TreeSitterClient.Constants.longParse` — a notification name from the upstream module.
   The editor surfaces it as a parse indicator; nothing else depends on it.
-- `Notification.Name.codeEditorOpenFolder` / `codeEditorOpenFiles` — `UI` posts, `App`
-  observes. Replace with a closure when a second consumer appears.
+- `Notification.Name.codeEditorOpenFolder` / `codeEditorOpenFiles` — **removed.** The seam
+  existed because the sidebar used to own an "Open Folder" button and could not call
+  `AppState` directly. It can now: the sidebar takes an `onCreateIn` closure and the canvas
+  empty state takes `onOpenFolder`, and the panel itself lives in `AppState`. Both
+  notifications posted and observed inside `CodeEditorApp`, which is a round trip to
+  nowhere. Call closures.
 - `FileSystemManager.load` returns rows synchronously from a cache while populating it
   asynchronously. The view re-renders as children arrive. Fine for a tree; would need
   thought for a list that must not reflow.

docs/CURRENT_STATE.md

@@ -82,6 +82,13 @@ security-scoped bookmarks. See [MEMORY.md](MEMORY.md).
 
 **Untitled documents are not restored.** They have no stable identity across launches.
 
+**Session restore reopens paths, not edits.** The snapshot stores the workspace root, tab
+paths and active path — never buffer content. Quit with unsaved changes and the tab comes
+back showing what is on disk, with the edits gone and no prompt on the way out. Restoring
+buffers would mean writing them somewhere, and there is no untitled-document story yet
+either. The honest version of this feature is "reopens what you had open", not "resumes
+your session".
+
 **No multi-cursor.** `TextSelectionManager` models multiple selections and `Document` stores
 them, but the text view drives a single caret.
 

docs/MEMORY.md

@@ -156,14 +156,21 @@ interop and belongs behind a testable protocol.
 
 Pinned `from: "0.15.2"`, so 0.16 lands automatically. That is intentional.
 
-Exposure is contained to two files:
+Exposure is contained to three files, all in `Editor/`:
 
-- `Sources/CodeEditorUI/Sources/Editor/EditorTheme+Bridge.swift` — the only place that
-  constructs `EditorTheme.Attribute`
-- `Sources/CodeEditorUI/Sources/Editor/CodeEditorView.swift` — `SourceEditor` and
-  `SourceEditorConfiguration`
+- `EditorTheme+Bridge.swift` — the only place that constructs `EditorTheme.Attribute`
+- `CodeEditorView.swift` — `SourceEditor`, `SourceEditorConfiguration` and its nested
+  `Appearance` / `Behavior` / `Peripherals`, `InvisibleCharactersConfiguration`,
+  `BracketPairEmphasis`
+- `EditorState.swift` — `IndentOption` only, because indent is an editor preference
 
-Keep it that way. If a third file starts naming upstream types, the boundary has leaked.
+The first two are the deliberate boundary. The third is a thin type reference; if you move
+`IndentOption` out of the editor's configuration, that import can go too.
+
+**Keep it at three.** If a fourth file starts naming upstream types, the boundary has
+leaked. The count was wrong in the docs for a while — they said two while `EditorState.swift`
+had been importing it all along — which is the reason to go and count instead of repeating
+the claim.
 
 Known break: 0.8.1 → 0.15 changed the API completely (`CodeEditorSourceEditor` with
 `cursorPositions:` became `SourceEditor` with `state: SourceEditorState`), and 0.8.1 no
@@ -305,6 +312,12 @@ about a *state*, not about a *range*. Deriving it from the range without checkin
 the range is degenerate is how you get a readout that is wrong in the one case everybody
 sees first.
 
+The same shape bit the session snapshot, and it is worth checking every "restore" feature
+against: it persists *paths*, never buffer content. Quit with unsaved changes and the tab
+returns showing what is on disk — the edits are gone and nothing said so on the way out.
+A feature named "restore" will be read as "resume"; say which one it is, in the docs and
+in the UI.
+
 ---
 
 ## Quick reference

docs/PROCESS.md

@@ -20,7 +20,7 @@ swift build && swift test
 swift-format lint --recursive --strict --configuration .swift-format Sources Tests
 ```
 
-All three, before every push. 35 tests, about 30 seconds.
+All three, before every push. 68 tests in 16 suites, about 30 seconds.
 
 `swift-format format --in-place --recursive --configuration .swift-format Sources Tests`
 when lint complains about formatting.

docs/STACK.md

@@ -6,7 +6,7 @@
 |---|---|---|
 | Swift | 6.4 (6.4.0.34.1) | `swift-tools-version: 6.4`, Swift 6 language mode |
 | Xcode | 16+ | `ApproachableConcurrency` enabled per target |
-| macOS deployment | 14.0 | `@Observable`, `.onChange(of:initial:)` |
+| macOS deployment | 14.0 | `@Observable`, `.onChange(of:initial:)`, `.onKeyPress`, `.formStyle(.grouped)` |
 | Build system | SwiftPM | no Xcode project, no workspace |
 
 Developed against macOS 27.0.1 arm64. Nothing in the code is version-specific above 14.0;
@@ -39,9 +39,17 @@ wired, and running two text engines in one app buys nothing.
 the `SourceEditor` + `SourceEditorConfiguration` shape this code targets.
 
 Pinning is `from: "0.15.2"`, so 0.16 will be picked up automatically. That is deliberate:
-the upstream package is pre-1.0 and moves. The exposure is contained to one file —
-`Sources/CodeEditorUI/Sources/Editor/EditorTheme+Bridge.swift` — which is the only place
-that touches upstream types beyond `SourceEditor` itself. See [MEMORY.md](MEMORY.md).
+the upstream package is pre-1.0 and moves. The exposure is contained to three files under
+`Sources/CodeEditorUI/Sources/Editor/`: `CodeEditorView.swift` (`SourceEditor`,
+`SourceEditorConfiguration` and its nested `Appearance`/`Behavior`/`Peripherals`,
+`InvisibleCharactersConfiguration`, `BracketPairEmphasis`), `EditorTheme+Bridge.swift`
+(`EditorTheme` and its `Attribute`), and `EditorState.swift` for `IndentOption` alone. A
+fourth file naming upstream types means the boundary has leaked. See
+[MEMORY.md](MEMORY.md#8-codeeditsourceeditor-is-pre-10-and-moves).
+
+0.15 also ships the pieces this app had no reason to rebuild: a find-and-replace panel
+driven by `SourceEditorState.findPanelVisible`, code-folding ribbon, minimap, invisibles
+and warning-character rendering. Finding them meant not designing a ⌘F UI at all.
 
 ## Tooling
 
@@ -69,10 +77,11 @@ compile errors in the original scaffold were exactly this.
 **`NavigationSplitView` for the layout.** Resizable sidebar, system-standard behaviour, free
 on macOS 14+.
 
-**Notifications between `UI` and `App`.** `FileExplorerView` posts `.codeEditorOpenFolder`;
-`CodeEditorApp` observes it. This keeps `NSOpenPanel` out of the view and avoids `UI`
-importing `AppKit` panel code. It is a small seam to replace with a closure when a second
-consumer appears.
+**No notifications between `UI` and `App`.** There used to be: the sidebar posted
+`.codeEditorOpenFolder` because it could not call `AppState`. It can — views take closures
+(`onOpenFile`, `onCreateIn`, `onOpenFolder`) and the panel logic lives in `AppState`, not in
+a view. Both notification names are gone. `NSOpenPanel` still does not appear in the view
+layer, because `AppState` owns the commands.
 
 ## Alternatives rejected
 
@@ -82,4 +91,7 @@ consumer appears.
 | Write our own text view | NSTextView already does selection, undo, IME, accessibility. Reimplementing is a year. |
 | Runestone | Duplicate text engine, no tree-sitter integration. |
 | SwiftLSPClient | Abandoned upstream. The LSP layer here is small and worth owning. |
-| `develop` branch | One line of work. Doubles merge cost for nothing. See [BRANCHING.md](BRANCHING.md). |
+| `develop` branch | One line of work. Doubles merge cost for nothing. See [BRANCHING.md](BRANCHING.md). |
+| Hand-rolled find/replace | 0.15 ships one. See above. |
+| Hand-rolled folding ribbon, minimap, invisibles | 0.15 ships all three as `Peripherals`. |
+| More built-in themes | Each one is a palette someone has to maintain and review, for a choice most users make once. Three is enough. |