Definitions

@@ -1,102 +1,97 @@ # Adom Definitions -Canonical glossary of Adom platform terms. Use these definitions consistently in conversation, code, documentation, and wiki content.+Canonical glossary of Adom platform terms. Use these definitions consistently in conversation, code, documentation, and wiki content. If a term isn't here, propose it — this page is the vocabulary every Adom AI and human shares.  ## Core Platform  | Term | Definition | |------|-----------| | **Adom** | The platform and company. Never surface internal codenames to users. |-| **Adom App** (aka **Workspace**) | The full web app: toolbar, panels, VS Code, profile, workcell picker. Internal codename "Hydrogen". "Workspace" emphasizes the persistent panel layout (cloud: Docker container; under Hydrogen Desktop: the WSL2 `Adom-Workspace` distro). |-| **Hydrogen Desktop (HD)** | The Windows/macOS desktop app — the flagship Adom experience. Runs the workspace LOCALLY (Windows: the WSL2 `Adom-Workspace` distro; macOS: Lima). Bundles Adom Desktop. Ships as a signed installer; a 27-step first-run cascade sets up the workspace. |-| **Adom Desktop (AD)** | The desktop bridge app/relay: gives cloud AIs and HD hands on the user's real machine — shell, files, screenshots, KiCad/Fusion bridges, pup, the browser extension. CLI verb surface `adom-desktop <verb>`. |-| **Panel** | A rectangular area in the Adom App (Workspace) layout — like a window pane. Each panel has a tab with a name and icon. Panels can be split, resized, moved, and closed. Types include VS Code, webview, 3D Viewer, Schematic Editor, cameras, sensors, etc. |+| **The wiki** | https://wiki.adom.inc — the shared electronics wiki for the AI age: apps, skills, components, bootstraps, packages. THE distribution channel for everything Adom. Driven by the `adom-wiki` CLI. |+| **Adom App** (aka **Workspace**) | The full web app: toolbar, panels, VS Code, profile. Internal codename "Hydrogen". "Workspace" also names the persistent environment itself (cloud: a Docker container; under HD: the local WSL2 `Adom-Workspace` distro). |+| **Hydrogen Desktop (HD)** | The Windows/macOS desktop app — the flagship Adom experience. Runs the workspace LOCALLY (Windows: WSL2 `Adom-Workspace` distro; macOS: Lima). Bundles Adom Desktop. Signed installer; a 27-step first-run cascade builds the workspace from the golden image. |+| **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>`. |+| **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. |+| **Golden image** | The pre-baked workspace rootfs (`adom-golden-vN.tar.gz`) that HD imports on first run — code-server, the Adom CLIs, extensions, settings, and all bundled skills, pre-converged via one `adom-wiki 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. |+| **Panel** | A rectangular area of the Adom App layout — VS Code, webview, 3D viewer, cameras, sensors. Panels split, resize, move, close; each has a tab with name + icon. |  ## Display Surfaces (how the AI shows an app or page)  | Term | Definition | |------|-----------| | **webview** (short: **wv**) | A native Adom workspace webview tab, opened via `adom-cli hydrogen webview open-or-refresh`. ONE word, always — "Web View" as two words is not an Adom term. On every platform, "show me in webview"/"wv" means THIS — never VS Code's built-in Simple Browser. |-| **pup** | A clean, scriptable Chrome the AI fully owns (Puppeteer bridge, `browser_*` verbs, sessionIds/tabs, cold profiles). The logged-out, automation-safe surface. |-| **native browser** | The user's own signed-in Chrome/Edge, driven via the Adom browser extension (`nbrowser_*`). For logged-in sites — real credentials, human trust. |-| **hdbw** | HD Browser Window — Hydrogen Desktop's standalone built-in Tauri browser window (picker label "HD Browser Window", window label `hd-browse-*`, destination id `webview-window`). Open first-class via `POST /hdbw/open {url}` on HD's control API (0.1.115+). NOT a webview panel, NOT pup — its own surface, only under HD. (Renamed from the one-day short name "hdw" 2026-07-17: "hdw" invited webview/window conflation.) |-| **Simple Browser** | VS Code's built-in browser page. NEVER an Adom surface — using it to show an app is a bug on every platform. |+| **pup** | A clean, scriptable Chrome the AI fully owns (Puppeteer bridge via AD, `browser_*` verbs, sessionIds/tabs, cold profiles). The logged-out, automation-safe surface. Always lowercase. |+| **native browser** | The user's own signed-in Chrome/Edge, driven via abe (`nbrowser_*`). For logged-in sites. |+| **hdbw** | HD Browser Window — Hydrogen Desktop's standalone built-in Tauri browser window (picker label "HD Browser Window", window label `hd-browse-*`, destination id `webview-window`). Open first-class via `POST /hdbw/open {url}` on HD's control API. NOT a webview panel, NOT pup — its own surface, only under HD. |+| **Browser Picker** | HD's canonical URL router: every link opened inside HD goes through it. Offers the surfaces above + native profiles from abe, a fresh-window toggle, a 5s auto-countdown, and per-domain memory of the user's past choice (incl. localhost:port domains). |+| **Simple Browser** | VS Code's built-in browser page. NEVER an Adom surface — showing an app there is a bug on every platform. | -## Creators and Services+## Skills & Distribution  | Term | Definition | |------|-----------|-| **Creator** | A service or skill that generates artifacts (symbols, footprints, 3D models, schematics, boards). |-| **symbol-creator** | Service at port 8781 that generates .kicad_sym files, metadata, SVG, branded viewer HTML. |-| **footprint-creator** | Skill that generates .kicad_mod files and viewer HTML. |-| **fp-to-3d.js** | CLI script that generates Babylon.js 3D pad viewer HTML from .kicad_mod files. |-| **3dcomponent-creator** | Generates STEP/GLB 3D component models. |-| **library-creator** | Creates all three artifacts (symbol + footprint + 3D) and shows them in a webview. |+| **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. |+| **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)++| Term | Definition |+|------|-----------|+| **Package layer** | The install payload (manifest + scripts + bundled user skills), published with `adom-wiki pkg publish`. What `pkg install` delivers. |+| **Page repo layer** | The page's git repo (Files tab, README, hero assets), pushed with `adom-wiki repo push`. Publishing a package does NOT sync the page repo, and vice versa — update both. |+| **Hero** | The 16:10 billboard image + headline/subhead on a wiki page — reused on the page header, homepage, installer, and screensaver. Required to publish apps/skills. |+| **Release** | Per-platform binaries attached to a package version (`adom-wiki release upload`) — the "Download for your machine" buttons. |  ## CLI Tools  | Term | Definition | |------|-----------|-| **adom-cli** | Rust CLI for the Adom platform API — containers, repos, users, workspaces, SSH keys, orgs. Binary at `/usr/local/bin/adom-cli`. Repo: `adom-inc/adom-cli`. |-| **adom-vscode** | Rust CLI + VS Code extension for controlling code-server from Docker processes. Opens files, reveals in explorer, searches/installs extensions, starts Claude Code chats, switches UI modes. Extension runs HTTP server on port 8821. Binary at `/usr/local/bin/adom-vscode`. Repo: `adom-inc/adom-vscode`. |-| **shotlog** | Rust CLI + HTTP server for chronological screenshot logging. Supports multiple named channels, clipboard paste with auto-resize, real-time WebSocket updates. Server on port 8820. Binary at `/usr/local/bin/shotlog`. |-| **pup** | Puppeteer browser control via Adom Desktop (`adom-desktop browser_*` verbs): a clean, scriptable Chrome the AI fully owns — sessions, tabs, screenshots, JS eval, taskbar alerts. The logged-out automation surface (see Display Surfaces). Always lowercase. |+| **adom-cli** | Platform CLI — containers, repos, workspaces, orgs, SSH keys, Hydrogen control (`adom-cli hydrogen …` drives panels/webviews). |+| **adom-wiki** | THE wiki CLI — pkg publish/install/update, page repos, releases, issues, PRs. (`adompkg` is dead; never use it.) |+| **adom-desktop** | AD's verb surface from any container — shell, files, screenshots, bridges, pup (`browser_*`), windows (`desktop_*`), HD control (`hd_*`). |+| **adom-vscode** | CLI + VS Code extension controlling code-server (port 8821): open files, run editor commands, drive Claude Code panels. |+| **shotlog** | Screenshot log server + CLI (port 8820) — chronological, multi-channel, live viewers. How the AI SHOWS work. Always lowercase. |+| **claude** | The Claude Code CLI. The ONE tool installed at runtime by HD's cascade (its self-setup needs a live session) — everything else is baked or package-delivered. |+| **adom-google / adom-tts / adom-gchat** | Google Workspace access (as the user), shared TTS narration, and org chat posting, respectively. |++## AI-First Rules++| Term | Definition |+|------|-----------|+| **real-view** | Always show the ACTUAL running app/view — never a mockup, placeholder, or approximation. Applies to demos, screenshots, wiki pages, landing pages, everywhere. |+| **fake-view** | Any static SVG/HTML/screenshot that approximates a real app without running it. BANNED. If you're about to fake it, stop and run the real thing with sample data. |+| **AI-drivable** | Every Adom app exposes state + control to the AI (GET /state, GET /console, a live SSE/WebSocket channel, CLI verbs) so the AI can drive, verify, and ralph-test it. See the ai-driven-apps skill. |+| **Ralph loop** | The AI's visual QA loop: drive a step, screenshot, read, fix, repeat until the UI is right — no human in the loop. |+| **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). |  ## URLs  | URL Pattern | What it is | |-------------|-----------|-| `https://hydrogen.adom.inc/{owner}/{repo}` | **Repo page** — shows repo info, container status, README. Not the editor. |-| `https://hydrogen.adom.inc/{owner}/{repo}/edit` | **Editor** — the full Adom App (Workspace) with panels, VS Code, toolbar. This is what users open to work in their container. Always add `/edit` to get into the editor. |-| `https://hydrogen.adom.inc/{owner}/{repo}/tree/latest/{path}` | **File browser** — browse project files in the repo. |-| `https://hydrogen.adom.inc/{owner}/{repo}/blob/latest/{path}` | **File viewer** — view a single file in the repo. |-| `https://{slug}.adom.cloud/` | **Direct container URL** — raw VS Code in the browser, bypassing the Adom App (the slug is assigned by the platform, e.g. `john-myboard-8v0y…`). Proxied app ports: `https://{slug}.adom.cloud/proxy/{port}/`. |--**Key distinction:** `/{owner}/{repo}` is the repo page. `/{owner}/{repo}/edit` is the editor (Adom App / Workspace). Always use `/edit` when you want users to actually work in the container.+| `https://hydrogen.adom.inc/{owner}/{repo}` | Repo page (info, container status, README) — not the editor. |+| `https://hydrogen.adom.inc/{owner}/{repo}/edit` | The editor — the full Adom App. Always add `/edit` to work in a container. |+| `https://{slug}.adom.cloud/` | Direct container URL (raw VS Code). App ports proxy at `https://{slug}.adom.cloud/proxy/{port}/`. |+| `https://wiki.adom.inc/{org}/{page}` | A wiki page (Overview, Files, Skills, Packages, Releases, Issues tabs). | -## Infrastructure+## Naming & Brand Rules -| Term | Definition |-|------|-----------|-| **Skill** | A Markdown document (SKILL.md) that teaches the AI a specialized task. Distributed REGISTRY-NATIVE: skills ship inside wiki packages (an app's skill rides its package; platform-layer skills are bundled in the bootstraps, e.g. adom/hd-bootstrap) and install to `~/.claude/skills/<name>/`. Kept current by `adom-wiki pkg update` via the adom/hook. |-| **Conduit** | WebSocket bridge between containers or between container and desktop. Two types: Desktop Conduit (DeskConduit) and Container Conduit (ContConduit). |-| **MCP** | Model Context Protocol — the tool interface that connects Claude to services (viewer, DigiKey, Mouser, etc.). |-| **Sample data** | Pre-generated real view HTML files in viewer/samples/ used for dropdown landing pages. Ensures real-view compliance when no user data is available. |+| Rule | Detail |+|------|--------|+| **webview is one word** | Never "Web View". Short form: wv. |+| **lowercase tools** | pup, shotlog, abe, wv, hdbw — always lowercase in prose. |+| **VS Code** | The IDE inside the workspace (powered by code-server). Never call it "the editor" — the Editor is the Adom App around it. Avoid "code-server"/"Coder" in user-facing text. |+| **No internal codenames to users** | "Hydrogen" (the web app) and "Carbon" (backend registry) appear in code/URLs only. Public names: Adom App / Adom. |  ## Coordinate System  | Term | Definition | |------|-----------|-| **Z-up** | Adom 3D convention: Z is always up. Ground plane is XY at z=0. Babylon.js scenes use `zUp: true`. |-| **KiCad Y flip** | KiCad Y points down; negate Y when converting to Adom 3D coordinates. |-| **GLB 1000x scale** | glTF uses meters, Adom uses mm. GLB models are scaled 1000x. Overlay meshes need positions multiplied by 1000. |--## Tools & Brand Names--Use these names consistently in conversation, docs, CLI output, and skill files.--| Name | What it is | Notes |-|------|-----------|-------|-| **Adom Editor** | The full Hydrogen web app (panels, toolbar, layout) | "Editor" always means this. Never call VS Code "the editor". |-| **VS Code** | The code IDE running inside the workspace (cloud: Docker container; HD: the WSL2 distro), powered by code-server | **Primary name.** Embedded as an iframe panel in the Adom Editor, or accessed directly via `https://<slug>.adom.cloud/?folder=...`. Synonyms to avoid in user-facing contexts: "code-server", "coder", "Coder.com". Use those only when discussing internals or infrastructure. Never call it "the editor" (that's Hydrogen). |-| **pup** | Puppeteer browser control via Adom Desktop | Always lowercase. "Open in pup", "pup screenshot", "pup reload". |-| **shotlog** | Screenshot log viewer and injector | Always lowercase. CLI binary name = `shotlog`. |-| **adom-vscode** | VS Code extension + CLI for controlling code-server | Hyphenated. CLI binary name = `adom-vscode`. |-| **adom-cli** | Adom platform CLI (containers, repos, users, workspaces) | Hyphenated. Binary = `adom-cli`. |-| **SB** | Sandbox panel | User shorthand. "Show in sb" = show in the sandbox panel. |--## Internal Names--<!-- NOTE: Customers may see this file. These are listed here so the AI uses-     the correct public name and avoids leaking internal codenames in-     conversation, docs, or UI. Do not remove this section — it prevents-     the AI from accidentally using internal terminology with users. -->--The following names are used internally in code, repos, and infrastructure. **Always use the public name** in conversation, documentation, wiki, and anything user-facing.--| Internal Name | Public Name | Where you'll see the internal name |-|---------------|-------------|-------------------------------------|-| **Hydrogen** | **Adom Editor** (or just "Editor") | Repo paths (`hydrogen.adom.inc`), API endpoints, workspace control skill |-| **Carbon** | (no public name — backend only) | Container registry API (`carbon.adom.inc`), `adom-cli carbon` commands |-| **code-server** / **Coder** | **VS Code** | Docker infrastructure, server processes, port configs |-| **conduit** | **Desktop Conduit** or **Container Conduit** | Relay server code, WebSocket bridge internals |+| **Z-up** | Adom 3D convention: Z is up, ground plane XY at z=0. Babylon scenes use `zUp: true`. |+| **KiCad Y flip** | KiCad Y points down; negate Y converting to Adom 3D. |+| **GLB 1000x scale** | glTF is meters, Adom is mm — GLB models scale 1000x; overlay positions multiply by 1000. |