@omega.js/backend 0.1.0

package/dist/cli/utils/target-checks.js

@@ -0,0 +1,161 @@
+/**
+ * target-checks — the AUDIT half of the retired `omega setup`
+ * ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)).
+ *
+ * The setup command had two halves: write the local files if missing (now
+ * `ensureTarget()`, which every verb runs through `ensureStaged`) and CHECK
+ * the target, healing what it can. The checks are a test lane, so they ride
+ * `omega test`: the registry under cli/commands/setup-tests runs before the
+ * emulator suite, and a check nothing can fix halts the run.
+ *
+ * The registry reads its state off the `main` object (`self.package`,
+ * `self.gitignore`, `self.omegaConfigJSON`, `self.projectId`, the generated
+ * rules on `self.default`), so `loadFiles` + `getRulesFile` below are the
+ * preamble every run needs — the same one `runSetup()` did before the split.
+ */
+const path = require('path');
+const chalk = require('chalk').default;
+const jetpack = require('fs-jetpack');
+const JSON5 = require('json5');
+const omegaConfig = require('../../vendor/config/index.js');
+
+const ui = require('./ui');
+
+// Rules-marker regex shared with the rules checks (used by getRulesFile)
+const { omegaAllRulesRegex } = require('../commands/setup-tests/helpers.js');
+
+// The rules SCHEMA version — the stamp in `database.rules.json`'s open marker
+// and in the compiled firestore artifact's header. Owned by the rules compiler
+// (src/cli/utils/compile-rules.js) and re-exported here, the address every
+// caller already knows.
+const { RULES_VERSION } = require('./compile-rules');
+
+/** Read a JSON5 file, `{}` when it is missing or empty. */
+function loadJSON(filePath) {
+  const contents = jetpack.read(filePath);
+  return contents ? JSON5.parse(contents) : {};
+}
+
+function hasContent(object) {
+  return Object.keys(object).length > 0;
+}
+
+/**
+ * Load the target files every check reads onto `main`.
+ *
+ * @param {object} main - The CLI's Main instance (firebaseProjectPath).
+ * @returns {object} The same main, for chaining.
+ */
+function loadFiles(main) {
+  // THE target manifest (target root — scripts + runtime deps; the staged
+  // dist/package.json derives from it at stage time)
+  main.package = loadJSON(`${main.firebaseProjectPath}/package.json`);
+  main.firebaseJSON = loadJSON(`${main.firebaseProjectPath}/firebase.json`);
+  main.firebaseRC = loadJSON(`${main.firebaseProjectPath}/.firebaserc`);
+  // Target root — where setup-tests/remoteconfig-template-file.js writes it.
+  // The old `functions/` spelling is the pre-src/dist layout and always
+  // read {}.
+  main.remoteconfigJSON = loadJSON(`${main.firebaseProjectPath}/remoteconfig.template.json`);
+  main.projectPackage = main.package;
+  // Resolved through @omega.js/config (local ← brand root, no framework-defaults
+  // layer). Throws on secrets/parse errors (the checks ARE the audit — hard
+  // failures are correct here). The omega-config check validates the resolved
+  // config against the shared schema (friction #5). A brand target carries no
+  // file of its own — the brand root's config resolves alone.
+  main.omegaConfigJSON = (omegaConfig.hasOmegaConfig(main.firebaseProjectPath)
+    || omegaConfig.findBrandRoot(main.firebaseProjectPath))
+    ? omegaConfig.loadConfig(main.firebaseProjectPath, 'backend').config
+    : {};
+  main.gitignore = jetpack.read(`${main.firebaseProjectPath}/.gitignore`) || '';
+
+  return main;
+}
+
+/**
+ * Generate the realtime-database rules the rules checks compare against, onto
+ * `main.default`. firestore.rules is COMPILED (#255), not marker-managed: the
+ * brand's file is pure source and the framework half ships in templates/, so
+ * nothing here generates it. database.rules.json keeps the marker model.
+ *
+ * @param {object} main - The CLI's Main instance.
+ * @returns {object} `main.default`, carrying the generated rules.
+ */
+function getRulesFile(main) {
+  main.default.databaseRulesWhole = jetpack
+    .read(path.resolve(`${__dirname}/../../../templates/database.rules.json`))
+    .replace('(v0.0.0)', `(v${RULES_VERSION})`);
+  main.default.databaseRulesCore = main.default.databaseRulesWhole.match(omegaAllRulesRegex)[0];
+
+  return main.default;
+}
+
+/**
+ * Run the check registry against the target, healing what it can.
+ *
+ * Every check reports through `main.test()` — pass, warn, or fix-then-pass —
+ * and an unfixable one calls `main.haltSetup()`, which prints the summary and
+ * exits 1. Loud by design: a target that cannot be made whole must not go on
+ * to boot an emulator against it.
+ *
+ * @param {object} main - The CLI's Main instance.
+ * @returns {Promise<{ passed: boolean, total: number }>}
+ */
+async function runTargetChecks(main) {
+  const testRegistry = require('../commands/setup-tests');
+  const helpers = require('../commands/setup-tests/helpers');
+
+  // Fresh state for this run (the check runner records into the summary and
+  // prints it on a hard failure; we print it here on success).
+  main.testCount = 0;
+  main.testTotal = 0;
+  main.warnCount = 0;
+  main.setupSummary = new ui.Summary().start();
+
+  loadFiles(main);
+
+  if (!hasContent(main.package)) {
+    ui.status('fail', `Missing ${chalk.bold('package.json')} at the target root`);
+    ui.note(`Run an OMEGA verb from a backend target root (a package.json with the ${chalk.bold('@omega.js/backend')} dependency).`);
+    process.exit(1);
+  }
+
+  getRulesFile(main);
+  // The rules SCHEMA version rides in the block's open marker:
+  // `// ========== OMEGA Rules (v2.0.0) ==========`
+  main.default.rulesVersionRegex = new RegExp(`========== OMEGA Rules \\(v${RULES_VERSION.replace(/\./g, '\\.')}\\) ==========`);
+
+  // Resolve project info — the checks read projectId (demo-* gating, live
+  // index sync, campaign seeding). ensureTarget() guarantees .firebaserc.
+  main.projectId = main.firebaseRC.projects?.default;
+  main.projectUrl = `https://console.firebase.google.com/project/${main.projectId}`;
+  main.apiUrl = `https://api.${(main.omegaConfigJSON.brand?.url || '').replace(/^https?:\/\//, '')}`;
+
+  const tests = testRegistry.getTests({
+    main,
+    package: main.package,
+    packageJSON: main.packageJSON,
+    gitignore: main.gitignore,
+    hasContent: helpers.hasContent,
+    isLocal: helpers.isLocal,
+    loadJSON: helpers.loadJSON,
+  });
+
+  // Expose the total count so the per-check `[N]` prefix can right-align its
+  // width (single- vs double-digit indices stay aligned).
+  main.testTotalExpected = tests.length;
+
+  for (const test of tests) {
+    await main.test(
+      test.getName(),
+      async () => test.run(),
+      async () => test.fix(),
+      { details: () => test.getWarning() },
+    );
+  }
+
+  main.setupSummary.print();
+
+  return { passed: main.testCount + main.warnCount === main.testTotal, total: main.testTotal };
+}
+
+module.exports = { runTargetChecks, loadFiles, getRulesFile, RULES_VERSION };

package/dist/cli/utils/target.js

@@ -0,0 +1,24 @@
+/**
+ * Which stack a CLI subcommand talks to — the ONE home of that rule.
+ *
+ * Ruling (#51, uniformity amendment Ian 2026-07-30): EVERY subcommand targets
+ * the emulator by default — reads and writes alike, one rule for the whole
+ * surface — and reaches live only with an explicit `--production`. A habitual
+ * `--emulator` is accepted (it names the default) but consults nothing.
+ */
+
+/**
+ * Resolve the stack a subcommand should run against.
+ *
+ * @param {object} argv - Parsed CLI flags (`production`)
+ * @returns {{ emulator: boolean, label: string }} label is 'emulator' or 'production'
+ */
+function resolveTarget(argv) {
+  argv = argv || {};
+
+  const emulator = !argv.production;
+
+  return { emulator, label: emulator ? 'emulator' : 'production' };
+}
+
+module.exports = { resolveTarget };

package/dist/cli/utils/ui.js

@@ -0,0 +1,292 @@
+const chalk = require('chalk').default;
+
+/**
+ * Shared CLI styling helpers — the SSOT for @omega.js/backend's console output look.
+ *
+ * Mirrors the OMEGA Manager (omega-manager) styling conventions so every @omega.js/backend
+ * command renders with the same dividers, indentation, timestamps, colors, and
+ * status symbols. Pull these helpers into any command (setup/serve/deploy/test/
+ * emulator/...) instead of hand-rolling chalk + console.log.
+ *
+ * Conventions (matching OMEGA):
+ *   - 70-char `━` horizontal rules wrap section titles.
+ *   - Indentation is 2 spaces per level (level 1 = 2 spaces, level 2 = 4, ...).
+ *   - Dimmed labels (`ID:`, `URL:`, `Local:`) with normal-weight values.
+ *   - Status symbols: → (running) ✓ (pass) ✗ (fail) ⊘ (skip) ⚠ (warn) ✅ (done).
+ *   - Timestamps via `new Date().toLocaleTimeString()` (e.g. "7:47:12 PM").
+ */
+
+// Divider width + character (OMEGA uses 70 × `━`).
+const RULE_WIDTH = 70;
+const RULE_CHAR = '━';
+
+// Status symbols — the single source of truth for @omega.js/backend's CLI iconography.
+const SYMBOLS = {
+  running: '→',
+  pass: '✓',
+  fail: '✗',
+  skip: '⊘',
+  warn: '⚠',
+  done: '✅',
+  rocket: '🚀',
+  add: '+',
+  change: '↻',
+};
+
+/** Two-space-per-level indentation. */
+function indent(level = 1) {
+  return '  '.repeat(level);
+}
+
+/** Locale time string, e.g. "7:47:12 PM". */
+function timestamp() {
+  return new Date().toLocaleTimeString();
+}
+
+/** A full-width horizontal rule in the given chalk color (default cyan). */
+function rule(color = chalk.cyan) {
+  return color(RULE_CHAR.repeat(RULE_WIDTH));
+}
+
+/** Print a blank line. */
+function blank() {
+  console.log('');
+}
+
+/**
+ * Print the top-level program banner, e.g. `🚀 OMEGA Backend`.
+ * @param {string} title
+ */
+function banner(title) {
+  blank();
+  console.log(chalk.bold.cyan(`${SYMBOLS.rocket} ${title}`));
+  blank();
+}
+
+/**
+ * Print a divider-wrapped section header with an optional subtitle + timestamp.
+ *
+ *   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *     Title  subtitle  @ 7:47:12 PM
+ *   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *
+ * @param {string} title - Bold white title.
+ * @param {object} [opts]
+ * @param {string} [opts.subtitle] - Dimmed/colored text after the title (e.g. a URL).
+ * @param {Function} [opts.subtitleColor] - chalk fn for the subtitle (default cyan).
+ * @param {boolean} [opts.time=true] - Append `@ <time>`.
+ * @param {Function} [opts.color] - chalk fn for the rules (default cyan).
+ */
+function header(title, opts = {}) {
+  const color = opts.color || chalk.cyan;
+  const subtitleColor = opts.subtitleColor || chalk.cyan;
+  const time = opts.time !== false;
+
+  const parts = [chalk.bold.white(title)];
+  if (opts.subtitle) {
+    parts.push(subtitleColor(opts.subtitle));
+  }
+  if (time) {
+    parts.push(chalk.dim(`@ ${timestamp()}`));
+  }
+
+  console.log(rule(color));
+  console.log(`${indent(1)}${parts.join('  ')}`);
+  console.log(rule(color));
+}
+
+/**
+ * Print a magenta section label like `[SETUP]`.
+ * @param {string} label
+ */
+function section(label) {
+  blank();
+  console.log(`${indent(1)}${chalk.bold.magenta(`[${String(label).toUpperCase()}]`)}`);
+}
+
+/**
+ * Print a dimmed `Label: value` line at a given indent level.
+ * @param {string} label
+ * @param {string} value
+ * @param {object} [opts]
+ * @param {number} [opts.level=1]
+ * @param {number} [opts.pad] - Pad the label (incl. trailing colon) to this width for alignment.
+ * @param {Function} [opts.valueColor] - chalk fn for the value (default none).
+ */
+function field(label, value, opts = {}) {
+  const level = opts.level || 1;
+  let labelText = `${label}:`;
+  if (opts.pad) {
+    labelText = labelText.padEnd(opts.pad);
+  }
+  const valueText = opts.valueColor ? opts.valueColor(value) : value;
+  console.log(`${indent(level)}${chalk.dim(labelText)} ${valueText}`);
+}
+
+/**
+ * Print a status line: `<symbol> <text>` at a given indent level.
+ * @param {('running'|'pass'|'fail'|'skip'|'warn'|'add'|'change')} kind
+ * @param {string} text
+ * @param {object} [opts]
+ * @param {number} [opts.level=1]
+ * @param {string} [opts.detail] - Dimmed trailing detail.
+ */
+function status(kind, text, opts = {}) {
+  const level = opts.level || 1;
+  const colorByKind = {
+    running: chalk.dim,
+    pass: chalk.green,
+    fail: chalk.red,
+    skip: chalk.dim,
+    warn: chalk.yellow,
+    add: chalk.green,
+    change: chalk.yellow,
+  };
+  const color = colorByKind[kind] || chalk.white;
+  const symbol = SYMBOLS[kind] || '';
+  const detail = opts.detail ? ` ${chalk.dim(opts.detail)}` : '';
+  console.log(`${indent(level)}${color(symbol)} ${text}${detail}`);
+}
+
+/** Print a plain dimmed note line. */
+function note(text, level = 1) {
+  console.log(`${indent(level)}${chalk.dim(text)}`);
+}
+
+/**
+ * Collects setup-check results and prints an OMEGA-style summary block.
+ *
+ * Used by the setup command's test runner. `start()` stamps a wall-clock so the
+ * summary can report duration; `passed()` / `failed()` record outcomes; the
+ * failing check (if any) carries optional detail lines to surface in the block.
+ */
+class Summary {
+  constructor() {
+    this.startTime = null;
+    this.passes = 0;
+    this.warns = [];
+    this.fails = [];
+  }
+
+  start() {
+    this.startTime = Date.now();
+    return this;
+  }
+
+  pass() {
+    this.passes++;
+  }
+
+  /**
+   * @param {string} name - Check name.
+   * @param {string[]} [details] - Pre-formatted detail lines to show under the warning.
+   */
+  warn(name, details = []) {
+    this.warns.push({ name, details });
+  }
+
+  /**
+   * @param {string} name - Check name.
+   * @param {string[]} [details] - Pre-formatted detail lines to show under the failure.
+   */
+  fail(name, details = []) {
+    this.fails.push({ name, details });
+  }
+
+  get total() {
+    return this.passes + this.warns.length + this.fails.length;
+  }
+
+  /**
+   * Format milliseconds into "Xs" / "Xm Ys" / "Xh Ym Zs".
+   * @param {number} ms
+   */
+  _formatDuration(ms) {
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60) {
+      return `${seconds}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remSeconds = seconds % 60;
+    if (minutes < 60) {
+      return `${minutes}m ${remSeconds}s`;
+    }
+    const hours = Math.floor(minutes / 60);
+    const remMinutes = minutes % 60;
+    return `${hours}h ${remMinutes}m ${remSeconds}s`;
+  }
+
+  /**
+   * Print the summary block. Green ✅ when everything passed, yellow ⚠ otherwise.
+   * @param {object} [opts]
+   * @param {string} [opts.hint] - A closing call-to-action line (e.g. how to re-run).
+   */
+  print(opts = {}) {
+    const hasErrors = this.fails.length > 0;
+    const hasWarnings = this.warns.length > 0;
+    const headerColor = hasErrors ? chalk.yellow : chalk.green;
+    const icon = hasErrors ? SYMBOLS.warn : SYMBOLS.done;
+    const elapsed = this.startTime ? this._formatDuration(Date.now() - this.startTime) : '0s';
+
+    blank();
+    console.log(headerColor(RULE_CHAR.repeat(RULE_WIDTH)));
+    console.log(`${indent(1)}${headerColor.bold(`${icon} Summary`)}`);
+    console.log(headerColor(RULE_CHAR.repeat(RULE_WIDTH)));
+
+    blank();
+    field('Checks', String(this.total), { pad: 11 });
+    field('Duration', elapsed, { pad: 11 });
+    const parts = [chalk.green(`${this.passes} passed`)];
+    if (hasWarnings) {
+      parts.push(chalk.yellow(`${this.warns.length} warned`));
+    }
+    parts.push(hasErrors ? chalk.red(`${this.fails.length} failed`) : chalk.dim('0 failed'));
+    field('Results', parts.join(chalk.dim(', ')), { pad: 11 });
+
+    if (hasWarnings) {
+      blank();
+      for (const { name, details } of this.warns) {
+        console.log(`${indent(1)}${chalk.yellow(SYMBOLS.warn)} ${chalk.bold(name)}`);
+        for (const line of details) {
+          console.log(`${indent(3)}${line}`);
+        }
+      }
+    }
+
+    if (hasErrors) {
+      blank();
+      for (const { name, details } of this.fails) {
+        console.log(`${indent(1)}${chalk.red(SYMBOLS.fail)} ${chalk.bold(name)}`);
+        for (const line of details) {
+          console.log(`${indent(3)}${line}`);
+        }
+      }
+    }
+
+    if (opts.hint) {
+      blank();
+      console.log(`${indent(1)}${chalk.dim(SYMBOLS.running)} ${opts.hint}`);
+    }
+
+    blank();
+    console.log(headerColor(RULE_CHAR.repeat(RULE_WIDTH)));
+  }
+}
+
+module.exports = {
+  chalk,
+  RULE_WIDTH,
+  RULE_CHAR,
+  SYMBOLS,
+  indent,
+  timestamp,
+  rule,
+  blank,
+  banner,
+  header,
+  section,
+  field,
+  status,
+  note,
+  Summary,
+};

package/dist/defaults/AGENTS.md

@@ -0,0 +1,125 @@
+# ========== Default Values ==========
+# OMEGA Backend (@omega.js/backend) consumer project
+
+<!-- MAINTAINERS (framework repo): this consumer template is MIRRORED across all OMEGA framework
+     consumer templates (src/defaults/AGENTS.md ×N; web's lives at scaffold/AGENTS.md) with the same
+     sections in the same order (framework-specific extras may be inserted; canonical sections are
+     never reordered/renamed). Edit every framework consumer template together. The mirroring rule
+     lives in each framework guide's Doc-update parity section (docs/<framework>/index.md) -->
+
+## Framework
+
+This project consumes **OMEGA Backend** (@omega.js/backend), a comprehensive framework for building
+modern Firebase Cloud Functions backends. A single `Manager.init(exports, {...})` bootstrap wires:
+
+- built-in functions (`omega_api`, auth events, cron jobs)
+- helper classes (RouteContext, User, Analytics, Usage, Middleware, Settings, Utilities, Metadata)
+- payment provider integrations (Stripe / PayPal) and Firestore-trigger pipelines
+- a deploy/emulator/watch tooling pipeline
+
+## 🚨 READ THE FRAMEWORK DOCS FIRST
+
+**Before doing ANY work on this codebase, the agent MUST read the framework documentation: that is where the architecture, conventions, APIs, and gotchas live. Skipping these will result in solutions that conflict with framework patterns.**
+
+**Required reading:**
+- **`node_modules/@omega.js/AGENTS.md`**: the OMEGA map, the one agent entry into the framework docs; follow it to `docs/backend/index.md` (the @omega.js/backend guide: identity, architecture, conventions)
+- **`node_modules/@omega.js/backend/docs/`**: subsystem deep references (read the relevant ones for the task at hand)
+
+## Quick start
+
+All commands run from the **target root** (this directory). `dist/` is staged build output; never edit it.
+
+```bash
+npx omega build             # stage src/ → dist/ (the tree firebase.json points at)
+npx omega emulator          # start Firebase emulators (auth/firestore/functions/database/storage)
+npx omega test              # target checks, then YOUR project's test suites (bare runs are project-only; mgr:/backend: → framework, full: → both)
+npx omega test --extended   # opt into REAL external APIs (shorthand for the shared TEST_EXTENDED_MODE; default: skipped)
+npx omega watch             # auto-reload functions on file change
+npx omega deploy            # deploy to Firebase
+npx omega logs:read         # read Cloud Functions logs (also: logs:tail to stream)
+npx omega firestore:get     # read a doc from Firestore (also: firestore:set / :query / :delete)
+npx omega auth:get          # read an Auth user (also: auth:list / :delete / :set-claims)
+npx omega install dev       # use LOCAL @omega.js/backend source (to test framework edits)
+npx omega install live      # restore the published @omega.js/backend from npm
+```
+
+`npx omega-backend <cmd>` works too (alias of `npx omega <cmd>`).
+
+> Editing the @omega.js/backend framework source while working here? Run `npx omega install dev` so this project picks up your uncommitted framework changes (it otherwise uses its installed `node_modules/@omega.js/backend`). Run `npx omega install live` to switch back.
+
+## Where things live
+
+- `package.json`: THE target manifest, carrying scripts + runtime deps (`@omega.js/backend`, firebase-admin, firebase-functions). The staged `dist/package.json` derives from it.
+- `src/index.js`: entry point. Must call `Manager.init(exports, { ... })` to register all built-in + custom endpoints.
+- `src/routes/<verb>/<path>.js`: custom routes mounted at runtime (e.g. `src/routes/get/hello.js` → `GET /hello`).
+- `src/schemas/<name>.js`: schema definitions for `Manager.Settings()` validation.
+- `src/hooks/<area>/<event>.js`: auth/cron hooks.
+- `src/public/`: OPTIONAL overrides for the hosting boilerplate (`index.html`, `404.html`); defaults are generated into `dist/public/`.
+- `config/omega.json5`: STANDALONE projects only. In a brand monorepo the brand root's `config/omega.json5` is the config (`targets.backend` = this target's settings) and this target carries NO config file.
+- `.env`: OPTIONAL per-key overrides you write by hand. The brand root's `.env` is the one file to edit; every verb composes `dist/.env` from the cascade (company ← brand ← this file), filtered to the keys the env schema names for `backend`. Gitignored; no machine writes this file.
+- `service-account.json`: Firebase Admin credentials (STANDALONE projects; brand targets keep it in the brand's `.omega/secrets/`). Gitignored.
+- `firebase.json`: Firebase config (hosting, rewrites, emulator ports). Points `functions.source` + `hosting.public` at `dist/`. Some fields managed by the verbs' scaffold.
+- `.firebaserc`: Firebase project ID alias.
+- `firestore.rules`: YOUR security rules — the whole file, no managed block. `omega build` compiles it with @omega.js/backend's framework half into `dist/firestore.rules`, which the emulator and `firebase deploy` read (never edit that).
+  - Your rules may call any framework helper: `is*` asks a question (`isUser`, `isOwner`, `isAdmin`, `isWritingAny`), `get*` hands back a value (`getAuthUid`, `getExistingData`).
+  - A match block of yours whose path names a framework block's MERGES into it (your condition ANDs onto the framework's) — that is how you TIGHTEN. Ops pair by NAME: `match /users/{uid} { allow create, update: if !isWritingAny(['xp']); }`.
+- `database.rules.json`: Realtime Database security rules. @omega.js/backend owns a `// ========== OMEGA Rules ==========` block inside it; everything outside is yours.
+- `dist/`: GENERATED staged output (`omega build`) carrying the src copy, derived manifest, composed config, and hosting boilerplate. Never edit; gitignored.
+
+## Per-context imports
+
+```js
+// src/index.js: the entire backend bootstrap
+const Manager = require('@omega.js/backend');
+Manager.init(exports, {
+  // ...your options. How this backend RUNS is config, not an option here:
+  // targets.backend.projectType in config/omega.json5 ('firebase' | 'custom').
+});
+
+// In a custom route (src/routes/get/hello.js):
+module.exports = async function(Manager, ctx) {
+  // ctx.req, ctx.res, ctx.user, etc.
+};
+```
+
+## Available APIs at runtime
+
+After `Manager.init()`, the Manager instance exposes factory methods:
+- `Manager.RouteContext({ req, res })`: request handler with user + analytics + utility access
+- `Manager.User(data)`: user property structure + schema
+- `Manager.Analytics({ ctx })`: GA4 event tracking
+- `Manager.Usage()`: rate-limiting
+- `Manager.Middleware(req, res)`: request pipeline
+- `Manager.Settings()`: schema validation against `src/schemas/*`
+- `Manager.Utilities()`: batch operations + helpers
+- `Manager.Metadata(doc)`: timestamps + tag helpers
+- `Manager.storage({ name })`: local JSON storage (lowdb)
+
+Auth events, payment-webhook transitions, and cron jobs are wired automatically; hook into them by exporting from `src/hooks/<area>/<event>.js`.
+
+## Dependency resolution
+
+- **`Manager.require(name)`** resolves from @omega.js/backend's module context. Consumer code (routes, schemas) can use it to access @omega.js/backend's bundled dependencies without installing them directly.
+- **@omega.js/client owns Firebase on the client side.** Frontend consumer code (UJM pages, BXM extensions, EM renderers) NEVER imports Firebase directly. @omega.js/backend backend code uses `firebase-admin` directly (server-side is different).
+
+## Testing
+
+**Two lanes.** `npm test` is the STATIC lane: `node --test` over `test/_unit/**/*.test.js` with `test/_helpers/connect-trap.js` preloaded, which turns any TCP connect or DNS lookup into a throw. `npm run test:emulator` (`npx omega test`) is the emulator lane. A test needing a real client goes there; in the static lane, pass a stub.
+
+Every feature ships with tests at every surface it exposes:
+
+- **logic** — `test/routes/`, `test/events/`: handler suites against the real emulator
+- **wiring** — route round-trips over `http.as(...)`: registration, auth gates, schema validation
+- **rules** — `test/rules/`, when Firestore rules change
+
+Skip a surface only when the feature genuinely doesn't have one; "the handler test covers it" does
+not excuse the route round-trip. See `test/README.md` and
+`node_modules/@omega.js/backend/docs/test-framework.md`.
+
+<!-- Everything above this marker is owned by the framework and rewritten by every OMEGA verb. Add your project-specific notes below — they are preserved. -->
+
+# ========== Custom Values ==========
+
+## Project-specific notes
+
+Add anything specific to THIS project here. Edits below this line are preserved across runs.

package/dist/defaults/CHANGELOG.md

@@ -0,0 +1,15 @@
+# CHANGELOG
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## Changelog Categories
+
+- `BREAKING` for breaking changes.
+- `Added` for new features.
+- `Changed` for changes in existing functionality.
+- `Deprecated` for soon-to-be removed features.
+- `Removed` for now removed features.
+- `Fixed` for any bug fixes.
+- `Security` in case of vulnerabilities.

package/dist/defaults/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/dist/defaults/_.gitignore

@@ -0,0 +1,65 @@
+# ========== Default Values ==========
+# macOS
+.DS_Store
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+firebase-debug.log*
+
+# Firebase cache
+.firebase/
+
+# Firebase config
+.firebaserc
+
+# Staged output (generated by `omega build` — src/ is the source)
+dist/
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Coverage directory
+coverage
+.nyc_output
+
+# Dependency directories
+node_modules/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env*
+
+# @omega.js/backend specific
+.runtimeconfig.json
+service-account*.json
+omega-reload-trigger.js
+.temp/
+_legacy
+
+# Per-run port-bumped emulator config (N7 auto-allocation)
+firebase.resolved.json
+
+# Hosting boilerplate (generated by setup / emulator boot / deploy)
+/public/
+
+# ========== Custom Values ==========
+# Add your custom ignore patterns below this line
+# ...