Merge branch 'staging' into feat/table-v2-block

Author: TheodoreSpeaks

.agents/skills/add-block/SKILL.md

@@ -640,6 +640,7 @@ import type { BlockConfig, BlockMeta } from '@/blocks/types'
 
 export const {Service}BlockMeta = {
   tags: ['messaging', 'automation'],   // Same tags as the block's tags field
+  url: 'https://{service}.com',         // Canonical homepage of the external service
   templates: [                          // Optional but strongly encouraged
     {
       icon: {Service}Icon,
@@ -666,6 +667,7 @@ export const {Service}BlockMeta = {
 
 - **Import `BlockMeta`** from `@/blocks/types` alongside `BlockConfig`
 - **`tags`** must match the `tags` array on the block config exactly
+- **`url`** is the canonical homepage of the external service the block integrates with (e.g. `'https://exa.ai'`, `'https://salesforce.com'`) — the catalog "link back to the tool". It is distinct from `BlockConfig.docsLink`, which points at Sim's own integration docs on `docs.sim.ai`. Use the service's real root domain over `https` (verify it actually resolves), no tracking params, no trailing slash. Omit `url` only for first-party/built-in blocks that have no external service (e.g. `agent`, `function`, `condition`, `api`, `response`)
 - **Templates are optional** but should be added for any integration that has a recognizable use case — aim for 2–4 templates per block
 - **Template `prompt`** should start with "Build a workflow that..." or "Create a workflow that..." and be concrete enough to generate a real workflow in Mothership
 - **Template `modules`** lists the Sim modules the template relies on: `'knowledge-base' | 'tables' | 'files' | 'workflows' | 'scheduled' | 'agent'`
@@ -906,6 +908,7 @@ All tool IDs referenced in `tools.access` and returned by `tools.config.tool` MU
 - [ ] Outputs match tool outputs
 - [ ] Block registered in `registry.ts` blocks object (alphabetically)
 - [ ] `{Service}BlockMeta` exported at bottom of block file with `tags` and `templates`
+- [ ] `url` set on `{Service}BlockMeta` to the external service's verified homepage (omit only for first-party blocks with no external service)
 - [ ] `skills` added to `{Service}BlockMeta`, each grounded in the block's `tools.access` and derived from a real online-sourced use case (not invented)
 - [ ] `BlockMeta` imported from `@/blocks/types` alongside `BlockConfig`
 - [ ] Block meta registered in `registry.ts` blocksMeta object (alphabetically)

.agents/skills/add-connector/SKILL.md

@@ -12,8 +12,8 @@ You are an expert at adding knowledge base connectors to Sim. A connector syncs
 When the user asks you to create a connector:
 1. Use Context7 or WebFetch to read the service's API documentation
 2. Determine the auth mode: **OAuth** (if Sim already has an OAuth provider for the service) or **API key** (if the service uses API key / Bearer token auth)
-3. Create the connector directory and config
-4. Register it in the connector registry
+3. Create the connector directory: a client-safe `meta.ts` (declarative metadata) plus the runtime module that spreads it
+4. Register it in BOTH the server registry and the client-safe meta registry
 
 ## Hard Rule: No Guessed Response Or Document Schemas
 
@@ -32,13 +32,19 @@ If the source schema is unknown, do one of these instead:
 
 ## Directory Structure
 
+Each connector is split into a client-safe metadata file and a server-only runtime file. This mirrors the `XBlockMeta` / `BLOCK_META_REGISTRY` split in `apps/sim/blocks` — client components (the knowledge UI) only need the metadata (icon, name, auth, config fields), so the runtime functions (which pull server-only helpers like `input-validation.server` → `undici` → `node:net`) must stay out of the client bundle.
+
 Create files in `apps/sim/connectors/{service}/`:
 ```
 connectors/{service}/
-├── index.ts          # Barrel export
-└── {service}.ts      # ConnectorConfig definition
+├── index.ts          # Barrel export (re-exports the runtime connector)
+├── meta.ts           # ConnectorMeta — client-safe declarative metadata
+└── {service}.ts      # ConnectorConfig — spreads the meta + adds runtime functions
 ```
 
+- `meta.ts` exports `{service}ConnectorMeta: ConnectorMeta`. It imports ONLY the icon from `@/components/icons`, `import type { ConnectorMeta } from '@/connectors/types'`, and any pure-data constants. It must NEVER import server/runtime code.
+- `{service}.ts` exports `{service}Connector: ConnectorConfig`. It imports the meta via `import { {service}ConnectorMeta } from '@/connectors/{service}/meta'`, spreads it as the first property, and holds the runtime functions (which may import server-only helpers like `@/lib/knowledge/documents/utils`).
+
 ## Authentication
 
 Connectors use a discriminated union for auth config (`ConnectorAuthConfig` in `connectors/types.ts`):
@@ -55,19 +61,17 @@ For services with existing OAuth providers in `apps/sim/lib/oauth/types.ts`. The
 ### API key mode
 For services that use API key / Bearer token auth. The modal shows a password input with the configured `label` and `placeholder`. The API key is encrypted at rest using AES-256-GCM and stored in a dedicated `encryptedApiKey` column on the connector record. The sync engine decrypts it automatically — connectors receive the raw access token in `listDocuments`, `getDocument`, and `validateConfig`.
 
-## ConnectorConfig Structure
+## Connector Structure (meta.ts + runtime)
+
+The declarative metadata lives in `meta.ts` (`ConnectorMeta`). The runtime functions live in `{service}.ts` (`ConnectorConfig`), which spreads the meta as its first property.
 
-### OAuth connector example
+### `meta.ts` — client-safe metadata
 
 ```typescript
-import { createLogger } from '@sim/logger'
 import { {Service}Icon } from '@/components/icons'
-import { fetchWithRetry } from '@/lib/knowledge/documents/utils'
-import type { ConnectorConfig, ExternalDocument, ExternalDocumentList } from '@/connectors/types'
-
-const logger = createLogger('{Service}Connector')
+import type { ConnectorMeta } from '@/connectors/types'
 
-export const {service}Connector: ConnectorConfig = {
+export const {service}ConnectorMeta: ConnectorMeta = {
   id: '{service}',
   name: '{Service}',
   description: 'Sync documents from {Service} into your knowledge base',
@@ -85,6 +89,26 @@ export const {service}Connector: ConnectorConfig = {
     // Supports 'short-input' and 'dropdown' types
   ],
 
+  // Optional: tag definitions are metadata too — declare them here
+  // tagDefinitions: [ ... ],
+}
+```
+
+Keep `meta.ts` free of any server/runtime import. Only the icon, the `ConnectorMeta` type, and pure-data constants belong here.
+
+### `{service}.ts` — runtime (OAuth example)
+
+```typescript
+import { createLogger } from '@sim/logger'
+import { fetchWithRetry } from '@/lib/knowledge/documents/utils'
+import { {service}ConnectorMeta } from '@/connectors/{service}/meta'
+import type { ConnectorConfig, ExternalDocument, ExternalDocumentList } from '@/connectors/types'
+
+const logger = createLogger('{Service}Connector')
+
+export const {service}Connector: ConnectorConfig = {
+  ...{service}ConnectorMeta,
+
   listDocuments: async (accessToken, sourceConfig, cursor) => {
     // Return metadata stubs with contentDeferred: true (if per-doc content fetch needed)
     // Or full documents with content (if list API returns content inline)
@@ -111,8 +135,11 @@ Only map fields in `listDocuments`, `getDocument`, `validateConfig`, and `mapTag
 
 ### API key connector example
 
+The split is identical — `auth` lives in `meta.ts`, runtime functions in `{service}.ts`.
+
 ```typescript
-export const {service}Connector: ConnectorConfig = {
+// meta.ts
+export const {service}ConnectorMeta: ConnectorMeta = {
   id: '{service}',
   name: '{Service}',
   description: 'Sync documents from {Service} into your knowledge base',
@@ -126,6 +153,11 @@ export const {service}Connector: ConnectorConfig = {
   },
 
   configFields: [ /* ... */ ],
+}
+
+// {service}.ts
+export const {service}Connector: ConnectorConfig = {
+  ...{service}ConnectorMeta,
   listDocuments: async (accessToken, sourceConfig, cursor) => { /* ... */ },
   getDocument: async (accessToken, sourceConfig, externalId) => { /* ... */ },
   validateConfig: async (accessToken, sourceConfig) => { /* ... */ },
@@ -499,7 +531,9 @@ If the service already has an icon in `apps/sim/components/icons.tsx` (from a to
 
 ## Registering
 
-Add one line to `apps/sim/connectors/registry.ts`:
+Register in BOTH registries, keeping the same alphabetical-by-id ordering in each.
+
+1. **Server registry** — `apps/sim/connectors/registry.server.ts` (server-only full registry; holds full connectors with runtime functions, imported by the sync engine and knowledge API routes):
 
 ```typescript
 import { {service}Connector } from '@/connectors/{service}'
@@ -510,6 +544,19 @@ export const CONNECTOR_REGISTRY: ConnectorRegistry = {
 }
 ```
 
+2. **Client-safe meta registry** — `apps/sim/connectors/registry.ts` (imports each connector's `meta.ts` only, so client components can use it without pulling server-only code; the metadata counterpart to `BLOCK_META_REGISTRY`):
+
+```typescript
+import { {service}ConnectorMeta } from '@/connectors/{service}/meta'
+
+export const CONNECTOR_META_REGISTRY: ConnectorMetaRegistry = {
+  // ... existing connector metas ...
+  {service}: {service}ConnectorMeta,
+}
+```
+
+`registry.ts` exports `CONNECTOR_META_REGISTRY: ConnectorMetaRegistry` plus the helpers `getConnectorMeta(id)` and `getAllConnectorMeta()`, importing each `@/connectors/{service}/meta` directly — never the runtime module. `registry.server.ts` exports `CONNECTOR_REGISTRY: ConnectorRegistry`.
+
 ## Reference Implementations
 
 - **OAuth + contentDeferred**: `apps/sim/connectors/google-drive/google-drive.ts` — file download with metadata-based hash, `orderBy` for deterministic pagination
@@ -520,7 +567,8 @@ export const CONNECTOR_REGISTRY: ConnectorRegistry = {
 
 ## Checklist
 
-- [ ] Created `connectors/{service}/{service}.ts` with full ConnectorConfig
+- [ ] Created `connectors/{service}/meta.ts` with `{service}ConnectorMeta: ConnectorMeta` (icon, name, auth, configFields, tagDefinitions) — no server/runtime imports
+- [ ] Created `connectors/{service}/{service}.ts` with `{service}Connector: ConnectorConfig` spreading the meta + runtime functions
 - [ ] Created `connectors/{service}/index.ts` barrel export
 - [ ] **Auth configured correctly:**
   - OAuth: `auth.provider` matches an existing `OAuthService` in `lib/oauth/types.ts`
@@ -542,4 +590,5 @@ export const CONNECTOR_REGISTRY: ConnectorRegistry = {
 - [ ] All external API calls use `fetchWithRetry` (not raw `fetch`)
 - [ ] All optional config fields validated in `validateConfig`
 - [ ] Icon exists in `components/icons.tsx` (or asked user to provide SVG)
-- [ ] Registered in `connectors/registry.ts`
+- [ ] Registered the full connector in `connectors/registry.server.ts`
+- [ ] Registered the meta in `connectors/registry.ts` (same alphabetical-by-id ordering as registry.server.ts)

.agents/skills/add-model/SKILL.md

@@ -143,12 +143,12 @@ If anything matches, run the affected provider tests and update assertions as ne
 
 ### New API behavior is NOT data-driven
 
-The Consumption Matrix (Step 2) tells you which capability *flags* are honored by existing provider code. But if the new model needs **net-new** request handling that the provider doesn't implement yet — a new beta header (e.g. Anthropic's `anthropic-beta` structured-outputs header in `anthropic/index.ts`), a new thinking/reasoning encoding, a Responses-API quirk — you must edit `apps/sim/providers/<provider>/core.ts` / `index.ts`. Setting a flag whose behavior isn't implemented is a silent no-op.
+The Consumption Matrix (Step 2) tells you which capability *flags* are honored by existing provider code. But if the new model needs **net-new** request handling that the provider doesn't implement yet — a new beta header (e.g. Anthropic's `anthropic-beta` structured-outputs header in `anthropic/index.ts`), a new thinking/reasoning encoding, a Responses-API quirk — you must edit `apps/sim/providers/<provider>/core.ts` / `index.ts`. Setting a flag whose behavior isn't implemented is a silent no-op. When you do edit provider code, reuse the shared helpers rather than hand-rolling: streaming responses are assembled via `createStreamingExecution` (`@/providers/streaming-execution`) and tool schemas via `adaptOpenAIChatToolSchema` / `adaptAnthropicToolSchema` (`@/providers/tool-schema-adapter`).
 
 ### Wrong family entirely?
 
 - **Embedding or rerank model** → it does NOT go in the `models[]` array. Use `EMBEDDING_MODEL_PRICING` / `RERANK_MODEL_PRICING` in `models.ts` instead.
-- **Brand-new provider** (not just a new model under an existing one) → much larger surface: add the id to `ProviderId` in `providers/types.ts`, a registry entry in `providers/registry.ts`, a provider implementation under `providers/<id>/`, an icon in `components/icons.tsx`, and the `PROVIDER_DEFINITIONS` block. That is beyond this skill — tell the user.
+- **Brand-new provider** (not just a new model under an existing one) → much larger surface: add the id to `ProviderId` in `providers/types.ts`, a registry entry in `providers/registry.ts`, a provider implementation under `providers/<id>/` (assemble streaming responses with `createStreamingExecution` and wrap tool schemas with the `@/providers/tool-schema-adapter` helpers), an icon in `components/icons.tsx`, and the `PROVIDER_DEFINITIONS` block. That is beyond this skill — tell the user.
 
 ## Step 5: Write, lint