@agent-native/core 0.161.16 → 0.161.20

package/docs/content/deployment.mdx

@@ -7,6 +7,73 @@ description: "Deploy agent-native apps to any platform with Nitro presets — No
 
 Agent-native apps use [Nitro](https://nitro.build) under the hood, which means you can deploy to any platform with zero config changes — just set a preset.
 
+## Fast path: self-host a Chat app locally {#self-host-quickstart}
+
+There are two good starting points, depending on your role:
+
+- **Building an app?** Start with [Getting Started](/docs/getting-started), then return here when you are ready to put the result somewhere permanent.
+- **Operating an app?** Use the local Docker path below first. It exercises the same Node.js, Postgres, authentication, and environment-variable shape you will use on a small server.
+
+The local stack intentionally uses a fake auth secret, trust authentication, and a local Postgres volume. It is for `localhost`, not an internet-facing deployment. Do not reuse the trust-authentication setting in production.
+
+### 1. Create the app
+
+```bash
+npx @agent-native/core@latest create my-app --standalone --template chat
+cd my-app
+pnpm install
+```
+
+The install step creates the lockfile that the production Dockerfile below copies into its build stage.
+
+### 2. Add a local Compose file
+
+Create `docker-compose.yml` in the app root. It uses the [Dockerfile](#docker) in the next section and starts Postgres only on the private Compose network:
+
+You can also download the [Dockerfile](https://www.agent-native.com/examples/self-hosted-chat/Dockerfile), [Compose file](https://www.agent-native.com/examples/self-hosted-chat/docker-compose.yml), and [environment template](https://www.agent-native.com/examples/self-hosted-chat/env.example) as a starter fixture.
+
+```yaml filename="docker-compose.yml" maxLines=40
+services:
+  app:
+    build: .
+    ports:
+      - "127.0.0.1:3000:3000"
+    environment:
+      DATABASE_URL: postgres://agent_native@postgres:5432/agent_native
+      BETTER_AUTH_SECRET: local-development-secret-change-me-1234567890
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  postgres:
+    image: postgres:18
+    environment:
+      POSTGRES_DB: agent_native
+      POSTGRES_USER: agent_native
+      POSTGRES_HOST_AUTH_METHOD: trust
+    volumes:
+      - postgres-data:/var/lib/postgresql
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U agent_native -d agent_native"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+volumes:
+  postgres-data:
+```
+
+### 3. Run it
+
+```bash
+docker compose up --build
+```
+
+Open [http://localhost:3000](http://localhost:3000). The app infers its local auth origin from the browser request. Set `ANTHROPIC_API_KEY` in a local `.env` file if you want to use the embedded agent; leave it empty if you only want to verify that the app and database start. Stop the stack with `docker compose down`; add `-v` when you intentionally want to reset the local database.
+
+Before putting this on the public internet, replace the example secret, configure HTTPS and OAuth callback URLs, use a persistent production database, and complete the [production environment checklist](#env-required-prod).
+
 ## Before You Deploy: Pick a Persistent Database {#persistent-database}
 
 Every deployed app needs a persistent SQL database. In local development, agent-native falls back to a SQLite file at `data/app.db`; that is convenient on your machine, but it is not durable in containers, previews, or serverless environments where the filesystem can be reset.
@@ -233,6 +300,8 @@ receives upstream security updates.
 
 ### Docker {#docker}
 
+This Dockerfile works for the standalone app created above. Run `pnpm install` before building so `pnpm-lock.yaml` exists in the build context. Keep the dependency manifest and lockfile in sync when you update the app.
+
 ```dockerfile filename="Dockerfile"
 FROM node:24-slim AS build
 WORKDIR /app
@@ -247,6 +316,7 @@ COPY --from=build /app/.output .output
 # data/ is a runtime-created SQLite directory — do not copy a dev DB into prod.
 # For production, set DATABASE_URL to a hosted Postgres or Turso instance.
 RUN mkdir -p /app/data
+ENV NODE_ENV=production
 ENV PORT=3000
 EXPOSE 3000
 CMD ["node", ".output/server/index.mjs"]

package/docs/content/faq.mdx

@@ -104,7 +104,7 @@ If you'd rather not manage any of this, the hosted version on `agent-native.com`
 
 ### Can I host this myself? {#can-i-self-host}
 
-Yes. Pick any host that runs Node — Netlify, Vercel, Cloudflare, AWS, Deno Deploy, your own server — and any SQL database (Postgres, SQLite, Turso, D1). The framework is built to be portable. See [Deployment](/docs/deployment).
+Yes. Pick any host that runs Node — Netlify, Vercel, Cloudflare, AWS, Deno Deploy, your own server — and any SQL database (Postgres, SQLite, Turso, D1). The framework is built to be portable. Start with the [local Docker quickstart](/docs/deployment#self-host-quickstart), then use [Deployment](/docs/deployment) for production.
 
 ### What AI models does it support? {#what-models}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.161.16",
+  "version": "0.161.20",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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