@omega.js/web 0.1.0

package/docs/index.md

@@ -0,0 +1,254 @@
+# OMEGA Web (@omega.js/web)
+
+> **Note for contributors and Claude:** This file is the guide for `@omega.js/web` — identity, the module map, the command surface, and pointers to the deep references. It lives in the monorepo's `docs/` tree and is loaded on demand (the omega Claude plugin's hooks inject it by context; the repo-root AGENTS.md map is the one agent entry — packages carry no agent docs). The **meat** lives in the shared docs ([shared/](shared/)), the web deep references ([sections.md](sections.md), [frontmatter.md](frontmatter.md), [omega-sections-spec.md](omega-sections-spec.md), [template-kit.md](template-kit.md), [libs.md](libs.md), [ads-system.md](ads-system.md)), and [README.md](../README.md), which carries the long-form module/feature detail. Write new detail there and cross-link from here — do NOT inline it.
+
+> **Mirrored structure:** the four framework guides — `docs/web/index.md`, `docs/backend/index.md`, `docs/extension/index.md`, and `docs/desktop/index.md` — mirror each other (the legacy UJM/BEM/BXM/EM lineage): shared sections (Supply-Chain Security, Development Workflow, File Conventions, Doc-update parity, etc.) appear in the **same order at the same position** across all four. When adding a section that applies to multiple frameworks, insert it in the same spot in all of them. Each consumer template (`src/defaults/AGENTS.md`; web's lives at `scaffold/AGENTS.md`, beside its one-line `@AGENTS.md` `CLAUDE.md` pointer) mirrors its guide the same way.
+
+## Identity
+
+OMEGA Web (`@omega.js/web`) is the framework for building a brand's marketing site + authenticated frontend. It is the **UJM (Jekyll) successor, rebuilt — not ported**: Eleventy 3 + LiquidJS + [`@omega.js/template-kit`](../../packages/template-kit), with layered themes (zero copying), the section/component library, virtual default pages, the esbuild/sass/PurgeCSS asset pipeline, and an ESM boot runtime that hands every page the `@omega.js/client` singleton. It ships the `omega` CLI for the whole consumer lifecycle (dev → build → test → deploy) plus `omega migrate`, the one-command in-place conversion of a legacy UJM consumer.
+
+**This repository** is the framework itself. **Consumer projects** are a brand's website target: `config/omega.json5` + a consumer-owned `src/`, everything else delivered from the package as layers. Config comes from `@omega.js/config` (shared sections top-level, web settings under `targets.web`).
+
+## Recommended skills
+
+- **`js:patterns`** — JavaScript/Node.js conventions: file structure, JSDoc, defensive coding (`?.` usage), template literals, `package.json` conventions. Auto-loads when creating new `.js` files or touching JS module structure.
+- **`omega:web`** — the router skill from the omega Claude plugin. The inject hook loads it automatically in any project with `@omega.js/web` (and inside `packages/web` here); it points back to this guide + `docs/` (the SSOT).
+- **`omega:seo`** — the search-surface checklist for a page (meta values, the per-type structured-data gates in foot.html, one h1, sitemap/robots, link shape): [agent-plugins/claude/skills/seo/SKILL.md](../../agent-plugins/claude/skills/seo/SKILL.md). The plugin's quality hook fires it on any page, layout, or head/foot-chrome edit.
+- **`omega:accessibility`** — the front-end checklist (landmarks and heading order, alt text, control names, token color, focus visibility, reduced motion): [agent-plugins/claude/skills/accessibility/SKILL.md](../../agent-plugins/claude/skills/accessibility/SKILL.md). Same hook fires it on markup, section, and stylesheet edits.
+
+## 🚨 READ @omega.js/client TOO
+
+**`@omega.js/web` ships `@omega.js/client` into every page** (a real runtime dependency, bundled through the boot runtime as a shared chunk so every `import omega from '@omega.js/client'` is the SAME initialized singleton). It powers auth, Firebase, reactive `data-omega-bind` directives, analytics, error tracking, the service-worker registration, and utilities. Any task touching auth flows, Firestore reads/writes, subscription resolution, push notifications, or DOM bindings means you are working with `@omega.js/client` as much as with `@omega.js/web`.
+
+**Required reading:** [docs/client/index.md](../client/index.md) and `packages/client/docs/` (Auth, Bindings, Firestore, Notifications, …).
+
+## Quick Start
+
+### For Consuming Projects
+
+1. `npm install @omega.js/web` (in the brand's website target)
+2. There is no setup step ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)). Every verb below starts by running `ensureTarget()` — scaffold/refresh defaults + sync `package.json` scripts, idempotently, offline, and silently once the target is converged (bare `omega` prints help). It announces the seed mode it detected on a `[setup]` line: **standalone project** (the full `config/omega.json5` template + the per-target agent docs land here) or **brand monorepo** (no local-level config is seeded at all: the brand root's `config/omega.json5` is the target's config, and the agent docs live there too; a local-level file stays the standalone escape hatch you author yourself, and no verb touches one that exists). The scaffolded `src/pages/` carries one file — `example.md.txt`, a commented walkthrough of meta-only frontmatter and `{% section %}` composition. The `.txt` suffix keeps it out of the build; copy it to `<name>.md` to start from it
+3. `npx omega dev` — Eleventy watch/serve + in-place asset rebuilds. Port 4000 by convention, auto-bumps +1 when taken; `--port=N` or config `ports.website` PINS it. HTTPS by default via mkcert (`--no-https` falls back). Dev pages auto-connect the real Auth/Firestore SDKs to the LOCAL emulators — start them from the brand's backend target (`npx omega emulator`) **before** `omega dev`, because there is no live-Firebase opt-out in dev ([docs/backend/index.md](../backend/index.md)). Without them the site still builds and renders perfectly, and only the data surfaces misbehave — quietly: sign-in and sign-up hang then fail on a connection refused, every Firestore read stays pending so account/subscription state reads as signed-out, and every API request fails the same way (dev resolves the API base to the backend target's local `mgr serve` proxy — `https://localhost:5002` unless a dev port map says otherwise; `?_dev_apiEnvironment=production` is the per-request escape to the live API, and it does nothing for Auth/Firestore, which have no opt-out). A page that "loads fine but nobody can log in" is almost always this. `--local` links every `@omega.js/*` dep from this monorepo first ([docs/shared/local-dev.md](shared/local-dev.md)).
+4. `npx omega build` — production: assets (hashed, `@dev`-only blocks stripped) → Eleventy → PurgeCSS → Firebase auth helpers (`/__/auth/*`) → `dist/`
+5. `npx omega test` — PROJECT scope by default (production build + smoke checks + the consumer's `test/`); `framework:`/`omega:`/`web:` run the framework's own suite, `full:` runs both ([docs/shared/testing.md](shared/testing.md)). The smoke checks read the built `dist/`: pages rendered, a themed 404, the main bundle on disk, every internal link resolving ([#430](https://github.com/Omega-JS-Stack/omega/issues/430)), and the four audit checks — page meta (title + description), anchor fragments landing on a real id, `<img alt>`, and sitemap orphans ([#468](https://github.com/Omega-JS-Stack/omega/issues/468)). All of them share one exception file, `config/link-exceptions.json5`, one list per check keyed by the page that owns the finding, where a declaration that has started passing is itself a failure ([docs/test-framework.md](../docs/test-framework.md))
+6. `npx omega deploy` — THE publish verb: sync, then dispatch the CI build workflow ([docs/shared/deploys.md](shared/deploys.md))
+7. `npx omega migrate` — convert a UJM consumer in place; `--check` reports everything with zero writes. An already-converted config is not a failure: when the legacy files are gone but an `omega.json5` resolves (the target's own, or the brand root's), the config step validates the found config through the real loader, logs `already converted`, and skips itself while the codemods and legacy-file cleanup still run, so the command exits 0 for scripted pipelines. A project with neither legacy configs nor a resolvable `omega.json5` fails, and so does a found config the loader rejects
+
+`npx omega-web <cmd>` runs this CLI directly (no dispatch); `omg` and `mgr` are aliases for `omega`.
+
+> **Important:** all `npx omega ...` commands run from the consumer's **target root** (the directory with `package.json` + `config/omega.json5`). `dist/` and `.omega/` are generated — never edit them.
+
+### For Framework Development (This Repository)
+
+> **🚫 NEVER use `npx omega ...` from the framework repo.** `npx omega` is for CONSUMER projects. Here, use the `package.json` scripts.
+
+1. `npm install`
+2. `npm run prepare` — build once: `src/` → `dist/` via prepare-package (copy, no transforms), then the devkit `vendor` hook
+3. `npm run prepare:watch` (also `npm start`) — watch mode; the root `npm start` runs this for every package at once
+4. `npm test` — `node --test test/*.test.js` (engine slice, assets/ESM, CLI/scaffold, migrate, ports, sections, themes, translate, …). Fixtures live in `test/fixtures/`, the shared build harness in `test/lib/build.js`.
+5. Exercise real consumers: `brands/omega-playground` (classy) and `brands/newsflash-brand` (newsflash) are the standing in-repo brands; `brands/sandbox-brand` is the synthetic fixture the automated corpus mangles and resets ([docs/shared/brands.md](shared/brands.md)).
+
+## Architecture
+
+Long-form detail (packaged content, URL shape, service worker, design tokens, theming tiers, app shell, pricing, responsive images, engine facts) lives in [README.md](../README.md). This is the map.
+
+### Module map (`src/`)
+
+| Module | Owns |
+|---|---|
+| [engine.js](../src/engine.js) | `configureOmega()` — turns an Eleventy instance into the OMEGA engine: Liquid options + template-kit registration, layered layouts, the frontmatter preprocessor, `resolved`/`paginator`/`pageAssets` computed data, site collections, default pages, globals |
+| [layers.js](../src/layers.js) / [layouts.js](../src/layouts.js) | First-layer-wins file resolution across the layer chain; layered layout delivery with zero copying (virtual templates in build, a symlink farm in dev) |
+| [sections.js](../src/sections.js) | The section/component library: the `{% section %}` / `{% component %}` tags, json5 schemas + defaults, the `{% composition %}` page-body guard, `buildSectionLibrary()`, `collectSectionAssets()` |
+| [assets.js](../src/assets.js) | Page/layout modules + main bundle over the layer roots, bundled through [`@omega.js/devkit`'s `bundle`](../devkit/index.md) — the ONE esbuild wrapper ([#736](https://github.com/Omega-JS-Stack/omega/issues/736)), which composes the framework-deps resolve hook, the production `@dev-only` strip, the minify/sourcemap rules and the per-build timing line, leaving web only its boot-stub plugin and its entry shape. Plus layered sass (`omega:` importer, in both languages), the layered page/layout css lanes, font copy, PurgeCSS post-pass, and the critical-css extraction the head inlines ([#750](https://github.com/Omega-JS-Stack/omega/issues/750)) |
+| [build.js](../src/build.js) | `buildSite()` — assets → service worker/meta → static → imagemin → Eleventy → PurgeCSS, with per-phase timings (what `omega build` runs) |
+| [collections.js](../src/collections.js) | posts / alternatives / team / updates collections + taxonomy aggregation, and the same registration for the brand's own collections |
+| [dynamic-pages.js](../src/dynamic-pages.js) | Dynamic pages ([#207](https://github.com/Omega-JS-Stack/omega/issues/207)): the listing + category pages a declared collection gets for free (see Key contracts below) |
+| [limit-collections.js](../src/limit-collections.js) | Dev-mode collection sampling ([#190](https://github.com/Omega-JS-Stack/omega/issues/190)): `targets.web.dev.limitCollections` ({ posts: 50, randomize: true }) drops everything outside the sample before it renders — development builds only, never production |
+| [markdown-images.js](../src/markdown-images.js) | Markdown images render optimized ([#193](https://github.com/Omega-JS-Stack/omega/issues/193)): `![alt](src)` goes through the `omega_image` builder (responsive picture + lazy placeholder; plain lazy img for external/non-raster). Post authors get the `@post/<file>` shorthand for the post's own image dir — off a post it fails the build. Feeds embed the lazy markup (readers see the placeholder), legacy parity |
+| [frontmatter-liquid.js](../src/frontmatter-liquid.js) | Liquid inside frontmatter VALUES — the lane a value takes is decided by its variable ROOTS (cached site-scope renders; page-scoped values defer to a copy-on-write pass; everything else renders against the template's own cascade; the context-free `omega_*` filters are registered, since LiquidJS drops an unknown filter silently) |
+| [consumer.js](../src/consumer.js) / [consumer-scan.js](../src/consumer-scan.js) | Consumer layout (`src/`, `dist/`, `.omega/`) + omega.json5 → site data; permalink scan → default-page suppression |
+| [pricing.js](../src/pricing.js) / [brand-tokens.js](../src/brand-tokens.js) | `site.pricing` composed from `payment.products` × the top-level `features` catalog ([#647](https://github.com/Omega-JS-Stack/omega/issues/647) — the catalog supplies row order, name, icon and definition; a product names only its VALUE); the accent ramp derived from `brand.color` |
+| [imagemin.js](../src/imagemin.js) / [minify-html.js](../src/minify-html.js) / [static-assets.js](../src/static-assets.js) / [cachebreak-html.js](../src/cachebreak-html.js) | Production output passes (the `@dev-only` strip moved to devkit's esbuild plugin, [#736](https://github.com/Omega-JS-Stack/omega/issues/736)) |
+| [service-worker.js](../src/service-worker.js) | `buildServiceWorker()` + `writeBuildMeta()` — the build manifest at `/build.js` + `/build.json` (brand, environment, version, theme, package versions, repo, commit, assets, cacheBreaker), which `@omega.js/client`'s version check polls and the `/status` page displays ([#13](https://github.com/Omega-JS-Stack/omega/issues/13)) |
+| [firebase-auth-helpers.js](../src/firebase-auth-helpers.js) | Self-hosted `/__/auth/*` helper files (authDomain = the brand host), write-through cached per project |
+| [translate/](../src/translate) | The AI translation pass over `dist/` with the committed cache, plus the default-page translations the framework ships in `translations/` — its own plumbing pages never reach a provider and still get their `/{lang}/` copies ([docs/shared/translation.md](shared/translation.md)) |
+| [purge.js](../src/purge.js) | Cloudflare cache purge (`omega purge`, auto after a direct deploy) |
+| [customize.js](../src/customize.js) / [overrides.js](../src/overrides.js) | `omega customize <url>` — materialize a default page into `src/pages/`; the layered override map + single-file materialize (`--list`, `omega customize <path>`), built from the same layer chains the build resolves through |
+| [scaffold.js](../src/scaffold.js) | `scaffoldDefaults()` — the devkit defaults engine over `scaffold/` + the web FILE_MAP |
+| [migrate/](../src/migrate) | `runMigration()` — config conversion, the codemod rule tables (templates, consumer JS, and section `.json` descriptors each get their own walk, [#248](https://github.com/Omega-JS-Stack/omega/issues/248); the renamed section args `hero.tagline` → `hero.badge.text`, `cta.description` → `cta.subheadline`, `cta.button` → `cta.primary_button` ride the same table, [#545](https://github.com/Omega-JS-Stack/omega/issues/545), and a `hero.secondary_button` block with no `enabled` key gains `enabled: true` with a warning — `marketing/hero` defaults that button OFF and a UJM page opted in by writing the block, [#579](https://github.com/Omega-JS-Stack/omega/issues/579); the `page.<key>` rewrite is loop-scope aware and reports what it skipped instead of repointing a read at the loop item, [#541](https://github.com/Omega-JS-Stack/omega/issues/541); the UJM library accessor `webManager.uj()`/`omega.uj()` becomes `omega.library()` and any surviving `.uj(` is an error finding — the client has no `uj()`, [#560](https://github.com/Omega-JS-Stack/omega/issues/560); the retired `{% include modules/adunits/adsense.html … %}` becomes `{% section "verts/unit", type: …, size: … %}` (`vert-size` → `size`), and every other `adunits/*` include is an error finding, [#559](https://github.com/Omega-JS-Stack/omega/issues/559); a class-only Kramdown attribute list on a link, `[text](url){: .a .b }`, becomes `<a href="url" class="a b">text</a>` in MARKDOWN files only, and any other surviving `{: … }` is an error finding — markdown-it reads no IAL and prints them, and the engine loads no attrs plugin, [#565](https://github.com/Omega-JS-Stack/omega/issues/565); `authorizedFetch(…)` becomes `omega.request(…)` carrying the two shapes the rename alone left dead — `response: 'json'` dropped (the client parses by content type and RETURNS the body) and `err.status` → `err.code` INSIDE the catch block that binds the error, with a non-json `response`, options behind an identifier and any other `.status` named at their own line, [#594](https://github.com/Omega-JS-Stack/omega/issues/594); a bare `random_id` read gets the `{% assign %}` UJM handed every page for free, [#595](https://github.com/Omega-JS-Stack/omega/issues/595)), the legacy Jekyll `collections:` block DROPPED with the manual step named per collection — mapping and array spellings alike, because a Jekyll collection carries no grouping `field` and `targets.web.collections` requires one ([#589](https://github.com/Omega-JS-Stack/omega/issues/589)), the dependency-resolution report (every bare `require()` under `src/**` the consumer's own package.json does not declare, named file:line with the fix and never installed — the legacy FLAT install answered them and an OMEGA install answers only by hoisting; the framework's own bundler aliases are never named, because a consumer must NOT install `@omega.js/client`, [#600](https://github.com/Omega-JS-Stack/omega/issues/600)), the legacy-test warning (`migrate --check` names UJM harness files `omega test` would count as a false pass 0, detected by shape not filename), liquid-lint (known names from the real registration path — template-kit's filters/tags AND the framework's `{% section %}` family, [#489](https://github.com/Omega-JS-Stack/omega/issues/489)), consumer-asset fixes, legacy-file removal |
+| [cli.js](../src/cli.js) + [commands/](../src/commands) | The CLI: `bin/omega` → the devkit `omega-bin` dispatcher → `cli-run.js` → `cli.js` → `commands/<name>.js` (`bin/omega-web` skips the dispatch and runs `cli-run.js` directly) |
+| [mode-helpers.js](../src/mode-helpers.js) | The environment surface ([#717](https://github.com/Omega-JS-Stack/omega/issues/717)): `getEnvironment()` + `isDevelopment()` / `isProduction()` / `isTesting()`, mixed into the CLI class via `attachTo()` and read by the build lanes (see Key contracts below) |
+| [paths.js](../src/paths.js) | Packaged content locations + `resolveClientEntry()` |
+
+### Packaged content (shipped, not in `src/`)
+
+`themes/` (`base` — the structural `omega-*` markup layer every theme chain terminates at; `classy` — the flagship v2 skin, the default; `newsflash` + `neobrutalism` — skins with bounded identity forks, falling back to base per file; `bootstrap` — the vendored Bootstrap source; `_template` — the theme starter) · `core/` (the theme-agnostic layer: blueprint layouts, the document shell, head/body/foot chrome, the `--omega-*` token sheet, `.omega-shell`, core js) · `defaults/` (~60 default pages at their real URLs, the meta-files, and the dev-only sample content corpus) · `runtime/` (the browser ESM boot: `boot.js` bootMain/bootPage/bootLayout handshake, `manager.js` frontend Manager) · `sw/` (the service worker) · `scaffold/` (what `ensureTarget()` writes on every verb).
+
+### Key contracts
+
+- **Layered resolution, everywhere.** Consumer files → active theme → base → core, first-layer-wins per relative path — for layouts, includes, sections, css, and js. A consumer overrides by owning the same path; everything it does not own keeps flowing from the framework.
+- **Sections are the content model.** Pages are compositions of `{% section %}` / `{% component %}` calls; each entry is a folder owning markup + scss + js + json5 schema. Full contract: [docs/web/sections.md](sections.md); design + sequencing: [docs/web/omega-sections-spec.md](omega-sections-spec.md).
+- **A page's JS and CSS bind to its URL — and one `[name]` wildcard file serves a whole page FAMILY** ([#470](https://github.com/Omega-JS-Stack/omega/issues/470)). Nothing in frontmatter points a page at a module (the legacy `asset_path` key is dead, spec §7): `pageAssets` ([engine.js](../src/engine.js)) turns the URL into a key and `resolvePageAsset` ([assets.js](../src/assets.js)) answers it in ONE order — the **exact key** (`js/pages/pricing.js`), then the **per-page-dir spelling** (`js/pages/pricing/index.js`), then a **`[name]` wildcard filename**, the Next.js convention spelled Windows-safe: `js/pages/blog/[slug].js` + `css/pages/blog/[slug].scss` serve every `/blog/<slug>` page, and `js/pages/alternatives/[alternative]/index.js` does the same one directory deeper. A wildcard segment matches exactly ONE URL segment, exact beats wildcard, the most-literal wildcard wins among wildcards (ties break lexicographically), and a trailing `/index` on a wildcard key is the per-page-dir spelling, never a consumed segment. Underscore basenames under `pages/` are shared partials in both languages, never entries (`js/pages/legal/_document.js` backs the flat `terms`/`cookies`/`privacy` entries). **Reach for a wildcard whenever more than one URL shares a module — a generated family, a collection, a set of look-alike pages — and keep the re-export ESCAPE HATCH (a `js/pages/<this page>/index.js` that does `export { default } from '../<other page>/index.js';` plus a `css/pages/<this page>/index.scss` that `@use`s the other sheet) for the one-off page borrowing a single other page's module.** `omega migrate` names both, in that order, wherever it finds an `asset_path` key, and the orphan guard ([#469](https://github.com/Omega-JS-Stack/omega/issues/469)) warns by name when a consumer `js/pages/` file is neither an entry nor imported by one — a legacy 4-segment module (`js/pages/dashboard/agents/edit.js`) is the usual culprit, and a family file is its usual answer. Deep contract: [docs/web/sections.md](sections.md). Pinned by `test/assets.test.js` and `test/slice.test.js`.
+- **ONE rule decides what loads for a page: EVERY layer's file does, in layer order** ([#624](https://github.com/Omega-JS-Stack/omega/issues/624), Ian's ruling — JS and CSS alike, no replace semantics and no extend one-liners to remember). A framework page script always runs, the theme decorates, the consumer adds; a manifest key holds a LIST, and `pageAssets.js` / `pageAssets.css` render one `<script>` / `<link>` per entry (a css entry under the inline budget renders a `<style>` block in the link's place instead, [#767](https://github.com/Omega-JS-Stack/omega/issues/767)) in **core → base theme → active theme → consumer** order, which for module scripts IS execution order and for stylesheets IS the cascade. There is no opt-out: a layer that wants nothing from the layer below writes its own behavior, it does not silence one. Worked examples on the classy chain:
+  - `/signin` — core ships `js/pages/signin/index.js` and no theme or consumer file exists, so exactly one script loads. Nothing changed from before.
+  - `/pricing` — core ships `js/pages/pricing/index.js` + `css/pages/pricing/index.scss`; a brand that adds `src/assets/css/pages/pricing/index.scss` gets BOTH sheets, its own last, so it restyles by writing the rules it wants rather than by re-copying the framework's.
+  - `/blog/<slug>` — core's `js/pages/blog/[slug].js` (in-article verts, reading progress) plus the newsflash theme's `js/pages/blog/[slug].js` (its own progress bar) plus a consumer's, all three. Before #624 the theme's file REPLACED core's while both layers' CSS loaded — two rules for one feature, which is the hole this closes.
+  - Outputs are content-hashed per layer and named for their owner (`pages/blog/[slug]-HASH.js`, `…[slug].newsflash-HASH.js`, `…[slug].site-HASH.js`), so dev's stable names never collide either.
+- **Assets can key on a LAYOUT as well as a URL** ([#624](https://github.com/Omega-JS-Stack/omega/issues/624)). `js/layouts/<layout>.js` + `css/layouts/<layout>.scss` are keyed by the layout NAME a page writes in frontmatter, resolved through the manifest and layered exactly like page assets — and applied across the page's whole layout CHAIN, outermost first, so a blueprint sitting on another layout still gets that layout's assets. The framework's own user is the redirect layout: `core/js/layouts/modules/utilities/redirect.js` loads on every page rendering `modules/utilities/redirect` (`/account`, `/careers`, every social and target shortlink) and on nothing else. A layout module reaches the boot handshake as its NAMESPACE (`bootLayout`), so its default export is OPTIONAL: chrome that must act before the client is ready runs at import time and exports nothing, and no generated stub ever names a `default` that is not there ([#742](https://github.com/Omega-JS-Stack/omega/issues/742), where esbuild proved that access undefined and warned on every build; `test/assets.test.js` now pins the js lane's warning count at zero). This replaced the `js/modules/` lane — standalone IIFEs at fixed, un-hashed URLs, scripted by hand from a layout — which is DELETED: `js/modules/` builds nothing now, in any layer, and the build says so by name rather than ignoring the directory ([#249](https://github.com/Omega-JS-Stack/omega/issues/249)).
+- **The site-wide bundle is the one REPLACE-with-extend lane, and JS spells the extend exactly as CSS does.** `js/main.js` and `css/main.scss` resolve first-layer-wins, so a consumer's own file takes over — and reaches the framework's through the same `omega:` name on both sides: `import coreMain from 'omega:main'` (esbuild) and `@use 'omega:main' with (…)` (sass) each resolve `main` from the layers BELOW the importing file. The three customization recipes, end to end:
+  - **Site-wide** — `src/assets/css/main.scss` with `@use 'omega:main' with ($primary: …)`, and/or `src/assets/js/main.js` with `import coreMain from 'omega:main'; export default async (context) => { await coreMain(context); /* your boot code */ };`. Skipping the extend line is how you replace the framework bundle outright, deliberately.
+  - **Page-specific** — write `src/assets/js/pages/<key>.js` / `src/assets/css/pages/<key>.scss` at the URL's key and it loads AFTER the framework's for that URL. Nothing to import, nothing to declare.
+  - **Premade JS** — put shared browser modules in `src/assets/js/libs/` and import them by relative path from any page or main file. That is the consumer twin of the framework's own `core/js/libs/`; both are documented in [docs/web/libs.md](libs.md).
+- **Consumer page frontmatter is META-ONLY.** The allow-list is `meta`, `schema`, `config`, `sitemap`, `redirect`, `templateEngineOverride`, `eleventyExcludeFromCollections` ([engine.js](../src/engine.js) `PAGE_FRONTMATTER_ALLOW`; every key documented in [docs/web/frontmatter.md](frontmatter.md)); plumbing keys (`layout`, `permalink`, `tags`, `pagination`, …) are filtered before the check. Content keys in a page's own frontmatter are STRIPPED from the cascade with a build warning, so sections can never consume them. The two frontmatter mistakes that FAIL the build are the `config:` namespace's two directions (#607): a config section restated bare, and a non-section key under `config:`. Collection entries (`_posts`, `_team`, …) and layouts are exempt from the content-key strip — their frontmatter IS the document. Pinned by `test/frontmatter-guard.test.js`. The page-level lane that DOES exist for a shell layout's band data is the page's sidecar data file, `<page>.11tydata.*` ([#269](https://github.com/Omega-JS-Stack/omega/issues/269)): `resolved` re-applies it with the engine's deepMerge, so a sidecar array REPLACES the layout default instead of concatenating onto it, and object/string keys merge as before ([docs/web/sections.md](sections.md), `test/sidecar-data.test.js`). The EXTENSION does not change the contract ([#543](https://github.com/Omega-JS-Stack/omega/issues/543)): `.11tydata.js` and `.11tydata.cjs` ride the same re-apply as `.11tydata.json`, merged in Eleventy's own order (`.js` → `.cjs` → `.json`); only `.mjs`, which no synchronous read can load, stays on pure cascade behavior.
+- **Frontmatter Liquid renders against the page's own cascade, and `meta:` fails loudly** ([#542](https://github.com/Omega-JS-Stack/omega/issues/542), [#544](https://github.com/Omega-JS-Stack/omega/issues/544) — both found porting a real brand). A frontmatter or sidecar value's variable ROOTS decide its lane ([frontmatter-liquid.js](../src/frontmatter-liquid.js)): `site.*` alone is build-constant and caches by raw source; `page.*`, `resolved.*` (every config ref included, since #607 spells them `resolved.config.*`) and the page's OWN pagination alias defer to the per-page `resolved` pass; anything else — the consumer's `_data` globals, so `{{ brands.size }}` beside a `_data/brands.json` reads the file sitting next to it — renders uncached against the same cascade a template render gets. An alias ref therefore needs no `resolved.` prefix any more (`{{ brand_doc.name }}` works), in the page's head and in the meta files alike. And because a `meta:` value renders ONCE and caches, a meta ref whose ROOT nothing in the cascade defines FAILS the build, naming the file and the ref, instead of caching an empty string onto every page that shares the value; a legit empty optional (`{{ resolved.config.brand.tagline }}` on a brand that sets none) still passes, because only the root is checked. Pinned by `test/data-globals-frontmatter.test.js`, `test/meta-pagination-alias.test.js` and `test/frontmatter-liquid.test.js`.
+- **Markdown renders with the typographer on** ([#547](https://github.com/Omega-JS-Stack/omega/issues/547)). `markdown-it` runs with `typographer: true` as a HARD default on BOTH instances — Eleventy's own (a `.md` body) and the engine's (template-kit's `markdownify`) — so straight quotes, apostrophes, `--` and `...` come out smart. Kramdown did this at build time on every Jekyll site, so without it every brand converted off UJM drifts into straight punctuation on its next build (HARD RULE 5: preserve semantics). There is no consumer knob. Pinned by `test/markdown-typographer.test.js`.
+- **Client-runtime configuration is the `client` key** ([#1](https://github.com/Omega-JS-Stack/omega/issues/1) — it configures `@omega.js/client`; it was `web_manager` through the UJM era and there is no dual-read). It reaches the page through the engine's site composition (`cloud.config` and `payment` compose back into `client.*` at build), the core chrome emits it as the Configuration payload from `resolved.config.client`, and a page or layout may set it under its `config:` block with the layout chain merging underneath (#607). Legacy conversion row: [docs/shared/config.md](shared/config.md).
+- **Three namespaces, and a page overrides config under `config:`** ([#607](https://github.com/Omega-JS-Stack/omega/issues/607) — Ian's ruling, no backwards compatibility). A template reads exactly three things:
+  - `resolved.config.*` — the brand's omega.json5 for this target, with THIS page's `config:` block merged over it. Every config key lives here: `resolved.config.brand.name`, `resolved.config.theme.main.class`, `resolved.config.inbound.chat.providers.chatsy.enabled`.
+  - `resolved.meta.*` — the page meta walk: page `meta:` → layout `meta` defaults → `brand.name` / `brand.description` (the last step is `core/_includes/core/head.html`'s fallback). `meta` is PAGE machinery, not config: omega.json5 declares no `meta` section at all ([#607 addendum](https://github.com/Omega-JS-Stack/omega/issues/607), Ian 2026-08-26 — meta never exists in two places), and a config still carrying one is a retired-key error. The full key-by-key contract is [docs/web/frontmatter.md](frontmatter.md).
+  - `site.*` — BUILD FACTS only: the indexed collections (`site.posts`, `site.team`, …), `site.omega` (cache breaker, version, build date), `site.data`, `site.pricing`, `site.brandTokens`, `site.characters`, `site.license` (the deploy-time license verdict, whose `attribution` gates the footer's omega credit — [docs/shared/publishing.md](shared/publishing.md#the-license-check-320)), and the curated `site.targets` view. Nothing config ever rides it.
+
+    A collection doc is the Jekyll shape — `id`, `url`, `date`, the document's own frontmatter at the top level, and `content`, its RENDERED body ([#711](https://github.com/Omega-JS-Stack/omega/issues/711)). ONE flattener produces it for both lanes, `site.<name>` and `paginator.posts`, so `{% omega_readtime post.content %}` counts the same words wherever the card is drawn. `content` is lazy and non-enumerable by necessity: the site arrays are captured into the data cascade before collections render, so an eager (or enumerable) read would throw Eleventy's premature-content error on every `resolved` walk. Pinned by `test/site-collection-content.test.js`.
+
+  What a page's `config:` block looks like, which shapes FAIL THE BUILD, and how far each failure reaches is [docs/web/frontmatter.md](frontmatter.md) — the one home of the key-by-key contract. `omega migrate`'s `config-parent` rule moves a legacy page's bare sections under `config:` (idempotent, one finding per file), and the guard lane (`test/config-namespace-guard.test.js`) fails a framework template that reads config off `site.*` or off the old flat `resolved.<section>` path. Pinned by `test/page-config-overrides.test.js`.
+
+  READS move with the keys ([#611](https://github.com/Omega-JS-Stack/omega/issues/611)). A `site.<config section>` read does not fail on its own — it renders an EMPTY STRING, on every page carrying one — so the build censuses each template's own source (frontmatter values and body alike) and stops on the first sighting, naming the file, the line, the expression it found and the one that replaces it. `omega migrate`'s `config-reads` rule is the rewrite: `site.<section>` and the old flat `resolved.<section>` both become `resolved.config.<section>`, `site.meta` becomes `resolved.meta`, build facts are untouched, and it runs over section `.json` descriptors too (a `{{ … }}` binding emits the same empty string a template would). Idempotent, one finding per file.
+
+  Two surfaces the per-template census cannot see ride the SAME rule ([#671](https://github.com/Omega-JS-Stack/omega/issues/671)). The first is the config FILE's own string values — `targets.web.tagline: "Agency - {{ site.brand.name }}"` is a read like any other, rendered empty wherever it lands since #611 — rewritten in the file (never through a re-serialize, which would eat a brand's comments) and previewed by `--check` from the config the run WOULD write, so a legacy root's pre-flight report is the real one. The second is a page's own `meta:` block, whose reads are DROPPED rather than moved: a block that FEEDS the meta walk may not read it (the page shipped the literal `{{ … }}` in its `<title>`), in the block, one-line flow and multi-line flow spellings alike, and absence falls through to the brand default. Every key the drop empties goes with it — nested keys first, up to the `meta:` opener — because a childless key is YAML null and a null REPLACES the default it was meant to fall through to. Each dropped line is an EDIT, so the repair reaches the disk instead of being announced over an unchanged file.
+
+  What COUNTS as a read has ONE home, `src/config-sections.js`'s `templateReads` — shared by the migrate rule, the build guard and the static guard lane, so none of the three can fail on something the others would not have fixed. A read is a `site.*`/`resolved.*` path in LIQUID context (`{{ … }}` or `{% … %}`) outside a display block: a hostname (`https://site.company.com/x`), a filename (`/site.webmanifest`), a fenced code sample and a `{% raw %}` body are not reads (the #521 doctrine — code display is not markup). The guard's section list is the schema's `CONFIG_SECTIONS` **exactly**, never the frontmatter lane's `hasOwn(config, key)` widening: `site.url` is a build fact and a brand may override `site.omega` / `site.characters`, and a read guard's false positive is a build a brand cannot fix.
+- **No tracker loads without consent** ([#383](https://github.com/Omega-JS-Stack/omega/issues/383)). `core/foot.html` emits the provider IDS and nothing else — the GA4, Meta and TikTok loaders are injected at runtime by `core/js/core/analytics-loader.js`, and only for a category the visitor's consent record allows (ga4 → `analytics`, meta/tiktok → `marketing`). The regime is region-gated off the browser timezone (`core/js/libs/consent-region.js`): a STRICT roster — `Europe/*`, the four Atlantic EEA zones, Brazil, China, South Korea, and anything unplaceable — is real opt-in, where nothing loads until Accept; everywhere else loads immediately with no banner. A country joins the roster only when its law genuinely requires opt-in consent, verified; when in doubt it stays out ([#423](https://github.com/Omega-JS-Stack/omega/issues/423)). Google Consent Mode is wired either way: the `consent default` command is queued into dataLayer before gtag.js can load, and every change pushes a `consent update`. The record lives in `omega.storage()` under `trackingConsent` — NOT `consent`, which is already the signup form's legal consent (`libs/auth/forms.js`, read by the backend signup route) — and is reached through `core/js/libs/tracking-consent.js` (`getTrackingConsent()`), the one seam the banner, the loader, and the checkout/signup payloads share. Granting injects a loader immediately; revoking cannot unload a running script, so it takes effect next page load while Consent Mode updates now. The banner itself (`core/js/core/consent.js`, config `client.consent`) is a cookie-iconed message, one big Accept, and a small Customize opening a panel of instant-saving pill switches with an Accept all / Accept none pair; it never auto-accepts on scroll. In an opt-out region a first visit sees no banner at all — just the Cookies Settings tab that reopens it ([#391](https://github.com/Omega-JS-Stack/omega/issues/391)). Pinned by `test/consent-region.test.js`, `test/tracking-consent.test.js`, `test/consent-gating.test.js` and `test/consent-banner.test.js`.
+- **`site.characters` is engine-owned, brand-overridable** ([#286](https://github.com/Omega-JS-Stack/omega/issues/286)). The literal-character set core templates interpolate rather than type — `characters.copyright` in the head's copyright meta, plus the brace/bracket pairs, `asterisk` and `underscore` — ships as a DEFAULT set from the engine ([engine.js](../src/engine.js)), composed onto the site global beside `site.omega`; a brand that writes a top-level `characters` key in its omega.json5 wins per key and the rest of the set still stands (nothing in OMEGA defined the set, so every page fleet-wide shipped a leading blank in that meta). Pinned by `test/site-characters.test.js`.
+- **Machine files ship by default.** Every build emits `robots.txt` (with the sitemap pointer), `sitemap.xml`, `feeds/posts.xml` (RSS) + `feeds/posts.json` (JSON Feed), `pages.json` (the search index), `ads.txt` (the configured AdSense publisher, an honest comment when no provider is configured), `llms.txt` ([llmstxt.org](https://llmstxt.org) — brand heading, summary, then pages and posts as markdown links, [#4](https://github.com/Omega-JS-Stack/omega/issues/4)), `humans.txt`, `opensearch.xml`, and `.well-known/security.txt`. All are default pages generated from site metadata and the URL-sorted page collection, honoring the same exclusion convention (admin, redirect, draft, noindexed and sitemap-excluded pages, the `/test` dev SEGMENT, and the machine files themselves — each meta template carries the walk, kept in step by the tests) — so a consumer file at the same URL suppresses the framework's like any other default page. Titles and descriptions read another page's data through the `omega_rendered` filter ([#141](https://github.com/Omega-JS-Stack/omega/issues/141)): layout-contributed meta (the `/updates/*` pages' `Version {{ page.update.version }}`) holds raw Liquid until the owning page renders it, so a meta file renders it against THAT page's scope instead of emitting the source. Pinned by `test/meta-files.test.js`.
+- **Structured data rides `core/foot.html`.** The unconditional blocks (BreadcrumbList, the brand node, WebSite) plus gated ones (BlogPosting, Person, Product, SoftwareApplication, ContactPage, FAQPage). The brand node's schema.org type is `brand.type`, optional config that defaults to `Organization` in the template ([#271](https://github.com/Omega-JS-Stack/omega/issues/271) — an unset key shipped `"@type": ""` on every page and collapsed the `<site.url>#<type>` @id every other block cross-references). Pinned by `test/head-foot-fixes.test.js`.
+- **The index posture is ONE decision, and both signals read it** ([#564](https://github.com/Omega-JS-Stack/omega/issues/564), found by a blind verify of a migrated brand — 745 legacy `<loc>` entries became 255 while every dropped page still shipped `content="index"`). `meta.index: false` — set by a page or by the layout it renders on — makes `core/head.html` emit `noindex` AND drops the page from `sitemap.xml`, `pages.json` and `llms.txt`, so no two signals can disagree — one flag governs all three machine files. **The site-wide default is the SAME key one level up, `targets.web.meta.index`** ([#564](https://github.com/Omega-JS-Stack/omega/issues/564), Ian's same-name ruling 2026-09-09, where a global value and its specific override share ONE name and ONE shape; #725's `seo.index` was a second name for one decision and is retired with a pointer): the literal `false` in omega.json5 SEEDS every page's meta walk with `index: false`, so the whole site goes noindex and all three machine files empty through the very same flag — never a second emission path. A page's own `meta.index` still wins both directions, so `meta.index: true` keeps one page indexed on an otherwise dark staging site. **`sitemap.include` is retired with it**: "indexable but out of the sitemap" is not a state a page can be in any more, so the key is off the frontmatter allow-list and the sitemap simply follows the index flag. Consequential-feature doctrine ([#527](https://github.com/Omega-JS-Stack/omega/issues/527)): absent or `true` is exactly today's behavior. **The posture is thin-taxonomy EXCLUSION**: a taxonomy page is a list of links to pages that are themselves indexed, so it earns nothing and competes with them. **Indexed** — posts, authored pages, collection items, and every listing's page 1 (`/blog`, a declared collection's `/docs`); **noindex** — the blog taxonomy entire (tag AND category terms, and both hubs) plus a declared collection's category pages, a listing's `/page/N` (page 1 is the canonical listing), auth, account, checkout, 404, `/extension/installed`, and the framework's `/test` dev surfaces. Every AUTOMATIC exclusion comes from the ENGINE, not from a URL list each template keeps: `resolved` sets `meta.index: false` on a draft, on the `/test` dev surfaces, under `/admin/`, on a redirect-layout page, and on any non-alias paginated page past the first ([engine.js](../src/engine.js)), so a page whose URL merely contains `/page/` stays indexed and listed, and a draft now SAYS noindex instead of silently vanishing from the sitemap while telling crawlers to index it. The templates and the dist audit read that one resolved value and nothing else. `robots.txt` disallows nothing new — a crawler must fetch a page to read its `noindex`. `head.html` answers no URL at all now: the `/test/` dev surfaces (which a production build omits entirely, #554) get the flag from the engine like everything else. **The listing exemption**: `defaults/pages/blog.md` and the generated collection listing are the only paginated templates WITHOUT `eleventyExcludeFromCollections` — a page cannot be in `sitemap.xml` if it is not in the walk, and Eleventy adds only page 0 of a paginated template to collections, so the exemption exposes page 1 and never `/page/N` (`test/collections-gate.test.js` pins which templates get it, and why an alias generator never does). Pinned by `test/index-posture.test.js`; `omega migrate` prints the `<loc>` delta as a conversion note so a migrating brand records it instead of filing it as a regression.
+- **Blog search is client-side and self-contained** ([#44](https://github.com/Omega-JS-Stack/omega/issues/44) item 22): the build emits `/blog/index.json` (title, url, capped description, tags, categories, date; no bodies; sitemap-excluded), and the blog index page lazily fetches it on first focus, ranks title hits first, deep-links `?q=`, and binds Cmd/Ctrl+K. The schema `SearchAction` and `opensearch.xml` target `/blog?q={search_term_string}`; no Google CSE anywhere. Pinned by `test/blog-search.test.js`.
+- **Theming** is the `--omega-*` token contract: themes redefine tokens, components read `var(--omega-*)`. Two consumer tiers — restyle the stock theme from `src/assets/css/main.scss` (`@use 'omega:main' with (…)`), or ship a full theme at `src/themes/<id>/`. A tier-2 theme owes only that dir and a `_theme.scss` (`@forward 'omega:theme';` inherits the packaged skin whole); `_theme.js` and `fonts/` are optional — a theme SHADOWING a packaged id inherits that skin's theme js and font files along with its faces, and a theme with a NEW id lands on base's floor ([#773](https://github.com/Omega-JS-Stack/omega/issues/773)). Full contract: [docs/shared/theming.md](shared/theming.md); visual spec: [docs/web/classy-v2/DIRECTION.md](classy-v2/DIRECTION.md).
+- **The purge pass scans HTML _and_ the built JS.** `purgeCss` ([assets.js](../src/assets.js)) globs `dist/**/*.html` plus `dist/**/*.js`, so classes that exist only inside a client-rendered app's markup strings survive `omega build` with zero config — a consumer never needs a safelist for its own classes (#66). The built-in safelist stays for what no content scan can see: the runtime-stamped `omega-` namespace and Bootstrap's JS-toggled transition classes — and it is the DEFAULT, not the whole truth: `targets.web.purgecss.safelist` merges over it ([#250](https://github.com/Omega-JS-Stack/omega/issues/250)), in PurgeCSS's own shape (`{ standard, deep, greedy, keyframes }`, or a bare array for `standard`). Config is JSON5, so the pattern lanes take strings and the build compiles them to regexes. Pinned by `test/purge-css-safelist.test.js`.
+- **The main sheet does not render-block** ([#750](https://github.com/Omega-JS-Stack/omega/issues/750), Phase 2 of [#467](https://github.com/Omega-JS-Stack/omega/issues/467)). The css lane extracts the FIRST-PAINT subset of the compiled main bundle (`extractCriticalCss` in [assets.js](../src/assets.js)) into `assetManifest.css.critical`, which is css TEXT rather than a url: [head.html](../core/_includes/core/head.html) inlines it in a `<style>` block, then loads the full sheet through `<link rel="preload" as="style" onload="this.rel='stylesheet'">` with a `<noscript>` twin. The `<link>` keeps its document position, so the cascade order never moves and the per-layout and per-page sheets (inlined when small, a blocking link past the budget, see #767 below) still win over it. A page or layout sheet that compiles to nothing is never emitted or linked ([#766](https://github.com/Omega-JS-Stack/omega/issues/766)): an empty blocking request still costs the round trip, about a second of first paint on a slow mobile connection. **A sheet small enough costs no request either** ([#767](https://github.com/Omega-JS-Stack/omega/issues/767)): compiled at or under **8 KB** (`INLINE_MAX_BYTES` in [assets.js](../src/assets.js)) it rides the manifest as css TEXT, so a manifest entry is `{ inline }` instead of `{ href }` and the head prints a `<style>` block in the exact document position the link held, layout sheets before page sheets and layers in load order, which leaves the cascade untouched. Over the budget the sheet keeps its content-hashed file and its link, and the split is per sheet: a heavy layer's link stands beside a light layer's block inside one key. The budget is about the ROUND TRIP rather than the bytes, which is why it is so low: the request queues behind the HTML and the font preloads, so the [#763](https://github.com/Omega-JS-Stack/omega/issues/763) proof measured `/terms`, whose page sheet is 1 KB, first-painting at 1,928 ms against the 824 ms of a home page that ships no page sheet at all. `omega dev` inlines nothing (the reason it keeps the main sheet a plain link: a stable link is what keeps a watch rebuild flash-free), and the critical extractor's content set is unchanged, since an inlined sheet is already whole and already in the head. The font prune reads the inlined text beside the emitted css tree for the same reason ([#768](https://github.com/Omega-JS-Stack/omega/issues/768) lane, `inlinedSheetCss` in [assets.js](../src/assets.js)): a face declared only by a sheet that never reached disk is referenced just as surely as any other, and pruning it would delete it out from under the page that needs it. Pinned by `test/inline-sheets.test.js` and the inlined-face case in `test/assets.test.js`. **The subset is chosen by MARKUP, not by a selector list**: PurgeCSS, already the pipeline's extractor, reads the first-paint templates as its content, layer-resolved like everything else (`_layouts/core/root.html`, each `_layouts/**/core/base.html`, every `_includes/**/sections/nav.html`, the app shell's `app-topbar.html` and `app-sidebar.html`, every `_sections/**/hero/section.html`, and the shared `heading/masthead` component), plus every band any template stamps `data-omega-first-paint`: the extractor scans the layers for those `<section>` chunks and feeds ONLY the band's markup, so the attribute that starts a band's reveals at parse time is also what selects its critical css, and a whole page layout never drags its below-the-fold vocabulary into the block. So a theme, or a consumer that overrides one of those files, gets its own nav and hero rules inlined with no per-theme bookkeeping, and a page that opens on the nav plus a hero (the shipped home page) paints with no layout shift because every class those templates really render carries its rules, the collapsed mobile menu's `.collapse:not(.show)` guard included. A route whose FIRST band is neither of those paints that band with nav-only styling until the deferred sheet lands; stamp the band `data-omega-first-paint` (which also starts its reveals at parse time, ahead of the motion engine) if that shift matters. The one safelisted lane is motion ([#763](https://github.com/Omega-JS-Stack/omega/issues/763)): every reveal rule is scoped `html[data-omega-motion] …` and resolved by `data-omega-inview`, tokens no markup scan can see, so the extractor purged the whole lane and a built page painted its first-paint copy visible, stamped it, and met the deferred sheet with nothing left to transition — no fade at all. A greedy `data-omega-(motion|reveal|inview)` pattern keeps it, about 1.1 KB, and the site-wide greedy `omega-` lane stays out. Two more rules ride the same safelist because no markup scan reaches them (the [#763](https://github.com/Omega-JS-Stack/omega/issues/763) proof measured the playground home at CLS 0.27 without them, 0.07 with): the skip link's `visually-hidden-focusable` hide rule, since body.html renders that link before every band and the rest of that file is `hidden` alert bars whose icon vocabulary would cost 11 KB of block, and the `omega-dotfield__canvas` positioning, since the dotfield module creates its canvas at runtime and an unpositioned canvas lands in flow whenever the module beats the deferred sheet. Keyframes are pruned to what the kept rules reference; every `@font-face` stays, because the kept rules name their family through `var(--omega-font-*)`, which PurgeCSS cannot follow, and a late `@font-face` is a swap-time reflow (the eight declarations cost about a kilobyte, and the faces the head preloads are among them). The block has a **72 KiB budget** (`CRITICAL_MAX_BYTES`): the packaged themes measure 64 KB (neobrutalism) to 71 KB (newsflash; classy 68 KB), 12 to 15 KB gzipped, roughly one initial congestion window arriving with the HTML instead of costing a round trip; over budget the build warns by name and still ships the block, since a heavier theme is that theme's call. `omega dev` extracts nothing (that lane never purges either), and with no critical block the head falls back to the plain blocking link, so a watch rebuild never flashes. Pinned by `test/critical-css.test.js`.
+- **The head warms only the origins the page will really use** ([#467](https://github.com/Omega-JS-Stack/omega/issues/467) Phase 2). [head.html](../core/_includes/core/head.html) emits a `preconnect` + `dns-prefetch` pair per third party, each gated on the SAME config read the loader makes, so a provider that is off costs nothing and no page ships a handshake nobody spends. The list: `https://www.googletagmanager.com` on `analytics.providers.google.id`, `https://connect.facebook.net` on `analytics.providers.meta.id`, `https://analytics.tiktok.com` on `analytics.providers.tiktok.id` (the three origins `core/js/core/analytics-loader.js` injects a script from), and `https://securetoken.googleapis.com` + `https://firestore.googleapis.com` on `cloud.config.apiKey`, which is the very value `@omega.js/client` boots the Firebase SDK on (auth refreshes the persisted token, then the auth module reads the account doc). Chatsy's pair on `inbound.chat.providers.chatsy.enabled` predates all of them and is unchanged. **`crossorigin` follows the REQUEST, not the habit**: the Firebase origins are CORS fetches so their warmup is anonymous, while the three analytics origins are plain `<script src>` loads, where an anonymous preconnect would open a connection the tag cannot reuse. Consent gates the injection, never the warmup: a preconnect sends no request and sets no cookie, and the connection is already open by the time a visitor accepts the banner. The GA4 beacon origin (`www.google-analytics.com`) is deliberately NOT warmed, since nothing reaches it until gtag.js has loaded and consent has been granted, which is well past the first viewport. Pinned by `test/head-preconnect.test.js`.
+- **Font preloads come from the sheet's `@font-face` rules** ([#765](https://github.com/Omega-JS-Stack/omega/issues/765), after [#467](https://github.com/Omega-JS-Stack/omega/issues/467) Phase 2 and [#749](https://github.com/Omega-JS-Stack/omega/issues/749)). The css lane reads the COMPILED main bundle (`firstPaintFontFaces` in [assets.js](../src/assets.js)) and fills `assetManifest.fontPreloads`, which [head.html](../core/_includes/core/head.html) loops into one `<link rel="preload" as="font" crossorigin>` per face. The rule is what the CSS DECLARES, never what a file is named: a face preloads when it carries no `unicode-range` (it covers everything, the single-file variable font case) or when one of its ranges reaches basic latin (U+0000-00FF) — `U+0131`, `U+0100-02BA` and the `U+00??` wildcard form all reduce to their lowest codepoint. So a theme that vendors one variable face, or names its files its own way, is covered the day it ships; the old `site.fontPreloads` name rule (`*-normal-latin.woff2` / `*-italic-latin.woff2` off the first theme layer with a `fonts/` dir) is gone, and so is the `site` key. woff2 only (the one format the `type="font/woff2"` link names), deduped and sorted so the emitted HTML is deterministic, and kept to the faces the build actually SHIPS — the inheritance hatch hands a partial theme the default skin's `@font-face` rules without its font files ([#177](https://github.com/Omega-JS-Stack/omega/issues/177)), and a preload for a face that is not there is a 404. A face hosted on another origin (an absolute or protocol-relative `src`, the CDN case) rides through untouched: the browser can fetch it, and the head's link already carries the `crossorigin` the spec asks for. Both styles ride the list: every display headline renders its accent as an `<em>` (the `heading/masthead` cluster, the hero's `headline_accent`), so the first viewport asks for italic as surely as it asks for normal; once #749 made the hero paint with the document, an unpreloaded italic swapped in AFTER first paint and put a 0.02 CLS on the unthrottled trace at 72 ms. The `-latin-ext` subsets stay OUT by their ranges: they cover glyphs the first viewport's copy does not use, and every extra preload competes with the ones it does. The list is root-relative like every other manifest URL — the HTML transform mounts it under a base path. In `omega dev` the path is explicit, and not a race: the asset watcher rebuilds the sheet on a theme's `@font-face` (or font-file) edit, folds the new list into the live manifest (`refreshLiveManifest` in [commands/dev.js](../src/commands/dev.js)) and — only when the list actually MOVED — rewrites `.omega/asset-manifest.json`. Eleventy watches that file, so its re-render happens after the asset build rather than beside it, and only when the head's list changed. The `assetManifest` global is registered as a CALLBACK for this to land: an object handed to `addGlobalData` is snapshotted at registration, so the re-render has to re-read the live object to see the new list. Classy still preloads exactly four faces (Inter + Newsreader, normal + italic, latin), newsflash its own four; pinned by the font-preload tests in `test/themes.test.js`.
+- **The fallback face is metric-matched, so the swap moves nothing** ([#768](https://github.com/Omega-JS-Stack/omega/issues/768), after [#765](https://github.com/Omega-JS-Stack/omega/issues/765)). A preloaded face still lands late on a slow connection, and `font-display: swap` reflowed every paragraph when it did (the [#763](https://github.com/Omega-JS-Stack/omega/issues/763) proof measured `/terms` at CLS 0.158, one shift at 3.1 s on the body copy). So the css lane GENERATES a fallback face per vendored family: `@font-face{font-family:"Inter Fallback";src:local("Helvetica Neue");size-adjust:105.508%;ascent-override:91.818%;descent-override:22.862%;line-gap-override:0.000%}`, and rewrites every `--omega-font-*` stack to name it immediately after the web family. The system font then occupies the same lines the webfont will, and the swap is free. `size-adjust` is the width ratio of the two faces and each vertical override is the web face's own proportion divided by it (an override is read against the already adjusted em), which is the fontaine / `next/font` formula. The numbers are MEASURED from the font files at build time by [font-metrics.js](../src/font-metrics.js), a dependency-free reader: a WOFF2 is a header, a table directory and one brotli stream (node's own `zlib`), and the reader takes `head`/`hhea`/`OS/2` for the vertical box (`OS/2`'s sTypo* values when the face sets the USE_TYPO_METRICS bit, as a browser does) plus `cmap` and the `hmtx` advances for the width. It reads a bare `.ttf`/`.ttc` through the same table parse, which is how the checked-in table of system-family metrics was measured (see the provenance comment on `SYSTEM_FONT_METRICS`). Width is measured over a fixed English sample rather than read from `OS/2`'s own `xAvgCharWidth`: the spec redefined that field between table versions and vendors did not restate the value (Arial's file says version 3 and still carries its old lowercase figure), so a ratio of two such fields compares two different quantities. Off `OS/2`, classy's Newsreader fallback would size-adjust to 123.5% of Georgia when the text it sets measures 91.2% of Georgia's width, and Inter's to 145.0% of Arial instead of 106.9%; measuring both sides keeps one definition on both ends of every ratio. The generated face lists EVERY measured family the stack names after the web one as a `local()` source, in stack order (classy's UI stack: `Helvetica Neue`, then `Arial`), with the overrides computed against the first: `local()` resolves only where that font is installed, and a face with no resolvable source would hand the swap to an unadjusted tail entry on Windows. The transform (`injectFallbackFonts` in [assets.js](../src/assets.js)) runs on the COMPILED sheet, before the critical extractor, so the inlined block and the deferred sheet carry the same faces and the same stacks; no scss source names a fallback family, and a consumer theme's own faces are covered the day they ship. The fallback family is the theme's OWN choice: the first family after the web font in that token's stack that the metrics table knows (classy ui: Inter → `Helvetica Neue`, classy serif: Newsreader → `georgia`). A stack that reaches no known family gets no face and one warning naming it, never a throw; a face whose file this build does not ship (the [#177](https://github.com/Omega-JS-Stack/omega/issues/177) inheritance hatch) is skipped silently, like its preload. A `local()` face names no url, so the preload list is untouched. Always on, no config key. Pinned by `test/font-fallback.test.js`, `test/font-metrics.test.js` and the inline-block case in `test/critical-css.test.js`.
+- **Charts are the framework's.** `core/js/libs/charts.js` owns [TanStack Charts](https://tanstack.com/charts/latest) — a real dependency of this package, never a runtime CDN load (Ian 2026-07-27), pinned EXACTLY because the library is Alpha ([#772](https://github.com/Omega-JS-Stack/omega/issues/772)). Page code imports the helpers (`loadCharts`, `chartSlot`, `chartColors`, `barChart`/`stackedBarChart`/`doughnutChart`/`lineChart`) and never names the library, so its version and delivery stay ours to change. Every import inside `loadCharts` is dynamic, so ESM splitting puts the library in its own chunks — a page with no chart pays nothing (`test/dataviz.test.js` builds a charting page and pins it). Colors come off the `--omega-chart-*` ramp; `chartSlot` stamps the series onto the box so `@omega.js/client`'s write-on-change `swap` redraws on data-only changes. **Every page goes through the helper — the admin dashboard included** ([#74](https://github.com/Omega-JS-Stack/omega/issues/74)): it passes `colors: ['var(--omega-ok)', …]` to keep STATUS meaning where the categorical ramp would only say "different". The mounted host follows its container's width and is TOLD its height, so a hand-authored host div needs a height-bearing box (`.admin-chart-box`) exactly like `chartSlot`'s markup. A definition is DOM-free, so `chartDefinition(kind, data)` lets node pin all four builders' geometry through `createChartScene`; the PAINT is pinned in the browser by the sandbox e2e lane's chart step (`brands/sandbox-brand/test/e2e/run.js` → `window.__omega.drawCharts()`), which fails a chart whose host holds no SVG mark with a non-zero box.
+- **Graphs are the framework's too.** `core/js/libs/graph.js` owns mermaid on the same terms ([#169](https://github.com/Omega-JS-Stack/omega/issues/169)): a real dependency of this package, never a runtime CDN load, and page code imports the helpers (`loadGraph`, `graphReady`, `graphSlot`, `graphTheme`, `drawGraph`) without ever naming the library. The import inside `loadGraph` is dynamic, so ESM splitting puts mermaid in its own chunk — a page with no diagram pays nothing (`test/graph.test.js` builds a diagramming page and pins it). The module takes a DEFINITION in and puts an SVG out: composing the mermaid text is the page's business, because a diagram's shapes and words are content, not framework. `drawGraph` initializes per render (`startOnLoad: false`, `securityLevel: 'strict'`, `theme: 'base'`) with `themeVariables` resolved from the live tokens — ink, both surfaces, `--omega-line`, `--omega-accent` for the node outline, and the same `--omega-chart-*` ramp charts read, mapped onto mermaid's `cScale`/`pie` slots ([docs/shared/theming.md](shared/theming.md)); mermaid paints with literal colors, so nothing is handed a `var()`, and the read happens at draw time, so a light/dark flip lands on the next redraw exactly like charts. `graphSlot` stamps the definition onto the host so `swap` redraws on definition-only changes, and carries a height FLOOR (`min-height`) — the host is empty until the render lands, and a taller diagram still grows past it. Rendering needs a real DOM, so `drawGraph` itself is not unit-tested, and unlike the chart builders it has no sandbox e2e step yet — the first page that draws a graph should add one.
+- **Browser log lines carry the ONE identity tag.** `core/js/libs/logger.js` owns it: `createLogger('<module>')` returns `{ tag, log, info, warn, error, debug }` printing `[@omega.js/web:<module>] message` with NO timestamp (devtools stamps runtime lines; only the build-time devkit logger in `src/` prefixes `[HH:MM:SS]`) — [#12](https://github.com/Omega-JS-Stack/omega/issues/12). No core/js file hand-writes a tag: the module segment comes from the file's identity (`core/auth.js` → `auth`, `pages/dashboard/account/sections/security.js` → `account:security`), and `console.group`/`%c` lines embed `logger.tag` rather than a literal. Web's own file on purpose — `@omega.js/client`'s twin would stamp the wrong package segment. Every layer reaches it through `__main_assets__/js/libs/logger.js` (the `modules/` lane that imported it relatively is gone, [#624](https://github.com/Omega-JS-Stack/omega/issues/624)). Pinned by `test/logger.test.js` and repo-wide by `scripts/log-tags.test.js`.
+- **Icons** are plain `fa-*` markup everywhere — the build inlines every one the rendered page names, and a runtime watcher upgrades whatever JS creates afterwards ([#619](https://github.com/Omega-JS-Stack/omega/issues/619)): [docs/shared/icons.md](shared/icons.md).
+- **A redirect is a PAGE, and that is the ONLY redirect mechanism the web build has** ([#466](https://github.com/Omega-JS-Stack/omega/issues/466), Ian's ruling 2026-08-22 — pages own URLs, and no config path exists). A page sets `redirect.url` (plus optional `redirect.querystring` forwarding) in frontmatter on the `modules/utilities/redirect` layout, and the build emits **meta-refresh + canonical + noindex**: `<link rel="canonical">` points at the DESTINATION rather than at this URL, `meta.index: false` on the layout keeps the shortlink out of every index and out of the machine files, and `<noscript><meta http-equiv="refresh" content="0; url=…"></noscript>` performs the hop with JavaScript off — all three from the one head ([core/_includes/core/head.html](../core/_includes/core/head.html)), which absolutizes a SITE-RELATIVE destination against `resolved.config.url` because the base-path pass ([#355](https://github.com/Omega-JS-Stack/omega/issues/355)) only rewrites `href`/`src` attributes — and only that one, a single leading slash: a protocol-relative `//cdn.example.com/x` is already absolute and a `mailto:` is not a path, so both ship verbatim. The refresh sits INSIDE `<noscript>` on purpose: with JS on, the layout's `#redirect-config` and its layout-keyed script (`core/js/layouts/modules/utilities/redirect.js`, [#624](https://github.com/Omega-JS-Stack/omega/issues/624)) do the hop and forward the query and the fragment, which a refresh cannot, so the two must never race. That script hops at IMPORT time rather than from a default export — a shortlink must not wait on the @omega.js/client boot the page's other bundles await. The framework ships shortlink defaults (`/account`, the auth aliases, `/billing`, `/admin/dashboard`) a consumer overrides like any default page. Pinned by `test/redirects.test.js`, plus `test/assets.test.js`, `test/contract.test.js`, and `test/slice.test.js`.
+- **A TEMPLATED redirect is a Cloudflare rule, never web config** ([#466](https://github.com/Omega-JS-Stack/omega/issues/466)). `targets.web.redirects` shipped in 0.45.0 and is RETIRED — a config still carrying it fails validation naming its new home. A redirect whose destination is computed from the request path (DashQR's printed QR codes point at `/c/<id>` for unbounded ids) cannot be enumerated as a page, and static hosting has no server to answer it with: the map could only ever be materialized through the built 404 page, so a search engine saw a 404 that redirects rather than a permanent move. Those redirects belong at the edge, where the computation actually happens — `edge.providers.cloudflare.rules.redirect`, reconciled by the manager's edge service ([docs/manager/edge.md](../manager/edge.md)). **`omega dev` does NOT answer edge-owned routes** (the manager call, 2026-08-30): the edge owns them, so a `/c/<id>` request in dev is a plain 404, exactly as it is on the built output — the alternative is a local mirror of Cloudflare's filter language whose only job is to disagree with production. Test the rule against the zone.
+- **A brand's socials come with their shortlinks** ([#429](https://github.com/Omega-JS-Stack/omega/issues/429), legacy UJM parity — brands do NOT hand-author these pages). Every entry of the `socials` config block generates a redirect page at `/<platform>` on the module above ([social-pages.js](../src/social-pages.js)), so `/discord` — which the footer links site-wide — resolves instead of 404ing. The string form is a HANDLE (`twitter: 'somiibo'`) and the destination is the profile URL template-kit's platform patterns derive from it, the same URL JSON-LD `sameAs` and the footer row read; the object form `{ handle, redirect }` adds a destination that is not the profile (kirue's Spotify ARTIST page, where the handle still names the profile `sameAs` points at) and the redirect target wins for the shortlink alone. A blank handle, or a platform with neither a known URL pattern nor a `redirect`, generates nothing — legacy configs list every platform and fill in a few — while a malformed entry (unknown key, non-string handle) is a config ERROR. The pages ride the SAME lane as the default pages, so a consumer page at `/<platform>` takes that URL over, and the layout's own `meta.index: false` keep them noindex and out of the machine files. Pinned by `test/social-pages.test.js`.
+- **So do a brand's download platforms and store listings** ([#561](https://github.com/Omega-JS-Stack/omega/issues/561), the same legacy-parity lane, same FILE-AND-SKIP ruling). An opted-in desktop target generates a redirect page per platform at `/download/<platform>` and one per artifact at `/download/<platform>/<artifact>` (mac/universal, windows/universal, linux/debian + linux/appimage — the URL shape the legacy pages published), and every store listing with a url generates `/extension/<store>` ([target-shortlinks.js](../src/target-shortlinks.js)) — the URLs legacy UJM shipped as hand-maintained default pages (`src/defaults/dist/redirects/download/**`), which store pages, third-party listings and old posts link to and which every migrating brand 404s. The declaration is the SAME curated view `/download` and `/extension` render from ([#85](https://github.com/Omega-JS-Stack/omega/issues/85), [#610](https://github.com/Omega-JS-Stack/omega/issues/610)): `site.targets.desktop.downloads` and `site.targets.extension.listings` — there is no hand-written `download`/`extension` page map any more, and a config still carrying one fails validation. **A download link hands over the FILE, never the releases page** ([#620](https://github.com/Omega-JS-Stack/omega/issues/620)): the shortlinks and the `/download` buttons both redirect to `<releasesUrl>/download/<versionless asset>`, whose names are @omega.js/desktop's own packaging rule (the contract, including the survivor and never-reuse rules for moving the repo: [docs/desktop/releasing.md](../../packages/desktop/docs/releasing.md)) — so a desktop release never touches the website and these URLs never change. Legacy parity on the bare platform URL: `/download/<platform>` points at the platform's FIRST artifact (UJM sent `/download/linux` to the `.deb`). A listing with no url generates nothing — an announced store waits on Coming soon — while a store key that is not a URL segment is a config ERROR, because a shortlink that silently fails to generate is a dead link on a listing nobody controls. Same lane, so a consumer page at one of those URLs takes it over, and the layout keeps them noindex and out of the machine files. Both lanes share the generated-page shape in [redirect-page.js](../src/redirect-page.js). Pinned by `test/target-shortlink-pages.test.js`.
+- **A brand's own collections come with their pages** ([#207](https://github.com/Omega-JS-Stack/omega/issues/207), the legacy dynamic-pages generator's successor). `targets.web.collections` declares them — `docs: { field: 'doc.category', size: 12, title, description, permalink }` — and documents in `_docs/` publish at `/docs/<slug>`, listing at `/docs` (+ `/docs/2…`), one page per category of `field` at `/docs/categories/<slug>`. `field` is the dotted frontmatter path the categories group on (one value or a list), `permalink` moves the whole base, and a built-in collection name is a config error. The pages are generated as virtual templates on the SAME lane as the default pages ([dynamic-pages.js](../src/dynamic-pages.js)): a consumer page at any one of those permalinks takes that URL over, and the markup is the layered `blueprint/collection/*` → `frontend/pages/collection/*` layouts a theme overrides like any other. A declared collection is a SITE collection like the built-ins: its documents publish as `site.<name>` in the `site.posts` shape (`url`, `date`, and the document's own frontmatter at the top level), so a UJM consumer's `{% for product in site.products %}` renders ([#593](https://github.com/Omega-JS-Stack/omega/issues/593) — reaching templates only as `collections.<name>`, frontmatter under `.data`, rendered that loop empty on a green build). Every generated page names itself: category pages carry per-term title/description ([#312](https://github.com/Omega-JS-Stack/omega/issues/312)), and each DOCUMENT of a declared collection gets `meta.title`/`meta.description` filled from its own frontmatter — namespace `title` (or `name`, the other spelling a real corpus uses, [#596](https://github.com/Omega-JS-Stack/omega/issues/596)) and `description` first, bare keys next, a title-cased slug and a backfill sentence last — with the document's own `meta.*` always winning ([#317](https://github.com/Omega-JS-Stack/omega/issues/317), `applyDocumentData`). The layered `blueprint/collection/document` layout gives a document the masthead h1 and back link its siblings have; a document on another layout keeps the derived meta regardless. The blog does NOT ride this mechanism — its default pages stay as they are. Pinned by `test/dynamic-pages.test.js`.
+- **Every page paints under the page paint contract** ([#637](https://github.com/Omega-JS-Stack/omega/issues/637)). Static content paints immediately, user data arrives through bindings with skeletons, an answer the visitor acts on resolves ONCE, every wait behind visible copy has a deadline and a named fallback, and every form's submit control is gated until its answers land: [docs/web/page-contract.md](page-contract.md).
+- **A one-time buy bills on `once`, and its confirmation never polls** ([#668](https://github.com/Omega-JS-Stack/omega/issues/668)). Checkout resolves the frequency from the PRODUCT (`resolveFrequency`, `core/js/pages/payment/checkout/modules/state.js`) — a cadence term only ever belongs to a subscription — so the intent payload, the intent doc, the confirmation URL and every funnel event's `item_variant` carry `once` instead of the `annually` the price-list fallback used to pick; the pricing page's `add_to_cart` says `once` for a one-time product too, and the checkout's funnel value goes through `calculatePrices()`, the one read that knows the `once` key (`begin_checkout` and `add_payment_info` used to report $0 on a product priced `{ once: 49.99 }`). The intent route stamps `type` on the confirmation URL, which the verifier reads as a second guard, so a one-time purchase opens CONFIRMED rather than polling the account for a plan it never writes. Pinned by `test/checkout-one-time-frequency.test.js`, `test/confirmation-verify.test.js`, `test/confirmation-purchase-pixel.test.js` and `test/pricing-switch-cta.test.js`.
+- **A one-time purchase has an account surface, and a refund it can reach** ([#672](https://github.com/Omega-JS-Stack/omega/issues/672)). The account page carries an **Orders** section (`core/js/pages/dashboard/account/sections/orders.js`) listing every purchase — product, order number, date, amount, status — read from `GET /user/orders`, which is the ONLY way a browser can see a one-time purchase at all: `payments-orders` is admin-only to clients and a one-time buy writes nothing to `users/{uid}`, so the route reads the caller's own orders server-side through the admin SDK (the Firestore rules are untouched) and hands back a summary, never the provider's raw resource or the request context. The Refund section reads the SAME fetch (`sections/../modules/orders.js`, one request for both) and is eligible when the subscription is refundable **or** any purchase is: its subject picker lists them, the form posts the picked `orderId`, and the backend's guarded one-time lane — unreachable from the product until now — takes it. `refundable` is the backend's own answer, so a button the page offers is a refund the route accepts, and the success copy no longer tells a one-time buyer their subscription was cancelled. The confirmation page and the one-time receipt email both point at `#orders`. Pinned by `test/account-orders.test.js`.
+- **The crypto pay button is back, on two conditions** ([#642](https://github.com/Omega-JS-Stack/omega/issues/642)). #636 deleted it because no Coinbase provider existed behind it; the provider is real now, so `payment.providers.coinbase.enabled` shows it — AND the product must be one-time. Coinbase Commerce sells a single hosted charge and has no recurring anything, so the backend's intent provider refuses a subscription outright and a button offered on a plan could only end in the checkout's generic failure sentence. `resolveProvider('crypto')` starts a `coinbase` intent and the page redirects to the charge's `hosted_url` like any other provider. Pinned by `test/checkout-crypto.test.js` and `test/checkout-page.test.js`.
+- **A fully discounted total takes the PayPal and crypto buttons away** ([#786](https://github.com/Omega-JS-Stack/omega/issues/786)). PayPal and Coinbase are the two providers whose amount the backend computes and SENDS, and neither API accepts a zero one — so a code covering the whole price (the shipped `WELCOME10OFF` on anything at or under $10) is refused server-side, and `buildBindingsState()` stops offering the buttons that could only end there (`core/js/pages/payment/checkout/modules/state.js`); they come back the moment the code is removed or changed, off the same rebuild every discount change already does. Card checkout is untouched (Stripe and Chargebee hold a real coupon), and a free TRIAL is never this case — nothing is charged today through the provider's own trial machinery and the code comes off the first PAID period, which is exactly what the backend does, so the buttons stay. A brand selling through PayPal (and crypto) alone would be left with an empty grid, so when a code hides every remaining method the discount field's own error line says which code did it and that removing it brings them back — the page-level error surface is not reusable there, it hides the whole checkout and the discount field with it. The terms note dropped its "not available with PayPal" clause with the same change: a PayPal subscription has taken the code as a discounted first period since [#759](https://github.com/Omega-JS-Stack/omega/issues/759). Pinned by `test/checkout-zero-total.test.js`.
+- **One catalog behind /pricing and the account page** ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)). A feature is DEFINED once, in the top-level `features` catalog (name, icon, definition, and a `usage` block on the metered ones), and each product names only its VALUE — so a limit and the row that renders it can no longer disagree, and the definition BACKFILL that used to unify per-product copies is gone with the duplication it papered over. `composePricing(payment, features)` reads both halves for the cards, the common/extra split and the comparison matrix; `payment-config.js`'s `getProductLimits` became the catalog-aware read (only the counted features a product gives a NUMBER); the billing panel's plan bullets read the same two halves, and its **usage bars** read the account's counters through the SAME `@omega.js/account` derivation the backend's gate uses — one bar per counted feature, showing what is left **today** and **this month** with any admin-granted override credits included in the month's number and named beside it. The catalog rides the client blob (`site.client.features`) like `payment` does. Pinned by `test/pricing.test.js`, `test/sections-pricing-cards.test.js`, `test/billing-plan-switcher.test.js` and `test/billing-usage-bars.test.js`.
+- **The account page's connection cards are the CONFIG, and the logos ship in the framework** ([#771](https://github.com/Omega-JS-Stack/omega/issues/771), [#792](https://github.com/Omega-JS-Stack/omega/issues/792), [#793](https://github.com/Omega-JS-Stack/omega/issues/793)). The Connections section used to be closed twice over and a card had two homes: the layout drew one per `connections:` frontmatter row (twelve of them, hardcoded CDN URLs — the Twitch and Kick ones 404), a row WON over the brand's config entry so a brand could not correct one, and `core/js/pages/dashboard/account/sections/connections.js` carried a third list of descriptions naming providers this lane cannot connect. The rows are gone. The card list is every `resolved.config.connections` key carrying a `name` and a `logo` (`_includes/frontend/sections/account-connections.html`, one loop, one card component), the section drives from `Object.keys(connectionsConfig)` alone, and the FRAMEWORK's config defaults carry `name` + `logo` + `description` for the five providers @omega.js/backend ships a module for — so `google: { enabled: true }` is a complete card, and any key a brand writes wins through the ordinary merge chain. `logo` is the NAME of a mark this package ships (`core/logos/brandmarks/original/<name>.svg`, drawn inline by `omega_logo`; `kick.svg` is new) or a full URL (drawn as an `<img>`) — a value with a `/` or a `:` is a URL, anything else is a mark. An enabled provider with no `name`+`logo` still gets the unsupported card naming what its config entry is missing — as does a key that is not a legal provider name (`[a-z0-9-]`, the backend loader's own rule), which is never offered as a live card whatever fields it carries. Pinned by `test/connections-cards.test.js`.
+- **A connect comes back where it started** ([#784](https://github.com/Omega-JS-Stack/omega/issues/784)). `/connections/callback` hardcoded `/dashboard/account#connections` on both its exits, so a brand page that started a connect from its own surface could not get the visitor back to it. The authorize call takes an optional `returnUrl` — one line, `url.searchParams.set('returnUrl', location.pathname + location.search + location.hash)` ([packages/backend/docs/connections.md](../../packages/backend/docs/connections.md)) — which rides the encrypted state and comes back out of `tokenize`; the page navigates there on success and offers it as the way back on an error. It re-checks the rule itself first (a path on this site: one leading `/`, no scheme, no `//`, no backslash, no whitespace), because a value off the wire is never trusted with `location` — anything else, and an answer that named nothing, keeps the default. The account page's own connect passes no `returnUrl` and is unchanged. Pinned by `test/connections-return.test.js`.
+- **The account page collects the address the ad platforms match on** ([#663](https://github.com/Omega-JS-Stack/omega/issues/663)). The profile form's location block carries an optional **Street** and **Postal code** beside country/region/city (`name="personal.location.street"` / `"personal.location.postalCode"`, browser-autofillable), saved by the same FormManager dot-notation write as every other profile field and loaded back by `core/js/pages/dashboard/account/sections/profile.js` — whose payload names every field it loads, so a new input that is not in that literal is written once and never seen again. The schema fields are `@omega.js/account`'s (`personal.location.postalCode` / `.street`, both nullable strings), and the backend's ONE match reader takes the postal code into the `zip` bag key the ad platforms name: it reaches Meta's `zp` on every server conversion, and GA4's `postal_code` / `sha256_street` on the authenticated requests the Measurement Protocol helper builds from the request's own user ([docs/shared/analytics.md](shared/analytics.md)). No signup field and no new flow. Pinned by `test/account-page.test.js`.
+- **A taxonomy term DISPLAYS humanized** ([#457](https://github.com/Omega-JS-Stack/omega/issues/457)). Terms are aggregated keyed by SLUG with the most frequent spelling winning ([collections.js](../src/collections.js)), and that winner is then humanized the way legacy UJM's blog-taxonomy generator titleized every term it named a page after: hyphens and underscores are word breaks (runs collapse), then each word capitalizes first-char-up/rest-down — `time-tracking-tools` reads "Time Tracking Tools" in its page's `<title>`, h1 and description, on blog tags/categories and on a declared collection's category pages alike. Keeping the corpus's own spelling sentence-cased drifted every migrating brand's taxonomy SEO titles. The SLUG is untouched, so no URL moves, and a tag CLOUD still title-cases the raw spelling it iterates (legacy did the same). The one slug rule that is not "non-alphanumeric runs become `-`": an APOSTROPHE is deleted, straight or typographic, so "Beginner's Guides" slugs to `beginners-guides` the way UJM published it instead of splitting to `beginner-s-guides` ([#597](https://github.com/Omega-JS-Stack/omega/issues/597)) — one slugifier ([`@omega.js/template-kit/jekyll-compat`](../../packages/template-kit/src/jekyll-compat.js)) answers both the taxonomy pages and every template's `| slugify`, so the two can never disagree. Pinned by `test/collections.test.js` and `test/blog-taxonomy-meta.test.js`.
+- **Generated sample content announces itself** ([#208](https://github.com/Omega-JS-Stack/omega/issues/208)). The dev-only sample corpus ([sample-content.js](../src/sample-content.js)) renders on the real posts lane with rolling recent dates, so on screen it is indistinguishable from the brand's own writing — until it says so. The generator stamps `generated: true` into every sample document's frontmatter (never the corpus files, so a newly authored sample cannot forget it), and every packaged theme renders a TEST pill wherever such a document shows: base badges the post page, the listing's featured lead and every post card; newsflash (which forks the blog markup) badges its post page, its lead-story splash and its story-card rows. The pill's STYLE is core-homed and theme-agnostic ([core/css/core/_generated-badge.scss](../core/css/core/_generated-badge.scss)), colored off the `--omega-warn` status token family and never a raw hex; its BOX is the shared `omega-chip` (every site writes `omega-chip omega-generated-badge`, so sizing has one home), and it rides the row's meta line ABOVE the title with `align-self: flex-start`, because a card body is a flex column that stretched it into a full-width band under the title ([#322](https://github.com/Omega-JS-Stack/omega/issues/322)) — but the MARKUP is each theme's own, so what stops a forked blog template from dropping the warning is the packaged-theme sweep in `test/sample-generated-badge.test.js`: every theme's blog `index.html`, `post.html` and row unit must carry the conditional, and a future skin fails that test the moment it ships unbadged. The templates key off the frontmatter flag ALONE — no environment check — because samples never inject into a production build; the same suite pins the dev badge and the production absence.
+- **The consumer's whole `src/assets` tree ships verbatim** ([#295](https://github.com/Omega-JS-Stack/omega/issues/295)). The static phase ([static-assets.js](../src/static-assets.js)) copies the framework's core images, then the brand's minted identity set from `<brandRoot>/.omega/assets`, then every child of `src/assets` LAST so consumer files win collisions — so `src/assets/audio/alarm.mp3` serves at `/assets/audio/alarm.mp3` with no configuration (it used to vanish: only `images/` was copied). The exceptions are the three lanes the ASSET pipeline owns as layer roots — `js/`, `css/`, `fonts/` — whose hashed bundles and pruned font set would be undone by a verbatim copy over the top. imagemin still walks `dist/assets/images` alone. Pinned by `test/static.test.js`.
+- **The VISIBLE logo prefers the bridged vector; the CONFIG value stays a raster** ([#467](https://github.com/Omega-JS-Stack/omega/issues/467)). The manager's assets service mints `color-x.svg` beside the png ladder, and the static bridge already shipped both to `assets/images/brand/brandmark.svg` and `.png` — but every template read `brand.images.brandmark`, which is a png in every brand config, so the nav and footer downloaded a raster for a mark that exists as vector. `brand.images.brandmark` cannot simply flip: the manager's payment service hands that same url to Stripe/PayPal as the product image and OG/social cards need a raster too, so a blind swap breaks payment sync. So the READ moves instead, with no new config key: [static-assets.js](../src/static-assets.js)'s `brandmarkSvgUrl()` reports whether the copies about to ship include a `brandmark.svg` (the mint's, or a consumer's own `src/assets/images/brand/brandmark.svg` winning the same collision), the build records it on the asset manifest as `brandmarkSvg` — exactly the lane the favicon links already ride (`manifest.favicons`) — and every template that renders the VISIBLE lockup reads `assetManifest.brandmarkSvg` first, falling back to the configured raster when no mint produced one: the shared chrome (`frontend/sections/nav.html`, `frontend/sections/footer.html`, `global/sections/app-sidebar.html`) and the pages that carry their own mark because they wear no nav (`pages/auth/{signin,signup,reset,token}.html`, `pages/connections/callback.html`, `pages/app.html`, `pages/payment/checkout.html`, `pages/portal/email-preferences.html`, `pages/extension/installed.html`, and the six card sites on `pages/download.html`). The NON-visible reads stay on the raster deliberately: the OG/social image in `core/head.html`, the JSON-LD logo in `core/foot.html`, and the product image the manager's payment service syncs to Stripe/PayPal. A template never guesses the filename: whether the file exists is a build-time fact or it is nothing. An authored `data.logo.src` (a consumer's `_includes/frontend/sections/nav.json`) still outranks both. Pinned by `test/brandmark-svg.test.js`.
+- **`/test/*` is development-only and NEVER deployed** ([#554](https://github.com/Omega-JS-Stack/omega/issues/554), Ian's call 2026-08-24). A production build emits no page whose permalink is `/test` or sits under `/test/` — the framework's own dev surfaces (`/test`, `/test/styleguide`, `/test/libraries/*`, `/test/translation`, `/test/account/*`, `/test/redirect/*`) and a CONSUMER page that claims one of those URLs alike, the same omission the `/test/sections` showcase gallery already rode. Dev builds keep every one of them, which is the whole point of the lane. The boundary is a path SEGMENT, not a bare prefix: `/testimonials` is brand content and ships. Framework defaults drop out at config time (`frameworkPages`), a consumer's page at a `/test` URL through the shared permalink resolver ([engine.js](../src/engine.js)). Pinned by `test/test-pages-production.test.js`.
+- **Production output carries no framework developer comments** ([#330](https://github.com/Omega-JS-Stack/omega/issues/330)). `omega build` renders every `.html` through the production-only minify transform ([minify-html.js](../src/minify-html.js), `keep_comments: false`) and esbuilds every bundle minified, so the head's developer notes and each module's header never reach a built page. Two classes survive on purpose: IE conditional comments (restored verbatim) and third-party LEGAL blocks (`/*! …`) — plus the one class no bundler can reach, comment text inside a generated document STRING. `omega dev` keeps everything for debuggability, and there is no config knob either way. Pinned by `test/production-comments.test.js`.
+- **URLs are flat `.html` with no trailing slash** (`/signin` → `signin.html`, `page.url` extensionless) — legacy UJM/Jekyll parity, in dev and on static hosts alike.
+- **A site can be served under a URL PATH** ([#355](https://github.com/Omega-JS-Stack/omega/issues/355)). Everything a build emits is root-relative, so a GitHub Pages *project* site (`https://<user>.github.io/<repo>/`) used to 404 on every asset. `OMEGA_PATH_PREFIX=/workkit npx omega build` mounts every emitted URL under that path. The value is a PUBLISHER input, never an end-user one — the machinery that publishes the site knows its mount point (workkit's publish reads it off the Pages API), and hosts that serve at the domain root pass nothing — and it is normalized defensively (leading slash added, trailing slash stripped; `/` and unset both mean the domain root, and then no pass runs, so output is unchanged byte for byte). Three lanes carry it ([path-prefix.js](../src/path-prefix.js)): the rendered HTML (`href`/`src`/`srcset`/`action` — asset URLs, favicons, config-sourced `brand.images.*` and every internal link), the emitted CSS (`url()` targets, the theme sheets' `@font-face` sources), and the runtime, which reads the value off `<html data-omega-path-prefix>` through `core/js/libs/path-prefix.js` instead of baking it into a bundle. Page IDENTITY stays site-relative (`data-page-path` is the route the client's route checks compare against), and `omega dev` serves at the root and never sets one. The asset MANIFEST stays root-relative too: the HTML pass is the ONE place its URLs become markup. Pinned by `test/path-prefix.test.js`. The service worker is the fourth lane ([#360](https://github.com/Omega-JS-Stack/omega/issues/360)): `@omega.js/client` reads the same stamp and registers `<prefix>/service-worker.js` at scope `<prefix>/` — the only scope a script served from there can claim — carrying the value to the worker as the `omega-path-prefix` query param on that script URL, because a worker has no document to read the stamp from; `sw/manager.js` reads it back off `self.location.search` and mounts every site URL it builds (`/build.js`, the default notification icon, the default click target). Pinned by `test/service-worker-mount.test.js`.
+- **The Firebase auth helpers are cached, and a failed fetch is not a failed build** ([#548](https://github.com/Omega-JS-Stack/omega/issues/548)). A production build self-hosts the six `/__/auth/*` + `/__/firebase/init.json` files from `{projectId}.firebaseapp.com` ([firebase-auth-helpers.js](../src/firebase-auth-helpers.js)); every fetch is WRITE-THROUGH to `<brandRoot>/.omega/cache/firebase-auth/<projectId>/`, and any failure — offline, sandboxed, rate-limited, `--cached-only` — serves that last good copy with a loud warn naming the date it was fetched. Nothing cached (a first-ever offline build) stays fatal: a site without the handler breaks sign-in silently, and there is nothing to serve. A framework-baked copy is impossible because `init.json` is project-specific, which is why the cache is keyed by project id, and `demo-*` projects skip the whole lane as before. Pinned by `test/firebase-auth-helpers.test.js`.
+- **One environment surface, in the same call form as every sibling framework** ([#717](https://github.com/Omega-JS-Stack/omega/issues/717)). `getEnvironment()` returns `'development' | 'testing' | 'production'` (mutually exclusive — testing wins), and `isDevelopment()` / `isProduction()` / `isTesting()` DERIVE from it, so they can never disagree; `isProduction()` is a real positive check, never `!isDevelopment()`. Gate side effects on the INTENTIONAL check (`isProduction()` for prod-only, `isDevelopment() || isTesting()` for local-or-test). The vocabulary is `@omega.js/config`'s `ENV_ENVIRONMENTS` ([#586](https://github.com/Omega-JS-Stack/omega/issues/586)) — the same three names the `.env.<environment>` overlay files are spelled with — so a `.env.development` and an `isDevelopment()` can never mean different things. Web's Manager equivalent is the CLI class ([cli.js](../src/cli.js)), which mixes the four in via `attachTo()` exactly as `@omega.js/desktop` and `@omega.js/extension` do (statically and on the prototype), and the package export carries them too. Precedence: `OMEGA_TEST_MODE=true` → the context's own `environment` (the deliberate value the verbs thread — `omega build` → production, `omega dev` → development) → `OMEGA_BUILD_MODE` / `NODE_ENV` → development (a bare context is build tooling; a deployed web artifact carries its environment in `/build.json`). Internally the build lanes call it on their own options object — `getEnvironment.call(options)` in [build.js](../src/build.js) / [engine.js](../src/engine.js) / [service-worker.js](../src/service-worker.js), `isProduction.call(options)` in [limit-collections.js](../src/limit-collections.js) / [decisions.js](../src/decisions.js) — instead of comparing a loose `options.environment` string. The BROWSER half already answered the same four ([runtime/manager.js](../runtime/manager.js), off `window.Configuration.environment`) and is fed by this very value — the engine bakes the resolved environment into the `jekyll` global and `/build.json`, so build-time and page-time can never disagree. Pinned by `test/mode-helpers.test.js`.
+- **Nothing generated is committed.** `dist/`, `.omega/` (including the imagemin and Firebase-auth-helper caches and materialized sample content) are build artifacts; the translation cache is the deliberate exception — it IS committed.
+
+## CLI
+
+`npx omega <command>` (alias `omega-web`; bare `omega` prints the listing, as does `help`). Every verb runs `ensureTarget()` first — the local scaffold the retired `omega setup` used to own ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)). It writes no `.env` ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)): the brand root's `.env` is the one file humans and the manager edit, and a target `.env` is an optional per-key override you author yourself.
+
+| Command | Description |
+|---|---|
+| `install` | `i local` links every `@omega.js/*` dep from this monorepo; `i live`/`prod` restores registry specs tree-wide (aliases `-i`, `i`) |
+| `dev` | Dev server: Eleventy watch/serve + in-place asset rebuilds, mkcert HTTPS, emulator wiring (aliases `serve`, `start`) |
+| `build` | Production build → `dist/` (alias `-b`) |
+| `test` | Project scope by default; `framework:`/`omega:`/`web:`/`full:` select the framework suite (alias `-t`) |
+| `deploy` | Sync + dispatch the CI build workflow; `--dry-run` prints the POST, `--local` builds only (alias `-d`) |
+| `update` | Dependency freshness report; `--apply` installs the safe set, `--major` explicit (aliases `outdated`, `out`) |
+| `migrate` | UJM consumer → `@omega.js/web`, in place; `--check` for a zero-write report (alias `migration`) |
+| `customize` | Materialize a default page into `src/pages/`; `<path>` materializes ONE shadowable file (section/include/css) at its shadowing path with a provenance header; `--list` prints the layered override map (every shadowable file, its owning layer, your shadows); no argument lists every customizable URL + lane |
+| `translate` | Translate `dist/` into `translation.languages` (`omega build` runs it automatically when enabled) |
+| `purge` | Cloudflare cache purge (alias `cloudflare-purge`) |
+| `clean` | Remove `dist/` + `.omega/` (alias `-c`) |
+| `version` | Print the framework version (alias `-v`) |
+| `audit` | Lighthouse over a production build: full build → `dist/` served on an ephemeral loopback port → the home page plus every page path argument scored. Report-only until a `--min-<category>` flag (`--min-performance=90`, `--min-accessibility`, `--min-best-practices`, `--min-seo`) arms the gate — under = loud failure + exit 1. Every page also prints LCP, CLS and the form factor the run emulated beside the scores, and `--max-lcp=<ms>` arms the perceived-usability bar the same way (any page over it = loud failure + exit 1). Headless Chrome comes from `CHROME_PATH`, else puppeteer's Chrome for Testing, else a system Chrome (alias `-a`, bare form — pass page paths with the full `audit` name) |
+
+Alias table: [src/cli.js](../src/cli.js).
+
+**The standing performance check** ([#467](https://github.com/Omega-JS-Stack/omega/issues/467)): `npx omega audit --max-lcp=1300` in a brand's website target, run BY HAND before a deploy. Lighthouse's default preset is mobile emulation on Slow 4G, the same shape PageSpeed Insights reports for mobile and the one the #467 proofs measured against (2,588 ms LCP on the home page before the fix wave; the shipped pair after [#763](https://github.com/Omega-JS-Stack/omega/issues/763) brought the above-the-fold fade back is first paint 824 ms and LCP 1,232 ms, gzip, the LCP landing at the end of the fade rather than at first paint), so the printed LCP is comparable run to run and `--max-lcp=1300` is the perceived-usability bar. Deploys are deliberate ([docs/shared/deploys.md](shared/deploys.md)), so there is no scheduled job: the check belongs beside the deploy decision, on a full production build. The fast `omega test` tier never runs Lighthouse; its always-on cheap half is the dist audit ([#468](https://github.com/Omega-JS-Stack/omega/issues/468)). The bar is 1,300 ms, the end of the fade, by ruling (Ian 2026-09-09): the fade is the design, first paint stays under 1 s, and 1.3 s is about half of Core Web Vitals' "good" LCP line.
+
+## Dependency Resolution
+
+- **`@omega.js/client` owns Firebase on the client side.** Page and module code never imports Firebase directly — `omega.firestore()`, `omega.auth()`. It is a real runtime dependency here, never vendored.
+- **`@omega.js/config`, `@omega.js/devkit`, `@omega.js/template-kit` are devDependencies** — private packages vendored into the published tarball by the `vendor` prepare hook. Consumers never install them.
+- **Bundler aliases**: `__main_assets__/*` → the core layer / themes dir, `__theme__/*` → the active theme (base fallback), `omega:<name>` → the same name from the layers BELOW the importing file (sass's `omega:` importer, spelled for JS — [#624](https://github.com/Omega-JS-Stack/omega/issues/624)), `@omega.js/client` (subpaths included) → the client package.
+- **Anything the framework depends on, a consumer imports bare; anything else it declares itself** ([#2](https://github.com/Omega-JS-Stack/omega/issues/2)). A consumer page module's `import { defineChart } from '@tanstack/charts'` resolves from **`@omega.js/web`'s own installation** — the resolve hook [devkit's `bundle`](../devkit/index.md) composes into every build reads the framework package.json's `dependencies` at build time (no curated list — the declared set IS the list) and re-resolves matching bare specifiers and their subpaths from the package root. Consequences: the framework's copy wins even when the consumer declares its own (one copy, one shared chunk with core's own users of the library — the charts helper's @tanstack/charts, DOMPurify, Popper), and a name the framework does not declare resolves normally from the consumer, failing with esbuild's usual `Could not resolve` when it is missing. Build-time-only dependencies (esbuild, sass, sharp) need no exclusion: resolution happens on demand, so nothing enters a bundle unless browser code imports it by name. No CDN `loadScript()` workaround, and offline apps keep working.
+
+## Development Workflow
+
+- **🚫 NEVER use `npx omega ...` from the framework repo** — it is for CONSUMER projects only. Use `npm test`, `npm run prepare`, etc.
+- **🚫 NEVER run a consumer's `omega dev`** — it is the user's long-running dev process. Assume it is running; if it is not, ask the user to start it rather than starting it yourself.
+- **Logs, not scrollback.** Every verb tees its whole run to the target root, truncated per launch and ANSI-stripped: `logs/dev.log` (`omega dev`), `logs/build.log` (`omega build`), `logs/test.log` (`omega test`). Grep them — "did the watcher rebuild?", "what did the last build print?" is a `tail`, never a restart. The mechanism and the full per-surface path table: [docs/shared/logging.md](shared/logging.md).
+- **Prove changes against a real brand.** `brands/omega-playground` and `brands/newsflash-brand` keep both first-party skins alive; the corpus and cross-stack e2e lanes gate behavior changes ([docs/shared/testing.md](shared/testing.md)).
+- **Dev watch targets register themselves — never hand-register one** ([#200](https://github.com/Omega-JS-Stack/omega/issues/200)). Config-time code reads files ONLY through `@omega.js/devkit/reads` ([reads.js](../../packages/devkit/src/reads.js) — devkit-homed per the build-time-harmonization ruling, any framework dev loop may adopt it; `readdir`/`read`/`dirExists`/`fileExists`); each read records its directory, and the recorded union becomes the config-reset watch targets (pruned to ancestors, realpathed outside the consumer dir, missing dirs pre-armed). A direct `fs` read in a config-time module fails the guard test, which names the helper. Scan-shaped questions ("does the brand own posts?", the permalink set) ride a lighter RESCAN lane instead: [decisions.js](../src/decisions.js) re-answers them on their own file events and every rebuild reads fresh answers, so a brand's first real post retires the sample corpus live, with ordinary page edits staying incremental. Permalink collisions surface from the same scan: a loud `[@omega.js/web:decisions]` diagnostic in dev, a failed build in production. Boot-phase reads (the omega.json5 merge, sample-content materialization) stay restart-expected.
+- **Live-verify UI changes via CDP.** Use the `chrome-devtools` MCP tools (screenshot, click, evaluate, console) against the running dev server instead of guessing at rendered output.
+- **Signing in during dev is URL-only.** `npx omega auth:token <uid-or-email>` (the backend CLI — [docs/backend/index.md](../backend/index.md); emulator by default, `--production` explicit) mints a custom token and prints the sign-in URL; open `/signin?authCustomToken=<token>` (with an optional `&authReturnUrl=…`) and the page signs that user in, then goes to the return URL. `?authSignout=true` is the same lane in reverse. `?authPrivateKey=<api.privateKey>` is the DURABLE version, for a URL somebody saves (an OBS dock, a kiosk, a bookmark): a custom token expires in an hour, so the page trades the key for a fresh one at `POST /omega/user/token` on every load, strips the key from the address bar, and never logs it. Every one of these params is read ONLY by the auth pages — `/signin`, `/signup`, `/reset` via [session-params.js](../core/js/libs/auth/session-params.js) — so appending them to any other page does nothing.
+- **Provider signin runs the REDIRECT flow in dev, exactly as it does in production** ([#156](https://github.com/Omega-JS-Stack/omega/issues/156)). The auth emulator's OAuth handler hands the credential back through `sessionStorage` on the origin it is served from, so on the emulator's own port (`http://localhost:9099`) it is a third party to the site: the browser partitions that storage by top-level site, the SDK's helper iframe reads an empty partition, and `getRedirectResult()` resolves null forever. `omega dev` closes that gap by PROXYING the emulator under the site origin — `/emulator/*` plus the `identitytoolkit`/`securetoken` REST prefixes, mounted at the site root because `connectAuthEmulator()` discards any path on the URL it is given — so handler and iframe are first-party and share one partition. It is the dev counterpart of the self-hosted `/__/auth/*` helpers a production build ships. The dev server declares the proxy in the page chrome (`dev.authEmulatorProxy`) and @omega.js/client then points the emulator at `window.location.origin`. [oauth.js](../core/js/libs/auth/oauth.js) keeps the popup for exactly two cases: an iframed page and the `?authPopup=true` override. A redirect that comes home empty is loud, not silent: the page reports it and says so inline.
+
+## CI secrets — `.env` is the source ([#189](https://github.com/Omega-JS-Stack/omega/issues/189))
+
+`omega deploy` publishes the target's **composed env** to the brand repo's **GitHub Actions secrets** as a precheck before it dispatches, and every verb's `ensureTarget()` regenerates the scaffolded workflow's env block — one `KEY: ${{ secrets.KEY }}` line per published key — so CI reads the same key set the laptop does. Nothing is hand-created and nothing is hand-edited: add the key to the brand root's `.env`, deploy.
+
+- **Collected**: `composeTargetEnv({ targetDir, target: 'web' })` ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)) — company `.env` ← brand `.env` ← target `.env`, the brand-side layers filtered by the env schema to the keys the web target reads (`deliverAs` applied, so the brand's `GOOGLE_ANALYTICS_SECRET_WEB` publishes as `GOOGLE_ANALYTICS_SECRET`), the target layer passing through unfiltered. The brand root's `.env` is the one file a human keeps; a target `.env` is an optional per-key override that no machine writes. An empty value never claims a key, and the name must be UPPER_SNAKE.
+  - **FILES only, never the shell**: a key that exists only in the shell is never published, and a shell value never overrides a file's — CI gets what the brand's files say, under any shell.
+- **Except the machine-local lane** ([#454](https://github.com/Omega-JS-Stack/omega/issues/454)): the env schema's `machineLocal: true` flag ([env-schema.js](../../packages/config/src/env-schema.js)) marks the developer-tooling keys that live in `.env` but are not secrets. They never enroll as Actions secrets and never inject into a workflow — the drop happens once, in `deliveredNames()` ([env-delivery.js](../../packages/config/src/env-delivery.js)), the source of both sets. The flag is the seam a future key joins; today it is `OMEGA_FONTAWESOME_ROOT` alone.
+  - **The CI FontAwesome story**: `OMEGA_FONTAWESOME_ROOT` is a path to the developer's local Pro download (the fleet convention sets `~/.omega/fontawesome` in every brand-root `.env`). That path does not exist on a runner, so publishing it churned the secret list per machine and handed CI a dead path that fell back silently. **CI resolves Pro icons through the `@fortawesome` npm token lane instead** — the registry auth of [docs/shared/icons.md](shared/icons.md), with `@fortawesome/fontawesome-pro` installed from it; the free floor is the fallback when no token is configured. The filesystem root is a laptop convenience only.
+- **Transport**: the `gh` CLI (`@omega.js/devkit/actions-secrets`), values on **stdin**, never in argv and never logged. No usable `gh` fails LOUD with install/auth instructions — `omega deploy --no-secrets` is the opt-out (the same flag name on desktop and extension). Publishing is unconditional (the API can't report a secret's current value, so "unchanged" isn't detectable); setting the same value twice is harmless.
+- **Skips loudly** (a `[deploy]` line, never silence): CI itself, a target with nothing composed, no git remote, or a remote that isn't the brand's own repo (`repo.providers.github` names a different one — a target inside a framework/test monorepo never arms that monorepo's Actions).
+- The workflow's `env:` block is FRAMEWORK-OWNED and rewritten by every verb's `ensureTarget()`; `GH_TOKEN`/`CLOUDFLARE_TOKEN`/`NODE_VERSION`/`NODE_ENV` stay declared by the template and never duplicate into the generated region.
+- **In a brand monorepo the workflow lives at the BRAND ROOT** ([#265](https://github.com/Omega-JS-Stack/omega/issues/265)): GitHub runs workflows from the repo root's `.github/workflows/` only, so the scaffold skips `.github/**` in the target and composes the template into `<brand>/.github/workflows/<target>-build.yml` via `@omega.js/devkit/ci-workflows` — every post-checkout `run:` step scoped to the target (a per-step `working-directory:`, never a workflow-level `defaults.run.working-directory` — it would scope the pre-checkout steps too, where the target dir does not exist yet), the path inputs an action ignores `working-directory:` for rewritten to the target dir (`actions/cache`'s `path` + its `hashFiles()` key pattern, `peaceiris/actions-gh-pages`'s `publish_dir` — otherwise the publish pushes a repo-root `dist/` no build wrote), a per-target concurrency group, the same `.env` secrets block rendered in, regenerated on every verb (a rerun rewrites that one file, never duplicates), and the target's dead copy swept when the framework wrote every line of it: an exact match, or a copy a SUPERSEDED template wrote (the pre-secrets-block copies #189 left behind are the same file minus the lines it added, [#334](https://github.com/Omega-JS-Stack/omega/issues/334)); a copy carrying a line no current template ships is kept and reported instead (an edit that ONLY deletes template lines still reads as framework-written and is swept). `omega deploy` dispatches the composed name (`website-build.yml`) in a brand and the plain `build.yml` standalone. A standalone project is its own repo root and keeps its `.github/workflows/build.yml`.
+
+## Supply-Chain Security
+
+All `npm install` calls in CLI commands (`npx omega i`, the local-linking flows) route through devkit's `safeInstall()` helper (`@omega.js/devkit/safe-install`, invoked by `@omega.js/devkit/local`). It prefixes `sfw` (Socket Firewall) when installed — blocking confirmed malware at the network level before packages reach disk — and falls back to plain npm when sfw is absent. Installs **fail if sfw detects confirmed malware** anywhere in the dependency tree; non-critical CVEs and quality warnings pass through.
+
+## File Conventions
+
+- **CommonJS** in `src/` (prepare-package copies `src/` → `dist/` 1:1, no transforms). **ESM** in `runtime/` and `sw/` — those are browser bundles.
+- **`fs-jetpack`** over `fs` / `fs-extra` for file operations.
+- One `module.exports = ...` per file; **short-circuit early returns** rather than nested ifs; **logical operators at the start of continuation lines**.
+- **No backwards compatibility** unless explicitly requested.
+- Every module carries a top-of-file JSDoc block naming what it owns — match it when adding one.
+- **Tests are `node --test`**, one file per concern under `test/`, real builds over fixtures — never mock the engine.
+
+## Doc-update parity
+
+Whenever you make a behavioral change (new command, new flag, new contract, removed feature), update:
+
+1. **[README.md](../README.md)** — the long-form package reference
+2. **`docs/web/index.md`** (this file) — the map, one line or a cross-link
+3. **`shared/<topic>.md`** and the web deep references here in `docs/web/` — the deep reference (sections, theming, testing, deploys, updates, translation, icons, config)
+4. **`../../CHANGELOG.md`** — `[Unreleased]`, on ship
+
+Validate first, then document — write docs that describe shipped reality, not intentions.
+
+## Documentation
+
+- [README.md](../README.md) — the package's own long-form reference (module map, packaged content, URL shape, service worker, tokens, theming tiers, app shell, pricing, responsive images, the test-pinned engine facts, and what is not built yet)
+- [docs/web/sections.md](sections.md) — the section/component contract · [docs/web/omega-sections-spec.md](omega-sections-spec.md) — the ratified architecture spec
+- [docs/web/page-contract.md](page-contract.md) — the five paint rules every page owes a visitor: immediate static content, bindings for user data, one-shot answers, deadlines with named fallbacks, gated form submits
+- [docs/web/libs.md](libs.md): the `core/js/libs/` inventory, covering the `__main_assets__` import idiom, every shared browser module with its exports, and the auth cluster
+- [docs/shared/theming.md](shared/theming.md) — the `--omega-*` design-system contract · [docs/web/classy-v2/DIRECTION.md](classy-v2/DIRECTION.md) — the visual spec
+- [docs/shared/config.md](shared/config.md) — omega.json5 shape, merge chain, and the legacy mapping tables `omega migrate` implements
+- [docs/test-framework.md](../docs/test-framework.md) — the consumer test guide: the layered doctrine, what `omega test` builds and smoke-checks (the internal link check and the four audit checks — meta, fragments, alt, sitemap orphans — with their shared `config/link-exceptions.json5`), the scope grammar, authoring `node --test` suites
+- [docs/shared/testing.md](shared/testing.md) — the verification tiers and which lane gates what
+- [docs/shared/deploys.md](shared/deploys.md) · [docs/shared/updates.md](shared/updates.md) · [docs/shared/translation.md](shared/translation.md) · [docs/shared/icons.md](shared/icons.md) · [docs/web/ads-system.md](ads-system.md)
+- [docs/shared/local-dev.md](shared/local-dev.md) — linking this monorepo into a brand · [docs/shared/brands.md](shared/brands.md) — which brand is which
+- [docs/shared/publishing.md](shared/publishing.md) — the private-latch policy and the proving checkpoint