backend-manager 5.2.19 → 5.3.1

package/CHANGELOG.md

@@ -14,6 +14,30 @@ 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.1] - 2026-06-02
+
+### Fixed
+- **Leaking `wonderful-fetch` mock in the webhook-forward unit test.** `test/helpers/webhook-forward.js` installs a stub into `require.cache['wonderful-fetch']` at module load (the sanctioned cross-project fan-out exception — there's no second BEM emulator to receive the real fan-out POSTs), but never restored it. Because every test file is `require()`d into the same process, the stub leaked process-wide: every later test whose route did `require('wonderful-fetch')` got `{ received: true }` in 0ms instead of a real HTTP round-trip (observed breaking consumer sponsorship + inbound-email route tests). The helper now saves the original cache entry and restores it in a suite-level `cleanup()`, confining the mock to its own file.
+
+# [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

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).
@@ -107,7 +108,7 @@ Deep references live in `docs/`. **Whenever you make a behavioral change, update
 - [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/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) — `assistant.isDevelopment/isProduction/isTesting()`
+- [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
@@ -129,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. **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.** 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/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/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`)
 
@@ -121,7 +166,7 @@ npx mgr test user/ admin/       # Multiple paths
 - **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. Mirror BEM's own per-area layout — **one file per concern** under `test/<area>/` (e.g. `test/article/allocation.js`, `test/article/markdown.js`, `test/article/generate.js`), never one giant `test/test.js`. The runner discovers files by directory, so the split is also what the `project:<path>` filter targets (`npx mgr test project:article`).
+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
 

package/package.json

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

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();
     }
   }

package/src/cli/commands/setup.js

@@ -195,10 +195,14 @@ class SetupCommand extends BaseCommand {
       const rel = path.relative(defaultsDir, src);
       const segments = rel.split(path.sep);
 
-      // Skip "archive" directories — anything under a path segment starting with `_` and
-      // followed by a non-`.` character. Matches EM/BXM/UJM convention. The `_.env` /
-      // `_.gitignore` files are NOT skipped; their leading `_` strips on copy below.
-      if (segments.some((s) => s.startsWith('_') && !s.startsWith('_.'))) {
+      // Skip "archive" DIRECTORIES — any non-final path segment starting with `_` and
+      // followed by a non-`.` character (e.g. `_legacy/`). Matches EM/BXM/UJM convention.
+      // The check is restricted to directory segments (all but the last) so a `_`-prefixed
+      // FILENAME still ships — e.g. `test/_init.js` copies verbatim (the test runner skips
+      // it from discovery on its own). The `_.env` / `_.gitignore` files are likewise not
+      // skipped; their leading `_` strips on copy below.
+      const dirSegments = segments.slice(0, -1);
+      if (dirSegments.some((s) => s.startsWith('_') && !s.startsWith('_.'))) {
         continue;
       }
 
@@ -274,6 +278,10 @@ class SetupCommand extends BaseCommand {
     // Get all tests
     const tests = testRegistry.getTests(testContext);
 
+    // Expose the total count so the per-check `[N]` prefix can right-align its
+    // width (single- vs double-digit indices stay aligned).
+    self.testTotalExpected = tests.length;
+
     // Run each test
     for (const test of tests) {
       await self.test(

package/src/cli/commands/test.js

@@ -36,7 +36,7 @@ class TestCommand extends BaseCommand {
       const envSubset = captureSyncedEnv(process.env);
       writeTestMode(projectDir, envSubset);
       const extended = !!process.env.TEST_EXTENDED_MODE;
-      this.log(chalk.gray(`  Test mode: ${extended ? 'EXTENDED (real APIs)' : 'normal (mocked)'}`));
+      this.log(chalk.gray(`  Test mode: ${extended ? 'extended (real external APIs)' : 'normal (external APIs skipped)'}`));
     }
 
     // Load emulator ports from firebase.json

package/src/cli/index.js

@@ -168,12 +168,16 @@ Main.prototype.test = async function(name, fn, fix, args) {
   const ui = require('./utils/ui');
 
   // Prints `    [N] <symbol> <name>` — the OMEGA-style per-check status line
-  // (indented one level under the `[CHECKS]` section label).
+  // (indented one level under the `[CHECKS]` section label). The `[N]` bracket
+  // is padded to the width of the total check count so single- and double-digit
+  // numbers (`[1] ` … `[13]`) keep the symbols/names aligned.
+  const indexWidth = String(self.testTotalExpected || 99).length;
   const printLine = (index, kind, label) => {
     const colorByKind = { pass: chalk.green, fail: chalk.red, warn: chalk.yellow };
     const color = colorByKind[kind] || chalk.white;
     const suffix = label ? ` ${chalk.dim(label)}` : '';
-    console.log(`${ui.indent(2)}${chalk.dim(`[${index}]`)} ${color(ui.SYMBOLS[kind])} ${name}${suffix}`);
+    const bracket = `[${index}]`.padEnd(indexWidth + 2, ' ');
+    console.log(`${ui.indent(2)}${chalk.dim(bracket)} ${color(ui.SYMBOLS[kind])} ${name}${suffix}`);
   };
 
   let passed = await fn();

package/src/defaults/CLAUDE.md

@@ -24,12 +24,12 @@ npx mgr logs:read         # read Cloud Functions logs (also: logs:tail to stream
 npx mgr firestore:get     # read a doc from Firestore (also: firestore:set / :query / :delete)
 npx mgr auth:get          # read an Auth user (also: auth:list / :delete / :set-claims)
 npx mgr install dev       # use LOCAL backend-manager source (to test framework edits)
-npx mgr install prod      # restore the published backend-manager from npm
+npx mgr install live      # restore the published backend-manager from npm
 ```
 
 All `npx mgr <cmd>` aliases — `npx bm <cmd>`, `npx bem <cmd>`, `npx backend-manager <cmd>` work too.
 
-> Editing the BEM framework source while working here? Run `npx mgr install dev` so this project picks up your uncommitted framework changes (it otherwise uses its installed `node_modules/backend-manager`). Run `npx mgr install prod` to switch back.
+> Editing the BEM framework source while working here? Run `npx mgr install dev` so this project picks up your uncommitted framework changes (it otherwise uses its installed `node_modules/backend-manager`). Run `npx mgr install live` to switch back.
 
 ## Where things live
 

package/src/defaults/test/_init.js

@@ -0,0 +1,14 @@
+/**
+ * Test lifecycle hook for this project. Runs before any test (not a test itself).
+ * See backend-manager/docs/testing.md → "test/_init.js".
+ */
+
+module.exports = ({ config }) => ({
+  // Extra test accounts (one per lifecycle this project exercises):
+  // { id, uid, email, properties }. email may use the {domain} placeholder.
+  accounts: [],
+
+  // Seed fixtures into the freshly-flushed emulator, after accounts are created.
+  async setup({ admin, accounts }) {
+  },
+});

package/src/manager/functions/_legacy/actions/create-post-handler.js

@@ -51,7 +51,7 @@ let Module = {
         assistant.error(response.error)
       } else {
         mailchimp = new Mailchimp(self.Manager.config?.mailchimp?.key ?? '');
-        await fetch(`${self.Manager.project.apiUrl}/backend-manager`, {
+        await fetch(`${self.Manager.getApiUrl()}/backend-manager`, {
           method: 'POST',
           response: 'json',
           body: {

package/src/manager/functions/core/actions/api/admin/edit-post.js

@@ -100,7 +100,7 @@ Module.prototype.fetchPost = function (url) {
   const payload = self.payload;
 
   return new Promise(async function(resolve, reject) {
-    fetch(`${Manager.project.apiUrl}/backend-manager`, {
+    fetch(`${Manager.getApiUrl()}/backend-manager`, {
       method: 'post',
       response: 'json',
       timeout: 190000,

package/src/manager/functions/core/actions/api/general/send-email.js

@@ -83,7 +83,7 @@ Module.prototype.main = function () {
     assistant.log('Email payload:', emailPayload);
 
     // Send the email via admin:send-email
-    await fetch(`${Manager.project.apiUrl}/backend-manager`, {
+    await fetch(`${Manager.getApiUrl()}/backend-manager`, {
       method: 'post',
       response: 'json',
       log: true,

package/src/manager/functions/core/actions/api/user/delete.js

@@ -29,7 +29,7 @@ Module.prototype.main = function () {
 
       // Signout of all sessions
       assistant.log(`Signout of all sessions...`);
-      await fetch(`${self.Manager.project.apiUrl}/backend-manager`, {
+      await fetch(`${self.Manager.getApiUrl()}/backend-manager`, {
         method: 'post',
         timeout: 60000,
         response: 'json',

package/src/manager/functions/core/actions/api/user/oauth2.js

@@ -40,7 +40,7 @@ Module.prototype.main = function () {
         : payload.data.payload.referrer
 
       payload.data.payload.serverUrl = typeof payload.data.payload.serverUrl === 'undefined'
-        ? `${Manager.project.apiUrl}/backend-manager`
+        ? `${Manager.getApiUrl()}/backend-manager`
         : payload.data.payload.serverUrl
 
       payload.data.payload.provider = payload.data.payload.provider || '';

package/src/manager/helpers/analytics.js

@@ -43,7 +43,9 @@ function Analytics(Manager, options) {
   // Fix options
   options.dataSource = options.dataSource || 'server';
   options.uuid = options.uuid || self.request.ip || Manager.SERVER_UUID;
-  options.isDevelopment = typeof options.isDevelopment === 'undefined' ? self.assistant.isDevelopment() : options.isDevelopment;
+  // Skip real analytics in ANY non-production environment (development OR testing) so
+  // test/dev runs never pollute GA4. Intentional `!isProduction()` check.
+  options.isDevelopment = typeof options.isDevelopment === 'undefined' ? !self.assistant.isProduction() : options.isDevelopment;
   options.pageview = typeof options.pageview === 'undefined' ? true : options.pageview;
   options.version = options.version || Manager.package.version;
   options.userProperties = options.userProperties || {};