# AGENTS.md (Codex CLI guidance)

This repository is a screen reader. Prioritize accessibility, correctness, and stability over “clever” changes.

## System interactions
- If a command requires `sudo`, stop and ask the user to run it (no password entry is possible from here).

## Build / run quick refs
- Local dev build + install: `./build-local.sh`
- Quick local sanity checks: `./test-local.sh`
- Clean local artifacts/install: `./clean-local.sh`
- Meson (manual):
  - `meson setup _build --prefix=$HOME/.local`
  - `meson compile -C _build`
  - `meson install -C _build`

## Runtime target and testing rules
- Make source changes in this repo, not in `~/.local/lib/python*/site-packages/cthulhu/`, unless the user explicitly asks for an installed-package hotfix.
- If you confirm the active import comes from `~/.local/...`, that does **not** mean you should edit there. It means you should update the repo and then run `./build-local.sh` to replace the installed copy for testing.
- Default test/apply workflow for local Cthulhu fixes:
  - edit repo files
  - run `./build-local.sh`
  - reproduce/test against the refreshed `~/.local` install
- If repo and installed behavior differ, prefer rebuilding with `./build-local.sh` over patching the installed package directly.
- Treat direct edits under `~/.local/.../cthulhu/` as an exception path that requires explicit user approval.

## Bug intake
- Assume reporters may have little or no development experience. Ask for user-visible steps and guide them through logs or diagnostic commands without expecting them to identify the subsystem or use technical terminology.
- Capture the application or browser, page URL when relevant, desktop/session type, exact steps, expected result, actual result, and whether the problem is reproducible elsewhere.
- Separate keyboard focus from speech output: ask whether focus fails to move, moves but is not announced, or is reachable through another navigation method.
- For web issues, determine whether the behavior is site-specific, browser-specific, or reproducible across similar controls before changing code.
- When a log is needed, guide the reporter through launching the locally installed build with `~/.local/bin/cthulhu --debug-file /tmp/cthulhu.log --debug`, reproducing the problem once, exiting Cthulhu, and providing `/tmp/cthulhu.log` for review.
- If a reporter still sees the same problem after a fix, verify that the refreshed build is actually installed and running before assuming the patch failed. Guide the reporter through the check rather than assuming they know how the local install works.

## Contribution workflow (including generated patches)
- Assume contributors may use code-generation tools without understanding every changed line. Review the resulting code, not the contributor's confidence in it.
- Start from a reproducible user-visible problem. Complete the relevant bug-intake steps before changing code.
- Investigate the full confirmed behavior class before implementing a fix. For example, a stale-focus bug seen in one browser may also affect other applications or empty workspaces.
- Prefer the smallest root-cause fix that covers the full confirmed behavior class. Do not add app-specific exceptions, desktop-specific branches, compatibility fallbacks, or broad refactors unless the evidence requires them.
- Add or update automated regression tests for the general behavior and the originally reported workflow whenever practical.
- Read every generated diff before committing. Remove unrelated rewrites, speculative cleanup, dead code, debug leftovers, and generated files that are not required by the fix.
- Never commit a behavior change solely because it compiles or because an automated tool says it works. Verify the real user-facing workflow after rebuilding the installed copy.

## Verification checklist before commit
Run the narrowest relevant checks first, then broaden testing based on the affected behavior:
- For documentation-only changes, diff inspection is sufficient unless the edited documentation includes commands or generated content that need validation.

1. Inspect the diff:
   - `git diff --check`
   - `git status --short`
   - `git diff --stat`
   - `git diff -- <changed files>`
2. Run syntax checks for each changed Python file:
   - `python -m py_compile <changed .py files>`
3. Run focused automated regression tests:
   - `python -m unittest <relevant test modules>`
   - For shared input, focus, script lifecycle, settings, plugin loading, or installation changes, run `./test-local.sh` after the focused tests pass.
4. For code or behavior changes, rebuild the local installed copy:
   - `./build-local.sh`
5. For code or behavior changes, confirm the runtime import resolves to the refreshed local install:
   - `python - <<'PY'`
   - `import importlib.util`
   - `print(importlib.util.find_spec("cthulhu").origin)`
   - `PY`
6. For code or behavior changes, reproduce the original user-visible workflow against the rebuilt copy.
7. For focus, keyboard, or window-tracking changes, manually test closely related regressions:
   - Xorg and the user's active window manager or desktop.
   - Switching among browser content, terminal windows, GTK applications, dialogs, and empty workspaces.
   - Returning to the original application after each switch.
   - Cthulhu shortcuts, structural navigation, flat review, and any delegated key handling such as Fenrir in XTerm.
   - Both key press and key release behavior for modifiers, NumLock, and keypad keys when relevant.
   - Clean shutdown without crashing the browser or leaving grabs behind.
8. Record what was tested, what could not be tested locally, and any remaining uncertainty in the commit message or review notes.

## Platform support stance
- **critical** Robust Xorg support is required and is a merge gate for Cthulhu.
- Wayland support is desirable, but it is secondary to keeping Xorg stable and usable.
- If a change that improves Wayland would break, weaken, or regress Xorg support, the answer is a hard no by default.
- If the user explicitly insists on such a change anyway, warn them plainly that the change is expected to be rejected without further consideration as long as Xorg is adversely affected.
- Prefer desktop-agnostic fixes first. If a tradeoff is unavoidable, choose the path that preserves Xorg correctness and defer the Wayland-specific improvement.

## Coding guidelines
- **When modifying existing code:** follow the surrounding code’s conventions.
- **When writing new code from scratch:** prefer
  - variables: `camelCase`
  - functions/methods: `snake_case`
  - classes: `PascalCase`
- Keep changes clean and well-structured; avoid layering short-term workarounds when a focused fix is possible.
- Add debug logs where helpful for troubleshooting. When adding timestamps to logs, use: `"Message [timestamp]"` (message first).

## Accessibility requirements (high priority)
### General
- Screen-reader-first UX: assume non-visual navigation.
- No keyboard traps; Tab/Shift+Tab must move through all controls.
- Use clear, complete labels (e.g., “Confirm Password”, not “Confirm”).
- Do not invoke `spd-say` or add direct speech output to GUI dialogs. Expose accessible UI state and let the active screen reader announce it.

### Python GTK (Gtk 3)
- Associate labels with controls (mnemonics + buddy widget):
  - `label.set_use_underline(True)`
  - `label.set_mnemonic_widget(entry)`
- For `Gtk.TextView`, call `set_accepts_tab(False)` so Tab moves focus.
- For custom widgets, set accessible name/role via ATK where applicable.

## Shell script rules
- **Bash variables must be `camelCase`** (except system env vars like `ACCESSIBILITY_ENABLED`).
- If you edit a `#!/usr/bin/env bash`, `#!/bin/bash`, or POSIX `sh` script, run `shellcheck` and fix issues.
- Avoid colorized output unless explicitly requested (accessibility-first; keep scripts simple).

## Plugins (Cthulhu)
- System plugins live in `src/cthulhu/plugins/`.
- Follow existing plugin patterns (keybinding registration, GTK dialog/window patterns, debug logging).

## Meson install reminder (important)
- If you add new Python modules under `src/cthulhu/`, update `src/cthulhu/meson.build` so they get installed (otherwise imports can fail after install).
- If you add a new plugin directory, update `src/cthulhu/plugins/meson.build` and add a `meson.build` in the plugin directory.

## Settings policy (important)
- Keep persistent settings in Cthulhu TOML files through the existing settings manager and TOML backend.
- Do not add `gsettings`, `dconf`, or `Gio.Settings` dependencies or fallback paths.

## Dependency synchronization (important)
- This repository does not use `requirements.txt`. When adding, removing, or changing a runtime, optional, or build dependency, keep the relevant dependency declarations and documentation synchronized.
- Check `pyproject.toml`, `meson.build`, the dependency sections in `README.md` and `README-DEVELOPMENT.md`, and each applicable distro package recipe under `distro-packages/`.
- In particular, update both Arch Linux `PKGBUILD` files and, when relevant, Slint's `cthulhu-info` and `README`. Review the Slackware and Slint build files for any corresponding build-dependency changes.
- Preserve the distinction between required, optional, and build-only dependencies so package builds install what Cthulhu actually needs without forcing optional features on every user.

## Common Cthulhu agent mistakes
- Do not edit or diagnose a stale installed copy under `~/.local/...`; update the repo and rebuild with `./build-local.sh`.