Document Go installation and standalone Wine helper recovery

Record the user-local Go installation used by the working reader: install
cthulhu and cthulhu-braille together, validate the configuration, and use
--replace from the original desktop session. Explain that another session
bus can start a second reader instead of replacing the intended instance.

Document the complete five-file standalone wine-access installation and
the legacy helper path supported by the Go supervisor. Older Python
Cthulhu builds can overwrite the launcher and sidecar at that path while
leaving the native hook files behind. Such a helper can connect to D-Bus
without supplying the current native menu and editor support.

Describe recovery by reinstalling the standalone helper and reloading the
reader, including restarting Wine applications when older hook DLLs are
already loaded. Keep the source/build distinction explicit: rebuilding
the Go reader alone does not refresh wine-access.

Validation for these documentation changes:
- Reviewed the complete diff and ran git diff --check.
- Checked the documented shell commands with bash -n.
- Installed both documented Go build outputs into a temporary directory,
  compared their bytes with the builds, and passed --check-config.
- Verified the installed reader, Braille helper, and all five Wine helper
  files match the builds used for the restored installation.

Runtime validation during the preceding repair:
- Cthulhu internal/wine and internal/remote tests passed; Wine-specific
  internal/app tests passed.
- The legacy installed helper failed the isolated 32-bit editor check;
  the standalone helper passed it.
- Standalone controller, 32-bit late-attachment/restart, and hook-safety
  checks passed on private displays and session buses.
- The user confirmed MUSHclient reading was restored. Physical Braille
  was not checked.

These are documentation changes; the installed behavior already comes
from the existing source revisions, with no new runtime source patch.
This commit is contained in:
deedra committed 2026-10-20 02:44:48 -07:00
1 parent 15d527c619
commit 538ff88028
2 files changed
+45

No files matched your search

+29
View File
@@ -33,6 +33,35 @@ Preserve event order, GLib/cgo ownership, and native lifetimes. Balance key grab
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.
### Local installation and reload
After building, install both Go binaries beside one another so the reader can
find its Braille helper:
```sh
install -Dm755 build/cthulhu "$HOME/.local/bin/cthulhu"
install -Dm755 build/cthulhu-braille "$HOME/.local/bin/cthulhu-braille"
"$HOME/.local/bin/cthulhu" --check-config
```
When replacement of the running reader is authorized, reload it from a terminal
in the same desktop session:
```sh
"$HOME/.local/bin/cthulhu" --replace
```
The replacement command finds the running reader through its session D-Bus
service. A terminal using a different session bus can start another reader
instead of replacing the intended one. Preserve the original reader's desktop
session environment when restarting it from automation.
Wine accessibility also needs the separate standalone `wine-access`
installation described in the [README](README.md#wine-access). Building the Go
reader does not build or refresh that helper. After restoring an overwritten
helper, check MUSHclient menus, command typing, and incoming plugin speech;
automated event recordings alone do not establish audible speech acceptance.
## 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:
+16
View File
@@ -21,6 +21,22 @@ system locations, and the old name on `PATH` follows the new name.
Restart Cthulhu after changing the selected helper. Keep the launcher, its
`.exe.so` sidecar, and the native hooks together in the installed directory.
The standalone helper currently installs under the compatible name
`~/.local/libexec/cthulhu/wine/cthulhu-wine-access.exe`. Its complete installation
contains the launcher, `cthulhu-wine-access.exe.so`, `wine-access-menu.dll`,
`wine-access-menu32.dll`, and `wine-access-menu-host32.exe`. The 32-bit host
supplies native menu and editor feedback for applications such as MUSHclient.
Older Python Cthulhu builds can overwrite the helper launcher and sidecar in
that same directory while leaving the standalone hook files behind. The old
helper can still run and connect to Cthulhu without providing the standalone
menu and editor hooks. If Wine reading disappears after installing an older
Cthulhu build, rebuild and reinstall the separate `wine-access` project, then
reload Cthulhu from the same desktop session. If a Wine application already
loaded a previous hook DLL, save its work and restart it to load the replacement.
See [local installation and reload](CONTRIBUTING.md#local-installation-and-reload)
for the Go reader commands.
Wine typing feedback in standard Edit controls follows the current key echo
settings, including the master switch, character echo, and alphabetic, numeric,
punctuation, space and diacritical categories. Tabs and line breaks follow