Backend

---
name: backend
description: Use when working on a brand's backend app or on @omega.js/backend itself — Cloud Functions routes, schemas, auth hooks, the emulator harness, usage, payments, email, or anything under targets/backend, functions/, or packages/backend/.
user-invocable: true
---

# OMEGA Backend (@omega.js/backend)

`@omega.js/backend` builds Firebase Cloud Functions backends. Its main export is ONE ready-made instance: `const omega = require('@omega.js/backend')` then `omega.initialize({...})` wires the built-in functions (`omega_api`, auth events, cron jobs) into `omega.functions` (the file's export), the request pipeline, the `Context` every handler receives (`async ({ ctx, omega, user, data, usage, analytics }) => {}` for a route), the services (User, Usage, Analytics, Settings, Utilities, Metadata, Storage, Email, AI), the one schema system (a function of the request returning a plain declaration, validated by zod), the payment providers, Firestore-trigger pipelines, marketing campaigns, an MCP server, and the CLI for emulator, deploy, logs, auth, and Firestore work. Consumer apps are src-first: `src/index.js` plus optional `src/routes/`, `src/schemas/`, `src/hooks/`, staged into `dist/` by `omega build`.

## Where the knowledge lives

This skill routes; the docs are the source of truth. Read the guide BEFORE touching files.

- **Working in this monorepo** — `docs/backend/index.md` is the guide (identity, architecture, the CLI table, file conventions). The per-subsystem meat lives in `docs/backend/*.md`: routes, schemas, firestore, test-framework, common-mistakes, environment-detection, logging, payment-system, email-system, usage-rate-limiting, auth-hooks, mcp, verts. Cross-framework contracts live in `docs/shared/`.
- **Working in a consumer project**: read `node_modules/@omega.js/manager/docs/backend/index.md`: the installed manager ships the monorepo's whole `docs/` tree, and a locally linked brand's copy is synced from the monorepo before every omega verb but a read-only one.

## Non-negotiables

- **Read the guide before editing.** The route/schema contract, the usage helper, and the Firestore conventions each have footguns documented and nowhere else.
- **🚫 Never start the user's long-running processes** (`omega emulator`, `omega serve`) — assume they are running. `omega test` is fine; it starts its own emulator.
- **Grep the logs FIRST.** Two lanes, both truncated per launch: the CLI's own run in the app's `logs/dev.log` / `logs/build.log` / `logs/test.log`, and the firebase children in `dist/emulator.log` / `dist/dev.log`, beside firebase-tools' `*-debug.log`. Emulator traffic and the last failure are already on disk: read them instead of restarting anything (`docs/shared/logging.md`).
- **Never mock — test against the real emulator.** Every feature ships tests at every surface it exposes.
- **Secrets never enter `config/omega.json5`** — `.env` only; the config validator hard-fails secret-shaped keys.
- **Deploys are deliberate** — only `omega deploy` publishes; a commit never does (`docs/shared/deploys.md`).