Definitions

@@ -1,6 +1,6 @@ {   "slug": "definitions",-  "version": "1.0.3",+  "version": "1.0.4",   "type": "skill",   "description": "Canonical Adom glossary. Use when the user asks \"what is [term]\", \"define [term]\", \"glossary\", or uses Adom shorthand that must resolve correctly (wv, extwv, nb, pup, abe, hdbw, ad, hd, hw, aw, cf).",   "dependencies": {},

@@ -4,7 +4,7 @@   "slug": "definitions",   "title": "Definitions",   "brief": "Use when the user asks \"what is [term]\", \"define [term]\", \"what does [term] mean\", \"glossary\", \"definitions\", or needs clarification on Adom platform terminology.",-  "version": "1.0.3",+  "version": "1.0.4",   "tags": [     "glossary",     "definitions",@@ -15,7 +15,7 @@   ],   "license": "MIT",   "source_path": "SKILL.md",-  "readme": "# Adom Definitions\n\nCanonical glossary of Adom platform terms. Use these consistently in conversation, code,\ndocumentation and wiki content.\n\n**Read this before guessing what a short form means.** Adom shorthand is real vocabulary, not\ntypos: `wv` is webview, `nb` is the user's native browser, `aw` is the wiki. Resolving one by\nguesswork (or \"testing\" whether it is a CLI subcommand) produces confidently wrong answers.\n\nIf a term isn't here, propose it -- this page is the vocabulary every Adom AI and human shares.\n\n## Core Platform\n\n| Term | Definition |\n|------|-----------|\n| **Adom** | The platform and company. Never surface internal codenames to users. |\n| **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. |\n| **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.) |\n| **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). |\n| **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. |\n| **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. |\n| **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. |\n| **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. |\n\n## Display Surfaces (how the AI shows an app or page)\n\n| Term | Definition |\n|------|-----------|\n| **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. Under HD, a site that refuses framing shows a handoff card offering the External Webview (extwv) or hdbw. |\n| **External Webview** (short: **extwv**) | An HD panel tab backed by a REAL browser surface (native WebView2) instead of the default wv iframe: the opt-in escape hatch for sites that refuse to be embedded, like Google and Amazon (X-Frame-Options / CSP frame-ancestors). Same tab ergonomics as wv (URL bar, back/forward, reload, rename, rich tab tooltip), but heavier, and HD's own HTML cannot draw over a native surface, so it is opt-in rather than the default. Open it from the + panel menu (\"External Webview\"), or take the handoff card a blocked wv shows. Only exists under HD. \"Open it in extwv\" == this. |\n| **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. |\n| **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. |\n| **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`. |\n| **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). |\n| **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). |\n| **Simple Browser** | VS Code's built-in browser page. NEVER an Adom surface — showing an app there is a bug on every platform. |\n\n## Skills & Distribution\n\n| Term | Definition |\n|------|-----------|\n| **Skill** | A Markdown document (SKILL.md) that teaches the AI a specialized task. Installed flat at `~/.claude/skills/<name>/`. |\n| **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. |\n| **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. |\n| **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. |\n| **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. |\n| **Discovery metadata** | `discovery_triggers` / `discovery_pitch` / `sample_prompts` in a package manifest — how AIs find and auto-install a tool. Required for apps/skills. |\n\n## The Wiki — pillars\n\nEvery wiki page is built from these pillars (each is a tab on the page and a verb family in aw):\n\n| Pillar | Definition |\n|--------|-----------|\n| **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). |\n| **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. |\n| **release** | Per-platform binaries attached to a version (`aw release upload`) — the \"Download for your machine\" buttons. How humans get CLIs without the registry. |\n| **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. |\n| **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). |\n| **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. |\n\n## CLI Tools\n\n| Term | Definition |\n|------|-----------|\n| **adom-cli** | Platform CLI — containers, repos, orgs, SSH keys, Hydrogen control (`adom-cli hydrogen …` drives panels/webviews). |\n| **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.) |\n| **pkg** | Bare \"pkg\" means `adom-wiki pkg` — \"pkg install it\", \"pkg update\", \"did you pkg publish?\" all refer to the wiki package manager. |\n| **adom-desktop** | AD's verb surface from any container — shell, files, screenshots, bridges, pup (`browser_*`), windows (`desktop_*`), HD control (`hd_*`). |\n| **adom-vscode** | CLI + VS Code extension controlling code-server (port 8821): open files, run editor commands, drive Claude Code panels. |\n| **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. |\n| **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. |\n| **adom-google / adom-tts / adom-gchat** | Google Workspace access (as the user), shared TTS narration, and org chat posting, respectively. |\n\n## AI-First Rules\n\n| Term | Definition |\n|------|-----------|\n| **real-view** | Always show the ACTUAL running app/view — never a mockup, placeholder, or approximation. Applies to demos, screenshots, wiki pages, landing pages, everywhere. |\n| **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. |\n| **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. |\n| **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. |\n\n## EDA Tools & Apps (the daily vocabulary)\n\n| Term | Definition |\n|------|-----------|\n| **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. |\n| **adom-footprint** | Creates KiCad `.kicad_mod` footprints (and the 3D pad preview) the same way — generate, preview in wv, deliver to the EDA tool. |\n| **adom-lbr** | The Adom Library management tool — organizes symbols/footprints/3D models into libraries, browses and exports them (incl. Fusion export). |\n| **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. |\n| **ds2sf** | Datasheet-to-symbol/footprint — turns a datasheet PDF straight into a symbol + footprint. The \"I have a PDF, make me library parts\" path. |\n| **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.) |\n| **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. |\n| **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. |\n| **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. |\n| **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. |\n| **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\".) |\n| **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. |\n| **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. |\n\n### Chip Vendors & CAD Sources (spoken shorthand)\n\n| Shorthand | Means |\n|-----------|-------|\n| **ti** | Texas Instruments |\n| **stm** | STMicroelectronics (also \"an stm32\" = their MCU family) |\n| **nxp** | NXP Semiconductors |\n| **nrf** | Nordic Semiconductor's nRF chip families (\"an nrf\" = nRF52/nRF53/nRF54 etc.) |\n| **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). |\n| **ul** | Ultra Librarian — CAD-model source |\n| **cse** | Component Search Engine (SamacSys) — CAD-model source |\n\n## Hydrogen Desktop (hd) terms\n\n| Term | Definition |\n|------|-----------|\n| **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. |\n| **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. |\n| **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. |\n| **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). |\n\n## URLs\n\n| URL Pattern | What it is |\n|-------------|-----------|\n| `https://hydrogen.adom.inc/{owner}/{repo}` | Repo page (info, container status, README) — not the editor. |\n| `https://hydrogen.adom.inc/{owner}/{repo}/edit` | The editor — full Hydrogen Web. Always add `/edit` to work in a container. |\n| `https://{slug}.adom.cloud/` | Direct container URL (raw VS Code). App ports proxy at `https://{slug}.adom.cloud/proxy/{port}/`. |\n| `https://wiki.adom.inc/{org}/{page}` | A wiki page (Overview, Files, Skills, Packages, Releases, Issues tabs). |\n\n## Naming & Brand Rules\n\n| Rule | Detail |\n|------|--------|\n| **webview is one word** | Never \"Web View\". Short form: wv. |\n| **lowercase tools** | pup, shotlog, abe, wv, nb, hdbw, ad, hd, hw, aw, cf — always lowercase in casual prose (AD/HD/HW in formal docs). |\n| **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. |\n| **No internal codenames to users** | \"Carbon\" (the backend registry) is internal — code/URLs only. \"Hydrogen\" is PUBLIC brand (Hydrogen Web / Hydrogen Desktop). |\n\n## Coordinate System\n\n| Term | Definition |\n|------|-----------|\n| **Z-up** | Adom 3D convention: Z is up, ground plane XY at z=0. Babylon scenes use `zUp: true`. |\n| **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. |\n| **KiCad Y flip** | KiCad Y points down; negate Y converting to Adom 3D. |\n| **GLB 1000x scale** | glTF is meters, Adom is mm — GLB models scale 1000x; overlay positions multiply by 1000. |\n\n## Adom Hardware\n\n| Term | Definition |\n|------|-----------|\n| **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. |\n| **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. |\n| **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. |\n| **Scaffold** | Medium unit, structural molecule on which several other molecules can be assembled. |\n| **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. |\n| **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. |\n| **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. |\n\n## Workcell Types\n\n| Term | Definition |\n|------|-----------|\n| **User Workcell** | A workcell that is meant to be frequently accessed and driven by users of Adom. |\n",+  "readme": "# Adom Definitions\n\nCanonical glossary of Adom platform terms. Use these consistently in conversation, code,\ndocumentation and wiki content.\n\n**Read this before guessing what a short form means.** Adom shorthand is real vocabulary, not\ntypos: `wv` is webview, `nb` is the user's native browser, `aw` is the wiki. Resolving one by\nguesswork (or \"testing\" whether it is a CLI subcommand) produces confidently wrong answers.\n\nIf a term isn't here, propose it -- this page is the vocabulary every Adom AI and human shares.\n\n## Core Platform\n\n| Term | Definition |\n|------|-----------|\n| **Adom** | The platform and company. Never surface internal codenames to users. |\n| **The wiki** / **adom-wiki** (short: **aw**) | One product, two faces: the site (https://wiki.adom.inc \u2014 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 \u2014 context says whether you mean the site or the CLI. |\n| **Hydrogen Web (HW)** (casual: **hw**) | The web app at hydrogen.adom.inc: toolbar, panels, VS Code, profile \u2014 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.) |\n| **Container** | The persistent environment your work lives in \u2014 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\" \u2014 the word workspace survives only inside frozen identifiers (`Adom-Workspace`, `adom-cli hydrogen workspace \u2026`, adom-workspace-control). |\n| **Hydrogen Desktop (HD)** (casual: **hd**) | The Windows/macOS desktop app \u2014 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. |\n| **Adom Desktop (AD)** | The desktop bridge/relay: gives AIs hands on the user's real machine \u2014 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\") \u2014 when a user says \"ad\" they mean this bridge. |\n| **abe** | The Adom browser extension \u2014 lets the AI drive the user's REAL signed-in Chrome/Edge (`nbrowser_*` verbs): logged-in sites, real credentials, human trust. |\n| **Panel** | A rectangular area of the Hydrogen layout (hw or hd) \u2014 VS Code, webview, 3D viewer, cameras, sensors. Panels split, resize, move, close; each has a tab with name + icon. |\n\n## Display Surfaces (how the AI shows an app or page)\n\n| Term | Definition |\n|------|-----------|\n| **webview** (short: **wv**) | THE workhorse display surface: a native Hydrogen webview tab \u2014 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 \u2014 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 \u2014 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. Under HD, a site that refuses framing shows a handoff card offering the External Webview (extwv) or hdbw. |\n| **External Webview** (short: **extwv**) | An HD panel tab backed by a REAL browser surface (native WebView2) instead of the default wv iframe: the opt-in escape hatch for sites that refuse to be embedded, like Google and Amazon (X-Frame-Options / CSP frame-ancestors). Same tab ergonomics as wv (URL bar, back/forward, reload, rename, rich tab tooltip), but heavier, and HD's own HTML cannot draw over a native surface, so it is opt-in rather than the default. Open it from the + panel menu (\"External Webview\"), or take the handoff card a blocked wv shows. Only exists under HD. \"Open it in extwv\" == this. |\n| **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 \u2014 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 \u2014 `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 \u2014 clean up when a task ends. Always lowercase. |\n| **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. |\n| **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`. |\n| **hdbw** | HD Browser Window \u2014 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 \u2014 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 \u2014 URL bar, back/forward, tabs, and a move-this-tab-to-another-surface action powered by the Browser Picker (design in flight). |\n| **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). |\n| **Simple Browser** | VS Code's built-in browser page. NEVER an Adom surface \u2014 showing an app there is a bug on every platform. |\n\n## Skills & Distribution\n\n| Term | Definition |\n|------|-----------|\n| **Skill** | A Markdown document (SKILL.md) that teaches the AI a specialized task. Installed flat at `~/.claude/skills/<name>/`. |\n| **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. |\n| **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) \u2192 `adom/hd-bootstrap` (platform-generic HD + shared hd-* skills) \u2192 `adom/hd-windows-bootstrap` (WSL2 layer) / `adom/hd-mac-bootstrap` (Kyle's macOS layer). Each layer bundles ITS OWN skills. |\n| **The hook** | `adom/hook` \u2014 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. |\n| **Skill tiers** | `skills/` (user skills \u2014 ship in the install tarball), `dev-skills/` (build/debug \u2014 source repo only), `publish-skills/` (app\u2192wiki publishing \u2014 source repo only). Only user skills reach installed containers. |\n| **Discovery metadata** | `discovery_triggers` / `discovery_pitch` / `sample_prompts` in a package manifest \u2014 how AIs find and auto-install a tool. Required for apps/skills. |\n\n## The Wiki \u2014 pillars\n\nEvery wiki page is built from these pillars (each is a tab on the page and a verb family in aw):\n\n| Pillar | Definition |\n|--------|-----------|\n| **repo** | The page's own git repo (Files tab) \u2014 README, source files, hero assets. Pushed with `aw repo push`; cloned with `aw repo clone`. Host SOURCE here (never tarballs). |\n| **pkg** | The package registry pillar \u2014 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 \u2014 update both. |\n| **release** | Per-platform binaries attached to a version (`aw release upload`) \u2014 the \"Download for your machine\" buttons. How humans get CLIs without the registry. |\n| **hero** | The 16:10 billboard \u2014 headline, subhead, screenshot \u2014 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. |\n| **issues** | Per-page issue tracker (`aw issue create` / Issues tab) \u2014 bugs, proposals, coordination. How work on someone else's page gets requested (e.g. adom/core#1). |\n| **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 \u2014 so it's discoverable from where people already look. |\n\n## CLI Tools\n\n| Term | Definition |\n|------|-----------|\n| **adom-cli** | Platform CLI \u2014 containers, repos, orgs, SSH keys, Hydrogen control (`adom-cli hydrogen \u2026` drives panels/webviews). |\n| **adom-wiki** (short: **aw**) | The wiki's CLI \u2014 pkg publish/install/update, page repos, releases, issues, PRs. Same product as \"the wiki\" above; aw covers both. (`adompkg` is dead; never use it.) |\n| **pkg** | Bare \"pkg\" means `adom-wiki pkg` \u2014 \"pkg install it\", \"pkg update\", \"did you pkg publish?\" all refer to the wiki package manager. |\n| **adom-desktop** | AD's verb surface from any container \u2014 shell, files, screenshots, bridges, pup (`browser_*`), windows (`desktop_*`), HD control (`hd_*`). |\n| **adom-vscode** | CLI + VS Code extension controlling code-server (port 8821): open files, run editor commands, drive Claude Code panels. |\n| **shotlog** | THE show-your-work channel: a screenshot log server + CLI (port 8820). The AI cannot display images in chat \u2014 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. |\n| **claude** | The Claude Code CLI. The ONE tool installed at runtime by HD's cascade (its self-setup needs a live session) \u2014 everything else is baked or package-delivered. |\n| **adom-google / adom-tts / adom-gchat** | Google Workspace access (as the user), shared TTS narration, and org chat posting, respectively. |\n\n## AI-First Rules\n\n| Term | Definition |\n|------|-----------|\n| **real-view** | Always show the ACTUAL running app/view \u2014 never a mockup, placeholder, or approximation. Applies to demos, screenshots, wiki pages, landing pages, everywhere. |\n| **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. |\n| **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. |\n| **Ralph loop** | The AI's visual QA loop: drive a step, screenshot, read, fix, repeat until the UI is right \u2014 no human in the loop. |\n\n## EDA Tools & Apps (the daily vocabulary)\n\n| Term | Definition |\n|------|-----------|\n| **adom-symbol** | Creates schematic symbols \u2014 KiCad `.kicad_sym` and Fusion/EAGLE `.lbr` \u2014 from a part number or datasheet, previews them in a webview, and sends them to KiCad or Fusion 360 Electronics via AD. |\n| **adom-footprint** | Creates KiCad `.kicad_mod` footprints (and the 3D pad preview) the same way \u2014 generate, preview in wv, deliver to the EDA tool. |\n| **adom-lbr** | The Adom Library management tool \u2014 organizes symbols/footprints/3D models into libraries, browses and exports them (incl. Fusion export). |\n| **chip-fetcher** (short: **cf**) | Fetches EVERYTHING about a chip \u2014 datasheet, symbol, footprint, 3D model \u2014 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. |\n| **ds2sf** | Datasheet-to-symbol/footprint \u2014 turns a datasheet PDF straight into a symbol + footprint. The \"I have a PDF, make me library parts\" path. |\n| **chip-thumbnailer** | The chip-icon factory: from one STEP file, renders the full family of chip icons \u2014 shaded orientations, transparent alpha-keyed variants, the part number lasered on the chip top, vector outline styles \u2014 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.) |\n| **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. |\n| **mouser / digikey / jlcpcb** (or **jlc**) | When a user says a vendor name bare \u2014 \"search mouser\", \"check digikey\", \"jlc has it?\" \u2014 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. |\n| **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. |\n| **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. |\n| **fusion** | When a user says \"fusion\" in an Adom context they mean the AD **Fusion 360 bridge** (`fusion_*` verbs) driving desktop Fusion 360 Electronics \u2014 open projects, place parts, screenshot, drive the schematic/board/3D. (The Autodesk product itself is \"Fusion 360\".) |\n| **kicad** | When a user says \"kicad\" they TYPICALLY mean AD's **KiCad bridge** (`kicad_*` verbs): open sch/pcb, symbol/footprint editors, 3D viewer \u2014 driving the real desktop KiCad. Disambiguate from the other KiCad tools below by context. |\n| **service-kicad** | The SHARED headless KiCad service container \u2014 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. |\n\n### Chip Vendors & CAD Sources (spoken shorthand)\n\n| Shorthand | Means |\n|-----------|-------|\n| **ti** | Texas Instruments |\n| **stm** | STMicroelectronics (also \"an stm32\" = their MCU family) |\n| **nxp** | NXP Semiconductors |\n| **nrf** | Nordic Semiconductor's nRF chip families (\"an nrf\" = nRF52/nRF53/nRF54 etc.) |\n| **snapmagic** | SnapMagic \u2014 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). |\n| **ul** | Ultra Librarian \u2014 CAD-model source |\n| **cse** | Component Search Engine (SamacSys) \u2014 CAD-model source |\n\n## Hydrogen Desktop (hd) terms\n\n| Term | Definition |\n|------|-----------|\n| **Golden image** | The pre-baked hd-container rootfs (`adom-golden-vN.tar.gz`) HD imports on first run \u2014 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. |\n| **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 \u2014 it verifies its artifact or halts. |\n| **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. |\n| **ESM** | The Editor State Machine \u2014 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). |\n\n## URLs\n\n| URL Pattern | What it is |\n|-------------|-----------|\n| `https://hydrogen.adom.inc/{owner}/{repo}` | Repo page (info, container status, README) \u2014 not the editor. |\n| `https://hydrogen.adom.inc/{owner}/{repo}/edit` | The editor \u2014 full Hydrogen Web. Always add `/edit` to work in a container. |\n| `https://{slug}.adom.cloud/` | Direct container URL (raw VS Code). App ports proxy at `https://{slug}.adom.cloud/proxy/{port}/`. |\n| `https://wiki.adom.inc/{org}/{page}` | A wiki page (Overview, Files, Skills, Packages, Releases, Issues tabs). |\n\n## Naming & Brand Rules\n\n| Rule | Detail |\n|------|--------|\n| **webview is one word** | Never \"Web View\". Short form: wv. |\n| **lowercase tools** | pup, shotlog, abe, wv, nb, hdbw, ad, hd, hw, aw, cf \u2014 always lowercase in casual prose (AD/HD/HW in formal docs). |\n| **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\" \u2014 the Editor is Hydrogen (hw/hd) around it. Avoid \"code-server\"/\"Coder\" in user-facing text. |\n| **No internal codenames to users** | \"Carbon\" (the backend registry) is internal \u2014 code/URLs only. \"Hydrogen\" is PUBLIC brand (Hydrogen Web / Hydrogen Desktop). |\n\n## Coordinate System\n\n| Term | Definition |\n|------|-----------|\n| **Z-up** | Adom 3D convention: Z is up, ground plane XY at z=0. Babylon scenes use `zUp: true`. |\n| **Y-up** | The OTHER up. ~30% of the industry ships chip STEP files Y-up (the rest Z-up) \u2014 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. |\n| **KiCad Y flip** | KiCad Y points down; negate Y converting to Adom 3D. |\n| **GLB 1000x scale** | glTF is meters, Adom is mm \u2014 GLB models scale 1000x; overlay positions multiply by 1000. |\n\n## Adom Hardware\n\n| Term | Definition |\n|------|-----------|\n| **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. |\n| **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. |\n| **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. |\n| **Scaffold** | Medium unit, structural molecule on which several other molecules can be assembled. |\n| **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. |\n| **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. |\n| **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. |\n\n## Workcell Types\n\n| Term | Definition |\n|------|-----------|\n| **User Workcell** | A workcell that is meant to be frequently accessed and driven by users of Adom. |\n",   "author": {     "name": "Kyle Bergstedt",     "email": "[email protected]"@@ -45,8 +45,6 @@     "what does wv mean",     "what is nb",     "define hdbw",-    "what is extwv",-    "define external webview",     "adom glossary",     "adom definitions",     "what does pup mean",@@ -63,7 +61,7 @@   "sub_skills": [],   "parent_app": null,   "org": "adom",-  "description": "Canonical Adom glossary. Use when the user asks \"what is [term]\", \"define [term]\", \"glossary\", or uses Adom shorthand that must resolve correctly (wv, extwv, nb, pup, abe, hdbw, ad, hd, hw, aw, cf).",+  "description": "Canonical Adom glossary. Use when the user asks \"what is [term]\", \"define [term]\", \"glossary\", or uses Adom shorthand that must resolve correctly (wv, nb, pup, abe, hdbw, ad, hd, hw, aw, cf).",   "dependencies": {},   "scripts": {     "install": "./install.sh",

@@ -1,17 +1,37 @@ #!/bin/bash-# Regenerate page.json's `readme` from SKILL.md so the wiki page and the installed skill can+# Regenerate the rendered page body from SKILL.md so the wiki page and the installed skill can # never drift apart again. They drifted to 10,712 vs 21,144 bytes -- and into contradicting each # other -- precisely because both were authored by hand. Run this before every publish.+#+# WHERE THE RENDERED PAGE ACTUALLY COMES FROM (learned the hard way, John 2026-07-24):+#   `adom-wiki pkg publish` renders the page body from **README.md in the tarball** and IGNORES+#   page.json entirely (it warns PAGE_JSON_IGNORED). It also refuses to shrink a page: if the+#   tarball README is smaller than the already-rendered body it keeps the old one (README_PRESERVED).+#   So the earlier "README.md is just a pointer, page.json.readme is what the wiki reads" design was+#   WRONG -- syncing page.json did nothing to the live page. README.md IS the page. We generate BOTH+#   README.md (the render source) and page.json.readme (kept in lockstep for repo-push consumers)+#   from SKILL.md, the single source of truth. set -e cd "$(dirname "$0")" python3 - <<'PY' import json, re skill = open('SKILL.md').read() body = skill.split('---', 2)[2].lstrip('\n')          # strip frontmatter, keep the glossary++# 1) README.md — the file pkg publish actually renders as the page body. A leading banner marks+#    it generated so nobody hand-edits it (edit SKILL.md instead), then the full glossary.+banner = ("<!-- GENERATED FROM SKILL.md by sync-page-readme.sh. Do not edit by hand: edit SKILL.md,\n"+          "     then run ./sync-page-readme.sh before publishing. README.md IS the rendered wiki\n"+          "     page body (pkg publish renders README.md, not page.json). -->\n\n")+open('README.md', 'w').write(banner + body)++# 2) page.json.readme — kept in lockstep for repo-push / page-repo consumers, even though+#    pkg publish ignores it. pg = json.load(open('page.json')) before = len(pg.get('readme', '')) pg['readme'] = body json.dump(pg, open('page.json', 'w'), indent=2)+ terms = len(re.findall(r'^\|\s*\*\*', body, re.M))-print(f"page.json readme: {before} -> {len(body)} bytes, {terms} terms (source: SKILL.md)")+print(f"README.md: {len(banner)+len(body)} bytes | page.json readme: {before} -> {len(body)} bytes | {terms} terms (source: SKILL.md)") PY