@agent-native/core 0.161.17 → 0.161.20

package/dist/client/chat/run-recovery.js

@@ -158,7 +158,7 @@ export function BuilderSetupContent({ onConnected, layout = "default", }) {
     return (_jsxs("div", { className: cn("agent-builder-setup-content", sidebarLayout && "agent-builder-setup-card--sidebar"), children: [_jsxs("div", { className: cn("agent-builder-setup-card__content flex flex-col sm:flex-row sm:items-center sm:justify-between", sidebarLayout ? "gap-2" : "gap-3"), children: [_jsxs("div", { className: "agent-builder-setup-card__copy min-w-0", children: [_jsx("h3", { className: "text-[13px] font-medium text-foreground", children: t("agentPanel.connectAi", { defaultValue: "Connect AI" }) }), _jsx("p", { className: "mt-0.5 text-[11px] leading-relaxed text-muted-foreground", children: t("agentPanel.builderOrOwnKeys", {
                                     defaultValue: "Choose Builder.io or custom keys.",
                                 }) })] }), _jsxs("div", { className: cn("agent-builder-setup-card__actions flex shrink-0", sidebarLayout
-                            ? "flex-col items-start gap-1 sm:items-center"
+                            ? "flex-row items-center gap-1"
                             : "flex-nowrap items-center gap-2"), children: [_jsx(BuilderConnectCta, { variant: "compact", onConnected: onConnected }), _jsx("button", { type: "button", onClick: () => setKeyOpen((open) => !open), className: cn("agent-builder-setup-card__key-button inline-flex shrink-0 items-center whitespace-nowrap rounded-md text-[11px] font-medium", sidebarLayout
                                     ? "h-7 border-0 bg-transparent px-0 text-muted-foreground hover:bg-transparent hover:text-foreground"
                                     : "h-8 border border-border bg-background px-3 text-foreground hover:bg-accent"), "aria-expanded": keyOpen, children: t("agentPanel.addOwnKeys", {

package/dist/client/route-state.js

@@ -58,19 +58,24 @@ function shallowEqualNavigationState(left, right) {
     }
     return true;
 }
-function stringifyForWriteDedup(value) {
+/**
+ * Dedup token for the navigation write. Unserializable state falls back to the
+ * state's own identity, never a fresh symbol: the caller's `navigationKeys` is
+ * usually a new array each render, so a symbol recomputed here would never
+ * match the last one and every re-render would issue another failing write.
+ * Identity still lets a genuinely different state reach the write path.
+ */
+function navigationWriteDedupToken(keys, state) {
     try {
-        const serialized = JSON.stringify(value);
-        return typeof serialized === "string"
-            ? serialized
-            : Symbol("unserializable navigation state");
+        const serialized = JSON.stringify({ keys, state });
+        if (typeof serialized === "string")
+            return serialized;
     }
     catch {
-        // Do not turn a serialization failure into a reusable string key. A
-        // distinct token lets a changed unserializable state reach the write path
-        // and surface its real error instead of being silently deduplicated.
-        return Symbol("unserializable navigation state");
+        // coercion-ok: deferred, not dropped — the write below still rejects with
+        // this error and reports it through `onError`.
     }
+    return state;
 }
 function resolveAgentChatViewTransitionOption(option, command, path) {
     const resolved = typeof option === "function" ? option(command, path) : option;
@@ -92,16 +97,15 @@ export function useSemanticNavigationState(options) {
     const commandKeys = useMemo(() => uniqueKeys(options.commandKeys ?? ["navigate"]), [options.commandKeys]);
     const commandQueryKey = useMemo(() => options.commandQueryKey ?? ["navigate-command"], [options.commandQueryKey]);
     const navigationState = options.state ?? null;
-    const navigationWriteDedup = useMemo(() => stringifyForWriteDedup({
-        keys: navigationKeys,
-        state: navigationState,
-    }), [navigationKeys, navigationState]);
+    const navigationWriteDedup = useMemo(() => navigationWriteDedupToken(navigationKeys, navigationState), [navigationKeys, navigationState]);
     const getCommandDedupKeyRef = useRef(options.getCommandDedupKey);
     const onCommandRef = useRef(options.onCommand);
     const onErrorRef = useRef(options.onError);
     getCommandDedupKeyRef.current = options.getCommandDedupKey;
     onCommandRef.current = options.onCommand;
     onErrorRef.current = options.onError;
+    // `null` is safe as "never written": a null state serializes to a string, so
+    // the token itself is never null.
     const lastNavigationWriteRef = useRef(null);
     useEffect(() => {
         if (!enabled)

package/dist/collab/routes.d.ts

@@ -26,8 +26,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
  * Body: { update: string (base64), requestSource?: string }
  */
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/observability/routes.d.ts

@@ -44,14 +44,14 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-    error?: undefined;
     ok?: undefined;
+    error?: undefined;
 } | {
     summary?: undefined;
     spans?: undefined;
     id: string;
-    error?: undefined;
     ok?: undefined;
+    error?: undefined;
 } | {
     summary?: undefined;
     spans?: undefined;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/server/auth.d.ts

@@ -37,6 +37,12 @@ export interface AuthOptions {
      * Both page routes and API routes can be made public.
      */
     publicPaths?: string[];
+    /**
+     * Public, unauthenticated ingest paths that may receive cross-origin
+     * requests when CORS_ALLOWED_ORIGINS is unset. These routes must perform
+     * their own request validation and must not rely on cookies for auth.
+     */
+    publicCorsPaths?: string[];
     /**
      * Workspace-level audience for the app.
      *

package/dist/server/auth.js

@@ -1380,11 +1380,11 @@ export async function runAuthGuard(event) {
  * unauthenticated requests. Returns the login HTML for page routes
  * or a 401 JSON response for API routes.
  *
- * Reads loginHtml and publicPaths from _authGuardConfig on every request
+ * Reads loginHtml and public paths from _authGuardConfig on every request
  * so that a custom plugin can update them after the default has already
  * installed this middleware (the production race condition fix).
  */
-function applyCorsHeaders(event) {
+function applyCorsHeaders(event, publicCorsPaths = [], requestPath) {
     // Framework-level CORS. The auth guard runs before any of the app's own
     // route handlers, so we need to set CORS here too — otherwise a 401
     // response would be missing the Allow-Origin header and the browser
@@ -1404,15 +1404,22 @@ function applyCorsHeaders(event) {
             Boolean(getHeader(event, EMBED_TARGET_HEADER)) ||
             Boolean(getHeader(event, EMBED_TRANSPLANT_HEADER)) ||
             Boolean(getHeader(event, "authorization")));
+    const isPublicCorsPath = Boolean(requestPath && matchesPathList(requestPath, publicCorsPaths));
     const allowedOrigin = getAllowedCorsOrigin(origin, {
         allowedOrigins: readCorsAllowedOrigins(),
+        // Public ingestion endpoints such as analytics replay are intentionally
+        // callable by browser apps on arbitrary origins. The endpoint still owns
+        // its public-key, payload, quota, and origin checks; this only lets the
+        // browser complete the preflight when no deployment-wide allowlist exists.
+        allowAnyOriginWhenNoAllowlist: isPublicCorsPath,
     });
     const responseOrigin = mcpEmbedCorsRequest ? origin : allowedOrigin;
     if (!responseOrigin)
         return { hasOrigin: true, allowed: false };
     setResponseHeader(event, "Access-Control-Allow-Origin", responseOrigin);
     setResponseHeader(event, "Vary", "Origin");
-    if (!mcpEmbedCorsRequest || shouldAllowMcpEmbedCredentials(responseOrigin)) {
+    if (!isPublicCorsPath &&
+        (!mcpEmbedCorsRequest || shouldAllowMcpEmbedCredentials(responseOrigin))) {
         setResponseHeader(event, "Access-Control-Allow-Credentials", "true");
     }
     setResponseHeader(event, "Access-Control-Allow-Methods", "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS");
@@ -1431,7 +1438,7 @@ function applyCorsHeaders(event) {
 }
 function createAuthCorsHandler() {
     return defineEventHandler((event) => {
-        const cors = applyCorsHeaders(event);
+        const cors = applyCorsHeaders(event, _authGuardConfig?.publicCorsPaths);
         if (getMethod(event) !== "OPTIONS")
             return;
         if (cors.hasOrigin && !cors.allowed) {
@@ -1835,7 +1842,7 @@ function createAuthGuardFn(app) {
             return callbackRelay;
         // Emit CORS headers on every request the guard sees so that even
         // error responses (401) reach the browser.
-        const cors = applyCorsHeaders(event);
+        const cors = applyCorsHeaders(event, config.publicCorsPaths, p);
         // Preflight short-circuit: the browser sends OPTIONS before the real
         // credentialed request. Must return success without invoking auth.
         if (getMethod(event) === "OPTIONS") {
@@ -4039,6 +4046,7 @@ async function mountBetterAuthRoutes(app, options) {
     _authGuardConfig = {
         ...loginHtmlConfig,
         publicPaths,
+        publicCorsPaths: options.publicCorsPaths ?? [],
         workspaceAppAudience,
         workspaceAppPublicPaths: workspaceAppRouteAccess.publicPaths,
         workspaceAppProtectedPaths: workspaceAppRouteAccess.protectedPaths,
@@ -4236,6 +4244,14 @@ export async function autoMountAuth(app, options = {}) {
                     ...options.publicPaths,
                 ];
             }
+            if (options.publicCorsPaths) {
+                _authGuardConfig.publicCorsPaths = [
+                    ...new Set([
+                        ...(_authGuardConfig.publicCorsPaths ?? []),
+                        ...options.publicCorsPaths,
+                    ]),
+                ];
+            }
             if (options.workspaceAppAudience) {
                 _authGuardConfig.workspaceAppAudience =
                     resolveWorkspaceAppAudience(options);
@@ -4307,6 +4323,7 @@ export async function autoMountAuth(app, options = {}) {
                     getLoginHtml: () => getCustomAuthRequiredHtml(),
                 }),
             publicPaths,
+            publicCorsPaths: options.publicCorsPaths ?? [],
             workspaceAppAudience,
             workspaceAppPublicPaths: workspaceAppRouteAccess.publicPaths,
             workspaceAppProtectedPaths: workspaceAppRouteAccess.protectedPaths,
@@ -4334,6 +4351,7 @@ export async function autoMountAuth(app, options = {}) {
         _authGuardConfig = {
             ...loginHtmlConfig,
             publicPaths,
+            publicCorsPaths: options.publicCorsPaths ?? [],
             workspaceAppAudience,
             workspaceAppPublicPaths: workspaceAppRouteAccess.publicPaths,
             workspaceAppProtectedPaths: workspaceAppRouteAccess.protectedPaths,

package/dist/templates/chat/.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/dist/templates/chat/.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/dist/templates/chat/.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/dist/templates/chat/AGENTS.md

@@ -25,6 +25,10 @@ the matching skill only when this app actually uses that workflow. The
 - 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 an existing connection and its scoped credential resolver; only
+  use app-local vault/OAuth/settings primitives when no reusable connection
+  exists. Keep custom setup UI provider-specific and never duplicate storage.
 - Keep actions deterministic and focused. Research, analysis, generation,
   recommendation, and synthesis start in the AgentSidebar and let the agent
   orchestrate its tools; follow-ups stay in the same thread rather than moving

package/dist/templates/default/.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/dist/templates/default/.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/dist/templates/default/.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/dist/templates/default/AGENTS.md

@@ -52,6 +52,10 @@ cross-cutting work and `self-modifying-code` when changing app source.
   and focused-object context.
 - Never hardcode keys, tokens, webhook URLs, private data, or credential-like
   literals. Use secrets, OAuth, or obvious placeholders.
+- For external integrations, inspect the workspace/provider connection catalog
+  first. Reuse an existing connection and its scoped credential resolver; only
+  use app-local vault/OAuth/settings primitives when no reusable connection
+  exists. Keep custom setup UI provider-specific and never duplicate storage.
 - A missing or unreadable value must stay distinguishable from success. Throw or
   return an explicit error instead of silently falling back to an empty value.
 

package/dist/templates/headless/.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/dist/templates/headless/.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/dist/templates/headless/AGENTS.md

@@ -13,6 +13,10 @@ This app is not stateless. The Agent Native runtime uses SQL-backed stores for a
   ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
   storage and persist only URLs, ids, or handles.
 - Do not hardcode API keys, tokens, webhook URLs, private data, or credential-looking literals.
+- For external integrations, inspect the workspace/provider connection catalog
+  first. Reuse an existing connection and its scoped credential resolver; only
+  use app-local vault/OAuth/settings primitives when no reusable connection
+  exists. Keep custom setup UI provider-specific and never duplicate storage.
 - `actions/run.ts` is the CLI dispatcher for `pnpm action ...`, not an app
   action. Leave it in place and add callable primitives as separate
   `actions/<name>.ts` files.

package/dist/templates/workspace-core/.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/dist/templates/workspace-core/.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/dist/templates/workspace-core/.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/dist/templates/workspace-core/AGENTS.md

@@ -98,3 +98,7 @@ file plus `.agents/skills/` for workspace-specific conventions.
 | --- | --- |
 | `docs-search` | Search version-matched framework docs by query or slug, or list |
 | `source-search` | Search the bundled core/template source corpus by pattern or path |
+
+- For external integrations, check the provider connection catalog first; reuse
+  its scoped resolver before app-local vault/OAuth/settings. Custom UI is for
+  provider readiness only, never duplicate credential storage.

package/dist/templates/workspace-root/AGENTS.md

@@ -164,6 +164,15 @@ an additional locale or changelog.
 - Dispatch vault access is workspace-wide by default: every saved vault key is
   available to every workspace app. Only create or request per-app vault grants
   when Dispatch's vault access setting is switched to manual mode.
+- Before implementing an app that connects to an external service, inspect the
+  workspace/provider connection catalog first. Reuse an existing connection and
+  its scoped credential resolver; only then use shared settings, vault, OAuth,
+  onboarding, and provider API primitives for app-local setup.
+- Keep custom setup UI only for provider-specific prerequisites, sequencing,
+  readiness, or health checks. It must link to or call shared settings/OAuth and
+  action surfaces, not duplicate credential storage or transport. Model one
+  logical connection as one onboarding outcome instead of marking every field
+  required by reflex.
 - When an app needs a provider credential, read it through the framework's
   scoped secret or workspace-connection resolver so the Dispatch vault remains
   the source of truth. Framework apps should use `resolveSecret` from