Definitions

@@ -8,9 +8,9 @@ Canonical glossary of Adom platform terms. Use these definitions consistently in |------|-----------| | **Adom** | The platform and company. Never surface internal codenames to users. | | **The wiki** / **adom-wiki** (short: **aw**) | One product, two faces: the site (https://wiki.adom.inc — the shared electronics wiki for the AI age: apps, skills, components, bootstraps, packages; THE distribution channel for everything Adom) and its CLI (`adom-wiki`). "The wiki", "adom-wiki", and "aw" all refer to it — context says whether you mean the site or the CLI. |-| **Hydrogen Web (HW)** (casual: **hw**) | The web app at hydrogen.adom.inc: toolbar, panels, VS Code, profile — the browser twin of Hydrogen Desktop. Parallel naming: hw (web) and hd (desktop) are the two faces of Hydrogen. ("Adom App" and "Workspace" are NOT names for this product.) |-| **Workspace** | The persistent environment your work lives in — panels layout, files, tooling. hw attaches to a cloud workspace (Docker container); hd runs a local one (the WSL2 `Adom-Workspace` distro / Lima). |-| **Hydrogen Desktop (HD)** (casual: **hd**) | The Windows/macOS desktop app — the flagship, publicly released face of Hydrogen. Runs the workspace locally and bundles AD. Sibling of hw. HD-specific terms: see the Hydrogen Desktop section below. |+| **Hydrogen Web (HW)** (casual: **hw**) | The web app at hydrogen.adom.inc: toolbar, panels, VS Code, profile — the browser twin of Hydrogen Desktop. Parallel naming: hw (web) and hd (desktop) are the two faces of Hydrogen. ("Adom App" and "Workspace" are NOT Adom terms.) |+| **Container** | The persistent environment your work lives in — files, tooling, panels layout. Specify with the product: an **hw container** (cloud Docker) or an **hd container** (local: the WSL2 `Adom-Workspace` distro on Windows, Lima on macOS). We say "container", NOT "workspace" — the word workspace survives only inside frozen identifiers (`Adom-Workspace`, `adom-cli hydrogen workspace …`, adom-workspace-control). |+| **Hydrogen Desktop (HD)** (casual: **hd**) | The Windows/macOS desktop app — the flagship, publicly released face of Hydrogen. Runs its container locally and bundles AD. Sibling of hw. HD-specific terms: see the Hydrogen Desktop section below. | | **Adom Desktop (AD)** | The desktop bridge/relay: gives AIs hands on the user's real machine — shell, files, screenshots, KiCad/Fusion bridges, pup, the browser extension, window control. CLI surface: `adom-desktop <verb>`. Everyday short form: **AD** / "ad" ("is ad running?", "ask ad", "ad is back") — when a user says "ad" they mean this bridge. | | **abe** | The Adom browser extension — lets the AI drive the user's REAL signed-in Chrome/Edge (`nbrowser_*` verbs): logged-in sites, real credentials, human trust. | | **Panel** | A rectangular area of the Hydrogen layout (hw or hd) — VS Code, webview, 3D viewer, cameras, sensors. Panels split, resize, move, close; each has a tab with name + icon. |@@ -19,7 +19,7 @@ Canonical glossary of Adom platform terms. Use these definitions consistently in  | Term | Definition | |------|-----------|-| **webview** (short: **wv**) | THE workhorse display surface: a native Adom workspace webview tab — a first-class panel next to the editor. ONE word, always ("Web View" is not an Adom term); on every platform "show me in webview"/"wv" means THIS, never VS Code's Simple Browser. Open idempotently: `adom-cli hydrogen webview open-or-refresh --name "<Tab>" --url "<URL>" --panel-id <id>` (re-running with the same `--name` just navigates — a stable handle). THE PLATFORM TRAP is the URL: in a CLOUD container the tab renders in the user's browser, so `localhost` is WRONG — use the slug proxy URL (`https://{slug}.adom.cloud/proxy/{port}/`); under HD the tab renders on the same machine, so `http://localhost:{port}` is correct. Verify the tab exists (`adom-cli hydrogen workspace tabs`) before claiming it opened. |+| **webview** (short: **wv**) | THE workhorse display surface: a native Hydrogen webview tab — a first-class panel next to the editor. ONE word, always ("Web View" is not an Adom term); on every platform "show me in webview"/"wv" means THIS, never VS Code's Simple Browser. Open idempotently: `adom-cli hydrogen webview open-or-refresh --name "<Tab>" --url "<URL>" --panel-id <id>` (re-running with the same `--name` just navigates — a stable handle). THE PLATFORM TRAP is the URL: in a CLOUD container the tab renders in the user's browser, so `localhost` is WRONG — use the slug proxy URL (`https://{slug}.adom.cloud/proxy/{port}/`); under HD the tab renders on the same machine, so `http://localhost:{port}` is correct. Verify the tab exists (`adom-cli hydrogen workspace tabs`) before claiming it opened. | | **pup** | The AI's own Chrome on the user's desktop (Puppeteer bridge via AD, `browser_*` verbs). A real, full browser window the AI fully controls: sessions (`sessionId` is the handle — task-prefix it and set `owner` so threads never steal each other's windows), many TABS in one window (preferred over window sprawl), screenshots, JS eval, taskbar flash. Opens BACKGROUND by default — `foreground:true` is the only thing that raises it; signal with a flash instead of stealing focus. Cold profiles = LOGGED OUT by design: the safe automation surface (fresh-user testing, scraping public pages, showing wiki pages). For logged-in sites use nb instead. Windows never auto-close — clean up when a task ends. Always lowercase. | | **native browser** (short: **nb**) | The user's own signed-in Chrome/Edge, driven via abe (`nbrowser_*`). For logged-in sites. "Show it in nb" == open in the user's real browser. | | **nb addressing** | `nb [browser] [profile]` names a specific browser/profile: "nb chrome", "nb edge", "nb chrome work", "nb chrome personal". Maps to the Browser Picker's native destination ids (`browser:<browser>:<profileDir>`) and the profiles abe reports. The AI resolves the profile from the user's words + `GET /browser-profiles`. |@@ -32,10 +32,10 @@ Canonical glossary of Adom platform terms. Use these definitions consistently in | Term | Definition | |------|-----------| | **Skill** | A Markdown document (SKILL.md) that teaches the AI a specialized task. Installed flat at `~/.claude/skills/<name>/`. |-| **Registry-native distribution** | THE update model: everything is an `adom-wiki` package. An app's skill rides its own package; platform-layer skills are bundled inside the bootstraps. `adom-wiki pkg update` (run automatically by the hook) converges every workspace. There is no separate updater daemon and no skills-only package. |-| **Bootstrap** | A meta-package whose dependency tree converges a machine to a role, installed with one line (`adom-wiki pkg install adom/<bootstrap>`). Layers: `adom/core` (every workspace) → `adom/hd-bootstrap` (platform-generic HD + shared hd-* skills) → `adom/hd-windows-bootstrap` (WSL2 layer) / `adom/hd-mac-bootstrap` (Kyle's macOS layer). Each layer bundles ITS OWN skills. |-| **The hook** | `adom/hook` — the background auto-updater installed by core: runs `adom-wiki pkg update` (throttled ~30 min, on user prompts) so tooling and skills stay current fleet-wide. |-| **Skill tiers** | `skills/` (user skills — ship in the install tarball), `dev-skills/` (build/debug — source repo only), `publish-skills/` (app→wiki publishing — source repo only). Only user skills reach installed workspaces. |+| **Registry-native distribution** | THE update model: everything is an `adom-wiki` package. An app's skill rides its own package; platform-layer skills are bundled inside the bootstraps. `adom-wiki pkg update` (run automatically by the hook) converges every container. There is no separate updater daemon and no skills-only package. |+| **Bootstrap** | A meta-package whose dependency tree converges a machine to a role, installed with one line (`adom-wiki pkg install adom/<bootstrap>`). Layers: `adom/core` (every container) → `adom/hd-bootstrap` (platform-generic HD + shared hd-* skills) → `adom/hd-windows-bootstrap` (WSL2 layer) / `adom/hd-mac-bootstrap` (Kyle's macOS layer). Each layer bundles ITS OWN skills. |+| **The hook** | `adom/hook` — the background auto-updater installed by core: runs `adom-wiki pkg update` (throttled ~30 min, on user prompts) so tooling and skills stay current in every container fleet-wide. |+| **Skill tiers** | `skills/` (user skills — ship in the install tarball), `dev-skills/` (build/debug — source repo only), `publish-skills/` (app→wiki publishing — source repo only). Only user skills reach installed containers. | | **Discovery metadata** | `discovery_triggers` / `discovery_pitch` / `sample_prompts` in a package manifest — how AIs find and auto-install a tool. Required for apps/skills. |  ## The Wiki (two layers — not synced)@@ -51,7 +51,7 @@ Canonical glossary of Adom platform terms. Use these definitions consistently in  | Term | Definition | |------|-----------|-| **adom-cli** | Platform CLI — containers, repos, workspaces, orgs, SSH keys, Hydrogen control (`adom-cli hydrogen …` drives panels/webviews). |+| **adom-cli** | Platform CLI — containers, repos, orgs, SSH keys, Hydrogen control (`adom-cli hydrogen …` drives panels/webviews). | | **adom-wiki** (short: **aw**) | The wiki's CLI — pkg publish/install/update, page repos, releases, issues, PRs. Same product as "the wiki" above; aw covers both. (`adompkg` is dead; never use it.) | | **pkg** | Bare "pkg" means `adom-wiki pkg` — "pkg install it", "pkg update", "did you pkg publish?" all refer to the wiki package manager. | | **adom-desktop** | AD's verb surface from any container — shell, files, screenshots, bridges, pup (`browser_*`), windows (`desktop_*`), HD control (`hd_*`). |@@ -103,7 +103,7 @@ Canonical glossary of Adom platform terms. Use these definitions consistently in  | Term | Definition | |------|-----------|-| **Golden image** | The pre-baked workspace rootfs (`adom-golden-vN.tar.gz`) HD imports on first run — code-server, the Adom CLIs, extensions, settings, and all bundled skills, pre-converged via one `pkg install` of the platform bootstrap at bake time. The bake is an optimization of the runtime flow, not a different mechanism. |+| **Golden image** | The pre-baked hd-container rootfs (`adom-golden-vN.tar.gz`) HD imports on first run — code-server, the Adom CLIs, extensions, settings, and all bundled skills, pre-converged via one `pkg install` of the platform bootstrap at bake time. The bake is an optimization of the runtime flow, not a different mechanism. | | **Setup cascade** | HD's gated first-run steps (currently 27): import the golden image, inject identity, wire the relay, install the `claude` CLI (the one runtime install), walk Claude auth, then open the welcome + named AI-thread conversations. Every step is a hard gate — it verifies its artifact or halts. | | **Virgin reset** | Wiping the workspace back to first-run through HD's own visible reset panel (never out-of-band). Rebuilds from the golden image. | | **ESM** | The Editor State Machine — HD's authoritative editor-state read (`GET /editor/state`): lifecycle, layout/bars, tab census, disk-backed conversation truth, and the typing cardinality gates (exactly one compose box, stray audits, disk-verified delivery). |@@ -123,7 +123,7 @@ Canonical glossary of Adom platform terms. Use these definitions consistently in |------|--------| | **webview is one word** | Never "Web View". Short form: wv. | | **lowercase tools** | pup, shotlog, abe, wv, nb, hdbw, ad, hd, hw, aw, cf — always lowercase in casual prose (AD/HD/HW in formal docs). |-| **VS Code** | The IDE inside the workspace (powered by code-server). Never call it "the editor" — the Editor is Hydrogen (hw/hd) around it. Avoid "code-server"/"Coder" in user-facing text. |+| **VS Code** | The IDE inside the container (powered by code-server). Never call it "the editor" — the Editor is Hydrogen (hw/hd) around it. Avoid "code-server"/"Coder" in user-facing text. | | **No internal codenames to users** | "Carbon" (the backend registry) is internal — code/URLs only. "Hydrogen" is PUBLIC brand (Hydrogen Web / Hydrogen Desktop). |  ## Coordinate System