@omega.js/extension 0.1.0

package/docs/shared/local-dev.md

@@ -0,0 +1,147 @@
+# Local dev loop (master plan §8)
+
+How to work on the frameworks and see edits live in consumers — one repo, one window, one command. The mechanics live in **`@omega.js/devkit/local`** (`packages/devkit/src/local.js`), the single home for monorepo resolution, brand/app detection, file:-linking, and the watch lock.
+
+## Root watch: `npm start`
+
+`npm start` at the monorepo root runs `scripts/watch-all.js`, which starts every package's `prepare:watch` (src→dist rebuild-on-change) **concurrently**, with per-package output prefixes:
+
+```
+Watching 4 packages (src→dist): backend, client, desktop, extension
+[client   ] [02:25:05] 'prepare-package': Ready for changes!
+```
+
+- **Discovery, not hardcoding**: any `packages/*` with a `prepare:watch` script is watched. Packages without one (`account`, `analytics`, `config`, `devkit`, `mcp-router`, `monitoring`, `template-kit`) serve `src/` directly — file:-linked consumers see those edits live with no watch at all.
+- **Vendor propagation**: a per-package `prepare:watch` only sees its OWN src, but the vendorable shared packages (`devkit`, `config`, `account`, `template-kit`, `analytics`, `monitoring` — `VENDORABLE_PACKAGES` in `packages/devkit/tools/vendor.js` is the list) also live as copies inside every framework's `dist/vendor/*`. The orchestrator watches those srcs too (`startVendorPropagation`) and re-runs `npm run prepare` in every watchable package on change — debounced, coalescing, one failure never stops the pass. Without it, a devkit edit strands dist-running frameworks on stale vendored code until a manual rebuild (the cp184 `http://localhost:5002` no-redirect bug). Running processes still need a restart to load the fresh dist, same as any src edit.
+- **Single-instance**: the orchestrator takes `.omega/dev-watch.lock` (pid inside). A second `npm start` — or an `omega dev --local` session — sees the live lock and exits cleanly instead of double-watching. Stale locks (dead pid) are swept automatically.
+- **Shutdown**: SIGINT/SIGTERM kills every watch child and releases the lock. A watch child dying on its own is announced loudly; the others stay up.
+- **Its log**: the whole watcher — its own lines and every child watch's prefixed output — tees to `.temp/logs/watch-all.log`, truncated per launch (attached AFTER the lock, so a losing second instance never wipes the live one's log). "Is it alive, did it respawn, what did it rebuild" is a `grep`, never a restart ([logging.md](logging.md)).
+
+## Brand-root one command: `omega dev` (web + backend together)
+
+At a **brand root** (the dir with `config/omega.json5`), every framework's `omega` bin dispatches to `@omega.js/manager` — whose `dev` command boots the whole local stack at once (`npm start` is the packaged form, `npm run dev` its alias — the manage cycle is `npm run manage`, i.e. `omega manage`; a bare `omega` prints help and runs nothing, [#229](https://github.com/Omega-JS-Stack/omega/issues/229)):
+
+```
+omega dev                      # website dev server + backend FULL emulator suite
+omega dev --target=web         # one leg
+omega dev --target=web,backend # explicit set
+omega dev --all                # every target with a dev leg (desktop/extension opt-in)
+omega dev --full               # boot on the WHOLE manage walk, not just the boot lane
+```
+
+- **Boot opens with ONE freshness sweep, before anything spawns** ([#340](https://github.com/Omega-JS-Stack/omega/issues/340)): `omega dev` checks every selected lane's framework closure itself (devkit's `freshnessSweep`, deps-first, one check per package dir), so a heal — `npm run prepare`, which PURGES dist before recopying — happens once, with no sibling lane mid-`require('../dist/…')` through it. Each leg still checks itself at CLI boot; swept first, that check is a no-op. A stale MONOREPO-linked dist stops the boot here instead of taking a leg down later.
+- **Boot opens with a manage cycle** ([#44](https://github.com/Omega-JS-Stack/omega/issues/44)): before any leg spawns, `omega dev` reconciles the brand — its boot lane, below — so brand-level sources reach the targets instead of sitting stale (see the redistribution contract below). Errors in that cycle stop the boot loudly; nothing serves on top of a broken brand.
+- **The boot walks the LOCAL lane, in about a second** ([#228](https://github.com/Omega-JS-Stack/omega/issues/228)): `workspace` (structure + config health), `assets` (derived logo/icon variants) and `disperse` (signing artifacts) — the file work the dev legs actually consume. It is the DELIVERY lane, not a boot-only one ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)): a brand-root `omega deploy` runs the same `BOOT_SERVICES` walk before it fans out, so brand inputs reach the targets on both triggers from one list. Cloud reconciliation and the rebuild lane (cloud, campaigns, payment, update, account, …) cost a minute-plus and reach no dev leg, so they belong to `npm run manage` — or `omega dev --full`, which boots on the whole walk. A service is manage-lane unless `BOOT_SERVICES` names it, so nothing new can slow a boot by accident. The boot still prints the preflight walkthrough for the FULL setup (it is local and instant), then one line pointing at `npm run manage`.
+- **The boot cycle never waits on a human** ([#228](https://github.com/Omega-JS-Stack/omega/issues/228)): it runs non-interactive, so any step that needs a person — a console confirm, a consent flow, a secret paste — steps aside into the run summary's ⚑ pending list, each item naming its `npm run manage -- --service=<name>` rerun. The dev legs boot regardless of what is pending; only real errors (broken config, an unloadable brand) stop the boot. A never-setup brand and a fully setup one behave identically here — the difference shows up as a longer pending list, not as a stalled terminal. A dead Google grant is pending too, not an error: the service warns into the same list and the walk carries on. One consequence on a `--full` boot: its web build uses the committed translation cache only (`--cached-only`, the same determinism law the pipeline and deploys follow), so new strings translate on the next interactive manage or build.
+- **Default set = `web` + `backend`** — the local web loop. GUI/watcher targets (desktop opens an Electron window; extension runs a build watcher) never boot unless named via `--target=`/`--all` ([#780](https://github.com/Omega-JS-Stack/omega/issues/780)). The default also adapts: a web-only brand boots just web, no warning.
+- **Legs**: web → the target's `npm start` (`omega dev`, :4000); backend → `npm run emulator` (auth/firestore/functions/database/hosting + seeded personas). Backend boots first so its port map is published before web reads it, and the order is optional either way ([#346](https://github.com/Omega-JS-Stack/omega/issues/346)): the web dev server rewrites each page's port map into the response as it serves it, so a backend that publishes later reaches the browser on the next request instead of never.
+- **Multi-instance web ports offset deterministically**: each instance wants the classic base + its position in the `targets.web` instances array (targets/website → :4000, targets/website-admin → :4001), so instances dev side-by-side from their own target dirs; the N7 allocator still bumps if the offset port happens to be taken, and pins (`--port` / config `ports.website`) win verbatim. Single-object brands stay on :4000 exactly as before.
+- **Per-target Node**: each leg spawns under its target's own `.nvmrc` major (web and backend pin different ones).
+- **A leg targets the `https` port, never `hosting`** ([#795](https://github.com/Omega-JS-Stack/omega/issues/795)): the ports file publishes both, and only `https` is the public origin under the local certificate; `hosting` is the internal plain-http port the mkcert proxy forwards to, so a consumer process aimed there is talking to the proxy's back door instead of the address every other surface uses. Every leg `omega dev` spawns carries `NODE_EXTRA_CA_CERTS=<mkcert -CAROOT>/rootCA.pem` (a shell-set value wins verbatim; a host without mkcert gets no key at all), so a brand's own Node process VERIFIES that certificate rather than dying on it. A leg that never speaks TLS ignores the variable, and since this is verification and not a bypass, Node prints no warning. The emulator's and `omega serve`'s own children take the same variable in place of the old `NODE_TLS_REJECT_UNAUTHORIZED=0`, whose boot warning is gone with it; that bypass survives in exactly one place, a host whose mkcert root vanished under certificates already on disk.
+- **One terminal covers FRAMEWORK edits too** ([#587](https://github.com/Omega-JS-Stack/omega/issues/587)): when the brand's `@omega.js/*` deps RESOLVE into a monorepo checkout, the boot starts that monorepo's watch as a session child — no flag, no second terminal, so editing a framework's `src/` rebuilds its `dist/` while the stack runs. Resolution answers the question, never the manifest (a `file:` spec can be stale, and workspace hoisting puts the copy at the brand root): `resolveLinkedMonorepo(brandRoot)`. Lock-aware — a watch already running (root `npm start`, or another brand's session) is REUSED, never doubled — session-scoped, so it dies with the stack, and its output rides the `[watch]` tag into `logs/dev.log`. A registry-installed brand has nothing to watch and says so in one line. It starts AFTER the freshness sweep on purpose: the sweep's verdict depends on whether a watch holds the lock ([#281](https://github.com/Omega-JS-Stack/omega/issues/281)/[#398](https://github.com/Omega-JS-Stack/omega/issues/398)), so starting one first would change the answer it just gave. A FRESH watch's initial prepare rewrites every package's `dist/` as it runs, so the boot WAITS for that pass to land ([#670](https://github.com/Omega-JS-Stack/omega/issues/670)) — the helper's `ready` promise resolves once every watched package has printed its `Ready for changes!` line (or the moment the watch child exits without reporting, or after 120s with one warning naming the stragglers), and only then do the legs boot, so nothing loads a CLI out from under the rewrite. **An ALREADY-RUNNING watch gates the same way** ([#622](https://github.com/Omega-JS-Stack/omega/issues/622)) — the branch a linked brand normally takes, since the root `npm start` is usually already up: with no child stdout to read, the boot tails that watch's own `.temp/logs/watch-all.log` (believed only when its pid header IS the lock owner's) through the same tracker, and also waits out a vendor-propagation pass holding `.omega/vendor-propagation.lock`. A settled watch answers off the file with no wait at all; a watch that dies mid-wait settles it at once. Same helper as the website target's `--local` prelude — one implementation, two callers.
+- **Every seeded persona is a FULL account** ([#327](https://github.com/Omega-JS-Stack/omega/issues/327)): identical in shape AND in substance to a real user — a name, a place, a phone, a company, a birthday, and the device and IP it signed up from — so a persona renders like a customer on every surface that shows a person. The profile is DERIVED from the persona key (`packages/backend/src/test/test-accounts.js` `seededProfile`), so it is the same on every boot and a new persona is born complete; anything a persona names for itself wins. Paid personas carry the provider record a real purchase leaves (provider, resource, order, term start, the event that last wrote it), which is what payment-gated surfaces — the billing card's save offer — read before they show anything. Established personas also carry the two lists an account accumulates ([#343](https://github.com/Omega-JS-Stack/omega/issues/343)): the REFERRALS an affiliate link earned (`{ uid, timestamp }`, exactly as a signup appends them, and naming other personas — so whether a referral converted is the referred account's own subscription state) — carried by the DEDICATED `referrer` persona and nothing else ([#363](https://github.com/Omega-JS-Stack/omega/issues/363)), because a persona demonstrates exactly its own scenario — and the ACTIVE SESSIONS of the two or three devices they are signed in on (Realtime Database records under `sessions/app`, seeded on boot and restored by "Reset to seed", because they live outside the user doc). Demo-safe by construction: documentation-range IPs, fictional 555 numbers, invented companies.
+- **The dev palette** (the DEV pull-tab the web framework renders in development): one-click sign-in as the seeded personas, including the four billing-journey accounts ([#215](https://github.com/Omega-JS-Stack/omega/issues/215)), and a "Reset to seed" button on any signed-in test account — a development-only backend route rebuilds the account from its canonical seed shape. The switcher's roster is the SEED's own ([#400](https://github.com/Omega-JS-Stack/omega/issues/400)): the backend labels each human-facing persona (`palette: '<Label>'` in `packages/backend/src/test/test-accounts.js`) and serves that list, in declaration order, at `GET /omega/test/roster`; the palette fetches it on build and keeps no copy, so a persona seeded today is switchable today and the machinery an automated suite drives never appears. The WHOLE seed is read, both halves ([#712](https://github.com/Omega-JS-Stack/omega/issues/712)): a project's own personas from its `test/_init.js` carry the same label and are offered after the framework's, so a consumer persona is switchable the moment it is seeded. The address the palette signs in on is the brand's HOST, and so is the one the seeder creates ([#708](https://github.com/Omega-JS-Stack/omega/issues/708)) — ONE derivation, `@omega.js/config`'s `resolvedBrandHost` (an instance's `url`, else `brand.url`), because a brand answering support mail on the apex while the site sits on a subdomain used to seed accounts the palette could never sign in as. There is no fallback list: with no emulator up the dropdown holds its placeholder alone and the "Signed in as" line carries the reason on a second line, under whoever you are signed in as (that readout is composed, so an auth state settling after the failure lands beside it rather than on top of it). A page opened while the emulator is still booting does not stay stuck there ([#402](https://github.com/Omega-JS-Stack/omega/issues/402)): a spinner and a "Backend starting…" line sit at the top of the panel and the roster is fetched again every two seconds, forever, until it answers; the attempt that lands fills the dropdown, preselects the signed-in persona, and clears both the indicator and the explanation, so no reload is needed. A built-in **Storage** section ([#390](https://github.com/Omega-JS-Stack/omega/issues/390)) covers the client blob: a target dropdown ("All" first, then every top-level key, re-derived from the LIVE blob each time the panel opens) with Log and Clear buttons acting on the selected target — Log prints the parsed value into the console, Clear removes it, and nothing asks you to confirm. Source: `packages/web/core/js/core/dev-palette.js`. Pages contribute their own controls via `registerDevSection` (`core/js/core/dev-sections.js`, [#234](https://github.com/Omega-JS-Stack/omega/issues/234)): sections render on open and merge by id — the checkout page's controls (product, frequency, pre-delay, trial, card provider, reCAPTCHA, the decline toggle) live in the palette's Checkout section, and every one of them applies the same way — Apply & reload navigates with its param set, the decline arm included (`_dev_decline`, which stays armed until you apply it away); the page's old gear dropdown is gone.
+- **The palette is the ONLY dev-testing surface** (Ian's ruling, [#342](https://github.com/Omega-JS-Stack/omega/issues/342), extending [#329](https://github.com/Omega-JS-Stack/omega/issues/329)): no client-side test personas as code objects, no helper hung on `window`, no dev switch you can only reach by already knowing its name — hidden functions get forgotten in six months. Alongside Checkout the panel now carries **Tools** (log opening tags, toggle theme), **Icons** (re-run the missing-icon audit), **Download** (open the onboarding walkthrough for a platform), **Extension** (fire a browser's install click) and **OAuth** (rehearse a returning provider redirect: returning user, new user, credential conflict). The account page carries NO control of its own: its referrals and sessions lists were the last client-side fixtures (`?_dev_prefill`), and the personas carry both now ([#343](https://github.com/Omega-JS-Stack/omega/issues/343)) — switching persona IS the affordance. Every one of them is a `@dev-only` block, so a production build ships neither the control nor what it unlocks. The rule outlives the sweep as a guard: `packages/web/test/dev-hooks-guard.test.js` fails on a new `_dev_*` hook or `window.<helper>` in client code, on a listed hook no palette section actually offers, and on any hook read outside a `@dev-only` block.
+- **Google/OAuth signin uses the redirect flow here, same as production** ([#156](https://github.com/Omega-JS-Stack/omega/issues/156)): the auth emulator returns its credential through storage on the origin it is served from, so `omega dev` proxies the emulator under the SITE origin and the return leg survives the browser's storage partitioning. Details in [docs/web/index.md](../web/index.md).
+- Output is line-prefixed per target (`[backend] …`, `[web] …`); one Ctrl-C stops everything; a leg dying alone is announced and its siblings stay up.
+- **No production build runs under a live dev server** ([#617](https://github.com/Omega-JS-Stack/omega/issues/617)): `omega dev` and `omega build` write the SAME `dist/`, and a build landing under a running website dev server replaces the pages it keeps serving — production-stamped, `dev: null`, no re-render until a restart. So `omega build` in a website target REFUSES in one line while that target's dev run holds it, and so does anything that runs it (`omega test`'s project lane, `omega audit`, the manage cycle's rebuild lane, and `omega deploy`'s local/direct lanes — mid-session, scope manage: `npm run manage -- --service=<name>`). Stop the leg first. The dev run is known by the ports file it already publishes and retracts on shutdown, so there is no second lock — and a crash leftover (dead pid) is ignored, never a wedged build. Web only for now: the same guard reaches another framework the day the mechanism is shared, never as a fourth copy.
+
+## What refreshes when — the redistribution contract
+
+Brand-level sources are not read by the targets directly; most of them are **redistributed** by the manage cycle, and target watchers only watch their own dir. So:
+
+| You edited | What moves it | When it lands |
+|---|---|---|
+| `assets/logo/*.svg`, `assets/templates/*.psd` | assets service → derived variants in the gitignored `.omega/assets/`, mtime-diffed (only stale outputs regenerate) | a manage cycle: restart `omega dev`, or run `npm run manage` in the brand |
+| `.omega/assets/*` (the derived set) | the web build's static channel copies them into the site as `assets/images/brand/*` + `assets/images/favicon`, and mirrors the shipped `favicon.ico` to the site root so the browser's `/favicon.ico` probe resolves (`packages/web/src/static-assets.js`) | the web build's `static` phase — the dev server copies at BOOT, no watcher, so a restart picks them up |
+| signing certs | disperse service → each target's gitignored certs dir | the delivery lane: a boot, a `npm run manage`, or a brand-root `omega deploy` |
+| brand `.env` | nothing copies it — every verb composes its target's runtime env (the backend's staged `dist/.env`) from the cascade, filtered by the env schema ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)) | the next build; **the dev watchers reload the env cascade on change** — the backend restages `dist/.env`, and the web + extension dev lanes reload it into `process.env` for the next rebuild ([#681](https://github.com/Omega-JS-Stack/omega/issues/681)). A **NEW** key and an **EDITED** value both land on that rebuild, and a key dropped from the file is dropped from the process — the reload drops what a file layer owns and re-reads the cascade ([#724](https://github.com/Omega-JS-Stack/omega/issues/724)); a **shell**-set value still wins over every file. One limit worth knowing: **desktop is pre-wired only** (its dev pipeline builds once, and the electron child snapshots env at spawn, so nothing there consumes a reload yet) |
+| `config/omega.json5` (brand or local) | nothing — targets read it directly, there is no mirror to disperse | the reading process's own reload (a running backend restages on it; a dev-server restart is always enough) |
+| a target's own `src/` | that target's watcher | live |
+
+The short version: **anything under the brand root that isn't inside a target needs the manage cycle**, and `omega dev` now runs one at boot ([#44](https://github.com/Omega-JS-Stack/omega/issues/44)) — so the loop for a brandmark edit is *edit the svg → restart `omega dev`*. Mid-session, `npm run manage` (or `npx omega manage --service=assets`) does the same without stopping the stack, then restart the web leg to pick up the copies.
+
+## One-command consumer sessions: `omega dev --local`
+
+In a brand's website target, `omega dev --local` runs the full local-mode prelude before the normal dev server:
+
+1. **Resolve the monorepo** — `OMEGA_MONOREPO` env override → self-location (works whenever the running framework is linked from the monorepo, or the consumer lives inside it) → `~/Developer/Repositories/Omega/omega`.
+2. **Find the brand root** — walk up from cwd to the first directory with both a `package.json` and `targets/<name>/package.json` (the Omega monorepo itself never counts); standalone projects resolve to themselves.
+3. **Link brand-wide** — for every project (brand root + `targets/*`), every `@omega.js/*` dependency in the ONE authored manifest (src/dist pillar — a backend's `functions/` is staged output and carries no authored manifest) is flipped to a `file:` spec and installed. **Idempotent**: deps already resolving to the monorepo copy are skipped (resolution walks up node_modules, so npm-workspace hoisting is handled), and an already-correct committed `file:` spec is never rewritten. **Transactional**: an install failure restores every flipped manifest to its pre-link spec.
+4. **Start the monorepo watch** — spawned as a session-scoped child (dies with the dev server; the lock prevents doubles). Watch output streams into the dev log under a `[watch]` prefix. Same helper the brand root uses (below): `startMonorepoWatch()` owns the session scoping, each caller keeps its own Ctrl-C policy.
+
+Then the standard `omega dev` loop runs. Result: edit any framework's `src/` and the consumer picks it up live — no N windows, no N × `mgr i local`.
+
+**Upstream-first (Ian 2026-07-27).** The live link is not just a convenience — it is how framework holes get found and fixed. Building a real consumer app regularly exposes gaps in OMEGA; when a defect or missing piece would hit EVERY consumer (a broken core style, a wrong default, a missing option), fix it in the framework right here through the link, not in the consumer project — a consumer-side patch has to be rediscovered and repeated in the next project. The test: would the next consumer need the same change? Then it belongs upstream. Brand-specific looks, content, and one-off behavior stay in the brand. The same rule ships to brand sessions in the brand guide (`docs/manager/brand.md`).
+
+**Permission first (Ian 2026-07-27).** Upstream-first says WHERE a fix belongs, never that a consumer session may make it unprompted. A session working in a consumer project that finds a framework-level hole SURFACES the proposed framework change — what is broken, what it would change, why every consumer needs it — and WAITS for Ian's go before touching the monorepo (or files it as an issue when Ian is not in the loop). No consumer session edits the framework silently as a side effect of its own task.
+
+## Per-target linking: `mgr i local`
+
+**Linking is one-time and durable (Ian 2026-07-28) — never re-run it per change or per session.** The `file:` specs resolve to real symlinks into the monorepo, so once a brand is linked, every framework edit is live the moment its `dist/` rebuilds (the monorepo watch or any prepare). The web dev server watches the resolved `@omega.js/client` dist and rebuilds the site bundle on ANY change there — including a prepare's wholesale delete-and-recreate, which the watch survives by re-arming onto the new directory ([#378](https://github.com/Omega-JS-Stack/omega/issues/378)) — so client changes reach a RUNNING site with no restart. Framework PROCESS code (the dev server itself, a backend leg) still loads at boot: those edits need the normal stack restart. Re-running `i local` is a HEAL for a link something overwrote (a registry install, a fresh clone) — reruns all-skip and cost nothing, but they are never part of the edit loop.
+
+Unchanged contract for consumers, now monorepo-backed: `mgr i local` (web, desktop, extension — web gained its install command in cp194) and `mgr i local` / `mgr install --local` (backend) call the same `linkLocalPackages()`. Backend links its target-root manifest like every other target (`functions/` is staged output; the CLI normalizes a `functions/` cwd up to the target root). `mgr i live/prod` still installs from the registry and is untouched.
+
+**Linking is brand-tree-wide by construction (cp194):** npm resolves the WHOLE workspace tree on any install anchored in a brand monorepo, so linking one target while a sibling still carries an unpublished registry spec (`@omega.js/backend: *`) 404s before anything links — only reachable in a brand OUTSIDE the omega monorepo, the real consumer topology. `linkLocalPackages()` therefore flips every target's `@omega.js/*` specs to `file:` first (dev/prod placement preserved; specs computed from REAL paths so symlinked/aliased dirs can't dangle), then runs ONE `npm install` for the tree. One call from any target links the whole brand; reruns all-skip.
+
+**The brand root itself is part of the tree (cp195):** onboard scaffolds `@omega.js/manager` into the brand root's devDependencies — the omega-bin dispatcher resolves brand-level verbs (`omega dev`, manage, the scaffolded `start`/`manage` scripts) FROM the brand root, and without the declaration nothing installs the manager outside the monorepo (inside it, workspace hoisting masked the gap). `linkLocalPackages()` links it like any target dep (`discoverTargets` already includes the brand root).
+
+**Outside brands may COMMIT relative `file:` specs — the real brand does (cp229):** `../omega-brand` (folder renamed from omegajs.dev, cp235) declares every `@omega.js/*` dep as `file:../../../omega/packages/<name>` (brand root: `file:../omega/packages/manager`), the same pattern the in-repo brands already use at their own depth. Clone the two repos side by side and a plain `npm install` links the whole tree with zero linker involvement; `linkLocalPackages()` all-skips because the specs already resolve into the monorepo. At first publish the specs flip to exact `0.1.0` registry pins (versions re-reset to 0.1.0 at cp238 — 0.x until live publishes are proven — so the flip stays seamless).
+
+## Vendoring vs runtime deps (what ships where)
+
+Two different mechanisms keep consumers working:
+
+| Kind | Packages | Mechanism |
+|------|----------|-----------|
+| Private shared internals | `devkit`, `config`, `account`, `template-kit`, `analytics`, `monitoring` (devDependencies of the frameworks) | Vendored into `dist/vendor/<pkg>` at prepare time by `@omega.js/devkit/vendor`; requires rewritten to relative paths. Never published. |
+| Published runtime deps | `@omega.js/client` (dependency of web + backend + desktop + extension), `@omega.js/backend` and `@omega.js/mcp-router` (dependencies of manager) | Normal npm dependency — **never vendored** (a vendored copy would pin a stale snapshot and duplicate the shared client singleton). Requires stay as package requires. |
+
+The vendor tool derives the split from the host's package.json: anything in `dependencies`/`peerDependencies`/`optionalDependencies` is published-runtime and skipped; devDependency workspace packages get vendored. All six DIST-BUILDING publishables (backend, client, desktop, extension, manager, web) run the vendor after-hook; the seventh, `@omega.js/mcp-router`, ships its `src/` as-is and vendors nothing. Two mirrored gates prove self-containment: CI's pack-smoke and the local `npm run release:check` — both pack, scratch-install with tarball `overrides` for the published runtime deps, resolve, and grep the whole shipped tree for raw private `@omega.js/*` refs — the alternation is DERIVED from `VENDORABLE_PACKAGES`, never written out ([#713](https://github.com/Omega-JS-Stack/omega/issues/713): the hand-written four sat two names behind the list, so a raw `analytics`/`monitoring` require could ship undetected). The publish runbook lives in [docs/shared/publishing.md](publishing.md).
+
+## API surface (`@omega.js/devkit/local`)
+
+| Export | Purpose |
+|--------|---------|
+| `resolveMonorepoRoot()` | env → self-location walk-up → conventional path; throws with guidance if none |
+| `findBrandRoot(dir)` / `discoverTargets(root)` | brand-root walk-up / brand root + `targets/*` list |
+| `frameworkPackagesOf(targetDir)` | `@omega.js/*` deps incl. `functions/package.json`, with dev/prod placement + owning dir |
+| `linkLocalPackages({ dir, monorepoRoot, logger, dryRun })` | idempotent brand-tree file:-link (spec flip + one install, transactional — a failed install restores every manifest); returns `[{ name, dir, target, action: link\|skip\|missing }]` across the tree |
+| `restoreRegistrySpecs({ dir, logger, dryRun, range })` | the publish-day INVERSE (`omega i live` in every framework): every `file:` spec flips to the EXACT `<linked version>` (read from the file: target — no monorepo needed, no caret: the family is lockstep, [#794](https://github.com/Omega-JS-Stack/omega/issues/794)) or the explicit `range`, used verbatim; then one registry install, same transactional restore on failure |
+| `resolveLinkedMonorepo(brandRoot)` | the monorepo a brand's `@omega.js/*` deps actually RESOLVE into, or null for a registry install |
+| `startMonorepoWatch({ monorepoRoot, logger })` | lock-aware, SESSION-SCOPED spawn of the root watch (dies with the caller); `{ alreadyRunning, pid, child, ready }` — `ready` resolves with `'ready'`, `'exit'` or `'timeout'` on BOTH branches (#670, #622) |
+| `awaitRunningWatchReady({ monorepoRoot, pid, logger })` | the same verdict for a watch this process did not start: its tee'd log + the propagation marker, 120s bound |
+| `vendorPropagationActive(monorepoRoot)` | is a propagation pass purging framework dists right now (stale marker = no) |
+| `createWatchReadyTracker()` | the pure line parser behind `ready`: `push(line)`, `isReady()`, `pending()` |
+| `startVendorPropagation({ packagesDir, packages, dependents, runPrepare?, log?, debounceMs? })` | watch vendorable srcs → re-prepare dependents (debounced, coalescing); `{ watched, poke, close }` — `poke` is the fs-free test seam; a running pass holds `.omega/vendor-propagation.lock` |
+| `acquireWatchLock` / `releaseWatchLock` / `readLiveWatchPid` | the `.omega/dev-watch.lock` single-instance protocol (owned by watch-all) |
+
+## Freshness guard (cp247, hardened in [#195](https://github.com/Omega-JS-Stack/omega/issues/195))
+
+Every framework CLI boot (web/backend/desktop/extension/manager — `freshnessBoot` in devkit `local.js`, wired in each `cli-run`) checks whether a locally-linked framework's `dist/` is stale. What happens next depends on who OWNS that dist ([#281](https://github.com/Omega-JS-Stack/omega/issues/281), narrowed by [#398](https://github.com/Omega-JS-Stack/omega/issues/398)): a link into this monorepo **whose watch is running** is read-only and the boot stops loudly (below), while every other local checkout — a plain link, and a monorepo link with the watch DOWN — heals in place, a loud auto `npm run prepare` in the package, after which the invocation RE-EXECS once (`OMEGA_FRESH_REEXEC` loop guard) so no verb ever runs stale framework code.
+
+**Linked monorepo packages are READ-ONLY to consumer builds while their watch runs** ([#281](https://github.com/Omega-JS-Stack/omega/issues/281), Ian's call 2026-08-17). A consumer that resolves an `@omega.js/*` dependency to a link into this monorepo never prepares that package out from under the process that owns the build: no dist purge, no cache refetch (backend's prepare refetches `.cache/email/disposable-domains.json` over the network), not even a heal lock inside the package. That checkout is SHARED, by a fleet of agents, several brands and the monorepo's own processes, and a prepare deletes the `dist/` a sibling process is mid-`require` on, with nothing in `git status` to show for it. **Dist freshness is owned by the monorepo watch** (root `npm start`) whenever that watch exists.
+
+**With the watch DOWN, the boot heals the link itself** ([#398](https://github.com/Omega-JS-Stack/omega/issues/398), Ian's call 2026-08-20). The stop is right only while something else owns the rebuild; with no watch running it is pure friction — the guard already knows the watch is down (the `.omega/dev-watch.lock` pid probe it warns from), so a stale linked dist takes the ordinary heal: one `npm run prepare` in place under the package's heal lock, `rebuilt` by `self`, then the boot's re-exec. The hazard #281 named is narrowed, not dismissed: the heal lock still serializes the CLIs booting on that package, and the largest concurrent writer is by definition not running. The once-per-process watch-down warning STAYS on this path — a stale linked dist is healed once at boot, and a framework edit made during the session still needs `npm start` for live rebuilds. **And a heal that FAILS is a loud stop, not a shrug**: the outcome is `heal-failed`, and the boot exits 1 naming the package, the staleness, the prepare's exit status and the `npm run prepare` to run by hand in that checkout. A plain checkout keeps the old warn-and-continue (its dist is the developer's own, and nothing shared hangs on this boot), but a monorepo link has no watch coming to land the build, so continuing would serve code nobody built — the silent fallback #281 forbids. `omega dev`'s hoisted sweep returns those entries as `healFailed` and stops the fan-out before any leg spawns, exactly as it does for `staleLinked`.
+
+**The INSTALL path is guarded at the prepare script** ([#350](https://github.com/Omega-JS-Stack/omega/issues/350)). npm runs a `file:`-linked dependency's `prepare` INSIDE the linked checkout, so `omega i local`, `omega dev --local` and any plain `npm install` in a linked brand rebuilt a monorepo package in place through the one door a CLI guard cannot see — npm invokes prepare, devkit never gets a say. Every dist-building package's prepare now opens with devkit's gate: `node -e "require('@omega.js/devkit/prepare-guard')() && require('prepare-package')()"` (`packages/devkit/tools/prepare-guard.js`). When npm's install root (`npm_config_local_prefix`, `INIT_CWD` as the fallback) lies OUTSIDE the monorepo that contains the package, the build is skipped — a false return short-circuits the `&&`, exit 0, so the consumer's install completes normally — with one stderr line naming the package, the install that reached in, and the watch that owns the dist. It fires for every TREE-TOUCHING command from outside — `install`, `ci`, `update`, `rebuild`, `dedupe`, the five npm reports in `npm_command` that re-run a linked package's prepare (npm 11.12.1) — and for nothing else: the monorepo's own root install, workspace installs (`-w packages/web`), an install typed inside a package or an in-repo app, `npm run prepare`, and the `npm pack`/`npm publish` prepare lane all build exactly as before, so a published tarball still carries a freshly built dist. npm buffers lifecycle output, so the notice surfaces under `--foreground-scripts`.
+
+**The gate keeps itself wired.** prepare-package OWNS `scripts.prepare`: every full build rewrites the manifest with its own canonical one-liner, which would silently drop the gate on the monorepo's next prepare. So each package's `preparePackage.hooks.after` is now a two-command chain — the vendor hook, then `require('@omega.js/devkit/prepare-guard').rewire()` — which runs after that manifest write in BOTH the `prepare` and `prepare:watch` lanes and puts the gated line back, in prepare-package's own formatting so a settled `package.json` never churns. It is idempotent and narrow: it writes only when the manifest holds prepare-package's exact string, and never touches a prepare it does not own. Pinned by devkit `test/prepare-guard.test.js` (22 tests: the decision table, the notice, and real-npm/real-prepare-package fixture runs — including the red baselines, an unguarded consumer install rebuilding the linked package and a real build overwriting the gate).
+
+The consequence is deliberate: with that watch running, a linked dist that is missing, unbuilt or stale FAILS the consumer build loudly, before the verb runs, naming the package, the evidence, the checkout it will not touch, and the watch already on the job:
+
+```
+omega: @omega.js/backend is linked into the omega monorepo and its dist is not built (dist/ is missing).
+omega: linked packages are read-only to consumer builds, so this build will not rebuild /Users/ian/…/omega/packages/backend.
+omega: the monorepo watch (`npm start` in /Users/ian/…/omega) is running but has not landed that build yet: give it a moment, then re-run this command.
+```
+
+There is no silent fallback and no staging copy: the build runs on a dist the watch built, or it stops and waits for it. `OMEGA_SKIP_FRESHNESS` remains the one opt-out, for harnesses that manage their own builds.
+
+**The boot checks the host AND its `@omega.js/*` runtime deps** ([#198](https://github.com/Omega-JS-Stack/omega/issues/198)): each `cli-run` names its host package, and `freshnessCheckList` walks that host's `dependencies` (never devDependencies) through local checkouts — cycle-safe, each dep resolved from ITS depender so the walk follows the real node_modules chain — producing a DEPS-FIRST, host-last check order (web → `client`, web; manager → `client`, `backend`, manager). The host alone was never enough: web's bundle carries `@omega.js/client`'s dist verbatim, so a boot that healed web and stopped there still served the browser a stale client. A rebuild ANYWHERE in that list re-execs the invocation once; a dep that resolves into `node_modules` is classified `registry` and its own deps are not walked. **Every heal re-execs, whoever built it**: the outcome is `rebuilt` with a `by: self|watch|peer` discriminator (this boot's own prepare, the monorepo watch landing its copy inside the grace, or a peer CLI that won the heal lock) — a process that booted from the pre-heal dist is just as stale when someone else fixed it. Registry installs (realpath inside node_modules) and non-buildable dirs skip instantly; `OMEGA_SKIP_FRESHNESS` is the opt-out seam. A monorepo-linked entry that comes back stale under a live watch ends the walk where it stands: the boot prints the read-only stop above and exits 1, deps included, so a stale `client` never reaches its dependent's build. Pinned by devkit `test/local-freshness.test.js` (49 tests incl. linked-consumer integration proofs).
+
+**Detection is per-file evidence, never a whole-tree mtime compare** (`distStaleReason`, 1–36ms per package). Every file under `src/` must exist at its mapped `dist/` path with an mtime at least as new — a MISSING dist file is stale whatever the timestamps say — and every dist file must have a src counterpart, or a leftover from a deleted source reads stale. The exceptions are the paths prepare itself generates: `dist/vendor/**` plus every destination the host declares in `omega.vendorAssets` (that is how desktop/extension carry a `dist/assets` tree the web package owns) — and nothing else, because vendor-docs writes the package ROOT `docs/` and prepare-package rewrites the ROOT `package.json`, so a `dist/docs/**` or `dist/package.json` is a leftover like any other. One subtree is exempt from the orphan question alone ([#352](https://github.com/Omega-JS-Stack/omega/issues/352)): `dist/test/fixtures/**`, where a package's own self-tests seed runtime state (backend writes its fixture project's `firestore.rules` and `service-account.json` there) that shadows no consumer require and outlives a crashed run — a file there WITH a src counterpart still answers the mtime question. The embedded `dist/vendor/<name>` copies are still compared against each private package's `src/` — they only refresh on a full prepare. The declared `omega.vendorAssets` destinations get the same positive question ([#199](https://github.com/Omega-JS-Stack/omega/issues/199)): each is compared against its source package's `from` tree (web's `core/`/`themes/` for desktop/extension), monorepo-only, so the exemption from the orphan scan is no longer a free pass: a boot acts on a stale vendored copy — heal or stop — instead of serving it. The old newest-mtime heuristic read "fresh" whenever ANYTHING touched dist after a src edit, and the vendor after-hook does exactly that: on 2026-08-05 `packages/web/dist` served a stale `commands/setup.js` and was missing new files for a day with both automatic layers silent.
+
+**A live watch buys a bounded grace, not blind trust.** Stale with the root-watch lock held → recheck for ~2s so an in-flight watcher copy can land (dim note, `rebuilt` by `watch` if it does — still a heal, so the boot re-execs onto it), then the verdict: a monorepo link stops the invocation, any other local checkout heals here. **A dead watcher is loud**: a monorepo-linked boot with no live lock prints one stderr line naming the fix (`npm start` in the monorepo) — the boot's own heal ([#398](https://github.com/Omega-JS-Stack/omega/issues/398)) repairs a STALE dist once, at boot, and nothing propagates a src edit made afterwards, so the warning still carries the whole story (it fires on a fresh dist too, so it states that standing deal rather than claiming a heal that may not have happened). Both surfaced from the freshness path, so all five framework CLIs get them for free.
+
+**Heals are locked per package** (a local checkout outside this monorepo, a monorepo link with the watch down, and the watch's own prepares): a mkdir-as-mutex at `<package>/.omega/heal.lock` with the owner pid inside (the `withStateLock` idiom from `deploy-record.js`; pid liveness replaces its mtime age because a real prepare holds the lock for minutes). The loser waits, then RE-CHECKS freshness — the winner's build makes it a no-op, so two or ten CLIs booting on the same stale link produce one build. Abandoned locks (owner gone — an EPERM pid is LIVE, never stolen) are stolen; a wait past the deadline proceeds unlocked rather than failing a boot, and lock bookkeeping that cannot be written (read-only fs, full disk) degrades to unlocked instead of throwing out of a heal. **The vendor-propagation watcher takes the same lock** around its own `npm run prepare` spawn (`startVendorPropagation`, held for the child's whole life, awaited async so the watcher keeps serving its other watches) — that spawn is devkit's own, so it locks; only prepare-package's INTERNAL src→dist copying stays unlocked third-party territory, and it converges on the watcher's next change event.

package/docs/shared/logging.md

@@ -0,0 +1,202 @@
+# 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/manager/helpers/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.
+- **`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/website`, `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 |
+| **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` | `<targetRoot>/dist/deploy.log` | the deploy transcript |
+| `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` | `<targetRoot>/logs/ci.log` | the GH Actions release run, streamed locally |
+| 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 — the backend's own transcript additionally lands in `targets/backend/dist/deploy.log` (the other targets keep no per-target 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/website/logs/dev.log            # is the dev server up, what did it last build
+grep -i error targets/backend/dist/emulator.log  # what the emulator actually served
+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

@@ -0,0 +1,153 @@
+# 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
+  (`RouteContext.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.<type>.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). |
+| `OMEGA_BUILD_MODE=true` | The default production signal, for a host with no runtime one. |
+
+The production signal is the host's to supply. @omega.js/desktop has no runtime answer — "should we
+ship telemetry" is a property of its BUILD — so it falls through to `OMEGA_BUILD_MODE`.
+@omega.js/backend has one (`Manager.isProduction()`, env-derived and stable for the life of the
+process) and passes it in, alongside its own `reportErrorsInDev` option.
+
+## 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 emitted in the page `Configuration` block 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 | `RouteContext.report()` — 5xx captures automatically, 4xx never ([backend guide](../backend/index.md)) |
+| Backend event triggers | `helpers/event-middleware.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 every framework
+maps it from `monitoring.providers.sentry`:
+
+| Framework | Where |
+|---|---|
+| `@omega.js/web` | the `Configuration` block in `core/_includes/core/foot.html` — `resolved.monitoring.providers.sentry` → `sentry`. A real DSN is emitted AFTER the `resolved.client` loop, so the canonical home outranks a stale `client.sentry` ([#485](https://github.com/Omega-JS-Stack/omega/issues/485)); with no DSN there, the off state rides before the loop, so a brand not yet migrated off `client.sentry` keeps reporting |
+| `@omega.js/extension` | `src/gulp/tasks/bundle.js` (`composeBuildConfig`, baked into every bundle) |
+
+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.