docs: add repo-wide and module-scoped AGENTS guidance

.gitattributes

@@ -0,0 +1,10 @@
+* text=auto eol=lf
+
+*.png binary
+*.ico binary
+*.jpg binary
+*.jpeg binary
+*.webp binary
+*.pdf binary
+*.gz binary
+*.zip binary

.github/AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS.md
+
+## Scope
+- Applies to GitHub workflows, issue templates, and repository automation under `.github/`.
+
+## Architecture
+- Workflows should mirror local CI and release/package validation.
+- Release automation depends on version checks, packaging manifests, Nix/package checks, artifact upload, and repository publishing behavior.
+
+## Invariants
+- Keep CI aligned with `./tools/lint-and-test.sh`.
+- Keep Linux system dependencies aligned with real build needs for Wayland, Cairo, Pango, Iced, D-Bus, packaging, and Nix checks.
+- Do not weaken release checks or skip package layout/version validation without a documented reason.
+
+## Coupled Changes
+- Workflow dependency changes may require updates to `tools/`, `packaging/`, `flake.nix`, and setup docs.
+- Release workflow changes may require updates to version scripts and packaging manifests.
+
+## Validation
+- Prefer local script validation before changing CI.
+- For workflow-only edits, run `git diff --check` and inspect YAML carefully.

.gitignore

@@ -14,7 +14,7 @@
 *.swo
 
 # Local agent instructions
-AGENTS.md
+AGENTS.local.md
 CLAUDE.md
 
 
@@ -29,6 +29,8 @@ tools/release.sh
 # Packaging (but keep the service file)
 packaging/**
 !packaging/wayscriber.service
+!packaging/AGENTS.md
+!packaging/.SRCINFO
 !packaging/PKGBUILD
 !packaging/package.wayscriber.yaml
 !packaging/package.configurator.yaml

AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md
+
+## Scope
+- This file applies to the whole wayscriber workspace.
+- wayscriber is a Rust desktop annotation app for Wayland compositors.
+- The workspace root crate is `wayscriber`; `configurator/` is a separate Iced desktop configurator crate.
+- Both crates use Rust 1.95 and edition 2024.
+- The workspace default member is only the root crate; use `-p wayscriber-configurator` or `--workspace` when configurator coverage is needed.
+
+## Architecture
+- The main app starts in `src/main.rs`, parses CLI state, then routes through `src/app/` into daemon mode or active Wayland overlay mode.
+- Shared library modules are exported from `src/lib.rs` for tests and the configurator; binary-only modules stay private to `src/main.rs`.
+- Core domains are backend/Wayland runtime, input state, drawing data/rendering, overlay UI, capture, config, session persistence, daemon lifecycle, canvas export, and configurator UI.
+- Start with `README.md`, `CONTRIBUTING.md`, `docs/codebase-overview.md`, `docs/CONFIG.md`, and `configurator/README.md` when changing behavior.
+
+## Invariants
+- Preserve foreground and fullscreen safety: do not launch, foreground, focus, or interact with another app/window, especially fullscreen apps, without explicit user permission.
+- Treat `cargo run`, `wayscriber --active`, `wayscriber --daemon`, `wayscriber-configurator`, and manual UI checks as potentially foreground/focus-affecting unless proven otherwise.
+- Preserve feature-gate intent for `tablet-input`, `dbus`, `portal`, `tray`, and `config-schema`.
+- Do not edit generated/build output such as `target/`.
+- Preserve existing Rust module style. This repo intentionally mixes `foo.rs`, `foo/`, and `foo/mod.rs`.
+- For Rust split modules, an `AGENTS.md` in `foo/` does not apply to sibling `foo.rs`; put shared rules in the parent guide.
+
+## Coupled Changes
+- Config changes often require `config.example.toml`, `docs/CONFIG.md`, configurator models/views, schema behavior, and tests.
+- Tool/action/keybinding changes often require config defaults, action metadata, help/command UI, toolbar UI, configurator labels/search, docs, and tests.
+- Daemon, service, shortcut, path, and packaging changes often need updates across `src/daemon/`, `src/paths/`, `src/systemd_user_service.rs`, `src/shortcut_hint.rs`, `configurator/src/app/daemon_setup/`, and `packaging/`.
+
+## Validation
+- Full local CI is `./tools/lint-and-test.sh`.
+- That script runs version/package checks, `cargo fmt --all -- --check`, clippy with all targets/features, all-feature tests, and no-default-feature tests.
+- For docs-only `AGENTS.md` edits, make new files visible to Git before whitespace checks, for example `rg --files --hidden -g AGENTS.md -0 | xargs -0 git add -N --` followed by `git diff --check`.
+- On PowerShell, use `rg --files --hidden -g AGENTS.md | ForEach-Object { git add -N -- $_ }` followed by `git diff --check`.
+- If you do not want to alter the index, run an explicit trailing-whitespace check across the untracked `AGENTS.md` files instead of relying on plain `git diff --check`.

configurator/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md
+
+## Scope
+- Applies to the `wayscriber-configurator` crate.
+- This is a separate Iced desktop crate that reuses core `wayscriber` config and session types.
+
+## Architecture
+- `configurator/src/main.rs` is the binary entry point.
+- `configurator/src/messages.rs` owns top-level UI messages.
+- `configurator/src/app/` owns app state, update logic, views, daemon setup, search, subscriptions, I/O, and session catalog operations.
+- `configurator/src/models/` owns editable models, parsing, validation, conversion to core config/session types, labels, search data, and reusable fields.
+
+## Invariants
+- Keep `wayscriber` dependency usage compatible with `default-features = false`; do not pull portal D-Bus or tray runtime behavior into the configurator binary.
+- Views should emit messages and render state; file/process work belongs in update tasks or side-effect modules.
+- Invalid user input should remain visible and actionable instead of being silently coerced or dropped.
+
+## Coupled Changes
+- Main config changes often require configurator draft models, setters, `to_config/`, views, updates, labels, search terms, docs, and tests.
+- Daemon setup changes must stay aligned with `src/daemon/`, `src/systemd_user_service.rs`, `src/shortcut_hint.rs`, and `packaging/wayscriber.service`.
+- Session catalog changes must stay aligned with `src/session/` lock, artifact, catalog, and path behavior.
+
+## Validation
+- Run `cargo test -p wayscriber-configurator` or targeted configurator tests for model/update changes.
+- Use `cargo run -p wayscriber-configurator` for manual UI checks when user-approved foreground app launch is acceptable.
+- Run full local CI for workspace-level config/session changes.

configurator/src/AGENTS.md

@@ -0,0 +1,24 @@
+# AGENTS.md
+
+## Scope
+- Applies to configurator source code under `configurator/src/`.
+
+## Architecture
+- `main.rs` starts the Iced app.
+- `messages.rs` defines the top-level message surface.
+- `app/` owns state, update handlers, views, subscriptions, side effects, search, daemon setup, and session catalog workflows.
+- `models/` owns draft/editable data and conversion to/from core wayscriber types.
+- `test_env.rs` and `test_temp.rs` provide isolated test helpers.
+
+## Invariants
+- Keep message routing explicit and centralized.
+- Keep view code side-effect free; route I/O and process work through update tasks or app-side helper modules.
+- Preserve `default-features = false` use of the core crate.
+
+## Coupled Changes
+- Configurator changes often mirror main crate config, action metadata, keybindings, session, daemon setup, and path behavior.
+- Search and labels must stay aligned with visible configuration sections and option names.
+
+## Validation
+- Use targeted tests under `configurator/src/models/`, `configurator/src/app/search/`, or `configurator/src/app/update/`.
+- Run `cargo test -p wayscriber-configurator` for broad configurator changes.

configurator/src/app/AGENTS.md

@@ -0,0 +1,27 @@
+# AGENTS.md
+
+## Scope
+- Applies to configurator app state, updates, views, side effects, daemon setup, search, subscriptions, and session catalog operations.
+- Parent guidance here covers sibling files such as `session_catalog.rs`; child guides under `session_catalog/` should cover helper internals only.
+
+## Architecture
+- `state.rs` owns top-level app state.
+- `update/` handles `Message` variants and returns `iced::Task<Message>`.
+- `view/` builds Iced UI from state.
+- `io.rs`, `daemon_setup/`, `session_catalog.rs`, `session_catalog/`, `search/`, and `subscription.rs` perform side-effecting or app-wide work.
+
+## Invariants
+- Do not do file/process work directly from view code.
+- Preserve non-blocking task behavior and explicit validation feedback.
+- Session catalog operations must preserve lock checks, artifact movement, primary-file behavior, catalog collision handling, and rollback.
+- Daemon setup behavior must stay aligned with daemon runtime, shared service/shortcut helpers, and packaging service files.
+
+## Coupled Changes
+- App changes may require model, message, view, search, docs, and tests updates.
+- Daemon setup changes may require `src/daemon/`, `src/systemd_user_service.rs`, `src/shortcut_hint.rs`, `src/paths/`, and `packaging/wayscriber.service`.
+- Session catalog changes may require `src/session/` and `src/paths/` updates.
+
+## Validation
+- Add focused tests near update/search/session catalog helpers where possible.
+- Run `cargo test -p wayscriber-configurator` for app behavior changes.
+- Manually run the configurator only when launching a foreground app is explicitly acceptable.

configurator/src/app/daemon_setup/AGENTS.md

@@ -0,0 +1,19 @@
+# AGENTS.md
+
+## Scope
+- Applies to configurator daemon setup helpers under `configurator/src/app/daemon_setup/`.
+
+## Architecture
+- Owns setup commands, Hyprland shortcut integration, systemd user service behavior, and shortcut helper UI flows.
+
+## Invariants
+- Keep daemon setup aligned with daemon runtime behavior, shared service/shortcut helpers, and packaging service files.
+- Avoid blocking UI update paths; use tasks for process/file operations.
+- Preserve clear user-facing errors for setup failures.
+
+## Coupled Changes
+- Daemon setup changes may affect `src/daemon/`, `src/systemd_user_service.rs`, `src/shortcut_hint.rs`, `src/paths/`, `packaging/wayscriber.service`, setup docs, and tests.
+
+## Validation
+- Add focused tests for command/service/shortcut helpers where possible.
+- Run configurator tests for daemon setup behavior changes.

configurator/src/app/session_catalog/AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+## Scope
+- Applies only to helper modules under `configurator/src/app/session_catalog/`.
+- The sibling root `configurator/src/app/session_catalog.rs` is governed by `configurator/src/app/AGENTS.md`.
+
+## Architecture
+- Helper modules support inactive-session duplicate, move, and tests.
+- They coordinate with core session catalog, artifact, lock, and path behavior.
+
+## Invariants
+- Preserve runtime lock checks, primary-file behavior, catalog collision checks, artifact movement, rollback behavior, and error reporting.
+- Do not mutate inactive sessions without validating target paths and lock state.
+
+## Coupled Changes
+- Session catalog helper changes may affect `src/session/`, `src/paths/`, configurator app state/update/view, and tests.
+
+## Validation
+- Add focused tests under this subtree for duplicate/move behavior.
+- Run configurator tests for session catalog changes.

configurator/src/app/update/AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+## Scope
+- Applies to configurator update handlers under `configurator/src/app/update/`.
+
+## Architecture
+- Update modules handle `Message` variants and return `iced::Task<Message>` for async work.
+- Modules are split by config sections and workflows such as boards, daemon, fields, presets, render profiles, session catalog, and tabs.
+
+## Invariants
+- Keep update routing centralized and explicit.
+- Preserve non-blocking I/O/process work through tasks.
+- Surface validation errors instead of silently coercing invalid input.
+
+## Coupled Changes
+- Update changes may affect messages, state, views, models, search, docs, and tests.
+
+## Validation
+- Add focused update tests where available.
+- Run `cargo test -p wayscriber-configurator` for broad app behavior changes.

configurator/src/app/view/AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+## Scope
+- Applies to configurator Iced views under `configurator/src/app/view/`.
+
+## Architecture
+- View modules build UI for config sections, daemon setup, session settings, render profiles, themes, presets, boards, and shared widgets.
+- Views should render state and emit messages; side effects belong in updates or app helper modules.
+
+## Invariants
+- Keep labels, defaults, validation states, section ordering, and search-visible text aligned with models/docs.
+- Do not do file/process work directly from view code.
+- Keep reusable widgets consistent across sections.
+
+## Coupled Changes
+- View changes may affect models, update messages, search terms, docs, and tests.
+
+## Validation
+- Run configurator tests for model/view coupling changes.
+- Manually launch the configurator only when foreground app launch is explicitly acceptable.

configurator/src/models/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+## Scope
+- Applies to configurator models under `configurator/src/models/`.
+
+## Architecture
+- Models convert editable UI fields to/from core wayscriber config and session types.
+- `config/` owns draft config and conversion to core config.
+- `fields/` owns reusable form field wrappers.
+- `keybindings/` owns keybinding draft/parsing/labels.
+- Color, session, search, daemon, tab, and utility models support app state and views.
+
+## Invariants
+- Invalid user input should surface as form errors, not silent coercion.
+- Keep defaults, labels, parsing, and conversion aligned with main crate config/session/action metadata.
+
+## Coupled Changes
+- Model changes may affect configurator views/updates/search, main `src/config/`, `src/session/`, action metadata, docs, and tests.
+
+## Validation
+- Add focused model tests.
+- Run `cargo test -p wayscriber-configurator` for broad model changes.

configurator/src/models/config/AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+## Scope
+- Applies to configurator config draft models, parsing, setters, board/render profile models, toolbar overrides, and conversion to core config.
+
+## Architecture
+- `draft/` loads editable state from core config.
+- `to_config/` converts validated draft state back to `wayscriber::config::Config`.
+- Section files mirror main config areas such as boards, presets, render profiles, and toolbar overrides.
+
+## Invariants
+- Keep draft defaults and conversion behavior aligned with `src/config/types/` and `src/config/validate/`.
+- Preserve validation feedback; do not silently discard invalid user input.
+
+## Coupled Changes
+- Config model changes may require configurator views/updates/search, `config.example.toml`, `docs/CONFIG.md`, schema behavior, and tests.
+
+## Validation
+- Add or update tests under `configurator/src/models/config/`.
+- Run main config tests when conversion behavior mirrors core config changes.

configurator/src/models/fields/AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+## Scope
+- Applies to reusable configurator field models under `configurator/src/models/fields/`.
+
+## Architecture
+- Field modules wrap editable values, validation state, and conversion for UI forms.
+- Tool, toolbar, status, session, pressure, presenter, font, export, eraser, and toggle fields support model/view/update workflows.
+
+## Invariants
+- Invalid input should stay visible and report a form error; do not silently coerce or drop user input.
+- Keep field defaults and validation aligned with core config validation and configurator views.
+
+## Coupled Changes
+- Field changes may affect config draft conversion, views, updates, search labels, docs, and tests.
+- Tool field changes must stay aligned with `src/input/tool/`, config defaults, action metadata, and toolbar UI.
+
+## Validation
+- Add focused field tests under this subtree.
+- Run configurator model tests for field behavior changes.

configurator/src/models/keybindings/AGENTS.md

@@ -0,0 +1,18 @@
+# AGENTS.md
+
+## Scope
+- Applies to configurator keybinding models under `configurator/src/models/keybindings/`.
+
+## Architecture
+- Owns draft keybinding state, parsing, field-level labels/config read/write, grouping, and tests.
+
+## Invariants
+- Keep action labels, categories, defaults, parsing, and display aligned with `src/config/keybindings/` and `src/config/action_meta/`.
+- Invalid keybinding input should remain visible and actionable.
+
+## Coupled Changes
+- Keybinding model changes may affect configurator views/updates, main keybinding maps, action metadata, help overlay, command palette, docs, and tests.
+
+## Validation
+- Add focused keybinding model tests.
+- Run main config/keybinding tests for shared action behavior changes.

docs/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+## Scope
+- Applies to repository documentation under `docs/`.
+
+## Architecture
+- `docs/CONFIG.md` is the user-facing config guide.
+- `docs/SETUP.md` documents installation/setup workflows.
+- `docs/codebase-overview.md` is architecture reference material for the main crate.
+- `docs/temp/` is draft and planning material unless a file explicitly says otherwise.
+
+## Invariants
+- Keep user-facing docs aligned with current CLI behavior, config behavior, `config.example.toml`, README usage, and configurator UI.
+- Do not treat `docs/temp/` drafts as authoritative product documentation.
+
+## Coupled Changes
+- Config docs may need updates when `src/config/`, `config.example.toml`, configurator fields, action metadata, or keybindings change.
+- Setup docs may need updates when packaging, daemon service files, shortcut setup, or install scripts change.
+
+## Validation
+- For docs-only changes, run `git diff --check`.
+- Run code/tests only when docs are generated from code or the change touches scripts/config behavior.

packaging/AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS.md
+
+## Scope
+- Applies to packaging manifests, desktop files, service unit, icons, and package metadata under `packaging/`.
+
+## Architecture
+- Package manifests describe the wayscriber binary and configurator package outputs.
+- `PKGBUILD` and `.SRCINFO` represent Arch/AUR packaging metadata.
+- Desktop files, icons, and `wayscriber.service` define installed desktop and daemon integration.
+
+## Invariants
+- Keep `package.wayscriber.yaml`, `package.configurator.yaml`, `PKGBUILD`, `.SRCINFO`, desktop files, service unit, icons, and release scripts aligned.
+- Packaging hotfix versions may differ from Cargo versions only according to the existing versioning policy.
+- Do not change daemon service semantics without checking daemon runtime and configurator daemon setup.
+
+## Coupled Changes
+- Packaging changes may require `tools/`, `.github/`, setup docs, `src/systemd_user_service.rs`, `src/shortcut_hint.rs`, and configurator daemon setup updates.
+
+## Validation
+- Run `tools/check-version-consistency.sh` and `tools/test-package-repo-layout.sh` for package/version changes.
+- Run `git diff --check` for metadata-only edits.

src/AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.md
+
+## Scope
+- Applies to the main `wayscriber` crate under `src/`.
+- Covers parent guidance for file-level modules and sibling Rust split-module roots.
+
+## Architecture
+- `src/main.rs` owns binary wiring, initializes logging, and routes errors.
+- CLI parsing flows through `src/cli.rs` and `src/app/`, then into `src/daemon/` or the active Wayland backend.
+- `src/lib.rs` exports shared modules for integration tests and the configurator while keeping binary-only runtime modules private.
+- Major domains are `backend`, `input`, `draw`, `ui`, `capture`, `config`, `session`, `daemon`, `canvas_export`, `paths`, `toolbar_icons`, `render_profiles`, and `runtime_capabilities`.
+
+## Invariants
+- Keep Wayland/runtime side effects in backend/about-window code; keep reusable data, validation, rendering helpers, and path logic in library modules.
+- Preserve feature gates when moving code between binary-private and library-exported modules.
+- Shared helpers such as `src/file_uri.rs`, `src/systemd_user_service.rs`, `src/shortcut_hint.rs`, `src/ui.rs`, `src/bin/dump_config_schema.rs`, and `src/toolbar_icons/` need parent-level coupling rules here because sibling child guides do not apply to them.
+- `src/file_uri.rs` is a shared URI trust boundary used by clipboard URI-list paste and portal capture reading.
+- `src/systemd_user_service.rs` and `src/shortcut_hint.rs` couple daemon runtime, configurator daemon setup, shortcut backend selection, and packaging service behavior.
+
+## Coupled Changes
+- Schema dump changes in `src/bin/` must stay aligned with `src/config/schema.rs` and the `config-schema` feature.
+- Toolbar icon changes must stay aligned with toolbar UI, backend toolbar rendering, action metadata, and visual tests where applicable.
+- UI module-root changes in `src/ui.rs` must stay aligned with `src/ui/` child modules and input/backend render callers.
+
+## Validation
+- Use focused `cargo test` filters for touched modules when possible.
+- Run `cargo fmt --all -- --check` for Rust edits.
+- Run `./tools/lint-and-test.sh` for broad behavior, feature-gate, or workspace-level changes.

src/about_window/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+## Scope
+- Applies to the separate Wayland about dialog under `src/about_window/`.
+
+## Architecture
+- `state.rs` owns about-window state.
+- `handlers/` owns Wayland protocol callbacks for the dialog.
+- `render/` owns Cairo drawing and text/widget helpers.
+- `clipboard.rs` supports about-dialog clipboard behavior.
+
+## Invariants
+- Keep about-window runtime separate from the annotation overlay backend unless a shared abstraction is real.
+- Preserve foreground/fullscreen safety for any launch, focus, or window behavior.
+- Keep protocol handlers thin and rendering deterministic.
+
+## Coupled Changes
+- About dialog changes may affect app metadata, clipboard behavior, docs, and Wayland handler dependencies.
+
+## Validation
+- Add focused tests if logic becomes testable.
+- Run clippy for handler/render changes.

src/app/AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+## Scope
+- Applies to top-level application orchestration under `src/app/`.
+
+## Architecture
+- Owns mode routing, environment checks, session CLI handling, and usage output.
+- Delegates daemon lifecycle to `src/daemon/` and active overlay runtime to `src/backend/`.
+
+## Invariants
+- Keep CLI-visible behavior aligned with docs and integration tests.
+- Do not duplicate daemon, backend, session, or config ownership in this layer.
+- Preserve Wayland environment checks for modes that require a compositor session.
+
+## Coupled Changes
+- CLI/mode changes may require `src/cli.rs`, `tests/cli.rs`, `README.md`, `docs/SETUP.md`, and daemon/session docs.
+
+## Validation
+- Run CLI integration tests for user-visible CLI changes.
+- Run full local CI for broad mode routing changes.

src/backend/AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+## Scope
+- Applies to backend abstraction code under `src/backend/`.
+
+## Architecture
+- `mod.rs` exposes the backend entry surface.
+- `wayland/` owns the concrete Wayland backend implementation.
+
+## Invariants
+- Keep the public backend surface small; active overlay mode should enter through the backend API rather than reaching into Wayland internals.
+- Backend code translates compositor/protocol events into input, capture, session, and render operations.
+- Avoid blocking runtime/event-loop paths.
+
+## Coupled Changes
+- Backend API changes may affect `src/app/`, `src/daemon/`, tests, and docs.
+
+## Validation
+- Run backend-focused checks and clippy for runtime changes.
+- Run full local CI for public backend API changes.

src/backend/wayland/AGENTS.md

@@ -0,0 +1,29 @@
+# AGENTS.md
+
+## Scope
+- Applies to the Wayland backend runtime under `src/backend/wayland/`.
+- Covers central split-module files such as `state.rs` and `session.rs` plus child runtime subtrees.
+
+## Architecture
+- `backend/` owns startup, setup, event loop phases, signals, tray integration, capture polling, rendering, and session save on exit.
+- `handlers/` translates Wayland/Smithay callbacks into state and input calls.
+- `state.rs` is the central live runtime state root; `state/` contains state helpers for boards, buffers, damage, clipboard paste, toolbar plumbing, zoom, onboarding, and export handoff.
+- `toolbar/` owns runtime toolbar layout, hit testing, rows, surfaces, rendering, and widgets.
+- `clipboard/`, `frozen/`, `zoom/`, and runtime session helpers integrate external compositor, clipboard, capture, and persistence behavior.
+
+## Invariants
+- Preserve Wayland object lifetimes, dispatch order, frame callbacks, surface lifecycle, output identity, damage tracking, and feature gates.
+- Keep protocol handlers thin; route durable business logic into state/input/capture/session owners.
+- Do not block event-loop dispatch or rendering with file, process, clipboard, or capture work.
+- Child guides under split-module directories must not be used to govern sibling `*.rs` files; keep shared rules here or in the immediate parent.
+
+## Coupled Changes
+- Tablet behavior must stay coherent with `tablet-input`.
+- Portal capture and URI/file handling must stay coherent with `portal` and `dbus`.
+- Tray behavior must stay coherent with `tray`, daemon runtime, configurator daemon setup, and packaging service files.
+- Clipboard file URI behavior must stay aligned with shared `src/file_uri.rs`.
+
+## Validation
+- Use focused tests near changed state/session/toolbar helpers when available.
+- Run `cargo clippy --workspace --all-targets --all-features -- -D warnings` for protocol/runtime changes.
+- Run full local CI for broad event-loop, feature-gate, or runtime lifecycle changes.

src/backend/wayland/backend/AGENTS.md

@@ -0,0 +1,24 @@
+# AGENTS.md
+
+## Scope
+- Applies to Wayland backend startup, setup, event-loop phases, state initialization, signal handling, tray wiring, rendering dispatch, capture polling, and session save on exit.
+
+## Architecture
+- `run.rs` is the active backend run entry.
+- `setup.rs`, `surface.rs`, and `state_init/` build the initial Wayland state.
+- `event_loop/` owns dispatch, render, capture polling, and exit-time session save phases.
+- `signals.rs` and `tray.rs` integrate process lifecycle and daemon/tray behavior.
+
+## Invariants
+- Keep event-loop phases explicit and non-blocking.
+- Do not perform slow file, process, clipboard, or capture work inline in dispatch/render paths.
+- Preserve signal behavior, tray feature gating, frame callback assumptions, and session-save ordering.
+
+## Coupled Changes
+- Startup and state-init changes may affect `src/backend/wayland/state.rs`, `src/input/`, `src/config/`, `src/session/`, and daemon mode.
+- Tray changes must stay aligned with `tray` feature behavior, daemon lifecycle, configurator daemon setup, and packaging service files.
+
+## Validation
+- Add focused tests near changed event-loop/session-save helpers when available.
+- Run clippy for backend lifecycle changes.
+- Run full local CI for broad startup, feature-gate, or event-loop changes.

src/backend/wayland/clipboard/AGENTS.md

@@ -0,0 +1,24 @@
+# AGENTS.md
+
+## Scope
+- Applies to the Wayland clipboard module under `clipboard/`.
+- This directory is not a split module; `clipboard/mod.rs` is covered by this file.
+
+## Architecture
+- `image.rs` and `file_list.rs` build clipboard payloads.
+- `transfer.rs` owns Wayland clipboard transfer helpers.
+- `system.rs` and `system/command.rs` provide external command fallback behavior.
+
+## Invariants
+- Treat file URI and external command inputs as trust boundaries.
+- Keep clipboard error reporting and cancellation behavior explicit.
+- Preserve compatibility between image payloads, URI-list payloads, and session paste behavior in `src/backend/wayland/state/clipboard.rs`.
+
+## Coupled Changes
+- URI-list behavior must stay aligned with shared `src/file_uri.rs`.
+- Clipboard paste changes may affect input selection behavior and session paste tests.
+- System command behavior may affect packaging/runtime dependencies and docs.
+
+## Validation
+- Add or update tests under `clipboard/transfer/`, `clipboard/system/`, or state clipboard tests.
+- Use targeted cargo tests for clipboard behavior.

src/backend/wayland/frozen/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+## Scope
+- Applies to frozen-screen snapshot capture, image handling, portal fallback, and frozen state machine code.
+
+## Architecture
+- `capture.rs` coordinates frozen capture setup.
+- `image.rs` owns frozen image data handling.
+- `portal.rs` provides portal-based fallback behavior.
+- `state.rs` tracks frozen-mode state.
+
+## Invariants
+- Preserve overlay-hide, capture, restore, and render ordering.
+- Treat user cancellation as cancellation, not a hard failure.
+- Keep coordinate and scale handling aligned with `src/backend/wayland/frozen_geometry.rs`, zoom behavior, and render state.
+
+## Coupled Changes
+- Frozen capture changes may affect `src/capture/`, `src/backend/wayland/zoom/`, and `src/backend/wayland/state/render/`.
+- Portal changes must stay aligned with `portal`/`dbus` feature behavior.
+
+## Validation
+- Add focused tests around state or geometry helpers when possible.
+- Run full local CI for broad capture or feature-gate changes.

src/backend/wayland/handlers/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+## Scope
+- Applies to Wayland/Smithay protocol handlers under `handlers/`.
+
+## Architecture
+- Handler files translate protocol callbacks into `WaylandState`, `InputState`, capture, surface, and render operations.
+- Pointer, keyboard, tablet, touch, output, layer, registry, buffer, screencopy, seat, SHM, and XDG behavior is split by protocol area.
+- Translation helpers such as keyboard keysym mapping should stay testable and isolated.
+
+## Invariants
+- Keep handlers thin; do not bury durable business logic in protocol callbacks.
+- Preserve coordinate transforms, modifier synchronization, seat/device lifetimes, frame/callback ordering, and tablet feature gating.
+- Avoid blocking protocol callback paths.
+
+## Coupled Changes
+- Input event changes may require `src/input/` state tests.
+- Tablet changes must stay coherent with `tablet-input`.
+- Screencopy/portal changes may affect frozen, zoom, and capture behavior.
+
+## Validation
+- Add focused tests near translation helpers where possible.
+- Run clippy and relevant input/backend tests for protocol behavior changes.

src/backend/wayland/session/AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS.md
+
+## Scope
+- Applies only to helper modules under `session/`.
+- The sibling root `src/backend/wayland/session.rs` is governed by `src/backend/wayland/AGENTS.md`.
+
+## Architecture
+- This subtree supports runtime session operations for the live overlay.
+- It should work with core session validation, snapshots, catalog metadata, and input session preflight instead of duplicating those rules.
+
+## Invariants
+- Preserve save-before-open behavior, target validation, user prompt boundaries, rollback behavior, and catalog updates.
+- Do not replace active board state until a runtime open has validated and loaded successfully.
+- Keep named-session safety aligned with `src/session/` and `src/paths/`.
+
+## Coupled Changes
+- Runtime session changes may affect `src/session/`, `src/input/state/core/session_preflight*`, daemon named-session switching, and configurator session catalog code.
+
+## Validation
+- Add focused tests under this subtree or `src/session/` for transaction behavior.
+- Run session-focused tests for open/save-as/clear changes.

src/backend/wayland/state/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+## Scope
+- Applies only to child modules under `state/`.
+- The sibling root `src/backend/wayland/state.rs` is governed by `src/backend/wayland/AGENTS.md`.
+
+## Architecture
+- This subtree supports live overlay runtime state: buffers, damage, boards, capture routing, clipboard paste, color picker, onboarding, PDF export, render helpers, toolbar plumbing, zoom, and core accessors.
+- `render/` owns overlay render phases; `toolbar/` owns runtime toolbar state helpers; `clipboard/` owns session paste helpers.
+
+## Invariants
+- Preserve snapshot boundaries for export and session actions.
+- Keep render order, damage assumptions, buffer lifecycle, output identity, and toolbar visibility behavior explicit.
+- State helpers may coordinate subsystems, but durable config, drawing, capture, session, and input rules should remain with their owning modules.
+
+## Coupled Changes
+- Render changes may affect `src/draw/`, `src/ui/`, `src/input/state/render.rs`, backend toolbar rendering, and visual tests.
+- Toolbar state changes may affect `src/backend/wayland/toolbar/` and `src/ui/toolbar/`.
+- Clipboard paste changes may affect `src/backend/wayland/clipboard/`, `src/file_uri.rs`, and input selection behavior.
+
+## Validation
+- Add focused tests near state helper modules when available.
+- Run targeted backend/state/session/toolbar tests for runtime state changes.

src/backend/wayland/toolbar/AGENTS.md

@@ -0,0 +1,24 @@
+# AGENTS.md
+
+## Scope
+- Applies to runtime toolbar layout, hit testing, event types, rows, surfaces, rendering, widgets, and main toolbar state.
+
+## Architecture
+- `layout/` computes top-strip and side-palette geometry.
+- `render.rs` and `render/` draw toolbar surfaces and widgets.
+- `surfaces/` owns Wayland surface lifecycle, buffers, hit testing, and surface rendering.
+- `main/` owns runtime toolbar state and lifecycle.
+- `events.rs`, `hit.rs`, and `rows.rs` connect runtime events, hit targets, and row definitions.
+
+## Invariants
+- Keep layout geometry, hit regions, event snapshots, and Cairo rendering aligned.
+- Preserve top-strip versus side-palette behavior, drawer/collapsible sections, session rows, delay sliders, preset rows, tool rows, and event policy.
+- Child guides under split-module directories must not govern sibling roots such as `render.rs`.
+
+## Coupled Changes
+- Runtime toolbar changes may affect `src/backend/wayland/state/toolbar.rs`, `src/backend/wayland/state/toolbar/`, `src/ui/toolbar/`, `src/input/`, toolbar icons, config toolbar settings, and action metadata.
+
+## Validation
+- Add or update layout tests under `layout/tests/` for geometry changes.
+- Use rendering smoke tests or targeted tests for render/hit/surface changes.
+- Run full local CI for broad toolbar behavior changes.

src/backend/wayland/zoom/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+## Scope
+- Applies to Wayland zoom capture, portal fallback, zoom state, and view transform code.
+
+## Architecture
+- `capture.rs` coordinates zoom capture.
+- `portal.rs` provides portal fallback behavior.
+- `state.rs` owns zoom runtime state.
+- `view.rs` owns zoom view transforms.
+
+## Invariants
+- Preserve coordinate transforms, capture-source fallback behavior, and state transitions.
+- Treat user cancellation as cancellation, not a hard failure.
+- Keep zoom behavior aligned with frozen capture, render state, and input zoom actions.
+
+## Coupled Changes
+- Zoom changes may affect `src/input/state/actions/action_capture_zoom.rs`, `src/backend/wayland/state/zoom.rs`, `src/backend/wayland/state/render/`, and `src/capture/`.
+- Portal behavior must stay coherent with `portal`/`dbus` feature gates.
+
+## Validation
+- Add focused tests around transform/state helpers where possible.
+- Run targeted input/backend/capture tests for zoom behavior changes.

src/canvas_export/AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+## Scope
+- Applies to PNG/PDF canvas export code under `src/canvas_export/`.
+
+## Architecture
+- `png.rs` owns PNG export.
+- `pdf.rs` and `pdf/` own PDF export and tests.
+- `page.rs` and `pdf_labels.rs` support page metadata and PDF labels.
+
+## Invariants
+- Export from snapshots, not live mutable state.
+- Preserve viewport origin, scale handling, persisted backdrop behavior, render profile remapping, PDF labels/layout, and page metadata.
+
+## Coupled Changes
+- Export changes may affect capture delivery, render profiles, session snapshots, board/page state, docs, and tests.
+
+## Validation
+- Add pixel-style tests for PNG regressions where practical.
+- Add PDF header/layout/label tests for PDF behavior changes.

src/capture/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+## Scope
+- Applies to screenshot capture, image/document delivery, file save, clipboard delivery, portal support, and capture tests under `src/capture/`.
+
+## Architecture
+- `manager.rs` bridges synchronous Wayland state and async capture/delivery work.
+- `pipeline.rs` owns capture, image delivery, document delivery, save, and clipboard flows.
+- `dependencies.rs` provides traits for testable capture sources, savers, and clipboard implementations.
+- `sources/` chooses compositor-specific or portal capture sources.
+
+## Invariants
+- Preserve cancellation semantics; user cancellation is not a hard failure.
+- Keep async capture work out of Wayland event-loop blocking paths.
+- Preserve desktop backdrop and portal behavior across feature gates.
+
+## Coupled Changes
+- Capture changes may affect Wayland frozen/zoom paths, notifications, canvas export, clipboard behavior, docs, and tests.
+
+## Validation
+- Add focused tests under `src/capture/tests/`.
+- Run targeted capture tests for manager/pipeline/source changes.
+- Run full local CI for broad async or feature-gate changes.

src/config/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md
+
+## Scope
+- Applies to configuration types, defaults, validation, I/O, config paths, schema export, keybindings, and action metadata.
+- Parent guidance here covers split root `keybindings.rs`; `keybindings/AGENTS.md` covers only child modules under `keybindings/`.
+
+## Architecture
+- `types/` owns config structs and defaults.
+- `validate/` owns clamping, warnings, and user-provided config validation.
+- `keybindings.rs` and `keybindings/` adapt action bindings, defaults, parsing, display, and per-domain maps.
+- `action_meta/` owns human-facing action names, labels, descriptions, and categories.
+- `schema.rs` exports JSON schema behind `config-schema`.
+
+## Invariants
+- Preserve serde compatibility, documented defaults, validation warning behavior, and feature-gated schema output.
+- Do not silently drop invalid user config; validation should make coercion or rejection explicit.
+- Keep action labels/categories aligned with help overlay, command palette, keybindings, configurator labels, and docs.
+
+## Coupled Changes
+- Any config field change may require `config.example.toml`, `docs/CONFIG.md`, configurator draft/models/views/update code, tests, and schema behavior.
+- Keybinding/action changes may require `src/input/`, `src/ui/`, toolbar model/rendering, configurator keybinding UI, and docs.
+
+## Validation
+- Use config-focused tests under `src/config/tests/` and keybinding tests for parser/map changes.
+- Run schema tests when changing `config-schema` output.
+- Run full local CI for broad config or feature-gate changes.

src/config/action_meta/AGENTS.md

@@ -0,0 +1,18 @@
+# AGENTS.md
+
+## Scope
+- Applies to action metadata under `src/config/action_meta/`.
+
+## Architecture
+- `entries/` groups human-facing action labels, descriptions, and categories by domain.
+- Metadata feeds help overlay, command palette, configurator labels/search, and documentation.
+
+## Invariants
+- Keep labels, descriptions, categories, action enum variants, keybinding defaults, and UI presentation synchronized.
+- Avoid renaming user-facing actions without considering config/docs compatibility.
+
+## Coupled Changes
+- Action metadata changes may affect `src/config/keybindings/`, `src/input/`, `src/ui/help_overlay/`, command palette, configurator search/labels, and docs.
+
+## Validation
+- Run action metadata tests and relevant config/keybinding tests.

src/config/keybindings/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+## Scope
+- Applies only to child modules under `src/config/keybindings/`.
+- The sibling root `src/config/keybindings.rs` is governed by `src/config/AGENTS.md`.
+
+## Architecture
+- `actions.rs` owns action enums.
+- `binding.rs` owns key binding parsing/display.
+- `defaults/` owns default bindings.
+- `config/` owns typed keybinding config and per-domain action maps.
+
+## Invariants
+- Keep action names, defaults, map construction, parsing, display, and validation coherent.
+- Do not add or rename actions without updating action metadata, help/command UI, docs, and configurator keybinding UI.
+
+## Coupled Changes
+- Keybinding changes may affect `src/input/`, `src/config/action_meta/`, `src/ui/help_overlay/`, command palette, configurator keybinding models/views, and docs.
+
+## Validation
+- Add keybinding parser/map tests for behavior changes.
+- Run config and input action tests for action changes.

src/daemon/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+## Scope
+- Applies to daemon lifecycle, toggle protocol, runtime files, tray integration, setup helpers, global shortcuts, overlay process control, and daemon tests.
+
+## Architecture
+- `core.rs`, `control.rs`, and `types.rs` own daemon state and toggle/control behavior.
+- `overlay/` owns overlay process spawn/control.
+- `tray/` owns tray integration and shortcut hint I/O.
+- `setup.rs` and `global_shortcuts.rs` support daemon setup workflows.
+
+## Invariants
+- Preserve single-instance locking, stale runtime cleanup, duplicate-toggle suppression, typed daemon toggle responses, and named-session switching rules.
+- Keep runtime path behavior aligned with `src/paths/`.
+- Do not change service/shortcut behavior without checking configurator daemon setup and packaging.
+
+## Coupled Changes
+- Daemon changes may affect `src/paths/`, `src/systemd_user_service.rs`, `src/shortcut_hint.rs`, `configurator/src/app/daemon_setup/`, `packaging/wayscriber.service`, and setup docs.
+
+## Validation
+- Run daemon-focused tests for lifecycle/toggle changes.
+- Run full local CI for process, lock, service, or feature-gate changes.

src/draw/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+## Scope
+- Applies to drawing data, shapes, frames, canvas sets, dirty tracking, colors, fonts, and Cairo/Pango rendering helpers under `src/draw/`.
+
+## Architecture
+- `canvas_set/` owns multi-board/page canvas state.
+- `frame/` owns frame storage, serialization, and undo/redo history.
+- `shape/` owns shape types, bounds, text cache, polygons, step markers, and labels.
+- `render/` owns Cairo/Pango rendering helpers.
+
+## Invariants
+- Keep this area mostly pure; rendering helpers should not mutate application state except intentional caches or Cairo surface/path operations.
+- Preserve serialization compatibility, undo/history invariants, canvas/page identity, and Cairo path isolation.
+
+## Coupled Changes
+- Drawing changes may affect input tools, selection behavior, canvas export, session snapshots, toolbar controls, config defaults, and tests.
+
+## Validation
+- Add focused tests for frame, shape, history, or canvas behavior.
+- Use rendering/path-leakage tests for Cairo regressions.
+- Run full local CI for serialized data or history changes.

src/input/AGENTS.md

@@ -0,0 +1,25 @@
+# AGENTS.md
+
+## Scope
+- Applies to input events, tools, board modes, hit testing, tablet glue, board operations, and `InputState`.
+- Parent guidance here covers split roots such as `boards.rs` plus child modules under `boards/`.
+
+## Architecture
+- Backend code forwards pointer, keyboard, tablet, and touch events into input state.
+- `InputState` owns action dispatch, mouse/keyboard handling, interaction routing, panels, selection, text editing, highlight state, and pending backend actions.
+- `tool/` owns tool kind/catalog/profile/settings/drag behavior.
+- `boards.rs` and `boards/` own board/page identity, ordering, naming, color, mapping, and operations.
+
+## Invariants
+- Backend code should drain pending backend actions instead of directly mutating drawing, capture, or session state.
+- Keep drawing mutations behind `InputState` methods so dirty tracking, undo, and history remain coherent.
+- Preserve panel focus, command-palette dispatch, text input lifecycle, selection transforms, board/page identity, and session preflight behavior.
+
+## Coupled Changes
+- Tool changes must update config defaults, action metadata, keybinding actions/default maps, toolbar UI, backend render behavior, docs, tests, configurator field models, configurator drawing views, and configurator search labels.
+- Board changes may affect session snapshots, board picker UI, toolbar board/page controls, config defaults, and tests.
+
+## Validation
+- Add focused tests under `src/input/state/tests/`, `src/input/boards/`, or `src/input/tool/` for behavior changes.
+- Use targeted `cargo test` filters for input state, boards, selection, text input, or tools.
+- Run full local CI for changes that alter action dispatch, tool semantics, or board persistence.

src/input/boards/AGENTS.md

@@ -0,0 +1,18 @@
+# AGENTS.md
+
+## Scope
+- Applies only to child helpers under `src/input/boards/`.
+- The sibling root `src/input/boards.rs` is governed by `src/input/AGENTS.md`.
+
+## Architecture
+- Owns board/page identity, mapping, naming, color, operations, and tests.
+
+## Invariants
+- Preserve stable identifiers, ordering, active-board transitions, configured defaults, and undo/history expectations.
+- Keep board/page behavior coherent with session snapshots and board picker UI.
+
+## Coupled Changes
+- Board changes may affect `src/input/state/core/board*`, `src/session/`, `src/ui/board_picker/`, backend toolbar board/page rows, config board defaults, and tests.
+
+## Validation
+- Add focused board tests under `src/input/boards/` or `src/input/state/tests/`.

src/input/state/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+## Scope
+- Applies to `InputState` internals under `src/input/state/`.
+
+## Architecture
+- `actions/` owns action dispatch and key press/release behavior.
+- `core/` owns board state, history, selection, panels, properties, command palette, board picker, utilities, and session preflight.
+- `mouse/`, `interaction/`, and `highlight/` own pointer/mouse routing, interaction adapters, and highlight state.
+- `tests/` owns focused input state tests.
+
+## Invariants
+- Keep direct drawing mutations behind `InputState` methods so dirty tracking, undo, and history remain coherent.
+- Preserve pending backend action boundaries; backend code should drain actions rather than duplicating side effects.
+- Preserve text input lifecycle, panel focus, selection transforms, command palette dispatch, and session preflight behavior.
+
+## Coupled Changes
+- Input state changes may affect `src/draw/`, `src/ui/`, backend Wayland handlers/state, session, capture/export, toolbar model/apply, config actions, and tests.
+
+## Validation
+- Add focused tests under `src/input/state/tests/` for behavior changes.
+- Use targeted tests for menus, selection, text input, board picker, properties, or actions.

src/input/tool/AGENTS.md

@@ -0,0 +1,19 @@
+# AGENTS.md
+
+## Scope
+- Applies to tool catalog, kinds, profiles, settings, drag behavior, and tool tests under `src/input/tool/`.
+
+## Architecture
+- `kind.rs`, `catalog.rs`, `profile.rs`, `settings.rs`, and `drawing.rs` define tool identity and behavior.
+- `drag.rs` owns drag-specific behavior.
+
+## Invariants
+- Tool semantics must stay coherent across input state, drawing/rendering, toolbar controls, config defaults, action metadata, and keybindings.
+- Preserve serialized/config-facing tool names unless a migration/doc update is intentional.
+
+## Coupled Changes
+- Tool changes may affect `src/config/types/`, `src/config/keybindings/`, `src/config/action_meta/`, `src/ui/toolbar/`, `src/backend/wayland/toolbar/`, `src/draw/`, configurator field models/views/search, docs, and tests.
+
+## Validation
+- Add tool tests under `src/input/tool/` or input state tests for behavior changes.
+- Run config/keybinding tests when changing tool actions or defaults.

src/paths/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+## Scope
+- Applies to XDG and runtime path resolution helpers under `src/paths/`.
+- Covers config/session paths plus daemon command files, tray action paths, pid files, log paths, overlay locks, daemon locks, runtime/data/config directories, and tests.
+
+## Architecture
+- Path helpers are shared by config loading, session storage, daemon runtime files, configurator workflows, and packaging/user-service behavior.
+- Environment overrides and XDG directory behavior should stay centralized here rather than duplicated in callers.
+
+## Invariants
+- Preserve path safety, XDG semantics, environment override behavior, and cross-platform assumptions already encoded by tests.
+- Do not broaden trusted filesystem locations without checking daemon/session/config callers.
+- Keep runtime path changes compatible with daemon single-instance locks, command queues, tray actions, and overlay process management.
+
+## Coupled Changes
+- Path changes may affect `src/config/`, `src/session/`, `src/daemon/`, `src/systemd_user_service.rs`, configurator session/daemon setup, docs, and packaging service behavior.
+
+## Validation
+- Add or update `src/paths/tests.rs` for path behavior changes.
+- Run targeted path/session/daemon tests when changing runtime paths.
+- Run full local CI for broad path resolution changes.

src/session/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md
+
+## Scope
+- Applies to session persistence, named sessions, primary file validation, options, locks, snapshots, storage, artifacts, catalog metadata, clear/inspect flows, and path safety.
+- Parent guidance here covers split roots such as `artifacts.rs` and `catalog.rs`.
+
+## Architecture
+- `options/` builds persistence targets and output identity behavior.
+- `snapshot/` captures, applies, loads, saves, compresses, and recovers session state.
+- `storage/` handles clear/inspect operations and stored-session data.
+- `artifacts.rs` and `artifacts/` own sidecar/artifact movement and rollback.
+- `catalog.rs` and `catalog/` own named-session identity and metadata.
+
+## Invariants
+- Preserve lock behavior, backup/recovery behavior, clear boundaries, rollback on artifact moves, and named-session catalog identity.
+- Reject symlinks, directories, and special files where forbidden by named-session rules.
+- Runtime session open/save-as/clear behavior must validate paths before mutating active state.
+
+## Coupled Changes
+- Session changes may affect `src/backend/wayland/session.rs`, input session preflight, daemon named-session switching, configurator session catalog operations, and `src/paths/`.
+- Snapshot format changes must consider backward compatibility and recovery behavior.
+
+## Validation
+- Add focused tests under `src/session/tests/`, `src/session/snapshot/`, `src/session/storage/`, `src/session/artifacts/`, or `src/session/catalog/`.
+- Use targeted session test filters for persistence changes.
+- Run full local CI for changes that affect storage, locks, named sessions, or snapshot compatibility.

src/ui/AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS.md
+
+## Scope
+- Applies only to child modules under `src/ui/`.
+- The sibling root `src/ui.rs` is governed by `src/AGENTS.md`.
+
+## Architecture
+- Owns Cairo-rendered overlay UI pieces: status, help overlay, command palette, context menu, board picker, properties panel, radial menu, onboarding card, color picker popup, toasts, tour UI, and primitives.
+- `toolbar/` owns input-side toolbar model/snapshot/apply plumbing, distinct from runtime backend toolbar rendering.
+
+## Invariants
+- Keep layout calculations deterministic and avoid text overlap on small surfaces.
+- Prefer shared constants/primitives where present.
+- Keep UI rendering side-effect-light; durable state changes belong in input/backend owners.
+
+## Coupled Changes
+- UI changes may affect `src/input/`, `src/backend/wayland/state/render/`, action metadata, keybindings, toolbar rendering, docs, and tests.
+
+## Validation
+- Add focused layout/render tests for complex UI paths where possible.
+- Run targeted UI/input tests for command palette, board picker, help overlay, or toolbar behavior.

src/ui/toolbar/AGENTS.md

@@ -0,0 +1,25 @@
+# AGENTS.md
+
+## Scope
+- Applies to input-side toolbar model, event bindings, snapshot building, and apply logic under `src/ui/toolbar/`.
+- Runtime Wayland/Cairo toolbar rendering is governed by `src/backend/wayland/toolbar/AGENTS.md`.
+
+## Architecture
+- `model/` defines toolbar state, controls, activation/session/settings/tool models, and event policy.
+- `snapshot/` and `snapshot.rs` build immutable snapshots consumed by runtime rendering and event handling.
+- `apply/` mutates `InputState` from toolbar events, page changes, board changes, action requests, delay/layout changes, and tool selections.
+- `bindings.rs` and `events.rs` connect toolbar models to application events without owning backend surface state.
+
+## Invariants
+- Keep this layer distinct from backend Cairo/Wayland toolbar layout, surfaces, and rendering.
+- Snapshot data should be immutable after construction and should not perform durable state mutation.
+- Apply code should route mutations through `InputState` and preserve existing action/keybinding semantics.
+- Keep model/event policy changes compatible with top-strip and side-palette runtime behavior.
+
+## Coupled Changes
+- Toolbar model/snapshot/apply changes often require updates to config toolbar settings, backend toolbar rendering/layout, action metadata, input state, docs, and tests.
+- Control additions or renamed events may require configurator labels/search and command/help UI updates.
+
+## Validation
+- Add or update focused tests for toolbar snapshot building, event application, and input state mutations when behavior changes.
+- Run targeted toolbar/input tests; use full local CI for broad toolbar behavior changes.

tests/AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS.md
+
+## Scope
+- Applies to integration tests under `tests/`.
+
+## Architecture
+- `tests/cli.rs` covers CLI behavior.
+- `tests/ui.rs` covers UI smoke/integration behavior that can run without an ungated visible overlay.
+
+## Invariants
+- Tests should not launch visible Wayland overlays, steal focus, or interact with foreground/fullscreen apps by default.
+- Use isolated temp dirs and environment variables for CLI, config, path, and session behavior.
+- Keep output assertions specific enough to catch regressions without depending on noisy logs.
+
+## Coupled Changes
+- CLI changes may require `tests/cli.rs`, docs, and usage text updates.
+- UI or rendering smoke changes may require fixtures or focused module tests in `src/`.
+
+## Validation
+- Run targeted integration tests for touched behavior.
+- Run full local CI for broad CLI, config, session, or workspace changes.

tools/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+## Scope
+- Applies to repository scripts under `tools/`.
+
+## Architecture
+- Scripts support build, install, lint/test, versioning, packaging, release tags, package repository generation, daemon reload, and dependency fetching.
+- Scripts should resolve the repository root and work from any starting directory.
+
+## Invariants
+- Preserve release/version/package semantics, including packaging-only hotfix behavior.
+- Keep `tools/lint-and-test.sh` aligned with CI.
+- Avoid platform-specific assumptions unless the script is explicitly platform-specific.
+
+## Coupled Changes
+- Version and packaging scripts must stay aligned with `tools/README.md`, `packaging/`, `.github/`, `Cargo.toml`, and release docs.
+- Install/reload scripts may affect setup docs and daemon service behavior.
+
+## Validation
+- Run changed scripts directly when safe.
+- Run `./tools/lint-and-test.sh` for changes to lint/test behavior.
+- Use `git diff --check` for docs/script-only edits.