@agent-native/core 0.77.24 → 0.78.1

package/corpus/core/src/db/schema.ts

@@ -19,16 +19,20 @@
 import { sql } from "drizzle-orm";
 import {
   pgTable,
+  index as pgIndex,
   text as pgText,
   integer as pgInteger,
   boolean as pgBoolean,
   doublePrecision as pgDoublePrecision,
+  uniqueIndex as pgUniqueIndex,
 } from "drizzle-orm/pg-core";
 import {
   sqliteTable,
+  index as sqliteIndex,
   text as sqliteText,
   integer as sqliteInteger,
   real as sqliteReal,
+  uniqueIndex as sqliteUniqueIndex,
 } from "drizzle-orm/sqlite-core";
 
 import { getDialect } from "./client.js";
@@ -46,6 +50,14 @@ function pg(): boolean {
 export const table: typeof sqliteTable = ((...args: any[]) =>
   pg() ? (pgTable as any)(...args) : (sqliteTable as any)(...args)) as any;
 
+export const index: typeof sqliteIndex = ((...args: any[]) =>
+  pg() ? (pgIndex as any)(...args) : (sqliteIndex as any)(...args)) as any;
+
+export const uniqueIndex: typeof sqliteUniqueIndex = ((...args: any[]) =>
+  pg()
+    ? (pgUniqueIndex as any)(...args)
+    : (sqliteUniqueIndex as any)(...args)) as any;
+
 /**
  * Text column. Works identically in both dialects.
  * Supports `{ enum: [...] }` config in both.

package/corpus/core/src/deploy/build.ts

@@ -1318,6 +1318,16 @@ const SERVERLESS_FFMPEG_STATIC_ARCHES = new Set<NodeJS.Architecture>([
   "arm64",
   "x64",
 ]);
+const SERVERLESS_FUNCTION_PACKAGE_DENYLIST = new Set([
+  "@vscode/test-electron",
+  "electron",
+  "electron-builder",
+  "electron-updater",
+  "electron-vite",
+  "fsevents",
+  "node-pty",
+  "playwright",
+]);
 type ServerlessFfmpegStaticArch = "arm64" | "x64";
 
 function serverlessFfmpegStaticTargetArchFromEnv(): ServerlessFfmpegStaticArch | null {
@@ -1748,6 +1758,70 @@ function copyInstalledFfmpegStaticPackage(serverDir: string | undefined) {
   );
 }
 
+/**
+ * Nitro's file tracer can over-include optional desktop/dev packages that are
+ * present in a monorepo install but cannot run in serverless. Netlify installs
+ * the generated per-function package.json before upload; if `electron` remains
+ * there, the function can exceed Netlify's 250 MB unzipped size limit even
+ * though the server bundle never imports Electron at runtime.
+ */
+export function sanitizeServerlessFunctionPackageManifest(
+  functionDir: string | undefined,
+): void {
+  if (!functionDir || !fs.existsSync(functionDir)) return;
+
+  const packageJsonPath = path.join(functionDir, "package.json");
+  if (!fs.existsSync(packageJsonPath)) return;
+
+  let packageJson: Record<string, unknown>;
+  try {
+    packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+  } catch {
+    return;
+  }
+
+  let removed = 0;
+  const depFields = [
+    "dependencies",
+    "optionalDependencies",
+    "devDependencies",
+    "peerDependencies",
+  ];
+  for (const field of depFields) {
+    const deps = packageJson[field];
+    if (!deps || typeof deps !== "object" || Array.isArray(deps)) continue;
+    const depRecord = deps as Record<string, unknown>;
+    for (const packageName of SERVERLESS_FUNCTION_PACKAGE_DENYLIST) {
+      if (Object.prototype.hasOwnProperty.call(depRecord, packageName)) {
+        delete depRecord[packageName];
+        removed++;
+      }
+    }
+    if (Object.keys(depRecord).length === 0) {
+      delete packageJson[field];
+    }
+  }
+
+  const nodeModulesDir = path.join(functionDir, "node_modules");
+  for (const packageName of SERVERLESS_FUNCTION_PACKAGE_DENYLIST) {
+    const packageDir = path.join(nodeModulesDir, ...packageName.split("/"));
+    if (fs.existsSync(packageDir)) {
+      fs.rmSync(packageDir, { recursive: true, force: true });
+      removed++;
+    }
+  }
+
+  if (removed > 0) {
+    fs.writeFileSync(
+      packageJsonPath,
+      `${JSON.stringify(packageJson, null, 2)}\n`,
+    );
+    console.log(
+      `[deploy] Removed ${removed} desktop-only package reference(s) from ${path.relative(cwd, functionDir)}.`,
+    );
+  }
+}
+
 /**
  * Create stub directories for dangling platform-specific optional dependency
  * symlinks in the pnpm store.
@@ -2139,6 +2213,7 @@ export default bundle;
     copyInstalledLibsqlNativePackages(nitro.options.output.serverDir);
     copyInstalledResvgPackages(nitro.options.output.serverDir);
     copyInstalledFfmpegStaticPackage(nitro.options.output.serverDir);
+    sanitizeServerlessFunctionPackageManifest(nitro.options.output.serverDir);
   }
 
   // Durable background agent runs (default-OFF / opt-in; enable with a truthy

package/corpus/core/src/private-blob/index.ts

@@ -0,0 +1,18 @@
+export type {
+  PrivateBlobDeleteResult,
+  PrivateBlobHandle,
+  PrivateBlobMetadata,
+  PrivateBlobProvider,
+  PrivateBlobPutInput,
+  PrivateBlobReadResult,
+} from "./types.js";
+export {
+  deletePrivateBlob,
+  getActivePrivateBlobProvider,
+  listPrivateBlobProviders,
+  putPrivateBlob,
+  readPrivateBlob,
+  registerPrivateBlobProvider,
+  setPrivateBlobPublicUploadFallbackEnabled,
+  unregisterPrivateBlobProvider,
+} from "./registry.js";

package/corpus/core/src/private-blob/registry.ts

@@ -0,0 +1,241 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+
+import { uploadFile } from "../file-upload/index.js";
+import {
+  decryptSecretValue,
+  encryptSecretValue,
+  getSecretEncryptionKey,
+} from "../secrets/crypto.js";
+import type {
+  PrivateBlobDeleteResult,
+  PrivateBlobHandle,
+  PrivateBlobProvider,
+  PrivateBlobPutInput,
+  PrivateBlobReadResult,
+} from "./types.js";
+
+interface PrivateBlobGlobals {
+  __agentNativePrivateBlobProviders?: Map<string, PrivateBlobProvider>;
+  __agentNativePrivateBlobPublicUploadFallback?: { enabled: boolean };
+}
+
+interface EncryptedPayload {
+  iv: string;
+  tag: string;
+  ciphertext: Uint8Array;
+}
+
+interface EncryptionParams {
+  iv: string;
+  tag: string;
+}
+
+interface PublicUploadDescriptor {
+  kind: "agent-native.private-blob.public-upload";
+  version: 1;
+  url: string;
+  uploadProvider: string;
+  uploadId?: string;
+  encryption: EncryptionParams;
+  mimeType?: string;
+  metadata?: PrivateBlobHandle["metadata"];
+  size: number;
+  createdAt: string;
+}
+
+const PUBLIC_UPLOAD_HANDLE_PREFIX = "public-upload:v1:";
+const globals = globalThis as typeof globalThis & PrivateBlobGlobals;
+const providers: Map<string, PrivateBlobProvider> =
+  (globals.__agentNativePrivateBlobProviders ??= new Map());
+const publicUploadFallbackRef: { enabled: boolean } =
+  (globals.__agentNativePrivateBlobPublicUploadFallback ??= {
+    enabled: true,
+  });
+
+function toBytes(data: Uint8Array | Buffer): Uint8Array {
+  return data instanceof Uint8Array ? data : new Uint8Array(data);
+}
+
+function encryptBytes(data: Uint8Array): EncryptedPayload {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", getSecretEncryptionKey(), iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(Buffer.from(data)),
+    cipher.final(),
+  ]);
+  return {
+    iv: iv.toString("base64url"),
+    ciphertext: new Uint8Array(ciphertext),
+    tag: cipher.getAuthTag().toString("base64url"),
+  };
+}
+
+function decryptBytes(
+  params: EncryptionParams,
+  ciphertext: Uint8Array,
+): Uint8Array {
+  const decipher = createDecipheriv(
+    "aes-256-gcm",
+    getSecretEncryptionKey(),
+    Buffer.from(params.iv, "base64url"),
+  );
+  decipher.setAuthTag(Buffer.from(params.tag, "base64url"));
+  return new Uint8Array(
+    Buffer.concat([decipher.update(Buffer.from(ciphertext)), decipher.final()]),
+  );
+}
+
+function encodePublicUploadDescriptor(
+  descriptor: PublicUploadDescriptor,
+): string {
+  return `${PUBLIC_UPLOAD_HANDLE_PREFIX}${encryptSecretValue(
+    JSON.stringify(descriptor),
+  )}`;
+}
+
+function decodePublicUploadDescriptor(id: string): PublicUploadDescriptor {
+  if (!id.startsWith(PUBLIC_UPLOAD_HANDLE_PREFIX)) {
+    throw new Error(
+      "Private blob handle is not a public-upload fallback handle",
+    );
+  }
+  const raw = decryptSecretValue(id.slice(PUBLIC_UPLOAD_HANDLE_PREFIX.length));
+  const descriptor = JSON.parse(raw) as PublicUploadDescriptor;
+  if (
+    descriptor?.kind !== "agent-native.private-blob.public-upload" ||
+    descriptor.version !== 1 ||
+    typeof descriptor.url !== "string"
+  ) {
+    throw new Error("Private blob handle descriptor is invalid");
+  }
+  return descriptor;
+}
+
+function isPublicUploadFallbackHandle(handle: PrivateBlobHandle): boolean {
+  return handle.id.startsWith(PUBLIC_UPLOAD_HANDLE_PREFIX);
+}
+
+async function putViaEncryptedPublicUpload(
+  input: PrivateBlobPutInput,
+): Promise<PrivateBlobHandle | null> {
+  const bytes = toBytes(input.data);
+  const encrypted = encryptBytes(bytes);
+  const uploaded = await uploadFile({
+    data: Buffer.from(encrypted.ciphertext),
+    filename: input.filename ?? input.key ?? "private-blob.bin",
+    mimeType: "application/octet-stream",
+    ownerEmail: input.ownerEmail,
+  });
+  if (!uploaded) return null;
+
+  const descriptor: PublicUploadDescriptor = {
+    kind: "agent-native.private-blob.public-upload",
+    version: 1,
+    url: uploaded.url,
+    uploadProvider: uploaded.provider,
+    uploadId: uploaded.id,
+    encryption: { iv: encrypted.iv, tag: encrypted.tag },
+    mimeType: input.mimeType,
+    metadata: input.metadata,
+    size: bytes.byteLength,
+    createdAt: new Date().toISOString(),
+  };
+
+  return {
+    id: encodePublicUploadDescriptor(descriptor),
+    provider: `public-upload:${uploaded.provider}`,
+    opaque: true,
+    encrypted: true,
+    mimeType: input.mimeType,
+    size: bytes.byteLength,
+    createdAt: descriptor.createdAt,
+    metadata: input.metadata,
+  };
+}
+
+async function readViaEncryptedPublicUpload(
+  handle: PrivateBlobHandle,
+): Promise<PrivateBlobReadResult> {
+  const descriptor = decodePublicUploadDescriptor(handle.id);
+  const response = await fetch(descriptor.url);
+  if (!response.ok) {
+    throw new Error(
+      `Private blob public-upload read failed (${response.status}): ${response.statusText}`,
+    );
+  }
+  // The uploaded ciphertext is intentionally opaque; the descriptor carries
+  // auth tag + IV separately so the backing public URL is useless by itself.
+  const ciphertext = new Uint8Array(await response.arrayBuffer());
+  return {
+    data: decryptBytes(descriptor.encryption, ciphertext),
+    mimeType: descriptor.mimeType,
+    metadata: descriptor.metadata,
+    handle,
+  };
+}
+
+export function registerPrivateBlobProvider(
+  provider: PrivateBlobProvider,
+): void {
+  providers.set(provider.id, provider);
+}
+
+export function unregisterPrivateBlobProvider(id: string): void {
+  providers.delete(id);
+}
+
+export function listPrivateBlobProviders(): PrivateBlobProvider[] {
+  return [...providers.values()];
+}
+
+export function getActivePrivateBlobProvider(): PrivateBlobProvider | null {
+  for (const provider of providers.values()) {
+    if (provider.isConfigured()) return provider;
+  }
+  return null;
+}
+
+export function setPrivateBlobPublicUploadFallbackEnabled(
+  enabled: boolean,
+): void {
+  publicUploadFallbackRef.enabled = enabled;
+}
+
+export async function putPrivateBlob(
+  input: PrivateBlobPutInput,
+): Promise<PrivateBlobHandle | null> {
+  const provider = getActivePrivateBlobProvider();
+  if (provider) return provider.put(input);
+  if (!publicUploadFallbackRef.enabled) return null;
+  if (process.env.AGENT_NATIVE_PRIVATE_BLOB_PUBLIC_UPLOAD_FALLBACK === "0") {
+    return null;
+  }
+  return putViaEncryptedPublicUpload(input);
+}
+
+export async function readPrivateBlob(
+  handle: PrivateBlobHandle,
+): Promise<PrivateBlobReadResult> {
+  const provider = providers.get(handle.provider);
+  if (provider) return provider.read(handle);
+  if (isPublicUploadFallbackHandle(handle)) {
+    return readViaEncryptedPublicUpload(handle);
+  }
+  throw new Error(`No private blob provider registered for ${handle.provider}`);
+}
+
+export async function deletePrivateBlob(
+  handle: PrivateBlobHandle,
+): Promise<PrivateBlobDeleteResult> {
+  const provider = providers.get(handle.provider);
+  if (provider) return provider.delete(handle);
+  if (isPublicUploadFallbackHandle(handle)) {
+    return {
+      deleted: false,
+      provider: handle.provider,
+      reason:
+        "delete is not supported by the encrypted public-upload fallback provider",
+    };
+  }
+  throw new Error(`No private blob provider registered for ${handle.provider}`);
+}

package/corpus/core/src/private-blob/types.ts

@@ -0,0 +1,55 @@
+export interface PrivateBlobMetadata {
+  [key: string]: string | number | boolean | null | undefined;
+}
+
+export interface PrivateBlobPutInput {
+  /** Private blob contents. */
+  data: Uint8Array | Buffer;
+  /** Optional caller-owned key for providers that support deterministic paths. */
+  key?: string;
+  /** Original filename or logical blob name. */
+  filename?: string;
+  /** MIME type, e.g. "application/json". */
+  mimeType?: string;
+  /** Optional owner email for provider-specific scoping. */
+  ownerEmail?: string;
+  /** Low-cardinality metadata safe to store beside the blob. */
+  metadata?: PrivateBlobMetadata;
+}
+
+export interface PrivateBlobHandle {
+  /** Opaque provider handle. Consumers must not interpret this as a URL. */
+  id: string;
+  /** Provider that owns the handle. */
+  provider: string;
+  /** True for handles that intentionally do not expose fetchable URLs. */
+  opaque: true;
+  /** True when bytes are encrypted before reaching the backing store. */
+  encrypted: boolean;
+  mimeType?: string;
+  size?: number;
+  createdAt?: string;
+  metadata?: PrivateBlobMetadata;
+}
+
+export interface PrivateBlobReadResult {
+  data: Uint8Array;
+  mimeType?: string;
+  metadata?: PrivateBlobMetadata;
+  handle: PrivateBlobHandle;
+}
+
+export interface PrivateBlobDeleteResult {
+  deleted: boolean;
+  provider: string;
+  reason?: string;
+}
+
+export interface PrivateBlobProvider {
+  id: string;
+  name: string;
+  isConfigured: () => boolean;
+  put: (input: PrivateBlobPutInput) => Promise<PrivateBlobHandle>;
+  read: (handle: PrivateBlobHandle) => Promise<PrivateBlobReadResult>;
+  delete: (handle: PrivateBlobHandle) => Promise<PrivateBlobDeleteResult>;
+}

package/corpus/core/src/scripts/utils.ts

@@ -8,29 +8,57 @@ export { parseArgs, camelCaseArgs } from "./parse-args.js";
 
 /**
  * Load .env files. In an enterprise workspace (detected via
- * `agent-native.workspaceCore` in a parent package.json) this also loads
- * the workspace root's .env first, so shared keys like ANTHROPIC_API_KEY
- * flow to every app without duplication. Per-app .env values win on
- * conflict (dotenv doesn't overwrite existing process.env values).
+ * `agent-native.workspaceCore` in a parent package.json) this also loads the
+ * workspace root's .env as a fallback, so shared keys like ANTHROPIC_API_KEY
+ * flow to every app without duplication. Shell values win, then app
+ * .env.local, app .env, workspace .env.local, and workspace .env.
  */
 export function loadEnv(envPath?: string): void {
   const appEnv = envPath ?? path.join(process.cwd(), ".env");
+  const shellKeys = new Set(Object.keys(process.env));
   // App-level .env first. Dotenv won't clobber already-set process.env, so
   // values that are already present (e.g. set by the shell) still win.
   // `quiet: true` suppresses the dotenv tip line on every load (v17+).
-  dotenv.config({ path: appEnv, quiet: true });
+  loadEnvFile(appEnv);
+  loadEnvLocalOverrides(localEnvPathFor(appEnv), shellKeys);
 
   // Then workspace root, if any — but only fill in keys the app didn't
   // define. Setting `override: false` is dotenv's default.
   const workspaceRoot = findWorkspaceRoot(path.dirname(appEnv));
   if (workspaceRoot) {
+    const beforeWorkspaceKeys = new Set(Object.keys(process.env));
     const wsEnv = path.join(workspaceRoot, ".env");
     if (fs.existsSync(wsEnv) && wsEnv !== appEnv) {
-      dotenv.config({ path: wsEnv, quiet: true });
+      loadEnvFile(wsEnv);
+      loadEnvLocalOverrides(localEnvPathFor(wsEnv), beforeWorkspaceKeys);
     }
   }
 }
 
+function loadEnvFile(filePath: string): void {
+  if (fs.existsSync(filePath)) {
+    dotenv.config({ path: filePath, quiet: true });
+  }
+}
+
+function localEnvPathFor(envPath: string): string {
+  return path.basename(envPath) === ".env"
+    ? path.join(path.dirname(envPath), ".env.local")
+    : `${envPath}.local`;
+}
+
+function loadEnvLocalOverrides(
+  filePath: string,
+  protectedKeys: Set<string>,
+): void {
+  if (!fs.existsSync(filePath)) return;
+  const values = dotenv.parse(fs.readFileSync(filePath));
+  for (const [key, value] of Object.entries(values)) {
+    if (protectedKeys.has(key)) continue;
+    process.env[key] = value;
+  }
+}
+
 /**
  * Locate the nearest enterprise workspace root above `startDir`, identified
  * by the `agent-native.workspaceCore` field in its package.json.

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -6660,6 +6660,11 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             refPath?: string;
             refId?: string;
             section?: string;
+            slotKey?: string;
+            slotLabel?: string;
+            metadata?: Record<string, unknown>;
+            clearsSlots?: string[];
+            relatedReferences?: unknown[];
           }
 
           const matchesQuery = (item: MentionItemResponse) =>
@@ -6796,6 +6801,11 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                         refPath: item.refPath,
                         refId: item.refId,
                         section: provider.label,
+                        slotKey: item.slotKey,
+                        slotLabel: item.slotLabel,
+                        metadata: item.metadata,
+                        clearsSlots: item.clearsSlots,
+                        relatedReferences: item.relatedReferences,
                       })),
                     );
                   } catch (e) {

package/corpus/core/src/server/email.ts

@@ -16,6 +16,8 @@ export interface EmailAttachment {
   filename: string;
   content: string | Buffer;
   contentType?: string;
+  contentId?: string;
+  disposition?: "attachment" | "inline";
 }
 
 export interface SendEmailArgs {
@@ -76,6 +78,7 @@ export async function sendEmail(args: SendEmailArgs): Promise<void> {
             ? a.content
             : a.content.toString("base64"),
         content_type: a.contentType,
+        content_id: a.contentId,
       }));
     }
     const headers: Record<string, string> = {};
@@ -129,6 +132,8 @@ export async function sendEmail(args: SendEmailArgs): Promise<void> {
             ? Buffer.from(a.content).toString("base64")
             : a.content.toString("base64"),
         type: a.contentType,
+        disposition: a.disposition ?? (a.contentId ? "inline" : undefined),
+        content_id: a.contentId,
       }));
     }
 

package/corpus/core/src/server/index.ts

@@ -398,6 +398,7 @@ export {
   sendEmail,
   isEmailConfigured,
   getEmailProvider,
+  type EmailAttachment,
   type EmailProvider,
   type SendEmailArgs,
 } from "./email.js";

package/corpus/core/src/styles/agent-native.css

@@ -46,6 +46,7 @@
    opening animates in as reliably as closing animates out. */
 .agent-sidebar-panel[data-agent-sidebar-animation="desktop"] {
   width: 0;
+  overflow: clip;
   will-change: width;
   transition: width 260ms cubic-bezier(0.32, 0.72, 0, 1);
 }
@@ -54,6 +55,22 @@
   width: var(--agent-sidebar-width);
 }
 
+.agent-sidebar-panel[data-agent-sidebar-animation="desktop"]
+  > .agent-sidebar-panel-inner {
+  width: var(--agent-sidebar-width);
+  min-width: var(--agent-sidebar-width);
+  max-width: var(--agent-sidebar-width);
+  height: 100%;
+  transform: var(--agent-sidebar-inner-closed-transform, translateX(100%));
+  will-change: transform;
+  transition: transform 260ms cubic-bezier(0.32, 0.72, 0, 1);
+}
+
+.agent-sidebar-panel[data-agent-sidebar-animation="desktop"][data-agent-sidebar-state="open"]
+  > .agent-sidebar-panel-inner {
+  transform: translateX(0);
+}
+
 .agent-sidebar-panel[data-agent-sidebar-animation="mobile"] {
   transform: var(
     --agent-sidebar-closed-transform,
@@ -81,6 +98,11 @@
     width: 0;
   }
 
+  .agent-sidebar-panel[data-agent-sidebar-animation="desktop"][data-agent-sidebar-state="open"]
+    > .agent-sidebar-panel-inner {
+    transform: var(--agent-sidebar-inner-closed-transform, translateX(100%));
+  }
+
   .agent-sidebar-panel[data-agent-sidebar-animation="mobile"][data-agent-sidebar-state="open"] {
     transform: var(
       --agent-sidebar-closed-transform,
@@ -95,6 +117,8 @@
 
 @media (prefers-reduced-motion: reduce) {
   .agent-sidebar-panel[data-agent-sidebar-animation],
+  .agent-sidebar-panel[data-agent-sidebar-animation="desktop"]
+    > .agent-sidebar-panel-inner,
   .agent-sidebar-backdrop[data-agent-sidebar-animation] {
     transition: none;
   }

package/corpus/templates/analytics/.agents/skills/dashboard-management/SKILL.md

@@ -257,7 +257,7 @@ For a **first-party analytics** dashboard, prefer `compose-dashboard` over hand-
 - Each metric accepts an optional per-metric `window` of `'30d' | '90d' | 'all'` (only affects windowed virality/time metrics) and `title` / `chartType` / `width` overrides.
 - Returns `{ dashboardId, panelCount, createdMetrics, unknownMetrics, invalidMetrics, skippedExistingIds }` — report `panelCount` as proof-of-done.
 
-Available metric keys: `total-signups`, `signups-over-time`, `signups-by-template`, `sessions-by-app`, `sessions-over-time`, `signed-in-vs-anon`, `total-template-clicks`, `total-demo-clicks`, `total-cli-copies`, `template-interest-over-time`, `clicks-by-template`, `demo-clicks-by-template`, `cli-copies-by-template`, `cli-copies-over-time`, `pageviews-over-time`, `top-referrer-domains`, `referred-signups-30d`, `viral-signup-share-30d`, `clip-share-signups-30d`, `signups-by-referral-source`, `referred-signups-over-time`, `top-referrers`, `share-funnel-30d`, `viral-participation-rate-90d`, `viral-coefficient-90d`, `activated-referrers-90d`.
+Available metric keys: `total-signups`, `signups-over-time`, `signups-by-template`, `sessions-by-app`, `sessions-over-time`, `replay-sessions`, `replay-chunks-over-time`, `recent-replay-sessions`, `signed-in-vs-anon`, `total-template-clicks`, `total-demo-clicks`, `total-cli-copies`, `template-interest-over-time`, `clicks-by-template`, `demo-clicks-by-template`, `cli-copies-by-template`, `cli-copies-over-time`, `pageviews-over-time`, `top-referrer-domains`, `referred-signups-30d`, `viral-signup-share-30d`, `clip-share-signups-30d`, `signups-by-referral-source`, `referred-signups-over-time`, `top-referrers`, `share-funnel-30d`, `viral-participation-rate-90d`, `viral-coefficient-90d`, `activated-referrers-90d`.
 
 ```bash
 # Build a large first-party dashboard in ONE call (server generates the panels)

package/corpus/templates/analytics/.agents/skills/session-replay/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: session-replay
+description: Inspect, troubleshoot, and extend Analytics session replay recordings.
+scope: dev
+---
+
+# Session Replay
+
+Use this skill when working on `/sessions`, replay ingest, replay storage, or
+agent answers about browser recordings in the Analytics template.
+
+## Source Of Truth
+
+- Replay ingest writes `session_recordings` and `session_replay_chunks`.
+- The UI and agent must use `list-session-recordings`,
+  `get-session-replay-summary`, and `get-session-replay-events`.
+- `/sessions/:recordingId` is keyed by `session_recordings.id`, not
+  `analytics_events.session_id`.
+- Do not add actions that synthesize "sessions" from `analytics_events`.
+  Events can be linked beside a recording through `session_id`, but they are not
+  playable replay rows by themselves.
+
+## Storage And Access
+
+- Never expose object-storage URLs or raw `session_replay_chunks` rows to the
+  browser or agent.
+- Playback bytes must go through scoped server helpers that check
+  `session-recording` access before reading private blob refs.
+- SQL inline chunks are a local/dev fallback only; production should use
+  private or encrypted blob storage.
+
+## Capture Defaults
+
+- Replay is off unless enabled by config/env.
+- Consumers can enable replay directly with
+  `configureTracking({ key, endpoint, sessionReplay: { enabled: true } })`.
+- Agent Native templates already call `configureTracking()` in their roots;
+  hosted template deployments can usually enable replay with Vite/Netlify env
+  vars on the recorded site.
+- Inputs are masked by default. Page text is visible unless marked with
+  `.an-mask` or `data-an-mask`.
+- Use `.an-block`, `.an-ignore`, `data-an-block`, or `data-an-ignore` for
+  sensitive zones that should not be captured.