Initial commit.

hello-world/README.md

@@ -0,0 +1,78 @@
+# Hello World
+
+Press **Cthulhu+Alt+Shift+H** to speak and braille **Hello world!**. The Tentacle
+suggests this global binding in both desktop and laptop layouts. Core and user
+bindings take precedence; a conflict leaves the command available for remapping.
+Learn mode announces the command description without running it.
+
+The command returns one plain-message presentation through the reader SDK,
+with `uninterruptible = true`. After the reader accepts the result, ordinary
+typing, focus changes and reader commands cannot interrupt the speech; later
+output queues until the synthesizer reports completion. Pending stale results
+are still rejected. Session disable/failure, screen lock, terminal handoff,
+reader shutdown, speech disable and speech mode changes can stop it. Protection
+has a 30-second bound starting at acceptance. This requires Speech Dispatcher
+completion events; hardware speech backends cannot guarantee audible completion.
+The message obeys speech/beeps/off and Braille preferences. Braille uses a normal
+translated flash and can be replaced by newer core output.
+
+Hello World requests presentation access only. It receives no focused text,
+uses no network services, and stores no settings. Source and distribution are
+licensed under GPL-3.0-or-later; see [LICENSE](LICENSE).
+
+## Local launch
+
+Run `make build` from the repository root. Rebuild Cthulhu-Go with the matching
+SDK/output implementation before a live test:
+
+```sh
+cd ../cthulhu-go
+GOCACHE=/tmp/cthulhu-go-cache go build -o /tmp/cthulhu-with-hello-world ./cmd/cthulhu
+```
+
+Create a development launch list with an absolute executable path. From this
+repository root, this command writes one without changing your saved registry:
+
+```sh
+python3 - <<'PY'
+import json
+from pathlib import Path
+
+programPath = Path('hello-world/bin/hello-world').resolve()
+Path('/tmp/cthulhu-hello-world.json').write_text(json.dumps([
+    {'ID': 'hello-world', 'Presentation': True, 'Program': [str(programPath)]}
+]) + '\n')
+PY
+```
+
+When ready to test, launch the rebuilt reader explicitly:
+
+```sh
+/tmp/cthulhu-with-hello-world --replace --tentacles /tmp/cthulhu-hello-world.json
+```
+
+That command replaces the running Go reader and selects the development launch
+list instead of saved Tentacles. The reader automatically requests systemd user
+cgroup delegation. A delegation failure leaves the Tentacle unavailable.
+Resource limits do not make untrusted same-user programs safe.
+
+## Live verification
+
+1. In an ordinary accessible GTK window on Xorg, press Cthulhu+Alt+Shift+H.
+   Listen for exactly “Hello world!” and verify it on a connected Braille display.
+   Repeat with desktop and laptop layouts.
+2. Immediately type or move focus after activation. Once speech has begun,
+   it should finish and later control speech should follow. Input before the
+   result is accepted can still suppress that stale reply.
+3. Try the binding in learn mode: expect its description, with no greeting.
+   Verify existing heading navigation and ordinary reader commands still work.
+4. During the greeting, disable Tentacles with Cthulhu+Ctrl+Shift+Q, enter screen
+   lock or terminal handoff, or change speech mode. The greeting must stop and
+   must not resume afterward. Restart the reader to re-enable the development list.
+5. Check speech off/beeps and disabled Braille settings. Hello World must respect
+   them. Remap or occupy the suggested binding and check core/user precedence.
+
+Audible speech, physical shortcuts, actual display output and the eventual
+repository-installation workflow require these live checks; protocol tests do
+not establish them.
+