Keep README.md in sync with marketing + the workspace

README.md is hand-written prose that must not contradict the product. Several facts are machine-enforced by a guard; the rest is your judgment.

The guard

pnpm check:readme runs in pnpm validate, lefthook pre-commit, and CI's verify job. It chains two scripts (scripts/check-readme-parity.mts and scripts/gen-readme-metrics.mts --check) and fails the commit/build on any of four machine-checkable mismatches:

1. Tagline — the README's first blockquote must equal the marketing hero headline.
2. Monorepo layout — the ## Monorepo layout block must list every apps/* and packages/* member (each dir with a package.json), and nothing that no longer exists.
3. Metrics block — the generated <!-- METRICS:START … --> badge row must match a fresh render from its committed sources. Unlike 1 & 2, drift here is auto-fixed: just run pnpm gen:readme (then pnpm metrics to refresh the snapshotted health + coverage numbers).
4. Product promises — marketing claims from i18n.ts are verified against the code (LICENSE, the extension manifest + source, defaultSettings). A broken promise is NOT auto-fixable: pnpm gen:readme renders the ✗, but --check still fails until you restore the invariant — or update the promise/marketing copy if the product genuinely changed.

Sources of truth

README element	Canonical source
Tagline (blockquote)	strings.en.hero.headlineLine1 + ' ' + headlineLine2 in apps/marketing/src/i18n.ts
Monorepo layout	apps/* + packages/* dirs on disk
Feature claims, copy	docs/copy.md (voice + claims) and the marketing i18n.ts
Default behaviours	packages/settings/src/index.ts (defaultSettings)
Tech stack / deps	the actual package.json dependency trees
Metrics badges	pnpm gen:readme ← wxt manifest permissions + LICENSE (live); fallow health + Vitest coverage (snapshot via pnpm metrics)
Product promises	collectPromises() in gen-readme-metrics.mts ← marketing claims (i18n.ts) checked vs LICENSE, the extension manifest + source, defaultSettings

Procedure

1. Run pnpm check:readme and read exactly what it reports.
2. Tagline mismatch → set the README blockquote to the marketing hero headline verbatim. If design-brief.md's tagline diverges too, fix it in the same pass (it's the brand spec; not machine-checked).
3. Layout mismatch → add every missing apps/<x> / packages/<x>, drop any that no longer exist, and keep the comment column aligned.
4. Re-run pnpm check:readme until green.

Not machine-checked — eyeball these too

The guard can't catch prose drift. While you're in the README, confirm:

• Feature list matches reality. Off-by-default capabilities (e.g. contentModification in packages/settings) must say "off by default". Don't list features that were removed (the old "usefulness dashboard" was).
• Tech stack lists only real deps. If a library isn't in any package.json / lockfile (Tremor was a stale entry), drop it.
• Browser targets match the marketing download buttons (Chrome, Firefox, Edge, Opera, Brave, Safari).
• Claims match docs/copy.md — it's the copy authority.

Verify

pnpm check:readme is green, and pnpm exec prettier --check README.md passes.