@agent-native/core 0.127.3 → 0.128.1

package/corpus/templates/design/app/pages/DesignSystemSetup.tsx

@@ -1,4 +1,3 @@
-import { appApiPath } from "@agent-native/core/client/api-path";
 import { useActionQuery } from "@agent-native/core/client/hooks";
 import { useT } from "@agent-native/core/client/i18n";
 import { openAgentSidebar } from "@agent-native/core/client/navigation";
@@ -30,6 +29,11 @@ import { Input } from "@/components/ui/input";
 import { Spinner } from "@/components/ui/spinner";
 import { Textarea } from "@/components/ui/textarea";
 import { sendToDesignAgentChat } from "@/lib/agent-chat";
+import {
+  uploadAndIndexFigmaFiles,
+  pollDecodeJobStatus,
+  type DecodeJobStatus,
+} from "@/lib/builder-design-system-upload";
 
 interface GitHubLink {
   id: string;
@@ -58,20 +62,6 @@ interface BuilderIndexResult {
   instructions?: string;
 }
 
-async function readJsonResponse(res: Response): Promise<any> {
-  const text = await res.text();
-  if (!text.trim()) return {};
-  try {
-    return JSON.parse(text);
-  } catch {
-    return {
-      error: res.ok
-        ? "The server returned an invalid response."
-        : text.slice(0, 240),
-    };
-  }
-}
-
 export default function DesignSystemSetup() {
   const t = useT();
   const navigate = useNavigate();
@@ -117,6 +107,62 @@ export default function DesignSystemSetup() {
   const [builderIndexError, setBuilderIndexError] = useState<string | null>(
     null,
   );
+  const [decodeStatus, setDecodeStatus] = useState<DecodeJobStatus | null>(
+    null,
+  );
+  const decodePollRef = useRef<AbortController | null>(null);
+
+  const stopDecodePolling = useCallback(() => {
+    decodePollRef.current?.abort();
+    decodePollRef.current = null;
+  }, []);
+
+  useEffect(() => stopDecodePolling, [stopDecodePolling]);
+
+  const startDecodePolling = useCallback(
+    (jobId: string, indexResult: BuilderIndexResult) => {
+      decodePollRef.current?.abort();
+      const controller = new AbortController();
+      decodePollRef.current = controller;
+      setDecodeStatus({
+        status: "pending",
+        branchUrl: null,
+        error: null,
+        framesProcessed: 0,
+        totalFrames: 0,
+      });
+      pollDecodeJobStatus(jobId, {
+        signal: controller.signal,
+        onUpdate: (status) => {
+          if (!controller.signal.aborted) setDecodeStatus(status);
+        },
+      })
+        .then((status) => {
+          if (controller.signal.aborted) return;
+          setDecodeStatus(status);
+          setBuilderIndexResult(
+            status.branchUrl
+              ? { ...indexResult, builderUrl: status.branchUrl }
+              : indexResult,
+          );
+          setBuilderIndexing(false);
+        })
+        .catch((err: unknown) => {
+          if (controller.signal.aborted) return;
+          if (err instanceof DOMException && err.name === "AbortError") return;
+          setDecodeStatus((prev) => ({
+            status: "error",
+            branchUrl: prev?.branchUrl ?? null,
+            error: err instanceof Error ? err.message : String(err),
+            framesProcessed: prev?.framesProcessed ?? 0,
+            totalFrames: prev?.totalFrames ?? 0,
+          }));
+          setBuilderIndexResult(indexResult);
+          setBuilderIndexing(false);
+        });
+    },
+    [],
+  );
 
   const handleBuilderIndexUpload = useCallback(
     async (e: React.ChangeEvent<HTMLInputElement>) => {
@@ -129,33 +175,35 @@ export default function DesignSystemSetup() {
       }
       setBuilderIndexError(null);
       setBuilderIndexResult(null);
+      stopDecodePolling();
+      setDecodeStatus(null);
       setBuilderIndexing(true);
       try {
-        const body = new FormData();
-        body.append("file", file);
-        const res = await fetch(
-          appApiPath("/api/index-design-system-with-builder"),
-          {
-            method: "POST",
-            body,
-          },
-        );
-        const json = await readJsonResponse(res);
-        if (!res.ok || json?.error) {
-          throw new Error(json?.error || `Upload failed (${res.status})`);
+        const suggestedTitle =
+          file.name
+            .replace(/\.fig$/i, "")
+            .replace(/[-_]+/g, " ")
+            .trim() || "Imported brand";
+        const json = await uploadAndIndexFigmaFiles([file], {
+          projectName: suggestedTitle,
+        });
+        const parsed = json as unknown as BuilderIndexResult;
+        if (parsed.jobId) {
+          startDecodePolling(parsed.jobId, parsed);
+        } else {
+          setBuilderIndexResult(parsed);
+          setBuilderIndexing(false);
         }
-        setBuilderIndexResult(json as BuilderIndexResult);
       } catch (err) {
         setBuilderIndexError(
           err instanceof Error
             ? err.message
             : t("designSystemSetup.errors.parseFig"),
         );
-      } finally {
         setBuilderIndexing(false);
       }
     },
-    [t],
+    [t, startDecodePolling, stopDecodePolling],
   );
 
   useEffect(() => {
@@ -606,7 +654,10 @@ export default function DesignSystemSetup() {
               ) : (
                 <BuilderIndexPreview
                   result={builderIndexResult}
+                  decodeStatus={decodeStatus}
                   onReset={() => {
+                    stopDecodePolling();
+                    setDecodeStatus(null);
                     setBuilderIndexResult(null);
                     setBuilderIndexError(null);
                   }}
@@ -1076,12 +1127,16 @@ function FileList({
 
 function BuilderIndexPreview({
   result,
+  decodeStatus,
   onReset,
 }: {
   result: BuilderIndexResult;
+  decodeStatus: DecodeJobStatus | null;
   onReset: () => void;
 }) {
   const t = useT();
+  const decodeError =
+    decodeStatus?.status === "error" ? decodeStatus.error : null;
 
   return (
     <div className="space-y-4 rounded-xl border border-border bg-card p-4">
@@ -1101,30 +1156,11 @@ function BuilderIndexPreview({
         </div>
       </div>
 
-      <dl className="grid grid-cols-[112px_minmax(0,1fr)] gap-x-3 gap-y-2 rounded-lg border border-border bg-muted/25 p-3 text-xs">
-        <dt className="text-muted-foreground">
-          {"Status" /* i18n-ignore Builder indexing field */}
-        </dt>
-        <dd className="font-medium text-foreground">{result.status}</dd>
-        <dt className="text-muted-foreground">
-          {"Project" /* i18n-ignore Builder indexing field */}
-        </dt>
-        <dd className="truncate font-mono !text-[11px] text-foreground/80">
-          {result.projectId}
-        </dd>
-        <dt className="text-muted-foreground">
-          {"Job" /* i18n-ignore Builder indexing field */}
-        </dt>
-        <dd className="truncate font-mono !text-[11px] text-foreground/80">
-          {result.jobId}
-        </dd>
-        <dt className="text-muted-foreground">
-          {"Design system" /* i18n-ignore Builder indexing field */}
-        </dt>
-        <dd className="truncate font-mono !text-[11px] text-foreground/80">
-          {result.designSystemId}
-        </dd>
-      </dl>
+      {decodeError ? (
+        <p role="alert" className="text-xs text-destructive">
+          {t("designSystemSetup.figmaDecodeFailed", { error: decodeError })}
+        </p>
+      ) : null}
 
       <div className="flex items-center gap-2 border-t border-border pt-4">
         {result.builderUrl ? (

package/corpus/templates/design/app/root.tsx

@@ -13,7 +13,12 @@ import {
   useCommandMenuShortcut,
 } from "@agent-native/core/client/navigation";
 import { getThemeInitScript } from "@agent-native/core/client/ui";
-import { IconHierarchy2, IconSun, IconMoon } from "@tabler/icons-react";
+import {
+  IconArrowsMaximize,
+  IconHierarchy2,
+  IconSun,
+  IconMoon,
+} from "@tabler/icons-react";
 import { useQueryClient } from "@tanstack/react-query";
 import { useTheme } from "next-themes";
 import { useCallback, useState } from "react";
@@ -31,6 +36,7 @@ import type { LinksFunction } from "react-router";
 import { Layout as AppLayout } from "@/components/layout/Layout";
 import { Toaster } from "@/components/ui/sonner";
 import { AppToolkitProvider } from "@/components/ui/toolkit-provider";
+import { requestDesignUiToggle } from "@/lib/design-ui-events";
 
 import changelog from "../CHANGELOG.md?raw";
 import { i18nCatalog } from "./i18n";
@@ -128,7 +134,9 @@ function DesignCommandMenu({
   onOpenChange: (open: boolean) => void;
 }) {
   const t = useT();
+  const location = useLocation();
   const navigate = useNavigate();
+  const isDesignEditor = location.pathname.startsWith("/design/");
   return (
     <CommandMenu
       open={open}
@@ -146,6 +154,15 @@ function DesignCommandMenu({
         </CommandMenu.Item>
       </CommandMenu.Group>
       <CommandMenu.Group heading={t("root.commandAppearance")}>
+        {isDesignEditor ? (
+          <CommandMenu.Item
+            onSelect={requestDesignUiToggle}
+            keywords={["canvas", "focus", "panels", "hide ui", "show ui"]}
+          >
+            <IconArrowsMaximize size={16} />
+            {t("designEditor.keyboardShortcuts.commands.toggleUi")}
+          </CommandMenu.Item>
+        ) : null}
         <ThemeToggleItem />
       </CommandMenu.Group>
     </CommandMenu>

package/corpus/templates/design/changelog/2026-07-28-figma-fig-uploads-now-show-indexing-progress-and-an-open-in-.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-28
+---
+
+Figma .fig uploads now show indexing progress and an Open in Builder link to the generated project once decoding finishes.

package/corpus/templates/design/changelog/2026-07-28-show-or-hide-design-editing-chrome-with-cmd-on-apple-devices.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-28
+---
+
+Show or hide Design editing chrome from Cmd+K, the canvas menu, or Cmd/Ctrl+Shift+\.

package/corpus/templates/design/server/handlers/design-system-decode-job-status.ts

@@ -0,0 +1,49 @@
+import {
+  FeatureNotConfiguredError,
+  fetchBuilderDesignSystemDecodeJobStatus,
+  getSession,
+  runWithRequestContext,
+} from "@agent-native/core/server";
+import { defineEventHandler, getQuery, setResponseStatus } from "h3";
+
+/**
+ * Reads a Builder design-system decode job's status. The UI polls this after
+ * `/api/index-design-system-sources` returns a jobId, until the `.fig` decode
+ * job leaves `pending` and exposes a `branchUrl` (or reports an `error`).
+ */
+export const designSystemDecodeJobStatus = defineEventHandler(async (event) => {
+  const session = await getSession(event).catch(() => null);
+  if (!session?.email) {
+    setResponseStatus(event, 401);
+    return { error: "Unauthorized" };
+  }
+
+  const jobId = getQuery(event).jobId;
+  if (typeof jobId !== "string" || !jobId.trim()) {
+    setResponseStatus(event, 400);
+    return { error: "jobId is required." };
+  }
+
+  try {
+    return await runWithRequestContext(
+      { userEmail: session.email, orgId: session.orgId },
+      () => fetchBuilderDesignSystemDecodeJobStatus(jobId.trim()),
+    );
+  } catch (err) {
+    if (err instanceof FeatureNotConfiguredError) {
+      setResponseStatus(event, 412);
+      return {
+        error: err.message,
+        builderConnectUrl:
+          err.builderConnectUrl ?? "/_agent-native/builder/connect",
+      };
+    }
+    setResponseStatus(event, 502);
+    return {
+      error:
+        err instanceof Error
+          ? err.message
+          : "Failed to read decode job status.",
+    };
+  }
+});

package/corpus/templates/design/server/handlers/design-system-upload-start.ts

@@ -0,0 +1,87 @@
+import {
+  FeatureNotConfiguredError,
+  getSession,
+  runWithRequestContext,
+  startBuilderDesignSystemUpload,
+} from "@agent-native/core/server";
+import { defineEventHandler, readBody, setResponseStatus } from "h3";
+
+const MAX_FIG_BYTES = 512 * 1024 * 1024;
+
+interface AttachmentInput {
+  name?: unknown;
+  mimetype?: unknown;
+  declaredSize?: unknown;
+}
+
+/**
+ * Opens signed resumable-upload slots so the browser can stream large `.fig`
+ * bytes straight to storage. Only small JSON metadata rides through the app
+ * server; the file bytes never do.
+ */
+export const designSystemUploadStart = defineEventHandler(async (event) => {
+  const session = await getSession(event).catch(() => null);
+  if (!session?.email) {
+    setResponseStatus(event, 401);
+    return { error: "Unauthorized" };
+  }
+
+  const body = (await readBody(event).catch(() => null)) as {
+    attachments?: AttachmentInput[];
+  } | null;
+  const rawList = Array.isArray(body?.attachments) ? body.attachments : [];
+  if (rawList.length === 0) {
+    setResponseStatus(event, 400);
+    return { error: "No attachments provided." };
+  }
+
+  const attachments: {
+    name: string;
+    mimetype: string;
+    declaredSize: number;
+  }[] = [];
+  for (const raw of rawList) {
+    const name = typeof raw?.name === "string" ? raw.name.trim() : "";
+    const mimetype =
+      typeof raw?.mimetype === "string" && raw.mimetype.trim()
+        ? raw.mimetype.trim()
+        : "application/octet-stream";
+    const declaredSize = Number(raw?.declaredSize);
+    if (!name) {
+      setResponseStatus(event, 400);
+      return { error: "Attachment name is required." };
+    }
+    if (!Number.isSafeInteger(declaredSize) || declaredSize <= 0) {
+      setResponseStatus(event, 400);
+      return { error: "Attachment declaredSize must be a positive integer." };
+    }
+    if (declaredSize > MAX_FIG_BYTES) {
+      setResponseStatus(event, 413);
+      return {
+        error: `File too large (max ${Math.round(MAX_FIG_BYTES / 1024 / 1024)} MB).`,
+      };
+    }
+    attachments.push({ name, mimetype, declaredSize });
+  }
+
+  try {
+    const uploads = await runWithRequestContext(
+      { userEmail: session.email, orgId: session.orgId },
+      () => startBuilderDesignSystemUpload(attachments),
+    );
+    return { uploads };
+  } catch (err) {
+    if (err instanceof FeatureNotConfiguredError) {
+      setResponseStatus(event, 412);
+      return {
+        error: err.message,
+        builderConnectUrl:
+          err.builderConnectUrl ?? "/_agent-native/builder/connect",
+      };
+    }
+    setResponseStatus(event, 502);
+    return {
+      error: err instanceof Error ? err.message : "Failed to start upload.",
+    };
+  }
+});

package/corpus/templates/design/server/handlers/index-design-system-sources.ts

@@ -0,0 +1,82 @@
+import {
+  FeatureNotConfiguredError,
+  getSession,
+  indexBuilderDesignSystem,
+  runWithRequestContext,
+} from "@agent-native/core/server";
+import { defineEventHandler, readBody, setResponseStatus } from "h3";
+
+import { upsertBuilderProxyDesignSystem } from "../lib/builder-design-system-proxy.js";
+
+/**
+ * Finalizes Builder DSI indexing from upload tokens produced by the
+ * browser-streamed resumable upload. The file bytes were streamed straight to
+ * storage; this endpoint only forwards the opaque tokens.
+ */
+export const indexDesignSystemSources = defineEventHandler(async (event) => {
+  const session = await getSession(event).catch(() => null);
+  if (!session?.email) {
+    setResponseStatus(event, 401);
+    return { error: "Unauthorized" };
+  }
+
+  const body = (await readBody(event).catch(() => null)) as {
+    projectName?: unknown;
+    uploadTokens?: unknown;
+  } | null;
+  const uploadTokens = Array.isArray(body?.uploadTokens)
+    ? body.uploadTokens.filter(
+        (token): token is string =>
+          typeof token === "string" && token.length > 0,
+      )
+    : [];
+  if (uploadTokens.length === 0) {
+    setResponseStatus(event, 400);
+    return { error: "No uploaded files to index." };
+  }
+  const projectName =
+    typeof body?.projectName === "string"
+      ? body.projectName.trim() || undefined
+      : undefined;
+
+  const sources = uploadTokens.map((uploadToken) => ({
+    kind: "file" as const,
+    uploadToken,
+  }));
+
+  try {
+    return await runWithRequestContext(
+      { userEmail: session.email, orgId: session.orgId },
+      async () => {
+        const result = await indexBuilderDesignSystem({ sources, projectName });
+        const proxy = await upsertBuilderProxyDesignSystem({
+          result,
+          ownerEmail: session.email,
+          orgId: session.orgId ?? null,
+          projectName,
+        });
+        return {
+          ...result,
+          ...proxy,
+          uploadedFileCount: uploadTokens.length,
+        };
+      },
+    );
+  } catch (err) {
+    if (err instanceof FeatureNotConfiguredError) {
+      setResponseStatus(event, 412);
+      return {
+        error: err.message,
+        builderConnectUrl:
+          err.builderConnectUrl ?? "/_agent-native/builder/connect",
+      };
+    }
+    setResponseStatus(event, 502);
+    return {
+      error:
+        err instanceof Error
+          ? err.message
+          : "Builder design-system indexing failed.",
+    };
+  }
+});

package/corpus/templates/design/server/routes/api/design-system-decode-job-status.get.ts

@@ -0,0 +1 @@
+export { designSystemDecodeJobStatus as default } from "../../handlers/design-system-decode-job-status";

package/corpus/templates/design/server/routes/api/design-system-upload-start.post.ts

@@ -0,0 +1 @@
+export { designSystemUploadStart as default } from "../../handlers/design-system-upload-start";

package/corpus/templates/design/server/routes/api/index-design-system-sources.post.ts

@@ -0,0 +1 @@
+export { indexDesignSystemSources as default } from "../../handlers/index-design-system-sources";

package/corpus/templates/dispatch/.agents/skills/actions/SKILL.md

@@ -305,6 +305,38 @@ export default defineAction({
 
 On success the validated value is returned, so coercion/defaults on `outputSchema` apply. Omit `outputSchema` and behavior is byte-for-byte unchanged (no wrapping).
 
+### Authorization (`authorize`)
+
+`authorize` decides whether the caller may run the action at all. It wraps
+`run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
+hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
+agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
+to ask a human to bless one call a permitted caller is already allowed to make.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+The wrappers compose as `validate input -> authorize -> run -> validate output
+-> audit`: the gate sits inside input validation, so a guard reading `args` gets
+the parsed, coerced value, and auditing is outermost, so denials are recorded.
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. A guarded action
+needs a user identity, so an unattended CLI/cron caller with no user email is
+denied. `authorize` gates the operation; `accessFilter` / `assertAccess` still
+scope which rows a permitted caller may touch. See the `authentication` skill
+for `defineAppRoles` and the `sharing` skill for row scoping.
+
 ### Human-in-the-Loop Approval (`needsApproval`)
 
 For high-consequence, outward-facing, hard-to-undo actions (sending an email, charging a card, deleting an account), set `needsApproval` so the agent **cannot** run the action without a human approving the specific call:

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

@@ -159,6 +159,35 @@ whole site. Data scoping lives in actions and API routes; the client gates
 private UI after the shell loads. See the `authentication` skill and
 `guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
 
+**Authorization beyond "is there a session" — `authorize`.** The auth guard only
+proves *someone* is signed in. To restrict an operation to some teammates, set
+`authorize` on the `defineAction`. It wraps `run`, so it applies at every
+dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
+`needsApproval`, which is honoured only in the agent loop.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. Guarded actions need
+a user identity — an unattended CLI/cron caller with no user email is denied.
+
+`authorize` is **not** a substitute for `accessFilter` / `assertAccess`. It
+decides whether this caller may perform the operation at all; `accessFilter` /
+`assertAccess` scope which rows a permitted caller may see or touch. A
+restricted write action needs both. See the `authentication` skill for
+`defineAppRoles` and the `actions` skill for the full surface.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.
@@ -274,6 +303,8 @@ Run `pnpm action db-check-scoping` to verify. Use `--require-org` for multi-org
 - [ ] New env vars in `.env` only, not committed
 - [ ] New user-data tables have `owner_email` column
 - [ ] Custom routes call `getSession` and reject unauthenticated requests
+- [ ] Actions only some teammates may run set `authorize` (in addition to any
+      `accessFilter` / `assertAccess` row scoping)
 
 ## Related Skills
 

package/corpus/templates/dispatch/.agents/skills/sharing/SKILL.md

@@ -34,6 +34,8 @@ Visibility is coarse. Explicit share grants are fine-grained (per user or per or
 - **`editor`** — read + write.
 - **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
 
+There are three role systems and they never imply one another. A share role answers "what may this person do to **one row**". An org role (`org_members.role`) answers "what may this person do to the **team**". An app role (`defineAppRoles`, see the `authentication` skill) answers "what may this person do inside **one app**". A share `admin` is not an app admin and neither is an org admin.
+
 ### Anonymous public URLs stay separate
 
 Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
@@ -137,6 +139,8 @@ export default defineAction({
 
 For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
 
+`authorize` is a different axis, not an alternative: it gates whether the caller may run the operation at all, while `assertAccess` scopes which row they may touch. A write action restricted to some teammates needs both — `authorize: appAccess.requireAny(...)` on the action, `assertAccess` inside `run`.
+
 ## Create actions must set owner
 
 When inserting a new row, fill `ownerEmail` and `orgId` from the request context:

package/corpus/templates/dispatch/_gitignore

@@ -9,8 +9,10 @@ npm-debug.log*
 pnpm-debug.log*
 
 node_modules
+build/
 dist
 dist-ssr
+.output/
 *.local
 
 # Editor directories and files

package/corpus/templates/forms/.agents/skills/actions/SKILL.md

@@ -305,6 +305,38 @@ export default defineAction({
 
 On success the validated value is returned, so coercion/defaults on `outputSchema` apply. Omit `outputSchema` and behavior is byte-for-byte unchanged (no wrapping).
 
+### Authorization (`authorize`)
+
+`authorize` decides whether the caller may run the action at all. It wraps
+`run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
+hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
+agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
+to ask a human to bless one call a permitted caller is already allowed to make.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+The wrappers compose as `validate input -> authorize -> run -> validate output
+-> audit`: the gate sits inside input validation, so a guard reading `args` gets
+the parsed, coerced value, and auditing is outermost, so denials are recorded.
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. A guarded action
+needs a user identity, so an unattended CLI/cron caller with no user email is
+denied. `authorize` gates the operation; `accessFilter` / `assertAccess` still
+scope which rows a permitted caller may touch. See the `authentication` skill
+for `defineAppRoles` and the `sharing` skill for row scoping.
+
 ### Human-in-the-Loop Approval (`needsApproval`)
 
 For high-consequence, outward-facing, hard-to-undo actions (sending an email, charging a card, deleting an account), set `needsApproval` so the agent **cannot** run the action without a human approving the specific call: