merge origin/staging into feat/remove-fractional-index-ff

Author: TheodoreSpeaks

.agents/skills/design-taste-frontend/SKILL.md

@@ -49,10 +49,35 @@ Read these when doing a deeper pass:
   - cap downloads and parsed output separately
   - preserve partial results when a later item exceeds the cap
   - never read untrusted response bodies without a byte cap
+- KB connector file downloads in `apps/sim/connectors/utils.ts`
+  - `CONNECTOR_MAX_FILE_BYTES`: shared per-file cap (aligned with the manual KB upload limit)
+  - `readBodyWithLimit`: stream a download body to a Buffer with a hard byte cap (null on overflow)
+  - `stubOrSkipBySize`: listing-time skip when the reported size exceeds the cap
+  - `markSkipped` / `sizeLimitSkipReason`: surface oversized files as failed (skipped) KB rows
+  - `ConnectorFileTooLargeError`: thrown mid-download when the listing under-reported size
 - Large workflow value payloads
   - prefer durable references/manifests over inlining large arrays or files
   - materialize refs only behind an explicit byte budget
 
+## KB Connector File Size Handling
+
+The connector size pattern in `apps/sim/connectors/utils.ts` (`CONNECTOR_MAX_FILE_BYTES` + `readBodyWithLimit` + `stubOrSkipBySize`/`markSkipped`) exists for one risk: a knowledge-base connector downloading **arbitrary, user-controlled file bytes** that the source does not hard-cap. Apply it by that risk, not by the connector's name.
+
+Use the pattern when the connector downloads file content via a stream/`download_url` where the user controls the size:
+- file-storage connectors: Dropbox, OneDrive, SharePoint, Google Drive, S3, GitHub, GitLab, Azure DevOps
+- any connector that fetches a file via a download URL even if it is not a "storage" service (e.g. the Zoom transcript `.vtt`)
+
+For those, require all three:
+- stream the body with `readBodyWithLimit(resp, CONNECTOR_MAX_FILE_BYTES)` — never raw `response.text()`/`response.arrayBuffer()`
+- skip oversize at listing (`stubOrSkipBySize` with the reported size) and again at fetch time (overflow -> `markSkipped`), since the listing size can be missing or under-reported
+- never drop/truncate silently — oversized files become content-less failed rows carrying `skippedReason`, so they stay visible in the KB UI instead of vanishing from the index
+
+Skip the pattern when the source already bounds the payload:
+- pure API/structured-data connectors (Jira, Linear, Notion, Confluence, Sentry, Slack, Zendesk, Gmail, ...) — paginated JSON/text; apply normal pagination + concurrency bounds instead of a per-file byte cap
+- native-document connectors capped by the platform (Google Docs ~50 MB, Google Sheets via `MAX_ROWS`, Evernote ~25 MB/note) — a 100 MB cap can never fire, and wrapping a `response.json()`/Thrift parse in `readBodyWithLimit` is cargo-culting
+
+Litmus test: "Can a user make this one fetch arbitrarily large, with nothing upstream stopping it?" Yes -> use the pattern. No (platform hard-cap, or already paginated) -> a per-file byte cap adds noise, not safety. Borderline: a user-configured/self-hosted endpoint with no platform cap (e.g. Obsidian) — bound it only if the content is genuinely unbounded.
+
 ## Review Workflow
 
 1. Identify every changed data source:
@@ -96,6 +121,7 @@ Read these when doing a deeper pass:
 - fetches all pages from an external API before processing
 - reads an entire file, HTTP response, or stream without a max byte budget
 - checks size only after `Buffer.concat`, `arrayBuffer`, `text`, `JSON.parse`, or parse expansion
+- a KB connector silently drops or truncates an oversized file instead of recording it as a failed (skipped) row
 - chunks only after loading the complete dataset
 - paginates with unbounded/deep `OFFSET` on a mutable or large table
 - creates one queue job per row without batching or a queue-level concurrency key

.agents/skills/emil-design-eng/SKILL.md

@@ -31,7 +31,7 @@ Read these before analyzing:
 
 ### Query hooks
 - Every `queryFn` must forward `signal` for request cancellation
-- Every query must have an explicit `staleTime` (default 0 is almost never correct)
+- Every query must have an explicit `staleTime` (default 0 is almost never correct), assigned from a named exported constant — never an inline numeric literal. A server-side prefetch hydrating the same query key must import and reuse that constant instead of restating the number
 - `keepPreviousData` / `placeholderData` only on variable-key queries (where params change), never on static keys
 - Use `enabled` to prevent queries from running without required params
 

.agents/skills/memory-load-check/SKILL.md

@@ -27,7 +27,7 @@ export const {ServiceName}Block: BlockConfig = {
   name: '{Service Name}',               // Human readable
   description: 'Brief description',     // One sentence
   longDescription: 'Detailed description for docs',
-  docsLink: 'https://docs.sim.ai/tools/{service}',
+  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)
@@ -600,17 +600,20 @@ export const ServiceV2Block: BlockConfig = {
 
 ## Registering Blocks
 
-After creating the block, remind the user to:
-1. Import in `apps/sim/blocks/registry.ts`
-2. Add to the `registry` object (alphabetically):
+After creating the block, remind the user to register it in `apps/sim/blocks/registry-maps.ts` (the data maps live here; `registry.ts` holds only the accessor functions). Add the import and an entry to each map alphabetically:
 
 ```typescript
-import { ServiceBlock } from '@/blocks/blocks/service'
+import { ServiceBlock, ServiceBlockMeta } from '@/blocks/blocks/service'
 
-export const registry: Record<string, BlockConfig> = {
+export const BLOCK_REGISTRY: Record<string, BlockConfig> = {
   // ... existing blocks ...
   service: ServiceBlock,
 }
+
+export const BLOCK_META_REGISTRY: Record<string, BlockMeta> = {
+  // ... existing metas ...
+  service: ServiceBlockMeta,
+}
 ```
 
 ## Complete Example
@@ -626,7 +629,7 @@ export const ServiceBlock: BlockConfig = {
   name: 'Service',
   description: 'Integrate with Service API',
   longDescription: 'Full description for documentation...',
-  docsLink: 'https://docs.sim.ai/tools/service',
+  docsLink: 'https://docs.sim.ai/integrations/service',
   category: 'tools',
   integrationType: IntegrationType.DeveloperTools,
   tags: ['oauth', 'api'],
@@ -729,6 +732,13 @@ 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.
 ```
 
+When converting the SVG: a **monochrome** logo (single white or black mark) must
+use `fill='currentColor'`, never a hardcoded `#fff`/`#000000`. Block icons render
+both inside their `bgColor` tile and "bare" on a neutral page (the home Suggested
+actions list) in light and dark mode; a hardcoded white/black mark goes invisible
+bare on the matching background. Multi-color brand logos keep their own fills.
+Verify with `bun run check:bare-icons`.
+
 ## 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:
@@ -840,7 +850,7 @@ Derive templates from the service's real use cases. Each prompt should name a co
 - [ ] 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
+- [ ] Block + meta registered in registry-maps.ts (`BLOCK_REGISTRY` / `BLOCK_META_REGISTRY`)
 - [ ] 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'`

.agents/skills/react-query-best-practices/SKILL.md

@@ -121,7 +121,7 @@ export const {Service}Block: BlockConfig = {
   name: '{Service}',
   description: '...',
   longDescription: '...',
-  docsLink: 'https://docs.sim.ai/tools/{service}',
+  docsLink: 'https://docs.sim.ai/integrations/{service}',
   category: 'tools',
   integrationType: IntegrationType.X,   // Primary category (see IntegrationType enum)
   tags: ['oauth', 'api'],              // Cross-cutting tags (see IntegrationTag type)
@@ -279,6 +279,31 @@ Once the user provides the SVG:
 2. Create a React component that spreads props
 3. Ensure viewBox is preserved from the original SVG
 
+### Theme-safety (bare rendering) — REQUIRED
+
+The icon renders both inside its colored `bgColor` tile AND "bare" (no tile) on a
+neutral page — e.g. the home **Suggested actions** list — in both light and dark
+mode. A monochrome logo whose paths hardcode a single near-white or near-black
+fill is invisible bare on the matching background (white-on-white in light mode,
+black-on-black in dark mode).
+
+Rules when adding the SVG:
+
+- **Monochrome logos** (a single white or black mark): draw the shape with
+  `fill='currentColor'`, not `fill='#fff'` / `fill='#000000'`. It then inherits
+  white inside dark tiles, near-black inside light tiles (via
+  `getTileIconColorClass`), and the theme-aware `var(--text-icon)` bare — legible
+  everywhere. Do NOT set `iconColor` for these.
+- **Multi-color brand logos** (their own vivid fills): keep the hardcoded fills.
+  They read on any background. Only set `iconColor` (a vivid brand hex, never a
+  near-black/near-white tile color) if the bare icon should adopt a brand tint.
+- A large white shape with a tiny vivid accent (e.g. a logo where the body is the
+  white negative space) still vanishes bare — convert the body to `currentColor`.
+
+Verify with `bun run check:bare-icons` (also runs in CI). It flags purely
+monochrome hazards; for partial-accent logos, eyeball the suggested-actions list
+in both light and dark mode.
+
 ## Step 5: Create Triggers (Optional)
 
 If the service supports webhooks, create triggers using the generic `buildTriggerSubBlocks` helper.
@@ -364,17 +389,25 @@ export const tools: Record<string, ToolConfig> = {
 }
 ```
 
-### Block Registry (`apps/sim/blocks/registry.ts`)
+### Block Registry (`apps/sim/blocks/registry-maps.ts`)
+
+The data maps (`BLOCK_REGISTRY` + `BLOCK_META_REGISTRY`) live in `registry-maps.ts`; `registry.ts` holds only the accessor functions. Add the import and an entry to each map alphabetically:
 
 ```typescript
 // Add import (alphabetically)
-import { {Service}Block } from '@/blocks/blocks/{service}'
+import { {Service}Block, {Service}BlockMeta } from '@/blocks/blocks/{service}'
 
-// Add to registry (alphabetically)
-export const registry: Record<string, BlockConfig> = {
+// Add to the config map (alphabetically)
+export const BLOCK_REGISTRY: Record<string, BlockConfig> = {
   // ... existing blocks ...
   {service}: {Service}Block,
 }
+
+// Add to the catalog-meta map (alphabetically)
+export const BLOCK_META_REGISTRY: Record<string, BlockMeta> = {
+  // ... existing metas ...
+  {service}: {Service}BlockMeta,
+}
 ```
 
 ### Trigger Registry (`apps/sim/triggers/registry.ts`) - If triggers exist
@@ -443,7 +476,7 @@ If creating V2 versions (API-aligned outputs):
 - [ ] Configured tools.access with all tool IDs
 - [ ] Configured tools.config.tool selector
 - [ ] Defined outputs matching tool outputs
-- [ ] Registered block in `blocks/registry.ts`
+- [ ] Registered block + meta in `blocks/registry-maps.ts` (`BLOCK_REGISTRY` / `BLOCK_META_REGISTRY`)
 - [ ] If triggers: set `triggers.enabled` and `triggers.available`
 - [ ] If triggers: spread trigger subBlocks with `getTrigger()`
 - [ ] Exported `{Service}BlockMeta` with at least 7 templates
@@ -458,6 +491,7 @@ If creating V2 versions (API-aligned outputs):
 - [ ] Asked user to provide SVG
 - [ ] Added icon to `components/icons.tsx`
 - [ ] Icon spreads props correctly
+- [ ] Monochrome marks use `fill='currentColor'` (not hardcoded white/black) so the icon renders bare in light AND dark mode — verified with `bun run check:bare-icons`
 
 ### Triggers (if service supports webhooks)
 - [ ] Created `triggers/{service}/` directory

.claude/commands/add-block.md

@@ -374,7 +374,7 @@ export const {service}PollingHandler: PollingProviderHandler = {
 
     try {
       // For OAuth services:
-      const accessToken = await resolveOAuthCredential(webhookData, '{service}', requestId, logger)
+      const accessToken = await resolveOAuthCredential(webhookData, '{service}', requestId)
       const config = webhookData.providerConfig as unknown as {Service}WebhookConfig
 
       // First poll: seed state, emit nothing
@@ -421,7 +421,7 @@ export const {service}PollingTrigger: TriggerConfig = {
   polling: true,               // REQUIRED — routes to polling infrastructure
 
   subBlocks: [
-    { id: 'triggerCredentials', type: 'oauth-input', title: 'Credentials', serviceId: '{service}', requiredScopes: [], required: true, mode: 'trigger', supportsCredentialSets: true },
+    { id: 'triggerCredentials', type: 'oauth-input', title: 'Credentials', serviceId: '{service}', requiredScopes: [], required: true, mode: 'trigger' },
     // ... service-specific config fields (dropdowns, inputs, switches) ...
     { id: 'triggerInstructions', type: 'text', title: 'Setup Instructions', hideFromPreview: true, mode: 'trigger', defaultValue: '...' },
   ],

.claude/commands/add-integration.md

@@ -1,5 +1,5 @@
 ---
-description: Run all code quality skills in sequence — effects, memo, callbacks, state, React Query, and emcn design review
+description: Run all code quality skills in sequence — effects, memo, callbacks, state, React Query, emcn design review, and url-state
 argument-hint: [scope] [fix=true|false]
 ---
 
@@ -21,5 +21,6 @@ Run each of these skills in order on the specified scope, passing through the sc
 4. `/you-might-not-need-state $ARGUMENTS`
 5. `/react-query-best-practices $ARGUMENTS`
 6. `/emcn-design-review $ARGUMENTS`
+7. `/you-might-not-need-url-state $ARGUMENTS`
 
-After all skills have run, output a summary of what was found and fixed (or proposed) across all six passes.
+After all skills have run, output a summary of what was found and fixed (or proposed) across all seven passes.

.claude/commands/add-trigger.md

@@ -31,7 +31,7 @@ Read these before analyzing:
 
 ### Query hooks
 - Every `queryFn` must forward `signal` for request cancellation
-- Every query must have an explicit `staleTime` (default 0 is almost never correct)
+- Every query must have an explicit `staleTime` (default 0 is almost never correct), assigned from a named exported constant — never an inline numeric literal. A server-side prefetch hydrating the same query key must import and reuse that constant instead of restating the number
 - `keepPreviousData` / `placeholderData` only on variable-key queries (where params change), never on static keys
 - Use `enabled` to prevent queries from running without required params
 

.claude/commands/cleanup.md

@@ -24,7 +24,7 @@ Read **every** file for the integration — do not skip any:
 apps/sim/tools/{service}/          # All tool files, types.ts, index.ts
 apps/sim/blocks/blocks/{service}.ts # Block definition
 apps/sim/tools/registry.ts          # Tool registry entries for this service
-apps/sim/blocks/registry.ts         # Block registry entry for this service
+apps/sim/blocks/registry-maps.ts    # Block + meta registry entry (BLOCK_REGISTRY / BLOCK_META_REGISTRY)
 apps/sim/components/icons.tsx        # Icon definition
 apps/sim/lib/auth/auth.ts           # OAuth config — should use getCanonicalScopesForProvider()
 apps/sim/lib/oauth/oauth.ts         # OAuth provider config — single source of truth for scopes
@@ -185,12 +185,12 @@ For **each tool** in `tools.access`:
 - [ ] `name` is human-readable (e.g., `'X'`, `'Cloudflare'`)
 - [ ] `description` is a concise one-liner
 - [ ] `longDescription` provides detail for docs
-- [ ] `docsLink` points to `'https://docs.sim.ai/tools/{service}'`
+- [ ] `docsLink` points to `'https://docs.sim.ai/integrations/{service}'`
 - [ ] `category` is `'tools'`
 - [ ] `bgColor` uses the service's brand color hex
 - [ ] `icon` references the correct icon component from `@/components/icons`
 - [ ] `authMode` is set correctly (`AuthMode.OAuth` or `AuthMode.ApiKey`)
-- [ ] Block is registered in `blocks/registry.ts` alphabetically
+- [ ] Block + meta are registered in `blocks/registry-maps.ts` (`BLOCK_REGISTRY` / `BLOCK_META_REGISTRY`) alphabetically
 
 ### BlockMeta
 - [ ] `{Service}BlockMeta` is exported in the same file as the block