@omega.js/manager 0.1.0

package/docs/AGENTS.md

@@ -0,0 +1,200 @@
+# ========== Default Values ==========
+# OMEGA Desktop (@omega.js/desktop) consumer project
+
+<!-- MAINTAINERS (framework repo): this consumer template is MIRRORED across all OMEGA framework consumer templates (src/defaults/AGENTS.md ×N; web's lives at scaffold/AGENTS.md).
+  Same sections in the same order: framework-specific extras may be inserted; canonical sections are never reordered/renamed. Edit every framework consumer template together.
+  The mirroring rule lives in each framework guide's Doc-update parity section (docs/<framework>/index.md) -->
+
+## Framework
+
+This project consumes **OMEGA Desktop** (@omega.js/desktop), a comprehensive framework for building modern Electron desktop apps. @omega.js/desktop provides one-line-import bootstrap per Electron process, a modular feature library with file-based extensibility, a multi-platform build/release pipeline (DMG / NSIS / deb / AppImage), and a built-in four-layer test framework.
+
+## 🚨 READ THE FRAMEWORK DOCS FIRST
+
+**Before doing ANY work on this codebase, the agent MUST read the framework documentation: that is where the architecture, conventions, APIs, and gotchas live. Skipping these will result in solutions that conflict with framework patterns.**
+
+**Required reading:**
+- **`node_modules/@omega.js/AGENTS.md`**: the OMEGA map, the one agent entry into the framework docs; follow it to `docs/desktop/index.md` (the @omega.js/desktop guide: identity, architecture, conventions)
+- **`node_modules/@omega.js/desktop/docs/`**: subsystem deep references (read the relevant ones for the task at hand)
+
+## 🚨 READ @omega.js/client TOO
+
+**@omega.js/desktop ships `@omega.js/client` as a runtime singleton inside the renderer process.**
+- It powers auth, Firebase, reactive `data-omega-bind` directives, analytics, error tracking, and utilities (`escapeHTML`, etc.).
+- Any task that touches 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/desktop.
+
+**Required reading:**
+- **`node_modules/@omega.js/AGENTS.md`** → `docs/client/index.md`, the @omega.js/client guide: identity, module list, conventions
+- **`node_modules/@omega.js/client/docs/`**: module deep references (Auth, Bindings, Firestore, Notifications, etc.)
+
+## Quick start
+
+```bash
+npm start           # dev with auto-reload (gulp → esbuild → electron .)
+npm run build       # local production build (compiles bundles only, no installer)
+npm run package     # full local production package (DMG/zip/universal-mac, NSIS-win, deb+AppImage-linux)
+npm run package:quick   # fast packaged build for the host platform/arch only (~20-30s)
+npm run release     # signed + published release (requires certs)
+npx omega test        # run YOUR project's test suites (bare runs never include the framework corpus)
+npx omega test build/config         # run project tests by path (relative to test/; full:<path> for both sources)
+npx omega test project:             # run ONLY your project tests (all of them)
+npx omega test project:custom-test  # run only consumer project tests matching a path
+npx omega test mgr:                 # run ONLY framework tests (universal alias; desktop:/framework: are equivalent)
+npx omega test desktop:build/config      # run only framework tests matching a path
+npx omega test --extended           # also run tests that hit REAL external services (off by default; TEST_EXTENDED_MODE=true is the env equivalent, a shared name across @omega.js/backend, @omega.js/extension, UJM, and @omega.js/desktop)
+# (output is teed to logs/: dev.log on `npm start`, build.log on `npm run build`, test.log on `npx omega test`; cat instead of scrolling scrollback)
+npx omega install dev  # use LOCAL @omega.js/desktop source (to test framework edits)
+npx omega install live # restore the published @omega.js/desktop from npm
+```
+
+> Editing the @omega.js/desktop framework source while working here? Run `npx omega install dev` so this project picks up your uncommitted framework changes (it otherwise uses its installed `node_modules/@omega.js/desktop`). Run `npx omega install live` to switch back.
+
+## Where things live
+
+- `config/omega.json5`: the single OMEGA config (JSON5), with shared sections (brand, analytics, payment, cloud, monitoring, theme) at the top level; desktop settings (app, platforms, autoUpdate, startup, releases, remoteConfig, restartManager) under `targets.desktop`.
+- Packaging config: fully generated. @omega.js/desktop produces `dist/electron-builder.yml` from `config/omega.json5` (brand/app/signing) + @omega.js/desktop's opinionated defaults. Consumers never ship an `electron-builder.yml`. Override defaults via the `electronBuilder:` block in `omega.json5` if you genuinely need to.
+- `hooks/notarize/post.js`: optional post-notarize extension hook (@omega.js/desktop owns the actual `afterSign` notarize step).
+- `src/main.js`: main-process entry. One-line bootstrap of `@omega.js/desktop/main`.
+- `src/preload.js`: preload entry. Exposes `window.desktop` via contextBridge.
+- `src/integrations/tray/index.js`: tray definition. Edit this; it's yours.
+- `src/integrations/menu/index.js`: application menu definition.
+- `src/integrations/context-menu/index.js`: right-click menu definition (called per-event with `params`).
+- `src/views/<window>/index.html`: per-window HTML.
+- `src/assets/js/components/<window>/index.js`: renderer entry per window.
+- `src/assets/scss/main.scss`: shared SCSS.
+- `config/icons/<platform>/<slot>.png`: optional icon overrides (`macos/icon.png`, `macos/tray.png`, `macos/dmg.png`, `windows/icon.png`, etc.).
+  - Ship ONE file per slot at the native (retina) size; @omega.js/desktop auto-downscales @1x variants.
+  - macOS tray must be 32×32 (@omega.js/desktop renames to `trayTemplate.png` in dist for the OS dark-mode magic).
+  - Missing slots fall back to @omega.js/desktop bundled defaults; Linux falls back to Windows resolution.
+- `test/**/*.js`: your project test suites (framework auto-runs them alongside its own).
+
+## Per-context imports
+
+```js
+// src/main.js
+new (require('@omega.js/desktop/main'))().initialize();   // auto-loads JSON5 config
+
+// src/preload.js
+new (require('@omega.js/desktop/preload'))().initialize();
+
+// src/assets/js/components/main/index.js
+new (require('@omega.js/desktop/renderer'))().initialize();
+```
+
+## Available APIs at runtime
+
+In main: `manager.storage`, `manager.ipc`, `manager.windows`, `manager.tray`, `manager.menu`, `manager.contextMenu`, `manager.startup`, `manager.appState`, `manager.deepLink`, `manager.autoUpdater`, `manager.sentry`, `manager.omega`, `manager.context`, `manager.usage`, `manager.remoteConfig`, `manager.analytics`, `manager.restartManager`.
+
+In renderer: `window.desktop.storage`, `window.desktop.ipc`, `window.desktop.logger`, `OMEGA_BUILD_JSON.config`.
+
+## Dependency resolution
+
+- **Do NOT install framework dependencies directly** (`firebase`, `fs-jetpack`, `@omega.js/client`, etc.). @omega.js/desktop's bundler resolves them through the framework's own `node_modules/`. If something doesn't resolve, the issue is in @omega.js/desktop's bundle task, not your `package.json`.
+- **@omega.js/client owns Firebase.** Never `require('firebase')` or `import('firebase/app')`. Use `require('@omega.js/client')` → `omega.auth()`, `omega.firestore()` in renderers. In main process, use `manager.omega` (the @omega.js/desktop bridge).
+- **`Manager.require(name)`** resolves from @omega.js/desktop's module context at runtime for unbundled code (gulp tasks, test fixtures).
+
+## Testing
+
+Every feature ships with tests at every layer it has a surface in: **logic** (`test/build/`, `test/main/`), **UI** (`test/renderer/`: real events on the real DOM), and **end-to-end** (`test/boot/`).
+- Skip a layer only when the feature genuinely has no surface there; "the logic test covers it" does not excuse the UI test.
+- Test runs are invisible and never steal keyboard focus (@omega.js/desktop test stealth; set `OMEGA_TEST_SHOW=1` to watch a run live).
+- See `test/README.md` and `node_modules/@omega.js/desktop/docs/test-framework.md`.
+
+<!-- Everything above this marker is owned by the framework and rewritten by every omega verb. Add your project-specific notes below — they are preserved. -->
+
+# ========== Custom Values ==========
+> The entry point. Read this top to bottom (it is short), then follow the map. This file is a MAP, not a manual: the knowledge lives in `docs/` (segregated by framework), and the omega Claude plugin's hooks load it into a session deterministically, by where the work is happening. Keep this file under 250 lines.
+The `@omega.js` framework ecosystem in one repo: npm workspaces, changesets for independent versioning. Remote: [github.com/Omega-JS-Stack/omega](https://github.com/Omega-JS-Stack/omega) (npm org `omega.js`, GH org `Omega-JS-Stack` — both Ian's, names final).
+**Lineage** (the migration story, kept short): OMEGA consolidates the legacy manager ecosystem. The legacy repos keep serving production and are read-only reference (HARD RULE 1).
+- backend-manager (BEM) became `@omega.js/backend`; electron-manager (EM) became `@omega.js/desktop`; browser-extension-manager (BXM) became `@omega.js/extension`.
+- ultimate-jekyll-manager (UJM) was replaced by `@omega.js/web` (rebuilt on Eleventy 3, not ported); jekyll-uj-powertools became `@omega.js/template-kit`.
+- web-manager (WM) was absorbed into `@omega.js/client` — WM no longer exists as a concept; omega-manager's brains became `@omega.js/manager`.
+1. 🚫 **The legacy repos are READ-ONLY.** Never modify `omega-manager`, `backend-manager`, `ultimate-jekyll-manager`, `browser-extension-manager`, `electron-manager`, `mobile-app-manager`, `web-manager`, `jekyll-uj-powertools`, or any consumer brand repo. They are reference/history and keep serving production. All work happens HERE.
+2. **Every package here is `@omega.js/*`-named; zero npm publishes until Ian finalizes versions.** Old-name releases ship from the LEGACY repos; the monorepo's `pre-*-rename` tags are the backup lane.
+3. **Publish policy — internal by default**: private shared packages (`account`, `analytics`, `config`, `devkit`, `monitoring`, `template-kit`) are vendored into published frameworks at prepare time and never publish.
+   - Published = frameworks + `@omega.js/manager` + `@omega.js/client` (a real runtime dependency of backend/desktop/extension — never vendored) + `@omega.js/mcp-router` (a real runtime dependency of manager, so the vendored plugin's MCP declaration resolves inside the install — Ian 2026-07-30).
+   - All seven publishables carry a mechanical `private: true` latch until the proving checkpoint ([docs/shared/publishing.md](shared/publishing.md)) unlatches them.
+4. **MAM is parked.** No `packages/mobile`, no mobile work — slot reserved only.
+5. **Preserve semantics, replace plumbing.** Blueprints/default-pages, FILE_MAP scaffolding semantics, `mgr i local`, prepare-watch, the frontend↔backend contract, and the disperse model must keep working exactly as consumers expect.
+6. **Every extraction/normalization step is gated**: golden-master where applicable, package test suites, cross-stack e2e, canary consumer.
+- **`docs/` is the SSOT.** Cross-framework contracts live in `docs/shared/`; each framework's guide is `docs/<framework>/index.md` with its deep docs beside it. No line budget applies inside `docs/`.
+- **This file is the ONE agent entry — packages carry no agent docs.** Agents work at this level; the parent walk hands every session this map, and the map plus the plugin's hooks route to `docs/`. Knowledge lives in `docs/`, never in any AGENTS.md.
+  - No `packages/<pkg>/AGENTS.md` or `CLAUDE.md` exists, none — the one lookalike is `packages/manager/docs/AGENTS.md`, a gitignored GENERATED copy of this map the prepare lane vendors for published installs ([#144](https://github.com/Omega-JS-Stack/omega/issues/144)); never read or edit it here.
+- **Loading is deterministic, not preloaded.** The omega Claude plugin's hooks detect where the chat is working — a `packages/<framework>/` tree here, or a target's tree in a consumer repo — and inject the relevant docs then. Nobody reads guides "just in case".
+- **Consumer brands read THIS file.** A brand root's `AGENTS.md` line-1 import is `@node_modules/@omega.js/AGENTS.md` — a symlink the manager's workspace service maintains, pointing at this map.
+  - It resolves to the LIVE file in a locally linked brand, and to the copy prepare vendors into `@omega.js/manager/docs/AGENTS.md` (links retargeted) on a published install.
+  - Brand-root knowledge (the target table, the verbs, the brand hard rules, upstream-first) lives in [docs/manager/brand.md](brand.md). Contract: [docs/shared/agent-docs.md](shared/agent-docs.md).
+- **Consumers get version-matched knowledge.** In the local era, `node_modules/@omega.js/*` symlinks into this monorepo, so the pointers resolve as-is.
+  - Published packages carry their docs inside the package — prepare vendors each guide as `docs/index.md` plus `docs/shared/` ([docs/shared/agent-docs.md](shared/agent-docs.md)) — so the plugin reads knowledge that matches the installed version, never a global copy.
+The monorepo ships a Claude Code plugin (`agent-plugins/claude/`, listed by the repo-root marketplace manifest `.claude-plugin/marketplace.json`). It serves both audiences: developing this monorepo, and every consumer working on a brand built from these frameworks.
+- It is the ONLY home of the `omega:*` skills — folders and frontmatter names stay plain (`web`, `backend`, …); Claude Code namespaces them `omega:<skill>` automatically from the plugin manifest's `"name": "omega"`; the old global copies are deleted — plus the hooks that do the deterministic loading above.
+- Install is AUTOMATIC (Ian 2026-07-27): the repo's committed `.claude/settings.json` registers the marketplace and enables the plugin — Claude Code asks one trust question on first open, then it loads every session.
+- Consumer brands get the same deal: the plugin is vendored into `@omega.js/manager` at prepare time and the workspace service writes the brand's `.claude/settings.json` to enable it from `./node_modules/@omega.js/manager` ([docs/shared/agent-docs.md](shared/agent-docs.md)).
+- It declares exactly ONE MCP server, in `agent-plugins/claude/.mcp.json`: the `@omega.js/mcp-router` endpoint that lazily proxies the browser, electron, and extension upstreams ([docs/mcp-router/index.md](../../mcp-router/docs/index.md)) — no other native MCP declarations, anywhere.
+- A directory-source marketplace is read LIVE from its path, so an enabled plugin serves the CURRENT files — `/reload-plugins` picks up edits mid-session, and `claude --plugin-dir ./agent-plugins/claude` is only for same-session iteration and edge cases, not for freshness. The contract: [docs/shared/agent-docs.md](shared/agent-docs.md).
+| Package | What it is | The guide |
+|---|---|---|
+| `@omega.js/web` | Web framework (UJM successor): Eleventy 3 + LiquidJS, sections/themes, asset lanes, translation | [docs/web/index.md](../../web/docs/index.md) |
+| `@omega.js/backend` | Firebase Cloud Functions backend framework: build, test, deploy | [docs/backend/index.md](../../backend/docs/index.md) |
+| `@omega.js/desktop` | Electron desktop framework: build, test, package for macOS/Windows/Linux | [docs/desktop/index.md](../../desktop/docs/index.md) |
+| `@omega.js/extension` | Chrome/Firefox MV3 extension framework | [docs/extension/index.md](../../extension/docs/index.md) |
+| `@omega.js/client` | Shared frontend runtime singleton (Firebase auth, account, analytics, notifications, bindings) embedded by web/desktop/extension | [docs/client/index.md](../../client/docs/index.md) |
+| `@omega.js/manager` | Brand orchestration engine: walks every service in dependency order, reconciles a brand monorepo to its omega.json5 | [docs/manager/index.md](index.md) |
+| `@omega.js/mcp-router` | One lazy MCP endpoint per session: a stdio server proxying the browser/extension upstreams, tools cached and children spawned on demand | [docs/mcp-router/index.md](../../mcp-router/docs/index.md) |
+| `@omega.js/devkit` | Internal: shared build-time internals (logger, local linking, CLI router, prompts, deploy/update executors), vendored into every framework | [docs/devkit/index.md](../../devkit/docs/index.md) |
+| `@omega.js/config` | Internal: the omega.json5 loader, schema, merge, validator | [docs/shared/config.md](shared/config.md) |
+| `@omega.js/account` | Internal: user/account schema + subscription resolution, shared by backend and client | packages/account/src |
+| `@omega.js/analytics` | Internal: the ONE analytics contract — event catalog, per-provider adapters (GA4/Meta/TikTok), guarded browser transport, consent seam | [docs/shared/analytics.md](shared/analytics.md) |
+| `@omega.js/monitoring` | Internal: the ONE error-reporting contract — config resolution, release tags, PII scrub, the client-side @omega.js-bundle filter, per-platform SDK entries | [docs/shared/monitoring.md](shared/monitoring.md) |
+| `@omega.js/template-kit` | Internal: the `omega_*` template filters/tags as engine-neutral JS | [docs/web/template-kit.md](../../web/docs/template-kit.md) |
+| Brand | Who it is | Cloud |
+|---|---|---|
+| `brands/naked-brand` | "Naked Brand" — the bare fixture: the minimum a brand can declare, so a walkthrough sees every prompt fire from zero; a QA walk may reset it | Offline, `demo-*` only |
+| `brands/sandbox-brand` | Synthetic fixture for the automated corpus/e2e; test runs may mangle and reset it | Offline, `demo-*` only |
+| `brands/omega-playground` | "OMEGA Playground" — the standing LIVE test brand, classy theme | Real-but-throwaway project `omegajs-playground` |
+| `brands/newsflash-brand` | "The Daily Build" — the standing second-skin brand, newsflash theme | Offline, `demo-*` only |
+| `../omega-brand` (sibling repo) | The REAL brand: omegajs.dev, LIVE | Real project `omegajs` |
+The in-repo brands and the playground project are test-only forever; nothing in this monorepo is ever the production brand.
+- Full topology, history, the local-era `file:` dependency contract, and the remaining launch gates: [docs/shared/brands.md](shared/brands.md).
+- **Working inside a consumer brand right now?** Read [docs/manager/brand.md](brand.md) first — the brand-root anatomy, the verbs, and the brand hard rules.
+- **Migrating a legacy brand onto OMEGA?** The playbook is [docs/manager/migration.md](migration.md) — the six phases, their exit criteria, and the trap register.
+- Root `npm start` watches every dist-building package concurrently (single-instance lock).
+- Re-preparing EVERY package (pre-ship, or after touching a vendored internal like analytics) is ONE root command: `npm run prepare --workspaces --if-present`. Bare `npm run prepare` fails (no root script); never loop per-package.
+- In a brand's website target, `omega dev --local` links every `@omega.js/*` dep brand-wide from this monorepo and starts the watch; `omega i local` does the same per target.
+  - Linking is ONE-TIME and durable — never re-run per change; a linked brand just restarts `npm start`.
+  - A brand ROOT's `npm start` runs `omega dev`: the whole stack (website + backend) in ONE terminal — never boot the targets separately. Full contract: [docs/shared/local-dev.md](shared/local-dev.md).
+- **Upstream-first**: consumer work on a locally linked brand that reveals a framework-level hole fixes it HERE, in the framework — never as a consumer-side patch to repeat in the next project.
+  - A consumer session asks first: it surfaces the proposed framework change and waits for Ian's go (or files an issue), never editing the monorepo unprompted.
+  - The rule (and its "within reason" line) lives in [docs/shared/local-dev.md](shared/local-dev.md) and ships to brand sessions via the brand guide.
+- Tests run in lanes: `npm run test:packages` (unit), then corpus/e2e/verts/auth/journey — the full pipeline and when each lane gates is in [docs/shared/testing.md](shared/testing.md).
+Every framework AND `@omega.js/manager` ship `omega` + `omg` + `mgr` — all are the SAME context-aware dispatcher (`@omega.js/devkit/omega-bin`).
+- The nearest package.json walking up from cwd (including a backend's `functions/`) names the framework, and THAT framework's CLI runs via its `./cli` export — so npm's arbitrary hoist-winner in a brand monorepo is always correct.
+- An `@omega.js/*` package's OWN root dispatches to that package's own CLI, ahead of any framework it merely DEPENDS on — `npx omega test` in `packages/extension` runs the extension's self-test, and a package with no CLI is refused rather than scaffolded into ([#757](https://github.com/Omega-JS-Stack/omega/issues/757)).
+- No target context (fresh dir) → falls back to the HOST package's CLI with a stderr note, which keeps a verb run in a fresh directory on the host CLI — and with the manager as host, keeps `npx omega onboard` working in a fresh brand-template clone ([#276](https://github.com/Omega-JS-Stack/omega/issues/276)).
+- `omega-<framework>` bins run their own CLI directly, no dispatch. Docs say `npx omega`; `omg`/`mgr` are supported aliases.
+- Every framework-owned package.json script spells the verb BARE (`omega build`), on all four frameworks ([#748](https://github.com/Omega-JS-Stack/omega/issues/748)): npm already puts `node_modules/.bin` on the path inside a script. `npx omega` stays canonical for docs and the terminal.
+Single config format everywhere: shared sections (brand, cloud, analytics, payment, sentry, connections, theme) + a `targets` object (key presence = target enabled; any shared key inside a target entry overrides it). Owned by `@omega.js/config`.
+- Merge chain: `defaults ← company ← brand shared ← brand targets.<type> ← local shared ← local targets.<type>`.
+- Secrets stay in `.env` — the validator hard-fails secret-shaped keys in config.
+- **No dual-read (Ian's call, 2026-07-06)**: frameworks flip to omega.json5 outright; legacy brands convert once via the mapping tables. Full reference: [docs/shared/config.md](shared/config.md).
+`docs/shared/` — cross-framework contracts:
+- [config.md](shared/config.md) — the omega.json5 schema, merge chain, legacy mapping tables
+- [local-dev.md](shared/local-dev.md) — local linking + watch mechanics
+- [testing.md](shared/testing.md) — the tiered verification pipeline (unit → corpus → e2e → verts → journey)
+- [deploys.md](shared/deploys.md) — the deliberate `omega deploy` verb on every target (no push triggers, ever)
+- [updates.md](shared/updates.md) — the `omega update` dependency-update contract
+- [publishing.md](shared/publishing.md) — the publish proving-checkpoint runbook (gated, not yet run)
+- [icons.md](shared/icons.md) — the one Font Awesome mechanism on every surface
+- [logging.md](shared/logging.md) — the one log-tag contract (`[@omega.js/<package>:<module>]`) and its guard
+- [theming.md](shared/theming.md) — the `--omega-*` design-system contract, shell chrome, motion
+- [translation.md](shared/translation.md) — the AI translation engine + config-driven cache
+- [analytics.md](shared/analytics.md) — the event catalog, the placement rule, consent gating, attribution
+- [monitoring.md](shared/monitoring.md) — the error-reporting contract: the doctrine, the switches, the release tags, the capture seams
+- [agent-docs.md](shared/agent-docs.md) — the agent-docs chain: thin pointers here, the brand chain in consumers
+- [breaking-changes.md](shared/breaking-changes.md) — the legacy→OMEGA breaking-changes register: what changed shape, and the by-hand migration step for each
+- [brands.md](shared/brands.md) — brand topology, history, the local era
+- [rulings.md](shared/rulings.md) — standing rulings from the retired board era
+`docs/<framework>/` — each framework's guide (`index.md`) plus its deep docs. Web carries the extra set:
+- [sections.md](../../web/docs/sections.md) (the sections & components contract), [frontmatter.md](../../web/docs/frontmatter.md) (every page-frontmatter key, by family), [omega-sections-spec.md](../../web/docs/omega-sections-spec.md) (the ratified architecture spec), [template-kit.md](../../web/docs/template-kit.md)
+- [libs.md](../../web/docs/libs.md) (the `core/js/libs/` inventory and the `__main_assets__` import idiom), [classy-v2/DIRECTION.md](../../web/docs/classy-v2/DIRECTION.md) (the locked visual spec), [ads-system.md](../../web/docs/ads-system.md) (the ratified vert/ads architecture)
+Live work is GitHub issues (project-state spec v4): the queue is a query (`gh issue list`), status labels carry state, and a spec is the `## Spec` section of its issue — never a file. The retired board era's plan files are history in `_attic/plans/` (on disk, out of git); its durable rulings live in [docs/shared/rulings.md](shared/rulings.md).

package/docs/account.md

@@ -0,0 +1,45 @@
+# The account service — the brand's required accounts
+
+The `account` service makes sure the configured admin accounts exist in the brand's Firebase
+Auth with the resolved passwords, carry the admin role and the highest plan on their Firestore
+user doc — and that NO ONE ELSE holds the admin role. It runs AFTER the update/deploy pass,
+because the signup and marketing calls it makes hit the live brand backend.
+
+## What it reconciles
+
+One operation, `users`. Per configured entry:
+
+- `account: true` → create the auth user when missing (then `POST /user/signup` to complete
+  the flow), else converge the password; set `roles.admin` and the highest plan on the user
+  doc; sync to marketing when flagged.
+- `marketing: true` only → push the contact to the marketing providers when the auth user
+  exists, and skip quietly when it does not.
+
+Then the AUDIT: any other user holding `roles.admin` FAILS the service. An unauthorized admin
+is not a warning.
+
+## Config
+
+| Key | Meaning |
+|---|---|
+| `account.enabled: false` (or `account: false`) | Skip. |
+| `account.admins[]` | The required accounts — `{ email, account, marketing }`, with `{domain}` templated from `brand.url`. The manager default is `support@{domain}` ONLY; a company's own list lives in its company omega.json5 and replaces the default whole. |
+| `cloud.config.apiKey` | Read for password verification and backend calls (the cloud service lands it). |
+| `cloud.shared: true` | Skip — the owning brand manages accounts. |
+
+The service also skips with no `backend` target, and when
+`.omega/secrets/service-account.json` is missing (run the cloud service first).
+
+**Passwords** resolve per account through the owner channels, lazily — nothing happens until
+an account actually needs one: `OMEGA_ACCOUNT_PASSWORD__*` env var →
+`config/hooks/account/password.js` → a lazy `ACCOUNT_PASSWORD_SEED` derivation. A brand fully
+covered by env vars or hooks never grows a seed in its `.env`.
+
+## Gotchas
+
+- **De-ITW'd from omega-manager.** The account list used to be hardcoded company Gmail
+  addresses and the password a company-specific formula in code; both are config and owner
+  channels now.
+- **`firebase-admin` is not used.** The service talks to the Identity Toolkit REST API and
+  `FirestoreREST` over the brand's own service account, which is what keeps it runnable from
+  the manager without the admin SDK's ambient credentials.

package/docs/advertising.md

@@ -0,0 +1,46 @@
+# The advertising service — the domain in AdSense
+
+The `advertising` service verifies the brand's domain is present in the configured AdSense
+account and reports its approval state. The AdSense Management API v2 is READ-ONLY — sites
+cannot be added or configured programmatically — so the service proves presence and state and
+deep-links the console for the manual half. It never mutates AdSense, which makes a dry run
+identical to a normal run.
+
+## What it reconciles
+
+One operation, `sites`: presence with a `READY` state is the converged proof. Missing → an
+interactive run opens the add-site console page and polls until the site appears;
+non-interactive and dry runs warn with the deep-link. A non-READY state is warned with what
+Google is waiting on:
+
+| State | Meaning |
+|---|---|
+| `READY` | Serving ads. |
+| `GETTING_READY` | Google is reviewing the site — a multi-day human review, so this one legitimately stays a rerun. |
+| `REQUIRES_REVIEW` | Request one in the console. |
+| `NEEDS_ATTENTION` | Resolve the issues in the console. |
+
+## Config
+
+`advertising.providers.adsense` is the home — the provider-neutral section, never a
+brand-named top-level key. **A missing provider entry is a deliberate absence**: authoring
+`advertising: { providers: { adsense: {} } }`, even empty, is how a brand opts in.
+
+- `advertising.providers.adsense.client` — the `ca-pub-…` id, and the ONE AdSense switch
+  ([#527](https://github.com/Omega-JS-Stack/omega/issues/527)): there is no second `enabled`
+  key. The API's account id is the same value without the `ca-` prefix. Missing, with
+  credentials in hand, an interactive run offers the account selection flow (create-new opens
+  the AdSense signup) and lands it in omega.json5.
+
+Because `client` is schema-typed as a string, "Disable permanently" opts the PROVIDER out
+(`advertising.providers.adsense: false`) rather than landing `client: false`, which would fail
+validation forever.
+
+**Credentials**: `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` with the `adsense.readonly`
+scope.
+
+## Gotcha
+
+AdSense lists sites at the APEX only, so an apex entry covers every subdomain of it
+([#631](https://github.com/Omega-JS-Stack/omega/issues/631)) — a subdomain project matches its
+parent's entry rather than needing one of its own.

package/docs/ai.md

@@ -0,0 +1,34 @@
+# The ai service — one key per AI provider
+
+The `ai` service ([#639](https://github.com/Omega-JS-Stack/omega/issues/639)) provisions
+NOTHING: there is no AI platform API to reconcile a brand against, only two credentials the
+backend needs before it can call OpenAI or Anthropic (contact inference, content and
+newsletter generation). The whole service is the shared setup contract's gate plus a line in
+the run record naming which providers the brand has credentials for.
+
+It runs before the delivery lane, because the keys must be in the brand `.env` before a
+target's runtime env composes from it.
+
+## What it reconciles
+
+One operation, `keys`: by the time it runs the setup gate has already acquired what was
+missing (or skipped the service), so the environment IS the answer. It prints which of the
+declared keys are present — NAMES only; a value never reaches the log — and returns them as
+the operation's output.
+
+## Config and credentials
+
+- `ai.enabled: false` — the tri-state opt-out. A brand that does not want AI answers "Disable
+  permanently" once and is never asked again.
+
+`OPENAI_API_KEY` and `ANTHROPIC_API_KEY` in the brand `.env`. Both are OPTIONAL
+(`gates: false`): preflight never gates a run on them, and the service asks in place. The
+legacy split — a company-wide `OMEGA_*` key beside the brand's bare one — is GONE: the bare
+name is the only name, and a company-wide value is simply the COMPANY layer of the `.env`
+cascade under that same name.
+
+## Gotcha
+
+`ANTHROPIC_API_KEY` is a workspace API key. A Claude Code subscription login is a separate
+thing and needs no key — the two are often confused when a brand's translation lane works
+locally but not in CI.

package/docs/analytics.md

@@ -0,0 +1,69 @@
+# The analytics service — GA4 streams and the ad pixels
+
+The `analytics` service reconciles the brand's analytics providers to `analytics: {}` in
+`config/omega.json5`: one GA4 web data stream per enabled target, the GA property ↔ Firebase
+project link, and the Meta and TikTok pixels. It runs after the cloud service (the Firebase
+project must exist to link) and before search (which associates the GA property).
+
+The cross-framework event contract — the catalog, the placement rule, consent gating — is
+[analytics.md](shared/analytics.md); this file is only what the manage walk provisions.
+
+## What it reconciles
+
+| Operation | What it does |
+|---|---|
+| `google-streams` | One GA4 web stream per enabled target, found BY URI (each target gets its own subdomain of the brand domain, virtual for app targets): created when missing, renamed on displayName drift, enhanced measurement diffed before patching, plus a clean Measurement Protocol secret per stream. |
+| `google-firebase-link` | The GA property ↔ Firebase project link. A property holds at most one FirebaseLink and a project links to at most one property, so a project linked to the WRONG property is unlinked there and linked here — config is the source of truth. It also normalizes the stream Firebase auto-creates on linking ("Web App", often with no URI). |
+| `meta-pixel` | The Meta Pixel exists on the ad account and a Conversions API token is in hand. |
+| `tiktok-pixel` | The same shape for TikTok. |
+
+## Config
+
+- `analytics.enabled: false` — skip.
+- `analytics.providers.google.propertyId` / `.accountId` — the GA4 property. Missing, with
+  credentials available, an interactive run offers the account + property selection/creation
+  flow and lands both ids; without a propertyId the two google operations are filtered out.
+- `targets.<type>.analytics.providers.google.id` — where each stream's measurement ID lands
+  ([#417](https://github.com/Omega-JS-Stack/omega/issues/417)): the per-surface override every
+  framework reads through the merge chain, the same shape monitoring uses for DSNs.
+- `analytics.providers.meta.{id,accountId}` and `analytics.providers.tiktok.{id,accountId}` —
+  the pixel and the ad account / advertiser it lives on. Public ids, so they live in config
+  beside the Google ones, never in `.env`. `analytics.providers.<provider>: false` disables
+  that provider outright.
+
+**Credentials**: `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` (the `analytics.edit` scope;
+tokens cache to `.omega/auth/google-analytics-tokens.json`), plus `META_ACCESS_TOKEN` and
+`TIKTOK_ACCESS_TOKEN` — the names `@omega.js/backend` reads. Both pixel tokens are OPTIONAL
+(`gates: false`): a pixel-only brand is never asked for a Google credential, and a Google-only
+brand is never gated on a pixel token. Each stream's Measurement Protocol secret goes to the
+brand `.env` as `GOOGLE_ANALYTICS_SECRET_{TARGET}`
+([#434](https://github.com/Omega-JS-Stack/omega/issues/434)); the delivery step composes it
+into each target's runtime env as `GOOGLE_ANALYTICS_SECRET`, so the pair travels together.
+
+## Near-zero input
+
+A missing pixel reconciles in ONE interactive pass (Ian 2026-08-21, the GA4 standard): acquire
+the access token (an Enter-gated open of the mint page, then a paste-in), discover the ad
+account the token can see — auto-selected when there is exactly one, landed in config —
+create the pixel by name, land its id in omega.json5 and in the in-memory config, so the token
+check in the same pass reports the pixel it just made. No token means no provisioning this
+pass: warned with where-to-get guidance, never a failure.
+
+## TikTok: the one credential OMEGA MINTS rather than asks for
+
+TikTok is the instance where the credential is MINTED rather than pasted ([#448](https://github.com/Omega-JS-Stack/omega/issues/448)): the setup asks for the developer app's secret ONCE (masked, never persisted anywhere), opens the app's page in the developer portal (`analytics.providers.tiktok.appId`), takes the app's own "Advertiser authorization URL" pasted from there (never built, never stored: the redirect URI is the app's setting), opens it, takes the pasted redirect URL and reads its `auth_code`, exchanges it inline, and saves ONLY the long-lived `TIKTOK_ACCESS_TOKEN` — the name `@omega.js/backend` reads. A re-authorization asks for the secret again; a company-level home for it is [#446](https://github.com/Omega-JS-Stack/omega/issues/446). Nothing here can fail a walk: a headless run, a declined gate, an empty paste, or a rejected exchange all keep the warned where-to-get guidance.
+
+## Gotchas
+
+- **GA's "User Data Collection Acknowledgement" gates secret creation** and has no API. An
+  interactive run opens the settings page and retry-polls until the acknowledgement lands, so
+  ONE run finishes the job. It is per-property, so the first stream's prompt clears the gate for
+  every stream after it.
+- **GA holds a just-deleted link for a moment.** When the service unlinks a wrong property and
+  immediately creates the right link, the create can fail as "still propagating"; since
+  [#662](https://github.com/Omega-JS-Stack/omega/issues/662) an interactive run polls the create
+  until GA releases it, and only a skipped or headless run reports warned.
+- **A shared cloud project skips the link** — the owning brand manages it.
+- **The TikTok pixel path is a scaffold.** The wiring is complete and the token is the gate, but
+  no brand carries the key yet, so the create path has never run against the live API and the
+  pass ends at the warned guidance.

package/docs/assets.md

@@ -0,0 +1,57 @@
+# The assets service — the brand's derived visual collateral
+
+The `assets` service generates everything derived from the brand's logo sources: the wordmark
+and combomark, colour and black SVG variants with PNG size ladders, the PSD templates and
+their exports, the macOS/Windows app icons, the social profile icons, and the web favicon set.
+It runs on the BOOT lane too — `omega dev` and a brand-root `omega deploy` both redistribute
+it — because it is local file work the target legs consume.
+
+**Sources** are committed brand collateral in the brand repo: `assets/logo/*.svg` and
+`assets/templates/*.psd`. **Derived files** land in the gitignored `.omega/assets/`.
+
+## What it reconciles
+
+| Operation | What it does |
+|---|---|
+| `logo-gen` | Wordmark + combomark SVGs from the brandmark and `brand.font`, text rendered as PATH OUTLINES so the SVGs are self-contained. Missing-only: an existing (possibly hand-tuned) file is never overwritten. |
+| `process` | Per logo source: the colour SVG as-is plus an all-black conversion, exported as SVG + PNGs at every ladder size. |
+| `templates` | Seeds the brand's PSDs from the company root when missing (company-managed brands), replaces the logo and text layers, writes the PSD back, composites and exports the PNGs. |
+| `icons` | macOS `.icns` and Windows `.ico`, from the composited `icon.png` the templates op produced when there is one, else the brandmark. |
+| `social-icons` | The square brandmark centred on white with padding, for profile pictures. |
+| `favicons` | The favicon PNG ladder, a multi-size `favicon.ico`, and `site.webmanifest` (content-diffed, since it derives from config rather than an image). |
+| `reconcile` | Deletes the files inside the operations' own output dirs that the brand's current sources no longer derive ([#636](https://github.com/Omega-JS-Stack/omega/issues/636)) — dropping `assets/logo/wordmark.svg` takes its variants and ladders with it. Runs last, so everything this walk generated is already derived; the derived NAMES come from the same lib the writers generate from (`lib/derived.js`). The brand's committed sources are never touched. |
+
+## Config
+
+- `assets.enabled: false` — skip.
+- `brand.font` — a font FILE NAME without extension, resolved from the brand repo's
+  `assets/fonts/` first, then the system font dirs. No font configured means nothing to
+  generate a wordmark with (noted and passed); configured but not found is an ERROR — the
+  config intent failed. There is no default: omega-manager packaged the company's licensed
+  fonts, this port ships none.
+- `brand.name`, `brand.images.brandmark` and the other brand values the templates and
+  webmanifest read.
+
+**Credentials** (optional): `MRLOGO_SERVICE_ACCOUNT` / `MRLOGO_API_KEY` / `LOGO_API_ID_TOKEN`
+— the product-service ladder for AI brandmark generation via MrLogo when the brand has no
+`assets/logo/brandmark.svg` yet. Zero config options by design: setting a credential IS the
+consent to spend the call. Interactive runs ask for optional art direction; dry runs never
+mint. With no credentials the service skips with guidance.
+
+## The force refresh
+
+The `assets` service is mtime-diffed, so a converged brand rebuilds nothing; `omega manage --reset-assets` ([#214](https://github.com/Omega-JS-Stack/omega/issues/214)) is the force refresh for the cases no timestamp records. It clears the derived cache under `.omega/assets/` before the walk, then the same operations regenerate it and the run names what was cleared. Bare resets both kinds; `--reset-assets=logos` takes the logo variants, app icons, social icons and favicons, `--reset-assets=templates` the PSD exports. The brand's committed `assets/logo/*.svg` and `assets/templates/*.psd` are sources, never cache, so they are never touched (the port of omega-manager's `--reset-logos` / `--reset-templates`).
+
+Invalidation IS deletion: `isStale()` calls a missing derived file stale, so removing a kind's
+outputs is precisely what makes the same walk regenerate them — no second freshness mechanism
+to keep in sync.
+
+## Gotchas
+
+- **The brandmark is the root of every derived asset.** No `assets/logo/brandmark.svg` and no
+  MrLogo credential means the whole service skips.
+- **A PSD stores each layer's raster.** Replaced TEXT content lands in the layer metadata and
+  Photoshop re-renders it on open, so a text change appears in the exports only after the PSD
+  is opened and saved once. The LOGO layers are re-rastered here, so they are always current.
+- **Manual Photoshop edits persist and re-trigger the pass**: editing a PSD bumps its mtime, so
+  the next run re-replaces the logo/text layers and re-exports.

package/docs/bookmark.md

@@ -0,0 +1,26 @@
+# The bookmark service — brand links into Chrome
+
+The `bookmark` service pushes the brand's console and dashboard links to the companion Chrome
+extension over the WebSocket protocol; the extension files them under `Ω / {Brand} /
+{Category}`. It runs at the very end of the walk and is interactive-only.
+
+## What it reconciles
+
+One operation, `sync`: start the WebSocket server the extension auto-connects to (it retries
+every 5s), send one `OMEGA_BOOKMARK_SYNC` message, and wait for the extension's ack.
+
+Link sources are the brand's own config and state, so groups with unmet inputs are simply
+absent — a brand with no analytics ids gets no Analytics folder. Deployed Cloud Function names
+(for per-function log links) come from a `gcloud` shell-out whose every failure — no gcloud, no
+auth, no project — just means "no function links".
+
+## Config and credentials
+
+None of its own: everything is derived from the brand's existing config and state.
+
+## Gotchas
+
+- **A headless run skips cleanly** rather than burning the ten-second connect wait: there is no
+  Chrome to talk to.
+- **A dry run prints the link groups** it would sync without opening the server and without the
+  gcloud lookup — no live reads.