@omega.js/manager 0.1.0

package/docs/directory.md

@@ -0,0 +1,140 @@
+# The directory service — a brand's entry in its parent's directory
+
+The `directory` service ([#246](https://github.com/Omega-JS-Stack/omega/issues/246)) is
+how a brand keeps its own listing current in the project ABOVE it. During the manage
+walk the brand PUSHES an entry into the parent project's Firestore `brands` collection at
+`brands/{brand.id}` — identity plus whatever opt-in blocks it declares — and whatever the
+parent runs on top of that collection reads a directory that is never stale.
+
+**The boundary.** The framework owes the fresh ENTRY. It owes nothing else. The
+marketplace, hub or admin surface that CONSUMES the directory is brand code and never
+enters the framework — ITW's guest-post sponsorship marketplace is the first consumer, and
+its routes, pricing UI and moderation stay in the ITW brand. That split is why the write is
+a merge, not a replace: the framework owns its own sections of the entry and the hub owns
+everything else it keeps on the same document.
+
+Legacy omega-manager wrote this collection centrally, from the brand configs it held in
+`.brands/*/config.json`. A brand migrated onto OMEGA has no central config to be written
+FROM, so the direction inverts: each brand pushes for itself, from its own omega.json5.
+
+## The config a brand writes
+
+Opt in at the shared (brand) level of `config/omega.json5`:
+
+```json5
+{
+  // Which project's directory this brand belongs in. Required — no parent
+  // relationship, no directory to push into.
+  parent: 'https://itwcreativeworks.com',
+
+  // Opt in. Absent, `false`, or an empty block all mean "do not push": the
+  // parent publishes the collection for anyone to read, so participation is
+  // never implicit.
+  directory: {
+    enabled: true,
+  },
+
+  // The first BLOCK. Declared → published; absent → the block is removed from
+  // the entry on the next walk.
+  sponsorships: {
+    acceptable: ['productivity', 'business', 'social media'],
+    unacceptable: ['link-in-bio services', 'social media link services'],
+    prices: {
+      'guest-post': 20,
+      'link-insertion': 10,
+    },
+  },
+}
+```
+
+Both keys are schema-known in `@omega.js/config`. **Public facts only**: the entry lands in
+a collection the parent declares world-readable (the one operator step below), and the
+validator's secret-shape guard is the hard floor on what can go in them. Credentials never
+appear here — the service authenticates with
+`DIRECTORY_SERVICE_ACCOUNT` in the brand `.env`, a path to the PARENT project's Firebase
+service-account JSON (absolute, or relative to the brand root), the `server` service's
+mechanism exactly. The service account names the target project.
+
+## What lands in the entry
+
+```json5
+// brands/{brand.id} in the parent project
+{
+  brand:  { id, name, url },                 // identity — `url` only when configured
+  github: { owner, name, repo },             // repo slugs, omitted unless BOTH halves resolve
+  sponsorships: { … },                       // the declared block, verbatim
+}
+```
+
+`github` is `@omega.js/config`'s ONE repo derivation
+([#290](https://github.com/Omega-JS-Stack/omega/issues/290)) — the same `{ owner, name,
+repo }` a backend app reads as `config.resolved.github`. The service never re-derives it,
+and a half-resolved repo (an owner with no name, or the reverse) is omitted rather than
+pushed broken.
+
+## The read rule the parent adds (the one operator step)
+
+Nothing in the framework grants the public read. A compiled-rules project is admin-only by
+default — the framework half's `match /{document=**}` is the floor — so the PARENT, the
+project the entries land in, declares the collection public itself. Once, by hand, in its
+own `firestore.rules` source (the brand half, under "Your rules"):
+
+```
+    // The brand directory: every brand's own entry, readable by anyone.
+    // Writes stay closed — the pushing brand authenticates with a service
+    // account and bypasses rules.
+    match /brands/{id} {
+      allow read: if true;
+      allow write: if false;
+    }
+```
+
+`omega build` compiles that into the parent's `dist/firestore.rules` and `omega deploy`
+ships it. Skipping the step costs the push nothing (a service account writes past rules
+either way) — it costs every CLIENT that tries to read the directory, which is the whole
+point of the collection.
+
+## The gates and the diff
+
+Three gates, each a clean skip, in order: `directory.enabled: true`, a `parent` to push
+into, and not a `demo-*` (emulator-only) brand — the cloud service's gate, for the same
+reason: an offline fixture must never reach a live project. A missing
+`DIRECTORY_SERVICE_ACCOUNT` skips too.
+
+The push reads first and writes only on drift, so an unchanged config performs **zero
+writes** on every subsequent walk. Drift is compared against the framework-owned slice of
+the document only, so a hub-owned field appearing beside the entry is not drift and is
+never rewritten. The write is a `patchDoc` whose updateMask names every owned section —
+including the ones with no value this run, which is how a block the brand drops from config
+disappears from the directory instead of lingering.
+
+## Legacy → doc field mapping
+
+Legacy source: omega-manager `.brands/<brand-id>/config.json` (read-only reference).
+Target: `brands/{brand.id}` in the parent project.
+
+| Legacy `.brands/<id>/config.json` | Directory entry field | Note |
+|---|---|---|
+| `brand.id` | document id `brands/{brand.id}`, and `brand.id` | Unchanged; denormalized into the entry as legacy did |
+| `brand.name` | `brand.name` | Unchanged — the ITW routes read `brand.brand.name` |
+| `brand.url` | `brand.url` | Unchanged — the ITW routes derive the brand's API host from it |
+| `github.orgMain` / `github.orgWebsite` + `github.templates.website.{useOrgWebsite,suffix}` | `github.owner` | **Derived, not carried.** Legacy pushed the raw org pair and the CONSUMER picked between them; the entry now carries the already-resolved owner from `repo.providers.github` ([#290](https://github.com/Omega-JS-Stack/omega/issues/290)) |
+| `brand.id` + `github.templates.website.suffix` (`'-website'` default), composed by the consumer | `github.name` | **Derived, not carried.** One repo per brand now (the brand monorepo), so the `<id><suffix>` composition retires with the split-repo era |
+| — | `github.repo` | New: the `owner/name` slug the GitHub API takes, so no consumer composes it |
+| `sponsorships.acceptable` | `sponsorships.acceptable` | Verbatim |
+| `sponsorships.unacceptable` | `sponsorships.unacceptable` | Verbatim |
+| `sponsorships.prices['guest-post']` | `sponsorships.prices['guest-post']` | Verbatim (USD) |
+| `sponsorships.prices['link-insertion']` | `sponsorships.prices['link-insertion']` | Verbatim (USD) |
+| `parent` | — | Not published: it names WHERE the entry goes, it is not part of the entry |
+
+The two placement keys are the only ones the 23 legacy brands with a `sponsorships` block
+ever used. `prices` is an open map, not an enum — a new placement type is a config line, not
+a framework change. `marketing.newsletter.*.sponsorships` in the legacy configs is a
+different thing entirely (newsletter ad slots) and never entered this collection.
+
+## Adding the next block
+
+One entry in `packages/manager/src/services/directory/lib/blocks.js` naming the brand-config
+section it reads, plus its schema line in `@omega.js/config`. A block crosses only when the
+brand declares its section, and `OWNED_SECTIONS` picks it up automatically, so removal
+converges for free.

package/docs/disperse.md

@@ -0,0 +1,46 @@
+# The disperse service — signing artifacts into the targets
+
+The `disperse` service is what remains of legacy omega-manager's disperse after the config
+hierarchy dissolved file dispersal: targets read `config/omega.json5` directly, so there is no
+`.brands/` mirror and no per-repo config writes. What cannot ride the hierarchy is exactly
+what this service still moves — binary signing artifacts.
+
+It runs on the DELIVERY lane (`BOOT_SERVICES`): every `omega dev` boot, every brand-root
+`omega deploy`, and the full manage walk — after `certificates` (the artifacts must exist) and
+before `update` (builds read the cert files).
+
+## What it delivers
+
+One operation, `certs`: the certificates service's signing tree —
+`{companyRoot||brandRoot}/.omega/certificates/apple/` — copied into each desktop/mobile
+target's certs dir. The copy itself is devkit's (`@omega.js/devkit/certs`,
+[#678](https://github.com/Omega-JS-Stack/omega/issues/678)), the ONE delivery step every verb
+rides, so a desktop build reaches the same artifacts through the same rules. What lives here is
+the manage-lane framing: which targets get a pass, the config gate, and the per-rule reporting.
+
+Optional rules skip silently when their source is missing; REQUIRED rules warn (the build
+would be unsigned) and the operation returns warned with the count. A brand with no Apple
+artifacts at all — certificates disabled, or never run — is a quiet note, not a warning.
+
+A miss is WARN-ONLY — the delivery never deletes, which is why certs is NOT one of the
+reconcile surfaces (those are [assets](assets.md) and [workspace](workspace.md)). Every dest is
+a documented HUMAN drop point (desktop's [signing guide](../../packages/desktop/docs/signing.md)
+tells an operator to `cp` their `.p12`/`.p8` straight into `config/certs/`), and
+`omega company init` scaffolds `.omega/certificates/apple/` EMPTY — which passes the tree guard
+above. A delete-on-missing pass would therefore eat hand-placed signing material on the very
+next build, so a dest with no source in the tree is reported and left exactly where the
+operator put it.
+
+## Config
+
+- `certificates.enabled: false` (or `certificates: false`) — nothing to disperse.
+- The target set is every dir mapping to a framework with a cert file map (desktop, mobile).
+
+## Gotcha: no machine composes a target `.env`
+
+`.env` composition is GONE ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)). The
+brand-root `.env` is the ONE file humans and the manager edit, and every verb composes its
+target's runtime env from the cascade by schema. A CUSTOM target has no `@omega.js/config` to
+walk the cascade for it, so it INHERITS instead: `manage.js` loads the env chain into
+`process.env` before it spawns anything, which is why a custom target started by `omega dev`
+or `omega deploy` has the brand keys and a standalone run inside the target dir does not.

package/docs/domain.md

@@ -0,0 +1,56 @@
+# The domain service — the registrar points at Cloudflare
+
+The `domain` service does one thing: make the registrar's nameservers point at the brand's
+Cloudflare zone. It runs right after the `edge` service, because the values it writes are the
+nameservers that zone was assigned.
+
+## What it reconciles
+
+One operation, `nameservers`:
+
+1. Read the Cloudflare zone to learn its assigned nameservers.
+2. **namecheap** (the one API registrar today) — read the current nameservers and set them
+   when they mismatch.
+3. **Manual registrars** — an ACTIVE zone proves the nameservers are already set (success); a
+   pending zone prints the exact values to set and returns warned.
+
+Since [#662](https://github.com/Omega-JS-Stack/omega/issues/662) a brand-new zone that has no
+nameservers assigned yet is WAITED on rather than deferred: a bounded poll (six reads, 5s
+apart) gives Cloudflare the seconds it needs, and only a zone still bare after that — or a run
+with no TTY — reports warned with the rerun message.
+
+## Config
+
+`domain` carries TWO roles, each with its own providers block
+([#425](https://github.com/Omega-JS-Stack/omega/issues/425)):
+
+- `domain.providers.<registrar>` — the registrar. Presence picks one; no entry means nothing
+  chosen and this service skips. `namecheap` is reconciled via API, everything else
+  (`squarespace`, …) is manual guidance.
+- `domain.email.providers.<provider>` and `domain.email.forwarding` — the MAILBOX provider.
+  This service does not read them: the `edge` service's `dns-records` and `email-routing`
+  operations do.
+
+`domain.enabled: false` skips the service.
+
+## Credentials
+
+- `CLOUDFLARE_TOKEN` — always, even for a manual registrar: the required nameserver values
+  come off the zone.
+- `NAMECHEAP_USERNAME` + `NAMECHEAP_API_KEY` — only when the registrar is namecheap (their
+  registry entries carry a `when` that drops them otherwise).
+
+## Gotchas
+
+- **Namecheap's API is IP-whitelisted.** The client detects its own public IP via
+  `api.ipify.org`; that address must be whitelisted in the Namecheap dashboard or every call
+  is refused. Since [#698](https://github.com/Omega-JS-Stack/omega/issues/698) a refusal is
+  walked rather than warned: an interactive run names the IP to add, gates on Enter to open
+  the [API access page](https://ap.www.namecheap.com/settings/tools/apiaccess/) (enable, key
+  reset and whitelist all live there), and rechecks the refused call until it passes — ENTER
+  checks now, `s` steps aside. Non-interactive and dry runs warn and continue as before.
+  There is no JSON variant of the API — it is the XML query API.
+- **Nameservers live at the REGISTRABLE domain.** For a subdomain project
+  (`playground.omegajs.dev`) that is the parent (`omegajs.dev`) — the zone the edge service
+  manages and the domain the registrar actually holds. The split uses the public suffix list,
+  not a last-dot-label pop, so `mybrand.co.uk` resolves correctly.

package/docs/edge.md

@@ -0,0 +1,234 @@
+# The edge service — the brand's Cloudflare zone
+
+The `edge` service reconciles the brand's zone to `edge.providers.cloudflare` in
+`config/omega.json5`: the zone itself, DNS records, email routing, zone settings, the five
+rulesets, scheduled speed tests, and workers. It runs early — third in the walk — because
+every DNS-dependent service after it needs the zone to exist. Every handler follows
+read → diff → write (Cloudflare requires fetching current state before patching), and each
+read step is cached to `.omega/cache/cloudflare/{op}.json` as a debugging aid.
+
+## What it reconciles
+
+| Operation | What it does |
+|---|---|
+| `zone` | The zone exists; created when missing. A pending zone reports its nameservers, and an interactive run on a manual registrar opens the registrar's nameserver page and polls until the zone activates. The resolved id lands in `edge.providers.cloudflare.zone` ([#434](https://github.com/Omega-JS-Stack/omega/issues/434)) — the id `omega purge` targets from a build, where no Cloudflare token is in play — and rides the run as state for every later operation. |
+| `dns-records` | The required platform record set (GitHub Pages, `www`, the email provider's MX/SPF, DMARC; BIMI and the SendGrid CNAMEs only when configured) plus `dns.records` custom entries, diff-synced: create, update, delete. |
+| `email-routing` | Cloudflare Email Routing, only when `domain.email.providers` names cloudflare; rules come from `domain.email.forwarding` (`[{ from: 'support' \| '*', to: 'inbox@…' }]`). |
+| `zone-settings` | A flat map matching Cloudflare's own setting IDs, diffed in one bulk read and patched per changed setting (Cloudflare has no bulk PATCH). Addon settings (`speed_brain`, `fonts`) need their own GET each. Read-only and absent settings are skipped, and one setting's failure never blocks the rest. |
+| `cache-rules` | The `http_request_cache_settings` entrypoint ruleset, rules matched by description. The framework ships the whole default set (below), so a brand that declares nothing still gets both cache lifetimes. |
+| `rules-managed-transforms` | Cloudflare's managed request/response headers, enabled or disabled per config name, PATCHed in one call. |
+| `rules-redirect` | The `http_request_dynamic_redirect` ruleset — the ONE home for a brand's templated redirects ([#466](https://github.com/Omega-JS-Stack/omega/issues/466), below). |
+| `rules-configuration` | The `http_config_settings` ruleset. |
+| `rules-response-headers` | The `http_response_headers_transform` ruleset (always PUT — at the ruleset's id when it exists, at the phase entrypoint when it does not). |
+| `rules-security` | Custom firewall rules in `http_request_firewall_custom`. |
+| `speed-scheduled-tests` | The homepage's Speed Test schedule (a create-or-replace POST on the custom Speed API endpoint). |
+| `workers` | Worker scripts + routes from `edge.providers.cloudflare.workers` — `script` names a file in the service's own `workers/` dir, `route` supports `{ domain }` templating. Unconfigured workers and routes are removed. |
+
+## Config
+
+Everything sits under `edge.providers.cloudflare`:
+
+- `enabled: false` — the tri-state opt-out; the whole service skips.
+- `zone` — the resolved zone id, written back by the `zone` operation.
+- `dns` — `spf` (`'strict'`/`'soft'`), `dmarcPolicy`, `spfIncludes`, `dmarcReports.{rua,ruf}`,
+  `bimiLogo`, and `records[]` for custom entries such as verification TXTs. The SendGrid
+  domain-auth values are NOT here — they are read live off SendGrid every run
+  ([#692](https://github.com/Omega-JS-Stack/omega/issues/692), below).
+- `settings` — the zone-settings map, keyed by Cloudflare's setting IDs exactly.
+- `cacheRules[]`, `rules.{managedTransforms,redirect,configuration,responseHeaders,security}`,
+  `speedTest.{frequency,region}`, `workers[]`.
+
+The manager's defaults hold PLATFORM answers only; company-specific values (DMARC report
+addresses, the BIMI logo, extra CSP hosts) belong in the company or brand layer.
+
+**Credential**: `CLOUDFLARE_TOKEN` in the brand `.env`, asked for through the shared setup
+contract. No `brand.url` → the service skips.
+
+## Cache lifetimes: /assets for a year, HTML for a minute
+
+The manager's defaults carry the whole `cacheRules` set, so a brand that declares no rules
+still reconciles both of them ([#751](https://github.com/Omega-JS-Stack/omega/issues/751)):
+
+| Rule | Matches | Edge TTL | Browser TTL |
+|---|---|---|---|
+| `Assets: Cache for 1 Year` | `/assets/*` plus `/__/auth/iframe.js`, on any host | 1 year | 1 year |
+| `HTML: Short Browser Cache` | a SITE host (not `api.`), outside `/assets`, with no file extension or ending `.html` | 2 hours | 1 minute |
+
+The safety in the one-year rule is the CONTENT HASH, and only the CSS and JS bundles carry
+one (`main-39ce99d8.css`, `first-paint-A7T6PAIK.js`): new bytes get a new URL, so the old
+one can be held forever. **Fonts and images under `/assets` are NOT hashed** — they land at
+stable names by design (`assets/fonts/inter-normal-latin.woff2`,
+`assets/images/brand/brandmark-640px.webp`), because `@font-face` src URLs are written into
+theme CSS. So replacing a font file or a logo in place pins the OLD file in visitors'
+browsers for up to a year, and a purge cannot reach a browser copy: ship such a replacement
+under a new filename, or accept the year.
+
+HTML is the opposite of a hashed bundle: its URL never changes, so whatever a browser holds
+IS what a returning visitor sees until it expires. One minute is short enough that a deploy
+is visible almost immediately; the rule sets its own 2-hour edge TTL (a cache rule overrides
+the zone's `edge_cache_ttl` setting) and a deploy purges it.
+
+**A cache rule is ZONE-scoped, so the HTML rule is guarded by host.** The zone serves the
+brand's site AND `api.<domain>`, whose Firebase rewrites answer extensionless, user-scoped
+GETs (`/authorize`, `/token`, `/omega/**`, `/mcp/**`) — edge-caching one of those would hand
+one user's answer to the next. The zone also serves `emailurl.<domain>`, the proxied SendGrid
+link-tracking CNAME, whose extensionless click and open URLs must reach SendGrid on every hit or
+campaign counts undercount. The guard is `not starts_with(http.host, "api.")` plus the same for
+`emailurl.`, rather than an equality on the site host, because every OTHER host on the zone is
+a site host: the apex, `www`, and a subdomain project served under the parent zone. Those two
+are the non-site hosts the stack creates, at every shape it builds (`api.brand.com`,
+`api.app.brand.com` — `packages/manager/src/services/cloud/ensure/hosting.js`;
+`emailurl.<domain>` — `packages/manager/src/services/edge/lib/dns-records-helpers.js`). A
+hand-added `dns.records` host for some other service is not covered; declare your own
+`cacheRules` in that case. The assets rule needs no guard: both of its paths are static files
+wherever they are served from.
+
+The two rules cannot both match one request — the HTML expression excludes `/assets` across
+BOTH of its path shapes (extensionless and `.html`), not just the extensionless one.
+Extensionless is the normal page shape here, since the default redirect rule strips trailing
+slashes (`/about`), and `not … contains "."` is how the free plan says "no file extension"
+(`matches` needs Business).
+
+`cacheRules` is an ARRAY, and arrays REPLACE across the config merge chain: a brand
+declaring its own `edge.providers.cloudflare.cacheRules` replaces the framework set whole
+(the same doctrine as `rules.redirect`), so its block has to carry any platform rule it still
+wants. A subdomain project never runs this operation at all (below) — the parent brand's
+zone owns the rules its subdomains are served under. A TTL of `0` is a legal value that
+reaches Cloudflare as declared rather than falling back to the default
+([#754](https://github.com/Omega-JS-Stack/omega/issues/754)): `browserTtl: 0` is `max-age=0`,
+revalidate on every request, and a `0` edge TTL means whatever Cloudflare's own rules grammar
+makes of it (a full edge bypass is a MODE there, not a TTL).
+
+**Static hosting contributes nothing here.** The web target publishes to GitHub Pages, which
+has no header configuration, and nothing in the stack writes a hosting config for the built
+site — so the edge is the ONE place a brand's cache lifetimes are set
+([docs/shared/deploys.md](shared/deploys.md)).
+
+## Templated redirects live here, not in the web config
+
+A redirect whose destination is COMPUTED from the request path — DashQR's printed QR codes
+point at `/c/<id>` for unbounded ids, and every one of them must land on `/code?id=<id>` —
+cannot be enumerated as a page, and static hosting has no server to answer it with. It needs
+edge computing, so `edge.providers.cloudflare.rules.redirect` is its one home
+([#466](https://github.com/Omega-JS-Stack/omega/issues/466)): the web target's own
+`targets.web.redirects` block shipped in 0.45.0 and is retired, and a config still carrying
+it fails validation naming this key.
+
+An entry is `{ name, expression, statusCode, preserveQueryString, targetUrl, enabled }`, in
+Cloudflare's own filter language — nothing is translated, because the edge is what evaluates
+it:
+
+```json5
+{
+  name: 'Redirect: QR short code',
+  expression: '(starts_with(http.request.uri.path, "/c/"))',
+  statusCode: 301,
+  // The target carries its OWN `?id=`, so an inbound querystring must not be appended
+  preserveQueryString: false,
+  targetUrl: { expression: 'concat("https://", http.host, "/code?id=", substring(http.request.uri.path, 3))' },
+  enabled: true,
+}
+```
+
+`targetUrl` takes `{ value }` for a fixed destination and `{ expression }` for a computed
+one. The ruleset is reconciled whole — a configured rule is created or updated by `name`,
+and a rule in Cloudflare that config does not name is REMOVED — so the block is the complete
+desired set, the manager's platform defaults (the trailing-slash rule) included.
+
+A redirect whose URLs CAN be enumerated is not this: it is a redirect PAGE in the web target
+(`redirect.url` in frontmatter on the `modules/utilities/redirect` layout,
+[docs/web/index.md](../web/index.md)).
+
+**`omega dev` does not answer these routes** (the manager call, 2026-08-30). The edge owns
+them, so `/c/<id>` is a plain 404 in dev, exactly as it is against the built output — a
+local mirror of Cloudflare's filter language would exist only to disagree with production.
+Verify a rule against the zone.
+
+## Subdomain projects use the parent zone
+
+When `brand.url` is not an apex (`playground.omegajs.dev`), the service works on the PARENT
+zone (`omegajs.dev`) and runs only `zone` and `dns-records` — zone-level settings, rules and
+workers belong to the parent brand. `dns-records` then only touches records belonging to the
+subdomain. Creating the parent zone is inert until the registrar's nameservers point at it,
+which the `domain` service handles right after.
+
+## Gotcha: a subdomain project's API host stays DNS-only, so it gets no Cloudflare geo headers
+
+Cloudflare's Universal SSL — every plan, free included — covers the apex and exactly ONE
+label below it (`*.omegajs.dev`). A subdomain project's API host is two labels deep
+(`api.playground.omegajs.dev`), so no certificate at the proxy can terminate TLS for it, and
+the `cloud` service's hosting ensure leaves that CNAME **DNS-only** (grey cloud) with
+Firebase serving the certificate instead (`packages/manager/src/services/cloud/ensure/hosting.js`,
+`zoneTlsCoverage`). Traffic therefore never passes through Cloudflare, and Cloudflare's
+visitor-location headers — the ones the `addVisitorLocationHeaders` managed transform turns
+on — never reach that API. Region and city read null in the backend
+([#638](https://github.com/Omega-JS-Stack/omega/issues/638)) and no edge setting fixes it:
+nothing is missing, the name is simply outside the certificate.
+
+- **Top-level brands are unaffected**: `api.brand.com` is one label under the zone, Universal
+  SSL covers it, the record is proxied, and the geo headers arrive.
+- **The fix for a subdomain project is the paid Cloudflare add-on** — Advanced Certificate
+  Manager / Total TLS on the zone. The gate already recognizes it: the hosting ensure asks the
+  zone for its ACTUAL coverage (`/acm/total_tls`, then active certificate packs) and proxies
+  the name the moment a certificate covers it, printing which coverage let it through. A
+  lookup failure falls back to not-covered — a DNS-only record works on every plan, a wrongly
+  proxied one never does.
+- **The log line names it either way**: verified-but-uncovered prints "Universal SSL stops at
+  `*.<zone>`; no Total TLS or deeper cert pack on this zone — CNAME stays DNS-only, Firebase
+  serves the certificate".
+
+## The SendGrid records come from SendGrid, not from config
+
+`emailauth.<domain>`, the `<id>.<domain>` owner CNAME, `emailurl.<domain>` and both DKIM keys
+are all built from one host, `u<id>.<whitelabel>.sendgrid.net`. Those values are SendGrid's own
+observed facts about the domain, so `dns-records` READS them per run
+(`GET /v3/whitelabel/domains`, the same client the campaigns service uses, `SENDGRID_API_KEY`
+from the brand `.env`) instead of carrying a config copy that nothing ever wrote back
+([#692](https://github.com/Omega-JS-Stack/omega/issues/692)).
+
+Every no-answer skips the whole SendGrid set and prints the reason: no `SENDGRID_API_KEY`, no
+authenticated domain for this brand's domain (the campaigns service creates it), an unreachable
+SendGrid, or a `mail_cname` that is not the `u<id>.<whitelabel>.sendgrid.net` shape — that last
+one names the host it got. A dry run does the same read and names the host in its plan; a
+subdomain project never asks, because the apex record set belongs to the parent brand.
+
+## Gotcha: the branded-link CNAME is grey until SendGrid validates it
+
+`emailurl.<domain>` is the one SendGrid record that rides Cloudflare's proxy. SendGrid
+validates a branded link by resolving that host as a CNAME to `sendgrid.net`, and a
+Cloudflare-PROXIED record answers with the edge's own addresses instead — so proxying it
+before validation locks the branding out of ever validating and every emailed link stays
+broken ([#646](https://github.com/Omega-JS-Stack/omega/issues/646)). The handler therefore
+asks SendGrid first (`GET /v3/whitelabel/links`) and only proxies once that host reports
+`valid: true`.
+
+Since [#662](https://github.com/Omega-JS-Stack/omega/issues/662) the walk WAITS for that
+answer instead of leaving the flip to a later run: `pollWithSpinner` re-asks SendGrid every
+10s (ENTER checks now, `s` skips) and the same pass proxies the CNAME. A skipped wait, or a
+run with no TTY, keeps the record grey and returns **warned** with the reason — "SendGrid has
+not validated the branded link — the emailurl CNAME stays unproxied" — so the run summary
+names what is still owed. An unreachable SendGrid or a subdomain project answer NO the same
+way: the unproxied record is the safe half of the pair (with no key or no authenticated
+domain, the SendGrid records are skipped outright).
+
+A host with NO link-branding entry is the one NO that never waits — the `campaigns` service
+creates and validates the branding LATER IN THE SAME WALK, when campaigns is enabled for the
+brand ([#693](https://github.com/Omega-JS-Stack/omega/issues/693)), so waiting on it here would
+never end. The line says so, the record lands grey (exactly the state SendGrid validates
+against), and the step is not **warned**: there is nothing pending for this service to finish.
+When the campaigns service's validation passes, it flips that same record to proxied itself;
+this handler's next live read agrees, because a valid branding desires a proxied record. On a
+brand's FIRST walk this handler writes no SendGrid records at all — the live domain-auth read
+finds nothing yet — so the campaigns service writes both link CNAMEs itself.
+
+## Other gotchas
+
+- **The Speed API rejects a zone that is not active yet** (`speed.errors.zone_not_active`) —
+  the operation skips until activation instead of failing.
+- **A never-used ruleset phase** answers "could not find entrypoint ruleset"; that is detected,
+  and the first write POSTs a new ruleset rather than PUTting a missing one.
+- **Rules are matched by their `name`** (Cloudflare's `description`): rename a rule in config
+  and the old one is removed and a new one created.
+- **`omega-api-proxy.js`** is for a brand whose api host fronts a dedicated non-Firebase
+  backend: the worker carves `/omega` (and the legacy `/backend-manager` alias) out at the
+  edge and proxies it to the brand's Cloud Functions, passing everything else through.

package/docs/email.md

@@ -0,0 +1,42 @@
+# The email service — the brand's Replyify agent
+
+The `email` service keeps the brand's customer-service email agent on
+[Replyify](https://replyify.app) in sync — its Gmail filter and its knowledge — and sets the
+agent-owner account to the configured plan. Agents live in Replyify's OWN Firestore, so this
+is an OPERATOR service, with the same clean-skip contract as forms and chat.
+
+Not to be confused with `domain.email` (mailbox routing, owned by the `edge` service) or the
+marketing lanes (`campaigns`, `newsletter`).
+
+## What it reconciles
+
+- **`agent`** — the FILTER is the brand's Gmail query (the `---filter---` section of the brand
+  repo's `config/replyify.md`, or auto-generated as `to:(@domain)`) ANDed with the packaged
+  baseline exclusion filter; the KNOWLEDGE is the packaged baseline plus that file's knowledge
+  section. Diff-synced and patched with a leaf mask, so Replyify-owned fields survive.
+- **`user`** — the agent owner's subscription set to
+  `inbound.email.providers.replyify.plan` (Replyify's Max top tier by default) through the
+  shared owner-plan reconciliation.
+
+## Config
+
+| Key | Meaning |
+|---|---|
+| `inbound.email.providers.replyify.enabled: false` (or `replyify: false`) | Skip. |
+| `inbound.email.providers.replyify.agentId` | The agent. Missing → minted or asked for. |
+| `inbound.email.providers.replyify.templateAgentId` | The shape donor for create-on-missing. |
+| `inbound.email.providers.replyify.plan` | The owner account's plan. |
+| `inbound.email.providers.replyify.updateAgentInfo: false` | A shared agent another brand manages. |
+
+## The three auth tiers (Ian 2026-07-13)
+
+1. **Operator SA** — `REPLYIFY_SERVICE_ACCOUNT` in the brand `.env`: full create + manage,
+   minting the brand's own agent from `templateAgentId` and converging filter/knowledge/plan in
+   the same run.
+2. **User API key** — `REPLYIFY_API_KEY` is recognized; product-API management is not wired yet.
+3. **Dashboard** — an interactive run opens replyify.app and takes the pasted agent id, with a
+   Disable option.
+
+## Gotcha
+
+A wrong `agentId` is a visible error, never a silently created orphan document.

package/docs/forms.md

@@ -0,0 +1,48 @@
+# The forms service — the brand's Slapform contact form
+
+The `forms` service keeps the brand's contact form on [Slapform](https://slapform.com) in sync
+and sets the form-owner account to the configured plan, so the brand has full access. Forms
+live in Slapform's OWN Firestore, which makes this an OPERATOR service: it needs a service
+account for Slapform's Firebase project. Every other brand answers "Disable permanently" once
+and is never asked again — that clean skip is the sanctioned outcome, which is why the
+credential never gates a run.
+
+## What it reconciles
+
+- **`form`** — the form document's name (`Contact Form - {brand.name}`) and `settings.enabled`,
+  diff-synced: read first, patched only on drift.
+- **`user`** — the form owner's account subscription set to
+  `forms.providers.slapform.plan` (Slapform's top tier by default), through the shared
+  owner-plan reconciliation. The form document carries the owner UID.
+
+## Config
+
+| Key | Meaning |
+|---|---|
+| `forms.providers.slapform.enabled: false` (or `slapform: false`) | Skip. |
+| `forms.providers.slapform.formId` | The form. Missing → minted (below) or asked for interactively. |
+| `forms.providers.slapform.templateFormId` | The company layer's shape donor for create-on-missing. |
+| `forms.providers.slapform.plan` | The owner account's plan (`plan.id` required). |
+| `forms.providers.slapform.updateFormInfo: false` | The form is shared and another brand owns its branding — never renamed or re-enabled from here. |
+
+The service also requires a `web` target: the contact form lives on the brand's website.
+
+## The three auth tiers (Ian 2026-07-13)
+
+1. **Operator SA** — `SLAPFORM_SERVICE_ACCOUNT` in the brand `.env` (path to the
+   service-account JSON, absolute or brand-root-relative). Full create + manage: a missing
+   `formId` with a `templateFormId` configured MINTS the brand's own form — a product user
+   (email = brand contact email, password through the account service's owner channels) plus a
+   doc shape-templated from the donor — writes the new id back into omega.json5, and the
+   ensures converge name/settings/plan in the SAME run.
+2. **User API key** — `SLAPFORM_API_KEY` is recognized, but management through the product's
+   public API lands when those routes are verified; today it is a named skip.
+3. **Dashboard** — an interactive run opens slapform.com and takes the pasted form id
+   (comment-preserving writeback, with a Disable option). Non-interactive and dry runs skip
+   cleanly.
+
+## Gotcha
+
+A `formId` that points at no document is an ERROR, not a create: omega-manager silently
+created a name-only orphan document in that case. Fix the id, or let the operator tier mint
+one.