Code review and cleanup.

docs/testing/audacious.md

@@ -0,0 +1,32 @@
+# Audacious GUI verification
+
+The shared AT-SPI table handling recognizes Qt trees exposing the Table
+interface and GTK list tables. A uniquely selected row can restore its showing,
+focused cell after a menu closes. Multiple selected rows must not produce a
+guessed focus target. GUI full-row speech omits cells that are not showing.
+When Qt hides a submenu without a focus event, its parent action is accepted
+only with fresh provider focus and visibility evidence.
+
+Run `python3 tests/native_audacious.py` with Audacious's Qt and GTK interfaces,
+Xvfb, i3, xdotool, Python gi/pyatspi, and the native build dependencies installed.
+The harness creates temporary tracks and private configuration, display and
+D-Bus sessions. It checks queued speech and Braille for playlists, nested menus,
+the playlist manager, settings, and context menus. It does not verify audible
+speech or a physical Braille display. Also run the
+[generic Qt checks](qt-control-states.md).
+
+For live acceptance:
+
+1. Quit Cthulhu with Cthulhu+Q. Press Ctrl+Escape, then Shift+G to rebuild and
+   launch it. These are separate key presses.
+2. In an Audacious playlist, move between tracks. Expect the selected track's
+   visible row content in speech and the focused cell on Braille, without
+   hidden filename/path columns.
+3. Open Playlist's Sort submenu. Move through commands, then press Left and
+   Escape. Expect the parent menu item on return and the original track when
+   the menus close; arrow keys must continue moving through tracks.
+4. Open Settings, Tab and Shift+Tab through controls, then close it. Expect each
+   focused control and restoration of the playlist. Unfocused password-field
+   initialization must not be announced.
+5. Repeat with the other interface when available. Record the exact speech,
+   Braille, focused control and key sequence for any discrepancy.

docs/testing/tentacle-updates.md

@@ -0,0 +1,44 @@
+# Tentacle update verification
+
+Refresh an installed Tentacle's repository in Preferences, select the Tentacle,
+and choose Update. The confirmation displays both versions and the old and new
+capabilities. Cancel must leave the installation unchanged. Update preserves
+enablement at the point the package is saved, including a disable requested
+while downloading.
+
+Versions use dotted numeric components, optional prerelease identifiers and
+optional build metadata. Missing numeric components compare as zero; build
+metadata does not make a release newer. Invalid versions are not offered as
+updates. Downloads retain the existing HTTPS, checksum and manifest checks.
+
+An enabled replacement must register and activate before success is reported.
+Startup failure or cancellation attempts to restore the previous package and
+enablement. Recovery persistence errors are reported explicitly. Retired files
+remain until their session has stopped. A disabled package is replaced without
+starting it.
+
+Automated checks:
+
+```sh
+go test ./internal/tentacle ./internal/app -run 'Test.*(Upgrade|Update|Version)' -count=1
+go build -o /tmp/cthulhu-update-check ./cmd/cthulhu
+CTHULHU_BINARY=/tmp/cthulhu-update-check CTHULHU_PREFS_TENTACLE_UPDATES_ONLY=1 python3 tests/native_preferences.py
+```
+
+The GTK harness uses fixture data and a private display/bus, checks Tab and
+Shift+Tab, confirmation details, Cancel and the upgrade request, and does not
+update installed packages. Lifecycle tests exercise activation and rollback.
+
+For live acceptance:
+
+1. Quit Cthulhu with Cthulhu+Q. Press Ctrl+Escape, then Shift+G to rebuild and
+   launch it. These are separate key presses.
+2. Open Preferences and select an installed test Tentacle with a newer release.
+   Refresh its repository, then Tab to Update and use Shift+Tab to return.
+   Expect accessible control names in speech/Braille and no keyboard trap.
+3. Activate Update. Verify versions and capabilities are readable, then Cancel.
+   Verify the installed version and existing shortcuts still work.
+4. If you intend to install that release, reopen Update and accept. Verify the
+   new version, its shortcuts and its previous enabled/disabled state. Close
+   and reopen Preferences to verify persistence.
+5. Record exact speech, Braille, focus and keyboard results for discrepancies.

docs/testing/wine-proton.md

@@ -0,0 +1,48 @@
+# Wine and Proton verification
+
+Cthulhu selects a loader from the application's Wine environment and executable.
+It bypasses a recognized Protontricks runtime proxy and searches the Proton
+installation for a usable loader. For processes advertising
+`PRESSURE_VESSEL_RUNTIME`, it stages the complete helper set under
+`$XDG_STATE_HOME/cthulhu/wine-access/helper` (default `~/.local/state`). Sets are
+content-addressed and verified before use; running sets are never overwritten.
+The helper keeps the reader's D-Bus address and receives the application's
+display, authentication and Wine synchronization settings.
+
+The active profile can contain:
+
+```toml
+[profiles.default.wine]
+controller-only = false
+excluded-hook-programs = ["ExampleGame.exe"]
+```
+
+Use your actual active profile name in place of `default`. Exclusions are
+case-insensitive executable basenames, without paths. These settings are read
+when the Wine manager starts; restart Cthulhu after editing them. They are not
+live application-profile switches. The helper must support
+`--exclude-hook-program` and `--no-dialog-reader`.
+
+An excluded program appearing in a prefix switches that prefix's helper to
+controller-only mode. That mode remains until the prefix is retired, even if
+the excluded program exits while a launcher remains. `controller-only = true`
+or a nonempty `WINE_ACCESS_NO_DIALOG_READER` other than `0` requests it globally.
+
+Run `go test ./internal/wine ./internal/config -count=1` for loader selection,
+staging, environment forwarding, exclusion handling and settings persistence.
+Fixtures do not establish compatibility with a real Proton runtime or audible
+Wine output.
+
+For live acceptance:
+
+1. Quit Cthulhu with Cthulhu+Q. Press Ctrl+Escape, then Shift+G to rebuild and
+   launch it. These are separate key presses.
+2. Open an ordinary Wine editor. Verify focused controls, typing, selection and
+   menus are spoken, Braille follows focus, and keyboard navigation is intact.
+3. Launch a test Proton application. Verify its supported accessibility output
+   reaches the reader and closing it does not leave an unnecessary helper.
+4. With an intentionally excluded test game, verify its controller speech still
+   arrives without dialog-reader interference. Check an ordinary editor in a
+   separate prefix still has normal dialog reading.
+5. Report the exact application, prefix relationship, speech, Braille and focus
+   behavior if a result differs. Redact private paths and text from debug logs.

docs/testing/xterm-handoff.md

@@ -0,0 +1,30 @@
+# XTerm handoff verification
+
+While input is delegated to a terminal reader in XTerm, Cthulhu suppresses
+ordinary key echo, input-driven speech interruption and lock-state feedback.
+It releases its command grabs. On return, Caps Lock tracking adopts the current
+XKB lock state before treating Caps Lock as the reader modifier again.
+
+Focused checks:
+
+```sh
+go test ./internal/app -run 'Test(XTerm|DelegatedInput)' -count=1
+python3 tests/native_x11.py
+```
+
+The native harness uses a private X display and checks grab suspension,
+restoration and lock state with synthetic input. Audible output from another
+reader and physical keyboard handling require live verification.
+
+1. Quit Cthulhu with Cthulhu+Q. Press Ctrl+Escape, then Shift+G to rebuild and
+   launch it. These are separate key presses.
+2. Focus XTerm with your console reader active. Press its reader modifier and
+   navigation keys. Expect the console reader to receive them, without
+   Cthulhu modifier echo or Cthulhu interrupting its speech.
+3. Change Caps Lock in XTerm, then switch to an ordinary desktop application.
+   Expect Cthulhu to resume focused-control speech and Braille and accept its
+   configured modifier commands with the current lock state.
+4. Switch back and repeat with keypad commands where configured. Confirm
+   focus stays on the intended application and no key remains grabbed after
+   handoff. Restore the original lock state.
+5. Record the exact keys, focused application, speech and Braille for failures.