backend-manager 5.2.18 → 5.3.0

package/CHANGELOG.md

@@ -14,6 +14,41 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+# [5.3.0] - 2026-06-02
+
+### Added
+- **`Manager.AI(assistant).image({ prompt, ... })`** — image generation via OpenAI's `gpt-image-2`. Separate method from `request()` (return type is bytes, not text; bypasses moderation/token-accounting/schema/prompt-normalization, none of which apply to image gen). Returns `{ buffer, b64, mime, revisedPrompt, model, size, quality, raw }` for a single image, or an array when `n > 1`. Options: `prompt` (required), `model` (default `gpt-image-2`), `size` (`1024x1024` default), `quality` (`medium` default), `background`, `n`, `timeout` (default 5min — image gen is slow). Only `openai` implements it. Lives on `OpenAI.prototype.image()` + dispatched via `AI.prototype.image()`. See [docs/ai-library.md](docs/ai-library.md).
+- **AI tools passthrough (nested) — `ai.request({ tools: { list, choice } })`.** `tools.list` is an array of tool definitions passed to the OpenAI Responses API verbatim — built-in hosted tools (e.g. `{ type: 'web_search' }`) OR custom function tools (`{ type: 'function', name, parameters }`); `tools.choice` *(optional)* maps to `tool_choice`. Opt-in — omitted/empty means no tools and identical behavior to a plain request. Primary use is OpenAI's built-in **web search** so the model finds and cites real, currently-live URLs instead of hallucinating them. When tools are active the response `output` may carry tool-call items (e.g. `web_search_call`) + `url_citation` annotations; the message-text extractor ignores non-message items so `r.content` is unaffected. See [docs/ai-library.md](docs/ai-library.md).
+- **`image-illustrator.js` — newsletter section illustrations now generated as flat-vector PNGs via `gpt-image-2` by default**, replacing the SVG-author-then-rasterize approach as the default. Clean flat 2D vector style (Stripe / Linear / undraw.co aesthetic) built from the brand palette (`content.theme.{primary,secondary,accent}Color`), white background, no text. The legacy `svg-illustrator.js` method is still available per-brand via `marketing.beehiiv.content.method.image = 'svg'`. Both return the same `{ png: Buffer, fallback, meta }` contract, so `image-host.js` / `uploadAssets` are unchanged. Validated end-to-end against live `gpt-image-2` with Somiibo's real config. See [docs/marketing-campaigns.md](docs/marketing-campaigns.md).
+- **Full emulator-Firestore flush before every test run.** `deleteTestUsers()` now calls `flushEmulatorFirestore()` — `listCollections()` + `recursiveDelete()` on the entire emulator DB — before recreating test accounts. The emulator DB is 100% test data, so a full flush is the simplest correct clean slate; there are no per-collection allowlists to maintain. Guarded to run ONLY when `FIRESTORE_EMULATOR_HOST` is set, so it can never touch a real project.
+- **`test/_init.js` pre-test lifecycle hook.** The test runner loads an optional `test/_init.js` from BOTH test roots (BEM core + consumer project) and runs it before any test (it is not run as a test itself). The module **must export a function** — `module.exports = (ctx) => ({ ... })` — called with `{ config, Manager }` and returning the hook object. It may declare `accounts` (array of extra test accounts `{ id, uid, email, properties }`, created/fetched/deleted on the same path as the built-ins so a project has a user per lifecycle) and `async setup({ admin, config, accounts, Manager, assistant })` (reseed fixtures into the freshly-flushed DB, after account creation). There is **no `cleanup` hook** — the whole DB is flushed each run and each test cleans up after itself. A default boilerplate `test/_init.js` now ships via `src/defaults/` (copied into consumers on first `npx mgr setup`, never overwriting an existing one). Mirrored across all four OMEGA frameworks. See `docs/testing.md`.
+
+### Changed
+- **Environment detection consolidated onto the Manager as SSOT.** `getEnvironment()` returns exactly one of `development | testing | production` (mutually exclusive, testing wins), read **live** from `process.env` on every call (no caching). `assistant.isDevelopment/isProduction/isTesting/getEnvironment` forward to the Manager. Fixes a bug where a cached environment made `getApiUrl()` resolve to the production URL inside the test runner.
+- **Install-command parity.** `npx mgr install` accepts the unified alias set across all four frameworks — `dev|d|development|local|l` for the local source install and `live|prod|p|production` for the published version; docs advertise the canonical `dev` + `live`.
+- **`copyDefaults` no longer skips `_`-prefixed filenames.** The archive-skip rule now only applies to `_`-prefixed *directory* segments (e.g. `_legacy/`); a `_`-prefixed *filename* like `test/_init.js` ships verbatim. The `_.env` / `_.gitignore` dotfile rename is unchanged.
+
+### Fixed
+- **Test-account creation race.** A late `auth:on-delete` could clobber the fresh `auth:on-create` doc, leaving accounts without `api.clientId`/`privateKey` and cascading into dozens of auth/payment test failures. `createAccount()` now verifies the API keys landed and repairs (recreate) if a stale delete clobbered the doc, making the suite deterministic.
+- **`meta/stats` seed ordering.** `ensureMetaStats()` ran before the emulator flush (so it was wiped) and skipped when the doc already existed (so the notification on-write trigger could leave it without a `users` field). It now merges the `users` baseline AFTER the flush, fixing flaky admin-stats tests.
+- **Flaky payment/dispute tests.** The trial journey now skips cleanly when no paid product has `trial.days > 0` (mirrors trial-cancel) instead of timing out; the dispute-alert dedup test seeds a deterministic in-flight doc instead of racing a live webhook to `failed`.
+
+# [5.2.19] - 2026-05-29
+
+### Added
+
+- **Shared CLI styling module (`src/cli/utils/ui.js`)** — the SSOT for BEM console output, matching the OMEGA Manager look: a `🚀` banner, 70-char `━` dividers, indented tree output, dimmed `Label:` fields, timestamps, a consistent set of status symbols (`→ ✓ ✗ ⊘ ⚠ ✅ + ↻`), and a `Summary` block (green `✅` / yellow `⚠`). Exposed on every command as `this.ui` (wired in `base-command.js`) and adoptable incrementally by `serve`/`deploy`/`test`/`emulator`. See `docs/cli-output.md`.
+- **Regression test for the `.env`/`.gitignore` merge** (`test/helpers/merge-line-files.js`). Covers key-based alignment when key order drifts (the original scramble), Custom→Default promotion when the template adopts a key, Default→Custom migration of unknown keys, value preservation, quote normalization, idempotency, and that the setup-test helper is the same function as the canonical impl (SSOT guard).
+
+### Changed
+
+- **`npx mgr setup` now renders in the OMEGA style.** The old `---- RUNNING SETUP ----` / `[1] name: passed` / bare missing-keys dump is replaced with a banner, a divider-wrapped project header (brand name + Firebase console URL + `Project`/`API` fields), and `[DEFAULTS]` / `[CHECKS]` / `[STATS]` sections. Each check prints `[N] ✓ name`, with `⚠ … — fixing…` → `✓ fixed` on auto-fix and `✗ Could not fix: …` on hard failure. The run ends with a `Summary` block (checks count, duration, passed/failed, and any failing checks with detail lines). The `bem-config` check lists the missing `backend-manager-config.json` keys as a bulleted list and surfaces a compact version in the summary.
+
+### Fixed
+
+- **No more `UnhandledPromiseRejection` crash on setup failure.** Previously an unfixable check (e.g. missing config keys) rejected a promise with no reason, which bubbled out of the un-`catch`'d `bin/backend-manager` IIFE as Node's raw `UnhandledPromiseRejection: undefined` dump (exit non-zero, lost message). Setup now exits cleanly via `haltSetup()` → `process.exit(1)` after printing the styled summary, and `bin/backend-manager` wraps the run in a `try/catch` that prints a one-line `✗ <message>` backstop. The early-exit guards (missing `functions/package.json`, wrong directory) now print styled errors and exit `1` instead of `0`.
+- **`.env` merge no longer scrambles keys under the wrong headers.** The `has correct .env file` / `has correct .gitignore` setup checks (`env-file.js`, `gitignore.js`) imported a SECOND, **positional** merge implementation in `src/cli/commands/setup-tests/helpers/merge-line-files.js` that zipped comment lines and value lines by index — so any drift between the consumer's key order and the template shifted every value down a slot (the last key of each group landed under the next group's header), dropped newly-added template keys, and duplicated keys. That duplicate is **deleted**; the helper is now a thin SSOT shim re-exporting the canonical key-based merge in `src/utils/merge-line-files.js`. The canonical merge also now **promotes** a key from the user's Custom section up into Default (with its value) when the framework template adopts that key, instead of emitting an empty Default line and leaving the value stranded in Custom.
+
 # [5.2.17] - 2026-05-29
 
 ### Added

package/CLAUDE.md

@@ -34,7 +34,7 @@ All `npx mgr <cmd>` aliases work: `npx bm <cmd>`, `npx bem <cmd>`, `npx backend-
 1. `npm install` — install BEM's own deps
 2. `npm run prepare` — build once: copies `src/` → `dist/` via prepare-package
 3. `npm run prepare:watch` — watch mode
-4. Test in a consumer project: from inside the consumer, run `npx mgr install dev` to swap BEM to this local repo — required whenever you edit the framework source and want the consumer to pick up the changes (the consumer otherwise keeps its installed `node_modules/backend-manager`). Reverse with `npx mgr install prod`. If `npx mgr` then errors with "could not determine executable to run", the local install skipped bin-linking — re-run `npm install` to relink, or call `node node_modules/backend-manager/bin/backend-manager <cmd>` directly.
+4. Test in a consumer project: from inside the consumer, run `npx mgr install dev` to swap BEM to this local repo — required whenever you edit the framework source and want the consumer to pick up the changes (the consumer otherwise keeps its installed `node_modules/backend-manager`). Reverse with `npx mgr install live`. If `npx mgr` then errors with "could not determine executable to run", the local install skipped bin-linking — re-run `npm install` to relink, or call `node node_modules/backend-manager/bin/backend-manager <cmd>` directly.
 
 ## Architecture
 
@@ -79,6 +79,7 @@ See [docs/cli-firestore-auth.md](docs/cli-firestore-auth.md) and [docs/cli-logs.
 - **Routes receive whitespace-trimmed data; HTML is preserved.** Sanitize at the HTML-insertion site via `utilities.sanitize()`. Opt into middleware-level HTML strip per-route with `{ sanitize: true }`. See [docs/sanitization.md](docs/sanitization.md).
 - **Match schema names to route names** — if route is `myEndpoint`, schema is `myEndpoint`.
 - **Always use `assistant.respond()` for responses** — do NOT use `res.send()` directly.
+- **Always use `Manager.getApiUrl()` for the API URL** — never read the cached `Manager.project.apiUrl` property. The getter is the SSOT and auto-resolves to the local emulator in dev AND test (and production otherwise), so it's safe everywhere without passing an env arg. See [docs/environment-detection.md](docs/environment-detection.md).
 - **Add Firestore composite indexes** for any compound query (`where` + `orderBy`, or multiple `where`s) to `src/cli/commands/setup-tests/helpers/required-indexes.js` (the SSOT). Without the index, queries crash with `FAILED_PRECONDITION` in production.
 
 See [docs/code-patterns.md](docs/code-patterns.md) for code-pattern detail, [docs/common-mistakes.md](docs/common-mistakes.md) for the full anti-pattern checklist, and [docs/file-naming.md](docs/file-naming.md) for the naming table (routes / schemas / API commands / events / cron jobs / hooks).
@@ -106,7 +107,8 @@ Deep references live in `docs/`. **Whenever you make a behavioral change, update
 - [docs/file-naming.md](docs/file-naming.md) — naming table for routes, schemas, API commands, events, cron jobs, hooks
 - [docs/common-mistakes.md](docs/common-mistakes.md) — anti-pattern checklist (don't modify Manager internals, always await, increment-before-update, etc.)
 - [docs/key-files.md](docs/key-files.md) — quick lookup for the most-touched files (Manager, helpers, auth events, cron, payment processors, CLI commands)
-- [docs/environment-detection.md](docs/environment-detection.md) — `assistant.isDevelopment/isProduction/isTesting()`
+- [docs/cli-output.md](docs/cli-output.md) — shared CLI styling module (`src/cli/utils/ui.js`): OMEGA-style banner/dividers/sections/status symbols + the `Summary` block; used by `setup`, adoptable by other commands
+- [docs/environment-detection.md](docs/environment-detection.md) — `getEnvironment()` returns `'development' | 'testing' | 'production'` (mutually exclusive); gate side effects on the INTENTIONAL check (`isProduction()` for prod-only, `isDevelopment() || isTesting()` for local-or-test) — never `!isDevelopment()`. Plus the URL helper convention (always `Manager.getApiUrl()` — auto-resolves local in dev+test, never read `project.apiUrl`)
 - [docs/response-headers.md](docs/response-headers.md) — automatic `bm-properties` header
 
 ### Building Routes & Components
@@ -128,12 +130,12 @@ Deep references live in `docs/`. **Whenever you make a behavioral change, update
 ### Subsystems & Libraries
 
 - [docs/usage-rate-limiting.md](docs/usage-rate-limiting.md) — usage tracking, monthly/daily caps, `setUser()` + mirrors for proxy usage, reset schedule
-- [docs/ai-library.md](docs/ai-library.md) — `Manager.AI()` unified entry for OpenAI + Anthropic
+- [docs/ai-library.md](docs/ai-library.md) — `Manager.AI()` unified entry for OpenAI + Anthropic (text via `.request()`, images via `.image()` → `gpt-image-2`)
 - [docs/marketing-fields.md](docs/marketing-fields.md) — adding custom fields to SendGrid + Beehiiv via the BEM/OMEGA SSOT pair
 - [docs/stripe-webhook-forwarding.md](docs/stripe-webhook-forwarding.md) — auto-started Stripe CLI forwarding for local dev
 
 ### Testing & CLI
 
-- [docs/testing.md](docs/testing.md) — running, filtering, log files, test types (standalone/suite/group), context object, assertions, auth levels. **All cleanup runs at the START of every run, never at the end.** If you add a test that writes Firestore data, register the collection/namespace in the runner's pre-test wipe list, don't add a trailing cleanup step. Marketing providers (SendGrid/Beehiiv) don't need a special exception — `_test.*` emails are blocked at the validation layer so test signups never reach providers. The `_test.allow_*` carve-out exists only for the live-provider lifecycle test (`test/marketing/consent-lifecycle.js`), which manages its own teardown.
+- [docs/testing.md](docs/testing.md) — running, filtering, log files, test types (standalone/suite/group), context object, assertions, auth levels. **NEVER mock — test against the real emulator.** No `mockManager`/`mockAdmin`/fake `firestore`/stubbed `assistant`; every `run()` gets the real `Manager`/`assistant`/`firestore`/`http`/`accounts` — use them. Pure functions (zero I/O) are the only thing you call directly; anything touching Firestore or an external API runs for real. Real external APIs (OpenAI/PayPal/GitHub/SendGrid/Stripe) are gated behind `TEST_EXTENDED_MODE` in-source (not mocked), and anything an extended test creates externally must be cleaned up by the test. **Each test file `module.exports` a `{ description, type, tests }` object — NOT raw Mocha (`describe`/`it`/`beforeEach`); those globals are not injected and the file fails to load. Split tests one-file-per-concern under `test/<area>/`, never one giant `test/test.js`.** **All cleanup runs at the START of every run, never at the end** — the runner flushes the ENTIRE emulator Firestore before every run, so there's nothing to register; seed any needed fixtures in `test/_init.js`'s `setup()`, and never add a trailing cleanup step. Marketing providers (SendGrid/Beehiiv) don't need a special exception — `_test.*` emails are blocked at the validation layer so test signups never reach providers. The `_test.allow_*` carve-out exists only for the live-provider lifecycle test (`test/marketing/consent-lifecycle.js`), which manages its own teardown.
 - [docs/cli-firestore-auth.md](docs/cli-firestore-auth.md) — `npx mgr firestore:*` and `auth:*` commands, shared flags, examples
 - [docs/cli-logs.md](docs/cli-logs.md) — `npx mgr logs:read` / `logs:tail` with full flag reference and built-in Cloud Function names

package/bin/backend-manager

@@ -2,5 +2,14 @@
 let Main = new (require('../src/cli/index.js'))(process.argv);
 (async function() {
   'use strict';
-  await Main.process(process.argv);
+  try {
+    await Main.process(process.argv);
+  } catch (e) {
+    // Print a clean one-line error instead of Node's raw UnhandledPromiseRejection
+    // dump. Commands that intend a hard stop should `process.exit(1)` themselves
+    // (e.g. setup's haltSetup); this is the catch-all backstop.
+    const chalk = require('chalk').default;
+    console.error(chalk.red(`\n✗ ${e && e.message ? e.message : e}`));
+    process.exit(1);
+  }
 }());

package/docs/admin-post-route.md

@@ -4,6 +4,8 @@ The `POST /admin/post` route creates blog posts via GitHub's API. It handles ima
 
 **Consumers.** Besides direct admin/blogger HTTP calls, this route is the publish target for the **Ghostii article engine** (`src/manager/libraries/content/ghostii.js` → `publishArticle()`), which is used by two paths: the standalone daily `ghostii-auto-publisher.js` cron (off by default), and the newsletter generator's linked-article flow (`marketing.beehiiv.content.article.enabled`). Both POST `title`/`url`/`description`/`headerImageURL`/`body`/`author`/`categories`/`tags`/`postPath`/`githubUser`/`githubRepo` with a `backendManagerKey`. Note: `headerImageURL` MUST resolve to a `.jpg` (the downloader rejects non-`.jpg` headers); Ghostii's `unsplash` hero satisfies this. See [docs/marketing-campaigns.md](marketing-campaigns.md).
 
+**Ghostii is unopinionated about BEM.** Its `/write/article` response is a generic article — a `json` block array (`[{ name, content }]` where name ∈ `heading-1..6`/`image`/`paragraph`/`blockquote`/`list`) plus top-level `title`/`description`/`headerImageUrl`/`images`/`categories`/`keywords`. BEM owns the transform into this route's shape: `blocksToPost(article.json)` extracts the `heading-1` as the title, the first `image` block as `headerImageURL`, and joins every remaining block as the `body` (content only — NO title, NO header image embedded, since this route adds those itself; section images stay in the body and are extracted normally). Older Ghostii responses without `json` fall back to the flat `article.{title,body,headerImageUrl}` fields.
+
 ## Image Processing Flow
 
 1. Receives markdown body with external image URLs (e.g., `![alt](https://images.unsplash.com/...)`)

package/docs/ai-library.md

@@ -14,16 +14,43 @@ Return shape (same for all providers): `{ content, output, tokens, raw }`.
 
 API keys: `BACKEND_MANAGER_OPENAI_API_KEY`, `BACKEND_MANAGER_ANTHROPIC_API_KEY` (process.env or config).
 
+## Image generation (OpenAI)
+
+`Manager.AI(assistant).image({ prompt, ... })` generates an image via OpenAI's image model (`gpt-image-2` by default). Separate from `request()` because the return type is bytes, not text — it bypasses moderation, token accounting, schema, and prompt-normalization (none apply to image gen).
+
+```js
+const ai = Manager.AI(assistant);
+const { buffer, b64, mime, revisedPrompt } = await ai.image({
+  prompt: 'Minimal flat vector illustration of a rocket, undraw.co style, blue + white, no text.',
+  size: '1024x1024',   // 1024x1024 | 1536x1024 | 1024x1536 | auto (default 1024x1024)
+  quality: 'medium',   // low | medium | high | auto (default medium)
+  background: 'opaque', // transparent | opaque | auto (opt-in)
+  n: 1,                // default 1; n > 1 returns an array
+});
+// buffer is a PNG Buffer; b64 is the same data base64-encoded.
+```
+
+Return shape (single image): `{ buffer, b64, mime, revisedPrompt, model, size, quality, raw }`. With `n > 1` it returns an array of those.
+
+`gpt-image-2` always returns base64 (no URL round-trip). Generation is slow — `medium`/`1024²` ≈ 40-50s; the default request timeout is 5 minutes. Only `openai` implements `image()`; calling it on another provider throws.
+
+API key resolution is the same as `request()` — `BACKEND_MANAGER_OPENAI_API_KEY` / `OPENAI_API_KEY` (process.env or config).
+
 ## Tools / web search (OpenAI)
 
-`options.tools` (and optional `options.toolChoice`) are passed through to the OpenAI Responses API verbatim. Opt-in — when omitted, no tools are sent and behavior is identical to a plain request. Use this to enable OpenAI's built-in **web search** so the model finds and cites real, currently-live URLs instead of hallucinating them:
+Tools are nested under `options.tools` and opt-in — when omitted, no tools are sent and behavior is identical to a plain request:
+
+- `tools.list` — array of tool definitions passed to the OpenAI Responses API verbatim. Built-in hosted tools (e.g. `{ type: 'web_search' }`, `{ type: 'code_interpreter' }`) OR custom function tools (`{ type: 'function', name, parameters }`).
+- `tools.choice` *(optional)* — maps to `tool_choice` (`'auto'` | `'required'` | `'none'`, or a specific tool). Omit to let OpenAI default to `auto`.
+
+The most common use is OpenAI's built-in **web search** so the model finds and cites real, currently-live URLs instead of hallucinating them:
 
 ```js
 const r = await ai.request({
   model: 'gpt-5.4',
   response: 'json',
   reasoning: { effort: 'medium' },
-  tools: [{ type: 'web_search' }],
+  tools: { list: [{ type: 'web_search' }] },
   prompt: { path: '.../research/system.md', settings },
   message: { path: '.../research/user.md', settings },
 });

package/docs/cli-output.md

@@ -0,0 +1,122 @@
+# CLI Output Styling (`src/cli/utils/ui.js`)
+
+BEM'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('Backend Manager 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/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.fail('check name', detailsArr);// record a fail with pre-formatted detail lines
+summary.print({ hint: 'Fix the above, then run npx mgr setup again.' });
+```
+
+`fail()`'s second arg is an array of already-styled lines shown indented under the
+failing check in the summary block.
+
+## How `setup` uses it
+
+[`src/cli/commands/setup.js`](../src/cli/commands/setup.js) builds the whole run
+from these helpers:
+
+1. `ui.banner(...)` → `ui.header(brand, { subtitle: consoleUrl })` → `ui.field('Project'/'API', ...)`.
+2. `ui.section('Defaults')` then `ui.status('add'|'change', ...)` per scaffolded file.
+3. `ui.section('Checks')` then the per-check status lines (printed by the test
+   runner — see below), with `✓ fixed` / `✗ Could not fix` sub-lines.
+4. `ui.section('Stats')` then a pass/skip/warn line.
+5. `self.setupSummary.print()` on success.
+
+### Test runner (`Main.prototype.test` in `src/cli/index.js`)
+
+Each setup check prints `    [N] <symbol> <name>`. A check can:
+- **pass** → `✓` (recorded via `setupSummary.pass()`).
+- **fail then auto-fix** → `⚠ … — fixing…` then `✓ fixed`.
+- **fail unfixably** → `✗ Could not fix: <message>`, recorded via
+  `setupSummary.fail(name, details)`, then `haltSetup()` prints the summary and
+  `process.exit(1)`.
+
+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 `backend-manager-config.json` keys.
+
+`--continue` records the failure but keeps going instead of halting.
+
+> **No more `UnhandledPromiseRejection`.** Hard failures exit cleanly via
+> `haltSetup()` / `process.exit(1)`, and `bin/backend-manager` 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/common-mistakes.md

@@ -9,4 +9,4 @@
 7. **Use short-circuit returns** — Return early from error conditions
 8. **Increment usage before update** — Call `usage.increment()` then `usage.update()`
 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 mgr setup`, which syncs 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()`). When adding a test that writes data: register the Firestore collection in `testDataCollections` (mixed prod+test data) or `testOnlyCollections` (test-only), or use the `_test-` doc-id prefix so the id-keyed pass catches it. 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 [testing.md](testing.md) "Test Data Cleanup".
+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 [testing.md](testing.md) "Test Data Cleanup".

package/docs/environment-detection.md

@@ -1,7 +1,91 @@
 # Environment Detection
 
+`getEnvironment()` returns exactly ONE of three mutually-exclusive, exhaustive values:
+
+```javascript
+Manager.getEnvironment()    // 'development' | 'testing' | 'production'
+
+Manager.isDevelopment()     // true ONLY in development
+Manager.isTesting()         // true ONLY in testing
+Manager.isProduction()      // true ONLY in production
+```
+
+**The Manager is the single source of truth.** `getEnvironment()` is the ONLY function that reads the raw signals (`BEM_TESTING` / `ENVIRONMENT` / `FUNCTIONS_EMULATOR` / `TERM_PROGRAM`). The three `is*()` checks **derive** from it live on every call — they never read raw signals themselves, so they can never disagree with `getEnvironment()`.
+
+**The assistant forwards to the Manager.** Request handlers receive an `assistant`, so the same methods are exposed there and return identical results — call whichever is in scope:
+
+```javascript
+assistant.getEnvironment()  // === Manager.getEnvironment() — a thin forward
+assistant.isTesting()       // === Manager.isTesting()
+```
+
+(An assistant always has a Manager — `init()` throws without one. The `assistant.meta.environment` field is still populated for code that reads it, but the `is*()` checks no longer depend on that snapshot.)
+
+**Resolution order:** testing wins first, then production, else development. The three checks are mutually exclusive — exactly one is true. `isDevelopment()` is **false** during testing, and `isProduction()` is a real positive check (it is NOT `!isDevelopment()`).
+
+## Available helpers
+
+| Helper | Returns |
+|---|---|
+| `getEnvironment()` | `'development' \| 'testing' \| 'production'` — the SSOT resolver; the only reader of raw signals. |
+| `isDevelopment()` | `true` ONLY in development (local Firebase emulator / dev), and NOT testing. Derives from `getEnvironment()`. |
+| `isTesting()` | `true` ONLY in testing (`BEM_TESTING === 'true'`). **Takes precedence** — a test run is not development. |
+| `isProduction()` | `true` ONLY in production (deployed Cloud Functions). A **real positive check** — NOT `!isDevelopment()`. |
+
+## Gating side effects — use the INTENTIONAL check
+
+Because there are three environments, never gate a side effect on a two-value assumption. State what you mean:
+
 ```javascript
-assistant.isDevelopment()  // true when ENVIRONMENT !== 'production' or in emulator
-assistant.isProduction()   // true when ENVIRONMENT === 'production'
-assistant.isTesting()      // true when running tests (via npx mgr test)
+// Production-only (skip real emails/analytics/Sentry/webhooks in dev AND testing):
+if (isProduction())  { /* do the real thing */ }
+if (!isProduction()) { /* skip / use the safe local behavior */ }
+
+// Local-or-test (anything that should run in BOTH dev and testing):
+if (isDevelopment() || isTesting()) { /* localhost URL, console logging, etc. */ }
 ```
+
+**Avoid** `if (!isDevelopment())` or `if (env !== 'development')` to gate production behavior — those wrongly include `testing` as production and leak real side effects (emails, analytics, Sentry) during test runs. This is the bug class that motivated the 3-value model.
+
+## URL helpers
+
+```javascript
+Manager.getApiUrl()  // this brand's API URL — the SSOT for calling the BEM API
+```
+
+**`Manager.getApiUrl()` is the one and only way to get the API URL.** It resolves to the **local** hosting emulator (`http://localhost:5002`) in development OR testing, and to production (`https://api.{domain}`) otherwise. Always call `getApiUrl()` directly — do NOT read the cached `Manager.project.apiUrl` property (it's a boot-time snapshot kept only for internal env-var export; the getter is the SSOT and always fresh). Build full endpoints by appending the path: `` `${Manager.getApiUrl()}/backend-manager/admin/post` ``.
+
+Resolving local in test mode is required because tests hit the local emulator — without it, internal BEM→BEM calls (and tests calling `getApiUrl()`) would leak to the live production server. Pass an explicit `env` arg (`getApiUrl('production')`) only to force a specific environment regardless of the current one — rarely needed, and mainly used by tests to pin a specific environment's mapping.
+
+> `getFunctionsUrl()` (raw Cloud Functions URL) exists for the ONE internal case that must name a specific deployed function by its raw address (`assistant.tryUrl()`). Application/route code should never need it — use `getApiUrl()`.
+
+**Exception — parent helpers stay live:** `Manager.getParentApiUrl()` / `getParentUrl()` ALWAYS return the live production URL, even in dev/test. The parent BEM is a real remote server with no localhost equivalent, so cross-brand parent calls are never redirected to localhost.
+
+## Where they live
+
+Source: [src/manager/index.js](../src/manager/index.js). BEM has a single Manager (no multi-context mixin like EM/UJM/BXM), so `getEnvironment()` + `is*()` + the URL helpers live directly on the Manager. The `assistant` exposes the same methods and forwards each to its Manager (`assistant.isTesting()` → `Manager.isTesting()`), so request handlers can call whichever object is in scope.
+
+## How detection works
+
+`getEnvironment()` resolves in this precedence order:
+
+1. **Testing** — `process.env.BEM_TESTING === 'true'` (set by the test runner / emulator). A test run is a test run regardless of any other signal.
+2. **Production** — `process.env.ENVIRONMENT === 'production'`.
+3. **Development** — `process.env.ENVIRONMENT === 'development'`, or `FUNCTIONS_EMULATOR` is set, or `TERM_PROGRAM` is `Apple_Terminal` / `vscode` (running locally).
+4. **Default** — production. BEM's deployed *runtime* can legitimately lack a dev signal (a live Cloud Function has no `FUNCTIONS_EMULATOR`), so "no signal" IS the normal production state. (Contrast UJM/BXM, whose deployed artifacts always carry their signal baked in, so they default to **development** — a bare context there is just build tooling. EM defaults to production for the same reason as BEM.)
+
+## Adding a new helper
+
+If you need a new environment-derived helper, add it next to the others on the Manager in [src/manager/index.js](../src/manager/index.js), and forward it from the assistant if request handlers need it. Don't read `process.env` ad-hoc elsewhere — derive from `getEnvironment()` so there is one source of truth and no chance of drift.
+
+## Why this matters
+
+**One signal, used everywhere.** The test runner sets `BEM_TESTING=true`; every piece of code that calls `isTesting()` (framework or consumer) then sees `true` — no need to invent a per-module env var.
+
+**Sub-modules check the same signal.** When framework code (an analytics flush, a webhook fan-out) needs to skip side effects in tests, it checks `isTesting()` — the same answer the consumer's own code gets. No drift.
+
+**`is*()` can never disagree with `getEnvironment()`.** Because the checks derive from the single resolver instead of reading raw signals, there is exactly one definition of "what environment is this," and a wrong-but-confident gate (leaking real emails during a test run) is structurally impossible.
+
+## See also
+
+- [testing.md](testing.md) — `BEM_TESTING` is set automatically by the test runner; `TEST_EXTENDED_MODE` gates real external APIs.

package/docs/marketing-campaigns.md

@@ -96,7 +96,7 @@ Campaigns reference segments by SSOT key: `segments: ['subscription_free']`. Aut
 Pipeline:
 1. Fetch sources: `GET {parentUrl}/newsletter/sources?category=X&claimFor=brandId` (atomic claim)
 2. **structure.js** — Generic dispatcher. Resolves the active template, merges `BASE_SCHEMA` (universal fields: subject, preheader, signoff, citations) with the template's own `schema` fragment, calls the template's `buildPrompt({brand, newsletterConfig, sources})` to get the AI brief, runs the AI call, and normalizes the result via the template's optional `normalize()`. Default provider: `openai` (override per-run only via `NEWSLETTER_PROVIDER_STRUCTURE` env).
-3. **svg-illustrator.js** — One SVG per section in parallel (`Promise.all`). Iterates `structure.sections` — templates whose content shape isn't section-based (e.g. field-report uses `dispatches`) populate `sections` in their `normalize()` step so this loop keeps working unchanged. Default provider: `anthropic` (override via `NEWSLETTER_PROVIDER_SVG` env).
+3. **image-illustrator.js** (default) — One flat-vector PNG per section in parallel (`Promise.all`), generated directly via `Manager.AI(assistant).image()` → `gpt-image-2`. Iterates `structure.sections` — templates whose content shape isn't section-based (e.g. field-report uses `dispatches`) populate `sections` in their `normalize()` step so this loop keeps working unchanged. The prompt enforces a clean flat 2D vector style (Stripe / Linear / undraw.co aesthetic) built from the brand palette (`content.theme.{primary,secondary,accent}Color`), on a white background, no text. **Legacy method:** set `marketing.beehiiv.content.method.image = 'svg'` to use the older `svg-illustrator.js` (AI authors an `<svg>`, rasterized via `@resvg/resvg-js`). Both methods return the same `{ png: Buffer, fallback, meta }` contract.
 4. **mjml-template.js** — Resolves the template by name from `templates/index.js`, calls `template.build({structure, imagePaths, theme, ...})` for the MJML, compiles to email-safe HTML via the `mjml` package. Brand-domain links get UTM-tagged via the existing `tagLinks()` utility.
 5. Mark used: `PUT {parentUrl}/newsletter/sources` per source
 

package/docs/payment-system.md

@@ -180,7 +180,7 @@ module.exports = async function ({ before, after, uid, userDoc, admin, assistant
 
 1. Add detection logic in `transitions/index.js` (in priority order)
 2. Create handler file in `transitions/{category}/{name}.js`
-3. Handler receives full context — use `assistant.log()` for logging, `Manager.project.apiUrl` for API calls
+3. Handler receives full context — use `assistant.log()` for logging, `Manager.getApiUrl()` for API calls
 
 ## Processor Interface
 

package/docs/testing.md

@@ -1,5 +1,25 @@
 # Testing
 
+## 🚫 NEVER mock — test against the real emulator (HARD RULE)
+
+Tests run against a **real Firebase emulator** (real Firestore/Auth). **Do NOT hand-roll fake/stub/mock objects** — no `mockManager`, `mockAdmin`, `makeManager()`, fake `firestore()`/`admin`, stubbed `assistant`, or fake HTTP. Every test `run()` receives the **real** booted `Manager`, `assistant`, `firestore`, `http`, and `accounts` (see [the test context](#test-context)). Use them.
+
+- Call routes over `http.as(...)`; call handlers/helpers with the real `Manager`/`assistant` from context; read/write/verify with the real `firestore` helper.
+- **Pure functions are the only exception** — a function with zero I/O can be `require()`d and called with plain inputs (nothing to mock). The instant it touches Firestore or any external system, it must run for real against the emulator.
+- **Real external APIs (OpenAI, PayPal, GitHub, SendGrid, Beehiiv, Stripe) are gated behind `TEST_EXTENDED_MODE` in the source, NOT mocked** — see [Extended Mode](#extended-mode-test_extended_mode). Normal mode skips them; extended mode runs them for real.
+- **Anything an extended test creates in an external system must be cleaned up by the test** (delete the GitHub file, cancel the PayPal invoice, etc.) — the runner's pre-test wipe only covers local Firestore/Auth.
+
+If you're writing `const mockX = {...}` to satisfy a function under test, STOP and pass the real context object instead.
+
+### The ONLY two exceptions where a stub is allowed
+
+Mock **nothing** by default. There are exactly two narrow cases where the real dependency genuinely cannot run in the test environment — and even then, stub the *smallest possible seam*, never a whole `Manager`/`assistant`:
+
+1. **A side effect that would destroy the test run itself.** If invoking the real method would kill or corrupt the harness — e.g. a process-exit, an `app.quit()`, a destructive filesystem wipe, a recursive re-invocation of the test/build command — you may stub *that one call* to a no-op, assert the surrounding logic, then restore it. You are not faking behavior; you are preventing the harness from terminating mid-assertion.
+2. **Cross-project fan-out that needs infrastructure you can't run locally.** Some routes fan out to *other* BEM backends (parent → child brand servers). Only **one** BEM emulator runs locally, so the real cross-project call has no second backend to hit. A unit test may hand-roll the minimal inputs (`makeManager`/`makeAdminMock`/mocked `wonderful-fetch`) to exercise the *fan-out logic* in isolation — but a companion integration test MUST still verify the real route's gate/wiring against the emulator. (Example: `test/helpers/webhook-forward.js`.)
+
+**Rules for both exceptions:** stub the narrowest seam (one method / one module), restore it immediately, and add a comment stating *why the real thing can't run here*. If you can run it for real, you must.
+
 ## Running Tests
 
 ```bash
@@ -18,12 +38,11 @@ npx mgr test
 What the runner wipes pre-test (in [src/test/test-accounts.js](../src/test/test-accounts.js) `deleteTestUsers()` and [src/test/runner.js](../src/test/runner.js) `setupAccounts()`):
 
 1. **`meta/stats`** doc ensured (required for on-create batch writes).
-2. **`users/_test-*`** Firebase Auth users + Firestore docs (delete).
-3. **Mixed Firestore collections** — `payments-orders`, `payments-webhooks`, `payments-intents`, `payments-disputes`. Two-pass cleanup per collection:
-   - Pass 1 — owner-keyed: `where('owner', 'in', [...testUids])` (batched at 30 uids per `in` query).
-   - Pass 2 — id-keyed: any doc whose ID starts with `_test-` (catches ownerless test docs like dispute alerts and raw test webhooks).
-4. **Test-only Firestore collections** — `_test`, `_test_query` — wiped in full.
-5. **Realtime Database** — the `_test` namespace removed in full (`admin.database().ref('_test').remove()`).
+2. **The ENTIRE emulator Firestore** — every top-level collection, flushed recursively (`flushEmulatorFirestore()` → `listCollections()` + `recursiveDelete()`). The emulator DB is 100% test data, so a full flush is the simplest correct clean slate — no per-collection allowlist to maintain. **SAFETY: it only runs when `FIRESTORE_EMULATOR_HOST` is set** (which the test command always sets); if absent it is a no-op, so it can never wipe a real project.
+3. **Firebase Auth test users** — all `TEST_ACCOUNTS` uids deleted (Auth is a separate store from Firestore, so this still runs explicitly).
+4. **Realtime Database** — the `_test` namespace removed in full (`admin.database().ref('_test').remove()`, guarded — RTDB is optional).
+
+After the flush, `test/_init.js`'s `setup()` reseeds fixtures into the empty DB.
 
 ### Marketing-provider cleanup
 
@@ -35,18 +54,44 @@ All cleanup follows the start-only rule. No trailing-cleanup exception.
 
 ### When adding a new test that writes data
 
-| If your test writes to... | Then... |
-|---|---|
-| A new Firestore collection (mixed test + prod data) | Add the collection name to `testDataCollections` in `src/test/test-accounts.js`. |
-| A new Firestore collection (test-only data) | Add it to `testOnlyCollections` in `src/test/test-accounts.js`. |
-| Realtime Database | Use a path under `_test/...` — already wiped pre-test. |
-| Anywhere else | Use the `_test-` doc-id prefix so id-keyed pass-2 catches it. |
+Nothing to register — the **entire emulator Firestore is flushed before every run**, so any collection a test writes starts empty next run automatically. If a test needs a fixture to exist (e.g. a brand doc) before the suite runs, seed it in `test/_init.js`'s `setup()` (it runs after the flush). Realtime Database test data should live under `_test/...` (that namespace is wiped pre-run).
 
 ### Within-run state isolation is different
 
-Per-test cleanup is still appropriate when a test sets up DB state that would pollute a **later test in the same run** — e.g. trial-eligibility's `try/finally` that removes the fake `payments-orders/_test-trial-eligibility-*` doc so the next sibling test sees a clean slate. Those stay in the test. They are *intra-run* state management, not *next-run* cleanup, and the distinction matters.
+Per-test cleanup is still appropriate when a test sets up DB state that would pollute a **later test in the same run** — e.g. a `try/finally` that removes a fixture so the next sibling test sees a clean slate. Those stay in the test. They are *intra-run* state management, not *next-run* cleanup, and the distinction matters.
+
+The rule: **never put cleanup at the END of a test file or suite for the purpose of preparing the next run** — for LOCAL state. The pre-test full flush already guarantees a clean slate. (The third-party provider exception lives in the runner's post-suite hook, not in individual tests.)
 
-The rule: **never put cleanup at the END of a test file or suite for the purpose of preparing the next run** — for LOCAL state. If a test cleans up local Firestore/Auth data only to "leave no trace," that cleanup belongs in the runner's pre-test phase instead. Add the collection/namespace to the runner's wipe list and remove the trailing cleanup step. The third-party provider exception (see above) lives in the runner's post-suite hook, not in individual tests.
+## `test/_init.js` — pre-test lifecycle hook
+
+The runner loads an optional `test/_init.js` from **both** test roots — BEM core (`<bem>/test/_init.js`) and the consumer project (`<projectDir>/test/_init.js`) — and runs it before any test (it is NOT itself run as a test). Same contract for both roots, so framework and consumer authors write the identical file. Because the entire emulator Firestore is flushed each run, there are **no collection lists to declare** — `_init.js` only declares accounts and reseeds fixtures.
+
+The module **must export a function** — `module.exports = (ctx) => ({ ... })` — called with `{ config, Manager }` and returning the hook object. (The function form lets a project compute its accounts/fixtures from config.) It may declare:
+
+- `accounts` — array of extra test accounts to create alongside the built-in ones (admin/basic/premium-*/journey-*), so this project has a user for each lifecycle it exercises. Each entry is `{ id, uid, email, properties }` (email may use the `{domain}` placeholder, `properties` is merged into the user doc after `auth:on-create`). These accounts are created, fetched (privateKeys), and deleted on the same path as the built-ins, and show up in the `accounts` map that tests and `setup()` receive. A project account may override a built-in one by reusing its `id`.
+- `async setup({ admin, config, accounts, Manager, assistant })` — seed fixtures (e.g. a brand doc) into the freshly-flushed DB, AFTER the clean slate + account creation. `accounts` is available so fixtures can reference a test uid. Use real ids that mirror production shape (no `_test-` prefix needed — the whole DB is wiped each run).
+
+There is **no `cleanup` hook**: the entire emulator Firestore is flushed before every run and each test cleans up after itself, so there is nothing project-level to tear down.
+
+```javascript
+// <projectDir>/test/_init.js
+module.exports = ({ config }) => ({
+  // One account per lifecycle this project needs. Created alongside the built-ins.
+  accounts: [
+    { id: 'shop-owner', uid: '_test-shop-owner', email: '_test.shop-owner@{domain}', properties: { roles: {} } },
+  ],
+
+  // The entire emulator Firestore is flushed before each run, so just reseed.
+  async setup({ admin, accounts }) {
+    await admin.firestore().doc('brands/ultimate-jekyll').set({
+      id: 'ultimate-jekyll',
+      brand: { id: 'ultimate-jekyll', name: 'Ultimate Jekyll', url: 'https://ultimate-jekyll.itwcreativeworks.com' },
+      owner: accounts['shop-owner'].uid,
+      sponsorships: { prices: { 'guest-post': 50, 'link-insertion': 30 } },
+    });
+  },
+});
+```
 
 ## Extended Mode (`TEST_EXTENDED_MODE`)
 
@@ -118,13 +163,15 @@ npx mgr test user/ admin/       # Multiple paths
 
 ## Test Locations
 
-- **BEM core tests:** `test/`
-- **Project tests:** `functions/test/bem/`
+- **BEM core tests:** `test/` (in the framework repo)
+- **Project tests:** the consumer project's repo-root `test/` directory (NOT inside `functions/`)
 
-Use `bem:` or `project:` prefix to filter by source.
+Use `bem:` or `project:` prefix to filter by source. **Mirror the source path so a test reads like what it tests.** Route tests live under `test/routes/<route-path>/<concern>.js`, mirroring `functions/routes/<route-path>/` — e.g. `functions/routes/write/article/` → `test/routes/write/article/generate.js`, `functions/routes/sponsorship/post.js` → `test/routes/sponsorship/post.js`. Split each route into **one file per concern** under its mirrored dir (`test/routes/sponsorship/post.js`, `.../manual-validation.js`), never one giant `test/test.js`. The runner discovers files by directory, so the split also drives the `project:<path>` filter: `npx mgr test project:routes/write` runs a whole route's tests, `project:routes/write/markdown` runs one concern.
 
 ## Test Types
 
+> **The runner reads each file's `module.exports` object — it does NOT inject Mocha/Jest globals.** A test file that calls `describe`/`it`/`before`/`beforeEach`/`after` at top level throws `ReferenceError: beforeEach is not defined` and shows as `Failed to load`. There is no global `assert` either — use the `assert` passed into `run({ assert })`. Every test file MUST export one of the shapes below.
+
 | Type | Use When | Behavior |
 |------|----------|----------|
 | Standalone | Single logical test | Runs once |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.2.18",
+  "version": "5.3.0",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/src/cli/commands/base-command.js

@@ -3,6 +3,7 @@ const { confirm } = require('@inquirer/prompts');
 const { execSync, spawn } = require('child_process');
 const path = require('path');
 const jetpack = require('fs-jetpack');
+const ui = require('../utils/ui');
 
 class BaseCommand {
   constructor(main) {
@@ -10,6 +11,9 @@ class BaseCommand {
     this.firebaseProjectPath = main.firebaseProjectPath;
     this.argv = main.argv;
     this.options = main.options;
+    // Shared OMEGA-style CLI styling helpers (dividers, headers, status lines).
+    // See src/cli/utils/ui.js. Use `this.ui.*` in any command for consistent output.
+    this.ui = ui;
   }
 
   async execute() {

package/src/cli/commands/install.js

@@ -8,9 +8,9 @@ const wonderfulVersion = require('wonderful-version');
 
 class InstallCommand extends BaseCommand {
   async execute(type) {
-    if (type === 'local' || type === 'dev' || type === 'development') {
+    if (['local', 'l', 'dev', 'd', 'development'].includes(type)) {
       await this.installLocal();
-    } else if (type === 'live' || type === 'prod' || type === 'production') {
+    } else if (['live', 'prod', 'p', 'production'].includes(type)) {
       await this.installLive();
     }
   }