release(3.2.0.0): the refactor release — 466 lines lighter, a design system that can be seen, a build that runs

Six days since 3.1.0.2: 31 non-merge commits, 133 files, +7,395/-1,041.
Major bump rather than minor, calibrated against 3.0.1.0 → 3.1.0.0 ("the
multi-tenant + tested milestone") — comparable scale, and this one removes a
build tool and adds two packages.

Release narrative at changelog/releases/v3.2.0.0.md, the first entry in that
folder. It aggregates four changelog entries and follows the audience cascade:
what changed and why it matters up top, the map's own errors and the
checkers-that-were-not-checking further down, upgrade notes with the three
things that need doing, and the story last.

Also writes the changelog entry that was missing. 2026-08-08_01 covered the
NATS outage and five commits shipped after it with nothing recorded — the
design system landing, the drift-parser fix, the swatch page, the Developers
menu, and mounting the portal in the shell. That arc is now
2026-08-08_02, and the release aggregates a complete log rather than one with a
hole in it.

The release notes are deliberately honest about what this release corrected in
our own beliefs rather than only what it added: the frontend had no duplicate
CSS and a harder problem; the design system was blocked on a laptop rather than
a decision; drift was 98 findings and not 18; the corpora were never missing.
Every one of those was a belief that could have been held indefinitely without
contradiction, which is the thread the story section pulls on.

Blake is credited in Thanks for Phases 0 and 1, and for the handoff document
whose named failure modes made three of this release's findings legible as
findings rather than noise — including the one that caught his own checker.

Files changed:
- changelog/releases/v3.2.0.0.md (new)
- changelog/2026-08-08_02_The-Design-System-Arrives-And-Gets-Looked-At-For-The-First-Time.md (new)
- package.json

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019a8tSPbFdvF1pKtADnWyDg

Author: mpstaton

changelog/2026-08-08_02_The-Design-System-Arrives-And-Gets-Looked-At-For-The-First-Time.md

@@ -0,0 +1,98 @@
+---
+date_created: 2026-08-08
+date_modified: 2026-08-08
+title: "The design system arrives — and gets looked at for the first time"
+lede: "Thirty-five design tokens had been verified by arithmetic and never once rendered. We built the page that renders them, and it found three bugs in itself and three in the theme before it had been open a minute."
+publish: true
+authors:
+  - Michael Staton
+  - Steven Blake Casio
+augmented_with:
+  - Claude Code on Claude Opus 5
+files_changed:
+  - packages/theme/theme.css
+  - scripts/design-drift.mjs
+  - apps/docs-portal/src/App.svelte
+  - design-manifest.json
+  - shell/src/DevelopersMenu.svelte
+  - shell/src/App.svelte
+tags:
+  - Augment-It
+  - Design-System
+  - Design-Tokens
+  - Accessibility
+  - Module-Federation
+---
+
+# The design system arrives
+
+## Why Care?
+
+augment-it is seventeen micro-frontends that load into one shell. Seventeen surfaces, built one at a time, each of which invented its own greys. A design system is the fix, and ours had a real problem: it existed entirely as **documentation and arithmetic**.
+
+Thirty-five tokens. One hundred and eight contrast pairs computed. Eleven enforcement rules. And, by its own author's admission, *"not one change has been rendered in a browser."*
+
+That gap is now closed. The tokens are in the repo, there is a page that shows every one of them on every surface in all three modes, and it is one click from the shell header — signed in or not.
+
+## What's New?
+
+- **The token system landed.** Blake's Phase 0 and Phase 1 — the enforcement script, the colour tier, five accessibility fixes — merged from the laptop they had been stranded on.
+- **A design system viewer**, showing 30 colour tokens × 5 surfaces with live measured contrast, in dark, light and vibrant.
+- **A Developers menu** in the shell header, replacing a label that said `tiling host · :3100` and nothing else.
+- **The viewer opens inside the shell**, and works without signing in.
+- **A drift-checker bug fixed** that had been quietly reporting everything as fine.
+
+## The part where the checker wasn't checking
+
+Phase 0's whole point is `design-drift.mjs`: until it existed, the eleven design rules were prose. With the work merged, we ran it. **18 failures**, almost all "no per-member DESIGN.md", which is known Phase 8 work. Looked healthy.
+
+It wasn't. The member list is parsed out of DESIGN.md's frontmatter with a regex, and one capture group was greedy across a comma:
+
+```js
+// path: shell, prefix: shell, …   →   path === "shell,"
+entry.match(/…path:\s*(\S+)…/)
+```
+
+`shell,/src` is not a directory. So the file walker returned **nothing for all nineteen members**, and every check that inspects member files — hardcoded colours, raw z-indexes, illegal token usage — had nothing to look at and passed.
+
+The disguise was good. The one check still firing was the DESIGN.md one, which broke the same way, so it failed for everybody — and "no DESIGN.md at member root" reads as *we haven't done that phase yet*, not as *I am blind*.
+
+Real number, once fixed: **98**.
+
+Blake's own notes name this failure mode — *a checker reporting success because it failed to look* — and document two earlier instances he caught. This was the third.
+
+## What rendering found
+
+The viewer is deliberately shallow: one grid, one loop, its own chrome built only from design tokens so a broken token can't hide behind a colour the page smuggled in. It paints `color: var(--token)` over `background: var(--surface)` and measures the result **from what the browser actually painted**, not from what the stylesheet says.
+
+It found three bugs in itself, none of which a build or a typecheck could see:
+
+- **Every contrast number was blank.** Reading a token's value returns a hex string; the parser expected `rgb()` and silently matched the digits inside the hex.
+- **Every reading was taken mid-animation.** The theme transitions colour over 75ms on a mode swap, so measuring two frames later caught colours still moving. It reported the dark background as light grey and every vibrant token as failing.
+- **It cried wolf.** Grading all 150 cells produced 75 "failures" — the grid pairs every token with every surface, and most pairings the product never makes.
+
+And two where the page was wrong about the theme rather than the other way round: `--color-thread` graded as text when the spec calls it a line, and `--color-on-accent` graded against surfaces it never touches. It now has its own section testing it on the accent fills, where it passes comfortably — 5.19 to 14.11.
+
+Then, once it was honest, three findings in the theme itself:
+
+| Finding | |
+|---|---|
+| `--color-border` misses the 3:1 boundary bar on every surface, every mode | confirms a known open question |
+| `--color-thread` carries the border value, so the chat rail is below it too | **not previously recorded** |
+| `--color-border-strong` fails on all five surfaces in **light** mode | **contradicts a documented fix** |
+
+That last one matters. The border question was deferred as a brand decision because changing it changes the look of everything — and `--color-border-strong` was the compliant escape hatch you reach for when a boundary must actually meet the bar. If it doesn't clear 3:1 either, there is no escape hatch.
+
+## Under the hood
+
+The viewer is a federated remote that also runs standalone. The two entries differ on purpose: mounted in the shell it loads only the token floor, because the shell is the canonical injector and supplies all three mode blocks; standalone it loads the full theme, because there is no shell to inherit from and a one-mode swatch page would be pointless.
+
+Its token list is generated from the stylesheet rather than hand-kept, with a check that fails if the two drift apart. That check earned itself immediately: merging Phase 1 changed the theme, and it caught the staleness before anything else did.
+
+It renders **outside the sign-in wall**. Brand guidelines and a token contract are not client data, and gating them costs a developer the one reference they need while debugging a themed surface — including the case where what's broken is why they can't get past the wall.
+
+## What's Next?
+
+The numbers now say what to do. The border tokens need a brand decision, and it is a narrower decision than it looked: not "what colour is our border" but "what is the compliant line, given the one we designated does not clear the bar in light mode."
+
+And with a surface to look at, Phase 2 can finally pick typography, spacing and radius **by eye** — which was always the only way to pick them.

changelog/releases/v3.2.0.0.md

@@ -0,0 +1,184 @@
+---
+date_created: 2026-08-08
+date_modified: 2026-08-08
+title: "augment-it v3.2.0.0 — the refactor release: 466 lines lighter, a design system that can be seen, and a build that runs"
+lede: "Six days, 133 files, and the first refactor this codebase has ever had. Seventeen micro-frontend mount files became one, the design system stopped being arithmetic and became a page you can look at, and `pnpm build` works for the first time in the repo's history."
+publish: true
+authors:
+  - Michael Staton
+  - Steven Blake Casio
+augmented_with:
+  - Claude Code on Claude Opus 5
+release_version: "3.2.0.0"
+previous_version: "3.1.0.2"
+files_changed:
+  - packages/federation/src/index.ts
+  - packages/theme/theme.css
+  - packages/theme/token-baseline.css
+  - apps/docs-portal/src/App.svelte
+  - scripts/design-drift.mjs
+  - scripts/generate-token-baseline.mjs
+  - services/record-surrealdb-resolver/src/nats-loop.ts
+  - shell/src/DevelopersMenu.svelte
+  - tsconfig.base.json
+  - design-manifest.json
+tags:
+  - Release
+  - Augment-It
+  - Refactor
+  - Design-System
+  - Module-Federation
+  - Resilience
+---
+
+# augment-it v3.2.0.0 — the refactor release
+
+- [Why Care?](#why-care)
+- [What's New?](#whats-new)
+- [How it works](#how-it-works)
+- [Under the hood](#under-the-hood)
+- [Upgrade notes](#upgrade-notes)
+- [The story behind this release](#the-story-behind-this-release)
+- [Thanks](#thanks)
+
+## Why Care?
+
+augment-it got built the way real products get built: seventeen micro-frontends and eleven services, one at a time, each correct on its own, none of them looking sideways at the last. That is the right way to move fast, and it accrues a specific kind of debt — not bugs, but **repetition with no home**.
+
+This release is the first time we stopped and paid some of it down. Not by guessing where the mess was, but by building a map of the codebase and then checking every candidate it surfaced against the actual files.
+
+The headline is that **466 lines net went away** while the app gained a design system, a resilience fix, and a root build command that runs. The more useful outcome is that we now know which of our assumptions about this codebase were wrong.
+
+## What's New?
+
+### Highlights
+
+- **The design system is real and visible** — 35 tokens, three modes, and a page that renders every one of them on every surface with live measured contrast. One click from the shell header, signed in or not.
+- **Seventeen mount files became one.** Eleven of them differed by exactly one line.
+- **`pnpm build` works** for the first time in this repository's history.
+- **A whole request channel can no longer be killed by one bad message** — the bug that made a client's research corpora appear to vanish.
+- **Design tokens now have a floor**, so a micro-frontend deployed ahead of the shell degrades to something legible instead of rendering invisible text.
+
+### Added
+
+- `@augment-it/federation` — the one copy of the mount glue every remote used to keep its own version of.
+- `apps/docs-portal` — the design system viewer, on `:3020` standalone and mounted in the shell as a federated remote.
+- A **Developers menu** in the shell header: the design system, which services this build points at, and one click to copy the full environment for a bug report.
+- `design-manifest.json` and `packages/theme/token-baseline.css` — both generated from the stylesheet, with `pnpm tokens:check` to fail CI if they drift.
+- `scripts/design-drift.mjs` — the enforcement engine that turns eleven design rules from prose into checks.
+- Regression tests for three failure modes the existing suite structurally could not reach.
+
+### Changed
+
+- The shell is the canonical injector of design tokens; members carry a floor rather than a copy of the theme.
+- App TypeScript configs converge on one shared base — three drifted variants became one, 20 lines to 4 per app.
+- The design system renders **outside the sign-in wall**. Brand guidelines are not client data.
+
+### Fixed
+
+- **`domain.list: timeout`** — one unanswerable message could take a NATS subject down for the lifetime of the process, silently, with nothing in the logs.
+- **The shell's typecheck had never passed.** A missing CSS shim, compounded by a config that would have ignored the shim anyway.
+- **The drift checker was blind.** A greedy regex meant every per-file design check inspected nothing and passed. Real failure count: 98, not 18.
+- Five accessibility fixes from Phase 1, including a light-mode focus ring that was invisible.
+- The one import cycle in the codebase.
+
+### Removed
+
+- **Turbo.** Not a dependency, never installed, and orchestrating a task graph with zero edges.
+- **React.** One config line, in a codebase where React is prohibited, with no `.tsx` files and no `react` dependency.
+- ~250 lines of verified dead code.
+
+## How it works
+
+### Sharing code without losing autonomy
+
+The instinct that sharing code costs a micro-frontend its independence is sound, and in this architecture it happens to be wrong — for a specific, checkable reason. The federation host declares no `shared` block, so a workspace import is **inlined into each remote's own bundle at build time**.
+
+> **Build-time import *is* the copy.** One source of truth in the repo, seventeen independent artifacts.
+
+Every remote still boots with every other remote down. We verified it rather than asserted it: one app's built stylesheet is **byte-identical** before and after the change, same content hash.
+
+The real cost is not runtime coupling, it is **redeploy fan-out** — which yields the rule we now package by: split shared packages by *change frequency*, not by topic.
+
+### The token floor
+
+A micro-frontend deployed against a token the deployed shell does not have yet used to resolve to **nothing** — text inherits, backgrounds go transparent. Invisible locally, because your machine always has the latest theme.
+
+Every token is now registered with an initial value, so the worst case is a legible dark surface. Measured in a browser, three ways:
+
+```
+healthy (shell + member)      tokens resolve to the shell's values, all modes distinct
+degraded (member alone)       #e8eaf0 on #13151b — 15.17:1 contrast
+counterfactual (no floor)     rgb(0,0,0) on transparent  ← the bug, reproduced
+```
+
+The third line is why we trust the second.
+
+## Under the hood
+
+### What the map got wrong, and what it got right
+
+We built a knowledge graph over 490 source files — 4,330 nodes, 6,011 edges, for zero tokens, because code parses structurally. It pointed at the right places. It was not always right about them.
+
+**It was right** that eleven of seventeen mount files differed by one line, that ~250 lines were unreachable, and that there was exactly one import cycle.
+
+**It was wrong**, or at least incomplete, about two things worth remembering. Two components looked dead and were not — they are imported through package subpath exports that static analysis cannot follow. And it reported three functions sharing a name when there were five: god-node rankings show the top of a distribution, not a census.
+
+Everything deleted in this release was confirmed by hand afterwards.
+
+### The assumption that turned out to be backwards
+
+We expected the frontend to be full of copy-pasted CSS waiting to be deduplicated. Of **1,392 distinct selectors** across 5,434 lines, **1,386 are unique to a single app**. The six shared ones are keyframe stops and media queries.
+
+There is almost nothing to deduplicate. There are seventeen independently invented vocabularies that have never had to agree. That reframes the component library from consolidation into **greenfield extraction plus migration** — better to know before starting than after.
+
+### Checkers that weren't checking
+
+Two instruments in this release reported success because they failed to look, and both were caught only by someone asking "that number seems wrong."
+
+The design drift checker parsed its member list with a greedy regex, captured a trailing comma into every path, and so inspected zero files across all nineteen members. Its only visible symptom was a failure that looked like known outstanding work.
+
+The design system viewer, on first render, measured every colour mid-transition and reported the dark background as light grey.
+
+Neither was catchable by a build or a typecheck. Both were caught by rendering the thing and looking at it.
+
+## Upgrade notes
+
+**Root build command changed.** `turbo.json` is gone; root scripts use pnpm's own recursive runner. Nothing downstream breaks — every Dockerfile already bypassed turbo with direct `pnpm --filter` calls.
+
+```diff
+- "build": "turbo run build"     # turbo was never installed; this always failed
++ "build": "pnpm -r build"
+```
+
+**New deploy variables** for the design system portal, both falling back to localhost until it has a hosted home:
+
+```
+PUBLIC_DESIGN_SYSTEM_REMOTE   # federated remoteEntry.js the shell mounts
+PUBLIC_DESIGN_PORTAL_URL      # standalone page
+```
+
+**If you have a dev server running**, restart it. Adding a workspace dependency does not reach a live rsbuild process, which holds its module-resolution graph from startup and will report `Can't resolve '@augment-it/federation'` until restarted.
+
+**Regenerate after touching the theme.** `packages/theme/theme.css` is now the source for two generated artifacts:
+
+```bash
+pnpm tokens:baseline    # regenerate
+pnpm tokens:check       # CI: fail if stale
+```
+
+## The story behind this release
+
+This release started as a request to understand a codebase before refactoring it, and most of what it produced was corrections to things we believed.
+
+We believed the frontend was full of duplicate CSS. It has no duplicate CSS and a much harder problem. We believed the design system was blocked on a decision. It was blocked on a laptop. We believed drift was down to 18 findings; it was 98 and the checker was broken. We believed a client's corpora had failed to load; they had never been anything other than fine.
+
+The pattern across all of them: **every wrong belief was one someone could have held indefinitely without contradiction.** The corpora looked missing. The checker looked clean. The build looked like it worked because nobody ran the root command. Each was only dislodged by measuring the specific thing rather than the thing next to it.
+
+The other pattern, less comfortable: nearly everything completed in this release was verifiable mechanically. Builds, typechecks, tests, contrast ratios. The work that remains — a component library, an improved UI — needs someone to look at the product and have an opinion. That is not a coincidence, and no amount of tooling closes it.
+
+Which is the real reason the swatch page matters more than its size suggests. It is not much of a page. It is the first surface on which anyone can have an opinion about this design system, and until it existed there was nothing to have an opinion about.
+
+## Thanks
+
+**Steven Blake Casio** built Phase 0 and Phase 1 of the federated design system — the enforcement script, the colour tier, the contrast work that took light mode from 103 to 108 passing pairs, and the accessibility fixes that came with it. His handoff document is also the reason three of this release's findings were legible as findings rather than noise: it named the failure modes to watch for, including the one that caught his own checker.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "augment-it",
-  "version": "3.1.0.2",
+  "version": "3.2.0.0",
   "private": true,
   "packageManager": "pnpm@10.15.0",
   "workspaces": [