@omega.js/manager 0.1.0

package/docs/brand.md

@@ -0,0 +1,151 @@
+# Working in a consumer brand monorepo
+
+> Framework-owned. This is the brand-root guide: what a session inside ANY consumer brand needs before touching files. Brands reach it through the agent-docs chain (their root `AGENTS.md` imports the top-level omega `AGENTS.md` via `node_modules` — contract: [shared/agent-docs.md](shared/agent-docs.md)) and through the omega plugin's `omega:manager` skill. Brand-specific notes never go here; they live below the import in that brand's own `AGENTS.md`.
+
+## What you are working in
+
+A **brand monorepo**: one brand (`config/omega.json5`), npm workspaces, one dir per enabled target under `targets/`. The `@omega.js/*` frameworks do the heavy lifting — targets stay thin (config + content + custom routes/pages).
+
+| Target dir | Target | Framework | Required reading |
+|---|---|---|---|
+| `targets/website/` | web | `@omega.js/web` | the `omega:web` skill → `docs/web/index.md` |
+| `targets/backend/` | backend | `@omega.js/backend` | the `omega:backend` skill → `docs/backend/index.md` |
+| `targets/desktop/` | desktop | `@omega.js/desktop` | the `omega:desktop` skill → `docs/desktop/index.md` |
+| `targets/extension/` | extension | `@omega.js/extension` | the `omega:extension` skill → `docs/extension/index.md` |
+| `targets/<name>/` | custom ([#603](https://github.com/Omega-JS-Stack/omega/issues/603)) | none — the target's own stack | its own README; the contract is [index.md](index.md) § Custom targets |
+
+**Before doing ANY work inside a target, read its framework's guide** — the omega plugin's inject hook loads the matching skill automatically in that target, and the skill points at the guide; architecture, conventions, APIs, and gotchas live there, not here.
+
+A **custom target** is the exception: `targets.<name>: { type: 'custom' }` in the brand config declares a target no framework owns (a Render API, a worker, a script). It has no framework guide and no framework services — everything it can do is what its own `package.json` scripts (`start`, `build`, `test`, `deploy`, `clean`) declare, and the manager runs those.
+
+## Brand root anatomy
+
+- `config/omega.json5` — THE brand config (shared sections + `targets.<type>`; key presence = target enabled). Targets in a brand carry NO config file of their own.
+- `.env` — secrets, ALWAYS (the config loader hard-fails secret-shaped keys in omega.json5). Gitignored.
+- `.env.development` / `.env.testing` / `.env.production` — the per-environment OVERLAYS of that `.env` ([#586](https://github.com/Omega-JS-Stack/omega/issues/586)). Only the keys that differ for one environment: the run's own environment picks exactly one file, its values win over the base, and every other environment's file is never read. Put a `sk_test_…` in `.env.development` and the live key in `.env`. Onboard scaffolds all three empty; `.env.*` is gitignored. The mechanics: [shared/config.md](shared/config.md#the-env-cascade-secrets--d15).
+- `.omega/` — the secrets store, run output, caches, and the per-machine deploy record. Gitignored; never commit it. No durable state file: every provisioned fact the manage cycle resolves lands in `config/omega.json5`, every secret in `.env` ([#434](https://github.com/Omega-JS-Stack/omega/issues/434)).
+- `targets/<target>/` — one workspace per enabled target (see table above). A brand still carrying the old `apps/` folder is fixed ONCE, by hand — `npx omega manage --migration=targets-rename --execute` (bare = the audit, moving nothing) renames the folder and flips the root `workspaces` glob with it; re-run `npm install` afterwards so npm re-links the workspaces. Nothing heals it inside a run: every other verb fails loud on the old shape and names that command. Both folders at once is a half-done migration and fails loudly rather than guessing ([shared/breaking-changes.md](shared/breaking-changes.md#one-vocabulary--a-brands-surfaces-live-in-targets-443)).
+- `logs/` — the brand-level run logs, one file per brand-root verb: `logs/manage.log`, `logs/dev.log`, `logs/build.log`, `logs/clean.log`, `logs/deploy.log`, `logs/update.log`, `logs/test.log`, `logs/pipeline.log` ([#623](https://github.com/Omega-JS-Stack/omega/issues/623)). Gitignored, truncated on every launch.
+- `AGENTS.md` / `CLAUDE.md` — the doc chain: `CLAUDE.md` is a one-line `@AGENTS.md` pointer; `AGENTS.md`'s first line imports the framework guide; everything below the import is the brand's own.
+
+**The brand's repos are named `<brand.id>-<role>`** (Ian 2026-09-07, [#809](https://github.com/Omega-JS-Stack/omega/issues/809)). Two roles exist today: `omega`, the brand's SOURCE monorepo (the one you are working in), and `releases`, the one public repo the desktop releases and the autoupdater feed live in. Both are derived, never typed: `@omega.js/config` answers `<brand.id>-omega` for the source repo and `<brand.id>-releases` for the releases one, under the owner `repo.providers.github.org` names, so every verb that addresses a repo (`omega deploy --direct`, the manager's github service, desktop's release lane) reaches the same address. A brand whose repo is named something else declares it: `repo.providers.github.repo` takes a bare name or an `owner/name` slug and wins over the default, which is how a repo under the paid company org is addressed.
+
+### The placement contract — where a thing lives, and what refreshes it
+
+**Authored-once shared things live at the brand ROOT and are distributed from there** (`config/omega.json5`, the `.env` files, the agent docs); **target code and every generated artifact live IN the target** (build hooks, logs, `dist/`, the composed per-target env). A file that is not authored is DERIVED: it refreshes on the verb that owns it and is never hand-edited ([#623](https://github.com/Omega-JS-Stack/omega/issues/623)).
+
+The asymmetry the contract had to settle: `config/omega.json5` is **walked**, never copied — a key deleted at the root is gone from the next read everywhere. `.env` is walked too since [#678](https://github.com/Omega-JS-Stack/omega/issues/678) retired dispersal, so the ONE env copy left is the backend's `dist/.env`, recomposed by every verb that stages it. Neither surface can leave a deleted key behind.
+
+One row per surface; **Siblings** is the set that must match each other (a new mechanism on one sibling and not the others is a defect):
+
+| Surface | Authored where | Lands where | Mechanism | Siblings |
+|---|---|---|---|---|
+| Brand config | `<brandRoot>/config/omega.json5` | read in place — no copy | **walked** (`defaults ← company ← brand shared ← brand targets.<type> ← local`) | every target reads the one file through `@omega.js/config` |
+| Env + secrets | `<brandRoot>/.env`, `.env.<environment>`, company `.env` under both; `.omega/secrets/` for provisioned key material; `targets/<target>/.env` is an optional per-key override | the run's own process env; backend also `targets/backend/dist/.env` | **walked** per verb; the backend `dist/.env` is **generated** per verb ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)) | web · backend · desktop · extension compose from the same cascade (the runtime `environment()` accessor is the open parity gap: [#717](https://github.com/Omega-JS-Stack/omega/issues/717)) |
+| Owner hooks | `<brandRoot>/config/hooks/<point>.js`, else the company root's | loaded in place — no copy | **walked** at the call site | every hook point the services declare (today `account/password.js`); committed by default |
+| Target build hooks | `targets/<target>/hooks/<point>/{pre,post}.js` | in the target | **scaffolded once** (copy-once), then the target's own file | desktop · extension — one ctx (`{ manager, projectRoot, mode }`), same per-target discovery, desktop adds release/notarize; web has NONE by design and backend's "hooks" are Firebase blocking functions, a name collision ([#591](https://github.com/Omega-JS-Stack/omega/issues/591)) |
+| Logs | nobody — output only | `<brandRoot>/logs/<verb>.log` · `targets/<target>/logs/{dev,build,test}.log` | **generated**, truncated per launch, gitignored | every brand-root verb (manage, dev, build, clean, deploy, update, test, pipeline) · every target |
+| Translations | source strings in the target's own content | `targets/<target>/translations/{lang}/{namespace}.json` | **generated incrementally, COMMITTED** — a warm cache builds with no AI credentials ([#24](https://github.com/Omega-JS-Stack/omega/issues/24)) | web today; any future target that renders copy |
+| Caches | nobody — derived data | `<brandRoot>/.omega/cache/**` | **generated**, gitignored, safe to delete (`--force` ignores them) | every caching service: edge reads, the update fingerprints, web's firebase-auth helpers |
+| Build output | nobody — compiled | `targets/<target>/dist/` (+ `packaged/`) | **generated** per verb, gitignored, never edited | every target |
+| Agent docs | the framework monorepo (`AGENTS.md` + `docs/`); the brand's own notes below the import in `<brandRoot>/AGENTS.md` | `<brandRoot>/AGENTS.md` + `CLAUDE.md`; `.claude/settings.json` | **distributed** — the workspace service maintains the `node_modules/@omega.js/AGENTS.md` symlink the import resolves through ([shared/agent-docs.md](shared/agent-docs.md)) | every brand root; targets carry none by design |
+| Package scripts | the manifest's other keys are yours | `<brandRoot>/package.json` + each `targets/<target>/package.json` | **generated write-on-change** — only the named verb keys, every other key and the ordering untouched | brand root (`start`, `manage`, `deploy`) · every target's framework `projectScripts` |
+| Tests | per surface: `targets/<target>/test/`; the brand's own browser lane at `<brandRoot>/test/e2e/run.js` | in place | **walked**: each target's own runner, then the brand lane, fanned out by the brand-root `omega test` ([#775](https://github.com/Omega-JS-Stack/omega/issues/775)) | every target · the brand e2e lane |
+
+One file inside `.omega/` is not derived data: `.omega/company.json`, present only in a brand that belongs to a **company workspace**. It is the stamp that makes this brand inherit the company's config layer, its `.env` (under this brand's own), and its shared Apple signing tree — written by `omega company adopt` (or by `omega onboard` inside a company) and re-stamped by company-wide runs. Nothing else about the brand changes. What a company workspace is, and the two commands that own it: [company.md](company.md).
+
+## Verbs (the whole interface)
+
+Run from the **brand root**:
+
+```bash
+npm start                           # local dev stack (website + backend by default; `npm run dev` is the same)
+npm run manage                      # manage: reconcile EVERY service to omega.json5 (idempotent)
+npm run manage -- --service=<name>  # reconcile one service (workspace, repo, cloud, edge, …)
+npm run deploy                      # DELIBERATE publish fan-out: each target's own deploy, backend first
+npx omega build                     # build fan-out: every target, backend first
+npx omega clean                     # clean fan-out: wipe every target's build output
+npx omega test                      # test fan-out: every target, then the brand's own e2e lane
+```
+
+Every fan-out covers EVERY target type ([#603](https://github.com/Omega-JS-Stack/omega/issues/603)) — a framework target runs its framework's own verb, a custom target runs the matching `package.json` script, and a target that declares no such script steps aside loudly (naming the target and the verb) instead of failing. `build` and `clean` take `--target=` like `deploy` (and like `dev`, `update` and `test`: one picker on every fan-out, [#780](https://github.com/Omega-JS-Stack/omega/issues/780)), plus `--dry-run` (every target prints the command it would have run and nothing executes), and unlike `deploy` a failing target never stops the rest: nothing is published, so one run names every broken target.
+
+**The test walk covers the brand itself, not only its targets** ([#775](https://github.com/Omega-JS-Stack/omega/issues/775)). After every target's own runner, `omega test` runs `<brandRoot>/test/e2e/run.js` when that file exists: ONE entry file by convention, so the walk never guesses which file in the folder is the runner. That lane is the brand's browser proof, driving its real pages against its real local stack (the backend emulator with its seeded personas, plus the real `omega dev`), built on `@omega.js/devkit/test/e2e-harness`. It is a runner script, so like a custom target's `test` script it hears no scope ids and no flags: a bare run reaches it, a scoped or picked or laned run does not. A `test/e2e/` folder with no `run.js` is skipped in one line, never failed. **The browser comes with the manager**: `@omega.js/manager` carries puppeteer, so a brand installs nothing for the lane, and the flip side is that every brand install downloads a Chrome (~150 MB). A brand that will never run the lane skips that download with `PUPPETEER_SKIP_DOWNLOAD=1` in the environment its `npm install` runs in (CI included); the lane then reports the missing browser by name if it is ever run.
+
+Three flags shape the walk. `--target=<a,b>` is the target picker (a comma list of target keys like `web`, or dir names like `website`) and it composes with every scope: `omega test --target=backend framework:` is the backend target's framework suite, `omega test --target=web` its project tests. A framework scope whose owning target the picker excludes is a contradiction, and the run refuses by name rather than testing nothing. `--extended` (real external services) reaches every target. `--lane=<name>` reaches the targets whose framework DECLARES that lane in its package.json `omega.testLanes`; a target that declares none prints one line and the run stays green, because a lane a framework does not serve is not a failure there. A forwarded PATH works the same way: the walk sets `OMEGA_TEST_FANOUT=1` on every target run, so a target that carries no file matching the path answers with a distinct exit code and counts as a miss rather than a failure. The run fails only when every target missed, and says so in one line naming the target, because a path no target carries is a typo and testing nothing is never a green ([#814](https://github.com/Omega-JS-Stack/omega/issues/814)).
+
+The scripts are the named verbs (`omega manage`, `omega dev`, `omega deploy`) — a bare `omega` prints help and runs nothing. `npm start`'s boot reconciles the LOCAL lane only (workspace, assets, disperse); `npm run manage` is the full setup. There is no per-target setup step to remember ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)): a target's verbs scaffold and heal its framework-owned files on first run, so a fresh brand goes `npm install` → `npm start`.
+
+Run from a **target root** (`targets/<target>/`):
+
+```bash
+npx omega dev        # this target's dev server/build watch
+npx omega test       # the target's test suites
+npx omega deploy     # DELIBERATE publish for this target (commits never auto-deploy)
+npx omega i local    # link the local framework monorepo (ONE-TIME — the link is durable; rerun only to heal, never per change)
+npx omega i live     # restore published registry versions
+```
+
+`omega`, `omg`, and `mgr` are the same context-aware dispatcher — the nearest target names the framework that runs.
+
+Tests follow the layered doctrine in each framework's own `docs/test-framework.md` (unit for functions, integration for in-package systems, e2e only across framework boundaries; never mock what you can test real). Bare `npx omega test` runs are PROJECT-only — the framework corpus needs an explicit `framework:` or `full:` target.
+
+## One version for the whole family ([#794](https://github.com/Omega-JS-Stack/omega/issues/794))
+
+Every `@omega.js/*` package in this brand carries the SAME version number, and the
+manager writes each one as an exact pin — `"@omega.js/manager"` at the root,
+`"@omega.js/<framework>"` in each target. `npm run manage` and `npm start` both
+open by comparing what is actually INSTALLED (each target's framework and the
+`@omega.js/client` under it) against the manager's own version, and a brand that
+has drifted is refused before any service or dev leg runs:
+
+```
+the @omega.js family ships ONE version — this brand is mixed (#794):
+  backend: @omega.js/backend 0.4.0, @omega.js/client 0.4.0
+  this manager is 0.5.0
+  fix: run `omega update --apply` at the brand root — it moves every target together
+```
+
+**The fix is always `omega update --apply` at the brand root** — it fans out over
+every target AND the root's own `@omega.js/manager` pin, so the whole family
+lands on one number (a bare `omega update` only reports). Never bump a single
+target's version by hand: one target ahead means two copies of
+`@omega.js/client` in one brand and one omega.json5 validated by two validators,
+which nothing downstream can see. A target linked with a `file:` spec is exempt
+(the local era — its version is the monorepo's by construction), and a target
+with nothing installed yet is skipped with a line rather than failed:
+`npm install` is that fix. An installed `package.json` that cannot be parsed, or
+carries no version, is its own refusal naming the file — reinstall.
+
+## Logs — grep them, never restart
+
+Every verb tees its whole run to a file: truncated on each launch, ANSI-stripped, gitignored. Server state, build errors, test failures and emulator traffic are ALREADY on disk — read them instead of restarting a process or re-running a suite.
+
+| Where | Files |
+|---|---|
+| brand root | one file per verb — `logs/manage.log` (the manage cycle) · `logs/dev.log` (`npm start`'s dev fan-out across every leg; consecutive duplicate lines collapse to one `  (repeated N×)` note) · `logs/build.log` · `logs/clean.log` · `logs/deploy.log` · `logs/update.log` · `logs/test.log` · `logs/pipeline.log`. A fan-out log holds the walk's OWN verdict (header, skips, summary) — each target's output is in that target's own log |
+| any target | `targets/<target>/logs/dev.log`, `logs/build.log`, `logs/test.log` |
+| backend, extra | `targets/backend/dist/emulator.log` (the emulator's own traffic), `dist/dev.log`, `dist/test.log` — beside firebase-tools' `*-debug.log` |
+| desktop, extra | `targets/desktop/logs/runtime.log` — the running app itself (packaged builds: the OS log dir) |
+
+```bash
+tail -50 targets/website/logs/dev.log            # is the dev server up, what did it last build
+grep -i error targets/backend/dist/emulator.log  # what the emulator actually served
+```
+
+The mechanism, the retention rule, and the complete path table: [shared/logging.md](shared/logging.md).
+
+## Working locally against the framework (upstream-first)
+
+When this brand runs `omega i local` / `omega dev --local`, every `@omega.js/*` dep is linked LIVE from the local framework monorepo — a framework change reflects here instantly. That linkage exists for a reason: real applications expose framework holes. **When you hit a defect or gap that EVERY consumer would face — a broken core style, a missing option, a wrong default — it belongs in the FRAMEWORK (the linked monorepo), not in this brand.** The test: would the next consumer project need the same patch? Then it belongs upstream. **But ask first, always: SURFACE the proposed framework change (what is broken, what you would change, why every consumer needs it) and WAIT for Ian's go before editing the monorepo — or file it as an upstream issue.** Never edit the framework silently as a side effect of brand work. Within reason: brand-specific looks, content, and one-off behavior stay in the brand; framework edits follow the framework's own rules (its docs, its tests). When the link is NOT active (published versions installed), file the gap upstream instead of patching around it locally.
+
+**The guard hook enforces this half of the rule.** A `Write|Edit` to a framework-owned file in this brand is refused by `omega:guard` ([#452](https://github.com/Omega-JS-Stack/omega/issues/452)): generated and vendored files (`node_modules/`, any `dist/`, a generated header, the OMEGA-managed `database.rules.json`) are hard-refused and name the real source to edit, and a SHADOW COPY — a file whose path mirrors one the installed framework ships through its override layer — is refused with the upstream-first message. Two exits for the shadow case, both deliberate: file the framework issue, or declare the override with `omega:consumer-override: <reason>` in the file's first five lines (`OMEGA_CONSUMER_OVERRIDE=1` skips it for one session). `omega customize` already writes that marker into what it materializes, so the sanctioned copy needs nothing from you. Your pages under `src/pages/`, your `src/assets/css/main.scss` and `src/assets/js/main.js`, and your backend's `src/index.js` and `firestore.rules` are yours and are never guarded. The checklist line the hook cannot check for you: **a hand-written rule or template that fills a framework hole is a framework issue, not a brand patch.**
+
+## Hard rules
+
+- **Never edit generated output**: `dist/`, `packaged/`, anything gitignored. Edit `src/`, run the build.
+- **Never edit `node_modules/`** — framework bugs get fixed in the framework.
+- **Secrets never enter omega.json5** — `.env` / `.omega/secrets/` only.
+- **Deploys are deliberate**: only `omega deploy` publishes. Commits and pushes never auto-publish.
+- **Don't start long-running dev processes the user may already be running** (`npm run dev`, emulators) — assume theirs is up and GREP THE LOGS; every surface already wrote its output to disk.
+- **Framework-owned file sections** (marked `Default Values` / `OMEGA Rules` blocks) are rewritten by the target's own verbs when they scaffold — put customizations in the marked custom sections only. One exception, by design: a backend target's `firestore.rules` is YOURS end to end — it is compiled with the framework half into `dist/firestore.rules` (never edit that), and a match block you write whose path names a framework block's is MERGED into it (your condition ANDs onto the framework's, for every op you both name), which is how the brand tightens a framework rule. See [docs/backend/index.md](../backend/index.md) § Firestore rules.

package/docs/campaigns.md

@@ -0,0 +1,96 @@
+# The campaigns service — the brand's email marketing (SendGrid)
+
+The `campaigns` service reconciles the brand's email-marketing infrastructure on SendGrid:
+domain authentication, link branding, a verified sender for Single Sends, the brand's marketing
+list, the unsubscribe groups the backend sends through, `@omega.js/backend`'s custom fields and
+segments, and the account-global Event Webhook. It runs after `edge`, because the DKIM records
+are written into the Cloudflare zone.
+
+The whole service reconciles ONE SendGrid account per brand-or-company: the
+groups/fields/segments/webhook operations converge on the same result when sibling brands
+share the account.
+
+## What it reconciles
+
+| Operation | What it does |
+|---|---|
+| `domain-auth` | SendGrid domain authentication for `brand.url`'s domain. Missing → authenticate (`automatic_security` returns three CNAMEs under `emailauth.`), diff-sync those records into the Cloudflare apex zone, then validate — an interactive run polls until DNS propagates and SendGrid confirms. |
+| `link-branding` | SendGrid link branding for `brand.url`'s domain — the `emailurl.` host every transactional link is rewritten through. Missing → brand the links (`POST /v3/whitelabel/links` with subdomain `emailurl`), diff-sync both returned CNAMEs into the Cloudflare apex zone UNPROXIED, then validate — an interactive run polls until SendGrid confirms. On valid, the `emailurl` CNAME is PATCHed to proxied ([#693](https://github.com/Omega-JS-Stack/omega/issues/693)). Skipped on a subdomain project: the apex records belong to the parent brand's walk. |
+| `sender-identity` | The verified sender Single Sends require: `offers@{contact domain}` with the brand's name. It auto-verifies because `domain-auth` ran first. |
+| `list` | The brand's marketing list, resolved config id → exact-name lookup → create, with the id written back to `marketing.campaigns.providers.sendgrid.listId`. |
+| `unsubscribe-groups` | The account's ASM groups (below). |
+| `custom-fields` | `@omega.js/backend`'s custom fields, from its marketing SSOT, honoring each field's provider skip list (SendGrid has first/last name built in) — ONE derivation (`fieldsForProvider()`), the same one the backend's contact sync writes through, so a skipped field is neither provisioned here nor sent there ([#695](https://github.com/Omega-JS-Stack/omega/issues/695)). A type mismatch cannot be patched in SendGrid, so the field is deleted and recreated. |
+| `segments` | `@omega.js/backend`'s segments, each one's `query_dsl` rebuilt from its conditions and compared against the live segment; stale ones are PATCHed, falling back to delete + recreate. Orphaned `__temp_` segments (leaked by a brand-scoped campaign send that crashed) are swept. |
+| `event-webhook` | The account-global Event Webhook pointed at the PARENT backend's forwarder, with the consent toggles (`bounce`, `dropped`, `spam_report`, `unsubscribe`, `group_unsubscribe`) enabled and drift patched by minimum diff. |
+| `contact-person` | `brand.contact.person.name` exists — the human `@omega.js/backend`'s welcome, discount-nudge and checkup emails sign off as. Missing → the operation FAILS the walk naming the key ([#694](https://github.com/Omega-JS-Stack/omega/issues/694)). Last in the order: it gates the backend's sends, not anything provisioned here, so every SendGrid operation still converges first. |
+
+Fields and segments `@omega.js/backend` does not own are never touched.
+
+## Unsubscribe groups ([#649](https://github.com/Omega-JS-Stack/omega/issues/649))
+
+The `unsubscribe-groups` operation ensures the SendGrid ASM groups the backend's send path
+names actually exist, and lands their ids in config. The KEYS come from `@omega.js/backend`'s
+email SSOT (`GROUP_KEYS`); the recipient-facing NAME and description of each live here, on the
+provider side:
+
+| Key | Group name |
+|---|---|
+| `orders` | OMEGA - Order Updates |
+| `hello` | OMEGA - Onboarding |
+| `account` | OMEGA - Account |
+| `marketing` | OMEGA - Marketing & Promotions |
+| `security` | OMEGA - Security |
+| `newsletter` | OMEGA - Newsletter |
+| `internal` | OMEGA - Internal Alerts |
+
+Groups are matched by NAME, never by id: ASM ids are per SendGrid ACCOUNT, so sibling brands
+sharing one account converge on the same groups and land the same ids. Each resolved id is
+written to `marketing.campaigns.providers.sendgrid.groups.<key>` — its ONE authoritative home,
+through the comment-preserving editor, so a converged brand leaves omega.json5 byte-identical.
+`@omega.js/backend` reads the id there and fails loudly at send time when one is missing. A
+backend group key with no name+description row here throws at the top of the operation, not at
+send time. A dry run names the groups it would create and writes nothing.
+
+## Config
+
+- `marketing.campaigns.enabled: false` — skip.
+- `marketing.campaigns.providers.sendgrid` — the vendor is a KEY under `providers`
+  ([#425](https://github.com/Omega-JS-Stack/omega/issues/425)): no entry means none chosen.
+- `marketing.campaigns.providers.sendgrid.listId` — written back by `list`.
+- `marketing.campaigns.providers.sendgrid.groups.<key>` — written back by `unsubscribe-groups`.
+- `brand.address` — the physical mailing address CAN-SPAM requires on a sender. omega-manager
+  stamped the company's address on every brand; this ASKS for the brand's own
+  ([#635](https://github.com/Omega-JS-Stack/omega/issues/635)), five fields behind ONE gate,
+  and warns only when nobody can be asked.
+- `brand.contact.person.name` — the human the backend's personal sends sign off as. REQUIRED
+  here: without it the walk fails ([#694](https://github.com/Omega-JS-Stack/omega/issues/694)).
+- `parent` — whose backend the Event Webhook points at (`'self'` when this brand IS the
+  parent; `false` is a deliberate opt-out).
+
+**Credentials**: `SENDGRID_API_KEY` in the brand `.env`. `OMEGA_WEBHOOK_KEY` is OMEGA's own
+and is MINTED by the setup contract rather than asked for
+([#635](https://github.com/Omega-JS-Stack/omega/issues/635)), so the webhook operation can
+read it even when this service runs before the workspace one did.
+
+## Gotchas
+
+- **SendGrid supports ONE Event Webhook per account**, so it always targets the parent brand's
+  forwarder and the parent fans events out to each brand's own `/marketing/webhook` endpoint.
+  Only the consent toggles are managed — tracking toggles (open/click/delivered) are not ours
+  to touch.
+- **No Cloudflare token is survivable.** `domain-auth` prints the records to add by hand and
+  still attempts validation, so a manual fix converges on the next run; `link-branding` prints
+  the one-line manual flip (orange-cloud the `emailurl` CNAME) and warns.
+- **`link-branding` writes its own CNAMEs, because on run 1 nobody else has.** The `edge`
+  service builds the SendGrid record set from a LIVE domain-auth read, and a brand new brand has
+  no authenticated domain until `domain-auth` creates one minutes later in the same walk — so
+  edge wrote none of those records, and a branding with no CNAME behind it can never validate.
+  This operation diff-syncs both link CNAMEs itself (unproxied, the only state SendGrid can
+  validate) through the same writer `domain-auth` uses. Edge still stays the RECONCILER: its
+  next live read sees `valid: true` and desires the record proxied, so both services agree
+  ([#693](https://github.com/Omega-JS-Stack/omega/issues/693)).
+- **The sender's identity needs human input** where config has none: the address prompt is a
+  genuine ask, not a wait, so a headless run legitimately warns.
+- **Changing the query builder re-syncs every segment.** The generated SQL is compared against
+  the live segments for staleness, so any edit to the DSL translation is a fleet-wide re-sync
+  on the next run.

package/docs/captcha.md

@@ -0,0 +1,46 @@
+# The captcha service — the brand's own reCAPTCHA keys
+
+The `captcha` service proves the brand's OWN classic reCAPTCHA keys work. Every brand mints
+its own key in its own GCP project — never a company-shared key — and interactive runs ask
+for both halves through the shared setup contract, pointing at the GCP reCAPTCHA console.
+
+## What it reconciles
+
+One operation, `site-key`:
+
+- **The secret is PROVEN.** Classic reCAPTCHA has exactly one documented endpoint,
+  `siteverify`, and it doubles as a validity check: verifying a throwaway token answers
+  `invalid-input-response` for a good secret and `invalid-input-secret` for a bad one. The
+  probe is a pure read — no assessment is created — so a dry run behaves identically.
+- **The domain list cannot be reconciled.** Classic reCAPTCHA has no key-management API, so
+  the key's allowed-domain list is manual: an interactive run opens the console deep-link and
+  confirms once, stamping `captcha.providers.recaptcha.domainsConfirmed`
+  ([#434](https://github.com/Omega-JS-Stack/omega/issues/434) — a confirmation nothing can
+  re-check is the one kind of reconcile flag config keeps). Non-interactive runs keep the
+  printed guidance.
+
+## Config and credentials
+
+| Key | Meaning |
+|---|---|
+| `captcha.providers.recaptcha.enabled: false` | Skip the service. |
+| `captcha.providers.recaptcha.siteKey` | The public site key — the client mints tokens with it. |
+| `captcha.providers.recaptcha.project` | Only for a key minted OUTSIDE the brand's own GCP project; otherwise the deep-link resolves from `cloud.config.projectId`. |
+| `captcha.providers.recaptcha.domainsConfirmed` | The one-time domain-list confirmation. |
+
+`RECAPTCHA_SITE_KEY` + `RECAPTCHA_SECRET_KEY` in the brand `.env`. Missing keys → an
+interactive run asks; a non-interactive one skips with guidance.
+
+## Gotcha: the orphan secret
+
+`RECAPTCHA_SECRET_KEY` set with NO `captcha.providers.recaptcha.siteKey` in config is a silent
+403 on every protected POST ([#507](https://github.com/Omega-JS-Stack/omega/issues/507)): the
+backend enforces verification the moment the secret exists, and the client has no key to mint
+a token with. This service is the one place that sees both halves, so it says that direction
+out loud, with the console link to paste the site key from.
+
+The REVERSE direction — a site key requiring its secret — is the env schema's `requiredWhen`
+rule ([#626](https://github.com/Omega-JS-Stack/omega/issues/626)): warned brand-wide by the
+workspace `env-rules` op and refused by a production backend boot. NEITHER half is the
+sanctioned unkeyed brand ([#17](https://github.com/Omega-JS-Stack/omega/issues/17)) — green,
+and skipped.

package/docs/certificates.md

@@ -0,0 +1,68 @@
+# The certificates service — Apple signing material
+
+The `certificates` service reconciles Apple signing certificates, bundle IDs, and provisioning
+profiles for brands with a desktop or mobile target, via the App Store Connect API. It runs
+before `disperse`, which copies the artifacts into the targets.
+
+## The signing home
+
+ONE Apple account signs everything a company ships, so a company-managed brand (the
+`.omega/company.json` marker) shares the COMPANY workspace's signing tree; a standalone brand
+keeps it brand-local, and the material simply moves to the company root when one is born.
+Layout under the gitignored `{companyRoot||brandRoot}/.omega/certificates/apple/`:
+
+```
+AuthKey_*.p8                                            App Store Connect API key
+certificates/{TYPE}.cer + .p12                          downloaded or created, then exported
+csr/{TYPE}/{private.key,request.csr}                    PRESERVED — the issued cert pairs with this key
+profiles/{BRAND_ID}/{TYPE}/{PLATFORM}.mobileprovision   per-brand — a profile binds ONE bundle ID
+```
+
+## What it reconciles
+
+- **`api-key`** — the sanity checkpoint: which Apple account (issuer, team, key) the
+  downstream operations act on.
+- **`certificates`** — per cert type: a valid cert on the account is downloaded when the local
+  `.cer` is missing (delete it to force a re-download) and its `.p12` refreshed when stale; no
+  valid cert and automatable → created via a reused CSR, downloaded, exported; no valid cert
+  and manual (`DEVELOPER_ID_*`) → the local `.cer` is validated, and a missing or expired one
+  prints the portal URL and warns. Exported `.p12` files are then imported into the macOS
+  login keychain (best-effort, never in dry-run).
+- **`bundle-ids`** — the brand's bundle ID exists with the required capabilities. It is
+  `composeBundleId(certificates.providers.apple.bundleIdPrefix, brand.id)` — a reverse-DNS
+  prefix plus the brand id with hyphens as dots. Platforms derive from the enabled targets
+  (desktop → MACOS, mobile → IOS).
+- **`profiles`** — provisioning profiles for the brand's bundle ID × every applicable cert
+  type and platform, downloaded per brand. Device lists are fetched lazily, only when a
+  development profile actually needs creating.
+
+## Config and credentials
+
+| Key | Meaning |
+|---|---|
+| `certificates.enabled: false` | Skip. Also skipped with no desktop or mobile target. |
+| `certificates.providers.apple.bundleIdPrefix` | The reverse-DNS prefix. A brand without one is ASKED ([#635](https://github.com/Omega-JS-Stack/omega/issues/635)). |
+| `certificates.providers.apple.certificates` | Which cert types to reconcile. |
+
+`APPLE_API_ISSUER`, `APPLE_API_KEY_ID`, `APPLE_TEAM_ID` in the brand `.env` are required.
+`CSC_KEY_PASSWORD` is auto-generated on the first real run and persisted to the SIGNING ROOT's
+`.env` (the company workspace when company-managed — shared `.p12` files need the one shared
+password). `APPLE_KEYCHAIN_PASSWORD` is optional and suppresses macOS keychain prompts.
+
+## Gotchas
+
+- **Never rotate `CSC_KEY_PASSWORD`.** A `.p12` must carry a real password (modern macOS
+  rejects an empty one with "MAC verification failed"), and rotating orphans every existing
+  `.p12`.
+- **The `.p8` downloads ONCE** — Apple never re-serves it. An interactive run opens the keys
+  page Enter-gated and watches `~/Downloads` for a fresh `AuthKey_*.p8`, filing it into the
+  signing tree; the key is auto-detected by prefix, so no path config exists.
+- **`DEVELOPER_ID_*` certs have no API path.** Apple requires an Account Holder login to issue
+  them, so the interactive walkthrough stages the CSR itself, opens the portal create page, and
+  watches Downloads for the issued `.cer`; a headless run keeps printed guidance and converges
+  on rerun.
+- **The per-brand profile segment matters.** The signing tree is shared at the company root,
+  but a profile binds one bundle ID — without `profiles/{BRAND_ID}/`, sibling brands would
+  overwrite each other's profiles.
+- **`--force-recreate` was not ported.** Delete the local `.cer` to force a re-download;
+  expired certs recreate automatically.

package/docs/chat.md

@@ -0,0 +1,47 @@
+# The chat service — the brand's Chatsy agent
+
+The `chat` service keeps the brand's support chat agent on [Chatsy](https://chatsy.ai) in
+sync — settings plus knowledge — and sets the agent-owner account to the configured plan.
+Agents live in Chatsy's OWN Firestore, so this is an OPERATOR service: it needs a service
+account for Chatsy's Firebase project, and every other brand's clean skip is the sanctioned
+outcome (the credential never gates a run).
+
+## What it reconciles
+
+- **`chat`** — the agent's managed fields (name, website, image from `brand.images.brandmark`)
+  and its KNOWLEDGE: the packaged baseline with the brand's values filled in — `{website}`,
+  `{description}`, `{pricing}` generated from `payment.products`, `{sponsorshipsUrl}` — plus
+  the brand repo's `config/chatsy.md` appended when present. Diff-synced and patched with a
+  LEAF MASK, so Chatsy-owned fields (owner, id, metadata, other settings) survive.
+- **`user`** — the agent owner's subscription set to
+  `inbound.chat.providers.chatsy.plan` (Chatsy's Max top tier by default) through the shared
+  owner-plan reconciliation.
+
+## Config
+
+| Key | Meaning |
+|---|---|
+| `inbound.chat.providers.chatsy.enabled: false` (or `chatsy: false`) | Skip. |
+| `inbound.chat.providers.chatsy.agentId` | The agent. Missing → minted (below) or asked for. |
+| `inbound.chat.providers.chatsy.templateAgentId` | The shape donor for create-on-missing. |
+| `inbound.chat.providers.chatsy.plan` | The owner account's plan (`plan.id` required). |
+| `inbound.chat.providers.chatsy.sponsorshipsUrl` | The knowledge baseline's sponsorship link (default `{website}/contact`). |
+| `inbound.chat.providers.chatsy.updateAgentInfo: false` | A shared agent another brand manages — never rewritten from here. |
+
+A `web` target is required: the chat widget lives on the brand's website.
+
+## The three auth tiers (Ian 2026-07-13)
+
+1. **Operator SA** — `CHATSY_SERVICE_ACCOUNT` in the brand `.env`. Full create + manage: a
+   missing `agentId` with a `templateAgentId` MINTS the brand's own agent (product user + doc
+   templated from the donor), writes the id back, and converges name/knowledge/plan in the same
+   run.
+2. **User API key** — `CHATSY_API_KEY` is recognized; product-API management lands when those
+   routes are verified.
+3. **Dashboard** — an interactive run opens chatsy.ai and takes the pasted agent id, with a
+   Disable option. Non-interactive and dry runs skip cleanly.
+
+## Gotcha
+
+An `agentId` that points at no document is a visible ERROR. omega-manager silently created an
+orphan agent document instead; a wrong id should be fixed, not written around.

package/docs/cloud.md

@@ -0,0 +1,110 @@
+# The cloud service — the brand's Firebase/GCP project
+
+The `cloud` service (Firebase provider) reconciles the brand's cloud project to `cloud: {}` in
+`config/omega.json5`: billing, the required Google Cloud APIs, project identity, the OAuth
+consent screen, the Admin SDK service account and its key, the Hosting `api.{domain}` custom
+domains, Firestore, the Realtime Database, Authentication, Storage, Cloud Functions readiness,
+Cloud Messaging, and the web SDK config. It runs fifth — after the zone exists, before
+everything that depends on a backend.
+
+## What it reconciles
+
+| Operation | What it does |
+|---|---|
+| `billing` | The Blaze plan. `cloud.billingAccount` set → linked; `false` → the user chose Spark, silently; missing → an interactive run picks from the accounts the authed user can see (or creates one) and lands the answer in omega.json5. |
+| `services` | The required Google Cloud APIs (serviceusage first — the Firebase CLI's preflight needs it — then firebase, firestore, storage, hosting, database, identitytoolkit, cloudfunctions, cloudbuild, run, artifactregistry, iap, recaptchaenterprise, fcm) plus the compute service account's Cloud Functions deploy roles. Reads the enabled set first, so a converged project is a zero-mutation no-op. |
+| `project-settings` | The GCP display name matches `brand.name`, and a web app named "Web App" exists. Diffed before writing. |
+| `oauth-consent` | The OAuth consent screen (IAP brand): application title, support email, and the AUDIENCE (below). |
+| `service-account` | The Admin SDK service account with `firebase.admin`, `firebaseauth.admin`, `datastore.owner`, `serviceusage.serviceUsageConsumer`, and its key downloaded. The IAM grant diffs the policy first. |
+| `hosting` | The default hosting site gets `api.{domain}`: ONE api domain, shared by every web instance the brand runs ([#588](https://github.com/Omega-JS-Stack/omega/issues/588)); DNS is written through Cloudflare. The main domain is NOT added — the website hosts on GitHub Pages. |
+| `firestore` | The Firestore database (nam5 US multi-region) with Point-in-Time Recovery. |
+| `database` | The default Realtime Database instance (`{projectId}-default-rtdb`, us-central1). |
+| `authentication` | Identity Platform, email/password sign-in, email-enumeration privacy, anonymous auto-delete, the password policy, authorized domains — all diffed via Identity Toolkit — plus Google sign-in. |
+| `storage` | The default storage bucket, created and linked. |
+| `functions` | A read-only readiness check on cloudfunctions/cloudbuild/run. |
+| `cloud-messaging` | The FCM API plus a VAPID key pair — the PUBLIC half to `cloud.messaging.vapidKey`, the private half to `VAPID_PRIVATE_KEY` in the brand `.env`. |
+| `sdk-config` | The web SDK config fetched into state and diffed against `cloud.config` in omega.json5, written back key by key. |
+
+## Config
+
+- `cloud.enabled: false` — skip.
+- `cloud.config.projectId` — the ONE home of the project id
+  ([#23](https://github.com/Omega-JS-Stack/omega/issues/23)). Missing → an interactive run
+  offers the selection/creation flow and lands it in omega.json5; otherwise the service skips.
+- `cloud.config.*` — the SDK keys (`apiKey`, `authDomain`, `databaseURL`, `projectId`,
+  `storageBucket`, `messagingSenderId`, `appId`, `measurementId`), owned by `sdk-config`.
+- `cloud.billingAccount`, `cloud.organizationId` — both tri-state
+  ([#33](https://github.com/Omega-JS-Stack/omega/issues/33)): a value, `false` for a deliberate
+  opt-out, or missing to be asked once.
+- `cloud.supportEmail` — the consent screen's support address.
+- `cloud.oauthRedirectsConfigured` — the one-time confirm that the OAuth client's redirect
+  URIs are set (there is no API for them).
+- `cloud.consentAudience: false` — the tri-state opt-out
+  ([#33](https://github.com/Omega-JS-Stack/omega/issues/33)) for the audience stopper below: the brand
+  accepts an org-only sign-in, so only that step goes quiet — every other cloud operation still runs.
+- `cloud.messaging.vapidKey` — the public web-push key.
+- `cloud.shared: true` — the project is shared by several brands, so only the per-brand
+  operations run (`service-account`, `sdk-config`): one brand never rewrites a shared
+  project's settings.
+
+**Credentials**: `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` in the brand `.env` (OAuth2;
+tokens cache to `.omega/auth/google-tokens.json`, and the first run prints an auth URL).
+
+## The consent screen's audience — a manage-time STOPPER
+
+An Internal consent screen admits only the owning org's Workspace users — `Error 403: org_internal` for
+every Gmail account — and **Google gives no API write for the audience**
+([#667](https://github.com/Omega-JS-Stack/omega/issues/667), proven live): the PATCH is a 404 (the method
+does not exist), `orgInternalOnly` is output-only on create, an API-made brand is born Internal always, and
+brand creation itself is org-only. So `oauth-consent` READS the audience and stops on it instead of
+attempting a write that cannot exist:
+
+- **External** — a `✓` line, no prompt, no poll.
+- **Internal, interactive** — the uniform three-outcome gate: **Yes** opens
+  [the audience page](https://console.cloud.google.com/auth/audience) behind the ENTER gate and polls the
+  brand read until `orgInternalOnly` flips (the [#662](https://github.com/Omega-JS-Stack/omega/issues/662)
+  one-walk-finishes-the-job wait, so the flip lands in THIS run); **Skip for now** — and `s` at the poll —
+  warns with the console URL and asks again next run; **Disable** lands `cloud.consentAudience: false` and
+  nothing ever asks again (later runs print a dim `⊘` line).
+- **Internal, non-interactive** (CI, a piped `omega dev` boot) — the warn plus the console URL, `status:
+  warned`. A dry run plans the stopper and touches nothing.
+
+Creating the screen is org-only too: on a project that belongs to no organization the create answers
+400 "Project must belong to an organization", and the ensure names that cause with the console consent URL
+instead of the generic could-not-create line.
+
+## The branding page — a NAMED manual step
+
+The consent screen's **branding** extras (logo, home/privacy/terms links, authorized domains) have no API
+at all, so nothing here can reconcile them. Per the automation ruling
+([#693](https://github.com/Omega-JS-Stack/omega/issues/693)) what cannot be automated gets NAMED, so
+`oauth-consent` prints
+[the branding page](https://console.cloud.google.com/auth/branding) with its one-line checklist
+([#696](https://github.com/Omega-JS-Stack/omega/issues/696)): links and authorized domains are safe to
+change anytime, while uploading a LOGO starts Google's verification review for External apps. It is a
+named step, not a warning — the run's status never changes for it.
+
+## Gotchas
+
+- **A `demo-*` project is emulator-only** by Firebase's own convention, so there is no real
+  cloud to reconcile and the service skips. Found live: an offline brand's `demo-` id sent the
+  ensure at real Google APIs, 403'd, and killed the whole boot.
+- **The service-account key is shown ONCE.** Google never re-serves it, so its ONE home is the
+  brand's gitignored `.omega/secrets/service-account.json`; the backend's stage step carries it
+  into the staged `dist/` tree.
+- **Access self-heals before any operation runs.** A manage identity with no role on the
+  project gets granted one through a local `gcloud` account that can (owner first, then
+  editor + firebase.admin — projects outside an organization only accept new owners via a
+  console invitation), then the probe re-runs through a short IAM-propagation window.
+- **`supportEmail` must be an address the AUTHORIZING USER owns** (their own, or a Google Group
+  they manage) — anything else is "Request contains an invalid argument". The default is the
+  authenticated user's own email.
+- **Google sign-in's OAuth client cannot be created programmatically**, and its redirect URIs
+  have no API either: instructions plus an interactive confirm, stamped in config.
+- **`authDomain` is the BRAND host** (Ian's ruling 2026-07-23): a first-party authDomain keeps
+  `signInWithRedirect` working under storage partitioning, and the site self-hosts Firebase's
+  `/__/auth/*` helper files at build time.
+- **API enablement is eventually consistent.** The `functions` readiness check reads three APIs
+  once; a Service Usage lag can report a freshly enabled API as off, and the next run agrees.
+- **The API-domain TLS gate** — why a subdomain project's `api.` host stays DNS-only, and what
+  the paid Cloudflare add-on changes — is documented in [edge.md](edge.md).

package/docs/company.md

@@ -0,0 +1,64 @@
+# The company workspace
+
+> The COMPANY → BRAND rung: one workspace whose config, secrets, and signing material every brand it manages inherits. Two commands own it — `omega company init` makes the workspace, `omega company adopt` joins a brand to it. The runtime behavior (discovery, the per-brand fan-out, the child-process model) is in [packages/manager/README.md](../README.md) § Company mode.
+
+## What a company workspace IS
+
+A **repo, not a machine cache.** Machine-wide state stays in `~/.omega` (auth token caches, the per-machine deploy record); the company workspace is a directory you clone, commit, and share with the company's other machines. It owns exactly four things:
+
+| What | Where | Reaches a brand by |
+|---|---|---|
+| The config layer | `config/omega.json5` (the `brands` key is what MAKES it a company root) | the merge chain: manager DEFAULTS ← **company** ← brand ← `targets.<type>` ← local |
+| The shared secrets | `.env` | the env chain: shell env > brand `.env` > **company `.env`** |
+| The shared Apple signing tree | `.omega/certificates/apple/` | `signingRoot = companyRoot \|\| brandRoot` — the certificates + disperse services read the company's tree for every company-managed brand |
+| Where the brands are | `brands.roots` in that config (default `['./brands']`; `['..']` treats the workspace's siblings as brands) | company-wide runs (`omega manage` from the company root) |
+
+A brand behaves IDENTICALLY everywhere — standalone, nested under `brands/`, or a loose sibling. The company layer only changes what defaults it inherits.
+
+## The stamp is the whole link
+
+The reverse link needs no nesting and no registry: a brand carries `.omega/company.json` (`{ "root": "/abs/path/to/company" }`), and every brand-local run reads it, layers the company config (minus the `brands` key), loads the company `.env` under the brand's own, resolves the signing tree there, and prints a `Company:` line in its header. A marker pointing at something that is no longer a company root warns and the run continues standalone; no marker at all = standalone. That is the ONE mechanism — `omega company adopt` writes exactly this file, `omega onboard` writes it for brands it creates in a company, and a company-wide `omega manage` re-stamps every brand it discovers.
+
+## `omega company init [path]`
+
+Scaffolds the workspace in one command (default: the current directory). **Idempotent** — it fills gaps only and never overwrites a file that exists, so rerunning it after an edit is a byte-level no-op.
+
+```bash
+mkdir my-company && cd my-company
+npx omega company init          # or: npx omega company init ~/Developer/my-company
+```
+
+What it writes:
+
+| Path | What it is |
+|---|---|
+| `config/omega.json5` | The company layer: a real `brands: { roots: ['./brands'] }` plus commented, brand-agnostic placeholders for the sections a company usually owns (identity, `account.admins`, the GA account, the Sentry org, the Apple `bundleIdPrefix`) |
+| `.env` | The canonical group template with every key commented out — no values, no generated secrets (a brand's own `.env` always wins over this file) |
+| `.gitignore` | The tracking decisions below |
+| `README.md` | A short stub: what's here, and the verbs |
+| `.omega/certificates/apple/{certificates,csr,profiles}/` | The shared signing tree, created empty — the App Store Connect `AuthKey_*.p8` goes at its root. Carries its own self-protecting `.gitignore` (`*`) so signing material can never be committed even if the tree is copied elsewhere |
+| `brands/` | The default `brands.roots` entry, created empty |
+
+**Tracked vs ignored.** The repo tracks the config skeleton, the README, and the `.gitignore` — the shareable half. Ignored: `.env` (secrets), `.omega/` (the signing tree's `.p8`/`.p12`/CSR private keys, plus run output and caches), `logs/`, and `brands/` — each managed brand is its OWN git repo and must never be embedded in this one. Signing material moves between machines out of band, never through git; the certificates service re-downloads or recreates what it can, and preserves the CSR private key that pairs with each issued certificate.
+
+## `omega company adopt <brand-path>`
+
+Run from anywhere inside the company workspace. Adoption is the ONE step a brand needs:
+
+```bash
+npx omega company adopt brands/acme      # or any path: ../acme, /abs/path/to/acme
+```
+
+It writes the brand's `.omega/company.json` and nothing else. Idempotent: a marker already pointing here is left untouched. It refuses what would be wrong rather than guessing — a cwd that is not a company root, a path with no `config/omega.json5`, or a path that is itself a company workspace (the hierarchy is one rung: company → brands). A brand outside `brands.roots` is still stamped — its own runs inherit the company — but the command warns that company-wide runs won't include it until its parent dir joins `brands.roots`.
+
+New brands need no adopt step: `omega onboard` from a company root lands the brand under `brands.roots[0]` and stamps it in the same pass.
+
+## After adoption
+
+```bash
+npx omega manage                  # from the company root: the full walk, once per brand (child process each)
+npx omega manage --brand=acme     # one brand
+npx omega manage --parallel       # every brand concurrently
+```
+
+Brand-local runs need nothing new — `npm run manage` inside an adopted brand already layers the company. See [packages/manager/README.md](../README.md) § Company mode for the fan-out mechanics, the per-brand log tee, and why children are processes; [shared/config.md](shared/config.md) for the merge chain itself.