@koda-sl/baker-cli 0.217.0 → 0.224.0

package/README.md

@@ -5511,18 +5511,31 @@ Output is the standard envelope `{ ok, data, hints }` with `data = { advisory, s
 Verifies that a brand's typefaces really load, and self-hosts them. A font that isn't actually available never announces itself — the browser substitutes its nearest fallback, so the page renders fine and is quietly off-brand. Reading a family name off a live site tells you what the CSS *asks for*, never what loads.
 
 ```bash
-baker brand fonts check                                    # are the brand's fonts real?
+baker brand fonts check                                    # does every brand face actually load?
+baker brand fonts adopt                                    # a page already loads it? move it into global.css
 baker brand fonts fetch "DM Sans"                          # self-host, weights taken from global.css
 baker brand fonts fetch "Manrope" --weights 500,700        # self-host specific weights
 baker brand fonts fetch "Inter" --subsets latin,latin-ext  # add accented-glyph coverage
 ```
 
-- **`check`** asks Google Fonts what it *actually* serves for every family and weight `src/styles/global.css` requests, and reports `requested` / `served` / `missing` plus the available unicode subsets. It exits 2 with `FONT_NOT_SERVED` when the brand asks for something Google won't serve, and distinguishes an unknown family name from a family that exists at other weights — the fix differs.
+- **`check`** runs two checks in order. First, every `--font-*` family in `src/styles/global.css` must be provided by an `@font-face` or a Google import; a family provided by nothing exits 2 with `FONT_NOT_LOADED` and lists them at `error.fix.unresolved`. Then, for the families requested from Google, it asks Google what it *actually* serves and reports `requested` / `served` / `missing` plus the available unicode subsets, exiting 2 with `FONT_NOT_SERVED` when the brand asks for something Google won't serve — distinguishing an unknown family name from a family that exists at other weights, since the fix differs.
+- **`check` used to pass on the worst case.** With no Google `@import` it answered `selfHosted: true` without looking at whether anything hosted the font, so a stylesheet declaring `--font-sans: "Inter"` and loading nothing was reported healthy. Measured across the client fleet, 56 of 60 repos have no Google import, so that was the answer almost everyone got; the only thing that caught it was the scaffold validator at verify time.
 - **Failures carry the numbers, so nothing needs a second call.** `check`'s error keeps the full per-family breakdown at `error.fix.families` (healthy families included, so a multi-family brand shows what not to touch), and both commands probe the standard weights to report the ones that *do* exist at `error.fix.served` — the remediation is "retry with one of these" rather than "run `check`", which would be the command that just failed.
-- **`fetch`** downloads the family into `src/brand/fonts/` and prints the `@font-face` block to paste above `@theme`. Defaults to the `latin` subset; `--subsets latin,latin-ext` adds accented-glyph coverage for Spanish and Portuguese copy. One file per weight *and* subset, since Google ships them separately and `unicode-range` is carried through verbatim.
-- **It does not edit `global.css` for you.** Paste the block, then drop that family from the Google `@import` — otherwise the page self-hosts *and* still calls Google. Record the weights in `src/brand/BRAND.md` in the same change.
-- **The emitted `src:` is relative to `global.css` (`../brand/fonts/…`) on purpose — keep it that way.** A root-relative `/src/brand/fonts/…` reads to the bundler as a path something else already serves, so the file never lands in the published build and every page 404s it. That failure is silent: an unfetchable face falls back to a system font, so the site just renders off-brand. Kept relative, the bundler resolves it on disk, content-hashes it, and ships it. The scaffold's `validate-public-asset-refs` blocks the root-relative form.
-- **Licensing:** Google Fonts are open-licensed and safe to self-host. A client's own commercial typeface is not — confirm before re-hosting one.
+- **`fetch`** downloads the family into `src/brand/fonts/` **and writes its `@font-face` into `global.css` above `@theme`**, so the family loads without a second step. It is idempotent — re-running replaces that family's faces rather than stacking duplicates — and it leaves other families, any commented-out block, and any face it cannot itself write untouched. Defaults to the subsets the family already self-hosts, else `latin`; `--subsets latin,latin-ext` adds accented-glyph coverage for Spanish and Portuguese copy. One file per weight *and* subset, since Google ships them separately and `unicode-range` is carried through verbatim.
+- **A re-run keeps the weights and subsets the stylesheet already self-hosts.** `fetch` puts the downloaded faces *in charge* of the family, so it has to know which weights already exist — and the first fetch is what removes the Google `@import`, leaving the stylesheet's own `@font-face` rules as the only surviving record of them. It reads those. Passing `--weights` on a re-run therefore **narrows** the family to exactly what you passed: every other weight is dropped from the stylesheet and its file orphaned, with nothing failing, because the family stays resolved either way. A variable face declared as a range (`font-weight: 100 900`) counts as every step in that range, not as its first number — read as `100` alone, a re-fetch replaced the whole range with a single hairline rule. `--subsets` works the same way and for the same reason: the default is what the family already self-hosts (read back from the file names `fetch` wrote), so a bare re-run after `--subsets latin,latin-ext` no longer drops the latin-ext face and leaves accented copy on a fallback.
+- **`--italic` self-hosts the family's italic too, and a stylesheet that already loads one turns it on by itself.** There is deliberately no `--no-italic`: `--weights` and `--subsets` narrow because a brand really does drop a weight, but narrowing an italic away is the silent loss this path exists to prevent — delete the rule if you mean it. A face `fetch` cannot write is never deleted either, so a hand-made `oblique` survives untouched.
+- **It always asks the catalogue about italic, and says what it found.** The request costs the same either way, so when a family ships an italic the brand did not take, that goes in the hints — and when you ask for one the catalogue does not ship, that goes in the hints too, instead of reading as success while the browser slants the upright face. Which styles landed comes back as `data.styles`.
+- **Drop the family from the Google `@import` afterwards** — otherwise the page self-hosts *and* still calls Google. Record the weights in `src/brand/BRAND.md` in the same change. (`fetch` used to only print the block for you to paste; the download happened either way, so a skipped paste left the files on disk with nothing loading them. One client repo had 44 font files and zero `@font-face` rules.)
+- **The written `src:` is relative to `global.css` (`../brand/fonts/…`) on purpose — keep it that way.** A root-relative `/src/brand/fonts/…` reads to the bundler as a path something else already serves, so the file never lands in the published build and every page 404s it. That failure is silent: an unfetchable face falls back to a system font, so the site just renders off-brand. Kept relative, the bundler resolves it on disk, content-hashes it, and ships it. The scaffold's `validate-public-asset-refs` blocks the root-relative form.
+- **`adopt`** moves brand faces a page already self-hosts into `global.css`. A `--font-*` token in `@theme` is global, but a page's own `<style>` ships only with that page — so one page declaring the face leaves every other page on a fallback, which is invisible unless you happen to load one of them. It never downloads: re-fetching the same family would hand the working page a different build of the face. Refuses a family that two files declare differently (`ADOPTION_CONFLICT`) and one whose files are not in `src/brand/fonts/` (`FONT_FILE_MISSING`); `NOTHING_TO_ADOPT` means no page declares it at all, and that one is genuinely a `fetch`.
+- **`check` tells you which of the two to run.** Its `error.fix.action` says `adopt` when a page already self-hosts the family and `fetch` when nothing does — worth following, because reaching for `fetch` on a face the repo already ships is the exact substitution `adopt` exists to prevent.
+- **The scaffold sync adopts too, unattended.** The `2026-08-20-wire-unresolved-brand-fonts` migration runs the same planner at the front of every sync, before it asks any catalogue, so a client whose brand face lives in one page's `<style>` is repaired without anyone opening a Session. It diverges in one place: a conflict there falls through to downloading rather than refusing, because refusing would leave that client frozen out of every future scaffold update with nobody watching to reconcile it. It draws the Google-outage line in the same place, and has to: an unreachable catalogue is reported as *retryable*, which is what stops the migration runner recording — and so permanently disabling — a repair that only hit a bad minute.
+- **Two catalogues, Google first.** `fetch` resolves against Google Fonts, then Fontsource — which carries open-licence families Google does not (Open Sauce One, and ~2000 more). Google wins a family both carry, so a re-run can never swap which foundry's file the brand ships; the winner is reported as `data.provider`. When no catalogue has the name, the error carries `fix.didYouMean` — a client asking for "Open Sauce" gets back One / Sans / Two rather than a dead end.
+- **Google refuses a request only when EVERY tuple in it is missing.** Measured, not assumed: `Lato:wght@400;500` answers **200 with 400 alone** — the missing weight is silently dropped, not rejected — while `Lato:wght@500` on its own is a `400`. So a refusal is true both of a name Google has never heard of *and* of a family asked for at weights it does not ship, and one rejection cannot mean "try elsewhere": read that way, `fetch "Lato" --weights 500` self-hosts Fontsource's Lato. On a refusal the command re-asks Google **once, for all nine standard weights**, and if the family exists at any of them it fails `FONT_NOT_SERVED` with `fix.served` rather than switching foundry. Note Google's API is **case-sensitive** (`family=roboto` → 400, `family=Roboto` → 200), so a mis-cased name is one of the ways a Google family ends up being looked for elsewhere.
+- **That probe is one request, and it matters that it is.** It used to fan out nine concurrent requests per family, on the belief above. Google answers a rapid series of requests with **`400`** — indistinguishable from "does not carry it" — so a three-family brand firing 27 requests could be told a real family is unknown, and act on it by self-hosting another foundry's build. The same fan-out ran unattended in the scaffold's wiring migration, where the substitute gets committed to the client repo.
+- **An unanswered catalogue is never a verdict, on either of them.** A lookup that times out or 5xxs fails `CATALOGUE_UNREACHABLE` (with `fix.provider`) and asks you to re-run, instead of self-hosting a different foundry's build on the strength of one failed request. That holds for Fontsource too: only its `404` means "no such family", so an outage there can no longer surface as "no font catalogue carries a family called X" — advice that would send you to check the spelling, or to hand-write an `@font-face` for a face Fontsource has.
+- **Multi-subset Fontsource families need the API's `unicode-range`, and get it.** Two `@font-face` rules with the same family, style and weight and no range both claim every character, so the later silently wins and the other file is downloaded, fingerprinted, shipped and never read. The ~120 families Fontsource hosts itself are single-subset with no range (nothing to disambiguate); the ~1976 it mirrors from Google are multi-subset and carry the map, which `fetch` now emits. If a multi-subset family ever reports no range, `fetch` fails `SUBSET_AMBIGUOUS` rather than writing two rules that cannot both apply.
+- **Licensing:** Google Fonts and Fontsource carry open-licensed families, safe to self-host. A client's own commercial typeface is not — confirm before re-hosting one.
 
 Complements the offline `validate-brand-fonts` check that runs in the scaffold's `verify`: that one compares what `global.css` declares against what provides it, with no network. Only the network can answer whether Google really serves a given family and weight.