@agent-native/core-corpus 0.221.0 → 0.222.0-nightly-20261028092719

package/corpus/README.md

@@ -32,4 +32,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core-corpus/corpu
 
 ## Generated Counts
 
-- template files: 14961
+- template files: 15033

package/corpus/templates/analytics/.agents/skills/first-touch-radar/SKILL.md

@@ -10,8 +10,10 @@ scope: dev
 
 1. Run `pnpm --filter analytics radar:watch --window daily` and read both the
    JSON and Markdown under `.tmp/first-touch-radar/runs/`.
-2. Treat exit 0 as clear, exit 1 as one or more fired checks, and exit 2 as
-   incomplete evidence. Never turn a missing source or failed query into zero.
+2. Treat exit 0 as clear, exit 1 as a fired, unavailable, or insufficient
+   check needing attention, and exit 2 as a run that could not complete. Keep
+   unavailable and insufficient metrics explicit; never turn missing evidence
+   into zero or a pass.
 3. On a fire, run `pnpm --filter analytics radar:triage` and inspect the
    outcome-ranked sessions. Use `metric-watch` and `replay-triage` for details.
 4. For a weekly review, run `pnpm --filter analytics radar:report --week
@@ -24,18 +26,21 @@ scope: dev
    report-wide cap, and treat a reached cap as incomplete evidence.
 5. Run `feedback-ingest` for Slack themes. Searches are read-only and begin at
    the saved watermark.
-6. Send one Telegram to Steve only when a check fired or the weekly report is
-   ready. Include counts and the private run-file path. Send nothing on a quiet
-   day. Never send Slack or email.
-7. Keep recipient emails and prompt text out of logs, reports, Telegram, and
-   commits. The campaign check reads its mode-0600 recipient file in memory and
-   emits aggregate counts only. With a PostgreSQL sink, recipient identifiers
-   are parameters to the read-only query and caching is disabled. A BigQuery
-   sink cannot run campaign follow-up until a keyed recipient matching
-   function is configured; report it as incomplete rather than treating it as
-   zero. Unknown signup campaign labels are grouped as `other`. Anonymous
-   landings cannot be assigned to a recipient; do not interpret identified
-   counts as a complete click total.
+6. Send one Telegram to Steve only when a check fired, is unavailable or is
+   insufficient, or the weekly report is ready. Include counts and the private
+   run-file path. Send nothing on a quiet day. Never send Slack or email.
+7. Keep recipient emails, HMAC keys, and prompt text out of logs, reports,
+   Telegram, and commits. The campaign check reads its mode-0600 recipient file
+   in memory, binds keyed email digests as query parameters, disables local and
+   BigQuery result caching, and emits aggregate counts only. BigQuery matching
+   requires `ANALYTICS_RADAR_CAMPAIGN_HMAC_KEY` and a configured
+   `ANALYTICS_RADAR_CAMPAIGN_HMAC_FUNCTION` backed by the same secret server-side.
+   The function accepts a normalized email and returns lowercase hex
+   `HMAC_SHA256`; keep its key in Secret Manager and never pass the key to
+   BigQuery. When either setting is missing, keep the campaign check
+   unavailable. Unknown signup campaign labels are grouped as `other`.
+   Anonymous landings cannot be assigned to a recipient; do not interpret
+   identified counts as a complete click total.
 8. This radar changes scripts and skills only. Do not make user-visible UI
    changes. If UI work becomes necessary, stop that scope and request Steve's
    screenshot approval before implementing it.

package/corpus/templates/analytics/.agents/skills/metric-watch/SKILL.md

@@ -11,10 +11,13 @@ scope: dev
 - Run `pnpm --filter analytics radar:watch --window daily`; use `--window
   hourly` for provisioning and environment-key checks.
 - Read the check status, numerator, denominator, seven-day comparison, and
-  coverage. `insufficient` is not a pass, and `unavailable` means the run exits
-  2.
+  coverage. `insufficient` is not a pass. `unavailable` and `insufficient`
+  remain explicit and make a completed watch exit 1; exit 2 means the run could
+  not complete.
 - Compare daily thresholds with the incident window and an ordinary week before
   changing them. Record both windows and the observed counts in the PR or report.
+- Use `pnpm --filter analytics radar:backtest` to compare the Oct 9–23 incident
+  window with the Oct 2–8 clean week.
 - Action success uses a weighted `action.response` rate. Keep its app-specific
   threshold below the quiet-week distribution; do not copy the 95% starting
   value without a backtest.

package/corpus/templates/analytics/.agents/skills/onboarding-journeys/SKILL.md

@@ -18,7 +18,8 @@ The pipeline runs without a UI. Codex does all four steps from the terminal:
 2. Run the capture CLI from the agent-native checkout:
    `pnpm --filter analytics journey:capture --tree tree.json --out ./frames`
    (`--per-node 2 --concurrency 3`, `--min-aspect` / `--max-aspect`, `--dry-run`
-   to print the plan, `--upload` for private `attachmentRef`s).
+   to print the plan, `--upload` for private `attachmentRef`s, or
+   `--upload --upload-target cdn` for standard Builder CDN URLs).
 3. Call Design's `create-journey-canvas` with
    `{ title, tree, frames: [{ nodeKey, exampleIndex, imageUrl?, attachmentRef?, width, height, capturedAt }], designId? }`
    -> `{ designId, url, nodeCount, frameCount }`. Build `frames` from
@@ -315,12 +316,14 @@ extraction time. Each snapshot also says whether its frame capture or upload
 succeeded and includes the failure reason when it did not. This is visible
 user-role text at the seek, not proof of an exact source event or attempt-ID
 relationship. Unsupported transform, mask, or rounded clipping geometry fails
-the extraction explicitly. It is never uploaded, including when `--upload` stores PNGs
-through the private attachment action.
+the extraction explicitly. The prompt sidecar itself is never uploaded; PNG
+screenshots can use the private attachment action or the explicitly selected
+`cdn.builder.io` upload target.
 
 Keep recorded URLs and CSS intact for rrweb playback; network controls belong
 at the capture boundary. `--upload` stores PNGs through the private upload
-action, which checks recording access again. Design's own sandboxed template
+action by default; `--upload-target cdn` uses `upload-image` and accepts only
+HTTPS `cdn.builder.io` URLs. Design's own sandboxed template
 previews opt into the cooperative iframe recorder, so their child DOM can be
 replayed without granting the parent access to the preview document or
 credentials.
@@ -328,3 +331,18 @@ credentials.
 Viewport comes from the recording's first rrweb Meta event, stored by replay
 ingest in `session_recordings.metadata.viewport` (`first` and `last`). Older
 recordings have none.
+
+## Weekly snapshot CLI
+
+Use the cached weekly pipeline when generating or refreshing app storyboards:
+
+```bash
+pnpm --filter analytics journey:snapshot --week 2026-10-19 --apps clips,design,slides
+pnpm --filter analytics journey:snapshot --week 2026-10-19 --apps design --experiment first_run_builder_credits
+```
+
+`--week` is a closed UTC Monday week. The query starts the previous day to include sessions already underway. Without `--week`, the CLI selects the last full week. It runs the pinned cost preflight and reads one tree per missing app/week/cohort from deployed Analytics; complete trees are cached by app, dates, preset, app URL, and authenticated principal. `--dry-run` prints the request without network access. `--refresh` bypasses existing tree, screenshot, and Design caches and should be used only for an intentional refresh.
+
+The output lives under `.tmp/onboarding-journey-snapshots/runs/<week>/`: each app with captured session frames has a Design canvas, and each app has a per-app tree cache and screenshot manifests; the shared `summary.md` includes the cohort trees. Each canvas has a 36 screenshot-backed frame ceiling allocated across its cohort bands. Multi-band canvases place independent trees side by side and keep each band's own root denominator. Same-app cohort trees use `app::cohort::step` node keys so the source app and band denominator stay distinct. Canvas cache keys include the experiment and cohort layout so different runs cannot overwrite one another. The optional experiment accepts `first_run_builder_credits` and `first_run_builder_credits_v2`; control and credits share one canvas, and `summary.md` reports per-arm forks and matching-step week-over-week changes from the full Analytics trees, including cohorts with zero screenshot frames. The canvas contains only screenshot-backed cohorts. Clips first output is `recording_ready`.
+
+Design cohorts split web, `/mcp/oauth`, and unknown signup paths. Sessionless MCP OAuth signup events appear as a separate event-grain cohort in `summary.md`, with a week-over-week event-count delta; they have no web replay and must not be represented as screenshot steps. Captured PNGs use `journey:capture --upload-target cdn`; the CLI verifies each result is an HTTPS `cdn.builder.io` URL before passing it to Design. Capture failures remain explicit in the run summary, and the pipeline does not create screenshotless cards.

package/corpus/templates/analytics/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","analytics-alert-jobs","analytics-rollup-backfill-jobs","auth","collab","config","content-metrics-collection-jobs","core-routes","creative-context","dashboard-report-jobs","db","feature-flags","labs","onboarding","otel","session-replay-retention-jobs","transactional-emails","uptime-monitor-jobs"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

package/corpus/templates/analytics/actions/get-onboarding-journey.ts

@@ -14,6 +14,7 @@ import {
   DEFAULT_ONBOARDING_EVENT_ROW_BUDGET,
   getOnboardingJourney,
   MAX_ONBOARDING_EVENT_ROW_BUDGET,
+  ONBOARDING_JOURNEY_EXPERIMENT_IDS,
   ONBOARDING_EVENTS_DEFAULT_MAX_TOTAL_BYTES_BILLED,
   ONBOARDING_EVENTS_MAX_BYTES_BILLED,
   ONBOARDING_EVENTS_MAX_TOTAL_BYTES_BILLED,
@@ -192,10 +193,10 @@ export default defineAction({
           "Leave out examples whose viewport was not recorded or cannot be read. Without it they are kept with viewport null and a viewportReason.",
         ),
       experimentId: z
-        .literal("first_run_builder_credits")
+        .enum(ONBOARDING_JOURNEY_EXPERIMENT_IDS)
         .optional()
         .describe(
-          "Return session trees for the control and credits arms from one event read. Sessions with conflicting or missing assignment properties remain outside both arms.",
+          "Experiment ID to match exactly against each exposure event's experiment_id: first_run_builder_credits or first_run_builder_credits_v2. Returns control and credits session trees from one event read; events for other IDs are not included. Sessions with conflicting or missing assignments remain outside both arms.",
         ),
       splitDesignFirstTouch: z
         .boolean()

package/corpus/templates/analytics/actions/open-traffic-dashboard.ts

@@ -15,6 +15,7 @@ function trafficDashboardDeepLink(): string {
 }
 
 export default defineAction({
+  mcpTool: true,
   description:
     "Open the first-party traffic dashboard in the real Analytics app. Use this directly when the user asks to see their traffic dashboard, site traffic, app traffic, or first-party analytics dashboard inline in ChatGPT or Claude. Do not call view-screen, ask_app, or broad resource discovery first for this known dashboard.",
   schema: z.object({}),

package/corpus/templates/analytics/changelog/2026-10-22-outside-assistants-can-open-the-traffic-dashboard-inside-the.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-10-22
+---
+
+Outside assistants can open the Traffic dashboard in Analytics.

package/corpus/templates/analytics/package.json

@@ -16,9 +16,13 @@
     "journey:capture": "tsx scripts/journey-capture.ts",
     "radar:query": "tsx scripts/radar/query.ts",
     "radar:watch": "tsx scripts/radar/watch.ts",
+    "radar:live-watch": "tsx scripts/first-touch-radar-live.ts watch",
     "radar:triage": "tsx scripts/radar/triage.ts",
     "radar:ab": "tsx scripts/radar/ab.ts",
+    "radar:live-ab": "tsx scripts/first-touch-radar-live.ts ab",
     "radar:report": "tsx scripts/radar/report.ts",
+    "radar:live-report": "tsx scripts/first-touch-radar-live.ts report",
+    "radar:backtest": "tsx scripts/first-touch-radar-live.ts backtest",
     "journey:snapshot": "tsx scripts/journey-snapshot.ts",
     "source-index": "tsx scripts/build-source-index.ts",
     "backfill:first-party-bigquery": "tsx scripts/first-party-analytics-bigquery-backfill.ts",

package/corpus/templates/analytics/scripts/first-touch-radar-live.ts

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  runAbReadout,
+  formatAbMarkdown,
+  parseAbReadoutArgs,
+} from "./radar/ab.ts";
+import {
+  formatRadarBacktest,
+  parseRadarBacktestArgs,
+  runRadarBacktest,
+} from "./radar/backtest.ts";
+import { liveDatabaseUrlFromEnv } from "./radar/live.ts";
+import {
+  REPO_ROOT,
+  RadarQueryError,
+  configureRadarRuntimeEnvironment,
+  closeRadarQueries,
+  radarRunCliExitCode,
+} from "./radar/query.ts";
+import {
+  buildWeeklyReport,
+  formatWeeklyMarkdown,
+  parseReportArgs,
+  writeWeeklyReport,
+} from "./radar/report.ts";
+import { parseWatchArgs, runWatch, writeWatchRun } from "./radar/watch.ts";
+
+function loadLiveDatabaseUrl(): void {
+  const configuredFile = process.env.ANALYTICS_RADAR_ENV_FILE;
+  const envFile = path.resolve(
+    REPO_ROOT,
+    configuredFile ?? "templates/analytics/.env",
+  );
+  let contents: string;
+  try {
+    contents = fs.readFileSync(envFile, "utf8");
+  } catch {
+    throw new RadarQueryError(
+      "Live radar environment file could not be read.",
+      2,
+    );
+  }
+  configureRadarRuntimeEnvironment({
+    selectedFile: envFile,
+    contents,
+    databaseUrl: liveDatabaseUrlFromEnv(contents),
+  });
+}
+
+async function main(): Promise<void> {
+  try {
+    const [command, ...args] = process.argv.slice(2);
+    if (!command || !["watch", "report", "ab", "backtest"].includes(command)) {
+      throw new RadarQueryError(
+        "Usage: radar:live-watch [watch options], radar:live-report [report options], radar:live-ab [A/B options], or radar:backtest [--max-total-gb N].",
+        2,
+      );
+    }
+    loadLiveDatabaseUrl();
+
+    if (command === "watch") {
+      const run = await runWatch(parseWatchArgs(args));
+      const paths = await writeWatchRun(run);
+      console.log(JSON.stringify({ ...paths, exitCode: run.exitCode }));
+      process.exitCode = run.exitCode;
+    } else if (command === "report") {
+      const { week, skipJourneySnapshot, maxTotalGb, freshBigQuery } =
+        parseReportArgs(args);
+      if (!week) {
+        throw new RadarQueryError(
+          "Usage: radar:live-report --week YYYY-MM-DD [--max-total-gb N]",
+          2,
+        );
+      }
+      const report = await buildWeeklyReport(week, {
+        skipJourneySnapshot,
+        maxTotalGb,
+        freshBigQuery,
+      });
+      const paths = await writeWeeklyReport(report);
+      console.log(formatWeeklyMarkdown(report));
+      console.log(JSON.stringify({ ...paths, exitCode: report.exitCode }));
+      process.exitCode = report.exitCode;
+    } else if (command === "ab") {
+      const result = await runAbReadout(parseAbReadoutArgs(args));
+      console.log(formatAbMarkdown(result));
+      console.log(JSON.stringify(result));
+    } else {
+      const result = await runRadarBacktest(parseRadarBacktestArgs(args));
+      console.log(formatRadarBacktest(result));
+    }
+  } catch (error) {
+    console.error(
+      error instanceof Error ? error.message : "Live radar could not run.",
+    );
+    process.exitCode = radarRunCliExitCode(error);
+  } finally {
+    await closeRadarQueries();
+  }
+}
+
+if (
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  await main();
+}

package/corpus/templates/analytics/scripts/journey-snapshot-plan.ts

@@ -14,8 +14,8 @@ export const SNAPSHOT_PRESET = Object.freeze({
   maxTotalBytesBilled: 275_000_000_000,
   minWidth: 1100,
   maxWidth: 1920,
-  minAspect: 1.25,
-  maxAspect: 1.8,
+  minAspect: 1.2,
+  maxAspect: 2.1,
   requireKnownViewport: true,
   recency: "newest" as const,
   settleMs: 300,
@@ -32,6 +32,7 @@ export interface SnapshotExample {
 
 export interface SnapshotNode {
   key: string;
+  cohortKey?: string;
   label: string;
   parentKey: string | null;
   depth: number;
@@ -47,7 +48,9 @@ export interface SnapshotNode {
 export interface SnapshotTree {
   window: { from: string; to: string };
   app: string;
+  populationGrain?: "sessions" | "signup_events";
   rootN: number;
+  appRootN?: Record<string, number>;
   coverage: {
     sessionsWithEvents: number;
     sessionsWithReplay: number | null;
@@ -60,12 +63,61 @@ export interface SnapshotTree {
   [key: string]: unknown;
 }
 
+export function snapshotPopulationUnit(
+  tree: Pick<SnapshotTree, "populationGrain">,
+): "sessions" | "signup events" {
+  return tree.populationGrain === "signup_events"
+    ? "signup events"
+    : "sessions";
+}
+
 export interface SnapshotBand {
   key: string;
   tree: SnapshotTree;
 }
 
-function arrayItemAt<T>(items: readonly T[], index: number): T | undefined {
+export interface SnapshotSummaryBand extends SnapshotBand {
+  label: string;
+  previousTree?: SnapshotTree;
+}
+
+export function snapshotSummaryBands(
+  bands: readonly (SnapshotBand & { label: string })[],
+  previousTrees: ReadonlyMap<string, SnapshotTree>,
+): SnapshotSummaryBand[] {
+  return bands.map(({ key, label, tree }) => {
+    const previousTree = previousTrees.get(key);
+    return {
+      key,
+      label,
+      tree,
+      ...(previousTree ? { previousTree } : {}),
+    };
+  });
+}
+
+export function snapshotCanvasTitle(input: {
+  app: string;
+  week: string;
+  experimentId?: string;
+  singleBand?: Pick<SnapshotSummaryBand, "key" | "label">;
+  hasFirstTouchBands: boolean;
+}): string {
+  const suffixes = [
+    ...(input.experimentId ? [`Experiment ${input.experimentId}`] : []),
+    ...(input.singleBand && input.singleBand.key !== input.app
+      ? [input.singleBand.label]
+      : input.hasFirstTouchBands
+        ? ["first-touch cohorts"]
+        : []),
+  ];
+  return `Onboarding snapshot · ${input.app} · ${input.week}${suffixes.length ? ` · ${suffixes.join(" · ")}` : ""}`;
+}
+
+export function arrayItemAt<T>(
+  items: readonly T[],
+  index: number,
+): T | undefined {
   return items.slice(index, index + 1)[0];
 }
 
@@ -95,6 +147,12 @@ export function validateSnapshotCostEstimate(
   return estimatedBytes as number;
 }
 
+export function isBuilderCdnUrl(value: unknown): value is string {
+  if (typeof value !== "string" || !URL.canParse(value)) return false;
+  const url = new URL(value);
+  return url.protocol === "https:" && url.hostname === "cdn.builder.io";
+}
+
 export function defaultSnapshotWeek(now = new Date()): string {
   if (!Number.isFinite(now.valueOf())) {
     throw new Error("The current date must be valid.");
@@ -173,9 +231,21 @@ export function snapshotCanvasCacheKey(input: {
   designUrl: string;
   designScopeHash: string;
   analyticsScopeHash: string;
+  layout: {
+    experimentId: string | null;
+    cohortKeys: readonly string[];
+  };
 }): string {
   return createHash("sha256")
-    .update(JSON.stringify(input))
+    .update(
+      JSON.stringify({
+        ...input,
+        layout: {
+          ...input.layout,
+          cohortKeys: [...input.layout.cohortKeys].sort(),
+        },
+      }),
+    )
     .digest("hex")
     .slice(0, 20);
 }
@@ -363,6 +433,80 @@ export function selectCaptureTree<T extends SnapshotTree>(
   };
 }
 
+export function combineSnapshotBands(
+  bands: readonly SnapshotBand[],
+  sourceApp?: string,
+): SnapshotTree {
+  const first = arrayItemAt(bands, 0);
+  if (bands.length < 2 || !first) {
+    throw new Error(
+      "At least two cohorts are required for a side-by-side tree.",
+    );
+  }
+  if (sourceApp !== undefined && !/^[a-z][a-z0-9-]{0,127}$/.test(sourceApp)) {
+    throw new Error(
+      `Invalid source app for side-by-side cohorts: ${sourceApp}`,
+    );
+  }
+  const appRootN: Record<string, number> = {};
+  const nodes: SnapshotNode[] = [];
+  const nodeKeys = new Set<string>();
+
+  for (const band of bands) {
+    if (!/^[a-z][a-z0-9-]{0,127}$/.test(band.key)) {
+      throw new Error(`Invalid side-by-side cohort key: ${band.key}`);
+    }
+    if (
+      band.tree.window.from !== first.tree.window.from ||
+      band.tree.window.to !== first.tree.window.to
+    ) {
+      throw new Error("Side-by-side journey cohorts must use the same window.");
+    }
+    if (!Number.isSafeInteger(band.tree.rootN) || band.tree.rootN < 1) {
+      throw new Error(`Cohort ${band.key} needs a positive root denominator.`);
+    }
+    const rootKey = sourceApp ? `${sourceApp}::${band.key}` : band.key;
+    if (Object.prototype.hasOwnProperty.call(appRootN, rootKey)) {
+      throw new Error(`Duplicate side-by-side cohort key: ${rootKey}`);
+    }
+    appRootN[rootKey] = band.tree.rootN;
+    const prefix = sourceApp ? `${sourceApp}::${band.key}` : band.key;
+    for (const node of band.tree.nodes) {
+      const key = `${prefix}::${node.key}`;
+      if (key.length > 2048 || nodeKeys.has(key)) {
+        throw new Error(`Side-by-side journey node key is invalid: ${key}`);
+      }
+      nodeKeys.add(key);
+      nodes.push({
+        ...node,
+        key,
+        ...(sourceApp ? { cohortKey: band.key } : {}),
+        parentKey: node.parentKey ? `${prefix}::${node.parentKey}` : null,
+      });
+    }
+  }
+
+  const sessionsWithReplay = bands.reduce<number | null>((total, band) => {
+    const count = band.tree.coverage.sessionsWithReplay;
+    return total === null || count === null ? null : total + count;
+  }, 0);
+  return {
+    window: first.tree.window,
+    app: "all",
+    rootN: bands.reduce((total, band) => total + band.tree.rootN, 0),
+    appRootN,
+    coverage: {
+      sessionsWithEvents: bands.reduce(
+        (total, band) => total + band.tree.coverage.sessionsWithEvents,
+        0,
+      ),
+      sessionsWithReplay,
+      truncated: bands.some((band) => band.tree.coverage.truncated),
+    },
+    nodes,
+  };
+}
+
 export function allocateFrameBudgets(
   bands: readonly SnapshotBand[],
   maxFrames = SNAPSHOT_MAX_FRAMES,