@agent-native/core 0.98.17 → 0.99.0

package/corpus/core/src/server/core-routes-plugin.ts

@@ -64,6 +64,7 @@ import {
   handleMcpOAuthAuthorizationServerMetadata,
   handleMcpOAuthProtectedResourceMetadata,
 } from "../mcp/oauth-route.js";
+import { MCP_ROUTE_PREFIXES } from "../mcp/route-paths.js";
 import { registerBuiltinNotificationChannels } from "../notifications/channels.js";
 import { createNotificationsHandler } from "../notifications/routes.js";
 import { getOrgContext } from "../org/context.js";
@@ -873,9 +874,10 @@ export interface CoreRoutesPluginOptions {
   /** Disable the /_agent-native/embed/start iframe session launcher. */
   disableEmbedRoute?: boolean;
   /**
-   * Disable the /_agent-native/mcp/connect routes (browser Connect page +
-   * CLI device-code flow that mints per-user, revocable MCP tokens) and the
-   * standard remote-MCP OAuth endpoints under /_agent-native/mcp/oauth.
+   * Disable the /mcp/connect routes (browser Connect page + CLI device-code
+   * flow that mints per-user, revocable MCP tokens) and the standard remote-MCP
+   * OAuth endpoints under /mcp/oauth. The legacy /_agent-native/mcp aliases
+   * are disabled at the same time.
    * Enabled by default — the routes are session-gated where they approve user
    * access; token endpoints are protected by single-use codes / refresh
    * tokens.
@@ -939,7 +941,7 @@ export function createCoreRoutesPlugin(
       rejectInit = reject;
     });
     trackPluginInit(nitroApp, initPromise, {
-      paths: [FRAMEWORK_ROUTE_PREFIX, "/.well-known"],
+      paths: [FRAMEWORK_ROUTE_PREFIX, "/mcp", "/.well-known"],
     });
     try {
       await awaitBootstrap(nitroApp);
@@ -3497,16 +3499,18 @@ export function createCoreRoutesPlugin(
             handleMcpOAuthAuthorizationServerMetadata(event),
           ),
         );
-        getH3App(nitroApp).use(
-          `${P}/mcp/oauth`,
-          defineEventHandler(async (event: H3Event) => {
-            const subpath = event.url?.pathname || "";
-            return handleMcpOAuth(event, subpath, {
-              appId: options.mcpConnectAppId,
-              appName: options.mcpConnectAppName ?? getAppName(),
-            });
-          }),
-        );
+        for (const mcpRoutePrefix of MCP_ROUTE_PREFIXES) {
+          getH3App(nitroApp).use(
+            `${mcpRoutePrefix}/oauth`,
+            defineEventHandler(async (event: H3Event) => {
+              const subpath = event.url?.pathname || "";
+              return handleMcpOAuth(event, subpath, {
+                appId: options.mcpConnectAppId,
+                appName: options.mcpConnectAppName ?? getAppName(),
+              });
+            }),
+          );
+        }
 
         // Frictionless external-agent connection. A logged-in user mints a
         // per-user, scoped, revocable MCP bearer token here — via the browser
@@ -3522,16 +3526,18 @@ export function createCoreRoutesPlugin(
           appName: options.mcpConnectAppName ?? getAppName(),
           serverName: options.mcpConnectServerName,
         };
-        getH3App(nitroApp).use(
-          `${P}/mcp/connect`,
-          defineEventHandler(async (event: H3Event) => {
-            // The framework strips the mount prefix from event.url.pathname,
-            // so what remains is the subpath after `/connect` (e.g. `/token`,
-            // `/device/start`, or `` for the page itself).
-            const subpath = event.url?.pathname || "";
-            return handleMcpConnect(event, subpath, mcpConnectOpts);
-          }),
-        );
+        for (const mcpRoutePrefix of MCP_ROUTE_PREFIXES) {
+          getH3App(nitroApp).use(
+            `${mcpRoutePrefix}/connect`,
+            defineEventHandler(async (event: H3Event) => {
+              // The framework strips the mount prefix from event.url.pathname,
+              // so what remains is the subpath after `/connect` (e.g. `/token`,
+              // `/device/start`, or `` for the page itself).
+              const subpath = event.url?.pathname || "";
+              return handleMcpConnect(event, subpath, mcpConnectOpts);
+            }),
+          );
+        }
       }
 
       // Cross-app SSO ("Sign in with Agent-Native") — CLIENT side. Mounted

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

@@ -50,6 +50,7 @@ import {
   setResponseStatus,
 } from "h3";
 
+import { MCP_PUBLIC_ROUTE_PREFIX } from "../mcp/route-paths.js";
 import { getConfiguredAppBasePath } from "./app-base-path.js";
 
 /**
@@ -166,12 +167,28 @@ function matchingFrameworkPrefix(
 ): string | undefined {
   if (pathname.startsWith(frameworkPrefix)) return frameworkPrefix;
 
+  if (
+    pathname === MCP_PUBLIC_ROUTE_PREFIX ||
+    pathname.startsWith(`${MCP_PUBLIC_ROUTE_PREFIX}/`)
+  ) {
+    return MCP_PUBLIC_ROUTE_PREFIX;
+  }
+
   const basePath = getConfiguredAppBasePath();
   const basePathFrameworkPrefix = `${basePath}${frameworkPrefix}`;
   if (basePath && pathname.startsWith(basePathFrameworkPrefix)) {
     return basePathFrameworkPrefix;
   }
 
+  const basePathMcpPrefix = `${basePath}${MCP_PUBLIC_ROUTE_PREFIX}`;
+  if (
+    basePath &&
+    (pathname === basePathMcpPrefix ||
+      pathname.startsWith(`${basePathMcpPrefix}/`))
+  ) {
+    return basePathMcpPrefix;
+  }
+
   return undefined;
 }
 

package/corpus/core/src/server/framework-request-handler.ts

@@ -15,6 +15,7 @@ import type { EventHandler, H3Event } from "h3";
 import { setResponseHeader, setResponseStatus } from "h3";
 
 import { getMissingDefaultPlugins } from "../deploy/route-discovery.js";
+import { MCP_PUBLIC_ROUTE_PREFIX } from "../mcp/route-paths.js";
 import { getConfiguredAppBasePath } from "./app-base-path.js";
 import { captureError } from "./capture-error.js";
 import { createCsrfMiddleware } from "./csrf.js";
@@ -48,7 +49,8 @@ function pathMatchesPrefix(reqPath: string, prefix: string): boolean {
 function supportsAppBasePathMount(path: string): boolean {
   return (
     pathMatchesPrefix(path, FRAMEWORK_PREFIX) ||
-    pathMatchesPrefix(path, WELL_KNOWN_PREFIX)
+    pathMatchesPrefix(path, WELL_KNOWN_PREFIX) ||
+    pathMatchesPrefix(path, MCP_PUBLIC_ROUTE_PREFIX)
   );
 }
 
@@ -164,6 +166,9 @@ export function getH3App(nitroApp: any): H3AppShim {
     registerMiddleware(nitroApp, WELL_KNOWN_PREFIX, readinessGate, {
       prepend: true,
     });
+    registerMiddleware(nitroApp, MCP_PUBLIC_ROUTE_PREFIX, readinessGate, {
+      prepend: true,
+    });
 
     // CSRF (see csrf.ts): registered here — synchronously, on the very
     // first `getH3App()` call for this nitroApp — rather than inside
@@ -196,7 +201,8 @@ export function getH3App(nitroApp: any): H3AppShim {
       const reqPath = event.url?.pathname ?? "";
       if (
         resolveMountMatch(reqPath, FRAMEWORK_PREFIX) ||
-        resolveMountMatch(reqPath, WELL_KNOWN_PREFIX)
+        resolveMountMatch(reqPath, WELL_KNOWN_PREFIX) ||
+        resolveMountMatch(reqPath, MCP_PUBLIC_ROUTE_PREFIX)
       ) {
         await awaitFrameworkRoutesReadyForRequest(nitroApp, reqPath);
       }

package/corpus/core/src/server/google-oauth.ts

@@ -170,6 +170,12 @@ function getConfiguredOriginAllowlist(): Set<string> {
   return out;
 }
 
+/** Return whether a candidate is one of this deployment's configured origins. */
+export function isConfiguredAppOrigin(value: string | undefined): boolean {
+  const origin = normalizeOrigin(value);
+  return !!origin && getConfiguredOriginAllowlist().has(origin);
+}
+
 function getWorkspaceCallbackOrigin(): string | undefined {
   const publicAuthOrigin = firstOriginFromEnv(EXPLICIT_PUBLIC_ORIGIN_ENV_KEYS, {
     allowLoopback: true,

package/corpus/core/src/server/http-response-telemetry.ts

@@ -2,6 +2,7 @@ import { defineEventHandler, getHeader, getMethod } from "h3";
 import type { EventHandler, H3Event } from "h3";
 
 import { getDatabaseRuntimeFingerprint } from "../db/runtime-diagnostics.js";
+import { isMcpPublicPath } from "../mcp/route-paths.js";
 import { track } from "../tracking/index.js";
 import { getAppName } from "./app-name.js";
 
@@ -74,7 +75,11 @@ function statusClass(statusCode: number): string {
 }
 
 function routeKind(pathname: string): string {
-  if (pathname === "/_agent-native" || pathname.startsWith("/_agent-native/")) {
+  if (
+    isMcpPublicPath(pathname) ||
+    pathname === "/_agent-native" ||
+    pathname.startsWith("/_agent-native/")
+  ) {
     return "framework";
   }
   if (pathname === "/api" || pathname.startsWith("/api/")) return "api";

package/corpus/core/src/server/recap-image-route.ts

@@ -5,7 +5,7 @@
  *     Auth: `Authorization: Bearer <token>` — accepts the SAME tokens the MCP /
  *     action surface accepts: a legacy `sessions` bearer (desktop/native) OR a
  *     connect-minted MCP OAuth access token (the `agent-native connect` token,
- *     audience-bound to this app's `{origin}/_agent-native/mcp` resource). A
+ *     audience-bound to this app's `{origin}/mcp` resource). A
  *     normal browser session cookie is also accepted. Rejects unauthenticated
  *     callers with 401.
  *     Body: raw `image/png` bytes, or JSON `{ "pngBase64": "..." }`. Capped at
@@ -74,13 +74,13 @@ async function resolveUploadSession(
   if (!authHeader || !bearer) return null;
 
   try {
-    const [{ getMcpOAuthResource }, { verifyAuth, resolveOrgIdFromDomain }] =
+    const [{ getMcpOAuthAudiences }, { verifyAuth, resolveOrgIdFromDomain }] =
       await Promise.all([
         import("../mcp/oauth-route.js"),
         import("../mcp/build-server.js"),
       ]);
     const result = await verifyAuth(authHeader, undefined, {
-      resourceUrl: getMcpOAuthResource(event),
+      resourceUrl: getMcpOAuthAudiences(event),
       allowDevOpen: false,
     });
     const identity = result.authed ? result.identity : undefined;

package/corpus/core/src/server/security-headers.ts

@@ -56,6 +56,10 @@ import { createHash } from "node:crypto";
 
 import { defineEventHandler, getHeader, setResponseHeader } from "h3";
 
+import {
+  isMcpProtocolPath,
+  MCP_PUBLIC_ROUTE_PREFIX,
+} from "../mcp/route-paths.js";
 import {
   isMcpEmbedCorsOrigin,
   MCP_EMBED_CORS_ALLOW_HEADERS,
@@ -101,8 +105,10 @@ function isMcpEndpointRequest(event: any): boolean {
   const pathname =
     event?.url?.pathname ??
     String(event?.node?.req?.url ?? event?.path ?? "/").split("?")[0];
+  const normalizedPathname = pathname.replace(/\/+$/, "");
   return (
-    pathname === "/_agent-native/mcp" || pathname.endsWith("/_agent-native/mcp")
+    isMcpProtocolPath(normalizedPathname) ||
+    normalizedPathname.endsWith(MCP_PUBLIC_ROUTE_PREFIX)
   );
 }
 

package/corpus/core/src/server/ssr-handler.ts

@@ -18,6 +18,7 @@ import { defineEventHandler } from "h3";
  */
 import { createRequestHandler } from "react-router";
 
+import { isMcpPublicPath } from "../mcp/route-paths.js";
 import {
   DEFAULT_SSR_CACHE_HEADERS,
   DEFAULT_SPECULATION_RULES_PATH,
@@ -318,6 +319,7 @@ function removeDocumentCsp(headers: Headers): void {
 
 function isFrameworkOrAssetPath(pathname: string): boolean {
   return (
+    isMcpPublicPath(pathname) ||
     pathname.startsWith("/.well-known/") ||
     pathname.startsWith("/_agent_native/") ||
     pathname.startsWith("/_agent-native/") ||

package/corpus/core/src/shared/cache-control.ts

@@ -1,10 +1,12 @@
-export const DEFAULT_SSR_CACHE_CONTROL = "public, max-age=0, must-revalidate";
+export const DEFAULT_PUBLIC_CACHE_CONTROL =
+  "public, max-age=600, stale-while-revalidate=604800, stale-if-error=3600";
 
-export const DEFAULT_SSR_CDN_CACHE_CONTROL =
-  "public, s-maxage=600, stale-while-revalidate=604800, stale-if-error=3600";
+export const DEFAULT_SSR_CACHE_CONTROL = DEFAULT_PUBLIC_CACHE_CONTROL;
+
+export const DEFAULT_SSR_CDN_CACHE_CONTROL = DEFAULT_SSR_CACHE_CONTROL;
 
 export const DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL =
-  "public, durable, s-maxage=600, stale-while-revalidate=604800, stale-if-error=3600";
+  DEFAULT_PUBLIC_CACHE_CONTROL;
 
 export const DEFAULT_SSR_CACHE_HEADERS = {
   "cache-control": DEFAULT_SSR_CACHE_CONTROL,

package/corpus/core/src/templates/default/.agents/skills/security/SKILL.md

@@ -147,6 +147,16 @@ export default defineEventHandler(async (event) => {
 
 - Never create unprotected routes that modify data.
 
+**Exception — the SSR HTML/`.data` catch-all is deliberately session-blind.**
+The rule above is for routes that read or mutate user data. The SSR page
+render and React Router `.data` route are different: they serve one
+impersonal, public-cacheable shell to every visitor by design, and loaders on
+that path render no user data. Do not "fix" this by adding `getSession`,
+`private`, or `no-store` to it — that regresses the CDN cache contract for the
+whole site. Data scoping lives in actions and API routes; the client gates
+private UI after the shell loads. See the `authentication` skill and
+`guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.

package/corpus/core/src/templates/workspace-core/.agents/skills/authentication/SKILL.md

@@ -36,12 +36,12 @@ Auth is powered by **Better Auth** with account-first design. Every new user cre
 
 ## Remote MCP OAuth
 
-Every app's `/_agent-native/mcp` endpoint is also a standard protected MCP
+Every app's `/mcp` endpoint is also a standard protected MCP
 resource. OAuth-capable hosts connect with the remote MCP URL only, receive a
 `WWW-Authenticate` challenge, discover `/.well-known/oauth-protected-resource`
 and `/.well-known/oauth-authorization-server`, dynamically register a public
 client, and complete authorization-code + PKCE at
-`/_agent-native/mcp/oauth/authorize` / `/_agent-native/mcp/oauth/token`.
+`/mcp/oauth/authorize` / `/mcp/oauth/token`.
 Access tokens are audience-bound to the exact MCP URL and carry user/org
 identity plus `mcp:read`, `mcp:write`, `mcp:apps`, and/or `offline_access`;
 advertising `offline_access` lets hosts such as ChatGPT retain refresh access.
@@ -137,10 +137,19 @@ Bookmarked private paths work through the client session gate: the shared shell
 ## Gating the App Shell (avoid the logged-out infinite spinner)
 
 Normal app HTML and React Router page-data responses deliberately bypass the
-server session guard. They are rendered impersonally and cached as one shared
-shell; APIs, actions, and framework data routes remain server-protected. The
-client session gate is therefore the authoritative decision point for whether
-private app UI renders.
+server session guard. They are rendered impersonally and cached as one shared,
+public, hard-cached-at-the-CDN shell; APIs, actions, and framework data routes
+remain server-protected. The client session gate is therefore the
+authoritative decision point for whether private app UI renders.
+
+**Never**, on the SSR HTML/`.data` path: set `private`, `no-store`, or
+`Vary: Cookie`; call `getSession` or read cookies in the SSR route or the
+login HTML path; or embed tokens/secrets into the rendered HTML — a
+token-bearing page still returns the same anonymous shell and resolves access
+client-side. This has regressed repeatedly (agents "fixing" it back to
+per-user SSR); it is enforced by `guard:ssr-cache-shell` and
+`ssr-handler.spec.ts` (`packages/core/src/server/ssr-handler.ts`), and reverts
+will be rejected.
 
 `AppProviders` applies `RequireSession` automatically on its private branch. It
 resolves the session on the client and redirects signed-out visitors to

package/corpus/core/src/templates/workspace-core/.agents/skills/external-agents/SKILL.md

@@ -21,12 +21,12 @@ An agent-native app is reachable by any MCP-compatible host (Claude, Claude
 Desktop, Claude Code, ChatGPT custom MCP apps, Codex, Cursor, Cowork, VS Code
 GitHub Copilot, Goose, Postman, MCPJam, and future standard clients). Keep
 setup simple: for workspace or cross-app access, add one remote MCP connector:
-`https://dispatch.agent-native.com/_agent-native/mcp`. Dispatch's Agents page
+`https://dispatch.agent-native.com/mcp`. Dispatch's Agents page
 controls whether that single connector reaches all apps or only selected apps,
 and Dispatch filters `list_apps`, `ask_app`, and `open_app` to the granted set.
 For a deliberately isolated app, add that app directly at
-`https://<app>.agent-native.com/_agent-native/mcp` or
-`https://<your-host>/_agent-native/mcp`.
+`https://<app>.agent-native.com/mcp` or
+`https://<your-host>/mcp`.
 
 OAuth-capable hosts should use the standard remote MCP OAuth flow. Claude
 connectors and Claude Code `/mcp` authentication discover the protected
@@ -68,7 +68,7 @@ the real app focused on exactly what was produced. It reuses the existing
 Use one connector for normal workspace access:
 
 ```text
-https://dispatch.agent-native.com/_agent-native/mcp
+https://dispatch.agent-native.com/mcp
 ```
 
 Then open Dispatch → Agents to choose whether the gateway exposes every app or
@@ -79,8 +79,8 @@ only selected app IDs. External agents call `list_apps` to see the granted set,
 Use a direct app URL only when you intentionally want one isolated app:
 
 ```text
-https://mail.agent-native.com/_agent-native/mcp
-https://<your-app>.agent-native.com/_agent-native/mcp
+https://mail.agent-native.com/mcp
+https://<your-app>.agent-native.com/mcp
 ```
 
 Claude / Claude Desktop: add a custom connector with the URL, click Connect,
@@ -104,7 +104,7 @@ npx @agent-native/core@latest connect https://mail.agent-native.com
 
 The command opens the app in the browser, the user clicks **Authorize**, and a
 per-user, scoped, revocable token is written to the selected client config. The
-no-CLI equivalent is `https://<app>/_agent-native/mcp/connect`, which shows
+no-CLI equivalent is `https://<app>/mcp/connect`, which shows
 the copyable MCP URL, Claude / ChatGPT / Cursor / Claude Code / Codex / Other
 steps, and static-token fallback for clients that need it.
 
@@ -130,7 +130,7 @@ that MCP URL; pass `--client` to limit which configs it searches. Pass
 Under the hood: a logged-in browser session mints an `A2A_SECRET`-signed JWT
 carrying the caller's `sub` + `org_domain` and a unique `jti`, so tool runs
 stay tenant-scoped via `runWithRequestContext`. The existing
-`/_agent-native/mcp` endpoint accepts it like any bearer — no new endpoint.
+`/mcp` endpoint accepts it like any bearer — no new endpoint.
 The same Connect page lists and revokes minted tokens by `jti`; treat them
 like personal access tokens. Nothing exposes the deployment's shared secret.
 
@@ -146,7 +146,13 @@ agent has a predictable surface without guessing per-app action names:
   "Open …" link and, with `embed: true`, an inline full-app MCP App in capable
   hosts.
 - `ask_app({ app, message })` — routes a natural-language task to that app's
-  in-app agent (delegates to the existing `ask-agent` meta-tool).
+  in-app agent (delegates to the existing `ask-agent` meta-tool). It also
+  accepts `async` and `maxWaitMs`; hosted calls wait at most 25 seconds inline
+  and return a durable `taskId` plus an `ask_app_status` poll instruction when
+  the task is still running.
+- `ask_app_status({ app, taskId })` — retrieves the current or terminal result
+  for a durable `ask_app` task. Dispatch checks the selected-app grant again
+  before polling.
 - `create_workspace_app({ name, template })` — scaffolds + boots a new app via
   the workspace path (rejects non-allow-listed templates), returns its running
   URL + deep link.
@@ -375,7 +381,7 @@ the `[mcp_servers.*]` block in `~/.codex/config.toml` for Codex,
 user `mcp.json` for GitHub Copilot / VS Code, and the Claude-Code JSON shape
 for Cowork. The entry runs `pnpm exec agent-native mcp serve --app <id>`, by
 default a **thin stdio proxy** to the running local app's
-`/_agent-native/mcp` (live registry + HMR + correct deep links stay the single
+`/mcp` (live registry + HMR + correct deep links stay the single
 source of truth; `--standalone` builds the registry in-process). Companion
 subcommands: `mcp uninstall`, `mcp status`, `mcp token [--rotate]`. You can
 also hand-write an `http` `.mcp.json` entry with a token you supply yourself —

package/corpus/core/src/templates/workspace-core/.agents/skills/performance/SKILL.md

@@ -121,7 +121,24 @@ index the growing tables first.
 - Data the UI doesn't display (export formats, alternate renderings) belongs in a
   separate on-demand action, not baked into the hot read.
 
-## 6. Big payloads and long lists
+## 6. SSR shell caching — load-bearing, do not undo
+
+Every SSR HTML page and React Router `.data` response is one impersonal,
+public shell, hard-cached at the CDN and served identically to every visitor —
+logged in or not. This is the single biggest lever on first-response latency:
+one shared cache entry serves the whole site instead of a per-user render on
+every request. Adding `private`, `no-store`, `Vary: Cookie`, a session read, or
+an auth branch to the SSR path defeats the cache for **every visitor**, not
+just one.
+
+If you're debugging a slow first response, check whether something
+re-personalized the shell before concluding the render itself is slow — the
+fix is client-side data loading after the shell paints, never per-user SSR.
+See the `authentication` skill for the full model and `guard:ssr-cache-shell`
+plus `ssr-handler.spec.ts` (`packages/core/src/server/ssr-handler.ts`) for the
+enforced contract.
+
+## 7. Big payloads and long lists
 
 - **Paginate or window** unbounded lists (messages, responses, events, activity).
   Don't load the entire history on open; load a recent window and fetch older on
@@ -144,3 +161,5 @@ index the growing tables first.
 - [ ] Client fires independent queries in parallel, not a waterfall.
 - [ ] No heavy recompute on every read; no aggressive polling of heavy endpoints.
 - [ ] Unbounded lists are paginated/windowed; large blobs aren't inlined on the hot path.
+- [ ] SSR HTML/`.data` path stays session-blind and cacheable — no `private`,
+      `no-store`, `Vary: Cookie`, or auth branch added to it.

package/corpus/core/src/templates/workspace-core/.agents/skills/security/SKILL.md

@@ -147,6 +147,16 @@ export default defineEventHandler(async (event) => {
 
 - Never create unprotected routes that modify data.
 
+**Exception — the SSR HTML/`.data` catch-all is deliberately session-blind.**
+The rule above is for routes that read or mutate user data. The SSR page
+render and React Router `.data` route are different: they serve one
+impersonal, public-cacheable shell to every visitor by design, and loaders on
+that path render no user data. Do not "fix" this by adding `getSession`,
+`private`, or `no-store` to it — that regresses the CDN cache contract for the
+whole site. Data scoping lives in actions and API routes; the client gates
+private UI after the shell loads. See the `authentication` skill and
+`guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.

package/corpus/templates/analytics/.agents/skills/security/SKILL.md

@@ -147,6 +147,16 @@ export default defineEventHandler(async (event) => {
 
 - Never create unprotected routes that modify data.
 
+**Exception — the SSR HTML/`.data` catch-all is deliberately session-blind.**
+The rule above is for routes that read or mutate user data. The SSR page
+render and React Router `.data` route are different: they serve one
+impersonal, public-cacheable shell to every visitor by design, and loaders on
+that path render no user data. Do not "fix" this by adding `getSession`,
+`private`, or `no-store` to it — that regresses the CDN cache contract for the
+whole site. Data scoping lives in actions and API routes; the client gates
+private UI after the shell loads. See the `authentication` skill and
+`guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.

package/corpus/templates/analytics/app/global.css

@@ -245,14 +245,73 @@
   transform-origin: top left;
 }
 
-/* IMPORTANT: Keep rrweb's stock SVG arrow. Only suppress its permanently
-   visible purple ::after disc, which can otherwise read as the cursor itself
-   when the arrow is small. The stock .active animation still supplies the
-   brief click halo. Do not replace the arrow with an app-colored dot. */
+/* INTENTIONAL — DO NOT REMOVE OR REPLACE WITH rrweb's STOCK CURSOR.
+   The recorded visitor cursor is a core session-replay affordance: users need
+   to see the Mac-style arrow where the visitor clicked, including on dark
+   recordings. rrweb's bundled cursor is a small black sprite that disappears
+   against those pages. This high-contrast arrow stays inside the replayer
+   wrapper and scales with the fit-to-stage transform. */
+.an-replay-stage-root .replayer-mouse {
+  position: absolute;
+  z-index: 2;
+  width: 1.125rem;
+  height: 1.5rem;
+  border-radius: 0;
+  background: transparent;
+  background-image: none;
+  box-shadow: none;
+  transform: none;
+  transition:
+    left 80ms linear,
+    top 80ms linear;
+  pointer-events: none;
+}
+
+.an-replay-stage-root .replayer-mouse::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: hsl(0 0% 100%);
+  clip-path: polygon(0 0, 0 77%, 30% 57%, 48% 100%, 68% 92%, 50% 51%, 92% 51%);
+  filter: drop-shadow(0 0 1px hsl(0 0% 0% / 0.95))
+    drop-shadow(0 1px 3px hsl(0 0% 0% / 0.35));
+}
+
 .an-replay-stage-root .replayer-mouse::after {
+  content: "";
+  position: absolute;
+  left: -0.5rem;
+  top: -0.5rem;
+  width: 1rem;
+  height: 1rem;
+  border: 2px solid hsl(217 91% 60%);
+  border-radius: 9999px;
+  background: transparent;
   opacity: 0;
 }
 
+/* rrweb toggles `.active` on mouse interactions; pulse a click ripple. */
+.an-replay-stage-root .replayer-mouse.active::after {
+  animation: an-replay-mouse-click 0.4s ease-out 1;
+}
+
+@keyframes an-replay-mouse-click {
+  0% {
+    opacity: 0.5;
+    transform: scale(1);
+  }
+  100% {
+    opacity: 0;
+    transform: scale(3.5);
+  }
+}
+
+.an-replay-stage-root .replayer-mouse-tail {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+
 .analytics-session-snippet .plan-code-surface {
   border: 0;
   border-radius: 0;

package/corpus/templates/analytics/app/pages/sessions/SessionDetailPage.tsx

@@ -986,11 +986,14 @@ function ReplayPlayer({
                 />
                 <button
                   type="button"
-                  // IMPORTANT: Keep the viewer's real OS pointer visible while
-                  // the synthetic rrweb pointer replays underneath it. Hiding
-                  // this during playback makes the page feel broken whenever
-                  // the viewer moves their mouse over the full-stage control.
-                  className="absolute inset-0 z-20 cursor-pointer rounded-[inherit] border-0 bg-transparent p-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-default"
+                  className={cn(
+                    "absolute inset-0 z-20 rounded-[inherit] border-0 bg-transparent p-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-default",
+                    // INTENTIONAL — DO NOT REMOVE `cursor-none` while playing.
+                    // The recorded cursor is the meaningful pointer here;
+                    // hiding the viewer's stationary pointer keeps the
+                    // Mac-style replay cursor easy to follow.
+                    playing ? "cursor-none" : "cursor-pointer",
+                  )}
                   disabled={disabled}
                   aria-label={
                     playing ? t("sessions.pause") : t("sessions.play")

package/corpus/templates/analytics/changelog/2026-07-13-daily-dashboard-emails-recover-more-reliably-from-serverless.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-13
+---
+
+Daily dashboard emails recover more reliably from serverless browser failures and report image errors accurately.

package/corpus/templates/analytics/changelog/2026-07-13-session-replays-keep-a-visible-mac-style-cursor-over-the-vis.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-13
+---
+
+Session replays keep a visible Mac-style cursor over the visitor's recorded actions