@omega.js/web 0.1.0

package/docs/shared/deploys.md

@@ -0,0 +1,215 @@
+# Deliberate deploys (D13 / D9 addendum)
+
+**Commits never auto-publish.** Save = commit; publish = an explicit deploy
+action. Every entry surface — the local CLI, a server-side content action
+(admin post), or a plain HTTP call — converges on ONE executor:
+`@omega.js/devkit/deploy`.
+
+## The executor — `@omega.js/devkit/deploy`
+
+A GitHub REST `workflow_dispatch` client on native fetch (no gh-CLI
+dependency — Cloud Functions and laptops share the code path). Vendored into
+framework dists like every devkit module.
+
+| Export | Contract |
+|--------|----------|
+| `parseRemoteUrl(url)` | ssh / https / `.git`-less GitHub remotes → `{ owner, repo }` (non-GitHub → null) |
+| `dispatchRepo(config)` | `{ owner, repo }` from the BRAND's config (`@omega.js/config`'s `brandRepo`), throwing on half an address: the one address every deploy dispatch uses ([#799](https://github.com/Omega-JS-Stack/omega/issues/799)) |
+| `resolveRepo({ cwd, remote, execFn })` | `{ owner, repo }` from `git config --get remote.origin.url` (the direct lane's slug fallback, never a dispatch address) |
+| `resolveToken({ env, execFn })` | `GH_TOKEN` → `GITHUB_TOKEN` → `gh auth token` → null |
+| `buildDispatch({ owner, repo, workflow, ref, inputs })` | the PLAN: `{ method, url, body, runsUrl }` — dry-run output is exactly this |
+| `dispatchWorkflow(plan, { token, fetchFn })` | POST to `/repos/{o}/{r}/actions/workflows/{wf}/dispatches`; 204 = accepted, anything else throws with status + body |
+| `deployViaDispatch({ workflow, cwd, owner, repo, ref, inputs, dryRun, … })` | the one path: resolve → plan → (`dryRun` returns the plan unsent) → dispatch |
+| `assertNoLocalSpecs({ dir })` | the TREE-WIDE `file:` guard: throws (listing every offender) when any target in the brand carries a `file:` @omega.js spec — one linked sibling breaks the whole CI install (cp194) |
+| `syncWorkingTree({ cwd, message, logger })` | plain-git commit + push before a dispatch (`git add -A` → commit only when staged → push; argument arrays, no shell) — pushes trigger NOTHING (D13) |
+
+`ref` defaults to `main`; pass the real branch when it isn't (the admin post
+routes read the repo's `default_branch` first). All I/O is injectable
+(`fetchFn`/`execFn`) — pinned by `packages/devkit/test/deploy.test.js`.
+
+**Every framework's deploy verb dispatches to the BRAND repo named by its config, never the git remote** ([#799](https://github.com/Omega-JS-Stack/omega/issues/799)): web, extension and desktop (`omega release` included) all take `{ owner, repo }` from `dispatchRepo(config)` and refuse when the config names none, because a remote answers the repo the working tree sits in, which inside a brand nested in another repo is the enclosing one.
+
+## Scaffolded workflows — no push triggers
+
+| Target | Workflow | Triggers | Publishes |
+|--------|----------|----------|-----------|
+| web | `.github/workflows/build.yml` (authoritative, regenerated by the target scaffold every verb runs) | `workflow_dispatch` + `repository_dispatch: [omega-deploy]` | gh-pages |
+| extension | `.github/workflows/publish.yml` (authoritative via defaults engine) | same | stores (when creds present) + the package zip attached to a GitHub release `extension-v<version>` (D9 addendum 2 — durable artifact channel, no 7-day purge) |
+| desktop | `.github/workflows/build.yml` | `workflow_dispatch` (was already manual-only — the reference shape) | GitHub releases in the brand's ONE public releases repo (`<brand.id>-releases` by default, addressed by `@omega.js/config`'s `releasesRepo`, [#799](https://github.com/Omega-JS-Stack/omega/issues/799)): electron-builder's publish block, the signed-Windows upload and the autoupdater feed all name it |
+| backend | none | — | direct `firebase deploy` from the CLI |
+
+Existing consumers converge on their next omega verb (both scaffold
+engines treat workflow files as framework-owned overwrites).
+
+**The desktop workflow runs no tests** ([#802](https://github.com/Omega-JS-Stack/omega/issues/802)): CI is dispatch-only and BUILDS. Its Test job (first ahead of Build, then beside it) was a leftover of the era before that standard, and it is gone: `build` needs `setup`, and `finalize`, the job that flips the draft release to published, needs `[setup, build, windows-sign]` and gates on `needs.build.result == 'success'` inside its `always()`. Proof lives where web's and the extension's release workflows already leave it: the suites run on the developer's machine, and the commit gate runs the battery at ship ([testing.md](testing.md)).
+
+**In a brand monorepo the workflow moves to the ROOT** ([#265](https://github.com/Omega-JS-Stack/omega/issues/265)): GitHub executes workflows from the repo root's `.github/workflows/` only, so a `targets/<target>/.github/workflows/*.yml` never fires — CI builds and store publishes silently do not exist. The target scaffold composes the target's workflow into the brand root as `<target>-<workflow>.yml` (`extension-publish.yml`) via `@omega.js/devkit/ci-workflows`: every post-checkout `run:` step scoped to the target (a per-step `working-directory:`, never a workflow-level `defaults.run.working-directory` — that would also scope the steps running before `actions/checkout`, where the target dir does not exist yet, killing the job on step 1), the path-bearing inputs of a post-checkout `uses:` step rewritten to the target dir (an action ignores `working-directory:` — the table is explicit per action: `actions/cache`/`upload-artifact`/`download-artifact` `path`, `peaceiris/actions-gh-pages` `publish_dir`, and every `hashFiles()` pattern, which globs from the workspace root wherever it sits), a per-target concurrency group, regenerated from the template on every verb (a rerun updates that one file, never duplicates), and the target's own dead copy swept when the framework wrote every line of it: an exact match, or a copy a SUPERSEDED template wrote, which is what templates evolve into by GAINING lines ([#334](https://github.com/Omega-JS-Stack/omega/issues/334)); a copy carrying a line no current template ships is kept with a loud move-it-then-delete warning, never destroyed (accepted blind spot: an edit that ONLY deletes template lines is still swept — harmless, since a target-dir workflow never runs). `omega deploy` dispatches the composed name in a brand and the plain name standalone, and so does desktop's `omega release`: all three frameworks take the file name from ONE helper, `composedWorkflowName({ targetDir, brandRoot, workflow })` in `@omega.js/devkit/ci-workflows` (desktop joined it in [#799](https://github.com/Omega-JS-Stack/omega/issues/799), which also moved its dispatch repo off the git remote onto the config). Wired for all three: extension (`extension-publish.yml`), web (`website-build.yml`), and desktop (`desktop-build.yml`, composed by its ensure-target pass since [#627](https://github.com/Omega-JS-Stack/omega/issues/627)); each carries its schema-rendered secrets block. Scoping is by working directory, not a `paths:` filter — dispatch-only workflows have nothing to path-filter.
+
+**The monorepo runs the playground's desktop release itself** ([#802](https://github.com/Omega-JS-Stack/omega/issues/802)): the playground brand is a DIRECTORY inside this repo, so the file its desktop target composes at `brands/omega-playground/.github/workflows/desktop-build.yml` sits where GitHub never looks, and the desktop release run (hosted build, the self-hosted EV-token Windows signer registered to the Omega-JS-Stack org, finalize) had no repo to execute in. It runs in a repo of its OWN: `Omega-JS-Stack/omega-playground-rehearsal`, PRIVATE, throwaway, `<brand.id>-rehearsal` per the brand repo rule ([#808](https://github.com/Omega-JS-Stack/omega/issues/808)). Not a branch of this repo and not the playground's own declared repo, for reasons that leave no other shape: GitHub dispatches a workflow only when it exists on the target repo's DEFAULT branch (a `rehearsal` branch answered HTTP 404 until the file went to `main`), the org's runner group refuses a public repo, and `Omega-JS-Stack/omega-playground` is public because it serves gh-pages, so a snapshot there would publish the whole framework source. Nothing rehearsal-shaped lives on omega's own branches, and `main` moves only when Ian ships it. The workflow itself, `.github/workflows/playground-desktop.yml`, is rendered from the SAME desktop template through the same `composeWorkflow` by `scripts/playground-desktop-workflow.js` (target path `brands/omega-playground/targets/desktop`), with the two monorepo-only edits a brand never needs: a root `npm install && npm run prepare --workspaces --if-present` ahead of the target steps in every job that checks out, because the playground's `@omega.js/*` deps are `file:` links into this checkout, and the target's `npm ci` becoming `npm install`, because the lockfile `npm ci` would read is the brand root's and that file is not committed. Neither install is `npm ci`: the root one runs on a SNAPSHOT of a working tree, whose root lockfile may lag its package.json files until the ship's own `npm install` heals it, and `npm ci` refuses a lagging lockfile. That rendered file is GITIGNORED here and committed nowhere: it is rewritten before every rehearsal and lives only in the snapshot repo, so `scripts/playground-desktop-workflow.test.js` (in the root `test:packages` lane) checks the RENDER against the template and drives the generator to prove it writes exactly that. The run is TEST-ONLY and never fires on a push: one command rehearses it, `npm run rehearse:desktop -- --platforms windows [--watch]` (`scripts/playground-desktop-rehearsal.js`), because a workflow only runs from code GitHub already has. Six steps: render the workflow; ensure the rehearsal repo exists (created private the first time); PUBLISH the playground desktop target's composed secrets to it (the set `omega push-secrets` composes for a brand, the env schema's desktop delivery keys valued from the target's `.env` cascade through desktop's own file resolver, so `APPLE_API_KEY` still travels as base64, sent here because push-secrets publishes to the brand's DECLARED repo and skips loudly on the remote mismatch a target nested in this monorepo always is, which is why the first real run died inside `npm run package` on a missing `GOOGLE_ANALYTICS_SECRET`); commit the WORKING TREE (untracked-not-ignored files included, the ignored workflow file force-added, the playground's uncommitted lockfile excluded) out of a TEMPORARY index (`GIT_INDEX_FILE`, so no stash, no checkout, and the working tree, the real index and every local branch untouched) onto the local ref `refs/rehearsal/head`, which is outside `refs/heads/` so no branch appears here at all, and force-push that commit to the rehearsal repo's `main`; wait for GitHub to register the pushed workflow, then dispatch it there; then print the run's URL and follow it with `--watch`. Nothing is `gh secret set` by hand. The dispatch WAITS for the push to register instead of asking a human for a second attempt: a dispatch reads the workflow off the repo's DEFAULT branch and GitHub indexes a freshly pushed one a few seconds after it arrives, so the first run against the brand-new repo answered `HTTP 404: workflow playground-desktop.yml not found on the default branch` to both the run probe and the dispatch, while the same command a minute later worked. The step now polls `gh api repos/<repo>/actions/workflows/<file>` up to 20 times, 3 seconds apart, one line per try, and fails loudly past that budget (a push that never carried the file, or a repo whose default branch is not `main`). Re-running with no edits reuses the same commit and pushes nothing new. A real brand is its own repo and needs none of this; it gets the composed file at its own root from any omega verb.
+
+**A web deploy fills its own base path** ([#358](https://github.com/Omega-JS-Stack/omega/issues/358)): `brand.url` set → the site serves at that domain's root (the CNAME both lanes publish cannot carry a path) → `OMEGA_PATH_PREFIX=/`; unset → the default project address `https://<owner>.github.io/<name>/` → `/<name>/`, from the same repo slug the direct plan resolves. `--direct` sets it around the build it runs itself, and the scaffolded `build.yml` derives it remotely through the SAME function (`@omega.js/web/deploy`'s `targetPathPrefix()`, `GITHUB_REPOSITORY` naming the repo when the checked-out config carries no slug) into `$GITHUB_ENV`. An explicitly exported `OMEGA_PATH_PREFIX` wins (publisher machinery like workkit supplies its own); `omega dev` and a bare `omega build` stay at the root ([#355](https://github.com/Omega-JS-Stack/omega/issues/355)).
+
+**The direct lane publishes BOTH Pages shapes** ([#361](https://github.com/Omega-JS-Stack/omega/issues/361)): with a `brand.url` naming a domain of the brand's own it writes the CNAME and reports the custom domain; without one it deploys a PROJECT site — the address derived from the repo slug (`https://<owner>.github.io/<name>/`), the build mounted under the matching base path, and the CNAME step skipped entirely (an empty CNAME file would claim a domain). Plan and prefix come from ONE derivation, so the address a deploy reports and the path its build mounts under can never disagree. The slug itself resolves config first, then `GITHUB_REPOSITORY`, then the working tree's own `origin` remote — a brand cloned without a slug in its config still names its repo. The plan refuses only when nothing names the repo at all, and says so, naming only what actually resolves it: the config keys, the environment, the remote, or the CI dispatch lane. A project site still SETS `brand.url` — to its Pages URL, no trailing slash (`https://<owner>.github.io/<name>`) — because absolute URLs (canonical, `og:url`, hreflang alternates, the sitemap) build from it, and nothing derives it at build time; the direct lane WARNS on a project-site plan with `brand.url` unset, printing the exact value to set ([#366](https://github.com/Omega-JS-Stack/omega/issues/366)). **A `*.github.io` host is never read as a custom domain**, anywhere that reasons from `brand.url`: it keeps the project shape (no CNAME from either the deploy or the production build, and the path the URL carries IS the base path, ahead of the slug derivation), so taking that advice cannot move the site to the domain root and 404 every asset.
+
+**The web workflow cannot fill the runner's disk** ([#568](https://github.com/Omega-JS-Stack/omega/issues/568), ported from UJM 1.9.33 after somiibo-website failed every deploy for four days on `No space left on device` — the build passed and the gh-pages step took the runner down). `ubuntu-latest` gives about 14 GB, and four levers keep the scaffolded `build.yml` inside it: the checkout is **`fetch-depth: 1`** (the biggest one — a 4.3 GB packed history bought nothing, because NOTHING in an omega build reads git history: the service worker asks `git rev-parse --short HEAD`, which a depth-1 clone answers, `devkit`'s deploy asks `git diff --cached --quiet`, and `--direct` inits a fresh repo in `dist`); the gh-pages step sets **`force_orphan: true`**, so the published branch stays ONE commit instead of growing by a whole site per deploy (it holds build artifacts only — discarding its history is intended, and takes effect on the next deploy); **`df -h /` runs before the build and after it**, the after step with `if: always()` so it still reports when the build itself is what ran out of room; and the file-listing step is **`git ls-files`**, never `ls -R` — the old sweep printed node_modules and truncated the job log exactly when a failure needed reading. Pinned by `packages/web/test/workflow-disk.test.js`; the brand-root twin picks it up on the next omega verb.
+
+**Cache headers come from the EDGE, not from hosting** ([#751](https://github.com/Omega-JS-Stack/omega/issues/751)). A web deploy publishes to GitHub Pages, and GitHub Pages has no header configuration of any kind — nothing in `packages/web/src` or `packages/manager/src` writes a hosting config for the built site, and the one `firebase.json` a brand carries belongs to the BACKEND target (`packages/backend/templates/firebase.json`), and it declares `hosting.public: dist/public` plus the `omega_api` rewrites for `api.<domain>` — the API host only, and with no `headers` block. So the lifetime of a content-hashed bundle is set by Cloudflare cache rules, which the manager's edge service ships as framework defaults — hashed `/assets` for a year, HTML for a minute ([docs/manager/edge.md](../manager/edge.md)). A brand whose site does not sit behind Cloudflare gets GitHub Pages' own defaults and has nothing to tune.
+
+**The secrets those workflows read come from `.env`** ([#189](https://github.com/Omega-JS-Stack/omega/issues/189)): web's `omega deploy` precheck publishes the target's COMPOSED env — `composeTargetEnv({ targetDir, target: 'web' })`, the brand root's `.env` schema-filtered to the target's keys under an optional target `.env`, files only ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)) — to the brand repo's Actions secrets through `@omega.js/devkit/actions-secrets` (the `gh` CLI, values on stdin, never logged) and regenerates the workflow's env block — since [#627](https://github.com/Omega-JS-Stack/omega/issues/627) both the block and the published set derive from the env schema's `delivery` declarations (`@omega.js/config/env-delivery`), one `KEY: ${{ secrets.KEY }}` line per schema-delivered key, never an `.env` scan. Extension gained the same precheck step ([#680](https://github.com/Omega-JS-Stack/omega/issues/680)), and desktop's `push-secrets` joined them ([#682](https://github.com/Omega-JS-Stack/omega/issues/682)): all three bind the one devkit publisher (`@omega.js/devkit/target-secrets`) with their target string, and desktop adds the only shape difference — a `resolveValue` seam that base64-encodes its file-path signing secrets (`CSC_LINK=config/certs/dev-id.p12`) before the send. No target mints a PAT for this; `gh`'s auth session is the credential. So a CI build has exactly the keys the schema names for it, with no hand-created secrets and no hand-edited workflow. `--no-secrets` opts out; a repo-less/remote-less brand, a CI run, or a checkout that isn't the brand's declared repo skips loudly. **A step that runs only when a secret EXISTS gates on `env`, never on the secret** ([#715](https://github.com/Omega-JS-Stack/omega/issues/715)): the `secrets` context is available in no `if` expression, and one `if: ${{ secrets.X != '' }}` makes GitHub refuse to parse the whole file — a zero-job "workflow file issue" run on every push, however the workflow's own triggers are set. The key goes in the workflow-level `env:` block and the step reads `if: env.X != ''` (web's Cloudflare purge is the live case); consumers heal on the next verb's ensureTarget. Details: [docs/web/index.md](../web/index.md).
+
+## The verb — `omega deploy` on every target
+
+| Target | Behavior | Flags |
+|--------|----------|-------|
+| web | linked-local auto-detect → DIRECT lane; else sync (plain git commit + push — publishes nothing) → dispatch `build.yml` | `--dry-run` (print the exact plan, send nothing), `--local` (build only), `--no-sync`, `--direct` (force the direct lane: build + push dist to gh-pages, then Cloudflare purge) |
+| extension | linked-local auto-detect → `npm run release` (local build + store publish); else sync → dispatch `publish.yml` | `--dry-run`, `--no-sync` |
+| desktop | linked-local auto-detect → `npm run release:local` (local build + sign + publish); else `--dry-run` prints the dispatch / delegates to `omega release` (dispatch + live CI log streaming) | `--dry-run`, `--platforms` |
+| backend | artifact cleanup-policy pre-step → local-package staging (ALWAYS auto — file: deps pack into the artifact) → `firebase deploy` → public-invoker IAM fix | `--only <targets>` pass-through (e.g. `--only hosting` deploys on Spark where functions would demand Blaze) |
+| backend, `projectType: 'custom'` | REFUSED — a custom-server backend has no Cloud Functions to publish ([#584](https://github.com/Omega-JS-Stack/omega/issues/584)). The container host is the publisher; see the Render lane below | — |
+
+Every one of them runs the OMEGA license check once on the way — the production build for web/desktop/extension, the deploy itself for backend — and bakes the verdict into that artifact. What each target does with it, and what a keyless verdict costs: [publishing.md § The license check](publishing.md#the-license-check-320).
+
+### The brand-root fan-out — `omega deploy` at a brand root (cp251)
+
+At a brand root the dispatcher hands `omega deploy` to `@omega.js/manager`'s deploy command (`src/commands/deploy.js`), which fans out over the brand's targets — **not a new executor**: each target's own framework `omega deploy` verb runs (the table above), spawned sequentially with streamed output, cwd = the target dir, under the target's own Node.
+
+- **The DELIVERY lane runs first, once** ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)): before any target is spawned, the fan-out walks the same `BOOT_SERVICES` lane an `omega dev` boot walks (asked for by NAME, so the list can only be that one constant), so config, assets and certs reach the targets before anything publishes them. Errors there stop the run and nothing deploys; `--dry-run` reaches the lane too.
+- **Order: backend first, then web, then extension/desktop** — the API must be live before the surfaces that point at it.
+- **The target picker (consumed here, never forwarded)**: `--target=<target|targetDir>[,…]` names the exact set, the same picker `omega test` takes ([#780](https://github.com/Omega-JS-Stack/omega/issues/780)). A token matching nothing is an error, never a deploy-everything fallback. `--only`/`--except` are retired: passing either fails, naming `--target=`.
+- **Every other flag forwards verbatim** to each target's deploy (`--dry-run`, `--direct`, `--no-sync`, `--platforms`, …). Backend-target `--only` values (`--only hosting`) are firebase's own flag, target-level — run those from `targets/backend`.
+- **A failing target stops the run** (later targets depend on it); `--continue-on-error` overrides. Any failure → exit 1.
+- **Deliberate stays deliberate**: nothing invokes the brand-root verb automatically — it is only the human-typed command (scaffolded as the brand root's `deploy` npm script; the workspace service's `scripts` op guarantees the script exists — it mints a missing `deploy: "omega deploy"` and never rewrites script values).
+
+#### The container lane — a custom-server backend ([#584](https://github.com/Omega-JS-Stack/omega/issues/584))
+
+A backend declaring `targets.backend.projectType: 'custom'` runs its Express app on `PORT` for a container host (Render & co) instead of exporting Cloud Functions, so there is no `firebase deploy` to fan out to — and its framework verb refuses. The fan-out takes the SCRIPT lane instead, exactly as it does for a custom TARGET ([#603](https://github.com/Omega-JS-Stack/omega/issues/603)); the one home of that decision is the manager's `resolveTargetRun`, so the two lanes cannot drift.
+
+- **`npm run deploy` in the target dir** — whatever the brand put there IS the deploy: `render deploys create --service-id …`, a `git push` at the host's connected branch, a `docker` build-and-push. OMEGA does not name the host's command, because the host is the brand's choice, not the framework's.
+- **No framework flags are forwarded** (a package script has no contract for them), and for the same reason `--dry-run` stops at the PLAN rather than running a script that could not honor it.
+- **No `deploy` script = a loud skip**, naming the target and the verb. Nothing is marked failed: an absent script is a brand that has not wired its host yet, not a broken deploy.
+- **Order is unchanged** — the backend still deploys first, container or not; the surfaces that call the API go after it.
+- The other half is a trap worth knowing: the scaffolded backend `deploy` script is `npx omega deploy`, which in custom mode ends in the framework's refusal. That is deliberate — it fails loudly, on the line that says what to put there, instead of quietly deploying nothing.
+
+**Mirrored rule (Ian 2026-07-20): every deploy verb auto-detects linked local packages (`findLocalSpecs` — tree-wide, cp194) and takes its LOCAL-ARTIFACT lane**, loudly, so a linked brand ships the local framework without flags or errors; CI dispatch is only for registry-clean trees (`omega i live` restores them). Dry-runs show whichever plan would actually run. Sync is plain git via the shared `syncWorkingTree` (the old `npu sync` shell-out is gone — npu is a personal tool consumer machines don't have).
+
+## One command, repo to live — manage + deploy + verify ([#48](https://github.com/Omega-JS-Stack/omega/issues/48))
+
+A brand goes from repo to live through the EXISTING verbs, not a new one:
+`omega pipeline --deploy=web,backend` at a brand root runs the full manage
+cycle (provisioning every service), then each target's deploy leg, then the
+**verify sweep** — the last mile that proves the launch surface actually
+answers from the outside:
+
+| Check | What it proves | How |
+|---|---|---|
+| `verify:site` | the canonical URL serves a real page | HTTPS GET on `brand.url` → 200 + `text/html` + a non-trivial body (a 200 empty shell fails) |
+| `verify:domain` | the names resolve | DNS resolution of the apex (plus `www` when the brand owns the apex; a subdomain brand checks only its own host) |
+| `verify:cloudflare` | traffic arrives proxied, not origin-direct | `cf-ray` header, or `server: cloudflare` |
+
+Checks land in the pipeline scorecard as `verify:<name>` rows and are judged
+exactly like deploy legs — a failed check fails the run. The sweep runs
+automatically for whatever was deployed (`--deploy=web` → all three);
+`--verify` alone runs it WITHOUT deploying (the post-hoc "is it still up?"
+pass). Three states gate the sweep — a dry run (plan-only, like every other
+manager verb), a demo-* (emulator-only) brand, and a brand with no cloud
+project at all: each check records a gated skip with its reason and no
+transport is called, so the offline brands stay offline. Home: `packages/manager/src/lib/verify-live.js`
+(both transports — fetch and DNS — are injected seams, so the tests run
+fully offline).
+
+## Local frameworks in production artifacts (iterate without publishing)
+
+A brand linked to the local monorepo (`file:` specs) can ship the LOCAL framework code to production — no npm publish involved. This is a supported feature (Ian 2026-07-20: iterate fast on unproven framework changes without burning registry versions). Per target:
+
+| Target | Lane | How the local framework reaches production |
+|---|---|---|
+| backend | `omega deploy` (always direct) | `stage-local-packages`: every `file:` @omega.js dep — and, transitively, every @omega.js runtime dep of those that resolves through a node_modules SYMLINK — is `npm pack`ed — the package's REAL prepare runs, so vendoring makes the tarball self-contained — into `functions/omega_modules/*.tgz`; the staged manifest respells to the tarball and the lockfile regenerates, so Cloud Build installs the LOCAL framework verbatim; everything restores after the upload |
+| web | `omega deploy --direct` | the site builds HERE with the linked framework; only built output pushes to gh-pages (the CNAME + purge ride along) |
+| desktop | `npm run package` / `npm run release:local` | the build bundles the linked framework into the artifact; `release:local` signs + publishes that locally-built artifact |
+| extension | `npm run build` → `packaged/<browser>/` | same — the bundles carry the linked framework; upload the zip (or `OMEGA_IS_PUBLISH=true npm run build`) |
+
+The ONE lane that inherently needs the registry is CI-dispatch builds (web `omega deploy` without `--direct`; extension/desktop CI publish workflows): CI rebuilds from pushed source and cannot install `file:` specs — exactly what the tree-wide guard refuses, pointing back at the lanes above. cp241 made every packed tarball self-contained (vendoring in all six publishables), so the backend staging lane works for ANY linked @omega.js dep.
+
+**Every successful deploy records itself (cp196)**: `<target>` under the `deploy` section of the brand's `.omega/state.json` via `@omega.js/devkit/deploy-record` (`recordDeploy`/`readDeployRecord` — brand-root-resolved from any target dir; gitignored, per-machine). state.json is the ONE per-machine record file, sectioned per fact kind ([#479](https://github.com/Omega-JS-Stack/omega/issues/479)) — future record-shaped facts join it as sibling top-level sections, and deploy-record passes every section but its own through verbatim (caches, locks, certs and logs are not records and keep their own homes). #434 retired the file's old CONTENT, not the file: a brand that has not run the state-retirement migration yet keeps its config-shaped keys sitting beside the records, untouched, and its records are read in place. The one adoption left is the interim `.omega/deploys.json` the records spent 0.45.0 in ([#449](https://github.com/Omega-JS-Stack/omega/issues/449)): a brand still carrying that file has it folded into state.json on the first read or write — one-time and LOUD, ONE line naming what moved and that the old file was removed. **Multi-instance targets deploy per target, and records key per target**: each target's `omega deploy` ships ITS instance (`omega deploy` in `targets/website-admin` publishes the admin site) — the primary keeps the bare `<target>` key (adopted records stay valid) and any other instance records under `<target>:<id>` (`web:admin`), so the testing service's never-deployed/deployed-but-down split works per instance. The manager's testing service reads it to split **never deployed** (live-URL checks warn with a "run `omega deploy` when ready" nudge) from **deployed but down** (an honest error), and ADOPTS a record when a record-less brand's live URL answers — so fresh clones of long-deployed brands self-heal on their first manage run. Dry-runs never record.
+
+### Backend: local-package staging
+
+Cloud Build only installs what's inside the uploaded functions folder, and its
+buildpack runs `npm ci` (lockfile required) — so a local-first dep like
+`"@omega.js/backend": "file:../../../../../packages/backend"` can never deploy
+as-is. When `--only` includes functions, the deploy command stages the
+functions dir in place (`src/cli/utils/stage-local-packages.js`): each
+outside-the-folder `file:` dep is `npm pack`ed into `functions/omega_modules/*.tgz`
+(pack runs the package's prepare, so the tarball reflects current source),
+package.json is respelled to the tarball, and the lockfile is regenerated for
+the staged shape. After the deploy — success or failure — the original
+package.json + package-lock.json are restored verbatim and `omega_modules/` is
+removed. Published (registry) deps are untouched; a functions dir with no
+outside `file:` deps stages nothing. The Artifact Registry cleanup policy is
+ensured before deploying because firebase-tools otherwise exits 1 AFTER a
+successful functions deploy, which would skip the public-invoker fix.
+
+**"Local" is transitive ([#331](https://github.com/Omega-JS-Stack/omega/issues/331)).** A packed framework still declares its own
+dependencies by registry spec, and `@omega.js/client` is a real runtime
+dependency of `@omega.js/backend` that is never vendored — unpublished under
+the publish latch, so regenerating the lock 404'd on it and no deploy ran. The
+lane therefore packs the CLOSURE: after each target, its `@omega.js` runtime
+deps that resolve through a node_modules **symlink** (the local-era shape npm
+workspaces and `mgr i local` produce — the registry may have no copy of what
+the link points at) are packed too, and the staged manifest gets an npm
+`overrides` entry per packed transitive dep, since only an override redirects a
+NESTED requirement to the artifact beside it. A dep resolving to a real
+directory is a registry install and is left to Cloud Build. Result: lock
+regeneration never asks the registry for a local package.
+
+**A failing stage is loud and clean.** Any failure inside the lane restores the
+functions folder first (manifest, lockfile, `omega_modules/` — no half-staged
+tree) and then throws with the lane named, so the CLI's error path prints it
+and exits nonzero: nothing deploys, and the next run starts from the original
+shape.
+
+### Backend: resolved-config staging (#31)
+
+The config cascade (company ← brand ← local) is a walk-up over the local tree,
+and the upload boundary cuts it — Cloud Functions receives only the functions
+folder with its slim targets-only local config, so a deployed backend used to
+serve framework defaults ("My Brand"). Alongside package staging, the deploy
+command stages the resolved config (`src/cli/utils/stage-resolved-config.js`):
+`@omega.js/config`'s `composeTargetConfig(functionsPath, 'backend')` freezes
+the full interleave (brand shared ← brand target ← local shared ← local target)
+into the staged local file's shared namespace with a presence-only `targets`
+map, so the deployed runtime's own `defaults ← shared ← targets[backend]`
+merge yields EXACTLY the local resolution (framework defaults are NOT baked —
+the shipped package applies its own). The original file is restored verbatim
+after the deploy; targets with no brand layer are already self-contained and
+stage nothing.
+
+## Content-publish implies deploy
+
+`POST/PUT /admin/post` commit the article to the website repo, then dispatch
+its `build.yml` on the repo's default branch (shared helper
+`routes/admin/post/dispatch-deploy.js`). `settings.deploy: false` opts out;
+the outcome lands in the response as `deployDispatched` (dispatch failure is
+non-fatal — the post is committed either way, with a warning logged).
+
+## HTTP surface
+
+Any caller with a repo-scoped token can deploy without OMEGA installed:
+
+```
+POST https://api.github.com/repos/<owner>/<repo>/actions/workflows/build.yml/dispatches
+Authorization: Bearer <token>
+{"ref":"main"}
+```
+
+`repository_dispatch` (`event_type: omega-deploy`) triggers the same
+workflows — the channel the future CMS/hosted-company surface rides (D9).
+
+## Proven (cp98)
+
+Dry-runs from omega-brand print the exact dispatch for all three
+workflow-backed targets; a REAL deliberate deploy shipped hosting to the
+playground: `omega deploy --only hosting` (from `targets/backend`) → https://omegajs-playground.web.app
+serves 200 (functions stay Blaze-gated; live Actions runs stay Ian-gated on
+runner minutes). Suites: devkit deploy 7, corpus 1225, desktop 761, ext 99,
+web 80.

package/docs/shared/icons.md

@@ -0,0 +1,201 @@
+# Icons — one Font Awesome mechanism, every surface
+
+Authoring is plain Font Awesome markup, everywhere, with **zero setup** and
+nothing to learn ([#619](https://github.com/Omega-JS-Stack/omega/issues/619)):
+
+```html
+<i class="fa-solid fa-rocket"></i>
+<i class="fa-brands fa-github"></i>
+<i class="fa-sharp fa-light fa-bolt"></i>   <!-- Pro, when the brand supplies it -->
+<i class="omega-flag omega-flag-us"></i>    <!-- the flags namespace -->
+```
+
+```js
+el.className = 'fa-solid fa-play';   // set OR CHANGED via JS, any time —
+el.className = 'fa-solid fa-stop';   // the icon re-renders in place
+```
+
+There is no icon TAG, no `prerender_icons` list, no icon font, no CDN and no
+sprite system. SVGs land inline, sized `1em`/`currentColor` (they scale with
+font-size and inherit text color), `overflow="visible"` (FA 7 glyphs may
+overdraw their viewBox).
+
+**Emojis are text**, not icons: type the character. Nothing to build.
+
+## The two halves
+
+| Half | When | What happens |
+|------|------|--------------|
+| **Build inlining** | every icon present in the RENDERED HTML | The SVG is inlined into the `<i>`. Tiny payload, no flash, no runtime fetch, purge-safe. |
+| **Runtime upgrading** | every icon JS creates afterwards, and every class change | A MutationObserver fetches that ONE icon from the site's own set. Zero cost until an icon is actually requested. |
+
+Both halves emit exactly the same markup — the `<i>` carries
+`data-omega-fa="<style>/<name>"` and holds the SVG — so nothing can render one
+icon two ways, and the build's stamp is what tells the watcher to leave the
+element alone.
+
+## The pieces
+
+| Piece | Home | What it owns |
+|-------|------|--------------|
+| `icon-core` | `@omega.js/client/modules/icon-core.js` | Pure semantics: name/style validation, `parseIconClasses` (FA's family × weight class model, plus the `omega-flag-*` namespace), candidate lookup order (style dir → brands fallback), SVG root attributes, alias mapping, the package preference order (`PACKAGES`), the emitted dir name (`ICONS_DIR` — `icons`) |
+| `icon-renderer` | `@omega.js/client/modules/icon-renderer.js` | The ONE browser auto-render: scan + MutationObserver (insertions AND class changes), render/re-render/clear, caching. Transport-injected — callers pass one `resolve(name, style) → Promise<svg\|null>` |
+| Build-side reads | `@omega.js/devkit/icons` | `resolveFontAwesomeRoots()` (the root chain), `createIconLoader()` (read one icon out of it, aliases and brands fallback included), `emitIcons()` (ship the merged set into a build output), `ICONS_DIR` (icon-core's, re-exported so the build side has one import) |
+| Web's build pass | `@omega.js/web` `src/inline-icons.js` | The post-render transform over every rendered page (registered in `src/engine.js` beside the cache-breaker) |
+| Web's runtime | `@omega.js/web` `runtime/icons.js` | The transport + the watcher, started by `runtime/boot.js` on EVERY page, main bundle or not |
+
+The emitted set is `assets/icons/<style>/<name>.svg`, with the country flags
+one namespace over at `assets/icons/flags/<country>.svg`. It carries every
+style the brand's chain supplies: the free floor plus whatever Pro set the
+brand brought. Hosting deploys diff by hash and browsers fetch only the icons
+a page actually asks for.
+
+## Per-target transport (the only non-shared line)
+
+| Target | Resolver | Wired in |
+|--------|----------|----------|
+| Web pages | `fetch('/assets/icons/<style>/<name>.svg')` from the site's own origin — `omega dev` emits the set at boot too, so runtime icons resolve in dev | `runtime/icons.js`, started by `runtime/boot.js` `initialize()` |
+| Desktop renderers | IPC `desktop:fontawesome:get` → main's icon server (fs, works packaged/offline) | `renderer.js` `_wireFontAwesome` |
+| Extension pages | `fetch(chrome.runtime.getURL('assets/icons/…'))` — the packaged set (gulp `fontawesome` task emits it to `dist/assets/icons` at every brand build), fully offline | `src/lib/icons.js` (self-starting side-effect import) in popup/options/sidepanel/page |
+| Extension content scripts | NOT auto-wired on purpose — watching a HOST page's DOM would collide with sites using FA themselves. Injected UI imports `createIconRenderer` and `scan()`s its own container; `assets/icons/*` is in `web_accessible_resources` for exactly this | manual, per injected surface |
+
+**Build-time inlining is WEB's** — it is the only target that renders HTML at
+build. Desktop and extension pages ship their markup as authored and let the
+shared watcher fill it on first paint, out of the same emitted set.
+
+Web's `src/language-flags.js` additionally writes language-named copies into
+their own namespace (`assets/icons/flags/lang/en.svg` = the us flag — language
+and country codes collide, so `ar` is Arabic there and Argentina one level up),
+so the client-side footer language switcher fetches a flag by the row's own
+hreflang code with no map in the browser; a language the set has no flag for
+drops its `<img>` rather than showing a broken glyph.
+
+## Missing icons
+
+A name the icon set has no file for leaves the element **empty** — a missing
+icon is a content problem, never a crash and never a wrong-style fallback —
+and says so, loudly, where a human will see it:
+
+- **At build**, web's pass marks the element `data-omega-icon-missing="<style>/<name>"`
+  and warns once per name. The dev-only browser audit
+  (`core/js/core/dev-icon-audit.js`) turns each marker into a console error.
+- **At runtime**, a 404 is a `console.error` naming the icon **in development**
+  and a silent skip in production, where a missing icon must never be worse
+  than a missing icon.
+
+## Supplying Font Awesome Pro (brand-owned, never redistributed)
+
+Pro is NO omega package's dependency — publishing a package that vendors Pro
+SVGs violates the FA license. A brand that owns Pro brings its own copy; every
+surface picks it up automatically. Two routes:
+
+1. **npm** — authenticate the `@fortawesome` scope with your FA token
+   (fontawesome.com → Account → API Tokens), machine-global, never
+   committed:
+
+   ```bash
+   npm config set "@fortawesome:registry" "https://npm.fontawesome.com/"
+   npm config set "//npm.fontawesome.com/:_authToken" "YOUR-TOKEN"
+   ```
+
+   Then install `@fortawesome/fontawesome-pro` (monorepo root for dev; a
+   brand desktop app declares it as a **prod dependency** so it ships in
+   the packaged asar).
+
+2. **Download dir (no token)** — set `OMEGA_FONTAWESOME_ROOT` to a dir
+   containing `svgs/` (+ optionally `metadata/`): a fontawesome.com "Pro
+   for Web" download, or any style-shaped SVG tree. Lives in the brand
+   `.env` (the config env cascade delivers it to manager runs, web
+   builds, and desktop dev) or the shell profile for machine-global.
+
+Both can coexist — the chain is `[env dir, pro npm, free]`; missing files
+fall through per icon, so a solid-only download plus the npm package plus
+free compose seamlessly.
+
+## Styles
+
+Free floor: `solid` (default), `regular`, `brands`. Pro adds `light`,
+`thin`, and the `duotone` / `sharp` / `sharp-duotone` families, which
+compose with weights exactly like FA markup: `fa-sharp fa-light fa-play`
+→ `sharp-light/play` (bare `fa-duotone` → the `duotone` dir =
+duotone-solid). Style validation is by path-safe shape, not a whitelist —
+future FA families work with zero framework changes.
+
+A name the requested style has no file for falls back to `brands/`, so
+`<i class="fa-solid fa-github">` resolves without the author knowing which
+side of the set the mark lives on.
+
+## The sheet (one home, every surface)
+
+Icon PRESENTATION is one sheet:
+`packages/web/core/css/core/_custom-font-awesome.scss`. It owns the box, the
+size scale and the animation utilities, and it is deliberately self-contained
+(plain css, its own `$fa-sizes` map, its own keyframes) so the other targets
+take it verbatim instead of hand-writing a second copy that drifts.
+
+Desktop and extension VENDOR it at prepare through their package.json
+`omega.vendorAssets`, the same channel that carries the `--omega-*` tokens and
+the shell mechanics: it lands at `dist/assets/css/core/_fontawesome.scss` and
+the `omega-desktop` / `omega-extension` entries `@use` it. Nothing to import in
+a consumer project, and no second sheet to keep in sync (#183).
+
+## Animation
+
+`.fa-spin` turns an icon one full rotation a second, linear, forever;
+`.fa-bounce` hops it; `.fa-beat` swells it. All three are Font Awesome's own
+class names, so the muscle memory carries over, and each rides either half of
+the mechanism:
+
+```html
+<i class="fa-solid fa-spinner fa-spin"></i>
+```
+
+The keyframes are ours, not FA's: FA's own are built on a stack of
+custom-property knobs the sheet does not ship, so each utility gets a minimal
+implementation under FA's name.
+
+Under `prefers-reduced-motion: reduce` every one of them is dropped and the
+icon parks, the same deal every looping effect in the motion library
+makes.
+
+The rendered icon `<i>` is a square `1em` box with the glyph centered in
+it, so a spin (or any other transform) turns about the glyph's own center
+instead of a point down on the text baseline. Nothing to hand-fix, and no
+class to remember: the box keys on the `data-omega-fa` stamp the renderers
+leave themselves.
+
+The 12 size classes (`fa-2xs` … `fa-6xl`) are the sheet's `$fa-sizes` map, and
+`icon-core`'s modifier list carries the same roster, so a size class never
+reads as an icon name.
+
+## The rule for packaged markup
+
+**Framework markup names FREE icons only** (#3). Pro is brand-owned and never a
+package dependency, so a Pro-only name in a packaged theme, core layout, or
+default page renders nothing in every consumer that does not own Pro — and the
+consumer cannot fix it (the chain has no consumer-local icon dir). Stock chrome
+must build with zero missing-icon markers; a brand's OWN pages are free to use
+whatever its set resolves.
+
+## Testing
+
+- `packages/client/test/icon-core.test.js` — parsing/validation, the flags
+  namespace, plus the 12-size roster the modifier list must carry.
+- `packages/client/test/icon-renderer.test.js` — the shared watcher on a real
+  class list: insert, re-class, clear, flags.
+- `packages/devkit/test/{fontawesome-roots,icons}.test.js` — chain resolution,
+  the build-side loader, and the emission merge.
+- `packages/web/test/icons-inline.test.js` — the build pass (native markup,
+  modifiers, brands fallback, aliases, flags, misses), one real mini-site
+  build, and the grep guard that the retired mechanisms are gone.
+- `packages/web/test/icons-runtime.test.js` — the transport and the watcher:
+  a JS-created icon upgrading, a flag upgrading, dev loudness vs production
+  silence, and zero fetches for what the build already inlined.
+- `packages/desktop/src/test/suites/{main,renderer}/fontawesome.test.js` —
+  the real-DOM proof of the SHARED renderer + main's root chain and IPC
+  sanitization.
+- `packages/web/test/icons.test.js` — the compiled icon sheet: the square
+  box, `.fa-spin` / `.fa-bounce` / `.fa-beat`, their reduced-motion branch,
+  and the size roster derived from `$fa-sizes`.
+- `packages/{desktop,extension}/src/test/suites/build/icon-sheet.test.js`:
+  the vendored copy lands, and the entry compiles the box + the park.