@agent-native/core 0.122.3 → 0.123.0

package/dist/shared/sign-in-journey.js

@@ -0,0 +1,269 @@
+/**
+ * The single "establish a session and return the user where they started"
+ * primitive.
+ *
+ * Before this file the framework had five return-path validators, four
+ * "don't redirect to yourself" checks, and two complete copies of the login
+ * document — so every anti-loop fix landed on whichever fork the ticket named
+ * and the reports never stopped. Every sign-in surface now calls exactly this:
+ * the client gate (`RequireSession`), the login document, the sign-in entry
+ * route, and every template button.
+ *
+ * The continuation is a PATH, never a URL, and it is carried opaquely in the
+ * `c` query param. That combination is why nesting is structurally impossible
+ * rather than guarded against:
+ *
+ *  - the grammar is not recursive: decoding a continuation yields a string,
+ *    never another continuation;
+ *  - `signInJourney` returns `signInHref: null` — no token at all — when the
+ *    browser is already at an auth entry path, so the one function permitted
+ *    to mint continuations refuses to mint the dangerous value;
+ *  - the sign-in URL is `<base>/_agent-native/sign-in?c=<opaque>`, so
+ *    "capture the current location as the return" has no URL-shaped input to
+ *    re-encode;
+ *  - `c` does not look like a URL, so Better Auth's `callbackURL`, a proxy, or
+ *    a future patch cannot mistake it for a redirect target and wrap it.
+ *
+ * There is exactly ONE auth-entry-path predicate left in the codebase and it
+ * lives in `normalizeAppPath` below. The four call-site copies are gone.
+ *
+ * Not signed. Signing buys nothing: the user already controls their own
+ * browser and can type any URL. The only threat is open redirect, which is a
+ * validation problem, not an integrity problem — and an HMAC would add a
+ * secret dependency to code that must run inside a CDN-cached public document.
+ */
+export const SIGN_IN_CONTINUATION_PARAM = "c";
+/**
+ * Legacy entry-point grammar. Generated apps in the wild hand-write
+ * `/_agent-native/sign-in?return=<path>` and are not upgradeable, so the
+ * CONSUMER side of this param is permanent API surface. New producers must
+ * emit `c` instead; deleting the consumer fallback silently redirects every
+ * generated app to `/`, which reads as a UX quirk rather than a regression and
+ * therefore will not be caught.
+ */
+export const SIGN_IN_LEGACY_RETURN_PARAM = "return";
+export const SIGN_IN_ENTRY_PATH = "/_agent-native/sign-in";
+/** Max length of an encoded continuation token, in characters. */
+export const SIGN_IN_CONTINUATION_MAX_LENGTH = 512;
+/**
+ * The whole runtime, as one self-contained function.
+ *
+ * Self-contained on purpose: `signInJourneyInlineScript()` emits this via
+ * `Function.prototype.toString()` so the login documents run the identical
+ * code instead of a hand-transcribed copy. A reference to anything outside
+ * this function body would be undefined inside the emitted script.
+ */
+function createSignInJourneyRuntime(basePath) {
+    var PARAM = "c";
+    var LEGACY_PARAM = "return";
+    var ENTRY_PATH = "/_agent-native/sign-in";
+    var MAX_TOKEN = 512;
+    var SENTINEL = "http://an.invalid";
+    function normalizeBasePath(raw) {
+        if (!raw || raw === "/")
+            return "";
+        var trimmed = String(raw).replace(/^\/+/, "").replace(/\/+$/, "");
+        return trimmed ? "/" + trimmed : "";
+    }
+    var base = normalizeBasePath(basePath);
+    function hasControlCharacter(value) {
+        for (var i = 0; i < value.length; i++) {
+            var code = value.charCodeAt(i);
+            if (code < 0x20 || code === 0x7f)
+                return true;
+        }
+        return false;
+    }
+    function isAuthEntryPath(pathname) {
+        // Suffix match rather than equality so this holds under any base path,
+        // including one this process was not configured with (a workspace host
+        // serving a sibling app's URL).
+        if (pathname === ENTRY_PATH ||
+            pathname.slice(-ENTRY_PATH.length) === ENTRY_PATH) {
+            return true;
+        }
+        var rest = pathname;
+        if (base) {
+            if (rest === base)
+                rest = "/";
+            else if (rest.slice(0, base.length + 1) === base + "/")
+                rest = rest.slice(base.length);
+        }
+        return rest === "/login" || rest === "/signup";
+    }
+    /**
+     * The shared validator. Returns a full same-origin app path, or `null` —
+     * never `"/"`, so an invalid continuation stays distinguishable from a
+     * genuine request for the home page. Callers that want a fallback write it
+     * at the call site.
+     */
+    function normalizeAppPath(raw) {
+        if (typeof raw !== "string" || !raw)
+            return null;
+        // Header/URL injection: a `\r\n` reaching a `Location` splits the response.
+        if (hasControlCharacter(raw))
+            return null;
+        if (raw.charAt(0) !== "/")
+            return null;
+        // Scheme-relative, plus the backslash form WHATWG normalizes to `//`.
+        if (raw.charAt(1) === "/" || raw.charAt(1) === "\\")
+            return null;
+        var parsed;
+        try {
+            parsed = new URL(raw, SENTINEL);
+        }
+        catch (e) {
+            return null;
+        }
+        // Catches everything WHATWG normalizes that prefix checks miss. This is
+        // why prefix checks alone are insufficient.
+        if (parsed.origin !== SENTINEL)
+            return null;
+        var pathname = parsed.pathname || "/";
+        // WHATWG path normalization can turn traversal such as `/..//host` into
+        // `//host`; validate the normalized path before returning it to a redirect
+        // sink.
+        if (pathname.startsWith("//"))
+            return null;
+        if (isAuthEntryPath(pathname))
+            return null;
+        // Containment in this app's own base path. On a multi-app workspace host
+        // `/otherapp/admin` is same-origin but is NOT this app, so this is the
+        // only control that makes an unsigned path-only token safe there. `base`
+        // is resolved from configured env / `appBasePath()` and NEVER from the
+        // continuation itself.
+        if (base &&
+            pathname !== base &&
+            pathname.slice(0, base.length + 1) !== base + "/") {
+            return null;
+        }
+        return pathname + parsed.search + parsed.hash;
+    }
+    function encodeContinuation(path) {
+        var normalized = normalizeAppPath(path);
+        if (!normalized)
+            return "";
+        var token;
+        try {
+            // encodeURIComponent first so the input to btoa is pure ASCII; the pair
+            // round-trips any UTF-8 exactly.
+            token = btoa(encodeURIComponent(normalized))
+                .replace(/\+/g, "-")
+                .replace(/\//g, "_")
+                .replace(/=+$/, "");
+        }
+        catch (e) {
+            return "";
+        }
+        return token.length > MAX_TOKEN ? "" : token;
+    }
+    function decodeContinuation(token) {
+        if (typeof token !== "string" || !token)
+            return null;
+        if (token.length > MAX_TOKEN)
+            return null;
+        var decoded;
+        try {
+            var b64 = token.replace(/-/g, "+").replace(/_/g, "/");
+            while (b64.length % 4 !== 0)
+                b64 += "=";
+            decoded = decodeURIComponent(atob(b64));
+        }
+        catch (e) {
+            return null;
+        }
+        // Re-validated on decode: a user can paste any `c`, so encode-time
+        // validation is never trusted here.
+        return normalizeAppPath(decoded);
+    }
+    function homeHref() {
+        return base || "/";
+    }
+    function signInJourney(input) {
+        var here = normalizeAppPath(input.at);
+        var resume = decodeContinuation(input.continuation) ??
+            normalizeAppPath(input.legacyReturn) ??
+            here ??
+            homeHref();
+        var signInHref = null;
+        if (here !== null) {
+            var token = encodeContinuation(here);
+            signInHref = base + ENTRY_PATH + (token ? "?" + PARAM + "=" + token : "");
+        }
+        return { signInHref: signInHref, resumeHref: resume };
+    }
+    /** Read a query param out of a raw `?a=b` / `a=b` search string. */
+    function readParam(search, name) {
+        try {
+            return new URLSearchParams(search || "").get(name);
+        }
+        catch (e) {
+            return null;
+        }
+    }
+    function journeyForLocation(location) {
+        return signInJourney({
+            at: (location.pathname || "/") +
+                (location.search || "") +
+                (location.hash || ""),
+            continuation: readParam(location.search, PARAM),
+            legacyReturn: readParam(location.search, LEGACY_PARAM),
+        });
+    }
+    return {
+        PARAM: PARAM,
+        LEGACY_PARAM: LEGACY_PARAM,
+        basePath: base,
+        homeHref: homeHref,
+        normalizeAppPath: normalizeAppPath,
+        encodeContinuation: encodeContinuation,
+        decodeContinuation: decodeContinuation,
+        signInJourney: signInJourney,
+        journeyForLocation: journeyForLocation,
+    };
+}
+const runtimeCache = new Map();
+function runtime(basePath) {
+    const key = basePath ?? "";
+    let cached = runtimeCache.get(key);
+    if (!cached) {
+        cached = createSignInJourneyRuntime(key);
+        runtimeCache.set(key, cached);
+    }
+    return cached;
+}
+/**
+ * Validate a candidate app path. Returns the normalised full path (base path
+ * included) or `null`. Pass `basePath` to additionally require containment —
+ * omit it for surfaces such as provider OAuth returns whose targets are not
+ * guaranteed to be base-path prefixed.
+ */
+export function normalizeAppPath(raw, basePath = "") {
+    return runtime(basePath).normalizeAppPath(raw);
+}
+/** Encode an app path as a continuation token. `""` for anything not returnable. */
+export function encodeContinuation(path, basePath = "") {
+    return runtime(basePath).encodeContinuation(path);
+}
+/** Decode a continuation token to an app path. `null` for anything invalid. */
+export function decodeContinuation(token, basePath = "") {
+    return runtime(basePath).decodeContinuation(token);
+}
+export function signInJourney(input) {
+    return runtime(input.basePath).signInJourney(input);
+}
+/**
+ * The runtime as `<script>`-embeddable source declaring
+ * `__anCreateSignInJourney(basePath)`.
+ *
+ * Emitted from the same function the server and client call, so the login
+ * document cannot drift from the module — which is exactly how the repo ended
+ * up with two login pages disagreeing about return paths in the first place.
+ * `packages/core` builds with plain `tsc` (no bundler, no minifier), so the
+ * emitted source is verbatim; `createSignInJourneyRuntime` must therefore stay
+ * self-contained, ES5-compatible, and free of references to module scope.
+ */
+export function signInJourneyInlineScript() {
+    return `var __anCreateSignInJourney = ${createSignInJourneyRuntime.toString()};`;
+}
+//# sourceMappingURL=sign-in-journey.js.map

package/dist/shared/sign-in-journey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign-in-journey.js","sourceRoot":"","sources":["../../src/shared/sign-in-journey.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The single \"establish a session and return the user where they started\"\n * primitive.\n *\n * Before this file the framework had five return-path validators, four\n * \"don't redirect to yourself\" checks, and two complete copies of the login\n * document — so every anti-loop fix landed on whichever fork the ticket named\n * and the reports never stopped. Every sign-in surface now calls exactly this:\n * the client gate (`RequireSession`), the login document, the sign-in entry\n * route, and every template button.\n *\n * The continuation is a PATH, never a URL, and it is carried opaquely in the\n * `c` query param. That combination is why nesting is structurally impossible\n * rather than guarded against:\n *\n *  - the grammar is not recursive: decoding a continuation yields a string,\n *    never another continuation;\n *  - `signInJourney` returns `signInHref: null` — no token at all — when the\n *    browser is already at an auth entry path, so the one function permitted\n *    to mint continuations refuses to mint the dangerous value;\n *  - the sign-in URL is `<base>/_agent-native/sign-in?c=<opaque>`, so\n *    \"capture the current location as the return\" has no URL-shaped input to\n *    re-encode;\n *  - `c` does not look like a URL, so Better Auth's `callbackURL`, a proxy, or\n *    a future patch cannot mistake it for a redirect target and wrap it.\n *\n * There is exactly ONE auth-entry-path predicate left in the codebase and it\n * lives in `normalizeAppPath` below. The four call-site copies are gone.\n *\n * Not signed. Signing buys nothing: the user already controls their own\n * browser and can type any URL. The only threat is open redirect, which is a\n * validation problem, not an integrity problem — and an HMAC would add a\n * secret dependency to code that must run inside a CDN-cached public document.\n */\n\nexport const SIGN_IN_CONTINUATION_PARAM = \"c\";\n\n/**\n * Legacy entry-point grammar. Generated apps in the wild hand-write\n * `/_agent-native/sign-in?return=<path>` and are not upgradeable, so the\n * CONSUMER side of this param is permanent API surface. New producers must\n * emit `c` instead; deleting the consumer fallback silently redirects every\n * generated app to `/`, which reads as a UX quirk rather than a regression and\n * therefore will not be caught.\n */\nexport const SIGN_IN_LEGACY_RETURN_PARAM = \"return\";\n\nexport const SIGN_IN_ENTRY_PATH = \"/_agent-native/sign-in\";\n\n/** Max length of an encoded continuation token, in characters. */\nexport const SIGN_IN_CONTINUATION_MAX_LENGTH = 512;\n\nexport interface SignInJourney {\n  /**\n   * Where to send the browser to authenticate — always same-origin, always\n   * under the app base path, always carrying exactly one continuation.\n   * `null` when the browser is ALREADY at an auth entry path: there is no\n   * such thing as signing in from the sign-in page, and a caller must not\n   * navigate. Distinguishable absence, never a lookalike default.\n   */\n  readonly signInHref: string | null;\n  /**\n   * Where to send the browser once a session exists. Always same-origin,\n   * always under the app base path, never an auth entry path. Always a value —\n   * worst case the app home, which is a correct answer rather than a swallowed\n   * failure.\n   */\n  readonly resumeHref: string;\n}\n\nexport interface SignInJourneyInput {\n  /** Current location as a PATH: pathname + search + hash. Never a URL. */\n  at: string;\n  /** Whatever arrived in the `c` query param, if anything. */\n  continuation?: string | null;\n  /**\n   * Legacy `?return=` value, if anything. Accepted forever; see\n   * SIGN_IN_LEGACY_RETURN_PARAM.\n   */\n  legacyReturn?: string | null;\n  /** App base path, `\"\"` for root deploys. */\n  basePath?: string;\n}\n\n/**\n * The whole runtime, as one self-contained function.\n *\n * Self-contained on purpose: `signInJourneyInlineScript()` emits this via\n * `Function.prototype.toString()` so the login documents run the identical\n * code instead of a hand-transcribed copy. A reference to anything outside\n * this function body would be undefined inside the emitted script.\n */\nfunction createSignInJourneyRuntime(basePath: string) {\n  var PARAM = \"c\";\n  var LEGACY_PARAM = \"return\";\n  var ENTRY_PATH = \"/_agent-native/sign-in\";\n  var MAX_TOKEN = 512;\n  var SENTINEL = \"http://an.invalid\";\n\n  function normalizeBasePath(raw: string): string {\n    if (!raw || raw === \"/\") return \"\";\n    var trimmed = String(raw).replace(/^\\/+/, \"\").replace(/\\/+$/, \"\");\n    return trimmed ? \"/\" + trimmed : \"\";\n  }\n\n  var base = normalizeBasePath(basePath);\n\n  function hasControlCharacter(value: string): boolean {\n    for (var i = 0; i < value.length; i++) {\n      var code = value.charCodeAt(i);\n      if (code < 0x20 || code === 0x7f) return true;\n    }\n    return false;\n  }\n\n  function isAuthEntryPath(pathname: string): boolean {\n    // Suffix match rather than equality so this holds under any base path,\n    // including one this process was not configured with (a workspace host\n    // serving a sibling app's URL).\n    if (\n      pathname === ENTRY_PATH ||\n      pathname.slice(-ENTRY_PATH.length) === ENTRY_PATH\n    ) {\n      return true;\n    }\n    var rest = pathname;\n    if (base) {\n      if (rest === base) rest = \"/\";\n      else if (rest.slice(0, base.length + 1) === base + \"/\")\n        rest = rest.slice(base.length);\n    }\n    return rest === \"/login\" || rest === \"/signup\";\n  }\n\n  /**\n   * The shared validator. Returns a full same-origin app path, or `null` —\n   * never `\"/\"`, so an invalid continuation stays distinguishable from a\n   * genuine request for the home page. Callers that want a fallback write it\n   * at the call site.\n   */\n  function normalizeAppPath(raw: string | null | undefined): string | null {\n    if (typeof raw !== \"string\" || !raw) return null;\n    // Header/URL injection: a `\\r\\n` reaching a `Location` splits the response.\n    if (hasControlCharacter(raw)) return null;\n    if (raw.charAt(0) !== \"/\") return null;\n    // Scheme-relative, plus the backslash form WHATWG normalizes to `//`.\n    if (raw.charAt(1) === \"/\" || raw.charAt(1) === \"\\\\\") return null;\n    var parsed;\n    try {\n      parsed = new URL(raw, SENTINEL);\n    } catch (e) {\n      return null;\n    }\n    // Catches everything WHATWG normalizes that prefix checks miss. This is\n    // why prefix checks alone are insufficient.\n    if (parsed.origin !== SENTINEL) return null;\n    var pathname = parsed.pathname || \"/\";\n    // WHATWG path normalization can turn traversal such as `/..//host` into\n    // `//host`; validate the normalized path before returning it to a redirect\n    // sink.\n    if (pathname.startsWith(\"//\")) return null;\n    if (isAuthEntryPath(pathname)) return null;\n    // Containment in this app's own base path. On a multi-app workspace host\n    // `/otherapp/admin` is same-origin but is NOT this app, so this is the\n    // only control that makes an unsigned path-only token safe there. `base`\n    // is resolved from configured env / `appBasePath()` and NEVER from the\n    // continuation itself.\n    if (\n      base &&\n      pathname !== base &&\n      pathname.slice(0, base.length + 1) !== base + \"/\"\n    ) {\n      return null;\n    }\n    return pathname + parsed.search + parsed.hash;\n  }\n\n  function encodeContinuation(path: string | null | undefined): string {\n    var normalized = normalizeAppPath(path);\n    if (!normalized) return \"\";\n    var token;\n    try {\n      // encodeURIComponent first so the input to btoa is pure ASCII; the pair\n      // round-trips any UTF-8 exactly.\n      token = btoa(encodeURIComponent(normalized))\n        .replace(/\\+/g, \"-\")\n        .replace(/\\//g, \"_\")\n        .replace(/=+$/, \"\");\n    } catch (e) {\n      return \"\";\n    }\n    return token.length > MAX_TOKEN ? \"\" : token;\n  }\n\n  function decodeContinuation(token: string | null | undefined): string | null {\n    if (typeof token !== \"string\" || !token) return null;\n    if (token.length > MAX_TOKEN) return null;\n    var decoded;\n    try {\n      var b64 = token.replace(/-/g, \"+\").replace(/_/g, \"/\");\n      while (b64.length % 4 !== 0) b64 += \"=\";\n      decoded = decodeURIComponent(atob(b64));\n    } catch (e) {\n      return null;\n    }\n    // Re-validated on decode: a user can paste any `c`, so encode-time\n    // validation is never trusted here.\n    return normalizeAppPath(decoded);\n  }\n\n  function homeHref(): string {\n    return base || \"/\";\n  }\n\n  function signInJourney(input: {\n    at: string;\n    continuation?: string | null;\n    legacyReturn?: string | null;\n  }) {\n    var here = normalizeAppPath(input.at);\n    var resume =\n      decodeContinuation(input.continuation) ??\n      normalizeAppPath(input.legacyReturn) ??\n      here ??\n      homeHref();\n    var signInHref = null as string | null;\n    if (here !== null) {\n      var token = encodeContinuation(here);\n      signInHref = base + ENTRY_PATH + (token ? \"?\" + PARAM + \"=\" + token : \"\");\n    }\n    return { signInHref: signInHref, resumeHref: resume };\n  }\n\n  /** Read a query param out of a raw `?a=b` / `a=b` search string. */\n  function readParam(search: string, name: string): string | null {\n    try {\n      return new URLSearchParams(search || \"\").get(name);\n    } catch (e) {\n      return null;\n    }\n  }\n\n  function journeyForLocation(location: {\n    pathname: string;\n    search: string;\n    hash: string;\n  }) {\n    return signInJourney({\n      at:\n        (location.pathname || \"/\") +\n        (location.search || \"\") +\n        (location.hash || \"\"),\n      continuation: readParam(location.search, PARAM),\n      legacyReturn: readParam(location.search, LEGACY_PARAM),\n    });\n  }\n\n  return {\n    PARAM: PARAM,\n    LEGACY_PARAM: LEGACY_PARAM,\n    basePath: base,\n    homeHref: homeHref,\n    normalizeAppPath: normalizeAppPath,\n    encodeContinuation: encodeContinuation,\n    decodeContinuation: decodeContinuation,\n    signInJourney: signInJourney,\n    journeyForLocation: journeyForLocation,\n  };\n}\n\ntype SignInJourneyRuntime = ReturnType<typeof createSignInJourneyRuntime>;\n\nconst runtimeCache = new Map<string, SignInJourneyRuntime>();\n\nfunction runtime(basePath: string | undefined): SignInJourneyRuntime {\n  const key = basePath ?? \"\";\n  let cached = runtimeCache.get(key);\n  if (!cached) {\n    cached = createSignInJourneyRuntime(key);\n    runtimeCache.set(key, cached);\n  }\n  return cached;\n}\n\n/**\n * Validate a candidate app path. Returns the normalised full path (base path\n * included) or `null`. Pass `basePath` to additionally require containment —\n * omit it for surfaces such as provider OAuth returns whose targets are not\n * guaranteed to be base-path prefixed.\n */\nexport function normalizeAppPath(\n  raw: string | null | undefined,\n  basePath = \"\",\n): string | null {\n  return runtime(basePath).normalizeAppPath(raw);\n}\n\n/** Encode an app path as a continuation token. `\"\"` for anything not returnable. */\nexport function encodeContinuation(\n  path: string | null | undefined,\n  basePath = \"\",\n): string {\n  return runtime(basePath).encodeContinuation(path);\n}\n\n/** Decode a continuation token to an app path. `null` for anything invalid. */\nexport function decodeContinuation(\n  token: string | null | undefined,\n  basePath = \"\",\n): string | null {\n  return runtime(basePath).decodeContinuation(token);\n}\n\nexport function signInJourney(input: SignInJourneyInput): SignInJourney {\n  return runtime(input.basePath).signInJourney(input);\n}\n\n/**\n * The runtime as `<script>`-embeddable source declaring\n * `__anCreateSignInJourney(basePath)`.\n *\n * Emitted from the same function the server and client call, so the login\n * document cannot drift from the module — which is exactly how the repo ended\n * up with two login pages disagreeing about return paths in the first place.\n * `packages/core` builds with plain `tsc` (no bundler, no minifier), so the\n * emitted source is verbatim; `createSignInJourneyRuntime` must therefore stay\n * self-contained, ES5-compatible, and free of references to module scope.\n */\nexport function signInJourneyInlineScript(): string {\n  return `var __anCreateSignInJourney = ${createSignInJourneyRuntime.toString()};`;\n}\n"]}

package/dist/styles/agent-native.css

@@ -27,6 +27,14 @@
 @import "./blocks.css";
 @import "./chat-history-list.css";
 
+/* Core's own client components (settings, TeamPage, share dialogs, …) render
+   @agent-native/toolkit UI, so the toolkit's @source registration belongs here
+   rather than in each app's global.css. Without it Tailwind never generates the
+   classes that appear only inside toolkit components — including the `z-[290]`
+   on portaled dropdown/select/popover content — and those menus render behind
+   raised app surfaces. Apps that import this stylesheet get it for free. */
+@import "@agent-native/toolkit/styles.css";
+
 /* Scan @agent-native/core's compiled client output for Tailwind classes.
    Path is resolved relative to THIS file. After build, this CSS lives at
    dist/styles/agent-native.css, so `../client/**` resolves to dist/client/**. */

package/dist/templates/chat/.agents/skills/actions/SKILL.md

@@ -18,6 +18,8 @@ Actions in `actions/` are the **single source of truth** for app operations. The
 
 Before creating any custom REST/API route for app data, inspect `actions/` and the action table in `AGENTS.md`. If an action already exists, call it directly from the agent or with `useActionQuery` / `useActionMutation` from the UI. If the capability is missing, create or update a `defineAction`. Do not add `/api/*`, `server/routes/*`, or other pass-through endpoints whose main job is to call, repackage, or re-export an action.
 
+**Stop trigger:** the moment you are about to create a file under `server/routes/api/` — or add server middleware to guard one — stop and check it against the exception list in *When You Still Need Custom `/api/` Routes* below. If it is not on that list, write a `defineAction` instead. This applies even when you already started the route; abandoning a half-written action to hand-roll routes is the exact failure this rule exists to prevent.
+
 ## Why
 
 Actions give the agent callable tools with structured input/output, AND they give the frontend a typed client contract through hooks. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.
@@ -390,12 +392,28 @@ This is the canonical approach for new apps. Action names must be lowercase with
 
 ## When You Still Need Custom `/api/` Routes
 
-Most operations should be actions. You only need custom routes in `server/routes/api/` for:
+This is the complete exception list. A route in `server/routes/api/` is only
+justified when the caller is not your own UI or agent, or when the payload is
+not JSON:
 
 - **File uploads** — actions receive JSON params, not multipart form data
 - **Streaming responses** — SSE or chunked responses that need direct H3 control
 - **Webhooks** — external services POST to a specific URL
 - **OAuth callbacks** — redirect-based flows that need specific URL patterns
+- **Public unauthenticated endpoints** — SEO/OG images, share links, and other
+  URLs opened directly by a browser or crawler
+- **Binary or non-JSON responses** — media, exports, generated assets
+
+Everything else is an action: CRUD, settings, search, list/detail reads, auth
+state, and anything the UI fetches as JSON. If a route needs new middleware to
+scope it to the current user, that is a signal it should be an action — actions
+already run inside request context with access checks.
+
+Existing first-party templates still contain a shrinking, explicitly
+grandfathered set of older `/api/*` CRUD routes for app data. The repository's
+`guard:no-action-twin-routes` CI check ratchets that baseline down across the
+first-party template route trees (with the separately owned Plan template
+fenced out); it is not a substitute for keeping generated apps action-first.
 
 When the agent needs a durable image or file URL, call the core `upload-image`
 action or use `uploadFile()` in server code. Do not write base64 into SQL,

package/dist/templates/chat/.agents/skills/adding-a-feature/SKILL.md

@@ -14,6 +14,8 @@ metadata:
 
 Every new feature MUST update all four areas. Skipping any one breaks the agent-native contract — the agent and UI must always be equal partners.
 
+Scope check first: this is the checklist for a feature that adds app data or a new capability. A restyle, a copy change, or a screen with no new data model and no new agent-visible operation only needs the areas it actually touches — do not manufacture actions, state keys, or a skill for it.
+
 ## Why
 
 Agent-native apps are defined by parity: everything the UI can do, the agent can do, and vice versa. A feature that only has UI is invisible to the agent. A feature that only has scripts is invisible to the user. A feature without app-state sync means the agent is blind to what the user is doing.

package/dist/templates/chat/.agents/skills/frontend-design/SKILL.md

@@ -1,14 +1,17 @@
 ---
 name: frontend-design
 description: >-
-  Create distinctive, production-grade frontend interfaces with high design
-  quality. Use when building web components, pages, artifacts, posters, or
-  applications (websites, landing pages, dashboards, React components,
-  HTML/CSS layouts, or when styling/beautifying any web UI). Generates
-  creative, polished UI that avoids generic AI aesthetics.
+  Sets the visual direction for a new or redesigned surface, with production
+  quality that avoids generic AI aesthetics. Use when building a new page,
+  app, or marketing surface, defining visual identity, or doing a design pass
+  ("make this look good"). Do not load it for routine UI edits: adding a field
+  to an existing form, fixing spacing, wiring a button, or changing copy.
 scope: dev
 license: Complete terms in LICENSE.txt
 source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
+local-changes: >-
+  Description narrowed and Verification rescoped deliberately; an upstream sync
+  must not restore the broad auto-load triggers or screenshot-everything step.
 metadata:
   internal: true
 ---
@@ -141,11 +144,22 @@ Avoid:
 
 ## Verification
 
+Match verification effort to the size of the change. For one component, one
+form, one page, or a restyle, run the app's existing checks — formatter,
+`pnpm typecheck`, existing tests — and stop there.
+
+Escalate to browser verification only when the user asks for it, or when the
+change is a multi-step user-visible flow that cannot be confirmed any other
+way. Never author a new Playwright/Puppeteer script, add a browser-automation
+dependency, or stand up an e2e harness to check work the user did not ask you
+to test that way; use an available browser tool, or say what you could not
+verify.
+
 For substantial frontend work:
 
 1. Run the relevant formatter/checks.
 2. Start the dev server when the app needs one.
-3. Verify with browser screenshots at desktop and mobile widths.
+3. Verify with the available browser tooling at desktop and mobile widths.
 4. Check interactive states: hover, focus, loading, empty, error, and destructive confirmations.
 5. When registering or changing a company adapter, run
    `@agent-native/toolkit/conformance`, including mixed-overlay focus,

package/dist/templates/chat/.agents/skills/security/SKILL.md

@@ -127,6 +127,8 @@ Two more CI guards (also wired into `pnpm prep`) target the 2026-04 cross-tenant
 - `scripts/guard-no-env-mutation.mjs` — bans `process.env.<KEY> = …` (and bracket / compound forms) anywhere in production code. On serverless, every warm container handles many concurrent requests in one Node process, so `process.env` mutation leaks across in-flight requests (the "restore" line at the end of a handler races and never helps — most recently the Zoom webhook). Use `runWithRequestContext({ userEmail, orgId, timezone }, fn)` from `@agent-native/core/server` instead — it's AsyncLocalStorage-backed and per-request safe. Allowlisted paths: `scripts/`, `*.spec.ts` / `*.test.ts`, `packages/core/src/dev**`, `templates/*/test/`, anything under `/cli/` or `/scaffold/`. Per-line opt-out: `process.env.X = y // guard:allow-env-mutation — <reason>`.
 - `scripts/guard-no-localhost-fallback.mjs` — bans the literal `"local@localhost"` / `'local@localhost'` / `` `local@localhost` `` in production code. The bug class: `getRequestUserEmail() ?? "local@localhost"` silently pools every unauthenticated request into a single shared tenant, leaking credentials, tools, and `application_state` rows between accounts. The right behavior is to throw / 401 when there's no session. Allowlisted paths: the dev-mode auth shim (`packages/core/src/server/auth.ts`), `packages/core/src/dev**`, tests, `scripts/`, `seed/` / `seeds/`, plus a few framework helpers that intentionally inspect or migrate the dev identity. SQL DDL `DEFAULT 'local@localhost'` and the Drizzle helper `.default('local@localhost')` are skipped per-line — schema column defaults are intentional dev fixtures, not the dangerous fallback pattern. Per-line opt-out: `email ?? "local@localhost" // guard:allow-localhost-fallback — <reason>`.
 
+  The same guard also bans the **ambient process identity** as a request-scoped fallback: `?? process.env.AGENT_USER_EMAIL`, `|| process.env.WORKSPACE_OWNER_EMAIL`, and `?? getAmbientUserEmail()`. Those name the identity of the *deployment*, not the caller, so a handler reading one authorizes whoever the deploy env names rather than whoever signed in — it fails open toward more privilege. Exempt paths are the ones with no request by construction: `scripts/` (including `templates/*/scripts/`), `src/cli/`, `src/scripts/`, `script-helpers.ts` / `script-entries.ts`, tests, and seeds. It deliberately matches only the `??` / `||` fallback position, so reading the same env var to build an admin allowlist (`envEmails("WORKSPACE_OWNER_EMAIL").includes(email)`) is untouched. Known gaps, both requiring dataflow analysis the guard does not do: an env read aliased through a local (`const fallback = process.env.AGENT_USER_EMAIL; … ?? fallback`) and a destructured `const { AGENT_USER_EMAIL } = process.env`.
+
 ## Auth
 
 - All actions are protected by the auth guard automatically.

package/dist/templates/chat/.agents/skills/self-modifying-code/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: self-modifying-code
 description: >-
-  How the agent can modify the app's own source code. Use when the agent needs
-  to edit components, routes, styles, or scripts, when designing UI for agent
-  editability, or when deciding what the agent should and shouldn't modify.
+  Tiers, checkpoints, and off-limits paths for an agent editing the app's own
+  source. Use when designing UI for agent editability, deciding whether a file
+  is safe for the agent to change, or when tempted to patch config, `.env`, or
+  an `@agent-native/*` package. Do not load it for ordinary source edits.
 scope: dev
 metadata:
   internal: true

package/dist/templates/chat/.agents/skills/shadcn-ui/SKILL.md

@@ -1,11 +1,15 @@
 ---
 name: shadcn-ui
 description: >-
-  Use when adding, updating, debugging, styling, or composing shadcn/ui
-  components, forms, dialogs, menus, charts, sidebars, themes, registries, or
-  any project with a components.json file.
+  The shadcn CLI, component composition, theming, and registry workflow. Use
+  when adding, replacing, upgrading, or debugging a shadcn/ui primitive itself,
+  or when changing a theme or registry. Do not load it for ordinary edits to a
+  file that happens to import a shadcn component.
 scope: dev
 source: https://ui.shadcn.com/docs/skills
+local-changes: >-
+  Description narrowed deliberately; an upstream sync must not restore the
+  "any project with a components.json file" trigger.
 metadata:
   internal: true
 ---