@omega.js/backend 0.1.0

package/dist/vendor/monitoring/core.js

@@ -0,0 +1,180 @@
+/**
+ * core — the ONE place error-reporting policy lives (#380).
+ *
+ * Pure functions, zero runtime assumptions: no SDK, no `process`, no DOM. The
+ * browser bundle imports this file, so an env read here would be a
+ * ReferenceError on a web page (esbuild defines only the NODE_ENV key) — every
+ * environment signal is passed IN as a gate. `env.js` is the Node/Electron side
+ * of that seam.
+ *
+ * Policy it owns, once for every target:
+ *   - config resolution from omega.json5's `monitoring` role section — the
+ *     settings live under `monitoring.providers.sentry` (#425) and DSN presence
+ *     is the enable signal (no separate `enabled` flag — matches
+ *     @omega.js/backend convention: a config block's credentials are its switch)
+ *   - the release tag, from the host's own version identity
+ *   - user normalization with the email SCRUBBED BY DEFAULT (the uid stays —
+ *     it is the join key to the account, and it is not PII on its own)
+ *   - the client-side framework-bundle filter: browser events report ONLY when
+ *     they come from OUR bundles. User-land page scripts, browser extensions
+ *     injecting into the page, and cross-origin "Script error." noise never do.
+ *
+ * The SDK is never loaded from here. Nothing in this file can turn reporting
+ * ON either: it can only say whether a host SHOULD boot one.
+ */
+
+const DEFAULTS = {
+  dsn:              '',
+  environment:      null,   // null = the host's gate decides (production / development)
+  sampleRate:       1,      // error events kept, 0..1 — the sampling knob (Sentry-native)
+  tracesSampleRate: 0.1,
+  attachScreenshot: false,
+  scrubEmail:       true,   // PII off by default — set false to opt IN to emails
+  // Browser only: the URL fragments that identify OUR bundles. Both @omega.js/web
+  // and @omega.js/extension serve every framework bundle (the client runtime
+  // included) out of `/assets/js/`, so one default covers both surfaces.
+  bundlePatterns:   ['/assets/js/'],
+};
+
+// A resolved-but-off result. `options` still comes back so a caller can log what
+// it read.
+function disabled(options, reason) {
+  return { shouldEnable: false, options, reason };
+}
+
+/**
+ * The Sentry settings inside a `monitoring` role section (#425). The role level
+ * carries only `enabled`; every SDK-facing key hangs off the provider, so this
+ * is the one place that knows the nesting. `{ sentry: false }` (deliberately
+ * disabled) and a missing block both resolve to nothing — no dsn, no boot.
+ *
+ * @param {object} [section] - the `monitoring` config block (target-resolved)
+ * @returns {object} the provider's settings, or {} when there are none
+ */
+function providerOptions(section) {
+  const settings = section && section.providers && section.providers.sentry;
+  return settings && typeof settings === 'object' ? settings : {};
+}
+
+/**
+ * Resolve the runtime config and decide whether reporting should boot.
+ *
+ * Reads omega.json5's `monitoring` role section: the SDK-facing keys come from
+ * `monitoring.providers.sentry`, so the resolved options feed init directly.
+ *
+ * @param {object} section - the `monitoring` config block (target-resolved)
+ * @param {object} [gates] - the host's environment signals
+ * @param {boolean} [gates.killed] - a kill switch tripped (env var, test runner)
+ * @param {string} [gates.killedReason] - what tripped it, for the log line
+ * @param {boolean} [gates.isProduction] - this run ships telemetry
+ * @param {boolean} [gates.allowInDev] - report anyway outside production
+ * @returns {{ shouldEnable: boolean, options: object, reason: string|null }}
+ */
+function resolveConfig(section, gates) {
+  gates = gates || {};
+
+  const options = { ...DEFAULTS, ...providerOptions(section) };
+
+  if (gates.killed) {
+    return disabled(options, gates.killedReason || 'disabled by the host');
+  }
+  if (!options.dsn) {
+    return disabled(options, 'no dsn set');
+  }
+  if (!gates.isProduction && !gates.allowInDev) {
+    return disabled(options, 'not a production run (set OMEGA_SENTRY_FORCE=true to override)');
+  }
+
+  if (!options.environment) {
+    options.environment = gates.isProduction ? 'production' : 'development';
+  }
+
+  return { shouldEnable: true, options, reason: null };
+}
+
+/**
+ * Normalize a @omega.js/client / firebase / admin user into the minimal shape
+ * the SDK wants. The email is PII: it rides ONLY when the host explicitly opts
+ * in with `monitoring.providers.sentry.scrubEmail: false`.
+ *
+ * @param {object} user - a user-ish object carrying uid/id and maybe email
+ * @param {object} [options] - the resolved monitoring options
+ * @returns {object|null} { id, email? } — null when there is nothing safe to send
+ */
+function normalizeUser(user, options) {
+  if (!user) return null;
+
+  const scrubEmail = (options || {}).scrubEmail !== false;
+  const out = {};
+
+  if (user.uid)     out.id = user.uid;
+  else if (user.id) out.id = user.id;
+  if (user.email && !scrubEmail) out.email = user.email;
+
+  return Object.keys(out).length === 0 ? null : out;
+}
+
+/**
+ * Build the release tag from the host's own version identity. ONE format on
+ * every target (Ian, 2026-08-20): `<brand.id>@<version>` — a Sentry release is
+ * comparable across the backend, the desktop app and the browser bundles only
+ * when they spell it the same way. The brand id is required config, so a tag
+ * missing one is a config hole, not a second format: no id, no tag.
+ *
+ * The version is the host's own — @omega.js/backend's functions package
+ * version, @omega.js/desktop's app version, the browser blob's app version.
+ *
+ * @param {object} identity - { id, version }
+ * @returns {string|undefined} the tag, or undefined when either half is missing
+ */
+function releaseTag(identity) {
+  const { id, version } = identity || {};
+  if (!id || !version) return undefined;
+  return `${id}@${version}`;
+}
+
+/**
+ * Every stack-frame filename an event carries (exception frames first, then the
+ * threads a hung-renderer report uses).
+ */
+function eventFrameFilenames(event) {
+  const values = [
+    ...((event && event.exception && event.exception.values) || []),
+    ...((event && event.threads && event.threads.values) || []),
+  ];
+
+  return values.flatMap((value) => ((value.stacktrace && value.stacktrace.frames) || [])
+    .map((frame) => frame.filename || frame.abs_path || '')
+    .filter(Boolean));
+}
+
+/**
+ * The client-side doctrine gate (#380): a browser event reports ONLY when our
+ * own framework code is on its stack.
+ *
+ * An event with no matching frame is DROPPED, and that includes an event with no
+ * frames at all — a cross-origin `Script error.` is exactly the third-party noise
+ * this exists to kill. Deliberate `omega.sentry().captureException(...)` calls
+ * are unaffected: they are thrown from page bundles, which ARE our bundles.
+ *
+ * @param {string[]} [patterns] - URL fragments identifying our bundles
+ * @returns {(event: object) => boolean} true when the event may report
+ */
+function createBundleFilter(patterns) {
+  const fragments = (patterns || DEFAULTS.bundlePatterns).filter(Boolean);
+
+  return function isFrameworkEvent(event) {
+    const filenames = eventFrameFilenames(event);
+    return filenames.some((filename) => fragments.some((fragment) => filename.includes(fragment)));
+  };
+}
+
+module.exports = {
+  DEFAULTS,
+  providerOptions,
+  resolveConfig,
+  normalizeUser,
+  releaseTag,
+  eventFrameFilenames,
+  createBundleFilter,
+};

package/dist/vendor/monitoring/env.js

@@ -0,0 +1,49 @@
+/**
+ * env — the Node/Electron half of core's gate seam (#380).
+ *
+ * core.js is pure so the browser bundle can import it; every `process.env` read
+ * lives HERE, and only hosts with a real process require this file.
+ *
+ * The switches, in the order they win:
+ *   OMEGA_SENTRY_ENABLED=false  kill switch — nothing reports, ever
+ *   OMEGA_TEST_RUNNER           a test run never pollutes a live project
+ *   OMEGA_SENTRY_FORCE=true     report from a non-production run (local proving)
+ *   OMEGA_BUILD_MODE=true       the DEFAULT production signal, for hosts that
+ *                               have no runtime one
+ *
+ * The production signal is the host's to supply. @omega.js/desktop has no
+ * runtime answer — "should we ship telemetry" is a property of its BUILD, so it
+ * falls through to OMEGA_BUILD_MODE. @omega.js/backend does have one
+ * (`Manager.isProduction()`, env-derived and stable for the life of the
+ * process) and passes it in.
+ */
+
+/**
+ * Read the environment gates for core.resolveConfig().
+ * @param {object} [host] - the host's own signals
+ * @param {boolean} [host.isProduction] - overrides the OMEGA_BUILD_MODE default
+ * @param {boolean} [host.allowInDev] - the host's own dev opt-in (e.g. @omega.js/backend's `reportErrorsInDev`)
+ * @returns {{ killed: boolean, killedReason: string|null, isProduction: boolean, allowInDev: boolean }}
+ */
+function readGates(host) {
+  host = host || {};
+  const env = process.env;
+
+  let killedReason = null;
+  if (env.OMEGA_SENTRY_ENABLED === 'false') {
+    killedReason = 'OMEGA_SENTRY_ENABLED=false';
+  } else if (env.OMEGA_TEST_RUNNER) {
+    killedReason = 'test run (OMEGA_TEST_RUNNER)';
+  }
+
+  return {
+    killed:       !!killedReason,
+    killedReason,
+    isProduction: typeof host.isProduction === 'boolean'
+      ? host.isProduction
+      : env.OMEGA_BUILD_MODE === 'true',
+    allowInDev:   !!host.allowInDev || env.OMEGA_SENTRY_FORCE === 'true',
+  };
+}
+
+module.exports = { readGates };

package/dist/vendor/monitoring/logger.js

@@ -0,0 +1,39 @@
+/**
+ * The monitoring package's log tag — the ONE identity tag every OMEGA surface
+ * prints: `[@omega.js/monitoring:<module>]` ([#12](https://github.com/Omega-JS-Stack/omega/issues/12)).
+ *
+ * The twin of @omega.js/analytics' createLogger, emitting this package's
+ * segment: no timestamp, because devtools, Cloud Logging and electron-log all
+ * stamp their own lines.
+ *
+ * CJS like the rest of the package: the backend and the electron main process
+ * require() it, the browser bundles import it with standard interop.
+ */
+
+// The package segment — this file IS @omega.js/monitoring, so it is a literal.
+const PACKAGE = '@omega.js/monitoring';
+
+/**
+ * Create a tagged console for one module, e.g. createLogger('core').
+ * @param {string} module - The module identity segment.
+ * @returns {object} A console-shaped logger whose calls carry the tag.
+ */
+function createLogger(module) {
+  const tag = `[${PACKAGE}:${module}]`;
+
+  // GETTERS returning a BOUND console method, not wrapper arrows: devtools
+  // attributes a line to the frame that called console, so a wrapper would make
+  // every line read as coming from this file. Resolution stays at ACCESS time,
+  // so a test (or a consumer) that swaps console[method] still sees its own stub.
+  const logger = { tag };
+  for (const method of ['log', 'info', 'warn', 'error', 'debug']) {
+    Object.defineProperty(logger, method, {
+      get: () => console[method].bind(console, tag),
+      enumerable: true,
+    });
+  }
+
+  return logger;
+}
+
+module.exports = { createLogger };

package/dist/vendor/monitoring/node.js

@@ -0,0 +1,72 @@
+/**
+ * node — the server-side entry (#380). @omega.js/backend's Cloud Functions
+ * process boots reporting through here.
+ *
+ * Server errors ALWAYS report: routes, cron, and event triggers are our code by
+ * definition, so there is no bundle filter on this side — the capture SEAMS
+ * decide (RouteContext.report()'s 5xx rule, the event-trigger catch). What this
+ * file owns is the boot: resolve, guard, init, hand back the SDK.
+ *
+ * The SDK is required ONLY when the resolved config says to report, so a brand
+ * with no `monitoring.providers.sentry.dsn` never loads @sentry/node at all.
+ */
+
+const { resolveConfig, releaseTag, normalizeUser } = require('./core.js');
+const { readGates } = require('./env.js');
+const { createLogger } = require('./logger.js');
+
+const logger = createLogger('node');
+
+/**
+ * Boot the node SDK.
+ *
+ * @param {object} options
+ * @param {object} options.config - the omega.json5 `monitoring` section
+ * @param {object} [options.release] - { id, version } — the host's version identity
+ * @param {boolean} [options.isProduction] - the host's runtime production signal
+ * @param {boolean} [options.allowInDev] - report from a non-production run anyway
+ * @param {() => object} [options.tags] - per-event tags, read at capture time
+ * @returns {object|null} the @sentry/node module when reporting is live, else null
+ */
+function initialize(options) {
+  options = options || {};
+
+  const { shouldEnable, options: resolved, reason } = resolveConfig(options.config, readGates(options));
+  if (!shouldEnable) {
+    logger.log(`disabled — ${reason}`);
+    return null;
+  }
+
+  let Sentry;
+  try {
+    Sentry = require('@sentry/node');
+  } catch (e) {
+    logger.warn(`@sentry/node is not installed — reporting disabled. (${e.message})`);
+    return null;
+  }
+
+  const release = releaseTag(options.release);
+  const readTags = typeof options.tags === 'function' ? options.tags : null;
+
+  Sentry.init({
+    dsn:              resolved.dsn,
+    release,
+    environment:      resolved.environment,
+    sampleRate:       resolved.sampleRate,
+    tracesSampleRate: resolved.tracesSampleRate,
+    beforeSend(event) {
+      // Tags are read HERE, not at init: a Cloud Functions process serves many
+      // invocations, so the function name/type belong to the event, not the boot.
+      if (readTags) {
+        event.tags = { ...event.tags, ...readTags() };
+      }
+      return event;
+    },
+  });
+
+  logger.log(`initialized — env=${resolved.environment} release=${release}`);
+
+  return Sentry;
+}
+
+module.exports = { initialize, normalizeUser, releaseTag };

package/docs/admin-post-route.md

@@ -0,0 +1,57 @@
+# Admin Post Route
+
+The `POST /admin/post` route creates blog posts via GitHub's API. It handles image extraction, resize, upload, and body rewriting.
+
+**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 `blog-auto-publisher.js` cron (off by default), and the newsletter generator's linked-article flow (`marketing.newsletter.content.article.enabled`). Both POST `title`/`url`/`description`/`headerImageURL`/`body`/`author`/`categories`/`tags`/`postPath`, admin-authenticated via the `omega-admin-key` header. **The target repo is never part of the request** — the route always derives owner/repo from its own brand config, so a blogger-role caller can't redirect a write at another repo the shared `GH_TOKEN` can reach (caller-supplied `githubUser`/`githubRepo` were removed from the schemas). 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 @omega.js/backend.** 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`. @omega.js/backend 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/...)`)
+2. Extracts all `![alt](url)` patterns from the body using regex
+3. Downloads each image to a tmp dir
+4. **Converts** png/webp sources to progressive JPEG in place (`convertToJpeg` — alpha flattened onto white); other non-JPG formats are rejected, naming the offending URL
+5. **Resizes** each image in place if its long edge exceeds `IMAGE_MAX_DIMENSION` (see below)
+6. Commits all images to `src/assets/images/blog/post-{id}/` on GitHub (single commit via Git Trees API)
+7. **Rewrites the body** to replace external URLs with `@post/{filename}` format
+8. The `@post/` prefix is resolved at Jekyll build time by `jekyll-uj-powertools` to the full path
+
+**Download failures:** the header image is fatal (the whole request 400s); body images are skipped with a warning (the body keeps the original external URL — the post still publishes). Failure reasons go through `formatImageDownloadError` — `Could not download image (<url>): <reason>` with HTML stripped from the reason (CDN 404 pages return raw HTML bodies) and long reasons truncated, so callers (e.g. sponsorship failure emails) surface something readable. Unsupported formats (anything that isn't jpg/png/webp) are rejected, naming the offending URL. Tests: `test/routes/admin/post-download-error.test.js` + `test/routes/admin/post-convert-image.test.js`.
+
+## Image resize
+
+Sources from guest-post submissions can be enormous (16384×10576 has been seen in the wild — ~520MB raw RGB). Sources that large stall downstream Jekyll/imagemin pipelines on the consumer site, and can OOM a 256MB Cloud Function when sharp decompresses them (a 5184×3456 JPEG decodes to ~71MB raw pixels).
+
+Two defenses:
+
+1. **CDN pre-scale** — `applyImageCDNParams(src)` adds server-side resize params to supported CDN URLs *before* downloading. Currently supports Unsplash (`images.unsplash.com`, Imgix-style `?w=&q=` params) and Pexels (`images.pexels.com`, `?w=&auto=compress`). The CDN delivers a pre-scaled image (e.g. ~314KB instead of 3.8MB for a 2048px cap), so sharp never sees the massive original. Params are only added if not already present on the URL.
+
+2. **Local sharp resize** — after download, `resizeImage()` checks the long edge against `IMAGE_MAX_DIMENSION` and re-encodes as progressive JPEG at `IMAGE_JPEG_QUALITY` if it exceeds the limit. Images already within the limit pass through untouched. `sharp.cache(false)` is set so decoded pixel buffers are freed immediately between images — without this, processing several images serially can OOM even at 256MB.
+
+The resize happens in `downloadImage()` (after the `.jpg` extension check, before returning to the caller), so:
+- The base64 content that gets committed to GitHub is the resized version
+- The consumer repo never sees the giant source
+- Future downstream optimization (UJM imagemin, etc.) starts from a sane source size
+
+Constants live in `src/manager/routes/admin/post/post.js` (UJM's `imagemin.js` uses the same names and values):
+```js
+const IMAGE_MAX_DIMENSION = 2048;
+const IMAGE_JPEG_QUALITY = 80;
+```
+
+If these need to become configurable later, promote to `config/omega.json5` rather than env vars (deploy-environment-specific overrides aren't a real use case — the values are algorithm constants).
+
+## Key Details
+
+- Image filenames are derived from `hyphenate(alt_text)` + downloaded extension
+- Only `.jpg` is accepted; other formats reject with a 400
+- Header image (`headerImageURL`) is uploaded but NOT rewritten in the body (it's in frontmatter)
+- Failed image downloads are skipped — the original external URL stays in the body
+- All images + the post markdown are committed in a single commit via the Git Trees API
+
+## Files
+
+- `src/manager/routes/admin/post/post.js` — POST handler (create), includes `downloadImage()` + `resizeImage()` helpers
+- `src/manager/routes/admin/post/put.js` — PUT handler (edit) — does NOT download images, just edits frontmatter/body in place
+- `src/manager/routes/admin/post/templates/post.html` — Post template

package/docs/ai-library.md

@@ -0,0 +1,171 @@
+# AI Library
+
+`Manager.AI(ctx).request({ provider, model, messages, ... })` is the unified entry for all AI calls. Provider-agnostic surface — same options shape, same return shape.
+
+| Provider | Default model | Notes |
+|---|---|---|
+| `openai` | `gpt-5-mini` | Better at structured JSON via JSON schema |
+| `anthropic` | `claude-sonnet-4-6` | Better at SVG illustrations and creative output |
+| `claude-code` | `claude-opus-4-7` | Same Claude models as `anthropic`, but bills a Claude Pro/Max **subscription** instead of API credits |
+
+Return shape (same for all providers): `{ content, output, tokens, raw }` — plus `toolCalls` and `stopReason` when tools are in play (see Tools below).
+
+`options.response: 'json'` triggers JSON parsing — all providers strip fences and parse with JSON5 for robustness. `options.schema` enforces structure on OpenAI (real JSON schema) and is injected into the system prompt on Anthropic / claude-code.
+
+API keys: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` (process.env or config).
+
+## Prompt forms: one internal shape
+
+`normalizeOptions()` runs once at the top of `ai.request()` and collapses every prompt/message form into ONE internal shape before any provider sees it:
+
+- `options.prompt` becomes `[{ role, content }, ...]`: canonical segments, the universal prompt injections as the leading `system` segment, every caller segment already resolved.
+- `options.message` becomes `{ content }`: already resolved, with its `path` consumed.
+
+**Every `{ path }` is read and templated at that one point**, so the openai, anthropic and claude-code formatters all receive the same text. Neither the injections nor a prompt file can go missing on one provider and not another.
+
+The two accepted prompt forms:
+
+- **Object** — `{ path|content, settings }`, one implicit `system` segment.
+- **Array** — `[{ role, path|content, settings }, ...]`, one segment per role (`system` | `developer` | `user` | `assistant`, defaulting to `system`), order preserved. One OpenAI caveat: a trailing `user` segment followed by a `message` is popped by the consecutive-role dedupe there, while the Claude providers merge the two turns.
+
+On the Claude providers (`anthropic`, `claude-code`) `system` + `developer` segments join into the `system` string and `user` + `assistant` segments become leading turns; OpenAI emits one Responses item per segment.
+
+### Ambiguity is an error
+
+There are no silent winners. A call that gives the same slot two texts is refused, and the error names both:
+
+| Input | Why it throws |
+|---|---|
+| `prompt: { path, content }` (or any array segment with both) | Two candidate texts for one segment. Pass the file path or the inline content. |
+| `message: { path, content }` | Same, for the user message. |
+| `prompt` + a `system`-role turn in `messages[]` | Two system prompts in one call. Pass the prompt or the system turn. |
+| `prompt` + any non-empty `messages[]` | `messages[]` is the whole conversation on every provider, so the prompt would be dropped. Move it in as a system turn, or drop `messages[]`. |
+
+A prompt file that is missing, unreadable, or a directory throws from the same one point, naming the input (`options.prompt[1]`, `options.message`, …).
+
+## Token accounting
+
+`r.tokens` is the usage of THAT call — `{ total, input, output }`, each `{ count, price }`, priced from the model table. Summing `r.tokens` across calls is therefore correct. When a call retries internally (OpenAI's `retries` / `retryTriggers`), `r.tokens` is the usage of the attempt that resolved it; the discarded attempts count only on the PROVIDER instance's totals (`provider.tokens`), not in the returned report and not in `ai.tokens`.
+
+The running totals live on the instances: `ai.tokens` counts every call made through that `Manager.AI(ctx)` instance (all providers combined), and each provider instance keeps its own. Callers never share a tokens object, so parallel requests report their own usage.
+
+## Image generation (OpenAI)
+
+`Manager.AI(ctx).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(ctx);
+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()` — `OPENAI_API_KEY` (process.env or config).
+
+## Tools — cross-provider function calling (agentic loops)
+
+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. **Normalized function tools** (`{ name, description, parameters }` where `parameters` is a JSON Schema object — `type: 'function'` optional) work on EVERY provider. Provider-specific hosted tools (e.g. `{ type: 'web_search' }`, `{ type: 'code_interpreter' }`) pass verbatim on OpenAI and throw a clear error on Anthropic/claude-code.
+- `tools.choice` *(optional)* — `'auto' | 'required' | 'none'`, or `{ name: 'tool_name' }` to force a specific tool. Mapped per provider (Anthropic: `auto`/`any`/`none`/`tool`).
+
+When the model decides to call tools, the response carries them in normalized form:
+
+- `r.toolCalls` — `[{ id, name, arguments }]`, `arguments` already parsed to an object.
+- `r.stopReason` — `'tool_use' | 'end' | 'max_tokens'`.
+
+A tool-call turn legitimately has `content: ''` — `response: 'json'` parsing is skipped on tool-call turns (the caller is expected to continue the loop, not consume a final answer).
+
+### Loop continuation via `options.messages`
+
+Structured conversations pass the full turn history through `options.messages` with two cross-provider conventions:
+
+- Assistant tool-call turn: `{ role: 'ctx', content?, toolCalls: [{ id, name, arguments }] }` — or replay the provider's raw blocks (`{ role: 'ctx', content: r.raw.content }`) on Anthropic.
+- Tool result turn: `{ role: 'tool', toolCallId, content }` — consecutive tool results merge into one Anthropic user turn of `tool_result` blocks; OpenAI gets `function_call_output` items.
+
+```js
+const ai = Manager.AI(ctx);
+const messages = [
+  { role: 'system', content: 'Use tools to answer.' },
+  { role: 'user', content: 'What is the weather in Paris?' },
+];
+const tools = { list: [{ name: 'get_weather', description: '...', parameters: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] } }] };
+
+const first = await ai.request({ provider: 'anthropic', messages, tools });
+// first.stopReason === 'tool_use'; first.toolCalls = [{ id, name: 'get_weather', arguments: { city: 'Paris' } }]
+
+messages.push({ role: 'ctx', content: first.raw.content });          // or { role: 'ctx', toolCalls: first.toolCalls }
+messages.push({ role: 'tool', toolCallId: first.toolCalls[0].id, content: '{"temp":"21C"}' });
+
+const second = await ai.request({ provider: 'anthropic', messages, tools });
+// second.stopReason === 'end'; second.content is the final answer
+```
+
+`normalizeOptions()` detects structured conversations (tool turns / toolCalls / raw blocks) and leaves them intact — only the system turn gets the universal prompt injections. Plain-text `messages[]` keep their legacy behavior, except OpenAI now sends ALL turns (previously middle turns were dropped in favor of prompt/message/history).
+
+### Hosted web search (OpenAI only)
+
+```js
+const r = await ai.request({
+  model: 'gpt-5.4',
+  response: 'json',
+  reasoning: { effort: 'medium' },
+  tools: { list: [{ type: 'web_search' }] },
+  prompt: { path: '.../research/system.md', settings },
+  message: { path: '.../research/user.md', settings },
+});
+```
+
+URL citations live in the returned `output` (message content) as `annotations` of type `url_citation`.
+
+## `test` provider — deterministic scripted AI for test suites
+
+`provider: 'test'` is the AI analog of the `test` payment provider: a first-class provider that suites drive with directives in the LAST user message, so consumer routes exercise their full loop (Firestore writes, usage, locks, tool execution) against the real emulator with zero paid API calls. It **refuses to run outside development/testing**.
+
+Directives form a sequence consumed across loop turns (call N executes directive N-1, indexed by ctx turns after the last user turn). Directive values must not contain `]]` internally (a trailing JSON `]` is fine).
+
+The directive source is resolved in order: the last `messages[]` user turn → `message.content` → **`message.settings` values** (flattened raw). That last fallback makes path-based routes (`message: { path, settings }` — the idiomatic @omega.js/backend prompt-template style) scriptable as-is: embed the directive in whatever request field gets interpolated into the template (e.g. a chat's `message`, a quiz's `topic`).
+
+| Directive | Behavior |
+|---|---|
+| `[[tool:name {json}]]` | Emit one tool call this step (`stopReason: 'tool_use'`) |
+| `[[tools:[{"name":"a","arguments":{}}, ...]]]` | Emit parallel tool calls this step |
+| `[[reply:{json}]]` | Final reply (parsed when `response: 'json'`) |
+| `[[delay:ms]]` | Modifier — delay the NEXT step (max 30s) |
+| `[[error:msg]]` | Throw at this step |
+| *(none / exhausted)* | Echo reply: `Echo: <message>` (`{ message }` in json mode) |
+
+## `claude-code` provider — subscription billing
+
+The `claude-code` provider hits the same Claude Messages API as `anthropic`, but authenticates with a **Claude Code OAuth token** (`Authorization: Bearer ...` + `anthropic-beta: oauth-2025-04-20`) so usage bills the Claude Pro/Max subscription tied to the token rather than API credits.
+
+It is **pure HTTPS** — no `claude` binary, no subprocess — so it runs in Cloud Functions / CI / anywhere Node runs.
+
+Token resolution (first match wins): `options.apiKey` / constructor key → `config.claude_code.oauth_token` → `process.env.CLAUDE_CODE_OAUTH_TOKEN`.
+
+Mint the token with `claude setup-token` (valid ~1 year). When it expires, requests 401 — re-mint and update the `CLAUDE_CODE_OAUTH_TOKEN` secret. There is no automatic refresh; renewal is a manual yearly step.
+
+> **Caveats:** the Bearer/beta subscription path is undocumented and may change. Usage is subject to the subscription's rate limits (not API-tier limits). For high-volume production traffic, prefer `anthropic` + `ANTHROPIC_API_KEY`.
+
+The legacy `src/manager/libraries/openai.js` is a thin compatibility shim that re-exports the OpenAI provider class — existing callers using `new OpenAI(ctx, key)` still work unchanged.
+
+| File | Purpose |
+|---|---|
+| `src/manager/libraries/ai/index.js` | Unified `AI` class (dispatches by provider; the one normalize point: prompt/message forms, prompt-file loading, universal injections, ambiguity guards; structured-messages detection) |
+| `src/manager/libraries/ai/prompt.js` | Shared prompt-segment normalization + content/prompt-file loading, called by the normalize point (and again, idempotently, by a directly constructed provider) |
+| `src/manager/libraries/ai/tokens.js` | Token accounting helpers (per-call report, running counters) |
+| `src/manager/libraries/ai/providers/openai.js` | OpenAI provider (Responses API; direct-messages mode + tool envelopes) |
+| `src/manager/libraries/ai/providers/anthropic.js` | Anthropic provider (Claude Messages API, x-api-key, API credits, native tool_use) |
+| `src/manager/libraries/ai/providers/claude-code.js` | claude-code provider (Claude Messages API, OAuth Bearer, subscription billing, native tool_use) |
+| `src/manager/libraries/ai/providers/anthropic-format.js` | Shared pure formatters for both Claude providers (tool defs, message building, extraction) |
+| `src/manager/libraries/ai/providers/test.js` | Deterministic `test` provider (scripted directives; dev/testing only) |
+| `src/manager/libraries/openai.js` | Back-compat shim → providers/openai.js |

package/docs/architecture.md

@@ -0,0 +1,62 @@
+# Architecture
+
+## Manager Class
+
+The core `Manager` class (in `src/manager/index.js`) extends EventEmitter and orchestrates all functionality:
+- Initializes Firebase Admin SDK
+- Sets up built-in Cloud Functions (`omega_api`, auth events, cron)
+- Provides factory methods for helper classes
+- Manages configuration from multiple sources
+
+## Derived config values (`config.resolved.*`)
+
+The composed config a consumer reads (`Manager.config`, and the same object every
+route/hook/cron receives) carries a `resolved` group of values the FRAMEWORK derives at
+boot ([#290](https://github.com/Omega-JS-Stack/omega/issues/290)). A brand target cannot
+require `@omega.js/config` — it is a private package, vendored into the framework's dist
+— so a brand that needed a derived value used to re-implement the derivation and drift
+from the real merge rules. The framework runs the recipe once; brands read the answer.
+
+| Path | What it is |
+|---|---|
+| `config.resolved.github.repo` | The brand repo as an `owner/name` slug (`''` unless both halves resolve) |
+| `config.resolved.github.owner` | The same answer's owner (GitHub org or user) |
+| `config.resolved.github.name` | The same answer's bare repo name |
+
+The GitHub values resolve `repo.providers.github` (`org`, `repo`) overlaid by the backend
+target's own `github` block, which wins — the CMS/content-repo override — with `repo`
+taking either an `owner/name` slug or a bare name, name falling back to `brand.id` and
+owner to `repo.providers.github.org`.
+
+Every derivation lives in `@omega.js/config` (`brandRepo()` here) — never a second copy.
+`src/manager/helpers/resolved-config.js` only names the group and the values in it; new
+derived values join there as real brand needs surface, each with a test pinning it to the
+config package's own function.
+
+## Dual-Mode Support
+
+@omega.js/backend supports two deployment modes, picked by the brand's config —
+`targets.backend.projectType` in `config/omega.json5`, read by `Manager.init()` (#584), so a
+consumer's `src/index.js` is the same in both. An explicit `init` option overrides it.
+- **Firebase Functions** (`projectType: 'firebase'`, the default): Cloud Functions with Firebase triggers
+- **Custom Server** (`projectType: 'custom'`): the same routes, schemas, auth middleware and
+  helpers, served by the Express app on `process.env.PORT` for a container host.
+  `firebase-functions` is never loaded (`libraries.functions` is `null`); `firebase-admin`
+  still is. The Firebase-only CLI verbs (`deploy`, `serve`, `emulator`, `test`) refuse and
+  name their replacement lane — `src/cli/utils/project-type.js` is the one home of that list.
+
+## Helper Factory Pattern
+
+All helpers are accessed via factory methods on the Manager instance:
+
+```javascript
+Manager.RouteContext({ req, res })  // Request handler
+Manager.User(data)               // User properties
+Manager.Analytics({ ctx }) // GA4 events
+Manager.Usage()                  // Rate limiting
+Manager.Middleware(req, res)     // Request pipeline
+Manager.Settings()               // Schema validation
+Manager.Utilities()              // Batch operations
+Manager.Metadata(doc)            // Timestamps/tags
+Manager.storage({ name })        // Local JSON storage (lowdb)
+```