@agent-native/core 0.161.16 → 0.161.20

package/dist/observability/routes.d.ts

@@ -41,27 +41,27 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
-    ok?: undefined;
-    error?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-} | {
     ok?: undefined;
     error?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id: string;
-} | {
     ok?: undefined;
+    error?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
+    ok?: undefined;
 } | {
-    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/secrets/routes.d.ts

@@ -34,16 +34,16 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    ok?: undefined;
     status?: undefined;
+    ok?: undefined;
 } | {
     ok: boolean;
     status: string;
     error?: undefined;
 } | {
-    ok?: undefined;
     error: string;
     removed?: undefined;
+    ok?: undefined;
 } | {
     ok: boolean;
     removed: boolean;
@@ -54,9 +54,9 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
     note?: undefined;
+    ok?: undefined;
 } | {
     ok: boolean;
     note?: undefined;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,10 +27,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
+    error?: undefined;
 }>>;
 export {};

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/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
+    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
-    error?: undefined;
 }>>;

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/chat/vitest.config.ts

@@ -1,9 +1,14 @@
-import baseConfig from "@agent-native/core/vitest-config";
-import { mergeConfig } from "vitest/config";
+import path from "node:path";
 
-import viteConfig from "./vite.config";
+import { defineConfig } from "vitest/config";
 
-// Kept separate from vite.config.ts so the production config never imports
-// vitest: `agent-native build` loads vite.config.ts in installs where vitest
-// is absent.
-export default mergeConfig(viteConfig, baseConfig);
+// Keep tests independent from vite.config.ts: the production config starts
+// Nitro/Vite watchers and evaluates browser-targeted CommonJS SSR modules.
+export default defineConfig({
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./app"),
+      "@shared": path.resolve(__dirname, "./shared"),
+    },
+  },
+});

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