# Adom Definitions

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. |
| **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 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. |

## Display Surfaces (how the AI shows an app or page)

| Term | Definition |
|------|-----------|
| **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 chrome / nb chrome work / nb edge** | The `nb [browser] [profile]` pattern 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`. |
| **hdbw** | HD Browser Window — Hydrogen Desktop's standalone built-in Tauri browser window: a separate OS window HD manages directly (1200x800, centered, its own webview badge icon; window label `hd-browse-*`). Bigger canvas than a wv pane tab, still HD-native — NOT a webview panel, NOT pup. Open first-class via `POST /hdbw/open {url}` on HD's control API, or pick "HD Browser Window (hdbw)" in the Browser Picker (destination id `webview-window`). Only exists under HD. Graduating into a full mini-browser — URL bar, back/forward, tabs, and a move-this-tab-to-another-surface action powered by the Browser Picker (design in flight). |
| **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. |

## Skills & Distribution

| 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 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 — pillars

Every wiki page is built from these pillars (each is a tab on the page and a verb family in aw):

| Pillar | Definition |
|--------|-----------|
| **repo** | The page's own git repo (Files tab) — README, source files, hero assets. Pushed with `aw repo push`; cloned with `aw repo clone`. Host SOURCE here (never tarballs). |
| **pkg** | The package registry pillar — the versioned install payload (manifest + scripts + bundled user skills). `pkg publish` / `pkg install` / `pkg update`; dependency trees make bootstraps possible. NOTE: publishing a pkg does NOT sync the repo pillar, and vice versa — update both. |
| **release** | Per-platform binaries attached to a version (`aw release upload`) — the "Download for your machine" buttons. How humans get CLIs without the registry. |
| **hero** | The 16:10 billboard — headline, subhead, screenshot — reused on the page header, homepage grid, HD installer, and screensaver. A page's face; required to publish apps/skills. Design rules: the adom-wiki-hero skill. |
| **issues** | Per-page issue tracker (`aw issue create` / Issues tab) — bugs, proposals, coordination. How work on someone else's page gets requested (e.g. adom/core#1). |
| **breadcrumbs** | Third-party "a path leads here" links: attach a small trail marker to SOMEONE ELSE's page announcing a related thing you built (a new bridge, an add-on) without editing their page — so it's discoverable from where people already look. |

## CLI Tools

| Term | Definition |
|------|-----------|
| **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_*`). |
| **adom-vscode** | CLI + VS Code extension controlling code-server (port 8821): open files, run editor commands, drive Claude Code panels. |
| **shotlog** | THE show-your-work channel: a screenshot log server + CLI (port 8820). The AI cannot display images in chat — shotlog is how the human actually SEES: inject/paste shots into named CHANNELS (per task/topic), watched live in a skinny wv panel, a pup window, or on the phone. `shotlog viewers -c <channel>` verifies a HUMAN is genuinely watching (on-screen vs backgrounded vs nobody) so the AI never claims "shown" unwatched. `shotlog channels` shows what every AI thread is sharing. Ralph loops and demos log every frame here. 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. |

## EDA Tools & Apps (the daily vocabulary)

| Term | Definition |
|------|-----------|
| **adom-symbol** | Creates schematic symbols — KiCad `.kicad_sym` and Fusion/EAGLE `.lbr` — from a part number or datasheet, previews them in a webview, and sends them to KiCad or Fusion 360 Electronics via AD. |
| **adom-footprint** | Creates KiCad `.kicad_mod` footprints (and the 3D pad preview) the same way — generate, preview in wv, deliver to the EDA tool. |
| **adom-lbr** | The Adom Library management tool — organizes symbols/footprints/3D models into libraries, browses and exports them (incl. Fusion export). |
| **chip-fetcher** (short: **cf**) | Fetches EVERYTHING about a chip — datasheet, symbol, footprint, 3D model — from vendor sites (SnapEDA, Ultra Librarian, Mouser, DigiKey) into a live dashboard, with per-site scraping playbooks. Scrapes via nb by preference (real logins beat bot-walls), pup as fallback. |
| **ds2sf** | Datasheet-to-symbol/footprint — turns a datasheet PDF straight into a symbol + footprint. The "I have a PDF, make me library parts" path. |
| **chip-thumbnailer** | The chip-icon factory: from one STEP file, renders the full family of chip icons — shaded orientations, transparent alpha-keyed variants, the part number lasered on the chip top, vector outline styles — plus the embossed .step for KiCad. Live web app + CLI; heavy OCCT work runs on service-step2glb. (Symbol/footprint thumbnails are adom-symbol / adom-footprint, not this.) |
| **chipsmith** | STEP-native chip detection + footprint validation + sign-off: loads .step + footprint + datasheet + spec manifest, reads the B-rep directly, detects every electrical contact (legs/pads/balls/EP/pins), validates measurements against declared body dims with unit auto-rescale. The "is this 3D model + footprint actually right?" gate. |
| **mouser / digikey / jlcpcb** (or **jlc**) | When a user says a vendor name bare — "search mouser", "check digikey", "jlc has it?" — they usually mean OUR per-vendor parts-search app for that vendor (**adom-mouser**, **adom-digikey**, **adom-jlcpcb**), not the vendor website. Each searches that vendor's catalog/API and shows results in wv. adom-parts-search queries all three at once. |
| **adom-parts-search** | One search across Mouser + DigiKey + JLCPCB with a Mouser-preferred recommendation (40-min drone delivery to Fort Worth). `adom-parts-search show` opens the wv app + prints the data. |
| **adom-tsci** | tscircuit-powered build-a-board-in-one-prompt: describe a board ("rp2040 dev board with usb-c"), get schematic/PCB/3D in the interactive Board Viewer (wv), with inspect/measure tools and a re-runnable autorouter. |
| **fusion** | When a user says "fusion" in an Adom context they mean the AD **Fusion 360 bridge** (`fusion_*` verbs) driving desktop Fusion 360 Electronics — open projects, place parts, screenshot, drive the schematic/board/3D. (The Autodesk product itself is "Fusion 360".) |
| **kicad** | When a user says "kicad" they TYPICALLY mean AD's **KiCad bridge** (`kicad_*` verbs): open sch/pcb, symbol/footprint editors, 3D viewer — driving the real desktop KiCad. Disambiguate from the other KiCad tools below by context. |
| **service-kicad** | The SHARED headless KiCad service container — DRC/ERC, gerber/STEP/GLB export, symbol/footprint/3D lookups via the `service-kicad` CLI. No desktop KiCad needed; every container can use it. "Run DRC" / "export gerbers" usually means this. |

### Chip Vendors & CAD Sources (spoken shorthand)

| Shorthand | Means |
|-----------|-------|
| **ti** | Texas Instruments |
| **stm** | STMicroelectronics (also "an stm32" = their MCU family) |
| **nxp** | NXP Semiconductors |
| **nrf** | Nordic Semiconductor's nRF chip families ("an nrf" = nRF52/nRF53/nRF54 etc.) |
| **snapmagic** | SnapMagic — CAD-model source (symbols/footprints/3D). RENAMED from SnapEDA (same company; "snapeda" is the legacy name you'll still hear and see in old URLs). |
| **ul** | Ultra Librarian — CAD-model source |
| **cse** | Component Search Engine (SamacSys) — CAD-model source |

## Hydrogen Desktop (hd) terms

| Term | Definition |
|------|-----------|
| **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 28: package convergence via pkg update runs early, right after code-server): 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 hd container 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). |

## URLs

| URL Pattern | What it is |
|-------------|-----------|
| `https://hydrogen.adom.inc/{owner}/{repo}` | Repo page (info, container status, README) — not the editor. |
| `https://hydrogen.adom.inc/{owner}/{repo}/edit` | The editor — full Hydrogen Web. 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). |

## Naming & Brand Rules

| Rule | Detail |
|------|--------|
| **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). |
| **vscode** (formal: **VS Code**) | The IDE inside the container (powered by code-server). We say/type "vscode" ("open it in vscode", "the vscode iframe"); "VS Code" is the formal spelling for docs/UI. 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

| Term | Definition |
|------|-----------|
| **Z-up** | Adom 3D convention: Z is up, ground plane XY at z=0. Babylon scenes use `zUp: true`. |
| **Y-up** | The OTHER up. ~30% of the industry ships chip STEP files Y-up (the rest Z-up) — it's weird out there. Detect and recover the true up-axis on import (chipsmith does this) rather than trusting the file; a Y-up part rendered as Z-up lies on its side. |
| **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. |

## Adom Hardware

| Term | Definition |
|------|-----------|
| **Workcell** | The largest unit in the Adom world. Standardized robotic enclosure where prototypes are physically assembled, tested, and iterated. Each workcell provides a controlled environment with integrated tools, sensors, and robotic manipulation capabilities accessible remotely through Adom's platform. There are several types of internal and user facing workcells. |
| **Base Scaffold** | The base scaffold is the foundation for any project sitting in a workcell. Every user workcell is built around it. It is an aluminum plate with a 576 mm x 576 mm working area. The working area is a structural PCB layer over the base scaffold that provides an insulated surface and mechanical connection points. These can be inserted into and removed from various workcells, allowing a project to undergo different functions in different workcells. |
| **Molecule** | Small, functional unit in the Adom system, to be assembled on scaffolds, wired, tested in workcells. Most but not all molecules are an electrical component or circuit, to be wired together and to the Control Panel. Some are electromechanical, and some have no electronics, but can be meant to interact in other ways with sensors in a project, for example. Molecules are designed with Adom's machine pin and contacts as described in our molecule design guide. |
| **Scaffold** | Medium unit, structural molecule on which several other molecules can be assembled. |
| **Machine Pin** (short: **m pin** / **mpin**) | Metal pin often in the corners of molecules that allow for automated mechanical manipulation and assembly. Can also be used as an electrical connection for the molecule. Large machine pins are spaced at a minimum pitch of 6 mm and Medium machine pins have a minimum pitch of 2 mm. |
| **Contact** | Small metal flexure serving as the female side of an electrical connection for molecules. Used to break out any pins/signals to wire molecules together. Bare wire and machine pin tails can be inserted into contacts for a connection. These have large and medium varieties, analogous to and sharing the same spacing as their respective machine pins. |
| **Control Panel** | The electrical bridge from the base scaffold to the workcell. All wiring that a user wants to provide to and access in their project runs through the control panel. It has two parts, one part permanently attached to the workcell, and one part permanently attached to a given base scaffold so that wiring can be preserved while moving the base scaffold between workcells. |

## Workcell Types

| Term | Definition |
|------|-----------|
| **User Workcell** | A workcell that is meant to be frequently accessed and driven by users of Adom. |