@agent-native/core 0.161.17 → 0.161.22

package/corpus/templates/forms/AGENTS.md

@@ -21,6 +21,7 @@ Read the relevant skill before deeper work:
   thumbnails, or replay chunks in app tables, `application_state`, `settings`,
   or `resources`; persist URLs, ids, or handles instead.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
+- For external integrations, inspect the workspace/provider connection catalog first; reuse its scoped resolver.
 - Use actions for form lifecycle, fields, publishing, responses, navigation,
   sharing, and database work. Do not bypass ownable access checks. The action
   schema is authoritative when a parameter is unclear.

package/corpus/templates/macros/.agents/skills/adding-a-feature/SKILL.md

@@ -76,6 +76,16 @@ Builder/internal data, or customer data in the action, UI, seed data, fixtures,
 docs, prompts, or generated extension/app content. Register required secrets,
 use OAuth helpers, or read scoped values from the vault/credential store.
 
+Before writing custom setup or credential UI, perform the shared-primitive
+preflight from `agent-native-toolkit`: inspect the workspace/provider connection
+catalog first, then settings, secrets/vault, OAuth, onboarding, and provider API
+support. Reuse an existing connection's app grant and scoped credential
+resolver; only use app-local vault or OAuth primitives when no reusable
+connection exists. Keep any wizard thin and provider-specific - it may explain
+prerequisites, ordering, or readiness, but must not become a second vault or
+custom credential transport. Do not mark each field `required` by reflex;
+model onboarding around the logical connection outcome.
+
 If the feature involves attachments, images, recordings, screenshots, exports,
 or other file-like payloads, design the upload path in the same change:
 provider upload first, then URL/id/blob handle in SQL. Do not add base64/binary

package/corpus/templates/macros/.agents/skills/agent-native-toolkit/SKILL.md

@@ -152,6 +152,30 @@ preference, notification preference, or usage/billing surface, register it as a
 settings tab or app settings panel first. Only add sidebar UI when it is needed
 in the moment of agent use.
 
+## Integration Setup Preflight
+
+Before building any setup, settings, credential, OAuth, or connection surface,
+search the workspace/provider connection catalog first. If the provider already
+has a reusable connection, use its catalog, app grant, and scoped credential
+resolver rather than registering a parallel secret. Only then classify fields
+that still need app-local setup by lifecycle and scope:
+
+| Need | Default primitive |
+| --- | --- |
+| Deploy- or app-level configuration | Runtime configuration or deployment env vars |
+| Existing workspace/provider connection | Workspace-connection catalog/grant plus `resolveWorkspaceConnectionCredential(s)ForApp` |
+| App-local API/service key with no reusable connection | `registerRequiredSecret({ kind: "api-key" })` and the vault |
+| Authorization-code or refresh-token flow | `kind: "oauth"` with `@agent-native/core/oauth-tokens` |
+| Account, customer, or other non-secret identifiers | Scoped connection metadata or app data |
+| Provider-specific prerequisites, sequencing, or health | A thin app-local guide over the shared primitives |
+
+Do not register every provider field as a generic secret, mark every field as
+required, or create a second credential-management surface. One logical
+connection should normally produce one onboarding outcome. A custom setup page
+is appropriate only when it adds domain-specific guidance or readiness checks;
+it should link to or call the shared settings, OAuth, and action surfaces rather
+than duplicating their storage or transport.
+
 ## Reusable Kits
 
 - **Settings kit**: a searchable settings page with account, workspace, AI

package/corpus/templates/macros/.agents/skills/secrets/SKILL.md

@@ -3,8 +3,8 @@ name: secrets
 description: >-
   Declaratively register API keys and service credentials a template needs so
   they appear in the agent sidebar settings UI and the onboarding checklist.
-  Use for any third-party API key (OpenAI, Stripe, Twilio, etc.) and for
-  surfacing OAuth connections in the unified settings UI.
+  Use before adding any third-party credential or setup UI so API keys, OAuth
+  connections, and scoped configuration use the correct shared primitive.
 scope: dev
 metadata:
   internal: true
@@ -24,6 +24,33 @@ encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
 `${keys.NAME}` substitution. Examples must use obvious placeholders such as
 `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
 
+## Credential Modeling Preflight
+
+Before registering a provider's fields, inspect the workspace/provider connection
+catalog first. If a reusable connection exists, use its app grant and scoped
+`resolveWorkspaceConnectionCredential(s)ForApp` path instead of registering a
+parallel secret. Only classify fields for app-local setup when no reusable
+connection exists:
+
+- **API or service key** - register it as `kind: "api-key"` with the narrowest
+  correct `scope`, a human label, a description, a docs link, and a validator.
+- **OAuth authorization or refresh token** - use the OAuth token store and
+  register a `kind: "oauth"` entry so the shared UI renders Connect and the
+  runtime owns status, refresh, and reauthorization.
+- **Deploy- or app-level configuration** - use deployment/runtime
+  configuration, not a per-user secret row.
+- **Account, customer, manager, or other non-secret identifier** - store it as
+  scoped connection metadata or app data, not as a masked secret field.
+
+`required: true` is for a logical setup requirement. If a provider needs
+several values, do not automatically create one required checklist item per
+field; use one composite onboarding step or a registered connection readiness
+check.
+
+Custom setup UI is allowed for provider-specific prerequisites, ordering, or
+health checks, but it must delegate credential storage and connection state to
+the shared vault/OAuth/settings surfaces.
+
 ## When to use
 
 Use this for any external credential your template needs: API keys, service

package/corpus/templates/macros/AGENTS.md

@@ -17,6 +17,7 @@ actions and SQL state.
   thumbnails, or replay chunks in app tables, `application_state`, `settings`,
   or `resources`; persist URLs, ids, or handles instead.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
+- For external integrations, inspect the workspace/provider connection catalog first; reuse its scoped resolver.
 - Use actions for meals, foods, calorie/macro updates, voice command handling,
   stats, and navigation. Do not mutate app tables directly.
 - Do not invent nutrition values when the source is unknown. Ask, use defaults

package/corpus/templates/mail/.agents/skills/adding-a-feature/SKILL.md

@@ -76,6 +76,16 @@ Builder/internal data, or customer data in the action, UI, seed data, fixtures,
 docs, prompts, or generated extension/app content. Register required secrets,
 use OAuth helpers, or read scoped values from the vault/credential store.
 
+Before writing custom setup or credential UI, perform the shared-primitive
+preflight from `agent-native-toolkit`: inspect the workspace/provider connection
+catalog first, then settings, secrets/vault, OAuth, onboarding, and provider API
+support. Reuse an existing connection's app grant and scoped credential
+resolver; only use app-local vault or OAuth primitives when no reusable
+connection exists. Keep any wizard thin and provider-specific - it may explain
+prerequisites, ordering, or readiness, but must not become a second vault or
+custom credential transport. Do not mark each field `required` by reflex;
+model onboarding around the logical connection outcome.
+
 If the feature involves attachments, images, recordings, screenshots, exports,
 or other file-like payloads, design the upload path in the same change:
 provider upload first, then URL/id/blob handle in SQL. Do not add base64/binary

package/corpus/templates/mail/.agents/skills/agent-native-toolkit/SKILL.md

@@ -152,6 +152,30 @@ preference, notification preference, or usage/billing surface, register it as a
 settings tab or app settings panel first. Only add sidebar UI when it is needed
 in the moment of agent use.
 
+## Integration Setup Preflight
+
+Before building any setup, settings, credential, OAuth, or connection surface,
+search the workspace/provider connection catalog first. If the provider already
+has a reusable connection, use its catalog, app grant, and scoped credential
+resolver rather than registering a parallel secret. Only then classify fields
+that still need app-local setup by lifecycle and scope:
+
+| Need | Default primitive |
+| --- | --- |
+| Deploy- or app-level configuration | Runtime configuration or deployment env vars |
+| Existing workspace/provider connection | Workspace-connection catalog/grant plus `resolveWorkspaceConnectionCredential(s)ForApp` |
+| App-local API/service key with no reusable connection | `registerRequiredSecret({ kind: "api-key" })` and the vault |
+| Authorization-code or refresh-token flow | `kind: "oauth"` with `@agent-native/core/oauth-tokens` |
+| Account, customer, or other non-secret identifiers | Scoped connection metadata or app data |
+| Provider-specific prerequisites, sequencing, or health | A thin app-local guide over the shared primitives |
+
+Do not register every provider field as a generic secret, mark every field as
+required, or create a second credential-management surface. One logical
+connection should normally produce one onboarding outcome. A custom setup page
+is appropriate only when it adds domain-specific guidance or readiness checks;
+it should link to or call the shared settings, OAuth, and action surfaces rather
+than duplicating their storage or transport.
+
 ## Reusable Kits
 
 - **Settings kit**: a searchable settings page with account, workspace, AI

package/corpus/templates/mail/.agents/skills/secrets/SKILL.md

@@ -3,8 +3,8 @@ name: secrets
 description: >-
   Declaratively register API keys and service credentials a template needs so
   they appear in the agent sidebar settings UI and the onboarding checklist.
-  Use for any third-party API key (OpenAI, Stripe, Twilio, etc.) and for
-  surfacing OAuth connections in the unified settings UI.
+  Use before adding any third-party credential or setup UI so API keys, OAuth
+  connections, and scoped configuration use the correct shared primitive.
 scope: dev
 metadata:
   internal: true
@@ -24,6 +24,33 @@ encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
 `${keys.NAME}` substitution. Examples must use obvious placeholders such as
 `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
 
+## Credential Modeling Preflight
+
+Before registering a provider's fields, inspect the workspace/provider connection
+catalog first. If a reusable connection exists, use its app grant and scoped
+`resolveWorkspaceConnectionCredential(s)ForApp` path instead of registering a
+parallel secret. Only classify fields for app-local setup when no reusable
+connection exists:
+
+- **API or service key** - register it as `kind: "api-key"` with the narrowest
+  correct `scope`, a human label, a description, a docs link, and a validator.
+- **OAuth authorization or refresh token** - use the OAuth token store and
+  register a `kind: "oauth"` entry so the shared UI renders Connect and the
+  runtime owns status, refresh, and reauthorization.
+- **Deploy- or app-level configuration** - use deployment/runtime
+  configuration, not a per-user secret row.
+- **Account, customer, manager, or other non-secret identifier** - store it as
+  scoped connection metadata or app data, not as a masked secret field.
+
+`required: true` is for a logical setup requirement. If a provider needs
+several values, do not automatically create one required checklist item per
+field; use one composite onboarding step or a registered connection readiness
+check.
+
+Custom setup UI is allowed for provider-specific prerequisites, ordering, or
+health checks, but it must delegate credential storage and connection state to
+the shared vault/OAuth/settings surfaces.
+
 ## When to use
 
 Use this for any external credential your template needs: API keys, service

package/corpus/templates/mail/AGENTS.md

@@ -56,6 +56,7 @@ Read the relevant skill before deeper work:
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private
   Builder/internal data, customer data, or credential-looking literals. Use
   secrets/OAuth/runtime configuration and obvious placeholders in examples.
+- For external integrations, inspect the workspace/provider connection catalog first; reuse its scoped resolver.
 
 ## Action Map
 

package/corpus/templates/mail/app/components/email/EmailList.tsx

@@ -62,6 +62,11 @@ import { ensureThread, warmThreads } from "@/lib/thread-cache";
 import { cn } from "@/lib/utils";
 
 import { EmailListItem } from "./EmailListItem";
+import {
+  observeNextPage,
+  retryNextPage as runPaginationRetry,
+  shouldShowPaginationRetry,
+} from "./infinite-pagination";
 
 type EmailsPage = { emails: EmailMessage[]; nextPageToken?: string };
 type InfiniteEmails = InfiniteData<EmailsPage, string | undefined>;
@@ -83,6 +88,7 @@ interface EmailListProps {
   hasNextPage?: boolean;
   fetchNextPage?: () => Promise<unknown>;
   isFetchingNextPage?: boolean;
+  isFetchNextPageError?: boolean;
   focusedId: string | null;
   setFocusedId: (id: string | null) => void;
   selectedIds: Set<string>;
@@ -366,6 +372,7 @@ export function EmailList({
   hasNextPage: hasNextPageProp,
   fetchNextPage: fetchNextPageProp,
   isFetchingNextPage: isFetchingNextPageProp,
+  isFetchNextPageError: isFetchNextPageErrorProp,
   focusedId,
   setFocusedId,
   selectedIds,
@@ -397,6 +404,7 @@ export function EmailList({
     hasNextPage: fetchedEmailsHasNextPage,
     fetchNextPage: fetchFetchedNextPage,
     isFetchingNextPage: fetchedEmailsFetchingNextPage,
+    isFetchNextPageError: fetchedEmailsFetchNextPageError,
   } = useEmails(view, searchQuery, labelParam ?? undefined, {
     enabled: emailsProp === undefined,
   });
@@ -410,6 +418,13 @@ export function EmailList({
   const fetchNextPage = fetchNextPageProp ?? fetchFetchedNextPage;
   const isFetchingNextPage =
     isFetchingNextPageProp ?? fetchedEmailsFetchingNextPage;
+  const isFetchNextPageError =
+    isFetchNextPageErrorProp ?? fetchedEmailsFetchNextPageError;
+  const paginationRetryInFlightRef = useRef(false);
+  const retryNextPage = useCallback(
+    () => runPaginationRetry(fetchNextPage, paginationRetryInFlightRef),
+    [fetchNextPage],
+  );
   const markRead = useMarkRead();
   const markThreadRead = useMarkThreadRead();
   const toggleStar = useToggleStar();
@@ -1127,31 +1142,20 @@ export function EmailList({
   }, [focusedIndex, rowVirtualizer]);
 
   // Infinite scroll — fetch next page when the sentinel enters the viewport.
-  // isFetchingNextPage is read via ref (not a dep) because re-observe fires
-  // the callback synchronously with the current intersection state; if the
-  // sentinel is still visible after a fetch, a reconnecting observer would
-  // immediately fire again and we'd loop (visible to the user as "Loading
-  // more..." flashing every ~second while tab is idle).
+  // Re-arm the observer when a fetch completes so a still-visible sentinel can
+  // walk through consecutive pages with no client-side filtered matches.
   const sentinelRef = useRef<HTMLDivElement>(null);
-  const isFetchingNextPageRef = useRef(isFetchingNextPage);
-  isFetchingNextPageRef.current = isFetchingNextPage;
   useEffect(() => {
     const el = sentinelRef.current;
-    if (!el || !hasNextPage) return;
-    const observer = new IntersectionObserver(
-      (entries) => {
-        if (entries[0].isIntersecting && !isFetchingNextPageRef.current) {
-          void fetchNextPage().catch(() => {
-            // React Query owns the visible error state; avoid a global
-            // unhandledrejection for transient list-page fetch failures.
-          });
-        }
-      },
-      { rootMargin: "200px" },
-    );
-    observer.observe(el);
-    return () => observer.disconnect();
-  }, [hasNextPage, fetchNextPage]);
+    if (!el) return;
+    return observeNextPage({
+      element: el,
+      hasNextPage: Boolean(hasNextPage),
+      isFetchingNextPage: Boolean(isFetchingNextPage),
+      isFetchNextPageError: Boolean(isFetchNextPageError),
+      fetchNextPage,
+    });
+  }, [hasNextPage, isFetchingNextPage, isFetchNextPageError, fetchNextPage]);
 
   // Advance selection when an email is snoozed (same logic as archiveFocused)
   useEffect(() => {
@@ -1597,6 +1601,41 @@ export function EmailList({
     return <MailLoadingState containerRef={containerRef} />;
   }
 
+  // Client-sliced inbox tabs can have no matches on the first page even when
+  // later inbox pages contain matching threads. Keep the sentinel mounted so
+  // the infinite query can continue before showing an empty state.
+  if (threads.length === 0 && hasNextPage) {
+    return (
+      <div className="flex h-full flex-col" ref={containerRef}>
+        <div className="flex flex-1 items-center justify-center" />
+        <div
+          ref={sentinelRef}
+          className="flex items-center justify-center py-3"
+        >
+          {isFetchingNextPage && (
+            <div className="flex items-center gap-2 text-xs text-muted-foreground">
+              <Spinner className="size-3 text-muted-foreground" />
+              {t("mail.empty.loadingMore")}
+            </div>
+          )}
+          {shouldShowPaginationRetry({
+            hasNextPage: Boolean(hasNextPage),
+            isFetchingNextPage: Boolean(isFetchingNextPage),
+            isFetchNextPageError: Boolean(isFetchNextPageError),
+          }) && (
+            <button
+              type="button"
+              onClick={() => void retryNextPage()}
+              className="rounded-md bg-primary px-3 py-1.5 text-xs font-medium text-primary-foreground shadow-sm hover:bg-primary/90"
+            >
+              {t("mail.error.tryAgain")}
+            </button>
+          )}
+        </div>
+      </div>
+    );
+  }
+
   // Empty state
   if (threads.length === 0) {
     if (searchQuery) {
@@ -1737,6 +1776,19 @@ export function EmailList({
                 {t("mail.empty.loadingMore")}
               </div>
             )}
+            {shouldShowPaginationRetry({
+              hasNextPage: Boolean(hasNextPage),
+              isFetchingNextPage: Boolean(isFetchingNextPage),
+              isFetchNextPageError: Boolean(isFetchNextPageError),
+            }) && (
+              <button
+                type="button"
+                onClick={() => void retryNextPage()}
+                className="rounded-md bg-primary px-3 py-1.5 text-xs font-medium text-primary-foreground shadow-sm hover:bg-primary/90"
+              >
+                {t("mail.error.tryAgain")}
+              </button>
+            )}
           </div>
         )}
       </div>

package/corpus/templates/mail/app/components/email/infinite-pagination.ts

@@ -0,0 +1,82 @@
+interface ObserveNextPageOptions {
+  element: Element;
+  hasNextPage: boolean;
+  isFetchingNextPage: boolean;
+  isFetchNextPageError: boolean;
+  fetchNextPage: () => Promise<unknown>;
+}
+
+export interface PaginationRetryState {
+  hasNextPage: boolean;
+  isFetchingNextPage: boolean;
+  isFetchNextPageError: boolean;
+}
+
+export function shouldShowPaginationRetry({
+  hasNextPage,
+  isFetchingNextPage,
+  isFetchNextPageError,
+}: PaginationRetryState): boolean {
+  return hasNextPage && isFetchNextPageError && !isFetchingNextPage;
+}
+
+/**
+ * Run an explicit pagination retry without leaking a rejected provider promise
+ * to the browser. The shared state closes the synchronous double-click window
+ * before React Query has reflected isFetchingNextPage.
+ */
+export async function retryNextPage(
+  fetchNextPage: () => Promise<unknown>,
+  inFlightState: { current: boolean },
+): Promise<void> {
+  if (inFlightState.current) return;
+  inFlightState.current = true;
+  try {
+    await fetchNextPage();
+  } catch {
+    // coercion-ok: React Query owns the error; catch prevents an unhandled retry rejection.
+    // React Query owns the visible error state for the failed page.
+  } finally {
+    inFlightState.current = false;
+  }
+}
+
+/**
+ * Observe a visible infinite-scroll sentinel for one page at a time.
+ *
+ * The owning effect re-runs when `isFetchingNextPage` changes. That lets the
+ * next observer receive the sentinel's already-visible state after a fetch,
+ * including when several consecutive pages contain no filtered matches. A
+ * failed page is deliberately left unobserved until the user explicitly
+ * retries it, so a persistent provider error cannot create a request loop.
+ */
+export function observeNextPage({
+  element,
+  hasNextPage,
+  isFetchingNextPage,
+  isFetchNextPageError,
+  fetchNextPage,
+}: ObserveNextPageOptions): () => void {
+  if (!hasNextPage || isFetchingNextPage || isFetchNextPageError)
+    return () => {};
+
+  let fetchInFlight = false;
+  const observer = new IntersectionObserver(
+    (entries) => {
+      if (!entries[0]?.isIntersecting || fetchInFlight) return;
+
+      fetchInFlight = true;
+      void fetchNextPage()
+        .catch(() => {
+          // React Query owns the visible error state; avoid a global
+          // unhandledrejection for transient list-page fetch failures.
+        })
+        .finally(() => {
+          fetchInFlight = false;
+        });
+    },
+    { rootMargin: "200px" },
+  );
+  observer.observe(element);
+  return () => observer.disconnect();
+}

package/corpus/templates/mail/app/hooks/use-emails.ts

@@ -573,6 +573,7 @@ export function useEmails(
     hasNextPage: q.hasNextPage,
     fetchNextPage: q.fetchNextPage,
     isFetchingNextPage: q.isFetchingNextPage,
+    isFetchNextPageError: q.isFetchNextPageError,
   };
 }
 

package/corpus/templates/mail/app/pages/InboxPage.tsx

@@ -31,6 +31,8 @@ import {
 import { groupIntoThreads, type ThreadSummary } from "@/lib/threads";
 import { cn } from "@/lib/utils";
 
+import { shouldShowInboxZero } from "./inbox-zero";
+
 function ContactPanel({
   emailId,
   contactEmail,
@@ -315,6 +317,7 @@ export function InboxPage() {
     hasNextPage,
     fetchNextPage,
     isFetchingNextPage,
+    isFetchNextPageError,
   } = useEmails(view, searchQuery, effectiveLabel);
   const hasEmailData = rawEmails !== undefined;
   const emailListLoading =
@@ -590,16 +593,17 @@ export function InboxPage() {
 
   const isMobile = useIsMobile();
   const hasThread = !!threadId;
-  const showsScenicInboxZero =
-    view === "inbox" && (!activeLabel || activeLabel === "important");
-  const isInboxZero =
-    showsScenicInboxZero &&
-    hasEmailData &&
-    !emailListLoading &&
-    !isError &&
-    !hasThread &&
-    !searchQuery &&
-    threads.length === 0;
+  const isInboxZero = shouldShowInboxZero({
+    view,
+    activeLabel,
+    hasEmailData,
+    isLoading: emailListLoading,
+    isError,
+    hasThread,
+    searchQuery,
+    threadCount: threads.length,
+    hasNextPage: Boolean(hasNextPage),
+  });
   const [sidebarContactEmail, setSidebarContactEmail] = useState<
     string | undefined
   >();
@@ -680,6 +684,7 @@ export function InboxPage() {
             hasNextPage={hasNextPage}
             fetchNextPage={fetchNextPage}
             isFetchingNextPage={isFetchingNextPage}
+            isFetchNextPageError={isFetchNextPageError}
           />
         )}
       </div>

package/corpus/templates/mail/app/pages/inbox-zero.ts

@@ -0,0 +1,35 @@
+export interface InboxZeroState {
+  view: string;
+  activeLabel: string | null | undefined;
+  hasEmailData: boolean;
+  isLoading: boolean;
+  isError: boolean;
+  hasThread: boolean;
+  searchQuery: string | undefined;
+  threadCount: number;
+  hasNextPage: boolean;
+}
+
+export function shouldShowInboxZero({
+  view,
+  activeLabel,
+  hasEmailData,
+  isLoading,
+  isError,
+  hasThread,
+  searchQuery,
+  threadCount,
+  hasNextPage,
+}: InboxZeroState): boolean {
+  return (
+    view === "inbox" &&
+    (!activeLabel || activeLabel === "important") &&
+    hasEmailData &&
+    !isLoading &&
+    !isError &&
+    !hasThread &&
+    !searchQuery &&
+    threadCount === 0 &&
+    !hasNextPage
+  );
+}

package/corpus/templates/mail/changelog/2026-08-18-pinned-labels-load-matches.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-18
+---
+
+Pinned labels now keep loading until matching inbox messages are found.

package/corpus/templates/plan/.agents/skills/adding-a-feature/SKILL.md

@@ -76,6 +76,16 @@ Builder/internal data, or customer data in the action, UI, seed data, fixtures,
 docs, prompts, or generated extension/app content. Register required secrets,
 use OAuth helpers, or read scoped values from the vault/credential store.
 
+Before writing custom setup or credential UI, perform the shared-primitive
+preflight from `agent-native-toolkit`: inspect the workspace/provider connection
+catalog first, then settings, secrets/vault, OAuth, onboarding, and provider API
+support. Reuse an existing connection's app grant and scoped credential
+resolver; only use app-local vault or OAuth primitives when no reusable
+connection exists. Keep any wizard thin and provider-specific - it may explain
+prerequisites, ordering, or readiness, but must not become a second vault or
+custom credential transport. Do not mark each field `required` by reflex;
+model onboarding around the logical connection outcome.
+
 If the feature involves attachments, images, recordings, screenshots, exports,
 or other file-like payloads, design the upload path in the same change:
 provider upload first, then URL/id/blob handle in SQL. Do not add base64/binary

package/corpus/templates/plan/.agents/skills/agent-native-toolkit/SKILL.md

@@ -152,6 +152,30 @@ preference, notification preference, or usage/billing surface, register it as a
 settings tab or app settings panel first. Only add sidebar UI when it is needed
 in the moment of agent use.
 
+## Integration Setup Preflight
+
+Before building any setup, settings, credential, OAuth, or connection surface,
+search the workspace/provider connection catalog first. If the provider already
+has a reusable connection, use its catalog, app grant, and scoped credential
+resolver rather than registering a parallel secret. Only then classify fields
+that still need app-local setup by lifecycle and scope:
+
+| Need | Default primitive |
+| --- | --- |
+| Deploy- or app-level configuration | Runtime configuration or deployment env vars |
+| Existing workspace/provider connection | Workspace-connection catalog/grant plus `resolveWorkspaceConnectionCredential(s)ForApp` |
+| App-local API/service key with no reusable connection | `registerRequiredSecret({ kind: "api-key" })` and the vault |
+| Authorization-code or refresh-token flow | `kind: "oauth"` with `@agent-native/core/oauth-tokens` |
+| Account, customer, or other non-secret identifiers | Scoped connection metadata or app data |
+| Provider-specific prerequisites, sequencing, or health | A thin app-local guide over the shared primitives |
+
+Do not register every provider field as a generic secret, mark every field as
+required, or create a second credential-management surface. One logical
+connection should normally produce one onboarding outcome. A custom setup page
+is appropriate only when it adds domain-specific guidance or readiness checks;
+it should link to or call the shared settings, OAuth, and action surfaces rather
+than duplicating their storage or transport.
+
 ## Reusable Kits
 
 - **Settings kit**: a searchable settings page with account, workspace, AI

package/corpus/templates/plan/.agents/skills/secrets/SKILL.md

@@ -3,8 +3,8 @@ name: secrets
 description: >-
   Declaratively register API keys and service credentials a template needs so
   they appear in the agent sidebar settings UI and the onboarding checklist.
-  Use for any third-party API key (OpenAI, Stripe, Twilio, etc.) and for
-  surfacing OAuth connections in the unified settings UI.
+  Use before adding any third-party credential or setup UI so API keys, OAuth
+  connections, and scoped configuration use the correct shared primitive.
 scope: dev
 metadata:
   internal: true
@@ -24,6 +24,33 @@ encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
 `${keys.NAME}` substitution. Examples must use obvious placeholders such as
 `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
 
+## Credential Modeling Preflight
+
+Before registering a provider's fields, inspect the workspace/provider connection
+catalog first. If a reusable connection exists, use its app grant and scoped
+`resolveWorkspaceConnectionCredential(s)ForApp` path instead of registering a
+parallel secret. Only classify fields for app-local setup when no reusable
+connection exists:
+
+- **API or service key** - register it as `kind: "api-key"` with the narrowest
+  correct `scope`, a human label, a description, a docs link, and a validator.
+- **OAuth authorization or refresh token** - use the OAuth token store and
+  register a `kind: "oauth"` entry so the shared UI renders Connect and the
+  runtime owns status, refresh, and reauthorization.
+- **Deploy- or app-level configuration** - use deployment/runtime
+  configuration, not a per-user secret row.
+- **Account, customer, manager, or other non-secret identifier** - store it as
+  scoped connection metadata or app data, not as a masked secret field.
+
+`required: true` is for a logical setup requirement. If a provider needs
+several values, do not automatically create one required checklist item per
+field; use one composite onboarding step or a registered connection readiness
+check.
+
+Custom setup UI is allowed for provider-specific prerequisites, ordering, or
+health checks, but it must delegate credential storage and connection state to
+the shared vault/OAuth/settings surfaces.
+
 ## When to use
 
 Use this for any external credential your template needs: API keys, service