@agent-native/core 0.121.1 → 0.122.0

package/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/src/templates/chat/_gitignore

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

package/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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,

package/corpus/templates/analytics/.agents/skills/adhoc-analysis/SKILL.md

@@ -68,11 +68,10 @@ Use the available actions to pull data. Read the relevant `.agents/skills/<provi
   associated companies/contacts/tickets/notes/emails, Gong call detail, compact
   transcript excerpts, coverage counts, and gaps. Use targeted `hubspot-records`
   or `gong-calls` follow-ups only when that bundle leaves a specific gap.
-- Structure named deal/account reports like Fusion Analytics: executive summary,
-  company/deal overview, key contacts and roles, dated timeline, Gong evidence
-  with call dates/titles, current state, risks/blockers, recommended next steps,
-  and methodology/gaps. Do not answer from an all-deals dump or Gong metadata
-  alone.
+- Structure named deal/account reports as: executive summary, company/deal
+  overview, key contacts and roles, dated timeline, Gong evidence with call
+  dates/titles, current state, risks/blockers, recommended next steps, and
+  methodology/gaps. Do not answer from an all-deals dump or Gong metadata alone.
 - Use action filters such as `query`, `properties`, `objectType`, `company`, and
   `limit` to narrow results before cross-referencing
 - For HubSpot deal cohorts, use `hubspot-deals` structured filters (`product`,

package/corpus/templates/analytics/.agents/skills/admin-surfaces/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: admin-surfaces
+description: >-
+  The /agents admin home for Analytics: fleet feature-flag control plane,
+  dashboard usage audit, and connected-app database admin. Use when an admin
+  asks about feature flags/rollouts, dashboard usage stats, or connecting
+  another agent-native app's database.
+---
+
+# Admin Surfaces (`/agents`)
+
+`/agents` is the Analytics home for admin surfaces. The default Monitoring
+view embeds the shared observability dashboard for traces, conversations,
+evals, agent experiments, and feedback.
+
+## Feature Flags (`?view=flags`)
+
+`/agents?view=flags` is the sole admin-only fleet feature-flag control plane.
+
+- Call `list-workspace-feature-flags` before changing a flag.
+- Preserve each app's explicit state: `unsupported`, `unreachable`,
+  `forbidden`, and `unknown-legacy` are unknown states, **never** synonyms for
+  off. Do not collapse them to a disabled toggle.
+- Use `set-workspace-feature-flag` for app-qualified changes; target apps
+  remain the source of truth and are resolved only through the trusted
+  organization directory.
+- Treat only a versioned mutation response whose key, org scope, and
+  requested rules match as success. Report a failed target mutation instead
+  of claiming the rollout changed.
+- Flags are source-declared booleans; do not create variants, metrics,
+  exposure tracking, or per-app management panels.
+
+## Dashboard Usage (`?view=dashboards`)
+
+`/agents?view=dashboards` shows the admin-only dashboard usage audit. Call
+`list-dashboard-usage-stats` when admins ask about dashboard created/modified
+dates, owners, last tracked modifier, views, edits, engagements, saved views,
+or cleanup candidates. The dashboard overflow menu shows created/updated
+timestamps and their tracked actors for both SQL and Explorer dashboards.
+
+## Connected Database Admin (`?view=database`)
+
+The Advanced menu opens `/agents?view=database`, where organization
+owners/admins can connect other agent-native app databases and use the
+shared database admin tool for table browsing, row editing, and SQL
+inspection. This surface is for connected target app databases, not broad
+access to all Analytics data.
+
+Keep future admin additions inside this route instead of adding many
+top-level sidebar tabs.
+
+## Related Skills
+
+- Root **feature-flags** (dev-scope) — how to declare and register a flag in
+  app code; this skill covers only the Analytics fleet control-plane UI/actions.

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

@@ -615,6 +615,16 @@ state or tracker context, but docs traffic is not app usage and should not appea
 as an app/template series. Use a minimum cohort-size threshold for retention
 rates so one or two identities cannot create misleading 100% or 0% spikes.
 
+## Template Catalog And Demo Dashboards
+
+`list-dashboard-templates` / `install-dashboard-template` install shipped
+dashboard templates (Node Exporter, the canonical Agent Native observability
+dashboard, etc.), and `ensure-demo-dashboards` auto-installs a per-user demo
+on first app open. See
+`references/template-catalog-and-demo.md` for the canonical-dashboard panel
+rule, Node Exporter template specifics, and the full demo-dashboard lifecycle
+(source routing, env var overrides, tombstoning, reset).
+
 ## Building Large First-Party Dashboards (compose-dashboard)
 
 For a **first-party analytics** dashboard, prefer `compose-dashboard` over hand-authoring a big `update-dashboard` config. You name the metrics; the SERVER expands each into a full, validated panel (SQL + chart config) from the shipped metric catalog and saves them in ONE atomic call. This avoids the failure mode where the agent must stream a giant multi-panel `update-dashboard` argument inside the ~40s budget — that big tool-call can't be resumed mid-stream and is all-or-nothing on validation, so the agent thrashes (repeated update-dashboard + tool-search, never landing).