From e5c2633822114e0757c9307b3ba6e8665671a4c9 Mon Sep 17 00:00:00 2001 From: devmobasa <4170275+devmobasa@users.noreply.github.com.> Date: Sat, 27 Jun 2026 17:36:08 +0200 Subject: [PATCH] docs: add repo-wide and module-scoped AGENTS guidance --- .gitattributes | 10 ++++++ .github/AGENTS.md | 21 ++++++++++++ .gitignore | 4 ++- AGENTS.md | 34 +++++++++++++++++++ configurator/AGENTS.md | 26 ++++++++++++++ configurator/src/AGENTS.md | 24 +++++++++++++ configurator/src/app/AGENTS.md | 27 +++++++++++++++ configurator/src/app/daemon_setup/AGENTS.md | 19 +++++++++++ .../src/app/session_catalog/AGENTS.md | 20 +++++++++++ configurator/src/app/update/AGENTS.md | 20 +++++++++++ configurator/src/app/view/AGENTS.md | 20 +++++++++++ configurator/src/models/AGENTS.md | 22 ++++++++++++ configurator/src/models/config/AGENTS.md | 20 +++++++++++ configurator/src/models/fields/AGENTS.md | 20 +++++++++++ configurator/src/models/keybindings/AGENTS.md | 18 ++++++++++ docs/AGENTS.md | 22 ++++++++++++ packaging/AGENTS.md | 21 ++++++++++++ src/AGENTS.md | 28 +++++++++++++++ src/about_window/AGENTS.md | 22 ++++++++++++ src/app/AGENTS.md | 20 +++++++++++ src/backend/AGENTS.md | 20 +++++++++++ src/backend/wayland/AGENTS.md | 29 ++++++++++++++++ src/backend/wayland/backend/AGENTS.md | 24 +++++++++++++ src/backend/wayland/clipboard/AGENTS.md | 24 +++++++++++++ src/backend/wayland/frozen/AGENTS.md | 23 +++++++++++++ src/backend/wayland/handlers/AGENTS.md | 23 +++++++++++++ src/backend/wayland/session/AGENTS.md | 21 ++++++++++++ src/backend/wayland/state/AGENTS.md | 23 +++++++++++++ src/backend/wayland/toolbar/AGENTS.md | 24 +++++++++++++ src/backend/wayland/zoom/AGENTS.md | 23 +++++++++++++ src/canvas_export/AGENTS.md | 20 +++++++++++ src/capture/AGENTS.md | 23 +++++++++++++ src/config/AGENTS.md | 26 ++++++++++++++ src/config/action_meta/AGENTS.md | 18 ++++++++++ src/config/keybindings/AGENTS.md | 22 ++++++++++++ src/daemon/AGENTS.md | 22 ++++++++++++ src/draw/AGENTS.md | 22 ++++++++++++ src/input/AGENTS.md | 25 ++++++++++++++ src/input/boards/AGENTS.md | 18 ++++++++++ src/input/state/AGENTS.md | 22 ++++++++++++ src/input/tool/AGENTS.md | 19 +++++++++++ src/paths/AGENTS.md | 22 ++++++++++++ src/session/AGENTS.md | 26 ++++++++++++++ src/ui/AGENTS.md | 21 ++++++++++++ src/ui/toolbar/AGENTS.md | 25 ++++++++++++++ tests/AGENTS.md | 21 ++++++++++++ tools/AGENTS.md | 22 ++++++++++++ 47 files changed, 1025 insertions(+), 1 deletion(-) create mode 100644 .gitattributes create mode 100644 .github/AGENTS.md create mode 100644 AGENTS.md create mode 100644 configurator/AGENTS.md create mode 100644 configurator/src/AGENTS.md create mode 100644 configurator/src/app/AGENTS.md create mode 100644 configurator/src/app/daemon_setup/AGENTS.md create mode 100644 configurator/src/app/session_catalog/AGENTS.md create mode 100644 configurator/src/app/update/AGENTS.md create mode 100644 configurator/src/app/view/AGENTS.md create mode 100644 configurator/src/models/AGENTS.md create mode 100644 configurator/src/models/config/AGENTS.md create mode 100644 configurator/src/models/fields/AGENTS.md create mode 100644 configurator/src/models/keybindings/AGENTS.md create mode 100644 docs/AGENTS.md create mode 100644 packaging/AGENTS.md create mode 100644 src/AGENTS.md create mode 100644 src/about_window/AGENTS.md create mode 100644 src/app/AGENTS.md create mode 100644 src/backend/AGENTS.md create mode 100644 src/backend/wayland/AGENTS.md create mode 100644 src/backend/wayland/backend/AGENTS.md create mode 100644 src/backend/wayland/clipboard/AGENTS.md create mode 100644 src/backend/wayland/frozen/AGENTS.md create mode 100644 src/backend/wayland/handlers/AGENTS.md create mode 100644 src/backend/wayland/session/AGENTS.md create mode 100644 src/backend/wayland/state/AGENTS.md create mode 100644 src/backend/wayland/toolbar/AGENTS.md create mode 100644 src/backend/wayland/zoom/AGENTS.md create mode 100644 src/canvas_export/AGENTS.md create mode 100644 src/capture/AGENTS.md create mode 100644 src/config/AGENTS.md create mode 100644 src/config/action_meta/AGENTS.md create mode 100644 src/config/keybindings/AGENTS.md create mode 100644 src/daemon/AGENTS.md create mode 100644 src/draw/AGENTS.md create mode 100644 src/input/AGENTS.md create mode 100644 src/input/boards/AGENTS.md create mode 100644 src/input/state/AGENTS.md create mode 100644 src/input/tool/AGENTS.md create mode 100644 src/paths/AGENTS.md create mode 100644 src/session/AGENTS.md create mode 100644 src/ui/AGENTS.md create mode 100644 src/ui/toolbar/AGENTS.md create mode 100644 tests/AGENTS.md create mode 100644 tools/AGENTS.md diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..b4921057 --- /dev/null +++ b/.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 diff --git a/.github/AGENTS.md b/.github/AGENTS.md new file mode 100644 index 00000000..c3534ee2 --- /dev/null +++ b/.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. diff --git a/.gitignore b/.gitignore index 61acde2e..380db462 100644 --- a/.gitignore +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..29d80797 --- /dev/null +++ b/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`. diff --git a/configurator/AGENTS.md b/configurator/AGENTS.md new file mode 100644 index 00000000..d4d16f69 --- /dev/null +++ b/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. diff --git a/configurator/src/AGENTS.md b/configurator/src/AGENTS.md new file mode 100644 index 00000000..15dcf291 --- /dev/null +++ b/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. diff --git a/configurator/src/app/AGENTS.md b/configurator/src/app/AGENTS.md new file mode 100644 index 00000000..5de3fd38 --- /dev/null +++ b/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`. +- `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. diff --git a/configurator/src/app/daemon_setup/AGENTS.md b/configurator/src/app/daemon_setup/AGENTS.md new file mode 100644 index 00000000..afb05731 --- /dev/null +++ b/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. diff --git a/configurator/src/app/session_catalog/AGENTS.md b/configurator/src/app/session_catalog/AGENTS.md new file mode 100644 index 00000000..cf3dac25 --- /dev/null +++ b/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. diff --git a/configurator/src/app/update/AGENTS.md b/configurator/src/app/update/AGENTS.md new file mode 100644 index 00000000..12278715 --- /dev/null +++ b/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` 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. diff --git a/configurator/src/app/view/AGENTS.md b/configurator/src/app/view/AGENTS.md new file mode 100644 index 00000000..46743a4d --- /dev/null +++ b/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. diff --git a/configurator/src/models/AGENTS.md b/configurator/src/models/AGENTS.md new file mode 100644 index 00000000..123d78ad --- /dev/null +++ b/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. diff --git a/configurator/src/models/config/AGENTS.md b/configurator/src/models/config/AGENTS.md new file mode 100644 index 00000000..8fd791cf --- /dev/null +++ b/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. diff --git a/configurator/src/models/fields/AGENTS.md b/configurator/src/models/fields/AGENTS.md new file mode 100644 index 00000000..7f1a4078 --- /dev/null +++ b/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. diff --git a/configurator/src/models/keybindings/AGENTS.md b/configurator/src/models/keybindings/AGENTS.md new file mode 100644 index 00000000..0c8133a5 --- /dev/null +++ b/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. diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 00000000..dd7223a4 --- /dev/null +++ b/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. diff --git a/packaging/AGENTS.md b/packaging/AGENTS.md new file mode 100644 index 00000000..ad2a7b8f --- /dev/null +++ b/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. diff --git a/src/AGENTS.md b/src/AGENTS.md new file mode 100644 index 00000000..aa12bcd3 --- /dev/null +++ b/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. diff --git a/src/about_window/AGENTS.md b/src/about_window/AGENTS.md new file mode 100644 index 00000000..ce4db506 --- /dev/null +++ b/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. diff --git a/src/app/AGENTS.md b/src/app/AGENTS.md new file mode 100644 index 00000000..09055fb4 --- /dev/null +++ b/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. diff --git a/src/backend/AGENTS.md b/src/backend/AGENTS.md new file mode 100644 index 00000000..c5ae4d78 --- /dev/null +++ b/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. diff --git a/src/backend/wayland/AGENTS.md b/src/backend/wayland/AGENTS.md new file mode 100644 index 00000000..083f7cc5 --- /dev/null +++ b/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. diff --git a/src/backend/wayland/backend/AGENTS.md b/src/backend/wayland/backend/AGENTS.md new file mode 100644 index 00000000..fc3011bd --- /dev/null +++ b/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. diff --git a/src/backend/wayland/clipboard/AGENTS.md b/src/backend/wayland/clipboard/AGENTS.md new file mode 100644 index 00000000..c345bbe2 --- /dev/null +++ b/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. diff --git a/src/backend/wayland/frozen/AGENTS.md b/src/backend/wayland/frozen/AGENTS.md new file mode 100644 index 00000000..33744e35 --- /dev/null +++ b/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. diff --git a/src/backend/wayland/handlers/AGENTS.md b/src/backend/wayland/handlers/AGENTS.md new file mode 100644 index 00000000..18fb562c --- /dev/null +++ b/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. diff --git a/src/backend/wayland/session/AGENTS.md b/src/backend/wayland/session/AGENTS.md new file mode 100644 index 00000000..62e66295 --- /dev/null +++ b/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. diff --git a/src/backend/wayland/state/AGENTS.md b/src/backend/wayland/state/AGENTS.md new file mode 100644 index 00000000..37592dc8 --- /dev/null +++ b/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. diff --git a/src/backend/wayland/toolbar/AGENTS.md b/src/backend/wayland/toolbar/AGENTS.md new file mode 100644 index 00000000..2e011989 --- /dev/null +++ b/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. diff --git a/src/backend/wayland/zoom/AGENTS.md b/src/backend/wayland/zoom/AGENTS.md new file mode 100644 index 00000000..f4e1b1b5 --- /dev/null +++ b/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. diff --git a/src/canvas_export/AGENTS.md b/src/canvas_export/AGENTS.md new file mode 100644 index 00000000..5ce0c3e4 --- /dev/null +++ b/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. diff --git a/src/capture/AGENTS.md b/src/capture/AGENTS.md new file mode 100644 index 00000000..db696ab4 --- /dev/null +++ b/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. diff --git a/src/config/AGENTS.md b/src/config/AGENTS.md new file mode 100644 index 00000000..21b1eaf9 --- /dev/null +++ b/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. diff --git a/src/config/action_meta/AGENTS.md b/src/config/action_meta/AGENTS.md new file mode 100644 index 00000000..81b582c4 --- /dev/null +++ b/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. diff --git a/src/config/keybindings/AGENTS.md b/src/config/keybindings/AGENTS.md new file mode 100644 index 00000000..2e5761e2 --- /dev/null +++ b/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. diff --git a/src/daemon/AGENTS.md b/src/daemon/AGENTS.md new file mode 100644 index 00000000..20aa6e63 --- /dev/null +++ b/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. diff --git a/src/draw/AGENTS.md b/src/draw/AGENTS.md new file mode 100644 index 00000000..839f5d92 --- /dev/null +++ b/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. diff --git a/src/input/AGENTS.md b/src/input/AGENTS.md new file mode 100644 index 00000000..38334fe3 --- /dev/null +++ b/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. diff --git a/src/input/boards/AGENTS.md b/src/input/boards/AGENTS.md new file mode 100644 index 00000000..a7eebac7 --- /dev/null +++ b/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/`. diff --git a/src/input/state/AGENTS.md b/src/input/state/AGENTS.md new file mode 100644 index 00000000..f3b4389b --- /dev/null +++ b/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. diff --git a/src/input/tool/AGENTS.md b/src/input/tool/AGENTS.md new file mode 100644 index 00000000..11c1dc03 --- /dev/null +++ b/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. diff --git a/src/paths/AGENTS.md b/src/paths/AGENTS.md new file mode 100644 index 00000000..2a20b002 --- /dev/null +++ b/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. diff --git a/src/session/AGENTS.md b/src/session/AGENTS.md new file mode 100644 index 00000000..cb4b633b --- /dev/null +++ b/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. diff --git a/src/ui/AGENTS.md b/src/ui/AGENTS.md new file mode 100644 index 00000000..bff3e05c --- /dev/null +++ b/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. diff --git a/src/ui/toolbar/AGENTS.md b/src/ui/toolbar/AGENTS.md new file mode 100644 index 00000000..217431c1 --- /dev/null +++ b/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. diff --git a/tests/AGENTS.md b/tests/AGENTS.md new file mode 100644 index 00000000..9a08d649 --- /dev/null +++ b/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. diff --git a/tools/AGENTS.md b/tools/AGENTS.md new file mode 100644 index 00000000..4beb7601 --- /dev/null +++ b/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.