Rename mechanics #8

New Issue

2026-11-05T15:23:10Z

xavierk commented

2026-11-05 15:23:10 +00:00

Part of #1

Question

What exactly renames to voculinux: binary, desktop id, XDG directories, D-Bus names, Python package, xbps package, and web site, and how does the one-time vocalinux config import work?

Part of #1 ## Question What exactly renames to voculinux: binary, desktop id, XDG directories, D-Bus names, Python package, xbps package, and web site, and how does the one-time vocalinux config import work?

xavierk added the wayfinder:grilling label 2026-11-05 15:23:10 +00:00

xavierk referenced this issue

2026-11-05 16:06:35 +00:00

Wayland terminal injection choice #6

xavierk referenced this issue

2026-11-05 16:09:52 +00:00

Carbon and Bongbetic UI direction #7

xavierk self-assigned this 2026-11-05 16:10:33 +00:00

xavierk commented

2026-11-05 16:11:08 +00:00

Resolution: Rename mechanics

Decision (made by agent under the user's explicit delegation for this run, with rationale and evidence below — the human did not personally dictate these answers): rename everything user-visible to Voculinux/voculinux, and keep the Python import package vocalinux as an internal legacy name.

What renames to voculinux

App name, binaries, and entry points. Console script vocalinux becomes voculinux and the GUI script vocalinux-gui becomes voculinux-gui (today declared in pyproject.toml under [project.scripts] / [project.gui-scripts]). argparse prog, GLib.set_prgname, and the tray APP_ID (today "vocalinux" in src/vocalinux/ui/tray_indicator.py) all use the new name.
Desktop file and autostart. vocalinux.desktop becomes voculinux.desktop with Exec=voculinux and Icon=voculinux; the autostart filename constant and the shutil.which("vocalinux") lookup in src/vocalinux/ui/autostart_manager.py move to the new name.
XDG directories and files. The single APP_DIR_NAME constant in src/vocalinux/utils/paths.py (today "vocalinux") becomes "voculinux", which moves config (~/.config/voculinux/config.json), data (~/.local/share/voculinux/, including instance.lock, transcription history, and logs), cache, and the IBus data dir together. The install-state log dir under ~/.local/state/vocalinux in install.sh moves the same way.
D-Bus identity. Bus name, object path, and interface move from com.vocalinux.Vocalinux / /com/vocalinux/Vocalinux to com.voculinux.Voculinux / /com/voculinux/Voculinux (today in src/vocalinux/dbus_service.py, with the matching gdbus example string in src/vocalinux/ui/keyboard_backends/__init__.py). No compatibility alias for the old name: this is a hard fork, and the niri keybinds already decided elsewhere will target the new name.
IBus engine. Engine name, component textdomain, and install/data paths move from vocalinux to voculinux (today ENGINE_NAME, VOCALINUX_IBUS_DIR, and the component dict in src/vocalinux/text_injection/ibus_engine.py).
System install paths. Packaged model/resource/icon lookup prefixes move from /usr[/local]/share|lib|lib64/vocalinux/... to the same trees under voculinux (today hardcoded in recognition_manager.py, settings_dialog.py, and utils/resource_manager.py), as do the tray icon names (voculinux-microphone*) and the User-Agent string.
xbps package. The package is named voculinux, owning the renamed system paths above, consistent with the already-decided dual-track packaging route.
Website. The marketing site rebrands from Vocalinux/vocalinux.com to Voculinux as part of this effort (the map Destination already places the web rebrand here, not later).

What deliberately stays `vocalinux`

The Python import package (src/vocalinux/..., from vocalinux..., python -m vocalinux.main, the setuptools packages list). Renaming it would churn every module, test, the IBus/engine process matching in install.sh, and every future hand cherry-pick from upstream, for zero runtime benefit. The distribution/binary rename is user-visible; the import name is internal. This also resolves the map's open fog patch about whether the Python package renames: it does not, and the fork documents vocalinux as the retained internal module name.
Upstream URLs and history (github.com/VocaHQ/vocalinux references, changelog) stay as-is for provenance.

One-time config import

On first run, when the new config directory has no config.json but the legacy ~/.config/vocalinux/config.json exists, the app copies the legacy config.json and the legacy custom-dictionary file into the new directory and logs the import. The existing normalize/validate path in config_manager.py then loads the copy unchanged.
Rules: the new directory always wins once it exists (never merge, never write back to the legacy path, never re-import). Models, history, logs, and locks are not migrated — models re-resolve through the pinned-checksum download path. If no legacy config exists, the app starts from fresh defaults.

Evidence inspected

Repo AGENTS.md (hard limit: no invented features; smallest change matching existing patterns), the map Destination and Notes (fresh voculinux XDG dirs plus one-time vocalinux import; Destination names app, binary, package, and site), src/vocalinux/utils/paths.py, src/vocalinux/dbus_service.py, src/vocalinux/single_instance.py, src/vocalinux/ui/config_manager.py (imports config_dir), src/vocalinux/ui/autostart_manager.py, src/vocalinux/ui/tray_indicator.py, src/vocalinux/text_injection/ibus_engine.py, vocalinux.desktop, pyproject.toml (project name, scripts, packages), install.sh (process matching, state dir), and web/PRODUCT.md (site scope). No GLOSSARY.md or docs/adr/ exists in the repo, so no glossary/ADR file change was made; the terminology (Voculinux app, voculinux binary/package/ids, vocalinux retained internal module plus legacy XDG source) lives in this comment.

Consequences for later tickets

The Python performance baseline ticket is unaffected (same interpreter, same module layout).
xbps template work uses voculinux package/path names; niri keybind work targets the new D-Bus name.
Remaining rename-adjacent fog (portal first-run prompt UX, model catalog) is unchanged and stays in Not yet specified.

## Resolution: Rename mechanics **Decision (made by agent under the user's explicit delegation for this run, with rationale and evidence below — the human did not personally dictate these answers): rename everything user-visible to Voculinux/voculinux, and keep the Python import package `vocalinux` as an internal legacy name.** ### What renames to voculinux - **App name, binaries, and entry points.** Console script `vocalinux` becomes `voculinux` and the GUI script `vocalinux-gui` becomes `voculinux-gui` (today declared in `pyproject.toml` under `[project.scripts]` / `[project.gui-scripts]`). `argparse` prog, `GLib.set_prgname`, and the tray `APP_ID` (today `"vocalinux"` in `src/vocalinux/ui/tray_indicator.py`) all use the new name. - **Desktop file and autostart.** `vocalinux.desktop` becomes `voculinux.desktop` with `Exec=voculinux` and `Icon=voculinux`; the autostart filename constant and the `shutil.which("vocalinux")` lookup in `src/vocalinux/ui/autostart_manager.py` move to the new name. - **XDG directories and files.** The single `APP_DIR_NAME` constant in `src/vocalinux/utils/paths.py` (today `"vocalinux"`) becomes `"voculinux"`, which moves config (`~/.config/voculinux/config.json`), data (`~/.local/share/voculinux/`, including `instance.lock`, transcription history, and logs), cache, and the IBus data dir together. The install-state log dir under `~/.local/state/vocalinux` in `install.sh` moves the same way. - **D-Bus identity.** Bus name, object path, and interface move from `com.vocalinux.Vocalinux` / `/com/vocalinux/Vocalinux` to `com.voculinux.Voculinux` / `/com/voculinux/Voculinux` (today in `src/vocalinux/dbus_service.py`, with the matching `gdbus` example string in `src/vocalinux/ui/keyboard_backends/__init__.py`). No compatibility alias for the old name: this is a hard fork, and the niri keybinds already decided elsewhere will target the new name. - **IBus engine.** Engine name, component `textdomain`, and install/data paths move from `vocalinux` to `voculinux` (today `ENGINE_NAME`, `VOCALINUX_IBUS_DIR`, and the component dict in `src/vocalinux/text_injection/ibus_engine.py`). - **System install paths.** Packaged model/resource/icon lookup prefixes move from `/usr[/local]/share|lib|lib64/vocalinux/...` to the same trees under `voculinux` (today hardcoded in `recognition_manager.py`, `settings_dialog.py`, and `utils/resource_manager.py`), as do the tray icon names (`voculinux-microphone*`) and the `User-Agent` string. - **xbps package.** The package is named `voculinux`, owning the renamed system paths above, consistent with the already-decided dual-track packaging route. - **Website.** The marketing site rebrands from Vocalinux/vocalinux.com to Voculinux as part of this effort (the map Destination already places the web rebrand here, not later). ### What deliberately stays `vocalinux` - **The Python import package** (`src/vocalinux/...`, `from vocalinux...`, `python -m vocalinux.main`, the setuptools `packages` list). Renaming it would churn every module, test, the IBus/engine process matching in `install.sh`, and every future hand cherry-pick from upstream, for zero runtime benefit. The distribution/binary rename is user-visible; the import name is internal. This also resolves the map's open fog patch about whether the Python package renames: it does not, and the fork documents `vocalinux` as the retained internal module name. - **Upstream URLs and history** (`github.com/VocaHQ/vocalinux` references, changelog) stay as-is for provenance. ### One-time config import - On first run, when the new config directory has no `config.json` but the legacy `~/.config/vocalinux/config.json` exists, the app copies the legacy `config.json` and the legacy custom-dictionary file into the new directory and logs the import. The existing normalize/validate path in `config_manager.py` then loads the copy unchanged. - Rules: the new directory always wins once it exists (never merge, never write back to the legacy path, never re-import). Models, history, logs, and locks are not migrated — models re-resolve through the pinned-checksum download path. If no legacy config exists, the app starts from fresh defaults. ### Evidence inspected Repo `AGENTS.md` (hard limit: no invented features; smallest change matching existing patterns), the map Destination and Notes (fresh voculinux XDG dirs plus one-time vocalinux import; Destination names app, binary, package, and site), `src/vocalinux/utils/paths.py`, `src/vocalinux/dbus_service.py`, `src/vocalinux/single_instance.py`, `src/vocalinux/ui/config_manager.py` (imports `config_dir`), `src/vocalinux/ui/autostart_manager.py`, `src/vocalinux/ui/tray_indicator.py`, `src/vocalinux/text_injection/ibus_engine.py`, `vocalinux.desktop`, `pyproject.toml` (project name, scripts, packages), `install.sh` (process matching, state dir), and `web/PRODUCT.md` (site scope). No `GLOSSARY.md` or `docs/adr/` exists in the repo, so no glossary/ADR file change was made; the terminology (`Voculinux` app, `voculinux` binary/package/ids, `vocalinux` retained internal module plus legacy XDG source) lives in this comment. ### Consequences for later tickets - The Python performance baseline ticket is unaffected (same interpreter, same module layout). - xbps template work uses `voculinux` package/path names; niri keybind work targets the new D-Bus name. - Remaining rename-adjacent fog (portal first-run prompt UX, model catalog) is unchanged and stays in Not yet specified.

xavierk closed this issue

2026-11-05 16:11:09 +00:00

xavierk referenced this issue

2026-11-05 16:11:20 +00:00

Voculinux port #1

xavierk referenced this issue

2026-11-05 16:23:08 +00:00

Cherry-pick policy for upstream fixes #13

xavierk referenced this issue

2026-11-05 16:28:34 +00:00

Portal first-run prompt UX under niri #15

xavierk referenced this issue