From 227c3cc1a39544bc09f5599edcfbec040674c854 Mon Sep 17 00:00:00 2001 From: Xavier Karma Date: Fri, 6 Nov 2026 18:26:02 +0530 Subject: [PATCH] docs(niri): state the first-run experience and refresh the layout map AGENTS.md layout now lists app_identity, legacy_import, model_ladder, packaging/void, the perf protocol script, the Gitea workflows and the niri doc, as its own maintenance rule requires. USER_GUIDE orders Wayland autodetection wtype before ydotool, matching the decided ladder, and says the portal is never tried on niri. docs/NIRI.md states the niri first dictation (no prompt; typing goes direct through wtype; IBus excluded) and points to the GNOME and KDE section. --- AGENTS.md | 18 ++++++++++++++++++ docs/NIRI.md | 9 +++++++++ docs/USER_GUIDE.md | 5 +++-- 3 files changed, 30 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1c9fcc6..bd79532 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -148,6 +148,8 @@ Optional extras: `vosk`, `whisper`, `vad`, `dev`. ``` src/vocalinux/ ├── main.py, version.py, common_types.py, dbus_service.py, post_processor.py +├── app_identity.py # user-visible identity constants (one slug); retained package name is vocalinux +├── legacy_import.py # one-time import of a legacy Vocalinux config, dictionary and restore token ├── audio/ │ ├── capture.py # PortAudio capture sources and device handling │ ├── pipewire.py # PipeWire system-audio capture @@ -160,6 +162,7 @@ src/vocalinux/ ├── gateway_embed/ # optional local VocaGateway lifecycle ├── speech_recognition/ │ ├── recognition_manager.py # VAD, segmentation, and engine dispatch +│ ├── model_ladder.py # memory-aware whisper.cpp rungs, backend order, step-down │ ├── engines/ # engine implementations and availability │ ├── command_processor.py # voice commands │ ├── command_phrases.py # voice command phrases and localized forms @@ -193,6 +196,18 @@ Also: `tests/`, `docs/`, `packaging/` (AppImage, AUR, Flatpak, native .deb/.rpm) `uninstall.sh`, `web/`. `scripts/distro-package-map.yaml` owns installer package names; `install.d/package_map.sh` is generated by `just distro-packages`. +- `packaging/void/`: xbps source templates (`srcpkgs/`), the podman build, smoke and + signed-repository pipeline (`repo.sh`, `container-repo.sh`), and the repository + public key (`repository-key.plist`). The app template consumes the fork's release + sdist; its checksum is pinned only after that release exists. +- `scripts/measure_perf_baseline.py`: the locked performance protocol (see + `docs/PERF_BASELINE_PROTOCOL.md`). Its host binaries obey the same `host_env()` rule as the package. +- `.gitea/workflows/`: the CI home (`ci.yml`, and `xbps-release.yml` for signed xbps + releases on version tags). `CI.md` describes the Gitea runner. The GitHub + `.github/workflows/` tree is the upstream mirror and is not the fork's release path. +- `docs/NIRI.md`: niri activation (documented keybind, toggle triggers) and the + first-dictation experience on niri. + | Task | Start here | |---|---| | Voice command | `speech_recognition/command_processor.py` | @@ -200,6 +215,9 @@ names; `install.d/package_map.sh` is generated by `just distro-packages`. | Text injection | `text_injection/text_injector.py`, `focused_window.py`, `remote_desktop_portal.py`, `ibus_engine.py` | | Settings | `ui/config_manager.py`, `ui/settings_dialog.py` | | Hotkeys | `ui/keyboard_shortcuts.py`, `ui/keyboard_backends/` | +| Model recommendation and memory ladder | `utils/whispercpp_model_info.py` (`get_recommended_model`), `speech_recognition/model_ladder.py` | +| niri activation and tray | `docs/NIRI.md`, `dbus_service.py`, `ui/tray_indicator.py` | +| Void packaging and signed repo | `packaging/void/`, `.gitea/workflows/xbps-release.yml`, `docs/RELEASE_PROCESS.md` | ## Style diff --git a/docs/NIRI.md b/docs/NIRI.md index be0e8e1..c3798a2 100644 --- a/docs/NIRI.md +++ b/docs/NIRI.md @@ -57,6 +57,15 @@ under **Settings → Shortcuts**; with it off, remove the niri bind. A key claimed on both sides fires twice: the compositor toggles over D-Bus while the internal listener fires on its own. +## First dictation + +There is no permission prompt on niri. The RemoteDesktop portal is never +used there, because no portal backend implements it, so your first dictation +types straight into the focused window through `wtype` with nothing to approve +or deny. Do not pin `portal` as a niri recommendation. IBus is excluded on +niri as well. The GNOME and KDE first-run behaviour is described in +[USER_GUIDE.md](USER_GUIDE.md#first-dictation-on-niri-gnome-and-kde). + ## Hold-to-talk stays in the app A compositor bind only sends the key press; it never sees the release, so diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index da62c57..827d50a 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -343,8 +343,9 @@ in place and may select IBus. An explicit non-IBus pin (`portal`, `wtype`, On Wayland, when IBus is not selected, autodetection tries the RemoteDesktop portal first -- it is the only injection path Wayland officially supports and -it needs no uinput device or helper daemon -- then `ydotool`, `wtype`, and -finally `xdotool` under XWayland. +it needs no uinput device or helper daemon -- then direct typing with `wtype`, +then the virtual-input tool `ydotool`, and finally `xdotool` under XWayland. +On niri the portal is never tried, because no backend there implements it. On X11 the injection tool is `xdotool` regardless of which non-`ibus` value you pin, so `xdotool` is the name to use there when IBus is unreliable in a