@agent-native/core 0.161.17 → 0.161.22

package/dist/server/cookie-namespace.js

@@ -1,9 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+import { getAppConfig } from "../app-config/index.js";
+import { isTruthyRuntimeValue } from "../shared/runtime-config.js";
 const FIRST_PARTY_COOKIE_DOMAIN = "agent-native.com";
 export function resolveAuthCookieNamespace(env = process.env, cwd = process.cwd()) {
-    const isWorkspaceMode = env.AGENT_NATIVE_WORKSPACE === "1" ||
-        env.VITE_AGENT_NATIVE_WORKSPACE === "1";
+    const isWorkspaceMode = env === process.env
+        ? isConfiguredWorkspaceRuntime()
+        : isWorkspaceModeFromEnv(env);
     const configuredCookieDomain = normalizeCookieDomain(env.COOKIE_DOMAIN);
     const isFirstPartyCookieDomain = normalizeDomainForCompare(configuredCookieDomain) ===
         FIRST_PARTY_COOKIE_DOMAIN;
@@ -63,6 +66,18 @@ export function resolveAuthCookieNamespace(env = process.env, cwd = process.cwd(
         isFirstPartyCookieDomain,
     };
 }
+function isConfiguredWorkspaceRuntime() {
+    const workspace = getAppConfig().workspace;
+    return (workspace.isWorkspace === true || typeof workspace.appsJson === "string");
+}
+function isWorkspaceModeFromEnv(env) {
+    const workspaceFlag = firstConfiguredValue(env.AGENT_NATIVE_WORKSPACE, env.VITE_AGENT_NATIVE_WORKSPACE);
+    const workspaceApps = firstConfiguredValue(env.AGENT_NATIVE_WORKSPACE_APPS_JSON, env.VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON);
+    return isTruthyRuntimeValue(workspaceFlag) || Boolean(workspaceApps);
+}
+function firstConfiguredValue(...values) {
+    return values.find((value) => value?.trim())?.trim();
+}
 function readPackageJsonName(cwd) {
     try {
         const raw = fs.readFileSync(path.join(cwd, "package.json"), "utf8");

package/dist/server/credential-provider.js

@@ -22,6 +22,7 @@ import { CREDENTIAL_STORE_UNAVAILABLE_ERROR_CODE, GATEWAY_UNAVAILABLE_VISITOR_ME
 import { getAppConfig } from "../app-config/index.js";
 import { getDbExec, isLocalDatabase, isTransientDatabaseError, } from "../db/client.js";
 import { getOrgSetting } from "../settings/org-settings.js";
+import { isTruthyRuntimeValue } from "../shared/runtime-config.js";
 import { getRequestUserEmail, getRequestOrgId } from "./request-context.js";
 const DISPATCH_VAULT_ACCESS_SETTINGS_KEY = "dispatch-vault-access-settings";
 /**
@@ -209,8 +210,10 @@ function isHostedWorkspaceRuntime() {
     const hasFusionPreview = Boolean(process.env.FUSION_ENVIRONMENT ||
         process.env.FUSION_ENV_ORIGIN ||
         process.env.VITE_FUSION_ENV_ORIGIN);
-    return (/^(1|true)$/i.test(process.env.AGENT_NATIVE_WORKSPACE ?? "") ||
-        /^(1|true)$/i.test(process.env.VITE_AGENT_NATIVE_WORKSPACE ?? "") ||
+    return (isTruthyRuntimeValue(process.env.AGENT_NATIVE_WORKSPACE) ||
+        isTruthyRuntimeValue(process.env.VITE_AGENT_NATIVE_WORKSPACE) ||
+        Boolean(process.env.AGENT_NATIVE_WORKSPACE_APPS_JSON?.trim()) ||
+        Boolean(process.env.VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON?.trim()) ||
         hasFusionPreview);
 }
 function isProductionLikeRuntime() {

package/dist/server/derived-secret.js

@@ -1,8 +1,9 @@
 import crypto from "node:crypto";
+import { getAppConfig } from "../app-config/index.js";
 const DERIVED_SECRET_PREFIX = "agent-native:derived-secret:v1";
 function isWorkspaceRuntime() {
-    return (process.env.AGENT_NATIVE_WORKSPACE === "1" ||
-        process.env.VITE_AGENT_NATIVE_WORKSPACE === "1");
+    const workspace = getAppConfig().workspace;
+    return (workspace.isWorkspace === true || typeof workspace.appsJson === "string");
 }
 export function deriveServerSecret(rootSecret, purpose) {
     return crypto

package/dist/server/onboarding-html.js

@@ -6,6 +6,7 @@
  *
  * After first account exists, this page acts as a normal login page.
  */
+import { getAppConfig } from "../app-config/index.js";
 import { getLocaleInitScript } from "../localization/server.js";
 import { DEFAULT_LOCALE, LOCALE_METADATA, LOCALE_STORAGE_KEY, SUPPORTED_LOCALES, } from "../localization/shared.js";
 import { NATIVE_AUTH_COPY } from "../shared/auth-copy.js";
@@ -42,6 +43,25 @@ function getConnectionLabel() {
         return "Turso";
     return "SQL database";
 }
+function isWorkspaceRuntime() {
+    const workspace = getAppConfig().workspace;
+    return (workspace.isWorkspace === true || typeof workspace.appsJson === "string");
+}
+function workspaceBasePathFromRequest(requestPath) {
+    if (!isWorkspaceRuntime() || !requestPath)
+        return "";
+    const pathname = requestPath.split(/[?#]/, 1)[0] || "/";
+    const firstSegment = pathname.split("/").find(Boolean);
+    if (!firstSegment ||
+        firstSegment === "_agent-native" ||
+        firstSegment === "api" ||
+        firstSegment === "sign-in" ||
+        firstSegment === "login" ||
+        firstSegment === "signup") {
+        return "";
+    }
+    return normalizeAppBasePath(`/${firstSegment}`);
+}
 function withAppBasePath(path) {
     const cleanPath = path.startsWith("/") ? path : `/${path}`;
     const basePath = normalizeAppBasePath(process.env.VITE_APP_BASE_PATH || process.env.APP_BASE_PATH);
@@ -997,7 +1017,9 @@ export function getOnboardingHtml(opts = {}) {
     // for every visitor. A genuinely misconfigured server instead surfaces a
     // clear error at click time via the auth API.
     const renderGoogleButton = showGoogle || googleOnly;
-    const appBasePath = normalizeAppBasePath(process.env.VITE_APP_BASE_PATH || process.env.APP_BASE_PATH);
+    const configuredAppBasePath = normalizeAppBasePath(process.env.VITE_APP_BASE_PATH || process.env.APP_BASE_PATH);
+    const appBasePath = configuredAppBasePath || workspaceBasePathFromRequest(opts.requestPath);
+    const workspaceRuntime = isWorkspaceRuntime();
     const publicOAuthOrigin = getPublicOAuthOrigin();
     const workspaceGatewayReturnOrigin = getWorkspaceGatewayReturnOrigin();
     const googleAuthMode = resolveGoogleAuthMode(opts.googleAuthMode);
@@ -2126,7 +2148,17 @@ ${signupLocalModeNoteHtml}
     if (configured) return configured;
     var marker = '/_agent-native';
     var idx = window.location.pathname.indexOf(marker);
-    return idx > 0 ? window.location.pathname.slice(0, idx) : '';
+    if (idx > 0) return window.location.pathname.slice(0, idx);
+    if (${JSON.stringify(workspaceRuntime)}) {
+      var segments = window.location.pathname.split('/');
+      for (var i = 0; i < segments.length; i++) {
+        var segment = segments[i];
+        if (segment && segment !== '_agent-native' && segment !== 'api' && segment !== 'sign-in' && segment !== 'login' && segment !== 'signup') {
+          return '/' + segment;
+        }
+      }
+    }
+    return '';
   }
     function __anPath(path) {
       return __anBasePath() + path;

package/dist/server/workspace-oauth.js

@@ -1,3 +1,5 @@
+import { getAppConfig } from "../app-config/index.js";
+import { isTruthyRuntimeValue } from "../shared/runtime-config.js";
 /**
  * Whether workspace OAuth callbacks use the root framework relay.
  *
@@ -8,13 +10,16 @@
  * the mounted app that initiated it.
  */
 export function isWorkspaceOAuthCallbackRelayEnabled() {
+    const workspace = getAppConfig().workspace;
     const metaEnv = import.meta.env;
-    return ([
-        process.env.AGENT_NATIVE_WORKSPACE,
-        process.env.VITE_AGENT_NATIVE_WORKSPACE,
-        metaEnv?.AGENT_NATIVE_WORKSPACE,
-        metaEnv?.VITE_AGENT_NATIVE_WORKSPACE,
-    ].some((value) => value === "1" || value === "true") ||
+    return (workspace.isWorkspace === true ||
+        typeof workspace.appsJson === "string" ||
+        [
+            process.env.AGENT_NATIVE_WORKSPACE,
+            process.env.VITE_AGENT_NATIVE_WORKSPACE,
+            metaEnv?.AGENT_NATIVE_WORKSPACE,
+            metaEnv?.VITE_AGENT_NATIVE_WORKSPACE,
+        ].some((value) => isTruthyRuntimeValue(value)) ||
         [
             process.env.AGENT_NATIVE_WORKSPACE_APP_ID,
             process.env.VITE_AGENT_NATIVE_WORKSPACE_APP_ID,

package/dist/shared/runtime-config.d.ts

@@ -37,6 +37,8 @@ export interface RuntimeConfigReportOptions {
     phase?: RuntimeConfigPhase;
     appName?: string;
 }
+/** Parse the truthy spellings accepted by typed runtime configuration flags. */
+export declare function isTruthyRuntimeValue(value: string | boolean | undefined): boolean;
 export declare function runtimeConfigRequirementsFromSearchParams(searchParams: URLSearchParams): RuntimeConfigRequirements;
 export declare function buildRuntimeConfigPrompt(report: Pick<RuntimeConfigReport, "environment" | "phase" | "issues">, appName?: string): string;
 export declare function getRuntimeConfigReport(env: Record<string, string | undefined>, requirements?: RuntimeConfigRequirements, options?: RuntimeConfigReportOptions): RuntimeConfigReport;

package/dist/shared/runtime-config.js

@@ -5,6 +5,13 @@
  * process.env so the same rules can run during a Vite build, on the server,
  * and in focused tests without ever exposing secret values to the browser.
  */
+/** Parse the truthy spellings accepted by typed runtime configuration flags. */
+export function isTruthyRuntimeValue(value) {
+    if (value === true)
+        return true;
+    return (typeof value === "string" &&
+        ["1", "true", "yes", "on"].includes(value.trim().toLowerCase()));
+}
 const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const RUNTIME_CONFIG_ISSUE_CODES = new Set([
     "auth-disabled-in-production",
@@ -36,7 +43,7 @@ function valueOf(env, key) {
     return value || undefined;
 }
 function truthy(value) {
-    return value === "1" || value?.toLowerCase() === "true";
+    return isTruthyRuntimeValue(value);
 }
 function isProductionEnvironment(env) {
     return (valueOf(env, "NODE_ENV") === "production" ||
@@ -44,8 +51,10 @@ function isProductionEnvironment(env) {
         valueOf(env, "VERCEL_ENV") === "production");
 }
 function isWorkspaceRuntime(env) {
-    return (valueOf(env, "AGENT_NATIVE_WORKSPACE") === "1" ||
-        valueOf(env, "VITE_AGENT_NATIVE_WORKSPACE") === "1");
+    return (isTruthyRuntimeValue(valueOf(env, "AGENT_NATIVE_WORKSPACE")) ||
+        isTruthyRuntimeValue(valueOf(env, "VITE_AGENT_NATIVE_WORKSPACE")) ||
+        Boolean(valueOf(env, "AGENT_NATIVE_WORKSPACE_APPS_JSON")) ||
+        Boolean(valueOf(env, "VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON")));
 }
 function appEnvPrefix(env, appName) {
     const raw = appName ?? valueOf(env, "APP_NAME");

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