@agent-native/core 0.127.3 → 0.128.0

package/corpus/templates/analytics/actions/data-source-status.ts

@@ -87,14 +87,11 @@ export default defineAction({
   run: async (args) => {
     const ctx = tryRequestCredentialContext();
     if (!ctx) {
-      return {
-        error: "missing_api_key",
-        key: "AUTH",
-        label: "Authentication",
-        message: "Sign in to view credential status.",
-        settingsPath: "/data-sources",
-        dataSourcesSetupLink: DATA_SOURCES_SETUP_LINK,
-      };
+      // Returning 200 here let callers read "signed out" as an authoritative
+      // "nothing is configured".
+      throw Object.assign(new Error("Sign in to view credential status."), {
+        statusCode: 401,
+      });
     }
 
     const { configs, known } = resolveCredentialConfigs(args.key);
@@ -195,12 +192,16 @@ export default defineAction({
             workspace.connections,
             workspace.grants,
           );
+        const configured =
+          hasRequiredCredentials ||
+          workspaceConnection.grantState === "connected";
         return {
           provider: provider.provider,
           label: provider.label,
-          configured:
-            hasRequiredCredentials ||
-            workspaceConnection.grantState === "connected",
+          // A failed workspace-connection lookup cannot prove a provider is
+          // disconnected — a workspace-held connection lives in exactly the
+          // data we could not read. Report null, never false.
+          configured: configured ? true : workspace.error ? null : false,
           configuredKeys: configuredProviderKeys,
           missingRequiredKeys,
           optionalKeys,
@@ -231,13 +232,21 @@ export default defineAction({
     const connectedExternalDataSources = configuredDataSources.filter(
       (source) => source.provider !== BUILT_IN_FIRST_PARTY_PROVIDER.provider,
     );
+    const hasUnknownProviderStatus = providers.some(
+      (provider) => provider.configured === null,
+    );
     return {
       // Keep a compact, explicit summary first so models do not infer source
       // availability from the much larger per-credential list below.
       hasConfiguredDataSources: configuredDataSources.length > 0,
       configuredDataSourceCount: configuredDataSources.length,
       configuredDataSources,
-      hasConnectedExternalDataSources: connectedExternalDataSources.length > 0,
+      hasConnectedExternalDataSources:
+        connectedExternalDataSources.length > 0
+          ? true
+          : hasUnknownProviderStatus
+            ? null
+            : false,
       connectedExternalDataSourceCount: connectedExternalDataSources.length,
       dataSourcesSetupLink: DATA_SOURCES_SETUP_LINK,
       credentials: results,

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

@@ -148,18 +148,18 @@
     hsl(var(--foreground) / 0.025) 56%,
     transparent 72%
   );
-  background-size: 220% 100%;
-  animation: dashboard-panel-skeleton-shimmer 2.4s ease-in-out infinite;
+  background-size: 28rem 100%;
+  background-repeat: repeat;
+  animation: dashboard-panel-skeleton-shimmer 2.6s linear infinite;
 }
 
 @keyframes dashboard-panel-skeleton-shimmer {
-  0%,
-  100% {
-    background-position: 120% 0;
+  0% {
+    background-position: 0 0;
   }
 
-  50% {
-    background-position: -120% 0;
+  100% {
+    background-position: 28rem 0;
   }
 }
 

package/corpus/templates/analytics/app/i18n-data.ts

@@ -893,6 +893,9 @@ const enUS = {
     sharedCredentials: "Shared credentials: {{credentials}}",
     ready: "Ready",
     notConfigured: "Not configured",
+    statusUnknown: "Couldn't check connection status",
+    statusUnknownDescription:
+      "The connection status couldn't be read, so this source may already be connected. Reload to check again before adding credentials.",
     back: "Back",
     continue: "Continue",
     saveCredentials: "Save Credentials",
@@ -1356,6 +1359,9 @@ const analyticsSliceTranslations: {
       sharedCredentials: "共享凭证：{{credentials}}",
       ready: "准备好",
       notConfigured: "未配置",
+      statusUnknown: "无法检查连接状态",
+      statusUnknownDescription:
+        "无法读取连接状态，此数据源可能已连接。请重新加载页面确认后再添加凭据。",
       back: "后退",
       continue: "继续",
       saveCredentials: "保存凭证",
@@ -1648,6 +1654,9 @@ const analyticsSliceTranslations: {
       sharedCredentials: "Credenciales compartidas: {{credentials}}",
       ready: "Listo",
       notConfigured: "No configurado",
+      statusUnknown: "No se pudo comprobar el estado de la conexión",
+      statusUnknownDescription:
+        "No se pudo leer el estado de la conexión, así que esta fuente puede estar ya conectada. Vuelve a cargar la página para comprobarlo antes de añadir credenciales.",
       back: "Atrás",
       continue: "Continuar",
       saveCredentials: "Guardar credenciales",
@@ -1957,6 +1966,9 @@ const analyticsSliceTranslations: {
       sharedCredentials: "Identifiants partagés : {{credentials}}",
       ready: "Prêt",
       notConfigured: "Non configuré",
+      statusUnknown: "Impossible de vérifier l'état de la connexion",
+      statusUnknownDescription:
+        "L'état de la connexion n'a pas pu être lu ; cette source est peut-être déjà connectée. Rechargez la page pour vérifier avant d'ajouter des identifiants.",
       back: "Dos",
       continue: "Continuer",
       saveCredentials: "Enregistrer les informations d'identification",
@@ -2264,6 +2276,9 @@ const analyticsSliceTranslations: {
       sharedCredentials: "Gemeinsame Anmeldeinformationen: {{credentials}}",
       ready: "Bereit",
       notConfigured: "Nicht konfiguriert",
+      statusUnknown: "Verbindungsstatus konnte nicht geprüft werden",
+      statusUnknownDescription:
+        "Der Verbindungsstatus konnte nicht gelesen werden, diese Quelle ist möglicherweise bereits verbunden. Lade die Seite neu, um erneut zu prüfen, bevor du Zugangsdaten hinzufügst.",
       back: "Zurück",
       continue: "Weitermachen",
       saveCredentials: "Anmeldeinformationen speichern",
@@ -2568,6 +2583,9 @@ const analyticsSliceTranslations: {
       sharedCredentials: "共有資格情報: {{credentials}}",
       ready: "準備ができて",
       notConfigured: "未設定",
+      statusUnknown: "接続状態を確認できませんでした",
+      statusUnknownDescription:
+        "接続状態を読み取れなかったため、このソースはすでに接続されている可能性があります。認証情報を追加する前に、再読み込みして確認してください。",
       back: "戻る",
       continue: "続く",
       saveCredentials: "認証情報の保存",
@@ -2867,6 +2885,9 @@ const analyticsSliceTranslations: {
       sharedCredentials: "공유 자격 증명: {{credentials}}",
       ready: "준비가 된",
       notConfigured: "구성되지 않음",
+      statusUnknown: "연결 상태를 확인할 수 없습니다",
+      statusUnknownDescription:
+        "연결 상태를 읽을 수 없어 이 소스가 이미 연결되어 있을 수 있습니다. 자격 증명을 추가하기 전에 새로 고쳐 다시 확인하세요.",
       back: "뒤쪽에",
       continue: "계속하다",
       saveCredentials: "자격 증명 저장",
@@ -3163,6 +3184,9 @@ const analyticsSliceTranslations: {
       sharedCredentials: "Credenciais compartilhadas: {{credentials}}",
       ready: "Preparar",
       notConfigured: "Não configurado",
+      statusUnknown: "Não foi possível verificar o status da conexão",
+      statusUnknownDescription:
+        "Não foi possível ler o status da conexão, então esta fonte pode já estar conectada. Recarregue a página para verificar antes de adicionar credenciais.",
       back: "Voltar",
       continue: "Continuar",
       saveCredentials: "Salvar credenciais",
@@ -3464,6 +3488,9 @@ const analyticsSliceTranslations: {
       sharedCredentials: "साझा क्रेडेंशियल: {{credentials}}",
       ready: "तैयार",
       notConfigured: "कॉन्फ़िगर नहीं किया गया",
+      statusUnknown: "कनेक्शन स्थिति जाँची नहीं जा सकी",
+      statusUnknownDescription:
+        "कनेक्शन स्थिति पढ़ी नहीं जा सकी, इसलिए हो सकता है कि यह स्रोत पहले से जुड़ा हो। क्रेडेंशियल जोड़ने से पहले पेज फिर से लोड करके जाँचें।",
       back: "पीछे",
       continue: "जारी रखना",
       saveCredentials: "क्रेडेंशियल सहेजें",
@@ -3756,6 +3783,9 @@ const analyticsSliceTranslations: {
       sharedCredentials: "بيانات الاعتماد المشتركة: {{credentials}}",
       ready: "مستعد",
       notConfigured: "لم يتم تكوينه",
+      statusUnknown: "تعذّر التحقق من حالة الاتصال",
+      statusUnknownDescription:
+        "تعذّرت قراءة حالة الاتصال، لذا قد يكون هذا المصدر متصلاً بالفعل. أعد تحميل الصفحة للتحقق قبل إضافة بيانات الاعتماد.",
       back: "خلف",
       continue: "يكمل",
       saveCredentials: "حفظ بيانات الاعتماد",

package/corpus/templates/analytics/app/lib/data-source-status.ts

@@ -30,7 +30,8 @@ export interface WorkspaceConnectionProviderSummary {
 export interface DataSourceProviderStatus {
   provider: string;
   label: string;
-  configured: boolean;
+  // null when the workspace-connection lookup failed: unreadable, not absent.
+  configured: boolean | null;
   configuredKeys: string[];
   missingRequiredKeys: string[];
   optionalKeys: string[];

package/corpus/templates/analytics/app/pages/DataSources.tsx

@@ -1100,6 +1100,7 @@ function DataSourceCard({
   sharedConnectionStatus,
   envStatus,
   isStatusLoading,
+  statusUnknown,
   onSaved,
 }: {
   source: DataSource;
@@ -1108,6 +1109,7 @@ function DataSourceCard({
   sharedConnectionStatus: SharedConnectionStatus | null;
   envStatus: EnvKeyStatus[];
   isStatusLoading: boolean;
+  statusUnknown: boolean;
   onSaved: () => void;
 }) {
   const t = useT();
@@ -1136,6 +1138,9 @@ function DataSourceCard({
   const readyViaWorkspace = sharedConnectionStatus?.kind === "ready";
   const showCredentialSetup =
     !locallyConfigured && (!readyViaWorkspace || showLocalCredentials);
+  // An unreadable status cannot tell this source apart from an unconfigured
+  // one, so the setup walkthrough would be guessing.
+  const showUnknownStatus = statusUnknown && !ready && !showLocalCredentials;
 
   return (
     <Card className="data-source-card bg-card border-border/50">
@@ -1161,6 +1166,11 @@ function DataSourceCard({
             <div className="flex shrink-0 items-center gap-2">
               {isStatusLoading ? (
                 <Skeleton className="h-4 w-20 rounded-full" />
+              ) : statusUnknown && !ready ? (
+                <span className="flex items-center gap-1.5 text-xs text-amber-500 font-medium whitespace-nowrap">
+                  <IconAlertCircle className="h-3.5 w-3.5" />
+                  {t("dataSources.statusUnknown")}
+                </span>
               ) : ready ? (
                 <span className="flex items-center gap-1.5 text-xs text-emerald-500 font-medium whitespace-nowrap">
                   <IconCheck className="h-3.5 w-3.5" />
@@ -1174,7 +1184,7 @@ function DataSourceCard({
                   {t("dataSources.notConfigured")}
                 </span>
               )}
-              {!isStatusLoading && sharedConnectionStatus && (
+              {!isStatusLoading && !statusUnknown && sharedConnectionStatus && (
                 <span className="data-source-shared-badge">
                   <SharedConnectionBadge status={sharedConnectionStatus} />
                 </span>
@@ -1189,7 +1199,26 @@ function DataSourceCard({
         </CardHeader>
       </button>
 
-      {expanded && (
+      {expanded && showUnknownStatus && (
+        <CardContent className="border-t border-border/50 px-5 py-4">
+          <div className="space-y-3">
+            <p className="flex items-start gap-2 text-xs text-muted-foreground">
+              <IconAlertCircle className="mt-px h-3.5 w-3.5 shrink-0 text-amber-500" />
+              {t("dataSources.statusUnknownDescription")}
+            </p>
+            <Button
+              size="sm"
+              variant="outline"
+              onClick={() => setShowLocalCredentials(true)}
+              className="text-xs"
+            >
+              {t("dataSources.addLocalCredentials")}
+            </Button>
+          </div>
+        </CardContent>
+      )}
+
+      {expanded && !showUnknownStatus && (
         <CardContent className="border-t border-border/50 px-5 py-4">
           {source.id === "github" && (
             <div className="mb-4">
@@ -1700,15 +1729,24 @@ export default function DataSources() {
   const queryClient = useQueryClient();
   const [search, setSearch] = useState("");
 
-  const { data: rawStatusData, isLoading: isStatusLoading } = useActionQuery(
-    "data-source-status",
-    undefined,
-    {
-      staleTime: 10_000,
-    },
-  );
+  const {
+    data: rawStatusData,
+    isLoading: isStatusLoading,
+    isError: isStatusError,
+  } = useActionQuery("data-source-status", undefined, {
+    staleTime: 10_000,
+  });
   const statusData = rawStatusData as DataSourceStatusResponse | undefined;
   const envStatus = credentialRowsFromStatus(statusData);
+  // A failed fetch, an error payload, or a failed workspace-connection lookup
+  // all read as "everything is unconfigured" once they collapse into the empty
+  // credential list. Keep them a separate state instead.
+  const statusUnknown =
+    !isStatusLoading &&
+    (isStatusError ||
+      !statusData ||
+      Boolean(statusData.error) ||
+      statusData.workspaceConnections?.available === false);
 
   const configuredCount = dataSources.filter((s) =>
     isSourceReady(s, statusData, envStatus),
@@ -1743,7 +1781,11 @@ export default function DataSources() {
       <p className="text-sm text-muted-foreground">
         {t("dataSources.intro")}{" "}
         {!isStatusLoading &&
-          (configuredCount > 0 ? (
+          (statusUnknown && configuredCount === 0 ? (
+            <span className="text-amber-500 font-medium">
+              {t("dataSources.statusUnknown")}
+            </span>
+          ) : configuredCount > 0 ? (
             <span className="text-emerald-500 font-medium">
               {t("dataSources.configuredCount", { count: configuredCount })}
             </span>
@@ -1793,6 +1835,7 @@ export default function DataSources() {
                 )}
                 envStatus={envStatus}
                 isStatusLoading={isStatusLoading}
+                statusUnknown={statusUnknown}
                 onSaved={handleSaved}
               />
             ))}
@@ -1830,6 +1873,7 @@ export default function DataSources() {
                     )}
                     envStatus={envStatus}
                     isStatusLoading={isStatusLoading}
+                    statusUnknown={statusUnknown}
                     onSaved={handleSaved}
                   />
                 ))}

package/corpus/templates/analytics/changelog/2026-07-28-analytics-pages-load-reliably-with-large-dashboard-workspaces.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-28
+---
+
+Analytics pages load reliably in workspaces with many saved dashboards.

package/corpus/templates/analytics/changelog/2026-07-28-dashboard-loading-shimmer-now-flows-smoothly-in-one-directi.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-28
+---
+
+Dashboard loading shimmer now flows smoothly in one direction instead of reversing.

package/corpus/templates/analytics/server/lib/first-party-dashboard-repair.ts

@@ -153,10 +153,11 @@ export async function repairPersistedFirstPartyDashboardQueries(): Promise<boole
  * Returns the number of dashboards actually changed.
  */
 export async function repairUnboundedFirstPartyPanelsAcrossDashboards(): Promise<number> {
-  // guard:allow-unscoped — this is an org-wide startup repair: it may touch
-  // any dashboard's persisted panel SQL, but only ever replaces an exact
-  // known-bad SQL string under the same optimistic (config, updatedAt) fence
-  // used by the canonical repair above, so a concurrent edit always wins.
+  // guard:allow-unscoped — this explicit operator repair may touch any
+  // dashboard's persisted panel SQL. It must never run during server startup:
+  // reading every config on each serverless cold start can saturate the
+  // database. Exact-string matches and the optimistic (config, updatedAt)
+  // fence ensure a concurrent edit always wins.
   const db = getDb() as any;
   const dialect = getDialect();
   const rows = await db

package/corpus/templates/analytics/server/plugins/agent-chat.ts

@@ -302,7 +302,6 @@ function dataSourceStatusSummary(
       .replace(/[\s_]+/g, "-");
     if (normalizedName !== "data-source-status" || result.isError) continue;
 
-    checked = true;
     let parsed: Record<string, unknown>;
     try {
       const value = JSON.parse(String(result.content ?? ""));
@@ -314,6 +313,19 @@ function dataSourceStatusSummary(
       continue;
     }
 
+    const workspaceConnections =
+      parsed.workspaceConnections &&
+      typeof parsed.workspaceConnections === "object" &&
+      !Array.isArray(parsed.workspaceConnections)
+        ? (parsed.workspaceConnections as Record<string, unknown>)
+        : null;
+    // A status result that errored, or whose workspace-connection lookup
+    // failed, says "we could not look", not "nothing is connected". Only a
+    // trustworthy result may mark the turn as checked.
+    if (!parsed.error && workspaceConnections?.available !== false) {
+      checked = true;
+    }
+
     let foundSetupLink = false;
     for (const candidate of [
       parsed.dataSourcesSetupLink,
@@ -392,12 +404,6 @@ function dataSourceStatusSummary(
       }
     }
 
-    const workspaceConnections =
-      parsed.workspaceConnections &&
-      typeof parsed.workspaceConnections === "object" &&
-      !Array.isArray(parsed.workspaceConnections)
-        ? (parsed.workspaceConnections as Record<string, unknown>)
-        : null;
     const workspaceProviders = Array.isArray(workspaceConnections?.providers)
       ? workspaceConnections.providers
       : [];
@@ -678,6 +684,46 @@ export function realDataFinalGuard(
   };
 }
 
+export async function searchDashboardMentions(query: string, event?: any) {
+  if (!event) return [];
+  try {
+    const { getOrgContext } = await import("@agent-native/core/org");
+    const { listDashboardSummaries } =
+      await import("../lib/dashboards-store.js");
+    const ctx = await getOrgContext(event);
+    const rows = await listDashboardSummaries(
+      { email: ctx.email, orgId: ctx.orgId ?? null },
+      { kind: "sql", hidden: query ? "all" : "visible" },
+    );
+    const items = rows.map((dashboard) => ({
+      id: dashboard.id,
+      name: dashboard.name,
+    }));
+
+    const q = (query || "").toLowerCase().trim();
+    const filtered = q
+      ? items.filter(
+          (dashboard) =>
+            (dashboard.name || "").toLowerCase().includes(q) ||
+            dashboard.id.toLowerCase().includes(q),
+        )
+      : items;
+
+    return filtered.slice(0, 20).map((dashboard) => ({
+      id: `dashboard:${dashboard.id}`,
+      label: dashboard.name || "Untitled dashboard",
+      description: `/dashboards/${dashboard.id}`,
+      icon: "deck",
+      refType: "dashboard",
+      refId: dashboard.id,
+      refPath: `/dashboards/${dashboard.id}`,
+    }));
+  } catch (err) {
+    console.error("[analytics] Dashboard mention provider failed:", err);
+    return [];
+  }
+}
+
 export default createAgentChatPlugin({
   appId: "analytics",
   actions: applyAnalyticsPlanModePolicy(
@@ -756,41 +802,7 @@ export default createAgentChatPlugin({
     dashboards: {
       label: "Dashboards",
       icon: "deck",
-      search: async (query: string, event?: any) => {
-        if (!event) return [];
-        try {
-          const { getOrgContext } = await import("@agent-native/core/org");
-          const { listDashboards } = await import("../lib/dashboards-store.js");
-          const ctx = await getOrgContext(event);
-          const rows = await listDashboards(
-            { email: ctx.email, orgId: ctx.orgId ?? null },
-            { kind: "sql", hidden: query ? "all" : "visible" },
-          );
-          const items = rows.map((d) => ({ id: d.id, name: d.title }));
-
-          const q = (query || "").toLowerCase().trim();
-          const filtered = q
-            ? items.filter(
-                (d) =>
-                  (d.name || "").toLowerCase().includes(q) ||
-                  d.id.toLowerCase().includes(q),
-              )
-            : items;
-
-          return filtered.slice(0, 20).map((d) => ({
-            id: `dashboard:${d.id}`,
-            label: d.name || "Untitled dashboard",
-            description: `/dashboards/${d.id}`,
-            icon: "deck",
-            refType: "dashboard",
-            refId: d.id,
-            refPath: `/dashboards/${d.id}`,
-          }));
-        } catch (err) {
-          console.error("[analytics] Dashboard mention provider failed:", err);
-          return [];
-        }
-      },
+      search: searchDashboardMentions,
     },
   },
 });

package/corpus/templates/analytics/server/plugins/db.ts

@@ -8,10 +8,7 @@ import {
 // startup so the dashboard / analysis share actions know where to dispatch.
 import "../db/index.js";
 import * as schema from "../db/schema.js";
-import {
-  repairPersistedFirstPartyDashboardQueries,
-  repairUnboundedFirstPartyPanelsAcrossDashboards,
-} from "../lib/first-party-dashboard-repair.js";
+import { repairPersistedFirstPartyDashboardQueries } from "../lib/first-party-dashboard-repair.js";
 
 /**
  * Every Drizzle table exported from schema.ts. Filters out type-only and
@@ -1338,20 +1335,6 @@ export default async (nitroApp: any): Promise<void> => {
       err instanceof Error ? err.message : err,
     );
   }
-  try {
-    const repairedCount =
-      await repairUnboundedFirstPartyPanelsAcrossDashboards();
-    if (repairedCount > 0) {
-      console.info(
-        `[db] Repaired ${repairedCount} dashboard(s) with unbounded first-party panel SQL.`,
-      );
-    }
-  } catch (err) {
-    console.warn(
-      "[db] Failed to repair unbounded first-party panels across dashboards (non-fatal):",
-      err instanceof Error ? err.message : err,
-    );
-  }
   try {
     const summary = await ensureAdditiveColumns({
       db: getDbExec(),

package/corpus/templates/assets/.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/assets/.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/assets/.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: