@omega.js/backend 0.1.0

package/docs/audit.md

@@ -0,0 +1,70 @@
+# Audit Workflow
+
+Full-project audit for @omega.js/backend — runs against a CONSUMER backend or the FRAMEWORK repo itself (scope auto-detected). Invoked via the `omega:backend` skill (`/omega:backend audit`) or any "audit this backend/project" request.
+
+Every check has a stable ID, a severity, and a scope. Findings are reported as `ID @ file:line`, fixed one at a time, then re-verified. The tables below do NOT restate the rules — each check links to the doc that owns the rule and the fix.
+
+## Protocol
+
+1. **Detect scope** — read `package.json` (consumer: `functions/package.json`): `name` is `@omega.js/backend` → **framework audit** (U + @omega.js/backend + F checks); `@omega.js/backend` in (dev)dependencies → **consumer audit** (U + @omega.js/backend checks).
+2. **Run the catalog** — every check matching the scope. Search with Grep/Glob/Read over `functions/` (`routes/`, `schemas/`, `hooks/`, `index.js`), `test/`, and config files; ALWAYS exclude `node_modules/`, `dist/`, `_legacy/`, `_backup/`. Record each finding as `ID @ file:line` + a one-line description.
+3. **Persist the report** — write the findings list to `functions/.temp/audit/claude-audit.md` (@omega.js/backend's `functions/`-local convention, like its logs) so a long fix loop survives session breaks. Summarize counts by severity in chat.
+4. **Fix loop** — TodoWrite per finding, highest severity first, ONE at a time: mark in-progress → root cause → fix → verify → complete. Ask before structural or destructive fixes (file deletions, schema reshapes, data migrations).
+5. **Re-verify** — re-run every check that produced findings until clean; finish with `npx omega test` from `functions/` (must be green — it auto-starts its own emulator if needed).
+6. **Doc parity** — if fixes changed behavior, update README / the framework guide / `docs/<topic>.md` / CHANGELOG in the same change set.
+
+Severity: **CRIT** security or broken functionality · **HIGH** hard-rule violation · **MED** convention drift · **LOW** optional improvement.
+Scope: **C** consumer · **F** framework repo · **B** both.
+
+## Universal checks (U-xx)
+
+Mirrored across all four OMEGA frameworks (UJM / @omega.js/backend / BXM / EM) — same ID means the same check everywhere.
+
+| ID | Sev | Scope | Check |
+|----|-----|-------|-------|
+| U-01 | HIGH | B | Every feature has tests at EVERY surface it exposes — handler suites + `http.as(...)` route round-trips + rules suites; never mocked, real emulator only ([test-framework.md](test-framework.md)) |
+| U-02 | HIGH | B | Test hygiene — side-effect tests use dedicated `journey-*` accounts; real-external-API tests gated behind `TEST_EXTENDED_MODE` in-source (not mocked); files export `{ description, type, tests }` (no raw Mocha); no trailing cleanup steps ([test-framework.md](test-framework.md)) |
+| U-03 | CRIT | B | Sanitization — middleware is trim-only by default; HTML strip via opt-in `{ sanitize: true }`; every HTML-insertion site calls `utilities.sanitize()` ([sanitization.md](sanitization.md)) |
+| U-04 | HIGH | B | Firebase ownership — server code uses `firebase-admin` via Manager (correct here); NO client `firebase` SDK in functions code; consuming frontends go through @omega.js/client ([the framework guide](../../../docs/backend/index.md) §Dependency Resolution) |
+| U-05 | HIGH | C | No @omega.js/backend transitive deps installed directly in `functions/package.json` — use `Manager.require(name)` ([the framework guide](../../../docs/backend/index.md) §Dependency Resolution) |
+| U-06 | HIGH | B | Env behavior gated on the INTENTIONAL check — `isProduction()` or `isDevelopment() \|\| isTesting()`, never `!isDevelopment()`; always `Manager.getApiUrl()`, never the cached `Manager.project.apiUrl` ([environment-detection.md](environment-detection.md)) |
+| U-07 | HIGH | B | Config canon — `config/omega.json5` matches the documented shape; canonical cross-framework blocks (`brand`, payment products, …) not reinvented ([architecture.md](architecture.md), [payment-system.md](payment-system.md)) |
+| U-08 | CRIT | B | No private credentials committed — `service-account.json`, `.env` secrets, API keys (Stripe `sk_`, SendGrid `SG.`, …); `.gitignore` covers them. (The Firebase WEB `apiKey` is public by design — do NOT flag it.) |
+| U-09 | HIGH | B | Source discipline — no live code referencing `_legacy/` / `_backup/`; framework edits in `src/` (never `dist/`) ([common-mistakes.md](common-mistakes.md)) |
+| U-10 | MED | B | Doc parity — README / the framework guide / `docs/` / CHANGELOG match shipped behavior; the docs index lists every `docs/*.md`; no stale names for renamed commands/patterns |
+| U-11 | MED | B | SSOT/DRY — no duplicated constants/config/logic; one authoritative home per value, imported everywhere else |
+| U-12 | MED | B | JS conventions — file structure, JSDoc, short-circuit returns, leading logical operators, `fs-jetpack`, one `module.exports` per file ([code-patterns.md](code-patterns.md) + global `js:patterns` skill) |
+| U-13 | MED | B | Dead code & stale patterns — no orphaned files nothing imports; no leftovers of migrated-away formats (constructor routes, tiered schemas, `Manager.config.*` reads — [migration.md](migration.md)); inventory TODO/FIXME (report only) |
+| U-14 | LOW | B | Dependency health — review `npm outdated` / `npm audit` (in `functions/`); apply fixes via the `general:update-packages` workflow (includes supply-chain checks) |
+
+## @omega.js/backend-specific checks
+
+| ID | Sev | Scope | Check |
+|----|-----|-------|-------|
+| BKD-01 | HIGH | B | Every custom route has a name-matched schema; handlers are context-object exports (`async ({ Manager, ctx, … }) => {}`) — no legacy constructor routes ([routes.md](routes.md), [schemas.md](schemas.md)) |
+| BKD-02 | HIGH | B | Schema field rules — never `required: true` + `default` together (required is checked BEFORE defaults; use `min: 1` for path-extracted IDs); flat schema with in-function plan branching, no tier arrays ([schemas.md](schemas.md)) |
+| BKD-03 | HIGH | B | Route handlers — ownership checks on PUT/DELETE; plural-noun route names; `ctx.respond()` only (never `res.send()`) ([routes.md](routes.md), [common-operations.md](common-operations.md)) |
+| BKD-04 | HIGH | C | Wiring — every route exported in `functions/index.js`; `firebase.json` rewrites use bracket syntax, ordered most-specific-first ([routes.md](routes.md)) |
+| BKD-05 | HIGH | B | Firestore canon — NO subcollections; path-string `.doc('users/abc')`; batched collection reads (~500, cursor pagination); timestamps under `metadata.{created,updated}`; mirror-the-doc responses; delete-don't-redact ([firestore.md](firestore.md)) |
+| BKD-06 | HIGH | B | Usage — never read/write `{doc}.usage.*` manually, always the `usage` helper; expensive/abusable routes carry usage validation or rate limiting ([usage-rate-limiting.md](usage-rate-limiting.md)) |
+| BKD-07 | MED | B | Composite indexes — every compound query (`where` + `orderBy`, multiple `where`s) is registered in the required-indexes SSOT ([the framework guide](../../../docs/backend/index.md) §File Conventions) |
+| BKD-08 | HIGH | B | Auth gates — routes resolve the caller via `ctx`/`user` before acting; admin-only routes verify admin status ([common-operations.md](common-operations.md), [routes.md](routes.md)) |
+| BKD-09 | HIGH | B | Rules coverage — `firestore.rules` changes ship a rules suite (`rules.asAccount` / `expectSuccess` / `expectFailure`) ([test-framework.md](test-framework.md)) |
+
+## Framework-repo checks (F-xx)
+
+Only when auditing the @omega.js/backend repo itself. Mirrored across the four frameworks.
+
+| ID | Sev | Check |
+|----|-----|-------|
+| F-01 | MED | Sister parity — mirrored sections (config shapes, test contract, guide skeleton, shared env/test conventions) in sync with UJM / BXM / EM; deviations are deliberate and documented |
+| F-02 | HIGH | Consumer-shipped defaults in sync — what `ensureTarget()` scaffolds (every verb runs it) matches current conventions and docs |
+| F-03 | MED | Docs completeness — every `docs/*.md` indexed in the framework guide; every subsystem has a doc; no "(planned)" links for things that have shipped |
+| F-04 | HIGH | `npx omega test mgr:` green before treating the audit as complete |
+
+## See also
+
+- [schemas.md](schemas.md) — the required-vs-default footgun behind BKD-02
+- [firestore.md](firestore.md) — the data canon behind BKD-05
+- [migration.md](migration.md) — the legacy formats U-13 hunts for
+- [test-framework.md](test-framework.md) — the surfaces behind U-01 / U-02 / BKD-09

package/docs/auth-hooks.md

@@ -0,0 +1,74 @@
+# Auth Hooks (Consumer Project)
+
+Auth hooks let consumer projects inject custom logic into @omega.js/backend's auth event lifecycle. @omega.js/backend runs its core handler first, then looks for a matching hook at `hooks/auth/{event-name}.js`.
+
+| Hook | File | Behavior |
+|------|------|----------|
+| `before-create` | `hooks/auth/before-create.js` | Runs after @omega.js/backend's disposable email + rate limit checks (the per-IP daily cap is `targets.backend.auth.signup.maxPerIpPerDay`, default 2). **Can throw `HttpsError` to block signup.** |
+| `before-signin` | `hooks/auth/before-signin.js` | Runs after @omega.js/backend's activity update. **Can throw `HttpsError` to block sign-in.** |
+| `on-create` | `hooks/auth/on-create.js` | Runs after @omega.js/backend creates the user doc. **Non-blocking** — errors are caught and logged. |
+| `on-delete` | `hooks/auth/on-delete.js` | Runs after @omega.js/backend deletes the user doc. **Non-blocking** — errors are caught and logged. |
+
+Hook signature (same as @omega.js/backend's internal handlers):
+
+```javascript
+module.exports = async ({ Manager, ctx, user, context, libraries }) => {
+  // user: AuthUserRecord (uid, email, providerData, etc.)
+  // context: AuthEventContext for blocking functions (ipAddress, userAgent, additionalUserInfo)
+  //          EventContext for triggers (eventId, eventType, timestamp — no IP/userAgent)
+  // libraries: { admin, functions, ... }
+};
+```
+
+## Blocking hook example (before-create)
+
+```javascript
+// hooks/auth/before-create.js — Only allow Google OAuth signups
+const ENFORCE = true;
+
+const ALLOWED_PROVIDERS = ['google.com'];
+
+module.exports = async ({ ctx, user, context, libraries }) => {
+  if (!ENFORCE) { return; }
+
+  const { functions } = libraries;
+  const provider = context.additionalUserInfo?.providerId;
+
+  if (!ALLOWED_PROVIDERS.includes(provider)) {
+    ctx.error(`hook/before-create: Blocked provider '${provider}' for ${user.email}`);
+    throw new functions.auth.HttpsError('permission-denied', 'Please sign up with Google.');
+  }
+};
+```
+
+## Non-blocking hook example (on-create)
+
+```javascript
+// hooks/auth/on-create.js — Auto-delete spam referrals
+const powertools = require('node-powertools');
+
+const ENFORCE = true;
+const BLOCKED_AFFILIATE_CODES = ['iLvQjmvm'];
+
+module.exports = async ({ Manager, ctx, user, context, libraries }) => {
+  if (!ENFORCE) { return; }
+
+  const { admin } = libraries;
+  const uid = user.uid;
+
+  // Poll until signup route attaches attribution.affiliate.code
+  let referredBy = null;
+
+  await powertools.poll(async () => {
+    const userDoc = await admin.firestore().doc(`users/${uid}`).get().catch(() => null);
+    if (!userDoc?.exists) { return true; }
+    referredBy = userDoc.data()?.attribution?.affiliate?.code;
+    return !!referredBy;
+  }, { interval: 10000, timeout: 60000 }).catch(() => {});
+
+  if (!referredBy || !BLOCKED_AFFILIATE_CODES.includes(referredBy)) { return; }
+
+  // Delete spam account (triggers on-delete for cleanup)
+  await admin.auth().deleteUser(uid).catch(e => ctx.error('Delete failed:', e));
+};
+```

package/docs/build-system.md

@@ -0,0 +1,65 @@
+# Build System
+
+@omega.js/backend now mirrors every other OMEGA framework: **consumer backends are src-first**. Authored code lives in `src/`, and `dist/` is staged output — generated by `omega build`, gitignored wholesale, disposable. `firebase.json` points both `functions.source` and `hosting.public` (`dist/public`) at the staged tree.
+
+## Pipeline overview
+
+| Stage | Command | What happens |
+|---|---|---|
+| Build | `npx omega build` | Stage `src/` → `dist/` (1:1 copy, derived manifest, composed brand⊕local config, public/ boilerplate, .env/.nvmrc/SA) |
+| Local dev | `npx omega emulator` / `npx omega serve` | Auto-stages first, then watches `src/` — re-staging IS the hot reload |
+| Test | `npx omega test` | Auto-stages first, runs suites against the emulator |
+| Ship | `npx omega deploy` | Auto-stages first, then `firebase deploy` on the staged tree |
+
+Environment behavior is governed by emulator vs production, not a build flag. See [environment-detection.md](environment-detection.md).
+
+## Consumer project layout
+
+```
+targets/<brand>/targets/backend/
+  package.json              # THE target manifest: scripts + runtime deps
+  .env                      # local-layer secrets (D15 cascade)
+  .nvmrc                    # Node version pin
+  src/
+    index.js                # Manager.init entry
+    routes/** schemas/** hooks/** mcp.js
+    public/                 # OPTIONAL: overrides for the hosting boilerplate
+  config/omega.json5        # STANDALONE escape hatch only — brand targets carry none
+  service-account.json      # STANDALONE only — brand targets keep it in the
+                            # brand's .omega/secrets/ (the key's ONE home)
+  test/                     # project tests
+  firebase.json  .firebaserc  *.rules  firestore.indexes.json
+  dist/                     # ← GENERATED (gitignored) — never edit
+```
+
+### Staged dist/ output
+
+- `src/**` → `dist/**` (1:1 copy, no transforms — CJS as-is; `src/public/` handled separately)
+- `dist/public/` → hosting boilerplate (default `index.html` + `404.html` from templates; consumer `src/public/*` overrides win file-by-file)
+- `package.json` → derived manifest (name/engines/deps only; relative `file:` deps respelled one level deeper for stage-local-packages)
+- `config/omega.json5` → composed via `composeTargetConfig` (brand⊕target flattened for the deploy upload boundary — the runtime cannot walk up past it)
+- `.env` / `.nvmrc` → verbatim copy from the target root
+- `service-account.json` → from the target root (standalone) or the brand's `.omega/secrets/` (brand targets — the firebase manage service mints it there)
+- `firestore.rules` → **compiled** into `dist/firestore.rules`: the target root's file is the brand's source half, the framework half ships in `@omega.js/backend/templates/firestore.framework.rules`, and `firebase.json` points the emulator and `firebase deploy` at the artifact ([#255](https://github.com/Omega-JS-Stack/omega/issues/255)). Every stage recompiles, so a brand-rules edit reaches a running emulator through the stage watch. The brand's own file is never written by the build — setup owns that.
+
+> **Credentials at runtime.** The staged key is for LOCAL scripts that talk to the real project. On any managed runtime — deployed Cloud Functions / Cloud Run (`K_SERVICE`/`FUNCTION_TARGET`), the emulator, or an explicit `GOOGLE_APPLICATION_CREDENTIALS` — `Manager.init` calls `admin.initializeApp()` with NO arguments and authenticates as the runtime's own service identity. When it does fall back to the staged cert, a `project_id` that doesn't match the resolved Firebase `projectId` **throws at boot** rather than warning: a mismatched key authenticates every Firestore call as the wrong identity and surfaces far away as gRPC `UNAUTHENTICATED (16)` on the first read.
+- `node_modules/` preserved across stages (runtime artifacts, never authored)
+- `*.log` preserved (co-located with firebase-tools logs)
+
+## prepare-package (framework-side)
+
+The @omega.js/backend library itself has one build step: `npm run prepare` copies `src/` → `dist/` via prepare-package (`npm run prepare:watch` for watch mode). Consumers always require from `dist/`. This mirrors the framework-side prepare step in EM/BXM/UJM.
+
+**The framework package is never a stage target.** Its root looks like a target root to the stage (a `package.json` beside a `src/`), so an `omega` verb run from inside the framework itself — no target context, so the dispatcher runs the host CLI — used to re-stage the framework's OWN `dist/`: prepare-package's output wiped, then a hard stop on the missing `omega.json5`, leaving the CLI unbootable until the next `npm run prepare` ([#308](https://github.com/Omega-JS-Stack/omega/issues/308)). `stageFunctions` now refuses by name BEFORE the wipe (`Refusing to stage <dir>: that is the @omega.js/backend framework package itself…`). The framework self-test is unaffected: `npx omega test` here retargets to the bundled fixture project before anything stages ([test-boot-layer.md](test-boot-layer.md)).
+
+At publish time, a `prepublishOnly` script first removes the self-test fixture's runtime `node_modules` — its `@omega.js/backend` symlink points back at the repo root, which would send prepare-package's publish-time cleanup walk into an infinite cycle. The symlinks are throwaway; the next `npx omega test` self-test regenerates them (see [test-boot-layer.md](test-boot-layer.md)).
+
+## Log files
+
+CLI commands tee output to `dist/*.log` (`dev.log`, `emulator.log`, `test.log`, `production.log`) — co-located with firebase-tools' own debug logs. Full reference: [logging.md](logging.md).
+
+## See also
+
+- [architecture.md](architecture.md) — Manager class, dual-mode support (`firebase` / `custom`)
+- [directory-structure.md](directory-structure.md) — @omega.js/backend library + consumer project layout
+- [test-framework.md](test-framework.md) — the emulator-based test harness

package/docs/cdp-debugging.md

@@ -0,0 +1,29 @@
+# CDP Debugging (driving a live browser)
+
+How to drive a browser you can CONTROL — see the frontend live, screenshot it, click, type, read console logs, inspect network requests against your routes — for agents (Claude via MCP/CDP) and humans.
+
+> Mirrored across the five sister frameworks (UJM / @omega.js/backend / BXM / EM / @omega.js/client) — same core section, framework-flavored. Edit all five together.
+
+## The browser: your Claude session owns one
+
+Browser work runs through the **`chrome-devtools` MCP** (via mcp-router). There is NO launch procedure anymore — no ports, no profile dirs, no curl checks:
+
+- **Just call the tools** — `new_page`, `navigate_page`, `take_screenshot`, `click`, `fill`, `evaluate_script`, `list_console_messages`, `list_network_requests`. The browser auto-launches on the first call.
+- **Each Claude session gets its OWN private Chrome** (`--isolated`): temp profile, CDP over an internal pipe. Parallel sessions cannot see or touch each other's pages — open and close pages freely, the whole browser is yours.
+- **It dies with the session.** No orphans, no cleanup, nothing to kill.
+- **Ephemeral profile** — cookies/logins do NOT persist between sessions. If a flow needs auth, log in during the task.
+- **Self-signed HTTPS is pre-accepted** (`--acceptInsecureCerts` in the upstream) — dev servers load without certificate interstitials.
+- **NEVER quit/kill Chrome by app name** (`killall "Google Chrome"`, osascript) — that's the user's personal browser, not yours.
+
+Humans: the agent's Chrome window is visible — you can watch it drive. Full reference: `~/.claude/mcp-server/servers/chrome-devtools/CLAUDE.md`.
+
+## Electron apps are the exception (attach, don't launch)
+
+An Electron dev app is a running singleton — you ATTACH to it instead of launching a browser: the `chrome-devtools-electron` MCP upstream (reads `OMEGA_CDP_PORT`, default 9222, expanded once at session start) or EM's per-invocation `npx omega cdp`. See EM's `docs/cdp-debugging.md`.
+
+## @omega.js/backend specifics
+
+- **The UJM dev site URL is `https://localhost:4000` — NEVER the LAN IP** (`https://192.168.x.x:...`). Port 4000 by default, increments (4001, …) when multiple sites run; the exact port is in `.temp/_config_browsersync.yml` at the root of the WEBSITE project (the UJM consumer — e.g. `<brand>-website/.temp/_config_browsersync.yml`, NOT this backend repo).
+- The network tab is the payoff: `list_network_requests` shows every call the frontend makes to your routes — method, status, and payloads — while you click through the real UI.
+- **Auth'd flows**: the profile is ephemeral, so log in through the real UI at the start of the session (test creds) — then exercise the authenticated routes.
+- Backend-side observation stays where it always was: `npx omega logs` (gcloud logs) and the emulator suite; this doc only covers the browser half of the loop.

package/docs/cli-firestore-auth.md

@@ -0,0 +1,85 @@
+# CLI: Firestore & Auth Commands
+
+Quick commands for reading/writing Firestore and managing Auth users directly from the terminal. Works in any @omega.js/backend consumer project (production needs the service-account chain; the emulator needs nothing).
+
+**Which stack a subcommand hits** ([#51](https://github.com/Omega-JS-Stack/omega/issues/51)): EVERY subcommand — reads and writes alike — targets the **emulator by default** and reaches live only with an explicit `--production`. One rule, no exceptions; `--emulator` is accepted but just names the default. Every command prints the stack it hit — the `Target: <projectId> (<stack>)` header, and again in the success line (`Document written to emulator: …`). The rule lives in one place: `src/cli/utils/target.js`.
+
+**IMPORTANT: All CLI commands (`npx omega ...`) MUST be run from the consumer project's `functions/` subdirectory** (e.g., `cd /path/to/my-project/functions && npx omega ...`). The `mgr` binary lives in `functions/node_modules/.bin/` — running from the project root or any other directory will fail.
+
+For log commands, see [docs/cli-logs.md](cli-logs.md).
+
+## Firestore Commands
+
+```bash
+npx omega firestore:get <path>                          # Read a document (emulator; --production for live)
+npx omega firestore:set <path> '<json>'                 # Write/merge a document (emulator; --production for live)
+npx omega firestore:set <path> '<json>' --no-merge      # Overwrite a document entirely
+npx omega firestore:query <collection>                  # Query a collection (default limit 25)
+  --where "field==value"                              #   Filter (repeatable for AND)
+  --orderBy "field:desc"                              #   Sort
+  --limit N                                           #   Limit results
+npx omega firestore:delete <path>                       # Delete a document (emulator; --production prompts for confirmation)
+```
+
+## Auth Commands
+
+```bash
+npx omega auth:get <uid-or-email>                       # Get user by UID or email (emulator; --production for live)
+npx omega auth:list [--limit N] [--page-token T]        # List users (emulator; --production for live)
+npx omega auth:delete <uid-or-email>                    # Delete user (emulator; --production prompts for confirmation)
+npx omega auth:set-claims <uid-or-email> '<json>'       # Set custom claims (emulator; --production for live)
+npx omega auth:token <uid-or-email>                     # Mint a custom token + one-click sign-in URL (QA)
+```
+
+### `auth:token` — log in as anyone (QA)
+
+Mints a custom token for the user and prints a URL the auth pages consume
+directly (`/signin?authCustomToken=…&authReturnUrl=…`) — open it and the
+browser IS that user. Like every subcommand it targets the
+**emulator by default**; pass `--production` deliberately.
+
+| Flag | Description |
+|------|-------------|
+| `--url <base>` | Website base URL for the printed link (default `http://localhost:4000`) |
+| `--return <path>` | `authReturnUrl` after sign-in (default `/dashboard`) |
+| `--production` | Mint against production instead of the emulator |
+
+## Shared Flags
+
+| Flag | Description |
+|------|-------------|
+| `--production` | Target the live stack instead of the emulator (every subcommand) |
+| `--emulator` | Accepted for muscle memory — the emulator is already the default |
+| `--force` | Skip confirmation on destructive operations |
+| `--raw` | Compact JSON output (for piping to `jq` etc.) |
+
+## Examples
+
+```bash
+# Read a user document from the emulator (the default)
+npx omega firestore:get users/abc123
+
+# Read a user document from production (deliberate)
+npx omega firestore:get users/abc123 --production
+
+# Write to the emulator (the default)
+npx omega firestore:set users/test123 '{"name":"Test User"}'
+
+# Write to production (deliberate)
+npx omega firestore:set users/abc123 '{"name":"Real User"}' --production
+
+# Query with filters
+npx omega firestore:query users --where "subscription.status==active" --limit 10
+
+# Look up auth user by email
+npx omega auth:get user@example.com
+
+# Set admin claims
+npx omega auth:set-claims user@example.com '{"admin":true}'
+
+# One-click sign-in URL for a seeded persona (emulator)
+npx omega auth:token _test.admin@playground.omegajs.dev --return /account
+
+# Delete from the emulator (the default — no confirmation needed)
+npx omega firestore:delete users/test123
+```

package/docs/cli-logs.md

@@ -0,0 +1,67 @@
+# CLI: Logs Commands
+
+Fetch or stream Cloud Function logs from Google Cloud Logging. Requires `gcloud` CLI installed and authenticated. Auto-resolves the project ID from `service-account.json`, `.firebaserc`, or `GCLOUD_PROJECT`.
+
+> All `npx omega ...` commands must be run from the consumer project's `functions/` subdirectory. See [docs/cli-firestore-auth.md](cli-firestore-auth.md) for the explanation.
+
+## Commands
+
+```bash
+npx omega logs:read                                     # Read last 1h of logs (default: 300 entries, newest first)
+npx omega logs:read --fn omega_api                         # Filter by function name
+npx omega logs:read --fn omega_api --severity ERROR        # Filter by severity (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+npx omega logs:read --since 2d --limit 100              # Custom time range and limit
+npx omega logs:read --search "72.134.242.25"            # Search textPayload for a string (IP, email, error, etc.)
+npx omega logs:read --fn omega_authBeforeCreate --search "ian@example.com" --since 7d  # Combined filters
+npx omega logs:read --order asc                         # Oldest first (default: desc/newest first)
+npx omega logs:read --filter 'jsonPayload.level="error"'  # Raw gcloud filter passthrough
+npx omega logs:tail                                     # Stream live logs
+npx omega logs:tail --fn omega_paymentsWebhookOnWrite      # Stream filtered live logs
+```
+
+Both commands save output to `functions/production.log` (overwritten on each run). `logs:read` saves raw JSON; `logs:tail` streams text.
+
+**Cloud Logs vs Local Logs:** These commands query **production** Google Cloud Logging. For **local/dev** logs, read `functions/dev.log` (from `npx omega serve`) or `functions/emulator.log` (from `npx omega test`) directly — they are plain text files, not gcloud.
+
+## Flags
+
+| Flag | Description | Default | Commands |
+|------|-------------|---------|----------|
+| `--fn <name>` | Filter by Cloud Function name (see table below) | all | both |
+| `--severity <level>` | Minimum severity: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` | all | both |
+| `--search <text>` | Search textPayload for a substring (IP, email, uid, error message) | none | both |
+| `--filter <expr>` | Raw gcloud logging filter expression (appended to built-in filters) | none | both |
+| `--since <duration>` | Time range (`30m`, `1h`, `2d`, `1w`) | `1h` | read only |
+| `--limit <n>` | Max entries | `300` | read only |
+| `--order <dir>` | Sort order: `asc` (oldest first) or `desc` (newest first) | `desc` | read only |
+| `--interval <sec>` | Polling interval in seconds | `5` | tail only |
+| `--raw` | Output raw JSON | false | both |
+
+## `--fn` Function Name Reference
+
+The `--fn` flag uses the **deployed Cloud Function name**, not the route path.
+
+**@omega.js/backend built-in functions (always deployed):**
+
+| Function name | Type | Description |
+|---------------|------|-------------|
+| `omega_api` | HTTPS | Main API router — all consumer routes (GET/POST/PUT/DELETE) go through this |
+| `omega_authBeforeCreate` | Auth blocking | Before user creation: disposable email blocking, IP rate limiting, consumer hooks |
+| `omega_authBeforeSignIn` | Auth blocking | Before sign-in: consumer hooks |
+| `omega_authOnCreate` | Auth event | After user creation: user doc setup |
+| `omega_authOnDelete` | Auth event | After user deletion |
+| `omega_paymentsWebhookOnWrite` | Firestore trigger | Processes payment webhooks |
+| `omega_paymentsDisputeOnWrite` | Firestore trigger | Processes payment disputes |
+| `omega_notificationsOnWrite` | Firestore trigger | Sends push notifications |
+| `omega_cronDaily` | Scheduled | Daily cron (midnight UTC) |
+| `omega_cronFrequent` | Scheduled | Frequent cron (every 10 min) |
+
+**Consumer-defined functions** use the export name from `functions/index.js` (e.g., `exports.items = ...` → `--fn items`).
+
+**Quick lookup — which function to query:**
+- API route errors → `--fn omega_api`
+- Signup/auth blocked → `--fn omega_authBeforeCreate`
+- Sign-in issues → `--fn omega_authBeforeSignIn`
+- User doc not created → `--fn omega_authOnCreate`
+- Payment not processing → `--fn omega_paymentsWebhookOnWrite`
+- Cron job issues → `--fn omega_cronDaily` or `--fn omega_cronFrequent`

package/docs/cli-output.md

@@ -0,0 +1,146 @@
+# CLI Output Styling (`src/cli/utils/ui.js`)
+
+@omega.js/backend's CLI shares a single styling module so every command renders with the same
+look as the **OMEGA Manager** (`omega-manager`): `🚀` banner, 70-char `━`
+dividers, indented tree output, dimmed labels, timestamps, and a consistent set
+of status symbols. This is the **SSOT for console output** — commands should pull
+helpers from here instead of hand-rolling `chalk` + `console.log`.
+
+The module is exposed on every command as `this.ui` (wired in
+[`src/cli/commands/base-command.js`](../src/cli/commands/base-command.js)) and can
+also be `require('../utils/ui')`'d directly (e.g. from setup-test files).
+
+## Conventions
+
+| Aspect | Value |
+|---|---|
+| Divider | `━` × 70 (`ui.RULE_WIDTH`, `ui.RULE_CHAR`) |
+| Indentation | 2 spaces per level (`ui.indent(level)`) |
+| Section label | `[UPPERCASE]` in bold magenta, at indent level 1 |
+| Section items | one level deeper than the label (level 2) |
+| Timestamp | `new Date().toLocaleTimeString()` (e.g. `7:47:12 PM`) |
+| Banner | bold cyan, prefixed with `🚀` |
+
+### Status symbols (`ui.SYMBOLS`)
+
+| Key | Symbol | Color | Meaning |
+|---|---|---|---|
+| `running` | `→` | dim | step in progress / hint |
+| `pass` | `✓` | green | success |
+| `fail` | `✗` | red | failure |
+| `skip` | `⊘` | dim | skipped / no-op |
+| `warn` | `⚠` | yellow | warning |
+| `done` | `✅` | green | final success (summary) |
+| `add` | `+` | green | created a file/record |
+| `change` | `↻` | yellow | modified a file/record |
+
+## API
+
+```js
+const ui = require('../utils/ui'); // or this.ui inside a command
+
+ui.banner('OMEGA Backend v5.2.18');          // 🚀 bold-cyan banner + blank lines
+ui.header('Somiibo', { subtitle: url });        // ━ divider / title @ time / ━ divider
+ui.section('Checks');                            // blank line + bold-magenta [CHECKS]
+ui.field('Project', 'somiibo-91d13', { pad: 9 });// dimmed "Label:" + value (pad aligns columns)
+ui.status('pass', 'Stats fetched', { level: 2 });// <symbol> <text> at an indent level
+ui.note('All defaults up to date', 2);           // dimmed line at a level
+ui.blank();                                      // blank line
+ui.rule();                                       // a bare 70-char rule string (cyan)
+```
+
+`ui.header(title, opts)`:
+- `opts.subtitle` — text after the title (default cyan), e.g. a URL.
+- `opts.subtitleColor` — chalk fn for the subtitle.
+- `opts.time` — append `@ <time>` (default `true`).
+- `opts.color` — chalk fn for the rules (default cyan).
+
+`ui.field(label, value, opts)`:
+- `opts.level` — indent level (default 1).
+- `opts.pad` — pad the label (incl. colon) to this width for column alignment.
+- `opts.valueColor` — chalk fn for the value.
+
+`ui.status(kind, text, opts)`:
+- `kind` — one of `running|pass|fail|skip|warn|add|change` (picks symbol + color).
+- `opts.level` — indent level (default 1).
+- `opts.detail` — dimmed trailing detail string.
+
+### `ui.Summary`
+
+Collects pass/warn/fail outcomes and prints an OMEGA-style summary block (green `✅`
+when all passed, yellow `⚠` otherwise).
+
+```js
+const summary = new ui.Summary().start();
+summary.pass();                        // record a pass
+summary.warn('check name', detailsArr);// record a warning (non-blocking)
+summary.fail('check name', detailsArr);// record a fail with pre-formatted detail lines
+summary.print({ hint: 'Fix the above, then run npx omega test again.' });
+```
+
+Results line: `36 passed, 1 warned, 0 failed` (the warned segment only appears
+when > 0). Warnings are listed before failures in the summary block — yellow `⚠`
+lines with their detail arrays indented beneath.
+
+## How the target checks use it
+
+The AUDIT half of the retired `omega setup` — [`src/cli/utils/target-checks.js`](../src/cli/utils/target-checks.js),
+the lane `omega test` runs before it boots anything — builds its whole run from
+these helpers:
+
+1. `ui.section('Target checks')` (printed by the test command) opens the lane.
+2. the per-check status lines (printed by the check runner — see below), with
+   `✓ fixed` / `✗ Could not fix` sub-lines.
+3. `main.setupSummary.print()` when the lane finishes.
+
+### Test runner (`Main.prototype.test` in `src/cli/index.js`)
+
+Each target check prints `    [N] <symbol> <name>`. A check's `run()` can return:
+
+| Return value | Behavior |
+|---|---|
+| `true` | `✓` pass (recorded via `setupSummary.pass()`) |
+| `false` | Attempt `fix()` → `✓ fixed` on success, `✗ Could not fix` + halt on throw |
+| `Error` | `✗` hard halt, no fix attempted |
+| `'warn'` | `⚠` non-blocking warning — reported in summary, does **not** halt |
+
+**`'warn'` return type:** When `run()` returns `'warn'`, the runner prints the
+check as `⚠`, calls `getWarning()` on the test instance for detail lines (array
+of strings), and records it via `setupSummary.warn()`. The lane continues. The
+summary shows `36 passed, 1 warned, 0 failed` with the warning details listed
+at the bottom. Use this for environment prerequisites that don't block dev/deploy
+(e.g. Java, optional CLIs). `BaseTest` provides a default `getWarning()` returning
+`[]`; override it with your detail lines.
+
+A failing check's `fix()` may attach `error.summaryDetails` (an array of styled
+lines) to surface a compact version in the summary block — see
+[`setup-tests/bem-config.js`](../src/cli/commands/setup-tests/bem-config.js),
+which lists the missing `config/omega.json5` keys.
+
+`--continue` records the failure but keeps going instead of halting.
+
+`--offline` makes the run READ-ONLY against the brand's cloud project
+([#284](https://github.com/Omega-JS-Stack/omega/issues/284)): no mutation runs,
+but live READS still do (it is a no-mutation flag, not a no-network flag — an
+actually-offline machine still fails on the reads). The mutating checks
+downgrade to a `'warn'` naming the flag, so a scaffold run in CI, a sandbox, or
+a migration never rewrites production as a side effect: `firestore-indexes-synced`
+still fetches and prints the drift but skips `firebase deploy --only
+firestore:indexes` (its `fix()` is inert too, for direct callers),
+`storage-lifecycle-policy` — whose check *is* the mutation — returns before any
+`gsutil lifecycle set`, and `--seed-campaigns` is ignored (seeding writes real
+Firestore docs, so the opt-in loses to `--offline`). Read-only checks are
+unaffected. `BaseTest.isOffline` is the one reader of the flag.
+
+> **No more `UnhandledPromiseRejection`.** Hard failures exit cleanly via
+> `haltSetup()` / `process.exit(1)`, and `bin/omega-backend` wraps the run in a
+> `try/catch` that prints a one-line `✗ <message>` instead of Node's raw rejection
+> dump.
+
+## Adopting it in other commands
+
+`serve`, `deploy`, `test`, `emulator`, etc. can migrate to the same look
+incrementally: replace ad-hoc `console.log(chalk...)` with `this.ui.section(...)`,
+`this.ui.status(...)`, and `this.ui.field(...)`. The legacy
+`log/logError/logSuccess/logWarning` helpers on `BaseCommand` still work for
+simple one-off lines.

package/docs/code-patterns.md

@@ -0,0 +1,77 @@
+# Code Patterns
+
+## Short-Circuit Returns
+
+Use early returns instead of nested conditionals:
+
+```javascript
+// CORRECT
+function handler(data) {
+  if (!data) {
+    return ctx.report('Missing data', { code: 400 });
+  }
+
+  // Main logic here
+  return ctx.respond({ success: true });
+}
+
+// INCORRECT
+function handler(data) {
+  if (data) {
+    // Main logic here
+    return ctx.respond({ success: true });
+  }
+}
+```
+
+## Logical Operators on New Lines
+
+Place operators at the start of continuation lines:
+
+```javascript
+// CORRECT
+const isValid = hasPermission
+  || isAdmin
+  || isOwner;
+
+// INCORRECT
+const isValid = hasPermission ||
+  isAdmin ||
+  isOwner;
+```
+
+## Firestore Document Access
+
+Use shorthand `.doc()` path:
+
+```javascript
+// CORRECT
+admin.firestore().doc('users/abc123')
+
+// INCORRECT
+admin.firestore().collection('users').doc('abc123')
+```
+
+## Template Strings for Requires
+
+```javascript
+// CORRECT
+require(`${functionsDir}/node_modules/@omega.js/backend`)
+
+// INCORRECT
+require(functionsDir + '/node_modules/@omega.js/backend')
+```
+
+## Prefer fs-jetpack
+
+Use `fs-jetpack` over `fs` or `fs-extra` for file operations.
+
+## Coded errors: 400 = permanent config fault
+
+An error carrying `code: 400` means a brand-config hole (or an equally permanent
+caller fault) — something a retry can never heal. The full statement of the
+convention and every place it is caught lives in
+[marketing-campaigns.md](marketing-campaigns.md) § Claim/Lease Lifecycle; new
+config-hole throws follow it (`errorWithCode(..., 400)` in the email library,
+`err.code = 400` elsewhere) rather than throwing a code-less Error, which
+`respond()` reports as a Sentry-captured 500.

package/docs/common-mistakes.md

@@ -0,0 +1,12 @@
+# Common Mistakes to Avoid
+
+1. **Don't modify Manager internals directly** — Use factory methods and public APIs
+2. **Always use `ctx.respond()` for responses** — Don't use `res.send()` directly
+3. **Match schema names to route names** — If route is `myEndpoint`, schema should be `myEndpoint`
+4. **Always await async operations** — Don't forget `await` on Firestore operations
+5. **Handle errors properly** — Use `ctx.report()` with appropriate status codes
+6. **Don't call `respond()` multiple times** — Only one response per request
+7. **Use short-circuit returns** — Return early from error conditions
+8. **One call counts** — `await ctx.usage.consume('<feature>')` checks, counts and writes, and throws the 429 itself. Never hand-roll a gate around a counter read
+9. **Add Firestore composite indexes for new compound queries** — Any new Firestore query using multiple `.where()` clauses or `.where()` + `.orderBy()` requires a composite index. Add it to `src/cli/commands/setup-tests/helpers/required-indexes.js` (the SSOT). Consumer projects pick these up via `npx omega test`, whose target checks sync them into `firestore.indexes.json`. Without the index, the query will crash with `FAILED_PRECONDITION` in production.
+10. **Don't put test data cleanup at the END of a test** — End-of-test cleanup doesn't fire when the previous run was killed mid-execution, so the next run inherits stale state. ALL test-data cleanup belongs in the runner's pre-test phase ([../src/test/test-accounts.js](../src/test/test-accounts.js) `deleteTestUsers()` + [../src/test/runner.js](../src/test/runner.js) `setupAccounts()`), which **flushes the entire emulator Firestore before every run** — so there's nothing to register when you add a test that writes data. Seed any required fixtures in `test/_init.js`'s `setup()` (runs after the flush). The only acceptable trailing cleanup is within-run state isolation (one test removes a doc so the NEXT test in the same run sees a clean slate) — that's not preparing the next run, it's intra-run housekeeping. See [test-framework.md](test-framework.md) "Test Data Cleanup".