chore: merge upstream main to bring branch up to date

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: avianion

.claude/commands/add-block.md

@@ -20,6 +20,7 @@ When the user asks you to create a block:
 import { {ServiceName}Icon } from '@/components/icons'
 import type { BlockConfig } from '@/blocks/types'
 import { AuthMode } from '@/blocks/types'
+import { getScopesForService } from '@/lib/oauth/utils'
 
 export const {ServiceName}Block: BlockConfig = {
   type: '{service}',                    // snake_case identifier
@@ -115,12 +116,17 @@ export const {ServiceName}Block: BlockConfig = {
   id: 'credential',
   title: 'Account',
   type: 'oauth-input',
-  serviceId: '{service}',  // Must match OAuth provider
+  serviceId: '{service}',  // Must match OAuth provider service key
+  requiredScopes: getScopesForService('{service}'),  // Import from @/lib/oauth/utils
   placeholder: 'Select account',
   required: true,
 }
 ```
 
+**Scopes:** Always use `getScopesForService(serviceId)` from `@/lib/oauth/utils` for `requiredScopes`. Never hardcode scope arrays — the single source of truth is `OAUTH_PROVIDERS` in `lib/oauth/oauth.ts`.
+
+**Scope descriptions:** When adding a new OAuth provider, also add human-readable descriptions for all scopes in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`.
+
 ### Selectors (with dynamic options)
 ```typescript
 // Channel selector (Slack, Discord, etc.)
@@ -532,6 +538,41 @@ outputs: {
 }
 ```
 
+### Typed JSON Outputs
+
+When using `type: 'json'` and you know the object shape in advance, **describe the inner fields in the description** so downstream blocks know what properties are available. For well-known, stable objects, use nested output definitions instead:
+
+```typescript
+outputs: {
+  // BAD: Opaque json with no info about what's inside
+  plan: { type: 'json', description: 'Zone plan information' },
+
+  // GOOD: Describe the known fields in the description
+  plan: {
+    type: 'json',
+    description: 'Zone plan information (id, name, price, currency, frequency, is_subscribed)',
+  },
+
+  // BEST: Use nested output definition when the shape is stable and well-known
+  plan: {
+    id: { type: 'string', description: 'Plan identifier' },
+    name: { type: 'string', description: 'Plan name' },
+    price: { type: 'number', description: 'Plan price' },
+    currency: { type: 'string', description: 'Price currency' },
+  },
+}
+```
+
+Use the nested pattern when:
+- The object has a small, stable set of fields (< 10)
+- Downstream blocks will commonly access specific properties
+- The API response shape is well-documented and unlikely to change
+
+Use `type: 'json'` with a descriptive string when:
+- The object has many fields or a dynamic shape
+- It represents a list/array of items
+- The shape varies by operation
+
 ## V2 Block Pattern
 
 When creating V2 blocks (alongside legacy V1):
@@ -589,6 +630,7 @@ export const registry: Record<string, BlockConfig> = {
 import { ServiceIcon } from '@/components/icons'
 import type { BlockConfig } from '@/blocks/types'
 import { AuthMode } from '@/blocks/types'
+import { getScopesForService } from '@/lib/oauth/utils'
 
 export const ServiceBlock: BlockConfig = {
   type: 'service',
@@ -619,6 +661,7 @@ export const ServiceBlock: BlockConfig = {
       title: 'Service Account',
       type: 'oauth-input',
       serviceId: 'service',
+      requiredScopes: getScopesForService('service'),
       placeholder: 'Select account',
       required: true,
     },
@@ -695,16 +738,88 @@ Please provide the SVG and I'll convert it to a React component.
 You can usually find this in the service's brand/press kit page, or copy it from their website.
 ```
 
+## Advanced Mode for Optional Fields
+
+Optional fields that are rarely used should be set to `mode: 'advanced'` so they don't clutter the basic UI. This includes:
+- Pagination tokens
+- Time range filters (start/end time)
+- Sort order options
+- Reply settings
+- Rarely used IDs (e.g., reply-to tweet ID, quote tweet ID)
+- Max results / limits
+
+```typescript
+{
+  id: 'startTime',
+  title: 'Start Time',
+  type: 'short-input',
+  placeholder: 'ISO 8601 timestamp',
+  condition: { field: 'operation', value: ['search', 'list'] },
+  mode: 'advanced',  // Rarely used, hide from basic view
+}
+```
+
+## WandConfig for Complex Inputs
+
+Use `wandConfig` for fields that are hard to fill out manually, such as timestamps, comma-separated lists, and complex query strings. This gives users an AI-assisted input experience.
+
+```typescript
+// Timestamps - use generationType: 'timestamp' to inject current date context
+{
+  id: 'startTime',
+  title: 'Start Time',
+  type: 'short-input',
+  mode: 'advanced',
+  wandConfig: {
+    enabled: true,
+    prompt: 'Generate an ISO 8601 timestamp based on the user description. Return ONLY the timestamp string.',
+    generationType: 'timestamp',
+  },
+}
+
+// Comma-separated lists - simple prompt without generationType
+{
+  id: 'mediaIds',
+  title: 'Media IDs',
+  type: 'short-input',
+  mode: 'advanced',
+  wandConfig: {
+    enabled: true,
+    prompt: 'Generate a comma-separated list of media IDs. Return ONLY the comma-separated values.',
+  },
+}
+```
+
+## Naming Convention
+
+All tool IDs referenced in `tools.access` and returned by `tools.config.tool` MUST use `snake_case` (e.g., `x_create_tweet`, `slack_send_message`). Never use camelCase or PascalCase.
+
 ## Checklist Before Finishing
 
 - [ ] 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
 - [ ] Required fields marked correctly (boolean or condition)
-- [ ] OAuth inputs have correct `serviceId`
-- [ ] Tools.access lists all tool IDs
-- [ ] Tools.config.tool returns correct tool ID
+- [ ] OAuth inputs have correct `serviceId` and `requiredScopes: getScopesForService(serviceId)`
+- [ ] Scope descriptions added to `SCOPE_DESCRIPTIONS` in `lib/oauth/utils.ts` for any new scopes
+- [ ] Tools.access lists all tool IDs (snake_case)
+- [ ] Tools.config.tool returns correct tool ID (snake_case)
 - [ ] Outputs match tool outputs
 - [ ] Block registered in registry.ts
 - [ ] If icon missing: asked user to provide SVG
 - [ ] If triggers exist: `triggers` config set, trigger subBlocks spread
+- [ ] Optional/rarely-used fields set to `mode: 'advanced'`
+- [ ] Timestamps and complex inputs have `wandConfig` enabled
+
+## Final Validation (Required)
+
+After creating the block, you MUST validate it against every tool it references:
+
+1. **Read every tool definition** that appears in `tools.access` — do not skip any
+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)
+   - 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

.claude/commands/add-integration.md

@@ -102,6 +102,7 @@ export const {service}{Action}Tool: ToolConfig<Params, Response> = {
 - Always use `?? []` for optional array fields
 - 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
 
 ## Step 3: Create Block
 
@@ -113,6 +114,7 @@ export const {service}{Action}Tool: ToolConfig<Params, Response> = {
 import { {Service}Icon } from '@/components/icons'
 import type { BlockConfig } from '@/blocks/types'
 import { AuthMode } from '@/blocks/types'
+import { getScopesForService } from '@/lib/oauth/utils'
 
 export const {Service}Block: BlockConfig = {
   type: '{service}',
@@ -143,6 +145,7 @@ export const {Service}Block: BlockConfig = {
       title: '{Service} Account',
       type: 'oauth-input',
       serviceId: '{service}',
+      requiredScopes: getScopesForService('{service}'),
       required: true,
     },
     // Conditional fields per operation
@@ -408,7 +411,7 @@ If creating V2 versions (API-aligned outputs):
 ### Block
 - [ ] Created `blocks/blocks/{service}.ts`
 - [ ] Defined operation dropdown with all operations
-- [ ] Added credential field (oauth-input or short-input)
+- [ ] Added credential field with `requiredScopes: getScopesForService('{service}')`
 - [ ] Added conditional fields per operation
 - [ ] Set up dependsOn for cascading selectors
 - [ ] Configured tools.access with all tool IDs
@@ -418,6 +421,12 @@ If creating V2 versions (API-aligned outputs):
 - [ ] If triggers: set `triggers.enabled` and `triggers.available`
 - [ ] If triggers: spread trigger subBlocks with `getTrigger()`
 
+### 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 `getScopesForService()` in block `requiredScopes` (never hardcode)
+
 ### Icon
 - [ ] Asked user to provide SVG
 - [ ] Added icon to `components/icons.tsx`
@@ -436,6 +445,12 @@ If creating V2 versions (API-aligned outputs):
 - [ ] Ran `bun run scripts/generate-docs.ts`
 - [ ] Verified docs file created
 
+### Final Validation (Required)
+- [ ] Read every tool file and cross-referenced inputs/outputs against the API docs
+- [ ] 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
+
 ## Example Command
 
 When the user asks to add an integration:
@@ -685,13 +700,61 @@ return NextResponse.json({
 | `isUserFile` | `@/lib/core/utils/user-file` | Type guard for UserFile objects |
 | `FileInputSchema` | `@/lib/uploads/utils/file-schemas` | Zod schema for file validation |
 
+### Advanced Mode for Optional Fields
+
+Optional fields that are rarely used should be set to `mode: 'advanced'` so they don't clutter the basic UI. Examples: pagination tokens, time range filters, sort order, max results, reply settings.
+
+### WandConfig for Complex Inputs
+
+Use `wandConfig` for fields that are hard to fill out manually:
+- **Timestamps**: Use `generationType: 'timestamp'` to inject current date context into the AI prompt
+- **JSON arrays**: Use `generationType: 'json-object'` for structured data
+- **Complex queries**: Use a descriptive prompt explaining the expected format
+
+```typescript
+{
+  id: 'startTime',
+  title: 'Start Time',
+  type: 'short-input',
+  mode: 'advanced',
+  wandConfig: {
+    enabled: true,
+    prompt: 'Generate an ISO 8601 timestamp. Return ONLY the timestamp string.',
+    generationType: 'timestamp',
+  },
+}
+```
+
+### OAuth Scopes (Centralized System)
+
+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`
+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.
+
+```typescript
+// In auth.ts (Better Auth config)
+scopes: getCanonicalScopesForProvider('{service}'),
+
+// In block credential sub-block
+requiredScopes: getScopesForService('{service}'),
+```
+
 ### Common Gotchas
 
 1. **OAuth serviceId must match** - The `serviceId` in oauth-input must match the OAuth provider configuration
-2. **Tool IDs are snake_case** - `stripe_create_payment`, not `stripeCreatePayment`
+2. **All tool IDs MUST be snake_case** - `stripe_create_payment`, not `stripeCreatePayment`. This applies to tool `id` fields, registry keys, `tools.access` arrays, and `tools.config.tool` return values
 3. **Block type is snake_case** - `type: 'stripe'`, not `type: 'Stripe'`
 4. **Alphabetical ordering** - Keep imports and registry entries alphabetically sorted
 5. **Required can be conditional** - Use `required: { field: 'op', value: 'create' }` instead of always true
 6. **DependsOn clears options** - When a dependency changes, selector options are refetched
 7. **Never pass Buffer directly to fetch** - Convert to `new Uint8Array(buffer)` for TypeScript compatibility
 8. **Always handle legacy file params** - Keep hidden `fileContent` params for backwards compatibility
+9. **Optional fields use advanced mode** - Set `mode: 'advanced'` on rarely-used optional fields
+10. **Complex inputs need wandConfig** - Timestamps, JSON arrays, and other hard-to-type values should have `wandConfig` enabled
+11. **Never hardcode scopes** - Use `getScopesForService()` in blocks and `getCanonicalScopesForProvider()` in auth.ts
+12. **Always add scope descriptions** - New scopes must have entries in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`

.claude/commands/add-tools.md

@@ -147,9 +147,18 @@ closedAt: {
 },
 ```
 
-### Nested Properties
-For complex outputs, define nested structure:
+### Typed JSON Outputs
+
+When using `type: 'json'` and you know the object shape in advance, **always define the inner structure** using `properties` so downstream consumers know what fields are available:
+
 ```typescript
+// BAD: Opaque json with no info about what's inside
+metadata: {
+  type: 'json',
+  description: 'Response metadata',
+},
+
+// GOOD: Define the known properties
 metadata: {
   type: 'json',
   description: 'Response metadata',
@@ -159,7 +168,10 @@ metadata: {
     count: { type: 'number', description: 'Total count' },
   },
 },
+```
 
+For arrays of objects, define the item structure:
+```typescript
 items: {
   type: 'array',
   description: 'List of items',
@@ -173,6 +185,8 @@ items: {
 },
 ```
 
+Only use bare `type: 'json'` without `properties` when the shape is truly dynamic or unknown.
+
 ## Critical Rules for transformResponse
 
 ### Handle Nullable Fields
@@ -272,13 +286,36 @@ If creating V2 tools (API-aligned outputs), use `_v2` suffix:
 - Version: `'2.0.0'`
 - Outputs: Flat, API-aligned (no content/metadata wrapper)
 
+## Naming Convention
+
+All tool IDs MUST use `snake_case`: `{service}_{action}` (e.g., `x_create_tweet`, `slack_send_message`). Never use camelCase or PascalCase for tool IDs.
+
 ## Checklist Before Finishing
 
+- [ ] All tool IDs use snake_case
 - [ ] All params have explicit `required: true` or `required: false`
 - [ ] All params have appropriate `visibility`
 - [ ] All nullable response fields use `?? null`
 - [ ] All optional outputs have `optional: true`
 - [ ] No raw JSON dumps in outputs
 - [ ] Types file has all interfaces
 - [ ] Index.ts exports all tools
-- [ ] Tool IDs use snake_case
+
+## Final Validation (Required)
+
+After creating all tools, you MUST validate every tool before finishing:
+
+1. **Read every tool file** you created — do not skip any
+2. **Cross-reference with the API docs** to verify:
+   - All required params are marked `required: true`
+   - All optional params are marked `required: false`
+   - Param types match the API (string, number, boolean, json)
+   - Request URL, method, headers, and body match the API spec
+   - `transformResponse` extracts the correct fields from the API response
+   - 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
+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)