`** style (matches the existing log). HEREDOC for body. `Co-Authored-By: Claude Fable 5 ` line stays (updated June 2026 from the older `Claude Opus 4.8 (1M context)` trailer — use the current model's name; older log entries keep theirs). **Never** `git add -A` / `git add .` — always explicit paths.
### Push (manual trigger, default OFF)
**Only "push" or "push it"** maps to `git push origin main`. No other phrasing fires push — not "ship", not "publish", not "looks good", not "land it". If both commit + push together is wanted, say "push it"; if commit-only, the auto-commit triggers above handle it.
Tightening this trigger is deliberate. "Ship" / "publish" used to fire push (older memory rule, retired May 18 2026). Push is the one truly irreversible action; the literal command word is the only safe trigger.
**A push to `main` PUBLISHES A LIVE PUBLIC WEBSITE, not just a git ref.** This repo is deployed: Cloudflare Pages project `li-fi-design-system` → **https://design.vilendesign.com**, wired to GitHub `main`, so **every push auto-deploys in ~30–60 s**. There is **no build step** — the Pages project serves this repo's files raw (build command empty, output dir `/`), which is why a new root `foo.html` is live at `/foo` the moment it lands, and why a broken file is live just as fast. As of July 2026 the middleware's `GATE_OPEN=true` stand-down flag is active, so the site serves **publicly with no password** — the Portal, the DS catalog, personas, and partner-org data included. Treat "push" as "publish to the internet": it is the moment the work becomes externally visible, so the pre-push checks above (read `git log origin/main..HEAD`, sanity-check foreign commits) are guarding a live site, not just a branch. Full hosting/gate/rotation detail — and the only place it's canonical — is [`DEPLOYMENT.md`](DEPLOYMENT.md); **read it before answering anything about hosting, deploys, domains, or access**, rather than inferring from the absence of a `vercel.json` / `netlify.toml` / `.github/workflows` (there are none — the config lives in the Cloudflare dashboard plus `functions/`).
**Pull-rebase before push.** When the cue fires, always run `git pull --rebase origin main` immediately before `git push`. This protects against the multi-chat race: another chat may have pushed to main while I was working, and a bare `git push` rejects with "non-fast-forward" — at which point the wrong reflex (a `--force` push) would clobber the other chat's commit. If `git pull --rebase` produces conflicts, **abort the rebase** (`git rebase --abort`) and stop — don't auto-resolve. The conflicts are evidence that two sessions edited the same code paths and the merge needs deliberate eyes. **Exception — conflicts ONLY on generated artifacts** (`dashboard-data.json` / `search-index.json` / `catalog-redirects.js` / `widget.html`): resolve by REGENERATING from the mid-rebase tree (the generator's output IS the canonical content), continue, then re-run all three generators post-rebase and amend — see [`git-workflow.md → "GENERATED-ARTIFACT-only conflict"`](.claude/skills/lifi-ds-docs/references/git-workflow.md). **Second exception — a both-append docs conflict** (two sessions appended INDEPENDENT sections at the same EOF of an append-only log like `bug-history.md` — zero semantic overlap): READ both sections to confirm independence, then resolve keep-both (concatenate, incoming then yours), continue, and surface what you kept — it's a positional collision, not a code-path one (validated in `git-workflow.md → both-append docs conflict`). Genuine code conflicts still abort.
**A rebase does NOT fire `.githooks/pre-commit` — regen the generated artifacts before pushing (June 2026).** `git pull --rebase` replays local commits verbatim, so any hook-generated snapshot they carry (`dashboard-data.json` · `search-index.json` · `catalog-redirects.js` · `widget.html`) still describes the PRE-rebase tree — silently stale against the incoming commits it now sits on top of. After any rebase that pulled in catalog / CSS / component work, re-run all four generators (`collect-dashboard-data.js` · `build-search-index.js` · `build-redirect-map.js` · `build-widget-page.js`), check `git diff -- dashboard-data.json search-index.json catalog-redirects.js widget.html`, and commit the refresh as its own small commit BEFORE pushing. (`widget.html` only needs the regen when the rebase pulled in `playground.html` changes — see its derivation note below.) Validated June 2026: rebasing the withdraw-fees arc onto a parallel machine's 10-commit mini-rail arc left `dashboard-data.json` + `catalog-redirects.js` stale (both sides had touched catalog pages); the regen landed as `532141c` ahead of the push.
**Push publishes EVERY local commit on the branch — including a parallel chat's committed-but-unpushed work (June 2026).** The commit-hygiene rules below guard against *sweeping* foreign work into MY commit; this is the mirror at push time. `git push origin main` sends the whole branch, so any commit a parallel chat landed on local `main` ahead of `origin` ships too — not just mine. **Before pushing, run `git log origin/main..HEAD --oneline` and read what's actually about to go out;** if a foreign commit is in the list, NAME it to the user (subject + sha) so publishing it is a seen decision, not a surprise. It's usually not a blocker — a parallel chat's *committed* work is normally meant to ship — but a still-WIP-feeling commit that merely happens to be committed deserves the heads-up before it's live on origin. Validated June 2026: a `push` published my orders-price-sync commit (`5c9bde5`) alongside a parallel chat's receiving-wallet-reorder (`67db10d`) that had been committed to local main; both were surfaced before pushing.
**Sanity-check a foreign commit before publishing it — not just NAME it (June 2026).** When the push list includes a parallel chat's commit you didn't author or verify — especially a LARGE one (many files) or one that landed FRESHLY (after the user's "push" instruction, so they haven't seen it) — run a cheap pre-push check IN ADDITION to naming it: `node --check` every touched JS file + an integrity grep for whatever this session's work depended on (e.g. after a rename sweep, grep that the foreign commit didn't reintroduce the old symbols). `git push` is the irreversible action; spending ten seconds confirming a foreign commit isn't grossly broken before it goes live is cheap insurance — you're publishing it under the shared branch, so its breakage becomes everyone's. If the check fails, STOP and surface (don't push broken foreign work); if it passes, push + report what you checked. Validated June 2026: a `push` would have published a parallel chat's 28-file engine-extraction commit (`0269403`, `theme-composer-core.js`) that landed AFTER the "push" cue; before publishing, `node --check` passed all 7 composer JS files + a grep confirmed the debrand stayed clean (no old `lifi*` symbols reintroduced) — then pushed.
**For a CSS / non-JS foreign commit, there's no `node --check` — and an absolute brace-balance count is the WRONG tool (June 2026).** A `{`/`}` count over a large `styles.css` reliably comes out *off-by-one or more* because of braces inside comments (`/* … { … */`) and `content:`/`mask`/`url()` strings — so a "balanced=False" result is almost always a pre-existing false positive, not the foreign commit's breakage. Don't reject a push on the absolute count. Instead: (a) compare the **delta** — brace balance at the foreign commit's parent vs. at the foreign commit (`git show :styles.css` vs `git show :styles.css`, count each); if the delta is 0 the commit is brace-neutral, and (b) confirm the commit's own diff adds/removes braces evenly (`git show -- styles.css | grep '^[+-]'` → sum `{`/`}` on `+` vs `-` lines). For touched HTML, run the catalog validator (`validate-doc.py --html `) — that's the CSS/HTML analog of `node --check`. Validated June 2026: a CSS-only foreign commit (`16afbf1`, identity-tile reorder) tripped a naive `balanced=False` (3232/3231) that was identical at its parent and brace-neutral in its diff — a pre-existing false positive; validator passed 0-errors on all 3 touched catalog pages, so it published safely.
**Cross-machine: your local commits may ALREADY be on origin — verify before pushing (June 2026).** The mirror of the rule above, for the multi-Mac setup. The OTHER machine can pull your pushed work and build on top, so by the time you go to push from THIS machine, `origin/main` may already CONTAIN your session's commits (carried up inside the history the other machine pushed). `git log origin/main..HEAD` can then be **empty** even though you have commits that *feel* unpushed — and the only local-ahead commit may be a **parallel chat's**, not yours. So on a "push" cue, don't reflex-push: run `git merge-base --is-ancestor origin/main` for each of your session's commits (exit 0 = already upstream) AND `git log origin/main..HEAD` to see what's genuinely local-ahead. If your work is already on origin and the only local-ahead commit is foreign, **there's nothing of yours to push** — pushing would publish another chat's (possibly unfinished) work. Also expect the branch to **reconcile itself mid-check**: `origin/main..HEAD` can flip from `1` to `0` between two commands when another machine/chat syncs local `main` while you investigate — re-read the state fresh rather than acting on the first snapshot. Validated June 2026: a "check your commits and push" turn found both session commits (`83ecdd1` Portal corners, `e6a4417` doc-sync) already ancestors of `origin/main` via the other machine's history; the lone local-ahead `7f0e093` was a parallel chat's persona-connect-card commit and reconciled away on its own — net: nothing to push, and reflex-pushing would have shipped the parallel chat's work.
**Rebase / conflict recovery scenarios — see [`.claude/skills/lifi-ds-docs/references/git-workflow.md`](.claude/skills/lifi-ds-docs/references/git-workflow.md).** When `git pull --rebase` conflicts (after `git rebase --abort`), match the situation to one of the validated recoveries in the reference: a parallel chat *superseded* your unpushed work · a foreign genuine commit sits *beneath* yours · you *renamed a file* a parallel chat was editing · you *rebased a symbol rename* onto their pre-rename work · a parallel chat's *stopped `rebase -i`* blocks your commit (wedged `--continue` after a clean resolution + the hook contaminating the pick with your working-tree state — June 2026) · two sessions *claimed the same registry ID* (TC-check / B-number / `vN` races — published-wins, renumber the unpublished side incl. its in-flight commit message via `.git/rebase-merge/message` — June 2026) · a parallel session shipped the *SAME feature* and you must *port your design deltas onto their canonical base* (re-apply fresh, NOT cherry-pick — the deltas modify the same restructured surface; user arbitrates the divergence — June 2026). All are [[surface-DAG-impossible-ops]]-class — surface the situation + plan to the user before executing.
**Pull-rebase exception — confirmed-clean upstream (May 2026 refinement).** When `git fetch origin main` shows local is `0` behind, the pull-rebase is a strict no-op — but git refuses to enter pull-rebase with a dirty working tree, forcing a stash dance that itself can create transient index issues (see [`bug-history.md → \`git stash push -- \` — index inconsistency`](.claude/skills/lifi-ds-docs/references/bug-history.md)). In this case, **skip the pull-rebase and push directly.** The race window between `git fetch` and `git push` is small; if origin moves in that window, the push rejects with "non-fast-forward" — a safe failure (no data loss; recover by re-fetching and retrying). The defensive intent of "always pull-rebase" is preserved by the fetch step alone:
```sh
git fetch origin main
git rev-list --left-right --count origin/main...HEAD # if "0 N", origin is clean
git push origin main # push directly; pull-rebase no-op skipped
```
This shortcut is for the specific case where: (a) a fetch just confirmed 0 behind, AND (b) the working tree has uncommitted WIP that would block pull-rebase. When origin HAS moved or the tree is clean, follow the normal pull-rebase-then-push flow.
**Foreign-WIP blocks pull-rebase.** If the pull-rebase refuses with `cannot pull with rebase: You have unstaged changes` because foreign-WIP files from a parallel chat sit in the working tree, **stash those files by explicit path**, then rebase, push, and pop:
```sh
git stash push -m "foreign-WIP from parallel chat — auto-stash for push" --
git pull --rebase origin main
git push origin main
git stash pop
```
The scoped `-- ` is non-negotiable. A bulk `git stash` (no paths) would sweep my just-authored work AND the foreign WIP into the same stash, blending the two by the time of `pop`. With explicit paths, only foreign edits get stashed — my commits are already in the index (committed before the push attempt), so the working tree is left clean for the rebase.
**If the stash pop conflicts**, surface to the user immediately. The parallel chat may have committed a change to the same path while my push was in flight; the conflicts are evidence and need deliberate eyes — don't auto-resolve. `git stash list` keeps the stash entry around for inspection.
**Push-time multi-chat tree scenarios — see [`.claude/skills/lifi-ds-docs/references/git-workflow.md`](.claude/skills/lifi-ds-docs/references/git-workflow.md).** Two validated cases beyond the stash-by-path recipe: the foreign file set *grows mid-push* while a parallel chat writes (switch to a one-shot `git stash push -u`); and a parallel chat *committing mid-session resolves* your entanglement (re-read `git status` + `git diff` at each commit boundary — don't carry a stale "deferred" assessment). [[multichat-wip-separation]]
**A parallel chat's manifest-protection stash can SWEEP your uncommitted work — see [`.claude/skills/lifi-ds-docs/references/git-workflow.md`](.claude/skills/lifi-ds-docs/references/git-workflow.md).** When uncommitted work you verified vanishes from the working tree mid-session while sibling edits survive, run `git stash list` FIRST — a parallel chat's "protect ⌘K manifest" stash may hold it (shared with their files). Recover surgically (`git checkout stash@{0} -- `, leaving theirs stashed) or re-apply from your own context; commit promptly. Commit-time twin: after stashing the foreign page to commit, a residual `search-index.json` diff is YOUR OWN entries if your file is a `build-search-index` PAGES page (`portal.html` is) — commit it, don't abort. [[multichat-wip-separation]] [[surface-DAG-impossible-ops]]
### Rollback protocol — undoing a commit
The right `git` command depends on whether the commit has been pushed. Reach for these by reflex:
- **Unpushed commit** (still local) → `git reset --soft HEAD~1`. Keeps the changes staged for re-work; nothing is lost. Use when "undo that last commit" means "I want to re-do it differently."
- **Pushed commit** (already on origin/main) → `git revert `. Creates a new commit that inverts the bad one; non-destructive, preserves history. Use when "revert that" or "that commit was wrong" comes after a push has already landed.
Never use `git reset --hard` on a pushed commit, never use `git push --force` to clean up history — both stay on the Hard refusals list. The destructive variants exist when the user explicitly asks for them (rare); reflex moves never go there.
**Caveat — a parallel chat may have committed ON TOP of your commit (June 2026).** `git reset --soft HEAD~1` / `--amend` target the current HEAD, which is only *yours* if nothing landed after it. **Before any reset/amend, run `git log --oneline -3` (or `git reflog`) and confirm HEAD is actually yours** — otherwise you undo *their* commit (their changes land staged in your index, masquerading as yours). Recovery + the companion "don't scramble to fix the hook's foreign-WIP generated-file sweep" lesson: [`.claude/skills/lifi-ds-docs/references/git-workflow.md`](.claude/skills/lifi-ds-docs/references/git-workflow.md). [[multichat-wip-separation]]
### Multi-chat hygiene (because work happens in parallel chats)
Another chat's WIP is the failure mode this protocol prevents. Before any commit:
1. **`git status` + scan modified files.** Classify each as **mine** (touched via Read / Edit / Write in this conversation) or **foreign** (modified but not by me in this chat). **"I edited this file" does NOT mean every diff line in it is mine (June 2026):** with 2+ parallel chats in flight, a file you touched can ALSO carry a second chat's hunks — and a foreign-marker grep calibrated to the one parallel feature you KNOW about can't clear it (a house-org-vocabulary scan cleared `portal.css`, which carried a different chat's mini-rail rework; `git add portal.css` swept it). The reliable certificate is per-file diff EXTENT: compare `git diff --stat ` against the size of your own known edit BEFORE `git add` (a 38-line append showing 145 changed lines = foreign hunks present → hunk-classify first), and re-check `git show HEAD --stat` after committing. Full diagnostic + the classifier's "rail"-matches-"trailing" substring trap: `bug-history.md → "TWO parallel features in one file"`.
2. **Stage selectively.** `git add ` — only mine. Pre-commit hooks may auto-stage derived files (e.g. `dashboard-data.json` from `collect-dashboard-data.js`); that's fine because they derive from my changes. **The hook lives at `.githooks/pre-commit`** (configured via `core.hooksPath`), NOT `.git/hooks/` — so `ls .git/hooks/pre-commit` returning nothing does NOT mean "no hook." And it **re-runs the generators even inside a pathspec-scoped `git commit -- `** — staging `dashboard-data.json` only when its content FINGERPRINT actually changed (`collect-dashboard-data.js --hook`, since `63622f8`: exit 10 = real change, staged; exit 0 = metadata-only churn, writes nothing) — so a pathspec commit does NOT keep a genuinely-changed derived snapshot out of the commit (fine; it's derived), and the "leaves the rest of the index untouched" guarantee below holds only for files the hook doesn't touch. The trap: if a parallel chat left a STALE staged `dashboard-data.json`, the hook's regen + your pathspec commit produce an `MM` tangle (staged ≠ HEAD ≠ working). Recover, once the working tree matches HEAD, with `git restore --staged dashboard-data.json`. (Validated June 2026 — personas transfer-history commit.) **Second trigger, same recovery (June 2026):** the identical `MM` tangle is also self-inflicted by a `git stash pop` — when you stash a parallel chat's WIP by path to protect an independent commit, then commit (the hook regenerates + stages `dashboard-data.json`), the later `pop` re-applies the stash's index snapshot on top of the now-moved HEAD and re-stages the *pre-commit* (stale) `dashboard-data.json`. No parallel chat staged anything — the stash → commit → pop order did it. The diagnostic tell is that the staged copy carries the OLD `lastCommitHash` while the working copy already matches HEAD; confirm with `git diff --quiet HEAD -- dashboard-data.json`, then `git restore --staged dashboard-data.json`. (Validated June 2026 — ui-amount-card `--sm`/`--lg` retirement follow-up: stashed a parallel chat's `styles.css`/`swap.css` elevation WIP by path, committed a catalog doc fix, and the pop re-staged the stale snapshot.) **Third trigger — clean single-chat pathspec commit (June 2026): the COMMIT can be fine and only the INDEX stale.** A pathspec commit whose hook regen staged a genuinely-changed `dashboard-data.json` recorded the FRESH snapshot into HEAD, but left the index entry at the stale pre-commit blob (the pathspec machinery restores index entries for paths you didn't name) — `MM` with nothing actually wrong. So on any post-commit `MM`: **verify HEAD first** (`git show HEAD:dashboard-data.json` meta vs working copy) before assuming the commit shipped stale data; if HEAD + working tree carry the fresh regen, the index alone is stale → the same `git restore --staged dashboard-data.json` closes it. (Validated June 2026 — the Site-preview `.host-nav` commit `d32e0d6`.)
**Pre-check the staged index — `git add ` does NOT clear a foreign entry already staged there.** `git add ` only ADDS my paths; it doesn't unstage what a parallel chat already put in the index. A bare `git commit` then commits the **whole index**, sweeping that foreign entry into my commit under my message. Before committing, run `git diff --cached --name-only` (or read the `git status` first column for pre-staged `A` / `R` / `M` entries — a staged rename like `RM index.html -> home.html` is the canonical trap) to see EVERYTHING staged, not just what I added. If a foreign entry is present, scope the commit explicitly with a pathspec: `git commit -m "…" -- …` — a pathspec commit records only the named paths and leaves the rest of the index untouched, so the foreign work stays staged-but-uncommitted exactly as found. Recovery for an unpushed mistake: `git reset --soft HEAD~1`, then the pathspec commit. (Validated May 2026 — a parallel chat's pre-staged `index.html → home.html` rename got swept into a DS commit despite a clean `git add` of only my 4 files; recovered via `reset --soft` + pathspec commit.)
**Cross-page generated artifacts entangle with foreign WIP — defer the manual regen (June 2026).** **Three of the four** hook-regenerated artifacts — `search-index.json` (`build-search-index.js`), `catalog-redirects.js` (`build-redirect-map.js`), AND `dashboard-data.json` (`collect-dashboard-data.js`) — derive in part from **every** catalog page, so regenerating any of them while a parallel chat has uncommitted WIP on a DIFFERENT catalog page sweeps that foreign page's state into your output, even though your own change touched only one page. **`dashboard-data.json` is NOT exempt** (corrected June 2026 — it was previously documented here as "safe because it derives from my changes"; that was incomplete): its `componentSections` is a `.comp-section` tally over `design-system/index.html`, and it's the SNEAKIEST vector — a foreign section added there *without* a `.ds-doc-card` passes a `search-index`/`redirects`-only neutrality check (those index `.ds-doc-card`s + anchors, not `.comp-section`s) yet still bumps `componentSections`. The tell: the regenerated artifact's diff carries entries for ids/pages you never touched (e.g. `index.html` card entries while you only edited `playground.html`). Clean move: **commit only your authored page, `git restore` the regenerated artifact back to HEAD, and DEFER the regen until the foreign WIP lands** — a clean regen then reflects only `main` + your change. Don't ship a cross-page artifact whose content describes an uncommitted foreign page. (Validated June 2026 — the `#ui-receive-panel` catalog card on `playground.html`: a parallel chat's uncommitted `index.html` put 4 foreign `tables-rich` / `table-panel` / `persona-connect-card` entries into the `search-index.json` regen; committed `playground.html` alone, restored the index, deferred the regen. NB: the `.githooks/pre-commit` hook only fires when `core.hooksPath` is set — on a fresh clone where it's unset the hook does NOT auto-regenerate these, so a stale generated file can ship silently. **`npm install` now wires this automatically** via the `postinstall` script in `package.json` (`git config core.hooksPath .githooks`), so any fresh clone is armed the moment dependencies install. The manual `git config core.hooksPath .githooks` stays the recovery path — run it if `npm install` was skipped, if the config got unset, or if you're investigating a "hook isn't firing" report on a teammate's machine.)
**The `git restore` recipe above is DEFEATED by the hook when armed — stash-by-path is the commit-NOW answer (June 2026).** "Commit your page, `git restore` the artifact, defer" only works if you actually DEFER. If you must commit NOW with `core.hooksPath` set (the armed default), `git commit` re-runs `build-search-index.js` / `build-redirect-map.js` against the WORKING TREE — which still holds the foreign WIP — and re-stages the contaminated artifact, re-clobbering your `git restore` before the commit object is written. The restore never survives. The clean commit-now path is the [[multichat-wip-separation]] stash-by-path pattern (above, for push / pull-rebase) applied to the pre-commit hook: **stash the foreign catalog pages by explicit path** (`git stash push -m "…" -- design-system/.html …`), commit (the hook now regenerates from a tree holding ONLY your change; if your change is manifest-neutral — avatar cells, a no-`id` eyebrow, anything the builders don't index — the regen produces ZERO diff, so nothing contaminated stages), then `git stash pop`. **Confirm the generated artifacts are clean BEFORE staging** after the stash: run `build-search-index.js` + `build-redirect-map.js` and check `git diff --quiet -- search-index.json catalog-redirects.js` (both are byte-stable, so any diff is real); for the dashboard run **`collect-dashboard-data.js --hook`** and read the exit code — 0 = no content change (writes nothing, tree stays clean), 10 = real change (it rewrote the file; inspect the diff for foreign entries before staging). **A `dashboard-data.json` regen is NEVER diff-quiet** (timestamp + `lastCommitHash` + rolling-cadence churn on every run) — don't gate it on `git diff --quiet`; CLASSIFY the diff: `componentSections` / entries for pages you didn't touch = contamination, timestamp / hash / cadence = benign churn (full entry: `bug-history.md → "dashboard-data.json regen ALWAYS diffs — classify the diff"`). **Don't run the dashboard collector BARE for this check** — a bare run always rewrites its volatile metadata (timestamps, commit cadence, changelog), so `git diff --quiet -- dashboard-data.json` false-positives on every commit; if you did run it bare and the diff is metadata-only, `git restore dashboard-data.json` (the hook's fingerprint would have skipped it — validated June 2026, the Portal org-wide-withdraw commit's check produced a 120-line metadata-only diff that was correctly restored, not committed). (A `search-index`/`redirects`-only check is exactly what let a foreign `.comp-section` ride into a commit — see `bug-history.md → "dashboard-data.json is a cross-page contamination vector too"`.) Validated June 2026 — an avatar-library commit (4 marks + new `avatars/payments/` + catalog cells) landed clean while a parallel chat's uncommitted `.profile-tile → .identity-tile` rename sat in `index.html` / `personas.html` / `styles.css`: stashed the three, confirmed zero manifest diff, committed the 7 avatar paths, popped. [[multichat-wip-separation]]
3. **Collision = stop.** If a file has BOTH my edits AND modifications I didn't make (the "file modified since read" linter notes, or someone else's intervening edit), pause and ask. Don't merge instincts.
**Distinguish done-but-uncommitted from mid-development BEFORE picking a resolution.** Two collision shapes need different default responses:
- **Done-but-uncommitted** — modifications to existing files only, no new untracked files in the working tree. The parallel chat finished its work and is between commits. Interleaved-hunk staging (per the resolution paragraph below) is appropriate after user approval.
- **Mid-development** — modifications PLUS new untracked files supporting the area being edited (e.g., a new `*.js` introduced to back the markup I'm touching, or sibling helper files appearing alongside an HTML refactor). The parallel chat is genuinely mid-flight; the shape of their work may still change. Default to **wait for parallel chat to commit, then resume** — surface the situation, hold off on edits, spawn the planned work as a follow-up task chip if it's worth tracking. Authoring on top of WIP-with-untracked-files is fragile (the foreign work's API surface may shift), and interleaved-hunk staging is the wrong tool for mid-development collisions — its target case is "work that's done, just between commits." (Validated June 2026 — Orders panel dropdown-wiring session: `git status` showed `playground.html` modified PLUS new untracked `orders-data.js` + `orders-list.js`, both supporting the kebab area I was about to edit. The parallel chat had refactored the static rows into a JS renderer mid-stream; waiting for their commit was cleaner than authoring on top of an evolving renderer.)
**Protect already-made independent work with a scoped commit — the sweep runs both directions (June 2026 refinement).** The "hold off on edits" default assumes you haven't started. If you've ALREADY made an independent, verified change to a file the parallel chat is ALSO editing (a fix to one CSS rule while they churn a *different* region of the same file), leaving it uncommitted is risky: a parallel chat's `git add ` sweeps YOUR uncommitted hunks into THEIR commit. The rest of this section guards against *me* sweeping *theirs*; this guards against *them* sweeping *mine*. When your change is independent (disjoint region) + verified + the file is contested, prefer a scoped `git commit -- ` (or the interleaved-hunk `git apply --cached` below) to PROTECT it, rather than holding it exposed. (Validated June 2026 — the menu-standardization session: a verified `.menu-item` button-reset, left uncommitted per a deliberate "hold everything" choice, was swept into a parallel chat's seg-radius commit `4c00e2e`. The fix survived intact but landed under their message — a provenance smudge that a scoped commit would have avoided. The user made an informed hold choice and the outcome was benign; the lesson is that "protect via scoped commit" is the lower-risk default when the work is already done.) **The verification pass is itself an exposure window (June 2026, second instance).** Re-hit on the directional network-title change: I made the edit, got approval to commit-only-my-hunks, then ran a browser verification pass *first* — and the parallel chat committed during that window, sweeping my uncommitted title hunks into its empty-state commit `091ac5f` (same benign outcome — work intact, landed under their message). The sharpened rule: once you've decided to commit-scoped, commit **before** the verify pass — the dev server serves the working tree, which equals the committed state, so verify the committed result. A verify-then-commit reopens exactly the window the scoped commit is meant to close.
**Interleaved-hunk resolution (when the user approves staging only mine).** The stash-by-path pattern above separates *whole foreign files*. When foreign WIP is interleaved with mine in the **same** file — two features touching the same files in disjoint regions — path-separation can't help, and `git add ` would sweep the foreign hunks into my commit. After the user approves "stage only my hunks," the non-destructive move is **content-classify hunks and `git apply --cached` only mine**:
```sh
# 1. classify each hunk by distinctive markers UNIQUE to my work (the new
# class / function names I authored). Positive-match beats negate-on-
# foreign-keyword: a keyword like "review" false-matches "preview", and
# camelCase ("getReviewModel") defeats \bword\b boundaries. Match what's
# unmistakably mine, not what's unmistakably theirs.
# 2. reassemble the diff header + only my hunks into one patch
# 3. dry-run, then stage to the INDEX only (working tree untouched):
git apply --cached --check my-hunks.patch && git apply --cached my-hunks.patch
git diff --cached | grep -i '' # leak-check: must be empty
git commit -m "…" # commits index = my hunks only
```
`git apply --cached` stages to the index without touching the working tree, so all foreign WIP stays uncommitted in the tree for the other chat. Disjoint hunks apply independently by old-side line number, so a subset applies cleanly against HEAD. Avoid `git add -p` — it's interactive and can't be driven reliably. Always leak-check the staged diff for a foreign marker before committing. (Validated May 2026: mode-nav work cleanly separated from a parallel chat's interleaved Review-screen WIP across 3 shared files this way.)
**Edge case — foreign HEAD movement mid-staging.** If the parallel chat lands a commit between your `git apply --cached` and your `git commit`, your index gets reset (git ties the index to HEAD; HEAD moves → previously-staged hunks revert to "unstaged"). Symptom: `git status` shows files you thought you'd staged now appearing under "Changes not staged" again, and `git diff --cached --stat` is empty. Recovery: **re-stage from scratch** — re-`git add ` for pure-mine files, re-run `git apply --cached --recount ` for mixed files. The working-tree content of your work is unchanged; only the index pointer moved. Line numbers in your hunk patches may have shifted if the foreign commit touched the same files, so regenerate `git diff ` and rebuild the patch before re-applying. (Validated May 27 2026: parallel chat's `.hint → .muted` v20 commit landed between my staging and commit of `.empty-state` work; re-staged across 9 files in one pass.)
**Edge case — interleaved hunks WITHIN a single `@@` block.** When your `+` addition and a foreign `-` deletion fall close enough together that git combines them into one hunk (canonical case: sibling entries 4 lines apart in a sidebar / nav / list), `git apply --cached` of that hunk applies BOTH halves — you'd commit the foreign deletion alongside your addition. Four options at that point: **(a) skip the hunk and land it in a follow-up commit** — cleanest when deferring is cheap; **(b) hand-author a sub-patch** with only your `+` lines + adjusted context — risky, easy to get the line numbers wrong; **(c) ask the user; (d) stage a CONSTRUCTED BLOB** — when you know your own edits verbatim (you just made them via Edit in this session), build the staged content deterministically: `git show HEAD:` → re-apply ONLY your replacements (assert each anchor is unique) → `git hash-object -w` → `git update-index --cacheinfo 100644,,`. No line-number risk, no patch arithmetic, working tree untouched (the foreign half stays for the other chat). **Prefer (d) over (b) whenever your edits are replayable from context; fall back to (a) when they aren't.** (Validated June 2026 — the setting-row consolidation: a `theme-composer.md` bullet edit and a parallel chat's adjacent vignette rewrite merged into one hunk; the constructed blob staged HEAD + my three replacements cleanly.) (2nd validation June 11 2026 — the accordion retirement: after a parallel chat's push-protocol stash/discard/restore churned `styles.css` mid-turn, the blob staged HEAD + the one retirement replacement around the restored vignette WIP; also the right tool for whole disjoint-region files, not just merged single hunks — see `git-workflow.md → "The working tree can mutate BETWEEN consecutive commands"`.) (Validated May 27 2026: the `` sidebar entry skipped because its hunk also contained the parallel chat's `` deletion; the entry landed in a follow-up commit after the parallel chat's sidebar move shipped.)
**Edge case — `git commit -- ` DEFEATS `git apply --cached` staging.** After surgically staging only your hunks via `git apply --cached`, run `git commit -m "..."` **WITHOUT** a pathspec. A pathspec changes commit semantics from "commit the staged index" to "commit everything HEAD-vs-worktree for the named paths" — silently bypassing the index and sweeping every foreign hunk in those files under your message. The pathspec FEELS like extra safety ("commit only these paths") but is the trap: it overrides the protection the index was providing. **The staged index alone is the protection** — once you've used `git apply --cached`, the only safe commit is a bare `git commit`. Recovery if you hit it (unpushed): `git reset --soft HEAD~1` (the parallel chat's WIP comes back into the staged index alongside yours), `git restore --staged `, re-`git apply --cached` your hunk patch, then `git commit` with no pathspec. The leak-check (`git diff --cached | grep `) is empty AFTER the surgical staging but the pathspec commit goes around it; ALWAYS verify post-commit with `git show HEAD --stat -- ` against the staged stat — if the line count diverges from `git diff --cached --stat`, the pathspec swept foreign work in. (Validated June 5 2026 — `ds-footer.js` extraction: parallel chat had ~1,200 lines of doc-preview WIP staged in marketing.html; my 45-line footer hunk staged cleanly via `git apply --cached`, then `git commit -m "..." -- <12 paths>` swept their 1,200 lines under my message, recovered via soft-reset + re-stage + clean bare `git commit`.)
4. **Wrap-up report.** Every commit response ends with a line of the form `Committed: . Left untouched: ` so the state of every other chat's work is visible at the seam.
**Escape hatch:** if a session is genuinely single-chat and the protection isn't wanted ("just commit everything in `git status`"), say so for that turn.
### Hard refusals (never autonomous, even with full commit trust)
These always need explicit user confirmation, even when the rest of the framework says "go":
- `git push --force` (any force-push)
- `git reset --hard`, `git clean -fd` on uncommitted work I didn't author
- `git rebase -i` / amending pushed commits
- `--no-verify` / `--no-gpg-sign` to skip hooks
- Branch deletion, tag deletion, history rewrites
- Anything that affects shared refs beyond a normal `git push origin main`
When one of these is the literal right answer, I'll explain why and ask before doing it.
### Documentation surface vs. canonical source
When a policy / framework / spec gets a visual rendering in the catalog (e.g., `ai.html#git-workflow` rendering the git rules above), **the canonical source stays in the file that's loaded into every session** — usually `CLAUDE.md`, sometimes `design.md` or a per-skill `SKILL.md`. The visual rendering is the display surface, not the definition.
**Why this matters.** Drift creeps in fast when there are two sources of truth. The rule evolves in `CLAUDE.md` (loaded into every session at first prompt), the catalog visual goes stale, contributors who scan the catalog see the stale version, the system's behavior says one thing and the docs say another. Same trap that compromised the dashboard's caption-overrides narrative until I grep'd the real distribution.
**Contract for documentation-as-rendering.**
- The catalog/visual page **explicitly points at the canonical source** at the bottom of the section — a "Source of truth: ` → `" footnote so readers know which one wins on disagreement.
- When the canonical rule changes, **refresh the rendering in the same commit** (or flag it as a follow-up if the rendering needs design work).
- **Never let the catalog become the source.** If a contributor wants to evolve the rule, the canonical file is what they edit; the rendering follows.
Same pattern applies to the design-system dashboard (`dashboard-data.json` is the rendered snapshot, the live codebase is the source) and to skill SKILL.md → catalog pairings.
### Maintaining CLAUDE.md itself + `.claude/` reference docs
**CLAUDE.md is loaded into every session — keep operative rules inline, relocate the archaeology.** The canonical-source-vs-rendering rule above applies to *this file*: a rule's bug-history chronology, the validated war-stories, and the `vN` migration ladders are *renderings* (the evidence that produced the rule), not the rule itself. Keep the **operative every-time instruction** inline; relocate the narrative — verbatim — to its tracked reference (`bug-history.md`, `git-workflow.md`, etc.) behind a one-line dispatch pointer that still NAMES the scenario so it stays discoverable. **Verify the target is already mirrored (or move the text there) BEFORE trimming** — never trim toward a dangling anchor, and never relocate a paragraph that's the canonical *source* of a pointer elsewhere (e.g. the `.btn-alpha` border-slot narrative, which `bug-history.md` points *to*). Lossless by construction; the always-loaded file gets denser without losing anything. (June 2026 — a ~4.1k-token pass: relocated git rare-scenario recoveries → `git-workflow.md`, consolidated duplicated bug-history chronologies to one-line pointers, and collapsed the retirement ladder v10–v22 to a name-list + pointer, keeping v24 inline because it carries live contracts.)
**Repo docs under `.claude/` MUST live under `.claude/skills/…/` to be tracked.** `.gitignore` ignores `.claude/*` and re-includes only `.claude/skills/` (+ `**`) — so a new reference/doc placed at a top-level path like `.claude/references/…` is **silently gitignored**: it never commits, and any pointer to it from a tracked file dangles for teammates and your other Macs. Put shared `.claude/` docs alongside `bug-history.md` at `.claude/skills/lifi-ds-docs/references/` (the only tracked references area). Confirm with `git check-ignore ` before pointing a tracked file at a new `.claude/` location.
## CLAUDE.md — 12-rule template
These rules apply to every task in this project unless explicitly overridden.
Bias: caution over speed on non-trivial work. Use judgment on trivial tasks.
### Rule 1 — Think Before Coding
State assumptions explicitly. If uncertain, ask rather than guess.
Present multiple interpretations when ambiguity exists.
Push back when a simpler approach exists.
Stop when confused. Name what's unclear.
### Rule 2 — Simplicity First
Minimum code that solves the problem. Nothing speculative.
No features beyond what was asked. No abstractions for single-use code.
Test: would a senior engineer say this is overcomplicated? If yes, simplify.
### Rule 3 — Surgical Changes
Touch only what you must. Clean up only your own mess.
Don't "improve" adjacent code, comments, or formatting.
Don't refactor what isn't broken. Match existing style.
### Rule 4 — Goal-Driven Execution
Define success criteria. Loop until verified.
Don't follow steps. Define success and iterate.
Strong success criteria let you loop independently.
### Rule 5 — Use the model only for judgment calls
Use me for: classification, drafting, summarization, extraction.
Do NOT use me for: routing, retries, deterministic transforms.
If code can answer, code answers.
### Rule 6 — Token budgets are not advisory
Per-task: 4,000 tokens. Per-session: 30,000 tokens.
If approaching budget, summarize and start fresh.
Surface the breach. Do not silently overrun.
### Rule 7 — Surface conflicts, don't average them
If two patterns contradict, pick one (more recent / more tested).
Explain why. Flag the other for cleanup.
Don't blend conflicting patterns.
### Rule 8 — Read before you write
Before adding code, read exports, immediate callers, shared utilities.
"Looks orthogonal" is dangerous. If unsure why code is structured a way, ask.
### Rule 9 — Tests verify intent, not just behavior
Tests must encode WHY behavior matters, not just WHAT it does.
A test that can't fail when business logic changes is wrong.
### Rule 10 — Checkpoint after every significant step
Summarize what was done, what's verified, what's left.
Don't continue from a state you can't describe back.
If you lose track, stop and restate.
### Rule 11 — Match the codebase's conventions, even if you disagree
Conformance > taste inside the codebase.
If you genuinely think a convention is harmful, surface it. Don't fork silently.
### Rule 12 — Fail loud
"Completed" is wrong if anything was skipped silently.
"Tests pass" is wrong if any were skipped.
"Done / applied / fixed" is wrong if you only checked the code — **verify it VISUALLY first** (Cardinal rule 5). A resolved rule is not a visible result.
Default to surfacing uncertainty, not hiding it.
## Stack defaults
I'm not loyal to any framework. My design-taste anchors are **Tailwind, Shadcn, MUI, Material Design, Apple HIG** and other major design systems. Light engineering visibility on my side — verify build / runtime details against the repo before assuming, and explain the "why" when you use them.
For the LI.FI repo specifically: **Vite ^8** dev server, **npm** package manager, vanilla HTML pages with shared CSS / JS files (no React / Vue framework). Verify on the personal machine after cloning.
## Win patterns / miss patterns
- **Repeat:** real-time visual feedback tools (the OKLCH Theme Composer is the reference). When proposing color / type / spacing tooling, lean toward live-preview interactives over static decisions.
- **Never repeat:** doc style drift when adding new components — it has cost me manual rework. Use the canonical primitive every time.
## Design System
### The bundled default brand is the only default — never auto-apply any other preset
**Hard rule, no exceptions.** The CSS `:root` block in `styles.css` is the sole source of first-paint colours, and it always renders the DEFAULT brand — **LI.FI 1.0**, the approved LI.FI Brand Book (Figma `Sa2BL51sITY5vsfq8AXnQu`, FINAL deck — Core colours node `508:2`, Typography `531:67/106`). Five colours: **Sapphire `#405CCF`** (action — links/CTAs/data, ~30%) · **Pink `#F7C2FF`** (signature, ≤10%) · **Ink `#0C0E2E`** (surfaces + text, ~60%) · **Paper `#FAFBFF`** (light surface) · **Slate `#5C6070`** (secondary text on light). Typography **Geist + Geist Mono**. (June 2026 — this approved refresh became THE brand and the default; it supersedes BOTH the legacy blue/Figtree direction AND the interim cobalt "LI.FI 2.0" review preset `lifi-classic` — both retired. The book refined the action colour cobalt `#3B43D6` → Sapphire `#405CCF`.)
**Token names track the palette (renamed June 2026).** The brand-seed tokens are named for the official palette: `--lifi-sapphire` = **Sapphire** (primary), `--lifi-pink` = **Pink** (secondary, was Signal Pink), `--lifi-ink` = **Ink** (tertiary, was Midnight Ink) — mapped to roles via TC2's SEED_MAP. This replaced the prior misleading legacy names (`--lifi-blue` / `--lifi-teal` / `--lifi-pink`) in a single atomic Scheme-B sweep; the `--lifi-` brand-seed prefix is kept to distinguish seeds from role tokens (`--accent-*` / `--surface-*` / `--text-*`). The 9-step ramps stay `--midnight-*` / `--sapphire-*` / `--signal-*` — internal scale names, no product consumers yet.
- `--lifi-sapphire: oklch(52% 0.18 269)` (both modes) — Sapphire `#405CCF`. (June 2026: the dark lift L0.66→L0.52 was dropped so the filled-CTA label auto-flips to white AND passes AA on the dark page — white-on-L0.66 was 2.86:1, on native L0.52 it's 5.14:1. `--lifi-sapphire-mid` follows the seed at runtime (deriveTokens = seed+10L → L0.62 in both modes now; static dark literal lowered 0.76→0.62 to match, no FOUC); accent TEXT on the dark page stays AA at 5.16:1. The seed↔mid split is the lever for "white CTA label" vs "legible accent text on ink": both ride L0.52/L0.62 now and both pass AA.)
- `--lifi-pink: oklch(88% 0.1 322)` (both modes) — Pink `#F7C2FF`
- `--lifi-ink: oklch(66% 0.063 276)` (dark) / `oklch(24% 0.066 276)` (light) — Ink
- surfaces: **Ink dark page** (`oklch(18.5% 0.063 276)` ≈ `#0C0E2E`) / **Paper light page** (`oklch(99% 0.007 277)` ≈ `#FAFBFF` — lightened L98→L99 June 2026, designer call). The light **card** tier is fixed pure white (`oklch(100% 0.0021 277)`), so white cards lift ABOVE the pale-blue paper page via a 1% tonal step + shadow (the 2.0 model — page ≠ card in light). Hue ~276 (ink) / 277 (paper).
- text: **tinted opaque ladder** (the `text`-tint axis IS active on the default brand now — Slate `#5C6070` secondary on light; support tones `#A9AEDC` / `#6A70A0` on ink). This activates `check-theme-tokens.py` TC5 — the `--text-*` literals are the tinted derivation, not neutral-alpha.
- **Official 9-step ramps (June 2026)** — the three brand colours also exist as full hand-tuned scales in `styles.css :root`: **`--midnight-1…9`** · **`--sapphire-1…9`** · **`--signal-1…9`** (the exact 2.0 Brand Book hexes, Figma `409:75`, converted to OKLCH; anchors coincide with the seeds — sapphire-6 = `--lifi-sapphire`, signal-2 = `--lifi-pink`, midnight-9 = Ink). They are **static LI.FI-1.0 constants** (NOT `deriveTokens`-derived, NOT per-brand) — naming deliberately avoids the neutral `--ink-0…900` alpha ladder. Documented in `brand-guide.html #color` (ramp displays + the surface scale) and synced to the Figma **Foundation 2.0 [Library]** colour collection. No product consumers yet (a tints/shades layer is an opt-in follow-up); reach for them when a brand tint/shade is genuinely needed rather than hand-mixing.
**The brand book rendering.** `design-system/brand-guide.html` is the themeable LI.FI Brand Book — a rebuild of the Figma FINAL deck, wrapped in `[data-palette-canvas]` so the Theme Composer can re-skin it; pinned to light mode (a brand book is a fixed paper-and-ink DOCUMENT artifact — the `.doc-*` light-pin precedent), so the composer switches the *palette*, never the mode. It renders the default brand by default. The Figma colour sync (`lifi-figma-color-sync` → `export-color-tokens.mjs`) was re-run June 2026 for the new default + the 9-step ramps → the **Foundation 2.0 [Library]** mirror is current (70 tokens). Still tracked: the deep design.md §02 color-chapter rewrite to the new brand (use-case signals, brand gradient, spectral anchor, two-layer system); and the Brand Book file's own self-contained local colours collection isn't re-synced yet (only the Foundation Library was).
NO OTHER preset is ever auto-applied — LI.FI 1.0 (`lifi-1`), Jumper, partners, competitors all stay *selectable only* via the **Theme Composer**, as in-session changes. The page never starts with a non-default preset on load, regardless of what's in localStorage.
**Why this rule.** The brand must look the same to every visitor on every load. Auto-restoring a composer pick from localStorage (a) flashes the page default → picked theme (FOUC), and (b) makes the brand silently shift for any visitor who once tried the composer. Both are unacceptable on a brand surface.
**Contributing.** When adding any palette-related code, follow these constraints:
- **CSS `:root` defaults must always be the DEFAULT_BRAND_ID preset's OKLCH values** (currently `lifi-1` rev 11 — `scripts/check-theme-tokens.py` TC2 enforces the seed mirror, TC5 the text-tint mirror, TC7 the font mirror). Don't introduce `--lifi-*` tokens that paint a different brand by default.
- **Don't read `brand-palette` or `active-theme` from localStorage in any pre-paint or DOMContentLoaded path** that mutates `:root` (these are the Theme Composer's keys, debranded June 2026 from `lifi-brand-palette` / `lifi-active-preset` — migrated on read). The composer's `applyPresetById` is the only function that should mutate `:root` style — and it only fires on user click.
- **Don't add stylesheets that redefine the brand palette** (e.g., the retired `lifi-design-system.css` that flashed 2.0 hex values before `styles.css` cascaded). One cascade source = `styles.css`.
- **Don't add a "remember and restore" feature for the composer without explicit brand-review approval.** The current behaviour — composer change applies in-session, doesn't survive reload — is the correct default per this rule.
**Where the rule is enforced.**
- `styles.css` `:root` block — DEFAULT-brand OKLCH values (search `--lifi-sapphire:` for the canonical block).
- `shared.js` bootstrap IIFE — sets `data-theme` only; explicitly does NOT read `brand-palette` from localStorage.
- `shared.js → initBrandPalette()` — always starts from `DEFAULT_PALETTE` (single-sourced from `DEFAULT_BRAND_ID` = `'lifi-1'`); the saved palette in localStorage is never auto-applied. Additionally (June 12 2026) it RESETS `active-theme` to `DEFAULT_BRAND_ID` on every load — `active-theme` is written by every pick (sitewide AND canvas-scoped) but nothing re-applies it, so a persisted pick would make every composer/rail active-highlight lie about what's rendered (the bug the June 11 flip exposed: the rail highlighted LI.FI 1.0 while the page rendered the 2.0 default).
- `presets.js` — `lifi-1` carries the canonical default seeds (rev 11: Sapphire action / Pink signature / Ink fields / Paper light surface, Geist + Geist Mono, text-tint + semantics axes). The legacy blue/Figtree `lifi-1` and the cobalt `lifi-classic` "2.0" preset were both retired June 2026.
- `design.md §02 → "LI.FI 1.0 is the only default"` — full spec with the bug-history that prompted this rule (the no-auto-apply machinery; the section predates the June 2026 default flip).
### Jumper sibling brand — inside the DS until the formal split, three differentiation levers
Jumper (jumper.xyz, the consumer-app sibling) lives **inside this design system** — same components, same dev + design resources — until the brands formally split (months out, June 2026). Differentiation is exactly **three levers**; everything else is shared:
1. **Theme presets** — `jumper-1` / `jumper-2` in `presets.js` (selectable, never auto-applied; the LI.FI-1.0-default rule above is unaffected).
2. **Logo brand tokens** — `--jumper-indigo` (logo body + wordmark: `#31007A` light / `#653CA2` dark) + `--jumper-purple` (accent spark + lockup label: `#8700B8` light / `#B49BDA` dark), defined in `styles.css` (`:root` dark + `[data-theme="light"]`), mode-paired to Jumper's own published tokens. **These are brand CONSTANTS, not composer accents** — never wire logo fills to `--accent-*`, and never bake the hex into a consumer (the literals live only as `var()` fallbacks inside the asset files so `![]()
`/downloads stay brand-correct). **One deliberate exception — the playground site-PREVIEW host nav (June 2026):** that Jumper mark is a *mockup* showing the widget under a themed host site, so it FOLLOWS the active theme (spark → `--accent-primary`, body → `currentColor`/`--text-primary`) and re-tints with the canvas. The rule still holds for every SHIPPING surface — the `logos/jumper/*.svg` assets, `.brand-lockup`, and downloads keep the `--jumper-*` constants. The carve-out is scoped to the inline preview SVG only (`playground.html` + the `#host-nav` catalog preview); spec: `design/components/navigation.md → Host nav`.
3. **Typography** — `--font-jumper` (Urbanist; same fallback stack as `--font-sans`). The swap happens at the **brand-surface level**, never per-component; type scale, weights, tracking, and `--font-mono` stay shared. **Pages consuming the token statically must load Urbanist themselves** (Google Fonts `family=Urbanist:wght@300..900` — currently `design-system/foundations.html` + `assets.html`); unloaded pages silently fall back to system sans. **The Site-preview host nav no longer pins `--font-jumper` (June 2026)** — its tabs are seg-items reading `--font-sans`, so the bar's font (like its colours + logo) follows the active theme; the standalone `.host-nav--jumper` font pin + its `initRailNavPreview` `ensureFontLoaded('urbanist')` lazy-load + the `index.html` static Urbanist `` were all retired (atomic, the pin was inert once the tabs became seg-items). **Applying a Jumper THEME paints the brand's in-widget UI font via the Theme Composer's typography axis** (and needs no per-page load) — **both `jumper-1` and `jumper-2` carry `font: 'inter'`** (changed from Urbanist June 2026, designer's call, to match the official Foundation "Colors (Jumper)" widget mocks, which typeset their UI in the `UI (Inter)` styles — the canonical source); applying either lazy-loads Inter + paints `--font-sans` on the scope. **`--font-jumper` (Urbanist) is a SEPARATE concern** — the lockup / marketing constant, NOT the in-widget UI font; it stays Urbanist regardless of the preset's UI-font axis. (So picking a Jumper brand now renders the nav + widget UI in Inter; lockups always Urbanist.)
**Lockups compose the shared `.brand-lockup` primitive** + the `.brand-lockup--jumper` modifier, which owns exactly three label deltas (Urbanist · accent-2 colour · its own optical baseline nudge — the JUMPER wordmark's baseline sits at 18/25 of its box vs LI.FI's 36/48; see `bug-history.md → Lockup label "sits low"`). Don't fork further. Sub-products (JumperPass / JumperScan / JumperLearn) render as the JUMPER wordmark + a quiet label — never typeset the compound name as one wordmark.
**Where everything lives.** Assets: `logos/jumper/` (mark · horizontal · stacked; token fills with light-mode fallbacks) and `logos/lifi/` (monochrome `currentColor`). Catalog: `design-system/assets.html#brand-lockup` (both families, per-row + batch SVG export via `shared.js → initBrandLockupExport`'s per-brand `BRANDS` map) + `#logo-guidelines` (the formal brand-book layer: clear space ½H, minimum sizes 16/20/48px, colour application — values are proposed defaults pending designer ratification). Typography: `design-system/foundations.html#jumper-typography` (incl. the shared-vs-differentiated brand-overlap contract table — the extraction checklist for the eventual split). Spec: `design/components/imagery.md → Brand lockup`.
### Audience priority — Designers > Engineering > Marketing
The design system has a fixed audience ordering, and every visual / editorial decision answers it:
1. **Designers** — primary. They scan the catalog by *variant name* and a glance at the live preview. They want to recognise components instantly without reading prose.
2. **Engineering** — secondary. They arrive with the component name in mind and click into Markup / Specs / Source for implementation detail.
3. **Marketing** — tertiary. They use the catalog as a brand reference (button style, accent treatment, palette).
(AI scrapers parse the DOM directly — they're served by structure, not visual hierarchy.)
When a question comes up — "should this be bigger / brighter / more compact / more verbose?" — answer it from the designer's perspective first, the engineer's second, the marketer's third. Drift comes from optimising for engineering convenience (more tables, more code blocks, more prose) at the cost of designer scanning speed.
The visual hierarchy on every `.ds-doc-card` card reflects this: the **variant name** (`.ds-doc-card__label`) is the dominant element (h3-scale, sans, primary text colour), the caption is the supporting line (sm, muted), and the engineer-facing detail (Markup / Specs / Anatomy / Rules / Source) sits behind a tab strip on the same frame. Full rationale in `design.md §13 → Audience priority`.
### Visual separation between sections, components, variants — automatic
Three nested layers, each with its own separation recipe. **Don't author dividers, `
`, or extra spacers between cards** — the CSS handles every layer. | Layer | Markup | Separation | | --- | --- | --- | | **Section** (Buttons / Cards / Forms / …) | `` | 240 px section padding (already strong) plus an optional `.section-divider`. |
| **Component group** (within a section — *Primary actions* / *Secondary actions*) | `
`, or extra spacers between cards** — the CSS handles every layer. | Layer | Markup | Separation | | --- | --- | --- | | **Section** (Buttons / Cards / Forms / …) | `
…
` | Quiet uppercase-mono eyebrow with a hairline rule above. Use only when a section genuinely splits into named groups. | | **Variant card** (each `.ds-doc-card`) | `` | 80 px gap + 1 px hairline divider between adjacent cards. Driven by `.ds-doc-card + .ds-doc-card`. |
The variant-card divider is the one that matters most — long sections like `#buttons` (5–10 cards) used to feel like cards merged into each other. The 80 px gap + hairline gives an unmissable boundary without heavy chrome.
If two adjacent cards still feel merged, check they're direct siblings — the `+` combinator is direct-sibling-only. Mobile drops the gap to 48 px; print collapses the divider; the CSS handles those breakpoints. Full rationale in `design.md §13 → Visual separation` and the comment block above `.ds-doc-card + .ds-doc-card` in `styles.css`.
### Section chaptering & auto-TOC — when a section grows past ~6 cards
Heavy sections (currently `#inputs`, `#cards`, `#hero`, `#chips`, `#authoring-guide`) are **chaptered** with `` markers placed as direct children of the section's `.container`. The auto-TOC (`shared.js → initDsSectionTocs()` + `.ds-doc-section-toc` in `styles.css`) renders a horizontal chapter strip at the top of any section with 2+ such markers and scroll-spies as the reader scrolls.
**Authoring contract — when adding a new card:**
- **If the target section is chaptered**, pick the chapter before authoring and place the card after that chapter's marker (and before the next chapter's marker, if any). Today's chapter ids:
- `#inputs` → `inputs-text` · `inputs-sizes` · `inputs-modifiers` · `inputs-selection` · `inputs-composition`
- `#cards` → `cards-stat` · `cards-feature` · `cards-specialised` · `cards-behavior`
- `#hero` → `hero-anatomy` · `hero-variants` · `hero-composition`
- `#chips` → `chips-pills` · `chips-delta` · `chips-themed`
- `#authoring-guide` → `auth-skill` · `auth-audience` · `auth-typography` · `auth-panes` · `auth-structure` · `auth-chrome`
- **If the section isn't chaptered yet but has more than ~6 cards** after your addition, chapter it in the same edit. The validator warns (W009) when a section has 7+ cards and 0 chapters — heed the warning. Authoring guide is in `references/procedure.md → Adding chapters to a growing section`.
- **Never add a one-off chapter to fit a single new card.** Refine the card's scope to fit an existing chapter, or wait until at least two cards share the new theme before adding a chapter.
Chapter ids must follow `