@omega.js/backend 0.1.0

package/docs/usage-rate-limiting.md

@@ -0,0 +1,121 @@
+# Usage & Rate Limiting
+
+## The one call
+
+```js
+module.exports = async ({ ctx }) => {
+  const left = await ctx.usage.consume('saves');   // throws a 429 over limit
+
+  // ... do the work the user paid for
+  return ctx.respond({ saved: true, left: left.left });
+};
+```
+
+`consume` checks both counters, refuses with a 429 that names WHICH one hit, else counts, writes, and returns what is left. There is no "validate then increment then update" dance to get half right — every hand-rolled gate that used to live in a route existed because there was one.
+
+## What a feature IS lives in config, once
+
+A feature is defined ONCE, in the top-level `features` catalog, and each product names only its VALUE ([docs/shared/config.md](../../../docs/shared/config.md)):
+
+```json5
+{
+  features: {
+    saves:   { name: 'Saves', icon: 'feather', definition: 'Notes you can save.',
+               usage: { pace: 'daily', mirror: ['teams'] } },
+    support: { name: 'Priority support', icon: 'headset' },
+  },
+  payment: {
+    products: [
+      { id: 'basic',   name: 'Basic',   features: { saves: 100 } },
+      { id: 'premium', name: 'Premium', features: { saves: -1, support: true } },
+    ],
+  },
+}
+```
+
+- A `usage` block makes the entry **counted** (metered per user). An entry without one is a **perk** and is never counted — `consume('support')` is a 500, not a silent gate.
+- A counted feature's product value is its **monthly limit**, as a number. `-1` is unlimited. `false` (or absent) means the tier does not include it, which reads as a limit of `0`: every call refuses.
+- A perk's value is `true` / `false` / a string.
+- The validator fails a number on a perk and a perk value on a counted feature, so a plan can never advertise a meter nothing enforces.
+
+## Two counters, and the day's share
+
+Every counted feature carries two counters per user: **month** and **day**.
+
+| Field | What it is |
+|---|---|
+| `monthly` | This month's count, reset on the 1st by cron |
+| `daily` | Today's count, reset every day by cron |
+| `total` | All-time count, never resets |
+| `last` | `{ timestamp, timestampUNIX }` of the last time it moved |
+
+The day's share is `ceil(monthly limit / days in this month)`, so a quota of 100 in a 31-day month allows 4 a day and can never be burned on day one. **Unused day share expires at midnight** — it never rolls forward.
+
+Pacing by day is the **default**. `usage: { pace: false }` on the catalog entry opts a feature out to a plain monthly counter (`day.limit` reads `-1`, and the day never refuses).
+
+**Either counter full refuses, and the month cap always holds.** `consume` checks the MONTH first — a spent month is not "try again tomorrow":
+
+| State | The 429 says |
+|---|---|
+| Month spent | `You have used all 100 of your Saves this month (100/100). Upgrade your plan for more.` |
+| Day's share spent, month has room | `You have used today's Saves (4/4 of the 100 on your plan this month). Try again tomorrow.` |
+
+## Per-user overrides
+
+`user.usage.overrides.<feature>` is a number that **wins over the plan's**: extra credits granted to one account, not a second pricing tier. The day's share derives from the effective number, so an override of 300 on a 31-day month allows 10 a day rather than the plan's 4.
+
+`usage` is a framework field the Firestore rules deny every client ([templates/firestore.framework.rules](../templates/firestore.framework.rules)), so an override can only ever be server-written — which is what makes it trustworthy as a limit. The reset cron never touches it.
+
+## The API
+
+`ctx.usage` is attached to every route by the middleware. Attaching is **synchronous and I/O-free**: the counter resolves the account on the first `consume`/`read`, so a route that never counts pays nothing.
+
+| Method | What it does |
+|---|---|
+| `consume(feature, amount = 1, options?)` | async — check, count, write. Throws a 429 over limit; returns `{ used, left, day: { used, left } }` |
+| `read(feature)` | async — the same numbers plus `limit`, `planLimit`, `override`, `day.limit`, without counting |
+| `forKey(key)` | A SEPARATE counter for an anonymous key (see below) |
+| `limits()` / `counters()` | What the counter already KNOWS — the `omega-properties` header's `usage.limits` / `usage.current`; empty until it has resolved |
+| `getProduct(id?)` | The account's resolved product |
+| `addWhitelistKeys(keys)` | API keys that never get refused (they still count) |
+
+`options.limit` is for the counters that are **not plan features** — a per-IP signup gate is a security control with its own declared config key (`targets.backend.auth.signup.maxPerIpPerDay`), not a tier anybody buys. An explicit limit supplies the definition the catalog would have, so the catalog lookup and the product read are skipped and the counter is a plain period counter with no day share. The framework's own anti-abuse gates use it: signup-by-IP, `marketing/contact`, `marketing/email-preferences`.
+
+Every derivation — the effective limit, the day share, what is left — lives in `@omega.js/account`'s features module, the SAME one the browser's account page reads through `@omega.js/client/modules/features.js`. The number that refuses a request and the number a usage bar draws can never be two different numbers.
+
+## Anonymous counting is explicit
+
+```js
+await ctx.usage.forKey(ctx.request.geolocation.ip).consume('marketing-subscribe', 1, { limit: 5 });
+```
+
+`forKey` returns a **separate** counter bound to that key, writing to `usage/{key}` (or a local temp store when `unauthenticatedMode: 'local'`). Passing a key can never silently move a signed-in user's own counters into the anonymous store, which is exactly what the old `options.key` did.
+
+Keyed counters are **day-only in practice**: the cron wipes the whole anonymous store daily, so an anonymous monthly limit cannot exist.
+
+**`ctx.usage` refuses a signed-out caller.** `consume`/`read` on a request with no uid throws `usage: no signed-in account to count against; use usage.forKey(<key>) for anonymous callers`. It does not fall back to the anonymous store: routing there silently would be the very bug `forKey` exists to remove, and counting on the user doc would write `users/null` — one document every anonymous caller on earth would share.
+
+## Mirrors are declared in the catalog
+
+`usage: { mirror: ['teams'] }` on a catalog entry says a feature's counters also land on every document the account owns of that kind — resolved from `user.owns.teams` (a framework field, server-written like `usage`). `consume` writes the touched feature's counters to the user doc and every mirror in ONE parallel write:
+
+```
+users/{uid}          ← { usage: { saves: { monthly, daily, total, last } } }
+teams/{teamId}       ← the same patch
+```
+
+It writes **that feature's counters only**, never the whole usage object, so two features counted in the same second cannot overwrite each other. There is no call-site mirror API — nothing to re-derive per route.
+
+## Reset schedule
+
+| Target | Frequency | What happens |
+|---|---|---|
+| Local storage | Daily | Cleared entirely |
+| `usage` collection (anonymous keys) | Daily | Deleted entirely |
+| User doc `usage.<feature>.daily` | Daily | Reset to 0 |
+| User doc `usage.<feature>.monthly` | Monthly (1st) | Reset to 0 |
+| User doc `usage.overrides` | Never | Untouched — a reset is not a revoke |
+
+The daily cron (`events/cron/daily/reset-usage.js`) runs at midnight UTC, and performs a single write per user.
+
+**Which counters reset is a question of SHAPE, not of catalog membership.** The cron QUERIES on the counted features the catalog defines plus the framework's own gates (a Firestore query has to name a field path), but once it has the document it clears every counter-shaped key under `usage` — so a counter run against an explicit limit, which by definition has no catalog entry, resets like any other. Sweeping only the catalog left those growing forever, which permanently refused the user after their first few uses.

package/docs/verts.md

@@ -0,0 +1,29 @@
+# Verts — house inventory module (adblock-safe ad system)
+
+The backend half of the OMEGA ads system (spec: monorepo `docs/web/ads-system.md`): a brand (or the parent COMPANY — sub-brands point at its api) hosts its own ad inventory and serves self-contained ad units. Providers (AdSense) and the fallback ladder live in the client (`verts/unit` section) — this module is the in-house lane they fall back to.
+
+## Firestore collection `verts`
+
+`{ enabled, title, description, button, link, image, footer, weight (default 1), targeting: { sites: [], categories: [], keywords: [] }, whitelist: [], blacklist: [], metadata }`
+
+Client-inaccessible by rules (the framework's default admin-only lock — proven by `test/rules/verts.test.js`); ALL access rides the routes.
+
+## Routes
+
+| Route | Auth | Behavior |
+|---|---|---|
+| `GET /omega/verts/serve` | public | `parent, tags, width, height, theme ('' \| light \| dark), vertId` → a SELF-CONTAINED HTML ad unit (inline CSS/JS, light/dark theming, origin-checked postMessage `omega-vert:set-dimensions` via ResizeObserver + `omega-vert:click`, zero timers — the HOST owns rotation/staleness recovery), or **204 on no fill** (the host's fallback ladder moves on). A transient Firestore error while reading inventory also degrades to last-good inventory or a 204 rather than surfacing a 500 on this public route; the cache timestamp is left untouched so the next impression retries. The postMessage target origin PRESERVES an explicit parent port (`localhost:4100` → `http://localhost:4100` via `normalizeOrigin`) — a port-stripped origin would silently drop every report in local dev |
+| `GET /omega/verts/redirect?id&parent` | public | fail-closed click hop: 302 ONLY to the ad's STORED http(s) link + `utm_source=<parent>`/`utm_medium=omega-vert`/`utm_campaign=<vertId>`; a utm key the advertiser already put on the link WINS (the tagger only fills what is missing, so nothing double-appends); unknown id or non-http link → 404; caller-supplied URLs are never redirected to. The tagging itself is `applyVertUtm` in `@omega.js/client`'s `modules/vert-document.js` — the same function the client's promo lane tags its own link with |
+| `GET/POST/PUT/DELETE /omega/verts` | admin | schema-validated CRUD; PUT edits provided fields only (id/created immutable); writes bust the inventory cache |
+
+## Selection pipeline (`routes/verts/utils.js`)
+
+Eligibility (enabled ≠ false → whitelist [fail-closed on unknown parent] → blacklist → never-advertise-self via normalized link-host == parent-host) → optional eligible `vertId` pin → contextual score (overlap count of the ad's flattened targeting tags × the request's tags; no tags anywhere = neutral) → weighted random among the TOP scorers (`weight` default 1).
+
+## Inventory cache
+
+Module-level, shared by serve + redirect: ~5 min TTL in production (one Firestore read per instance per interval — runtime serving at ~zero read cost per impression), TTL 0 under the emulator for determinism, `resetInventoryCache()` on every CRUD write + as the test seam. View/click events track server-side via the standard `analytics.event()` lane (no gtag inside the frame).
+
+## Tests
+
+`test/routes/verts/{selection,cache,serve,redirect,crud,click-destination}.test.js` + `test/rules/verts.test.js` — 57 tests: scoring/eligibility, cache TTL, serve round-trip (200 HTML / 204 no-fill / XSS escaping / port-preserving target origin), redirect fail-closed + UTM, CRUD auth gates, rules lock. The cross-brand company-mode e2e (monorepo `scripts/e2e-verts-company.js`, root `npm run test:verts`) exercises the same routes through a real consumer resolution. Serve/redirect round-trips use raw `fetch` (HTML/302 can't ride the JSON `http` client — mcp-test precedent).

package/package.json

@@ -0,0 +1,143 @@
+{
+  "name": "@omega.js/backend",
+  "version": "0.1.0",
+  "description": "OMEGA backend framework — build, test, and deploy Firebase Cloud Functions backends",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/manager/index.js",
+  "files": [
+    "bin/",
+    "dist/",
+    "docs/",
+    "templates/",
+    "test/",
+    "cli.js"
+  ],
+  "bin": {
+    "omega": "./bin/omega",
+    "omg": "./bin/omg",
+    "mgr": "./bin/omega",
+    "omega-backend": "./bin/omega-backend"
+  },
+  "scripts": {
+    "start": "npm run prepare:watch",
+    "test": "node src/test/parse-audit.js && node bin/omega-backend test",
+    "prepare": "node -e \"require('@omega.js/devkit/prepare-guard')() && require('prepare-package')()\"",
+    "prepare:watch": "node -e \"require('prepare-package/watch')()\""
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "omega": {
+    "functionsRuntime": "22",
+    "testLanes": [
+      "stripe-live"
+    ]
+  },
+  "projectScripts": {
+    "start": "omega serve",
+    "deploy": "omega deploy",
+    "emulator": "omega emulator",
+    "test": "node --require ./test/_helpers/connect-trap.js --test 'test/_unit/**/*.test.js'",
+    "test:static": "npm test",
+    "test:emulator": "omega test"
+  },
+  "projectScriptsCustomOwned": [
+    "start",
+    "deploy",
+    "emulator",
+    "test:emulator"
+  ],
+  "keywords": [
+    "omega",
+    "firebase",
+    "firebase-functions",
+    "cloud-functions",
+    "firestore",
+    "backend",
+    "serverless",
+    "api",
+    "express",
+    "cli"
+  ],
+  "author": "ITW Creative Works",
+  "license": "Elastic-2.0",
+  "preparePackage": {
+    "input": "./src",
+    "output": "./dist",
+    "replace": {},
+    "type": "copy",
+    "hooks": {
+      "before": "node scripts/update-disposable-domains.js",
+      "after": [
+        "node -e \"require('@omega.js/devkit/vendor')()\"",
+        "node -e \"require('@omega.js/devkit/prepare-guard').rewire()\""
+      ],
+      "afterBlocking": true
+    }
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.153",
+    "@anthropic-ai/sdk": "^0.99.0",
+    "@firebase/rules-unit-testing": "^5.0.1",
+    "@google-cloud/firestore": "^7.11.6",
+    "@google-cloud/pubsub": "^5.3.1",
+    "@google-cloud/storage": "^7.21.0",
+    "@inquirer/prompts": "^8.5.2",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@octokit/rest": "^22.0.1",
+    "@omega.js/client": "0.1.0",
+    "@resvg/resvg-js": "^2.6.2",
+    "@sendgrid/mail": "^8.1.6",
+    "@sentry/node": "^10.54.0",
+    "body-parser": "^2.3.0",
+    "busboy": "^1.6.0",
+    "chalk": "^5.6.2",
+    "cheerio": "^1.2.0",
+    "cors": "^2.8.6",
+    "dotenv": "^17.4.2",
+    "express": "^5.2.1",
+    "fast-xml-parser": "^5.9.3",
+    "fs-jetpack": "^5.1.0",
+    "glob": "^13.0.6",
+    "hcaptcha": "^0.2.0",
+    "itwcw-package-analytics": "^1.0.8",
+    "json5": "^2.2.3",
+    "jwt-decode": "^4.0.0",
+    "lodash": "^4.18.1",
+    "lowdb": "^7.0.1",
+    "markdown-it": "^14.2.0",
+    "mime-types": "^3.0.2",
+    "minimatch": "^10.2.5",
+    "mjml": "^5.3.0",
+    "moment": "^2.30.1",
+    "nanoid": "^5.1.11",
+    "node-powertools": "^3.0.0",
+    "pushid": "^1.0.0",
+    "sanitize-html": "^2.17.5",
+    "sharp": "^0.35.2",
+    "stripe": "^22.2.0",
+    "uid-generator": "^2.0.0",
+    "uuid": "^14.0.1",
+    "wonderful-fetch": "^2.0.5",
+    "wonderful-log": "^1.0.7",
+    "wonderful-version": "^1.3.2",
+    "yaml": "^2.9.0",
+    "yargs": "^18.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@omega.js/account": "*",
+    "@omega.js/analytics": "*",
+    "@omega.js/config": "*",
+    "@omega.js/devkit": "*",
+    "@omega.js/monitoring": "*",
+    "prepare-package": "^2.2.0"
+  },
+  "peerDependencies": {
+    "firebase-admin": "^13.10.0",
+    "firebase-functions": "^7.2.5"
+  }
+}

package/templates/config/omega.json5

@@ -0,0 +1,322 @@
+// omega.json5 — the ONE config file for every OMEGA project type.
+//
+// Shared sections (brand, cloud, analytics, payment, monitoring, connections)
+// sit at the top level with identical spelling in every omega.json5. Backend
+// settings live under targets.backend — key presence under `targets` means
+// "this project supports this target".
+//
+// This file doubles as @omega.js/backend's framework-defaults layer: the Manager
+// resolves it through @omega.js/config and merges the consumer's own
+// functions/config/omega.json5 on top. Secrets NEVER live here — they go in
+// functions/.env (the loader hard-fails on secret-shaped keys).
+{
+  brand: {
+    id: 'my-app',
+    name: 'My Brand',
+    description: '',
+    url: 'https://example.com',
+    contact: {
+      email: 'support@example.com',
+      // Email identity — deliberately UNSET here so this defaults layer never supplies
+      // an identity a brand did not choose. Set them in your own config when needed:
+      //   person:     { name: 'Jane Doe, CEO', firstName: 'Jane', image, url, urlText }
+      //               required to send email with a "personal" signoff (the send throws without it)
+      //   carbonCopy: [{ email: 'audit@example.com', name: 'Audit' }]
+      //               audit BCCs added to transactional sends with copy: true
+    },
+    // Physical postal address — required by CAN-SPAM in commercial email footers.
+    // Rendered in the newsletter footer + transactional email footers.
+    // Structured so the renderer can format it consistently across locales
+    // and break onto multiple lines if needed. line2/region/postalCode are optional.
+    address: {
+      line1: '123 Main St',
+      line2: 'Suite 100',
+      city: 'City',
+      region: 'ST',
+      postalCode: '12345',
+      country: 'United States',
+    },
+    images: {
+      wordmark: 'https://example.com/wordmark.png',
+      brandmark: 'https://example.com/wordmark.png',
+      combomark: 'https://example.com/combomark.png',
+    },
+  },
+  monitoring: {
+    providers: {
+      sentry: {
+        dsn: 'https://d965557418748jd749d837asf00552f@o777489.ingest.sentry.io/8789941',
+      },
+    },
+  },
+  analytics: {
+    providers: {
+      google: {
+        id: null,
+      },
+      meta: {
+        id: null,
+      },
+      tiktok: {
+        id: null,
+      },
+    },
+  },
+  connections: {},
+  // The feature catalog (#647): every feature is defined ONCE here — name,
+  // icon, definition, and a `usage` block on the ones that are METERED (day
+  // pacing is the default; `pace: false` opts out; `mirror` names the document
+  // kinds a feature's counters also land on). No `usage` block = a perk. The
+  // products below name only their VALUE.
+  features: {
+    requests: {
+      name: 'API Requests',
+      icon: 'bolt',
+      definition: 'Calls this project may make per month.',
+      usage: {},
+    },
+  },
+  payment: {
+    providers: {
+      stripe: {
+        publishableKey: null,
+      },
+      paypal: {
+        clientId: null,
+      },
+      chargebee: {
+        site: null,
+      },
+    },
+    products: [
+      {
+        id: 'basic',
+        name: 'Basic',
+        type: 'subscription',
+        features: {
+          requests: 100,
+        },
+      },
+      {
+        id: 'premium',
+        name: 'Premium',
+        type: 'subscription',
+        features: {
+          requests: 1000,
+        },
+        trial: {
+          days: 14,
+        },
+        prices: {
+          monthly: 4.99,
+          annually: 49.99,
+        },
+        stripe: {
+          productId: null,
+        },
+        paypal: {
+          productId: null,
+        },
+        chargebee: {
+          itemId: null,
+          legacyPlanIds: [],
+        },
+      },
+      {
+        id: 'ultimate',
+        name: 'Ultimate',
+        type: 'subscription',
+        features: {
+          requests: 10000,
+        },
+        prices: {
+          monthly: 19.99,
+          annually: 199.99,
+        },
+        stripe: {
+          productId: null,
+        },
+        paypal: {
+          productId: null,
+        },
+        chargebee: {
+          itemId: null,
+          legacyPlanIds: [],
+        },
+      },
+      {
+        id: 'credits-100',
+        name: '100 Credits',
+        type: 'one-time',
+        prices: {
+          once: 9.99,
+        },
+        stripe: {
+          productId: null,
+        },
+        chargebee: {
+          itemId: null,
+        },
+      },
+      // Add more products/tiers here
+    ],
+  },
+  cloud: {
+    provider: 'firebase',
+    config: {
+      apiKey: '123-456',
+      authDomain: 'YOUR-BRAND-DOMAIN.com', // brand host — the web build self-hosts /__/auth/*
+      projectId: 'PROJECT-ID',
+      storageBucket: 'PROJECT-ID.appspot.com',
+      messagingSenderId: '123',
+      appId: '1:123:web:456',
+      measurementId: 'G-0123456789',
+    },
+  },
+
+  // ─── Backend target ────────────────────────────────────────────────────────
+  // Key presence = this project supports the backend target. Any shared key may
+  // also appear here as a backend-only override (e.g. a per-surface
+  // monitoring.providers.sentry.dsn).
+  targets: {
+    backend: {
+      // 'self' = this @omega.js/backend is the parent (newsletter-sources provider);
+      // a URL = external parent (e.g. 'https://api.itwcreativeworks.com') —
+      // used by the newsletter generator to pull sources; '' = no parent
+      parent: '',
+      // The brand repo the content routes (admin/post CMS, content/post)
+      // commit to. `repo` is optional — "owner/name" slug or bare name;
+      // name defaults to brand.id, owner to repo.providers.github.org (shared derivation:
+      // @omega.js/config brandRepoName/brandRepoOwner). Deliberately empty
+      // by default so the routes' "not configured" guard fires instead of
+      // aiming a real GH_TOKEN at a placeholder repo.
+      github: {
+        user: '',
+        repo: '',
+      },
+      auth: {
+        signup: {
+          // Signups allowed per client IP per day. The beforeUserCreated guard
+          // blocks the rest. Raise it when your audience shares egress (NAT/CGNAT,
+          // VPNs, offices, campuses), where one IP fronts many real people.
+          maxPerIpPerDay: 2,
+        },
+      },
+      marketing: {
+        campaigns: {
+          enabled: true,
+          providers: {
+            sendgrid: {
+              listId: '',  // SendGrid Marketing list UUID. Populated by OMEGA's campaigns/ensure/list.js. Skips runtime list-discovery API call.
+            },
+          },
+        },
+        newsletter: {
+          enabled: false,
+          providers: {
+            beehiiv: {
+              publicationId: '',  // Beehiiv publication ID (e.g., 'pub_xxxxx'). Populated by OMEGA's newsletter/ensure/publication.js. Required for marketing sync to Beehiiv.
+            },
+          },
+          // Content is PIPELINE config, not Beehiiv config, so it stays role-level.
+          // Single object or array (matches blog config shape). Generator uses the first entry.
+          content: [
+            {
+              sources: ['$parent'],    // '$parent' | '$feed:https://...' | '$brand'
+              sourceCount: 6,          // how many sources are picked (randomly) per issue
+              categories: [],          // e.g., ['social-media', 'marketing'] — topic constraints + AI categorization
+              links: [],               // links to inject into generated content
+              instructions: '',        // free-form text passed to the AI
+              tone: 'professional',    // 'professional' | 'casual' | 'actionable' | 'witty' | etc.
+              keywords: [],            // SEO keywords to weave in
+              template: 'clean',       // 'clean' | 'editorial' | 'field-report' — layout template
+              article: {
+                enabled: false,        // expand lead section into a full blog post via Ghostii
+                author: null,
+              },
+              theme: {
+                primaryColor: '#5B5BFF',
+                secondaryColor: '#1E1E2A',
+                accentColor: '#F6F7FB',
+                font: 'Inter, system-ui, sans-serif',
+              },
+              sponsorships: [],
+            },
+          ],
+        },
+        // Monthly contact prune (deletes cold contacts from your mail providers).
+        // OPT-IN: nothing runs unless enabled is true — see @omega.js/backend's
+        // docs/marketing-campaigns.md (Contact Pruning).
+        prune: {
+          enabled: false,
+        },
+      },
+      // Standalone blog auto-publisher (daily cron). OPT-IN: disabled by default.
+      // Set enabled: true and quantity >= 1 to auto-publish independent blog posts.
+      // For newsletter-linked articles, use marketing.newsletter.content.article.enabled instead.
+      //
+      // The key under `providers` selects the article-generation provider
+      // (only 'ghostii' for now).
+      //
+      // Source types:
+      //   '$brand'                          — generic brand-topic generation
+      //   '$feed:https://example.com/feed'  — RSS/Atom/JSON feed: pick one unprocessed article per run
+      //   '$parent'                         — fetch sources from parent server's source pool (without claiming)
+      //   'https://example.com/page'        — fetch URL content as prompt seed
+      //   'Write about topic X'             — text: use directly as prompt seed
+      //
+      // All feed/parent sources are tracked in Firestore (`content-sources`) so the same
+      // article is never reprocessed. When a feed is unreachable or exhausted, falls back to $brand.
+      blog: {
+        enabled: false,
+        providers: {
+          ghostii: {},
+        },
+        content: [
+          {
+            sources: [             // '$brand' | '$feed:https://...' | '$parent'
+              '$brand',
+              // '$feed:https://techcrunch.com/feed/',
+              // '$parent',
+            ],
+            categories: [],        // topic constraints + output tags
+            links: [],             // links to inject into generated content
+            instructions: '',      // free-form text passed to the AI
+            tone: 'professional',  // 'professional' | 'casual' | 'actionable' | 'witty' | etc.
+            keywords: [],          // SEO keywords to weave in
+            quantity: 0,           // number of articles to generate per run
+            chance: 1.0,
+            author: null,
+            postPath: 'ghostii',  // defaults to provider name; sub-folder under _posts/{year}/
+            // Per-entry Ghostii API overrides (all optional, fall back to framework defaults)
+            overrides: {
+              // keywords: ['AI', 'technology'],
+              // length: 'long',              // short | medium | long | comprehensive
+              // research: true,              // web search for real external links
+              // insertImages: true,          // section images from Unsplash
+              // headerImageUrl: 'unsplash',  // disabled | unsplash | generate
+              // maxLinks: 6,
+              // sectionQuantity: 5,
+              // feedUrl: '',                 // brand blog feed for title dedup
+            },
+            // brand: 'other-app-id',                // Optional: target a different brand
+            // brandUrl: 'https://api.otherapp.com',  // Required if brand is set
+          },
+        ],
+      },
+      reviews: {
+        enabled: true,
+        sites: [
+          'trustpilot.com',
+        ],
+      },
+      dataRequest: {
+        // Additional queries to include in GDPR data exports
+        // @omega.js/backend always exports: users, auth record, data-requests, payments-intents, payments-orders
+        // Single doc: { path: 'collection/{uid}', redact: ['field.to.redact'] }
+        // Collection query: { collection: 'my-data', where: [['ownerField', '==', '{uid}']] }
+        queries: [],
+      },
+    },
+  },
+}