docs(agents): fix contradictions and stale facts in integration skills

Verified against the code: tags live on BlockMeta, not BlockConfig;
check-block-registry requires required user-only params to be filled by a
subBlock of the same id, so remapping them in tools.config.params fails CI;
subblock ids are unique per condition; matchEvent may return a
NextResponse; createHmacVerifier needs requireSecret to fail closed;
FileToolProcessor is executor-side; provider scopes live in
lib/auth/connectors/providers.ts; BYOK needs PROVIDER_SECTIONS; polling
crons need the matching docker/crontab line. Duplicated option-list and
regenerate sections now point at one copy.

Author: waleedlatif1

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

@@ -35,7 +35,6 @@ export const {ServiceName}Block: BlockConfig = {
   docsLink: 'https://docs.sim.ai/integrations/{service}',
   category: 'tools',                    // 'tools' | 'blocks' | 'triggers'
   integrationType: IntegrationType.X,   // Primary category (see IntegrationType enum)
-  tags: ['oauth', 'api'],              // Cross-cutting tags (see IntegrationTag type)
   bgColor: '#HEXCOLOR',                 // Brand color
   icon: {ServiceName}Icon,
 
@@ -63,7 +62,7 @@ export const {ServiceName}Block: BlockConfig = {
   },
 
   inputs: {
-    // Optional: define expected inputs from other blocks
+    // Required: the params the block accepts, keyed by tool param / canonical id
   },
 
   outputs: {
@@ -74,7 +73,7 @@ export const {ServiceName}Block: BlockConfig = {
 
 ## SubBlock Types Reference
 
-**Critical:** Every subblock `id` must be unique within the block. Duplicate IDs cause conflicts even with different conditions.
+**Critical:** A subblock `id` is unique per condition. The only sanctioned cross-condition reuse is the hosted-key `apiKey` pair (`add-hosted-key` skill), where both fields deliberately share one value. `blocks.test.ts` fails same-condition duplicates.
 
 ### Text Inputs
 ```typescript
@@ -129,6 +128,7 @@ export const {ServiceName}Block: BlockConfig = {
   id: 'credential',
   title: 'Account',
   type: 'oauth-input',
+  canonicalParamId: 'oauthCredential',
   serviceId: '{service}',  // Must match OAuth provider service key
   requiredScopes: getScopesForService('{service}'),  // Import from @/lib/oauth/utils
   placeholder: 'Select account',
@@ -370,8 +370,6 @@ Declare the **canonical** id with `type: 'json'` — the subblock ids never reac
 ```typescript
 inputs: {
   file: { type: 'json', description: 'File to upload (UserFile or reference)' },
-  // Legacy field for backwards compatibility
-  fileContent: { type: 'string', description: 'Legacy: base64 encoded content' },
 }
 ```
 
@@ -500,6 +498,7 @@ Controls which UI view shows the field.
 - `'advanced'` - Only in advanced view
 - `'both'` - Both views (default if not specified)
 - `'trigger'` - Only in trigger configuration
+- `'trigger-advanced'` - The advanced side of a trigger field (a canonical pair member, or a standalone field under the block-level advanced toggle)
 
 ### canonicalParamId Pattern
 
@@ -616,7 +615,7 @@ tools: {
 - `items` property - This is only for tool outputs with array types
 
 Block outputs only support:
-- `type` - The data type ('string', 'number', 'boolean', 'json', 'array')
+- `type` - The data type ('string', 'number', 'boolean', 'json', 'array', 'file', 'file[]', 'any')
 - `description` - Human readable description
 - `condition` - Optional visibility condition
 - `hiddenFromDisplay` - Optional flag to hide from the output display
@@ -679,7 +678,7 @@ export const ServiceV2Block: BlockConfig = {
     access: ServiceBlock.tools?.access?.map(id => `${id}_v2`) || [],
     config: {
       tool: createVersionedToolSelector({
-        baseToolSelector: (params) => (ServiceBlock.tools?.config as any)?.tool(params),
+        baseToolSelector: (params) => ServiceBlock.tools.config?.tool(params) ?? 'service_default',
         suffix: '_v2',
         fallbackToolId: 'service_default_v2',
       }),
@@ -726,11 +725,23 @@ export const ServiceBlock: BlockConfig = {
   docsLink: 'https://docs.sim.ai/integrations/service',
   category: 'tools',
   integrationType: IntegrationType.DeveloperTools,
-  tags: ['oauth', 'api'],
   bgColor: '#FF6B6B',
   icon: ServiceIcon,
   authMode: AuthMode.OAuth,
 
+  // Sentence rules: apps/sim/blocks/AGENTS.md → "Canvas sentences"
+  canvasPresentation: {
+    defaultTitle: 'Create Resource',
+    sentences: {
+      byOperation: {
+        create: [{ text: 'Create resource', field: 'name', core: true }],
+        read: [{ text: 'Read resource', field: 'resourceId', core: true }],
+        update: [{ text: 'Update resource', field: 'resourceId', core: true }],
+        delete: [{ text: 'Delete resource', field: 'resourceId', core: true }],
+      },
+    },
+  },
+
   subBlocks: [
     {
       id: 'operation',
@@ -748,6 +759,7 @@ export const ServiceBlock: BlockConfig = {
       id: 'credential',
       title: 'Service Account',
       type: 'oauth-input',
+      canonicalParamId: 'oauthCredential',
       serviceId: 'service',
       requiredScopes: getScopesForService('service'),
       placeholder: 'Select account',
@@ -778,6 +790,13 @@ export const ServiceBlock: BlockConfig = {
     },
   },
 
+  inputs: {
+    operation: { type: 'string', description: 'Operation to perform' },
+    oauthCredential: { type: 'string', description: 'Service access token' },
+    resourceId: { type: 'string', description: 'Resource ID' },
+    name: { type: 'string', description: 'Resource name' },
+  },
+
   outputs: {
     id: { type: 'string', description: 'Resource ID' },
     name: { type: 'string', description: 'Resource name' },
@@ -937,30 +956,17 @@ tool IDs through `tools.access` and does not change any tool's shape.
 
 But if the same change also adds, edits **or removes** a tool, run `bun run tool-metadata:generate` and commit the result, or CI fails on stale artifacts. That matters here because a block's `outputs` are authored to match its tools' outputs, and the UI reads those from the generated metadata, not the executable registry — an unregenerated tool change makes the block's outputs disagree with what the panel renders. See `.agents/skills/tool-registry-boundary/SKILL.md`.
 
-A visible integration block does require the generated integration catalog and docs to be refreshed.
-After adding or changing one, run:
-
-```bash
-bun run scripts/generate-docs.ts
-bun run deployment-config:generate
-bun run integration-catalog:check
-bun run deployment-config:check
-bun run docs:check
-```
-
-The catalog check independently derives deployment metadata from the executable block registry and
-compares it with the committed `packages/deployment-config/src/integrations.json`. The deployment
-config check verifies the generated service-account facts against the canonical OAuth registry and
-catalog. `docs:check` re-renders every generated docs artifact in memory and fails on any committed
-file that differs — it runs in CI via `check:audits`, so commit the full generator output. If the
-generator also trues up pages an earlier PR left stale, commit that catch-up too; reverting it as
-"unrelated drift" makes `docs:check` fail. Review the generated diff and keep only intentional
-changes.
+A visible integration block does require the generated integration catalog and docs to be refreshed:
+`bun run tool-metadata:generate` (only when a tool changed), `bun run scripts/generate-docs.ts`,
+`bun run deployment-config:generate`, then `bun run check:audits`. Also run
+`bun run apps/sim/scripts/check-block-registry.ts` (CI runs it outside `check:audits`). Commit the
+full generator output. For what each check verifies, see the `validate-integration` skill →
+Regenerate Derived Artifacts.
 
 ## Checklist Before Finishing
 
 - [ ] `integrationType` is set to the correct `IntegrationType` enum value
-- [ ] `tags` array includes all applicable `IntegrationTag` values
+- [ ] `{Service}BlockMeta.tags` lists every applicable `IntegrationTag` (tags live on the meta, not the block)
 - [ ] All subBlocks have `id`, `title` (except switch), and `type`
 - [ ] Conditions use correct syntax (field, value, not, and)
 - [ ] DependsOn set for fields that need other values
@@ -996,7 +1002,7 @@ Validate the block against every tool in `tools.access`:
 2. **For each tool, verify the block has correct:**
    - SubBlock inputs that cover all required tool params (with correct `condition` to show for that operation)
    - SubBlock input types that match the tool param types (e.g., dropdown for enums, short-input for strings)
-   - `tools.config.params` correctly maps subBlock IDs to tool param names (if they differ)
+   - Each subBlock (or its `canonicalParamId`) is named exactly after the tool param it fills. A required `user-only` param that is only renamed in `tools.config.params` fails `bun run apps/sim/scripts/check-block-registry.ts`; remap only optional or `user-or-llm` params
    - Type coercions in `tools.config.params` for any params that need conversion (Number(), Boolean(), JSON.parse())
 3. **Verify block outputs** cover the key fields returned by all tools
 4. **Verify conditions** — each subBlock should only show for the operations that actually use it

.agents/skills/add-hosted-key/SKILL.md

@@ -198,7 +198,7 @@ In the block config (`blocks/blocks/{service}.ts`), add `hideWhenHosted: true` t
 },
 ```
 
-The visibility is controlled by `isSubBlockHidden()` in `lib/workflows/subblocks/visibility.ts`, which checks both the `isHosted` feature flag (`hideWhenHosted`) and optional env var conditions (`hideWhenEnvSet`).
+The visibility is controlled by `isSubBlockHidden()` in `lib/workflows/subblocks/visibility.ts`, which checks both `getDeploymentShape().hosted` (`hideWhenHosted`) and optional env var conditions (`hideWhenEnvSet`).
 
 ### Excluding Specific Operations from Hosted Key Support
 
@@ -251,6 +251,9 @@ Add an entry to the `PROVIDERS` array in the BYOK settings component so users ca
 },
 ```
 
+Then add the id to exactly one section's `ids` in `PROVIDER_SECTIONS` (same file), and run
+`bun run check:byok-providers`.
+
 ## Step 6: Summarize Pricing and Throttling Comparison
 
 After all code changes are complete, output a detailed summary to the user covering:
@@ -296,5 +299,6 @@ This summary helps reviewers verify that the pricing and rate limiting are well-
 - [ ] Cost data captured in `transformResponse` or `postProcess` if API provides it
 - [ ] `hideWhenHosted: true` added to the API key subblock in the block config
 - [ ] Provider entry added to the BYOK settings UI with icon and description
+- [ ] Provider id listed in exactly one `PROVIDER_SECTIONS` section's `ids`; `bun run check:byok-providers` passes
 - [ ] Env vars documented: `{PREFIX}_COUNT` and `{PREFIX}_1..N`
 - [ ] Pricing and throttling summary provided to reviewer

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

@@ -131,10 +131,8 @@ Three rules that are easy to get wrong when copying from existing blocks:
   add a client provider fetcher, a provider-specific query key, browser token acquisition, or a
   selector-only API route. The shared context builder sends only active `dependsOn` values and
   preserves exact `{{KEY}}` environment references for server-side resolution.
-- A `canonicalParamId` is a third name that neither member of a basic/advanced pair uses as its `id`
-  (e.g. `channelSelector` + `channelId` → `canonicalParamId: 'channel'`). It is the only key that
-  survives serialization, so `inputs` and `tools.config.params` reference the canonical id, never the
-  subblock ids. It is unique block-wide, and every member of a group shares the same `required` value.
+- Basic/advanced pairs use a `canonicalParamId`; its constraints are in
+  `.claude/rules/sim-integrations.md` and the `add-block` skill → canonicalParamId Pattern.
 - Every text-entry subBlock (`short-input`, `long-input`, `code`) and every selector declares a
   `placeholder`; an empty box tells the user nothing. Secrets read `Enter your {thing}` (e.g.
   `Enter your API key`), free text names what to type (`Enter branch name`), and formatted values
@@ -215,7 +213,7 @@ import {
 } from '@/tools/{service}'
 
 // Add to tools object (alphabetically)
-export const tools: Record<string, ToolConfig> = {
+export const tools: Record<string, ExecutableToolConfig> = {
   // ... existing tools ...
   {service}_action1: {service}Action1Tool,
   {service}_action2: {service}Action2Tool,
@@ -304,16 +302,11 @@ a resolvable capability must fail validation.
 
 ## Step 8: Generate and Validate the Catalog
 
-Run the documentation generator:
-```bash
-bun run scripts/generate-docs.ts
-bun run deployment-config:generate
-bun run integration-catalog:check
-bun run deployment-config:check
-bun run docs:check
-```
+Run `bun run tool-metadata:generate`, `bun run scripts/generate-docs.ts`,
+`bun run deployment-config:generate`, then `bun run check:audits` (see the `validate-integration`
+skill → Regenerate Derived Artifacts for the full list and what each check verifies).
 
-This creates `apps/docs/content/docs/integrations/{service}.mdx` — one page per service carrying the block's Actions and, if it has one, its Triggers section. Never hand-edit generated pages; the only editable region is the `{/* MANUAL-CONTENT */}` block (see `scripts/README.md`).
+The docs generator creates `apps/docs/content/docs/integrations/{service}.mdx` — one page per service carrying the block's Actions and, if it has one, its Triggers section. Never hand-edit generated pages; the only editable region is the `{/* MANUAL-CONTENT */}` block (see `scripts/README.md`).
 
 Every generated integration page carries a hand-written intro directly under `<BlockInfoCard />`. The
 generator preserves it across regenerations, so write it once after the first generate:
@@ -392,7 +385,7 @@ If creating V2 versions (API-aligned outputs):
 ### Block
 - [ ] Created `blocks/blocks/{service}.ts`
 - [ ] Set `integrationType` to the correct `IntegrationType` enum value
-- [ ] Set `tags` array with all applicable `IntegrationTag` values
+- [ ] `{Service}BlockMeta.tags` lists every applicable `IntegrationTag` (tags live on the meta, not the block)
 - [ ] Defined operation dropdown with all operations
 - [ ] Added credential field with `requiredScopes: getScopesForService('{service}')`
 - [ ] Added conditional fields per operation
@@ -415,7 +408,7 @@ If creating V2 versions (API-aligned outputs):
 ### OAuth Scopes (if OAuth service)
 - [ ] Defined scopes in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS`
 - [ ] Added scope descriptions in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
-- [ ] Used `getCanonicalScopesForProvider()` in `auth.ts` (never hardcode)
+- [ ] Used `getCanonicalScopesForProvider()` in `lib/auth/connectors/providers.ts` (never hardcode)
 - [ ] Used `getScopesForService()` in block `requiredScopes` (never hardcode)
 
 ### Deployment Availability (if OAuth service)
@@ -548,51 +541,20 @@ Implement `apps/sim/lib/internal/{service}/execute-tool.ts` and keep the file/pr
 operations beside it. The handler validates `request.input`, derives storage authority only from
 trusted `request.context`, authorizes every stored file before reading bytes, forwards
 `request.signal`, enforces declared and actual byte caps, and returns the canonical tool response.
-Register `{service}_upload` in `apps/sim/lib/internal/tool-operations/registry.server.ts` and add a
-registry/direct-handler test. There is no HTTP fallback.
+Register `{service}_upload` in `apps/sim/lib/internal/tool-operations/registry.server.ts`; the
+existing `registry.server.test.ts` completeness test covers registration. For anything more, run the
+`test-audit` gate. There is no HTTP fallback.
 
 ### File Output Pattern (Downloads)
 
-For tools that return files, use `FileToolProcessor` to store files and return `UserFile` objects.
-
-#### In Tool transformResponse
-
-```typescript
-import { FileToolProcessor } from '@/executor/utils/file-tool-processor'
-
-transformResponse: async (response, context) => {
-  const data = await response.json()
-
-  // Process file outputs to UserFile objects
-  const fileProcessor = new FileToolProcessor(context)
-  const file = await fileProcessor.processFileData({
-    data: data.content,      // base64 or buffer
-    mimeType: data.mimeType,
-    filename: data.filename,
-  })
-
-  return {
-    success: true,
-    output: { file },
-  }
-}
-```
-
-#### In the operation handler (for complex file handling)
+Declare a `file` / `file[]` output on the tool. For a raw binary endpoint, set
+`request.responseType: 'binary'` and return `output.file = { name, mimeType, data: buffer, size }`
+from `transformResponse(response, params?, context?)`. The executor's `FileToolProcessor` stores it
+and replaces it with a `UserFile`; tools never call it.
 
-```typescript
-// Return file data that FileToolProcessor can handle. No API route is involved.
-return Response.json({
-  success: true,
-  output: {
-    file: {
-      data: base64Content,
-      mimeType: 'application/pdf',
-      filename: 'document.pdf',
-    },
-  },
-})
-```
+In an operation handler, return `createInternalToolFileResult` / `createInternalToolFilesResult`
+from `lib/internal/tool-operations/file-result.ts` — never base64 JSON. See the `add-tools` skill →
+File Downloads and Generated Files.
 
 ### Key Helpers Reference
 
@@ -601,7 +563,7 @@ return Response.json({
 | `normalizeFileInput` | `@/blocks/utils` | Normalize file params in block config |
 | `processFilesToUserFiles` | `@/lib/uploads/utils/file-utils` | Convert raw inputs to UserFile[] |
 | `downloadFileFromStorage` | `@/lib/uploads/utils/file-utils.server` | Get file Buffer from UserFile |
-| `FileToolProcessor` | `@/executor/utils/file-tool-processor` | Process tool output files |
+| `FileToolProcessor` | `@/executor/utils/file-tool-processor` | Executor-side; stores declared file outputs (not called by tools) |
 | `isUserFile` | `@/lib/core/utils/user-file` | Type guard for UserFile objects |
 | `FileInputSchema` | `@/lib/uploads/utils/file-schemas` | Zod schema for file validation |
 
@@ -636,13 +598,13 @@ Scopes are maintained in a single source of truth and reused everywhere:
 
 1. **Define scopes** in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS[provider].services[service].scopes`
 2. **Add descriptions** in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts` for the OAuth modal UI
-3. **Reference in auth.ts** using `getCanonicalScopesForProvider(providerId)` from `@/lib/oauth/utils`
+3. **Reference in `lib/auth/connectors/providers.ts`** (`buildConnectorProviders`) using `getCanonicalScopesForProvider(providerId)` from `@/lib/oauth/utils`
 4. **Reference in blocks** using `getScopesForService(serviceId)` from `@/lib/oauth/utils`
 
-**Never hardcode scope arrays** in `auth.ts` or block `requiredScopes`. Always import from the centralized source.
+**Never hardcode scope arrays** in the Better Auth connector providers or block `requiredScopes`. Always import from the centralized source.
 
 ```typescript
-// In auth.ts (Better Auth config)
+// In lib/auth/connectors/providers.ts (Better Auth connector providers)
 scopes: getCanonicalScopesForProvider('{service}'),
 
 // In block credential sub-block