Adom Hydrogen (platform base)

@@ -0,0 +1,82 @@+---+name: hydrogen-key-values+description: >+  The user's cloud key-value store (Carbon KV): what the hydrogen.* / bridge.*+  keys are, how to READ and WRITE them from the workspace (auth proxy or API+  key), the naming + value conventions, the runtime-discovery entries+  (hydrogen.runtime.<machine>), and the profile-menu "Your cloud key-values"+  viewer. READ THIS before touching any key so you follow the ownership and+  no-secrets rules. Trigger words: key-values, kv, kv pairs, cloud settings,+  hydrogen_preferences, carbon settings, user settings store, hydrogen.runtime,+  bridge.container, desktop.container, cloud key value, my cloud data, kv+  viewer, patch settings, runtime discovery.+---++# Cloud key-values: the user's Adom-account KV store++Every Adom user has a small key-value store attached to their account (10MB).+It syncs to every machine and container they sign in on, which makes it the+shared memory between Hydrogen, Adom Bridge, and you: preferences live here,+and running apps publish their live addresses here so they can be discovered+from anywhere.++## Reading and writing++- Read: `GET https://carbon.adom.inc/user` then+  `body.hydrogen_preferences.settings` is the flat map. Auth is either the+  session token (`Cookie: session_token=<tok>`) or the workspace API key+  (`Authorization: Bearer $(cat /var/run/adom/api-key)`).+- Write: `PATCH https://carbon.adom.inc/user/hydrogen/settings` with body+  `{"key": "<dotted.key>", "value": <scalar>}`, same auth. A `null` value+  removes the key.+- From inside Hydrogen's UI surfaces, the control API relays for you:+  `POST /auth/proxy` with `{"path": "/user", "method": "GET"}` (see+  `hydrogen-api`).++## Conventions (follow these exactly)++1. **Dotted lowercase keys, brand-name prefix.** Each app owns its prefix:+   `hydrogen.*` (this app), `bridge.*` (Adom Bridge). Never write into+   another app's prefix. `desktop.*` keys are pre-rename legacy (the+   Adom-Desktop era); Hydrogen still READS them as a fallback but only ever+   WRITES `hydrogen.*`.+2. **Scalar values only.** Structured data goes in as a JSON *string*.+3. **User-visible.** The profile menu's "Your cloud key-values" dialog shows+   every entry, pretty-printed. Keep values compact and self-explanatory.+4. **NEVER a secret.** No tokens, no passwords, no credentials, ever.+5. **Modify with intent.** You MAY change a `hydrogen.*` preference when the+   user asks (e.g. set `hydrogen.editor_font_size`), but prefer the app's own+   settings surface when one exists; a raw PATCH bypasses the app's+   validation and mirrors.++## The keys you'll meet++| Key | Owner | What it is |+|---|---|---|+| `hydrogen.editor_font_size`, `hydrogen.color_scheme`, `hydrogen.wake_heal`, ... | Hydrogen | The Settings dialog's preference tree. |+| `hydrogen.runtime.<machine>` | Hydrogen | Live runtime identity, published at launch + every 4h: a JSON string `{host, control, proxy, cdp, code_server, instance_id, pid, install_path, version, ts}`. `<machine>` is the lowercase sanitized computer name. |+| `bridge.container.<id>` | Adom Bridge | A container connection ab dials (may appear as legacy `desktop.container.<id>` until ab's rename ships). |+| `bridge.runtime.<machine>` | Adom Bridge | ab's live runtime identity (planned mirror of Hydrogen's entry, adom/adom-bridge#72). |++## Using a runtime entry (discovery)++`hydrogen.runtime.<machine>` lets you find a running Hydrogen from a cloud+container or another machine with no port scanning. Rules:++- `ts` is unix seconds; older than ~5h (one missed heartbeat plus slack)+  means that instance is probably gone.+- A live port is NOT identity: hit `GET /buildinfo` on the advertised control+  port and match `instance_id` before trusting it. Zombies from uninstalled+  copies answering `/health` are a real observed failure.++## The viewer++Profile menu (avatar, top-right) → **Your cloud key-values**: read-only list+with filter, per-row copy, and expand for long values; refreshes from Carbon+on open. AI-drivable via the `profile.keyvalues` UI action.++## Related skills++- `hydrogen-ports`: the full discovery ladder these runtime entries sit in.+- `hydrogen-settings`: the Settings dialog that owns the preference keys.+- `hydrogen-api`: the control API and auth proxy.