book

Imported from mahkoh/jay (book/AGENTS.md). Install upstream with npx skills add mahkoh/jay --skill book. Copyright stays with the author.

Jay Book -- Agent Instructions

User-facing mdbook documentation for the Jay Wayland compositor. Target audience is end users, not developers. Goal is feature discoverability.

Quick reference

Book files (book/src/)

The table of contents is SUMMARY.md — it is the authoritative chapter list and must be updated when adding a new chapter. Chapter-to-topic mapping:

Source-of-truth files (from repo root)

Critical facts

1. Config replacement. ~/.config/jay/config.toml replaces the entire built-in default — not merged. Empty file = no shortcuts, nothing. Users must run jay config init.

2. Config reload. Manual by default (alt-shift-r / reload-config-toml). auto-reload = true enables inotify watching with 400 ms debounce.

3. Actions are composable. Anywhere an action is accepted, an array works. Named actions ($name) add reuse.

4. Exec action gotcha. Plain string = program name only (no arg splitting). exec = "notify-send 'hello'" is wrong — use array form.

5. Capability replacement. When any client rule matches, its capabilities replace defaults entirely (not additive). Verify against handler.rs:update_capabilities.

6. Window rule actions. Actions using window_or_seat! in lib.rs work in both shortcuts (focused window) and window rules (matched window). The list in shortcuts.md "Actions in window rules" must stay in sync.

7. Window/client rules are reactive. Re-evaluated when criteria change. latch fires when a rule stops matching.

8. VRR vs tearing subtlety. VRR variant1/2 use "fullscreen"; tearing variant3 says "a single application is displayed" (not necessarily fullscreen). Always check spec.yaml wording.

Style rules

• Audience: users, not developers. Explain what, not how.
• Code fences: ```shell for commands (prefix ~$), ```toml for config.
• Admonitions: > [!NOTE], > [!TIP], > [!WARNING], > [!IMPORTANT].
• Key combos: backticks, lowercase modifiers: alt-shift-c, ctrl-alt-F2, alt-Return. Never Alt+C.
• Definition lists for two-column term/description. Tables only for 3+ data columns.
• TOML formatting: multiline with trailing commas, 4-space indent.
• Examples: practical, not abstract. Link to spec.generated.md for exhaustive listings.
• Control center docs: verify field names, ordering, and conditional visibility against cc_*.rs source files. Labels must match exactly.

Common tasks

Documenting a new action

1. Read git diff for the commit introducing the action. Key files:

   • toml-spec/spec/spec.yaml — spec entry (description, fields, examples)
   • toml-config/src/config/parsers/action.rs — parser (field names, types, defaults)
   • toml-config/src/lib.rs — dispatch (check if window_or_seat! is used)
   • jay-config/src/input.rs and/or jay-config/src/window.rs — Rust API

2. Edit book/src/configuration/shortcuts.md:

   • Simple actions (no fields): add to the appropriate list in the "Simple actions" section.
   • Parameterized actions (has fields): add a new ### subsection before "Other parameterized actions". Include definition list for fields and practical TOML examples.
   • Also parameterized but minor: just add a - name -- description bullet to the "Other parameterized actions" list.

3. If window_or_seat! is used in lib.rs, add the action name to the "Actions in window rules" list at the bottom of shortcuts.md.

Documenting a new config field

1. Read toml-spec/spec/spec.yaml for the field definition.
2. Identify which book chapter covers that config section (see table above).
3. Add the field with a definition-list entry or example, matching the existing style of that chapter.

Documenting a new CLI subcommand

1. Read src/cli/*.rs for clap definitions.
2. Edit book/src/cli.md. Follow the existing pattern for subcommand docs.
3. If the subcommand has --json support, mention it in the "JSON Output" section.

Documenting a control center change

1. Read the relevant src/control_center/cc_*.rs file.
2. Edit book/src/control-center.md. Match field names, ordering, and conditional visibility exactly.

Adding a new book chapter

1. Create the new .md file under book/src/.
2. Add an entry in book/src/SUMMARY.md under the appropriate section.
3. Update the chapter-to-topic mapping in this file and AGENTS.md.

Building

~$ cd book && mdbook build    # outputs to book/book/
~$ cd book && mdbook serve    # preview at http://localhost:3000