Merge branch 'doc/update-mcp' into waleedlatif1/docs-gap-audit

Author: TheodoreSpeaks

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

@@ -14,6 +14,20 @@ When the user asks you to create a block:
 2. Configure all subBlocks with proper types, conditions, and dependencies
 3. Wire up tools correctly
 
+## Hard Rule: No Guessed Tool Outputs
+
+Blocks depend on tool outputs. If the underlying tool response schema is not documented or live-verified, you MUST tell the user instead of guessing block outputs.
+
+- Do NOT invent block outputs for undocumented tool responses
+- Do NOT describe unknown JSON shapes as if they were confirmed
+- Do NOT wire fields into the block just because they seem likely to exist
+
+If the tool outputs are not known, do one of these instead:
+1. Ask the user for sample tool responses
+2. Ask the user for test credentials so the tool responses can be verified
+3. Limit the block to operations whose outputs are documented
+4. Leave uncertain outputs out and explicitly tell the user what remains unknown
+
 ## Block Configuration Structure
 
 ```typescript
@@ -575,6 +589,8 @@ Use `type: 'json'` with a descriptive string when:
 - It represents a list/array of items
 - The shape varies by operation
 
+If the output shape is unknown because the underlying tool response is undocumented, you MUST tell the user and stop. Unknown is not the same as variable. Never guess block outputs.
+
 ## V2 Block Pattern
 
 When creating V2 blocks (alongside legacy V1):
@@ -829,3 +845,4 @@ After creating the block, you MUST validate it against every tool it references:
    - 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
+5. **If any tool outputs are still unknown**, explicitly tell the user instead of guessing block outputs

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

@@ -15,6 +15,21 @@ When the user asks you to create a connector:
 3. Create the connector directory and config
 4. Register it in the connector registry
 
+## Hard Rule: No Guessed Response Or Document Schemas
+
+If the service docs do not clearly show the document list response, document fetch response, pagination shape, or metadata fields, you MUST tell the user instead of guessing.
+
+- Do NOT invent document fields
+- Do NOT guess pagination cursors or next-page fields
+- Do NOT infer metadata/tag mappings from unrelated endpoints
+- Do NOT fabricate `ExternalDocument` content structure from partial docs
+
+If the source schema is unknown, do one of these instead:
+1. Ask the user for sample API responses
+2. Ask the user for test credentials so you can verify live payloads
+3. Implement only the documented parts of the connector
+4. Leave the connector incomplete and explicitly say which fields remain unknown
+
 ## Directory Structure
 
 Create files in `apps/sim/connectors/{service}/`:
@@ -92,6 +107,8 @@ export const {service}Connector: ConnectorConfig = {
 }
 ```
 
+Only map fields in `listDocuments`, `getDocument`, `validateConfig`, and `mapTags` when the source payload shape is documented or live-verified. If not, tell the user and stop rather than guessing.
+
 ### API key connector example
 
 ```typescript

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

@@ -29,6 +29,21 @@ Before writing any code:
    - Required vs optional parameters
    - Response structures
 
+### Hard Rule: No Guessed Response Schemas
+
+If the official docs do not clearly show the response JSON shape for an endpoint, you MUST stop and tell the user exactly which outputs are unknown.
+
+- Do NOT guess response field names
+- Do NOT infer nested JSON paths from related endpoints
+- Do NOT invent output properties just because they seem likely
+- Do NOT implement `transformResponse` against unverified payload shapes
+
+If response schemas are missing or incomplete, do one of the following before proceeding:
+1. Ask the user for sample responses
+2. Ask the user for test credentials so you can verify the live payload
+3. Reduce the scope to only endpoints whose response shapes are documented
+4. Leave the tool unimplemented and explicitly report why
+
 ## Step 2: Create Tools
 
 ### Directory Structure
@@ -103,6 +118,7 @@ export const {service}{Action}Tool: ToolConfig<Params, Response> = {
 - Set `optional: true` for outputs that may not exist
 - Never output raw JSON dumps - extract meaningful fields
 - When using `type: 'json'` and you know the object shape, define `properties` with the inner fields so downstream consumers know the structure. Only use bare `type: 'json'` when the shape is truly dynamic
+- If you do not know the response JSON shape from docs or verified examples, you MUST tell the user and stop. Never guess outputs or response mappings.
 
 ## Step 3: Create Block
 
@@ -450,6 +466,8 @@ If creating V2 versions (API-aligned outputs):
 - [ ] Verified block subBlocks cover all required tool params with correct conditions
 - [ ] Verified block outputs match what the tools actually return
 - [ ] Verified `tools.config.params` correctly maps and coerces all param types
+- [ ] Verified every tool output and `transformResponse` path against documented or live-verified JSON responses
+- [ ] If any response schema remained unknown, explicitly told the user instead of guessing
 
 ## Example Command
 

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

@@ -14,6 +14,21 @@ When the user asks you to create tools for a service:
 2. Create the tools directory structure
 3. Generate properly typed tool configurations
 
+## Hard Rule: No Guessed Response Schemas
+
+If the docs do not clearly show the response JSON for a tool, you MUST tell the user exactly which outputs are unknown and stop short of guessing.
+
+- Do NOT invent response field names
+- Do NOT infer nested paths from nearby endpoints
+- Do NOT guess array item shapes
+- Do NOT write `transformResponse` against unverified payloads
+
+If the response shape is unknown, do one of these instead:
+1. Ask the user for sample responses
+2. Ask the user for test credentials so you can verify live responses
+3. Implement only the endpoints whose outputs are documented
+4. Leave the tool unimplemented and explicitly say why
+
 ## Directory Structure
 
 Create files in `apps/sim/tools/{service}/`:
@@ -187,6 +202,8 @@ items: {
 
 Only use bare `type: 'json'` without `properties` when the shape is truly dynamic or unknown.
 
+If the response shape is unknown because the docs do not provide it, you MUST tell the user and stop. Unknown is not the same as dynamic. Never guess outputs.
+
 ## Critical Rules for transformResponse
 
 ### Handle Nullable Fields
@@ -441,7 +458,9 @@ After creating all tools, you MUST validate every tool before finishing:
    - All output fields match what the API actually returns
    - No fields are missing from outputs that the API provides
    - No extra fields are defined in outputs that the API doesn't return
+   - Every output field and JSON path is backed by docs or live-verified sample responses
 3. **Verify consistency** across tools:
    - Shared types in `types.ts` match all tools that use them
    - Tool IDs in the barrel export match the tool file definitions
    - Error handling is consistent (error checks, meaningful messages)
+4. **If any response schema is still unknown**, explicitly tell the user instead of guessing

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

@@ -14,6 +14,21 @@ You are an expert at creating webhook triggers for Sim. You understand the trigg
 3. Create a provider handler if custom auth, formatting, or subscriptions are needed
 4. Register triggers and connect them to the block
 
+## Hard Rule: No Guessed Webhook Payload Schemas
+
+If the service docs do not clearly show the webhook payload JSON for an event, you MUST tell the user instead of guessing trigger outputs or `formatInput` mappings.
+
+- Do NOT invent payload field names
+- Do NOT guess nested event object paths
+- Do NOT infer output fields from the UI or marketing docs
+- Do NOT write `formatInput` against unverified webhook bodies
+
+If the payload shape is unknown, do one of these instead:
+1. Ask the user for sample webhook payloads
+2. Ask the user for a test webhook source so you can inspect a real event
+3. Implement only the event registration/setup portions whose payloads are documented
+4. Leave the trigger unimplemented and explicitly say which payload fields are unknown
+
 ## Directory Structure
 
 ```

.agents/skills/cleanup/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: cleanup
+description: Run all code quality skills in sequence — effects, memo, callbacks, state, React Query, and emcn design review
+---
+
+# Cleanup
+
+Arguments:
+- scope: what to review (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- fix: whether to apply fixes (default: true). Set to false to only propose changes.
+
+User arguments: $ARGUMENTS
+
+## Steps
+
+Run each of these skills in order on the specified scope, passing through the scope and fix arguments. After each skill completes, move to the next. Do not skip any.
+
+1. `/you-might-not-need-an-effect $ARGUMENTS`
+2. `/you-might-not-need-a-memo $ARGUMENTS`
+3. `/you-might-not-need-a-callback $ARGUMENTS`
+4. `/you-might-not-need-state $ARGUMENTS`
+5. `/react-query-best-practices $ARGUMENTS`
+6. `/emcn-design-review $ARGUMENTS`
+
+After all skills have run, output a summary of what was found and fixed (or proposed) across all six passes.