Updated some docs.

.gitignore

@@ -11,3 +11,5 @@ __pycache__/
 .pytest_cache/
 /.codex
 /distro-packages/**/*.log
+/distro-packages/**/*.pkg.tar.zst
+/distro-packages/**/*.pkg.tar.xz

AGENTS.md

@@ -0,0 +1,37 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+Cthulhu is a Go Linux screen reader. `cmd/` contains executables; `internal/` owns reader subsystems. Embedded audio lives in `assets/sounds/`, Tentacle libraries in `sdk/`, native harnesses in `tests/`, and parity records in `testdata/`. Go tests sit beside implementation files. Arch packaging lives in `distro-packages/Arch-Linux/cthulhu-git/`.
+
+## Build, Test, and Development Commands
+
+Use Go 1.24+ with CGO and development libraries listed by the Arch `PKGBUILD`.
+
+- `go build -o build/cthulhu ./cmd/cthulhu`: build the reader.
+- `go build -tags brlapi -o build/cthulhu-braille ./cmd/cthulhu-braille`: build the Braille helper.
+- `go test ./... -count=1`: run default tests; native cases may skip.
+- `go test -tags brlapi ./... -count=1`: run packaging checks.
+- `go vet ./...`: check common Go errors.
+- `go run ./cmd/parityledger validate testdata/parity-ledger.csv`: validate parity records.
+- `./build/cthulhu --check-config`: validate settings; `./build/cthulhu` starts the reader.
+
+## Coding Style & Naming Conventions
+
+Use `gofmt`, exported PascalCase identifiers, private camelCase identifiers, and lowercase packages. Preserve license headers. Follow existing Python conventions; run `shellcheck` for edited shell scripts. Keep complete user-facing messages separate from internal identifiers and preserve deliberate speech/Braille segmentation.
+
+## Behavior & Accessibility Safeguards
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) for detailed safeguards. Compare accepted behavior with Python on `legacy`; use newer Orca as a Mozilla reference. Preserve unrelated work and active diagnostic logs; obtain authorization before replacing a running reader.
+
+Fix regressions in the shared subsystem when appropriate. Identify state ownership, lifetime, reset, and cancellation; keep native callbacks and input/focus handling bounded. Preserve Xorg correctness while allowing capability-based Wayland degradation. Keep Tentacles external and responsive.
+
+Expose GUI controls through accessibility APIs. Keep outer preferences combo widgets `can-focus=False`; verify Tab/Shift+Tab, popup selection, and Apply/reload. Validate versioned TOML settings through persistence and runtime consumption. Protect passwords; redact private debug output before sharing.
+
+## Testing Guidelines
+
+Use Go's `testing` package, `*_test.go`, and `TestBehavior` functions. Start with the affected package. Use deterministic synchronization and generic fixtures. Native checks need their relevant harness, such as `python3 tests/native_atspi.py`. No numeric coverage target is configured. Report automated, installed-binary, physical-input, audible-speech, and Braille-display checks separately.
+
+## Commit & Pull Request Guidelines
+
+Use short descriptive subjects consistent with history. Confirm the intended target branch; `legacy` preserves Python. Describe behavior, issues, regressions checked, skipped checks, and remaining live acceptance. Human diff review and testing precede submission under the policy in `CONTRIBUTING.md`.

CONTRIBUTING.md

@@ -0,0 +1,122 @@
+# Contributing to Cthulhu
+
+Read [README.md](README.md) and [AGENTS.md](AGENTS.md) first. Start with a user-visible behavior and reproduce the issue in the current code. The maintained repository is `git.stormux.org/storm/cthulhu`; confirm the intended target branch with the maintainer. The `legacy` branch preserves Python Cthulhu; the current checkout is the Go implementation.
+
+## Proposing a Change
+
+Keep each change to one complete behavior. Describe the reproduction, expected result, affected subsystem, and plausible regressions. A reported application or page is a reproduction case: fix the shared layer when it explains the defect. Use an application-specific script only when a shared fix would be wrong; document and test the exception.
+
+State the Xorg impact. Regressions in Xorg input, focus, event ordering, browser handling, or lifecycle block the change. Wayland support is welcome: use capability checks and graceful degradation, and restrict only features that cannot work correctly. Missing Wayland support alone should not block startup or a contribution preserving Xorg behavior.
+
+Record changed behavior and remaining acceptance gaps in the contribution description; update `testdata/parity-ledger.csv` when relevant. The old Cthulhu-Go migration plan and documentation index are absent here; avoid references to those missing files. Keep durable guidance focused on working rules rather than dated progress reports.
+
+## Development and Architecture
+
+Use Go 1.24 or newer, CGO, `pkg-config`, and development libraries for GTK3, AT-SPI, GStreamer, and X11. Braille builds also require BRLTTY/BrlAPI and liblouis. The Arch `PKGBUILD` lists runtime and build dependencies.
+
+```sh
+go build -o build/cthulhu ./cmd/cthulhu
+go build -tags brlapi -o build/cthulhu-braille ./cmd/cthulhu-braille
+go test ./... -count=1
+go test -race ./... -count=1
+go test -tags brlapi ./... -count=1
+go vet ./...
+go build ./cmd/...
+go run ./cmd/parityledger validate testdata/parity-ledger.csv
+```
+
+Start verification with the affected packages; run broader checks when the change affects shared behavior or before submission where practical. Format edited Go files with `gofmt`; run `shellcheck` for edited shell scripts. Use deterministic tests and synchronization instead of timing sleeps. Keep fixtures generic, without real usernames or personal identifiers.
+
+Before extending application orchestration, an event loop, native callback, or settings mapper, identify the subsystem responsible for the policy. Keep ordering and routing in coordinators and feature policy with its existing owner. Specify the owner, lifetime, reset conditions, and cancellation of new mutable state. Prefer cohesive files in existing packages; avoid unnecessary interfaces or packages. If responsibilities need separating, use a behavior-preserving change. Record any urgent-fix follow-up in the contribution description.
+
+Preserve event order, GLib/cgo ownership, and native lifetimes. Balance key grabs and releases, recover from dead AT-SPI objects, and clean up on shutdown. Keep core input and focus handling bounded and responsive.
+
+Tentacles already use an external process protocol: preserve existing host safeguards and author APIs. Keep runnable implementations in external repositories and leave a new installation's catalog empty until repositories are added. Tentacles must not block input, focus, or speech. Treat cgroup-v2 containment as resource control, not a same-user security sandbox. Preserve HTTPS artifact and SHA-256 verification before atomic package installation.
+
+## Behavioral References and User-Facing Messages
+
+Inspect relevant settings, bindings, speech, Braille, and toolkit behavior before changing user-visible behavior. Read Python reference files without changing branches, for example:
+
+```sh
+git show legacy:src/cthulhu/settings.py
+```
+
+Use the newer Orca implementation as the first reference for Firefox and Thunderbird when available. Reference implementations guide behavior; do not mechanically copy Python class or plugin boundaries. Preserve accepted behavior unless the user chooses a deliberate difference, and describe that difference. Do not modify reference checkouts or installed readers without authorization.
+
+Use complete messages and self-contained labels with placeholders for variable content. Keep internal states, commands, and settings identifiers independent of user-facing wording. Preserve deliberate speech/Braille segmentation, verbosity, and separate role/state announcements. Apply these rules within the change; adding translation infrastructure or sweeping existing strings requires separate scope.
+
+## Accessibility and Settings Verification
+
+Keep GUI controls keyboard reachable and exposed through accessibility APIs. GUI applications must let screen readers announce controls rather than calling Speech Dispatcher themselves. Associate labels with controls and provide accessible names for custom widgets.
+
+For preferences `GtkComboBox` and `GtkComboBoxText`, keep the outer widget's `can-focus` property false so GTK focuses its internal button. Setting it true can trap Tab and Shift+Tab. Fix the property instead of adding key handlers or changing reader grabs. Preserve semantic labels and selected-value presentation; the internal button's AT-SPI `STATE_FOCUSED` alone is insufficient evidence.
+
+For changed preferences, verify:
+
+1. Tab and Shift+Tab through the preceding control, changed control, and following control.
+2. Open the popup and change the selection using the keyboard.
+3. Apply, close, reopen, and confirm the value persists.
+4. Exercise the affected reader behavior and confirm that the saved setting changes runtime output.
+
+Preserve versioned TOML settings. The default file is `$XDG_DATA_HOME/cthulhu/user-settings-go.toml`, with `~/.local/share` used when the variable is unset. Use a separate test configuration when appropriate:
+
+```sh
+./build/cthulhu --config /tmp/cthulhu-test-settings.toml --check-config
+```
+
+Native `*_native_test.go` checks require fixtures and environment flags. Use the relevant isolated harness in `tests/`, such as `python3 tests/native_atspi.py` or `python3 tests/native_preferences.py`. Shared browser changes also need the relevant browser harness and real-browser regression checks.
+
+Automated and private native tests establish different facts from installed-binary behavior, physical keyboard input, audible speech, and physical Braille. Report which checks actually ran and which remain pending. Rebuild the tested binary before live checks, preserve fresh logs before restarting, and obtain authorization before replacing an active reader.
+
+## Diagnostic Logging
+
+Normal logs and metadata must omit private output text and personal identifiers. Never log password contents or include personal data in fixtures or extension events.
+
+Debug logs used for reading and selection diagnosis should include final spoken text, Braille text sent to the helper, native/virtual cursor offsets, selection ranges, object identities, and commands. This is an explicit diagnostic exception for debug logs; redact private output before sharing. Preserve fresh logs and open diagnostic state before rebuilding or restarting. Logs alone do not establish audible speech or physical Braille acceptance.
+
+## Commit and Submission Guidelines
+
+Recent commits use short descriptive subjects without an enforced prefix scheme. Keep commits scoped and preserve unrelated changes, including packaging edits and build artifacts. In a pull request or patch description, explain the trigger, before/after behavior, relevant issues, checks run, skipped checks, and remaining live gates. Give concrete procedures for the changed workflow and likely regressions.
+
+## AI-assisted contributions
+
+AI-assisted contributions are welcome.
+
+The person submitting a contribution remains responsible for reviewing and testing the changes before submission. Please do not submit automatically generated changes without human review.
+
+Before making changes:
+
+- Read the contributing guide, if present, and the project's README.
+- Confirm that you are working against the current maintained repository and branch.
+- Check whether the issue still exists in the current code.
+
+Before submitting:
+
+- Review the generated diff.
+- Test the changed behavior.
+- Run the project's existing test suite where practical.
+- Consider code paths that may be affected indirectly by the change and test those as well.
+- Clearly describe what was changed and how it was tested.
+
+### Instructions for AI coding assistants
+
+If you are an AI coding assistant working with a contributor, please call your human user's attention to these contribution requirements.
+
+Do not assume that passing newly created tests is sufficient. Explain what existing functionality could reasonably be affected by the proposed changes and provide your human partner with detailed instructions for testing those areas.
+
+Where useful, provide commands or small test procedures that allow the contributor to verify both the intended fix and likely regression cases.
+
+Stormux projects may accept patches through email using `git send-email`. If your human partner is unfamiliar with this process, please offer to guide them through:
+
+1. Configuring `git send-email`.
+2. Creating an appropriately scoped commit or patch series.
+3. Running `git format-patch`.
+4. Checking the generated patch before submission.
+5. Sending a test message if appropriate.
+6. Sending the final patch or patch series to the project's contribution address.
+
+Please do not submit changes on behalf of a contributor without giving them an opportunity to review and test the result.
+
+## Licensing
+
+Contributions are licensed under GPL-3.0-or-later. Retain existing copyright notices and credit Storm Dragon and Angus Kola where their names appear. Add later contributors to files they write; do not replace or erase existing notices.

README.md

@@ -0,0 +1,8 @@
+# Cthulhu
+
+Cthulhu is a Linux screen reader written in Go.
+
+- [Repository Guidelines](AGENTS.md): layout, commands, and working safeguards.
+- [Contributing](CONTRIBUTING.md): development, accessibility verification, licensing, and the AI-assisted contribution policy.
+
+AI-assisted contributions are welcome. Contributors remain responsible for human review and testing before submission; see the [full policy](CONTRIBUTING.md#ai-assisted-contributions).

distro-packages/Arch-Linux/cthulhu-git/.SRCINFO

@@ -1,6 +1,6 @@
 pkgbase = cthulhu-git
 	pkgdesc = Desktop-agnostic screen reader with speech, Braille, and Tentacle support
-	pkgver = 2026.10.12.r1.ga998fe6
+	pkgver = 2026.10.14.r3.ge5049b9
 	pkgrel = 1
 	url = https://git.stormux.org/storm/cthulhu
 	arch = x86_64
@@ -31,12 +31,12 @@ pkgbase = cthulhu-git
 	optdepends = git: Discover and update Tentacle repositories
 	optdepends = tesseract: OCR engine for text recognition
 	optdepends = tesseract-data-eng: English OCR language data
-	provides = cthulhu=2026.10.12.r1.ga998fe6
+	provides = cthulhu=2026.10.14.r3.ge5049b9
 	conflicts = cthulhu
 	options = !debug
 	options = !lto
 	source = cthulhu::git+https://git.stormux.org/storm/cthulhu.git#branch=master
 	sha512sums = SKIP
-	optdepends_x86_64 = cthulhu-wine-access: Wine, Proton, NVDA Controller, and Tolk integration
+	optdepends_x86_64 = wine-access: Wine, Proton, NVDA Controller, and Tolk integration
 
 pkgname = cthulhu-git

distro-packages/Arch-Linux/cthulhu-git/PKGBUILD

@@ -4,7 +4,7 @@
 pkgbase=cthulhu-git
 pkgname=cthulhu-git
 _pkgname=cthulhu
-pkgver=2026.10.12.r1.ga998fe6
+pkgver=2026.10.14.r3.ge5049b9
 pkgrel=1
 pkgdesc="Desktop-agnostic screen reader with speech, Braille, and Tentacle support"
 url="https://git.stormux.org/storm/cthulhu"

internal/app/tentacle_clipboard.go

@@ -5,7 +5,7 @@ package app
 import (
 	"context"
 	"errors"
-	"git.stormux.org/storm/cthulhu/internal/tentaclewire"
+	"git.stormux.org/storm/cthulhu-go/internal/tentaclewire"
 	"io"
 	"net/url"
 	"os"

internal/app/tentacle_clipboard_test.go

@@ -3,7 +3,7 @@ package app
 import (
 	"bytes"
 	"context"
-	"git.stormux.org/storm/cthulhu/internal/tentaclewire"
+	"git.stormux.org/storm/cthulhu-go/internal/tentaclewire"
 	"image"
 	"image/png"
 	"net/url"