@koda-sl/baker-cli 0.277.0 → 0.278.0

package/dist/cli.js

@@ -12875,7 +12875,22 @@ var ANALYTICS_EVENT_TYPES = [
    * know who this was" unanswerable.
    */
   "identify",
-  /** Escape hatch for a page-specific event. */
+  /**
+   * A named event: an escape hatch a page defines, or one a client's own server
+   * posted to `POST /v1/events`.
+   *
+   * One type for both, deliberately. There was briefly a `server_event`, and
+   * the type was the mistake: every report that shows named events whitelists
+   * `custom`, so a server-sent "Deal won" was structurally invisible on the
+   * Page events card, in Top pages and in the events catalogue — the three
+   * screens somebody would look at after being told it had arrived. GA4 makes
+   * the same call for the same reason: a Measurement Protocol event is just an
+   * event, and the transport is a property.
+   *
+   * Which collector wrote it is {@link ANALYTICS_SOURCES} — `client` for a
+   * page, `ingest` for a third party's server — and every report that needs to
+   * tell them apart filters on that.
+   */
   "custom"
 ];
 var ANALYTICS_DEVICE_TYPES = ["desktop", "mobile", "tablet", "bot", "unknown"];
@@ -13338,7 +13353,16 @@ var analyticsPresetSchema = z27.enum([
    * marketer could see that nothing was counted and had no way to find out what
    * was available to count.
    */
-  "conversions"
+  "conversions",
+  /**
+   * Every event as it was stored, newest first — the one preset that does not
+   * reduce.
+   *
+   * Deliberately not offered as a `baker analytics` preset. It is the raw feed
+   * a person watches while wiring something up, and an agent asked to describe
+   * an account wants the counts rather than the tape.
+   */
+  "stream"
 ]);
 var ANALYTICS_PRESETS = analyticsPresetSchema.options;
 var analyticsQueryRequestSchema = z27.object({
@@ -13398,6 +13422,29 @@ var analyticsQueryRequestSchema = z27.object({
    * superset and the right default for "how is paid doing".
    */
   adPlatform: z27.enum(AD_PLATFORMS).optional(),
+  /**
+   * Read only what one collector produced: `site` for everything Baker
+   * measured itself, `systems` for what a client's own server posted to
+   * `POST /v1/events`.
+   *
+   * Omit it for all of it, which is the default and the honest superset.
+   * Only the reads where the split is a question somebody asks honour it —
+   * the totals, the trend, the two page-event reads, the conversion
+   * breakdown and the events catalogue. A session-scoped report cannot: an
+   * ingest row carries no `session_id`, deliberately, so there is no visit
+   * for it to be counted in.
+   */
+  eventOrigin: z27.enum(["site", "systems"]).optional(),
+  /**
+   * `stream` only: keep just one kind of event, named by the key
+   * `conversions` hands back in its catalogue.
+   *
+   * The key rather than `eventName`, because three of the four families have
+   * no name of their own — a Form's trigger, a submit, an outbound click —
+   * and a filter that could only name the fourth would be a filter that hides
+   * most of the feed from itself.
+   */
+  eventKey: z27.string().optional(),
   /** Return the long breakdowns and the per-day trend. */
   full: z27.boolean().optional(),
   /**
@@ -13670,6 +13717,7 @@ var analyticsTagRowSchema = z27.object({
   /** Converting visits per entrance. */
   conversionRate: z27.number().min(0).max(1).nullable()
 });
+var ANALYTICS_EVENT_ORIGINS = ["site", "systems", "both"];
 var analyticsCustomEventRowSchema = z27.object({
   eventName: z27.string(),
   events: z27.number().int().nonnegative(),
@@ -13684,14 +13732,28 @@ var analyticsCustomEventRowSchema = z27.object({
    * reader already knowing what the page chose to record.
    */
   propertyKeys: z27.array(z27.string()),
-  valueTotal: z27.number(),
-  landings: z27.array(z27.string())
+  /**
+   * What these events were worth, per currency.
+   *
+   * A map and never one number, for the reason the person card's `money` is
+   * one: a name carrying 99,882.50 EUR and 1,000 USD is not worth 100,882.50
+   * of anything, and there is no rate in this product to make it so.
+   *
+   * The `''` key is a value a *page* reported — `value` with no currency,
+   * which is a score on the page's own terms rather than money. Kept rather
+   * than dropped, because for those events it is the only number there is.
+   */
+  money: z27.record(z27.string(), z27.number()).default({}),
+  landings: z27.array(z27.string()),
+  /** Which collector produced this name — and `both` when more than one did. */
+  origin: z27.enum(ANALYTICS_EVENT_ORIGINS)
 });
 var analyticsEventBreakdownRowSchema = z27.object({
   value: z27.string(),
   events: z27.number().int().nonnegative(),
   sessions: z27.number().int().nonnegative(),
-  valueTotal: z27.number()
+  /** Per currency, exactly as {@link analyticsCustomEventRowSchema.money}. */
+  money: z27.record(z27.string(), z27.number()).default({})
 });
 var analyticsCustomFunnelStepSchema = z27.object({
   stepIndex: z27.number().int().positive(),
@@ -14020,6 +14082,16 @@ var analyticsConversionRowSchema = z27.object({
 var analyticsEventCatalogRowSchema = z27.object({
   /** `form:…` | `submit:…` | `page:…` | `exit:…` — parse with `parseEventKey`. */
   eventKey: z27.string(),
+  /**
+   * Which collector produced this key — and `both` when more than one did.
+   *
+   * On the row rather than in the key, which is the whole shape of the change
+   * that removed the `server:` family: a picker can say where an event came
+   * from without a filter round-trip, and a report can still separate the two
+   * populations at any grain, but nothing downstream has to learn a second
+   * vocabulary to count one.
+   */
+  origin: z27.enum(ANALYTICS_EVENT_ORIGINS),
   events: z27.number(),
   sessions: z27.number(),
   /** The Form node's kind, for a `form:` key. Empty otherwise. */
@@ -14108,7 +14180,7 @@ var analyticsAdPlatformTrafficSchema = z27.object({
 });
 var analyticsPageInfoSchema = z27.object({
   /** Which field of the response was paged. */
-  block: z27.enum(["visitors", "submissions", "deliveries"]),
+  block: z27.enum(["visitors", "submissions", "deliveries", "stream"]),
   page: z27.number().int(),
   pageSize: z27.number().int(),
   returned: z27.number().int(),
@@ -14116,6 +14188,17 @@ var analyticsPageInfoSchema = z27.object({
 });
 var analyticsTimelineRowSchema = z27.object({
   timestamp: z27.string(),
+  /**
+   * The visit this event belongs to, and the browser that made it.
+   *
+   * Empty on anything that belongs to neither — a settlement, and an event a
+   * client's own server posted about somebody who was never on a page. Carried
+   * because the raw feed (`stream`) is a company-wide list rather than one
+   * visit's, so a row has to say who it was about before a reader can get from
+   * it to the person. On a replay both are constant and simply confirm it.
+   */
+  sessionId: z27.string(),
+  anonId: z27.string(),
   /**
    * Where the producer put this event in its own order, from 1. `0` means it
    * did not number this one.
@@ -14152,8 +14235,45 @@ var analyticsTimelineRowSchema = z27.object({
   targetUrl: z27.string(),
   /** A number the page reported alongside the event. */
   value: z27.number(),
+  /**
+   * The currency that number is in, when it has one.
+   *
+   * Only a server-sent event carries it — a page reports a `value` on its own
+   * terms, a CRM reports a deal in euros — and without it the replay prints a
+   * bare `4200.5` beside a closed deal, which is a number nobody can act on.
+   */
+  valueCurrency: z27.string().default(""),
   /** The visitor's digest, when they had identified themselves by this point. */
   identityHash: z27.string(),
+  /**
+   * The browser to attribute this row to, once the identity has been resolved.
+   *
+   * `anonId` when the row has one, and otherwise the browser {@link identityHash}
+   * resolves to through `identities`. Empty when neither exists.
+   *
+   * It is a separate field rather than a coalesce into `anonId` because the two
+   * claims are not the same: `anonId` is the cookie the row was written with,
+   * and a server-sent event was written with none and must not start claiming
+   * one. This is the *read's* answer to "who was that", and it is retroactive
+   * and cross-device by construction — a "Deal won" posted in March attaches to
+   * the person the moment they type that address into a Form in April, and to
+   * every browser they have used here.
+   *
+   * Only `event_stream` fills it. Empty everywhere else, which is honest: a
+   * session replay deliberately does not resolve, because an event that
+   * happened during no visit must not be placed inside one.
+   */
+  personAnonId: z27.string().default(""),
+  /**
+   * What this row knows the person by, when it does not know their browser:
+   * `email` | `phone` | `external` | `click` | `cookie`, or empty.
+   *
+   * The feed's Who column reads it. A row naming a person by a means that has
+   * no face here yet — a digest nobody has typed into a Form, an ad click, one
+   * of Meta's cookies — is not a row about nobody, and rendering it as one is
+   * what made the server-sent half of the feed look unattached to the rest.
+   */
+  knownBy: z27.string().default(""),
   /**
    * `email` | `phone` — which of the two they gave.
    *
@@ -14162,6 +14282,22 @@ var analyticsTimelineRowSchema = z27.object({
    * a replay renders the same sentence twice and reads as a duplicated event.
    */
   identityKind: z27.string(),
+  /**
+   * The `user_data` block this event carried, exactly as it arrived.
+   *
+   * The contact digests (`email_sha256`, `phone_sha256`, `external_id_sha256`),
+   * the click ids, Meta's cookies, and the advanced-matching /
+   * enhanced-conversions fields — first name, city, postcode, country. Empty on
+   * everything a page produced, which is most rows.
+   *
+   * **Per event, and deliberately not merged** — unlike the person card, which
+   * merges the same fields newest-wins across everything anyone ever sent. The
+   * question one event answers is "what did *this request* contain", and the
+   * answer has to be allowed to be *worse* than what is known about the person
+   * overall. That is how a sender finds the field they forgot to map: the
+   * person has a postcode, and this event does not.
+   */
+  userData: z27.record(z27.string(), z27.string()).default({}),
   sideEffectType: z27.string(),
   sideEffectName: z27.string(),
   sideEffectId: z27.string(),
@@ -14293,6 +14429,63 @@ var analyticsVisitProfileSchema = z27.object({
   conversions: z27.number().int().nonnegative(),
   engagementMs: z27.number().int().nonnegative()
 });
+var analyticsPersonKeySchema = z27.object({
+  /** `email` | `phone` | `external` | `browser` | a click-id name | `fbp` | `fbc`. */
+  kind: z27.string(),
+  /** A digest for a contact detail, the value itself for a cookie or a click id. */
+  value: z27.string(),
+  firstSeen: z27.string(),
+  lastSeen: z27.string(),
+  /** How many times it was observed beside another key — every submission repeats it. */
+  observations: z27.number().int().nonnegative(),
+  sessions: z27.number().int().nonnegative(),
+  /** `client` | `edge` | `server` | `ingest` — which collector first saw it. */
+  source: z27.string(),
+  /** The Form it was first seen on, where it came from one. */
+  flowSlug: z27.string(),
+  landingId: z27.string()
+});
+var analyticsPersonProfileSchema = z27.object({
+  firstSeen: z27.string(),
+  lastSeen: z27.string(),
+  sessions: z27.number().int().nonnegative(),
+  /** How many browsers resolved to this person. More than one is cross-device. */
+  devices: z27.number().int().nonnegative(),
+  pageViews: z27.number().int().nonnegative(),
+  conversions: z27.number().int().nonnegative(),
+  /**
+   * What they are worth, per currency — `{ EUR: 4753 }`.
+   *
+   * A map rather than an amount and a code, because the two-column shape had
+   * no honest answer for somebody with a deal in each of two currencies: it
+   * summed them and labelled the total with whichever code came back first.
+   * Only a server event ever carries money, and a retried post is counted
+   * once, on `event_uid`.
+   */
+  money: z27.record(z27.string(), z27.number()),
+  engagementMs: z27.number().int().nonnegative(),
+  /** How many of their events a client's own server posted. */
+  serverEvents: z27.number().int().nonnegative(),
+  country: z27.string(),
+  region: z27.string(),
+  city: z27.string(),
+  deviceType: z27.string(),
+  browser: z27.string(),
+  os: z27.string(),
+  utmSource: z27.string(),
+  utmMedium: z27.string(),
+  utmCampaign: z27.string(),
+  referrerSource: z27.string(),
+  entryLandingId: z27.string(),
+  entryPath: z27.string(),
+  /**
+   * The customer-matching block, merged newest-wins across everything anyone
+   * has ever told us about them — `city`, `postal_code`, `country`,
+   * `first_name_sha256`, `fbp`. Keyed exactly as the store holds it, so a key
+   * ending `_sha256` says its value is a digest and cannot be shown.
+   */
+  matchKeys: z27.record(z27.string(), z27.string())
+});
 var analyticsVisitorRowSchema = z27.object({
   anonId: z27.string(),
   firstSeen: z27.string(),
@@ -14315,6 +14508,18 @@ var analyticsVisitorRowSchema = z27.object({
   utmCampaign: z27.string(),
   clickPlatform: z27.string(),
   campaignParams: z27.record(z27.string(), z27.string()),
+  /**
+   * The click ids this person arrived on, by their own names — `gclid`,
+   * `fbclid`, `msclkid`, `li_fat_id`, `ttclid`, `twclid`, `wbraid`, `gbraid`.
+   *
+   * Only the ones that were present. The endpoint has always returned all eight
+   * columns and nothing above it carried them, so the one screen whose subject
+   * is a person could name the platform that paid for the click and not the
+   * click — which is the value a platform's own reporting is matched on, and
+   * therefore the value somebody is looking for when a conversion did not show
+   * up on the other side.
+   */
+  clickIds: z27.record(z27.string(), z27.string()),
   country: z27.string(),
   region: z27.string(),
   city: z27.string(),
@@ -14376,7 +14581,16 @@ var analyticsQueryDataSchema = z27.object({
   /** Every event these pages produced, counted or not. The "add a conversion" picker. */
   eventCatalog: z27.array(analyticsEventCatalogRowSchema).optional(),
   timeline: z27.array(analyticsTimelineRowSchema).optional(),
+  /**
+   * The raw feed. Same row shape as a replay, because it is the same rows —
+   * what changes is that this one is bounded by a window rather than by a visit.
+   */
+  stream: z27.array(analyticsTimelineRowSchema).optional(),
   visitorSessions: z27.array(analyticsVisitorSessionSchema).optional(),
+  /** Every key this person is known by — contact details, browsers, clicks, cookies. */
+  personKeys: z27.array(analyticsPersonKeySchema).optional(),
+  /** The same person, rolled up: their totals across every device, and what is known about them. */
+  personProfile: analyticsPersonProfileSchema.optional(),
   visitProfile: analyticsVisitProfileSchema.optional(),
   visitors: z27.array(analyticsVisitorRowSchema).optional(),
   /**
@@ -16911,7 +17125,7 @@ function parseCsvLine(line) {
     }
   }
   cells.push(current);
-  return cells.map((cell2) => cell2.trim());
+  return cells.map((cell3) => cell3.trim());
 }
 function parseListFileArg(path38, maxRows) {
   if (typeof path38 !== "string" || path38.length === 0) {
@@ -26881,6 +27095,808 @@ Full guides: __tooling__/docs/tools/baker/ads-<platform>.md (google|meta|linkedi
   }
 });
 
+// ../api/src/event-ingest/arrivals.ts
+import { z as z30 } from "zod";
+
+// ../api/src/event-ingest/mode.ts
+var INGEST_MODE_HEADER = "X-Baker-Mode";
+var INGEST_MODES = ["live", "test"];
+
+// ../api/src/event-ingest/arrivals.ts
+var INGEST_ARRIVALS_MAX = 200;
+var INGEST_ARRIVALS_DEFAULT = 25;
+var ingestArrivalsRequestSchema = z30.object({
+  /** `test` shows only rehearsals, `live` only real traffic. Absent shows both. */
+  mode: z30.enum(INGEST_MODES).optional(),
+  /** `rejected` is the one worth asking for on its own — it is the whole reason to look. */
+  outcome: z30.enum(["accepted", "rejected"]).optional(),
+  /** Narrow to one event name, for a company posting several kinds. */
+  eventName: z30.string().max(120).optional(),
+  limit: z30.coerce.number().int().positive().max(INGEST_ARRIVALS_MAX).optional().default(INGEST_ARRIVALS_DEFAULT),
+  /** Include the masked raw body and the per-field previews. Off by default — it is most of the bytes. */
+  full: z30.boolean().optional()
+});
+
+// ../api/src/event-ingest/endpoint.ts
+var EVENT_INGEST_PATH = "/v1/events";
+function eventIngestUrl(brandedUrl, convexSiteUrl) {
+  if (brandedUrl) return `${brandedUrl.replace(/\/$/, "")}${EVENT_INGEST_PATH}`;
+  return `${convexSiteUrl.replace(/\/$/, "")}${EVENT_INGEST_PATH}`;
+}
+var MODE_HINT = `
+# Rehearse the same request: add -H '${INGEST_MODE_HEADER}: test'
+# It is validated and answered exactly the same way, and nothing is written.`;
+function eventIngestCurl(url, apiKey) {
+  const body = JSON.stringify({
+    events: [
+      {
+        event_name: "deal_won",
+        user_data: { email: "person@example.com" },
+        value: "1200.00",
+        currency: "EUR"
+      }
+    ]
+  });
+  return [
+    `curl -X POST ${url} \\`,
+    `  -H 'Authorization: Bearer ${apiKey}' \\`,
+    `  -H 'Content-Type: application/json' \\`,
+    `  -d '${body}'`
+  ].join("\n") + MODE_HINT;
+}
+
+// ../api/src/event-ingest/currency.ts
+var MINOR_UNITS = {
+  AED: 2,
+  AFN: 2,
+  ALL: 2,
+  AMD: 2,
+  ANG: 2,
+  AOA: 2,
+  ARS: 2,
+  AUD: 2,
+  AWG: 2,
+  AZN: 2,
+  BAM: 2,
+  BBD: 2,
+  BDT: 2,
+  BGN: 2,
+  BHD: 3,
+  BIF: 0,
+  BMD: 2,
+  BND: 2,
+  BOB: 2,
+  BOV: 2,
+  BRL: 2,
+  BSD: 2,
+  BTN: 2,
+  BWP: 2,
+  BYN: 2,
+  BZD: 2,
+  CAD: 2,
+  CDF: 2,
+  CHE: 2,
+  CHF: 2,
+  CHW: 2,
+  CLF: 4,
+  CLP: 0,
+  CNY: 2,
+  COP: 2,
+  COU: 4,
+  CRC: 2,
+  CUP: 2,
+  CVE: 2,
+  CZK: 2,
+  DJF: 0,
+  DKK: 2,
+  DOP: 2,
+  DZD: 2,
+  EGP: 2,
+  ERN: 2,
+  ETB: 2,
+  EUR: 2,
+  FJD: 2,
+  FKP: 2,
+  GBP: 2,
+  GEL: 2,
+  GHS: 2,
+  GIP: 2,
+  GMD: 2,
+  GNF: 0,
+  GTQ: 2,
+  GYD: 2,
+  HKD: 2,
+  HNL: 2,
+  HTG: 2,
+  HUF: 2,
+  IDR: 2,
+  ILS: 2,
+  INR: 2,
+  IQD: 3,
+  IRR: 2,
+  ISK: 0,
+  JMD: 2,
+  JOD: 3,
+  JPY: 0,
+  KES: 2,
+  KGS: 2,
+  KHR: 2,
+  KMF: 0,
+  KPW: 2,
+  KRW: 0,
+  KWD: 3,
+  KYD: 2,
+  KZT: 2,
+  LAK: 2,
+  LBP: 2,
+  LKR: 2,
+  LRD: 2,
+  LSL: 2,
+  LYD: 3,
+  MAD: 2,
+  MDL: 2,
+  MGA: 2,
+  MKD: 2,
+  MMK: 2,
+  MNT: 2,
+  MOP: 2,
+  MRU: 2,
+  MUR: 2,
+  MVR: 2,
+  MWK: 2,
+  MXN: 2,
+  MXV: 2,
+  MYR: 2,
+  MZN: 2,
+  NAD: 2,
+  NGN: 2,
+  NIO: 2,
+  NOK: 2,
+  NPR: 2,
+  NZD: 2,
+  OMR: 3,
+  PAB: 2,
+  PEN: 2,
+  PGK: 2,
+  PHP: 2,
+  PKR: 2,
+  PLN: 2,
+  PYG: 0,
+  QAR: 2,
+  RON: 2,
+  RSD: 2,
+  RUB: 2,
+  RWF: 0,
+  SAR: 2,
+  SBD: 2,
+  SCR: 2,
+  SDG: 2,
+  SEK: 2,
+  SGD: 2,
+  SHP: 2,
+  SLE: 2,
+  SOS: 2,
+  SRD: 2,
+  SSP: 2,
+  STN: 2,
+  SVC: 2,
+  SYP: 2,
+  SZL: 2,
+  THB: 2,
+  TJS: 2,
+  TMT: 2,
+  TND: 3,
+  TOP: 2,
+  TRY: 2,
+  TTD: 2,
+  TWD: 2,
+  TZS: 2,
+  UAH: 2,
+  UGX: 0,
+  USD: 2,
+  USN: 2,
+  UYI: 0,
+  UYU: 2,
+  UYW: 4,
+  UZS: 2,
+  VED: 2,
+  VES: 2,
+  VND: 0,
+  VUV: 0,
+  WST: 2,
+  XAF: 0,
+  XAG: 0,
+  XAU: 0,
+  XBA: 0,
+  XBB: 0,
+  XBC: 0,
+  XBD: 0,
+  XCD: 2,
+  XCG: 2,
+  XDR: 0,
+  XOF: 0,
+  XPD: 0,
+  XPF: 0,
+  XPT: 0,
+  XSU: 0,
+  XTS: 0,
+  XUA: 0,
+  XXX: 0,
+  YER: 2,
+  ZAR: 2,
+  ZMW: 2,
+  ZWG: 2,
+  // Withdrawn recently enough that a client's CRM still carries them. Accepting
+  // a code that was legal tender last year costs nothing; rejecting a real
+  // historical `won` costs the client a reconciliation they cannot fix.
+  SLL: 2,
+  ZWL: 2,
+  CUC: 2,
+  HRK: 2
+};
+var ISO_4217_CODES = new Set(Object.keys(MINOR_UNITS));
+
+// ../api/src/event-ingest/names.ts
+var STANDARD_EVENT_NAMES = [
+  { name: "page_view", means: "A page was served somewhere Baker does not run." },
+  { name: "view_content", means: "Someone looked at a specific thing \u2014 a listing, a property, an article." },
+  { name: "lead", means: "Someone became a lead: they handed over a way to reach them." },
+  { name: "contact", means: "Someone got in touch \u2014 a call, a chat, an email in." },
+  { name: "schedule", means: "A meeting, viewing or call was booked." },
+  { name: "sign_up", means: "An account was created." },
+  { name: "start_trial", means: "A trial began." },
+  { name: "subscribe", means: "A subscription started." },
+  { name: "qualified_lead", means: "Sales judged the lead worth working. The first event only you can send." },
+  { name: "opportunity", means: "A deal was opened against the lead." },
+  { name: "deal_won", means: "The deal closed. Send the money on it." },
+  { name: "deal_lost", means: "The deal was lost. Send it \u2014 a campaign that only reports wins reads as free." },
+  { name: "purchase", means: "Something was paid for. Send the money on it." },
+  { name: "refund", means: "Money went back. A separate event, never a negative amount." }
+];
+
+// ../api/src/event-ingest/validation.ts
+var REJECTION_CODES = [
+  "invalid_event_id",
+  "invalid_name",
+  "missing_identity",
+  "invalid_timestamp",
+  "invalid_value",
+  "batch_too_large"
+];
+var EVENT_INGEST_BATCH_MAX = 500;
+var EVENT_INGEST_BODY_MAX_BYTES = 8 * 1024 * 1024;
+var EVENT_INGEST_REQUESTS_PER_MINUTE = 60;
+var FUTURE_TOLERANCE_MS = 5 * 6e4;
+var MAX_EVENT_NAME = 80;
+var REJECTION_MESSAGES = {
+  invalid_event_id: "event_id, when sent, must be 1-128 characters of A-Z a-z 0-9 . _ : -",
+  invalid_name: "event_name is required: up to 80 characters of letters, digits, spaces, . _ and -",
+  missing_identity: "user_data named nobody, and no url named a page",
+  invalid_timestamp: "event_time must be an ISO-8601 instant with an offset or Unix seconds, and not in the future",
+  invalid_value: "value and currency go together: a non-negative decimal and an ISO-4217 code",
+  batch_too_large: `a request carries at most ${EVENT_INGEST_BATCH_MAX} events and ${EVENT_INGEST_BODY_MAX_BYTES / (1024 * 1024)} MB`
+};
+
+// ../api/src/event-ingest/fields.ts
+var BODY_MAX_MB = EVENT_INGEST_BODY_MAX_BYTES / (1024 * 1024);
+var FUTURE_TOLERANCE_MINUTES = FUTURE_TOLERANCE_MS / 6e4;
+var HEADER_FIELDS = [
+  { name: "Authorization", need: "required", takes: "Bearer <your sending key>" },
+  { name: "Content-Type", need: "required", takes: "application/json" },
+  {
+    name: "X-Baker-Mode",
+    need: "optional",
+    takes: "live (the default) or test.",
+    // Deliberately says what a test send *is* rather than "see step 4". Every
+    // note here is read twice — on this screen, where the step below explains
+    // it in full, and inside the Markdown brief, where there are no steps and
+    // a cross-reference points at nothing.
+    note: "A test send is authenticated and validated identically and stores nothing. An unrecognised value is refused rather than assumed."
+  }
+];
+var EVENT_FIELDS = [
+  {
+    name: "event_name",
+    need: "required",
+    takes: `What happened. Up to ${MAX_EVENT_NAME} characters of letters, digits, spaces, . _ and -`,
+    note: "The only required field. Use one of the standard names below wherever one fits \u2014 anything else is yours to invent."
+  },
+  {
+    name: "event_time",
+    need: "optional",
+    takes: "ISO-8601 with an offset (2026-09-08T13:23:41Z), or Unix seconds (1757337821).",
+    note: `Left out, it is the moment we received it. Nothing is refused for being old \u2014 a backfill of last year's history is what this is for. More than ${FUTURE_TOLERANCE_MINUTES} minutes in the future is refused.`
+  },
+  {
+    name: "event_id",
+    need: "optional",
+    takes: "Your own id for this event: 1\u2013128 characters of letters, digits, and . _ : -",
+    note: "Send one only if you want it deduplicated \u2014 the same id twice is counted once. Send none and every post is its own event."
+  },
+  {
+    name: "user_data",
+    need: "required",
+    takes: "Who it was about. At least one field below \u2014 this is the whole of how a server event finds the person who visited your pages.",
+    note: "No field is required on its own and the block is: an event naming nobody is refused with missing_identity. The one exception is a page_view carrying a url, because a page serve is a fact about a page."
+  },
+  {
+    name: "email",
+    need: "optional",
+    under: true,
+    takes: "The address, or its SHA-256 digest if you already hash. Either \u2014 we tell them apart.",
+    note: "Send this one if you can. It is the road that cannot silently fail: we normalise and hash it here, so it lands on exactly the person your pages already recorded."
+  },
+  {
+    name: "phone",
+    need: "optional",
+    under: true,
+    takes: "The number with its country code, or its digest. Same treatment as email."
+  },
+  {
+    name: "external_id",
+    need: "optional",
+    under: true,
+    takes: "Your own id for the person \u2014 a CRM contact key.",
+    note: "Kept exactly as you send it, and hashed alongside so it joins: your own events to each other, and to a browser once one event carries it beside an email or a baker_id."
+  },
+  {
+    name: "baker_id",
+    need: "optional",
+    under: true,
+    takes: "The Baker ID one of our pages already gave this browser, if your system kept it.",
+    note: "The strongest of all of them: it names the visit, so the event lands on that person's timeline rather than beside it."
+  },
+  {
+    name: "the ad click ids",
+    need: "optional",
+    under: true,
+    takes: "The click id that brought them, if you kept it, under the name the platform stamps on the link: gclid, wbraid, gbraid, fbclid, ttclid, twclid, li_fat_id, msclkid.",
+    note: "A click id names a person too \u2014 it is enough on its own, and it attributes the event to the campaign that earned it."
+  },
+  {
+    name: "fbp, fbc",
+    need: "optional",
+    under: true,
+    takes: "Meta's own browser cookies (_fbp, _fbc), exactly as your site stored them.",
+    note: "Enough on their own, and worth sending: they are what Meta matches a server event on. We read the click id out of an fbc for you."
+  },
+  {
+    name: "the matching fields",
+    need: "optional",
+    under: true,
+    takes: "first_name, last_name, date_of_birth, gender, city, region, postal_code, country \u2014 Meta's advanced matching and Google's enhanced conversions, in one block. Plain or already hashed.",
+    note: "They name nobody here, so they never satisfy user_data on their own. They are kept so this event can be sent on to Meta or Google later without asking you for it all again."
+  },
+  {
+    name: "url",
+    need: "optional",
+    takes: "The full page URL this happened on.",
+    note: "Its query string is where campaign parameters and ad click ids are read from. Without it the event counts, and belongs to no page."
+  },
+  {
+    name: "value",
+    need: "optional",
+    takes: "What it was worth: a decimal string or a JSON number. No thousands separator, no sign, no exponent.",
+    note: 'Rounded to what the currency holds \u2014 1200.999 EUR is stored as 1201.00. "1,200" is refused.'
+  },
+  {
+    name: "currency",
+    need: "conditional",
+    takes: "An ISO-4217 code, e.g. EUR. Required whenever value is present, and refused on its own."
+  },
+  {
+    name: "properties",
+    need: "optional",
+    takes: "A flat object of strings \u2014 anything you want to break the event down by later."
+  }
+];
+var RESPONSE_FIELDS = [
+  {
+    name: "mode",
+    need: "required",
+    takes: "live or test, echoed back \u2014 so a forgotten header is visible in the reply rather than in a report next week."
+  },
+  { name: "received", need: "required", takes: "How many events we read, so you can detect a truncated body." },
+  { name: "accepted", need: "required", takes: "How many were counted." },
+  {
+    name: "rejected",
+    need: "required",
+    takes: "One entry per refused event: index, event_id, code, message.",
+    note: "index is the position in your own array, and is the one to branch on \u2014 event_id is empty for an event that sent none."
+  }
+];
+var REJECTION_CODE_LIST = REJECTION_CODES;
+var BATCH_LIMITS = {
+  events: EVENT_INGEST_BATCH_MAX,
+  megabytes: BODY_MAX_MB,
+  requestsPerMinute: EVENT_INGEST_REQUESTS_PER_MINUTE
+};
+
+// ../api/src/event-ingest/matching.ts
+var MATCH_FIELDS = [
+  "first_name",
+  "last_name",
+  "date_of_birth",
+  "gender",
+  "city",
+  "region",
+  "postal_code",
+  "country"
+];
+var MATCH_COOKIES = ["fbp", "fbc"];
+function tightened(value) {
+  const stripped = value.toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+  return stripped === "" ? null : stripped;
+}
+function loosened(value) {
+  const collapsed = value.trim().toLowerCase().replace(/\s+/g, " ");
+  return collapsed === "" ? null : collapsed;
+}
+function birthDate(value) {
+  const digits = value.replace(/\D/g, "");
+  if (!/^\d{8}$/.test(digits)) return null;
+  const month = Number(digits.slice(4, 6));
+  const day = Number(digits.slice(6, 8));
+  if (month < 1 || month > 12 || day < 1 || day > 31) return null;
+  return digits;
+}
+function genderLetter(value) {
+  const first = value.trim().toLowerCase().charAt(0);
+  return first === "f" || first === "m" ? first : null;
+}
+function countryCode(value) {
+  const code = value.trim().toLowerCase();
+  return /^[a-z]{2}$/.test(code) ? code : null;
+}
+var MATCH_SPECS = {
+  first_name: { keep: "hashed", normalize: tightened, meta: "fn", google: "hashed_first_name" },
+  last_name: { keep: "hashed", normalize: tightened, meta: "ln", google: "hashed_last_name" },
+  // Meta only. Google's enhanced conversions have no date of birth, so there is
+  // no destination wanting it in the clear and every reason not to keep one.
+  date_of_birth: { keep: "hashed", normalize: birthDate, meta: "db", google: null },
+  gender: { keep: "plain", normalize: genderLetter, meta: "ge", google: null },
+  city: { keep: "plain", normalize: loosened, meta: "ct", google: "city" },
+  region: { keep: "plain", normalize: loosened, meta: "st", google: "state" },
+  postal_code: { keep: "plain", normalize: loosened, meta: "zp", google: "postal_code" },
+  country: { keep: "plain", normalize: countryCode, meta: "country", google: "country_code" }
+};
+var MATCH_FIELD_FORWARDING = [
+  { field: "email", meta: "em", google: "hashed_email", hashed: true },
+  { field: "phone", meta: "ph", google: "hashed_phone_number", hashed: true },
+  // Kept in the clear — see `resolveOwnId`. The digest is still computed and
+  // still stored beside it, so a Meta forward has one; what changed is that the
+  // sender's own key is now readable, which is the entire reason they sent it.
+  { field: "external_id", meta: "external_id", google: null, hashed: false },
+  ...MATCH_FIELDS.map((field) => ({
+    field,
+    meta: MATCH_SPECS[field].meta,
+    google: MATCH_SPECS[field].google,
+    hashed: MATCH_SPECS[field].keep === "hashed"
+  })),
+  { field: "fbp", meta: "fbp", google: null, hashed: false },
+  { field: "fbc", meta: "fbc", google: null, hashed: false }
+];
+
+// ../api/src/event-ingest/brief.ts
+var KEY_ENV_VAR = "BAKER_EVENTS_KEY";
+var KEY_PLACEHOLDER = "<your sending key>";
+var NEED_WORD = {
+  required: "required",
+  optional: "optional",
+  conditional: "conditional"
+};
+function cell(text2) {
+  return text2.replaceAll("<", "\\<").replaceAll("|", "\\|");
+}
+function table(fields) {
+  const rows = fields.map((field) => {
+    const name = field.under === true ? `\u21B3 \`${field.name}\`` : `\`${field.name}\``;
+    const note = field.note === void 0 ? "" : `<br>${cell(field.note)}`;
+    return `| ${name} | ${NEED_WORD[field.need]} | ${cell(field.takes)}${note} |`;
+  });
+  return ["| Field | | What it takes |", "| --- | --- | --- |", ...rows].join("\n");
+}
+function standardNames() {
+  return [
+    "| Name | Means |",
+    "| --- | --- |",
+    ...STANDARD_EVENT_NAMES.map((standard) => `| \`${standard.name}\` | ${standard.means} |`)
+  ].join("\n");
+}
+function forwarding() {
+  return [
+    "| Field | Meta | Google | Held as |",
+    "| --- | --- | --- | --- |",
+    ...MATCH_FIELD_FORWARDING.map(
+      (row) => `| \`${row.field}\` | \`${row.meta}\` | ${row.google === null ? "\u2014" : `\`${row.google}\``} | ${row.hashed ? "SHA-256" : "plain text"} |`
+    )
+  ].join("\n");
+}
+function ingestBrief(endpointUrl) {
+  const { events, megabytes, requestsPerMinute } = BATCH_LIMITS;
+  return `# Send events to Baker from your server
+
+You are being handed this by somebody who wants an integration built against it. It is
+the complete contract for \`POST /v1/events\` on **their own Baker endpoint**, taken from
+the code that enforces it. Build from this document; you should not need to look
+anything else up.
+
+Baker measures what happens on the pages it publishes. This endpoint is how everything
+that happens *away* from those pages \u2014 a deal closing in a CRM, a subscription starting,
+an order shipping \u2014 reaches the same reports, joined to the same person.
+
+## Read this before you write anything
+
+1. **Never put the sending key in source, and never paste it into a chat.** It is
+   deliberately not in this document. Read it from \`${KEY_ENV_VAR}\` and ask the person
+   for the value \u2014 they can copy it from Baker \u2192 Measure \u2192 Events \u2192 Sending events.
+2. **Send \`X-Baker-Mode: test\` while you build.** A test request is authenticated,
+   parsed and validated in exactly the same way and answers in exactly the same shape,
+   and **stores nothing**. Remove the header to go live. There is no separate test key
+   and no separate endpoint, so nothing about the integration changes when it does.
+3. **A \`200\` does not mean it counted.** The body carries \`rejected[]\`, one entry per
+   refused event. Read it and log it on every response. Throwing it away is the single
+   most common way an integration against this endpoint is wrong and looks right.
+4. **Batch.** Up to ${events} events and ${megabytes} MB per request, and at most
+   ${requestsPerMinute} requests per minute for the whole company. One event per request
+   works and will exhaust that budget on any real backfill. Every event is judged on its
+   own, so one bad row is refused and the rest of the batch still counts.
+5. **Retry \`5xx\` and \`429\`, never \`4xx\`.** A \`4xx\` means the request is wrong and
+   will be wrong again. If you retry, send the same \`event_id\` \u2014 that is what makes the
+   retry count once.
+6. **A refund is its own event, not a negative amount.** \`value\` may not be negative.
+   Send an event with its own name and let the reports subtract.
+7. **You cannot declare a conversion.** Whether an event counts as one is a decision the
+   client makes in Baker, against the event's name, and it applies retroactively to
+   everything already sent under that name. Nothing in the payload can assert it.
+8. **Ask, do not guess.** Which events matter and where the person's email lives in their
+   system are things this document cannot tell you. Ask.
+
+## Endpoint
+
+\`\`\`
+POST ${endpointUrl}
+\`\`\`
+
+### Headers
+
+${table(HEADER_FIELDS)}
+
+### Body
+
+\`\`\`json
+{ "events": [ { "event_name": "..." } ] }
+\`\`\`
+
+Up to ${events} events and ${megabytes} MB per request.
+
+## The event
+
+The field names are Meta's. If you have written an integration against Meta's Conversions
+API or Google Ads' offline conversion upload, this is the same payload: \`event_name\`,
+\`event_time\`, \`event_id\`, \`user_data\`, \`value\`, \`currency\`.
+
+${table(EVENT_FIELDS)}
+
+### Naming the person is the part that matters
+
+\`user_data\` is required and every field in it is optional, which is not a contradiction:
+the event has to name **somebody**, and there are several ways to do it. An event that
+names nobody is refused with \`missing_identity\`.
+
+Ranked by how well each works, best first:
+
+1. \`baker_id\` \u2014 the id a Baker page already gave that browser. It names the *visit*, so
+   the event lands on a real session's timeline. Send it if the client's system kept it.
+2. \`email\` or \`phone\` \u2014 the road that cannot silently fail. Send the plain value if you
+   can: we normalise and hash it here under the same rule the browser uses, so it lands
+   on exactly the person the pages already recorded. If policy forbids sending it plain,
+   send the SHA-256 digest **in the same field** \u2014 we detect which it is. Hash the
+   trimmed, lower-cased address; for a phone, digits with a leading \`+\`.
+3. \`external_id\` \u2014 the client's own key for the person, a CRM contact id. Stored as sent,
+   and hashed alongside so it joins.
+   On its own it joins that system's events to each other; send it **once** alongside an
+   email or a \`baker_id\` and every later event carrying only the contact id joins the
+   person too. That link is retroactive: it reaches back to everything already sent.
+4. A click id, \`fbp\` or \`fbc\` \u2014 names the click or the browser that brought them, which
+   is what a report attributes the event to.
+
+Send every one you have, not just the best. They cost nothing extra and each is a
+separate chance to match.
+
+### The matching fields, and where they go afterwards
+
+\`first_name\` \u2026 \`country\` never satisfy \`user_data\` on their own \u2014 they describe a
+person and name nobody. They are worth sending anyway: they are exactly what Meta's
+advanced matching and Google's enhanced conversions match on, and keeping them means the
+event can be forwarded later without going back to the client's CRM for it.
+
+${forwarding()}
+
+## Standard event names
+
+Nothing is refused for being absent from this list \u2014 send whatever the business calls a
+thing. These are the spellings Baker publishes so that two companies measuring the same
+thing measure it under the same word. \`page_view\` is the one with behaviour: it becomes
+a page view rather than a named event, and it is the only event that may arrive without a
+person as long as it carries a \`url\`.
+
+${standardNames()}
+
+## The response
+
+\`\`\`json
+{ "ok": true, "data": { "mode": "live", "received": 2, "accepted": 1,
+  "rejected": [ { "index": 1, "event_id": "", "code": "invalid_value",
+    "message": "value and currency go together: a non-negative decimal and an ISO-4217 code" } ] } }
+\`\`\`
+
+${table(RESPONSE_FIELDS)}
+
+\`code\` is a closed set \u2014 branch on it, not on \`message\`:
+
+${REJECTION_CODE_LIST.map((code) => `- \`${code}\``).join("\n")}
+
+There is no duplicate count, on purpose. A repeated \`event_id\` is accepted like any other
+event and counted **once** \u2014 one conversion, one event, its value added once \u2014 so a retry
+is safe and needs no branch of its own. Both requests are shown in Baker, with the later
+one marked "Already counted", so a retry is visible without being counted.
+
+### HTTP statuses
+
+| Status | Means | Do |
+| --- | --- | --- |
+| \`200\` | The request was read. Individual events may still have been refused. | Read \`rejected[]\`. |
+| \`400\` | The body is not the shape above \u2014 an unknown field, or the wrong JSON type. | Fix the payload. Do not retry. |
+| \`401\` | The key is missing, wrong, or not a sending key. | Fix the credential. Do not retry. |
+| \`413\` | Over ${events} events or ${megabytes} MB. | Split the batch and re-post. |
+| \`429\` | Over ${requestsPerMinute} requests a minute for this company. | Back off and retry. |
+| \`5xx\` | Nothing was written. | Retry with the same \`event_id\`s. |
+
+## A request that works
+
+\`\`\`bash
+${eventIngestCurl(endpointUrl, KEY_PLACEHOLDER)}
+\`\`\`
+
+## Once it is sending
+
+Every accepted event appears in Baker under **Measure \u2192 Events**, live, with what was
+sent. Test sends and refusals appear there too, filed separately and marked, with the
+payload \u2014 so "did my request arrive and what did it say" is answered on the screen rather
+than in the client's own logs. To make an event count as a conversion, the client marks
+it by name under **Conversions**.
+`;
+}
+
+// ../api/src/event-ingest/preview.ts
+var MATCHING_KEYS = new Set(MATCH_FIELDS);
+var PREVIEWED_FIELDS = [
+  "email",
+  "phone",
+  ...MATCH_FIELDS.filter((field) => MATCH_SPECS[field].keep === "hashed")
+];
+
+// ../api/src/event-ingest/vocabulary.ts
+var INGEST_CLICK_ID_PARAMS = [
+  "gclid",
+  "wbraid",
+  "gbraid",
+  "fbclid",
+  "ttclid",
+  "twclid",
+  "li_fat_id",
+  "msclkid"
+];
+
+// ../api/src/event-ingest/wire.ts
+import { z as z31 } from "zod";
+var ingestUserDataSchema = z31.strictObject({
+  /** A plain address, or its SHA-256 digest. Both accepted; we tell them apart. */
+  email: z31.string().nullish(),
+  /** A plain number, or its SHA-256 digest. Include the country code. */
+  phone: z31.string().nullish(),
+  /** Your own id for this person — a CRM contact id. Stored as you sent it, and hashed alongside so it joins. */
+  external_id: z31.string().nullish(),
+  /** The Baker ID this browser already carries, if your system kept it. */
+  baker_id: z31.string().nullish(),
+  ...Object.fromEntries(
+    [...MATCH_FIELDS, ...MATCH_COOKIES, ...INGEST_CLICK_ID_PARAMS].map((param) => [param, z31.string().nullish()])
+  )
+});
+var ingestEventSchema = z31.strictObject({
+  /**
+   * What happened, in the sender's words. The only required field.
+   *
+   * Open vocabulary — nothing is checked against anything, exactly like a
+   * `data-baker-*` event on a landing page. `STANDARD_EVENT_NAMES` publishes a
+   * spelling for the common ones so two companies measuring the same thing
+   * measure it under the same word, and `page_view` is the one name that also
+   * carries behaviour.
+   *
+   * Whether an event **counts as a conversion** is not said here and cannot be:
+   * a conversion is a name this company marked on its own Conversions screen,
+   * matched at read time. A sender asserting one would be asserting something
+   * about our configuration that they cannot see.
+   */
+  event_name: z31.string(),
+  /**
+   * When it happened: an ISO-8601 instant with an offset, or Unix seconds.
+   *
+   * Optional, defaulting to when the request arrived. Meta and Google both
+   * require their equivalent, and both are *offline conversion upload* APIs
+   * where a past event is the only case there is. This door also serves the
+   * live one — a CRM firing a webhook the moment a deal closes — and for that
+   * sender the timestamp is the arrival time to within a second, so demanding
+   * it buys nothing and loses the events of anyone who forgets it.
+   */
+  event_time: z31.union([z31.string(), z31.number()]).nullish(),
+  /**
+   * Your own id for this event, and **only** if you want it deduplicated.
+   *
+   * Optional, exactly as it is on Meta's Conversions API: send the same id
+   * twice and it is counted once, send none and every post is its own event.
+   * Its *shape* is checked in `validateEventId`, not here, so a bad one is
+   * `invalid_event_id` inside a `200` rather than a `400` for the other 199.
+   */
+  event_id: z31.string().nullish(),
+  /**
+   * The page this happened on, as a full URL.
+   *
+   * Not in the minimal shape a server integration needs, and kept anyway: a
+   * `page_view` with no URL names nothing, and the campaign parameters and
+   * click ids a report is built on live in the query string. Everything else
+   * treats it as optional context.
+   */
+  url: z31.string().nullish(),
+  user_data: ingestUserDataSchema.nullish(),
+  /**
+   * What it was worth, as a decimal string or a JSON number.
+   *
+   * Flat beside `currency` rather than a `{ amount, currency }` object of our
+   * own: that is where Google Ads keeps `conversion_value`/`currency_code` and
+   * where Meta keeps `value`/`currency` inside `custom_data`.
+   */
+  value: z31.union([z31.string(), z31.number()]).nullish(),
+  /** ISO-4217, required whenever `value` is present. */
+  currency: z31.string().nullish(),
+  /**
+   * Flat detail about the event.
+   *
+   * Emails and phone numbers are masked out of the **values** before anything
+   * is persisted — both into the event store and into the ingest log. Keys are
+   * left alone: masking one would rename the field and could collide with a
+   * sibling.
+   */
+  properties: z31.record(z31.string(), z31.string()).nullish()
+});
+var ingestBatchSchema = z31.strictObject({
+  events: z31.array(ingestEventSchema).min(1).max(EVENT_INGEST_BATCH_MAX)
+});
+var ingestRejectionSchema = z31.strictObject({
+  index: z31.number().int().nonnegative(),
+  event_id: z31.string(),
+  code: z31.enum(REJECTION_CODES),
+  message: z31.string()
+});
+var ingestResponseSchema = z31.strictObject({
+  /**
+   * How this request was treated, echoed from `X-Baker-Mode`.
+   *
+   * Here because the mode is a property of the request rather than of the key,
+   * and the risk that comes with that is a forgotten header putting a rehearsal
+   * into a client's real reports. Echoing it puts the answer to "did that
+   * count?" in the reply to the request that asked, instead of in a report
+   * somebody reads a week later.
+   */
+  mode: z31.enum(INGEST_MODES),
+  /** `events.length`, echoed back so a client can detect a truncated body. */
+  received: z31.number().int().nonnegative(),
+  accepted: z31.number().int().nonnegative(),
+  rejected: z31.array(ingestRejectionSchema)
+});
+var ingestEnvelopeSchema = z31.object({ ok: z31.literal(true), data: ingestResponseSchema });
+
 // src/commands/analytics/index.ts
 import { defineCommand as defineCommand95 } from "citty";
 
@@ -27019,7 +28035,18 @@ function adHierarchyHints(data, platform) {
     `${platform} traffic carries no ${missing.map((entry) => AD_PARAM_ROLE_SPECS[entry.role].label.toLowerCase()).join(", ")}, so no report can say which ad sent a visit \u2014 only which platform. Add \`${suffix}\` to that account's tracking template. This cannot be backfilled: a parameter's values are only stored once it starts arriving.`
   ];
 }
-function buildAnalyticsHints(data, platform) {
+function sessionlessHint(data, origin) {
+  if (data.totals.pageViews === 0 || data.totals.sessions > 0) return [];
+  if (origin === "systems") {
+    return [
+      "No sessions, because this report is scoped to events a client's own server posted and those carry no visit \u2014 a session would be an invented one. Every per-visitor rate here is null for the same reason; read the counts, and drop --origin for anything about behaviour."
+    ];
+  }
+  return [
+    "Pages were served but no sessions were counted \u2014 visitors are declining analytics consent, so traffic is measurable and per-visitor behaviour is not. Say so rather than reporting zero visitors."
+  ];
+}
+function buildAnalyticsHints(data, platform, origin) {
   const hints2 = [];
   for (const funnel of data.funnels ?? []) {
     const worst = funnel.worstStep;
@@ -27039,11 +28066,7 @@ function buildAnalyticsHints(data, platform) {
       "Visitors leave in under ten seconds on average \u2014 that is usually a mismatch between the ad and the page, not a form problem. Check the top sources against the page's headline."
     );
   }
-  if (data.totals.pageViews > 0 && data.totals.sessions === 0) {
-    hints2.push(
-      "Pages were served but no sessions were counted \u2014 visitors are declining analytics consent, so traffic is measurable and per-visitor behaviour is not. Say so rather than reporting zero visitors."
-    );
-  }
+  hints2.push(...sessionlessHint(data, origin));
   hints2.push(...shapeHints(data));
   hints2.push(...adHierarchyHints(data, platform));
   if ((data.topCampaigns ?? []).length === 0 && (data.topSources ?? []).length > 0) {
@@ -27209,7 +28232,7 @@ function isTabular(rows) {
     )
   );
 }
-function cell(value, key) {
+function cell2(value, key) {
   if (value === null || value === void 0) return "";
   if (Array.isArray(value)) return value.join(" ");
   if (typeof value === "number" && !Number.isInteger(value)) {
@@ -27265,12 +28288,12 @@ function columnsOf(rows) {
   }
   return seen.filter((key) => rows.some((row) => !isAbsent(row[key]) && row[key] !== null && row[key] !== void 0)).sort(byIdentityFirst);
 }
-function table(rows) {
+function table2(rows) {
   const cols = columnsOf(rows);
   if (cols.length === 0) return "";
   const head = `| ${cols.join(" | ")} |`;
   const rule = `| ${cols.map(() => "---").join(" | ")} |`;
-  const body = rows.map((row) => `| ${cols.map((col) => cell(row[col], col)).join(" | ")} |`);
+  const body = rows.map((row) => `| ${cols.map((col) => cell2(row[col], col)).join(" | ")} |`);
   return [head, rule, ...body].join("\n");
 }
 function isRowList(value) {
@@ -27287,11 +28310,11 @@ function nestedBlock(name, rows) {
   const parents = rows.map(
     (row) => Object.fromEntries(Object.entries(row).filter(([, value]) => !isRowList(value) && !isPlainRow(value)))
   );
-  const parts = [`### ${name}`, table(parents)];
+  const parts = [`### ${name}`, table2(parents)];
   rows.forEach((row, index) => {
     for (const [key, value] of Object.entries(row)) {
-      if (isRowList(value)) parts.push(`#### ${name}[${labelOf(row, index)}].${key}`, table(value));
-      else if (isPlainRow(value)) parts.push(`#### ${name}[${labelOf(row, index)}].${key}`, table([value]));
+      if (isRowList(value)) parts.push(`#### ${name}[${labelOf(row, index)}].${key}`, table2(value));
+      else if (isPlainRow(value)) parts.push(`#### ${name}[${labelOf(row, index)}].${key}`, table2([value]));
     }
   });
   return parts.filter((part) => part !== "").join("\n");
@@ -27303,7 +28326,7 @@ function block(name, value) {
   if (Array.isArray(value)) {
     if (value.length === 0) return "";
     if (isTabular(value)) return `### ${name}
-${table(value)}`;
+${table2(value)}`;
     if (isRowList(value)) return nestedBlock(name, value);
     return `### ${name}
 ${JSON.stringify(value)}`;
@@ -27313,13 +28336,13 @@ ${JSON.stringify(value)}`;
     if (entries.length === 0) return "";
     if (entries.every(([, v]) => v === null || typeof v !== "object")) {
       return `### ${name}
-${entries.map(([k, v]) => `- ${k}: ${v === null ? "null" : cell(v, k)}`).join("\n")}`;
+${entries.map(([k, v]) => `- ${k}: ${v === null ? "null" : cell2(v, k)}`).join("\n")}`;
     }
     return `### ${name}
 ${JSON.stringify(value)}`;
   }
   return `### ${name}
-${cell(value)}`;
+${cell2(value)}`;
 }
 function renderMarkdown3(envelope) {
   const parts = [];
@@ -27425,6 +28448,11 @@ var SHARED_ARGS = {
     description: "Read the whole report in one ad platform's vocabulary, and from its traffic only: google, meta, microsoft, linkedin, tiktok, reddit, pinterest, snapchat. Two effects at once \u2014 --role resolves against the spellings that platform uses (`cid` is TikTok's ad and nobody else's campaign) and the report narrows to the visits that arrived from it. Start here when comparing platforms, because without it every dimension is the union across all of them and one parameter can land under two roles",
     required: false
   },
+  origin: {
+    type: "string",
+    description: "Read one collector only: `site` for what Baker measured on its own pages, `systems` for what the client's own server posted to POST /v1/events. Omit it for both, which is the default and the honest superset. Reach for it when a number moved and nothing on the pages changed \u2014 a CRM replaying history lands in the same totals as a visitor, and this is the only thing that separates them. Honoured by overview, traffic, events and conversions; every session-scoped report ignores it, because a server-sent event carries no visit to be counted in",
+    required: false
+  },
   output: {
     type: "string",
     description: "json (default) | md. `md` renders each block as a table \u2014 one header instead of the keys repeated on every row \u2014 which is 20-50% smaller than the JSON on a typical report and more on a long breakdown. Reach for it whenever you are going to read the numbers rather than pick one field out of them. Both carry the same warnings and hints",
@@ -27480,13 +28508,26 @@ function requestBody(args, options) {
     // everything.
     adValue: args.role !== void 0 && args.value !== void 0 ? String(args.value) : void 0,
     adPlatform: args.platform ? String(args.platform) : void 0,
+    eventOrigin: args.origin ? String(args.origin) : void 0,
     ...pageOf(args)
   };
   return Object.fromEntries(
     Object.entries(candidates).filter(([key, value]) => value !== void 0 && (value !== "" || key === "adValue"))
   );
 }
+var EVENT_ORIGINS = ["site", "systems"];
 async function runPreset(args, options) {
+  const origin = args.origin === void 0 ? "" : String(args.origin);
+  if (origin !== "" && !EVENT_ORIGINS.includes(origin)) {
+    writeJsonEnvelope({
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: `Unknown --origin "${origin}". Use one of: ${EVENT_ORIGINS.join(", ")}, or omit it for both.`
+      }
+    });
+    process.exit(1);
+  }
   try {
     const response = await apiPost("/api/analytics/query", requestBody(args, options));
     const requestedPlatform = args.platform === void 0 ? "" : String(args.platform);
@@ -27508,7 +28549,7 @@ async function runPreset(args, options) {
       // only speak about the inventory it was actually given. `adParams` is one
       // platform's list; a hint drawn from it without knowing which platform
       // would be a claim about Meta made from Google's URLs.
-      ...buildAnalyticsHints(response.data, adPlatformScope),
+      ...buildAnalyticsHints(response.data, adPlatformScope, origin === "" ? void 0 : origin),
       ...missingBreakdownHint(response.data, {
         eventName: options.eventName,
         property: options.property
@@ -27909,6 +28950,102 @@ function parseList(raw) {
   const out = raw.split(",").map((entry) => entry.trim()).filter((entry) => entry !== "");
   return out.length > 0 ? out : void 0;
 }
+var arrivalsCommand = (() => {
+  const args = {
+    mode: {
+      type: "string",
+      description: "live | test. Rehearsals (X-Baker-Mode: test) are accepted and write nothing, so they never reach a report \u2014 filter to them to confirm a rehearsal landed, or to live to see only what counted",
+      required: false
+    },
+    outcome: {
+      type: "string",
+      description: "accepted | rejected. Start with rejected: it is the half the sender's own logs threw away, and the reason to open this at all",
+      required: false
+    },
+    event: {
+      type: "string",
+      description: "Only this event_name, for a company posting several kinds",
+      required: false
+    },
+    limit: {
+      type: "string",
+      description: `How many to return, newest first (default 25, max ${INGEST_ARRIVALS_MAX})`,
+      required: false
+    },
+    full: {
+      type: "boolean",
+      description: "Also return the masked request body and the per-field identity previews. Reach for it only once the codes have not explained it \u2014 it is most of the bytes",
+      required: false
+    }
+  };
+  registerSchema({
+    command: "analytics.arrivals",
+    description: "What a client's own server posted to POST /v1/events in the last 48 hours, and why any of it was refused",
+    args
+  });
+  return defineCommand95({
+    meta: {
+      name: "arrivals",
+      description: `Every request a client's own server posted to POST /v1/events in the last 48 hours \u2014 accepted, refused or rehearsed. The one place a server-side integration can be debugged.
+
+Read this FIRST whenever somebody says events are being sent and nothing shows up. Four different causes look identical from the sender's side and only this tells them apart:
+  the request never reached us          \u2014 nothing here at all: the key, the URL, or their own dispatch
+  it was refused                        \u2014 rejectCode says which rule, rejectMessage says what the field had to be
+  it was a rehearsal                    \u2014 mode: test is accepted, answered identically, and writes nothing on purpose
+  it landed                             \u2014 then the question is a report's, not the endpoint's
+
+Examples:
+  baker analytics arrivals                      \u2014 the last 25, newest first
+  baker analytics arrivals --outcome rejected   \u2014 only the refusals, which is usually the whole answer
+  baker analytics arrivals --mode test          \u2014 did the rehearsal they just ran actually arrive
+  baker analytics arrivals --event deal_won     \u2014 one kind only
+  baker analytics arrivals --full --limit 5     \u2014 the masked body, when the codes have not explained it`
+    },
+    args,
+    run: async ({ args: raw }) => {
+      try {
+        const limit = raw.limit === void 0 ? void 0 : Number(raw.limit);
+        const response = await apiPost("/api/analytics/arrivals", {
+          ...raw.mode ? { mode: String(raw.mode) } : {},
+          ...raw.outcome ? { outcome: String(raw.outcome) } : {},
+          ...raw.event ? { eventName: String(raw.event) } : {},
+          ...limit !== void 0 && Number.isFinite(limit) ? { limit } : {},
+          ...raw.full ? { full: true } : {}
+        });
+        writeJsonEnvelope(response);
+      } catch (err) {
+        handleError(err);
+      }
+    }
+  });
+})();
+var sendingEventsCommand = (() => {
+  registerSchema({
+    command: "analytics.sending-events",
+    description: "The POST /v1/events contract as Markdown, for whoever is writing the integration",
+    args: {}
+  });
+  return defineCommand95({
+    meta: {
+      name: "sending-events",
+      description: `The complete contract for sending events into Baker from a client's own systems \u2014 a CRM marking a deal won, a back office recording a refund \u2014 as Markdown you can hand straight to whoever writes the integration.
+
+Use it whenever a client wants an outcome that happens AFTER the lead leaves the page to show up in Baker. Every bound, every rejection code and every rule is read off the code that enforces it, so it cannot go stale; the six mistakes that all produce a 200 are called out before the reader starts rather than explained afterwards.
+
+It contains no key \u2014 the brief says to read one from an environment variable, and the key itself is minted in the dashboard under Settings \u2192 API keys. Never put one in a file or a message.
+
+Examples:
+  baker analytics sending-events              \u2014 the contract, as Markdown
+  baker analytics arrivals --outcome rejected \u2014 after they have wired it up, what is being refused`
+    },
+    args: {},
+    run: () => {
+      const apiUrl = getEnv().BAKER_API_URL;
+      process.stdout.write(`${ingestBrief(eventIngestUrl(apiUrl, apiUrl))}
+`);
+    }
+  });
+})();
 var analyticsCommand2 = defineCommand95({
   meta: {
     name: "analytics",
@@ -27949,6 +29086,9 @@ Examples:
   baker analytics map --platform google --remove kw        \u2014 take that answer back
   baker analytics delivery --page 2 --page-size 50         \u2014 the next page of a long list
   baker analytics overview --compare          \u2014 this window against the one before it
+  baker analytics sending-events              \u2014 the contract for a client's server to post its own events
+  baker analytics arrivals --outcome rejected \u2014 what their server posted that we refused, and why
+  baker analytics events --origin systems     \u2014 the events their systems reported, not ours
 Full guide: __tooling__/docs/tools/baker/analytics.md`
   },
   subCommands: {
@@ -27972,6 +29112,8 @@ Full guide: __tooling__/docs/tools/baker/analytics.md`
     conversions: conversionsCommand3,
     map: mapCommand,
     tracking: trackingCommand,
+    arrivals: arrivalsCommand,
+    "sending-events": sendingEventsCommand,
     presets: presetsCommand
   }
 });
@@ -30296,7 +31438,7 @@ import { toCardinal as nwKo } from "n2words/ko-KR";
 import { toCardinal as nwNl } from "n2words/nl-NL";
 import { toCardinal as nwPl } from "n2words/pl-PL";
 import { toCardinal as nwPt } from "n2words/pt-PT";
-import { z as z30 } from "zod";
+import { z as z32 } from "zod";
 
 // src/engine/scaffold/lib/shoot-modes.ts
 var SHOOT_MODES = [
@@ -30646,71 +31788,71 @@ function trimArgs(durationS, offsetS = 0, dims) {
     "{{out.video}}"
   ];
 }
-var FrameAsset = z30.object({ url: z30.string().optional() }).loose().optional();
-var DialogueLine = z30.object({
-  speaker: z30.string().optional(),
-  line: z30.string().optional(),
+var FrameAsset = z32.object({ url: z32.string().optional() }).loose().optional();
+var DialogueLine = z32.object({
+  speaker: z32.string().optional(),
+  line: z32.string().optional(),
   // Absolute seconds on the source timeline (the deconstruct emits both).
-  start_s: z30.number().optional(),
-  end_s: z30.number().optional(),
-  delivery: z30.string().optional(),
-  voice_description: z30.string().optional(),
+  start_s: z32.number().optional(),
+  end_s: z32.number().optional(),
+  delivery: z32.string().optional(),
+  voice_description: z32.string().optional(),
   // DECON-supplied: is this speaker's FACE visibly speaking in THIS scene? Element
   // presence alone can't answer that — a founder pictured in a polaroid close-up is
   // "present" yet the line is voiceover, and treating it as on-camera produced a
   // native Seedance lip-sync clip of a still photograph. `false` pins the line to
   // the VO path; absent keeps the presence-based decision (old blueprints).
-  on_camera: z30.boolean().optional()
+  on_camera: z32.boolean().optional()
 }).loose();
-var Sfx = z30.object({
-  at_s: z30.number().optional(),
-  duration_s: z30.number().optional(),
-  sound_effect_prompt: z30.string().optional(),
-  description: z30.string().optional()
+var Sfx = z32.object({
+  at_s: z32.number().optional(),
+  duration_s: z32.number().optional(),
+  sound_effect_prompt: z32.string().optional(),
+  description: z32.string().optional()
 }).loose();
-var CompositionRegion = z30.object({
+var CompositionRegion = z32.object({
   // full | top | bottom | left | right | inset
-  panel: z30.string().optional(),
+  panel: z32.string().optional(),
   // 9-grid anchor for an `inset` presenter box.
-  position: z30.string().optional(),
-  is_presenter: z30.boolean().optional(),
+  position: z32.string().optional(),
+  is_presenter: z32.boolean().optional(),
   // The cast id shown/speaking in this region (routes lip-sync + element refs).
-  cast_ref: z30.string().optional(),
+  cast_ref: z32.string().optional(),
   // What the region's content IS: camera | screen_capture | static_graphic |
   // generated. Authoritative for routing when present (regex-over-prose fallback
   // otherwise): screen_capture/static_graphic are rebuilt from REAL surfaces on the
   // overlay layer, never AI-generated.
-  kind: z30.string().optional(),
+  kind: z32.string().optional(),
   // Opaque id naming the SPECIFIC on-screen document/note/app-state this
   // screen_capture region shows. Two scenes share it only when they show the SAME
   // recording continuing (scrolling/typing/waiting within it) — a genuinely
   // DIFFERENT document/note/recording (a source video splicing two screen captures)
   // gets a different id. Breaks a persistent-layout run into separate surface stubs
   // instead of asking the operator for one screenshot that can't cover both.
-  surface_id: z30.string().optional(),
+  surface_id: z32.string().optional(),
   // Camera bubble(s)/inset(s) embedded INSIDE this region's surface (a Loom-style
   // presenter bubble inside a screen recording) — video-in-video the reproduction
   // must re-composite, not paint into the surface.
-  nested: z30.array(z30.object({}).loose()).optional(),
-  summary: z30.string().optional(),
-  frame_prompt: z30.string().optional(),
-  motion_prompt: z30.string().optional()
+  nested: z32.array(z32.object({}).loose()).optional(),
+  summary: z32.string().optional(),
+  frame_prompt: z32.string().optional(),
+  motion_prompt: z32.string().optional()
 }).loose();
-var SceneComposition = z30.object({
+var SceneComposition = z32.object({
   // full_frame (default) | split_screen | pip | keyed_overlay
-  layout: z30.string().optional(),
+  layout: z32.string().optional(),
   // split_screen only: vertical (top/bottom) | horizontal (left/right).
-  split_axis: z30.string().optional(),
-  regions: z30.array(CompositionRegion).optional()
+  split_axis: z32.string().optional(),
+  regions: z32.array(CompositionRegion).optional()
 }).loose();
-var CameraMotion = z30.object({ movement: z30.string().optional(), detail: z30.string().optional() }).loose();
-var TranscriptWord = z30.object({ text: z30.string().optional() }).loose();
-var Scene = z30.object({
-  start_s: z30.number().optional(),
-  end_s: z30.number().optional(),
-  duration_s: z30.number().optional(),
-  summary: z30.string().optional(),
-  action_detail: z30.string().optional(),
+var CameraMotion = z32.object({ movement: z32.string().optional(), detail: z32.string().optional() }).loose();
+var TranscriptWord = z32.object({ text: z32.string().optional() }).loose();
+var Scene = z32.object({
+  start_s: z32.number().optional(),
+  end_s: z32.number().optional(),
+  duration_s: z32.number().optional(),
+  summary: z32.string().optional(),
+  action_detail: z32.string().optional(),
   // The scene's spatial layout. Absent/full_frame ⇒ one uncut shot (default path).
   // A layered layout (split_screen/pip/keyed_overlay) with regions ⇒ the scaffold
   // builds one clip per region and stacks/overlays them into the scene picture.
@@ -30718,82 +31860,82 @@ var Scene = z30.object({
   // The capture "look" for this scene — selected from the ad-native shoot-mode
   // grammar (see lib/shoot-modes.ts). When absent the scaffold auto-derives a
   // UGC/product mode; a human can override per scene by setting this.
-  shoot_mode: z30.string().optional(),
+  shoot_mode: z32.string().optional(),
   // Diegetic ambient the clip's native audio should carry (no music). When
   // absent the scene falls back to its shoot mode's default ambience.
-  ambient: z30.string().optional(),
+  ambient: z32.string().optional(),
   camera_motion: CameraMotion.optional(),
-  start_frame_prompt: z30.string().optional(),
-  end_frame_prompt: z30.string().optional(),
-  motion_prompt: z30.string().optional(),
+  start_frame_prompt: z32.string().optional(),
+  end_frame_prompt: z32.string().optional(),
+  motion_prompt: z32.string().optional(),
   // The scene's role in the ad's persuasion arc (DECON-supplied); drives the
   // script re-craft checklist. Inferred from position when absent.
-  narrative_role: z30.string().optional(),
+  narrative_role: z32.string().optional(),
   // DECON-supplied on the HOOK scene: the engineered physical/emotional state that
   // makes the first frame stop the scroll (sweaty/breathless/urgent …). Injected
   // into the hook's start-frame description so the generator renders that state,
   // not a calm influencer (CCA-11).
-  hook_mechanic: z30.object({ mechanic: z30.string().optional(), why_it_stops_scroll: z30.string().optional() }).loose().optional(),
+  hook_mechanic: z32.object({ mechanic: z32.string().optional(), why_it_stops_scroll: z32.string().optional() }).loose().optional(),
   // DECON-supplied per-scene location (so a gym hook isn't flattened to "home").
-  scene_setting: z30.string().optional(),
+  scene_setting: z32.string().optional(),
   // How this scene cuts to the next (DECON-supplied). A recognized non-cut type
   // (fade/whip/zoom/dissolve/swipe) is reproduced as an ffmpeg xfade at the
   // boundary; cut/match_cut/none/other stay hard cuts. The last scene's value is
   // ignored (nothing follows it).
-  transition_out: z30.object({ type: z30.string().optional(), description: z30.string().optional() }).loose().optional(),
-  dialogue: z30.array(DialogueLine).optional(),
-  sfx: z30.array(Sfx).optional(),
-  overlays: z30.array(z30.unknown()).optional(),
-  floating_elements: z30.array(z30.unknown()).optional(),
+  transition_out: z32.object({ type: z32.string().optional(), description: z32.string().optional() }).loose().optional(),
+  dialogue: z32.array(DialogueLine).optional(),
+  sfx: z32.array(Sfx).optional(),
+  overlays: z32.array(z32.unknown()).optional(),
+  floating_elements: z32.array(z32.unknown()).optional(),
   // DECON-supplied: how much the picture itself moves within the shot. Gates the
   // flash-hold optimization — a sub-2s b-roll flash with REAL subject motion
   // (pouring, spreading, hands working) must stay a real clip; freezing it turns
   // a montage into a slideshow. Absent (old blueprints) keeps the cheap still.
-  motion_level: z30.enum(["static", "subtle", "dynamic"]).optional(),
-  transcript_slice: z30.array(TranscriptWord).optional(),
+  motion_level: z32.enum(["static", "subtle", "dynamic"]).optional(),
+  transcript_slice: z32.array(TranscriptWord).optional(),
   start_frame_asset: FrameAsset,
   end_frame_asset: FrameAsset,
   // DECON-supplied: true when this scene is a length-split CONTINUATION of the
   // previous one (the SAME physical shot, broken up only because it exceeded the
   // clip ceiling). The scaffold then shares the splice keyframe — this scene's
   // start frame IS the previous scene's end frame — so the join is seamless.
-  continues_previous: z30.boolean().optional()
+  continues_previous: z32.boolean().optional()
 }).loose();
-var VideoBlueprint = z30.object({
-  source: z30.object({ aspect_ratio: z30.string().optional(), duration_s: z30.number().optional() }).loose().optional(),
-  global: z30.object({
-    music: z30.object({
-      present: z30.boolean().optional(),
-      music_prompt: z30.string().optional(),
+var VideoBlueprint = z32.object({
+  source: z32.object({ aspect_ratio: z32.string().optional(), duration_s: z32.number().optional() }).loose().optional(),
+  global: z32.object({
+    music: z32.object({
+      present: z32.boolean().optional(),
+      music_prompt: z32.string().optional(),
       // Absolute second the music enters in the reference (the bed often
       // kicks in mid-ad, after the hook). We start the regenerated track here
       // instead of at 0 so the timing matches.
-      starts_at_s: z30.number().optional(),
+      starts_at_s: z32.number().optional(),
       // Populated by the deconstruct when AudD (Shazam-style) recognizes the
       // reference track. We never reuse it — only style the regenerated bed.
-      identified_track: z30.object({ title: z30.string().optional(), artist: z30.string().optional() }).loose().nullish()
+      identified_track: z32.object({ title: z32.string().optional(), artist: z32.string().optional() }).loose().nullish()
     }).loose().optional(),
-    cast: z30.array(
-      z30.object({
-        id: z30.string().optional(),
-        description: z30.string().optional(),
+    cast: z32.array(
+      z32.object({
+        id: z32.string().optional(),
+        description: z32.string().optional(),
         // The deconstruct's note on the target-market localization (e.g. "native
         // French speaker") — read to derive the spoken-track language code.
-        market_localization_note: z30.string().optional()
+        market_localization_note: z32.string().optional()
       }).loose()
     ).optional(),
-    voiceover: z30.object({
+    voiceover: z32.object({
       // on_camera | mixed → mouths are on screen (lip-sync candidates);
       // voiceover | none → narration over the picture (no lip-sync).
-      mode: z30.string().optional(),
-      voice_description: z30.string().optional(),
-      persona: z30.string().optional()
+      mode: z32.string().optional(),
+      voice_description: z32.string().optional(),
+      persona: z32.string().optional()
     }).loose().optional(),
     // Visual palette — read only to colour a clean brand-card/CTA plate (the
     // first hex is the dominant brand colour); never to drive frame generation.
-    style: z30.object({ palette: z30.array(z30.object({ hex: z30.string().optional() }).loose()).optional() }).loose().optional()
+    style: z32.object({ palette: z32.array(z32.object({ hex: z32.string().optional() }).loose()).optional() }).loose().optional()
   }).loose().optional(),
-  scenes: z30.array(Scene).min(1)
+  scenes: z32.array(Scene).min(1)
 }).loose();
 function injectHookPhysicality(blueprint) {
   for (const scene of blueprint.scenes) {
@@ -30810,26 +31952,26 @@ function clipIntentOf(scene, sceneIndex) {
   if (/hero|reveal|product|payoff|transformation|result/.test(role) || scene.motion_level === "dynamic") return "hero";
   return "body";
 }
-var AppearsItem = z30.union([z30.number(), z30.object({ scene: z30.number(), edge: z30.string().optional() }).loose()]);
-var RecurringElement = z30.object({
+var AppearsItem = z32.union([z32.number(), z32.object({ scene: z32.number(), edge: z32.string().optional() }).loose()]);
+var RecurringElement = z32.object({
   // person | animal | product | logo | badge | other
-  type: z30.string(),
-  label: z30.string().optional(),
-  description: z30.string().optional(),
-  expression: z30.string().nullable().optional(),
+  type: z32.string(),
+  label: z32.string().optional(),
+  description: z32.string().optional(),
+  expression: z32.string().nullable().optional(),
   // When the element maps to a global cast entry, its stable id (for annotation).
-  cast_id: z30.string().nullable().optional(),
+  cast_id: z32.string().nullable().optional(),
   // The label of another element that is the SAME individual as this one, shown
   // in a DIFFERENT wardrobe/persona/state (e.g. one creator playing skeptic in a
   // pink shirt and believer in a white shirt). Each look gets its own reference
   // slot, but the face/identity must stay identical across them.
-  same_as: z30.string().nullable().optional(),
+  same_as: z32.string().nullable().optional(),
   // Scenes the element appears in. Either a bare list of scene indices (both
   // edges) or per-{scene,edge} entries. Both forms are accepted and merged.
-  scenes: z30.array(z30.number()).optional(),
-  appears_in: z30.array(AppearsItem).optional()
+  scenes: z32.array(z32.number()).optional(),
+  appears_in: z32.array(AppearsItem).optional()
 }).loose();
-var RecurringElements = z30.array(RecurringElement);
+var RecurringElements = z32.array(RecurringElement);
 function sanitizeId(raw, fallback) {
   const id = raw.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
   return /^[a-z]/.test(id) ? id : `${fallback}_${id}`.replace(/_+$/g, "") || fallback;
@@ -31308,7 +32450,7 @@ function scrubFloatSentences(text2, floatDescs) {
   return kept;
 }
 function sceneFloatDescs(scene) {
-  const floats = z30.array(FloatingElement).safeParse(scene.floating_elements ?? []);
+  const floats = z32.array(FloatingElement).safeParse(scene.floating_elements ?? []);
   if (!floats.success) return [];
   return floats.data.map((f) => f.description?.trim() ?? "").filter(Boolean);
 }
@@ -32741,25 +33883,25 @@ function buildSfxMusic(blueprint, clock, nodes) {
   }
   return tracks;
 }
-var OverlayStyle = z30.object({ color_hex: z30.string().optional(), background: z30.string().optional(), size: z30.string().optional() }).loose();
-var Overlay = z30.object({
-  text: z30.string().optional(),
-  appears_at_s: z30.number().optional(),
-  duration_s: z30.number().optional(),
-  position: z30.string().optional(),
-  role: z30.string().optional(),
-  animation: z30.string().optional(),
-  animation_detail: z30.string().optional(),
+var OverlayStyle = z32.object({ color_hex: z32.string().optional(), background: z32.string().optional(), size: z32.string().optional() }).loose();
+var Overlay = z32.object({
+  text: z32.string().optional(),
+  appears_at_s: z32.number().optional(),
+  duration_s: z32.number().optional(),
+  position: z32.string().optional(),
+  role: z32.string().optional(),
+  animation: z32.string().optional(),
+  animation_detail: z32.string().optional(),
   style: OverlayStyle.optional()
 }).loose();
-var FloatingElement = z30.object({
-  kind: z30.string().optional(),
-  description: z30.string().optional(),
-  brand_name: z30.string().nullish(),
-  what_it_represents: z30.string().optional(),
-  appears_at_s: z30.number().optional(),
-  duration_s: z30.number().optional(),
-  position: z30.string().optional()
+var FloatingElement = z32.object({
+  kind: z32.string().optional(),
+  description: z32.string().optional(),
+  brand_name: z32.string().nullish(),
+  what_it_represents: z32.string().optional(),
+  appears_at_s: z32.number().optional(),
+  duration_s: z32.number().optional(),
+  position: z32.string().optional()
 }).loose();
 function escapeHtml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -32791,7 +33933,7 @@ function positionClass(position) {
 function collectCaptions(blueprint, clock) {
   return blueprint.scenes.flatMap((scene, i) => {
     const sceneStart = scene.start_s ?? 0;
-    const overlays = z30.array(Overlay).safeParse(scene.overlays ?? []);
+    const overlays = z32.array(Overlay).safeParse(scene.overlays ?? []);
     return overlays.success ? overlays.data.filter((ov) => Boolean(ov.text?.trim())).map((ov) => {
       const at = clock.map(i, ov.appears_at_s ?? sceneStart);
       return { text: ov.text.trim(), at, end: at + (ov.duration_s ?? 2.5), ov };
@@ -32871,7 +34013,7 @@ function collectFloatWindows(blueprint, uiRouted, clock) {
   const windows = /* @__PURE__ */ new Map();
   blueprint.scenes.forEach((scene, i) => {
     const sceneStart = scene.start_s ?? 0;
-    const floats = z30.array(FloatingElement).safeParse(scene.floating_elements ?? []);
+    const floats = z32.array(FloatingElement).safeParse(scene.floating_elements ?? []);
     if (!floats.success) return;
     for (const fe of floats.data) {
       const at = clock.map(i, fe.appears_at_s ?? sceneStart);
@@ -33319,8 +34461,8 @@ function buildMotionBoard(blueprint) {
     const end_s = scene.end_s ?? start_s + sceneDurationS(scene);
     cursor = end_s;
     const spoken = sceneSpokenText(scene);
-    const overlays = z30.array(Overlay).safeParse(scene.overlays ?? []);
-    const floats = z30.array(FloatingElement).safeParse(scene.floating_elements ?? []);
+    const overlays = z32.array(Overlay).safeParse(scene.overlays ?? []);
+    const floats = z32.array(FloatingElement).safeParse(scene.floating_elements ?? []);
     const graphics = [
       ...(overlays.success ? overlays.data : []).filter((ov) => ov.text?.trim()).map((ov) => ({
         kind: "text",
@@ -34780,7 +35922,7 @@ import path20 from "path";
 import { defineCommand as defineCommand110 } from "citty";
 
 // src/engine/scaffold/staticAd.ts
-import { z as z31 } from "zod";
+import { z as z33 } from "zod";
 var GEN_ASPECT_RATIOS = /* @__PURE__ */ new Set(["1:1", "4:5", "9:16", "16:9", "4:3", "3:4", "2:3", "3:2", "21:9"]);
 var DEFAULT_ASPECT_RATIO = "9:16";
 var SHEET_SUBJECT_TYPE2 = {
@@ -34792,24 +35934,24 @@ var ACTOR_SHEET_IMAGE_SIZE = "4K";
 var ADAPT_MODEL = "google/gemini-3-pro-image-preview";
 var ADAPT_IMAGE_SIZE = "2K";
 var ADAPT_GUIDANCE = "Keep the headline, logo, CTA, and hero subject fully visible in every ratio. Reproduce every text string verbatim \u2014 no dropped, added, or altered characters \u2014 and preserve the exact brand-color treatment (e.g. a black\u2192red word pivot), never flattening it.";
-var Blueprint = z31.object({
-  meta: z31.object({ estimated_aspect_ratio: z31.string().optional() }).loose().optional(),
-  text_content: z31.array(z31.object({ text: z31.string().optional() }).loose()).optional()
+var Blueprint = z33.object({
+  meta: z33.object({ estimated_aspect_ratio: z33.string().optional() }).loose().optional(),
+  text_content: z33.array(z33.object({ text: z33.string().optional() }).loose()).optional()
 }).loose();
-var ElementLocator = z31.object({
-  collection: z31.enum(["subjects", "people", "brands_logos"]),
-  index: z31.number().int().nonnegative()
+var ElementLocator = z33.object({
+  collection: z33.enum(["subjects", "people", "brands_logos"]),
+  index: z33.number().int().nonnegative()
 }).loose();
-var MainElement = z31.object({
+var MainElement = z33.object({
   // logo | product | person | animal | badge | other
-  type: z31.string(),
-  label: z31.string().optional(),
-  description: z31.string().optional(),
-  expression: z31.string().nullable().optional(),
-  reason: z31.string().optional(),
+  type: z33.string(),
+  label: z33.string().optional(),
+  description: z33.string().optional(),
+  expression: z33.string().nullable().optional(),
+  reason: z33.string().optional(),
   locator: ElementLocator.optional()
 }).loose();
-var MainElements = z31.array(MainElement);
+var MainElements = z33.array(MainElement);
 function sanitizeId2(raw, fallback) {
   const id = raw.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
   return /^[a-z]/.test(id) ? id : `${fallback}_${id}`.replace(/_+$/g, "") || fallback;
@@ -35746,8 +36888,8 @@ function parsePySceneDetectCsvCuts(csv) {
   const firstLine = csv.split(/\r?\n/, 1)[0] ?? "";
   if (!/^\s*Timecode List:/i.test(firstLine)) return [];
   const cuts = [];
-  for (const cell2 of firstLine.split(",").slice(1)) {
-    const t = timecodeToSeconds(cell2);
+  for (const cell3 of firstLine.split(",").slice(1)) {
+    const t = timecodeToSeconds(cell3);
     if (t !== null && t > 0) cuts.push(Math.round(t * 1e3) / 1e3);
   }
   return [...new Set(cuts)].sort((a, b) => a - b);