@agent-native/core 0.161.17 → 0.161.22

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

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

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

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

package/corpus/templates/crm/AGENTS.md

@@ -30,6 +30,7 @@ HubSpot/Salesforce lens; UI and agent share actions.
 
 - Workspace Connections own provider credentials. Never request, store, log, or
   return a provider token.
+- For external integrations, inspect the workspace/provider connection catalog first; reuse its scoped resolver.
 - The mirror is thin: unknown fields are remote-only, sensitive ones redacted,
   only allow-listed fields mirrored. Raw payloads, transcripts, media, and
   base64 never enter SQL — evidence is a URL/id plus a bounded quote.

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

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

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

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

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

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

package/corpus/templates/design/AGENTS.md

@@ -45,6 +45,7 @@ Read the relevant skill before deeper work in that area.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private
   Builder/internal data, customer data, or credential-looking literals. Use
   secrets/OAuth/runtime configuration and obvious placeholders in examples.
+- For external integrations, inspect the workspace/provider connection catalog first; reuse its scoped resolver.
 - Use the app actions for designs, files, versions, design systems, variants,
   export, and sharing. Do not write design rows directly with SQL.
 - A message beginning with `[Reprompt selection]` is preview-only: the only

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

@@ -985,6 +985,7 @@ const enUS = {
       applyButton: "Apply styles",
       previewLabel: "Pending visual preview",
       applyDesignUpdates: "Apply design update",
+      applying: "Applying…",
       verifying: "Verifying source and runtime…",
       retryWithAgent: "Retry source verification",
       copyPrompt: "Copy prompt to your agent",
@@ -11443,6 +11444,7 @@ const designPendingVisualStyleOverrides = {
         applyButton: "套用樣式",
         previewLabel: "待處理的視覺預覽",
         applyDesignUpdates: "套用設計更新",
+        applying: "正在套用…",
         verifying: "正在驗證來源與執行階段…",
         retryWithAgent: "重試來源驗證",
         copyPrompt: "將提示複製給您的代理",
@@ -11476,6 +11478,7 @@ const designPendingVisualStyleOverrides = {
         applyButton: "应用样式",
         previewLabel: "待处理的视觉预览",
         applyDesignUpdates: "应用设计更新",
+        applying: "正在应用…",
         verifying: "正在验证源文件和运行时…",
         retryWithAgent: "重试源文件验证",
         copyPrompt: "将提示复制给你的代理",
@@ -11509,6 +11512,7 @@ const designPendingVisualStyleOverrides = {
         applyButton: "Aplicar estilos",
         previewLabel: "Vista previa visual pendiente",
         applyDesignUpdates: "Aplicar actualizaciones de diseño",
+        applying: "Aplicando…",
         verifying: "Verificando el código y el runtime…",
         retryWithAgent: "Reintentar verificación del código",
         copyPrompt: "Copiar prompt a tu agente",
@@ -11544,6 +11548,7 @@ const designPendingVisualStyleOverrides = {
         applyButton: "Appliquer les styles",
         previewLabel: "Aperçu visuel en attente",
         applyDesignUpdates: "Appliquer les mises à jour du design",
+        applying: "Application…",
         verifying: "Vérification de la source et du runtime…",
         retryWithAgent: "Réessayer la vérification de la source",
         copyPrompt: "Copier le prompt vers votre agent",
@@ -11579,6 +11584,7 @@ const designPendingVisualStyleOverrides = {
         applyButton: "Stile anwenden",
         previewLabel: "Ausstehende visuelle Vorschau",
         applyDesignUpdates: "Design-Updates anwenden",
+        applying: "Wird angewendet…",
         verifying: "Quelle und Laufzeit werden überprüft…",
         retryWithAgent: "Quellprüfung wiederholen",
         copyPrompt: "Prompt an deinen Agent kopieren",
@@ -11614,6 +11620,7 @@ const designPendingVisualStyleOverrides = {
         applyButton: "スタイルを適用",
         previewLabel: "保留中のビジュアルプレビュー",
         applyDesignUpdates: "デザインの更新を適用",
+        applying: "適用中…",
         verifying: "ソースとランタイムを検証中…",
         retryWithAgent: "ソース検証を再試行",
         copyPrompt: "エージェントにプロンプトをコピー",
@@ -11649,6 +11656,7 @@ const designPendingVisualStyleOverrides = {
         applyButton: "스타일 적용",
         previewLabel: "보류 중인 시각 미리보기",
         applyDesignUpdates: "디자인 업데이트 적용",
+        applying: "적용 중…",
         verifying: "소스와 런타임 확인 중…",
         retryWithAgent: "소스 확인 다시 시도",
         copyPrompt: "에이전트에 프롬프트 복사",
@@ -11683,6 +11691,7 @@ const designPendingVisualStyleOverrides = {
         applyButton: "Aplicar estilos",
         previewLabel: "Prévia visual pendente",
         applyDesignUpdates: "Aplicar atualizações de design",
+        applying: "Aplicando…",
         verifying: "Verificando origem e runtime…",
         retryWithAgent: "Tentar verificar a origem novamente",
         copyPrompt: "Copiar prompt para seu agente",
@@ -11718,6 +11727,7 @@ const designPendingVisualStyleOverrides = {
         applyButton: "Styles लागू करें",
         previewLabel: "लंबित visual preview",
         applyDesignUpdates: "डिज़ाइन अपडेट लागू करें",
+        applying: "लागू किया जा रहा है…",
         verifying: "Source और runtime सत्यापित हो रहे हैं…",
         retryWithAgent: "Source verification फिर करें",
         copyPrompt: "Prompt अपने agent को कॉपी करें",
@@ -11751,6 +11761,7 @@ const designPendingVisualStyleOverrides = {
         applyButton: "تطبيق الأنماط",
         previewLabel: "معاينة مرئية معلقة",
         applyDesignUpdates: "تطبيق تحديثات التصميم",
+        applying: "جارٍ التطبيق…",
         verifying: "جارٍ التحقق من المصدر ووقت التشغيل…",
         retryWithAgent: "إعادة التحقق من المصدر",
         copyPrompt: "نسخ الموجه إلى وكيلك",

package/corpus/templates/design/app/lib/agent-chat.ts

@@ -47,11 +47,11 @@ export interface DesignSourceHandoffResult {
   target: "host" | "local";
   delivered: boolean;
   /**
-   * The host prefilled its composer and the user has not sent it yet. Callers
-   * must not treat this as applied: discarding pending edits here loses work
-   * the agent was never asked to do.
+   * The host accepted the handoff and owns the turn from here. Callers must not
+   * treat this as applied: the edits stay pending until that turn settles, or a
+   * failed run would silently discard them.
    */
-  staged?: boolean;
+  awaitingHostTurn?: boolean;
   reason?: string;
   tabId?: string;
 }
@@ -72,19 +72,20 @@ export async function sendDesignSourceHandoffAndConfirm(
   options?: { timeoutMs?: number },
 ): Promise<DesignSourceHandoffResult> {
   // `embedChrome` alone is a display preference any embedder can ask for, so the
-  // shell route is what decides who receives source-edit context. `submit` is
-  // the host's call there, and its composer filling is the delivery evidence.
+  // shell route is what decides who receives source-edit context.
   if (isEmbedChromeRequested() && isBuilderHostEmbed()) {
     const posted = sendToBuilderChat({
       message: opts.message,
       context: opts.context,
-      submit: false,
+      // Runs the turn rather than prefilling: the prompt is generated from the
+      // pending edits, so there is nothing for the user to write or review.
+      submit: true,
       targetOrigin: getVerifiedBuilderHostOrigin() ?? undefined,
     });
     return {
       target: "host",
       delivered: posted,
-      ...(posted ? { staged: true } : { reason: "host-post-failed" }),
+      ...(posted ? { awaitingHostTurn: true } : { reason: "host-post-failed" }),
     };
   }
 

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

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

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

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

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

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

package/corpus/templates/dispatch/AGENTS.md

@@ -17,6 +17,7 @@ Read the relevant skill before deeper work:
   persist URLs, ids, or handles instead of base64, media, documents, archives,
   screenshots, thumbnails, or replay chunks.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
+- For external integrations, inspect the workspace/provider connection catalog first; reuse its scoped resolver.
 - Treat Dispatch as workspace infrastructure. Prefer actions over raw SQL for
   vault, integrations, resource grants, messaging, routing, and approvals.
 - Do not expose secret values. Vault stores references and encrypted values; apps
@@ -24,11 +25,10 @@ Read the relevant skill before deeper work:
 - Workspace integrations own provider identity, readiness, metadata, and grants.
   Domain apps still own provider-specific readers and interpretation.
 - Integration grants are not provider capability limits. For ad hoc provider
-  inspection, querying, reporting, or troubleshooting, call
-  `provider-api-catalog` / `provider-api-docs`, then `provider-api-request`
-  against the provider's real HTTP API. Use `connectionId` for a specific shared
-  grant and `accountId` for a specific OAuth account. Do not expose secret
-  values or silently widen app access while doing this.
+  analysis, call `provider-api-catalog` / `provider-api-docs`, then
+  `provider-api-request` against the provider's HTTP API. Use `connectionId` for
+  a shared grant and `accountId` for an OAuth account. Never expose secrets or
+  widen app access.
 - Use `view-screen` when the current integration, resource, approval, route, or
   setup item is unclear.
 - Use `import-agent` to normalize safe Claude Markdown or JSON into an

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

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

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

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

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

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

package/corpus/templates/factory/AGENTS.md

@@ -41,6 +41,7 @@ decisions, feedback, agent runs, and provider audit records.
 - Provider credentials belong to Dispatch/shared workspace integrations, never
   to a Factory or Factory graph. Agents use shared provider APIs and connected
   MCP tools through the workspace grant boundary.
+- For external integrations, inspect the workspace/provider connection catalog first; reuse its scoped resolver.
 
 ## Application state
 

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

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

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

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

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