@omega.js/desktop 0.53.0 → 0.54.1

package/docs/shared/logging.md

@@ -1,205 +0,0 @@
-# Logging — the tag contract and the file contract
-
-Two contracts live here. **What a line says**: every log line carries one identity tag.
-**Where a line lands**: every dev server, build, test runner, emulator and watcher tees
-its whole run to a greppable file ([#197](https://github.com/Omega-JS-Stack/omega/issues/197)).
-The tag contract first, the file contract from [The file tee](#the-file-tee) down.
-
-## The tag contract
-
-Every log line in the ecosystem carries ONE identity tag: `[@omega.js/<package>:<module>]`.
-The module segment is the file's identity (`push`, `watcher`, `auth:sync` — sub-modules
-join with `:`). Ratified 2026-07-29 ([#12](https://github.com/Omega-JS-Stack/omega/issues/12)).
-
-### The debug level (`OMEGA_DEBUG`)
-
-`debug` is the ONE opt-in level ([#230](https://github.com/Omega-JS-Stack/omega/issues/230)): a
-backend `ctx.debug(...)` line is dropped whole — console AND the log file — unless
-`OMEGA_DEBUG` is set (truthy STRING semantics, the house's `TEST_EXTENDED_MODE` idiom:
-`OMEGA_DEBUG=0` reads as on; read live per line). Fat payloads belong there: full user
-records, raw webhook bodies. Two related quieting rules from the same issue: boot-time
-environment notes (the TEST banner, the resolved-mode line) are suppressed under the
-emulator (`FUNCTIONS_EMULATOR`) and latched once-per-process everywhere else, and the
-`omega dev` leg output collapses consecutive duplicate lines into one plus a
-`(repeated N×)` note.
-
-### PII and secrets
-
-**A log line names a user by address or uid, never by serializing the document.** A user
-document carries `api.privateKey`, the consent records, the signup IP and the attribution,
-and a backend line lands in Cloud Logging for the whole retention window — one
-`JSON.stringify(user)` stores a live credential there in plain text
-([#632](https://github.com/Omega-JS-Stack/omega/issues/632)). The rule covers every object
-a caller hands in, not just user docs: log the identifier, not the payload — a payload's
-SHAPE (its top-level key names, a count) is fair game when the line needs it. A secret that
-has to be acknowledged at all renders through backend's `redactSecret()`
-(`***<last 4> (<n> chars)`), and a fat payload worth having while debugging goes to the
-`debug` level above, never to `log`.
-
-**A third party's credential is a credential.** An OAuth token exchange response holds the
-access, refresh and id tokens; the identity a provider answers with is the user's PII. Both
-used to ride `ctx.log` on every connection link
-([#641](https://github.com/Omega-JS-Stack/omega/issues/641)) — a line names the provider,
-the uid and whether the exchange succeeded, and nothing else. The same rule reaches an
-HTTP helper's own switches: `wonderful-fetch`'s `log: true` prints its whole configuration,
-headers included, so it never rides a request carrying ANY credential header — an
-`authorization` token, or the `omega-admin-key` an internal call authenticates with
-([#702](https://github.com/Omega-JS-Stack/omega/issues/702)). Backend's
-`test/security/fetch-log-secrets.test.js` scans the source and fails that pairing.
-
-### The two surfaces
-
-- **Build-time** (CLI, gulp, tests, the manager's services): the devkit logger prints a
-  timestamp bracket first — `[HH:MM:SS] [@omega.js/web:watcher] message`. Construction
-  stays `new Logger('watcher')`; the package segment derives at construction from the
-  constructing file's nearest `package.json` (stack-based, cached, non-throwing —
-  fallback `@omega.js/devkit`). Home: `packages/devkit/src/logger.js`.
-- **Runtime** (browser, electron renderer/main, extension): NO timestamp — devtools
-  stamps lines. Each runtime surface has its own logger emitting its own package
-  segment: client `createLogger()` (`packages/client/src/modules/logger.js`), web
-  core/js `createLogger()` (`packages/web/core/js/libs/logger.js`), and the
-  desktop/extension `logger-lite` lineage.
-- **Backend** (Cloud Functions) is server-side runtime: in PRODUCTION Cloud Logging
-  stamps every entry, so every level emits the tag ALONE —
-  `[@omega.js/backend:<module>] <invocation-id>[ <logPrefix>]: message`. Outside
-  production (the emulator's `>` prefix carries no time; plain local runs have
-  nothing at all) the same `[HH:MM:SS]` bracket the build-time logger prints opens
-  the line ([#130](https://github.com/Omega-JS-Stack/omega/issues/130)). The module
-  segment is the invocation's function name, which the context already knows
-  (`options.functionName || FUNCTION_TARGET`). Home:
-  `packages/backend/src/omega/context/logging.js`. A shared backend module
-  that logs outside a ctx carries its own file identity.
-
-### Markers and exemptions
-
-- `[DRY RUN]` survives as a MARKER after the tag, never as an identity tag (casing
-  unified; the lowercase form is retired).
-- The manager's reconciliation report is product output, not logging — it stays
-  untagged by design (ruling 2026-07-29). That covers ALL its rows: the indented
-  `✓ / ~ / +` lines AND the `[DRY RUN]` rows printed through the same report
-  (there the marker may open the line, since the report carries no tags at all).
-- Backend's record classifiers (`skip`, `expire`, `authenticated`, `test-mode`, …)
-  classify one function's records, not modules. They survive as leading WORDS, never
-  brackets (`ctx.log('local: Clearing...')`) — a bracket there would read as a second
-  identity tag ([#121](https://github.com/Omega-JS-Stack/omega/issues/121)).
-- Test harnesses and fixtures are exempt; web's `core/js/pages/test/` demo pages are
-  NOT (they ship).
-
-### Enforcement
-
-`scripts/log-tags.test.js` (runs in root `test:packages`) scans `packages/*/src` and
-`packages/web/core/js` for any log call whose message starts with a static bracket tag
-that is not `@omega.js/…` or the dry-run marker. It self-tests its own red path. New
-code uses the surface's shared logger — never a hand-written bracket prefix.
-
-## The file tee
-
-Nothing an OMEGA surface prints is terminal-only. ONE abstraction does it —
-`packages/devkit/src/attach-log-file.js`, vendored into every framework — and every
-surface attaches it at its entry point.
-
-- **Both sinks, always.** A chunk reaches the terminal exactly as written (colors
-  intact) and the file with ANSI escapes stripped, so `grep` and `tail -f` read clean.
-- **Synchronous fd writes.** A stream's buffer dies with the process, dropping exactly
-  the lines that describe a crash. The per-write syscall buys the crash tail.
-- **Truncate on attach.** A new launch clears the previous run's log — no history, no
-  rotation (the ruled retention, see below).
-- **Stackable.** `createTee()` returns an independent tee; an attach captures the
-  CURRENT writers, so tees nest and each detach restores exactly what it found (LIFO).
-  The default export is the process-wide singleton, which is what a CLI verb wants; two
-  attaches of different paths on the singleton stack the same way (a verb run inside
-  another verb's process), and its `detach()` pops the newest.
-- **`createChildLog()` for spawned children.** A child's stdout/stderr never pass
-  through this process' writers; the caller mirrors each buffer to the terminal —
-  which the verb's own tee then catches, making the verb log a SUPERSET of the child
-  file — and hands it to a child log, which adds the one thing the tee has no use for — a
-  mid-run `roll()`, requested by touching a reset sentinel, so a days-long emulator
-  log can be freshened without restarting it.
-- **CI is a no-op.** Under `CI=true` / `GITHUB_ACTIONS=true` the tee declines: the
-  runner captures its own output and no `logs/` is left in the workspace.
-- **A log it cannot open is a lost log, never a lost process.** The tee warns once and
-  the run continues untouched.
-
-## Where every log lives
-
-`<targetRoot>` is a target dir in a brand (`targets/web`, `targets/backend`, …);
-`<brandRoot>` is the brand monorepo root.
-
-| Surface | File | What's in it |
-|---|---|---|
-| **Per target** — every framework, same three names | | |
-| `omega dev` (web) · `omega serve` / `omega emulator` (backend) · `npm start` (desktop, extension) | `<targetRoot>/logs/dev.log` | the whole dev run: boot, ports, watcher rebuilds, the crash — plus every child chunk the verb mirrored (see below) |
-| `omega build` (web, backend) · production gulp build (desktop, extension) | `<targetRoot>/logs/build.log` | the whole production build |
-| `omega test` | `<targetRoot>/logs/test.log` | suite names, pass/fail, harness boot lines |
-| `omega deploy` (web, backend, extension, desktop) | `<targetRoot>/logs/deploy.log` | the whole deploy: the scaffold, the precheck and its refusals, the dispatch, then the followed run's job logs and its verdict ([#873](https://github.com/Omega-JS-Stack/omega/issues/873)) |
-| **Backend children** — firebase's own processes, beside firebase-tools' debug logs. The verb mirrors every child chunk to its own terminal, so the `logs/<verb>.log` above is a SUPERSET of these; a child file is the child-ONLY view (and the one that `roll()`s mid-run) | | |
-| the firebase emulator child | `<targetRoot>/dist/emulator.log` | emulator traffic: function invocations, Firestore/auth calls |
-| the `firebase serve` child | `<targetRoot>/dist/dev.log` | serve output; rolls on each reload |
-| the test runner child | `<targetRoot>/dist/test.log` | the runner's own output under `omega test` |
-| `omega deploy --direct` (the firebase child) | `<targetRoot>/dist/deploy.log` | the `firebase deploy` transcript (the verb's own record is `logs/deploy.log`, one row up) |
-| `omega logs` | `<targetRoot>/dist/production.log` | the Cloud Logging tail |
-| firebase-tools itself | `<targetRoot>/*-debug.log` | `firestore-debug.log`, `firebase-debug.log`, `ui-debug.log`, … — theirs, never swept by us |
-| **Desktop extras** | | |
-| the running app itself (main + preload + renderer converge) | `<targetRoot>/logs/runtime.log` (dev) · the OS log dir (packaged) | lifecycle, window and updater lines; kept across boots, rotating at 10 MB — `packages/desktop/docs/logging.md` |
-| `npx omega logs [runtime\|dev\|build\|test]` (desktop's own verb — read, not write) | tails whichever of the four `<targetRoot>/logs/` files was named, `runtime` by default | the print/follow/open surface for all of the above; backend's `omega logs` is a different verb (the Cloud Logging tail, one row up) |
-| `npm run release` (the same dispatch `omega deploy` delegates to) | `<targetRoot>/logs/deploy.log` | the GH Actions release run, streamed locally: one name for every target's deploy ([#873](https://github.com/Omega-JS-Stack/omega/issues/873)), where this was `logs/ci.log` |
-| Windows code-signing | `<targetRoot>/logs/signing.log` | JSONL signing events (local fallback; on CI it lands in the runner home) |
-| **Brand root** — every verb tees to its OWN `logs/<verb>.log` ([#623](https://github.com/Omega-JS-Stack/omega/issues/623)), so one verb never truncates another's record. A FAN-OUT log holds the walk's own verdict — its header, its loud skips, its summary — because `runCommand` spawns each target with stdio inherit, so a target's output goes past the tee into that target's own log above | | |
-| `omega manage` (the service walk) | `<brandRoot>/logs/manage.log` | the whole service walk |
-| `omega dev` (the fan-out) | `<brandRoot>/logs/dev.log` | the boot walk, then every dev leg's prefixed output (consecutive duplicate lines collapse to one `  (repeated N×)` note) |
-| `omega build` / `omega clean` (the fan-outs) | `<brandRoot>/logs/build.log` · `<brandRoot>/logs/clean.log` | the walk order, every loud skip, the per-target summary |
-| `omega deploy` (the fan-out) | `<brandRoot>/logs/deploy.log` | the delivery lane, then which target published in which order and the summary. Every target additionally keeps its own `<targetRoot>/logs/deploy.log` ([#873](https://github.com/Omega-JS-Stack/omega/issues/873)), and the backend its firebase transcript `targets/backend/dist/deploy.log` |
-| `omega update` (the fan-out) | `<brandRoot>/logs/update.log` | which target was checked and what it reported/applied |
-| `omega test` (the fan-out) | `<brandRoot>/logs/test.log` | which target ran which scope, and the aggregate verdict |
-| `omega pipeline` (the live full-cycle test) | `<brandRoot>/logs/pipeline.log` | the child invocation, the deploy/verify legs, the scorecard and the PASS/FAIL verdict |
-| the brand's cross-stack e2e (`@omega.js/devkit/test/e2e-harness`) | `<brandRoot>/test/e2e/.logs/` | `steps.log` (one `PASS` / `FAIL` per step — see below), `emulator.log`, `dev.log`, `page.log` |
-| **This monorepo** | | |
-| every root test lane (`npm test`, `npm run test:packages`, …) | `.temp/logs/<lane>.log` | the lane's own lines plus every child command's output — `test:packages` → `.temp/logs/test-packages.log` |
-| `npm start` (the watcher) | `.temp/logs/watch-all.log` | is it alive, did it respawn, what did it rebuild |
-| every e2e runner's per-step verdicts | `.temp/<lane>/steps.log` | one `PASS` / `FAIL` line per step — see below |
-| every e2e runner's environment | `.temp/<lane>/` | `emulator.log`, `page.log`, `sw.log`, `screenshots/`, the journey's numbered stage logs |
-
-The e2e lane dirs are `.temp/flows-e2e/`, `.temp/auth-token-e2e/`, `.temp/verts-e2e/`,
-`.temp/desktop-auth-e2e/`, `.temp/extension-auth-e2e/`, and `.temp/journey/`.
-
-### steps.log — which step failed
-
-Every e2e runner writes its verdicts incrementally
-(`packages/devkit/src/test/steps-log.js`, re-exported for the root runners as
-`scripts/steps-log.js`, and used by the journey harness and the brand e2e
-harness alike), so a SIGKILLed lane still names the step it died on:
-
-```
-PASS  the playground emulator boots (hosting :5002, auth :9099)
-FAIL  the popup reaches the background SW — timed out after 30s
-FAIL  preflight — a playground emulator stack is already running (hosting :5002)
-```
-
-`preflight` is the runner dying before or outside any step — the live-stack guard, a
-harness throw on the way up. One line, same shape, so one grep finds every failure:
-
-```bash
-grep '^FAIL' .temp/*/steps.log brands/*/e2e/.logs/steps.log
-```
-
-### Retention (ruled 2026-08-05)
-
-**Clear on launch, sweep what is stale.** Every log truncates when its surface starts;
-nothing rotates and no history is kept — the question a log answers is "what did the
-run that just happened do?". The backend additionally sweeps its own stale `dist/*.log`
-files and reset sentinels at every verb start, and deliberately leaves firebase-tools'
-`*-debug.log` files alone (a crashed run is diagnosed from them). `logs/` is gitignored
-everywhere, scaffolded brands included.
-
-### Grep the logs — do not re-run the process
-
-The whole point of the tee is that the answer is already on disk. A running dev server,
-emulator or watcher belongs to the user: never restart one, and never re-run a suite,
-just to see output.
-
-```bash
-tail -50 targets/web/logs/dev.log                # is the dev server up, what did it last build
-grep -i error targets/backend/dist/emulator.log  # what the emulator actually served
-grep '^FAIL' .temp/*/steps.log                # which e2e step broke
-tail -100 .temp/logs/test-packages.log        # what the last lane printed
-```

package/docs/shared/monitoring.md

@@ -1,167 +0,0 @@
-# Monitoring — the one error-reporting contract
-
-`@omega.js/monitoring` is the ONE home of error-reporting policy across every OMEGA target
-([#380](https://github.com/Omega-JS-Stack/omega/issues/380)). Private workspace package, CJS,
-vendored into the frameworks at prepare time — the same deal `@omega.js/analytics` gets.
-
-Before it, three surfaces each carried their own copy of "should we report, what release is this,
-what may we send": @omega.js/client's `modules/sentry.js`, @omega.js/backend's hand-rolled
-`Sentry.init`, and @omega.js/desktop's `lib/sentry/` split. They disagreed — on the release format,
-on whether an email rides, on whether a dev build reports. Now they share one core and each host
-supplies only what it alone can know.
-
-## The doctrine (Ian, 2026-08-20)
-
-- **Server and framework errors ALWAYS report.** Backend routes, cron, event triggers, desktop main,
-  extension background: our code, our fault, no filter.
-- **Client-side, only OUR framework code reports.** A web page shares its global with user-land
-  scripts, ad and chat widgets, and whatever browser extension a visitor installed. None of it is
-  ours to answer for, so a browser event reports only when an `@omega.js` bundle is on its stack.
-- **Capture lives at SEAMS**, never in scattered try/catch: process hooks, the route error handler
-  (`ctx.report()`), the event-trigger catch, the SDK's own global handlers.
-- **PII is scrubbed by default.** The uid rides (it is the join key to the account); the email is
-  OFF unless a config explicitly opts in.
-- **Everything is OFF when the DSN is unset** — and when it is off, the SDK is never `require()`d
-  or imported at all.
-
-## Config
-
-One block, `monitoring`, in omega.json5, with the monitor named as a KEY under `providers`
-([#425](https://github.com/Omega-JS-Stack/omega/issues/425) — the same shape every role uses). DSN
-presence IS the enable signal at runtime — there is no separate runtime `enabled` flag (the same
-convention every other role section follows: a block's credentials are its switch); the role-level
-`enabled: false` is the manager's skip switch for the provisioning service. Per-surface DSNs are
-`targets.<name>.monitoring.providers.sentry.dsn` overrides.
-
-```jsonc
-monitoring: {
-  enabled: true,                  // role-level, optional — false skips the monitoring service
-  providers: {
-    sentry: {                     // presence picks the monitor; no entry = none chosen
-      org:              'acme',   // provisioning only (the manager's monitoring service writes it)
-      dsn:              'https://…@o1.ingest.sentry.io/1',
-      environment:      null,     // null = the host's gate names it ('production' / 'development')
-      sampleRate:       1,        // error events kept, 0..1 — the sampling knob
-      tracesSampleRate: 0.1,
-      replaysSessionSampleRate: 0,  // browser only — session replay is opt-IN (0 = off, and off is the default)
-      replaysOnErrorSampleRate: 0,  // browser only — replay of an ERRORING session; either rate above 0 loads the integration
-      scrubEmail:       true,     // set false to opt IN to sending emails
-      attachScreenshot: false,    // desktop only
-      bundlePatterns:   ['/assets/js/'],  // browser only — the URLs that identify our bundles
-    },
-  },
-}
-```
-
-Full schema: [config.md](config.md).
-
-## The entries
-
-| Entry | Who requires it | What it does |
-|---|---|---|
-| `./core` | everything | Pure policy: config resolution, release tag, user scrub, the bundle filter. No `process`, no SDK, no DOM — it is safe inside a page bundle. |
-| `./env` | Node/Electron hosts | The `process.env` half of core's gate seam: the four switches below. |
-| `./node` | `@omega.js/backend` | Boots `@sentry/node` and hands the module back (or `null`). |
-| `./browser` | `@omega.js/client` | Builds the `@sentry/browser` init options — integrations plus the ONE `beforeSend` that decides what leaves a page. |
-| `./main` `./renderer` `./preload` | `@omega.js/desktop` | The `@sentry/electron` per-context wrappers. |
-| `.` | `@omega.js/desktop` | The Electron context delegator: `process.type === 'renderer'` picks the renderer module, anything else the main one. |
-
-Core is pure ON PURPOSE. The browser bundle imports it, so an env read there would be a
-ReferenceError on a live page — every environment signal is passed IN as a gate, and `env.js` is
-where the reads live for hosts that have a process. A package test pins this.
-
-## The switches
-
-In the order they win:
-
-| Env var | Effect |
-|---|---|
-| `OMEGA_SENTRY_ENABLED=false` | Kill switch. Nothing reports, ever. |
-| `OMEGA_TEST_RUNNER` | A test run never pollutes a live project. |
-| `OMEGA_SENTRY_FORCE=true` | Report from a non-production run (local proving). |
-| the ONE environment | The default production signal, for a host that passes no runtime one. |
-
-The production signal is the host's to supply, and the DEFAULT is the one environment every OMEGA
-target answers from ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)):
-`@omega.js/config/environment`'s `isProduction()`, read off the host the gates were asked for
-(`process.env.OMEGA_ENVIRONMENT` on Node, the host's baked `config.environment` in a browser-ish
-context such as a renderer bundle). `OMEGA_BUILD_MODE` used to be that default, which made it a
-FIFTH production signal with an opinion of its own: a build-mode run of a development artifact
-reported as production, and a packaged production app whose lane did not carry the flag reported as
-development. @omega.js/backend still passes its own answer in (`omega.isProduction()`, env-derived
-and stable for the life of the process), alongside its own `reportErrorsInDev` option, and a boolean
-a host supplies always wins. A context that names no environment at all throws by name, the same way
-every other read of the one environment does.
-
-## Release tags
-
-**ONE format on every target (Ian, 2026-08-20): `<brand.id>@<version>`.** A Sentry release is only
-comparable across the backend, the desktop app and the browser bundles when all three spell it the
-same way, so `core.releaseTag({ id, version })` builds that shape and nothing else — miss either
-half and there is NO tag (a bare version is not a second format). `brand.id` is required config, so
-a missing id is a config hole, not a supported case.
-
-Each host supplies its own version identity:
-
-| Host | Version source |
-|---|---|
-| `@omega.js/backend` | the functions package version. The id is `brand.id`, falling back to the project id on a config missing one (which already warns at boot). |
-| `@omega.js/desktop` (main + renderer) | `app.getVersion()` — the packaged app version, with `brand.id` read off the resolved config |
-| `@omega.js/client` in `@omega.js/extension` | the extension target's package version, baked into the build blob as `config.version` |
-| `@omega.js/client` in `@omega.js/web` | the website target's package version, read off the target root's package.json and baked into the page's `OMEGA_BUILD_JSON.config` as `version` |
-| `@omega.js/client` in the `@omega.js/desktop` renderer | the desktop target's package version, folded into `OMEGA_BUILD_JSON.config` at bake time (the renderer only ever sees `buildJson.config`) |
-
-The client reads `config.version` and falls back to `config.buildTime`. Every host above bakes a
-version now, so the fallback covers only a blob that carries none — a surface embedding the client
-by hand. Nothing tags a build stamp by design.
-
-## Where capture happens
-
-| Surface | Seam |
-|---|---|
-| Backend routes | `ctx.report()`: 5xx captures automatically, 4xx never ([backend guide](../backend/index.md)) |
-| Backend event triggers | `omega/events.js`: a handler that throws, or a handler file that will not load, goes through the SAME `report()` door. A deliberate block (an `HttpsError`, or an explicit numeric 4xx code) is the trigger's 4xx and never captures; a string `.code` (`ENOENT`, `messaging/invalid-token`) is a system error, not a block, and reports. |
-| Backend payment webhooks | the REFUSAL family's shared seam (`acknowledgeRefusal()` in `events/firestore/payments-webhooks/on-write.js`) captures ONE `warning` per refused event, tagged with the reason and the provider. A refusal is a decision, not a fault, so it never reports as an exception; a processed event reports nothing; and only IDS ride — the refusal stamp's own fields plus the event's ([#550](https://github.com/Omega-JS-Stack/omega/issues/550)). |
-| Desktop main | `@sentry/electron/main`'s own `OnUncaughtException` + `onUnhandledRejection` integrations. Desktop's process handlers log to `runtime.log` and are ADDITIVE — never a second capture. |
-| Desktop renderer | the SDK's window `error` / `unhandledrejection` handlers |
-| Browser (web, extension) | the SDK's global handlers, filtered by `beforeSend` to our bundles |
-
-## The browser filter
-
-`core.createBundleFilter(patterns)` checks every stack-frame filename an event carries against the
-configured URL fragments. Default: `/assets/js/`, which is where both @omega.js/web and
-@omega.js/extension serve every framework bundle (the client runtime included).
-
-An event with **no matching frame is dropped**, and that includes an event with no frames at all — a
-cross-origin `Script error.` is exactly the third-party noise this exists to kill. Deliberate
-`omega.sentry.captureException(…)` calls are unaffected: they are thrown from page bundles, which
-ARE our bundles. The corollary: a deliberate capture must pass an Error CONSTRUCTED in framework
-code — hand it a frameless one (a bare cross-browser `fetch` TypeError, say, which some engines
-raise with no usable stack) and the filter drops it, by design.
-
-What survives the filter is scrubbed of credential-bearing auth params: `browser.scrubAuthParams()`
-strips `?authPrivateKey` and `?authCustomToken` from every navigation breadcrumb (`data.from`/`data.to`,
-which the SDK records around `history.replaceState` — including the strip that removes the key) and
-from `event.request.url` (which `httpContext` attaches at capture time). A module constant, not
-config: a page never opts its own credentials back into an event ([#661](https://github.com/Omega-JS-Stack/omega/issues/661)).
-
-## How the config reaches a browser
-
-The client reads a `sentry: { enabled, config }` namespace on its init blob, and it maps that
-namespace from `monitoring.providers.sentry` ITSELF, once, for every framework
-([#894](https://github.com/Omega-JS-Stack/omega/issues/894)): each browser surface bakes the
-canonical section into `OMEGA_BUILD_JSON.config` and `_canonicalConfiguration()` in
-`packages/client/src/index.js` turns a DSN's presence into the switch. That home outranks a
-stale `client.sentry` blob, which keeps reporting until a brand migrates
-([#485](https://github.com/Omega-JS-Stack/omega/issues/485)); with no canonical DSN the off
-state rides first, so the legacy blob still decides.
-
-| Framework | Where the section is baked |
-|---|---|
-| `@omega.js/web` | the engine's per-build snapshot, written as `<outDir>/build.js` (#743) |
-| `@omega.js/extension` | `src/gulp/tasks/bundle.js` (`composeBuildJson`, written as `dist/build.js`) |
-| `@omega.js/desktop` | `src/gulp/tasks/bundle.js` (`composeClientBuildJson`, written as `dist/build.js` for the renderer) |
-
-The client's `sentry.config` is the PROVIDER block, flat — nothing role-level ever rides into
-`Sentry.init`. Node/Electron hosts pass the whole `monitoring` section instead and core's
-`providerOptions()` reaches in for them: one home for the nesting, on the runtime side.

package/docs/shared/publishing.md

@@ -1,187 +0,0 @@
-# Publishing — the runbook
-
-> The publish-proving checkpoint's script, run for real on 2026-09-09: the seven
-> publishables are on the registry ([#25](https://github.com/Omega-JS-Stack/omega/issues/25)) at 0.50.0, the
-> monorepo's own number (0.1.0 went out first that night and is deprecated: the family
-> carries ONE version, the root package.json's, by ruling 2026-09-10),
-> each with `publishConfig.access: public`, and published is the new normal. The unlatch
-> step below is history; versions move by changesets from here.
-
-## What publishes, what never does
-
-| Publishes (seven) | Never publishes (vendored at prepare, six) |
-|---|---|
-| `@omega.js/backend`, `@omega.js/client`, `@omega.js/desktop`, `@omega.js/extension`, `@omega.js/manager`, `@omega.js/mcp-router`, `@omega.js/web` | `@omega.js/devkit`, `@omega.js/config`, `@omega.js/account`, `@omega.js/template-kit`, `@omega.js/analytics`, `@omega.js/monitoring` |
-
-The private six are `VENDORABLE_PACKAGES` in [packages/devkit/tools/vendor.js](../../packages/devkit/tools/vendor.js),
-which is the SSOT: the vendor tool throws on a dist reference to any `@omega.js`
-package not on that list, so read the count from there rather than from this page.
-
-`@omega.js/mcp-router` joined the set (Ian 2026-07-30, [#144](https://github.com/Omega-JS-Stack/omega/issues/144)):
-the manager's vendored Claude plugin declares the router, so the router has to be
-installable beside it — a real dependency, never vendored. It ships no docs tree
-(it is not in the vendor lane's `DOCUMENTED_PACKAGES`) and no `exports` map, so the
-plugin's launcher can deep-resolve `@omega.js/mcp-router/bin/mcp-router.js`.
-
-Registry-real internal ranges (everything else is workspace `*`): `@omega.js/client`
-in backend/web/desktop/extension; `@omega.js/backend` and `@omega.js/mcp-router` in
-manager — the EXACT family version (0.50.0 today), not carets, because the family is
-lockstep (below).
-
-## Lockstep — the family ships ONE version ([#794](https://github.com/Omega-JS-Stack/omega/issues/794))
-
-Changesets carries the seven publishables as a single `fixed` group
-(`.changeset/config.json`; `scripts/changeset-config.test.js` holds that group
-and `release-check.js`'s `PUBLISHABLES` in parity, and release-check itself
-prints a `one version across the family` check). A bump on any one bumps all
-seven to the same number, and packages with no code change republish anyway.
-
-Why, in two sentences: ONE number for the family means a brand can never
-install a backend from one release beside a client from another — "everything
-is 0.5.x" is the whole compatibility contract, readable by a human and
-checkable in one comparison. The private internals are VENDORED copies inside
-each framework, so a config-schema change already forces every framework to
-republish; independent numbers only hid that, and let one omega.json5 be
-validated by two validators.
-
-`updateInternalDependencies` stays `patch`, so the exact ranges above move
-with the group on every release. In a brand, the same number lands as an exact
-PIN per target ([updates.md](updates.md)) and the manager's boot check refuses
-a brand that ever drifts ([../manager/brand.md](../manager/brand.md)).
-
-## What prepare vendors into a tarball
-
-Every publishable's prepare `after` hook runs the devkit vendor lane, which
-ships two payloads: the private packages' MODULES into `dist/vendor/`
-(`tools/vendor.js`), and the DOCS into the package root (`tools/vendor-docs.js`
-— the package's guide as `docs/index.md` plus `docs/shared/`, and for
-`@omega.js/manager` also the repo-root map as `docs/AGENTS.md` (links
-retargeted) and `claude-plugin/` + `.claude-plugin/marketplace.json`, the
-plugin a consumer brand enables from its node_modules, `.mcp.json` included —
-its launcher resolves `@omega.js/mcp-router` from the install
-([#144](https://github.com/Omega-JS-Stack/omega/issues/144))). All of it is
-generated and gitignored; `node --test scripts/vendor-docs.test.js` packs the
-six documented packages for real and asserts the tarball listings. A vendor
-failure ABORTS the prepare: every publishable sets `preparePackage.hooks.afterBlocking: true`
-(prepare-package 2.2.0, [#38](https://github.com/Omega-JS-Stack/omega/issues/38)),
-so a tarball can never build missing its vendored internals. Contract:
-[agent-docs.md](agent-docs.md).
-
-The MODULE payload is closed over itself ([#739](https://github.com/Omega-JS-Stack/omega/issues/739)): a vendored file's own cross-package requires are rewritten to the sibling vendored copy, and any vendorable only a vendored file needs is vendored too, so the raw-private-reference grep below reads `dist/vendor/` as strictly as the rest of the tree.
-
-## The license check ([#320](https://github.com/Omega-JS-Stack/omega/issues/320))
-
-A published install needs a LICENSE to enable the payment system and remove the omega
-attribution. A license is a subscription bought on omegajs.dev and the key is that
-account's API key — `OMEGA_LICENSE_KEY` in the brand `.env`, never in omega.json5
-(secret-shape rule). One key per ACCOUNT, unlimited brands for now.
-
-**When it runs**: at DEPLOY time, per target, once — `resolveLicenseVerdict({ config, env, transport })`
-in [`@omega.js/devkit/license`](../../packages/devkit/src/license.js). Each target's
-deploy asks and bakes the answer into that artifact; runtime never phones home and the
-payment call stays pure, so a cancelled key holds until the next deploy (accepted — a
-boot or periodic re-check is additive later).
-
-| Verdict | When | `payments` | `attribution` |
-|---|---|---|---|
-| licensed | the key resolves an omegajs.dev account whose subscription plan is not the reserved `basic` free sentinel | `live` | `removed` |
-| keyless | no key, an empty key, a `demo-*` project, or a key whose account has no active subscription | `gated` | `shown` |
-
-**Loud failure**: a key IS present but the server is unreachable, answers non-2xx, or
-resolves no account → the resolver THROWS. A typo'd or dead key must never quietly ship a
-gated artifact for a brand that is paying.
-
-**The keyless-dev carve-out**: a `demo-*` (emulator-only) project short-circuits before
-the network call, key present or not — local dev and the test brands run keyless forever,
-payments in test mode, attribution shown.
-
-**The wire**: `GET https://api.omegajs.dev/omega/user?apiKey=<key>&brandId=<brand.id>`.
-The host is a CONSTANT, not config: every other api base in OMEGA derives from a brand's
-own `brand.url` (`api.<host>`) because it belongs to that brand, and this one is the
-PRODUCT's license server — the same host for every brand that installs OMEGA. Server side
-it is the ordinary `GET /user` route resolving an API key (`users` where
-`api.privateKey ==` it), and the plan comes from `@omega.js/account`'s
-`resolveSubscription`, the same derivation the backend and the client run. `brandId` rides
-along and the server ignores it today, so a future per-key brand limit is a server-side
-change alone. `transport` is the injected fetch, so the tests run fully offline.
-
-**Delivery**: the env schema declares `OMEGA_LICENSE_KEY` as `ci` for web, desktop and
-extension — their deploys build on Actions runners, so the check runs where the build runs
-— and declares NOTHING for the backend, which deploys straight from the CLI and reads the
-key out of the `.env` cascade in its own process. It never bakes: a baked license key is a
-license key anyone who unpacks the app can copy.
-
-**What each target does with the verdict**: the resolver's answer becomes ONE stamp —
-`resolveLicenseStamp({ config, production })` in the same module, which returns
-`{ status: 'licensed'|'keyless', payments, attribution }` and short-circuits to the keyless
-stamp for any build that is not a production one (so a dev build, a watch and a test never
-phone home).
-
-| Target | Where the check runs | What the artifact carries | What changes |
-|---|---|---|---|
-| web | `omega build` (the production build — on the runner for a deploy, locally for a local one) | `site.license`, a build fact beside `site.pricing`/`site.brandTokens` | the footer's "Powered by omegajs.dev" block renders only while `site.license.attribution == 'shown'` (themes/base `_includes/frontend/sections/footer.html`) |
-| backend | `omega deploy`, before the stage — the CLI reads the key from the .env cascade in its own process | `OMEGA_LICENSE_STATUS` in the composed `dist/.env` (the one COMPUTED key there; the KEY itself never rides the upload) | `libraries/payment/license.js` refuses Stripe/PayPal/Chargebee `init()` on `keyless`. The `test` provider is never gated, and an ABSENT status — every local lane, the emulator, a test — behaves exactly as before |
-| desktop | the bundle task, production builds only | `OMEGA_BUILD_JSON.license` (outside `config`, in the bundles' define and in the renderer's `dist/build.js`) | nothing at runtime: the artifact records what it was packaged as. Neither target has an attribution surface today, and their payments ride the backend's gate |
-| extension | the bundle task, production builds only (once per build: the one snapshot every browser target then copies) | `OMEGA_BUILD_JSON.license` in the artifact's `build.js`, likewise outside `config` | as desktop |
-
-**Honesty system** (spec call 6): plain readable checks, no obfuscation and no artifact
-signing. The legal backing is the Elastic License 2.0 below, whose terms forbid
-circumventing license-key functionality and removing notices.
-
-## Pre-flight (any day, no GO needed)
-
-1. `npm run release:check` — packs all seven through their real prepare (vendoring
-   included), scratch-installs each tarball with local-tarball overrides, resolves,
-   and greps the shipped trees for raw private references. **Must be 7/7 green.**
-   This is the laptop mirror of CI's pack-smoke.
-2. Full battery green: root `npm test` (packages → corpus → sandbox e2e → journey).
-3. npm auth sanity: `npm whoami` (expected `itwcw2000`). Known parked mystery: `npm org ls omega.js`
-   403s on the empty org — the first real publish is the definitive test. If IT 403s,
-   the org-owning account must grant publish rights for the `@omega.js` scope.
-4. **License check** ([#349](https://github.com/Omega-JS-Stack/omega/issues/349)): every
-   `packages/*/package.json` reads `"license": "Elastic-2.0"`, every publishable carries a
-   root `LICENSE` naming the Elastic License 2.0 (npm ships it into the tarball regardless
-   of `files`), and no MIT text survives anywhere:
-   `grep -rL "Elastic License 2.0" packages/*/LICENSE` must print nothing and
-   `grep -ril "MIT License" packages/ --include=LICENSE*` must be empty. A tarball that
-   publishes under the wrong license cannot be recalled from the registry, so this runs
-   before the unlatch, not after.
-
-## Publish day (Ian's GO)
-
-1. **Unlatch**: remove `"private": true` from the seven publishables' package.json,
-   and ONLY those seven (the six vendorable privates keep theirs forever:
-   `VENDORABLE_PACKAGES` in [packages/devkit/tools/vendor.js](../../packages/devkit/tools/vendor.js)
-   names them, so the list is never re-typed here).
-2. **Publish** each (changesets is configured lockstep + `access: public`, so the
-   seven go out at ONE number; the direct form per package is equally fine):
-   `npm publish --workspace=packages/<name>` — order matters only where a dependent
-   waits on a dependency: **client and backend before their dependents**
-   (web/desktop/extension need client on the registry; manager needs backend and
-   mcp-router). Safe order: client → backend → mcp-router → extension → desktop →
-   web → manager.
-3. **Verify from the outside**: in an empty temp dir, `npm install @omega.js/web`
-   (and one more, e.g. manager) — install + `require.resolve` must succeed with no
-   overrides. That is the moment the untested-lane risk is retired.
-4. **Flip the real brand (omega-omega) to registry specs**: from any TARGET root (`targets/web`;
-   the manager has no `i` verb), `npx omega i live` — tree-wide `file:` → the EXACT
-   family pin + one registry install (`restoreRegistrySpecs` writes the linked copy's version with no
-   caret, because the family is lockstep; `omega i local` is the way back for
-   local-era work). Commit the brand's manifest+lock change.
-5. **Brand proof**: brand `npm run manage` (manage cycle) + a website build — the brand
-   now runs on registry packages; CI-dispatch web deploys become buildable (the
-   deploy guard stops refusing once no `file:` specs remain).
-6. Record: CHANGELOG entry + close the tracking issue; re-latch nothing — published is the
-   new normal, versions move by changesets from here.
-
-## After the first publish
-
-- 0.x caret ranges float patch-only (npm's conservative 0.x behavior) — breaking
-  changes bump minor and consumers move deliberately. A BRAND floats nothing: the
-  manager pins every target exactly, so `omega update` is the one thing that moves
-  a brand, and it moves the whole family ([updates.md](updates.md)).
-- **1.0.0 is NEVER published without Ian's explicit word** (ruling 2026-09-10): it is the
-  official release, and it waits until OMEGA has survived on its own with Ian's brands.
-  Every number below it is free to publish whenever he wants.
-- The publish is also the brand-CI-build unlock: no tarball vendoring exists by
-  design — the registry is the lane CI installs from.

package/docs/shared/rulings.md

@@ -1,34 +0,0 @@
-# Standing rulings
-
-Ian's durable rulings, migrated verbatim from PROGRESS.md's Rulings lane when the board retired (v4 migration, 2026-07-27). These bind all work in this monorepo; new rulings land here (or in AGENTS.md when they are architecture). Per-item decisions live on their issues.
-
-- Ian 2026-09-09: same-name rule for global + specific values: wherever a site-wide default and a specific override describe the same thing (config default vs page frontmatter, brand vs target, company vs brand, shared vs instance), they share ONE name and ONE shape at every level, the specific level overrides, and a differently named pair is a defect (`seo.index` vs `meta.index` was the case; #564 folds it into `meta.index`). Applies to every config item, never only page-vs-site.
-- Ian 2026-07-21: adblock-safe naming — the ad system speaks vert EVERYWHERE (paths, DOM, collection, API, modules); only ads.txt, Google's own ad* tokens, `advertising` config key say ad
-- Ian 2026-07-21: "DO NOT USE EM DASHES… REWRITE EVERYTHING TO MAKE SENSE WITHUT IT" — site/brand copy never uses em dashes; manual rewrites, not deletions. Operating home with scope + exemptions: docs/shared/theming.md § Copy register (2026-08-15)
-- Ian 2026-07-10: continuous mode — iterate/build/test autonomously, checkpoint after checkpoint; stop only for serious errors or genuinely-Ian decisions
-- Ian 2026-07-19: "I refuse to run a single command — wrap it in npm start, self healing idempotent" — absorb, never hand back; blocked one-offs = framework gaps; wrapped verbs only
-- Ian 2026-07-20: mirrored-implementation rule — same feature, same shape, every framework (cp242 deploys enforced it)
-- Ian 2026-07-20: local-omega-in-production is a SUPPORTED feature — deploys auto-detect linked local frameworks and take local-artifact lanes
-- Ian 2026-07-18: "still use local … until we are fully locked on all decisions that may result in breaking changes" — the local era (file: specs) holds until then
-- Ian 2026-07-19: 0.x until live publishes are proven; 1.0.0 is a later deliberate graduation; zero npm publishes + zero GH releases until GO (old names ship from legacy repos)
-- Ian 2026-07-12: website target = GH Pages ALWAYS; Firebase hosting is the backend/api surface only; GH Pages DNS defaults correct as-is
-- Ian 2026-07-12: FA Pro = local folder route via OMEGA_FONTAWESOME_ROOT (no npm token); skins design within solid/regular/brands
-- Ian 2026-07-11/12: playground = live test infra (Blaze/break/delete); payment+adjacent gated; deploys sparing + named; other brands deploy ONLY on explicit ask
-- Ian 2026-07-13/14: ad-hoc writes to real ITW resources stay gated — manage services' own convergence paths are the sanctioned route (2b mints included)
-- Ian 2026-07-18: credential copies from existing ITW brands SANCTIONED (brand .envs + omega-manager/.brands); new brands mint fresh identity keys; classifier-blocked copies fall to Ian
-- Ian 2026-07-12 (final): NO ITW CLI login — cached browser-OAuth + normal CLI login cover all; never suggest firebase/gcloud login as ITW; npm start = the blessed form *(command superseded 2026-08-13 by [#227](https://github.com/Omega-JS-Stack/omega/issues/227): the blessed reconcile form is now `npm run manage`; `npm start` boots the dev stack)*
-- Ian 2026-07-10: data-shape preservation — Firestore shapes + route semantics presumed good; breaking changes needing migration = flag with plan, don't build
-- Ian 2026-07-06: no backwards compat (dual-read cancelled) — new way only
-- Ian 2026-07-09: legacy repos READ-ONLY (omega-manager, all framework + consumer repos); migrators/verifiers/B5 verify/audit port PINNED; MAM parked
-- Ian 2026-07-20: per-target docs retire in brand context — the brand root is the ONE home (AGENTS.md chain + one README/docs/CHANGELOG)
-- Standing: secrets never in omega.json5 (.env only; config hard-fails); npu never raw npm/npx; explicit `git -C`; commit-and-continue; de-ITW to config = standard scope
-- Standing: checkpoint discipline — survey → design → implement → tests → sandbox/fixture proof → docs → commit; live checks never touch real ITW resources outside sanctioned paths
-- Ian 2026-07-30: uniformity — commands/surfaces of the same TYPE act the SAME; no split defaults within one family (the CLI read/write emulator split was the offense: every backend CLI subcommand now defaults to the emulator, `--production` the only path to live)
-- Ian 2026-07-30: NO legacy accommodations in the new system — no code path accepting a superseded form; breaking changes get DOCUMENTED (register: #148) and migrated once, manually (playbook: #149); the config-convert input lane is the one sanctioned legacy-reading exception
-- Ian 2026-07-30: company membership is a POINTER, never the directory tree: brands never physically nest inside a company folder, and anything resolving the company follows the pointer (SUPERSEDED in mechanism by #677, 2026-09-12: the pointer is the config key `company: { id }`, resolved through the machine registry, and the `.omega/company.json` stamp is retired; the rule itself stands)
-- Ian 2026-08-06: harmonize at BUILD time, never in a later pass — when a mechanism lands in one framework, its shared home (devkit) and the mirroring evaluation happen in the same work item; "wait for the harmonization pass" is not an accepted answer (first application: the #200 captured-read helper lifted to devkit pre-ship)
-- Ian 2026-08-20: migrations converge by SHAPE, not by version steps — each fix detects its legacy pattern in the doc itself, converged docs are proven no-ops, still-invalid docs surface loudly in the audit; every future doc reshape adds its convergent fix to the migrations pipeline in the SAME work item (register: docs/shared/breaking-changes.md)
-- Ian 2026-08-20: writing real data is OPT-IN for one-off scripts/processes — any standalone script that mutates live data (Firestore docs, mailing lists, provider accounts) previews by default and writes only under an explicit `--execute`; the manage/reconciliation services (own `--dry-run` + convergence) and scripts that only write tracked files (git diff is the review) are out of scope; template: the migrations service (#394)
-
-- Ian 2026-09-03: `--target=<name>[,<name>]` is the ONE target picker on every brand-root fan-out verb (test, deploy, build, clean, dev, update); `--only`/`--except` are retired, not aliased: `--only` collided with Firebase's own `firebase deploy --only hosting` (register: https://github.com/Omega-JS-Stack/omega/issues/780)
-- Ian 2026-09-03: an ORPHANED process of the emulator family (parent gone, this user's uid, a strict command-shape match) is NOBODY's and every emulator boot reaps it, whatever project it names, with no config and no warning-only mode. The family's shapes are named once, where the reap is described: [backend/index.md](../backend/index.md). Supersedes the #293 line that another brand's orphans stay; the #293 lesson survives as the strict family match replacing the loose name regex (register: https://github.com/Omega-JS-Stack/omega/issues/781)