docs: update session manager docs

Author: devmobasa

README.md

@@ -224,9 +224,12 @@ For distro-specific package details, see [Installation](#installation). For keyb
 - Copy to clipboard or save to file
 - Uses `grim`, `slurp`, `wl-clipboard` (installed automatically by deb/rpm/AUR packages; fallback: xdg-desktop-portal)
 
-### Session Persistence
-- Opt-in per board/monitor canvas + tool state restore
-- CLI overrides: `--resume-session` / `--no-resume-session`
+### Session Manager & Persistence
+- Session persistence is enabled by default for boards, undo/redo history, and tool state
+- Per-output default sessions, plus named session files with `--session-file`
+- Overlay Session panel: Open, Save As, Info, Clear, recent sessions, and Manager
+- Configurator Session tab: rename/reveal/forget catalog entries, plus duplicate/move/clear inactive session files
+- CLI overrides: `--resume-session`, `--no-resume-session`, `--session-info`, and `--clear-session`
 - Tray checkmark flips config on disk
 
 ### Toolbars & UI
@@ -788,7 +791,7 @@ ui_animation_fps = 30
 # named boards + backgrounds
 ```
 
-### Session Persistence
+### Session Manager & Persistence
 
 Enable via configurator (<kbd>F11</kbd> → Session tab), CLI flags, or the tray checkmark (writes to config).
 
@@ -798,15 +801,19 @@ wayscriber --no-resume-session   # disable resume for this run
 wayscriber --session-info        # inspect saved sessions
 wayscriber --clear-session       # remove stored boards
 wayscriber --active --session-file ~/Documents/lecture-04.wayscriber-session
+wayscriber --freeze --session-file ~/Documents/lecture-04.wayscriber-session
 wayscriber --daemon --session-file ~/Documents/lecture-04.wayscriber-session
 wayscriber --daemon-toggle --session-file ~/Documents/meeting.wayscriber-session
 wayscriber --session-info --session-file ~/Documents/lecture-04.wayscriber-session
+wayscriber --clear-session --session-file ~/Documents/lecture-04.wayscriber-session
 ```
 
 Notes:
 - When `restore_tool_state` is enabled (default), the last-used tool settings (including arrow head placement) override config defaults on startup. Disable it in the Session tab or clear the session to force config values.
-- `--session-file` uses exactly the selected file, implies persistence for that overlay run, and does not create missing parent directories. A running daemon can launch a hidden overlay with a named target; if the overlay is already visible, hide it before switching to a different named session.
-- The configurator Session tab can manage recent named sessions: rename catalog labels, reveal files, and forget metadata. When no overlay/background service is active, it can duplicate a session by copying its primary file, move inactive session files, and clear saved data.
+- `--session-file` uses exactly the selected file, implies persistence for that overlay run, rejects directories/symlinks/special files, and does not create missing parent directories. A running daemon can launch a hidden overlay with a named target; if the overlay is already visible, hide it before switching to a different named session.
+- The overlay Session panel lives in the side toolbar's Settings drawer. It can open an existing named session, save the current overlay as another named session, show session info, clear the active session, reopen recent named sessions, and jump to the configurator. The Open/Save As dialogs use `zenity` or `kdialog`; Save As appends `.wayscriber-session` when no extension is supplied and asks before replacing existing session artifacts.
+- The configurator Session tab manages recent named sessions recorded when named-session targets are opened or saved from the CLI, daemon, or overlay. It can rename catalog labels, reveal files, and forget metadata without touching files. Duplicate, Move, and Clear are disabled while an overlay, manually started daemon, or background service is active.
+- See [Session manager examples](examples/session-manager.md) for complete CLI, overlay, and configurator workflows.
 
 ### Tablet/Stylus Support
 
@@ -922,7 +929,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project structure,
 - [x] Native Wayland layer-shell
 - [x] Daemon mode with system tray
 - [x] Multiple customizable boards/backgrounds
-- [x] Session persistence (with CLI override + tray config toggle)
+- [x] Session manager and persistence (named sessions, overlay actions, configurator catalog, CLI override, tray config toggle)
 - [x] Highlighter & eraser tools
 - [x] Additional shapes (filled shapes)
 - [x] Color picker

config.example.toml

@@ -686,6 +686,10 @@ storage = "auto"
 
 # CLI note: --session-file PATH bypasses this storage directory for that run and
 # saves to exactly PATH, without creating missing parent directories.
+# The overlay Session panel can Open, Save As, inspect, clear, and reopen recent
+# named sessions. Save As appends .wayscriber-session when no extension is used.
+# The configurator Session tab can rename/reveal/forget catalog entries, and can
+# duplicate, move, or clear inactive session files when no overlay/daemon is running.
 
 # Store separate sessions per monitor (set false to reuse one file per display)
 per_output = true

configurator/README.md

@@ -32,7 +32,7 @@ The window loads the current config, lets you tweak values across the tabbed sec
 - **Drawing, Arrow, Performance, UI, Board, Capture** – numeric fields with inline validation, toggles, and color editors (RGBA/RGB components).
 - **Default color** – toggle between named colors and custom RGB triples.
 - **Keybindings** – per-action comma-separated shortcut lists that map to `KeybindingsConfig`.
-- **Session** – persistence settings plus named-session catalog management: rename display labels, reveal files, forget metadata, and clear saved data when no overlay/background service is active.
+- **Session** – persistence settings plus named-session catalog management. Rename display labels, reveal files, and forget metadata without touching files. Duplicate, Move, and Clear are disabled while an overlay, manually started daemon, or background service is active.
 - Live dirty-state indicator plus status banner for success/error details.
 
 ## Building Releases

docs/CONFIG.md

@@ -892,17 +892,29 @@ Use the CLI helpers for quick maintenance:
 - `wayscriber --daemon --session-file ~/Documents/lecture-04.wayscriber-session` starts a daemon whose overlay activations use that named session target.
 - `wayscriber --daemon-toggle --session-file ~/Documents/meeting.wayscriber-session` asks the running daemon to launch a hidden overlay with that named session target. If the overlay is already visible with a different target, hide it before switching.
 - `wayscriber --session-info --session-file <path>` and `wayscriber --clear-session --session-file <path>` inspect or remove only that named file and its sidecars.
-- The configurator Session tab also shows recent named sessions from the catalog. It can rename catalog display labels, reveal file locations, and forget catalog metadata without touching files. When no overlay/background service is active, it can duplicate a session by copying its primary file to a new target, move inactive session files and their non-lock sidecars to a new path, and clear saved data.
+
+The overlay Session panel lives in the side toolbar's Settings drawer:
+
+- `Open` loads an existing named session, saves dirty current data first when needed, and records the target in the recent catalog.
+- `Save As` writes the current overlay to another named session and switches the active target. It appends `.wayscriber-session` when no extension is supplied and asks before replacing existing session artifacts.
+- `Info` reports the active session file size, board shape counts, and history status.
+- `Clear` writes a durable empty session boundary for the active target.
+- Recent session rows reopen other named sessions. If a recent target is missing, Wayscriber removes that stale catalog entry after the failed open.
+- `Manager` opens the configurator. Overlay Open/Save As dialogs use `zenity` or `kdialog`.
+
+The configurator Session tab also shows recent named sessions from the catalog, recorded when named-session targets are opened or saved from the CLI, daemon, or overlay. It can rename catalog display labels, reveal file locations, and forget catalog metadata without touching files. Duplicate, Move, and Clear are disabled while an overlay, manually started daemon, or background service is active.
 
 Session overrides and recovery:
 
 - CLI flags: `--resume-session` forces persistence on, `--no-resume-session` forces it off for the current run. The environment variable `WAYSCRIBER_RESUME_SESSION=1/0` does the same.
-- `--session-file` implies session persistence for that overlay run and conflicts with `--no-resume-session`. Named sessions use the exact selected file path; Wayscriber does not create missing parent directories or fall back to configured storage.
+- `--session-file` implies session persistence for that overlay run and conflicts with `--no-resume-session`. Named sessions use the exact selected file path; Wayscriber does not create missing parent directories or fall back to configured storage. Foreground/open targets reject directories, symlinks, and special files.
 - Size fallback: if visible drawings fit but persisted undo/redo history would exceed save or restore safety limits, autosave saves the drawings and warns once per run that history was trimmed or omitted.
 - Image paste guard: when a pasted image would push visible session data over `max_file_size_mb`, Wayscriber blocks the paste and points you to `[session] max_file_size_mb`; when only undo history is at risk, the paste is allowed with a warning.
 - Load safety: compressed session files are checked against an internal expanded-size cap while saving and loading. If an existing file expands beyond that cap, wayscriber refuses to load it, leaves the primary session file unchanged, and avoids overwriting it until session data changes.
 - Recovery: if a session file is corrupt or cannot be parsed/decompressed, wayscriber logs a warning, writes a `.bak` copy of the bad file, removes the corrupt file, and continues with defaults. Overrides above still apply after recovery.
 
+For end-to-end CLI, overlay, and configurator flows, see [`examples/session-manager.md`](../examples/session-manager.md).
+
 ### `[keybindings]` - Custom Keybindings
 
 Customize keyboard shortcuts for all actions. Each action can have multiple keybindings.

docs/codebase-overview.md

@@ -7,7 +7,7 @@ This document explains how the application boots, how user input travels through
 ## 1. Execution Flow From `main.rs`
 
 1. **CLI parsing (`src/main.rs`)**
-   - Uses `clap` to parse `--daemon`, `--active`, `--mode`, and session management flags.
+   - Uses the manual parser in `src/cli.rs` for `--daemon`, `--active`, `--mode`, named session, and session maintenance flags.
    - Verifies `WAYLAND_DISPLAY` when a Wayland session is required.
 
 2. **Mode selection**
@@ -17,6 +17,7 @@ This document explains how the application boots, how user input travels through
 
 3. **Shared subsystems automatically pulled in**
    - `config`: loads user settings, key bindings, and drawing defaults.
+   - `session`: builds configured or named session targets, validates `--session-file`, loads saved state, and records named-session catalog entries.
 
 ---
 
@@ -133,7 +134,25 @@ Notifications are sent via `notification::send_notification_async`, keeping all
 
 ---
 
-## 7. Utility Modules
+## 7. Session Persistence and Named Session Manager
+
+**Modules:**
+- `src/session/`: target options, primary-file validation, snapshot load/save, sidecars, clear/recovery markers, locks, catalog metadata, and inactive file operations.
+- `src/backend/wayland/session/`: runtime Open, Save As, and Clear transactions for the active overlay.
+- `src/backend/wayland/state/toolbar/events/session.rs`: overlay Session panel routing for Open, Save As, Info, Clear, recent sessions, and configurator launch.
+- `src/daemon/`: accepts daemon-toggle requests that carry an optional named session target.
+
+**Flow:**
+1. CLI `--session-file` creates a named target instead of using configured storage. Named targets force persistence for that run, reject `--no-resume-session`, require an existing parent directory for foreground/open flows, and reject directories, symlinks, and special files.
+2. Backend startup builds `SessionOptions` from config plus any named target, then session loading restores boards/history/tool state before rendering begins.
+3. Runtime Open first saves dirty current data when needed, loads the candidate named session without mutating it, replaces board state only after a valid load, and records the open in the named-session catalog.
+4. Runtime Save As validates the target, prompts before replacing existing artifacts, writes the snapshot, switches the active target, and records the save in the catalog.
+5. Runtime Clear writes a durable empty-session boundary so older backup or recovery artifacts do not restore stale drawings.
+6. The configurator reads the same catalog for inactive-session management: rename/reveal/forget metadata, duplicate primary files, move non-lock sidecars, and clear saved data when daemon/overlay locks are absent.
+
+---
+
+## 8. Utility Modules
 
 - **`src/draw/`**: Shape definitions, Cairo helpers, arrow geometry, fonts, and the `CanvasSet` abstraction (with undo/history per board mode).
 - **`src/ui.rs`**: Composes the status bar and help overlay using Cairo.
@@ -143,7 +162,7 @@ Notifications are sent via `notification::send_notification_async`, keeping all
 
 ---
 
-## 8. Directory Map (excluding configurator)
+## 9. Directory Map (excluding configurator)
 
 | Path | Role |
 |------|------|
@@ -155,19 +174,21 @@ Notifications are sent via `notification::send_notification_async`, keeping all
 | `src/ui.rs` | Status/help overlays. |
 | `src/capture/` | Screenshot pipeline (manager, dependencies, sources, clipboard/file helpers). |
 | `src/config/` | Config parsing, defaults, keybinding map. |
+| `src/session/` | Configured and named session persistence, snapshots, sidecars, locks, and catalog metadata. |
 | `src/notification.rs` | Desktop notifications for capture results. |
 | `src/util.rs` | Shared math/color utilities. |
 | `tests/` | CLI + rendering integration tests. |
 
 ---
 
-## 9. Putting It Together
+## 10. Putting It Together
 
 1. **Launch** via CLI → choose daemon vs active.
 2. **Daemon** provides lifecycle management, tray integration, and toggles the backend on demand.
 3. **Backend** sets up Wayland surfaces and loops, forwarding input to `InputState`.
 4. **InputState + draw/ui** update the overlay contents and request renders.
 5. **Capture** subsystem handles screenshot actions asynchronously and notifies the user.
-6. **Config** module ensures user preferences are honored everywhere.
+6. **Session** loads and saves configured or named session state, including runtime Open/Save As/Clear transactions.
+7. **Config** module ensures user preferences are honored everywhere.
 
 Use this document to trace any feature: locate the entry point (CLI, tray, keybinding), follow it through the backend/input/capture stacks, and consult the relevant modules listed above for details.

examples/session-manager.md

@@ -0,0 +1,76 @@
+# Session Manager Examples
+
+These examples cover named sessions. Default persistence still works without a
+named file: start Wayscriber normally and it restores the configured session
+storage on the next run.
+
+## Direct CLI Workflows
+
+Use a named session file when you want one drawing set per meeting, lecture, or
+project:
+
+```bash
+wayscriber --active --session-file ~/Documents/lecture-04.wayscriber-session
+wayscriber --freeze --session-file ~/Documents/lecture-04.wayscriber-session
+```
+
+Named sessions can also be the target for daemon launches:
+
+```bash
+wayscriber --daemon --session-file ~/Documents/default-work.wayscriber-session
+wayscriber --daemon-toggle --session-file ~/Documents/meeting.wayscriber-session
+```
+
+Inspect or clear one named session without touching the configured default
+session:
+
+```bash
+wayscriber --session-info --session-file ~/Documents/lecture-04.wayscriber-session
+wayscriber --clear-session --session-file ~/Documents/lecture-04.wayscriber-session
+```
+
+`--session-file` uses the exact selected file, rejects directories, symlinks,
+and special files, and conflicts with `--no-resume-session`. Launch, Open, and
+Save As flows require an existing parent directory. `--session-info` and
+`--clear-session` can still report or clean up stale named-session paths when
+the parent directory is already gone.
+
+## Overlay Workflow
+
+Open Wayscriber with any persisted session target, then use the side toolbar's
+Settings drawer:
+
+- `Open` loads an existing named session and records it in the recent catalog.
+- `Save As` writes the current overlay to another named session and switches the
+  active target. It appends `.wayscriber-session` when no extension is supplied
+  and asks before replacing existing session artifacts.
+- `Info` reports the active session file size, board shape counts, and history
+  status.
+- `Clear` writes a durable empty session boundary for the active target.
+- Recent session rows reopen other named sessions.
+- `Manager` opens the configurator.
+
+The overlay file picker uses `zenity` first and falls back to `kdialog`.
+
+## Configurator Catalog Workflow
+
+Run:
+
+```bash
+wayscriber-configurator
+```
+
+Open the Session tab and use the Saved Sessions section. It shows recent named
+sessions recorded when named-session targets are opened or saved from the CLI,
+daemon, or overlay.
+
+- `Save Name` changes only the catalog display label.
+- `Reveal File` opens the session's parent folder.
+- `Forget` removes catalog metadata without deleting session files.
+- `Duplicate` copies the primary session file to a new named target.
+- `Move` moves an inactive session's primary file and non-lock sidecars.
+- `Clear Saved Data` removes saved data and sidecars for that catalog entry.
+
+Duplicate, Move, and Clear are disabled while an overlay, manually started
+daemon, or background service is active. Stop the service or close the overlay
+before managing inactive session files from the configurator.