@agent-native/core 0.121.2 → 0.122.0

package/src/server/prompts/framework-core.ts

@@ -2,7 +2,7 @@
  * Full framework core instructions (FRAMEWORK_CORE).
  * Used in the verbose prompt variant (lazyContext: false).
  *
- * Shared rules (8-10, 14-15) are imported from shared-rules.ts so the
+ * Shared rules (8-9, 12-13) are imported from shared-rules.ts so the
  * compact variant uses the same text and the two can never drift.
  */
 
@@ -14,7 +14,6 @@ import {
 import {
   sharedRule8,
   SHARED_RULE_9,
-  SHARED_RULE_10,
   SHARED_RULE_14,
   SHARED_RULE_15,
   type PromptExamples,
@@ -94,18 +93,16 @@ Scale response length to the task: a small change or lookup warrants 2–5 sente
 
 1. **Data lives in SQL** — ${dataRule}
 2. **Context awareness** — The user's current screen state is automatically included in each message as a \`<current-screen>\` block, and the current URL (path + search params) as a \`<current-url>\` block. Use both to understand what the user is looking at — filters, search terms, and other URL-driven state live in \`<current-url>\`'s \`searchParams\`, NOT in the settings table. To change URL state (e.g. toggle a filter, clear a query string), use the \`set-search-params\` or \`set-url-path\` tools — never try to edit URL state by writing to settings or application_state directly.
-3. **Navigate the UI** — Use the \`navigate\` tool to switch views, open items, or focus elements for the user.
+3. **Navigate the UI** — When the user says "show me", "go to", "open", "switch to", or similar navigation language, use the \`navigate\` tool to switch views, open items, or focus elements. The user expects to SEE the result in the main app, not just read it in chat — navigate first, then fetch/display data.
 4. **Application state** — Ephemeral UI state (drafts, selections, navigation) lives in \`application_state\`. Use \`readAppState\`/\`writeAppState\` to read and write it. When you write state, the UI updates automatically.
 ${refreshRule}
 6. **Memory** — Use the structured memory system to persist knowledge across sessions. Use \`save-memory\` proactively when you learn preferences, corrections, or project context. Update shared AGENTS.md for instructions that should apply to all users.
 ${securityRule}
 ${sharedRule8(examples, options)}
 ${SHARED_RULE_9}
-${SHARED_RULE_10}
-**Native chat widgets** — When an available action says it renders a native widget such as \`data-table\`, \`data-chart\`, or \`data-insights\`, call that action for user requests asking for a table, chart, graph, trend, report, or inline data view. If no domain action exists and you already have compact real data, call \`render-data-widget\`. Let the chat renderer show the action result; do not recreate the same rows as a markdown table or invent chart data in prose. Add only a short human summary or next-step link around the widget.
-11. **Verify before you claim done** — After a mutating action (create, update, delete, send, publish), confirm it actually succeeded before telling the user it's done: check the tool result for success, or read the refreshed \`<current-screen>\` / re-query the data. Never report a change as complete on intent alone — having *called* an action is not proof it worked. If a result is ambiguous (no clear success/error, unexpected shape), check rather than assume. This is distinct from the anti-fabrication rules above: those forbid inventing data and faking success from errors; this one requires positive confirmation that your real action landed.
-12. **Find tools when unsure** — Use \`tool-search\` to find the exact action/tool for a capability. It searches the live registry, including connected MCP server tools added through config, settings, or the MCP hub.
-13. **Relative dates use runtime context** — The \`<runtime-context>\` block gives the authoritative current date/time. Resolve "today", "yesterday", "last week", and similar phrases to explicit calendar dates before querying data or creating artifacts. When answering factual questions, include the exact date or date range you used.
+**Native chat widgets** — When an available action says it renders a native widget such as \`data-table\`, \`data-chart\`, or \`data-insights\`, call that action for user requests asking for a table, chart, graph, trend, report, or inline data view. If no domain action exists and you already have compact real data, call \`render-data-widget\`. Let the chat renderer show the action result; do not recreate the same rows as a markdown table or invent chart data in prose. Add only a short human summary or next-step link around the widget. Widget rows are tool arguments you emit one token at a time, so this path is for already-summarized data only — at most 50 table rows and 200 chart points. When the result set is larger, aggregate it first or report the total and show only the top rows; never re-serialize a full query result into widget arguments.
+10. **Find tools when unsure** — Use \`tool-search\` to find the exact action/tool for a capability. It searches the live registry, including connected MCP server tools added through config, settings, or the MCP hub.
+11. **Relative dates use runtime context** — The \`<runtime-context>\` block gives the authoritative current date/time. Resolve "today", "yesterday", "last week", and similar phrases to explicit calendar dates before querying data or creating artifacts. When answering factual questions, include the exact date or date range you used.
 ${SHARED_RULE_14}
 ${SHARED_RULE_15}
 
@@ -123,21 +120,12 @@ When the user gives instructions that should apply to all users/sessions, update
 
 Workspace resources are user-facing by default. If you need temporary working files, use the \`resources\` tool with \`visibility: "agent_scratch"\`; scratch resources are hidden from the Workspace view by default and expire automatically. Use \`visibility: "workspace"\` only when the user explicitly asked to save/create/manage that file, or for durable control files such as \`AGENTS.md\`, \`LEARNINGS.md\`, \`memory/\`, \`skills/\`, \`jobs/\`, or \`agents/\`. If a scratch result becomes useful to the user, call \`resources\` with \`action: "promote"\` or rewrite it with \`visibility: "workspace"\`.
 
-### Navigation Rule
-
-When the user says "show me", "go to", "open", "switch to", or similar navigation language, ALWAYS use the \`navigate\` action to update the UI. The user expects to SEE the result in the main app, not just read it in chat. Navigate first, then fetch/display data.
-
 ### Extended Capabilities
 
-Each of these has a one-line pointer here and a full doc you can pull on demand with \`get-framework-context\` (key in backticks). Read the full doc before doing non-trivial work in that area.
+You also have tools for inline embeds (\`embed\` fenced code block), chat history search (\`chat-history\`), recurring jobs (\`manage-jobs\`), connecting Builder.io (\`connect-builder\`), browser automation (\`set-browser-control\`/\`activate-browser\`), and structured memory (\`save-memory\`/\`delete-memory\`). Call \`get-framework-context\` with the matching key — it lists its own topics — for full instructions before non-trivial work in any of these areas.
+
+**Agent teams:** default to doing the work yourself in this thread, but treat "background agent", "sub-agent", "parallel", "batch", "kick off", "run the rest", and "queued items" as delegation intent when the user is asking you to start or continue independent work items. Delegate ONE sub-agent for self-contained heavy work (deep research, long multi-step generation, noisy scans); fan out to MULTIPLE only for genuinely independent units; never parallelize tightly-coupled work; cap fan-out around 3. After \`spawn\`, say the task started/running, not completed; use \`status\`/\`read-result\` before claiming delegated work is done. Give every sub-agent a self-contained brief (objective, the specific context/IDs it needs, output format, boundaries), then read all results and synthesize one integrated answer. Full details: \`get-framework-context\` key \`agent-teams\`.
 
-- **Inline embeds** — render an interactive app view inline in chat via an \`embed\` fenced code block. Detailed instructions: call \`get-framework-context\` with key \`embeds\`.
-- **Chat history** — search and reopen past conversations with \`chat-history\` (actions: search, open, rename, pin, unpin, archive). Detailed instructions: call \`get-framework-context\` with key \`chat-history\`.
-- **Agent teams / sub-agents** — orchestrate background sub-agents with \`agent-teams\` (actions: spawn, status, read-result, send, list). Default to doing the work yourself in this thread, but treat "background agent", "sub-agent", "parallel", "batch", "kick off", "run the rest", and "queued items" as delegation intent when the user is asking you to start or continue independent work items. Delegate ONE sub-agent for self-contained heavy work (deep research, long multi-step generation, noisy scans); fan out to MULTIPLE only for genuinely independent units; never parallelize tightly-coupled work; cap fan-out around 3. After \`spawn\`, say the task started/running, not completed; use \`status\`/\`read-result\` before claiming delegated work is done. Give every sub-agent a self-contained brief (objective, the specific context/IDs it needs, output format, boundaries), then read all results and synthesize one integrated answer. Detailed instructions: call \`get-framework-context\` with key \`agent-teams\`.
-- **Recurring jobs** — create cron-scheduled jobs with \`manage-jobs\` (actions: create, list, update). After a task with obvious recurring value, offer in one line to save it as an automation. Detailed instructions: call \`get-framework-context\` with key \`recurring-jobs\`.
-- **Connecting Builder.io** — when the user needs a source-code change or hits "Builder not configured", call \`connect-builder\`; it renders a one-click Connect card. Do NOT write setup steps yourself, and never route users to Builder org/beta settings. Detailed instructions: call \`get-framework-context\` with key \`builder\`.
-- **Browser automation** — drive a real Chrome via \`set-browser-control\` (local dev) or \`activate-browser\` (production) for rendered pages, screenshots, and design-token extraction. Detailed instructions: call \`get-framework-context\` with key \`browser\`.
-- **call-agent (external apps only)** — \`call-agent\` messages a DIFFERENT deployed app's agent over A2A; never use it for your own actions or to call yourself. For brand-consistent generated media when this app has no native generation action, call agent "assets". Detailed instructions: call \`get-framework-context\` with key \`call-agent\`.
-- **Structured memory** — persist knowledge across sessions with \`save-memory\` / \`delete-memory\`; save proactively when you learn preferences, corrections, or project context. Detailed instructions: call \`get-framework-context\` with key \`memory\`.
+**call-agent** messages a DIFFERENT deployed app's agent over A2A — never use it for your own actions or to call yourself. For brand-consistent generated media when this app has no native generation action, call agent "assets".
 `;
 }

package/src/server/prompts/index.ts

@@ -8,7 +8,6 @@ export { buildFrameworkCoreCompact } from "./framework-core-compact.js";
 export {
   sharedRule8,
   SHARED_RULE_9,
-  SHARED_RULE_10,
   SHARED_RULE_14,
   SHARED_RULE_15,
   type PromptExamples,

package/src/server/prompts/shared-rules.ts

@@ -3,8 +3,9 @@
  * Single source of truth so the two variants can't drift on rules that are
  * identical between them.
  *
- * Rules 8–10 (db-* tools, no fabrication, no false success) are reproduced
- * verbatim in both prompts — keep them here.
+ * Rules 8–9 (db-* tools; the consolidated no-fabrication / verify / recover
+ * rule) and 12–13 (planning discipline; collaborate through uncertainty) are
+ * reproduced verbatim in both prompts — keep them here.
  */
 import {
   normalizeDatabaseToolsMode,
@@ -83,14 +84,21 @@ export function sharedRule8(
   }, or any external data source. If the user asks about a table that is NOT in the app schema (e.g. \`dbt_analytics.*\`, \`dbt_mart.*\`, or any fully-qualified \`project.dataset.table\`), use the appropriate template action instead — ${warehouseExample}${providerExamples ? `${providerExamples} for their respective providers, ` : ""}etc. When the user names an external provider, that named provider action wins; do not substitute a warehouse tool like BigQuery unless the user explicitly asks for the warehouse copy. **Never use \`db-query\` for external data — it will fail.** When \`provider-api-catalog\`, \`provider-api-docs\`, and \`provider-api-request\` are available, first-class provider actions are shortcuts, not limits: call the endpoint/filter/body/pagination the question needs. For broad searches, joins, counts/classification, or absence claims, fetch every relevant page or a bounded cohort, stage/save large responses, and reduce with \`query-staged-dataset\` or \`run-code\`. Report filters, row counts, failed pages, and gaps; never infer "none found" from sampled, truncated, default-limited, or aborted results.${extensionAdvice}`;
 }
 
-/** Rule 9 — Never fabricate factual claims (shared). */
-export const SHARED_RULE_9 = `9. **Never fabricate factual claims or records** — Do NOT invent numbers, metrics, records, query results, URLs, citations, source attributions, customer names, dates, or success rates. This applies inside generated artifacts too: decks, documents, reports, dashboards, Slack/email replies, and charts must not contain unsupported factual specifics. Only state factual numbers/claims when the user provided them or you retrieved them with an action/tool. If a data source is unavailable, returns no rows, is missing credentials, or has a connection error, say so clearly; do not create placeholder rows or fetch unrelated external providers to make the answer look complete unless the user explicitly asked you to import/sync/backfill. If a specific metric would be useful but is not known, use qualitative wording, placeholders like \`[metric TBD]\`, or clearly labeled draft assumptions instead of plausible-looking facts. Presenting made-up data as real is a critical failure — it is worse than admitting the limitation.`;
-
-/** Rule 10 — Never fabricate success from tool errors (shared). */
-export const SHARED_RULE_10 = `10. **Never fabricate success from tool errors** — When any tool call returns an error (marked \`isError: true\`, contains "Command failed", "Error:", or non-zero exit output), the operation FAILED. Do NOT synthesize a success narrative or describe what the action "would have" produced. Report the failure verbatim from the tool output. This applies especially to \`bash(command="pnpm action ...")\` calls: if the action threw, it did NOT succeed.`;
+/**
+ * Rule 9 — Consolidated anti-fabrication rule (shared). Formerly three
+ * separate rules (fabricating facts, fabricating success, and Rule 11's
+ * "verify before you claim done") — merged because they are one behavior,
+ * honesty about what actually happened, viewed from three angles. Keep all
+ * three sub-behaviors distinct; do not re-split them back into separate
+ * numbered rules.
+ */
+export const SHARED_RULE_9 = `9. **Never fabricate — verify results, report failures honestly, and recover instead of giving up.**
+   - **Never fabricate factual claims or records** — do not invent numbers, metrics, records, query results, URLs, citations, source attributions, customer names, dates, or success rates. This applies inside generated artifacts too: decks, documents, reports, dashboards, Slack/email replies, and charts. Only state factual numbers/claims the user provided or you retrieved with an action/tool. If a data source is unavailable, returns no rows, is missing credentials, or has a connection error, say so clearly; do not create placeholder rows or fetch unrelated providers to look complete unless the user explicitly asked you to import/sync/backfill. Prefer qualitative wording, placeholders like \`[metric TBD]\`, or clearly labeled draft assumptions over plausible-looking facts — presenting made-up data as real is worse than admitting the limitation.
+   - **Never fabricate success from tool errors** — when a tool call returns an error (marked \`isError: true\`, contains "Command failed", "Error:", or non-zero exit output), the operation FAILED; do not synthesize a success narrative or describe what it "would have" produced. Report the failure verbatim (this applies especially to \`bash(command="pnpm action ...")\` calls). Before telling the user a mutating action (create/update/delete/send/publish) is done, confirm it actually landed — check the tool result, or read the refreshed \`<current-screen>\` / re-query the data; having *called* an action is not proof it worked. If a result is ambiguous, check rather than assume.
+   - **Recover instead of giving up** — treat a failure or ambiguous result as a signal to retry the obvious fix, try an alternate tool or approach, or clearly hand the blocker back with what you tried; never silently give up, and never paper over a failure by claiming success.`;
 
-/** Rule 14 — Planning and progress (adapted from Codex's update_plan discipline). */
-export const SHARED_RULE_14 = `14. **Plan and track multi-step work** — For non-trivial tasks that span several actions or phases, use \`manage-progress\` to make work visible and keep it on track.
+/** Rule 12 (const name retained as SHARED_RULE_14 for import stability) — Planning and progress (adapted from Codex's update_plan discipline). */
+export const SHARED_RULE_14 = `12. **Plan and track multi-step work** — For non-trivial tasks that span several actions or phases, use \`manage-progress\` to make work visible and keep it on track.
 
   - Call \`manage-progress\` with \`action: "start"\` at the beginning of multi-step work; include a descriptive \`title\` and the first \`step\`.
   - Update with \`action: "update"\` after each meaningful milestone — include \`step\` (what you just did or are doing now) and \`percent\` when there is a known upper bound. Do not batch-complete multiple steps after the fact; update as you go.
@@ -100,5 +108,5 @@ export const SHARED_RULE_14 = `14. **Plan and track multi-step work** — For no
   - Never create single-step plans — if everything fits in one \`start\`+\`complete\`, just call the action and report the outcome directly.
   - If the task pivots mid-run (unexpected blocker, scope change), update the current step to reflect the new direction before continuing.`;
 
-/** Rule 15 — Collaborate through uncertainty (better-specified version). */
-export const SHARED_RULE_15 = `15. **Collaborate through uncertainty** — If a task stalls, errors, or depends on setup the user may not know about, shift into builder-coach mode instead of repeating the same attempt. State what you verified, name the most likely next checks, and proactively try common unblockers you can inspect (for example prompt size, missing environment variables, unavailable connections, current screen state, or tool choice). When you finish a meaningful step, offer one or two concrete next steps or improvements so non-technical users can keep iterating. When you are genuinely blocked on a decision you cannot resolve from context — and a wrong guess would be costly — use \`ask-question\` to present the choice instead of guessing; otherwise prefer a reasonable assumption and keep moving.`;
+/** Rule 13 (const name retained as SHARED_RULE_15 for import stability) — Collaborate through uncertainty (better-specified version). */
+export const SHARED_RULE_15 = `13. **Collaborate through uncertainty** — If a task stalls, errors, or depends on setup the user may not know about, shift into builder-coach mode instead of repeating the same attempt. State what you verified, name the most likely next checks, and proactively try common unblockers you can inspect (for example prompt size, missing environment variables, unavailable connections, current screen state, or tool choice). When you finish a meaningful step, offer one or two concrete next steps or improvements so non-technical users can keep iterating. When you are genuinely blocked on a decision you cannot resolve from context — and a wrong guess would be costly — use \`ask-question\` to present the choice instead of guessing; otherwise prefer a reasonable assumption and keep moving.`;

package/src/server/ssr-handler.ts

@@ -20,8 +20,8 @@ import { createRequestHandler } from "react-router";
 
 import { isMcpPublicPath } from "../mcp/route-paths.js";
 import {
-  DEFAULT_SSR_CACHE_HEADERS,
   DEFAULT_SPECULATION_RULES_PATH,
+  resolveSsrCacheHeaders,
 } from "../shared/cache-control.js";
 import {
   AGENT_NATIVE_SOCIAL_IMAGE_ALT,
@@ -46,6 +46,10 @@ export {
   DEFAULT_SSR_CACHE_HEADERS,
   DEFAULT_SPECULATION_RULES_HEADER,
   DEFAULT_SSR_CACHE_CONTROL,
+  DISABLED_SSR_CACHE_HEADERS,
+  isSsrCacheEnabled,
+  resolveSsrCacheHeaders,
+  SSR_CACHE_ENV_VAR,
 } from "../shared/cache-control.js";
 
 function getAppBasePath(): string {
@@ -244,6 +248,13 @@ function isSsrHtmlOrDataResponse(
  * │ resolved CLIENT-SIDE after load. Keep it that way: if you need the SSR     │
  * │ output to differ per user, the fix is to move that work client-side, not   │
  * │ to disable caching here.                                                   │
+ * │                                                                            │
+ * │ HOW LONG the shell is cached is deployment-wide and configurable through   │
+ * │ AGENT_NATIVE_SSR_CACHE (see `resolveSsrCacheHeaders`), for hosts that do   │
+ * │ not purge their CDN on deploy. What remains forbidden is PER-REQUEST /     │
+ * │ PER-USER variation — no `private`, no `Vary: Cookie`, no per-route escape  │
+ * │ hatch — because that is what poisons a shared CDN cache key. A value fixed │
+ * │ for the whole deployment cannot.                                           │
  * └──────────────────────────────────────────────────────────────────────────┘
  */
 function applyDefaultSsrCacheHeader(
@@ -279,7 +290,7 @@ function applyDefaultSsrCacheHeader(
   // and Netlify-CDN-Cache-Control (with durable) so Netlify's shared cache
   // actually serves SSR HTML/.data from the edge instead of forwarding every
   // request to origin — for every visitor, authenticated or not.
-  for (const [name, value] of Object.entries(DEFAULT_SSR_CACHE_HEADERS)) {
+  for (const [name, value] of Object.entries(resolveSsrCacheHeaders())) {
     headers.set(name, value);
   }
 }

package/src/settings/user-settings.ts

@@ -16,6 +16,15 @@ import {
 } from "./store.js";
 
 function userKey(email: string, key: string): string {
+  return `u:${email.trim().toLowerCase()}:${key}`;
+}
+
+/**
+ * Pre-normalization spelling. Callers pass the session email verbatim, so the
+ * same user could be written under `Alice@Builder.IO` and read under
+ * `alice@builder.io` — silently losing settings such as `active-org-id`.
+ */
+function legacyUserKey(email: string, key: string): string {
   return `u:${email}:${key}`;
 }
 
@@ -24,7 +33,10 @@ export async function getUserSetting(
   email: string,
   key: string,
 ): Promise<Record<string, unknown> | null> {
-  return getSetting(userKey(email, key));
+  const normalized = await getSetting(userKey(email, key));
+  if (normalized !== null) return normalized;
+  const legacy = legacyUserKey(email, key);
+  return legacy === userKey(email, key) ? null : getSetting(legacy);
 }
 
 /** Write a user-scoped setting. Always writes to the prefixed key. */

package/src/shared/cache-control.ts

@@ -14,6 +14,147 @@ export const DEFAULT_SSR_CACHE_HEADERS = {
   "netlify-cdn-cache-control": DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL,
 } as const;
 
+/**
+ * Deployment-wide override for the SSR shell cache policy.
+ *
+ * The default (`DEFAULT_SSR_CACHE_HEADERS`) is deliberately aggressive: SSR
+ * HTML and React Router `.data` are one impersonal public shell, so hosts that
+ * purge their CDN on deploy get near-static page loads for free. Two situations
+ * make that default wrong, and both are properties of the DEPLOYMENT, not of
+ * the request:
+ *
+ *   1. The host does not purge its CDN on deploy, so a shipped build can keep
+ *      serving the previous shell for `max-age` + `stale-while-revalidate`.
+ *   2. The app's loaders return mutable public data, so a `useRevalidator()`
+ *      after a mutation reads the browser's cached `.data` copy instead of
+ *      fresh loader output.
+ *
+ * This override is intentionally global and env-driven rather than a
+ * per-route/per-request escape hatch. A response that varies by request is how
+ * one visitor's payload ends up in another visitor's shared CDN entry; a value
+ * fixed for the whole deployment cannot. Turning caching off does NOT make SSR
+ * personalized — `requestForAnonymousSsr` still strips cookies before render.
+ *
+ * Accepted values (case-insensitive):
+ *   unset | "on" | "default" | "true" | "1" → the default policy, unchanged
+ *   "off" | "false" | "0" | "none" | "no-store" | "disabled" → no caching
+ *   "<n>" | "<n>s" | "<n>m" | "<n>h" → public caching with that freshness
+ */
+export const SSR_CACHE_ENV_VAR = "AGENT_NATIVE_SSR_CACHE";
+
+export const DISABLED_SSR_CACHE_CONTROL = "no-store";
+
+export const DISABLED_SSR_CACHE_HEADERS = {
+  "cache-control": DISABLED_SSR_CACHE_CONTROL,
+  "cdn-cache-control": DISABLED_SSR_CACHE_CONTROL,
+  "netlify-cdn-cache-control": DISABLED_SSR_CACHE_CONTROL,
+} as const;
+
+export type SsrCachePolicy =
+  | { kind: "default" }
+  | { kind: "disabled" }
+  | { kind: "maxAge"; seconds: number };
+
+export type SsrCacheHeaders = Record<
+  "cache-control" | "cdn-cache-control" | "netlify-cdn-cache-control",
+  string
+>;
+
+const ON_VALUES = new Set(["", "on", "default", "true", "1", "yes"]);
+const OFF_VALUES = new Set([
+  "off",
+  "false",
+  "0",
+  "no",
+  "none",
+  "no-store",
+  "disabled",
+]);
+
+const DURATION_RE = /^(\d+)\s*(s|sec|secs|seconds?|m|min|mins?|h|hours?)?$/;
+const DURATION_MULTIPLIERS: Record<string, number> = {
+  s: 1,
+  m: 60,
+  h: 3600,
+};
+
+const MAX_SSR_CACHE_SECONDS = 31_536_000;
+
+export function parseSsrCacheSetting(
+  raw: string | undefined | null,
+): SsrCachePolicy {
+  const value = (raw ?? "").trim().toLowerCase();
+  if (ON_VALUES.has(value)) return { kind: "default" };
+  if (OFF_VALUES.has(value)) return { kind: "disabled" };
+
+  const match = DURATION_RE.exec(value);
+  if (match) {
+    const multiplier = DURATION_MULTIPLIERS[match[2]?.[0] ?? "s"] ?? 1;
+    const seconds = Math.min(
+      Number(match[1]) * multiplier,
+      MAX_SSR_CACHE_SECONDS,
+    );
+    return seconds > 0 ? { kind: "maxAge", seconds } : { kind: "disabled" };
+  }
+
+  // Unrecognized values fall back to the default rather than failing the
+  // deployment: a typo in this env var must never silently disable the CDN.
+  console.warn(
+    `[agent-native] Ignoring unrecognized ${SSR_CACHE_ENV_VAR}=${raw}. ` +
+      `Expected "on", "off", or a duration such as "30s" / "5m".`,
+  );
+  return { kind: "default" };
+}
+
+export function ssrCacheHeadersForPolicy(
+  policy: SsrCachePolicy,
+): SsrCacheHeaders {
+  if (policy.kind === "default") return { ...DEFAULT_SSR_CACHE_HEADERS };
+  if (policy.kind === "disabled") return { ...DISABLED_SSR_CACHE_HEADERS };
+  // Mirror stale-while-revalidate onto the chosen freshness. Apps opt into a
+  // short max-age precisely because a long stale window is the problem; keeping
+  // the 7-day default SWR here would hand back the staleness they opted out of.
+  const control =
+    `public, max-age=${policy.seconds}, ` +
+    `stale-while-revalidate=${policy.seconds}, stale-if-error=3600`;
+  return {
+    "cache-control": control,
+    "cdn-cache-control": control,
+    "netlify-cdn-cache-control": control,
+  };
+}
+
+let memoizedRaw: string | undefined;
+let memoizedHeaders: Readonly<SsrCacheHeaders> | undefined;
+
+/**
+ * Resolve the SSR cache headers for this deployment. Reads
+ * `AGENT_NATIVE_SSR_CACHE` and memoizes per distinct value so the hot SSR path
+ * does not re-parse on every response. The result is frozen and shared by every
+ * response — copy it before mutating.
+ */
+export function resolveSsrCacheHeaders(
+  env: Record<string, string | undefined> = typeof process === "undefined"
+    ? {}
+    : process.env,
+): Readonly<SsrCacheHeaders> {
+  const raw = env[SSR_CACHE_ENV_VAR];
+  if (memoizedHeaders && raw === memoizedRaw) return memoizedHeaders;
+  memoizedRaw = raw;
+  memoizedHeaders = Object.freeze(
+    ssrCacheHeadersForPolicy(parseSsrCacheSetting(raw)),
+  );
+  return memoizedHeaders;
+}
+
+export function isSsrCacheEnabled(
+  env: Record<string, string | undefined> = typeof process === "undefined"
+    ? {}
+    : process.env,
+): boolean {
+  return parseSsrCacheSetting(env[SSR_CACHE_ENV_VAR]).kind !== "disabled";
+}
+
 export const DEFAULT_SPECULATION_RULES_PATH =
   "/_agent-native/speculation-rules.json";
 

package/src/templates/chat/.agents/skills/upgrade-agent-native/SKILL.md

@@ -56,7 +56,29 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    - Runs `skills update scaffold --project`
    - Runs `typecheck` when the project has that script
 
-3. **If upgrade or typecheck fails**
+3. **Pull upstream template changes (optional, separate from the bump)**
+
+   `agent-native upgrade` moves package versions. It never touches files that
+   were copied out of a template at scaffold time, so template fixes and
+   improvements do not arrive with a bump.
+
+   ```bash
+   agent-native template status        # recorded ref vs latest, drift counts
+   agent-native template diff          # what upstream changed, read-only
+   agent-native template sync          # 3-way merge it into the app
+   ```
+
+   `sync` defaults to the ref matching the installed `@agent-native/core`, so
+   run it after `upgrade`. It merges per file against a pristine baseline
+   stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
+   did not touch are left alone, and real collisions get conflict markers.
+   After resolving markers, run `agent-native template accept` — the baseline
+   deliberately does not advance past an unresolved merge.
+
+   Apps scaffolded before provenance existed have no baseline. Create one
+   with `agent-native template baseline` before the first sync.
+
+4. **If upgrade or typecheck fails**
 
    - Read the concrete error
    - Fix **app** source, actions, config, or env — not framework packages
@@ -68,7 +90,7 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    copied component; do not use that path to reproduce framework runtime
    behavior or hide version skew.
 
-4. **Dry-run / partial runs**
+5. **Dry-run / partial runs**
 
    ```bash
    agent-native upgrade --dry-run

package/src/templates/chat/_gitignore

@@ -41,3 +41,4 @@ data/.sessions.json
 learnings.md
 
 .vercel/
+.agent-native/

package/src/templates/default/.agents/skills/upgrade-agent-native/SKILL.md

@@ -56,7 +56,29 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    - Runs `skills update scaffold --project`
    - Runs `typecheck` when the project has that script
 
-3. **If upgrade or typecheck fails**
+3. **Pull upstream template changes (optional, separate from the bump)**
+
+   `agent-native upgrade` moves package versions. It never touches files that
+   were copied out of a template at scaffold time, so template fixes and
+   improvements do not arrive with a bump.
+
+   ```bash
+   agent-native template status        # recorded ref vs latest, drift counts
+   agent-native template diff          # what upstream changed, read-only
+   agent-native template sync          # 3-way merge it into the app
+   ```
+
+   `sync` defaults to the ref matching the installed `@agent-native/core`, so
+   run it after `upgrade`. It merges per file against a pristine baseline
+   stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
+   did not touch are left alone, and real collisions get conflict markers.
+   After resolving markers, run `agent-native template accept` — the baseline
+   deliberately does not advance past an unresolved merge.
+
+   Apps scaffolded before provenance existed have no baseline. Create one
+   with `agent-native template baseline` before the first sync.
+
+4. **If upgrade or typecheck fails**
 
    - Read the concrete error
    - Fix **app** source, actions, config, or env — not framework packages
@@ -68,7 +90,7 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    copied component; do not use that path to reproduce framework runtime
    behavior or hide version skew.
 
-4. **Dry-run / partial runs**
+5. **Dry-run / partial runs**
 
    ```bash
    agent-native upgrade --dry-run

package/src/templates/headless/.agents/skills/upgrade-agent-native/SKILL.md

@@ -56,7 +56,29 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    - Runs `skills update scaffold --project`
    - Runs `typecheck` when the project has that script
 
-3. **If upgrade or typecheck fails**
+3. **Pull upstream template changes (optional, separate from the bump)**
+
+   `agent-native upgrade` moves package versions. It never touches files that
+   were copied out of a template at scaffold time, so template fixes and
+   improvements do not arrive with a bump.
+
+   ```bash
+   agent-native template status        # recorded ref vs latest, drift counts
+   agent-native template diff          # what upstream changed, read-only
+   agent-native template sync          # 3-way merge it into the app
+   ```
+
+   `sync` defaults to the ref matching the installed `@agent-native/core`, so
+   run it after `upgrade`. It merges per file against a pristine baseline
+   stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
+   did not touch are left alone, and real collisions get conflict markers.
+   After resolving markers, run `agent-native template accept` — the baseline
+   deliberately does not advance past an unresolved merge.
+
+   Apps scaffolded before provenance existed have no baseline. Create one
+   with `agent-native template baseline` before the first sync.
+
+4. **If upgrade or typecheck fails**
 
    - Read the concrete error
    - Fix **app** source, actions, config, or env — not framework packages
@@ -68,7 +90,7 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    copied component; do not use that path to reproduce framework runtime
    behavior or hide version skew.
 
-4. **Dry-run / partial runs**
+5. **Dry-run / partial runs**
 
    ```bash
    agent-native upgrade --dry-run

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

@@ -151,6 +151,23 @@ 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.
 
+**Never route mutation-fresh reads through SSR loader data.** Data that changes
+when a user acts belongs in an action, read from the client with
+`useActionQuery` / `useActionMutation` and kept live by `useDbSync()` polling —
+that path never touches the SSR shell cache. A `useRevalidator()` after a
+mutation re-fetches `.data` with a plain GET and can legitimately be served the
+cached copy. SSR loaders render the public shell; the client resolves anything
+that must be fresh.
+
+The one supported knob is the deployment-wide `AGENT_NATIVE_SSR_CACHE` env var:
+unset/`on` keeps the default, `off` sends `no-store`, and a duration such as
+`30s` / `5m` shortens freshness. It is for deployments whose host does not purge
+its CDN on deploy, or whose loaders genuinely serve mutable public data. It
+changes cache duration only — cookies are still stripped before render, so
+turning it off does not make SSR personalized. There is deliberately no
+per-route or per-request override; that is how one visitor's payload lands in
+another visitor's shared CDN entry.
+
 ## 7. Big payloads and long lists
 
 - **Paginate or window** unbounded lists (messages, responses, events, activity).
@@ -176,3 +193,5 @@ enforced contract.
 - [ ] 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.
+- [ ] Mutation-fresh reads go through actions + `useActionQuery`, not SSR loader
+      data.

package/src/templates/workspace-core/.agents/skills/upgrade-agent-native/SKILL.md

@@ -56,7 +56,29 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    - Runs `skills update scaffold --project`
    - Runs `typecheck` when the project has that script
 
-3. **If upgrade or typecheck fails**
+3. **Pull upstream template changes (optional, separate from the bump)**
+
+   `agent-native upgrade` moves package versions. It never touches files that
+   were copied out of a template at scaffold time, so template fixes and
+   improvements do not arrive with a bump.
+
+   ```bash
+   agent-native template status        # recorded ref vs latest, drift counts
+   agent-native template diff          # what upstream changed, read-only
+   agent-native template sync          # 3-way merge it into the app
+   ```
+
+   `sync` defaults to the ref matching the installed `@agent-native/core`, so
+   run it after `upgrade`. It merges per file against a pristine baseline
+   stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
+   did not touch are left alone, and real collisions get conflict markers.
+   After resolving markers, run `agent-native template accept` — the baseline
+   deliberately does not advance past an unresolved merge.
+
+   Apps scaffolded before provenance existed have no baseline. Create one
+   with `agent-native template baseline` before the first sync.
+
+4. **If upgrade or typecheck fails**
 
    - Read the concrete error
    - Fix **app** source, actions, config, or env — not framework packages
@@ -68,7 +90,7 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    copied component; do not use that path to reproduce framework runtime
    behavior or hide version skew.
 
-4. **Dry-run / partial runs**
+5. **Dry-run / partial runs**
 
    ```bash
    agent-native upgrade --dry-run

package/src/templates/workspace-core/.agents/skills/visual-answer/SKILL.md

@@ -3,6 +3,7 @@ name: visual-answer
 description: >-
   Answer code/product questions as visual Plan artifacts using repo, bridge, or
   GitHub context; use for API specs, UI look, schema models, and architecture.
+scope: dev
 metadata:
   visibility: exported
 ---

package/src/vite/agents-bundle-plugin.ts

@@ -118,10 +118,12 @@ export function agentsBundlePlugin(): Plugin {
         const rel = path.relative(projectRoot, file);
         if (!rel.startsWith("..")) {
           if (rel === "AGENTS.md") return true;
-          if (rel.endsWith("SKILL.md")) {
-            for (const skillsDir of TEMPLATE_SKILLS_DIRS) {
-              if (rel.startsWith(skillsDir + path.sep)) return true;
-            }
+          for (const skillsDir of TEMPLATE_SKILLS_DIRS) {
+            // Any file under a skills directory can affect the bundle now —
+            // `readSkillsDir` reads reference sub-files (not just SKILL.md)
+            // into `Skill.files`, so dev HMR must match that or reference
+            // edits go stale until a manual restart.
+            if (rel.startsWith(skillsDir + path.sep)) return true;
           }
         }
         // Workspace-core files
@@ -130,8 +132,7 @@ export function agentsBundlePlugin(): Plugin {
         }
         if (
           workspaceSkillsDir &&
-          file.startsWith(workspaceSkillsDir + path.sep) &&
-          file.endsWith("SKILL.md")
+          file.startsWith(workspaceSkillsDir + path.sep)
         ) {
           return true;
         }

package/src/vite/client.ts

@@ -872,6 +872,7 @@ const CORE_CLIENT_SUBPATHS = [
   // entry.client.tsx imports from here so it never pulls the full client barrel
   // (and its transitive ~650-700 KB gzip chat stack) onto the critical path.
   "@agent-native/core/client/api-path",
+  "@agent-native/core/client/clipboard",
   "@agent-native/core/blocks",
   "@agent-native/core/blocks/server",
   "@agent-native/core/client/extensions",
@@ -1265,6 +1266,10 @@ function getCoreSourceAliases(
       coreSrc,
       "client/api-path.ts",
     ),
+    "@agent-native/core/client/clipboard": path.join(
+      coreSrc,
+      "client/clipboard.ts",
+    ),
     "@agent-native/core/blocks": path.join(coreSrc, "client/blocks/index.ts"),
     "@agent-native/core/blocks/server": path.join(
       coreSrc,