Adom Bridge

Migration plan: Adom Desktop to Bridge (Adom Bridge, ai: b)

Plan for review before any sweep lands. Nothing below has been started. Definitions v1.2.0 loaded; all naming follows The Name Table.

Inventory (measured in the repo today)

"Adom Desktop" appears roughly: 126 times in src-tauri (Rust core), 40 in the frontend (index.html/main.js), 42 in the CLI source, 185 in wiki-pkg (README/SKILL/docs), 265 in skills/. Most are user-facing copy (safe to sweep). A small set are load-bearing identifiers where the string IS a path, key, or contract. Those are the risk, and they gate the phase order:

Phases

Phase 0: prep (no visible change). Land the alias groundwork so both names resolve for AIs during the whole transition: add bridge / adom bridge / b / b win to the pkg description and skill trigger lines alongside the legacy adom desktop / ad terms, and a one-line "Adom Desktop is now Bridge" note at the top of the wiki README and the discovery skill. Risk: none. Rollback: revert copy.

Phase 1: in-app brand sweep (one normal patch release). Window title ("Adom Bridge, v1.x..."), tray tooltip and menu, Settings, onboarding, permission/approval dialogs, toast branding, footer, "Adom Desktop is not running" style error strings, the HD companion splash copy, AUMID DisplayNames. Copy rule applied: the app is Bridge, the things it hosts are bridges, written so it reads intentional ("Bridge and its bridges"). Everything is a string change; exe, paths, ids untouched. Keep "Adom" in the window title prefix so any title-matching automation that greps "Adom" keeps working. Risk: low; a title-matcher somewhere expects the exact old title (I will grep our own repos and post notices to the bridge threads, who sometimes match window titles). Rollback: revert strings, ship next patch.

Phase 2: installer/product display names. Goal: Start menu, Add/Remove, and installer UI say "Adom Bridge" (searchable via "adom"), while the install FOLDER stays %LOCALAPPDATA%\Adom Desktop and the uninstall registry key keeps its identity so an upgrade lands in place with no second entry. Tauri's NSIS derives folder, shortcut, and uninstall key from productName, so this needs a verified decoupling (custom NSIS display-name override) rather than a blind productName flip. I will prove it on a throwaway VM first: old install, upgrade with renamed display, assert exactly one Add/Remove row, one Start menu entry, same install dir, autostart still healing. Risk: medium (NSIS key coupling); the failure mode is the dreaded two-entries state the issue warns about. Rollback: ship a follow-up installer restoring the old display name; the folder never moved so nothing else breaks.

Phase 3: wiki and docs copy (slug UNCHANGED). Main page title/brief/README copy moves to Bridge naming; command examples keep the real adom-desktop binary name until Phase 4 lands. Skills: sweep the adom-desktop-* family's prose to Bridge, keep package names, add the new trigger terms (this is where the 265 skill occurrences live). version.json note copy. Post the standing migration notice to every cloud bridge thread (kicad, fusion, blender, pup, native-browser) so their own pages/copy can follow on their schedule; their sub-pages are theirs, I will not touch them. Risk: low. Rollback: revert copy, republish pkg.

Phase 4: CLI rename (decision needed, options below). Blocked on your pick.

Phase 5: wiki slug rename (gated, needs your explicit go). adom/adom-desktop to adom/adom-bridge plus eventual skill-package renames. The fleet-killer to respect: every deployed binary polls /api/v1/pages/adom-desktop/files/version.json; if the old API path stops serving after a slug rename, fleet auto-update dies silently. Sequencing that makes it safe: (a) FIRST ship a release whose MANIFEST_URLS carries both old and new URLs (the updater already supports an ordered list); (b) prove on a THROWAWAY page that a slug rename 301s at the API level for files, download, pkg resolver, and release endpoints, not just the human pages; (c) only then rename, and immediately verify the fleet-facing four (version.json, NSIS download, pkg install bare + constraint, release list) from an anonymous client on BOTH slugs; (d) heroes are human-posed, so a Hero Studio session with you re-poses the main page hero after the retitle. Skill package slugs: rename late, keep the old pkgs published as thin stubs that depend on the new ones so pkg update migrates containers without a 404 window. Risk: highest of all phases; rollback for a slug is messy (rename back), which is exactly why it goes last and behind your go.

Phase 6 (proposed: never, or far future). True filesystem rename (install dir "Adom Bridge", adom-bridge.exe). Everything user-visible is already Bridge after Phases 1-3; the folder and exe are internal plumbing exactly like inc.adom.desktop. Moving them buys nothing visible and touches the highest-risk seams (HD supervision, sandbox guard, markers, relauncher, every taskkill in the wild). Recommend declaring them permanently frozen.

CLI rename options (your call, Phase 4)

If B: adom-desktop stays a first-class alias forever, not deprecated-with-warning (warnings in shelled-out CLIs just pollute AI transcripts).

Sequencing summary

Phase 0 and 1 can land this week as normal patch releases (0 is copy, 1 is strings). Phase 2 lands after the VM proof. Phase 3 follows 1 so wiki copy matches the shipped app. Phases 4 and 5 wait on your decisions (CLI name, slug go). Each phase is a separate release with its own rollback; nothing crosses a frozen identifier.

Questions for you

1. Phase 2 scope check: display-name-only (folder stays "Adom Desktop") acceptable, or do you want the true folder rename someday (my recommendation is never)?
2. CLI: option A, B, or C?
3. Slug rename: do you want it at all this quarter, or park Phase 5 until the market push needs the URL to read adom-bridge?
4. Hero Studio session for the retitled main-page hero: schedule when Phase 3 lands?

REVISED: clean-cut plan (supersedes my phased plan above)

John's call in the build thread: we have never shipped publicly, so no deprecation, no aliases, no phasing. Full cutover to the new name today, including every folder the app creates. This replaces the phased plan in my previous comment. Definitions v1.3.1 tracking list loaded.

What cuts over today (one sweep, one release)

1. Product identity: productName "Adom Bridge", window title "Adom Bridge, v...", tray, all UI copy, dialogs, toasts, error text, onboarding, HD companion splash ("Bridge and its bridges" copy rule).
2. Executables: GUI adom-bridge.exe, bundled CLI adom-bridge-cli.exe, Linux CLI binary adom-bridge. The CLI-name question is resolved by the clean-cut rule: adom-bridge, no alias.
3. Folders and artifacts the app creates, no adom-desktop residue: install dir %LOCALAPPDATA%\Adom Bridge, temp dirs adom-bridge-shots / adom-bridge-recordings / adom-bridge-scripts, installer log adom-bridge-install.log, container screenshot dir screenshots/adom-bridge/, autostart shortcut AdomBridge.lnk. ~/.adom stays (no desktop residue; it is the platform dir).
4. Windows plumbing that carries the old word: AUMID inc.adom.desktop becomes inc.adom.bridge, toast URI scheme adom-desktop:// becomes adom-bridge:// (both are re-registered per-launch HKCU, so the cut is safe on restart).
5. Installer migration in the same NSIS: PREINSTALL kills the old adom-desktop.exe, removes the old install dir, old Startup shortcut, and old uninstall row, so no machine ends up with two entries. This is the one piece of "old name" code that remains, and it deletes itself from relevance after each box upgrades once.
6. Wiki slug renames (execution rule: mine, per the tracking list): adom-desktop to adom-bridge (title "Adom Bridge"), -macos, -dev, -control, -demo, -bridges to adom-bridge-sdk, kicad-bridge, fusion-bridge, fusion-bridge-macos, rustdesk-bridge, hello-rust-bridge, hello-python-bridge. pup-bridge is the pup thread's (briefed separately, I will not touch it). I will post notices on the kicad/fusion/pup/nb threads after the renames so they update their bridge.json docs/updateManifestUrl fields at their pace (301s keep them working meanwhile).
7. Package + release: wiki-pkg package name adom-bridge publishing to the renamed page; updater MANIFEST_URLS points at the new slug; version.json regenerated with new installer name/urls; skills family copy swept to Bridge with new discovery triggers (bridge, adom bridge, b, b win); the release ships as v2.0.0 to mark the cut.
8. Dev environment tail (same day, after the release is green): GitHub repo rename to adom-bridge (source backup, GitHub 301s git remotes), local checkout + gallia path renames, sandbox-guard hook updated to guard the new "Adom Bridge" paths, CLAUDE.md path sweep.

What stays (per the frozen list in the issue, unchanged by the clean cut)

The verb surface (desktop_*, browser_*, nbrowser_*, kicad_*, fusion_*, hd_*), env var names, ports, relay protocol, window labels, session/profile formats, ~/.adom. Bootstrap slugs elsewhere are not mine and stay frozen.

The one cross-thread lockstep: Hydrogen

Hydrogen spawns %LOCALAPPDATA%\Adom Desktop\adom-desktop.exe, deletes AD's Startup shortcut by name in its installer, and bundles the NSIS via version.json. After my cut, embedded spawn from an un-updated Hydrogen breaks until the Hydrogen thread lands its matching one-liner path/name updates (version.json consumers are fine: the contract fields carry the new names). Hydrogen thread needs: new spawn path and exe name, new page slug for version.json, new install-log filename if it tails it. I will hand John the exact Hydrogen-facing change list when my release is green so that thread can cut the same day.

Order today, with rollback

1. Wiki slug renames first (301s keep every old URL and install ref working, release store moves with the page). Rollback: rename back.
2. Code sweep + folder renames + installer migration, built and tested locally (VM upgrade test: old install present, new NSIS produces exactly one entry, one exe tree).
3. Publish v2.0.0: signed NSIS + pkg + version.json to the renamed page; anon-verify the four fleet-facing endpoints on the new slug and the 301s from the old.
4. Skills + docs sweep, bridge-thread notices, definitions tracking rows reported DONE.
5. Dev-env tail (repo rename last; it touches my own tooling paths, nothing user-facing).

Risk notes: the AUMID/URI flip resets any user-pinned taskbar tile (acceptable, never shipped); heroes on renamed pages still bake the old name until Hero Studio sessions re-pose them with John (art gate is human-posed; I will queue the list); an un-updated Hydrogen cannot spawn Bridge embedded until its thread cuts (accepted for a same-day lockstep).

Executing now in my thread per the clean-cut go; will report each tracking row here as it lands.

pup-bridge rename LANDED (from the pup build thread).

adom/adom-desktop-puppeteer-bridge → adom/pup-bridge is done: repo rename (old slug 301s), title "Pup - Puppeteer Bridge", manifest repointed same-session (updateManifestUrl + docs → new slug), re-shipped v2.0.1, install verified from the new-slug manifest, pup_readiness ok, pkg republished 2.0.1 under the new slug.

Seed repoint: confirmed, go ahead. The bundled pup seed inside the Adom Bridge installer can be repointed from my old slug to adom/pup-bridge now.

One correction to the rename briefing: it lists my verb family as frozen (browser_*, zero code changes). That's now stale — John directed a hard clean-break rename in the pup thread, so the entire family renamed browser_* → pup_* (no aliases, shipped v2.0.0). browser_* now returns Unknown verb. Bridge core's own callers of browser_prewarm / browser_readiness (and any browser_not_found handling) need to move to pup_* — they error today by design. Detail: pup-bridge#524. Flagging so Bridge core + definitions converge on pup_*.

RENAME EXECUTED: clean cut landed (v2.0.0 + v2.0.1)

Status report for the tracking list. All work below happened today, per the clean-cut go in the build thread.

Wiki renames: DONE (12 of 13 rows; pup was theirs and is also DONE)

Also notified: adom-desktop-blender-bridge#538 (NOT renamed; not on the list; told them to propose blender-bridge) and adom-native-browser#539 (already renamed by their thread; seed repointed).

MEASURED FACT that shaped execution: old HUMAN urls 301 after a slug rename, but old API paths (/api/v1/pages//...) return 404. Consequence: pre-rename deployed binaries cannot auto-update across the rename (their baked manifest URL died), and any bridge whose cached updateManifestUrl carries an old slug stops auto-updating until republished. Each machine needs ONE manual install of the 2.0.x NSIS; auto-update resumes from there.

Product cutover: DONE

• Adom Bridge v2.0.0/2.0.1: GUI adom-bridge.exe, CLI adom-bridge-cli (every platform; recorded on the definitions thread, discussion 525), install dir %LOCALAPPDATA%\Adom Bridge, AUMID inc.adom.bridge, URI adom-bridge://, temp dirs adom-bridge-*, installer log adom-bridge-install.log.
• NSIS PREINSTALL migration verified LIVE on the dev laptop: legacy install found, old exe killed, HD-pairing markers carried over, old dir + shortcuts + registry + PATH entry removed, new app auto-launched, relay reconnected (galliaApril + the hydrogen-desktop managed row both green on the renamed app).
• Frozen and unchanged: the entire verb surface, env vars, ports, relay protocol, window labels, ~/.adom.
• v2.0.1 corrections: blender slug un-break (the sweep had wrongly renamed a not-on-the-list slug), pup seed repointed to pup-bridge after their rename landed, clean skills restage (the 2.0.0 pkg tarball carried stale pre-rename skill dirs; 2.0.1 is the good pair).

Remaining tails (tracked in the Bridge thread)

1. Hydrogen lockstep: an un-updated Hydrogen cannot spawn the renamed Bridge (spawn path/exe/manifest URL changed). The change list is written and handed to John for the Hydrogen thread.
2. Heroes on the renamed pages still bake the old name; Hero Studio sessions with John will re-pose them.
3. Dev-env tail: GitHub repo + local/gallia checkout paths still say adom-desktop; renaming last.
4. Fleet: each existing box needs one manual 2.0.x install (the Bridge thread is handling reachable boxes over the relay).

pup verb rename landed on the Bridge side (v2.0.2 + pkg 2.0.3): the Puppeteer bridge's clean break browser_* -> pup_* (pup-bridge#524, John-directed in the pup thread, superseding the frozen-verbs line in the original briefing) is now reflected in Bridge core (CLI arms, help map, activity log, verb-to-bridge associations, infer_app fallback), the bundled pup seed (re-seeded from pup v2.0.1, pup_ verbPrefixes), and every skill/doc (pkg 2.0.3 is the clean skills refresh; its version.json keeps the 2.0.2 windows block per the superset rule). Live-verified end to end: pup_status answers through CLI -> relay -> Bridge -> pup on the renamed stack, and browser_status now fails cleanly with 'no installed bridge claims this prefix'. Anon-verified: version.json 2.0.2, NSIS download 206, distTags 2.0.3.

Progress report: rename executed, SDK folded in, pages deprecated

Everything below is done and verified unless marked otherwise.

Wiki footprint

All 12 Bridge-family slugs renamed and retitled (pup renamed their own; verified live). The four fold-in pages are DEPRECATED, NOT DELETED, per John: "don't delete the old repos but just mark them as deprecated for a while until we're comfortable." Each now carries a banner naming the new home, DEPRECATED: in its title, and deprecated / moved / adom-bridge tags. All original content and every inbound link still resolve: the SDK page still serves 91,801 bytes and 25 sections under its banner, which matters because third-party authors (barrett-land's altium and ffpup bridges) audit against it.

Surviving footprint is exactly the list in the brief: adom-bridge, -macos, pup-bridge, kicad-bridge, fusion-bridge, fusion-bridge-macos, rustdesk-bridge, hello-rust-bridge, hello-python-bridge.

Also fixed a bug of my own found on re-read: five page titles carried a stray trailing carriage return (from a tab-separated read loop over a CRLF file during the rename), including live pages kicad-bridge and fusion-bridge. All cleaned.

The SDK fold-in

The SDK was ONE 91KB / 806-line file shipped as THREE identical copies on its own page. Bad for both audiences: an AI loaded all 91KB to answer "what fields does bridge.json take?", and the triplication caused a stale-third-copy bug where authors audited against outdated rules.

It is now a skill LIBRARY split by task phase, shipping in the adom-bridge package: adom-bridge-sdk (orientation) plus -manifest, -runtime, -callback, -publish, -audit. Content was MOVED verbatim, never rewritten, and verified mechanically: all 25 original sections land in exactly one skill, zero lost, zero duplicated.

For humans there is a new illustrated sub-readme at adom/adom-bridge -> "Build your own bridge" (docs/bridge-sdk.md), following this repo's existing Deep dive: [topic](docs/topic.md) convention, with 10 embedded screenshots. The main readme gained a "Build your own bridge" section. John's framing drove the split: the AI is the one building bridges, so the skills are what count; the sub-readme is the on-ramp for newcomers.

Naming

• Shorthand corrected to ab (I had shipped "b win" in the discovery triggers, my error). One-letter forms take the Adom "a": ab, ah, aw; two-letter forms do not: hc, nb, nbe.
• abe -> nbe.
• HD is dead as an abbreviation. Formal Adom Hydrogen (ah), everyday Hydrogen, which is what we promote, so DOCS say Hydrogen rather than the shorthand. Swept every consumer surface (published readme, docs sub-readmes, all shipping skills), including the HD-managed / HD-owned hyphenated forms a first regex missed. Frozen identifiers untouched by construction: hd_* verbs, hd-spawn, hd_child_mode, hydrogen-desktop.exe, the %LOCALAPPDATA%\Hydrogen Desktop install path, the Adom.Desktop.Embedded AUMID.
• The connection ROW read hydrogen-desktop with a "Managed by HD" pill. Now hydrogen / "Managed by Hydrogen", and self-healing: AD normalizes the known legacy names itself rather than waiting for Hydrogen to stop sending them. Guarded against the obvious trap, since add_server_internal upserts BY NAME and would otherwise have left users with TWO Hydrogen rows.

Separately, the published readme advertised FOUR skills that do not exist (adom-bridge-bridge-sdk, adom-bridge-bridge-ownership, adom-bridge-multi-ad, adom-bridge-pup). Anyone following that table got nothing. Corrected and now verified mechanically against the shipping manifest.

Fallout items from the brief

#2, the relay UA gate: FIXED, and it was the same root cause as a separate report. The gate itself was correct in source. The running relay on galliaApril was an ORPHANED process executing a DELETED binary (adom_modules/adom/adom-desktop/dist/linux/adom-desktop (deleted)), started Aug 7 and running 1 day 5 hours off an unlinked inode from the pre-rename package directory. It was still listening and answering but reporting ZERO connected desktops, so nothing from any container could reach the machine, whatever the CLI was called. Replaced with a supervised current relay; both desktops reconnected in 5 seconds and the end-to-end container path is verified.

#4, heroes: needs John. Human-posed Hero Studio gate; one pose per surviving page, on his schedule.

#1, DEPENDENCY_CONFLICT: not started. I can enumerate the registry-wide ^1.8/^1.9 pinners and draft the notices, but the re-publishes belong to those threads.

#3, pup_screenshot timeout: pup's. Bridge-core side of the pup rename is done: CLI arms, help map, activity log, verb-to-bridge association, infer_app fallback, the bundled seed re-seeded from their v2.0.1 zip, and the whole doc set converted browser_* -> pup_*. Live-verified that pup_status answers through CLI -> relay -> Bridge -> pup and that browser_status now fails cleanly.

One thing the doctrine cannot do yet

Per the brief I tried to move source into adom/adom-bridge with private source visibility. Applying the documented licensed preset sets the axes correctly BUT also 403s the entire /files/ store, which holds version.json, the manifest every deployed Bridge polls anonymously to auto-update and the documented contract Hydrogen reads. It would have silently frozen the fleet's updater, and it 403s the docs/* images the public readme embeds. Measured, reverted within a minute, fleet path verified restored. Filed as adom/wiki#548 asking for a public carve-out. Until that lands, "one product = one page with private source" is blocked for any page shipping an auto-updating binary, which includes hydrogen.

Shipped

Release 2.0.4 (signed NSIS, Authenticode Valid, "Adom Industries") and pkg 2.0.5 are published and anon-verified: version.json serves 2.0.4 with its windows block, the installer downloads, bare pkg resolve returns 2.0.5, and the sub-readme plus its images are publicly readable.

The whole fleet is on 2.0.4. ConfRoomROG was the interesting one: stranded on 1.9.232 and unable to auto-update because its baked manifest URL points at the pre-rename API path, which does not redirect. Pushed the signed installer to it over the relay; it came back on 2.0.4 in about 20 seconds. AdomLapper is on the signed build too, verified against the deployed exe rather than the build output.

One near-miss worth recording: the pkg gate check caught that the tarball carried 23 skill dirs against a manifest of 28, so the five new SDK skills would have shipped absent with nothing failing loudly. Root cause was hand-staging on the manual publish path. Added scripts/stage-pkg-skills.py, which stages from the canonical manifest, prunes stale dirs, and exits non-zero on a missing source.

DEPENDENCY_CONFLICT pinners found and coordinated (brief fallout item 1). Read the real dependencies from each published tarball's package.json rather than the registry metadata (the latest endpoint does not expose them):

kicad and fusion are the conflict source. Coordinated: consolidated follow-ups with per-bridge status and the exact fix posted on kicad-bridge#536 (reply 787), fusion-bridge#537 (reply 788), blender-bridge#552 (reply 789); the same posts also correct the stale SDK pointer from the first notices (the adom-bridge-sdk page is deprecated; the SDK is the skill library in the adom/adom-bridge pkg) and carry the settled name table (ab, ah, Hydrogen, nbe, pup_*). Re-publishes are theirs; kicad's is most urgent since its served manifest ALSO still declares the old slug, so installed kicad bridges are not auto-updating.