@omega.js/desktop 0.52.0 → 0.54.0

package/dist/vendor/config/env.js

@@ -32,7 +32,6 @@ const path = require('node:path');
 const { findBrandRoot } = require('./load.js');
 const { resolveCompany } = require('./company.js');
 const { ENV_SCHEMA, envFileGroups, envSchemaEntry } = require('./env-schema.js');
-const { assertNoRetiredEnvKeys } = require('./env-retired.js');
 // The one vocabulary lives with the one environment module (#817); this file
 // re-exports it so the .env overlay names and the runtime answer stay one list.
 const { ENV_ENVIRONMENTS } = require('./environment.js');
@@ -322,11 +321,8 @@ function reloadEnv(startDir, { target, environment = envEnvironment() } = {}) {
 /**
  * Parse one .env file into a plain map. Missing files read as empty.
  *
- * The ONE place a `.env` layer is read, so it is also where a RETIRED key is
- * refused ([#893](https://github.com/Omega-JS-Stack/omega/issues/893)): there
- * is no dual-read, so a line for a key that moved into config is a value
- * nothing consults, and both readers below (the process cascade and the
- * artifact composer) fail on it naming the move.
+ * The layer is OPEN: an .env may carry keys outside omega, so a key nothing
+ * reads (a retired one included) is simply unread. `omega migrate` names those.
  *
  * @param {string|null} envPath
  * @returns {Object<string, string>} Parsed key → value.
@@ -334,10 +330,7 @@ function reloadEnv(startDir, { target, environment = envEnvironment() } = {}) {
 function parseEnvFile(envPath) {
   if (!envPath || !fs.existsSync(envPath)) return {};
 
-  const parsed = require('dotenv').parse(fs.readFileSync(envPath, 'utf8'));
-  assertNoRetiredEnvKeys(parsed, envPath);
-
-  return parsed;
+  return require('dotenv').parse(fs.readFileSync(envPath, 'utf8'));
 }
 
 /**
@@ -441,34 +434,53 @@ function composeTargetEnv({ targetDir, target, environment = envEnvironment() })
 }
 
 /**
- * Serialize one value as a double-quoted .env line — the serializer SSOT every
- * writeback rides (this composer, the manager's brand .env writeback and
- * scaffold stub). Backslashes, quotes and newlines escape so a multi-line blob
- * stays line-safe (dotenv expands `\n` back on read).
+ * Throw unless dotenv reads every given value back from `content` exactly as
+ * given. The error names the keys, never a value.
+ *
+ * @param {string} content - .env content holding the written lines.
+ * @param {Object<string, string>} values - The values those lines must carry.
+ */
+function assertEnvReadsBack(content, values) {
+  const parsed = require('dotenv').parse(content);
+  const changed = Object.keys(values).filter((key) => parsed[key] !== String(values[key]));
+  if (changed.length === 0) return;
+
+  throw new Error(`.env: the value of ${changed.join(', ')} would not read back unchanged from KEY="value" (dotenv expands a literal \\n or \\r, a quote followed by # ends the value, and a trailing backslash can run into the next line)`);
+}
+
+/**
+ * Serialize one value as a double-quoted .env line, the serializer SSOT every
+ * writeback rides. The value goes in raw (dotenv reads `"`, `\`, `'`, `#` back
+ * unchanged); a real newline or carriage return becomes `\n` / `\r`, which
+ * dotenv expands back. A value dotenv would read back changed, such as a
+ * literal backslash-n or backslash-r, throws naming the key only.
  *
  * @param {string} key - Env var name.
  * @param {string} value - Value to serialize.
  * @returns {string} `KEY="value"`.
  */
 function envLine(key, value) {
-  const escaped = String(value)
-    .replace(/\\/g, '\\\\')
-    .replace(/"/g, '\\"')
-    .replace(/\n/g, '\\n');
+  const raw = String(value).replace(/\n/g, '\\n').replace(/\r/g, '\\r');
+  const line = `${key}="${raw}"`;
+  assertEnvReadsBack(line, { [key]: value });
 
-  return `${key}="${escaped}"`;
+  return line;
 }
 
 /**
- * Serialize composed values as .env content — one envLine per key.
+ * Serialize composed values as .env content, one envLine per key. The whole
+ * file is judged too: a value ending in a backslash can carry dotenv's read
+ * into the next line, which no single line shows.
  *
  * @param {Object<string, string>} values
  * @returns {string} The file content, newline-terminated.
  */
 function serializeEnv(values) {
   const lines = Object.entries(values).map(([key, value]) => envLine(key, value));
+  const content = `${lines.join('\n')}\n`;
+  assertEnvReadsBack(content, values);
 
-  return `${lines.join('\n')}\n`;
+  return content;
 }
 
-module.exports = { loadEnv, reloadEnv, ENV_ENVIRONMENTS, envEnvironment, resolveEnvChain, envLayerFiles, loadEnvChain, loadEnvRoots, applyDeliverAs, composeTargetEnv, envLine, serializeEnv };
+module.exports = { loadEnv, reloadEnv, ENV_ENVIRONMENTS, envEnvironment, resolveEnvChain, envLayerFiles, loadEnvChain, loadEnvRoots, applyDeliverAs, composeTargetEnv, assertEnvReadsBack, envLine, serializeEnv };

package/dist/vendor/config/environment.js

@@ -3,8 +3,8 @@
  * ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)).
  *
  * Four calls, one implementation, one call form everywhere: `getEnvironment()`
- * plus `isDevelopment()` / `isProduction()` / `isTesting()`, mixed into a
- * framework's Manager with `attachTo()`. @omega.js/backend, @omega.js/desktop,
+ * plus `isDevelopment()` / `isProduction()` / `isTesting()`, called directly
+ * by every framework's `omega` instance and build module. @omega.js/backend, @omega.js/desktop,
  * @omega.js/extension and @omega.js/web each carried their own copy of this
  * logic, each with its own signal list and its own DEFAULT, and the copies
  * disagreed: desktop answered `production` with no signal while the extension
@@ -18,7 +18,7 @@
  *   neither env nor files, it is `config.environment`, the build fact every
  *   surface already bakes into `OMEGA_BUILD_JSON.config`
  *   ([#896](https://github.com/Omega-JS-Stack/omega/issues/896)), reached as
- *   `this.config.environment` off the Manager the call is made on. Nothing else
+ *   `this.config.environment` off the instance the call is made on. Nothing else
  *   is consulted: no `app.isPackaged`, no `manifest.update_url`, no `NODE_ENV`,
  *   no terminal sniffing.
  *
@@ -31,7 +31,7 @@
  * already resolves its config, through `setEnvironment()` below (the only
  * writer, so a fourth word can never reach the variable): the backend's boot
  * takes the .env cascade's ambient answer, the desktop and extension build
- * Managers take `production` under their build-mode flag and the ambient answer
+ * modules take `production` under their build-mode flag and the ambient answer
  * otherwise, and web's verbs name their own (`omega build` is production,
  * `omega dev` is development).
  *
@@ -64,7 +64,7 @@ function fromProcess() {
 
 /**
  * The browser input: the build fact baked into `OMEGA_BUILD_JSON.config`,
- * reached through the Manager the call was made on.
+ * reached through the instance the call was made on.
  * @param {object} [context] - the `this` of the call.
  * @returns {string|undefined} the raw value.
  */
@@ -75,7 +75,7 @@ function fromBakedConfig(context) {
 /**
  * The running environment, from the one input.
  *
- * @this {object} [context] - a Manager carrying the baked `config`.
+ * @this {object} [context] - an instance carrying the baked `config`.
  * @returns {'development'|'testing'|'production'} exactly one of the three.
  * @throws {Error} when neither input names one of the three.
  */
@@ -92,7 +92,7 @@ function getEnvironment() {
 }
 
 /**
- * @this {object} [context] - a Manager carrying the baked `config`.
+ * @this {object} [context] - an instance carrying the baked `config`.
  * @returns {boolean} true only in development (never in testing).
  */
 function isDevelopment() {
@@ -100,7 +100,7 @@ function isDevelopment() {
 }
 
 /**
- * @this {object} [context] - a Manager carrying the baked `config`.
+ * @this {object} [context] - an instance carrying the baked `config`.
  * @returns {boolean} true only in production, a real positive check.
  */
 function isProduction() {
@@ -108,7 +108,7 @@ function isProduction() {
 }
 
 /**
- * @this {object} [context] - a Manager carrying the baked `config`.
+ * @this {object} [context] - an instance carrying the baked `config`.
  * @returns {boolean} true only while a test lane runs this process.
  */
 function isTesting() {
@@ -136,7 +136,7 @@ function setEnvironment(value) {
 
 /**
  * The environment a NODE BUILD LANE is for, decided once for the two frameworks
- * whose build Manager names it at load (@omega.js/desktop and
+ * whose build module names it at load (@omega.js/desktop and
  * @omega.js/extension, which carried byte-identical copies of this expression).
  * Two rules, no sniffing:
  *
@@ -151,31 +151,13 @@ function setEnvironment(value) {
  * writer. This is the only default anywhere near this module, and it belongs to
  * a build lane alone: a READER still gets no default at all.
  *
- * @param {boolean} buildMode - The lane's build-mode flag (`Manager.isBuildMode()`).
+ * @param {boolean} buildMode - The lane's build-mode flag (`build.isBuildMode()`).
  * @returns {'development'|'testing'|'production'} the word that lane is for.
  */
 function buildLaneEnvironment(buildMode) {
   return buildMode ? 'production' : (fromProcess() || 'development');
 }
 
-/**
- * Mix the surface into a Manager constructor's prototype AND the constructor
- * itself, so `Manager.isTesting()` works statically too. The idiom every
- * framework already attaches with.
- *
- * @param {Function} Manager - the constructor to extend.
- */
-function attachTo(Manager) {
-  Manager.prototype.getEnvironment = getEnvironment;
-  Manager.prototype.isDevelopment  = isDevelopment;
-  Manager.prototype.isProduction   = isProduction;
-  Manager.prototype.isTesting      = isTesting;
-  Manager.getEnvironment = getEnvironment;
-  Manager.isDevelopment  = isDevelopment;
-  Manager.isProduction   = isProduction;
-  Manager.isTesting      = isTesting;
-}
-
 module.exports = {
   ENV_ENVIRONMENTS,
   ENVIRONMENT_VAR,
@@ -185,5 +167,4 @@ module.exports = {
   isTesting,
   setEnvironment,
   buildLaneEnvironment,
-  attachTo,
 };

package/dist/vendor/config/index.js

@@ -9,12 +9,11 @@
  * `type`, and any shared key inside a target entry overrides the shared value
  * for that surface (one agnostic deep merge).
  *
- * Replaces the per-framework config zoo (UJM's _config.yml + JSON split,
- * EM's config/electron-manager.json, @omega.js/backend's backend-manager-config.json,
- * BXM's config) with NO dual-read: each framework flips to omega.json5
- * outright and legacy brands migrate their file once (docs/shared/config.md has
- * the mapping tables). omega-manager's disperse enumerates SHARED_SECTIONS
- * instead of hardcoding per-target mapping blocks.
+ * Replaces the per-framework legacy config files with NO dual-read: each
+ * framework reads omega.json5 outright and legacy brands migrate their file
+ * once (docs/shared/config.md has the mapping tables). @omega.js/manager's
+ * disperse enumerates SHARED_SECTIONS instead of hardcoding per-target mapping
+ * blocks.
  *
  * Private workspace package — vendored/bundled into the published frameworks
  * at prepare time, never published on its own.
@@ -24,19 +23,17 @@ const { TARGETS, CUSTOM_TARGET_TYPE, isCustomTargetEntry, BACKEND_PROJECT_TYPES,
 const { clientConfig, CLIENT_FACT_KEYS } = require('./client-config.js');
 const { deepMerge } = require('./merge.js');
 const { findSecretKeys, SECRET_KEY_PATTERN } = require('./secrets.js');
-const { findRetiredKeys, RETIRED_KEYS, RETIRED_PATHS } = require('./retired-keys.js');
 const { chosenProvider } = require('./providers.js');
-const { validateConfig, runSchema, formatErrors, resolvedBrandHost } = require('./validate.js');
-const { loadConfig, composeTargetConfig, hasOmegaConfig, resolveConfigPath, getEnabledTargets, findBrandRoot, findBrandConfigPath, resolveBrandRoot, FILE_NAME, CONFIG_LOCATIONS } = require('./load.js');
-const { ENV_ENVIRONMENTS, ENVIRONMENT_VAR, getEnvironment, isDevelopment, isProduction, isTesting, setEnvironment, buildLaneEnvironment, attachTo: attachEnvironment } = require('./environment.js');
-const { loadEnv, reloadEnv, envEnvironment, resolveEnvChain, envLayerFiles, loadEnvChain, loadEnvRoots, applyDeliverAs, composeTargetEnv, envLine, serializeEnv } = require('./env.js');
+const { validateConfig, undeclaredPaths, undeclaredAuthoredPaths, runSchema, formatErrors, resolvedBrandHost } = require('./validate.js');
+const { loadConfig, composeTargetConfig, hasOmegaConfig, resolveConfigPath, overlayPath, getEnabledTargets, findBrandRoot, findBrandConfigPath, resolveBrandRoot, FILE_NAME, CONFIG_LOCATIONS } = require('./load.js');
+const { ENV_ENVIRONMENTS, ENVIRONMENT_VAR, getEnvironment, isDevelopment, isProduction, isTesting, setEnvironment, buildLaneEnvironment } = require('./environment.js');
+const { loadEnv, reloadEnv, envEnvironment, resolveEnvChain, envLayerFiles, loadEnvChain, loadEnvRoots, applyDeliverAs, composeTargetEnv, assertEnvReadsBack, envLine, serializeEnv } = require('./env.js');
 const { ENV_SCHEMA, ENV_GROUPS, DELIVERY_MODES, envFileGroups, envSchemaEntry, envKeysForTarget, generatedEnvKeys, requiredEnvKeys, envKeysByGroup } = require('./env-schema.js');
 const { WORKFLOW_OWNED_KEYS, deliveredKeys, workflowSecretKeys, envFileKeys, artifactEnvValues, bakeKeys, bakeSourceKeys, publishSecretKeys, renderSecretsBlock, renderEnvFileKeys } = require('./env-delivery.js');
 const { checkEnvRules } = require('./env-rules.js');
-const { RETIRED_ENV_KEYS, findRetiredEnvKeys, assertNoRetiredEnvKeys } = require('./env-retired.js');
 const { resolveCompany, recordBrand, readRegistry, registryFile, COMPANY_DIR, COMPANY_RESOLVED_FILE, COMPANY_SELF } = require('./company.js');
-const { applyConfigEdits, writeConfigValues, applyConfigRemovals, removeConfigValues } = require('./edit.js');
-const { schemaDefaults, missingDefaults, defaultComments } = require('./defaults.js');
+const { applyConfigEdits, writeConfigValues, writeConfigFileValues, applyConfigRemovals, removeConfigValues, removeConfigFileValues } = require('./edit.js');
+const { schemaDefaults, missingDefaults, defaultComments, planMerge, setAtPath } = require('./defaults.js');
 const { applyCanonicalOrder, CANONICAL_TOP_LEVEL_ORDER } = require('./order.js');
 const { resolveSeedMode } = require('./seed.js');
 const { resolveHook, loadHook } = require('./hooks.js');
@@ -56,6 +53,7 @@ module.exports = {
   composeTargetConfig,
   hasOmegaConfig,
   resolveConfigPath,
+  overlayPath,
   getEnabledTargets,
   findBrandRoot,
   findBrandConfigPath,
@@ -79,8 +77,7 @@ module.exports = {
   ENV_ENVIRONMENTS,
   // The ONE environment module every target answers from (#817): one input
   // (OMEGA_ENVIRONMENT on Node, the baked config.environment in a browser),
-  // no per-surface default, a missing input is a loud error. `attachEnvironment`
-  // is its attachTo(), named for what it mixes in.
+  // no per-surface default, a missing input is a loud error.
   ENVIRONMENT_VAR,
   getEnvironment,
   isDevelopment,
@@ -88,9 +85,8 @@ module.exports = {
   isTesting,
   setEnvironment,
   // The word a node BUILD LANE is for, from its build-mode flag and whatever a
-  // parent lane named: the desktop and extension build Managers set this
+  // parent lane named: the desktop and extension build modules set this
   buildLaneEnvironment,
-  attachEnvironment,
   // The AMBIENT answer a lane resolves when nothing named one for it, and the
   // producer of the input above
   envEnvironment,
@@ -104,6 +100,7 @@ module.exports = {
   composeTargetEnv,
 
   // The .env serializer SSOT — every writeback renders through these
+  assertEnvReadsBack,
   envLine,
   serializeEnv,
 
@@ -139,13 +136,6 @@ module.exports = {
   // `requiredWhen`; every consumer calls it, none keeps its own if
   checkEnvRules,
 
-  // The .env half of the retired-key register (#893): a key that moved into
-  // config fails the layer that still declares it, naming the move. Every
-  // `.env` read goes through parseEnvFile, so nothing can miss the check
-  RETIRED_ENV_KEYS,
-  findRetiredEnvKeys,
-  assertNoRetiredEnvKeys,
-
   // The ONE company resolver (#677): `company: { id }` in, the company's public
   // facts plus its tree on this machine out. The config chain, the .env chain,
   // owner hooks and the desktop signing tree all inherit through its `file()`,
@@ -165,8 +155,10 @@ module.exports = {
   // Writeback (comment-preserving edits + canonical top-level key order)
   applyConfigEdits,
   writeConfigValues,
+  writeConfigFileValues,
   applyConfigRemovals,
   removeConfigValues,
+  removeConfigFileValues,
   applyCanonicalOrder,
   CANONICAL_TOP_LEVEL_ORDER,
 
@@ -174,6 +166,8 @@ module.exports = {
   // heal list the manage walk materializes into a brand's omega.json5
   schemaDefaults,
   missingDefaults,
+  planMerge,
+  setAtPath,
   defaultComments,
 
   // Layer-aware consumer seeding (brand target = no local-layer config at all)
@@ -247,6 +241,8 @@ module.exports = {
 
   // Validation
   validateConfig,
+  undeclaredPaths,
+  undeclaredAuthoredPaths,
   runSchema,
   formatErrors,
 
@@ -257,9 +253,6 @@ module.exports = {
 
   findSecretKeys,
   SECRET_KEY_PATTERN,
-  findRetiredKeys,
-  RETIRED_KEYS,
-  RETIRED_PATHS,
 
   // The one provider shape (#425) — `role.providers.<provider>`, where key
   // presence is the pick and `false` is the deliberate off switch

package/dist/vendor/config/load.js

@@ -58,8 +58,7 @@
  *
  * Secrets hard-fail: raw files are scanned BEFORE any merge — a secret in
  * any target section (requested or not) throws. Schema findings come back
- * as `errors` so callers pick their strictness (audit throws, boot warns —
- * EM's proven two-mode usage).
+ * as `errors` so callers pick their strictness (audit throws, boot warns).
  */
 
 const fs = require('node:fs');
@@ -67,7 +66,7 @@ const path = require('node:path');
 const JSON5 = require('json5');
 
 const { deepMerge, isPlainObject } = require('./merge.js');
-const { resolveCompany, recordBrand } = require('./company.js');
+const { resolveCompany, recordBrand, RESOLVED_COMPANY_KEYS } = require('./company.js');
 const { findSecretKeys } = require('./secrets.js');
 const { validateConfig } = require('./validate.js');
 const { TARGETS } = require('./schema.js');
@@ -135,10 +134,22 @@ function resolveOverlayEnvironment(environment, fallback) {
 function resolveOverlayPath(basePath, environment) {
   if (!basePath || !environment) return null;
 
-  const overlay = path.join(path.dirname(basePath), `${path.basename(FILE_NAME, '.json5')}.${environment}.json5`);
+  const overlay = overlayPath(basePath, environment);
   return fs.existsSync(overlay) ? overlay : null;
 }
 
+/**
+ * The ONE spelling of a layer's environment overlay: `omega.<environment>.json5`
+ * beside its base file, whether or not either exists. Every reader and writer
+ * of an overlay names it through here.
+ * @param {string} basePath - The layer's omega.json5 path.
+ * @param {string} environment - One of ENV_ENVIRONMENTS.
+ * @returns {string} Absolute overlay path.
+ */
+function overlayPath(basePath, environment) {
+  return path.join(path.dirname(basePath), `${path.basename(FILE_NAME, '.json5')}.${environment}.json5`);
+}
+
 /**
  * Cheap probe: does this project have an omega.json5 at all? Frameworks use it
  * to fail soft in non-consumer dirs (seeded-empty config); tooling uses it as
@@ -302,10 +313,6 @@ function stripTargets(config) {
   return shared;
 }
 
-// The `company` keys the LOADER fills (#677): authored, they would be
-// overwritten at every load, so an author hears about it at the file.
-const RESOLVED_COMPANY_KEYS = ['name', 'url', 'images'];
-
 /**
  * The company keys nobody types, refused where a human writes them: the BRAND
  * file and the COMPANY file (#677). The local layer is deliberately exempt,
@@ -738,4 +745,4 @@ function composeTargetConfig(projectDir, target, options) {
   return { config, files: { local: localPath, brand: brandPath, company: companyPath } };
 }
 
-module.exports = { loadConfig, composeTargetConfig, hasOmegaConfig, resolveConfigPath, getEnabledTargets, findBrandRoot, findBrandConfigPath, resolveBrandRoot, FILE_NAME, CONFIG_LOCATIONS, TARGET_SUBDIRS };
+module.exports = { loadConfig, composeTargetConfig, hasOmegaConfig, resolveConfigPath, overlayPath, getEnabledTargets, findBrandRoot, findBrandConfigPath, resolveBrandRoot, FILE_NAME, CONFIG_LOCATIONS, TARGET_SUBDIRS };

package/dist/vendor/config/platforms.js

@@ -181,7 +181,7 @@ function enabledFormats(config, target) {
 
 /**
  * The product name a desktop target packages under: the same derivation
- * @omega.js/desktop's `Manager.getConfig()` applies (`app.productName` then
+ * @omega.js/desktop's `build.getConfig()` applies (`app.productName` then
  * `brand.name`), so the website reads the name the packager actually used.
  *
  * @param {object} config - Desktop-shaped config (`{ app, brand }`).

package/dist/vendor/config/repo.js

@@ -1,31 +1,14 @@
 /**
- * @omega.js/config repo: the ONE derivation of every repo a brand owns
- * ([#883](https://github.com/Omega-JS-Stack/omega/issues/883)).
- *
- * ONE config block says where a brand hosts its code:
- *
- *   repo: { provider: 'github', org: 'Acme-Org' }
- *
- * and nothing else. Presence of the block enables the repo service, exactly
- * as a target's key presence enables a target; `provider` defaults to `github`
- * and `org` is the only typed value. No repo NAME is ever configured: every
- * name derives from the `<brand.id>-<role>` rule (Ian 2026-09-07,
- * [#809](https://github.com/Omega-JS-Stack/omega/issues/809)), one function per
- * role, so nobody types a repo name to get the right one:
- *
- *   - `<brand.id>-omega`    the SOURCE monorepo (`sourceRepo`)
- *   - `<brand.id>-releases` the public release channel (`releasesRepo`)
- *   - `<brand.id>-<name>`   one per web target that GitHub hosts (`websiteRepo`)
- *
- * A repo name that must differ is a brand id that must differ: the override
- * keys (`repo.providers.github.repo`, the top-level `github` block,
- * `targets.<name>.github.repo`, `targets.desktop.releases.owner/repo`) are
- * retired, each with a row in retired-keys.js.
- *
- * Visibility is NOT in omega.json5 either: the brand root's package.json
- * `private` field is the one statement of it (`brandVisibility`), absent
- * meaning private, because every brand monorepo is private by default
- * (Ian 2026-09-11).
+ * @omega.js/config repo: the ONE derivation of every repo a brand owns. One
+ * block says where a brand hosts its code, `repo: { provider: 'github', org }`:
+ * its presence enables the repo service, `provider` defaults to `github`, and
+ * `org` is the only typed value. No repo NAME is configured anywhere; each
+ * derives from `<brand.id>-<role>`, one function per role: `<brand.id>-omega`
+ * the source monorepo (`sourceRepo`), `<brand.id>-releases` the public release
+ * channel (`releasesRepo`), `<brand.id>-<name>` per GitHub-hosted web target
+ * (`websiteRepo`). The old override keys are rows in @omega.js/manager's
+ * src/migrate/retired-keys.js. Visibility is the brand root package.json's
+ * `private` field (`brandVisibility`), absent meaning private.
  */
 
 const fs = require('node:fs');

package/dist/vendor/config/schema-client.js

@@ -0,0 +1,64 @@
+/**
+ * Schema rules for the `client` blob: the @omega.js/client settings bag a web
+ * target carries. The bag is OPEN (the client normalizes it against its own
+ * defaults); only the keys a brand authors, and consent, are typed.
+ */
+
+const CLIENT_RULES = [
+  {
+    path:        'client',
+    type:        'object',
+    open:        true,
+    required:    false,
+    description: "The @omega.js/client runtime settings (auth, firebase, exitPopup, …), merged over the client's own defaults. Open by design: only consent and the keys a brand authors are typed below.",
+  },
+
+  // Consent decides whether a visitor is tracked at all: a typo that silently
+  // disabled the banner would ship a site with no consent gate and no error.
+  {
+    path:        'client.consent.enabled',
+    type:        'boolean',
+    required:    false,
+    default:     true,
+    description: 'The consent banner + the provider-script gate (default true). false ships NO banner: legal only for a site that loads no analytics/marketing provider at all.',
+  },
+  {
+    path:        'client.consent.config.position',
+    type:        'string',
+    required:    false,
+    enum:        ['bottom-left', 'bottom-right', 'bottom'],
+    description: "Where the panel sits. 'bottom' is the centered full-width form.",
+  },
+  {
+    path:        'client.consent.config.content',
+    type:        'object',
+    required:    false,
+    description: "Banner copy: message, panelIntro, accept, customize, acceptAll, acceptNone (a literal `{terms}`/`{cookies}` links the terms/cookie-policy page). Category labels are framework copy: a brand renames the buttons, not the categories.",
+  },
+
+  // The keys a BRAND authors: each one reaches the client payload and changes
+  // what the site does, so each one is typed.
+  {
+    path:        'client.auth.config.policy',
+    type:        'string',
+    required:    false,
+    enum:        ['authenticated', 'unauthenticated', 'disabled'],
+    description: "Who a page is FOR: 'authenticated' redirects a signed-out visitor to the signin route, 'unauthenticated' redirects a signed-in one away, 'disabled' skips the auth module entirely (a vert iframe). Absent = no policy, which is the site-wide answer: the auth/admin layouts set theirs in page frontmatter, so a brand only sets this to blanket a whole site.",
+  },
+  {
+    path:        'client.exitPopup.enabled',
+    type:        'boolean',
+    required:    false,
+    default:     true,
+    description: 'The exit-intent offer popup (default true). false ships no popup at all; its copy, timeout and avatars live under client.exitPopup.config.',
+  },
+  {
+    path:        'client.serviceWorker.enabled',
+    type:        'boolean',
+    required:    false,
+    default:     true,
+    description: 'Registers the site service worker (default true): the offline/refresh lane and the push-notification registration ride it. false unregisters any worker the visitor already has.',
+  },
+];
+
+module.exports = { CLIENT_RULES };

package/dist/vendor/config/schema-cloud.js

@@ -0,0 +1,38 @@
+/**
+ * Schema rules for `cloud.config`, the provider's web-app config. For firebase
+ * it is the console's config verbatim: public by design (the web API key is no
+ * secret), and every key the Firebase web SDK takes is typed.
+ */
+
+const FIREBASE_WEB_KEYS = {
+  apiKey: 'The web API key the Firebase SDKs identify the project with. Public by design: it ships in every browser bundle.',
+  authDomain: "The Firebase Auth domain: the BRAND host, where the web build self-hosts /__/auth/* (docs/shared/config.md → authDomain).",
+  databaseURL: 'The Realtime Database URL, for a project that has one.',
+  storageBucket: 'The default Cloud Storage bucket.',
+  messagingSenderId: 'The Cloud Messaging sender id web push registers against.',
+  appId: 'The Firebase web app id.',
+  measurementId: 'The Google Analytics measurement id Firebase links to the web app.',
+};
+
+const CLOUD_CONFIG_RULES = [
+  {
+    path:        'cloud.config',
+    type:        'object',
+    required:    false,
+    description: 'Provider app config. For firebase: the web-app config verbatim from the console. Public by design: the web API key is not a secret.',
+  },
+  {
+    path:        'cloud.config.projectId',
+    type:        'string',
+    required:    false,
+    description: 'Drives auth, emulator project selection, analytics uuidv5 namespace, remote-config URL fallbacks.',
+  },
+  ...Object.entries(FIREBASE_WEB_KEYS).map(([key, description]) => ({
+    path:        `cloud.config.${key}`,
+    type:        'string',
+    required:    false,
+    description,
+  })),
+];
+
+module.exports = { CLOUD_CONFIG_RULES };