@omega.js/manager 0.1.0

package/claude-plugin/skills/accessibility/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: accessibility
+description: Use before finishing any markup, theme, section, or stylesheet change in a website app, packages/web, or a desktop/extension UI surface — or when the ask names accessibility, a11y, aria, alt text, keyboard navigation, focus, contrast, reduced motion, or WCAG.
+user-invocable: true
+---
+
+# Accessibility (OMEGA front-end surfaces)
+
+Most of this is already built into the layers — tokens carry contrast, the motion library carries the reduced-motion branch, the theme partials carry the alt attributes. New markup breaks it by hand-rolling around them, so the review is mostly checking that the mechanism was used.
+
+## Where the mechanism lives
+
+- `docs/shared/theming.md` — the `--omega-*` token contract (light + dark values ship together), the one-status-hue rule, the motion library and its resilience rules.
+- `docs/web/sections.md` — the section/component contract: what a section owns and how its markup composes.
+- `docs/shared/icons.md` — the one icon mechanism (`fa-*` markup, inlined at build, upgraded at runtime).
+- `packages/web/core/css/motion/_index.scss` and `packages/web/core/css/tokens/_index.scss` — the two sheets the checks below refer to.
+
+## The checklist
+
+1. **Landmarks and heading order.** The document shell and blueprint layouts own `header`/`nav`/`main`/`footer` — a section never opens a second `main`. Sections start at h2 beneath the page's single h1, and levels do not skip.
+2. **Every image has an `alt`.** Content images describe; decorative ones take `alt=""`. Lazy images keep it too — the theme idiom is `src="{{ site.omega.placeholder.src }}" data-lazy="@src …" alt="…"`, and the `alt` is not optional in the copy.
+3. **Every control has a name.** Inputs get a real `<label>` (or `aria-label` where the design has no visible label); an icon-only button gets an `aria-label`, because an `fa-*` glyph contributes no text. Links say where they go — no bare "here".
+4. **Color comes from tokens, never raw hex.** `var(--omega-*)` in markup and scss. Status meaning uses only `--omega-ok` / `--omega-warn` / `--omega-danger` (with their `-rgb` twins when a translucency utility needs them). A raw hex is both a theming break and an untested contrast.
+5. **Contrast holds in BOTH modes.** Token values ship as light/dark pairs and `data-bs-theme` flips them, so a pairing checked in one mode is half-checked. Ink-on-surface and accent-on-surface are the two that bite.
+6. **Focus stays visible.** Keyboard focus shows a ring — `.omega-interactive` (and `--lift`) already gives hover, `:focus-visible`, and press states. Never remove an outline without shipping a replacement, and never make a `div` the click target without a `button`/`a` or explicit role plus key handling.
+7. **`prefers-reduced-motion` renders final states.** Reveals resolve instantly, count-ups show their target, rotators hold the first word, marquees park. A new animated section adds its reduced-motion branch in the same commit. The no-JS twin: reveal styles hide content only under the `html[data-omega-motion]` stamp, so a page without JS is fully visible.
+8. **Copied idioms carry their accessibility.** The marquee's cloned set is `aria-hidden` with focusables detabbed (`tabindex="-1"`); a duplicated pattern that drops those halves ships duplicate content to a screen reader.
+
+## Verifying
+
+Check the rendered page, not the template — the `omega:browser` skill drives the running dev server: tab through the surface, read the accessibility tree, and screenshot both `data-bs-theme` values. For a whole-page pass, the same upstream runs Lighthouse.

package/claude-plugin/skills/analytics/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: analytics
+description: Use before finishing any flow, checkout, auth, or backend payment/webhook work — or when the ask names analytics, tracking, an event, a conversion, a pixel, gtag/fbq/ttq, GA4, Meta, TikTok, consent gating, or attribution.
+user-invocable: true
+---
+
+# Analytics (OMEGA event tracking)
+
+Tracking is MECHANISM, not call sites: one catalog declares every event, one call fires it, and the adapters translate it into each provider's dialect. So the review is checking that a flow fires the events it owns, through the catalog, in the right tier — never that someone wrote a good pixel call.
+
+## Where the mechanism lives
+
+- `docs/shared/analytics.md` — the contract: the catalog entry shape, the three mapping kinds, the placement rule, consent, attribution, the dev fire-log. Read it before changing anything below.
+- `packages/analytics/src/catalog.js` — the SSOT: one entry per canonical event, with every provider mapping. The code is the answer to "does this event exist?".
+- `packages/analytics/src/index.js` — the facade (`analytics.event()`, `configure()`) and the consent → adapter → transport walk.
+- `packages/analytics/src/adapters/` and `transports/browser.js` — one file per provider; the guarded transport a blocked global cannot break.
+- `packages/web/core/js/libs/tracking-consent.js` — the web consent record the gate reads.
+
+## The checklist
+
+1. **Every user-facing flow fires its catalog events through `analytics.event()`.** A raw `gtag(...)`, `fbq(...)` or `ttq.track(...)` at a call site is the finding — even a guarded one, since the guard is now the transport's job. A flow that ships with no event at all is the same finding in the other direction: name what the surface should count.
+2. **A new event exists in the catalog FIRST.** One entry — canonical name, the `params` contract, the `placement`, and a per-provider mapping with an HONEST `kind` (`standard` only where the platform actually defines that event; anything else is `custom`) — plus its resolve case in `packages/analytics/test/catalog.test.js`. Never pass a name the catalog does not carry: it throws in development on purpose.
+3. **Placement follows the rule.** Money and account truth fires server-side (purchase, refund, trial, the subscription transitions, deletion); UI actions fire client-side; `sign_up` fires BOTH halves, carrying the same event id so the platforms deduplicate. A revenue event fired from a browser, or a click event fired from a Cloud Function, is misplaced.
+4. **No hand-rolled attribution or consent reads.** Attribution rides the facade's `context` slot and each adapter attaches it its own way; consent is the gate the facade asks per provider, per fire. A call site that reads storage for utm values, or checks a consent flag before firing, is duplicating a mechanism that already ran.
+5. **Unmapped providers stay unmapped.** A provider absent from an entry's `providers` is a decision — the adapter skips and the dev log says so. Never invent a junk custom event so a platform "has coverage".
+6. **Verify by the fire-log, not the template.** Drive the flow and read the one dev line per event (`[@omega.js/analytics:events] <event> → ga4 sent, meta …`); for a live drive, the platform debuggers. Reading the code you just wrote proves nothing about what fired.
+
+## Verifying
+
+Run the package suite for catalog and adapter changes (`npm test` in `packages/analytics`), then drive the actual flow with a dev server running and read the fire-log line — the `omega:browser` skill drives the running server rather than restarting anything. The full verification ladder, including the platform debuggers and the two consent regions, is in `docs/shared/analytics.md`.

package/claude-plugin/skills/backend/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: backend
+description: Use when working on a brand's backend app or on @omega.js/backend itself — Cloud Functions routes, schemas, auth hooks, the emulator harness, usage, payments, email, or anything under targets/backend, functions/, or packages/backend/.
+user-invocable: true
+---
+
+# OMEGA Backend (@omega.js/backend)
+
+`@omega.js/backend` builds Firebase Cloud Functions backends: one `Manager.init(exports, {...})` bootstrap wires the built-in functions (`omega_api`, auth events, cron jobs), the helper classes (RouteContext, User, Analytics, Usage, Middleware, Settings, Utilities), the payment providers, Firestore-trigger pipelines, marketing campaigns, an MCP server, and the CLI for emulator, deploy, logs, auth, and Firestore work. Consumer apps are src-first: `src/index.js` plus optional `src/routes/`, `src/schemas/`, `src/hooks/`, staged into `dist/` by `omega build`.
+
+## Where the knowledge lives
+
+This skill routes; the docs are the source of truth. Read the guide BEFORE touching files.
+
+- **Working in this monorepo** — `docs/backend/index.md` is the guide (identity, architecture, the CLI table, file conventions). The per-subsystem meat lives in `packages/backend/docs/*.md`: routes, schemas, firestore, test-framework, common-mistakes, environment-detection, logging, payment-system, email-system, usage-rate-limiting, auth-hooks, mcp, verts. Cross-framework contracts live in `docs/shared/`.
+- **Working in a consumer project** — read `docs/backend/index.md` in the framework monorepo (the local era links `node_modules/@omega.js/backend` straight into it; published installs will carry the docs inside the package ([#64](https://github.com/Omega-JS-Stack/omega/issues/64)).
+
+## Non-negotiables
+
+- **Read the guide before editing.** The route/schema contract, the usage helper, and the Firestore conventions each have footguns documented and nowhere else.
+- **🚫 Never start the user's long-running processes** (`omega emulator`, `omega serve`) — assume they are running. `omega test` is fine; it starts its own emulator.
+- **Grep the logs FIRST.** Two lanes, both truncated per launch: the CLI's own run in the app's `logs/dev.log` / `logs/build.log` / `logs/test.log`, and the firebase children in `dist/emulator.log` / `dist/dev.log` / `dist/test.log`, beside firebase-tools' `*-debug.log`. Emulator traffic and the last failure are already on disk — read them instead of restarting anything (`docs/shared/logging.md`).
+- **Never mock — test against the real emulator.** Every feature ships tests at every surface it exposes.
+- **Secrets never enter `config/omega.json5`** — `.env` only; the config validator hard-fails secret-shaped keys.
+- **Deploys are deliberate** — only `omega deploy` publishes; a commit never does (`docs/shared/deploys.md`).

package/claude-plugin/skills/brandcheck/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: brandcheck
+description: Use when editing config/omega.json5, theme or default-page copy, section defaults, or any file that names a brand — brand facts belong in config, never as a hardcoded name, url, or hex, and secrets never in config at all.
+user-invocable: true
+---
+
+# Brandcheck (config and copy consistency)
+
+One brand fact, one home: `omega.json5`. Everything a page says about the brand comes through `site.*`, and everything it looks like comes through the `--omega-*` tokens the config's one hex feeds. Copy that hardcodes a name, a URL, or a color is a fork that breaks on the next brand.
+
+## Where the truth lives
+
+- `docs/shared/config.md` — the omega.json5 schema, the merge chain, per-instance URL resolution, the validator.
+- `docs/shared/theming.md` — `brand.color` → `composeBrandTokens()` → the accent ramps, and the token contract components read.
+- `docs/web/sections.md` — section defaults and why they carry `{{ site.brand.name }}` rather than a name.
+
+## The checklist
+
+1. **Brand facts are read, never typed.** `{{ site.brand.name }}`, `site.url`, `site.socials.*` — in layouts, sections, section defaults, and default pages alike. A literal brand name or URL in framework or theme copy is the finding; the theme layer speaks generic, and a brand's own voice arrives through section args and config.
+2. **The two required fields exist.** `brand.id` (a URL-scheme-safe slug) and `brand.name` are the only universally required config fields — everything else is optional and has a resolution path, so a missing value is a config question, not a place to inline a default in a template.
+3. **A brand URL comes from the resolution order**, not from a guess: an instance entry's `url`, else the instance's `brand.url`, else the shared `brand.url`. Multi-instance brands (admin, subdomains) are exactly where a typed URL goes wrong.
+4. **One hex, and it lives in config.** `brand.color` drives the light and dark accent ramps; markup and scss read `var(--omega-accent…)` and the neutral/status tokens. A second brand hex anywhere in scss or markup means two sources for one color.
+5. **Read the RESOLVED config, not one file.** The chain is `defaults ← company ← brand shared ← brand targets.<type> ← local shared ← local targets.<type>`; a value that looks wrong in the local config is often set — or overridden — a layer away.
+6. **No secrets in config.** `.env` only; the validator hard-fails secret-shaped keys in omega.json5. An API key arriving as a "brand" value is the same bug wearing a different name.
+7. **Copy stays fork-portable.** Defaults, demo args, and sample content show the `{{ site.brand.name }}` tokens a consumer would see, so a fork lands its own name at fork time with nothing to find and replace.
+
+## Verifying
+
+Grep the surface you touched for the brand's literal name, its host, and `#` hex literals — three greps that make this checkable rather than a matter of reading care. Then confirm the value's real home in `config/omega.json5` (app) and the brand root's config.

package/claude-plugin/skills/browser/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: browser
+description: Use when the user wants to open, view, screenshot, test, or debug a page in a real browser, fill or submit forms, inspect live pages, run Lighthouse, attach to a running desktop dev app, or test an unpacked extension.
+user-invocable: true
+---
+
+# Browser (Chrome DevTools through the mcp-router)
+
+Control a browser over CDP. **Your session owns a private Chrome** — it auto-launches on your first tool call, only ever shows YOUR pages, and exits when your session ends. No setup, no ports, no cleanup, and parallel sessions cannot touch each other's browsers.
+
+## How to use
+
+1. `new_page` with your target URL (or `navigate_page` the initial blank page).
+2. Work with `click`, `fill`, `take_screenshot`, `evaluate_script`, etc.
+3. That's it — open/close pages freely; the whole browser is yours.
+
+## SAFETY
+
+- **NEVER quit, kill, or restart Chrome by app name** (`killall "Google Chrome"`, `pkill "Google Chrome"`, osascript). The user's PERSONAL Chrome is running too — you would kill their browser. You never need to kill anything: your browser dies with your session.
+- **Never launch Chrome manually.** The MCP owns the browser lifecycle.
+
+## Diagnosing a server? Grep the logs first
+
+A browser answers "what does this page render", not "why did the build fail" or "what did the backend serve". Every OMEGA surface already tee'd its run to disk — an app's `logs/dev.log` and `logs/build.log`, the backend's `dist/emulator.log`, a lane's `.temp/logs/<lane>.log`. Read those FIRST, and never restart a dev server, emulator or watcher to see output it already wrote. Paths and contract: `docs/shared/logging.md`.
+
+## Ephemeral profile
+
+The browser uses a throwaway profile — cookies/logins do NOT persist between sessions. If a task needs auth, log in during the task.
+
+## The router: one endpoint, four upstreams
+
+Every browser tool arrives through a single MCP server, `mcp-router` (`@omega.js/mcp-router`, declared once by this plugin). Tools are namespaced `mcp__mcp-router__<upstream>__<tool>` — so the default driver's click is `mcp__mcp-router__chrome-devtools__click`.
+
+| Upstream | For | Needs |
+|---|---|---|
+| `chrome-devtools` | The default: a fresh isolated Chrome | nothing |
+| `chrome-devtools-electron` | An ALREADY-RUNNING omega desktop dev app | the app started with a remote-debugging port |
+| `chrome-devtools-extension` | An unpacked extension in Chrome for Testing | `OMEGA_EXTENSION_PATH` |
+| `omega-extension` | The manager's own extension automation server | `@omega.js/manager` installed |
+
+Two meta-tools control them per session, and neither touches disk:
+
+- `router__list_upstreams` — what exists, what is enabled on disk, what is active in THIS session.
+- `router__enable_upstream {name, env?}` — activate one for this session; its tools appear in your tool list. `env` sets vars on the child process (passing it restarts a running child).
+
+An upstream marked `on-demand` stays invisible until you enable it. `router__disable_upstream` drops it and stops its child.
+
+## Desktop apps (Electron)
+
+This skill's default browser is always a fresh Chrome. To drive an already-running omega desktop dev app, enable `chrome-devtools-electron` — it attaches to the app's `--remote-debugging-port` at `http://127.0.0.1:$OMEGA_CDP_PORT` (default 9222). Pass a different port for the session with `router__enable_upstream {name: "chrome-devtools-electron", env: {"OMEGA_CDP_PORT": "9333"}}`.
+
+## Browser extensions
+
+To test an unpacked extension, enable `chrome-devtools-extension`: same isolated model, but it launches Chrome for Testing (from puppeteer's download cache) with the extension at `$OMEGA_EXTENSION_PATH` pre-loaded and the extension tool category on (`install_extension`, `list_extensions`, `reload_extension`, `trigger_extension_action`, …). Set `OMEGA_EXTENSION_PATH` to the built extension directory before the session starts. No Chrome for Testing installed → it fails loudly; install one with `npx puppeteer browsers install chrome`.
+
+## Available tools
+
+Navigate (`navigate_page`), screenshot (`take_screenshot`), click (`click`), fill forms (`fill`, `fill_form`), type (`type_text`), hover (`hover`), evaluate JS (`evaluate_script`), console logs (`list_console_messages`), network requests (`list_network_requests`), keyboard input (`press_key`), resize (`resize_page`), accessibility snapshots (`take_snapshot`), Lighthouse audits (`lighthouse_audit`), performance traces, heap snapshots, dialog handling.
+
+## Where the knowledge lives
+
+- `docs/mcp-router/index.md` — the router guide: architecture, the meta-tools, the bundled upstreams table, config layering, and the plugin wiring.
+- `packages/mcp-router/README.md` — the package: the `omega-mcp` CLI, the overlay at `~/.omega/mcp-router/`, and the env vars.
+- Adding a private upstream (playwright, firebase, …) is an overlay entry — it never edits the bundled defaults.

package/claude-plugin/skills/client/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: client
+description: Use when working in @omega.js/client or on any frontend behavior it owns — the runtime singleton, auth state, data-omega-bind bindings, the Firestore, storage, notifications and Sentry modules, omega.request(), verts, icons, motion, or anything in packages/client/.
+user-invocable: true
+---
+
+# OMEGA Client (@omega.js/client)
+
+`@omega.js/client` is the runtime singleton every frontend framework embeds — `@omega.js/web` ships it into each page, `@omega.js/desktop` runs it in the renderer, `@omega.js/extension` runs it in every context. One `import omega from '@omega.js/client'` returns the same already-initialized `Manager`, owning storage, auth, bindings, firestore, notifications, service-worker, sentry, dom, utilities, device, request, and verts, alongside the transport-free `icon-core`, `icon-renderer`, and `motion` modules the frameworks boot themselves. It is a library, not an app: real behavior is proved from inside a consuming framework.
+
+## Where the knowledge lives
+
+This skill routes; the docs are the source of truth. Read the guide BEFORE touching files.
+
+- **Working in this monorepo** — `docs/client/index.md` is the guide (identity, the module list, file conventions). The meat lives in `packages/client/docs/*.md`: architecture, modules, bindings, code-patterns, common-tasks, build-system, cdp-debugging, testing. Cross-framework contracts live in `docs/shared/`.
+- **Working in a consumer project** — read `docs/client/index.md` in the framework monorepo (the local era links `node_modules/@omega.js/client` straight into it; published installs will carry the docs inside the package ([#64](https://github.com/Omega-JS-Stack/omega/issues/64))). Consumer-side work is normally routed by the embedding framework's skill — `omega:web`, `omega:desktop`, or `omega:extension` — with this one for the runtime's own behavior.
+
+## Non-negotiables
+
+- **Singleton, always.** Never `new Manager()`, never pass the instance through function params or module-level variables.
+- **Keep Firebase imports lazy** — the dynamic imports are what keeps consumer bundles small; do not convert them to static imports.
+- **`resolveSubscription()` stays unified with `@omega.js/backend`'s `User.resolveSubscription()`** — subscription-state logic is identical frontend and backend, so a change here is a cross-stack change.
+- **The runtime is what makes the page paint contract possible** — bindings fill at auth settle, `bindings.update()` defers by ROOT key, and `FormManager`'s gates hold a submit control until its answers land. Read `docs/web/page-contract.md` before changing any of the three.
+- **Prove changes from a consumer.** `npm run prepare` plus the package tests are necessary, not sufficient; verify end to end inside a linked web, desktop, or extension app (`docs/shared/local-dev.md`).

package/claude-plugin/skills/desktop/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: desktop
+description: Use when working on a brand's desktop app or on @omega.js/desktop itself — Electron main, renderer or preload, windows, tray, menus, ipc, deep links, the auto-updater, or the sign/notarize/release pipeline, in targets/desktop or packages/desktop/.
+user-invocable: true
+---
+
+# OMEGA Desktop (@omega.js/desktop)
+
+`@omega.js/desktop` builds Electron desktop apps: a one-line-import bootstrap per Electron process, a modular lib layer (windows, tray, menu, context-menu, ipc, storage, theme, deep-link, protocol, app-state, auto-updater, client-bridge, auth-persistence, analytics, usage, remote-config, remote-scripts, restart-manager) extended by file-based definitions, a multi-platform build/sign/notarize/release pipeline, and a built-in test framework. It is the EM successor.
+
+## Where the knowledge lives
+
+This skill routes; the docs are the source of truth. Read the guide BEFORE touching files.
+
+- **Working in this monorepo** — `docs/desktop/index.md` is the guide (per-process singletons, the lib-module table, windows, icons, build system, config flow, CDP debugging, the CLI table). The per-subsystem meat lives in `packages/desktop/docs/*.md`. Cross-framework contracts live in `docs/shared/` (config, theming, icons, deploys, updates, testing, local-dev).
+- **Working in a consumer project** — read `docs/desktop/index.md` in the framework monorepo (the local era links `node_modules/@omega.js/desktop` straight into it; published installs will carry the docs inside the package ([#64](https://github.com/Omega-JS-Stack/omega/issues/64)).
+- **`@omega.js/client` comes with it.** The client singleton runs in the renderer, so any task touching auth, Firestore, subscriptions, notifications, or `data-omega-bind` is client work too — `docs/client/index.md` and the `omega:client` skill.
+
+## Non-negotiables
+
+- **Read the guide before editing.** Which process owns a concern (main is the auth source of truth; renderers reflect via IPC) is the first thing to get right.
+- **🚫 Never start the user's long-running processes** (`npm start`, a packaged app's dev loop) — assume they are running.
+- **Grep the logs FIRST.** The app's `logs/` holds `dev.log` (the gulp run + the Electron child), `build.log`, `test.log`, and `runtime.log` — the running app's own main/preload/renderer lines. All truncated per launch. Read them instead of relaunching the app to see what it already printed (`docs/shared/logging.md`).
+- **Secrets never enter `config/omega.json5`** — `.env` and the OS keychain only.
+- **Deploys are deliberate** — only `omega deploy` / `omega publish` ship a release; a commit never does (`docs/shared/deploys.md`).

package/claude-plugin/skills/extension/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: extension
+description: Use when working on a brand's extension app or on @omega.js/extension itself — the MV3 manifest, background service worker, popup, options, sidepanel, content scripts, cross-context auth, _locales translation, or the package/publish pipeline, in targets/extension or packages/extension/.
+user-invocable: true
+---
+
+# OMEGA Extension (@omega.js/extension)
+
+`@omega.js/extension` builds cross-browser MV3 extensions (Chrome, Firefox, Edge, Opera, Brave): a one-line-import bootstrap per extension context, a component-based architecture across background, popup, options, sidepanel, content, pages, and offscreen, cross-context auth synchronization with the background service worker as the source of truth, auto-translation across 16 languages, a gulp/esbuild build into `packaged/<browser>/`, and a four-layer test framework. It is the BXM successor.
+
+## Where the knowledge lives
+
+This skill routes; the docs are the source of truth. Read the guide BEFORE touching files.
+
+- **Working in this monorepo** — `docs/extension/index.md` is the guide (per-context singletons, the component table, auth sync, build system and modes, themes, defaults, translations, hooks, environment detection, the CLI table). The per-subsystem meat lives in `packages/extension/docs/*.md`. Cross-framework contracts live in `docs/shared/` (config, theming, icons, translation, testing, deploys, updates, local-dev).
+- **Working in a consumer project** — read `docs/extension/index.md` in the framework monorepo (the local era links `node_modules/@omega.js/extension` straight into it; published installs will carry the docs inside the package ([#64](https://github.com/Omega-JS-Stack/omega/issues/64)).
+- **`@omega.js/client` comes with it.** The client singleton runs in every context, so any task touching auth, Firestore, subscriptions, notifications, or `data-omega-bind` is client work too — `docs/client/index.md` and the `omega:client` skill.
+
+## Non-negotiables
+
+- **Read the guide before editing.** Which context owns a concern — background is the auth source of truth, everything else reflects it over `chrome.runtime` messaging — is the first thing to get right.
+- **🚫 Never start the user's `npm start`** — it is their long-running watcher. **Grep the logs FIRST**: the app's `logs/dev.log`, `logs/build.log` and `logs/test.log` carry the whole run, truncated per launch and ANSI-stripped, so a build error or a failing suite is a `grep`, never a restart (`docs/shared/logging.md`).
+- **Gate behavior on the intentional environment check** (`isProduction()`, or `isDevelopment() || isTesting()`) — never `!isDevelopment()`.
+- **Secrets never enter `config/omega.json5`** — `.env` only; the config validator hard-fails secret-shaped keys.
+- **Deploys are deliberate** — only `omega deploy` (and an explicit `OMEGA_IS_PUBLISH` run) reaches a store; a commit never does (`docs/shared/deploys.md`).

package/claude-plugin/skills/main/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: main
+description: Use when working across more than one OMEGA framework, in the monorepo itself, or when the right home for a change is not yet known — which package owns a thing, the docs topology, the brand map, or where project state lives.
+user-invocable: true
+---
+
+# OMEGA — the hub
+
+The `@omega.js` framework ecosystem lives in ONE monorepo: npm workspaces under `packages/`, test brands under `brands/`, changesets for independent versioning. Start at the repo root `AGENTS.md` — it is the map, and it carries the hard rules (the legacy manager repos are read-only; nothing publishes until the proving checkpoint). This skill orients; every fact belongs to a guide below.
+
+## The roster
+
+| Package | Skill | Guide |
+|---|---|---|
+| `@omega.js/web` | `omega:web` | `docs/web/index.md` |
+| `@omega.js/backend` | `omega:backend` | `docs/backend/index.md` |
+| `@omega.js/desktop` | `omega:desktop` | `docs/desktop/index.md` |
+| `@omega.js/extension` | `omega:extension` | `docs/extension/index.md` |
+| `@omega.js/client` | `omega:client` | `docs/client/index.md` |
+| `@omega.js/manager` | `omega:manager` | `docs/manager/index.md` |
+| `@omega.js/devkit` | — | `docs/devkit/index.md` |
+| `@omega.js/config` | — | `docs/shared/config.md` |
+| `@omega.js/account` | — | `packages/account/src` |
+| `@omega.js/template-kit` | — | `docs/web/template-kit.md` |
+| `@omega.js/mcp-router` | `omega:browser` | `docs/mcp-router/index.md` |
+
+Every framework ships the same context-aware `omega` / `omg` / `mgr` dispatcher: the nearest `package.json` walking up from cwd names the framework whose CLI runs.
+
+## The docs topology
+
+`docs/` is the SSOT. Cross-framework contracts are `docs/shared/*.md` — config, local-dev, testing, deploys, updates, publishing, icons, theming, translation, analytics, agent-docs, brands, rulings. Each framework's guide is `docs/<framework>/index.md` with its deep docs beside it, and the package's own `README.md` carries long-form detail. The four framework guides (web, backend, extension, desktop) mirror each other section for section — each guide's header states the rule.
+
+The repo-root `AGENTS.md` is the ONE agent entry — packages carry no agent docs (the parent walk hands every monorepo session the map). Consumer brands import `node_modules/@omega.js/AGENTS.md`, a symlink the workspace service maintains at the map. The brand-root guide is `docs/manager/brand.md`; the contract is `docs/shared/agent-docs.md`.
+
+## The brands
+
+Brand work happens in one of four places — resolve which before touching files, never guess a path:
+
+| Brand | What it is |
+|---|---|
+| `brands/sandbox-brand` | Synthetic fixture; test runs mangle and reset it |
+| `brands/omega-playground` | "OMEGA Playground" — the standing live test brand, classy theme |
+| `brands/newsflash-brand` | "The Daily Build" — the second-skin brand, newsflash theme |
+| `../omega-brand` | The REAL brand, omegajs.dev — a sibling repo, LIVE |
+
+Nothing in this monorepo is ever the production brand. Topology, history, and the local-era `file:` dependency contract: `docs/shared/brands.md`. Linking a brand against the local frameworks: `docs/shared/local-dev.md`.
+
+## Inspecting a running system — grep the logs FIRST
+
+Every OMEGA surface tees its whole run to a file, truncated on each launch: an app's `logs/dev.log` / `logs/build.log` / `logs/test.log`, a brand root's `logs/manage.log` (the manage walk) and `logs/dev.log` (the `omega dev` fan-out), the backend's `dist/emulator.log`, this monorepo's `.temp/logs/<lane>.log` and `.temp/logs/watch-all.log`, and each e2e lane's `.temp/<lane>/steps.log` (`grep '^FAIL' .temp/*/steps.log` names the failing step). Server state, build errors, test failures and emulator traffic are ALREADY on disk — never restart a dev server, emulator or watcher, and never re-run a suite, just to see output. The mechanism, the retention rule and the full path table: `docs/shared/logging.md`.
+
+## Project state
+
+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. Shipped work is `CHANGELOG.md`; durable rulings from the retired board era are `docs/shared/rulings.md`.

package/claude-plugin/skills/manager/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: manager
+description: Use when working at a brand monorepo root, on the manage cycle, or on @omega.js/manager itself — the service walk, reconciling a brand to its config/omega.json5, onboarding, deploy and update fan-out, .omega state, disperse, or the agent-docs chain.
+user-invocable: true
+---
+
+# OMEGA Manager (@omega.js/manager)
+
+`@omega.js/manager` is the orchestration engine for a brand monorepo. `npx omega` at a brand root walks every service in dependency order — workspace, github, cloud, cloudflare, domain, payment, analytics, seo, certificates, disperse, update, and the rest — and reconciles each one to `config/omega.json5`, idempotently: run it twice, get the same result. From a company workspace the same command fans out across every managed brand. It also owns `omega onboard` (create or converge a brand) and the deliberate `omega deploy` / `omega update` fan-outs across a brand's apps.
+
+## Where the knowledge lives
+
+This skill routes; the docs are the source of truth. Read the guide BEFORE touching files.
+
+- **Working in this monorepo** — `packages/manager/README.md` is the package's long-form reference (the wizard, the manage cycle, the three data buckets, every service, company mode, the CLI surface); `docs/manager/index.md` is the short map pointing at it. The brand-monorepo shape and the agent-docs chain are in `docs/shared/agent-docs.md`; cross-framework contracts are in `docs/shared/` (config, deploys, updates, brands, local-dev).
+- **Working in a consumer brand** — the brand root's `AGENTS.md` imports `node_modules/@omega.js/AGENTS.md`, a symlink the workspace service maintains at the monorepo's top-level `AGENTS.md` (the map). The brand-root guide itself is `docs/manager/brand.md`: the app-to-target map, the verbs, and the brand hard rules — read it first, then the framework guide for whichever app the work is in. Published installs will carry the map and docs inside the package ([#64](https://github.com/Omega-JS-Stack/omega/issues/64)).
+
+## Non-negotiables
+
+- **No package carries agent docs.** The repo-root `AGENTS.md` map is the one agent entry; the brand guide is `docs/manager/brand.md`. Never create a `packages/<pkg>/AGENTS.md` or `CLAUDE.md`.
+- **Upstream-first, permission first**: a defect the next consumer would hit gets fixed in the framework, not patched in the brand — but a consumer session surfaces the proposed framework change and waits for Ian's go (or files an upstream issue) before editing the monorepo. The rule and its "within reason" line live in `docs/shared/local-dev.md`.
+- **Every service is idempotent.** Check before acting; a second run must change nothing.
+- **Grep the logs FIRST.** The manage cycle tees to `<brandRoot>/logs/manage.log` and the `omega dev` fan-out to `<brandRoot>/logs/dev.log`, and every app keeps its own `logs/` beside it — truncated per launch, gitignored. What a service walk did, and what a dev leg printed, is on disk: read it instead of re-running a manage or restarting the stack (`docs/shared/logging.md`).
+- **Secrets never enter `config/omega.json5`** — `.env` and `.omega/secrets/` only; `.omega/` is gitignored and never committed.
+- **Deploys are deliberate** — only `omega deploy` publishes, backend first; a commit never does (`docs/shared/deploys.md`).

package/claude-plugin/skills/seo/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: seo
+description: Use before finishing any page work in a website app or in packages/web — or when the ask names SEO, meta title or description, canonical, open graph, structured data, one h1, sitemap, robots.txt, noindex, or search ranking.
+user-invocable: true
+---
+
+# SEO (OMEGA web pages)
+
+A page's search surface is almost entirely MECHANISM, not markup: the core head chrome emits the tags, page frontmatter supplies the values, and the sitemap is a default page. So the review is checking the inputs and checking that nothing was hand-written around the mechanism.
+
+## Where the mechanism lives
+
+- `packages/web/core/_includes/core/head.html` — emits `<title>`, `description`, `canonical`, the full `og:*` / `twitter:*` set, `robots`, favicons, feed links.
+- `packages/web/core/_includes/core/foot.html` — emits every `application/ld+json` block. Read the gates there before adding a `schema` key (item 4 below).
+- `packages/web/defaults/pages/sitemap.html` + `robots.html` — `/sitemap.xml` and `/robots.txt` as default pages a consumer can override.
+- The frontmatter allow-list (`meta`, `schema`, `sitemap`, …) and the URL contract: `docs/web/index.md`. Translated pages: `docs/shared/translation.md`.
+
+## The checklist
+
+1. **`meta.title` and `meta.description` are present** in the page's frontmatter. An empty title falls back to `site.brand.name` — a page titled with the bare brand name is the tell. Keep the title around 60 characters and the description around 155 so neither is cut off in a result listing.
+2. **Nothing hand-writes a meta tag.** No page or section emits `<title>`, `meta name="description"`, `link rel="canonical"`, or any `og:`/`twitter:` tag — head.html already did, and a second one is a duplicate. A page needs a value, not a tag.
+3. **Exactly one h1 per page.** The page's head/heading section supplies it (`docs/web/sections.md` — the head cluster and its `h1_class` knob); a second heading section on the same composition is the usual cause of two.
+4. **Structured data comes from foot.html, and each type has its OWN gate.** Never write a `ld+json` script into a page — check the gate instead, because a `schema` block on the wrong type is a silent no-op:
+   - `schema.software_application.enabled` and `schema.faq_page.enabled` are the two frontmatter switches. The FAQ block also needs items, which it takes from `schema.faq_page.items`, else `faqs.items`, else `alternative.faqs.items` — enabled with no items anywhere renders nothing.
+   - BlogPosting rides `resolved.post.id` and Person rides `resolved.member.id` — a collection document's own data, not a frontmatter switch. Nothing to set on a page.
+   - Breadcrumbs, the Organization/brand block (the `ContactPoint` lives inside it), and the WebSite/SearchAction block are unconditional on every page — they read `site`, so a gap there is a config gap.
+   - ContactPage renders on the URL: `page.url == "/contact"` only.
+   - The Product renderer is DEAD — it gates on a `page-is-product` flag nothing in the framework assigns. Product markup needs that flag wired first; a `schema` key will not reach it.
+5. **Indexability is deliberate, and it is ONE flag.** `meta.index: false` emits `noindex` AND drops the page from `/sitemap.xml`, `/pages.json` and `/llms.txt` (#564; `sitemap.include` is retired, and "indexable but out of the sitemap" is not a state a page can be in). The site-wide default is the same key one level up, `targets.web.meta.index`. If a page has the flag, it is on purpose; if a page that should be private lacks it, that is the finding. Drafts, `/admin/`, `/test/` and redirect stubs get it from the ENGINE, so they need nothing set.
+6. **The social image resolves.** `meta.image`, else `brand.images.social`, else the brandmark. Dimensions default to 1200×630 (`meta.og_image_width`/`_height` override).
+7. **Internal links use the URL contract** — flat and extensionless, no trailing slash (`/signin`, never `/signin/` or `/signin.html`) — and every one resolves to a real page or a default page's permalink.
+8. **Translations are the translate pass's job.** hreflang alternates, `og:locale`, and the translated sitemap entries are produced from `dist/`; never hand-author an alternate.
+
+## Verifying
+
+Read the built output rather than trusting the template: `omega build` in the app, then check `dist/<page>.html` and `dist/sitemap.xml`. For a running dev server, inspect the live head through the `omega:browser` skill instead of restarting anything.

package/claude-plugin/skills/theme/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: theme
+description: Use when building or changing a theme or a theme override — packages/web/themes, a brand's own src/themes/<id>, a section folder under src/_sections, or the tier-1 src/assets/css/main.scss — or when the ask names theming, skins, forks, tokens, the cascade, or inherit.
+user-invocable: true
+---
+
+# Theme (the OMEGA theme cascade)
+
+A theme is a LAYER, not a folder of files you own: resolution picks a winner per file across consumer → active theme → base, and the same markup is meant to survive a theme switch. So most theme work is deciding which layer a change belongs to and which lane carries it — and the docs below already answer that. This skill routes; never re-derive a rule from the file tree.
+
+## Where the mechanism lives
+
+- `docs/web/sections.md` § Resolution — the whole-folder, first-match-wins order (consumer `<src>/_sections/<id>/` → active theme → base), the one `inherit` exception for the `js`/`scss` lanes, and why html and json5 are never inheritable.
+- `docs/web/sections.md` § "Markup convention: base, skin, fork" — what base owns, what a skin may not fork, the theme-prefixed BEM rule, and the three-rung theme ladder.
+- `docs/shared/theming.md` — the `--omega-*` token contract and the surface tiers, the motion library, the two consumer tiers (tier 1 the consumer `main.scss`, tier 2 a consumer-local full theme at `<src>/themes/<id>` that beats the packaged one), and the two blessed CSS fall-through lanes.
+- `docs/web/classy-v2/DIRECTION.md` — the LOCKED classy spec. Where it and a comp disagree, the file wins.
+- `docs/web/index.md` — the guide for everything else the theme rides: the asset lanes, the layered `_layouts`, the CLI.
+- The code the docs describe: `packages/web/src/layers.js` (`resolveThemeLayers`), `packages/web/src/overrides.js` (`overrideLanes` — the sections/includes/css lanes), `packages/web/themes/`.
+
+## The checklist
+
+1. **The change lands in the LOWEST layer that owns it.** Structure is base's; look is the skin's; identity is a bounded fork. A skin that forks shared markup to restyle it is the finding — `docs/web/sections.md` § Markup convention.
+2. **A fork is declared.** Each skin theme's README carries a `## Forks` section whose bullets name its markup files, and the list must equal what is on disk in both directions — pinned by `packages/web/test/theme-convention.test.js`, which also polices the class prefixes.
+3. **Classes follow the convention.** `omega-*` BEM everywhere, `<theme>-*` BEM only inside that theme's own forks; a bare class needs the allowlist entry the same test reads.
+4. **Color, spacing, radii, and speeds come from the tokens**, never from a literal — `docs/shared/theming.md` names the token families and the light/dark pairing rule.
+5. **An override folder is whole.** Taking a section means taking its folder; a lone `section.scss` does nothing. The one exception is a json5 `inherit: ['js']` / `['scss']` declaration, which also makes the inherited js's selectors part of your markup contract — `docs/web/sections.md` § Resolution.
+6. **The override map is a command, not a directory read.** `npx omega customize --list` prints every shadowable file with its owning layer and your existing shadows; `npx omega customize <path>` materializes one with its provenance header. Reading the theme source tree to guess a path is not the mechanism.
+7. **A consumer's theme work picks its tier deliberately.** Recolor and Sass knobs are tier 1 (`src/assets/css/main.scss`, `omega:main`); a full brand theme is tier 2 (`src/themes/<id>`). A fork of the framework's own themes is neither.
+8. **Upstream-first.** A hole found while theming a brand is fixed in the framework, not patched in the consumer — the rule and its limits are in `docs/shared/local-dev.md`.
+
+## Verifying
+
+Read the BUILT output, not the source layer: `omega build` in the app, then check that the winning file is the one you meant (`npx omega customize --list` names the layer it resolved from) and that the compiled sheet carries your rules. The framework's own cascade guards are `packages/web/test/themes.test.js`, `overrides.test.js`, `customize.test.js`, and `theme-convention.test.js` — a theme change that does not keep those green has moved a contract, not a style.

package/claude-plugin/skills/web/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: web
+description: Use when working on a brand's website app or on @omega.js/web itself — Eleventy and Liquid templates, sections and components, themes, blueprints and default pages, the asset pipeline, or the omega CLI, in targets/website or packages/web/.
+user-invocable: true
+---
+
+# OMEGA Web (@omega.js/web)
+
+`@omega.js/web` builds a brand's marketing site and authenticated frontend: Eleventy 3 + LiquidJS with `@omega.js/template-kit`, layered themes that override by path with zero copying, the section/component library, ~60 virtual default pages, the esbuild/sass/PurgeCSS asset pipeline, and an ESM boot runtime that hands every page the `@omega.js/client` singleton. It ships the `omega` CLI for the whole consumer lifecycle. It is the UJM successor, rebuilt rather than ported — never carry a Jekyll-era assumption into it.
+
+## Where the knowledge lives
+
+This skill routes; the docs are the source of truth. Read the guide BEFORE touching files.
+
+- **Working in this monorepo** — `docs/web/index.md` is the guide (identity, module map, CLI, conventions). Its deep references: `docs/web/sections.md`, `docs/web/omega-sections-spec.md`, `docs/web/template-kit.md`, `docs/web/ads-system.md`, `docs/web/classy-v2/DIRECTION.md`. Cross-framework contracts live in `docs/shared/` (config, theming, icons, translation, testing, deploys, updates, local-dev). Long-form package detail is `packages/web/README.md`.
+- **Working in a consumer project** — read `docs/web/index.md` in the framework monorepo (the local era links `node_modules/@omega.js/web` straight into it; published installs will carry the docs inside the package ([#64](https://github.com/Omega-JS-Stack/omega/issues/64)).
+- **The framework ships shared browser modules.** Before hand-rolling a chart, a diagram, tooltips, an icon in JS, or reCAPTCHA on a form, read `docs/web/libs.md`: it inventories `core/js/libs/` and the `__main_assets__/js/libs/<name>.js` import idiom that reaches it from any layer, consumer page modules included.
+- **`@omega.js/client` comes with it.** The client singleton ships into every page, so any task touching auth, Firestore, subscriptions, notifications, or `data-omega-bind` is client work too — `docs/client/index.md` and the `omega:client` skill.
+
+## Non-negotiables
+
+- **Read the guide before editing.** Layers, the frontmatter allow-list, and the section contract each have rules that are not guessable from the file tree.
+- **🚫 Never run a consumer's `omega dev`** — it is the user's long-running process. Assume it is up; ask the user to start it if it is not.
+- **Grep the logs FIRST.** Every verb tees its whole run to the app's `logs/` — `dev.log`, `build.log`, `test.log`, truncated per launch and ANSI-stripped. `tail`/`grep` them; restarting the dev server or re-running a build to see output it already wrote is never the move (`docs/shared/logging.md`).
+- **Every page obeys the page paint contract** — static content paints immediately, user data arrives through bindings with skeletons, an answer the visitor acts on resolves ONCE, every wait has a deadline and a named fallback, and a form's submit control is gated until its answers land: `docs/web/page-contract.md`.
+- **Consumer page frontmatter is meta-only** and content keys are stripped with a build warning. Content belongs in sections.
+- **Compose, never hand-roll HTML.** `/test/sections` (dev builds only) is the auto-generated gallery of every RESOLVED section and component: the entry page carries the args contract and embeds each demo variant as its own frame page. Read it before writing markup for a page — `docs/web/sections.md` §9.
+- **Secrets never enter `config/omega.json5`** — `.env` only; the config validator hard-fails secret-shaped keys.
+- **Nothing generated is committed** — `dist/` and `.omega/` are artifacts. The translation cache is the one deliberate exception.

package/dist/cli-run.js

@@ -0,0 +1,34 @@
+/**
+ * run() — the manager CLI body, reached through the omega-bin brand-root
+ * dispatch ('@omega.js/manager/cli'): at a brand root, every framework's
+ * `omega` bin hands over here so brand-level commands (`omega test`,
+ * `omega manage`) fan out over targets/* instead of guessing one framework.
+ * The manager ships that bin itself too (bin/omega → src/omega-bin.js, #276),
+ * so a fresh clone with no framework installed still lands here — that is
+ * where `npx omega onboard` runs. The company orchestrator spawns this file
+ * directly as its per-brand child entry.
+ */
+// Value-less flags must be declared boolean — otherwise yargs treats the next
+// positional as the flag's VALUE (mirrors the framework bins).
+const BOOLEAN_FLAGS = ['continue-on-error', 'dry-run', 'execute', 'parallel', 'manage', 'all', 'full', 'verify', 'publish', 'extended'];
+
+async function run() {
+  // Local-dist freshness guard: a stale locally-linked dist rebuilds and the
+  // invocation re-execs once, so no command ever runs stale framework code
+  require('./vendor/devkit/local.js').freshnessBoot({ packageName: '@omega.js/manager' });
+
+  // yargs' built-in --version/--help are disabled so `-v`/`--version` route to
+  // our version command through the alias table.
+  const argv = require('yargs')(process.argv.slice(2))
+    .boolean(BOOLEAN_FLAGS)
+    .version(false)
+    .help(false)
+    .parseSync();
+  const cli = new (require('./cli.js'))(argv);
+
+  await cli.process(argv);
+}
+
+module.exports = { run, BOOLEAN_FLAGS };
+
+if (require.main === module) run();

package/dist/cli.js

@@ -0,0 +1,29 @@
+/**
+ * The @omega.js/manager CLI dispatcher — devkit's shared router over
+ * src/commands/. Every verb is NAMED (#229): `omega manage` walks every
+ * service and reconciles the brand to its omega.json5, `omega dev` boots the
+ * local stack, and a bare `omega` prints help and touches nothing — a CLI
+ * that silently rewrites a brand because it was called with no arguments is
+ * the wrong default. `manage` has no alias: one walk, one name.
+ */
+const path = require('node:path');
+
+const { createCliRouter } = require('./vendor/devkit/cli-router.js');
+
+// Command name → positional/flag aliases
+const ALIASES = {
+  onboard: ['-o', '--onboard', 'create', 'new'],
+  dev: ['--dev', 'serve'], // brand-root local stack (web + backend by default)
+  deploy: ['--deploy'], // brand-root deliberate publish fan-out (backend first)
+  build: ['--build'], // brand-root build fan-out, every target type (#603)
+  clean: ['--clean'], // brand-root clean fan-out, every target type (#603)
+  update: ['--update', 'outdated', 'out'], // brand-root dependency-freshness fan-out (devkit update per target)
+  test: ['--test'],
+  version: ['-v', '--version'],
+};
+
+module.exports = createCliRouter({
+  commandsDir: path.join(__dirname, 'commands'),
+  aliases: ALIASES,
+  defaultCommand: 'help',
+});

package/dist/commands/build.js

@@ -0,0 +1,17 @@
+/**
+ * `omega build` at a brand root — compile every target, each in its own
+ * framework's hands (#603): the web site, the backend's staged dist, the
+ * desktop bundles, the extension's gulp lane, and a custom target's own
+ * `build` script.
+ *
+ *   omega build                     → every target, backend first
+ *   omega build --target=web        → one target (target key or dir name)
+ *   omega build --target=web,api    → explicit set
+ *
+ * The walk, the order and the loud skip are the shared brand-root fan-out
+ * (lib/verb-fanout.js); this file is the verb. Targets are independent: a
+ * failing one never stops the rest, and any failure exits 1.
+ */
+const { runVerbFanout } = require('../lib/verb-fanout.js');
+
+module.exports = async (options = {}, deps = {}) => runVerbFanout('build', options, deps);

package/dist/commands/clean.js

@@ -0,0 +1,16 @@
+/**
+ * `omega clean` at a brand root — wipe every target's build output, each in
+ * its own framework's hands (#603): the frameworks' own `omega clean`, and a
+ * custom target's own `clean` script.
+ *
+ *   omega clean                     → every target
+ *   omega clean --target=web        → one target (target key or dir name)
+ *   omega clean --target=web,api    → explicit set
+ *
+ * The walk, the order and the loud skip are the shared brand-root fan-out
+ * (lib/verb-fanout.js); this file is the verb. Targets are independent: a
+ * failing one never stops the rest, and any failure exits 1.
+ */
+const { runVerbFanout } = require('../lib/verb-fanout.js');
+
+module.exports = async (options = {}, deps = {}) => runVerbFanout('clean', options, deps);