cleanup canonical tool param resolution code

Author: icecrasher321

.claude/commands/add-integration.md

@@ -206,10 +206,15 @@ export const {Service}Block: BlockConfig = {
 }
 ```
 
-**Critical:**
-- `canonicalParamId` must NOT match any other subblock's `id`, must be unique per block, and should only be used to link basic/advanced alternatives for the same parameter.
-- `mode` only controls UI visibility, NOT serialization. Without `canonicalParamId`, both basic and advanced field values would be sent.
-- Every subblock `id` must be unique within the block. Duplicate IDs cause conflicts even with different conditions.
+**Critical Canonical Param Rules:**
+- `canonicalParamId` must NOT match any subblock's `id` in the block
+- `canonicalParamId` must be unique per operation/condition context
+- Only use `canonicalParamId` to link basic/advanced alternatives for the same logical parameter
+- `mode` only controls UI visibility, NOT serialization. Without `canonicalParamId`, both basic and advanced field values would be sent
+- Every subblock `id` must be unique within the block. Duplicate IDs cause conflicts even with different conditions
+- **Required consistency:** If one subblock in a canonical group has `required: true`, ALL subblocks in that group must have `required: true` (prevents bypassing validation by switching modes)
+- **Inputs section:** Must list canonical param IDs (e.g., `fileId`), NOT raw subblock IDs (e.g., `fileSelector`, `manualFileId`)
+- **Params function:** Must use canonical param IDs, NOT raw subblock IDs (raw IDs are deleted after canonical transformation)
 
 ## Step 4: Add Icon
 

.claude/rules/sim-integrations.md

@@ -157,6 +157,36 @@ dependsOn: { all: ['authMethod'], any: ['credential', 'botToken'] }
 - `'both'` - Show in both modes (default)
 - `'trigger'` - Only when block is used as trigger
 
+### `canonicalParamId` - Link basic/advanced alternatives
+
+Use to map multiple UI inputs to a single logical parameter:
+
+```typescript
+// Basic mode: Visual selector
+{
+  id: 'fileSelector',
+  type: 'file-selector',
+  mode: 'basic',
+  canonicalParamId: 'fileId',
+  required: true,
+},
+// Advanced mode: Manual input
+{
+  id: 'manualFileId',
+  type: 'short-input',
+  mode: 'advanced',
+  canonicalParamId: 'fileId',
+  required: true,
+},
+```
+
+**Critical Rules:**
+- `canonicalParamId` must NOT match any subblock's `id`
+- `canonicalParamId` must be unique per operation/condition context
+- **Required consistency:** All subblocks in a canonical group must have the same `required` status
+- **Inputs section:** Must list canonical param IDs (e.g., `fileId`), NOT raw subblock IDs
+- **Params function:** Must use canonical param IDs (raw IDs are deleted after canonical transformation)
+
 **Register in `blocks/registry.ts`:**
 
 ```typescript

.cursor/rules/sim-integrations.mdc

@@ -155,6 +155,36 @@ dependsOn: { all: ['authMethod'], any: ['credential', 'botToken'] }
 - `'both'` - Show in both modes (default)
 - `'trigger'` - Only when block is used as trigger
 
+### `canonicalParamId` - Link basic/advanced alternatives
+
+Use to map multiple UI inputs to a single logical parameter:
+
+```typescript
+// Basic mode: Visual selector
+{
+  id: 'fileSelector',
+  type: 'file-selector',
+  mode: 'basic',
+  canonicalParamId: 'fileId',
+  required: true,
+},
+// Advanced mode: Manual input
+{
+  id: 'manualFileId',
+  type: 'short-input',
+  mode: 'advanced',
+  canonicalParamId: 'fileId',
+  required: true,
+},
+```
+
+**Critical Rules:**
+- `canonicalParamId` must NOT match any subblock's `id`
+- `canonicalParamId` must be unique per operation/condition context
+- **Required consistency:** All subblocks in a canonical group must have the same `required` status
+- **Inputs section:** Must list canonical param IDs (e.g., `fileId`), NOT raw subblock IDs
+- **Params function:** Must use canonical param IDs (raw IDs are deleted after canonical transformation)
+
 **Register in `blocks/registry.ts`:**
 
 ```typescript