From d3ab281baa174c13ee6bbe78f7538e1d25734d7b Mon Sep 17 00:00:00 2001
From: Keysat <licensing@keysat.xyz>
Date: Wed, 17 Jun 2026 07:41:36 -0500
Subject: [PATCH] Record CSS-token convention; refresh Current state for the
 design system

---
 AGENTS.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index ccfc54b..dfbd199 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -94,6 +94,7 @@ vendor/keysat-licensing-client/   local-link Keysat SDK
 - **`recaps.cc` IS the operator's StartOS box**, served via Start9 Pages + StartTunnel. So `make install` (after a version bump) updates the public cloud site automatically — there is no separate cloud deploy step. A frontend-only change reaches recaps.cc as soon as the box serves the new `public/` files.
 - **`render()` rebuilds the whole view via `innerHTML` — preserve live media + scroll across it.** It re-attaches the live podcast `<audio>` node (`replaceWith`, src-matched) and restores `.chunks-scroll` scrollTop, so a background re-render (e.g. the ~60s relay-credit poll) doesn't stop playback or bounce the reader to the top. YouTube minimize toggles the `.results-left.minimized` CSS class **in place** — never `render()`, because creating the YT iframe inside a `display:none` container wedges the IFrame API (black frame, needs reload); `ensureYtMounted()` + a `!state.videoMinimized` guard on `needsMount` keep the player from ever being built hidden, and `initPodcastPlayer()` is idempotent (`dataset.inited`). Don't reintroduce a full `render()` on minimize or drop these preservation steps.
 - **URL parsing is duplicated server + client — edit both in lockstep.** `extractVideoId` (and the sibling classifiers `isChannelUrl` / `isPodcastUrl`) live in BOTH `server/util.js` and `public/index.html` with the same logic; the server copy is the one that actually rejects a submit (`server/index.js` → "Invalid YouTube URL"). When you teach one a new URL form, teach the other or the frontend preview and server will disagree. `extractVideoId` accepts `/watch?v=`, `youtu.be/`, `/embed/`, `/v/`, `/live/`, `/shorts/`, and a bare 11-char id; trailing `?si=…` tracking params are fine (the regex stops after the id). Tests: `server/test/util.test.js`.
+- **Colors flow from CSS custom properties — edit the token, not the value.** `public/index.html`'s `<style>` opens with a `:root` token block (the single source of truth, mirroring `design/tokens.tokens.json`); the stylesheet references `var(--accent)` / `var(--surface)` / etc. Change a brand color there, once. **Three surfaces each carry their own `:root` copy and must stay in sync:** the main stylesheet, the `SHARE_PAGE_CSS` export string, and `public/auth.html` (standalone documents can't see each other's `:root`). Caveat: the long tail of inline `style=` attributes still hardcodes hex (Phase 2 in `ROADMAP.md`), and a few spots **cannot** take `var()` — the `<meta theme-color>`, SVG `fill`/`stroke` set via JS, and hex used in JS *logic* — so don't blind-sweep them.
 
 ### Client-side contract with the relay
 
@@ -139,7 +140,7 @@ unsure whether a change is contract-affecting, assume it is and check.
 
 **Done & live:** self-serve Pro/Max purchase (Bitcoin inline-Lightning + Zaprite card, prepaid, relay owns tier/expiry), core-decoupling, per-tenant subscriptions, expiry-reminder emails (`POST /api/admin/reminders/run {test_email}`), **opt-in Daily Digest** (0.2.158, `b4fa5d7`): off-by-default daily email of a user's last ~24h of library recaps, each synthesized via `/relay/analyze` (operator-absorbed); `daily-digest.js` scan at `SEND_HOUR=8`, per-user watermark dedup, public tokenized unsubscribe, admin trigger `POST /api/admin/digest/run`; and **YouTube `/live/` + `/shorts/` URL support** (0.2.159, `cb961cd`): `extractVideoId` now accepts those forms (was rejecting them as "Invalid YouTube URL"). Plans in `docs/*-plan.md`.
 
-**Design system (2026-06-16, committed `1741fb1` + a follow-up commit, NOT yet deployed):** the `design/` contract was extracted from the as-built UI (`design/DESIGN.md` + `design/tokens.tokens.json`; see the **Design** line near the top). Then **Phase 1 of the conformance cleanup landed**: a canonical `:root` token block is now the single source of truth in `public/index.html`'s `<style>`, the whole stylesheet + `public/auth.html` are migrated to `var(--token)`, and all color/weight drift was fixed across every surface (auth's blue accent → indigo, legacy darks → the ladder, etc.). Verified locally (144 tests pass, both pages serve 200, all `var()` resolve) but **not installed/deployed** — reaches recaps.cc when the box serves the new `public/` files. Phase 2 (var-ifying the long-tail inline styles, snapping off-scale font/radius) is queued in `ROADMAP.md`.
+**Design system (NEW this session, NOT yet deployed):** the `design/` contract is live (`design/DESIGN.md` + `design/tokens.tokens.json`; see the **Design** line up top). Phase 1 of the conformance cleanup is done — a canonical `:root` token block is the single source of truth in `public/index.html`'s `<style>`, the stylesheet + `public/auth.html` use `var(--token)`, and all color/weight drift is fixed across every surface (auth blue→indigo, legacy darks→ladder). Verified locally (144 tests, both pages serve 200, all `var()` resolve); **not installed** — reaches recaps.cc only on the next box-serve / `make install`. Phase 2 (var-ify the long-tail inline styles; snap off-scale font/radius — both *visible* changes) is queued in `ROADMAP.md`.
 
 **Only loose end:** the Daily Digest's relay-synthesis + SMTP path can't be exercised off-box, so it's installed but **not yet smoke-tested** — that's operator action #5 below. Everything else (schema/upgrade, scheduler boot, unsubscribe flow) is verified.