From 7438455b8d75d140e2690a29a95bc4b9abf18d9b Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Thu, 1 Oct 2026 17:08:07 -0700
Subject: [PATCH 01/18] fix(audits): guard the route wrapper against
 lib/mothership, not the removed lib/copilot

The Copilot modules moved to lib/mothership in the v1.0.0 rename, so the
route-wrapper graph guard was banning a directory that no longer exists.
---
 scripts/check-application-graph.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/check-application-graph.ts b/scripts/check-application-graph.ts
index 0281bde0a2c..c049f410816 100644
--- a/scripts/check-application-graph.ts
+++ b/scripts/check-application-graph.ts
@@ -108,7 +108,7 @@ const ROUTE_WRAPPER_FORBIDDEN_PREFIXES: Record<string, string> = {
     'the permission-group resolver — the wrapper only opens the memo scope; the resolver ' +
     'belongs to the gate call sites, and it is what dragged billing in',
   'lib/auth': 'the auth graph — the wrapper wraps handlers that authenticate, it does not',
-  'lib/copilot/': 'the copilot graph',
+  'lib/mothership/': 'the Mothership (Chat agent) graph',
   'lib/knowledge/': 'the knowledge-base graph',
 }
 

From fcfecd7e0913e0ff26a3c3173c659267fafb28f7 Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Thu, 1 Oct 2026 17:08:09 -0700
Subject: [PATCH 02/18] improvement(audits): add check:guidance-refs and fix
 the stale references it found

Agent guidance (CLAUDE.md, every AGENTS.md, .claude/rules, .agents/skills)
names paths, scripts, skills, and import specifiers that agents follow
literally. The new audit resolves each one and fails on any that no longer
exists. Fixes the references it found: lib/copilot -> lib/mothership,
stores/workflows/store -> stores/workflows/workflow/store, a relative landing
path, deleted selector-provider and legacy landing mentions, and illustrative
example imports rewritten as placeholders.
---
 .agents/skills/add-block/SKILL.md             |   2 +-
 .agents/skills/add-enrichment/SKILL.md        |   2 +-
 .agents/skills/add-integration/SKILL.md       |   4 +-
 .../skills/add-permission-group-item/SKILL.md |   2 +-
 .agents/skills/add-selector/SKILL.md          |   2 +-
 .../migrate-application-operation/SKILL.md    |  10 +-
 .agents/skills/ship/SKILL.md                  |   4 +-
 .claude/rules/landing-seo-geo.md              |   2 +-
 .claude/rules/sim-imports.md                  |   4 +-
 .claude/rules/sim-queries.md                  |   2 +-
 .claude/rules/sim-stores.md                   |   2 +-
 .claude/rules/sim-testing.md                  |   2 +-
 .claude/rules/sim-url-state.md                |   6 +-
 .cursor/rules/landing-seo-geo.mdc             |   2 +-
 .cursor/rules/sim-imports.mdc                 |   4 +-
 .cursor/rules/sim-queries.mdc                 |   2 +-
 .cursor/rules/sim-stores.mdc                  |   2 +-
 .cursor/rules/sim-testing.mdc                 |   2 +-
 .cursor/rules/sim-url-state.mdc               |   6 +-
 apps/sim/app/(landing)/CLAUDE.md              |   2 +-
 package.json                                  |   1 +
 scripts/check-guidance-refs.ts                | 320 ++++++++++++++++++
 22 files changed, 353 insertions(+), 32 deletions(-)
 create mode 100644 scripts/check-guidance-refs.ts

diff --git a/.agents/skills/add-block/SKILL.md b/.agents/skills/add-block/SKILL.md
index 24a0366b91f..27628cccf18 100644
--- a/.agents/skills/add-block/SKILL.md
+++ b/.agents/skills/add-block/SKILL.md
@@ -697,7 +697,7 @@ export const ServiceV2Block: BlockConfig = {
 Register the block in `apps/sim/blocks/registry-maps.ts` — add the import and an entry to each map alphabetically:
 
 ```typescript
-import { ServiceBlock, ServiceBlockMeta } from '@/blocks/blocks/service'
+import { ServiceBlock, ServiceBlockMeta } from '@/blocks/blocks/{service}'
 
 export const BLOCK_REGISTRY: Record<string, BlockConfig> = {
   // ... existing blocks ...
diff --git a/.agents/skills/add-enrichment/SKILL.md b/.agents/skills/add-enrichment/SKILL.md
index 34810e72f41..7a3a33c4664 100644
--- a/.agents/skills/add-enrichment/SKILL.md
+++ b/.agents/skills/add-enrichment/SKILL.md
@@ -118,7 +118,7 @@ Rules:
 In `apps/sim/enrichments/registry.ts`, import and add the entry (catalog order is registration order):
 
 ```typescript
-import { myEnrichment } from '@/enrichments/my-enrichment'
+import { myEnrichment } from '@/enrichments/{id}/{id}'
 
 export const ENRICHMENT_REGISTRY: EnrichmentRegistry = {
   // ...existing
diff --git a/.agents/skills/add-integration/SKILL.md b/.agents/skills/add-integration/SKILL.md
index 865681fa09b..4d5a8e51713 100644
--- a/.agents/skills/add-integration/SKILL.md
+++ b/.agents/skills/add-integration/SKILL.md
@@ -128,8 +128,8 @@ Three rules that are easy to get wrong when copying from existing blocks:
 - Every remote `selectorKey` must use the unified server selector path. Apply the `add-selector` skill:
   add browser-safe metadata to `apps/sim/lib/selectors/manifest.ts`, reuse or extract a server-only
   provider listing primitive, and add a credential- and destination-bound server attachment. Do not
-  add code under `hooks/selectors/providers`, a provider-specific query key, browser token acquisition,
-  or a selector-only API route. The shared context builder sends only active `dependsOn` values and
+  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
diff --git a/.agents/skills/add-permission-group-item/SKILL.md b/.agents/skills/add-permission-group-item/SKILL.md
index 43ff11e4106..e0cb4447eeb 100644
--- a/.agents/skills/add-permission-group-item/SKILL.md
+++ b/.agents/skills/add-permission-group-item/SKILL.md
@@ -197,7 +197,7 @@ Add a case to `capabilities.test.ts` for any rule with logic beyond reading one
 | Guarded root | Forbidden |
 |---|---|
 | `lib/core/application/index.ts`, and `lib/permission-groups/` `capabilities.ts` / `capability-assertions.ts` / `config-scope.server.ts` | `providers/`, `blocks/`, `tools/`, `executor/`, `lib/uploads/`, `lib/workflows/` |
-| `lib/core/utils/with-route-handler.ts` | those six **plus** `lib/billing/`, `lib/permission-groups/resolve.server`, `lib/auth`, `lib/copilot/`, `lib/knowledge/` |
+| `lib/core/utils/with-route-handler.ts` | those six **plus** `lib/billing/`, `lib/permission-groups/resolve.server`, `lib/auth`, `lib/mothership/`, `lib/knowledge/` |
 
 `lib/billing/` stays allowed for the funnel roots because `resolve.server.ts` legitimately reads the subscription to decide whether an organization is on an enterprise plan; the wrapper is a lifecycle shim that opens the memo scope and nothing more. That split is why the scope is two files.
 
diff --git a/.agents/skills/add-selector/SKILL.md b/.agents/skills/add-selector/SKILL.md
index 3c4f0099f9d..439b16a61f6 100644
--- a/.agents/skills/add-selector/SKILL.md
+++ b/.agents/skills/add-selector/SKILL.md
@@ -98,7 +98,7 @@ Keep connector selector/manual canonical pairs and fork reconfiguration behavior
 
 Do not add:
 
-- A module under `hooks/selectors/providers` or any client provider fetcher.
+- A client provider fetcher.
 - A provider-specific React Query key.
 - A selector-specific OAuth-token request.
 - A selector-only API route when the provider primitive can be called directly.
diff --git a/.agents/skills/migrate-application-operation/SKILL.md b/.agents/skills/migrate-application-operation/SKILL.md
index 47ea0d2b618..25774902091 100644
--- a/.agents/skills/migrate-application-operation/SKILL.md
+++ b/.agents/skills/migrate-application-operation/SKILL.md
@@ -47,16 +47,16 @@ Read these files completely before editing:
 - `apps/sim/lib/api/server/routes/internal-json-route.ts`
 - `apps/sim/lib/api/server/routes/v2-json-route.ts`
 - `apps/sim/lib/auth/internal-delegation.ts`
-- `apps/sim/lib/copilot/application/application-adapter.ts`
-- `apps/sim/lib/copilot/auth/application-delegation.ts`
+- `apps/sim/lib/mothership/application/application-adapter.ts`
+- `apps/sim/lib/mothership/auth/application-delegation.ts`
 
 Use the file domain only as a representative golden slice:
 
 - `apps/sim/lib/workspace-files/application/operations.ts`
 - `apps/sim/lib/workspace-files/application/authorized-workspace-file-use-case.ts`
 - `apps/sim/lib/workspace-files/application/rename-workspace-file.ts`
-- `apps/sim/lib/copilot/application/execute-file-use-case.ts`
-- `apps/sim/lib/copilot/auth/file-delegation.ts`
+- `apps/sim/lib/mothership/application/execute-file-use-case.ts`
+- `apps/sim/lib/mothership/auth/file-delegation.ts`
 
 Then read the target domain's operation registry, application code, repositories, contracts, adapters, aliases, resume paths, and focused tests. Fail immediately if the shared foundation is absent. Do not recreate it inside the domain.
 
@@ -250,7 +250,7 @@ Keep v1 middleware and routes unchanged unless explicitly included.
 
 ## Adapt Copilot
 
-Copilot is a surface adapter, not a separate application layer. If an HTTP or other surface already uses an application use case, Copilot must call that exact use case rather than reimplementing protected business behavior under `lib/copilot`.
+Copilot is a surface adapter, not a separate application layer. If an HTTP or other surface already uses an application use case, Copilot must call that exact use case rather than reimplementing protected business behavior under `lib/mothership`.
 
 Create one domain-level Copilot application adapter with `createCopilotApplicationAdapter` instead of constructing delegated principals in every tool:
 
diff --git a/.agents/skills/ship/SKILL.md b/.agents/skills/ship/SKILL.md
index 300118c485e..39fdae0dd29 100644
--- a/.agents/skills/ship/SKILL.md
+++ b/.agents/skills/ship/SKILL.md
@@ -48,7 +48,7 @@ When the user runs `/ship`:
   - `bun run check:migrations origin/staging` must pass (staging is the PR base). Do not silence a flagged statement with a `-- migration-safe:` annotation unless `/db-migrate` confirmed the old code no longer depends on it; otherwise split the destructive change into a later deploy.
 6. **Run pre-ship checks** from the repo root before staging. This has two phases: first **regenerate** every committed artifact so generated files never drift into a CI failure (this is what catches things like `agent-stream-docs` going stale after a `models.ts` edit), then run the **full audit suite** CI's `Lint and Test` job enforces. Both phases parallelize — but only across commands that write **disjoint** outputs — and a bare `wait` swallows child exit codes, so both phases below explicitly collect each job's status and abort ship if any failed.
 
-  **Phase A — regenerate the always-in-repo committed artifacts (parallel), then let step 7 stage whatever changed.** Regenerate only the generators whose inputs live entirely in this repo and that any ordinary code change can drift — `agent-stream-docs:generate` (derives from the provider model registry), `docs-manifest:generate` (derives from docs page paths), and `skills:sync` (derives from `.agents/skills/**`). They write disjoint outputs (`apps/docs/…/agent.mdx`, `apps/sim/lib/copilot/generated/docs-manifest.ts`, and `.claude/skills` links), so they parallelize safely, and each is idempotent (a no-op when already in sync):
+  **Phase A — regenerate the always-in-repo committed artifacts (parallel), then let step 7 stage whatever changed.** Regenerate only the generators whose inputs live entirely in this repo and that any ordinary code change can drift — `agent-stream-docs:generate` (derives from the provider model registry), `docs-manifest:generate` (derives from docs page paths), and `skills:sync` (derives from `.agents/skills/**`). They write disjoint outputs (`apps/docs/…/agent.mdx`, `apps/sim/lib/mothership/generated/docs-manifest.ts`, and `.claude/skills` links), so they parallelize safely, and each is idempotent (a no-op when already in sync):
   ```bash
   rm -f /tmp/ship-gen-results
   for g in agent-stream-docs:generate docs-manifest:generate skills:sync; do
@@ -63,7 +63,7 @@ When the user runs `/ship`:
   ```
   Then `git status --short` to see what regenerated — those files must be staged in step 7 alongside your own changes.
 
-  **Do NOT blanket-run the domain generators here.** `mship:generate` (`generate-mship-contracts.ts`) is an **umbrella** that drives all nine mothership contract generators (`mship-contracts`, `billing-protocol-contract`, `mship-tools`, the four `trace-*`, `metrics-contract`, `vfs-snapshot-contract`) and biome-formats `apps/sim/lib/copilot/generated/` — never run it *and* its constituents (they write the same files and corrupt each other in parallel), and never run it on an ordinary ship: it reads an **external** copilot-contract source that isn't checked out in most worktrees, so it hard-fails with `ENOENT` and would abort ship for an unrelated reason. `generate:pi-model-catalog` (under `apps/sim`) likewise regenerates from the installed Pi package, not repo source. `scripts/generate-docs.ts` rewrites the integration docs and client-safe catalog; run it when this PR changes their block/icon/landing-content inputs or when `integration-catalog:check` reports drift, then review its broad generated diff. Only when **this PR's diff actually touches** a domain generator's input do you regenerate it deliberately and run its matching `:check` (`bun run mship:check` / the individual `*:check`) — with the external source present.
+  **Do NOT blanket-run the domain generators here.** `mship:generate` (`generate-mship-contracts.ts`) is an **umbrella** that drives all nine mothership contract generators (`mship-contracts`, `billing-protocol-contract`, `mship-tools`, the four `trace-*`, `metrics-contract`, `vfs-snapshot-contract`) and biome-formats `apps/sim/lib/mothership/generated/` — never run it *and* its constituents (they write the same files and corrupt each other in parallel), and never run it on an ordinary ship: it reads an **external** copilot-contract source that isn't checked out in most worktrees, so it hard-fails with `ENOENT` and would abort ship for an unrelated reason. `generate:pi-model-catalog` (under `apps/sim`) likewise regenerates from the installed Pi package, not repo source. `scripts/generate-docs.ts` rewrites the integration docs and client-safe catalog; run it when this PR changes their block/icon/landing-content inputs or when `integration-catalog:check` reports drift, then review its broad generated diff. Only when **this PR's diff actually touches** a domain generator's input do you regenerate it deliberately and run its matching `:check` (`bun run mship:check` / the individual `*:check`) — with the external source present.
 
   **Phase B — run lint + every audit CI enforces, in parallel, and abort ship if any fails.** Before running the commands, compare this list with `.github/workflows/test-build.yml`; when CI adds an audit, run it and update this skill instead of trusting a stale snapshot. The env-flag audit is currently an inline workflow block rather than a package script: when `apps/sim/lib/core/config/env-flags.ts` changed, run that current workflow block verbatim instead of copying a second version into this skill. Run `bun run lint` first (it autofixes formatting and mutates files, so don't parallelize it with the read-only audits), then run the base-sensitive block-registry check, then fan the independent audits out and collect exit codes:
   ```bash
diff --git a/.claude/rules/landing-seo-geo.md b/.claude/rules/landing-seo-geo.md
index 12752a34b56..d603c2723e7 100644
--- a/.claude/rules/landing-seo-geo.md
+++ b/.claude/rules/landing-seo-geo.md
@@ -16,7 +16,7 @@ paths:
 - All internal navigation uses Next.js `<Link>` with real `href`s — never `onClick` navigation. External links get `rel="noopener noreferrer"`.
 - All copy is server-rendered text: no text baked into images, no content that exists only after a client effect runs.
 - Navbar is a Server Component (no `'use client'`) for immediate crawlability. Logo `<Image>` has `priority` (LCP element). The navbar `<nav>` carries `SiteNavigationElement` schema.org markup.
-- Structured data: emit JSON-LD (`Organization`, `WebSite`, `WebApplication` with `featureList`, `FAQPage` if an FAQ exists) from a server component rendered before visible content. Keep `featureList` in sync with the features the page shows (`components/home-structured-data/`).
+- Structured data: emit JSON-LD (`Organization`, `WebSite`, `WebApplication` with `featureList`, `FAQPage` if an FAQ exists) from a server component rendered before visible content. Keep `featureList` in sync with the features the page shows (`apps/sim/app/(landing)/components/home-structured-data/`).
 - After adding routes or anchors, verify `app/sitemap.ts` and `app/robots.ts` still reflect reality.
 
 ## GEO (Generative Engine Optimisation)
diff --git a/.claude/rules/sim-imports.md b/.claude/rules/sim-imports.md
index 6757ecc1d43..cb62fea68ff 100644
--- a/.claude/rules/sim-imports.md
+++ b/.claude/rules/sim-imports.md
@@ -14,10 +14,10 @@ paths:
 ```typescript
 // ✓ Good
 import { Chip } from '@sim/emcn'
-import { useWorkflowStore } from '@/stores/workflows/store'
+import { useWorkflowStore } from '@/stores/workflows/workflow/store'
 
 // ✗ Bad
-import { useWorkflowStore } from '../../../stores/workflows/store'
+import { useWorkflowStore } from '../../../stores/workflows/workflow/store'
 ```
 
 ## Barrel Exports
diff --git a/.claude/rules/sim-queries.md b/.claude/rules/sim-queries.md
index bb15ebd0342..da0900635ac 100644
--- a/.claude/rules/sim-queries.md
+++ b/.claude/rules/sim-queries.md
@@ -57,7 +57,7 @@ The `'use client'` hook module then imports these back for its hooks. **Never**
 
 ```typescript
 import { requestJson } from '@/lib/api/client/request'
-import { listEntitiesContract, type EntityList } from '@/lib/api/contracts/entities'
+import { listEntitiesContract, type EntityList } from '@/lib/api/contracts/<domain>'
 
 export const ENTITY_LIST_STALE_TIME = 60 * 1000
 
diff --git a/.claude/rules/sim-stores.md b/.claude/rules/sim-stores.md
index 56b5b67c76e..7e8fbd27f86 100644
--- a/.claude/rules/sim-stores.md
+++ b/.claude/rules/sim-stores.md
@@ -14,7 +14,7 @@ Stores live in `stores/`. Complex stores split into `store.ts` + `types.ts`.
 ```typescript
 import { create } from 'zustand'
 import { devtools } from 'zustand/middleware'
-import type { FeatureState } from '@/stores/feature/types'
+import type { FeatureState } from '@/stores/<feature>/types'
 
 const initialState = { items: [] as Item[], activeId: null as string | null }
 
diff --git a/.claude/rules/sim-testing.md b/.claude/rules/sim-testing.md
index 7216d2d3ad5..13a84169a95 100644
--- a/.claude/rules/sim-testing.md
+++ b/.claude/rules/sim-testing.md
@@ -75,7 +75,7 @@ the report.
 import { authMockFns } from '@sim/testing/mocks/auth.mock'
 import { createMockRequest } from '@sim/testing/mocks/request.mock'
 import { describe, expect, it } from 'vitest'
-import { GET } from '@/app/api/my-route/route'
+import { GET } from '@/app/api/<route>/route'
 
 describe('GET /api/my-route', () => {
   it('returns 401 without a session', async () => {
diff --git a/.claude/rules/sim-url-state.md b/.claude/rules/sim-url-state.md
index 69d8c3aec92..6b0d29b9d28 100644
--- a/.claude/rules/sim-url-state.md
+++ b/.claude/rules/sim-url-state.md
@@ -80,7 +80,7 @@ Conventions:
 ### Example — grouped filters (single source of truth)
 
 ```typescript
-// apps/sim/app/workspace/[workspaceId]/things/search-params.ts
+// apps/sim/app/workspace/[workspaceId]/<feature>/search-params.ts
 import { parseAsArrayOf, parseAsString, parseAsStringLiteral } from 'nuqs/server'
 
 const VIEW_MODES = ['list', 'grid'] as const
@@ -106,7 +106,7 @@ export const thingsUrlKeys = {
 'use client'
 
 import { useQueryStates } from 'nuqs'
-import { thingsParsers, thingsUrlKeys } from '@/app/workspace/[workspaceId]/things/search-params'
+import { thingsParsers, thingsUrlKeys } from '@/app/workspace/[workspaceId]/<feature>/search-params'
 
 export function useThingFilters() {
   const [filters, setFilters] = useQueryStates(thingsParsers, thingsUrlKeys)
@@ -129,7 +129,7 @@ When a Server Component or loader must read a param, build a cache from the **sa
 ```typescript
 // in a server component / page.tsx
 import { createSearchParamsCache } from 'nuqs/server'
-import { thingsParsers } from '@/app/workspace/[workspaceId]/things/search-params'
+import { thingsParsers } from '@/app/workspace/[workspaceId]/<feature>/search-params'
 
 const thingsCache = createSearchParamsCache(thingsParsers)
 
diff --git a/.cursor/rules/landing-seo-geo.mdc b/.cursor/rules/landing-seo-geo.mdc
index 07e8ed58b94..2d683b14287 100644
--- a/.cursor/rules/landing-seo-geo.mdc
+++ b/.cursor/rules/landing-seo-geo.mdc
@@ -16,7 +16,7 @@ globs: ["apps/sim/app/(landing)/**/*.tsx","apps/sim/content/**/*.mdx"]
 - All internal navigation uses Next.js `<Link>` with real `href`s — never `onClick` navigation. External links get `rel="noopener noreferrer"`.
 - All copy is server-rendered text: no text baked into images, no content that exists only after a client effect runs.
 - Navbar is a Server Component (no `'use client'`) for immediate crawlability. Logo `<Image>` has `priority` (LCP element). The navbar `<nav>` carries `SiteNavigationElement` schema.org markup.
-- Structured data: emit JSON-LD (`Organization`, `WebSite`, `WebApplication` with `featureList`, `FAQPage` if an FAQ exists) from a server component rendered before visible content. Keep `featureList` in sync with the features the page shows (`components/home-structured-data/`).
+- Structured data: emit JSON-LD (`Organization`, `WebSite`, `WebApplication` with `featureList`, `FAQPage` if an FAQ exists) from a server component rendered before visible content. Keep `featureList` in sync with the features the page shows (`apps/sim/app/(landing)/components/home-structured-data/`).
 - After adding routes or anchors, verify `app/sitemap.ts` and `app/robots.ts` still reflect reality.
 
 ## GEO (Generative Engine Optimisation)
diff --git a/.cursor/rules/sim-imports.mdc b/.cursor/rules/sim-imports.mdc
index 95d111c7747..3b9f0656c24 100644
--- a/.cursor/rules/sim-imports.mdc
+++ b/.cursor/rules/sim-imports.mdc
@@ -14,10 +14,10 @@ globs: ["apps/sim/**/*.ts","apps/sim/**/*.tsx"]
 ```typescript
 // ✓ Good
 import { Chip } from '@sim/emcn'
-import { useWorkflowStore } from '@/stores/workflows/store'
+import { useWorkflowStore } from '@/stores/workflows/workflow/store'
 
 // ✗ Bad
-import { useWorkflowStore } from '../../../stores/workflows/store'
+import { useWorkflowStore } from '../../../stores/workflows/workflow/store'
 ```
 
 ## Barrel Exports
diff --git a/.cursor/rules/sim-queries.mdc b/.cursor/rules/sim-queries.mdc
index a50f6eb5122..50f6a43da31 100644
--- a/.cursor/rules/sim-queries.mdc
+++ b/.cursor/rules/sim-queries.mdc
@@ -58,7 +58,7 @@ The `'use client'` hook module then imports these back for its hooks. **Never**
 
 ```typescript
 import { requestJson } from '@/lib/api/client/request'
-import { listEntitiesContract, type EntityList } from '@/lib/api/contracts/entities'
+import { listEntitiesContract, type EntityList } from '@/lib/api/contracts/<domain>'
 
 export const ENTITY_LIST_STALE_TIME = 60 * 1000
 
diff --git a/.cursor/rules/sim-stores.mdc b/.cursor/rules/sim-stores.mdc
index 3a20b932aab..02e19478d49 100644
--- a/.cursor/rules/sim-stores.mdc
+++ b/.cursor/rules/sim-stores.mdc
@@ -14,7 +14,7 @@ Stores live in `stores/`. Complex stores split into `store.ts` + `types.ts`.
 ```typescript
 import { create } from 'zustand'
 import { devtools } from 'zustand/middleware'
-import type { FeatureState } from '@/stores/feature/types'
+import type { FeatureState } from '@/stores/<feature>/types'
 
 const initialState = { items: [] as Item[], activeId: null as string | null }
 
diff --git a/.cursor/rules/sim-testing.mdc b/.cursor/rules/sim-testing.mdc
index 45ec66ebe18..f13f42c93d3 100644
--- a/.cursor/rules/sim-testing.mdc
+++ b/.cursor/rules/sim-testing.mdc
@@ -73,7 +73,7 @@ the report.
 import { authMockFns } from '@sim/testing/mocks/auth.mock'
 import { createMockRequest } from '@sim/testing/mocks/request.mock'
 import { describe, expect, it } from 'vitest'
-import { GET } from '@/app/api/my-route/route'
+import { GET } from '@/app/api/<route>/route'
 
 describe('GET /api/my-route', () => {
   it('returns 401 without a session', async () => {
diff --git a/.cursor/rules/sim-url-state.mdc b/.cursor/rules/sim-url-state.mdc
index ede5704a8e2..ffcbf3e47a4 100644
--- a/.cursor/rules/sim-url-state.mdc
+++ b/.cursor/rules/sim-url-state.mdc
@@ -77,7 +77,7 @@ Conventions:
 ### Example — grouped filters (single source of truth)
 
 ```typescript
-// apps/sim/app/workspace/[workspaceId]/things/search-params.ts
+// apps/sim/app/workspace/[workspaceId]/<feature>/search-params.ts
 import { parseAsArrayOf, parseAsString, parseAsStringLiteral } from 'nuqs/server'
 
 const VIEW_MODES = ['list', 'grid'] as const
@@ -103,7 +103,7 @@ export const thingsUrlKeys = {
 'use client'
 
 import { useQueryStates } from 'nuqs'
-import { thingsParsers, thingsUrlKeys } from '@/app/workspace/[workspaceId]/things/search-params'
+import { thingsParsers, thingsUrlKeys } from '@/app/workspace/[workspaceId]/<feature>/search-params'
 
 export function useThingFilters() {
   const [filters, setFilters] = useQueryStates(thingsParsers, thingsUrlKeys)
@@ -126,7 +126,7 @@ When a Server Component or loader must read a param, build a cache from the **sa
 ```typescript
 // in a server component / page.tsx
 import { createSearchParamsCache } from 'nuqs/server'
-import { thingsParsers } from '@/app/workspace/[workspaceId]/things/search-params'
+import { thingsParsers } from '@/app/workspace/[workspaceId]/<feature>/search-params'
 
 const thingsCache = createSearchParamsCache(thingsParsers)
 
diff --git a/apps/sim/app/(landing)/CLAUDE.md b/apps/sim/app/(landing)/CLAUDE.md
index 15086bfd5e6..88655f18ce1 100644
--- a/apps/sim/app/(landing)/CLAUDE.md
+++ b/apps/sim/app/(landing)/CLAUDE.md
@@ -7,7 +7,7 @@ This route group owns `/` and the entire public marketing surface - the home pag
 ## What this is
 
 - `app/(landing)/` - the marketing site. A shared `layout.tsx` renders the chrome once (the `LandingShell`: light tokens, navbar with server-side GitHub stars, painted pre-footer CTA, footer, site-wide JSON-LD); each page supplies only its `<main>` content. The painted light/dark CTA and footer are owned by `LandingShell`; never add page-specific closing CTA bands or footer instances.
-- The legacy `app/(home)/` group (old dark landing + `--landing-*` tokens) has been **deleted** - its marketing pages were migrated here and its chrome retired. Do not reintroduce `--landing-*` tokens, Martian Mono accents, or a separate marketing theme.
+- There is one marketing theme: the platform's. Never add `--landing-*` tokens, Martian Mono accents, or a separate marketing palette (the retired dark landing used them).
 
 ## Styling - draw from the platform's tokens
 
diff --git a/package.json b/package.json
index 8aaa3df2ead..4d76f4c6e37 100644
--- a/package.json
+++ b/package.json
@@ -79,6 +79,7 @@
     "check:schema-mock": "bun run scripts/generate-schema-mock.ts --check",
     "check:audits": "bun run scripts/run-audits.ts",
     "check:skills": "bun run scripts/sync-skills.ts --check",
+    "check:guidance-refs": "bun run scripts/check-guidance-refs.ts",
     "check:desktop-bridge": "bun run scripts/check-desktop-bridge-contract.ts --check",
     "check:desktop-ipc": "bun run scripts/check-desktop-ipc-contract.ts",
     "check:route-verbs": "bun run scripts/check-route-verbs.ts",
diff --git a/scripts/check-guidance-refs.ts b/scripts/check-guidance-refs.ts
new file mode 100644
index 00000000000..e67f9fd2794
--- /dev/null
+++ b/scripts/check-guidance-refs.ts
@@ -0,0 +1,320 @@
+#!/usr/bin/env bun
+/**
+ * Fails when agent guidance names something that does not exist.
+ *
+ * Agents follow `CLAUDE.md`, every `AGENTS.md`, `.claude/rules/*.md`, and the skills under
+ * `.agents/skills/` literally. A rule that points at a moved file, a renamed `check:*` script, a
+ * deleted skill, or an import path that no longer resolves sends the agent searching for it, or
+ * worse, recreating it. Code moves weekly and nothing else ties the prose to the tree, so this
+ * audit resolves every concrete reference the guidance makes:
+ *
+ * - `path`: a backticked or linked repo path (`apps/sim/lib/...`, `.claude/rules/x.md`,
+ *   `scripts/x.ts`). Resolved against the repo root, the document's directory, and `apps/sim`
+ *   (rules usually name app paths without the prefix). A path whose first segment exists in none
+ *   of those is not treated as a path, so MIME types and prose like `basic/advanced` pass.
+ * - `script`: `bun run <name>`, `turbo run <name>`, or a bare `check:<x>` / `<x>:check` that is
+ *   not a script in any workspace `package.json`.
+ * - `skill`: `/name` on a line that talks about skills, or `` `name` skill ``, with no
+ *   `.agents/skills/<name>/SKILL.md`.
+ * - `import`: an `@/…` or `@sim/…` specifier (in a code span, or a fenced `import`/`from` line)
+ *   that does not resolve to a file, directory, or package export.
+ *
+ * Placeholders are skipped rather than allow-listed: anything containing `<…>`, `{…}`, `*`, or
+ * an ellipsis is a pattern, not a reference. A reference in `~/…`, a URL, or another repo is out
+ * of scope.
+ *
+ * Fix a finding by pointing the sentence at the current path or name, or delete the sentence when
+ * the thing is gone. There is no baseline: guidance is small enough to keep at zero.
+ *
+ * Run: `bun run check:guidance-refs`
+ */
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
+import path from 'node:path'
+
+const ROOT = path.resolve(import.meta.dir, '..')
+const APP_ROOT = path.join(ROOT, 'apps/sim')
+const SKILLS_DIR = path.join(ROOT, '.agents/skills')
+const SKIP_DIRS = new Set(['node_modules', '.git', '.next', '.turbo', 'dist', 'build', 'worktrees'])
+const SOURCE_EXTENSIONS = ['', '.ts', '.tsx', '.js', '.mjs', '.json', '.md', '.css']
+
+interface Finding {
+  file: string
+  line: number
+  kind: 'path' | 'script' | 'skill' | 'import'
+  ref: string
+}
+
+/** Every guidance document, deduplicated through symlinks (`AGENTS.md` -> `CLAUDE.md`). */
+function guidanceFiles(): string[] {
+  const found = new Map<string, string>()
+  const add = (file: string) => {
+    const real = realpathSync(file)
+    if (!found.has(real)) found.set(real, path.relative(ROOT, file))
+  }
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (SKIP_DIRS.has(entry.name)) continue
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        // `.claude/skills` is a generated projection of `.agents/skills`.
+        if (full === path.join(ROOT, '.claude/skills') || full === path.join(ROOT, '.cursor')) {
+          continue
+        }
+        walk(full)
+      } else if (entry.name === 'AGENTS.md' || entry.name === 'CLAUDE.md') {
+        add(full)
+      }
+    }
+  }
+  walk(ROOT)
+  for (const entry of readdirSync(path.join(ROOT, '.claude/rules'))) {
+    if (entry.endsWith('.md')) add(path.join(ROOT, '.claude/rules', entry))
+  }
+  const walkSkills = (dir: string) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) walkSkills(full)
+      else if (entry.name.endsWith('.md')) add(full)
+    }
+  }
+  walkSkills(SKILLS_DIR)
+  return [...found.values()].sort()
+}
+
+/** Script names declared by the root and every workspace `package.json`. */
+function scriptNames(): Set<string> {
+  const names = new Set<string>()
+  const manifests = [path.join(ROOT, 'package.json')]
+  for (const group of ['apps', 'packages']) {
+    for (const entry of readdirSync(path.join(ROOT, group))) {
+      const manifest = path.join(ROOT, group, entry, 'package.json')
+      if (existsSync(manifest)) manifests.push(manifest)
+    }
+  }
+  for (const manifest of manifests) {
+    const scripts = JSON.parse(readFileSync(manifest, 'utf8')).scripts ?? {}
+    for (const name of Object.keys(scripts)) names.add(name)
+  }
+  return names
+}
+
+interface WorkspacePackage {
+  dir: string
+  exports: string[]
+}
+
+/** `@sim/*` packages by name, with their export subpaths. */
+function workspacePackages(): Map<string, WorkspacePackage> {
+  const packages = new Map<string, WorkspacePackage>()
+  for (const entry of readdirSync(path.join(ROOT, 'packages'))) {
+    const manifestPath = path.join(ROOT, 'packages', entry, 'package.json')
+    if (!existsSync(manifestPath)) continue
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+    if (typeof manifest.name !== 'string') continue
+    const exports =
+      manifest.exports && typeof manifest.exports === 'object' ? Object.keys(manifest.exports) : []
+    packages.set(manifest.name, { dir: path.join(ROOT, 'packages', entry), exports })
+  }
+  return packages
+}
+
+function isPlaceholder(ref: string): boolean {
+  return /[<>{}*$]|\.\.\.|…|\bfoo\b|\bxxx?\b/i.test(ref)
+}
+
+function resolvesFrom(base: string, ref: string): boolean {
+  return SOURCE_EXTENSIONS.some((ext) => existsSync(path.join(base, `${ref}${ext}`)))
+}
+
+const PATH_PREFIXES = ['apps/', 'packages/', 'scripts/', '.claude/', '.agents/', '.github/']
+
+/**
+ * Checks a path-shaped token. Returns false only for a confirmed dead reference: a token whose
+ * first segment does not exist anywhere is prose, not a path.
+ */
+function pathResolves(ref: string, docDir: string): boolean {
+  const clean = ref
+    .replace(/[#?].*$/, '')
+    .replace(/:\d+(-\d+)?$/, '')
+    .replace(/\/$/, '')
+  if (!clean) return true
+  const bases = [ROOT, docDir, APP_ROOT]
+  if (PATH_PREFIXES.some((prefix) => clean.startsWith(prefix))) {
+    return resolvesFrom(ROOT, clean)
+  }
+  const first = clean.replace(/^\.\//, '').split('/')[0]
+  const anchored = bases.filter((base) => existsSync(path.join(base, first)))
+  if (anchored.length === 0) return true
+  return anchored.some((base) => resolvesFrom(base, clean.replace(/^\.\//, '')))
+}
+
+function importResolves(spec: string, packages: Map<string, WorkspacePackage>): boolean {
+  const clean = spec.replace(/\/$/, '')
+  if (clean === '@' || clean === '@sim') return true
+  if (clean.startsWith('@/')) {
+    const rel = clean.slice(2)
+    return (
+      resolvesFrom(APP_ROOT, rel) ||
+      ['/index.ts', '/index.tsx'].some((index) => existsSync(path.join(APP_ROOT, `${rel}${index}`)))
+    )
+  }
+  const [scope, name, ...rest] = clean.split('/')
+  const pkg = packages.get(`${scope}/${name}`)
+  if (!pkg) return false
+  if (rest.length === 0) return true
+  const subpath = `./${rest.join('/')}`
+  if (pkg.exports.length === 0) return resolvesFrom(pkg.dir, rest.join('/'))
+  return pkg.exports.some((key) => {
+    if (key === subpath) return true
+    if (!key.includes('*')) return false
+    const [head, tail] = key.split('*')
+    return subpath.startsWith(head) && subpath.endsWith(tail)
+  })
+}
+
+function skillExists(name: string): boolean {
+  return existsSync(path.join(SKILLS_DIR, name, 'SKILL.md'))
+}
+
+const CODE_SPAN = /`([^`\n]+)`/g
+const MD_LINK = /\]\(([^)\s]+)\)/g
+const SCRIPT_RUN =
+  /\b(?:bun run|turbo run|bunx turbo run)\s+(?:--filter[= ]\S+\s+|-F\s+\S+\s+)?([^\s`'"]+)/g
+const IMPORT_SPEC = /(['"`])((?:@\/|@sim\/)[^'"`\s]+)\1/g
+const SKILL_SLASH = /(?:^|[\s(`"'])\/([a-z][a-z0-9]*(?:-[a-z0-9]+)+|[a-z]{3,})(?=[\s`)"',.:;]|$)/g
+const SKILL_NAMED = /`\/?([a-z][a-z0-9-]+)`\s+skills?\b/g
+const REPO_PATH =
+  /(?:^|[\s'"`(=])((?:apps|packages|scripts|\.claude|\.agents|\.github)\/[\w@.()[\]{}<>*/-]+)/g
+const CHECK_TOKEN = /^(check:[\w:-]+|[\w-]+:check)$/
+const PATH_TOKEN = /^\.{0,2}\/?[\w@.()[\]-]+(?:\/[\w@.()[\]-]*)+$/
+const BARE_DOC = /^[\w.-]+\.md$/
+
+/** Drops sentence punctuation and an unbalanced closing paren from a path found in running text. */
+function trimProse(ref: string): string {
+  let trimmed = ref.replace(/[.,:;]+$/, '')
+  while (trimmed.endsWith(')') && trimmed.split('(').length < trimmed.split(')').length) {
+    trimmed = trimmed.slice(0, -1).replace(/[.,:;]+$/, '')
+  }
+  return trimmed
+}
+
+/** Extracts every unresolved reference from one document. */
+function auditDocument(
+  relFile: string,
+  scripts: Set<string>,
+  packages: Map<string, WorkspacePackage>
+): Finding[] {
+  const findings: Finding[] = []
+  const file = path.join(ROOT, relFile)
+  const docDir = path.dirname(file)
+  const seen = new Set<string>()
+  const report = (line: number, kind: Finding['kind'], ref: string) => {
+    const key = `${line}:${kind}:${ref}`
+    if (seen.has(key)) return
+    seen.add(key)
+    findings.push({ file: relFile, line, kind, ref })
+  }
+
+  const checkScript = (line: number, raw: string) => {
+    const name = raw.replace(/[.,;:)]+$/, '')
+    if (isPlaceholder(name) || name.includes('/') || name.endsWith('.ts')) return
+    if (name.startsWith('-')) return
+    if (!scripts.has(name)) report(line, 'script', name)
+  }
+
+  const checkPath = (line: number, raw: string) => {
+    if (isPlaceholder(raw) || /^[a-z]+:\/\//i.test(raw) || raw.startsWith('~')) return
+    if (raw.startsWith('@/') || raw.startsWith('@sim/')) {
+      if (!importResolves(raw, packages)) report(line, 'import', raw)
+      return
+    }
+    if (raw.startsWith('/')) return
+    if (!pathResolves(raw, docDir)) report(line, 'path', raw)
+  }
+
+  let inFence = false
+  const lines = readFileSync(file, 'utf8').split('\n')
+  lines.forEach((text, index) => {
+    const line = index + 1
+    if (/^\s*(```|~~~)/.test(text)) {
+      inFence = !inFence
+      return
+    }
+    for (const match of text.matchAll(SCRIPT_RUN)) checkScript(line, match[1])
+    for (const match of text.matchAll(REPO_PATH)) checkPath(line, trimProse(match[1]))
+    if (inFence) {
+      // Example code: only imports are concrete enough to check.
+      if (/\b(?:from|import|mock|vi\.mock|doMock)\b/.test(text)) {
+        for (const match of text.matchAll(IMPORT_SPEC)) checkPath(line, match[2])
+      }
+      return
+    }
+
+    for (const match of text.matchAll(CODE_SPAN)) {
+      const span = match[1].trim()
+      if (CHECK_TOKEN.test(span)) {
+        checkScript(line, span)
+        continue
+      }
+      for (const imported of span.matchAll(IMPORT_SPEC)) checkPath(line, imported[2])
+      if (span.startsWith('@/') || span.startsWith('@sim/')) {
+        checkPath(line, span.split(/\s/)[0])
+        continue
+      }
+      const token = span.split(/\s/)[0]
+      if (span === token && PATH_TOKEN.test(token)) checkPath(line, token)
+      else if (span === token && BARE_DOC.test(token) && !isPlaceholder(token)) {
+        const bases = [docDir, ROOT, path.join(ROOT, '.claude/rules')]
+        if (!bases.some((base) => existsSync(path.join(base, token)))) report(line, 'path', token)
+      }
+    }
+    for (const match of text.matchAll(MD_LINK)) {
+      const target = match[1]
+      if (/^(https?:|mailto:|#)/.test(target)) continue
+      const resolved = target.startsWith('/') ? target.slice(1) : target
+      if (!pathResolves(resolved, docDir)) report(line, 'path', target)
+    }
+
+    const outsideSpans = text.replace(/`[^`\n]*`/g, (span) =>
+      span.startsWith('`/') ? span : 'CODE'
+    )
+    if (/\bskills?\b/i.test(text)) {
+      for (const match of outsideSpans.matchAll(SKILL_SLASH)) {
+        if (!isPlaceholder(match[1]) && !skillExists(match[1])) report(line, 'skill', match[1])
+      }
+    }
+    for (const match of text.matchAll(SKILL_NAMED)) {
+      if (!skillExists(match[1])) report(line, 'skill', match[1])
+    }
+  })
+  return findings
+}
+
+if (import.meta.main) {
+  const files = guidanceFiles()
+  const scripts = scriptNames()
+  const packages = workspacePackages()
+  const findings = files.flatMap((file) => auditDocument(file, scripts, packages))
+
+  if (findings.length > 0) {
+    const fixes: Record<Finding['kind'], string> = {
+      path: 'no such file or directory',
+      script: 'no package.json declares this script',
+      skill: 'no .agents/skills/<name>/SKILL.md',
+      import: 'specifier does not resolve to a file or package export',
+    }
+    console.error(`Guidance references that do not exist (${findings.length}):\n`)
+    for (const finding of findings) {
+      console.error(
+        `  ${finding.file}:${finding.line}  [${finding.kind}] ${finding.ref} — ${fixes[finding.kind]}`
+      )
+    }
+    console.error(
+      '\nPoint each reference at the current path or name, or delete the sentence if the thing is gone.' +
+        '\nWrite a pattern with a placeholder (`<name>`, `{service}`, `*`) when no single file is meant.'
+    )
+    process.exit(1)
+  }
+
+  console.log(`Guidance references resolve: ${files.length} documents checked.`)
+}

From 857053163058b7aab15e2412d19b26b8ecf3719e Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Thu, 1 Oct 2026 17:12:00 -0700
Subject: [PATCH 03/18] improvement(audits): check rule frontmatter globs in
 check:guidance-refs

A paths glob that matches nothing silently stops the rule from loading.
sim-api-contracts still targeted the removed apps/sim/hooks/selectors; drop
it, and name check:api-validation:strict as the gate the rule describes.
---
 .claude/rules/sim-api-contracts.md   |  5 ++--
 .cursor/rules/emcn-components.mdc    |  6 ++---
 .cursor/rules/sim-api-contracts.mdc  |  6 ++---
 .cursor/rules/sim-architecture.mdc   |  2 +-
 .cursor/rules/sim-components.mdc     |  5 ++--
 .cursor/rules/sim-list-ordering.mdc  | 14 ++++-------
 .cursor/rules/sim-queries.mdc        |  1 -
 .cursor/rules/sim-settings-pages.mdc | 16 ++++---------
 .cursor/rules/sim-styling.mdc        | 16 ++++++-------
 .cursor/rules/sim-testing.mdc        | 11 ++++-----
 .cursor/rules/sim-url-state.mdc      | 11 +--------
 scripts/check-guidance-refs.ts       | 35 +++++++++++++++++++++++++++-
 12 files changed, 66 insertions(+), 62 deletions(-)

diff --git a/.claude/rules/sim-api-contracts.md b/.claude/rules/sim-api-contracts.md
index 819adc3db0b..ea0a20a91d6 100644
--- a/.claude/rules/sim-api-contracts.md
+++ b/.claude/rules/sim-api-contracts.md
@@ -5,7 +5,6 @@ paths:
   - "apps/sim/lib/api/**"
   - "apps/sim/lib/**/application/**"
   - "apps/sim/hooks/queries/**"
-  - "apps/sim/hooks/selectors/**"
 ---
 
 # API Contracts and Routes
@@ -19,7 +18,7 @@ Boundary HTTP request and response shapes for all routes under `apps/sim/app/api
 
 ## Enforcement
 
-`bun run check:api-validation` enforces boundary policy and prints ratchet metrics (route Zod imports, route-local schema constructors, route `ZodError` references, client hook Zod imports, and related counters). `bun run check:api-validation:strict` is the CI gate: it additionally fails on annotations with empty reasons. Both must pass on PRs.
+`bun run check:api-validation:strict` is the gate (it runs in `check:audits`): it enforces boundary policy, prints ratchet metrics (route Zod imports, route-local schema constructors, route `ZodError` references, client hook Zod imports), and fails on annotations with empty reasons. `check:api-validation` is the same audit without the strict reason check.
 
 Whole-file allowlists for routes that legitimately import Zod for non-boundary reasons go through `INDIRECT_ZOD_ROUTES` in `scripts/check-api-validation-contracts.ts`, not per-line annotations.
 
@@ -27,7 +26,7 @@ Whole-file allowlists for routes that legitimately import Zod for non-boundary r
 
 A small number of legitimate exceptions are tolerated when annotated. The audit recognizes four forms:
 
-- `// boundary-raw-fetch: <reason>` — directly above a raw `fetch(` inside `apps/sim/hooks/queries/**`, `apps/sim/hooks/selectors/**`, or any other source under `apps/sim/**` (outside an API route handler) that targets a same-origin `/api/...` URL. Only for streaming responses, binary downloads, multipart uploads, signed-URL flows, OAuth redirects, and external-origin requests.
+- `// boundary-raw-fetch: <reason>` — directly above a raw `fetch(` inside `apps/sim/hooks/queries/**` or any other source under `apps/sim/**` (outside an API route handler) that targets a same-origin `/api/...` URL. Only for streaming responses, binary downloads, multipart uploads, signed-URL flows, OAuth redirects, and external-origin requests.
 - `// double-cast-allowed: <reason>` — directly above an `as unknown as X` cast outside test files.
 - `// boundary-raw-json: <reason>` — directly above a raw `await request.json()` / `await req.json()` read (or the multi-line `await request.clone().json()` shim variant) in a route handler. Only when the body is a JSON-RPC envelope, a tolerant `.catch(() => ({}))` parse, or otherwise cannot go through `parseRequest`.
 - `// untyped-response: <reason>` — directly above a `schema: z.unknown()` / `schema: z.object({}).passthrough()` / `schema: z.record(z.string(), z.unknown())` response declaration (or a simple alias to one of those) in a contract file. Only when the response body is genuinely opaque (user-supplied data, third-party passthrough).
diff --git a/.cursor/rules/emcn-components.mdc b/.cursor/rules/emcn-components.mdc
index 05f97dd7ad4..b4743462057 100644
--- a/.cursor/rules/emcn-components.mdc
+++ b/.cursor/rules/emcn-components.mdc
@@ -22,7 +22,7 @@ The menu surface intentionally diverges from the pill: `dropdown-menu.tsx` items
 
 ## Component catalogue
 
-- **`Chip` / `ChipLink`** — the pill button (`<button>` / Next `<Link>`). Variants: `primary`, `destructive`, `border-shadow`, `border`, `outline` (a true `--border` border, no shadow or hover fill); the bare chip is implicit (omit `variant`). `filled` is deliberately NOT a `Chip` variant — it is reserved for chip fields/triggers. For a selected/toggle chip use the `active` prop, never a variant. `leftIcon`/`rightIcon`, `active`, `fullWidth`. Chips carry **no outer margin** — space between them is the parent's `gap`. The old `mx-0.5` default and its `flush` opt-out are gone; do not reintroduce either, and never add a margin to a chip through `className`.
+- **`Chip` / `ChipLink`** — the pill button (`<button>` / Next `<Link>`). Variants: `primary`, `destructive`, `border-shadow`, `border`, `outline` (a true `--border` border, no shadow or hover fill); the bare chip is implicit (omit `variant`). `filled` is deliberately NOT a `Chip` variant — it is reserved for chip fields/triggers. For a selected/toggle chip use the `active` prop, never a variant. `leftIcon`/`rightIcon`, `active`, `fullWidth`. Chips carry **no outer margin** — space between them is the parent's `gap`, so never give a chip a margin, by default or through `className`.
 - **`ChipInput`** — single-line text field. `icon`, `endAdornment`, `error`, `inputClassName` (inner `<input>`); `className` styles the chrome wrapper.
 - **`ChipCopyInput`** — the canonical view-only field: a read-only `ChipInput` at full opacity with a trailing copy-to-clipboard button. View-only is a display mode, not a disabled state — reach for it (or `ChipModalField type='copy'`) over a `disabled` (greyed) input for values the user cannot edit.
 - **`ChipTextarea`** — multi-line sibling. `error`, `resizable` (off by default), `viewOnly` (read-only at full opacity with the default cursor — the multi-line counterpart of `ChipCopyInput`).
@@ -53,8 +53,8 @@ Declare keyboard intent on the action-owning primitive; never add document-level
 - **Props over `className` overrides.** When a consumer needs to change chrome, expose a prop (`error`, `icon`, `endAdornment`, `inputClassName`); reaching for `className` to restyle chrome is the smell.
 - **`cn()` for a single state toggle, CVA for genuine multiple variants.** A lone `error` boolean is `cn()`, not a CVA variant.
 - **Discriminated-union props for modes** (e.g. `multiple`, the modal field `type`) instead of near-duplicate components.
-- **Delete legacy variants after migration** — don't leave dead paths (this paradigm removed `Input variant='chip'` and `ChipMultiSelect`).
-- **Verify CSS vars exist.** An undefined var resolves to `currentColor` (caused a real black-border bug). Align to the canonical tokens: normal weight, `--text-body`, `--text-icon`.
+- **Delete legacy variants after migration** — leave no dead paths.
+- **Verify CSS vars exist.** An undefined var resolves to `currentColor`, which draws black borders. Align to the canonical tokens: normal weight, `--text-body`, `--text-icon`.
 - Use Radix UI primitives for accessibility. Export the component and its `variants` (when using CVA). Document with TSDoc + a usage example.
 
 Color tokens and icon-size conventions are canonical in `.claude/rules/sim-styling.md` — follow it rather than restating.
diff --git a/.cursor/rules/sim-api-contracts.mdc b/.cursor/rules/sim-api-contracts.mdc
index 9b76bcfb20c..7e97ed8b143 100644
--- a/.cursor/rules/sim-api-contracts.mdc
+++ b/.cursor/rules/sim-api-contracts.mdc
@@ -1,6 +1,6 @@
 ---
 description: "API contracts, route builders, boundary annotations, and the requestJson client boundary"
-globs: ["apps/sim/app/api/**","apps/sim/lib/api/**","apps/sim/lib/**/application/**","apps/sim/hooks/queries/**","apps/sim/hooks/selectors/**"]
+globs: ["apps/sim/app/api/**","apps/sim/lib/api/**","apps/sim/lib/**/application/**","apps/sim/hooks/queries/**"]
 ---
 
 <!-- Generated from .claude/rules/sim-api-contracts.md by `bun run skills:sync`. Edit the source, not this file. -->
@@ -16,7 +16,7 @@ Boundary HTTP request and response shapes for all routes under `apps/sim/app/api
 
 ## Enforcement
 
-`bun run check:api-validation` enforces boundary policy and prints ratchet metrics (route Zod imports, route-local schema constructors, route `ZodError` references, client hook Zod imports, and related counters). `bun run check:api-validation:strict` is the CI gate: it additionally fails on annotations with empty reasons. Both must pass on PRs.
+`bun run check:api-validation:strict` is the gate (it runs in `check:audits`): it enforces boundary policy, prints ratchet metrics (route Zod imports, route-local schema constructors, route `ZodError` references, client hook Zod imports), and fails on annotations with empty reasons. `check:api-validation` is the same audit without the strict reason check.
 
 Whole-file allowlists for routes that legitimately import Zod for non-boundary reasons go through `INDIRECT_ZOD_ROUTES` in `scripts/check-api-validation-contracts.ts`, not per-line annotations.
 
@@ -24,7 +24,7 @@ Whole-file allowlists for routes that legitimately import Zod for non-boundary r
 
 A small number of legitimate exceptions are tolerated when annotated. The audit recognizes four forms:
 
-- `// boundary-raw-fetch: <reason>` — directly above a raw `fetch(` inside `apps/sim/hooks/queries/**`, `apps/sim/hooks/selectors/**`, or any other source under `apps/sim/**` (outside an API route handler) that targets a same-origin `/api/...` URL. Only for streaming responses, binary downloads, multipart uploads, signed-URL flows, OAuth redirects, and external-origin requests.
+- `// boundary-raw-fetch: <reason>` — directly above a raw `fetch(` inside `apps/sim/hooks/queries/**` or any other source under `apps/sim/**` (outside an API route handler) that targets a same-origin `/api/...` URL. Only for streaming responses, binary downloads, multipart uploads, signed-URL flows, OAuth redirects, and external-origin requests.
 - `// double-cast-allowed: <reason>` — directly above an `as unknown as X` cast outside test files.
 - `// boundary-raw-json: <reason>` — directly above a raw `await request.json()` / `await req.json()` read (or the multi-line `await request.clone().json()` shim variant) in a route handler. Only when the body is a JSON-RPC envelope, a tolerant `.catch(() => ({}))` parse, or otherwise cannot go through `parseRequest`.
 - `// untyped-response: <reason>` — directly above a `schema: z.unknown()` / `schema: z.object({}).passthrough()` / `schema: z.record(z.string(), z.unknown())` response declaration (or a simple alias to one of those) in a contract file. Only when the response body is genuinely opaque (user-supplied data, third-party passthrough).
diff --git a/.cursor/rules/sim-architecture.mdc b/.cursor/rules/sim-architecture.mdc
index 9465cf547f4..c5a0e6f118d 100644
--- a/.cursor/rules/sim-architecture.mdc
+++ b/.cursor/rules/sim-architecture.mdc
@@ -11,7 +11,7 @@ Repository layout, package boundaries, the application operation boundary, namin
 
 ## The `'use client'` server boundary
 
-Every export of a `'use client'` module becomes a *client reference* on the server — server-evaluated code (RSC pages/layouts, `prefetch.ts`, route handlers, block definitions, triggers) can only *render* it as a component or pass it as a prop, never *call* it (doing so throws at runtime, e.g. `tableKeys.list is not a function`; `next build` does not catch it). Keep server-importable query primitives (key factories, fetchers, mappers, constants) in non-`'use client'` modules — see `.claude/rules/sim-queries.md`. Enforced by `scripts/check-client-boundary-imports.ts`.
+Server-evaluated code (RSC pages/layouts, `prefetch.ts`, route handlers, block definitions, triggers) can render an export of a `'use client'` module but never call it; the call throws at runtime and `next build` does not catch it. Keep anything a server module calls (key factories, fetchers, mappers, constants) in a non-`'use client'` module. Detail and the escape hatch: `.claude/rules/sim-queries.md`. Enforced by `bun run check:client-boundary`.
 
 ## The app/worker runtime boundary
 
diff --git a/.cursor/rules/sim-components.mdc b/.cursor/rules/sim-components.mdc
index d592832a0c5..13dfcfbac78 100644
--- a/.cursor/rules/sim-components.mdc
+++ b/.cursor/rules/sim-components.mdc
@@ -33,8 +33,7 @@ export function Component({ requiredProp, optionalProp = false }: ComponentProps
 
 When rendering or sorting a list of rows against a lookup collection (members, folders, tags), keep the per-row work O(1):
 
-- **Precompute a lookup `Map` once**, never `array.find(...)` per row. Build `const byId = useMemo(() => { const m = new Map<string, T>(); for (const x of items ?? []) m.set(x.id, x); return m }, [items])` and read `byId.get(id)` in the sort comparator, `.map(...)`, and cell builders. A `.find` inside a sort comparator is O(n²·log n) — the worst offender. Depend memos on the derived `Map`, not the raw array.
-- **Sort a copy with `[...array].sort(cmp)`**, never `toSorted` (`check:utils` bans it repo-wide) — see `sim-react-performance.md` → "Never mutate a shared array in place".
+- **Precompute a lookup `Map` once** (`useMemo` over the collection) and read `byId.get(id)` in the sort comparator, `.map(...)`, and cell builders. A `.find` inside a sort comparator is O(n²·log n). Depend downstream memos on the derived `Map`, not the raw array. Map-building and copy-then-sort rules: `sim-react-performance.md`.
 - **Partition in a single pass** — when splitting one collection into several (`fileIds`/`folderIds`), do one `for…of` pushing into each bucket and return `{ a, b }` from a single `useMemo`, not two memos that each `map→filter→map` the same source twice.
 
 ## react-doctor (`bunx react-doctor`) — apply the wins, skip the false positives
@@ -42,7 +41,7 @@ When rendering or sorting a list of rows against a lookup collection (members, f
 react-doctor diagnostics are hypotheses, not verdicts — confirm against the code before acting, and preserve behavior. Known repo-specific false positives to NOT "fix":
 
 - `no-barrel-import` — barrel imports are the repo convention (see sim-imports.md, "Barrel Exports"). Keep them.
-- `js-tosorted-immutable` — won't-fix anywhere; `check:utils` bans the ES2023 array methods repo-wide.
+- `js-tosorted-immutable` — won't-fix in `'use client'` code (see "List-render performance" above); apply it only in server-only modules.
 - `rerender-state-only-in-handlers` / "state set but never rendered" — a false positive when the `useState` is consumed by a `useEffect`/`useLayoutEffect` dependency (the effect must re-run on change). Only convert to a ref when nothing reads the value reactively.
 - `no-render-in-render` — a helper *called inline* (`{renderRow()}`) is reconciled by position and does **not** remount, so extracting it to a component is usually pure churn and can regress behavior (prop-drilling many closures, focus/scroll loss on the inner `<input>`). Apply it only when the helper is genuinely a *component defined during render*, or when the move is mechanical (a stateless, ref-free helper whose closures become a small, explicit prop set).
 - `async-await-in-loop` on an upload/progress loop where sequential execution is intentional (per-item progress, server backpressure) — leave it.
diff --git a/.cursor/rules/sim-list-ordering.mdc b/.cursor/rules/sim-list-ordering.mdc
index a1eb0b94af8..a11aa415ab9 100644
--- a/.cursor/rules/sim-list-ordering.mdc
+++ b/.cursor/rules/sim-list-ordering.mdc
@@ -9,8 +9,6 @@ globs: ["apps/sim/app/**/*.tsx","apps/sim/ee/**/*.tsx","apps/sim/components/**/*
 
 **A list orders itself the way the user already reads the same things somewhere else.** Dropdowns, context menus, tab strips, command palettes, and settings navs are all *second* presentations of a set the user has already seen — in a toolbar, in the settings nav, in a column-header row. When the second presentation reorders that set, the user re-reads it from scratch every time.
 
-This is not a style preference. Order is the cheapest affordance a list has, and the only one that costs nothing to get right.
-
 ## The rule
 
 Before writing a list of items, find where the user sees those same items *first*. That surface owns the order; your list mirrors it.
@@ -93,14 +91,10 @@ const hasDestructiveSection = (showLeave && onLeave) || showDelete
 {hasActionsAboveDestructive && hasDestructiveSection && <DropdownMenuSeparator />}
 ```
 
-This is the failure that put a dangling rule at the bottom of the logs row menu, where two
-unconditional separators sat above conditional items.
+Unconditional separators above conditional items leave a dangling rule at the bottom of the menu.
 
-**Do not add a prop to move a rule.** The shared workflow context menu grew
-`groupNonDestructiveActions` and `separateNavigationAction` for this; between them they moved one
-separator for one caller, four of six branches were unreachable, and `separateNavigationAction`
-had no observable effect anywhere in the repo. Both are gone. A menu that wants different
-grouping wants the standard grouping.
+**Never add a prop to move a rule.** Per-caller grouping props multiply unreachable branches; a
+menu that wants different grouping wants the standard grouping.
 
 ## Encode the order once
 
@@ -130,7 +124,7 @@ The most common way a canonical order gets silently defeated: emitting all items
 {groups.filter((g) => !FOLDERED.has(g.type)).map(renderFlat)}
 
 // ✓ Good — one ordered pass; each entry picks its own rendering
-{entries.sort(byResourceMenuOrder).map((entry) =>
+{[...entries].sort(byResourceMenuOrder).map((entry) =>
   sectionByType.has(entry.type) ? renderTree(entry) : renderFlat(entry)
 )}
 ```
diff --git a/.cursor/rules/sim-queries.mdc b/.cursor/rules/sim-queries.mdc
index 50f6a43da31..82f695bc66b 100644
--- a/.cursor/rules/sim-queries.mdc
+++ b/.cursor/rules/sim-queries.mdc
@@ -141,7 +141,6 @@ const handler = useCallback(() => {
 // ✓ Good — omit from deps, mutate is stable
 const handler = useCallback(() => {
   createEntity.mutate(data)
-  // eslint-disable-next-line react-hooks/exhaustive-deps
 }, [data])
 ```
 
diff --git a/.cursor/rules/sim-settings-pages.mdc b/.cursor/rules/sim-settings-pages.mdc
index d14a9dabc2a..7dd93bdc92b 100644
--- a/.cursor/rules/sim-settings-pages.mdc
+++ b/.cursor/rules/sim-settings-pages.mdc
@@ -110,17 +110,9 @@ Adding a new settings page:
 
 ## Text-scale tokens (no literal pixel sizes)
 
-Settings pages never use a literal `text-[Npx]` class — always the named Tailwind
-scale token from the `@theme` block in `apps/sim/app/_styles/globals.css` (`text-micro`
-10px, `text-xs` 11px, `text-caption` 12px, `text-small` 13px, `text-sm` 14px
-[Tailwind default, unmodified], `text-base` 15px, `text-md` 16px, `text-lg` 18px
-[Tailwind default]). A literal size is either a straight rename to the equivalent
-token (if the pixel value matches one exactly) or a sign the page never migrated —
-grep `text-\[1[0-8]px\]` under `apps/sim/app/workspace/*/settings/**` and
-`apps/sim/ee/**` to find stragglers.
-
-Watch `text-xs`: it is 11px here, so a "caption" written as `text-xs` is a pixel
-short. See `sim-styling.md` for the full scale.
+Settings pages never use a literal `text-[Npx]` class — always a named token from
+the scale in `sim-styling.md` ("Text Scale"). Find stragglers with
+`rg 'text-\[1[0-8]px\]' apps/sim/app/workspace apps/sim/ee`.
 
 The two-line list row (title over a muted subtitle — a name + email, a tool name
 + description, a server name + status) is **not something you build**: it is
@@ -399,4 +391,4 @@ A settings page is design-system-clean when:
 - [ ] Decorative trailing content is in `badge`, not `trailing`.
 - [ ] Labeled sections use `SettingsSection`; read-only fields use `SettingsField`; empty/loading/error use `SettingsEmptyState`.
 - [ ] Delete is a plain `id:'delete'` header action behind a `ChipConfirmModal`; `destructive` is reserved for bulk actions.
-- [ ] `tsc`, `biome`, and the page's tests pass.
+- [ ] The local gate in the root `CLAUDE.md` ("How your work is checked") passes.
diff --git a/.cursor/rules/sim-styling.mdc b/.cursor/rules/sim-styling.mdc
index 9527e796e49..54ef96abfb8 100644
--- a/.cursor/rules/sim-styling.mdc
+++ b/.cursor/rules/sim-styling.mdc
@@ -15,8 +15,8 @@ globs: ["apps/sim/**/*.tsx","apps/sim/**/*.css"]
 2. **No duplicate dark classes** - Skip `dark:` when value matches light mode
 3. **Exact values over approximations** - `h-[26px]`, not `h-6`. But **type size is
    always a named token** (`text-sm`, `text-caption`) — never `text-[14px]`, which
-   sets font-size only and inherits a different line-height. See
-   `sim-settings-pages.md` for the scale.
+   sets font-size only and inherits a different line-height. The scale is under
+   "Text Scale" below.
 4. **Transitions** - `transition-colors` for interactive states
 
 ## Conditional Classes
@@ -48,7 +48,7 @@ setWidth: (width) => {
 
 ## Text Scale
 
-Custom font sizes (the `@theme` block in `apps/sim/app/_styles/globals.css`): `text-micro`=10px, `text-xs`=11px, `text-caption`=12px, `text-small`=13px, `text-base`=15px. `text-sm` is Tailwind default 14px. Field titles use `text-small` (13px); hints/errors use `text-caption` (12px).
+The `@theme` block in `apps/sim/app/_styles/globals.css`: `text-micro` 10px, `text-xs` 11px, `text-caption` 12px, `text-small` 13px, `text-sm` 14px (Tailwind default), `text-base` 15px, `text-md` 16px, `text-lg` 18px (Tailwind default). `text-xs` is 11px here, so a caption written as `text-xs` is a pixel short. Field titles use `text-small`; hints/errors use `text-caption`. A literal `text-[Npx]` is either a rename to the matching token or an unmigrated straggler.
 
 Icons default `size-[14px]`. Equal h/w → `size-*` (`size-[14px]`, `size-4`), never `h-N w-N` or `h-[Npx] w-[Npx]`.
 
@@ -70,7 +70,7 @@ A scroll region that can hide rows past an edge uses `useScrollEdges` with `scro
 
 Three steps, Tailwind's stock scale, nothing else: **`font-normal` (400)**, **`font-medium` (500)**, **`font-semibold` (600)**. 400 is the document default, so body text, chip labels, sidebar items, and headings carry **no weight class at all** — they inherit. Reach for a class only to step *up* from body.
 
-Never write an arbitrary weight (`font-[380]`, `font-[430]`, `font-[450]`, …), and never set `fontWeight` in an inline `style`. There was previously a CSS-variable weight scale (`--font-weight-base/medium/semibold`, remapping `font-medium` to 440/480) plus seven ad-hoc values clustered between 380 and 500; it was deleted because nothing read as hierarchical. Off-scale values are only acceptable where the design system genuinely cannot reach — react-email templates and the static `apps/sim/emails/broadcasts/*.html`, which email clients render without CSS variables.
+Never write an arbitrary weight (`font-[380]`, `font-[450]`, …) or a `--font-weight-*` variable, and never set `fontWeight` in an inline `style`: values clustered between the three steps do not read as hierarchy. Off-scale values are acceptable only where the design system cannot reach — react-email templates and the static `apps/sim/emails/broadcasts/*.html`, which email clients render without CSS variables.
 
 Headings inherit their weight. Tailwind preflight resets `h1`–`h6` to `font-weight: inherit`, so an `<h1>` is 400 unless you say otherwise — that is the intended look, not a bug to patch.
 
@@ -95,19 +95,19 @@ Draw a line with a real `border-*` utility. Never hand-roll one as `shadow-[inse
 - **Errors** → `error` prop. Never `className={cn(err && 'border-[var(--text-error)]')}`.
 - **Leading icon** → `icon` prop (rendered 14px in `--text-icon`).
 - **Trailing buttons** (reveal/copy/fetch) → `endAdornment`.
-- **Inner-input styling** (e.g. `font-mono`, number-spinner reset) → `inputClassName` (ChipInput only). See `app/workspace/[workspaceId]/settings/components/billing/components/usage-limit-field/usage-limit-field.tsx:117`.
-- **`ChipModalField` controls take NO className.** Pass `title`/`value`/`onChange`/`error`/`hint`/`required`/`flush`. The field owns label, control, and error/hint rendering. See `app/workspace/[workspaceId]/skills/components/skill-modal/skill-modal.tsx:170`.
+- **Inner-input styling** (e.g. `font-mono`, number-spinner reset) → `inputClassName` (ChipInput only). See `app/workspace/[workspaceId]/settings/components/billing/components/usage-limit-field/usage-limit-field.tsx`.
+- **`ChipModalField` controls take NO className.** Pass `title`/`value`/`onChange`/`error`/`hint`/`required`/`flush`. The field owns label, control, and error/hint rendering. See `app/workspace/[workspaceId]/skills/components/skill-modal/skill-modal.tsx`.
 
 ### What className MAY carry
 
-Layout/sizing ONLY: `flex-1`, `w-full`, `w-[Npx]`, `min-w-0`, `max-w-*`, margins. `truncate` is allowed only for the explicit overflow exceptions above, never as a general layout class. Example: `<ChipInput icon={Search} className='min-w-0 flex-1' .../>` (`app/workspace/[workspaceId]/integrations/integrations.tsx:257`). NEVER re-specify canonical chrome — the component already applies it.
+Layout/sizing ONLY: `flex-1`, `w-full`, `w-[Npx]`, `min-w-0`, `max-w-*`, margins. `truncate` is allowed only for the explicit overflow exceptions above, never as a general layout class. Example: `<ChipInput icon={Search} className='min-w-0 flex-1' .../>` (`app/workspace/[workspaceId]/integrations/integrations.tsx`). NEVER re-specify canonical chrome — the component already applies it.
 
 ### Form / chip-modal layout rhythm
 
 - **Field row** = `ChipModalField`: label↔control `gap-[9px]`, field gutter `px-2` (`px-0` when `flush`). Title = `Label` at `text-small` (13px), muted, normal weight; hint/error at `text-caption` (12px).
 - **Modal body** (`ChipModalBody`): `gap-4` between fields, padding `px-2 pt-4 pb-4.5`.
 - **Header/footer**: horizontal gutter `px-4` (header `pt-3`; footer `px-4 pt-2 pb-2`, tinted bar).
-- **Every body field MUST be a `ChipModalField`** — NEVER hand-roll a field row (raw `<div>` + hand-rolled `<p>`/`<label>` title + bare `ChipInput`/`ChipTextarea`). WHY: body `px-2` + field `px-2` = effective `px-4`, exactly matching the `px-4` header/footer. A hand-rolled row skips the field gutter, sits at `px-2`, and is visibly misaligned (this bug shipped in the scheduled-tasks "Create new scheduled task" modal). Inline errors go through the `error` prop, not a hand-rolled `<p>`.
+- **Every body field MUST be a `ChipModalField`** — NEVER hand-roll a field row (raw `<div>` + hand-rolled `<p>`/`<label>` title + bare `ChipInput`/`ChipTextarea`). WHY: body `px-2` + field `px-2` = effective `px-4`, exactly matching the `px-4` header/footer. A hand-rolled row skips the field gutter, sits at `px-2`, and is visibly misaligned. Inline errors go through the `error` prop, not a hand-rolled `<p>`.
 - **Uncovered controls** (`ChipCombobox`, `ChipSelect`, `DatePicker`, `TimePicker`, `ButtonGroup`, arbitrary JSX) → `ChipModalField type='custom'` with a `title`. It still applies the `px-2` gutter and renders the canonical `Label`, so it stays aligned. Never drop such a control into a raw `<div>`, and never add a body-level wrapper `<div>` with a custom `gap-*` that fights `gap-4`.
 - **Page section rhythm** (integrations/skills/settings): muted `text-small` label + `mt-[9px] mb-3 h-px bg-[var(--border)]` divider, sections stacked `gap-7`. Reuse `SettingsSection` (`app/workspace/[workspaceId]/settings/components/settings-section/settings-section.tsx`) rather than re-deriving it.
 
diff --git a/.cursor/rules/sim-testing.mdc b/.cursor/rules/sim-testing.mdc
index f13f42c93d3..76de6f203dd 100644
--- a/.cursor/rules/sim-testing.mdc
+++ b/.cursor/rules/sim-testing.mdc
@@ -7,10 +7,9 @@ globs: ["**/*.test.ts","**/*.test.tsx","**/*.integration.ts","**/e2e/**"]
 
 # Testing
 
-Before writing or changing any test, run the `test-audit` skill's authoring gate. The short
-version: never write unit tests after the code; prefer E2E tests at the real boundary and end
-them with a verifiable artifact; if you must test in isolation, write the failure modes down
-first. A test that cannot name the bug it catches does not get written.
+The testing principles are in the root `CLAUDE.md` → Testing. Before writing or changing any test,
+run the `test-audit` skill's authoring gate: a test that cannot name the bug it catches does not
+get written.
 
 ## Layers
 
@@ -25,9 +24,7 @@ What already catches bugs, in the order to reach for it:
 
 A unit test is justified only for a failure the layers above cannot see: security boundaries,
 billing math, executor semantics, parsers and algorithms with edge cases, cross-process wire
-contracts, and demonstrated regressions. Never restate declarations (block/tool/provider config,
-registries, constants, schemas accepting valid input), assert that mocks were called, check
-rendered text or class names, or test mocks and factories themselves.
+contracts, and demonstrated regressions.
 
 ## Naming
 
diff --git a/.cursor/rules/sim-url-state.mdc b/.cursor/rules/sim-url-state.mdc
index ffcbf3e47a4..3537973d9aa 100644
--- a/.cursor/rules/sim-url-state.mdc
+++ b/.cursor/rules/sim-url-state.mdc
@@ -11,16 +11,7 @@ URL query state is managed with [`nuqs`](https://nuqs.dev). The `NuqsAdapter` is
 
 ## Decision framework — where does this state live?
 
-Pick exactly one home for each piece of state:
-
-- **React Query** → server/remote data. Unchanged; see `.claude/rules/sim-queries.md`.
-- **URL params (nuqs)** → client view-state worth putting in a link: active tab/panel, selected entity id, filters, search query, pagination, view mode (list/grid), an open "view" drawer/modal that represents a destination.
-- **Zustand** → cross-component client state that must NOT be in the URL: high-frequency, large, ephemeral, or socket-synced (canvas pan/zoom, cursor, drag state, resize widths, unsaved buffers, live collaborative selection).
-- **`useState`** → purely local, single-component UI.
-
-Put state in the URL **only** when it is *all* of: shareable, deep-linkable, bookmarkable, survives reload + back/forward — **and** is discrete, low-frequency, and small. If it fails any of those, it does not go in the URL.
-
-### When to use what (decision table)
+Pick exactly one home for each piece of state (table below). Put state in the URL **only** when it is *all* of: shareable, deep-linkable, bookmarkable, survives reload + back/forward — **and** is discrete, low-frequency, and small. If it fails any of those, it does not go in the URL.
 
 | Home | Trigger | Example |
 | --- | --- | --- |
diff --git a/scripts/check-guidance-refs.ts b/scripts/check-guidance-refs.ts
index e67f9fd2794..0848a1b3c5f 100644
--- a/scripts/check-guidance-refs.ts
+++ b/scripts/check-guidance-refs.ts
@@ -18,6 +18,8 @@
  *   `.agents/skills/<name>/SKILL.md`.
  * - `import`: an `@/…` or `@sim/…` specifier (in a code span, or a fenced `import`/`from` line)
  *   that does not resolve to a file, directory, or package export.
+ * - a rule's frontmatter `paths:` glob that matches no file, which silently stops the rule from
+ *   loading for the code it was written for.
  *
  * Placeholders are skipped rather than allow-listed: anything containing `<…>`, `{…}`, `*`, or
  * an ellipsis is a pattern, not a reference. A reference in `~/…`, a URL, or another repo is out
@@ -189,6 +191,33 @@ const CHECK_TOKEN = /^(check:[\w:-]+|[\w-]+:check)$/
 const PATH_TOKEN = /^\.{0,2}\/?[\w@.()[\]-]+(?:\/[\w@.()[\]-]*)+$/
 const BARE_DOC = /^[\w.-]+\.md$/
 
+/**
+ * The `paths:` globs in a rule's frontmatter. A glob that matches nothing silently stops the rule
+ * from loading for the files it was written for.
+ */
+function frontmatterPaths(lines: string[]): Array<{ line: number; glob: string }> {
+  if (lines[0] !== '---') return []
+  const globs: Array<{ line: number; glob: string }> = []
+  let inPaths = false
+  for (let index = 1; index < lines.length && lines[index] !== '---'; index++) {
+    const text = lines[index]
+    if (/^paths:\s*$/.test(text)) {
+      inPaths = true
+      continue
+    }
+    const item = text.match(/^\s+-\s+["']?([^"']+)["']?\s*$/)
+    if (inPaths && item) globs.push({ line: index + 1, glob: item[1] })
+    else if (!/^\s/.test(text)) inPaths = false
+  }
+  return globs
+}
+
+function globMatchesAnything(pattern: string): boolean {
+  const glob = new Bun.Glob(pattern)
+  for (const _ of glob.scanSync({ cwd: ROOT, onlyFiles: true })) return true
+  return false
+}
+
 /** Drops sentence punctuation and an unbalanced closing paren from a path found in running text. */
 function trimProse(ref: string): string {
   let trimmed = ref.replace(/[.,:;]+$/, '')
@@ -232,8 +261,12 @@ function auditDocument(
     if (!pathResolves(raw, docDir)) report(line, 'path', raw)
   }
 
-  let inFence = false
   const lines = readFileSync(file, 'utf8').split('\n')
+  for (const { line, glob } of frontmatterPaths(lines)) {
+    if (!globMatchesAnything(glob)) report(line, 'path', glob)
+  }
+
+  let inFence = false
   lines.forEach((text, index) => {
     const line = index + 1
     if (/^\s*(```|~~~)/.test(text)) {

From bb165d2097ad474869d56c6ede6bd3bdcbe909cd Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Thu, 1 Oct 2026 17:12:01 -0700
Subject: [PATCH 04/18] docs(agents): consolidate guidance and add the local
 gate to CLAUDE.md

- CLAUDE.md: "How your work is checked" (the local gate and a rule-to-check
  map), sharper comment rules (no narration, restated names, or change
  history), drop filler, fix the type-check command description.
- Rules: one source for the text scale (sim-styling), use-client boundary
  (sim-queries), testing principles (CLAUDE.md); fix an in-place sort in a
  list-ordering example and an ESLint directive the repo does not use; drop
  change-history narration and rotting line-number references.
---
 .claude/rules/emcn-components.md    |  6 ++---
 .claude/rules/sim-architecture.md   |  2 +-
 .claude/rules/sim-components.md     |  5 ++--
 .claude/rules/sim-list-ordering.md  | 14 +++-------
 .claude/rules/sim-queries.md        |  1 -
 .claude/rules/sim-settings-pages.md | 16 +++--------
 .claude/rules/sim-styling.md        | 16 +++++------
 .claude/rules/sim-testing.md        | 11 +++-----
 .claude/rules/sim-url-state.md      | 11 +-------
 CLAUDE.md                           | 42 +++++++++++++++++++++++++----
 10 files changed, 64 insertions(+), 60 deletions(-)

diff --git a/.claude/rules/emcn-components.md b/.claude/rules/emcn-components.md
index 92f95238590..d4c697869d0 100644
--- a/.claude/rules/emcn-components.md
+++ b/.claude/rules/emcn-components.md
@@ -21,7 +21,7 @@ The menu surface intentionally diverges from the pill: `dropdown-menu.tsx` items
 
 ## Component catalogue
 
-- **`Chip` / `ChipLink`** — the pill button (`<button>` / Next `<Link>`). Variants: `primary`, `destructive`, `border-shadow`, `border`, `outline` (a true `--border` border, no shadow or hover fill); the bare chip is implicit (omit `variant`). `filled` is deliberately NOT a `Chip` variant — it is reserved for chip fields/triggers. For a selected/toggle chip use the `active` prop, never a variant. `leftIcon`/`rightIcon`, `active`, `fullWidth`. Chips carry **no outer margin** — space between them is the parent's `gap`. The old `mx-0.5` default and its `flush` opt-out are gone; do not reintroduce either, and never add a margin to a chip through `className`.
+- **`Chip` / `ChipLink`** — the pill button (`<button>` / Next `<Link>`). Variants: `primary`, `destructive`, `border-shadow`, `border`, `outline` (a true `--border` border, no shadow or hover fill); the bare chip is implicit (omit `variant`). `filled` is deliberately NOT a `Chip` variant — it is reserved for chip fields/triggers. For a selected/toggle chip use the `active` prop, never a variant. `leftIcon`/`rightIcon`, `active`, `fullWidth`. Chips carry **no outer margin** — space between them is the parent's `gap`, so never give a chip a margin, by default or through `className`.
 - **`ChipInput`** — single-line text field. `icon`, `endAdornment`, `error`, `inputClassName` (inner `<input>`); `className` styles the chrome wrapper.
 - **`ChipCopyInput`** — the canonical view-only field: a read-only `ChipInput` at full opacity with a trailing copy-to-clipboard button. View-only is a display mode, not a disabled state — reach for it (or `ChipModalField type='copy'`) over a `disabled` (greyed) input for values the user cannot edit.
 - **`ChipTextarea`** — multi-line sibling. `error`, `resizable` (off by default), `viewOnly` (read-only at full opacity with the default cursor — the multi-line counterpart of `ChipCopyInput`).
@@ -52,8 +52,8 @@ Declare keyboard intent on the action-owning primitive; never add document-level
 - **Props over `className` overrides.** When a consumer needs to change chrome, expose a prop (`error`, `icon`, `endAdornment`, `inputClassName`); reaching for `className` to restyle chrome is the smell.
 - **`cn()` for a single state toggle, CVA for genuine multiple variants.** A lone `error` boolean is `cn()`, not a CVA variant.
 - **Discriminated-union props for modes** (e.g. `multiple`, the modal field `type`) instead of near-duplicate components.
-- **Delete legacy variants after migration** — don't leave dead paths (this paradigm removed `Input variant='chip'` and `ChipMultiSelect`).
-- **Verify CSS vars exist.** An undefined var resolves to `currentColor` (caused a real black-border bug). Align to the canonical tokens: normal weight, `--text-body`, `--text-icon`.
+- **Delete legacy variants after migration** — leave no dead paths.
+- **Verify CSS vars exist.** An undefined var resolves to `currentColor`, which draws black borders. Align to the canonical tokens: normal weight, `--text-body`, `--text-icon`.
 - Use Radix UI primitives for accessibility. Export the component and its `variants` (when using CVA). Document with TSDoc + a usage example.
 
 Color tokens and icon-size conventions are canonical in `.claude/rules/sim-styling.md` — follow it rather than restating.
diff --git a/.claude/rules/sim-architecture.md b/.claude/rules/sim-architecture.md
index 038fa16272e..a765e891765 100644
--- a/.claude/rules/sim-architecture.md
+++ b/.claude/rules/sim-architecture.md
@@ -10,7 +10,7 @@ Repository layout, package boundaries, the application operation boundary, namin
 
 ## The `'use client'` server boundary
 
-Every export of a `'use client'` module becomes a *client reference* on the server — server-evaluated code (RSC pages/layouts, `prefetch.ts`, route handlers, block definitions, triggers) can only *render* it as a component or pass it as a prop, never *call* it (doing so throws at runtime, e.g. `tableKeys.list is not a function`; `next build` does not catch it). Keep server-importable query primitives (key factories, fetchers, mappers, constants) in non-`'use client'` modules — see `.claude/rules/sim-queries.md`. Enforced by `scripts/check-client-boundary-imports.ts`.
+Server-evaluated code (RSC pages/layouts, `prefetch.ts`, route handlers, block definitions, triggers) can render an export of a `'use client'` module but never call it; the call throws at runtime and `next build` does not catch it. Keep anything a server module calls (key factories, fetchers, mappers, constants) in a non-`'use client'` module. Detail and the escape hatch: `.claude/rules/sim-queries.md`. Enforced by `bun run check:client-boundary`.
 
 ## The app/worker runtime boundary
 
diff --git a/.claude/rules/sim-components.md b/.claude/rules/sim-components.md
index 6c6179b2ef2..1c59df5be25 100644
--- a/.claude/rules/sim-components.md
+++ b/.claude/rules/sim-components.md
@@ -32,8 +32,7 @@ export function Component({ requiredProp, optionalProp = false }: ComponentProps
 
 When rendering or sorting a list of rows against a lookup collection (members, folders, tags), keep the per-row work O(1):
 
-- **Precompute a lookup `Map` once**, never `array.find(...)` per row. Build `const byId = useMemo(() => { const m = new Map<string, T>(); for (const x of items ?? []) m.set(x.id, x); return m }, [items])` and read `byId.get(id)` in the sort comparator, `.map(...)`, and cell builders. A `.find` inside a sort comparator is O(n²·log n) — the worst offender. Depend memos on the derived `Map`, not the raw array.
-- **Sort a copy with `[...array].sort(cmp)`**, never `toSorted` (`check:utils` bans it repo-wide) — see `sim-react-performance.md` → "Never mutate a shared array in place".
+- **Precompute a lookup `Map` once** (`useMemo` over the collection) and read `byId.get(id)` in the sort comparator, `.map(...)`, and cell builders. A `.find` inside a sort comparator is O(n²·log n). Depend downstream memos on the derived `Map`, not the raw array. Map-building and copy-then-sort rules: `sim-react-performance.md`.
 - **Partition in a single pass** — when splitting one collection into several (`fileIds`/`folderIds`), do one `for…of` pushing into each bucket and return `{ a, b }` from a single `useMemo`, not two memos that each `map→filter→map` the same source twice.
 
 ## react-doctor (`bunx react-doctor`) — apply the wins, skip the false positives
@@ -41,7 +40,7 @@ When rendering or sorting a list of rows against a lookup collection (members, f
 react-doctor diagnostics are hypotheses, not verdicts — confirm against the code before acting, and preserve behavior. Known repo-specific false positives to NOT "fix":
 
 - `no-barrel-import` — barrel imports are the repo convention (see sim-imports.md, "Barrel Exports"). Keep them.
-- `js-tosorted-immutable` — won't-fix anywhere; `check:utils` bans the ES2023 array methods repo-wide.
+- `js-tosorted-immutable` — won't-fix in `'use client'` code (see "List-render performance" above); apply it only in server-only modules.
 - `rerender-state-only-in-handlers` / "state set but never rendered" — a false positive when the `useState` is consumed by a `useEffect`/`useLayoutEffect` dependency (the effect must re-run on change). Only convert to a ref when nothing reads the value reactively.
 - `no-render-in-render` — a helper *called inline* (`{renderRow()}`) is reconciled by position and does **not** remount, so extracting it to a component is usually pure churn and can regress behavior (prop-drilling many closures, focus/scroll loss on the inner `<input>`). Apply it only when the helper is genuinely a *component defined during render*, or when the move is mechanical (a stateless, ref-free helper whose closures become a small, explicit prop set).
 - `async-await-in-loop` on an upload/progress loop where sequential execution is intentional (per-item progress, server backpressure) — leave it.
diff --git a/.claude/rules/sim-list-ordering.md b/.claude/rules/sim-list-ordering.md
index 825a545e9d2..de9448635b8 100644
--- a/.claude/rules/sim-list-ordering.md
+++ b/.claude/rules/sim-list-ordering.md
@@ -10,8 +10,6 @@ paths:
 
 **A list orders itself the way the user already reads the same things somewhere else.** Dropdowns, context menus, tab strips, command palettes, and settings navs are all *second* presentations of a set the user has already seen — in a toolbar, in the settings nav, in a column-header row. When the second presentation reorders that set, the user re-reads it from scratch every time.
 
-This is not a style preference. Order is the cheapest affordance a list has, and the only one that costs nothing to get right.
-
 ## The rule
 
 Before writing a list of items, find where the user sees those same items *first*. That surface owns the order; your list mirrors it.
@@ -94,14 +92,10 @@ const hasDestructiveSection = (showLeave && onLeave) || showDelete
 {hasActionsAboveDestructive && hasDestructiveSection && <DropdownMenuSeparator />}
 ```
 
-This is the failure that put a dangling rule at the bottom of the logs row menu, where two
-unconditional separators sat above conditional items.
+Unconditional separators above conditional items leave a dangling rule at the bottom of the menu.
 
-**Do not add a prop to move a rule.** The shared workflow context menu grew
-`groupNonDestructiveActions` and `separateNavigationAction` for this; between them they moved one
-separator for one caller, four of six branches were unreachable, and `separateNavigationAction`
-had no observable effect anywhere in the repo. Both are gone. A menu that wants different
-grouping wants the standard grouping.
+**Never add a prop to move a rule.** Per-caller grouping props multiply unreachable branches; a
+menu that wants different grouping wants the standard grouping.
 
 ## Encode the order once
 
@@ -131,7 +125,7 @@ The most common way a canonical order gets silently defeated: emitting all items
 {groups.filter((g) => !FOLDERED.has(g.type)).map(renderFlat)}
 
 // ✓ Good — one ordered pass; each entry picks its own rendering
-{entries.sort(byResourceMenuOrder).map((entry) =>
+{[...entries].sort(byResourceMenuOrder).map((entry) =>
   sectionByType.has(entry.type) ? renderTree(entry) : renderFlat(entry)
 )}
 ```
diff --git a/.claude/rules/sim-queries.md b/.claude/rules/sim-queries.md
index da0900635ac..f09036b315c 100644
--- a/.claude/rules/sim-queries.md
+++ b/.claude/rules/sim-queries.md
@@ -140,7 +140,6 @@ const handler = useCallback(() => {
 // ✓ Good — omit from deps, mutate is stable
 const handler = useCallback(() => {
   createEntity.mutate(data)
-  // eslint-disable-next-line react-hooks/exhaustive-deps
 }, [data])
 ```
 
diff --git a/.claude/rules/sim-settings-pages.md b/.claude/rules/sim-settings-pages.md
index 3702dcf3097..429d07f4963 100644
--- a/.claude/rules/sim-settings-pages.md
+++ b/.claude/rules/sim-settings-pages.md
@@ -113,17 +113,9 @@ Adding a new settings page:
 
 ## Text-scale tokens (no literal pixel sizes)
 
-Settings pages never use a literal `text-[Npx]` class — always the named Tailwind
-scale token from the `@theme` block in `apps/sim/app/_styles/globals.css` (`text-micro`
-10px, `text-xs` 11px, `text-caption` 12px, `text-small` 13px, `text-sm` 14px
-[Tailwind default, unmodified], `text-base` 15px, `text-md` 16px, `text-lg` 18px
-[Tailwind default]). A literal size is either a straight rename to the equivalent
-token (if the pixel value matches one exactly) or a sign the page never migrated —
-grep `text-\[1[0-8]px\]` under `apps/sim/app/workspace/*/settings/**` and
-`apps/sim/ee/**` to find stragglers.
-
-Watch `text-xs`: it is 11px here, so a "caption" written as `text-xs` is a pixel
-short. See `sim-styling.md` for the full scale.
+Settings pages never use a literal `text-[Npx]` class — always a named token from
+the scale in `sim-styling.md` ("Text Scale"). Find stragglers with
+`rg 'text-\[1[0-8]px\]' apps/sim/app/workspace apps/sim/ee`.
 
 The two-line list row (title over a muted subtitle — a name + email, a tool name
 + description, a server name + status) is **not something you build**: it is
@@ -402,4 +394,4 @@ A settings page is design-system-clean when:
 - [ ] Decorative trailing content is in `badge`, not `trailing`.
 - [ ] Labeled sections use `SettingsSection`; read-only fields use `SettingsField`; empty/loading/error use `SettingsEmptyState`.
 - [ ] Delete is a plain `id:'delete'` header action behind a `ChipConfirmModal`; `destructive` is reserved for bulk actions.
-- [ ] `tsc`, `biome`, and the page's tests pass.
+- [ ] The local gate in the root `CLAUDE.md` ("How your work is checked") passes.
diff --git a/.claude/rules/sim-styling.md b/.claude/rules/sim-styling.md
index cf1024529bf..264fa106e37 100644
--- a/.claude/rules/sim-styling.md
+++ b/.claude/rules/sim-styling.md
@@ -15,8 +15,8 @@ paths:
 2. **No duplicate dark classes** - Skip `dark:` when value matches light mode
 3. **Exact values over approximations** - `h-[26px]`, not `h-6`. But **type size is
    always a named token** (`text-sm`, `text-caption`) — never `text-[14px]`, which
-   sets font-size only and inherits a different line-height. See
-   `sim-settings-pages.md` for the scale.
+   sets font-size only and inherits a different line-height. The scale is under
+   "Text Scale" below.
 4. **Transitions** - `transition-colors` for interactive states
 
 ## Conditional Classes
@@ -48,7 +48,7 @@ setWidth: (width) => {
 
 ## Text Scale
 
-Custom font sizes (the `@theme` block in `apps/sim/app/_styles/globals.css`): `text-micro`=10px, `text-xs`=11px, `text-caption`=12px, `text-small`=13px, `text-base`=15px. `text-sm` is Tailwind default 14px. Field titles use `text-small` (13px); hints/errors use `text-caption` (12px).
+The `@theme` block in `apps/sim/app/_styles/globals.css`: `text-micro` 10px, `text-xs` 11px, `text-caption` 12px, `text-small` 13px, `text-sm` 14px (Tailwind default), `text-base` 15px, `text-md` 16px, `text-lg` 18px (Tailwind default). `text-xs` is 11px here, so a caption written as `text-xs` is a pixel short. Field titles use `text-small`; hints/errors use `text-caption`. A literal `text-[Npx]` is either a rename to the matching token or an unmigrated straggler.
 
 Icons default `size-[14px]`. Equal h/w → `size-*` (`size-[14px]`, `size-4`), never `h-N w-N` or `h-[Npx] w-[Npx]`.
 
@@ -70,7 +70,7 @@ A scroll region that can hide rows past an edge uses `useScrollEdges` with `scro
 
 Three steps, Tailwind's stock scale, nothing else: **`font-normal` (400)**, **`font-medium` (500)**, **`font-semibold` (600)**. 400 is the document default, so body text, chip labels, sidebar items, and headings carry **no weight class at all** — they inherit. Reach for a class only to step *up* from body.
 
-Never write an arbitrary weight (`font-[380]`, `font-[430]`, `font-[450]`, …), and never set `fontWeight` in an inline `style`. There was previously a CSS-variable weight scale (`--font-weight-base/medium/semibold`, remapping `font-medium` to 440/480) plus seven ad-hoc values clustered between 380 and 500; it was deleted because nothing read as hierarchical. Off-scale values are only acceptable where the design system genuinely cannot reach — react-email templates and the static `apps/sim/emails/broadcasts/*.html`, which email clients render without CSS variables.
+Never write an arbitrary weight (`font-[380]`, `font-[450]`, …) or a `--font-weight-*` variable, and never set `fontWeight` in an inline `style`: values clustered between the three steps do not read as hierarchy. Off-scale values are acceptable only where the design system cannot reach — react-email templates and the static `apps/sim/emails/broadcasts/*.html`, which email clients render without CSS variables.
 
 Headings inherit their weight. Tailwind preflight resets `h1`–`h6` to `font-weight: inherit`, so an `<h1>` is 400 unless you say otherwise — that is the intended look, not a bug to patch.
 
@@ -95,19 +95,19 @@ Draw a line with a real `border-*` utility. Never hand-roll one as `shadow-[inse
 - **Errors** → `error` prop. Never `className={cn(err && 'border-[var(--text-error)]')}`.
 - **Leading icon** → `icon` prop (rendered 14px in `--text-icon`).
 - **Trailing buttons** (reveal/copy/fetch) → `endAdornment`.
-- **Inner-input styling** (e.g. `font-mono`, number-spinner reset) → `inputClassName` (ChipInput only). See `app/workspace/[workspaceId]/settings/components/billing/components/usage-limit-field/usage-limit-field.tsx:117`.
-- **`ChipModalField` controls take NO className.** Pass `title`/`value`/`onChange`/`error`/`hint`/`required`/`flush`. The field owns label, control, and error/hint rendering. See `app/workspace/[workspaceId]/skills/components/skill-modal/skill-modal.tsx:170`.
+- **Inner-input styling** (e.g. `font-mono`, number-spinner reset) → `inputClassName` (ChipInput only). See `app/workspace/[workspaceId]/settings/components/billing/components/usage-limit-field/usage-limit-field.tsx`.
+- **`ChipModalField` controls take NO className.** Pass `title`/`value`/`onChange`/`error`/`hint`/`required`/`flush`. The field owns label, control, and error/hint rendering. See `app/workspace/[workspaceId]/skills/components/skill-modal/skill-modal.tsx`.
 
 ### What className MAY carry
 
-Layout/sizing ONLY: `flex-1`, `w-full`, `w-[Npx]`, `min-w-0`, `max-w-*`, margins. `truncate` is allowed only for the explicit overflow exceptions above, never as a general layout class. Example: `<ChipInput icon={Search} className='min-w-0 flex-1' .../>` (`app/workspace/[workspaceId]/integrations/integrations.tsx:257`). NEVER re-specify canonical chrome — the component already applies it.
+Layout/sizing ONLY: `flex-1`, `w-full`, `w-[Npx]`, `min-w-0`, `max-w-*`, margins. `truncate` is allowed only for the explicit overflow exceptions above, never as a general layout class. Example: `<ChipInput icon={Search} className='min-w-0 flex-1' .../>` (`app/workspace/[workspaceId]/integrations/integrations.tsx`). NEVER re-specify canonical chrome — the component already applies it.
 
 ### Form / chip-modal layout rhythm
 
 - **Field row** = `ChipModalField`: label↔control `gap-[9px]`, field gutter `px-2` (`px-0` when `flush`). Title = `Label` at `text-small` (13px), muted, normal weight; hint/error at `text-caption` (12px).
 - **Modal body** (`ChipModalBody`): `gap-4` between fields, padding `px-2 pt-4 pb-4.5`.
 - **Header/footer**: horizontal gutter `px-4` (header `pt-3`; footer `px-4 pt-2 pb-2`, tinted bar).
-- **Every body field MUST be a `ChipModalField`** — NEVER hand-roll a field row (raw `<div>` + hand-rolled `<p>`/`<label>` title + bare `ChipInput`/`ChipTextarea`). WHY: body `px-2` + field `px-2` = effective `px-4`, exactly matching the `px-4` header/footer. A hand-rolled row skips the field gutter, sits at `px-2`, and is visibly misaligned (this bug shipped in the scheduled-tasks "Create new scheduled task" modal). Inline errors go through the `error` prop, not a hand-rolled `<p>`.
+- **Every body field MUST be a `ChipModalField`** — NEVER hand-roll a field row (raw `<div>` + hand-rolled `<p>`/`<label>` title + bare `ChipInput`/`ChipTextarea`). WHY: body `px-2` + field `px-2` = effective `px-4`, exactly matching the `px-4` header/footer. A hand-rolled row skips the field gutter, sits at `px-2`, and is visibly misaligned. Inline errors go through the `error` prop, not a hand-rolled `<p>`.
 - **Uncovered controls** (`ChipCombobox`, `ChipSelect`, `DatePicker`, `TimePicker`, `ButtonGroup`, arbitrary JSX) → `ChipModalField type='custom'` with a `title`. It still applies the `px-2` gutter and renders the canonical `Label`, so it stays aligned. Never drop such a control into a raw `<div>`, and never add a body-level wrapper `<div>` with a custom `gap-*` that fights `gap-4`.
 - **Page section rhythm** (integrations/skills/settings): muted `text-small` label + `mt-[9px] mb-3 h-px bg-[var(--border)]` divider, sections stacked `gap-7`. Reuse `SettingsSection` (`app/workspace/[workspaceId]/settings/components/settings-section/settings-section.tsx`) rather than re-deriving it.
 
diff --git a/.claude/rules/sim-testing.md b/.claude/rules/sim-testing.md
index 13a84169a95..d19efd158fe 100644
--- a/.claude/rules/sim-testing.md
+++ b/.claude/rules/sim-testing.md
@@ -9,10 +9,9 @@ paths:
 
 # Testing
 
-Before writing or changing any test, run the `test-audit` skill's authoring gate. The short
-version: never write unit tests after the code; prefer E2E tests at the real boundary and end
-them with a verifiable artifact; if you must test in isolation, write the failure modes down
-first. A test that cannot name the bug it catches does not get written.
+The testing principles are in the root `CLAUDE.md` → Testing. Before writing or changing any test,
+run the `test-audit` skill's authoring gate: a test that cannot name the bug it catches does not
+get written.
 
 ## Layers
 
@@ -27,9 +26,7 @@ What already catches bugs, in the order to reach for it:
 
 A unit test is justified only for a failure the layers above cannot see: security boundaries,
 billing math, executor semantics, parsers and algorithms with edge cases, cross-process wire
-contracts, and demonstrated regressions. Never restate declarations (block/tool/provider config,
-registries, constants, schemas accepting valid input), assert that mocks were called, check
-rendered text or class names, or test mocks and factories themselves.
+contracts, and demonstrated regressions.
 
 ## Naming
 
diff --git a/.claude/rules/sim-url-state.md b/.claude/rules/sim-url-state.md
index 6b0d29b9d28..fb93787f16e 100644
--- a/.claude/rules/sim-url-state.md
+++ b/.claude/rules/sim-url-state.md
@@ -14,16 +14,7 @@ URL query state is managed with [`nuqs`](https://nuqs.dev). The `NuqsAdapter` is
 
 ## Decision framework — where does this state live?
 
-Pick exactly one home for each piece of state:
-
-- **React Query** → server/remote data. Unchanged; see `.claude/rules/sim-queries.md`.
-- **URL params (nuqs)** → client view-state worth putting in a link: active tab/panel, selected entity id, filters, search query, pagination, view mode (list/grid), an open "view" drawer/modal that represents a destination.
-- **Zustand** → cross-component client state that must NOT be in the URL: high-frequency, large, ephemeral, or socket-synced (canvas pan/zoom, cursor, drag state, resize widths, unsaved buffers, live collaborative selection).
-- **`useState`** → purely local, single-component UI.
-
-Put state in the URL **only** when it is *all* of: shareable, deep-linkable, bookmarkable, survives reload + back/forward — **and** is discrete, low-frequency, and small. If it fails any of those, it does not go in the URL.
-
-### When to use what (decision table)
+Pick exactly one home for each piece of state (table below). Put state in the URL **only** when it is *all* of: shareable, deep-linkable, bookmarkable, survives reload + back/forward — **and** is discrete, low-frequency, and small. If it fails any of those, it does not go in the URL.
 
 | Home | Trigger | Example |
 | --- | --- | --- |
diff --git a/CLAUDE.md b/CLAUDE.md
index 815c747b91c..52ef363d923 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,14 +1,12 @@
 # Sim Development Guidelines
 
-You are a professional software engineer. All code must follow best practices: accurate, readable, clean, and efficient.
-
 This file (also `AGENTS.md`) holds the repo-wide rules. Area detail lives in `.claude/rules/*.md` (indexed in `apps/sim/AGENTS.md`): Claude loads each one by path, and any other agent reads the file a section points to before editing in that area. Skills live in `.agents/skills/`.
 
 ## Global Standards
 
 - **Package manager**: `bun` and `bunx`, never `npm` and `npx`.
 - **Logging**: `createLogger` from `@sim/logger`; `logger.info` / `logger.warn` / `logger.error`, never `console.log`. Inside `withRouteHandler` the logger already carries the request ID — no manual `withMetadata({ requestId })`.
-- **Comments**: TSDoc for documentation. An inline `//` only for a terse, non-obvious why, or for a script-enforced `// <tag>: <reason>` annotation (`boundary-raw-fetch`, `double-cast-allowed`, `boundary-raw-json`, `untyped-response`, `rq-lint-allow`, `client-boundary-allow`, …). No `====` separators.
+- **Comments**: name things so the code explains itself. TSDoc documents exported APIs and non-obvious modules. An inline `//` is only for a terse, non-obvious *why*, or for a script-enforced `// <tag>: <reason>` annotation (`boundary-raw-fetch`, `double-cast-allowed`, `boundary-raw-json`, `untyped-response`, `rq-lint-allow`, `client-boundary-allow`, `utils-lint-allow`, …). A comment never narrates what the next line does, restates a name or type, or records change history ("moved from X", "previously", "now uses Y") — history belongs in the commit message. No `====` separators. The `/you-might-not-need-a-comment` skill applies this to a diff.
 - **ID generation**: `generateId()` (UUID v4, the default) or `generateShortId(size?)` (URL-safe, 21 chars by default) from `@sim/utils/id` — never `crypto.randomUUID()`, `nanoid`, or `uuid`. Both use `crypto.getRandomValues()`, so they also work in non-secure (HTTP) browsers.
 - **Common utilities**: use the shared helpers from `@sim/utils` instead of inline implementations (`check:utils` bans most of the inline forms below):
   - `sleep(ms)` from `@sim/utils/helpers` — never `new Promise(resolve => setTimeout(resolve, ms))`
@@ -24,8 +22,7 @@ This file (also `AGENTS.md`) holds the repo-wide rules. Area detail lives in `.c
   - `compareStrings(left, right)` from `@sim/utils/string` — code-unit ordering for hashes, fingerprints, and cross-process comparisons; never `localeCompare` there
   - `backoffWithJitter(attempt, retryAfterMs, options?)` / `parseRetryAfter(header)` from `@sim/utils/retry` — never reimplement exponential backoff inline
 - **Deployment flags in the browser**: client code inside a workspace, organization, or standalone settings surface reads `hosted`, `billingEnabled`, `chatEnabled`, and the enterprise feature set through `useDeploymentShape()` (components) or `getDeploymentShape()` (block conditions, stores, helpers) from `@/lib/core/config/deployment-shape`, never `isHosted`/`isBillingEnabled`/... from `env-flags`. Those constants freeze at module init from the root layout's `NEXT_PUBLIC_*` transport, which Next's bare 404 shell and `global-error` never emit, so a recovered tab would render Sim Cloud as self-hosted; the reader is seeded from the server-resolved workspace host context, organization layout, or standalone settings layout instead. Server code keeps reading `env-flags`.
-- **Type-checking**: `bun run type-check` (per workspace) or `bunx turbo run type-check` (all). Never remove the `@typescript/native` alias from the root `devDependencies`. Nothing imports it; it exists so a bare `tsc` resolves to the native TypeScript 7 compiler. `apps/sim` needs `@typescript/typescript6`, whose `@typescript/old` dependency (an alias of `typescript@6`) ships its own `tsc` bin, and bin winners are picked by lexical sort, so without the alias `tsc` silently becomes the ~10x slower JavaScript compiler. `bun run check:native-typecheck` enforces this, and also fails when a newly added dependency that sorts ahead of `@typescript/native` ships a `tsc` bin ([microsoft/typescript-go#4567](https://github.com/microsoft/typescript-go/issues/4567)).
-- **Checks**: `bun run lint` autofixes formatting; `bun run check:audits` runs every `check:*` audit CI enforces.
+- **Type-checking**: `bun run type-check` at the root checks every workspace (`bun run type-check` inside a workspace checks just that one). Never remove the `@typescript/native` alias from the root `devDependencies`: nothing imports it, but without it a bare `tsc` resolves to the ~10x slower TypeScript 6 compiler. `bun run check:native-typecheck` enforces this; its header explains the bin-resolution trap.
 
 ## Architecture
 
@@ -137,3 +134,38 @@ Remaining block/tool/trigger rules: `.claude/rules/sim-integrations.md`. Canvas
 Table column types are registry entries in `apps/sim/lib/table/column-types/` — one file per type owning its label, icon, storage cast, coercion, validation, conversion compatibility, formatting, and editor. `Record<ColumnType, …>` on `registry.ts` and `registry.server.ts` is a compile-time completeness gate: adding a type to the union errors until both entries exist.
 
 Never add a `case 'sometype':` outside `column-types/` — a missing arm fails silently (a wrong `jsonbCast` breaks every filter on the column). If a consumer needs per-type knowledge, add a registry field. Use `/add-column-type` for the full procedure.
+
+## How your work is checked
+
+Before declaring a change done, run the local gate from the repo root; CI runs the same commands and fails on any of them:
+
+```bash
+bun run lint            # biome format + lint, autofixes (CI runs lint:check)
+bun run type-check      # every workspace
+bun run check:audits    # every check:* audit plus the generated-artifact checks
+bun run test            # script tests, then every workspace's Vitest suite
+```
+
+A diff that touches `packages/db/migrations/**` also runs `bun run check:migrations origin/staging` (it needs a base ref, so it is not in `check:audits`). When an audit fails, its output and its script's header say what the rule protects; fix the code, never the check. Ratchet baselines (`scripts/*.baseline.json`) only shrink: regenerate one with the script's `--update`/`--write` flag after removing violations, never to admit new ones.
+
+| Written rule | Enforced by |
+| --- | --- |
+| Formatting, lint, no `nanoid`/`uuid` imports | `bun run lint` (biome) |
+| `@sim/utils` over inline idioms (`Math.random`, `crypto.randomUUID`, `JSON` clone, `instanceof Error` message, `setTimeout` sleep) | `check:utils` |
+| `apps → packages` only; realtime import bans | `check:boundaries`, `check:realtime-prune` |
+| Route contracts, no `zod` in routes or clients, `requestJson`, boundary annotations | `check:api-validation:strict`, `check:api-contract-routes`, `check:route-verbs` |
+| Application authorization funnel stays light; principal and capability policy | `check:application-graph`, `check:principal-kind-parity`, `check:capability-subject`, `check:actorless-executor-operations`, `check:permission-group-enforcement` |
+| `'use client'` server boundary | `check:client-boundary` |
+| React Query keys, `staleTime`, `signal` | `check:react-query` |
+| Zustand v5 selector stability | `check:zustand-v5` |
+| Tool registry out of client and prefetch graphs | `check:tool-registry-boundary` |
+| Outbound HTTP through the egress guard; tool request boundary | `check:egress-boundary`, `check:tool-request-boundary` |
+| Imports resolve under Turbopack; no `@/triggers` → `@/blocks` cycle | `check:import-specifiers`, `check:trigger-block-cycle` |
+| Canvas sentences, BYOK wiring, fork-dependent subblocks, reachable tool params | `check:canvas-sentences`, `check:byok-providers`, `check:fork-dependent-coverage`, `check:tool-param-reachability` |
+| Central mocks, colocated tests, script tests collected | `check:test-patterns`, `check:script-tests` |
+| Zero-downtime migrations | `check:migrations <base>` |
+| Unused files, exports, dependencies | `check:dead-code` (knip) |
+| Skills and rules projections in sync; guidance references resolve | `check:skills`, `check:guidance-refs` |
+| Generated artifacts fresh (tool metadata, docs, catalog, CLI/MCP/OpenAPI surfaces) | the `*:check` entries in `check:audits` |
+
+Rules not in this table (logging, comments, naming, imports, styling, state ownership, caching) are enforced by review only; follow them as written.

From 8f26f89cdb2884cfd27e9222a078f066401b5dde Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Thu, 1 Oct 2026 17:15:58 -0700
Subject: [PATCH 05/18] docs(agents): fix stale facts in connector, model,
 column-type, and selector skills

Verified against the code: fetchWithRetry moved to secure-fetch.server,
deletion reconciliation is checkpoint.unsafe (shouldReconcileDeletions is
gone), the legacy Search toggle is removed, inline-content connectors may
hash content, reasoningEffort/thinking provider lists, column-type metadata
update path, check:api-validation:strict as the gate. CLAUDE.md now names
the coerceValue switch and relative barrel re-exports as the documented
exceptions the code relies on. Selector rules in connector skills point at
validate-selector instead of restating it.
---
 .agents/skills/add-block-preview/SKILL.md  |  2 +-
 .agents/skills/add-column-type/SKILL.md    | 16 +++----
 .agents/skills/add-connector/SKILL.md      | 38 +++++++---------
 .agents/skills/add-enrichment/SKILL.md     |  4 +-
 .agents/skills/add-managed-cli/SKILL.md    |  4 +-
 .agents/skills/add-model/SKILL.md          |  6 ++-
 .agents/skills/add-selector/SKILL.md       |  6 +--
 .agents/skills/validate-connector/SKILL.md | 50 +++-------------------
 .agents/skills/validate-model/SKILL.md     |  4 +-
 .agents/skills/validate-selector/SKILL.md  |  9 ++--
 .claude/rules/sim-imports.md               |  2 +-
 .cursor/rules/sim-imports.mdc              |  2 +-
 CLAUDE.md                                  |  4 +-
 13 files changed, 52 insertions(+), 95 deletions(-)

diff --git a/.agents/skills/add-block-preview/SKILL.md b/.agents/skills/add-block-preview/SKILL.md
index c583a54c2cf..c3633e8dbc6 100644
--- a/.agents/skills/add-block-preview/SKILL.md
+++ b/.agents/skills/add-block-preview/SKILL.md
@@ -53,7 +53,7 @@ To pull an already-GA block from discovery surfaces on hosted (incident, depreca
 - **Clone-not-remove:** gated blocks stay in `getAllBlocks()` output as clones with `hideFromToolbar: true` — `.find`-by-type consumers rely on this. Never filter them out.
 - **Keys are registry block types.** Never `custom_block_*` (parse drops them — custom blocks have their own enabled/disabled lifecycle).
 - **The shared hidden-predicate is `isHiddenUnder`** (`apps/sim/blocks/visibility/context.ts`). Never restate the preview/disabled rule inline at a new consumer.
-- **Process-global caches stay ungated.** `getStaticComponentFiles` (VFS) and `getExposedIntegrationTools` build the ungated universe; per-viewer filtering happens at stamp/consumer time. Never move gating into a shared builder.
+- **Process-global caches stay ungated.** Shared builders such as `getExposedIntegrationTools` (`lib/integrations/tool-catalog.ts`) build the ungated universe; per-viewer filtering happens at consumer time via `isHiddenUnder`. Never move gating into a shared builder.
 - Gating is **surface hiding, not secrecy** — the full config ships in the client JS bundle. Anything truly secret cannot be a registered block.
 
 ## Tests
diff --git a/.agents/skills/add-column-type/SKILL.md b/.agents/skills/add-column-type/SKILL.md
index 1ac05a8c9ec..6a222a83bfc 100644
--- a/.agents/skills/add-column-type/SKILL.md
+++ b/.agents/skills/add-column-type/SKILL.md
@@ -12,7 +12,7 @@ A `case 'yourtype':` outside `column-types/` fails **silently** when missed (a w
 
 ## Hard Rule: the compiler tells you what to do
 
-Do **not** hunt for places to edit. Add your type to the `ColumnType` union first and let `tsc` produce the list:
+Do **not** hunt for places to edit. Append your type's id to the `COLUMN_TYPES` array in `column-types/types.ts` first (`ColumnType` derives from it) and let `tsc` produce the list:
 
 ```bash
 cd apps/sim && bun run type-check
@@ -86,7 +86,7 @@ export function Type{Pascal}(props: SVGProps<SVGSVGElement>) {
 
 ## Step 3: Write the type file
 
-`apps/sim/lib/table/column-types/{name}.ts`. Copy the closest existing type and change what differs. Every field is required by the interface, so the compiler enumerates them for you — read the TSDoc in `types.ts` rather than guessing.
+`apps/sim/lib/table/column-types/{name}.ts`. Copy the closest existing type and change what differs. Required fields are compiler-enforced; optional hooks (`isCompatibleWith`, `salvage`, `valueForEquality`, `filterOperatorsFor`, …) default sensibly — read the TSDoc in `types.ts` before overriding.
 
 The three that are easy to get wrong:
 
@@ -132,18 +132,18 @@ Registering the *type* is compiler-enforced. Registering its *metadata* is not,
 | `column-types/types.ts` `TYPE_SPECIFIC_COLUMN_KEYS` | it is never stripped on conversion, and poisons the target type |
 | `lib/api/contracts/tables.ts` — the schema slot in all three column schemas, plus `refineColumnOptions` | zod strips it at the boundary; silently never saved |
 | `columns/service.ts` `addTableColumn` param type | callers cannot pass it |
-| A metadata-only update path (`updateColumnCurrency` is the model) + a branch in both column routes + the copilot tool | changing it on an existing column is a silent 200 no-op |
+| A metadata-only update in `lib/table/columns/service.ts` (`updateColumnCurrency` is the model) + a branch in `updateColumn` in `lib/table/orchestration/columns.ts` | changing it on an existing column is a silent 200 no-op |
 | `column-config-sidebar.tsx` | no UI to set it |
 | `table-grid.tsx` delete-column undo + `use-table-undo.ts` restore | undo silently resets it to the default |
 
 `normalizeColumn`, `buildConvertedColumn`, and the undo snapshot read `TYPE_SPECIFIC_COLUMN_KEYS` generically, so those three are already zero-edit.
 
-**Known gap:** the metadata-only update path is ~6 near-identical copies (service + 2 routes + copilot). A `metadataUpdate` descriptor on `ColumnTypeServerDefinition` would collapse them; until that exists, copy `currency`'s.
+Copy `currency`'s service function and orchestration branch.
 
 ## Checklist Before Finishing
 
-- [ ] Added to the `ColumnType` union in `column-types/types.ts`
-- [ ] `column-types/{id}.ts` created, every interface field filled in
+- [ ] Id appended to `COLUMN_TYPES` in `column-types/types.ts`
+- [ ] `column-types/{id}.ts` created, every required field filled in
 - [ ] Registered in **both** `registry.ts` and `registry.server.ts`
 - [ ] Icon added, centered on the family's optical center, exported alphabetically
 - [ ] `migrateCellsTo` / `migrateCellsFrom` added if the stored bytes change
@@ -155,6 +155,6 @@ Registering the *type* is compiler-enforced. Registering its *metadata* is not,
 
 1. **`cd apps/sim && bun run type-check`** — must be clean. If any file *outside* `column-types/` errors, that file has a hardcoded type list; fix it to read the registry.
 2. **Grep for leaks** — `grep -rnE "(===|!==) '{id}'|case '{id}':" apps/sim --include='*.ts' --include='*.tsx' | grep -v column-types/`. (All three forms: a plain `!==` and a `case` are how half of `currency`'s real branches are written.) Hits are expected; judge each. A hit is fine when it mounts a specific React component or encodes a genuinely one-off behavior (`json`'s mono textarea, `date`'s timezone-aware parsing). A hit is a **leak** when it restates something the registry could answer — an icon, a label, a colour, an operator set, a cast, a coercion. Leaks get a registry field, not a new branch.
-3. **Run the suite** — `bun run --cwd apps/sim test lib/table 'app/workspace/[workspaceId]/tables' lib/api app/api/table app/api/v1 lib/copilot/tools/server/table`. Existing tests must pass **unchanged**; needing to edit one means you changed behavior for the other types.
-4. **`bun run lint`, `bun run check:api-validation`, `bun run check:client-boundary`** from the repo root.
+3. **Run the suite** — `bun run --cwd apps/sim test lib/table 'app/workspace/[workspaceId]/tables' lib/api app/api/table app/api/v1`. Existing tests must pass **unchanged**; needing to edit one means you changed behavior for the other types.
+4. **`bun run lint`, `bun run check:api-validation:strict`, `bun run check:client-boundary`** from the repo root.
 5. **Exercise it in the running app** on a table with one column of every type: create, edit inline / in the expanded popover / in the row modal, paste from a spreadsheet, filter, sort, convert to and from other types, export CSV, undo a column delete.
diff --git a/.agents/skills/add-connector/SKILL.md b/.agents/skills/add-connector/SKILL.md
index c3ca20556a0..0f435345d98 100644
--- a/.agents/skills/add-connector/SKILL.md
+++ b/.agents/skills/add-connector/SKILL.md
@@ -10,7 +10,7 @@ argument-hint: <service-name> [api-docs-url]
 
 For **Sim Search**, use the live provider workflow in [the federated Search developer guide](../../../apps/sim/lib/sim-search/live/README.md#adding-a-live-search-connector). Its browser-safe provider catalog owns provider IDs, API origins, credential aliases, and account modes; its typed runtime registry requires both search and read handlers. `ConnectorMeta` remains the owner of logos and setup fields. Member mode has no admin resource filters. Service mode requires independent live source verification; resource pickers use shared selectors with canonical manual-input pairs, and plain inputs are fine where no picker applies. Do not implement a Search source by adding a crawler, embeddings, or a scheduled ACL build.
 
-The ingestion instructions below apply to **ordinary knowledge-base connectors** and the explicit legacy Search backend (`SIM_SEARCH_LIVE=false`). If a provider supports both, implement and test both runtimes; adding `search: true` to metadata alone does not implement federated search. Preserve indexing documentation and behavior for those KB/legacy callers.
+The ingestion instructions below apply to **ordinary knowledge-base connectors**. Sim Search always uses the live backend, so setting `search: true` in metadata does not implement federated search; a provider that serves both needs the live handlers and this KB ingestion path.
 
 You are an expert at adding knowledge base connectors to Sim. A connector syncs documents from an external source (Confluence, Google Drive, Notion, etc.) into a knowledge base.
 
@@ -56,11 +56,7 @@ connectors/{service}/
 
 Connectors use a discriminated union for auth config (`ConnectorAuthConfig` in `connectors/types.ts`):
 
-```typescript
-type ConnectorAuthConfig =
-  | { mode: 'oauth'; provider: OAuthService; requiredScopes?: string[] }
-  | { mode: 'apiKey'; label?: string; placeholder?: string }
-```
+See `ConnectorAuthConfig` in `apps/sim/connectors/types.ts`: `oauth` takes `provider`, `requiredScopes`, and optional service-account/admin scopes; `apiKey` takes `label`, `placeholder`, and `optional`.
 
 ### OAuth mode
 For services with existing OAuth providers in `apps/sim/lib/oauth/types.ts`. The `provider` must match an `OAuthService`. The modal shows a credential picker and handles token refresh automatically.
@@ -107,7 +103,7 @@ Keep `meta.ts` free of any server/runtime import. Only the icon, the `ConnectorM
 
 ```typescript
 import { createLogger } from '@sim/logger'
-import { fetchWithRetry } from '@/lib/knowledge/documents/utils'
+import { fetchWithRetry } from '@/lib/knowledge/documents/secure-fetch.server'
 import { {service}ConnectorMeta } from '@/connectors/{service}/meta'
 import type { ConnectorConfig, ExternalDocument, ExternalDocumentList } from '@/connectors/types'
 
@@ -218,7 +214,7 @@ The user sees a toggle button (ArrowLeftRight) to switch between the selector dr
 
 1. **Every selector field MUST have a canonical pair** — a corresponding `short-input` (or `dropdown`) field with the same `canonicalParamId` and `mode: 'advanced'`.
 2. **`required` must be set identically on both fields** in a pair. If the selector is required, the manual input must also be required.
-3. **`canonicalParamId` must match the key the connector expects in `sourceConfig`** (e.g. `baseId`, `channel`, `teamId`). The advanced field's `id` should typically match `canonicalParamId`.
+3. **`canonicalParamId` must match the key the connector expects in `sourceConfig`** (e.g. `baseId`, `channel`, `teamId`). The advanced field's `id` should typically match `canonicalParamId` (connector config fields differ from block subBlocks here; the block rule that `canonicalParamId` must not equal a subblock id does not apply).
 4. **`dependsOn` references the selector field's `id`**, not the `canonicalParamId`. The modal propagates dependency clearing across canonical siblings automatically — changing either field in a parent pair clears dependent children.
 
 ### Selector canonical pair example (Airtable base → table cascade)
@@ -350,7 +346,7 @@ Every document returned from `listDocuments`/`getDocument` must include:
   title: string               // Document title
   content: string             // Extracted plain text (or '' if contentDeferred)
   contentDeferred?: boolean   // true = content will be fetched via getDocument
-  mimeType: 'text/plain'     // Always text/plain (content is extracted)
+  mimeType: 'text/plain'     // extracted text; for a format the KB pipeline parses (PDF, Office), set `sourceFile` instead
   contentHash: string         // Metadata-based hash for change detection
   sourceUrl?: string          // Link back to original (stored on document record)
   metadata?: Record<string, unknown>  // Source-specific data (fed to mapTags)
@@ -376,7 +372,7 @@ This pattern is critical for reliability: the sync engine processes documents in
 
 ### Content Hash Strategy
 
-Use a **metadata-based** `contentHash` — never a content-based hash. The hash must be derivable from the list response metadata alone, so the sync engine can detect changes without downloading content.
+Deferred-content connectors (`contentDeferred: true`) must use a **metadata-based** `contentHash` derivable from the list response alone, so the sync engine can detect changes without downloading content. Inline-content connectors may hash the content they already hold (`computeContentHash`).
 
 Good metadata hash sources:
 - `modifiedTime` / `lastModifiedDateTime` — changes when file is edited
@@ -519,12 +515,13 @@ mapTags: (metadata: Record<string, unknown>): Record<string, unknown> => {
 
 ## External API Calls — Use `fetchWithRetry`
 
-All external API calls must use `fetchWithRetry` from `@/lib/knowledge/documents/utils` instead of raw `fetch()`. This provides exponential backoff with retries on 429/502/503/504 errors. It returns a standard `Response` — all `.ok`, `.json()`, `.text()` checks work unchanged.
+All external API calls must use `fetchWithRetry` from `@/lib/knowledge/documents/secure-fetch.server` (SSRF-guarded) instead of raw `fetch()`; use `secureFetchWithRetry` for user-controlled hosts. This provides exponential backoff with retries on 429/502/503/504 errors. It returns a standard `Response` — all `.ok`, `.json()`, `.text()` checks work unchanged.
 
-For `validateConfig` (user-facing, called on save), pass `VALIDATE_RETRY_OPTIONS` to cap wait time at ~7s. Background operations (`listDocuments`, `getDocument`) use the built-in defaults (5 retries, ~31s max).
+For `validateConfig` (user-facing, called on save), pass `VALIDATE_RETRY_OPTIONS` to cap wait time at ~7s. Background operations (`listDocuments`, `getDocument`) use the built-in defaults (5 retries within a 150s budget).
 
 ```typescript
-import { VALIDATE_RETRY_OPTIONS, fetchWithRetry } from '@/lib/knowledge/documents/utils'
+import { fetchWithRetry } from '@/lib/knowledge/documents/secure-fetch.server'
+import { VALIDATE_RETRY_OPTIONS } from '@/lib/knowledge/documents/utils'
 
 // Background sync — use defaults
 const response = await fetchWithRetry(url, {
@@ -544,7 +541,7 @@ If `ExternalDocument.sourceUrl` is set, the sync engine stores it on the documen
 
 If `listDocuments` can ever return **less than the full source set** on a non-incremental sync — a `maxItems`/`maxDocuments`-style cap, or a transient per-item error that drops a still-existing document from the listing — it MUST set `syncContext.listingCapped = true` when that happens.
 
-The sync engine reconciles deletions by comparing the full listing against stored documents (`shouldReconcileDeletions` in `lib/knowledge/connectors/sync-engine.ts`, gated on `!syncContext?.listingCapped`). Anything not seen is tombstoned on that sync and hard-deleted when the next sync still does not see it — so a truncated listing without this flag eventually removes every real document beyond the cap.
+The engine reconciles deletions only when the listing is marked safe (`checkpoint.unsafe` in `lib/knowledge/connectors/listing-checkpoint.ts`): `syncContext.listingCapped`, `ExternalDocumentList.reconciliationSafe: false` (required for offset/unstable pagination), or a non-null `listingFailures` marks it unsafe. Anything absent from a safe listing is tombstoned on that sync and hard-deleted when the next sync still does not see it — so a truncated listing without this flag eventually removes every real document beyond the cap.
 
 ```typescript
 if (hitLimit && syncContext) {
@@ -564,14 +561,14 @@ The sync engine (`lib/knowledge/connectors/sync-engine.ts`) is connector-agnosti
 1. Calls `listDocuments` with pagination until `hasMore` is false
 2. Compares `contentHash` to detect new/changed/unchanged documents
 3. Stores `sourceUrl` and calls `mapTags` on insert/update automatically
-4. Handles soft-delete of removed documents
+4. Tombstones documents absent from a reconciliation-safe listing and hard-deletes them when the next safe listing still omits them
 5. Resolves access tokens automatically — OAuth tokens are refreshed, API keys are decrypted from the `encryptedApiKey` column
 
 You never need to modify the sync engine when adding a connector.
 
 ## Icon
 
-The `icon` field on `ConnectorConfig` is used throughout the UI — in the connector list, the add-connector modal, and as the document icon in the knowledge base table (replacing the generic file type icon for connector-sourced documents). The icon is read from `CONNECTOR_META_REGISTRY[connectorType].icon` (the client-safe registry) at runtime — no separate icon map to maintain.
+The `icon` field on `ConnectorConfig` is used throughout the UI — in the connector list, the add-connector modal, and as the document icon for connector-sourced documents in the knowledge base table. The icon is read from `CONNECTOR_META_REGISTRY[connectorType].icon` (the client-safe registry) at runtime — no separate icon map to maintain.
 
 If the service already has an icon in `apps/sim/components/icons.tsx` (from a tool integration), reuse it. Otherwise, ask the user to provide the SVG.
 
@@ -608,7 +605,7 @@ export const CONNECTOR_META_REGISTRY: ConnectorMetaRegistry = {
 - **OAuth + contentDeferred**: `apps/sim/connectors/google-drive/google-drive.ts` — file download with metadata-based hash, `orderBy` for deterministic pagination
 - **OAuth + contentDeferred (blocks API)**: `apps/sim/connectors/notion/notion.ts` — complex block content extraction deferred to `getDocument`
 - **OAuth + contentDeferred (git)**: `apps/sim/connectors/github/github.ts` — blob SHA hash, tree listing
-- **OAuth + inline content**: `apps/sim/connectors/slack/slack.ts` — list API returns message content inline, metadata-derived `contentHash`
+- **OAuth + inline content**: `apps/sim/connectors/slack/slack.ts` — list API returns message content inline; `contentHash` hashes that content
 - **OAuth + contentDeferred + config fields**: `apps/sim/connectors/confluence/confluence.ts` — multiple config field types, `mapTags`, label fetching
 - **API key**: `apps/sim/connectors/fireflies/fireflies.ts` — GraphQL API with Bearer token auth
 
@@ -626,11 +623,8 @@ export const CONNECTOR_META_REGISTRY: ConnectorMetaRegistry = {
   - `selectorKey` exists in `apps/sim/lib/selectors/manifest.ts`
   - `dependsOn` references selector field IDs (not `canonicalParamId`)
   - Each projected dependency key is a `SelectorContextKey` allowed by the selector manifest
-  - Every remote key has one server attachment with credential provider binding and a reviewed
-    `fixed`, `credential-bound`, or `user-controlled` destination policy
-  - No connector selector adds a client provider module, browser token request, or selector-only
-    API route
-- [ ] `listDocuments` handles pagination with metadata-based content hashes
+  - Validate the selector key itself with the `validate-selector` skill
+- [ ] `listDocuments` handles pagination; deferred-content connectors use metadata-based content hashes
 - [ ] `syncContext.listingCapped = true` set whenever the listing is truncated (max-items cap or transient per-item error) — required to prevent the engine's deletion reconciliation from removing unseen documents
 - [ ] `contentDeferred: true` used if content requires per-doc API calls (file download, export, blocks fetch)
 - [ ] `contentHash` is metadata-based (not content-based) and identical between stub and `getDocument`
diff --git a/.agents/skills/add-enrichment/SKILL.md b/.agents/skills/add-enrichment/SKILL.md
index 7a3a33c4664..7a4d93bbf94 100644
--- a/.agents/skills/add-enrichment/SKILL.md
+++ b/.agents/skills/add-enrichment/SKILL.md
@@ -27,7 +27,7 @@ Because enrichments run on Sim's hosted keys by default, **every provider tool y
 - **`enrichments/run.ts`** — the server-only cascade runner. Calls `executeTool(provider.toolId, { ...params, _context: { workspaceId, userId } })`, accumulates hosted-key cost, returns the first non-empty mapped result. **You do not edit this** — it works for any registry entry.
 - **`enrichments/registry.ts`** — `ENRICHMENT_REGISTRY` / `ALL_ENRICHMENTS` / `getEnrichment`. Register new entries here.
 
-Outputs automatically become table columns; billing, the catalog/sidebar UI, the column meta-header icon, and per-row execution all work with no extra wiring.
+Outputs automatically become table columns; billing, the catalog/sidebar UI, and per-row execution work with no extra wiring.
 
 ## Step 1: Pick the data-source tool(s)
 
@@ -118,7 +118,7 @@ Rules:
 In `apps/sim/enrichments/registry.ts`, import and add the entry (catalog order is registration order):
 
 ```typescript
-import { myEnrichment } from '@/enrichments/{id}/{id}'
+import { myEnrichment } from '@/enrichments/{id}'
 
 export const ENRICHMENT_REGISTRY: EnrichmentRegistry = {
   // ...existing
diff --git a/.agents/skills/add-managed-cli/SKILL.md b/.agents/skills/add-managed-cli/SKILL.md
index 0917a55a34b..c5bb3c9d0bf 100644
--- a/.agents/skills/add-managed-cli/SKILL.md
+++ b/.agents/skills/add-managed-cli/SKILL.md
@@ -43,7 +43,7 @@ Use `<tool>@<upstream-version>-r<recipe-revision>`.
 - New upstream version: append a new ID ending in `-r1`.
 - Recipe-only change for the same upstream version: append `-r2`, `-r3`, and so on.
 - Never mutate or delete an existing ID or recipe. Persisted sandboxes must continue resolving to the bytes and behavior they selected.
-- On upgrade, retain the old ID and recipe and set its metadata to `selectable: false`. Only the newest version keeps the public label selectable.
+- On upgrade, retain the old ID and recipe and mark the old metadata non-selectable; only the newest version keeps the public label selectable. `SandboxCliToolMetadata` has no retirement field yet, so the first upgrade adds one generically (type, selector, and contract validation) per the next paragraph.
 
 Before shipping the first upgrade for a tool family, verify that editing a sandbox cannot leave both the retired and replacement IDs selected. If the generic selector and API validation do not already replace or reject colliding versions, address that once at the generic registry boundary with focused UI and contract tests; never special-case the individual CLI or silently install two versions that expose the same executable.
 
@@ -123,7 +123,7 @@ From the repository root:
 
 ```bash
 bun run type-check
-bun run check:api-validation
+bun run check:api-validation:strict
 bunx biome check \
   apps/sim/lib/execution/remote-sandbox/cli-tools.ts \
   apps/sim/lib/execution/remote-sandbox/cli-tools.server.ts \
diff --git a/.agents/skills/add-model/SKILL.md b/.agents/skills/add-model/SKILL.md
index c7630651b10..53ee0ceb4a1 100644
--- a/.agents/skills/add-model/SKILL.md
+++ b/.agents/skills/add-model/SKILL.md
@@ -48,8 +48,10 @@ Use a precise WebFetch prompt: *"Extract for {model_id}: exact model id string,
 | Capability | Honored by | Effect if set elsewhere |
 |---|---|---|
 | `temperature` | All providers (passed through if set) | Safe but inert on always-reasoning models that reject it |
-| `toolUsageControl` | All providers (provider-level, not per-model) | n/a — set on `ProviderDefinition`, not models |
-| `reasoningEffort` | `openai/core.ts`, `azure-openai`, `xai`, `deepseek`, `groq`, `zai`, `meta`, `litellm` (each `index.ts`) | Not read by anthropic/gemini (they use `thinking`) or by mistral, cerebras, openrouter, fireworks, vertex — re-grep before assuming |
+| `toolUsageControl` | All providers (provider-level default) | Override per model only when that model differs |
+| `forcedToolUse` | Defaults to `toolUsageControl` | Set only when the model cannot force tools |
+| `promptCaching` | Caller-placed cache breakpoints | Set only where the vendor charges for opt-in caching (absent for OpenAI/Gemini implicit caching) |
+| `reasoningEffort` | `openai/core.ts`, `azure-openai`, `xai`, `deepseek`, `groq`, `zai`, `kimi`, `cerebras`, `meta`, `litellm` (each `index.ts`) | Not read by anthropic/gemini (they use `thinking`) or by mistral, openrouter, fireworks, vertex — re-grep before assuming |
 | `verbosity` | `openai/core.ts`, `azure-openai/index.ts` only | Dead elsewhere |
 | `thinking` | `anthropic/core.ts`, `gemini/core.ts`; `deepseek`, `groq`, `zai`, `kimi` (each `index.ts`) read the resolved `thinkingLevel` | Dead elsewhere |
 | `thinking.streamed` | Docs generator + `getThinkingStreamVisibility` (`models.ts`); `anthropic/core.ts` uses `'summary'` to request `display: 'summarized'` on agent-events runs | **Mandatory on Anthropic-family thinking models** (`agent-stream-docs:check` fails without it); other families fall back to provider defaults |
diff --git a/.agents/skills/add-selector/SKILL.md b/.agents/skills/add-selector/SKILL.md
index 439b16a61f6..4f3f6d40082 100644
--- a/.agents/skills/add-selector/SKILL.md
+++ b/.agents/skills/add-selector/SKILL.md
@@ -76,9 +76,9 @@ Choose the destination policy deliberately:
 - `user-controlled`: the user selects the destination. Hidden use-only authentication requires an
   explicit security policy; do not combine it with an arbitrary destination by default.
 
-Reuse or extract a server-only provider listing primitive. If an existing provider route has
-non-selector callers, keep the route as a thin caller of that primitive. If it is selector-only,
-move the logic and remove the obsolete route and contract. Never import a route handler or make an
+Reuse or extract a server-only provider listing primitive. A provider route exists only when it
+has a non-selector caller, and then it is a thin caller of that primitive; there are no
+selector-only routes or contracts. Never import a route handler or make an
 internal HTTP request from an attachment.
 
 The attachment must return normalized selector results only. It must never deliberately or
diff --git a/.agents/skills/validate-connector/SKILL.md b/.agents/skills/validate-connector/SKILL.md
index a65759287a8..6a1a6ef3819 100644
--- a/.agents/skills/validate-connector/SKILL.md
+++ b/.agents/skills/validate-connector/SKILL.md
@@ -10,7 +10,7 @@ argument-hint: <service-name> [api-docs-url]
 
 For **Sim Search**, validate the [live provider registration and access pipeline](../../../apps/sim/lib/sim-search/live/README.md#adding-a-live-search-connector): catalog and metadata parity, both search/read handlers, current member grants, service-source restrictions, safe scoped references, pagination, provenance, and provider failure behavior. Test real localhost setup/search/read with authorized fixtures when available, and distinguish those results from mocked provider tests. Live Search must not enqueue content indexing or background ACL/directory builds; GitLab still computes request-time permissions or uses current CSV grants.
 
-The ingestion-specific checks below apply to ordinary workspace KB connectors and legacy Search selected with `SIM_SEARCH_LIVE=false`. Keep those checks for providers supporting both runtimes; do not require a live-only provider to implement content hashes, ingestion cursors, embeddings, or stored ACL snapshots.
+The ingestion-specific checks below apply to ordinary workspace KB connectors only. Do not require a live-only provider to implement content hashes, ingestion cursors, embeddings, or stored ACL snapshots.
 
 You are an expert auditor for Sim knowledge base connectors. Your job is to thoroughly validate that an existing connector is correct, complete, and follows all conventions.
 
@@ -146,7 +146,7 @@ For each API endpoint the connector calls:
 - [ ] If the connector calls endpoints requiring scopes not in `requiredScopes`, flag as **warning**
 
 ### Token Refresh Config
-- [ ] Check the `getOAuthTokenRefreshConfig` function in `lib/oauth/oauth.ts` for this provider
+- [ ] Check the provider's entry in `getProviderAuthConfig` (`lib/oauth/oauth.ts`)
 - [ ] `useBasicAuth` matches the service's token exchange requirements
 - [ ] `supportsRefreshTokenRotation` matches whether the service issues rotating refresh tokens
 - [ ] Token endpoint URL is correct
@@ -169,7 +169,7 @@ The sync engine tombstones, then hard-deletes, any stored document absent from a
 - [ ] `syncContext.listingCapped = true` is set when a `maxItems`-style cap truncates the listing while more documents exist
 - [ ] `listingCapped` is set when a transient per-item error drops a still-existing document from the listing
 - [ ] `listingCapped` is NOT set when the source is genuinely exhausted (deleted documents must reconcile) or for intentional scope filters (date cutoffs)
-Verify it explicitly against `shouldReconcileDeletions` in `sync-engine.ts`.
+Verify it against the `checkpoint.unsafe` computation in `lib/knowledge/connectors/listing-checkpoint.ts`.
 
 ### Pagination State Across Pages
 - [ ] `syncContext` is used to cache state across pages (user names, field maps, instance URLs, portal IDs, etc.)
@@ -193,7 +193,7 @@ Connectors where the list API already returns content inline (e.g., Slack messag
 - [ ] `externalId` is a stable, unique identifier from the source API
 - [ ] `title` is extracted from the correct field and has a sensible fallback (e.g., `'Untitled'`)
 - [ ] `content` is plain text — HTML content is stripped using `htmlToPlainText` from `@/connectors/utils`
-- [ ] `mimeType` is `'text/plain'`
+- [ ] `mimeType` is `'text/plain'` for extracted text, or the document hands over `sourceFile` for a format the KB pipeline parses
 - [ ] `contentHash` uses a metadata-based format (e.g., `service:{id}:{modifiedTime}`) for connectors with `contentDeferred: true`, or `computeContentHash` from `@/connectors/utils` for inline-content connectors
 - [ ] `sourceUrl` is a valid, complete URL back to the original resource (not relative)
 - [ ] `metadata` contains all fields referenced by `mapTags` and `tagDefinitions`
@@ -230,17 +230,8 @@ Connectors where the list API already returns content inline (e.g., Slack messag
   - A `type: 'selector'` field with `selectorKey`, `canonicalParamId`, `mode: 'basic'`
   - A `type: 'short-input'` field with the same `canonicalParamId`, `mode: 'advanced'`
   - `required` is identical on both fields in the pair
-- [ ] `selectorKey` values exist in the browser-safe manifest and remote keys have exactly one
-      server attachment
 - [ ] `dependsOn` references selector field `id` values, not `canonicalParamId`
-- [ ] The shared builder projects only the active canonical dependency into an allowlisted
-      `SelectorContextKey`; exact `{{KEY}}` references remain unresolved in the browser
-- [ ] The attachment binds stored credentials to the actor, workspace, and trusted provider/service
-      and declares a reviewed `fixed`, `credential-bound`, or `user-controlled` destination policy
-- [ ] The connector sends workspace scope through the shared selector transport and does not send
-      the full connector configuration
-- [ ] No client provider selector module, browser token request, provider-specific selector request,
-      or selector-only route remains
+- [ ] Each selector key passes the `validate-selector` skill
 
 ### validateConfig
 - [ ] Validates all required fields are present before making API calls
@@ -267,7 +258,7 @@ Connectors where the list API already returns content inline (e.g., Slack messag
 ## Step 10: Validate General Quality
 
 ### fetchWithRetry Usage
-- [ ] All external API calls use `fetchWithRetry` from `@/lib/knowledge/documents/utils`
+- [ ] All external API calls use `fetchWithRetry` (or `secureFetchWithRetry` for user-controlled hosts) from `@/lib/knowledge/documents/secure-fetch.server`
 - [ ] No raw `fetch()` calls to external APIs
 - [ ] `VALIDATE_RETRY_OPTIONS` used in `validateConfig`
 - [ ] If `validateConfig` calls a shared helper (e.g., `linearGraphQL`, `resolveId`), that helper must accept and forward `retryOptions` to `fetchWithRetry`
@@ -367,31 +358,4 @@ After fixing, confirm:
 
 ## Checklist Summary
 
-- [ ] Read connector meta.ts, implementation, types, utils, both registries, and OAuth config
-- [ ] Pulled and read official API documentation for the service
-- [ ] Validated every API endpoint URL, method, headers, and body against API docs
-- [ ] Validated input sanitization: no query/filter injection, URL fields normalized
-- [ ] Validated OAuth scopes: `requiredScopes` ⊆ OAuth provider `scopes` in `oauth.ts`
-- [ ] Validated each scope is real and recognized by the service's API
-- [ ] Validated scopes are sufficient for all API endpoints the connector calls
-- [ ] Validated token refresh config (`useBasicAuth`, `supportsRefreshTokenRotation`)
-- [ ] Validated pagination: cursor names, page sizes, hasMore logic, no silent caps
-- [ ] Validated deletion-reconciliation safety: `syncContext.listingCapped` set on capped/error-truncated listings, not on genuine exhaustion or intentional scope filters
-- [ ] Validated content deferral: `contentDeferred: true` used when per-doc content fetch required, metadata-based `contentHash` consistent between stub and `getDocument`
-- [ ] Validated data transformation: plain text extraction, HTML stripping, content hashing
-- [ ] Validated tag definitions match mapTags output, correct fieldTypes
-- [ ] Validated config fields: canonical pairs, selector keys, required flags
-- [ ] Validated each dynamic selector through the shared manifest, server attachment, and
-      `selectors.execute` boundary
-- [ ] Validated validateConfig: lightweight check, error messages, retry options
-- [ ] Validated getDocument: null on 404, all content types handled, no redundant re-fetches, syncContext forwarding
-- [ ] Validated fetchWithRetry used for all external calls (no raw fetch), VALIDATE_RETRY_OPTIONS threaded through helpers
-- [ ] Validated API efficiency: field selection used, no redundant calls, sequential fetches batched
-- [ ] Validated error handling: graceful failures, no unhandled rejections
-- [ ] Validated logging: createLogger, no console.log
-- [ ] Validated meta/runtime split: `meta.ts` holds metadata with no server/runtime imports, `{service}.ts` spreads the meta + adds runtime functions
-- [ ] Validated registry: exported from index.ts, full connector in `registry.server.ts`, meta in `registry.ts`, matching keys and alphabetical-by-id ordering in both
-- [ ] Reported all issues grouped by severity
-- [ ] Fixed all critical and warning issues
-- [ ] Ran `bun run lint` after fixes
-- [ ] Verified TypeScript compiles clean
+Before reporting, confirm every step above was checked, issues are grouped by severity, critical and warning fixes are applied, and `bun run lint` plus type-check pass.
diff --git a/.agents/skills/validate-model/SKILL.md b/.agents/skills/validate-model/SKILL.md
index 06d982ebe10..7555cc45edf 100644
--- a/.agents/skills/validate-model/SKILL.md
+++ b/.agents/skills/validate-model/SKILL.md
@@ -68,8 +68,8 @@ For each model, evaluate every row. Statuses: ✓ matches docs, ✗ disagrees, 
 - [ ] `temperature` — provider accepts it for this model (reasoning-always-on models often reject)
 - [ ] `reasoningEffort.values` — list matches docs; **omitted** for always-reasoning models that reject the parameter (e.g., grok-4.3, where xAI docs explicitly state `reasoning_effort` is not supported). Verify per model — some always-reasoning models (e.g., OpenAI's o-series) DO accept `reasoning_effort` and should keep the flag.
 - [ ] `verbosity.values` — only on OpenAI gpt-5.x family; values match docs
-- [ ] `thinking.levels` + `thinking.default` — only on Anthropic/Gemini; values match docs
-- [ ] `thinking.streamed` — REQUIRED on Anthropic-family thinking models (`'full'` for generations returning full thinking deltas, `'summary'` for omitted-display generations like Opus 4.7+/Sonnet 5/Fable 5 where Sim requests `display: 'summarized'`); verify against the provider's thinking-display docs. After any change, run `bun run agent-stream-docs:generate` so the Agent block docs table stays in sync (CI diffs it)
+- [ ] `thinking.levels` + `thinking.default` — only on providers whose code reads `thinking`/`thinkingLevel` (see the add-model Consumption Matrix); values match docs
+- [ ] `thinking.streamed` — REQUIRED on Anthropic-family thinking models. Current Claude thinking models use `'summary'` (Sim requests `display: 'summarized'`); use `'full'` only if official API docs explicitly guarantee raw thinking deltas. Verify against the provider's thinking-display docs. After any change, run `bun run agent-stream-docs:generate` so the Agent block docs table stays in sync (CI diffs it)
 - [ ] `nativeStructuredOutputs` — only on providers whose code consumes it (see the Consumption Matrix); provider must document Structured Outputs / JSON-mode for this model
 - [ ] `toolUsageControl` — provider supports `tool_choice` semantics
 - [ ] `computerUse` — provider implements computer-use loop AND model is a computer-use SKU
diff --git a/.agents/skills/validate-selector/SKILL.md b/.agents/skills/validate-selector/SKILL.md
index bb251dada5c..1b2ea55fd7a 100644
--- a/.agents/skills/validate-selector/SKILL.md
+++ b/.agents/skills/validate-selector/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: validate-selector
-description: Audit a Sim dynamic selector across its declaration, browser-safe manifest, server attachment, provider primitive, and selectors.execute security boundary. Use when reviewing selector correctness, secret handling, scope authorization, or migration completeness.
+description: Audit a Sim dynamic selector across its declaration, browser-safe manifest, server attachment, provider primitive, and selectors.execute security boundary. Use when reviewing selector correctness, secret handling, scope authorization, or dead selector-only routes.
 argument-hint: <selector-key-or-service>
 ---
 
@@ -64,11 +64,8 @@ personal/shared values are not automatically protected plaintext, but the execut
 deliberately or wholesale echo selector context. Only intentionally projected, normalized
 `{ id, label, meta? }` options and bounded cursors may cross the boundary.
 
-Selector code must not introduce a context, token, or result cache. The sole existing cache
-exception is authorized client-credential resolution after authorization and provider binding,
-which may reuse the credential service's TTL-governed, lazily pruned process-local token cache. The
-cache is not hard-bounded, the exception requires explicit security-owner acceptance, and selector
-work must not expand it.
+Selector code adds no context, token, or result cache beyond the single accepted exception
+described in the `add-selector` skill ("Wire the UI declaration").
 
 ## Validate provider reuse and browser boundaries
 
diff --git a/.claude/rules/sim-imports.md b/.claude/rules/sim-imports.md
index cb62fea68ff..8871884f219 100644
--- a/.claude/rules/sim-imports.md
+++ b/.claude/rules/sim-imports.md
@@ -9,7 +9,7 @@ paths:
 
 ## Absolute Imports
 
-**Always use absolute imports.** Never use relative imports.
+**Always use absolute imports.** Never use relative imports, except that a barrel `index.ts` re-exports its own siblings relatively (`export { X } from './x'`).
 
 ```typescript
 // ✓ Good
diff --git a/.cursor/rules/sim-imports.mdc b/.cursor/rules/sim-imports.mdc
index 3b9f0656c24..2284d0b0ac4 100644
--- a/.cursor/rules/sim-imports.mdc
+++ b/.cursor/rules/sim-imports.mdc
@@ -9,7 +9,7 @@ globs: ["apps/sim/**/*.ts","apps/sim/**/*.tsx"]
 
 ## Absolute Imports
 
-**Always use absolute imports.** Never use relative imports.
+**Always use absolute imports.** Never use relative imports, except that a barrel `index.ts` re-exports its own siblings relatively (`export { X } from './x'`).
 
 ```typescript
 // ✓ Good
diff --git a/CLAUDE.md b/CLAUDE.md
index 52ef363d923..ae6a0ad0d87 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -83,7 +83,7 @@ The `'use client'` server boundary, the app/worker runtime env split, and featur
 ## Code Conventions
 
 - **Naming**: components PascalCase (`WorkflowList`); hooks `use*`; files kebab-case (`workflow-list.tsx`); constants SCREAMING_SNAKE_CASE; interfaces PascalCase with a suffix (`WorkflowListProps`); stores `stores/<feature>/store.ts`. A file never repeats its folder's name (`lib/logs/views.ts`, not `lib/logs/log-views.ts`; `utils/date.ts`, not `utils/date-utils.ts`); `check:file-names` enforces this.
-- **Imports**: absolute (`@/...`) only, never relative. A folder with 3+ exports gets an `index.ts` barrel; never re-export from a non-barrel file. `import type` for type-only imports. Order and lazy-loading through barrels: `.claude/rules/sim-imports.md`.
+- **Imports**: absolute (`@/...`) only, never relative (a barrel `index.ts` re-exports its own siblings relatively). A folder with 3+ exports gets an `index.ts` barrel; never re-export from a non-barrel file. `import type` for type-only imports. Order and lazy-loading through barrels: `.claude/rules/sim-imports.md`.
 - **TypeScript**: no `any` and no non-null `!` (use precise types or `unknown` with guards; `check:explicit-any` ratchets both); no export nothing imports (`check:unused-exports`); a props interface for every component; `as const` for constant objects/arrays; explicit ref types (`useRef<HTMLDivElement>(null)`).
 - **Unused bindings** fail lint (biome `noUnusedVariables`, `noUnusedFunctionParameters`): delete the dead variable, import, or parameter and update callers; write `catch {}` when the error is unused. Prefix `_` only for a parameter that must hold its position because a later one is used. `const { a, ...rest } = obj` to omit keys is allowed. The rules carry no autofix, so `bun run lint` will not rename anything for you.
 - **Components**: `'use client'` only for hooks or browser APIs. Structure order, extraction thresholds, and list-render rules: `.claude/rules/sim-components.md`. Render-performance idioms (lazy-init refs, hoisting, `Map` pre-indexing, `[...arr].sort()`, never `toSorted()`): `.claude/rules/sim-react-performance.md`. For effect/state/memo/callback anti-patterns use the `/you-might-not-need-*` skills and verify against the running UI.
@@ -133,7 +133,7 @@ Remaining block/tool/trigger rules: `.claude/rules/sim-integrations.md`. Canvas
 
 Table column types are registry entries in `apps/sim/lib/table/column-types/` — one file per type owning its label, icon, storage cast, coercion, validation, conversion compatibility, formatting, and editor. `Record<ColumnType, …>` on `registry.ts` and `registry.server.ts` is a compile-time completeness gate: adding a type to the union errors until both entries exist.
 
-Never add a `case 'sometype':` outside `column-types/` — a missing arm fails silently (a wrong `jsonbCast` breaks every filter on the column). If a consumer needs per-type knowledge, add a registry field. Use `/add-column-type` for the full procedure.
+Never add a `case 'sometype':` outside `column-types/`, except the one documented import-path switch (`coerceValue` in `lib/table/import.ts`), which every new type extends — a missing arm fails silently (a wrong `jsonbCast` breaks every filter on the column). If a consumer needs per-type knowledge, add a registry field. Use `/add-column-type` for the full procedure.
 
 ## How your work is checked
 

From 973ebbc0eafc1ba43039fe96b63d92486d035351 Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Thu, 1 Oct 2026 17:17:34 -0700
Subject: [PATCH 06/18] docs(agents): fix contradictions and stale facts in
 platform skills

tool-registry-boundary told tests to re-mock a global (check:test-patterns
fails that); db-migrate listed a nonexistent annotate rule and omitted the
pending-drop-tables contract; permission-group skills cited a removed
descriptions record, a nonexistent key-order test, and a single
principal-wide capability where there are two; v2-api-conventions cited a
removed helper; memory-load-check called a pattern the connectors use
cargo-culting. Gates now name check:api-validation:strict / check:audits,
ship runs CI's schema/migration sync step, test-audit points at CLAUDE.md
instead of copying it, and incident narration became current-state rules.
---
 .../skills/add-permission-group-item/SKILL.md | 24 +++++++-------
 .agents/skills/babysit/SKILL.md               |  4 +--
 .agents/skills/cleanup/SKILL.md               |  2 +-
 .agents/skills/db-migrate/SKILL.md            |  7 ++--
 .agents/skills/memory-load-check/SKILL.md     |  4 +--
 .../migrate-application-operation/SKILL.md    |  6 ++--
 .agents/skills/ship/SKILL.md                  |  1 +
 .agents/skills/test-audit/SKILL.md            | 16 ++-------
 .../skills/tool-registry-boundary/SKILL.md    | 33 +++++++------------
 .agents/skills/v2-api-conventions/SKILL.md    | 26 +++++----------
 .../validate-permission-group-item/SKILL.md   | 12 +++----
 .claude/rules/sim-testing.md                  |  2 +-
 .cursor/rules/sim-testing.mdc                 |  2 +-
 13 files changed, 56 insertions(+), 83 deletions(-)

diff --git a/.agents/skills/add-permission-group-item/SKILL.md b/.agents/skills/add-permission-group-item/SKILL.md
index e0cb4447eeb..23abe85a444 100644
--- a/.agents/skills/add-permission-group-item/SKILL.md
+++ b/.agents/skills/add-permission-group-item/SKILL.md
@@ -8,11 +8,11 @@ argument-hint: <what-to-restrict>
 
 You are adding one governed item an organization admin can withhold from a cohort of members. One entry in `apps/sim/lib/permission-groups/fields.ts` produces the write schema, the read schema, the `PermissionGroupConfig` type, the defaults, the tolerant parser, and (for a boolean) the admin editor row.
 
-**The registry does not produce enforcement.** Twelve keys once shipped with a checkbox, a hint, and no server check — an organization that ticked `hideCopilot` believed it had withheld a capability while every route still answered. Hence the `enforcement` field, the required `capability` field on every operation, and `scripts/check-permission-group-enforcement.ts`. You are done when something *refuses*, not when the key parses.
+**The registry does not produce enforcement.** A key with an admin checkbox but no server gate gives an admin a restriction that does not exist. The `enforcement` field, the required `capability` field on every operation, and `scripts/check-permission-group-enforcement.ts` exist to prevent that. You are done when something *refuses*, not when the key parses.
 
 ## Read the system first
 
-- `lib/permission-groups/fields.ts` — registry, three field builders, `permissionGroupConfigSchema`, `tolerantArray`, `parsePermissionGroupConfig`. There is **no `types.ts`** (folded in here); the DB constraint maps live in `constraints.ts`
+- `lib/permission-groups/fields.ts` — registry, three field builders, `permissionGroupConfigSchema`, `tolerantArray`, `parsePermissionGroupConfig`. `PermissionGroupConfig` and its schemas are defined here; the DB constraint maps live in `constraints.ts`
 - `lib/permission-groups/capabilities.ts` — `CAPABILITY_IDS`, `CAPABILITY_RULES`, `capabilityRefusal`, `refuseCapability`, the static/parameterized split
 - `lib/permission-groups/capability-assertions.ts` — the sanctioned assertion API; re-exports `capabilityRefusal`. `capability-error.ts` holds the thrown error, `capability-response.ts` the raw-route 403
 - `lib/permission-groups/integration-allowlist.ts` — the canonicalizing allowlist algebra, over the generated `block-successors.generated.ts`
@@ -41,7 +41,7 @@ Allowlist when the safe posture is "only what the admin named" and the member se
 | `'executor'` | Read per block/tool/model at run time by `assertPermissionsAllowed` in `ee/access-control/utils/permission-check.ts`. Governs what a *run* may do, which no operation gate can express (one API call executes fifty blocks). Only `allowedIntegrations`, `allowedModelProviders`, `deniedModels`, `deniedTools` live here. The matching primitives these four keys are compared with live in `lib/permission-groups/` — `block-access.ts` (exemptions, superseded-version resolution), `operation-access.ts` (`createToolAccessGate`), `model-access.ts` (`createModelAccessGate`), `integration-allowlist.ts` — shared so the run-time gate and the editor/Copilot projections cannot drift. `allowedIntegrations` alone is also asserted outside a run, by `assertSelectorIntegrationAllowed` (`lib/selectors/server/integration-access.ts`) ahead of the provider call in `selectors.execute`, against the selector's own `resourceServiceId` / `integrationBlockTypes` rather than the credentials it accepts — reaching a provider API is a use of the integration, so a key here can still need a non-run enforcement site |
 | `'ui-only'` | Hides a surface without withholding it. **Almost never right** — nothing ships as `ui-only`. Justify in the `enforcement` comment why a determined caller reaching the data is acceptable, and expect review to question it |
 
-**Is it per-operation at all?** `personal_api_key.use` is the one capability that is not: it withholds a *principal kind* across every operation, checked in the funnel's `personal_api_key` branch (`workspace-authorization.ts`) and again in `app/api/v1/middleware.ts`, so no operation declares it and its absence from every `capability:` field is correct rather than a hole.
+**Is it per-operation at all?** `personal_api_key.use` and `oauth_apps.use` are principal-wide (`PRINCIPAL_WIDE_CAPABILITIES` in `lib/core/application/operation.ts`): they withhold a principal kind across every operation, checked in the funnel's `personal_api_key` / `oauth_access_token` branches (`workspace-authorization.ts`) and in `app/api/v1/middleware.ts`. Declaring one on an operation throws at definition time, so its absence from every `capability:` field is correct.
 
 **Is the decision knowable from the config alone?** A rule needing a request value (an auth mode, a connector id) is *parameterized* and cannot be declared on an operation — see Step 3.
 
@@ -60,7 +60,7 @@ Allowlist when the safe posture is "only what the admin named" and the member se
 
 The second argument is the field's `feature` (`PlatformFeatureMeta`); `PLATFORM_FEATURES` spreads it and appends `configKey`, so those four values are what the editor renders. `PLATFORM_FEATURES` is *derived* from the registry in `features.ts`, so a boolean key cannot reach the config without reaching the editor.
 
-- **Declaration order is the wire order** of `PermissionGroupConfig`, both zod schemas, and every config JSON crossing the API. `fields.test.ts` pins it with a key-order contract test, and `ee/access-control/components/group-detail.tsx` dirty-checks by comparing stringified configs — a moved key fails the suite *and* makes every open editor read as unsaved. Extend the tail; do not tidy the middle.
+- **Declaration order is the wire order** of `PermissionGroupConfig`, both zod schemas, and every config JSON crossing the API. No test catches a reorder (schemas and defaults all derive from the registry), and `ee/access-control/components/group-detail.tsx` dirty-checks by comparing stringified configs, so a moved key makes every open editor read as unsaved. Extend the tail; do not tidy the middle.
 - **The default must be the permissive value.** Every stored `permission_group.config` row predates your key; `parsePermissionGroupConfig` fills the gap from the default and the update route merges a partial write over the stored config, so a restrictive default silently applies a new restriction to every existing group in every enterprise org. The builders hardcode `false` / `null` / `[]`, so a new key must be *phrased* so the permissive value is falsy: a `requireWidgetApproval` whose safe default is `true` must be inverted before it can use `booleanRestriction`.
 - **The checkbox is inverted.** `group-detail.tsx` renders `checked={!editingConfig[feature.configKey]}` — ticked means *allowed*, so an `allowX` name renders backwards.
 - **The hint must describe access withheld, never a surface hidden.** A `'capability'` key refuses at the API; "Hide the Tables module from the sidebar" tells an admin they are tidying a nav bar while they revoke a module. The same string is read again by `getActivePermissionGroupRestrictions` in `features.ts` as the prose for an *active* restriction — reaching users through the Copilot workspace VFS and the enterprise platform context — where "hide" is simply false. Write "Revoke the Tables module. Members cannot read or write any table." `PlatformFeatureMeta.hint` carries the rule in its TSDoc.
@@ -107,13 +107,13 @@ Capability ids are **domain-shaped** (`tables.create`); config keys are **surfac
 
 `configKeys` is what the audit reads to prove your key is enforced — it must list every key `deniedBy` reads. `describe` is the subject of one shared sentence, `"<describe> is not available under your organization's permission group"`, so make it a singular noun or gerund that agrees with "is". Exactly two functions build it, both defined in `capabilities.ts`: `refuseCapability(cap)` throws it as a `PermissionGroupCapabilityError`; `capabilityRefusal(cap)` returns it as a string for a raw route rendering its own body (`capability-assertions.ts` re-exports it so an inline gate reaches both through one module). Never write the sentence at a call site.
 
-Use `'PERMISSION_GROUP_CAPABILITY_BLOCKED'` for `detailCode`. Four rules carry a more specific one — `deploy.chat.auth_mode` (`CHAT_AUTH_MODE_NOT_PERMITTED`), `file_share.publish` / `file_share.auth_mode` (`PUBLIC_SHARING_NOT_ALLOWED`), `personal_api_key.use` (`PERSONAL_API_KEYS_DISABLED`) — which is why a call site reads the code off the rule and never spells one out. The set in `lib/core/application/forbidden.ts` is closed **over remedies, not causes** — a new code is warranted only when the remedy differs from "ask an organization admin", and requires an entry in `FORBIDDEN_DETAIL_CODE_DESCRIPTIONS` (a compile-time gate) plus a new value in the generated OpenAPI 403 description.
+Use `'PERMISSION_GROUP_CAPABILITY_BLOCKED'` for `detailCode`. Four rules carry a more specific one — `deploy.chat.auth_mode` (`CHAT_AUTH_MODE_NOT_PERMITTED`), `file_share.publish` / `file_share.auth_mode` (`PUBLIC_SHARING_NOT_ALLOWED`), `personal_api_key.use` (`PERSONAL_API_KEYS_DISABLED`) — which is why a call site reads the code off the rule and never spells one out. The set in `lib/core/application/forbidden.ts` is closed **over remedies, not causes** — a new code is warranted only when the remedy differs from "ask an organization admin", and needs a TSDoc-documented entry in the closed `FORBIDDEN_DETAIL_CODES` tuple, which is published to OpenAPI as the `V2ForbiddenDetailCode` enum via `v2ForbiddenDetailCodeSchema`.
 
 A **parameterized** rule is the same shape with `kind: 'parameterized'` and a `deniedBy` taking the request value second — `'knowledge.connectors'` is `(config, connectorType) => allowlistDenies(config.allowedKnowledgeConnectors, connectorType)`. It **cannot be declared on an operation**: the funnel decides from principal, workspace and operation, never request input, and widening it would touch every one of the hundreds of operations for the sake of two keys. `defineWorkspaceOperation` throws at definition time (`Operation <id> declares parameterized capability <cap>; assert it from the use case instead`) rather than letting the operation read as gated while the gate never fires.
 
 ## Step 4: Declare it on the operations it governs, or assert it at the call site
 
-`capability` is **required on the `ApplicationOperation` base type** (the `capability` field in `lib/core/application/operation.ts`), typed `StaticPermissionGroupCapability | 'none'` — required there, not only on `defineWorkspaceOperation`, so a bare object literal minted by a domain factory does not compile without it — *and* guarded at definition time (`Operation <id> declares no capability; name one, or 'none' with a reason`). The guard is not redundant: **`apps/sim/tsconfig.json` excludes `*.test.ts` / `*.test.tsx` from type-checking** and the enforcement audit walks past test files, so a fixture is the one construction site no static check reads. An absent capability does not deny — it throws `Cannot read properties of undefined` inside `capabilityDeniedBy`, and **only for a caller whose organization actually has a permission group**. It passes CI and every personal workspace, then fails in the tenants that bought the feature.
+`capability` is **required on the `ApplicationOperation` base type** (the `capability` field in `lib/core/application/operation.ts`), typed `OperationDeclarableCapability | 'none'` — required there, not only on `defineWorkspaceOperation`, so a bare object literal minted by a domain factory does not compile without it — *and* guarded at definition time (`Operation <id> declares no capability; name one, or 'none' with a reason`). The guard is not redundant: **`apps/sim/tsconfig.json` excludes `*.test.ts` / `*.test.tsx` from type-checking** and the enforcement audit walks past test files, so a fixture is the one construction site no static check reads. An absent capability does not deny — it throws `Cannot read properties of undefined` inside `capabilityDeniedBy`, and **only for a caller whose organization actually has a permission group**. It passes CI and every personal workspace, then fails in the tenants that bought the feature.
 
 **Static, and the operation is the whole decision** — set `capability` and write no gate code:
 
@@ -176,9 +176,9 @@ Always route through `CAPABILITY_RULES` and raise with `refuseCapability` — a
 | `TableAccessPrincipal` | `capabilityGovernedUserId(principal)` (`app/api/table/utils.ts`) |
 | `AuthResult` from `checkSessionOrInternalAuth` | `capabilityGovernedAuthUserId` (same file) — an internal JWT's `userId` is the run's actor, a bystander |
 
-When the subject is **persisted and read back later** — the table dispatch pipeline stamps it on `table_run_dispatches` / `table_row_executions` so auto-fired cells run under the person the write was gated for — declare it `capabilityGovernedUserId: string | null`, required with an explicit `null` and never optional. An optional field with a fallback is how every producer that had not been taught the distinction silently inherited `triggeredByUserId`, an *attribution* naming the billed account; making omission a compile error is the whole enforcement. A persisted subject also has a lifecycle: `lib/users/account-deletion.ts` cancels the dispatches stamped with a deleted user.
+When the subject is **persisted and read back later** — the table dispatch pipeline stamps it on `table_run_dispatches` / `table_row_executions` so auto-fired cells run under the person the write was gated for — declare it `capabilityGovernedUserId: string | null`, required with an explicit `null` and never optional. An optional field with a fallback lets producers silently use `triggeredByUserId` (an *attribution* naming the billed account) as the subject; making omission a compile error is the whole enforcement. A persisted subject also has a lifecycle: `lib/users/account-deletion.ts` cancels the dispatches stamped with a deleted user.
 
-- **`/api/v1`** authorizes in `app/api/v1/middleware.ts`. Every route threads a `V1RouteCapability` (`StaticPermissionGroupCapability | 'none'`, required and spelled out) whose value must match what its v2 or internal counterpart declares — v1 gets no mapping of its own. `check-capability-subject.ts` audits v1's subjects only, because the bug has shipped and been fixed twice there.
+- **`/api/v1`** authorizes in `app/api/v1/middleware.ts`. Every route threads a `V1RouteCapability` (`StaticPermissionGroupCapability | 'none'`, required and spelled out) whose value must match what its v2 or internal counterpart declares — v1 gets no mapping of its own. `check-capability-subject.ts` audits v1 subjects only; other surfaces rely on the `capabilityGoverned*` helpers.
 - **Raw internal table routes** (`/api/table/**`) share one gate in `checkAccess` (`app/api/table/utils.ts`), whose signature takes a `TableAccessPrincipal` union — `{ kind: 'user'; userId }` or `{ kind: 'workspace_api_key'; keyCreatorUserId }` — so a bare id does not type-check and only the kind that says so skips the gate. `tableAccessPrincipal(rateLimit)` builds it for v1.
 - **The route-wrapper graph.** `withRouteHandler` imports `request-scope.server.ts` and nothing heavier. Import a resolver at the *call site*, never from the wrapper or `lib/core/application` — see Step 6.
 
@@ -186,7 +186,7 @@ When the subject is **persisted and read back later** — the table dispatch pip
 
 Add the key to **both** the `input` and `expected` objects of the `'a fully populated config'` fixture in `lib/permission-groups/fields.test.ts`, set to a non-default value. That fixture is the pinned coercion corpus: a row that changes in a later diff is a semantic decision someone defends rather than a silent regression. The file's other assertions derive from `DEFAULT_PERMISSION_GROUP_CONFIG` (wire order, idempotence, read-schema acceptance, the 2000-iteration seeded fuzz, write/default/read key-set agreement, boolean-to-`PLATFORM_FEATURES` coverage) and pick your key up for free, as does `features.test.ts`.
 
-**Give the funnel test a real `workspaceOrganizationId`.** `requireCapability` short-circuits on `context.workspaceOrganizationId === null` (`lib/core/application/workspace-authorization.ts:204`), so a fixture whose workspace context leaves it null passes with the gate present *and* with it removed — a vacuous test that reads as load-bearing.
+**Give the funnel test a real `workspaceOrganizationId`.** `requireCapability` short-circuits on `context.workspaceOrganizationId === null` (`requireCapability` in `lib/core/application/workspace-authorization.ts`), so a fixture whose workspace context leaves it null passes with the gate present *and* with it removed — a vacuous test that reads as load-bearing.
 
 Add a case to `capabilities.test.ts` for any rule with logic beyond reading one key. For an allowlist assert all three states — `null` permits every member, a populated list only the named ones, `[]` permits **none** — as `capabilities.test.ts` already does for `knowledge.connectors`.
 
@@ -201,7 +201,7 @@ Add a case to `capabilities.test.ts` for any rule with logic beyond reading one
 
 `lib/billing/` stays allowed for the funnel roots because `resolve.server.ts` legitimately reads the subscription to decide whether an organization is on an enterprise plan; the wrapper is a lifecycle shim that opens the memo scope and nothing more. That split is why the scope is two files.
 
-Breaking this never announces itself — past regressions surfaced only as unrelated tests failing on partial mocks of modules they never meant to load. After adding an import, run this audit first.
+A broken edge shows up only indirectly (unrelated tests failing on partial mocks), so run this audit after adding any import.
 
 ## Step 7: Verify
 
@@ -213,7 +213,7 @@ cd apps/sim && bun run type-check
 bun run --cwd apps/sim test lib/permission-groups
 ```
 
-Also `bun run check:api-validation` if you touched a contract or the group routes. `bun run check:audits` runs all of these; it derives its list from the `check:*` scripts in `package.json`, so a new audit is opted *out* deliberately rather than opted in.
+Also `bun run check:api-validation:strict` if you touched a contract or the group routes. `bun run check:audits` runs every one of these (including the `:strict` variant); it derives its list from the `check:*` scripts in `package.json`, so a new audit is opted *out* deliberately rather than opted in.
 
 Read the success lines, not the exit codes — compare the counts against the previous run and check they grew by exactly what you added: an operation-declared capability adds one operation and one capability; a raw-route or parameterized capability adds one capability and no operation; an executor-gated or UI-only item adds neither:
 
@@ -229,7 +229,7 @@ The audits prove *reachability*: your capability is named somewhere, your key is
 
 ## Traps
 
-**An operation carries exactly ONE capability, and a narrower capability must subsume the broader one it replaced.** `knowledge.create` and `knowledge.upload` list `configKeys: ['disableKnowledgeBaseCreation', 'hideKnowledgeBaseTab']` and OR both in `deniedBy`, because moving KB creation off `knowledge.use` would otherwise let a group that withheld the whole module still create one through the API. Any time you re-point an operation to a more specific capability, the specific rule must read both keys.
+**An operation carries exactly ONE capability, and a narrower capability must subsume the broader one it replaced.** `knowledge.create` (`disableKnowledgeBaseCreation`) and `knowledge.upload` (`disableKnowledgeBaseFileUpload`) each also list and OR `hideKnowledgeBaseTab` in `deniedBy`, because moving KB creation off `knowledge.use` would otherwise let a group that withheld the whole module still create one through the API. Any time you re-point an operation to a more specific capability, the specific rule must read both keys.
 
 **`.catch()` on an array field is a fail-open security bug.** `z.array(item).catch(fallback)` is whole-value tolerant: one bad member discards every good one. On an allowlist the fallback is `null`, and `null` means **unrestricted** — a partly corrupt allowlist stops restricting anything. `tolerantArray` in `fields.ts` filters element by element, keeping what parses and failing closed. Never swap it for `.catch()`, never hand-roll a parallel coercion path.
 
diff --git a/.agents/skills/babysit/SKILL.md b/.agents/skills/babysit/SKILL.md
index 83204194548..c8810e7dd0f 100644
--- a/.agents/skills/babysit/SKILL.md
+++ b/.agents/skills/babysit/SKILL.md
@@ -88,8 +88,8 @@ conditions freshly after every push.
    across all pages has `isResolved: true`, and every check has finished and passed, stop —
    report the outcome (see "Reporting" below) and skip the rest of this list.
 
-2. **If the PR has a merge conflict**, merge `origin/staging`, resolve the conflicts, run the
-   usual pre-push checks, push, and go to step 8 to re-trigger review.
+2. **If the PR has a merge conflict**, merge `origin/staging`, resolve the conflicts, run `/ship`
+   steps 4–6 on the merge result, push, and go to step 8 to re-trigger review.
 
 3. **If no review has run yet** (fresh PR, no bot comments): both run automatically on PR open —
    confirm via `gh pr checks <n>` (look for `Greptile Review` and `cubic · AI code reviewer`) and
diff --git a/.agents/skills/cleanup/SKILL.md b/.agents/skills/cleanup/SKILL.md
index e957a1a64f7..1ddfddcce6e 100644
--- a/.agents/skills/cleanup/SKILL.md
+++ b/.agents/skills/cleanup/SKILL.md
@@ -7,7 +7,7 @@ argument-hint: "[scope] [fix=true|false]"
 # Cleanup
 
 Arguments:
-- scope: what to review (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase"
+- scope: what to review (default: your current changes). Examples: "diff to staging", "PR #123", "src/components/", "whole codebase"
 - fix: whether to apply fixes (default: true). Set to false to only propose changes.
 
 User arguments: $ARGUMENTS
diff --git a/.agents/skills/db-migrate/SKILL.md b/.agents/skills/db-migrate/SKILL.md
index d00f375f9ab..0ff4581a2b1 100644
--- a/.agents/skills/db-migrate/SKILL.md
+++ b/.agents/skills/db-migrate/SKILL.md
@@ -34,7 +34,7 @@ Never put expand and contract in the same PR. If this PR both removes the code t
 | Change a column type | add a new column of the new type; dual-write | backfill, swap reads, drop old |
 | Add FK / CHECK | `ADD CONSTRAINT ... NOT VALID` | `VALIDATE CONSTRAINT` separately |
 | Index an existing table | `COMMIT;` breakpoint → `SET lock_timeout = 0` → `CREATE INDEX CONCURRENTLY IF NOT EXISTS` (see `packages/db/scripts/migrate.ts`) | — |
-| Drop an index | `COMMIT;` breakpoint → `DROP INDEX CONCURRENTLY` — plain `DROP INDEX` takes ACCESS EXCLUSIVE on the table | — |
+| Drop an index | `COMMIT;` breakpoint → `DROP INDEX CONCURRENTLY IF EXISTS` — plain `DROP INDEX` takes ACCESS EXCLUSIVE on the table | — |
 | Backfill data | batched + idempotent `UPDATE` (keyset/`WHERE`, bounded) | — |
 
 A `CREATE INDEX`, `ADD COLUMN`, or `ADD CONSTRAINT` against a table **created in the same migration** is always safe (no rows, no live traffic) — the lint already suppresses those.
@@ -53,6 +53,7 @@ workspaceId: text('workspace_id'),
 Format: `contract-pending(<precondition>): <what to drop> — <why it's safe once the precondition holds>`. The precondition names the PR/release that removes the last reader and **must be fully deployed** before the contract ships.
 
 - **The TODO list is a grep** — always accurate, never drifts: `grep -rn "contract-pending" packages/db apps/sim`. Run it when starting migration work to see what is owed.
+- While a drop is pending, tag each doomed column `@deprecated` and make every read of that table name its columns: no argless `select().from(t)`, `findFirst()` without `columns`, argless `.returning()`, or bare `getTableColumns(t)` — use `omit(getTableColumns(t), [...])`. `check:pending-drop-tables` enforces this.
 - For anything with a real owner or schedule, also open a tracking issue and put its number in the marker.
 - **Close the loop in the contract PR:** the contract migration's `-- migration-safe:` annotation references the expand, and you **delete the `contract-pending` marker** in the same PR:
   ```sql
@@ -74,8 +75,8 @@ The lint flags risky *shapes*; it cannot know whether a given drop is *safe righ
 1. Edit `packages/db/schema.ts`, then `cd packages/db && bunx drizzle-kit generate` to produce the SQL. If this is an expand that defers a drop, leave a `contract-pending` marker on the legacy column (see "Tracking the contract"). If this is the contract, delete the marker it resolves.
 2. Hand-edit the generated SQL where the playbook requires it: `CONCURRENTLY` + `COMMIT;` breakpoint for indexes on existing tables, `NOT VALID` for constraints, batching for backfills.
 3. Run `bun run check:migrations` (base defaults to `origin/staging`).
-   - **Hard errors** (`add-not-null-no-default`, `rename`, `index-not-concurrent`, `constraint-not-valid`, …): rewrite into expand/contract. Do **not** try to annotate them away — the lint won't accept it.
-   - **Annotate tier** (`drop-table`, `drop-column`, `drop-default`, `set-not-null`, `alter-type`, `drop-index`): only after you've confirmed steps 1–3 above, add a comment on the line directly above the statement:
+   - **Hard errors** (`add-not-null-no-default`, `rename`, `index-not-concurrent`, `concurrent-index-not-idempotent`, `concurrent-index-no-commit`, `drop-index-not-concurrent`, `concurrent-drop-index-not-idempotent`, `concurrent-drop-index-no-commit`, `constraint-not-valid`, …): rewrite into expand/contract. Do **not** try to annotate them away — the lint won't accept it.
+   - **Annotate tier** (`drop-table`, `drop-column`, `drop-constraint`, `drop-default`, `set-not-null`, `alter-type`): only after you've confirmed steps 1–3 above, add a comment on the line directly above the statement:
      ```sql
      -- migration-safe: `secret` read removed in v0.6.1 (#1234), shipped two deploys ago
      ALTER TABLE "webhook" DROP COLUMN "secret";
diff --git a/.agents/skills/memory-load-check/SKILL.md b/.agents/skills/memory-load-check/SKILL.md
index 22c03cb7767..40af9c55e2c 100644
--- a/.agents/skills/memory-load-check/SKILL.md
+++ b/.agents/skills/memory-load-check/SKILL.md
@@ -72,9 +72,7 @@ For those, require all three:
 - 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
+Skip the *per-file `CONNECTOR_MAX_FILE_BYTES` + skipped-row* pattern when the source bounds the item count (paginated JSON: Jira, Linear, Sentry, Slack, Zendesk, Gmail, ...). Every response body is still read through `readBodyWithLimit` with a connector-specific budget (`MAX_DOCS_RESPONSE_BYTES` in google-docs, `MAX_CONTENT_BYTES` in google-sheets, a remaining-bytes budget in notion). Confluence attachments use the full file pattern.
 
 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.
 
diff --git a/.agents/skills/migrate-application-operation/SKILL.md b/.agents/skills/migrate-application-operation/SKILL.md
index 25774902091..cb27c518f12 100644
--- a/.agents/skills/migrate-application-operation/SKILL.md
+++ b/.agents/skills/migrate-application-operation/SKILL.md
@@ -166,7 +166,7 @@ Do not create internal-, public-, or Copilot-specific versions of the same seman
 
 Choose principal kinds from actual behavior. Do not accept every principal merely because the use case is shared. Workspace API keys have a write ceiling and cannot satisfy admin operations. The operation definition must fail fast when its role, workspace-key policy, and principal kinds disagree.
 
-`capability` is required — name the permission-group capability that governs the operation, or `'none'` with a `// permission-group-exempt: <reason>` comment directly above it. `defineWorkspaceOperation` throws at definition time when it is absent. See `add-permission-group-item`.
+`capability` is required: a static, operation-declarable capability (not parameterized, not principal-wide), or `'none'` with a `// permission-group-exempt: <reason>` comment directly above it. If `principalKinds` includes `oauth_access_token`, `oauthScope` (`api:read` | `api:write` | `search:read`) is required. `defineWorkspaceOperation` throws at definition time on any violation. See `add-permission-group-item`.
 
 Route declarations, tool adapters, and use cases must use the same literal operation. Runtime operation selection is permitted only from a trusted, code-defined registry. Never accept an operation ID or permission tag from an HTTP body, model argument, or other untrusted input.
 
@@ -317,7 +317,7 @@ Stop and report a missing design rather than weakening identity, authorization,
 
 ## Test each risk at one boundary
 
-Run the `test-audit` authoring gate before writing any test. Own each risk at exactly one boundary:
+Run the `test-audit` authoring gate before writing any test. Prefer one E2E/integration run over the real boundary; where a use-case unit test is justified, list its failure modes before writing code (CLAUDE.md → Testing). Own each risk at exactly one boundary:
 
 - Application use-case tests own authorization, principal-kind rejection before canonical loading, workspace assertion mismatch, delegated scope, not found, conflict, no-op, audit derived from authoritative results, and infrastructure failures (storage, rate-limit, provider, or database errors raised by delegated services) propagating as 5xx-mapped errors — never converted to not-found or forbidden.
 - One `*.integration.ts` owns repository semantics: canonical active lookup, workspace-predicated writes, archived resources, authoritative affected rows, and database error propagation.
@@ -335,7 +335,7 @@ Run at minimum:
 bun run --cwd apps/sim test <focused test files>
 bunx biome check <changed source and test files>
 bunx turbo run type-check --filter=@sim/app --filter=@sim/auth
-bun run check:api-validation:strict
+bun run check:audits
 git diff --check
 ```
 
diff --git a/.agents/skills/ship/SKILL.md b/.agents/skills/ship/SKILL.md
index 39fdae0dd29..ce9afd45e4f 100644
--- a/.agents/skills/ship/SKILL.md
+++ b/.agents/skills/ship/SKILL.md
@@ -45,6 +45,7 @@ When the user runs `/ship`:
   - Then run root `bun run test` from the repo root. It chains `test:scripts` (the `scripts/*.test.ts` suite CI runs) before every workspace suite; workspace-scoped runs skip it, which is how a `scripts/check-*.test.ts` failure has reached CI. A failing test aborts ship.
 5. **Run migration safety** — only if the diff touches `packages/db/migrations/**` or `packages/db/schema.ts`:
   - Run `/db-migrate` to review the migration for zero-downtime safety (expand/contract phasing, backward-compatibility with the deployed app version).
+  - `cd packages/db && bunx drizzle-kit generate` must leave `git status --porcelain packages/db/migrations` empty (CI's schema/migration sync step).
   - `bun run check:migrations origin/staging` must pass (staging is the PR base). Do not silence a flagged statement with a `-- migration-safe:` annotation unless `/db-migrate` confirmed the old code no longer depends on it; otherwise split the destructive change into a later deploy.
 6. **Run pre-ship checks** from the repo root before staging. This has two phases: first **regenerate** every committed artifact so generated files never drift into a CI failure (this is what catches things like `agent-stream-docs` going stale after a `models.ts` edit), then run the **full audit suite** CI's `Lint and Test` job enforces. Both phases parallelize — but only across commands that write **disjoint** outputs — and a bare `wait` swallows child exit codes, so both phases below explicitly collect each job's status and abort ship if any failed.
 
diff --git a/.agents/skills/test-audit/SKILL.md b/.agents/skills/test-audit/SKILL.md
index 31c3f924a03..e7829f4f992 100644
--- a/.agents/skills/test-audit/SKILL.md
+++ b/.agents/skills/test-audit/SKILL.md
@@ -17,19 +17,9 @@ mechanics (global mocks, `@sim/testing`, performance rules).
 
 ## The three rules
 
-1. **Never write unit tests after you write code.** A test written to describe code that already
-   exists restates the implementation, passes on the first run, and proves nothing. If the change
-   needs proof, prove it end to end.
-2. **Prefer E2E tests; use them to verify complex features.** Exercise the real boundary — real
-   Postgres/Redis (`*.integration.ts`), a running app over real HTTP, or the packaged desktop app
-   (Playwright). Every E2E run ends with a **verifiable, repeatable artifact**: a JSON report of
-   checks with pass/fail and durations, an HTTP status log, a trace, or a screenshot, written to a
-   path the caller controls (`<SUITE>_REPORT_PATH`) and uploaded by CI on failure.
-   `apps/sim/scripts/test-scim-e2e.ts` is the reference shape.
-3. **If you must test a system in isolation, write the failure modes down first, then write the
-   code.** List every way the unit can fail (bad input, boundary, concurrency, partial failure,
-   permission denial, resource cap). Each listed mode becomes one test that fails before the code
-   exists. A mode you cannot list is not a test you should write.
+CLAUDE.md → Testing sets them: no unit tests after the code; prefer E2E at the real boundary,
+ending in a verifiable artifact; list failure modes before testing in isolation. A mode you cannot
+list is not a test you should write. This skill enforces them.
 
 ## Authoring gate
 
diff --git a/.agents/skills/tool-registry-boundary/SKILL.md b/.agents/skills/tool-registry-boundary/SKILL.md
index af54a09ad35..779fe6e3d2c 100644
--- a/.agents/skills/tool-registry-boundary/SKILL.md
+++ b/.agents/skills/tool-registry-boundary/SKILL.md
@@ -18,7 +18,7 @@ through `lib/internal/tool-operations/registry.server.ts`. Request closures can
 clients, API helpers, and parsers, which is what makes the executable barrel expensive: reaching it
 costs roughly 4,700 additional modules (measured; re-measure with `--verbose`).
 
-`getTool()` returns the whole `ToolConfig`, so a single `getTool` import anywhere in a client-reachable file drags all of it in.
+`getTool()` returns the whole `ExecutableToolConfig`, so a single `getTool` import anywhere in a client-reachable file drags all of it in.
 
 ## Which module to import
 
@@ -29,7 +29,7 @@ costs roughly 4,700 additional modules (measured; re-measure with `--verbose`).
 | every tool id | `getToolIds` from `@/tools/tool-ids` | |
 | a tool's params | `getToolParams` / `getToolMetadata` from `@/tools/metadata` | ~4 MB |
 | a tool's declared outputs | `getToolOutputsMetadata` from `@/tools/metadata-outputs` | ~4 MB, separate on purpose |
-| to **execute** a tool | `getTool` from `@/tools/utils`, or `@/tools/utils.server` | server paths only |
+| to **execute** a tool | `getTool` from `@/tools/utils`, or `getToolAsync` from `@/tools/utils.server` (async/workspace-context lookup) | server paths only |
 
 Three modules, cheapest first. Ids are their own artifact because resolution and existence checks need only the key set; outputs are their own because they are the larger half of the data with a single consumer. `@/tools/metadata` and `@/tools/metadata-outputs` both resolve ids through `@/tools/tool-ids`, which is what keeps them independent of each other — do not "helpfully" re-export one from another, or every caller pays for all three.
 
@@ -46,7 +46,7 @@ bun run tool-metadata:check      # what CI runs; fails if stale
 
 Never hand-edit them. If you add a tool or change a tool's `params`/`outputs`, regenerate and commit the result, or CI fails.
 
-Three non-obvious properties, each of which was measured and is easy to undo by accident:
+Four non-obvious properties, each of which was measured and is easy to undo by accident:
 
 - **The data is a JSON string parsed at runtime, not an imported `.json` and not an object literal.** With `resolveJsonModule` (which this repo enables), a `.json` import makes TypeScript infer a literal type for all 5,000+ entries and takes `tsc --noEmit` from **12.6s to 8m07s** — a 38x regression. An ambient `declare module` does *not* short-circuit it, and an object literal costs the same. A single string literal is one cheap token for both the compiler and the bundler, and `JSON.parse` beats evaluating the equivalent literal at runtime. Do not "clean this up" into a `.json` import.
 - **The generator refuses to emit function values.** If you add a field to `METADATA_FIELDS` that contains a closure, generation fails loudly rather than shipping executable config to the client. `hosting` and `schemaEnrichment` are excluded for exactly this reason (`hosting.enabled`, `pricing`, and `enrichSchema` are functions) — they are server-only.
@@ -55,25 +55,25 @@ Three non-obvious properties, each of which was measured and is easy to undo by
 
 ## Testing code that reads tool metadata
 
-Mock the module the code under test actually reads. `vi.mock('@/tools/utils', () => toolsUtilsMock)` only controls `getTool`; code that reads `params`/`outputs`/`name` goes through `@/tools/metadata`, so mocking `tools/utils` there is a **no-op that still passes** — because the real generated artifacts happen to agree with the mock fixtures. The test looks green while controlling nothing.
+Mock the module the code under test actually reads. `@/tools/metadata` and `@/tools/metadata-outputs` are mocked globally in `apps/sim/vitest.setup.ts` and return `undefined`; never `vi.mock` them again (`check:test-patterns` fails a `global-remock`). Install fixtures on the global mock instead:
 
 ```ts
-import { blocksMock, toolsMetadataMock, toolsUtilsMock } from '@sim/testing/mocks'
+import { toolsMetadataMock } from '@sim/testing/mocks/blocks.mock'
+import { getToolMetadata } from '@/tools/metadata'
 
-vi.mock('@/tools/utils', () => toolsUtilsMock)      // executable lookup
-vi.mock('@/tools/metadata', () => toolsMetadataMock) // params / outputs / name
+vi.mocked(getToolMetadata).mockImplementation(toolsMetadataMock.getToolMetadata)
 ```
 
-Both are backed by the same `mockToolConfigs`, so mocking both gives one consistent tool universe. If you are unsure whether a mock is load-bearing, change a fixture value to a sentinel and confirm the test fails.
+Do the same for `getToolParams`. `vi.mock('@/tools/utils', () => toolsUtilsMock)` controls only `getTool`. Both mocks share `mockToolConfigs`, so together they give one consistent tool universe. If you are unsure whether a mock is load-bearing, change a fixture value to a sentinel and confirm the test fails.
 ## The guard
 
-`bun run check:tool-registry-boundary` (CI: "Tool registry client-boundary audit") walks the module graph from each workspace route and fails if `@/tools/registry` is reachable, printing the exact import chain that reintroduced it.
+`bun run check:tool-registry-boundary` (run in CI by `check:audits`) walks the module graph from each workspace route and fails if `@/tools/registry` is reachable, printing the exact import chain that reintroduced it.
 
-If it fails, do not add the entry to an allowlist — there isn't one. Find the symbol the offending file actually needs and move it to a registry-free module, exactly as `mergeToolParameters` and `formatParameterLabel` were.
+If it fails, do not add the entry to an allowlist — there isn't one. Find the symbol the offending file actually needs and move it to a registry-free module (e.g. `tools/merge-params.ts`).
 
 Run it with `--verbose` to print per-route module counts, which is also the quickest way to see whether a change moved the graph.
 
-The same command also ratchets those counts against `check-tool-registry-boundary.baseline.json`. `--check` (what CI runs) fails when an entry exceeds its baseline by more than `max(25 modules, 2%)`, naming the import chain responsible. This catches bloat the registry rule misses — a prefetch importing `listTables` cost the Tables page 444 modules without ever touching `@/tools/registry`.
+The same command also ratchets those counts against `check-tool-registry-boundary.baseline.json`. `--check` (what CI runs) fails when an entry exceeds its baseline by more than `max(25 modules, 2%)`, naming the import chain responsible. The baseline also catches graph growth that never touches `@/tools/registry`.
 
 Re-record with `--update-baseline` and commit the JSON when growth is deliberate. A *shrink* passes but is reported — re-record then too, or the win is silently spendable again.
 
@@ -85,16 +85,7 @@ Do not eyeball imports — the registry is reached through several redundant pat
 2. Check whether `apps/sim/tools/registry.ts` is in the reachable set, and print the parent chain if it is.
 3. Compare the reachable module count before and after.
 
-Reference points measured on this repo:
-
-| entry | modules |
-| --- | --- |
-| `tools/registry.ts` reachable | ~4,900 |
-| `tools/merge-params.ts` (leaf) | 2 |
-| `providers/utils.ts` after cutting its `params` edge | 22 |
-| `app/workspace/[workspaceId]/w/page.tsx` (canvas) | 6,592 before, 1,908 after |
-
-The canvas route reached the registry through **four** redundant edges — `providers/utils` (via `tools/params`), `lib/workflows/blocks/block-outputs`, `lib/workflows/sanitization/validation`, and `serializer/index`. Cutting any one alone moved the module count by ~1. They all had to go before anything improved; measure the route, not the file you edited.
+A route can reach the registry through several redundant edges; cutting one changes nothing until all are gone, so measure the route, not the file you edited.
 
 ## When adding a new caller
 
diff --git a/.agents/skills/v2-api-conventions/SKILL.md b/.agents/skills/v2-api-conventions/SKILL.md
index b177330a771..1e4c8ee25eb 100644
--- a/.agents/skills/v2-api-conventions/SKILL.md
+++ b/.agents/skills/v2-api-conventions/SKILL.md
@@ -16,15 +16,7 @@ failure (always)      { "error": { "code": "...", "message": "...", "details"?:
 
 Nothing else at the top level. No `success: true`, no bare `{ "error": "string" }`, no HTML.
 
-That promise is worth stating as a rule because it has been broken five separate ways, each time by a route or a builder taking a shortcut that looked local:
-
-- `GET /workflows?limit=1.5` returned **500**. The contract was copied from a sibling and lost its `.int()`, so a fractional limit passed validation and reached Postgres as `LIMIT 2.5`.
-- A malformed JSON body returned **`{"error":"Request body must be valid JSON"}`** — a bare string. The envelope was a per-route opt-in that only 8 routes remembered.
-- `GET /api/v2/nonexistent` returned a **full HTML 404 document**, because no route file matched and the request fell through to the app's global not-found page.
-- Four collections returned `nextCursor` while **silently discarding** any `limit` the caller sent, because Zod strips unknown keys unless the schema is `.strict()`.
-- Handing back a `nextCursor` from any timestamp-sorted list and passing it straight in returned **500**. The value was validated and bound — but bound with no SQL type, into `date_trunc`, which is overloaded, so Postgres could resolve no overload. Validation was never the missing half; the type was.
-
-Each was one line. The rules below are the generalisations.
+Each rule below guards a caller-visible failure: a non-integer `limit` reaching SQL, a non-envelope error body, an HTML 404 for unknown paths, an unapplied `limit` stripped by non-strict Zod, and an untyped bound parameter into an overloaded SQL function.
 
 ## Where the machinery lives
 
@@ -38,11 +30,11 @@ Each was one line. The rules below are the generalisations.
 
 ## Rule 1 — the envelope is produced by helpers, never by hand
 
-`v2Data`, `v2CursorList`, and `v2Error` in `response.ts` are the only things that build a v2 body. They also set `Cache-Control: private, no-store`, which every v2 response needs because every v2 response is authed per-caller data.
+`v2Data`, `v2Error`, and the typed error helpers in `response.ts` (`v2ValidationError`, `v2RateLimitError`, `v2HttpError`) are the only things that build a v2 body. They also set `Cache-Control: private, no-store`, which every v2 response needs because every v2 response is authed per-caller data.
 
 A route built with `defineV2JsonRoute` gets this for free: its `present` returns the *body shape* and the builder renders it. Never call `NextResponse.json` from a v2 route.
 
-**The envelope must hold for every failure mode, including the ones that happen before your handler runs.** That is what the four bugs above have in common. Defaults for the transport-level failures live on the builder — `v2PayloadTooLargeResponse` (413) and `v2InvalidJsonResponse` (400) — precisely so a route cannot forget them.
+**The envelope must hold for every failure mode, including the ones that happen before your handler runs.** Defaults for the transport-level failures live on the builder — `v2PayloadTooLargeResponse` (413) and `v2InvalidJsonResponse` (400) — precisely so a route cannot forget them.
 
 ## Rule 2 — status codes mean specific things
 
@@ -62,7 +54,7 @@ Two of these carry real design weight:
 
 **404 is deliberately overloaded.** A workspace the caller cannot reach answers `404 "Workspace not found"`, never 403 — a 403 would confirm the resource exists. `createV2ResourceConcealmentPolicy` does this by mapping a cross-tenant authorization failure to `v2Error('NOT_FOUND', ...)`. The unknown-path catch-all at `app/api/v2/[[...segments]]/route.ts` answers with the same body on purpose.
 
-**500 is never caller-reachable.** Any input a caller can send must be rejected at the contract boundary with a 400. If you can construct a query string or body that produces a 500, that is a bug in the contract, not something to wrap in a `try`/`catch`. `v2ErrorForOrchestration` also replaces the message on an unclassified failure with a generic one, so internal detail never leaks. A caller-reachable 500 has shipped three times — a fractional `limit` reaching `LIMIT 2.5`, a plain `HEAD` tripping the builder's method guard, and a keyset cursor's timestamp reaching `date_trunc` as an untyped placeholder — so treat "a well-formed request produced a 500" as the highest-severity class of defect on this surface.
+**500 is never caller-reachable.** Any input a caller can send must be rejected at the contract boundary with a 400. If you can construct a query string or body that produces a 500, that is a bug in the contract, not something to wrap in a `try`/`catch`. `v2ErrorForOrchestration` also replaces the message on an unclassified failure with a generic one, so internal detail never leaks. Treat any well-formed request that produces a 500 as the highest-severity defect on this surface: non-integer numerics, `HEAD` on a `GET` route, and untyped placeholders into SQL functions are the known shapes.
 
 **Validating a value is only half of it; the value also has to reach SQL with a type.** A bound parameter arrives as `unknown` and takes its type from context. Against a typed column (`sort_order > $1`) that inference always succeeds, which is why the gap stays invisible almost everywhere — but as an argument to an overloaded function it can resolve to nothing at all. So: **if a bound value is an argument to a SQL function rather than one side of a comparison, write its type down** (`lib/api/list-query.ts`, `timestampKey`, casts from the column).
 
@@ -75,11 +67,11 @@ And this class survives a green test suite — `keysetAfter` returned well-forme
 
 **A 403 a caller can act on names its cause in `error.details.code` — but not every 403 does yet.** One status covers several different remedies — raise a member's role, issue a personal key instead of a workspace-scoped one, re-point a workspace key, buy an enterprise plan, delete a resource to get under a quota — and prose is not branchable, so a client that must tell them apart was string-matching messages, which turns every reword into a silent break. A handful of domain refusals still throw a bare `OrchestrationError('forbidden', …)` and reach the wire with no code, so **write client code that treats `details.code` as optional**, and read `openapi/shared.ts`'s `FORBIDDEN_DESCRIPTION` for the current position rather than assuming the sweep is finished. For code you are *writing*, the rule below is unconditional.
 
-The vocabulary is a closed set, `FORBIDDEN_DETAIL_CODES` in `lib/core/application/forbidden.ts`, with a `Record` of descriptions beside it that the generated OpenAPI 403 description is built from. Adding a member fails to compile until it is documented, so a code cannot reach the wire unpublished. Do not invent a code at a route: throw `ForbiddenOperationError(code, message)` from the domain and let `v2CaughtOrchestrationError` — the function every v2 error policy falls through to — attach it. `InsufficientWorkspacePermissionsError`, `PersonalApiKeysDisabledError`, `WorkspaceApiKeyAuthorizationError`, and `PrincipalKindAuthorizationError` already carry theirs.
+The vocabulary is the closed tuple `FORBIDDEN_DETAIL_CODES` in `lib/core/application/forbidden.ts` (each member TSDoc-documented), published to OpenAPI as the `V2ForbiddenDetailCode` enum via `v2ForbiddenDetailCodeSchema`. A new code needs a documented entry there and is warranted only when the remedy differs. Do not invent a code at a route: throw `ForbiddenOperationError(code, message)` from the domain and let `v2CaughtOrchestrationError` — the function every v2 error policy falls through to — attach it. `InsufficientWorkspacePermissionsError`, `PersonalApiKeysDisabledError`, `WorkspaceApiKeyAuthorizationError`, and `PrincipalKindAuthorizationError` already carry theirs.
 
 The cross-tenant refusals (`NoWorkspaceAccessError`, `WorkspaceApiKeyScopeAuthorizationError`, `DelegatedWorkspaceAuthorizationError`) deliberately carry **no** code. They are concealed as 404, and naming their cause would hand back the resource-existence signal the concealment exists to withhold.
 
-Use the shared sets in `contracts/v2/openapi/shared.ts` — `RESOURCE_ERRORS`, `RESOURCE_CONFLICT_ERRORS`, `RESOURCE_MUTATION_ERRORS` — rather than assembling a per-operation list; all three already include `Forbidden`, and hand-assembled lists are how three knowledge reads and three upload operations quietly lost it.
+Use the shared sets in `contracts/v2/openapi/shared.ts` — `RESOURCE_ERRORS`, `RESOURCE_CONFLICT_ERRORS`, `RESOURCE_MUTATION_ERRORS` — rather than assembling a per-operation list; all three already include `Forbidden`, which hand-assembled lists drop.
 
 **HEAD is answered by the `GET` handler, not rejected.** Next aliases a missing `HEAD` export onto `GET` and drops the body when sending, so a route's `GET` legitimately runs with `request.method === 'HEAD'`. The builders' method guard accepts that pairing via `methodMatchesContract`; any other mismatch stays a hard error. Never hand-write a `HEAD` export to "fix" this.
 
@@ -95,7 +87,7 @@ Build the query slice from the shared helper, never by hand:
 ...v2PaginationFields({ description: 'Maximum widgets to return per page.' })
 ```
 
-That gives `limit` (integer, 1..`V2_MAX_PAGE_SIZE`, defaulting to `V2_DEFAULT_PAGE_SIZE` = 50) and an opaque `cursor`. Re-declaring `limit: z.coerce.number()...` inline is how the 500 happened; there is one schema so the family cannot drift again.
+That gives `limit` (integer, 1..`V2_MAX_PAGE_SIZE`, defaulting to `V2_DEFAULT_PAGE_SIZE` = 50) and an opaque `cursor`. Never re-declare `limit: z.coerce.number()...` inline; inline schemas drift from `.int()`.
 
 Three cursor schemes exist. Two are the shared codecs in `response.ts`, both opaque base64-JSON, and which of them you use is decided by what the read can express, not by taste:
 
@@ -120,7 +112,7 @@ Before documenting a second `order`-style exception, check every other endpoint
 
 ## Rule 4 — reject what you do not implement
 
-**Every contract declares a `query`, even when the endpoint takes none** — `query: noInputSchema` (`z.object({}).strict()`), never omission. `parseRequest` validates the query slice only when the contract declares one, so an omitted `query` means "never look at the query string", not "takes no query params". The two were indistinguishable, which is how 69 contracts ended up accepting anything without anyone deciding they should: `GET /workflows/{id}?bogus=1` answered 200 while every list answered 400 for the same shape. `query-declaration.test.ts` sweeps the tree so contract 70 fails at authoring time rather than shipping unvalidated.
+**Every contract declares a `query`, even when the endpoint takes none** — `query: noInputSchema` (`z.object({}).strict()`), never omission. `parseRequest` validates the query slice only when the contract declares one, so an omitted `query` means "never look at the query string", not "takes no query params". An omitted `query` silently accepts any query string; `query-declaration.test.ts` fails a contract that omits it.
 
 Unknown query params are a 400. That is safe for first-party callers — the two SDKs send only `includeOutput`/`selectedOutputs`, both declared; the UI makes no v2 calls; `requestJson` appends nothing implicitly and there is no v2 cache buster — and it matches the already-strict body slice. Third-party callers appending a tracking tag or cache buster do break, which is why `api-reference/getting-started.mdx` documents the behavior rather than leaving it to be discovered from a 400.
 
@@ -240,7 +232,7 @@ Run this against any new or changed v2 endpoint.
 - [ ] Validation messages name the field and echo the valid set.
 - [ ] Response schema matches every field the route actually emits.
 - [ ] OpenAPI description regenerated and truthful about pagination.
-- [ ] `bun run type-check`, `bun run check:api-validation`, `bun run check:openapi` pass.
+- [ ] `bun run type-check` (apps/sim) and `bun run check:audits` pass (includes `check:api-validation:strict`, `check:openapi`, `check:v2-route-table`, `check:cli-api`, `check:mcp-operations`).
 
 ## Known gap
 
diff --git a/.agents/skills/validate-permission-group-item/SKILL.md b/.agents/skills/validate-permission-group-item/SKILL.md
index 9422ddbe6c5..0dbf2c7913f 100644
--- a/.agents/skills/validate-permission-group-item/SKILL.md
+++ b/.agents/skills/validate-permission-group-item/SKILL.md
@@ -10,7 +10,7 @@ The question is not "does this key exist in the right places" — the registry m
 
 > **If an organization admin sets this, what refuses, and can I make that refusal happen?**
 
-Twelve keys once shipped with a checkbox, a hint, and no server check. Every one would have passed a structural audit. Assume nothing enforces until you have found the throw.
+A key with an admin checkbox but no server gate passes every structural audit. Assume nothing enforces until you have found the throw.
 
 **`add-permission-group-item` owns the procedure and the rationale for every invariant named below.** Read it for *why*; this skill is the checklist. Its "Read the system first" list is the same one — start there.
 
@@ -19,7 +19,7 @@ Twelve keys once shipped with a checkbox, a hint, and no server check. Every one
 Record the builder, the `enforcement`, and the position.
 
 - **Default permissive?** The builders hardcode `false` / `null` / `[]`, so the risk is a *name* that inverts the meaning — an `allowX` boolean. The checkbox renders `checked={!editingConfig[feature.configKey]}` (ticked = allowed), so a positively-named boolean renders backwards.
-- **Position stable?** Declaration order is the wire order and `fields.test.ts` pins it with a key-order contract test. If `git log -p` shows the key was ever *moved* rather than appended, that shipped as an editor dirty-check regression.
+- **Position stable?** Declaration order is the wire order, and no test catches a reorder. If `git log -p` shows the key was ever *moved* rather than appended, every open editor reads as unsaved (`group-detail.tsx` dirty-checks stringified configs).
 - **Phrasing accurate?** An allowlist's `{ limited, empty }` and a denylist's string are read by `getActivePermissionGroupRestrictions` in `features.ts` and surface to users through the Copilot workspace VFS and the enterprise platform context. Confirm `empty` says "none allowed", not "unrestricted".
 - **Does the `hint` tell the truth?** Highest-value read in this step. A `'capability'` key refuses at the API, so a hint saying it hides a tab, module, or nav item "from the sidebar" is a **lie an admin acts on** — they believe they are tidying chrome while withholding a module. The same string is reused as the prose for an *active* restriction, where "hide" is simply false. Any surviving "Hide the …" hint on a `'capability'` key is a finding, not a nit; check `label` and `category` the same way (a "Sidebar" or "Settings Tabs" section makes the claim structurally).
 
@@ -60,7 +60,7 @@ A `'capability'` key must appear in some rule's `configKeys` — the audit asser
 - **`configKeys` lists every key `deniedBy` reads.** The audit parses it textually and never reads the closure; a key read but unlisted is invisible to D and E.
 - **`kind` is right.** A rule needing a request value must be `'parameterized'` — and a parameterized rule named on an operation cannot have run in production (`defineWorkspaceOperation` throws at definition time), so something else is wrong.
 - **A narrower capability subsumes the broader one it replaced.** An operation carries exactly one capability. Precedent: `knowledge.create` / `knowledge.upload` both read `hideKnowledgeBaseTab`, without which a group withholding the whole module could still create a KB through the API. Check `git log` for a re-pointed `capability:` and verify the narrower rule grew the broader key in the same commit.
-- **`detailCode` matches the remedy** — `FORBIDDEN_DETAIL_CODES` is closed over remedies, not causes; otherwise `PERMISSION_GROUP_CAPABILITY_BLOCKED`. Any code in use needs an entry in `FORBIDDEN_DETAIL_CODE_DESCRIPTIONS`, a compile-time gate that also publishes the OpenAPI 403 text.
+- **`detailCode` matches the remedy** — `FORBIDDEN_DETAIL_CODES` is closed over remedies, not causes; otherwise `PERMISSION_GROUP_CAPABILITY_BLOCKED`. Any code in use needs a TSDoc-documented entry in `FORBIDDEN_DETAIL_CODES`, published to OpenAPI as the `V2ForbiddenDetailCode` enum.
 - **`describe` reads correctly** as the subject of `"<describe> is not available under your organization's permission group"` — a singular noun or gerund agreeing with "is". Exactly two functions build that sentence, both defined in `capabilities.ts` (`refuseCapability` throws it, `capabilityRefusal` returns it); any call site writing it out is a drift finding.
 
 ## Step 5: Prove the enforcement — do not assume it
@@ -82,9 +82,9 @@ Classify into exactly one of:
 4. **A field projection, not a gate.** `logs.trace_spans` and `logs.cost` withhold fields, so the logs routes correctly declare `capability: 'none'`. Single owner: `lib/logs/log-projection.ts` (`resolveLogFieldProjection`, `projectExecutionData`, `projectCostTotal`), which carries both annotations. A **second** implementation of the same redaction is the finding — as is a query that lets a caller filter or sort on a withheld field, which turns the projection into an oracle.
 5. **Nothing.** Report as a defect: "an organization that sets this believes it applied a restriction that does not exist".
 
-Ahead of all five: `personal_api_key.use` fits none of them. It withholds a *principal kind* across every operation — the funnel's `personal_api_key` branch (`lib/core/application/workspace-authorization.ts`) and `app/api/v1/middleware.ts` — so no operation declares it and `disablePersonalApiKeys` being absent from every `capability:` field is correct, not a hole.
+Ahead of all five: the principal-wide capabilities (`personal_api_key.use`, `oauth_apps.use`; `PRINCIPAL_WIDE_CAPABILITIES` in `lib/core/application/operation.ts`) fit none of them. They withhold a *principal kind* across every operation — the funnel's `personal_api_key` / `oauth_access_token` branches (`lib/core/application/workspace-authorization.ts`) and `app/api/v1/middleware.ts` — and declaring one on an operation throws, so their absence from every `capability:` field is correct, not a hole.
 
-Then **make the refusal happen**: write a failing case, or remove the gate (the `capability:` field, the `deniedBy` body, the assertion call) and confirm an existing test goes red. A test that still passes with the gate removed proves nothing. Restore afterward. **Check the fixture's `workspaceOrganizationId` first**: `requireCapability` short-circuits when it is `null` (`lib/core/application/workspace-authorization.ts:204`), so a context that leaves it unset passes either way and the existing test proves nothing even before you touch it.
+Then **make the refusal happen**: write a failing case, or remove the gate (the `capability:` field, the `deniedBy` body, the assertion call) and confirm an existing test goes red. A test that still passes with the gate removed proves nothing. Restore afterward. **Check the fixture's `workspaceOrganizationId` first**: `requireCapability` short-circuits when it is `null` (`requireCapability` in `lib/core/application/workspace-authorization.ts`), so a context that leaves it unset passes either way and the existing test proves nothing even before you touch it.
 
 For an allowlist the three states must be tested separately — `null` permits every member, a populated list only the named ones, `[]` permits **none**. `capabilities.test.ts` pins all three for `knowledge.connectors`; less than that elsewhere is a gap.
 
@@ -124,7 +124,7 @@ check:capability-subject — <N> v1 files, <M> capability subjects resolved thro
 | Audit | What it catches |
 |---|---|
 | `check:permission-group-enforcement` | Every operation declares a capability and every capability is enforced. All-or-nothing — no migration mode exits 0 with work outstanding, so do not go looking for a `pending enforcement:` list |
-| `check:application-graph` | The funnel roots (`lib/core/application/index.ts`, `capabilities.ts`, `capability-assertions.ts`, `config-scope.server.ts`) and `with-route-handler.ts` reach no heavy module tree at *runtime* (`import type` is erased and allowed). A gate that imports a resolver into a guarded root is a finding even if the gate is correct; past regressions surfaced only as unrelated tests failing on partial mocks |
+| `check:application-graph` | The funnel roots (`lib/core/application/index.ts`, `capabilities.ts`, `capability-assertions.ts`, `config-scope.server.ts`) and `with-route-handler.ts` reach no heavy module tree at *runtime* (`import type` is erased and allowed). A gate that imports a resolver into a guarded root is a finding even if the gate is correct; a broken edge shows up only as unrelated tests failing on partial mocks |
 | `check:capability-subject` | Every v1 capability sink takes its subject from `capabilityGovernedUserId`, no v1 file outside the middleware imports the permission-group modules, and at least one governed sink was found at all |
 
 Two ways the enforcement audit passes without proving what you want:
diff --git a/.claude/rules/sim-testing.md b/.claude/rules/sim-testing.md
index d19efd158fe..996b5106ae6 100644
--- a/.claude/rules/sim-testing.md
+++ b/.claude/rules/sim-testing.md
@@ -36,7 +36,7 @@ contracts, and demonstrated regressions.
 | `*.integration.ts` | real PostgreSQL (`TEST_DATABASE_URL`), optionally Redis (`TEST_REDIS_URL`) | `vitest run --mode integration` | `PostgreSQL integration` job, by glob |
 | `*.live.test.ts` | provider APIs, hosted sandboxes, local runtimes, or sibling checkouts | `vitest run --mode live <file>` (apps/sim) | never |
 | `apps/desktop/e2e/*.spec.ts` | the packaged Electron app | Playwright | desktop E2E workflow |
-| `apps/sim/scripts/test-*-e2e.ts` | a running app over HTTP | `bun run test:<suite>:e2e` | PostgreSQL integration job |
+| `apps/sim/scripts/test-*-e2e.ts` | a running app over HTTP | `bun scripts/test-<suite>-e2e.ts` from apps/sim (`bun run test:scim:e2e` for SCIM) | End-to-end over real HTTP job |
 
 - A unit test lives next to its source: `feature.ts` → `feature.test.ts`. No network, no database,
   no real timers.
diff --git a/.cursor/rules/sim-testing.mdc b/.cursor/rules/sim-testing.mdc
index 76de6f203dd..5411f0bac5d 100644
--- a/.cursor/rules/sim-testing.mdc
+++ b/.cursor/rules/sim-testing.mdc
@@ -34,7 +34,7 @@ contracts, and demonstrated regressions.
 | `*.integration.ts` | real PostgreSQL (`TEST_DATABASE_URL`), optionally Redis (`TEST_REDIS_URL`) | `vitest run --mode integration` | `PostgreSQL integration` job, by glob |
 | `*.live.test.ts` | provider APIs, hosted sandboxes, local runtimes, or sibling checkouts | `vitest run --mode live <file>` (apps/sim) | never |
 | `apps/desktop/e2e/*.spec.ts` | the packaged Electron app | Playwright | desktop E2E workflow |
-| `apps/sim/scripts/test-*-e2e.ts` | a running app over HTTP | `bun run test:<suite>:e2e` | PostgreSQL integration job |
+| `apps/sim/scripts/test-*-e2e.ts` | a running app over HTTP | `bun scripts/test-<suite>-e2e.ts` from apps/sim (`bun run test:scim:e2e` for SCIM) | End-to-end over real HTTP job |
 
 - A unit test lives next to its source: `feature.ts` → `feature.test.ts`. No network, no database,
   no real timers.

From ac9bded8652abf0b421d9d66a86347ccb202218f Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Thu, 1 Oct 2026 17:19:38 -0700
Subject: [PATCH 07/18] docs(agents): align UI skills with the settings, emcn,
 and state rules

add-settings-page's audit greps used a pathspec that matches nothing, and
its registration steps named types that no longer exist
(SETTINGS_SECTION_REGISTRY and SECTION_MODULES are the mechanism). The
emcn review taught the legacy Button variants and a destructive Delete
chip that sim-settings-pages forbids. The design skills now carry repo
precedence notes (no global styles, emcn owns chrome, framer-motion,
hover-hover:, fixed fonts and weights). The you-might-not-need-* skills
recognize URL state, the list-preference exception, and the Map memo the
component rule prescribes.
---
 .agents/skills/add-settings-page/SKILL.md     | 104 ++++++++----------
 .agents/skills/design-taste-frontend/SKILL.md |   2 +-
 .agents/skills/emcn-design-review/SKILL.md    |  17 +--
 .agents/skills/emil-design-eng/SKILL.md       |   2 +
 .../make-interfaces-feel-better/SKILL.md      |   6 +-
 .../make-interfaces-feel-better/animations.md |   2 +
 .../react-query-best-practices/SKILL.md       |   2 +-
 .../you-might-not-need-a-comment/SKILL.md     |   2 +-
 .../skills/you-might-not-need-a-memo/SKILL.md |   4 +
 .../skills/you-might-not-need-state/SKILL.md  |   3 +-
 .../you-might-not-need-url-state/SKILL.md     |   4 +-
 .claude/rules/sim-settings-pages.md           |  16 +--
 .cursor/rules/sim-settings-pages.mdc          |  16 +--
 13 files changed, 81 insertions(+), 99 deletions(-)

diff --git a/.agents/skills/add-settings-page/SKILL.md b/.agents/skills/add-settings-page/SKILL.md
index 9500ac39c73..0f561f165f6 100644
--- a/.agents/skills/add-settings-page/SKILL.md
+++ b/.agents/skills/add-settings-page/SKILL.md
@@ -21,65 +21,54 @@ Key paths:
 
 ## Mode A — Add a new settings page
 
-1. **Navigation.** In `navigation.ts`: add the id to the `SettingsSection` union,
-   then a `NavigationItem` with `label` AND a one-line `description` (verb-first,
-   ~40–55 chars, product voice per `.claude/rules/constitution.md`). Place it in
-   the right `section` group and set any gating flags (`requiresHosted`,
-   `requiresEnterprise`, etc.).
-2. **Wire the switch.** Add the component to the `effectiveSection` render switch
-   in `settings/[section]/settings.tsx` (lazy `dynamic(...)` like its siblings).
+1. **Navigation.** In `navigation.ts`: add the id to `UnifiedSettingsSection`, then a
+   `SETTINGS_SECTION_REGISTRY` entry with `label`, `icon`, and
+   `unified: { id, description, group, order }` (description verb-first, ~40–55 chars,
+   product voice per `.claude/rules/constitution.md`). Set gating flags
+   (`requiresHosted`, `requiresEnterprise`, …) on `unified`, and add `planes` only if the
+   section also exists on a standalone plane.
+2. **Wire the switch.** Register the module in `SECTION_MODULES`
+   (`settings/section-warmers.ts`), then add
+   `const X = dynamic(() => SECTION_MODULES.x().then((m) => m.X))` and its case in the
+   `effectiveSection` switch in `settings/[section]/settings.tsx`.
 3. **Build the body inside `SettingsPanel`** per the rule's canonical page shape:
    `actions`, `search`, `children`, modal siblings in a fragment.
-4. **If the page has editable state**, wire the shared save/discard stack — put
-   `SaveDiscardActions` (dirty-gated Discard+Save chips) in `actions`, and call
-   `useSettingsUnsavedGuard({ isDirty })` **before any early-return gate**.
-   Detail sub-views additionally route the back chip through
-   `guard.guardBack(closeFn)` and render the shared `UnsavedChangesModal`. Never
-   hand-roll a Save button, a `beforeunload`, or an "Unsaved changes" modal —
-   they're centralized. See the "Save / Discard + unsaved-changes guard" section
-   in `.claude/rules/sim-settings-pages.md`.
-5. **Verify:** `cd apps/sim && bun run type-check`; `bunx biome check --write <file>`.
+4. **If the page has editable state**, wire the shared save/discard stack exactly as in
+   `.claude/rules/sim-settings-pages.md` "Save / Discard + unsaved-changes guard"
+   (`saveDiscardActions()`, `useSettingsUnsavedGuard` before any early return).
+5. **Verify:** the local gate in the root `CLAUDE.md` ("How your work is checked").
 
 ## Mode B — Audit existing settings pages
 
 For each page component, confirm the checklist in `.claude/rules/sim-settings-pages.md`:
 
 1. Find hand-rolled shells that should be `SettingsPanel`:
-   `git grep -n "flex h-full flex-col bg-\[var(--bg)\]" -- 'apps/sim/**/settings/' 'apps/sim/ee/'`
-   — every match should be either `settings-panel.tsx`, a **detail sub-view**
-   (has a `<Chip leftIcon={ArrowLeft}>` back button), or an entitlement/loading
-   **gate** early-return. Anything else is a page that still needs migrating.
-2. Find hand-rolled title blocks (should be 0 outside detail views):
-   `git grep -n "text-\[var(--text-body)\] text-lg" -- 'apps/sim/**/settings/' 'apps/sim/ee/'`
-3. Find literal pixel text sizes (should be 0 — see "Text-scale tokens" in
-   `.claude/rules/sim-settings-pages.md` for the token map and the row
-   title/subtitle pairing convention):
-   `git grep -nE "text-\[1[0-8]px\]" -- 'apps/sim/**/settings/' 'apps/sim/ee/'` — should
-   be 0. Display type above the scale (`text-[40px]` hero headings) is deliberate
-   and out of scope.
-4. Confirm each page imports `SettingsPanel` and that its `NavigationItem` has an
+   `git grep -n "flex h-full flex-col bg-\[var(--bg)\]" -- 'apps/sim/**/settings/**' 'apps/sim/ee/'`
+   — every match should be the settings shell (`settings/layout.tsx`),
+   `CredentialDetailLayout` (the `settings/secrets/[credentialId]` exception), or an
+   entitlement/loading gate. A detail sub-view is never a match: it passes
+   `back={{ text, icon: ArrowLeft, onSelect }}` to `SettingsPanel`. Anything else is a
+   violation: render it through `SettingsPanel`.
+2. Find hand-rolled title blocks (should match only `settings-header.tsx`, the shell):
+   `git grep -n "text-\[var(--text-body)\] text-lg" -- 'apps/sim/**/settings/**' 'apps/sim/ee/'`
+3. Find literal pixel text sizes (should be 0 — see "Text Scale" in
+   `.claude/rules/sim-styling.md`):
+   `git grep -nE "text-\[1[0-8]px\]" -- 'apps/sim/**/settings/**' 'apps/sim/ee/'`.
+   Display type above the scale (`text-[40px]` hero headings) is deliberate and out of
+   scope.
+4. Confirm each page imports `SettingsPanel` and that its registry entry has an
    accurate `description` of consistent length with its peers.
-   - Editable pages: confirm Save/Discard go through `SaveDiscardActions` and
+   - Editable pages: confirm Save/Discard go through `saveDiscardActions()` and
      dirty is wired via `useSettingsUnsavedGuard` (called before early-return
      gates) — flag any hand-rolled Save button, `beforeunload`, or unsaved modal.
-     `git grep -n "beforeunload" -- 'apps/sim/**/settings/' 'apps/sim/ee/'`
+     `git grep -n "beforeunload" -- 'apps/sim/**/settings/**' 'apps/sim/ee/'`
      should only hit the centralized `use-settings-before-unload.ts`.
-5. When migrating a page, change ONLY the structural shell→`SettingsPanel` swap:
-   move header chips to `actions`, the standalone search to `search`, delete the
-   `<h1>` title block, replace the three closing `</div>` (column/scroll/shell)
-   with `</SettingsPanel>`, and keep modal siblings in a `<>` fragment. Do NOT
-   touch handlers, state, queries, conditional rendering, or detail/gate returns.
-   Drop per-page `gap-*`/`pt-*` on the content column in favor of the panel default.
-6. When fixing literal pixel text sizes, replace ONLY the size class with its
-   exact-pixel-equivalent named token (e.g. `text-[12px]` → `text-caption`,
-   never a different size) — this must render pixel-identical, not restyle the
-   page. Leave color tokens (`--text-primary` vs `--text-body`, etc.) untouched
-   unless they're also being changed for an unrelated, deliberate reason.
-7. Remove now-unused imports (`ChipInput`/`Search`) ONLY after grepping that
-   they are not still used elsewhere in the file (e.g. by a detail view).
-8. **Verify the whole sweep:** `bun run type-check`, `biome check` on every touched
-   file, and run the affected pages' tests. Diff each file against the base and
-   confirm the change is purely structural before shipping.
+5. Fix each finding with the smallest structural change that satisfies the checklist;
+   do not touch handlers, state, queries, or gate returns. A pixel-size fix swaps
+   only the size class for its exact-pixel token (`text-[12px]` → `text-caption`).
+6. **Verify the whole sweep:** the local gate in the root `CLAUDE.md`, plus the
+   affected pages' tests. Diff each file against the base and confirm the change is
+   purely structural before shipping.
 
 ## Mode C — Migrate list rows to `SettingsResourceRow`
 
@@ -91,20 +80,13 @@ contract. Then, per page:
    Every match outside `settings-resource-row.tsx` is either a row to migrate or a
    genuinely different shape (multi-line body, tabular columns, a grid) that stays
    bespoke — decide which, and say so.
-2. Replace the row *and* its wrapper: a `<button>`/`<Link>` around the row becomes
-   `onClick`/`href` on the row itself. Wrapping the row is what the primitive
-   exists to stop — it is also invalid HTML once `trailing` holds a control.
-3. Sort the trailing content: interactive → `trailing`, decorative → `badge`.
-   Getting this backwards makes the row's right edge a dead zone.
-4. Add `navigable` only if the row opens a detail page, and `clickLabel` always.
-5. Drop the container's `-mx-2` — the row now owns the bleed. Use
-   `RESOURCE_LIST_STACK` / `RESOURCE_LIST_GRID`; do not hand-write the gap.
-6. Unlike Mode B, this migration **may** change conditional rendering: a
-   `<button disabled={!can}>` becomes `onClick={can ? … : undefined}` +
-   `navigable={can}`, which renders a plain non-interactive row. Verify the gated
-   state has no clickable affordance left.
-7. Check what the old row rendered *beside* the title (a badge, a timestamp, a
+2. Convert the row and its wrapper per "The resource row" (props, `trailing` vs
+   `badge`, bleed, `navigable`/`clickLabel`). Unlike Mode B, this conversion **may**
+   change conditional rendering (a permission gate becomes
+   `onClick={can ? … : undefined}` + `navigable={can}`); verify the gated state has no
+   clickable affordance left.
+3. Check what the hand-rolled row rendered *beside* the title (a badge, a timestamp, a
    transport label). The row's title truncates as one unit, so anything folded
    into it can be ellipsised away — move it to `description` or `badge`.
-8. Verify: `bun run type-check`, `biome check`, the page's tests, and a diff read of
+4. Verify: the local gate, the page's tests, and a diff read of
    every converted block for lost props, conditions, and `key` placement.
diff --git a/.agents/skills/design-taste-frontend/SKILL.md b/.agents/skills/design-taste-frontend/SKILL.md
index 11ad6fa3e86..7b9bc3b6932 100644
--- a/.agents/skills/design-taste-frontend/SKILL.md
+++ b/.agents/skills/design-taste-frontend/SKILL.md
@@ -4,7 +4,7 @@ source: https://github.com/leonxlnx/taste-skill — skills/taste-skill/SKILL.md
 description: Anti-slop frontend skill for landing pages, portfolios, and redesigns. The agent reads the brief, infers the right design direction, and ships interfaces that do not look templated. Real design systems when applicable, audit-first on redesigns, strict pre-flight check.
 ---
 
-> **In this repo:** Tailwind 4 (CSS-first config in `apps/sim/app/_styles/globals.css`); animation via `import { motion } from 'framer-motion'` (not `motion/react` — rewrite every `motion/react` import in the samples below); icons from `@sim/emcn/icons`; colors through the CSS-variable tokens in `.claude/rules/sim-styling.md` (no hardcoded `text-gray-*`/hex/`zinc` utilities, no paired `dark:` utilities). This note overrides any conflicting guidance or code sample anywhere in this file.
+> **In this repo:** Tailwind 4 (CSS-first config in `apps/sim/app/_styles/globals.css`); animation via `import { motion } from 'framer-motion'` (not `motion/react` — rewrite every `motion/react` import in the samples below); icons from `@sim/emcn/icons`; colors through the CSS-variable tokens in `.claude/rules/sim-styling.md` (no hardcoded `text-gray-*`/hex/`zinc` utilities, no paired `dark:` utilities). This note overrides any conflicting guidance or code sample anywhere in this file. Fonts are fixed (Season body, Inter, Martian Mono); never introduce new families. Font weight is only `font-normal`/`font-medium`/`font-semibold`. Elevation uses the `shadow-subtle|medium|overlay|card` tokens. Type size uses named tokens, never `text-[Npx]`. Product forms use `ChipModalField`. Use `bunx`, never `npx`. Do not add GSAP, Lenis, Three, or shadcn. Landing copy and SEO follow `.claude/rules/constitution.md` and `.claude/rules/landing-seo-geo.md`.
 
 # tasteskill: Anti-Slop Frontend Skill
 
diff --git a/.agents/skills/emcn-design-review/SKILL.md b/.agents/skills/emcn-design-review/SKILL.md
index 2f14b66c83c..fef7bf5a1c3 100644
--- a/.agents/skills/emcn-design-review/SKILL.md
+++ b/.agents/skills/emcn-design-review/SKILL.md
@@ -32,7 +32,7 @@ This codebase uses **emcn**, a custom component library built on Radix UI primit
 
 ## Design Tokens
 
-Use CSS variable pattern (`text-[var(--text-primary)]`), never Tailwind semantics (`text-muted-foreground`) or hardcoded colors (`text-gray-500`, `#333`).
+Use CSS variable pattern (`text-[var(--text-body)]`), never Tailwind semantics (`text-muted-foreground`) or hardcoded colors (`text-gray-500`, `#333`).
 
 **Text**: `--text-primary`, `--text-secondary`, `--text-tertiary`, `--text-muted`, `--text-body` (canonical value text), `--text-icon`, `--text-placeholder`, `--text-subtle`, `--text-inverse`, `--text-error`
 **Surfaces**: `--bg`, `--surface-1` through `--surface-7`, `--surface-hover`, `--surface-active`
@@ -42,22 +42,13 @@ Use CSS variable pattern (`text-[var(--text-primary)]`), never Tailwind semantic
 **Shadows**: `shadow-subtle`, `shadow-medium`, `shadow-overlay`, `shadow-card`
 **Badges**: `--badge-*` semantic families (success/error/gray/blue/purple/orange/amber/teal/cyan/pink, each with `-bg`/`-text`)
 
-## Buttons
+## Buttons and chips
 
-Intent-to-variant mapping (read the actual `buttonVariants` in `packages/emcn/src/components/button/button.tsx` for the full variant set — it exposes more than listed here):
-
-| Action | Variant |
-|--------|---------|
-| Toolbar, icon-only | `ghost` |
-| Create, save, submit | `primary` |
-| Cancel, close | `default` |
-| Delete, remove | `destructive` |
-| Selected state | `active` |
-| Toggle | `outline` |
+Header/action chrome is `Chip`/`ChipLink` (variants `primary`, `destructive`, `outline`, `border`, `border-shadow`, bare). Selection and toggles use the `active` prop, never a variant. A single-resource Delete is a plain chip behind `ChipConfirmModal`; `destructive` is only for at-scale actions (`.claude/rules/sim-settings-pages.md` "Deleting a resource"). `Button` is only for icon-only toolbar controls (`ghost`/`quiet`, `size='icon'`).
 
 ## Delete/Remove Confirmations
 
-`ChipModal` `size='sm'`, title "Delete/Remove {ItemType}", destructive confirm button, plain Cancel (follow the chip footer layout in `.claude/rules/emcn-components.md`). Use `text-[var(--text-error)]` for irreversible warnings.
+Use `ChipConfirmModal` (title "Delete/Remove {ItemType}", `confirm={{ label, onClick }}`, which defaults to destructive). Keep its fail-safe `defaultAction='dismiss'` per `.claude/rules/emcn-components.md` "Modal keyboard defaults". Put irreversible-consequence copy in `text`.
 
 ## Toast
 
diff --git a/.agents/skills/emil-design-eng/SKILL.md b/.agents/skills/emil-design-eng/SKILL.md
index 05a5b4991e3..9ac52fe59da 100644
--- a/.agents/skills/emil-design-eng/SKILL.md
+++ b/.agents/skills/emil-design-eng/SKILL.md
@@ -6,6 +6,8 @@ description: This skill encodes Emil Kowalski's philosophy on UI polish, compone
 
 # Design Engineering
 
+> **In this repo:** emcn owns component chrome (press states, tooltip/popover/menu animation, easing): apply these principles by proposing changes in `packages/emcn`, not per call site, and add no global CSS variables or keyframes (CLAUDE.md "Styling and EMCN"). Animation uses `import { motion } from 'framer-motion'`. Gate touch-unsafe hover with the `hover-hover:` Tailwind variant (plain `hover:` is intentionally ungated). `.claude/rules/sim-styling.md` and `.claude/rules/emcn-components.md` win on any conflict.
+
 You are a design engineer with the craft sensibility. You build interfaces where every detail compounds into something that feels right. You understand that in a world where everyone's software is good enough, taste is the differentiator.
 
 ## Core Philosophy
diff --git a/.agents/skills/make-interfaces-feel-better/SKILL.md b/.agents/skills/make-interfaces-feel-better/SKILL.md
index 38e81ff26c4..4e62a1392a8 100644
--- a/.agents/skills/make-interfaces-feel-better/SKILL.md
+++ b/.agents/skills/make-interfaces-feel-better/SKILL.md
@@ -49,7 +49,7 @@ Animate contextual icons with opacity, scale, and blur instead of toggling visib
 
 ### 8. Font Smoothing
 
-Apply `-webkit-font-smoothing: antialiased` to the root layout on macOS for crisper text.
+Apply `-webkit-font-smoothing: antialiased` to the root layout on macOS for crisper text. In this repo, do not add root-level smoothing or other global styles (CLAUDE.md "Styling and EMCN"); raise it as a design-system proposal instead.
 
 ### 9. Tabular Numbers
 
@@ -61,7 +61,7 @@ Use `text-wrap: balance` on headings. Use `text-wrap: pretty` for body text to a
 
 ### 11. Image Outlines
 
-Add a subtle 1px low-opacity outline to images (`outline-black/10` light, `outline-white/10` dark); see surfaces.md.
+Add a subtle 1px low-opacity outline to images; see surfaces.md. In this repo, use the `--border` token (`outline-[var(--border)]`), not raw black/white alphas.
 
 ### 12. Scale on Press
 
@@ -119,7 +119,7 @@ Present changes as markdown tables with **Before** and **After** columns, one ta
 #### Scale on press
 | Before | After |
 | --- | --- |
-| `<button className="...">` | Added `active:scale-[0.96] transition-transform` |
+| `Chip` has no press affordance | Proposed in `packages/emcn/src/components/chip/chip.tsx` (`chipVariants`): `active:scale-[0.96] transition-transform` |
 | `scale(0.9)` on press | Raised to `scale(0.96)` — anything below `0.95` feels exaggerated |
 
 Rows should cite the specific file and the specific property that changed when it isn't obvious from the snippet. If a principle was reviewed but nothing needed to change, omit that table entirely — empty tables add noise.
diff --git a/.agents/skills/make-interfaces-feel-better/animations.md b/.agents/skills/make-interfaces-feel-better/animations.md
index 2c4c8291027..a9aad9bac09 100644
--- a/.agents/skills/make-interfaces-feel-better/animations.md
+++ b/.agents/skills/make-interfaces-feel-better/animations.md
@@ -1,5 +1,7 @@
 # Animations
 
+> In this repo: `import { motion, AnimatePresence } from 'framer-motion'`; never `motion/react`.
+
 Interruptible animations, enter/exit transitions, and contextual icon animations.
 
 ## Interruptible Animations
diff --git a/.agents/skills/react-query-best-practices/SKILL.md b/.agents/skills/react-query-best-practices/SKILL.md
index 0e426b8bd34..801e90f79a7 100644
--- a/.agents/skills/react-query-best-practices/SKILL.md
+++ b/.agents/skills/react-query-best-practices/SKILL.md
@@ -29,7 +29,7 @@ Read these before analyzing:
 Enforce `.claude/rules/sim-queries.md` (key factory with `all` + plural prefixes, `signal` forwarding, named `staleTime` constants reused by prefetches, `keepPreviousData` only on variable keys, `requestJson` boundary). Additionally:
 - Key factories live next to their hooks — except a factory, standalone fetcher/mapper, or `staleTime` constant that a server module (a `prefetch.ts`, route, block, trigger) imports, which must live in a non-`'use client'` module under `hooks/queries/utils/` per `.claude/rules/sim-queries.md` (a `'use client'` export called from the server crashes SSR)
 - Use `enabled` to prevent queries from running without required params
-- Warm data for hover/focus intent with `queryClient.prefetchQuery` and shared `queryOptions`; never temporarily enable a mounted hidden observer, which can remain active after focus restoration and refetch data for closed UI
+- Warm data for hover/focus intent with `prefetchQueryOnIntent(queryClient, sharedQueryOptions)` (`hooks/queries/utils/prefetch-query-on-intent.ts`, which cleans up a speculative failure per `sim-react-performance.md`); never temporarily enable a mounted hidden observer, which can remain active after focus restoration and refetch data for closed UI
 - When gating a query by view or modal state, move every consumer to the active query too: imperative refresh/pagination, loading and error feedback, and data-derived controls must never read a disabled query or placeholder data from a previous key
 - Compose caller-controlled `enabled` options with required-param guards (`Boolean(id) && (options?.enabled ?? true)`). Never spread options after an internal guard, because `{ enabled: true }` can silently re-enable an invalid request.
 - A disabled query can still report `isPending: true`. Aggregate loading state only for queries that are applicable/enabled, or an optional query can hold the whole surface in a permanent loading state.
diff --git a/.agents/skills/you-might-not-need-a-comment/SKILL.md b/.agents/skills/you-might-not-need-a-comment/SKILL.md
index 602ba36cb49..46b7f559b2d 100644
--- a/.agents/skills/you-might-not-need-a-comment/SKILL.md
+++ b/.agents/skills/you-might-not-need-a-comment/SKILL.md
@@ -32,7 +32,7 @@ This codebase's convention: **TSDoc for documentation; an inline `//` only for a
 
 - A `//` comment that explains a **non-obvious why**: a workaround for an upstream bug, an ordering constraint, a perf reason, a spec/edge-case the code can't self-document (`// first-match wins — matches the old find() semantics`).
 - Existing TSDoc `/** ... */` blocks on declarations — leave them (only tighten if verbose).
-- `// boundary-raw-fetch:`, `// double-cast-allowed:`, `// boundary-raw-json:`, `// untyped-response:`, `// migration-safe:`, `// rq-lint-allow:`, `// client-boundary-allow:` and any other `<kebab-tag>: <reason>` annotation a script under `scripts/` greps for, in line-comment or block-comment form (e.g. the `/** svg-path-precision-exception: ... */` directive on icon paths) — these are load-bearing, never touch them.
+- `// boundary-raw-fetch:`, `// double-cast-allowed:`, `// boundary-raw-json:`, `// untyped-response:`, `-- migration-safe:` (SQL migrations), `// rq-lint-allow:`, `// client-boundary-allow:` and any other `<kebab-tag>: <reason>` annotation a script under `scripts/` greps for, in line-comment or block-comment form (e.g. the `/** svg-path-precision-exception: ... */` directive on icon paths) — these are load-bearing, never touch them.
 - `// biome-ignore`, `// eslint-disable`, `// @ts-expect-error` and other tooling directives.
 - `// TODO` / `// FIXME` that point at real, still-open work.
 
diff --git a/.agents/skills/you-might-not-need-a-memo/SKILL.md b/.agents/skills/you-might-not-need-a-memo/SKILL.md
index 6f28c8e5266..5b7d27c79c2 100644
--- a/.agents/skills/you-might-not-need-a-memo/SKILL.md
+++ b/.agents/skills/you-might-not-need-a-memo/SKILL.md
@@ -27,6 +27,10 @@ Read before analyzing:
 6. **React.memo on components that always receive new props**: If the parent always passes new objects, arrays, or callbacks, React.memo's shallow comparison always fails. Fix the parent instead of memoizing the child.
 7. **useMemo for derived state**: If you're computing a value from props or state, just compute it inline during render. React renders are fast. `const fullName = first + ' ' + last` doesn't need useMemo.
 
+## Patterns that ARE correct — do not flag
+
+- A `useMemo` that builds a lookup `Map`/`Set` or a single-pass partition for list rendering (`.claude/rules/sim-components.md` "List-render performance").
+
 ## Steps
 
 1. Read the reference above to understand the two core techniques (move state down, lift content up)
diff --git a/.agents/skills/you-might-not-need-state/SKILL.md b/.agents/skills/you-might-not-need-state/SKILL.md
index 6006a2b3362..e4192fa7c1d 100644
--- a/.agents/skills/you-might-not-need-state/SKILL.md
+++ b/.agents/skills/you-might-not-need-state/SKILL.md
@@ -14,7 +14,7 @@ User arguments: $ARGUMENTS
 
 ## Context
 
-This codebase uses React Query for all server state and Zustand for client-only global state. useState should only be used for ephemeral UI concerns (open/closed, hover, local form input). Server data should never be copied into useState or Zustand — React Query is the single source of truth.
+React Query owns server data, nuqs (URL) owns shareable view-state (tabs, filters, search, sort, pagination, selected id), Zustand owns global client state, and `useState` owns only ephemeral UI (open/closed, hover, local form input). Server data should never be copied into useState or Zustand — React Query is the single source of truth.
 
 ## References
 
@@ -31,6 +31,7 @@ Read these before analyzing:
 4. **Chained useEffect state updates**: Never chain Effects that set state to trigger other Effects. Calculate all derived values in the event handler or inline during render.
 5. **Storing objects when an ID suffices**: Store `selectedId` not a copy of the selected object. Derive the object: `items.find(i => i.id === selectedId)`.
 6. **State that duplicates Zustand or React Query**: If the data already lives in a store or query cache, don't create a parallel useState.
+7. **Shareable view-state in useState**: hand off to `/you-might-not-need-url-state`.
 
 ## Steps
 
diff --git a/.agents/skills/you-might-not-need-url-state/SKILL.md b/.agents/skills/you-might-not-need-url-state/SKILL.md
index 7eeec0b1b37..e23c91fcfdf 100644
--- a/.agents/skills/you-might-not-need-url-state/SKILL.md
+++ b/.agents/skills/you-might-not-need-url-state/SKILL.md
@@ -31,11 +31,11 @@ Read these before analyzing:
 1. **Manual param reads for state**: `useSearchParams().get(...)` or `new URLSearchParams(window.location.search)` used to *read* view-state. Replace with `useQueryState`/`useQueryStates` bound to a `search-params.ts`. (Read-once auth/invite/redirect signals are NOT view-state — the list and the per-surface `new` caveat are in `.claude/rules/sim-url-state.md` "Read-once auth / redirect signals"; leave those on `useSearchParams`.)
 2. **Hand-built query mutation**: constructing a query string + `router.replace`/`router.push` to change a param on the current path. Use a nuqs setter. (A `router.push` that changes the route *path* is fine; an outbound `new URLSearchParams` building an `href`/`window.open`/download/API URL is fine.)
 3. **`window.history.replaceState`/`pushState`** to mutate a param.
-4. **URL state duplicated into a store/useState + synced with an effect** (or a `popstate` listener). The URL is the single source of truth; derive from it, don't mirror it.
+4. **URL state duplicated into a store/useState + synced with an effect** (or a `popstate` listener). The URL is the single source of truth; derive from it, don't mirror it. (Exception: the remembered list-preference snapshot for Files/Tables/Knowledge via `useResourceListPreferences`, per `sim-url-state.md` "Remembered list-preference exception".)
 5. **Objects in the URL**: serializing a `TableDefinition`/`SkillDefinition`/etc. Store the id and derive the object from the loaded list (`items.find(i => i.id === id)`).
 6. **High-frequency / large state in the URL**: cursor, pan/zoom, un-debounced keystrokes, big JSON blobs. Debounce text search via `useDebouncedSearchSetter` (never a local `useState` mirror + reconcile effect, and never inline `limitUrlUpdates` wiring); keep canvas/presence/resize state in Zustand.
 7. **Shareable view-state trapped in `useState`**: a tab/filter/sort/pagination/selected-entity that should be a link but lives in local state. Migrate it to the URL.
-8. **Missing Suspense boundary**: a component newly calling `useQueryState`/`useQueryStates` whose page entry has no `<Suspense>` wrapper (Next.js requires it for `useSearchParams`). Add one with a real-chrome fallback.
+8. **Missing Suspense boundary**: a component newly calling `useQueryState`/`useQueryStates` whose page entry has no `<Suspense>` wrapper (Next.js requires it for `useSearchParams`). Add one whose fallback is the route's `loading.tsx` default export (never `fallback={null}` on a page entry; see `sim-url-state.md` "Suspense boundary").
 9. **`import { z }` for param validation in client code**: use nuqs parsers instead.
 10. **Re-implemented shared wiring**: a hand-rolled `SORT_DIRECTIONS`/default-sort constants/`activeSort` derivation instead of `createSortParams` + `useUrlSort`, or an inline debounced-search setter instead of `useDebouncedSearchSetter`/`useSettingsSearch`.
 
diff --git a/.claude/rules/sim-settings-pages.md b/.claude/rules/sim-settings-pages.md
index 429d07f4963..da5447c642c 100644
--- a/.claude/rules/sim-settings-pages.md
+++ b/.claude/rules/sim-settings-pages.md
@@ -93,17 +93,17 @@ return (
 ## Title + description live in navigation metadata
 
 `apps/sim/components/settings/navigation.ts` is the single source of truth (the
-`settings/navigation.ts` in the route tree is only a re-export shim). Every `NavigationItem` carries a one-line `description`; `SettingsPanel`
+`settings/navigation.ts` in the route tree is only a re-export shim). Every `SETTINGS_SECTION_REGISTRY` entry carries a one-line `description`; `SettingsPanel`
 resolves both via `getSettingsSectionMeta(plane, section)` and the
 `SettingsSectionProvider` the settings shell wraps around the active section.
 
 Adding a new settings page:
 
-1. Add the section id to the `UnifiedSettingsSection` union + a `NavigationItem`
-   (with `label` **and** `description`) in `components/settings/navigation.ts`. Keep descriptions verb-first, one line,
+1. Add the section id to the `UnifiedSettingsSection` union + a `SETTINGS_SECTION_REGISTRY`
+   entry (with `label` **and** `unified.description`) in `components/settings/navigation.ts`. Keep descriptions verb-first, one line,
    ~40–55 chars, in the product voice (see `.claude/rules/constitution.md`).
-2. Render the component inside the shell's `effectiveSection` switch in
-   `settings/[section]/settings.tsx`.
+2. Register its module in `SECTION_MODULES` (`settings/section-warmers.ts`) and render it
+   inside the shell's `effectiveSection` switch in `settings/[section]/settings.tsx`.
 3. Build the component body inside `<SettingsPanel>` — no shell, no title block.
 4. When a real second consumer or server boundary needs it, extract client-safe React Query options;
    otherwise keep them with the hook. Approved intent warmers reuse those exact options and must keep
@@ -348,7 +348,7 @@ shells. Reach for it before hand-rolling a `Chip`.
     shared `<UnsavedChangesModal open={guard.showUnsavedModal}
     onOpenChange={guard.setShowUnsavedModal} onDiscard={guard.confirmDiscard} />`
     (from `@/app/workspace/[workspaceId]/components/credential-detail`). The
-    in-view header **Discard** chip (via `SaveDiscardActions onDiscard`) is a
+    in-view header **Discard** chip (via `saveDiscardActions({ onDiscard })`) is a
     *reset to original* — distinct from the back-confirm's discard, which leaves.
 - **`useSettingsBeforeUnload`** is mounted by the settings shells
   (`settings/layout.tsx` and `components/settings/standalone-settings-shell.tsx`) —
@@ -384,9 +384,9 @@ A settings page is design-system-clean when:
 - [ ] Its main return is a `<SettingsPanel>` (or `<>…<SettingsPanel>…</>` with modal siblings) — no hand-rolled shell/header/scroll/column.
 - [ ] It renders **no** hand-rolled `<h1>`/description title block — the title comes from nav metadata.
 - [ ] Header chips are in `actions`; a standalone search is in the `search` prop.
-- [ ] Its `NavigationItem` has an accurate, consistent-length `description`.
+- [ ] Its registry entry has an accurate, consistent-length `description`.
 - [ ] Detail sub-views and entitlement/loading gates keep their own chrome (intentional).
-- [ ] If it has editable state: Save/Discard go through `SaveDiscardActions`, dirty is wired via `useSettingsUnsavedGuard` (called before any early-return gate), and there is **no** hand-rolled Save button / `beforeunload` / "Unsaved changes" modal.
+- [ ] If it has editable state: Save/Discard go through `saveDiscardActions()`, dirty is wired via `useSettingsUnsavedGuard` (called before any early-return gate), and there is **no** hand-rolled Save button / `beforeunload` / "Unsaved changes" modal.
 - [ ] No business logic, handlers, or conditional rendering changed by the migration — except where the shared primitive makes a gate structural (a permission gate becomes `onClick={can ? … : undefined}` + `navigable={can}`, which renders a plain non-interactive row).
 - [ ] No literal `text-[Npx]` classes — named scale tokens only (see "Text-scale tokens" above).
 - [ ] Every **resource** list row (a thing with an identity — a tool, a server, a key, a credential) is a `SettingsResourceRow` in a `RESOURCE_LIST_STACK`/`RESOURCE_LIST_GRID` — no wrapper `<button>`/`<Link>`, no hand-passed arrow, no re-derived title/subtitle spans. Rows with a genuinely different shape stay bespoke, and draw their own arrow with `RESOURCE_ROW_ARROW_CLASSES`: multi-line bodies (inbox tasks), tabular columns (billing invoices, credit usage), grids (secrets), and the member rows (see the avatar note above).
diff --git a/.cursor/rules/sim-settings-pages.mdc b/.cursor/rules/sim-settings-pages.mdc
index 7dd93bdc92b..c34ff9f5e82 100644
--- a/.cursor/rules/sim-settings-pages.mdc
+++ b/.cursor/rules/sim-settings-pages.mdc
@@ -90,17 +90,17 @@ return (
 ## Title + description live in navigation metadata
 
 `apps/sim/components/settings/navigation.ts` is the single source of truth (the
-`settings/navigation.ts` in the route tree is only a re-export shim). Every `NavigationItem` carries a one-line `description`; `SettingsPanel`
+`settings/navigation.ts` in the route tree is only a re-export shim). Every `SETTINGS_SECTION_REGISTRY` entry carries a one-line `description`; `SettingsPanel`
 resolves both via `getSettingsSectionMeta(plane, section)` and the
 `SettingsSectionProvider` the settings shell wraps around the active section.
 
 Adding a new settings page:
 
-1. Add the section id to the `UnifiedSettingsSection` union + a `NavigationItem`
-   (with `label` **and** `description`) in `components/settings/navigation.ts`. Keep descriptions verb-first, one line,
+1. Add the section id to the `UnifiedSettingsSection` union + a `SETTINGS_SECTION_REGISTRY`
+   entry (with `label` **and** `unified.description`) in `components/settings/navigation.ts`. Keep descriptions verb-first, one line,
    ~40–55 chars, in the product voice (see `.claude/rules/constitution.md`).
-2. Render the component inside the shell's `effectiveSection` switch in
-   `settings/[section]/settings.tsx`.
+2. Register its module in `SECTION_MODULES` (`settings/section-warmers.ts`) and render it
+   inside the shell's `effectiveSection` switch in `settings/[section]/settings.tsx`.
 3. Build the component body inside `<SettingsPanel>` — no shell, no title block.
 4. When a real second consumer or server boundary needs it, extract client-safe React Query options;
    otherwise keep them with the hook. Approved intent warmers reuse those exact options and must keep
@@ -345,7 +345,7 @@ shells. Reach for it before hand-rolling a `Chip`.
     shared `<UnsavedChangesModal open={guard.showUnsavedModal}
     onOpenChange={guard.setShowUnsavedModal} onDiscard={guard.confirmDiscard} />`
     (from `@/app/workspace/[workspaceId]/components/credential-detail`). The
-    in-view header **Discard** chip (via `SaveDiscardActions onDiscard`) is a
+    in-view header **Discard** chip (via `saveDiscardActions({ onDiscard })`) is a
     *reset to original* — distinct from the back-confirm's discard, which leaves.
 - **`useSettingsBeforeUnload`** is mounted by the settings shells
   (`settings/layout.tsx` and `components/settings/standalone-settings-shell.tsx`) —
@@ -381,9 +381,9 @@ A settings page is design-system-clean when:
 - [ ] Its main return is a `<SettingsPanel>` (or `<>…<SettingsPanel>…</>` with modal siblings) — no hand-rolled shell/header/scroll/column.
 - [ ] It renders **no** hand-rolled `<h1>`/description title block — the title comes from nav metadata.
 - [ ] Header chips are in `actions`; a standalone search is in the `search` prop.
-- [ ] Its `NavigationItem` has an accurate, consistent-length `description`.
+- [ ] Its registry entry has an accurate, consistent-length `description`.
 - [ ] Detail sub-views and entitlement/loading gates keep their own chrome (intentional).
-- [ ] If it has editable state: Save/Discard go through `SaveDiscardActions`, dirty is wired via `useSettingsUnsavedGuard` (called before any early-return gate), and there is **no** hand-rolled Save button / `beforeunload` / "Unsaved changes" modal.
+- [ ] If it has editable state: Save/Discard go through `saveDiscardActions()`, dirty is wired via `useSettingsUnsavedGuard` (called before any early-return gate), and there is **no** hand-rolled Save button / `beforeunload` / "Unsaved changes" modal.
 - [ ] No business logic, handlers, or conditional rendering changed by the migration — except where the shared primitive makes a gate structural (a permission gate becomes `onClick={can ? … : undefined}` + `navigable={can}`, which renders a plain non-interactive row).
 - [ ] No literal `text-[Npx]` classes — named scale tokens only (see "Text-scale tokens" above).
 - [ ] Every **resource** list row (a thing with an identity — a tool, a server, a key, a credential) is a `SettingsResourceRow` in a `RESOURCE_LIST_STACK`/`RESOURCE_LIST_GRID` — no wrapper `<button>`/`<Link>`, no hand-passed arrow, no re-derived title/subtitle spans. Rows with a genuinely different shape stay bespoke, and draw their own arrow with `RESOURCE_ROW_ARROW_CLASSES`: multi-line bodies (inbox tasks), tabular columns (billing invoices, credit usage), grids (secrets), and the member rows (see the avatar note above).

From 54c89b885e8e0d6ee79e9455267670f4ddea456f Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Thu, 1 Oct 2026 17:22:15 -0700
Subject: [PATCH 08/18] 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.
---
 .agents/skills/add-block/SKILL.md            | 64 ++++++++-------
 .agents/skills/add-hosted-key/SKILL.md       |  6 +-
 .agents/skills/add-integration/SKILL.md      | 84 ++++++--------------
 .agents/skills/add-tools/SKILL.md            | 14 +++-
 .agents/skills/add-trigger/SKILL.md          | 56 ++++---------
 .agents/skills/validate-integration/SKILL.md | 40 +++++-----
 .agents/skills/validate-trigger/SKILL.md     |  5 +-
 .claude/rules/sim-integrations.md            |  4 +-
 .cursor/rules/sim-integrations.mdc           |  4 +-
 9 files changed, 117 insertions(+), 160 deletions(-)

diff --git a/.agents/skills/add-block/SKILL.md b/.agents/skills/add-block/SKILL.md
index 27628cccf18..97bdb9ba1ed 100644
--- a/.agents/skills/add-block/SKILL.md
+++ b/.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
diff --git a/.agents/skills/add-hosted-key/SKILL.md b/.agents/skills/add-hosted-key/SKILL.md
index a90895d5a46..cf265339d2a 100644
--- a/.agents/skills/add-hosted-key/SKILL.md
+++ b/.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
diff --git a/.agents/skills/add-integration/SKILL.md b/.agents/skills/add-integration/SKILL.md
index 4d5a8e51713..d3b75d5dbde 100644
--- a/.agents/skills/add-integration/SKILL.md
+++ b/.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
diff --git a/.agents/skills/add-tools/SKILL.md b/.agents/skills/add-tools/SKILL.md
index 39fbb963050..be47d23aff1 100644
--- a/.agents/skills/add-tools/SKILL.md
+++ b/.agents/skills/add-tools/SKILL.md
@@ -186,6 +186,9 @@ fallback, or caller-controlled `_context` authority.
 - `'hidden'` - System-injected (OAuth tokens, internal params). User never sees.
 - `'user-only'` - User must provide (credentials, api keys, account-specific IDs)
 - `'user-or-llm'` - User provides OR LLM can compute (search queries, content, filters, most fall into this category)
+- `'llm-only'` - Computed by the LLM only; never shown as a user field
+
+A required `'hidden'` param needs an `oauth` declaration or `hosting.apiKeyParam` to supply it (`bun run check:tool-param-reachability`).
 
 ### Parameter Types
 - `'string'` - Text values
@@ -287,8 +290,9 @@ downloads. Prefer raw provider endpoints over base64 metadata. Return the same f
 declared `file` / `file[]` output and nested message associations; `FileToolProcessor` stores it once
 and replaces every alias with the same `UserFile` in both workflow and Copilot execution.
 
-Preserve stored `UserFile` fields (`id`, `key`, `url`, `context`, `type`, `name`, `size`) in transforms;
-rebuilding the old `{ name, mimeType, data, size }` shape discards the reference. File outputs do not
+When a transform receives an already-stored `UserFile`, return it unchanged (keep `id`, `key`, `url`,
+`context`, `type`, `name`, `size`). Building a new `{ name, mimeType, data, size }` object from it
+discards the stored reference; that shape is only for fresh raw-binary responses. File outputs do not
 need duplicate inline text/base64 aliases; the file system handles content materialization. When
 an existing tool explicitly exposes content aliases in its contract, preserve its legacy version and
 use the existing block/tool version pattern for a file-only output. Test a file over 10 MiB through
@@ -301,6 +305,7 @@ tool result; keep additional provider fields only when they convey distinct info
 - `'json'` - Complex objects (use this, NOT 'object')
 - `'array'` - Arrays with `items` property
 - `'object'` - Objects with `properties` property
+- `'file'` / `'file[]'` - Stored files; the executor persists them (see File Downloads above)
 
 ### Optional Outputs
 Add `optional: true` for fields that may not exist in the response:
@@ -538,11 +543,14 @@ Add any type coercions needed for new params (runs at execution time, after vari
 params: (params) => {
   const result: Record<string, unknown> = {}
   if (params.limit != null && params.limit !== '') result.limit = Number(params.limit)
-  if (params.newParamName) result.toolParamName = params.newParamName  // rename if IDs differ
   return result
 },
 ```
 
+Name each subBlock (or its `canonicalParamId`) 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.
+
 ### 6. Add new outputs
 
 Add any new fields returned by the new tools to the block `outputs`:
diff --git a/.agents/skills/add-trigger/SKILL.md b/.agents/skills/add-trigger/SKILL.md
index 2e784a7f318..69f3657649a 100644
--- a/.agents/skills/add-trigger/SKILL.md
+++ b/.agents/skills/add-trigger/SKILL.md
@@ -191,7 +191,7 @@ export const {Service}Block: BlockConfig = {
 - **V2 defines its own `subBlocks`** (e.g., Google Sheets): Add trigger to V2 (the visible block). V1 is hidden and doesn't need it.
 - **Single block, no V2** (e.g., Google Drive): Add trigger directly.
 
-`generate-docs.ts` deduplicates by base type (first match wins). If V1 is processed first without triggers, the V2 triggers won't appear in `integrations.json`. Always verify by checking the output after running the script.
+`generate-docs.ts` documents only visible blocks (`category: 'tools'`, not `hideFromToolbar`, not `preview`), one per base type. A trigger appears only if that visible block lists it in `triggers.available`. Always verify by checking the output after running the script.
 
 ## Provider Handler
 
@@ -236,6 +236,7 @@ export const {service}Handler: WebhookProviderHandler = {
     headerName: 'X-{Service}-Signature',
     validateFn: validate{Service}Signature,
     providerLabel: '{Service}',
+    requireSecret: true,
   }),
 
   async matchEvent({ body, requestId, providerConfig }: EventMatchContext) {
@@ -437,7 +438,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' },
+    { id: 'triggerCredentials', type: 'oauth-input', title: 'Credentials', serviceId: '{service}', canonicalParamId: 'oauthCredential', requiredScopes: [], required: true, mode: 'trigger' },
     // ... service-specific config fields (dropdowns, inputs, switches) ...
     { id: 'triggerInstructions', type: 'text', title: 'Setup Instructions', hideFromPreview: true, mode: 'trigger', defaultValue: '...' },
   ],
@@ -469,7 +470,9 @@ Add to `helm/sim/values.yaml` under the existing polling cron jobs:
   failedJobsHistoryLimit: 1
 ```
 
-Mirror the existing `rssWebhookPoll` entry.
+Mirror the existing `rssWebhookPoll` entry, and add the matching line to `docker/crontab` under
+`# Polling triggers` (copy the existing `rss` line's format). `bun run check:cron-parity` fails when
+the two disagree.
 
 ### Reference Implementations
 
@@ -480,43 +483,12 @@ Mirror the existing `rssWebhookPoll` entry.
 
 ## Option Lists: `selectorKey` or `options`, never a per-block fetcher
 
-A sub-block gets its choices from exactly one of two places. There is no third.
-
-**`selectorKey` — every remote list.** Use the `add-selector` skill to add the key to the
-browser-safe manifest and attach its provider behavior on the server. All remote selectors execute
-through `selectors.execute`; never add a client provider module or selector-only fetch route.
-
-```ts
-{ id: 'triggerCredentials', type: 'oauth-input', canonicalParamId: 'oauthCredential', mode: 'trigger' },
-{ id: 'labelIds', type: 'dropdown', multiSelect: true,
-  selectorKey: 'gmail.labels', dependsOn: ['triggerCredentials'], mode: 'trigger' },
-{ id: 'manualLabelIds', type: 'short-input', mode: 'trigger-advanced' },
-```
-
-`canonicalParamId: 'oauthCredential'` on the credential sub-block is the line people forget. The
-shared context builder uses trigger mode and projects only active `dependsOn` values under their
-canonical ids. Exact `{{KEY}}` environment references remain unresolved until the authorized server
-executor. The builder does not infer a credential from `type: 'oauth-input'`; only the legacy ids
-`credential` / `botCredential` / `customBotCredential` / `manualBotCredential` are aliased. Give the
-field `canonicalParamId: 'oauthCredential'`, or declare a manifest `sourceFields` alias when a
-legacy source id must be retained.
-
-**`options` — everything else.** A static array, or a pure function of the block's own values for a list that narrows to a sibling's selection. No I/O.
-
-```ts
-options: (params) => {
-  const model = params?.values.model
-  return typeof model === 'string' ? effortsFor(model) : DEFAULT_EFFORTS
-}
-```
-
-**Never fetch inside `options`, and never reach into the stores from a block definition.** A fetcher that resolves its credential with `readSubBlockValue(blockId, ...)` only works on the canvas — every surface that is not the editor gets an empty list. `fetchOptions`/`fetchOptionById` were removed for exactly this reason.
-
-Two rules the checks enforce:
-
-- **Selector query keys contain no dependency values.** Credential IDs, secrets, unresolved
-  references, and their hashes stay out of browser cache identities.
-- **A sub-block that `dependsOn` a credential / knowledge-base / table selector must be reconfigurable at fork-sync time** — a `selectorKey`, a canonical pair whose basic member is a selector, or a `short-input`/`long-input`. `bun run check:fork-dependent-coverage` fails otherwise, because a fork sync clears those fields on every push and an unofferable one can never be set anywhere that sticks.
+Trigger sub-blocks follow the same rules as block sub-blocks: see the `add-block` skill → Option
+Lists, `.claude/rules/sim-integrations.md`, and the `add-selector` skill. Trigger-specific: the
+shared context builder runs in trigger mode, and it aliases only the legacy credential ids
+`credential` / `botCredential` / `customBotCredential` / `manualBotCredential`. Any other trigger
+credential sub-block (such as `triggerCredentials`) needs `canonicalParamId: 'oauthCredential'`, or a
+manifest `sourceFields` alias when a legacy source id must be retained.
 
 ## Checklist
 
@@ -532,6 +504,7 @@ registered `InternalToolConfig.operation`; a `directExecution` property fails
 - [ ] Primary trigger has `includeDropdown: true`; secondary triggers do NOT
 - [ ] All triggers use `buildTriggerSubBlocks` helper
 - [ ] Created `index.ts` barrel export
+- [ ] Trigger files never statically value-import `@/blocks`, directly or transitively (`import type` and dynamic `import()` are fine); `bun run check:trigger-block-cycle` enforces this
 
 ### Registration
 - [ ] All triggers in `triggers/registry.ts` → `TRIGGER_REGISTRY`
@@ -542,6 +515,7 @@ registered `InternalToolConfig.operation`; a `directExecution` property fails
 - [ ] Handler file at `apps/sim/lib/webhooks/providers/{service}.ts`
 - [ ] Registered in `providers/registry.ts` (alphabetical)
 - [ ] Signature validator is a private function inside the handler file
+- [ ] `createHmacVerifier` passes `requireSecret: true` when the provider always signs
 - [ ] `formatInput` output keys match trigger `outputs` exactly
 - [ ] Event matching uses dynamic `await import()` for trigger utils
 
@@ -557,7 +531,7 @@ registered `InternalToolConfig.operation`; a `directExecution` property fails
 - [ ] First poll seeds state and emits nothing
 - [ ] Added provider to `POLLING_PROVIDERS` in `triggers/constants.ts`
 - [ ] Added handler to `POLLING_HANDLERS` in `lib/webhooks/polling/registry.ts`
-- [ ] Added cron job to `helm/sim/values.yaml`
+- [ ] Added cron job to `helm/sim/values.yaml` and the matching `docker/crontab` line; `bun run check:cron-parity` passes
 - [ ] Payload shape matches trigger `outputs` schema
 
 ### Testing
diff --git a/.agents/skills/validate-integration/SKILL.md b/.agents/skills/validate-integration/SKILL.md
index 1bcde985b53..2e1a380f9a2 100644
--- a/.agents/skills/validate-integration/SKILL.md
+++ b/.agents/skills/validate-integration/SKILL.md
@@ -27,7 +27,7 @@ apps/sim/blocks/blocks/{service}.ts # Block definition
 apps/sim/tools/registry.ts          # Tool registry entries 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/auth/connectors/providers.ts # Better Auth connector providers (buildConnectorProviders) — should use getCanonicalScopesForProvider()
 apps/sim/lib/oauth/oauth.ts         # OAuth provider config — single source of truth for scopes
 apps/sim/lib/oauth/utils.ts         # Scope utilities, SCOPE_DESCRIPTIONS for modal UI
 packages/deployment-config/src/env-capabilities.ts # OAuth client runtime capability source of truth
@@ -40,7 +40,8 @@ packages/deployment-config/src/service-account-metadata.ts # Handwritten deploym
 
 If the block, its triggers, or connector fields use a `selectorKey`, also apply the `validate-selector` skill and read
 the key's entry in `apps/sim/lib/selectors/manifest.ts`, its server attachment and provider listing
-primitive, and the shared context builder. There is no client provider selector registry.
+primitive, and the shared context builder. Selector provider logic runs only server-side through
+`selectors.execute`.
 
 ## Step 2: Pull API Documentation
 
@@ -152,16 +153,16 @@ search, extraction, or "AI-powered" marketing terminology.
 - [ ] Serialized content proven to be sent directly to an external model is selected by
       `request.modelInput`, projected before the existing formatter parses it, and has deterministic
       formatter behavior when a whole-value placeholder is invalid for the serialized grammar
-- [ ] Actual inline/raw AI-consumed bytes owned by an authenticated internal route use
-      `privateProvenance` (or `mode: 'private-provenance'`), and the route validates
-      `validateOpaqueModelInputProvenance` before model egress; storage keys, paths, signed URLs,
+- [ ] Actual inline/raw AI-consumed bytes owned by a registered in-process operation use
+      `operation.modelInput` with `privateInputPaths` (or `mode: 'private-provenance'`), and the
+      operation calls `validateOpaqueModelInputProvenance` before model egress; storage keys, paths, signed URLs,
       and ordinary remote URLs are not treated as byte provenance, while tracked stored bytes are
       authorized independently at the owning model-egress boundary
 - [ ] Persisted workspace-file contents are checked with the shared provenance guard only when
       their bytes or decoded content cross into a model/tool-result boundary; ordinary file APIs
       remain unchanged. Unsupported secret-bearing file paths are rejected at `file_write`
 - [ ] Sim-owned durable writes and internal execution handoffs that can enter workflows/models use
-      field-scoped `request.secretProvenance`; authenticated receivers validate the exact selection
+      field-scoped `operation.secretProvenance`; the owning operation validates the exact selection
       and scope, strip private metadata, and persist, import, or propagate it at the owning boundary
 - [ ] Private provenance is never attached to external URLs; registered in-process operations
       preserve it through `operation.modelInput` / `operation.secretProvenance`, while proven
@@ -182,7 +183,7 @@ search, extraction, or "AI-powered" marketing terminology.
 
 Treat a missing or bypassed model, durable, or internal-execution provenance boundary as
 **critical**. Do not fix it with a tool-specific string replacer or by sanitizing every provider
-result; repair the shared request, authenticated internal-route, persistence, or re-entry boundary
+result; repair the shared request, in-process operation, persistence, or re-entry boundary
 that owns the data.
 
 ## Step 4: Validate Block
@@ -197,9 +198,9 @@ For **each tool** in `tools.access`:
   - Shown when that operation is selected (correct `condition`)
   - Marked as `required: true` (or conditionally required)
 - [ ] Every **optional** tool param has a corresponding subBlock input (or is intentionally omitted if truly never needed)
-- [ ] SubBlock `id` values are unique across the entire block — no duplicates even across different conditions
+- [ ] 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
 - [ ] The `tools.config.tool` function returns the correct tool ID for every possible operation value
-- [ ] The `tools.config.params` function correctly maps subBlock IDs to tool param names when 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
 
 ### SubBlocks
 - [ ] Operation dropdown lists ALL tool operations available in `tools.access`
@@ -249,11 +250,11 @@ For **each tool** in `tools.access`:
   - `Number()` conversion for numeric params that come as strings from inputs
   - `Boolean` / string-to-boolean conversion for toggle params
   - Empty string → `undefined` conversion for optional dropdown values
-  - Any subBlock ID → tool param name remapping
+  - SubBlock ID → tool param name remapping only for optional or `user-or-llm` params
 
 ### Block Outputs
 - [ ] Outputs cover the key fields returned by ALL tools (not just one operation)
-- [ ] Output types are correct (`'string'`, `'number'`, `'boolean'`, `'json'`)
+- [ ] Output types are correct (`'string'`, `'number'`, `'boolean'`, `'json'`, `'file'`, `'file[]'`)
 - [ ] `type: 'json'` outputs describe inner fields in the description string: `'User profile (id, name, username, bio)'` or `'[{address, status, type}]'` for arrays
 - [ ] **Do NOT add a `properties: {...}` field on block outputs.** Block-level `OutputFieldDefinition` (from `@sim/workflow-types/blocks`) only accepts `{ type, description?, condition?, hiddenFromDisplay? }`. Nested `properties` is a tool-level construct (`OutputProperty`) — adding it to a block output will fail TypeScript at build time
 - [ ] No opaque `type: 'json'` with vague descriptions like `'Response data'`
@@ -306,9 +307,9 @@ For **each tool** in `tools.access`:
 Scopes are centralized — the single source of truth is `OAUTH_PROVIDERS` in `lib/oauth/oauth.ts`.
 
 - [ ] Scopes defined in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS[provider].services[service].scopes`
-- [ ] `auth.ts` uses `getCanonicalScopesForProvider(providerId)` — NOT a hardcoded array
+- [ ] `lib/auth/connectors/providers.ts` (`buildConnectorProviders`) uses `getCanonicalScopesForProvider(providerId)` — NOT a hardcoded array
 - [ ] Block `requiredScopes` uses `getScopesForService(serviceId)` — NOT a hardcoded array
-- [ ] No hardcoded scope arrays in `auth.ts` or block files (should all use utility functions)
+- [ ] No hardcoded scope arrays in `lib/auth/connectors/providers.ts` or block files (should all use utility functions)
 - [ ] Each scope has a human-readable description in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
 - [ ] No excess scopes that aren't needed by any tool
 
@@ -384,7 +385,7 @@ Group findings by severity:
 - Incorrect response field mapping (accessing wrong path in response)
 - Missing error handling that would cause crashes
 - Tool ID mismatch between tool file, registry, and block `tools.access`
-- OAuth scopes missing in `auth.ts` that tools need
+- OAuth scopes missing in `lib/auth/connectors/providers.ts` that tools need
 - OAuth integration `serviceId` missing from the deployment capability catalog
 - Capability references an env field absent from the runtime env schema
 - Service-account metadata disagrees with the canonical OAuth service configuration
@@ -433,6 +434,8 @@ bun run deployment-config:generate  # canonical OAuth registry + catalog → pro
 bun run integration-catalog:check    # registry ↔ committed deployment metadata drift
 bun run docs:check                   # committed docs ↔ what the generator renders today
 bun run deployment-config:check     # OAuth registry/catalog ↔ provider-ID fact drift
+bun run check:audits                 # every audit CI enforces, including docs:check
+bun run apps/sim/scripts/check-block-registry.ts  # block ↔ tool param coverage (CI, not in check:audits)
 ```
 
 - **`tool-metadata:generate`** — required whenever a tool's `outputs`, `params`, or descriptions change. CI enforces this with `bun run tool-metadata:check`, which fails with *"Generated tool metadata is stale"*. This is the easiest gate to miss, because nothing in the tool file hints that a generated artifact mirrors it.
@@ -468,10 +471,11 @@ After fixing, confirm:
 4. Derived artifacts regenerated and their diffs reviewed (see above)
 5. `bun run integration-catalog:check` passes
 6. `bun run docs:check` passes
-7. For OAuth or service-account changes, `bun run deployment-config:check` passes
-8. For OAuth or service-account changes, `bun run --cwd apps/sim test lib/integrations/availability.server.test.ts` passes
-9. Re-read all modified files to verify fixes are correct
-10. Any remaining unknown response schemas were explicitly reported to the user instead of guessed
+7. `bun run apps/sim/scripts/check-block-registry.ts` passes
+8. For OAuth or service-account changes, `bun run deployment-config:check` passes
+9. For OAuth or service-account changes, `bun run --cwd apps/sim test lib/integrations/availability.server.test.ts` passes
+10. Re-read all modified files to verify fixes are correct
+11. Any remaining unknown response schemas were explicitly reported to the user instead of guessed
 
 ## Checklist Summary
 
diff --git a/.agents/skills/validate-trigger/SKILL.md b/.agents/skills/validate-trigger/SKILL.md
index e2855c3d26c..50d83edec1a 100644
--- a/.agents/skills/validate-trigger/SKILL.md
+++ b/.agents/skills/validate-trigger/SKILL.md
@@ -76,7 +76,7 @@ If a payload schema is unknown, validation must explicitly recommend:
 ### Trigger Files
 - [ ] Exactly one primary trigger has `includeDropdown: true`
 - [ ] All secondary triggers do NOT have `includeDropdown`
-- [ ] All triggers use `buildTriggerSubBlocks` helper (not hand-rolled subBlocks)
+- [ ] Webhook triggers use `buildTriggerSubBlocks`; polling triggers (`polling: true`) declare subBlocks manually
 - [ ] Every trigger's `id` matches the convention `{service}_{event_name}`
 - [ ] Every trigger's `provider` matches the service name used in the handler registry
 - [ ] `index.ts` barrel exports all triggers
@@ -104,7 +104,7 @@ If a payload schema is unknown, validation must explicitly recommend:
 - [ ] Signature is computed over raw body (not parsed JSON)
 
 ### Event Matching
-- [ ] `matchEvent` returns `boolean` (not `NextResponse` or other values)
+- [ ] `matchEvent` returns `true` to run, or `false` / a `NextResponse` to skip with a custom body
 - [ ] Challenge/verification events are excluded from matching (e.g., `endpoint.url_validation`)
 - [ ] When `triggerId` is a generic webhook ID, all events pass through
 - [ ] When `triggerId` is specific, only matching events pass
@@ -190,7 +190,6 @@ Group findings by severity:
 - Wrong HMAC algorithm or header name
 - `formatInput` keys don't match trigger `outputs`
 - Missing `verifyAuth` when the service sends signed webhooks
-- `matchEvent` returns non-boolean values
 - Provider-specific logic leaking into shared orchestration files
 - Trigger IDs mismatch between trigger files, registry, and block
 - `createSubscription` calling wrong API endpoint
diff --git a/.claude/rules/sim-integrations.md b/.claude/rules/sim-integrations.md
index 536f070e957..403b5cecc38 100644
--- a/.claude/rules/sim-integrations.md
+++ b/.claude/rules/sim-integrations.md
@@ -15,10 +15,10 @@ The full authoring instructions — tool/block/icon/trigger scaffolding, SubBloc
 ## Hard rules (don't get these wrong)
 
 - Tool IDs and the two registration/coercion rules are in the root `CLAUDE.md` → Integrations. `blocks/registry.ts` holds only the accessor functions; triggers register in `triggers/registry.ts`.
-- Every subblock `id` is unique within the block, even across different `condition`s — duplicate ids collide silently (the last definition wins).
+- A subblock `id` is unique per condition. The only sanctioned cross-condition reuse is the hosted-key `apiKey` pair (`/add-hosted-key`), where both fields deliberately share one value. `blocks.test.ts` fails same-condition duplicates.
 - Keep block outputs aligned with what the referenced tools actually return, and block `tools.access` aligned with the registered tool IDs.
 - `canonicalParamId` must NOT match any subblock's `id`, must be unique **block-wide** (groups are keyed by canonical id across every subblock and hold exactly one `basicId`, so two operations that each need a pair need two different canonical ids), and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs — the serializer deletes the subblock IDs and republishes the active member's value under the canonical ID.
 - A canonical pair carries ONE concept. For files that is upload (basic) + file reference (advanced), normalized with `normalizeFileInput`, as in Gmail attachments (`blocks/blocks/gmail.ts`). Never overload the advanced side with alternate identifiers (URL, provider asset ID) — give those their own subblocks, mark mutually exclusive sources `required: false`, and enforce "exactly one" at execution.
 - A sub-block's option list is EITHER `selectorKey` (a registered selector — the only way to load a remote list, and the only one that works off the canvas) OR `options` (a static array, or a pure function of the block's own values). Never fetch from a block definition, and never read the workflow stores there. A credential sub-block needs `canonicalParamId: 'oauthCredential'` for its dependants' selectors to resolve. A secret must never appear in a selector's `getQueryKey`. `bun run check:fork-dependent-coverage` fails a `dependsOn` under a credential/KB/table anchor that the fork sync modal cannot offer.
-- Blocks must also set the catalog/UI metadata fields `integrationType`, `tags`, `authMode`, `docsLink`, and export a `{Service}BlockMeta` — see the `/add-block` skill's BlockMeta section. `{Service}BlockMeta.skills` must be grounded in operations the block exposes via `tools.access` and sourced from real, popular use cases found online — never invented.
+- Blocks must also set the catalog/UI metadata fields `integrationType`, `authMode`, `docsLink`, and export a `{Service}BlockMeta` (with `tags`) — see the `/add-block` skill's BlockMeta section. `{Service}BlockMeta.skills` must be grounded in operations the block exposes via `tools.access` and sourced from real, popular use cases found online — never invented.
 - Every block declares canvas sentences: `apps/sim/blocks/AGENTS.md` → "Canvas sentences".
diff --git a/.cursor/rules/sim-integrations.mdc b/.cursor/rules/sim-integrations.mdc
index f4eadfdf8c8..2d1554b1dc5 100644
--- a/.cursor/rules/sim-integrations.mdc
+++ b/.cursor/rules/sim-integrations.mdc
@@ -14,10 +14,10 @@ The full authoring instructions — tool/block/icon/trigger scaffolding, SubBloc
 ## Hard rules (don't get these wrong)
 
 - Tool IDs and the two registration/coercion rules are in the root `CLAUDE.md` → Integrations. `blocks/registry.ts` holds only the accessor functions; triggers register in `triggers/registry.ts`.
-- Every subblock `id` is unique within the block, even across different `condition`s — duplicate ids collide silently (the last definition wins).
+- A subblock `id` is unique per condition. The only sanctioned cross-condition reuse is the hosted-key `apiKey` pair (`/add-hosted-key`), where both fields deliberately share one value. `blocks.test.ts` fails same-condition duplicates.
 - Keep block outputs aligned with what the referenced tools actually return, and block `tools.access` aligned with the registered tool IDs.
 - `canonicalParamId` must NOT match any subblock's `id`, must be unique **block-wide** (groups are keyed by canonical id across every subblock and hold exactly one `basicId`, so two operations that each need a pair need two different canonical ids), and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs — the serializer deletes the subblock IDs and republishes the active member's value under the canonical ID.
 - A canonical pair carries ONE concept. For files that is upload (basic) + file reference (advanced), normalized with `normalizeFileInput`, as in Gmail attachments (`blocks/blocks/gmail.ts`). Never overload the advanced side with alternate identifiers (URL, provider asset ID) — give those their own subblocks, mark mutually exclusive sources `required: false`, and enforce "exactly one" at execution.
 - A sub-block's option list is EITHER `selectorKey` (a registered selector — the only way to load a remote list, and the only one that works off the canvas) OR `options` (a static array, or a pure function of the block's own values). Never fetch from a block definition, and never read the workflow stores there. A credential sub-block needs `canonicalParamId: 'oauthCredential'` for its dependants' selectors to resolve. A secret must never appear in a selector's `getQueryKey`. `bun run check:fork-dependent-coverage` fails a `dependsOn` under a credential/KB/table anchor that the fork sync modal cannot offer.
-- Blocks must also set the catalog/UI metadata fields `integrationType`, `tags`, `authMode`, `docsLink`, and export a `{Service}BlockMeta` — see the `/add-block` skill's BlockMeta section. `{Service}BlockMeta.skills` must be grounded in operations the block exposes via `tools.access` and sourced from real, popular use cases found online — never invented.
+- Blocks must also set the catalog/UI metadata fields `integrationType`, `authMode`, `docsLink`, and export a `{Service}BlockMeta` (with `tags`) — see the `/add-block` skill's BlockMeta section. `{Service}BlockMeta.skills` must be grounded in operations the block exposes via `tools.access` and sourced from real, popular use cases found online — never invented.
 - Every block declares canvas sentences: `apps/sim/blocks/AGENTS.md` → "Canvas sentences".

From 469e741d8d4ff6fe3c4cbb868a5afbb0fbfca214 Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Thu, 1 Oct 2026 20:00:19 -0700
Subject: [PATCH 09/18] docs(agents): map the new ratchets and lint rules in
 the guardrail table

---
 CLAUDE.md | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index ae6a0ad0d87..f2b7ef27343 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -82,7 +82,7 @@ The `'use client'` server boundary, the app/worker runtime env split, and featur
 
 ## Code Conventions
 
-- **Naming**: components PascalCase (`WorkflowList`); hooks `use*`; files kebab-case (`workflow-list.tsx`); constants SCREAMING_SNAKE_CASE; interfaces PascalCase with a suffix (`WorkflowListProps`); stores `stores/<feature>/store.ts`. A file never repeats its folder's name (`lib/logs/views.ts`, not `lib/logs/log-views.ts`; `utils/date.ts`, not `utils/date-utils.ts`); `check:file-names` enforces this.
+- **Naming**: components PascalCase (`WorkflowList`); hooks `use*`; files kebab-case (`workflow-list.tsx`); constants SCREAMING_SNAKE_CASE; interfaces PascalCase with a suffix (`WorkflowListProps`); stores `stores/<feature>/store.ts`. A file never repeats its folder's name (inside `logs/`, `views.ts` not `log-views.ts`; inside `utils/`, `date.ts` not `date-utils.ts`); `check:file-names` enforces this.
 - **Imports**: absolute (`@/...`) only, never relative (a barrel `index.ts` re-exports its own siblings relatively). A folder with 3+ exports gets an `index.ts` barrel; never re-export from a non-barrel file. `import type` for type-only imports. Order and lazy-loading through barrels: `.claude/rules/sim-imports.md`.
 - **TypeScript**: no `any` and no non-null `!` (use precise types or `unknown` with guards; `check:explicit-any` ratchets both); no export nothing imports (`check:unused-exports`); a props interface for every component; `as const` for constant objects/arrays; explicit ref types (`useRef<HTMLDivElement>(null)`).
 - **Unused bindings** fail lint (biome `noUnusedVariables`, `noUnusedFunctionParameters`): delete the dead variable, import, or parameter and update callers; write `catch {}` when the error is unused. Prefix `_` only for a parameter that must hold its position because a later one is used. `const { a, ...rest } = obj` to omit keys is allowed. The rules carry no autofix, so `bun run lint` will not rename anything for you.
@@ -150,7 +150,7 @@ A diff that touches `packages/db/migrations/**` also runs `bun run check:migrati
 
 | Written rule | Enforced by |
 | --- | --- |
-| Formatting, lint, no `nanoid`/`uuid` imports | `bun run lint` (biome) |
+| Formatting, lint, no `nanoid`/`uuid` imports, no unused variables or parameters | `bun run lint` (biome) |
 | `@sim/utils` over inline idioms (`Math.random`, `crypto.randomUUID`, `JSON` clone, `instanceof Error` message, `setTimeout` sleep) | `check:utils` |
 | `apps → packages` only; realtime import bans | `check:boundaries`, `check:realtime-prune` |
 | Route contracts, no `zod` in routes or clients, `requestJson`, boundary annotations | `check:api-validation:strict`, `check:api-contract-routes`, `check:route-verbs` |
@@ -164,8 +164,11 @@ A diff that touches `packages/db/migrations/**` also runs `bun run check:migrati
 | Canvas sentences, BYOK wiring, fork-dependent subblocks, reachable tool params | `check:canvas-sentences`, `check:byok-providers`, `check:fork-dependent-coverage`, `check:tool-param-reachability` |
 | Central mocks, colocated tests, script tests collected | `check:test-patterns`, `check:script-tests` |
 | Zero-downtime migrations | `check:migrations <base>` |
-| Unused files, exports, dependencies | `check:dead-code` (knip) |
+| Unused files, exports, types, dependencies (exports and types ratcheted) | `check:unused-exports` (knip) |
+| No `any` or non-null `!` (ratcheted), no suppressions of either | `check:explicit-any` |
+| kebab-case file names; no file repeating its folder's name | `check:file-names` |
+| No banner separators or commented-out code | `check:comment-hygiene` |
 | Skills and rules projections in sync; guidance references resolve | `check:skills`, `check:guidance-refs` |
 | Generated artifacts fresh (tool metadata, docs, catalog, CLI/MCP/OpenAPI surfaces) | the `*:check` entries in `check:audits` |
 
-Rules not in this table (logging, comments, naming, imports, styling, state ownership, caching) are enforced by review only; follow them as written.
+Rules not in this table (logging, the rest of comment style and naming, imports, styling, state ownership, caching) are enforced by review only; follow them as written.

From 0a0a698a5a68ca701d333096b588a7c03fbfc874 Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Thu, 1 Oct 2026 21:14:26 -0700
Subject: [PATCH 10/18] docs(agents): correct audit findings in guidance and
 gate docs

Restore the connector byte-cap rule's skip list, list every CI gate step,
name the real baseline flags and generated-artifact checks, make
api-validation strict-only guidance explicit, pass a base ref to
check-block-registry, and teach check:guidance-refs about bun run --cwd.
---
 .agents/skills/add-block/SKILL.md             |  6 +-
 .agents/skills/add-connector/SKILL.md         |  4 +-
 .agents/skills/add-integration/SKILL.md       |  3 +-
 .agents/skills/add-settings-page/SKILL.md     | 16 ++--
 .agents/skills/add-tools/SKILL.md             |  2 +-
 .agents/skills/design-taste-frontend/SKILL.md |  2 +-
 .agents/skills/memory-load-check/SKILL.md     |  6 +-
 .agents/skills/v2-api-conventions/SKILL.md    |  2 +-
 .agents/skills/validate-integration/SKILL.md  |  8 +-
 .claude/rules/sim-api-contracts.md            |  2 +-
 .claude/rules/sim-imports.md                  |  6 +-
 .claude/rules/sim-integrations.md             |  2 +-
 .cursor/rules/sim-api-contracts.mdc           |  2 +-
 .cursor/rules/sim-imports.mdc                 |  6 +-
 .cursor/rules/sim-integrations.mdc            |  2 +-
 CLAUDE.md                                     | 10 ++-
 scripts/check-guidance-refs.ts                | 73 +++++++++++--------
 17 files changed, 89 insertions(+), 63 deletions(-)

diff --git a/.agents/skills/add-block/SKILL.md b/.agents/skills/add-block/SKILL.md
index 97bdb9ba1ed..c8a83361a6b 100644
--- a/.agents/skills/add-block/SKILL.md
+++ b/.agents/skills/add-block/SKILL.md
@@ -73,7 +73,7 @@ export const {ServiceName}Block: BlockConfig = {
 
 ## SubBlock Types Reference
 
-**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.
+**Critical:** Give every subblock a unique `id`: duplicates collide silently (the last definition wins). `blocks.test.ts` fails a duplicate within one condition unless the copies are a basic/advanced mode-swap pair, one basic plus trigger-mode copies, or all carry `canonicalParamId`. The only sanctioned cross-condition reuse is the hosted-key `apiKey` pair (`add-hosted-key` skill), where both fields deliberately share one value.
 
 ### Text Inputs
 ```typescript
@@ -959,7 +959,7 @@ But if the same change also adds, edits **or removes** a tool, run `bun run tool
 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
+`bun run apps/sim/scripts/check-block-registry.ts origin/staging` (CI runs it outside `check:audits`). Commit the
 full generator output. For what each check verifies, see the `validate-integration` skill →
 Regenerate Derived Artifacts.
 
@@ -1002,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)
-   - 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
+   - 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 origin/staging`; 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
diff --git a/.agents/skills/add-connector/SKILL.md b/.agents/skills/add-connector/SKILL.md
index 0f435345d98..894db91cee1 100644
--- a/.agents/skills/add-connector/SKILL.md
+++ b/.agents/skills/add-connector/SKILL.md
@@ -347,7 +347,7 @@ Every document returned from `listDocuments`/`getDocument` must include:
   content: string             // Extracted plain text (or '' if contentDeferred)
   contentDeferred?: boolean   // true = content will be fetched via getDocument
   mimeType: 'text/plain'     // extracted text; for a format the KB pipeline parses (PDF, Office), set `sourceFile` instead
-  contentHash: string         // Metadata-based hash for change detection
+  contentHash: string         // Change-detection hash (metadata-based when content is deferred)
   sourceUrl?: string          // Link back to original (stored on document record)
   metadata?: Record<string, unknown>  // Source-specific data (fed to mapTags)
 }
@@ -627,7 +627,7 @@ export const CONNECTOR_META_REGISTRY: ConnectorMetaRegistry = {
 - [ ] `listDocuments` handles pagination; deferred-content connectors use metadata-based content hashes
 - [ ] `syncContext.listingCapped = true` set whenever the listing is truncated (max-items cap or transient per-item error) — required to prevent the engine's deletion reconciliation from removing unseen documents
 - [ ] `contentDeferred: true` used if content requires per-doc API calls (file download, export, blocks fetch)
-- [ ] `contentHash` is metadata-based (not content-based) and identical between stub and `getDocument`
+- [ ] `contentHash` is metadata-based for deferred-content connectors (inline-content ones may use `computeContentHash`) and identical between stub and `getDocument`
 - [ ] `sourceUrl` set on each ExternalDocument (full URL, not relative)
 - [ ] `metadata` includes source-specific data for tag mapping
 - [ ] `tagDefinitions` declared for each semantic key returned by `mapTags`
diff --git a/.agents/skills/add-integration/SKILL.md b/.agents/skills/add-integration/SKILL.md
index d3b75d5dbde..5ee161e182a 100644
--- a/.agents/skills/add-integration/SKILL.md
+++ b/.agents/skills/add-integration/SKILL.md
@@ -542,7 +542,8 @@ operations beside it. The handler validates `request.input`, derives storage aut
 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`; the
-existing `registry.server.test.ts` completeness test covers registration. For anything more, run the
+sweep in `apps/sim/tools/request-transport.test.ts` fails a forgotten registration
+(`registry.server.test.ts` checks registered ids are canonical with loadable handlers). For anything more, run the
 `test-audit` gate. There is no HTTP fallback.
 
 ### File Output Pattern (Downloads)
diff --git a/.agents/skills/add-settings-page/SKILL.md b/.agents/skills/add-settings-page/SKILL.md
index 0f561f165f6..c59c187e738 100644
--- a/.agents/skills/add-settings-page/SKILL.md
+++ b/.agents/skills/add-settings-page/SKILL.md
@@ -42,15 +42,19 @@ Key paths:
 
 For each page component, confirm the checklist in `.claude/rules/sim-settings-pages.md`:
 
+Each grep lists candidates; review every match against the expected ones named below.
+
 1. Find hand-rolled shells that should be `SettingsPanel`:
    `git grep -n "flex h-full flex-col bg-\[var(--bg)\]" -- 'apps/sim/**/settings/**' 'apps/sim/ee/'`
-   — every match should be the settings shell (`settings/layout.tsx`),
-   `CredentialDetailLayout` (the `settings/secrets/[credentialId]` exception), or an
-   entitlement/loading gate. A detail sub-view is never a match: it passes
-   `back={{ text, icon: ArrowLeft, onSelect }}` to `SettingsPanel`. Anything else is a
-   violation: render it through `SettingsPanel`.
-2. Find hand-rolled title blocks (should match only `settings-header.tsx`, the shell):
+   — expected matches: the workspace and organization `settings/layout.tsx` shells, the shared
+   header shell (`components/settings/settings-header.tsx`), `CredentialDetailLayout` (the
+   `settings/secrets/[credentialId]` exception), or an entitlement/loading gate. A detail
+   sub-view is never a match: it passes `back={{ text, icon: ArrowLeft, onSelect }}` to
+   `SettingsPanel`. Anything else is a violation: render it through `SettingsPanel`.
+2. Find hand-rolled title blocks:
    `git grep -n "text-\[var(--text-body)\] text-lg" -- 'apps/sim/**/settings/**' 'apps/sim/ee/'`
+   — the only title is the `<h1>` in `settings-header.tsx`; a non-heading value at that size
+   (e.g. the credit balance in `ee/organization-usage/components/usage-credits.tsx`) is fine.
 3. Find literal pixel text sizes (should be 0 — see "Text Scale" in
    `.claude/rules/sim-styling.md`):
    `git grep -nE "text-\[1[0-8]px\]" -- 'apps/sim/**/settings/**' 'apps/sim/ee/'`.
diff --git a/.agents/skills/add-tools/SKILL.md b/.agents/skills/add-tools/SKILL.md
index be47d23aff1..e488f4c9469 100644
--- a/.agents/skills/add-tools/SKILL.md
+++ b/.agents/skills/add-tools/SKILL.md
@@ -549,7 +549,7 @@ params: (params) => {
 
 Name each subBlock (or its `canonicalParamId`) 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.
+`bun run apps/sim/scripts/check-block-registry.ts origin/staging`; remap only optional or `user-or-llm` params.
 
 ### 6. Add new outputs
 
diff --git a/.agents/skills/design-taste-frontend/SKILL.md b/.agents/skills/design-taste-frontend/SKILL.md
index 7b9bc3b6932..32d52ff68c9 100644
--- a/.agents/skills/design-taste-frontend/SKILL.md
+++ b/.agents/skills/design-taste-frontend/SKILL.md
@@ -4,7 +4,7 @@ source: https://github.com/leonxlnx/taste-skill — skills/taste-skill/SKILL.md
 description: Anti-slop frontend skill for landing pages, portfolios, and redesigns. The agent reads the brief, infers the right design direction, and ships interfaces that do not look templated. Real design systems when applicable, audit-first on redesigns, strict pre-flight check.
 ---
 
-> **In this repo:** Tailwind 4 (CSS-first config in `apps/sim/app/_styles/globals.css`); animation via `import { motion } from 'framer-motion'` (not `motion/react` — rewrite every `motion/react` import in the samples below); icons from `@sim/emcn/icons`; colors through the CSS-variable tokens in `.claude/rules/sim-styling.md` (no hardcoded `text-gray-*`/hex/`zinc` utilities, no paired `dark:` utilities). This note overrides any conflicting guidance or code sample anywhere in this file. Fonts are fixed (Season body, Inter, Martian Mono); never introduce new families. Font weight is only `font-normal`/`font-medium`/`font-semibold`. Elevation uses the `shadow-subtle|medium|overlay|card` tokens. Type size uses named tokens, never `text-[Npx]`. Product forms use `ChipModalField`. Use `bunx`, never `npx`. Do not add GSAP, Lenis, Three, or shadcn. Landing copy and SEO follow `.claude/rules/constitution.md` and `.claude/rules/landing-seo-geo.md`.
+> **In this repo:** Tailwind 4 (CSS-first config in `apps/sim/app/_styles/globals.css`); animation via `import { motion } from 'framer-motion'` (not `motion/react` — rewrite every `motion/react` import in the samples below); icons from `@sim/emcn/icons`; colors through the CSS-variable tokens in `.claude/rules/sim-styling.md` (no hardcoded `text-gray-*`/hex/`zinc` utilities, no paired `dark:` utilities). This note overrides any conflicting guidance or code sample anywhere in this file. Fonts are fixed (Season body, Inter); never introduce new families, and never use Martian Mono on landing (`apps/sim/app/(landing)/CLAUDE.md`). Font weight is only `font-normal`/`font-medium`/`font-semibold`. Elevation uses the `shadow-subtle|medium|overlay|card` tokens. Type size uses named tokens, never `text-[Npx]`. Product forms use `ChipModalField`. Use `bunx`, never `npx`. Do not add GSAP, Lenis, Three, or shadcn. Landing copy and SEO follow `.claude/rules/constitution.md` and `.claude/rules/landing-seo-geo.md`.
 
 # tasteskill: Anti-Slop Frontend Skill
 
diff --git a/.agents/skills/memory-load-check/SKILL.md b/.agents/skills/memory-load-check/SKILL.md
index 40af9c55e2c..9cef84d98dc 100644
--- a/.agents/skills/memory-load-check/SKILL.md
+++ b/.agents/skills/memory-load-check/SKILL.md
@@ -72,7 +72,11 @@ For those, require all three:
 - 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 *per-file `CONNECTOR_MAX_FILE_BYTES` + skipped-row* pattern when the source bounds the item count (paginated JSON: Jira, Linear, Sentry, Slack, Zendesk, Gmail, ...). Every response body is still read through `readBodyWithLimit` with a connector-specific budget (`MAX_DOCS_RESPONSE_BYTES` in google-docs, `MAX_CONTENT_BYTES` in google-sheets, a remaining-bytes budget in notion). Confluence attachments use the full file pattern.
+Skip the pattern when the source already bounds the payload:
+- pure API/structured-data connectors (Jira, Linear, 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 (Evernote ~25 MB/note, ...) — a 100 MB cap can never fire there
+
+Some connectors also budget the response body (google-docs `MAX_DOCS_RESPONSE_BYTES`, google-sheets `MAX_CONTENT_BYTES`, a remaining-bytes budget in notion); Confluence attachments use the full file pattern. Follow the connector's existing approach rather than adding a cap to every `response.json()`.
 
 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.
 
diff --git a/.agents/skills/v2-api-conventions/SKILL.md b/.agents/skills/v2-api-conventions/SKILL.md
index 1e4c8ee25eb..82756047c04 100644
--- a/.agents/skills/v2-api-conventions/SKILL.md
+++ b/.agents/skills/v2-api-conventions/SKILL.md
@@ -30,7 +30,7 @@ Each rule below guards a caller-visible failure: a non-integer `limit` reaching
 
 ## Rule 1 — the envelope is produced by helpers, never by hand
 
-`v2Data`, `v2Error`, and the typed error helpers in `response.ts` (`v2ValidationError`, `v2RateLimitError`, `v2HttpError`) are the only things that build a v2 body. They also set `Cache-Control: private, no-store`, which every v2 response needs because every v2 response is authed per-caller data.
+`v2Data`, `v2Error`, and the typed error helpers in `response.ts` (`v2ValidationError`, `v2RateLimitError`, `v2HttpError`, `v2InsufficientScope`, `v2HeadNoEffect`, `v2UploadDataPlaneError`) are the only things that build a v2 body. They also set `Cache-Control: private, no-store`, which every v2 response needs because every v2 response is authed per-caller data.
 
 A route built with `defineV2JsonRoute` gets this for free: its `present` returns the *body shape* and the builder renders it. Never call `NextResponse.json` from a v2 route.
 
diff --git a/.agents/skills/validate-integration/SKILL.md b/.agents/skills/validate-integration/SKILL.md
index 2e1a380f9a2..dce322e08fc 100644
--- a/.agents/skills/validate-integration/SKILL.md
+++ b/.agents/skills/validate-integration/SKILL.md
@@ -198,9 +198,9 @@ For **each tool** in `tools.access`:
   - Shown when that operation is selected (correct `condition`)
   - Marked as `required: true` (or conditionally required)
 - [ ] Every **optional** tool param has a corresponding subBlock input (or is intentionally omitted if truly never needed)
-- [ ] 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
+- [ ] Every subBlock `id` is unique (duplicates collide silently; the last definition wins). `blocks.test.ts` fails a duplicate within one condition unless the copies are a basic/advanced mode-swap pair, one basic plus trigger-mode copies, or all carry `canonicalParamId`. The only sanctioned cross-condition reuse is the hosted-key `apiKey` pair (`add-hosted-key` skill)
 - [ ] The `tools.config.tool` function returns the correct tool ID for every possible operation value
-- [ ] 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
+- [ ] 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 origin/staging`; remap only optional or `user-or-llm` params
 
 ### SubBlocks
 - [ ] Operation dropdown lists ALL tool operations available in `tools.access`
@@ -435,7 +435,7 @@ bun run integration-catalog:check    # registry ↔ committed deployment metadat
 bun run docs:check                   # committed docs ↔ what the generator renders today
 bun run deployment-config:check     # OAuth registry/catalog ↔ provider-ID fact drift
 bun run check:audits                 # every audit CI enforces, including docs:check
-bun run apps/sim/scripts/check-block-registry.ts  # block ↔ tool param coverage (CI, not in check:audits)
+bun run apps/sim/scripts/check-block-registry.ts origin/staging  # block ↔ tool param coverage (CI, not in check:audits)
 ```
 
 - **`tool-metadata:generate`** — required whenever a tool's `outputs`, `params`, or descriptions change. CI enforces this with `bun run tool-metadata:check`, which fails with *"Generated tool metadata is stale"*. This is the easiest gate to miss, because nothing in the tool file hints that a generated artifact mirrors it.
@@ -471,7 +471,7 @@ After fixing, confirm:
 4. Derived artifacts regenerated and their diffs reviewed (see above)
 5. `bun run integration-catalog:check` passes
 6. `bun run docs:check` passes
-7. `bun run apps/sim/scripts/check-block-registry.ts` passes
+7. `bun run apps/sim/scripts/check-block-registry.ts origin/staging` passes
 8. For OAuth or service-account changes, `bun run deployment-config:check` passes
 9. For OAuth or service-account changes, `bun run --cwd apps/sim test lib/integrations/availability.server.test.ts` passes
 10. Re-read all modified files to verify fixes are correct
diff --git a/.claude/rules/sim-api-contracts.md b/.claude/rules/sim-api-contracts.md
index ea0a20a91d6..5da3c93982f 100644
--- a/.claude/rules/sim-api-contracts.md
+++ b/.claude/rules/sim-api-contracts.md
@@ -18,7 +18,7 @@ Boundary HTTP request and response shapes for all routes under `apps/sim/app/api
 
 ## Enforcement
 
-`bun run check:api-validation:strict` is the gate (it runs in `check:audits`): it enforces boundary policy, prints ratchet metrics (route Zod imports, route-local schema constructors, route `ZodError` references, client hook Zod imports), and fails on annotations with empty reasons. `check:api-validation` is the same audit without the strict reason check.
+`bun run check:api-validation:strict` is the gate (it runs in `check:audits`): it enforces boundary policy, prints ratchet metrics (route Zod imports, route-local schema constructors, route `ZodError` references, client hook Zod imports), and fails on annotations with empty reasons. `check:api-validation` (non-strict) only fails when the non-Zod route count grows; every boundary ratchet, including the reason check, is strict-only, so always run the `:strict` variant.
 
 Whole-file allowlists for routes that legitimately import Zod for non-boundary reasons go through `INDIRECT_ZOD_ROUTES` in `scripts/check-api-validation-contracts.ts`, not per-line annotations.
 
diff --git a/.claude/rules/sim-imports.md b/.claude/rules/sim-imports.md
index 8871884f219..953c9819507 100644
--- a/.claude/rules/sim-imports.md
+++ b/.claude/rules/sim-imports.md
@@ -34,12 +34,14 @@ import { Dashboard } from '@/app/workspace/[workspaceId]/logs/components/dashboa
 
 ## Code-splitting through barrels
 
-When you `lazy(() => import(...))` a component to keep it out of a route's initial bundle, import the **deep module path** (`./components/foo/foo`), never the barrel — and **delete the now-dead barrel re-export** of that component. This app has no `"sideEffects": false` in `apps/sim/package.json`, so when any sibling still imports that barrel, webpack can conservatively keep the barrel's re-export edge to the heavy module. A leftover `export { Foo } from './foo'` line can therefore drag `Foo` (and its transitive deps) back into the initial chunk and silently defeat the split. Removing the dead re-export is the guaranteed fix; verify with a production bundle diff, not by eyeballing the `lazy()` call.
+When you `lazy(() => import(...))` a component to keep it out of a route's initial bundle, import the **deep module path** (absolute, e.g. `@/app/.../components/foo/foo`), never the barrel — and **delete the now-dead barrel re-export** of that component. This app has no `"sideEffects": false` in `apps/sim/package.json`, so when any sibling still imports that barrel, webpack can conservatively keep the barrel's re-export edge to the heavy module. A leftover `export { Foo } from './foo'` line can therefore drag `Foo` (and its transitive deps) back into the initial chunk and silently defeat the split. Removing the dead re-export is the guaranteed fix; verify with a production bundle diff, not by eyeballing the `lazy()` call.
 
 ```typescript
 // ✓ Good — deep lazy import + no barrel edge left behind
 const MothershipView = lazy(() =>
-  import('./components/mothership-view/mothership-view').then((m) => ({ default: m.MothershipView }))
+  import('@/app/workspace/[workspaceId]/home/components/mothership-view/mothership-view').then(
+    (m) => ({ default: m.MothershipView })
+  )
 )
 // (and remove `export { MothershipView } from './mothership-view'` from components/index.ts)
 ```
diff --git a/.claude/rules/sim-integrations.md b/.claude/rules/sim-integrations.md
index 403b5cecc38..90d6ebd6c33 100644
--- a/.claude/rules/sim-integrations.md
+++ b/.claude/rules/sim-integrations.md
@@ -15,7 +15,7 @@ The full authoring instructions — tool/block/icon/trigger scaffolding, SubBloc
 ## Hard rules (don't get these wrong)
 
 - Tool IDs and the two registration/coercion rules are in the root `CLAUDE.md` → Integrations. `blocks/registry.ts` holds only the accessor functions; triggers register in `triggers/registry.ts`.
-- A subblock `id` is unique per condition. The only sanctioned cross-condition reuse is the hosted-key `apiKey` pair (`/add-hosted-key`), where both fields deliberately share one value. `blocks.test.ts` fails same-condition duplicates.
+- Give every subblock a unique `id`: duplicates collide silently (the last definition wins). `blocks.test.ts` fails a duplicate within one condition unless the copies are a basic/advanced mode-swap pair, one basic plus trigger-mode copies, or all carry `canonicalParamId`. The only sanctioned cross-condition reuse is the hosted-key `apiKey` pair (`/add-hosted-key`), where both fields deliberately share one value.
 - Keep block outputs aligned with what the referenced tools actually return, and block `tools.access` aligned with the registered tool IDs.
 - `canonicalParamId` must NOT match any subblock's `id`, must be unique **block-wide** (groups are keyed by canonical id across every subblock and hold exactly one `basicId`, so two operations that each need a pair need two different canonical ids), and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs — the serializer deletes the subblock IDs and republishes the active member's value under the canonical ID.
 - A canonical pair carries ONE concept. For files that is upload (basic) + file reference (advanced), normalized with `normalizeFileInput`, as in Gmail attachments (`blocks/blocks/gmail.ts`). Never overload the advanced side with alternate identifiers (URL, provider asset ID) — give those their own subblocks, mark mutually exclusive sources `required: false`, and enforce "exactly one" at execution.
diff --git a/.cursor/rules/sim-api-contracts.mdc b/.cursor/rules/sim-api-contracts.mdc
index 7e97ed8b143..163e9e148f1 100644
--- a/.cursor/rules/sim-api-contracts.mdc
+++ b/.cursor/rules/sim-api-contracts.mdc
@@ -16,7 +16,7 @@ Boundary HTTP request and response shapes for all routes under `apps/sim/app/api
 
 ## Enforcement
 
-`bun run check:api-validation:strict` is the gate (it runs in `check:audits`): it enforces boundary policy, prints ratchet metrics (route Zod imports, route-local schema constructors, route `ZodError` references, client hook Zod imports), and fails on annotations with empty reasons. `check:api-validation` is the same audit without the strict reason check.
+`bun run check:api-validation:strict` is the gate (it runs in `check:audits`): it enforces boundary policy, prints ratchet metrics (route Zod imports, route-local schema constructors, route `ZodError` references, client hook Zod imports), and fails on annotations with empty reasons. `check:api-validation` (non-strict) only fails when the non-Zod route count grows; every boundary ratchet, including the reason check, is strict-only, so always run the `:strict` variant.
 
 Whole-file allowlists for routes that legitimately import Zod for non-boundary reasons go through `INDIRECT_ZOD_ROUTES` in `scripts/check-api-validation-contracts.ts`, not per-line annotations.
 
diff --git a/.cursor/rules/sim-imports.mdc b/.cursor/rules/sim-imports.mdc
index 2284d0b0ac4..988734d94f9 100644
--- a/.cursor/rules/sim-imports.mdc
+++ b/.cursor/rules/sim-imports.mdc
@@ -34,12 +34,14 @@ import { Dashboard } from '@/app/workspace/[workspaceId]/logs/components/dashboa
 
 ## Code-splitting through barrels
 
-When you `lazy(() => import(...))` a component to keep it out of a route's initial bundle, import the **deep module path** (`./components/foo/foo`), never the barrel — and **delete the now-dead barrel re-export** of that component. This app has no `"sideEffects": false` in `apps/sim/package.json`, so when any sibling still imports that barrel, webpack can conservatively keep the barrel's re-export edge to the heavy module. A leftover `export { Foo } from './foo'` line can therefore drag `Foo` (and its transitive deps) back into the initial chunk and silently defeat the split. Removing the dead re-export is the guaranteed fix; verify with a production bundle diff, not by eyeballing the `lazy()` call.
+When you `lazy(() => import(...))` a component to keep it out of a route's initial bundle, import the **deep module path** (absolute, e.g. `@/app/.../components/foo/foo`), never the barrel — and **delete the now-dead barrel re-export** of that component. This app has no `"sideEffects": false` in `apps/sim/package.json`, so when any sibling still imports that barrel, webpack can conservatively keep the barrel's re-export edge to the heavy module. A leftover `export { Foo } from './foo'` line can therefore drag `Foo` (and its transitive deps) back into the initial chunk and silently defeat the split. Removing the dead re-export is the guaranteed fix; verify with a production bundle diff, not by eyeballing the `lazy()` call.
 
 ```typescript
 // ✓ Good — deep lazy import + no barrel edge left behind
 const MothershipView = lazy(() =>
-  import('./components/mothership-view/mothership-view').then((m) => ({ default: m.MothershipView }))
+  import('@/app/workspace/[workspaceId]/home/components/mothership-view/mothership-view').then(
+    (m) => ({ default: m.MothershipView })
+  )
 )
 // (and remove `export { MothershipView } from './mothership-view'` from components/index.ts)
 ```
diff --git a/.cursor/rules/sim-integrations.mdc b/.cursor/rules/sim-integrations.mdc
index 2d1554b1dc5..c6700f46048 100644
--- a/.cursor/rules/sim-integrations.mdc
+++ b/.cursor/rules/sim-integrations.mdc
@@ -14,7 +14,7 @@ The full authoring instructions — tool/block/icon/trigger scaffolding, SubBloc
 ## Hard rules (don't get these wrong)
 
 - Tool IDs and the two registration/coercion rules are in the root `CLAUDE.md` → Integrations. `blocks/registry.ts` holds only the accessor functions; triggers register in `triggers/registry.ts`.
-- A subblock `id` is unique per condition. The only sanctioned cross-condition reuse is the hosted-key `apiKey` pair (`/add-hosted-key`), where both fields deliberately share one value. `blocks.test.ts` fails same-condition duplicates.
+- Give every subblock a unique `id`: duplicates collide silently (the last definition wins). `blocks.test.ts` fails a duplicate within one condition unless the copies are a basic/advanced mode-swap pair, one basic plus trigger-mode copies, or all carry `canonicalParamId`. The only sanctioned cross-condition reuse is the hosted-key `apiKey` pair (`/add-hosted-key`), where both fields deliberately share one value.
 - Keep block outputs aligned with what the referenced tools actually return, and block `tools.access` aligned with the registered tool IDs.
 - `canonicalParamId` must NOT match any subblock's `id`, must be unique **block-wide** (groups are keyed by canonical id across every subblock and hold exactly one `basicId`, so two operations that each need a pair need two different canonical ids), and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs — the serializer deletes the subblock IDs and republishes the active member's value under the canonical ID.
 - A canonical pair carries ONE concept. For files that is upload (basic) + file reference (advanced), normalized with `normalizeFileInput`, as in Gmail attachments (`blocks/blocks/gmail.ts`). Never overload the advanced side with alternate identifiers (URL, provider asset ID) — give those their own subblocks, mark mutually exclusive sources `required: false`, and enforce "exactly one" at execution.
diff --git a/CLAUDE.md b/CLAUDE.md
index f2b7ef27343..f18013e0b65 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,7 +22,7 @@ This file (also `AGENTS.md`) holds the repo-wide rules. Area detail lives in `.c
   - `compareStrings(left, right)` from `@sim/utils/string` — code-unit ordering for hashes, fingerprints, and cross-process comparisons; never `localeCompare` there
   - `backoffWithJitter(attempt, retryAfterMs, options?)` / `parseRetryAfter(header)` from `@sim/utils/retry` — never reimplement exponential backoff inline
 - **Deployment flags in the browser**: client code inside a workspace, organization, or standalone settings surface reads `hosted`, `billingEnabled`, `chatEnabled`, and the enterprise feature set through `useDeploymentShape()` (components) or `getDeploymentShape()` (block conditions, stores, helpers) from `@/lib/core/config/deployment-shape`, never `isHosted`/`isBillingEnabled`/... from `env-flags`. Those constants freeze at module init from the root layout's `NEXT_PUBLIC_*` transport, which Next's bare 404 shell and `global-error` never emit, so a recovered tab would render Sim Cloud as self-hosted; the reader is seeded from the server-resolved workspace host context, organization layout, or standalone settings layout instead. Server code keeps reading `env-flags`.
-- **Type-checking**: `bun run type-check` at the root checks every workspace (`bun run type-check` inside a workspace checks just that one). Never remove the `@typescript/native` alias from the root `devDependencies`: nothing imports it, but without it a bare `tsc` resolves to the ~10x slower TypeScript 6 compiler. `bun run check:native-typecheck` enforces this; its header explains the bin-resolution trap.
+- **Type-checking**: `bun run type-check` at the root checks every workspace (`bun run type-check` inside a workspace checks just that one). `apps/sim`'s tsconfig excludes `*.test.ts(x)`, so its tests are not type-checked. Never remove the `@typescript/native` alias from the root `devDependencies`: nothing imports it, but without it a bare `tsc` resolves to the ~10x slower TypeScript 6 compiler. `bun run check:native-typecheck` enforces this; its header explains the bin-resolution trap.
 
 ## Architecture
 
@@ -137,16 +137,18 @@ Never add a `case 'sometype':` outside `column-types/`, except the one documente
 
 ## How your work is checked
 
-Before declaring a change done, run the local gate from the repo root; CI runs the same commands and fails on any of them:
+Before declaring a change done, run the local gate from the repo root; CI runs these and fails on any of them:
 
 ```bash
 bun run lint            # biome format + lint, autofixes (CI runs lint:check)
 bun run type-check      # every workspace
 bun run check:audits    # every check:* audit plus the generated-artifact checks
 bun run test            # script tests, then every workspace's Vitest suite
+bun run docs-manifest:check
+bun run apps/sim/scripts/check-block-registry.ts origin/staging
 ```
 
-A diff that touches `packages/db/migrations/**` also runs `bun run check:migrations origin/staging` (it needs a base ref, so it is not in `check:audits`). When an audit fails, its output and its script's header say what the rule protects; fix the code, never the check. Ratchet baselines (`scripts/*.baseline.json`) only shrink: regenerate one with the script's `--update`/`--write` flag after removing violations, never to admit new ones.
+CI also runs `bun run check:migrations <base>` (it needs a base ref, so it is not in `check:audits`; run it with `origin/staging` when you touch `packages/db/migrations/**`), checks that `drizzle-kit generate` in `packages/db` produces no new migration, and runs a non-blocking `bun audit`. When an audit fails, its output and its script's header say what the rule protects; fix the code, never the check. Ratchet baselines (`scripts/*baseline.json`) only shrink: regenerate one with the update flag its failure output names (`--update` or `--update-baseline`) after removing violations, never to admit new debt. The one exception is `check:tool-registry-boundary`, whose module-count baseline is re-recorded when growth is deliberate (see its skill).
 
 | Written rule | Enforced by |
 | --- | --- |
@@ -169,6 +171,6 @@ A diff that touches `packages/db/migrations/**` also runs `bun run check:migrati
 | kebab-case file names; no file repeating its folder's name | `check:file-names` |
 | No banner separators or commented-out code | `check:comment-hygiene` |
 | Skills and rules projections in sync; guidance references resolve | `check:skills`, `check:guidance-refs` |
-| Generated artifacts fresh (tool metadata, docs, catalog, CLI/MCP/OpenAPI surfaces) | the `*:check` entries in `check:audits` |
+| Generated artifacts fresh (tool metadata, deployment config, docs, catalog, agent stream docs; CLI/MCP/OpenAPI surfaces) | the five `*:check` entries in `check:audits`; `check:cli-api`, `check:mcp-operations`, `check:openapi` |
 
 Rules not in this table (logging, the rest of comment style and naming, imports, styling, state ownership, caching) are enforced by review only; follow them as written.
diff --git a/scripts/check-guidance-refs.ts b/scripts/check-guidance-refs.ts
index 0848a1b3c5f..15c63d3def6 100644
--- a/scripts/check-guidance-refs.ts
+++ b/scripts/check-guidance-refs.ts
@@ -13,7 +13,8 @@
  *   (rules usually name app paths without the prefix). A path whose first segment exists in none
  *   of those is not treated as a path, so MIME types and prose like `basic/advanced` pass.
  * - `script`: `bun run <name>`, `turbo run <name>`, or a bare `check:<x>` / `<x>:check` that is
- *   not a script in any workspace `package.json`.
+ *   not a script in any workspace `package.json`; `bun run --cwd <dir> <name>` must be a script in
+ *   `<dir>/package.json`.
  * - `skill`: `/name` on a line that talks about skills, or `` `name` skill ``, with no
  *   `.agents/skills/<name>/SKILL.md`.
  * - `import`: an `@/…` or `@sim/…` specifier (in a code span, or a fenced `import`/`from` line)
@@ -30,13 +31,13 @@
  *
  * Run: `bun run check:guidance-refs`
  */
+import { execFileSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
 import path from 'node:path'
 
 const ROOT = path.resolve(import.meta.dir, '..')
 const APP_ROOT = path.join(ROOT, 'apps/sim')
 const SKILLS_DIR = path.join(ROOT, '.agents/skills')
-const SKIP_DIRS = new Set(['node_modules', '.git', '.next', '.turbo', 'dist', 'build', 'worktrees'])
 const SOURCE_EXTENSIONS = ['', '.ts', '.tsx', '.js', '.mjs', '.json', '.md', '.css']
 
 interface Finding {
@@ -53,22 +54,17 @@ function guidanceFiles(): string[] {
     const real = realpathSync(file)
     if (!found.has(real)) found.set(real, path.relative(ROOT, file))
   }
-  const walk = (dir: string) => {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      if (SKIP_DIRS.has(entry.name)) continue
-      const full = path.join(dir, entry.name)
-      if (entry.isDirectory()) {
-        // `.claude/skills` is a generated projection of `.agents/skills`.
-        if (full === path.join(ROOT, '.claude/skills') || full === path.join(ROOT, '.cursor')) {
-          continue
-        }
-        walk(full)
-      } else if (entry.name === 'AGENTS.md' || entry.name === 'CLAUDE.md') {
-        add(full)
-      }
-    }
+  const tracked = execFileSync(
+    'git',
+    ['ls-files', '--cached', '--others', '--exclude-standard', '*AGENTS.md', '*CLAUDE.md'],
+    { cwd: ROOT, encoding: 'utf8' }
+  )
+  for (const rel of tracked.split('\n')) {
+    // `.claude/skills` and `.cursor` are generated projections of `.agents/skills`.
+    if (!rel || rel.startsWith('.claude/skills/') || rel.startsWith('.cursor/')) continue
+    const full = path.join(ROOT, rel)
+    if (existsSync(full)) add(full)
   }
-  walk(ROOT)
   for (const entry of readdirSync(path.join(ROOT, '.claude/rules'))) {
     if (entry.endsWith('.md')) add(path.join(ROOT, '.claude/rules', entry))
   }
@@ -83,21 +79,30 @@ function guidanceFiles(): string[] {
   return [...found.values()].sort()
 }
 
+interface ScriptNames {
+  /** Every script declared by the root or any workspace. */
+  all: Set<string>
+  /** Scripts per workspace directory (`''` is the root), for `bun run --cwd <dir>`. */
+  byDir: Map<string, Set<string>>
+}
+
 /** Script names declared by the root and every workspace `package.json`. */
-function scriptNames(): Set<string> {
-  const names = new Set<string>()
-  const manifests = [path.join(ROOT, 'package.json')]
+function scriptNames(): ScriptNames {
+  const all = new Set<string>()
+  const byDir = new Map<string, Set<string>>()
+  const dirs = ['']
   for (const group of ['apps', 'packages']) {
     for (const entry of readdirSync(path.join(ROOT, group))) {
-      const manifest = path.join(ROOT, group, entry, 'package.json')
-      if (existsSync(manifest)) manifests.push(manifest)
+      if (existsSync(path.join(ROOT, group, entry, 'package.json'))) dirs.push(`${group}/${entry}`)
     }
   }
-  for (const manifest of manifests) {
-    const scripts = JSON.parse(readFileSync(manifest, 'utf8')).scripts ?? {}
-    for (const name of Object.keys(scripts)) names.add(name)
+  for (const dir of dirs) {
+    const manifest = path.join(ROOT, dir, 'package.json')
+    const names = new Set(Object.keys(JSON.parse(readFileSync(manifest, 'utf8')).scripts ?? {}))
+    byDir.set(dir, names)
+    for (const name of names) all.add(name)
   }
-  return names
+  return { all, byDir }
 }
 
 interface WorkspacePackage {
@@ -181,7 +186,7 @@ function skillExists(name: string): boolean {
 const CODE_SPAN = /`([^`\n]+)`/g
 const MD_LINK = /\]\(([^)\s]+)\)/g
 const SCRIPT_RUN =
-  /\b(?:bun run|turbo run|bunx turbo run)\s+(?:--filter[= ]\S+\s+|-F\s+\S+\s+)?([^\s`'"]+)/g
+  /\b(?:bun run|turbo run|bunx turbo run)\s+(?:--filter[= ]\S+\s+|-F\s+\S+\s+|--cwd[= ](\S+)\s+)?([^\s`'"]+)/g
 const IMPORT_SPEC = /(['"`])((?:@\/|@sim\/)[^'"`\s]+)\1/g
 const SKILL_SLASH = /(?:^|[\s(`"'])\/([a-z][a-z0-9]*(?:-[a-z0-9]+)+|[a-z]{3,})(?=[\s`)"',.:;]|$)/g
 const SKILL_NAMED = /`\/?([a-z][a-z0-9-]+)`\s+skills?\b/g
@@ -230,7 +235,7 @@ function trimProse(ref: string): string {
 /** Extracts every unresolved reference from one document. */
 function auditDocument(
   relFile: string,
-  scripts: Set<string>,
+  scripts: ScriptNames,
   packages: Map<string, WorkspacePackage>
 ): Finding[] {
   const findings: Finding[] = []
@@ -244,11 +249,17 @@ function auditDocument(
     findings.push({ file: relFile, line, kind, ref })
   }
 
-  const checkScript = (line: number, raw: string) => {
+  const checkScript = (line: number, raw: string, cwd?: string) => {
     const name = raw.replace(/[.,;:)]+$/, '')
     if (isPlaceholder(name) || name.includes('/') || name.endsWith('.ts')) return
     if (name.startsWith('-')) return
-    if (!scripts.has(name)) report(line, 'script', name)
+    if (cwd !== undefined) {
+      if (isPlaceholder(cwd)) return
+      const declared = scripts.byDir.get(cwd.replace(/^\.\//, '').replace(/\/$/, ''))
+      if (!declared?.has(name)) report(line, 'script', `${name} (in ${cwd})`)
+      return
+    }
+    if (!scripts.all.has(name)) report(line, 'script', name)
   }
 
   const checkPath = (line: number, raw: string) => {
@@ -273,7 +284,7 @@ function auditDocument(
       inFence = !inFence
       return
     }
-    for (const match of text.matchAll(SCRIPT_RUN)) checkScript(line, match[1])
+    for (const match of text.matchAll(SCRIPT_RUN)) checkScript(line, match[2], match[1])
     for (const match of text.matchAll(REPO_PATH)) checkPath(line, trimProse(match[1]))
     if (inFence) {
       // Example code: only imports are concrete enough to check.

From 79639a490ec7dff0e7025f5fb86bc9c1ce415c67 Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Fri, 2 Oct 2026 00:32:43 -0700
Subject: [PATCH 11/18] docs(agents): drop the hand-kept rule-to-check table
 from CLAUDE.md

Name the enforcing check on the rule's own bullet instead, and tighten the
Comments bullet.
---
 CLAUDE.md | 29 ++---------------------------
 1 file changed, 2 insertions(+), 27 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index f18013e0b65..5c0b615110a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,7 +6,7 @@ This file (also `AGENTS.md`) holds the repo-wide rules. Area detail lives in `.c
 
 - **Package manager**: `bun` and `bunx`, never `npm` and `npx`.
 - **Logging**: `createLogger` from `@sim/logger`; `logger.info` / `logger.warn` / `logger.error`, never `console.log`. Inside `withRouteHandler` the logger already carries the request ID — no manual `withMetadata({ requestId })`.
-- **Comments**: name things so the code explains itself. TSDoc documents exported APIs and non-obvious modules. An inline `//` is only for a terse, non-obvious *why*, or for a script-enforced `// <tag>: <reason>` annotation (`boundary-raw-fetch`, `double-cast-allowed`, `boundary-raw-json`, `untyped-response`, `rq-lint-allow`, `client-boundary-allow`, `utils-lint-allow`, …). A comment never narrates what the next line does, restates a name or type, or records change history ("moved from X", "previously", "now uses Y") — history belongs in the commit message. No `====` separators. The `/you-might-not-need-a-comment` skill applies this to a diff.
+- **Comments**: name things so the code explains itself. TSDoc documents exported APIs and non-obvious modules. An inline `//` is only for a terse, non-obvious *why*, or for a script-enforced `// <tag>: <reason>` annotation (`boundary-raw-fetch`, `double-cast-allowed`, `boundary-raw-json`, `untyped-response`, `rq-lint-allow`, `client-boundary-allow`, `utils-lint-allow`, …). History belongs in the commit message. No `====` separators or commented-out code (`check:comment-hygiene` enforces this). The `/you-might-not-need-a-comment` skill applies this to a diff.
 - **ID generation**: `generateId()` (UUID v4, the default) or `generateShortId(size?)` (URL-safe, 21 chars by default) from `@sim/utils/id` — never `crypto.randomUUID()`, `nanoid`, or `uuid`. Both use `crypto.getRandomValues()`, so they also work in non-secure (HTTP) browsers.
 - **Common utilities**: use the shared helpers from `@sim/utils` instead of inline implementations (`check:utils` bans most of the inline forms below):
   - `sleep(ms)` from `@sim/utils/helpers` — never `new Promise(resolve => setTimeout(resolve, ms))`
@@ -86,7 +86,7 @@ The `'use client'` server boundary, the app/worker runtime env split, and featur
 - **Imports**: absolute (`@/...`) only, never relative (a barrel `index.ts` re-exports its own siblings relatively). A folder with 3+ exports gets an `index.ts` barrel; never re-export from a non-barrel file. `import type` for type-only imports. Order and lazy-loading through barrels: `.claude/rules/sim-imports.md`.
 - **TypeScript**: no `any` and no non-null `!` (use precise types or `unknown` with guards; `check:explicit-any` ratchets both); no export nothing imports (`check:unused-exports`); a props interface for every component; `as const` for constant objects/arrays; explicit ref types (`useRef<HTMLDivElement>(null)`).
 - **Unused bindings** fail lint (biome `noUnusedVariables`, `noUnusedFunctionParameters`): delete the dead variable, import, or parameter and update callers; write `catch {}` when the error is unused. Prefix `_` only for a parameter that must hold its position because a later one is used. `const { a, ...rest } = obj` to omit keys is allowed. The rules carry no autofix, so `bun run lint` will not rename anything for you.
-- **Components**: `'use client'` only for hooks or browser APIs. Structure order, extraction thresholds, and list-render rules: `.claude/rules/sim-components.md`. Render-performance idioms (lazy-init refs, hoisting, `Map` pre-indexing, `[...arr].sort()`, never `toSorted()`): `.claude/rules/sim-react-performance.md`. For effect/state/memo/callback anti-patterns use the `/you-might-not-need-*` skills and verify against the running UI.
+- **Components**: `'use client'` only for hooks or browser APIs (`check:client-boundary` guards the server boundary). Structure order, extraction thresholds, and list-render rules: `.claude/rules/sim-components.md`. Render-performance idioms (lazy-init refs, hoisting, `Map` pre-indexing, `[...arr].sort()`, never `toSorted()`): `.claude/rules/sim-react-performance.md`. For effect/state/memo/callback anti-patterns use the `/you-might-not-need-*` skills and verify against the running UI.
 - **State ownership**: React Query owns server data — never `useState` + `fetch`; shareable client view-state (tabs, filters, search, pagination, selected id) lives in the URL via `nuqs`; Zustand owns global client state; `useState` owns UI-only state. Hooks: `.claude/rules/sim-hooks.md`. Stores (`devtools`, `persist` only with an explicit `partialize` whitelist, workflow value invariants): `.claude/rules/sim-stores.md`. URL state: `.claude/rules/sim-url-state.md`.
 - **Utils**: inline a helper with one consumer; create `utils.ts` when 2+ files share it — in `lib/` (app-wide) or `feature/utils/` (feature-scoped). Check `lib/` before writing a new one.
 - **Lists and menus** mirror the order the user already reads elsewhere (toolbar, settings nav), encoded in one exported order constant (resource menus share `RESOURCE_MENU_ORDER`, a product order that does not mirror the sidebar); a separator marks only a change in what the action acts on (typically one, before the destructive action): `.claude/rules/sim-list-ordering.md`.
@@ -149,28 +149,3 @@ bun run apps/sim/scripts/check-block-registry.ts origin/staging
 ```
 
 CI also runs `bun run check:migrations <base>` (it needs a base ref, so it is not in `check:audits`; run it with `origin/staging` when you touch `packages/db/migrations/**`), checks that `drizzle-kit generate` in `packages/db` produces no new migration, and runs a non-blocking `bun audit`. When an audit fails, its output and its script's header say what the rule protects; fix the code, never the check. Ratchet baselines (`scripts/*baseline.json`) only shrink: regenerate one with the update flag its failure output names (`--update` or `--update-baseline`) after removing violations, never to admit new debt. The one exception is `check:tool-registry-boundary`, whose module-count baseline is re-recorded when growth is deliberate (see its skill).
-
-| Written rule | Enforced by |
-| --- | --- |
-| Formatting, lint, no `nanoid`/`uuid` imports, no unused variables or parameters | `bun run lint` (biome) |
-| `@sim/utils` over inline idioms (`Math.random`, `crypto.randomUUID`, `JSON` clone, `instanceof Error` message, `setTimeout` sleep) | `check:utils` |
-| `apps → packages` only; realtime import bans | `check:boundaries`, `check:realtime-prune` |
-| Route contracts, no `zod` in routes or clients, `requestJson`, boundary annotations | `check:api-validation:strict`, `check:api-contract-routes`, `check:route-verbs` |
-| Application authorization funnel stays light; principal and capability policy | `check:application-graph`, `check:principal-kind-parity`, `check:capability-subject`, `check:actorless-executor-operations`, `check:permission-group-enforcement` |
-| `'use client'` server boundary | `check:client-boundary` |
-| React Query keys, `staleTime`, `signal` | `check:react-query` |
-| Zustand v5 selector stability | `check:zustand-v5` |
-| Tool registry out of client and prefetch graphs | `check:tool-registry-boundary` |
-| Outbound HTTP through the egress guard; tool request boundary | `check:egress-boundary`, `check:tool-request-boundary` |
-| Imports resolve under Turbopack; no `@/triggers` → `@/blocks` cycle | `check:import-specifiers`, `check:trigger-block-cycle` |
-| Canvas sentences, BYOK wiring, fork-dependent subblocks, reachable tool params | `check:canvas-sentences`, `check:byok-providers`, `check:fork-dependent-coverage`, `check:tool-param-reachability` |
-| Central mocks, colocated tests, script tests collected | `check:test-patterns`, `check:script-tests` |
-| Zero-downtime migrations | `check:migrations <base>` |
-| Unused files, exports, types, dependencies (exports and types ratcheted) | `check:unused-exports` (knip) |
-| No `any` or non-null `!` (ratcheted), no suppressions of either | `check:explicit-any` |
-| kebab-case file names; no file repeating its folder's name | `check:file-names` |
-| No banner separators or commented-out code | `check:comment-hygiene` |
-| Skills and rules projections in sync; guidance references resolve | `check:skills`, `check:guidance-refs` |
-| Generated artifacts fresh (tool metadata, deployment config, docs, catalog, agent stream docs; CLI/MCP/OpenAPI surfaces) | the five `*:check` entries in `check:audits`; `check:cli-api`, `check:mcp-operations`, `check:openapi` |
-
-Rules not in this table (logging, the rest of comment style and naming, imports, styling, state ownership, caching) are enforced by review only; follow them as written.

From 8e126e86589eb5dc8e8c3988ac981a3c93b04355 Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Fri, 2 Oct 2026 00:32:44 -0700
Subject: [PATCH 12/18] improvement(audits): share rule frontmatter parsing and
 fail on dead graph guards

check:guidance-refs reuses sync-skills' parseRule, reads workspace manifests
once from the root workspaces globs, and matches rule globs against one git
listing instead of a filesystem scan per glob (~2.5s to ~0.2s). Markdown
links now go through the shared path check. check:application-graph fails
when a forbidden prefix matches nothing under apps/sim.
---
 scripts/check-application-graph.ts |  28 +++-
 scripts/check-guidance-refs.ts     | 245 ++++++++++++-----------------
 scripts/sync-skills.ts             |  12 +-
 3 files changed, 135 insertions(+), 150 deletions(-)

diff --git a/scripts/check-application-graph.ts b/scripts/check-application-graph.ts
index c049f410816..dfeb9633404 100644
--- a/scripts/check-application-graph.ts
+++ b/scripts/check-application-graph.ts
@@ -68,8 +68,8 @@
  *    path and one on a once-a-month webhook read identically, which is why the
  *    deferred check stops at the edge's own target rather than walking past it.
  */
-import { existsSync, readFileSync, statSync } from 'node:fs'
-import { dirname, relative, resolve } from 'node:path'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { basename, dirname, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
@@ -283,7 +283,28 @@ export function findViolations({ root, forbidden }: GuardedRoot): GraphViolation
   return violations
 }
 
+/**
+ * Whether any path under `apps/sim` starts with `prefix`. A prefix that matches nothing guards
+ * nothing: the tree was renamed, and the audit would keep passing over it.
+ */
+function prefixMatchesAnything(prefix: string): boolean {
+  if (prefix.endsWith('/')) return existsSync(resolve(APP_ROOT, prefix))
+  const dir = resolve(APP_ROOT, dirname(prefix))
+  return existsSync(dir) && readdirSync(dir).some((entry) => entry.startsWith(basename(prefix)))
+}
+
 function main(): void {
+  const prefixes = new Set(GUARDED_ROOTS.flatMap((guarded) => Object.keys(guarded.forbidden)))
+  const dead = [...prefixes].filter((prefix) => !prefixMatchesAnything(prefix))
+  if (dead.length > 0) {
+    console.error(
+      `Application-graph audit forbids prefixes that match nothing under apps/sim: ${dead.join(', ')}\n` +
+        'The tree was renamed or removed. Point the key at its current path rather than leaving a\n' +
+        'guard that can never fire.\n'
+    )
+    process.exit(1)
+  }
+
   const violations: GraphViolation[] = []
   for (const guarded of GUARDED_ROOTS) {
     if (!existsSync(resolve(APP_ROOT, guarded.root))) {
@@ -310,10 +331,9 @@ function main(): void {
     process.exit(1)
   }
 
-  const trees = new Set(GUARDED_ROOTS.flatMap((guarded) => Object.keys(guarded.forbidden)))
   console.log(
     `✅ Application graph clean: ${GUARDED_ROOTS.length} roots reach none of ` +
-      `${trees.size} forbidden module trees`
+      `${prefixes.size} forbidden module trees`
   )
 }
 
diff --git a/scripts/check-guidance-refs.ts b/scripts/check-guidance-refs.ts
index 15c63d3def6..203000e7548 100644
--- a/scripts/check-guidance-refs.ts
+++ b/scripts/check-guidance-refs.ts
@@ -2,38 +2,27 @@
 /**
  * Fails when agent guidance names something that does not exist.
  *
- * Agents follow `CLAUDE.md`, every `AGENTS.md`, `.claude/rules/*.md`, and the skills under
- * `.agents/skills/` literally. A rule that points at a moved file, a renamed `check:*` script, a
- * deleted skill, or an import path that no longer resolves sends the agent searching for it, or
- * worse, recreating it. Code moves weekly and nothing else ties the prose to the tree, so this
- * audit resolves every concrete reference the guidance makes:
+ * Agents follow `CLAUDE.md`, every `AGENTS.md`, `.claude/rules/*.md`, and `.agents/skills/`
+ * literally, so a dead reference sends them searching for, or recreating, something that moved.
+ * Checked:
  *
- * - `path`: a backticked or linked repo path (`apps/sim/lib/...`, `.claude/rules/x.md`,
- *   `scripts/x.ts`). Resolved against the repo root, the document's directory, and `apps/sim`
- *   (rules usually name app paths without the prefix). A path whose first segment exists in none
- *   of those is not treated as a path, so MIME types and prose like `basic/advanced` pass.
- * - `script`: `bun run <name>`, `turbo run <name>`, or a bare `check:<x>` / `<x>:check` that is
- *   not a script in any workspace `package.json`; `bun run --cwd <dir> <name>` must be a script in
- *   `<dir>/package.json`.
- * - `skill`: `/name` on a line that talks about skills, or `` `name` skill ``, with no
- *   `.agents/skills/<name>/SKILL.md`.
- * - `import`: an `@/…` or `@sim/…` specifier (in a code span, or a fenced `import`/`from` line)
- *   that does not resolve to a file, directory, or package export.
- * - a rule's frontmatter `paths:` glob that matches no file, which silently stops the rule from
- *   loading for the code it was written for.
+ * - `path`: a backticked or linked repo path, resolved against the repo root, the document's
+ *   directory, and `apps/sim`. A token whose first segment exists in none of those is prose.
+ * - `script`: `bun run <name>`, `turbo run <name>`, or a bare `check:<x>` / `<x>:check` that no
+ *   workspace `package.json` declares; `bun run --cwd <dir> <name>` must be in `<dir>`.
+ * - `skill`: `/name` on a line about skills, or `` `name` skill ``, with no `SKILL.md`.
+ * - `import`: an `@/…` or `@sim/…` specifier that resolves to no file or package export.
+ * - a rule's frontmatter `paths:` glob that matches no file, so the rule never loads.
  *
- * Placeholders are skipped rather than allow-listed: anything containing `<…>`, `{…}`, `*`, or
- * an ellipsis is a pattern, not a reference. A reference in `~/…`, a URL, or another repo is out
- * of scope.
- *
- * Fix a finding by pointing the sentence at the current path or name, or delete the sentence when
- * the thing is gone. There is no baseline: guidance is small enough to keep at zero.
+ * Anything containing `<…>`, `{…}`, `*`, or an ellipsis is a placeholder and skipped. There is
+ * no baseline: fix the reference or delete the sentence.
  *
  * Run: `bun run check:guidance-refs`
  */
 import { execFileSync } from 'node:child_process'
-import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
 import path from 'node:path'
+import { parseRule } from './sync-skills'
 
 const ROOT = path.resolve(import.meta.dir, '..')
 const APP_ROOT = path.join(ROOT, 'apps/sim')
@@ -47,82 +36,82 @@ interface Finding {
   ref: string
 }
 
+/** Every tracked or untracked-but-not-ignored file, relative to the repo root. */
+function repoFiles(): string[] {
+  return execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard'], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    maxBuffer: 1 << 28,
+  })
+    .split('\n')
+    .filter(Boolean)
+}
+
 /** Every guidance document, deduplicated through symlinks (`AGENTS.md` -> `CLAUDE.md`). */
-function guidanceFiles(): string[] {
+function guidanceFiles(files: string[]): string[] {
   const found = new Map<string, string>()
-  const add = (file: string) => {
-    const real = realpathSync(file)
-    if (!found.has(real)) found.set(real, path.relative(ROOT, file))
-  }
-  const tracked = execFileSync(
-    'git',
-    ['ls-files', '--cached', '--others', '--exclude-standard', '*AGENTS.md', '*CLAUDE.md'],
-    { cwd: ROOT, encoding: 'utf8' }
-  )
-  for (const rel of tracked.split('\n')) {
+  for (const rel of files) {
+    const isGuidance =
+      ['AGENTS.md', 'CLAUDE.md'].includes(path.basename(rel)) ||
+      /^\.claude\/rules\/[^/]+\.md$/.test(rel) ||
+      /^\.agents\/skills\/.+\.md$/.test(rel)
     // `.claude/skills` and `.cursor` are generated projections of `.agents/skills`.
-    if (!rel || rel.startsWith('.claude/skills/') || rel.startsWith('.cursor/')) continue
+    if (!isGuidance || rel.startsWith('.claude/skills/') || rel.startsWith('.cursor/')) continue
     const full = path.join(ROOT, rel)
-    if (existsSync(full)) add(full)
-  }
-  for (const entry of readdirSync(path.join(ROOT, '.claude/rules'))) {
-    if (entry.endsWith('.md')) add(path.join(ROOT, '.claude/rules', entry))
+    if (!existsSync(full)) continue
+    const real = realpathSync(full)
+    if (!found.has(real)) found.set(real, rel)
   }
-  const walkSkills = (dir: string) => {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      const full = path.join(dir, entry.name)
-      if (entry.isDirectory()) walkSkills(full)
-      else if (entry.name.endsWith('.md')) add(full)
-    }
-  }
-  walkSkills(SKILLS_DIR)
   return [...found.values()].sort()
 }
 
-interface ScriptNames {
+interface WorkspacePackage {
+  dir: string
+  exports: string[]
+}
+
+interface Workspaces {
   /** Every script declared by the root or any workspace. */
-  all: Set<string>
+  scripts: Set<string>
   /** Scripts per workspace directory (`''` is the root), for `bun run --cwd <dir>`. */
-  byDir: Map<string, Set<string>>
+  scriptsByDir: Map<string, Set<string>>
+  /** Workspace packages by name, with their export subpaths. */
+  packages: Map<string, WorkspacePackage>
 }
 
-/** Script names declared by the root and every workspace `package.json`. */
-function scriptNames(): ScriptNames {
-  const all = new Set<string>()
-  const byDir = new Map<string, Set<string>>()
-  const dirs = ['']
-  for (const group of ['apps', 'packages']) {
-    for (const entry of readdirSync(path.join(ROOT, group))) {
-      if (existsSync(path.join(ROOT, group, entry, 'package.json'))) dirs.push(`${group}/${entry}`)
-    }
+/** Reads the root and every workspace `package.json` (from the root `workspaces` globs) once. */
+function readWorkspaces(files: string[]): Workspaces {
+  const root = JSON.parse(readFileSync(path.join(ROOT, 'package.json'), 'utf8'))
+  const patterns: string[] = Array.isArray(root.workspaces)
+    ? root.workspaces
+    : (root.workspaces?.packages ?? [])
+  const globs = patterns.map((pattern) => new Bun.Glob(`${pattern}/package.json`))
+  const dirs = [
+    '',
+    ...files.filter((rel) => globs.some((glob) => glob.match(rel))).map(path.dirname),
+  ]
+
+  const workspaces: Workspaces = {
+    scripts: new Set(),
+    scriptsByDir: new Map(),
+    packages: new Map(),
   }
   for (const dir of dirs) {
-    const manifest = path.join(ROOT, dir, 'package.json')
-    const names = new Set(Object.keys(JSON.parse(readFileSync(manifest, 'utf8')).scripts ?? {}))
-    byDir.set(dir, names)
-    for (const name of names) all.add(name)
-  }
-  return { all, byDir }
-}
-
-interface WorkspacePackage {
-  dir: string
-  exports: string[]
-}
-
-/** `@sim/*` packages by name, with their export subpaths. */
-function workspacePackages(): Map<string, WorkspacePackage> {
-  const packages = new Map<string, WorkspacePackage>()
-  for (const entry of readdirSync(path.join(ROOT, 'packages'))) {
-    const manifestPath = path.join(ROOT, 'packages', entry, 'package.json')
+    const manifestPath = path.join(ROOT, dir, 'package.json')
     if (!existsSync(manifestPath)) continue
     const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
-    if (typeof manifest.name !== 'string') continue
-    const exports =
-      manifest.exports && typeof manifest.exports === 'object' ? Object.keys(manifest.exports) : []
-    packages.set(manifest.name, { dir: path.join(ROOT, 'packages', entry), exports })
+    const names = new Set(Object.keys(manifest.scripts ?? {}))
+    workspaces.scriptsByDir.set(dir, names)
+    for (const name of names) workspaces.scripts.add(name)
+    if (dir && typeof manifest.name === 'string') {
+      const exports =
+        manifest.exports && typeof manifest.exports === 'object'
+          ? Object.keys(manifest.exports)
+          : []
+      workspaces.packages.set(manifest.name, { dir: path.join(ROOT, dir), exports })
+    }
   }
-  return packages
+  return workspaces
 }
 
 function isPlaceholder(ref: string): boolean {
@@ -145,14 +134,15 @@ function pathResolves(ref: string, docDir: string): boolean {
     .replace(/:\d+(-\d+)?$/, '')
     .replace(/\/$/, '')
   if (!clean) return true
-  const bases = [ROOT, docDir, APP_ROOT]
   if (PATH_PREFIXES.some((prefix) => clean.startsWith(prefix))) {
     return resolvesFrom(ROOT, clean)
   }
-  const first = clean.replace(/^\.\//, '').split('/')[0]
+  const bases = [ROOT, docDir, APP_ROOT]
+  const rel = clean.replace(/^\.\//, '')
+  const first = rel.split('/')[0]
   const anchored = bases.filter((base) => existsSync(path.join(base, first)))
   if (anchored.length === 0) return true
-  return anchored.some((base) => resolvesFrom(base, clean.replace(/^\.\//, '')))
+  return anchored.some((base) => resolvesFrom(base, rel))
 }
 
 function importResolves(spec: string, packages: Map<string, WorkspacePackage>): boolean {
@@ -196,33 +186,6 @@ const CHECK_TOKEN = /^(check:[\w:-]+|[\w-]+:check)$/
 const PATH_TOKEN = /^\.{0,2}\/?[\w@.()[\]-]+(?:\/[\w@.()[\]-]*)+$/
 const BARE_DOC = /^[\w.-]+\.md$/
 
-/**
- * The `paths:` globs in a rule's frontmatter. A glob that matches nothing silently stops the rule
- * from loading for the files it was written for.
- */
-function frontmatterPaths(lines: string[]): Array<{ line: number; glob: string }> {
-  if (lines[0] !== '---') return []
-  const globs: Array<{ line: number; glob: string }> = []
-  let inPaths = false
-  for (let index = 1; index < lines.length && lines[index] !== '---'; index++) {
-    const text = lines[index]
-    if (/^paths:\s*$/.test(text)) {
-      inPaths = true
-      continue
-    }
-    const item = text.match(/^\s+-\s+["']?([^"']+)["']?\s*$/)
-    if (inPaths && item) globs.push({ line: index + 1, glob: item[1] })
-    else if (!/^\s/.test(text)) inPaths = false
-  }
-  return globs
-}
-
-function globMatchesAnything(pattern: string): boolean {
-  const glob = new Bun.Glob(pattern)
-  for (const _ of glob.scanSync({ cwd: ROOT, onlyFiles: true })) return true
-  return false
-}
-
 /** Drops sentence punctuation and an unbalanced closing paren from a path found in running text. */
 function trimProse(ref: string): string {
   let trimmed = ref.replace(/[.,:;]+$/, '')
@@ -233,11 +196,7 @@ function trimProse(ref: string): string {
 }
 
 /** Extracts every unresolved reference from one document. */
-function auditDocument(
-  relFile: string,
-  scripts: ScriptNames,
-  packages: Map<string, WorkspacePackage>
-): Finding[] {
+function auditDocument(relFile: string, workspaces: Workspaces, files: string[]): Finding[] {
   const findings: Finding[] = []
   const file = path.join(ROOT, relFile)
   const docDir = path.dirname(file)
@@ -251,30 +210,36 @@ function auditDocument(
 
   const checkScript = (line: number, raw: string, cwd?: string) => {
     const name = raw.replace(/[.,;:)]+$/, '')
-    if (isPlaceholder(name) || name.includes('/') || name.endsWith('.ts')) return
-    if (name.startsWith('-')) return
+    if (isPlaceholder(name) || name.includes('/') || name.endsWith('.ts') || name.startsWith('-')) {
+      return
+    }
     if (cwd !== undefined) {
       if (isPlaceholder(cwd)) return
-      const declared = scripts.byDir.get(cwd.replace(/^\.\//, '').replace(/\/$/, ''))
+      const declared = workspaces.scriptsByDir.get(cwd.replace(/^\.\//, '').replace(/\/$/, ''))
       if (!declared?.has(name)) report(line, 'script', `${name} (in ${cwd})`)
       return
     }
-    if (!scripts.all.has(name)) report(line, 'script', name)
+    if (!workspaces.scripts.has(name)) report(line, 'script', name)
   }
 
   const checkPath = (line: number, raw: string) => {
     if (isPlaceholder(raw) || /^[a-z]+:\/\//i.test(raw) || raw.startsWith('~')) return
     if (raw.startsWith('@/') || raw.startsWith('@sim/')) {
-      if (!importResolves(raw, packages)) report(line, 'import', raw)
+      if (!importResolves(raw, workspaces.packages)) report(line, 'import', raw)
       return
     }
     if (raw.startsWith('/')) return
     if (!pathResolves(raw, docDir)) report(line, 'path', raw)
   }
 
-  const lines = readFileSync(file, 'utf8').split('\n')
-  for (const { line, glob } of frontmatterPaths(lines)) {
-    if (!globMatchesAnything(glob)) report(line, 'path', glob)
+  const raw = readFileSync(file, 'utf8')
+  const lines = raw.split('\n')
+  if (relFile.startsWith('.claude/rules/')) {
+    for (const glob of parseRule(path.basename(relFile, '.md'), raw).paths) {
+      const matcher = new Bun.Glob(glob)
+      if (files.some((rel) => matcher.match(rel))) continue
+      report(lines.findIndex((text) => text.includes(glob)) + 1, 'path', glob)
+    }
   }
 
   let inFence = false
@@ -301,22 +266,20 @@ function auditDocument(
         continue
       }
       for (const imported of span.matchAll(IMPORT_SPEC)) checkPath(line, imported[2])
-      if (span.startsWith('@/') || span.startsWith('@sim/')) {
-        checkPath(line, span.split(/\s/)[0])
-        continue
-      }
       const token = span.split(/\s/)[0]
-      if (span === token && PATH_TOKEN.test(token)) checkPath(line, token)
-      else if (span === token && BARE_DOC.test(token) && !isPlaceholder(token)) {
+      // An import specifier is checked even when prose follows it in the span.
+      if (span !== token && !/^@(?:sim)?\//.test(token)) continue
+      if (PATH_TOKEN.test(token)) checkPath(line, token)
+      else if (BARE_DOC.test(token) && !isPlaceholder(token)) {
         const bases = [docDir, ROOT, path.join(ROOT, '.claude/rules')]
         if (!bases.some((base) => existsSync(path.join(base, token)))) report(line, 'path', token)
       }
     }
     for (const match of text.matchAll(MD_LINK)) {
       const target = match[1]
-      if (/^(https?:|mailto:|#)/.test(target)) continue
-      const resolved = target.startsWith('/') ? target.slice(1) : target
-      if (!pathResolves(resolved, docDir)) report(line, 'path', target)
+      if (/^(mailto:|#)/.test(target)) continue
+      // A leading `/` in a link is the repo root.
+      checkPath(line, target.replace(/^\//, ''))
     }
 
     const outsideSpans = text.replace(/`[^`\n]*`/g, (span) =>
@@ -335,10 +298,10 @@ function auditDocument(
 }
 
 if (import.meta.main) {
-  const files = guidanceFiles()
-  const scripts = scriptNames()
-  const packages = workspacePackages()
-  const findings = files.flatMap((file) => auditDocument(file, scripts, packages))
+  const files = repoFiles()
+  const docs = guidanceFiles(files)
+  const workspaces = readWorkspaces(files)
+  const findings = docs.flatMap((doc) => auditDocument(doc, workspaces, files))
 
   if (findings.length > 0) {
     const fixes: Record<Finding['kind'], string> = {
@@ -360,5 +323,5 @@ if (import.meta.main) {
     process.exit(1)
   }
 
-  console.log(`Guidance references resolve: ${files.length} documents checked.`)
+  console.log(`Guidance references resolve: ${docs.length} documents checked.`)
 }
diff --git a/scripts/sync-skills.ts b/scripts/sync-skills.ts
index bf9914a11bf..caa31611c67 100644
--- a/scripts/sync-skills.ts
+++ b/scripts/sync-skills.ts
@@ -102,7 +102,7 @@ interface Rule {
 }
 
 /** Parse a canonical rule: `description`, optional `paths` list, then the body. */
-function parseRule(name: string, raw: string): Rule {
+export function parseRule(name: string, raw: string): Rule {
   if (!raw.startsWith('---\n')) {
     throw new Error(`${name}: rule must start with a '---' frontmatter block`)
   }
@@ -329,7 +329,9 @@ async function main() {
   )
 }
 
-main().catch((err) => {
-  console.error(err instanceof Error ? err.message : err)
-  process.exit(1)
-})
+if (import.meta.main) {
+  main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err)
+    process.exit(1)
+  })
+}

From 446b4ebe4bba9d4e00fb9e0a06c64057ee4db9a3 Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Fri, 2 Oct 2026 00:53:11 -0700
Subject: [PATCH 13/18] fix(audits): resolve wildcard and root package exports,
 ignore deleted files and test-only guards

check:guidance-refs now requires a bare @sim/<pkg> import to have a '.' export, checks that a wildcard export match maps to an existing file, and drops index entries missing from the working tree before matching rule path globs. check:application-graph no longer counts a leftover test file as keeping a non-directory forbidden prefix alive.
---
 scripts/check-application-graph.ts | 12 ++++++---
 scripts/check-guidance-refs.ts     | 41 ++++++++++++++++++++----------
 2 files changed, 37 insertions(+), 16 deletions(-)

diff --git a/scripts/check-application-graph.ts b/scripts/check-application-graph.ts
index dfeb9633404..b2b9e17045d 100644
--- a/scripts/check-application-graph.ts
+++ b/scripts/check-application-graph.ts
@@ -284,13 +284,19 @@ export function findViolations({ root, forbidden }: GuardedRoot): GraphViolation
 }
 
 /**
- * Whether any path under `apps/sim` starts with `prefix`. A prefix that matches nothing guards
- * nothing: the tree was renamed, and the audit would keep passing over it.
+ * Whether `prefix` names a directory or an importable module under `apps/sim`. A prefix that
+ * matches nothing guards nothing: the tree was renamed, and the audit would keep passing over it.
+ * A test file left behind does not count, because no runtime import resolves to it.
  */
 function prefixMatchesAnything(prefix: string): boolean {
   if (prefix.endsWith('/')) return existsSync(resolve(APP_ROOT, prefix))
   const dir = resolve(APP_ROOT, dirname(prefix))
-  return existsSync(dir) && readdirSync(dir).some((entry) => entry.startsWith(basename(prefix)))
+  if (!existsSync(dir)) return false
+  return readdirSync(dir, { withFileTypes: true }).some(
+    (entry) =>
+      entry.name.startsWith(basename(prefix)) &&
+      (entry.isDirectory() || /(?<!\.test)\.tsx?$/.test(entry.name))
+  )
 }
 
 function main(): void {
diff --git a/scripts/check-guidance-refs.ts b/scripts/check-guidance-refs.ts
index 203000e7548..6b8ae8097ba 100644
--- a/scripts/check-guidance-refs.ts
+++ b/scripts/check-guidance-refs.ts
@@ -36,7 +36,10 @@ interface Finding {
   ref: string
 }
 
-/** Every tracked or untracked-but-not-ignored file, relative to the repo root. */
+/**
+ * Every tracked or untracked-but-not-ignored file on disk, relative to the repo root. A file
+ * deleted from the working tree but still in the index is dropped.
+ */
 function repoFiles(): string[] {
   return execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard'], {
     cwd: ROOT,
@@ -44,7 +47,7 @@ function repoFiles(): string[] {
     maxBuffer: 1 << 28,
   })
     .split('\n')
-    .filter(Boolean)
+    .filter((rel) => rel && existsSync(path.join(ROOT, rel)))
 }
 
 /** Every guidance document, deduplicated through symlinks (`AGENTS.md` -> `CLAUDE.md`). */
@@ -67,7 +70,8 @@ function guidanceFiles(files: string[]): string[] {
 
 interface WorkspacePackage {
   dir: string
-  exports: string[]
+  /** The `exports` map, or null when the package declares none. */
+  exports: Record<string, unknown> | null
 }
 
 interface Workspaces {
@@ -105,9 +109,7 @@ function readWorkspaces(files: string[]): Workspaces {
     for (const name of names) workspaces.scripts.add(name)
     if (dir && typeof manifest.name === 'string') {
       const exports =
-        manifest.exports && typeof manifest.exports === 'object'
-          ? Object.keys(manifest.exports)
-          : []
+        manifest.exports && typeof manifest.exports === 'object' ? manifest.exports : null
       workspaces.packages.set(manifest.name, { dir: path.join(ROOT, dir), exports })
     }
   }
@@ -158,17 +160,30 @@ function importResolves(spec: string, packages: Map<string, WorkspacePackage>):
   const [scope, name, ...rest] = clean.split('/')
   const pkg = packages.get(`${scope}/${name}`)
   if (!pkg) return false
-  if (rest.length === 0) return true
-  const subpath = `./${rest.join('/')}`
-  if (pkg.exports.length === 0) return resolvesFrom(pkg.dir, rest.join('/'))
-  return pkg.exports.some((key) => {
-    if (key === subpath) return true
-    if (!key.includes('*')) return false
+  if (!pkg.exports) return rest.length === 0 || resolvesFrom(pkg.dir, rest.join('/'))
+  const subpath = rest.length === 0 ? '.' : `./${rest.join('/')}`
+  return Object.entries(pkg.exports).some(([key, value]) => {
     const [head, tail] = key.split('*')
-    return subpath.startsWith(head) && subpath.endsWith(tail)
+    if (tail === undefined) return key === subpath
+    if (!subpath.startsWith(head) || !subpath.endsWith(tail)) return false
+    // A wildcard export only proves the pattern; the file it maps to must also exist.
+    const target = exportTarget(value)
+    const matched = subpath.slice(head.length, subpath.length - tail.length)
+    return target !== null && resolvesFrom(pkg.dir, target.replace('*', matched))
   })
 }
 
+/** The first file path an export condition map points at. */
+function exportTarget(value: unknown): string | null {
+  if (typeof value === 'string') return value
+  if (!value || typeof value !== 'object') return null
+  for (const nested of Object.values(value)) {
+    const target = exportTarget(nested)
+    if (target) return target
+  }
+  return null
+}
+
 function skillExists(name: string): boolean {
   return existsSync(path.join(SKILLS_DIR, name, 'SKILL.md'))
 }

From b4ac006c05aeadc44337a0bfb2635c73dfd2b7c9 Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Fri, 2 Oct 2026 00:53:13 -0700
Subject: [PATCH 14/18] docs(agents): correct review findings in skills and
 rules

Scope SSRF, client-boundary, forcedToolUse, canonicalParamId, integration metadata, and HEAD claims to what the code does; fix the ship migration pathspec, the babysit conflict path, enrichment folder placeholders, framer-motion samples, and stale connector and column-type references.
---
 .agents/skills/add-column-type/SKILL.md                  | 2 +-
 .agents/skills/add-connector/SKILL.md                    | 4 ++--
 .agents/skills/add-enrichment/SKILL.md                   | 6 +++---
 .agents/skills/add-integration/SKILL.md                  | 2 +-
 .agents/skills/add-model/SKILL.md                        | 2 +-
 .agents/skills/add-permission-group-item/SKILL.md        | 4 ++--
 .agents/skills/babysit/SKILL.md                          | 5 +++--
 .agents/skills/design-taste-frontend/SKILL.md            | 8 ++++----
 .agents/skills/make-interfaces-feel-better/animations.md | 4 ++--
 .agents/skills/memory-load-check/SKILL.md                | 2 +-
 .agents/skills/ship/SKILL.md                             | 2 +-
 .agents/skills/v2-api-conventions/SKILL.md               | 2 +-
 .agents/skills/validate-permission-group-item/SKILL.md   | 2 +-
 .agents/skills/validate-trigger/SKILL.md                 | 2 +-
 .agents/skills/you-might-not-need-url-state/SKILL.md     | 2 +-
 .claude/rules/sim-architecture.md                        | 2 +-
 .claude/rules/sim-integrations.md                        | 4 ++--
 .claude/rules/sim-testing.md                             | 2 +-
 .cursor/rules/sim-architecture.mdc                       | 2 +-
 .cursor/rules/sim-integrations.mdc                       | 4 ++--
 .cursor/rules/sim-testing.mdc                            | 2 +-
 CLAUDE.md                                                | 1 +
 22 files changed, 34 insertions(+), 32 deletions(-)

diff --git a/.agents/skills/add-column-type/SKILL.md b/.agents/skills/add-column-type/SKILL.md
index 6a222a83bfc..91c27e4083c 100644
--- a/.agents/skills/add-column-type/SKILL.md
+++ b/.agents/skills/add-column-type/SKILL.md
@@ -132,7 +132,7 @@ Registering the *type* is compiler-enforced. Registering its *metadata* is not,
 | `column-types/types.ts` `TYPE_SPECIFIC_COLUMN_KEYS` | it is never stripped on conversion, and poisons the target type |
 | `lib/api/contracts/tables.ts` — the schema slot in all three column schemas, plus `refineColumnOptions` | zod strips it at the boundary; silently never saved |
 | `columns/service.ts` `addTableColumn` param type | callers cannot pass it |
-| A metadata-only update in `lib/table/columns/service.ts` (`updateColumnCurrency` is the model) + a branch in `updateColumn` in `lib/table/orchestration/columns.ts` | changing it on an existing column is a silent 200 no-op |
+| A metadata-only update in `lib/table/columns/service.ts` (`updateColumnCurrency` is the model) + a branch in `performUpdateTableColumn` in `lib/table/orchestration/columns.ts` | changing it on an existing column is a silent 200 no-op |
 | `column-config-sidebar.tsx` | no UI to set it |
 | `table-grid.tsx` delete-column undo + `use-table-undo.ts` restore | undo silently resets it to the default |
 
diff --git a/.agents/skills/add-connector/SKILL.md b/.agents/skills/add-connector/SKILL.md
index 894db91cee1..cfc24489aee 100644
--- a/.agents/skills/add-connector/SKILL.md
+++ b/.agents/skills/add-connector/SKILL.md
@@ -515,7 +515,7 @@ mapTags: (metadata: Record<string, unknown>): Record<string, unknown> => {
 
 ## External API Calls — Use `fetchWithRetry`
 
-All external API calls must use `fetchWithRetry` from `@/lib/knowledge/documents/secure-fetch.server` (SSRF-guarded) instead of raw `fetch()`; use `secureFetchWithRetry` for user-controlled hosts. This provides exponential backoff with retries on 429/502/503/504 errors. It returns a standard `Response` — all `.ok`, `.json()`, `.text()` checks work unchanged.
+All external API calls must use `fetchWithRetry` from `@/lib/knowledge/documents/secure-fetch.server` instead of raw `fetch()`. It does not validate the host (on a direct outbound route it calls plain `fetch`), so use `secureFetchWithRetry` for user-controlled hosts. This provides exponential backoff with retries on 429/502/503/504 errors. It returns a standard `Response` — all `.ok`, `.json()`, `.text()` checks work unchanged.
 
 For `validateConfig` (user-facing, called on save), pass `VALIDATE_RETRY_OPTIONS` to cap wait time at ~7s. Background operations (`listDocuments`, `getDocument`) use the built-in defaults (5 retries within a 150s budget).
 
@@ -605,7 +605,7 @@ export const CONNECTOR_META_REGISTRY: ConnectorMetaRegistry = {
 - **OAuth + contentDeferred**: `apps/sim/connectors/google-drive/google-drive.ts` — file download with metadata-based hash, `orderBy` for deterministic pagination
 - **OAuth + contentDeferred (blocks API)**: `apps/sim/connectors/notion/notion.ts` — complex block content extraction deferred to `getDocument`
 - **OAuth + contentDeferred (git)**: `apps/sim/connectors/github/github.ts` — blob SHA hash, tree listing
-- **OAuth + inline content**: `apps/sim/connectors/slack/slack.ts` — list API returns message content inline; `contentHash` hashes that content
+- **OAuth + inline content**: `apps/sim/connectors/airtable/airtable.ts` — list API returns record fields inline; `listDocuments` and `getDocument` share `recordToDocument`, which hashes that content
 - **OAuth + contentDeferred + config fields**: `apps/sim/connectors/confluence/confluence.ts` — multiple config field types, `mapTags`, label fetching
 - **API key**: `apps/sim/connectors/fireflies/fireflies.ts` — GraphQL API with Bearer token auth
 
diff --git a/.agents/skills/add-enrichment/SKILL.md b/.agents/skills/add-enrichment/SKILL.md
index 7a4d93bbf94..32b1bad4417 100644
--- a/.agents/skills/add-enrichment/SKILL.md
+++ b/.agents/skills/add-enrichment/SKILL.md
@@ -16,7 +16,7 @@ Because enrichments run on Sim's hosted keys by default, **every provider tool y
 |------|------|-------|
 | 1 | Pick the data-source tool(s) for each output | `tools/{service}/` + `tools/registry.ts` |
 | 2 | **Verify each tool has `hosting`; if not, run `/add-hosted-key`** | `tools/{service}/{action}.ts` |
-| 3 | Write the enrichment definition | `enrichments/{name}/{name}.ts` + `index.ts` |
+| 3 | Write the enrichment definition | `enrichments/{id}/{id}.ts` + `index.ts` |
 | 4 | Register it | `enrichments/registry.ts` |
 | 5 | Verify | tsc / biome / manual run |
 
@@ -60,7 +60,7 @@ Why it matters: the cascade runner only bills (and only reads `output.cost.total
 
 ## Step 3: Write the enrichment definition
 
-Create `apps/sim/enrichments/{name}/{name}.ts` and a barrel `index.ts`. Mirror the entries registered in `enrichments/registry.ts`.
+Create `apps/sim/enrichments/{id}/{id}.ts` and a barrel `index.ts`. Mirror the entries registered in `enrichments/registry.ts`.
 
 ```typescript
 import { SomeIcon } from '@sim/emcn/icons'
@@ -104,7 +104,7 @@ export const myEnrichment: EnrichmentConfig = {
 ```
 
 ```typescript
-// apps/sim/enrichments/{name}/index.ts
+// apps/sim/enrichments/{id}/index.ts
 export { myEnrichment } from './my-enrichment'
 ```
 
diff --git a/.agents/skills/add-integration/SKILL.md b/.agents/skills/add-integration/SKILL.md
index 5ee161e182a..07c33c130b7 100644
--- a/.agents/skills/add-integration/SKILL.md
+++ b/.agents/skills/add-integration/SKILL.md
@@ -497,7 +497,7 @@ Use the basic/advanced mode pattern:
 },
 ```
 
-**Critical:** `canonicalParamId` must NOT match any subblock `id`.
+**Critical:** `canonicalParamId` must NOT match the `id` of a subblock outside its canonical group.
 
 #### 2. Normalize File Input in Block Config
 
diff --git a/.agents/skills/add-model/SKILL.md b/.agents/skills/add-model/SKILL.md
index 53ee0ceb4a1..75721721c4b 100644
--- a/.agents/skills/add-model/SKILL.md
+++ b/.agents/skills/add-model/SKILL.md
@@ -49,7 +49,7 @@ Use a precise WebFetch prompt: *"Extract for {model_id}: exact model id string,
 |---|---|---|
 | `temperature` | All providers (passed through if set) | Safe but inert on always-reasoning models that reject it |
 | `toolUsageControl` | All providers (provider-level default) | Override per model only when that model differs |
-| `forcedToolUse` | Defaults to `toolUsageControl` | Set only when the model cannot force tools |
+| `forcedToolUse` | `anthropic/core.ts` (anthropic, azure-anthropic, kie); defaults to `toolUsageControl` | Ignored by every other provider; set `false` only on a model behind that core that cannot force tools |
 | `promptCaching` | Caller-placed cache breakpoints | Set only where the vendor charges for opt-in caching (absent for OpenAI/Gemini implicit caching) |
 | `reasoningEffort` | `openai/core.ts`, `azure-openai`, `xai`, `deepseek`, `groq`, `zai`, `kimi`, `cerebras`, `meta`, `litellm` (each `index.ts`) | Not read by anthropic/gemini (they use `thinking`) or by mistral, openrouter, fireworks, vertex — re-grep before assuming |
 | `verbosity` | `openai/core.ts`, `azure-openai/index.ts` only | Dead elsewhere |
diff --git a/.agents/skills/add-permission-group-item/SKILL.md b/.agents/skills/add-permission-group-item/SKILL.md
index 23abe85a444..e5a90a007b9 100644
--- a/.agents/skills/add-permission-group-item/SKILL.md
+++ b/.agents/skills/add-permission-group-item/SKILL.md
@@ -60,7 +60,7 @@ Allowlist when the safe posture is "only what the admin named" and the member se
 
 The second argument is the field's `feature` (`PlatformFeatureMeta`); `PLATFORM_FEATURES` spreads it and appends `configKey`, so those four values are what the editor renders. `PLATFORM_FEATURES` is *derived* from the registry in `features.ts`, so a boolean key cannot reach the config without reaching the editor.
 
-- **Declaration order is the wire order** of `PermissionGroupConfig`, both zod schemas, and every config JSON crossing the API. No test catches a reorder (schemas and defaults all derive from the registry), and `ee/access-control/components/group-detail.tsx` dirty-checks by comparing stringified configs, so a moved key makes every open editor read as unsaved. Extend the tail; do not tidy the middle.
+- **Declaration order is the wire order** of `PermissionGroupConfig`, both zod schemas, and every config JSON crossing the API, since all of them derive from the registry. Extend the tail; do not tidy the middle.
 - **The default must be the permissive value.** Every stored `permission_group.config` row predates your key; `parsePermissionGroupConfig` fills the gap from the default and the update route merges a partial write over the stored config, so a restrictive default silently applies a new restriction to every existing group in every enterprise org. The builders hardcode `false` / `null` / `[]`, so a new key must be *phrased* so the permissive value is falsy: a `requireWidgetApproval` whose safe default is `true` must be inverted before it can use `booleanRestriction`.
 - **The checkbox is inverted.** `group-detail.tsx` renders `checked={!editingConfig[feature.configKey]}` — ticked means *allowed*, so an `allowX` name renders backwards.
 - **The hint must describe access withheld, never a surface hidden.** A `'capability'` key refuses at the API; "Hide the Tables module from the sidebar" tells an admin they are tidying a nav bar while they revoke a module. The same string is read again by `getActivePermissionGroupRestrictions` in `features.ts` as the prose for an *active* restriction — reaching users through the Copilot workspace VFS and the enterprise platform context — where "hide" is simply false. Write "Revoke the Tables module. Members cannot read or write any table." `PlatformFeatureMeta.hint` carries the rule in its TSDoc.
@@ -213,7 +213,7 @@ cd apps/sim && bun run type-check
 bun run --cwd apps/sim test lib/permission-groups
 ```
 
-Also `bun run check:api-validation:strict` if you touched a contract or the group routes. `bun run check:audits` runs every one of these (including the `:strict` variant); it derives its list from the `check:*` scripts in `package.json`, so a new audit is opted *out* deliberately rather than opted in.
+Also `bun run check:api-validation:strict` if you touched a contract or the group routes. `bun run check:audits` runs every `check:*` command here (including the `:strict` variant) but not type-check or the tests; it derives its list from the `check:*` scripts in `package.json`, so a new audit is opted *out* deliberately rather than opted in.
 
 Read the success lines, not the exit codes — compare the counts against the previous run and check they grew by exactly what you added: an operation-declared capability adds one operation and one capability; a raw-route or parameterized capability adds one capability and no operation; an executor-gated or UI-only item adds neither:
 
diff --git a/.agents/skills/babysit/SKILL.md b/.agents/skills/babysit/SKILL.md
index c8810e7dd0f..7a4dbca020f 100644
--- a/.agents/skills/babysit/SKILL.md
+++ b/.agents/skills/babysit/SKILL.md
@@ -88,8 +88,9 @@ conditions freshly after every push.
    across all pages has `isResolved: true`, and every check has finished and passed, stop —
    report the outcome (see "Reporting" below) and skip the rest of this list.
 
-2. **If the PR has a merge conflict**, merge `origin/staging`, resolve the conflicts, run `/ship`
-   steps 4–6 on the merge result, push, and go to step 8 to re-trigger review.
+2. **If the PR has a merge conflict**, merge `origin/staging`, resolve the conflicts, then
+   follow steps 6–8 on the merge result: the full sync check plus `/ship` steps 4–6, push, and
+   re-trigger review.
 
 3. **If no review has run yet** (fresh PR, no bot comments): both run automatically on PR open —
    confirm via `gh pr checks <n>` (look for `Greptile Review` and `cubic · AI code reviewer`) and
diff --git a/.agents/skills/design-taste-frontend/SKILL.md b/.agents/skills/design-taste-frontend/SKILL.md
index 32d52ff68c9..428c7adf9c9 100644
--- a/.agents/skills/design-taste-frontend/SKILL.md
+++ b/.agents/skills/design-taste-frontend/SKILL.md
@@ -4,7 +4,7 @@ source: https://github.com/leonxlnx/taste-skill — skills/taste-skill/SKILL.md
 description: Anti-slop frontend skill for landing pages, portfolios, and redesigns. The agent reads the brief, infers the right design direction, and ships interfaces that do not look templated. Real design systems when applicable, audit-first on redesigns, strict pre-flight check.
 ---
 
-> **In this repo:** Tailwind 4 (CSS-first config in `apps/sim/app/_styles/globals.css`); animation via `import { motion } from 'framer-motion'` (not `motion/react` — rewrite every `motion/react` import in the samples below); icons from `@sim/emcn/icons`; colors through the CSS-variable tokens in `.claude/rules/sim-styling.md` (no hardcoded `text-gray-*`/hex/`zinc` utilities, no paired `dark:` utilities). This note overrides any conflicting guidance or code sample anywhere in this file. Fonts are fixed (Season body, Inter); never introduce new families, and never use Martian Mono on landing (`apps/sim/app/(landing)/CLAUDE.md`). Font weight is only `font-normal`/`font-medium`/`font-semibold`. Elevation uses the `shadow-subtle|medium|overlay|card` tokens. Type size uses named tokens, never `text-[Npx]`. Product forms use `ChipModalField`. Use `bunx`, never `npx`. Do not add GSAP, Lenis, Three, or shadcn. Landing copy and SEO follow `.claude/rules/constitution.md` and `.claude/rules/landing-seo-geo.md`.
+> **In this repo:** Tailwind 4 (CSS-first config in `apps/sim/app/_styles/globals.css`); animation via `import { motion } from 'framer-motion'` (not `motion/react`); icons from `@sim/emcn/icons`; colors through the CSS-variable tokens in `.claude/rules/sim-styling.md` (no hardcoded `text-gray-*`/hex/`zinc` utilities, no paired `dark:` utilities). This note overrides any conflicting guidance or code sample anywhere in this file. Fonts are fixed (Season body, Inter); never introduce new families, and never use Martian Mono on landing (`apps/sim/app/(landing)/CLAUDE.md`). Font weight is only `font-normal`/`font-medium`/`font-semibold`. Elevation uses the `shadow-subtle|medium|overlay|card` tokens. Type size uses named tokens, never `text-[Npx]`. Every labeled field inside a `ChipModalBody` is a `ChipModalField`. Use `bunx`, never `npx`. Do not add GSAP, Lenis, Three, or shadcn. Landing copy and SEO follow `.claude/rules/constitution.md` and `.claude/rules/landing-seo-geo.md`.
 
 # tasteskill: Anti-Slop Frontend Skill
 
@@ -345,7 +345,7 @@ These are tools, not defaults. Use them when the design read calls for them. **N
 import { useRef, useEffect } from "react";
 import { gsap } from "gsap";
 import { ScrollTrigger } from "gsap/ScrollTrigger";
-import { useReducedMotion } from "motion/react";
+import { useReducedMotion } from "framer-motion";
 
 gsap.registerPlugin(ScrollTrigger);
 
@@ -407,7 +407,7 @@ Critical points: `start: "top top"`, `pin: true`, every card except the last is
 import { useRef, useEffect } from "react";
 import { gsap } from "gsap";
 import { ScrollTrigger } from "gsap/ScrollTrigger";
-import { useReducedMotion } from "motion/react";
+import { useReducedMotion } from "framer-motion";
 
 gsap.registerPlugin(ScrollTrigger);
 
@@ -454,7 +454,7 @@ For simple "items appear as they enter viewport" (no pinning), prefer Motion's `
 
 ```tsx
 "use client";
-import { motion, useReducedMotion } from "motion/react";
+import { motion, useReducedMotion } from "framer-motion";
 
 export function RevealStagger({ items }: { items: string[] }) {
   const reduce = useReducedMotion();
diff --git a/.agents/skills/make-interfaces-feel-better/animations.md b/.agents/skills/make-interfaces-feel-better/animations.md
index a9aad9bac09..1f6ffdcbd8c 100644
--- a/.agents/skills/make-interfaces-feel-better/animations.md
+++ b/.agents/skills/make-interfaces-feel-better/animations.md
@@ -191,7 +191,7 @@ When icons appear or disappear contextually (on hover, on state change), animate
 ### Motion Example
 
 ```tsx
-import { AnimatePresence, motion } from "motion/react";
+import { AnimatePresence, motion } from "framer-motion";
 
 function IconButton({ isActive, icon: Icon }) {
   return (
@@ -261,7 +261,7 @@ The non-absolute icon (InactiveIcon) defines the layout size. The absolute icon
 | **Enter animation** | Yes | Yes |
 | **Exit animation** | Yes (via `AnimatePresence`) | Yes (cross-fade — icon never unmounts) |
 | **Spring physics** | Yes | No — use `cubic-bezier(0.2, 0, 0, 1)` as approximation |
-| **When to use** | Project already uses `motion/react` | No motion dependency, or keeping bundle small |
+| **When to use** | Project already uses `framer-motion` (or `motion/react`) | No motion dependency, or keeping bundle small |
 
 **Rule:** Check the project's `package.json` for `motion` or `framer-motion`. If present, use the Motion approach. If not, use the CSS cross-fade pattern — don't add a dependency just for icon transitions.
 
diff --git a/.agents/skills/memory-load-check/SKILL.md b/.agents/skills/memory-load-check/SKILL.md
index 9cef84d98dc..38c0f40864c 100644
--- a/.agents/skills/memory-load-check/SKILL.md
+++ b/.agents/skills/memory-load-check/SKILL.md
@@ -74,7 +74,7 @@ For those, require all three:
 
 Skip the pattern when the source already bounds the payload:
 - pure API/structured-data connectors (Jira, Linear, 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 (Evernote ~25 MB/note, ...) — a 100 MB cap can never fire there
+- native-document connectors whose platform caps each document — a 100 MB cap can never fire there
 
 Some connectors also budget the response body (google-docs `MAX_DOCS_RESPONSE_BYTES`, google-sheets `MAX_CONTENT_BYTES`, a remaining-bytes budget in notion); Confluence attachments use the full file pattern. Follow the connector's existing approach rather than adding a cap to every `response.json()`.
 
diff --git a/.agents/skills/ship/SKILL.md b/.agents/skills/ship/SKILL.md
index ce9afd45e4f..66b722b81a8 100644
--- a/.agents/skills/ship/SKILL.md
+++ b/.agents/skills/ship/SKILL.md
@@ -45,7 +45,7 @@ When the user runs `/ship`:
   - Then run root `bun run test` from the repo root. It chains `test:scripts` (the `scripts/*.test.ts` suite CI runs) before every workspace suite; workspace-scoped runs skip it, which is how a `scripts/check-*.test.ts` failure has reached CI. A failing test aborts ship.
 5. **Run migration safety** — only if the diff touches `packages/db/migrations/**` or `packages/db/schema.ts`:
   - Run `/db-migrate` to review the migration for zero-downtime safety (expand/contract phasing, backward-compatibility with the deployed app version).
-  - `cd packages/db && bunx drizzle-kit generate` must leave `git status --porcelain packages/db/migrations` empty (CI's schema/migration sync step).
+  - `cd packages/db && bunx drizzle-kit generate && git status --porcelain ./migrations` must print nothing (CI's schema/migration sync step).
   - `bun run check:migrations origin/staging` must pass (staging is the PR base). Do not silence a flagged statement with a `-- migration-safe:` annotation unless `/db-migrate` confirmed the old code no longer depends on it; otherwise split the destructive change into a later deploy.
 6. **Run pre-ship checks** from the repo root before staging. This has two phases: first **regenerate** every committed artifact so generated files never drift into a CI failure (this is what catches things like `agent-stream-docs` going stale after a `models.ts` edit), then run the **full audit suite** CI's `Lint and Test` job enforces. Both phases parallelize — but only across commands that write **disjoint** outputs — and a bare `wait` swallows child exit codes, so both phases below explicitly collect each job's status and abort ship if any failed.
 
diff --git a/.agents/skills/v2-api-conventions/SKILL.md b/.agents/skills/v2-api-conventions/SKILL.md
index 82756047c04..f947af3d68a 100644
--- a/.agents/skills/v2-api-conventions/SKILL.md
+++ b/.agents/skills/v2-api-conventions/SKILL.md
@@ -54,7 +54,7 @@ Two of these carry real design weight:
 
 **404 is deliberately overloaded.** A workspace the caller cannot reach answers `404 "Workspace not found"`, never 403 — a 403 would confirm the resource exists. `createV2ResourceConcealmentPolicy` does this by mapping a cross-tenant authorization failure to `v2Error('NOT_FOUND', ...)`. The unknown-path catch-all at `app/api/v2/[[...segments]]/route.ts` answers with the same body on purpose.
 
-**500 is never caller-reachable.** Any input a caller can send must be rejected at the contract boundary with a 400. If you can construct a query string or body that produces a 500, that is a bug in the contract, not something to wrap in a `try`/`catch`. `v2ErrorForOrchestration` also replaces the message on an unclassified failure with a generic one, so internal detail never leaks. Treat any well-formed request that produces a 500 as the highest-severity defect on this surface: non-integer numerics, `HEAD` on a `GET` route, and untyped placeholders into SQL functions are the known shapes.
+**500 is never caller-reachable.** Any input a caller can send must be rejected at the contract boundary with a 400. If you can construct a query string or body that produces a 500, that is a bug in the contract, not something to wrap in a `try`/`catch`. `v2ErrorForOrchestration` also replaces the message on an unclassified failure with a generic one, so internal detail never leaks. Treat any well-formed request that produces a 500 as the highest-severity defect on this surface: non-integer numerics, a method guard rejecting the `HEAD`-on-`GET` pairing, and untyped placeholders into SQL functions are the known shapes.
 
 **Validating a value is only half of it; the value also has to reach SQL with a type.** A bound parameter arrives as `unknown` and takes its type from context. Against a typed column (`sort_order > $1`) that inference always succeeds, which is why the gap stays invisible almost everywhere — but as an argument to an overloaded function it can resolve to nothing at all. So: **if a bound value is an argument to a SQL function rather than one side of a comparison, write its type down** (`lib/api/list-query.ts`, `timestampKey`, casts from the column).
 
diff --git a/.agents/skills/validate-permission-group-item/SKILL.md b/.agents/skills/validate-permission-group-item/SKILL.md
index 0dbf2c7913f..e2362b7c6e8 100644
--- a/.agents/skills/validate-permission-group-item/SKILL.md
+++ b/.agents/skills/validate-permission-group-item/SKILL.md
@@ -124,7 +124,7 @@ check:capability-subject — <N> v1 files, <M> capability subjects resolved thro
 | Audit | What it catches |
 |---|---|
 | `check:permission-group-enforcement` | Every operation declares a capability and every capability is enforced. All-or-nothing — no migration mode exits 0 with work outstanding, so do not go looking for a `pending enforcement:` list |
-| `check:application-graph` | The funnel roots (`lib/core/application/index.ts`, `capabilities.ts`, `capability-assertions.ts`, `config-scope.server.ts`) and `with-route-handler.ts` reach no heavy module tree at *runtime* (`import type` is erased and allowed). A gate that imports a resolver into a guarded root is a finding even if the gate is correct; a broken edge shows up only as unrelated tests failing on partial mocks |
+| `check:application-graph` | The funnel roots (`lib/core/application/index.ts`, `capabilities.ts`, `capability-assertions.ts`, `config-scope.server.ts`) and `with-route-handler.ts` reach no heavy module tree at *runtime* (`import type` is erased and allowed). A gate that imports a resolver into a guarded root is a finding even if the gate is correct; such an edge can also make unrelated tests fail on partial mocks |
 | `check:capability-subject` | Every v1 capability sink takes its subject from `capabilityGovernedUserId`, no v1 file outside the middleware imports the permission-group modules, and at least one governed sink was found at all |
 
 Two ways the enforcement audit passes without proving what you want:
diff --git a/.agents/skills/validate-trigger/SKILL.md b/.agents/skills/validate-trigger/SKILL.md
index 50d83edec1a..c41f24fc093 100644
--- a/.agents/skills/validate-trigger/SKILL.md
+++ b/.agents/skills/validate-trigger/SKILL.md
@@ -76,7 +76,7 @@ If a payload schema is unknown, validation must explicitly recommend:
 ### Trigger Files
 - [ ] Exactly one primary trigger has `includeDropdown: true`
 - [ ] All secondary triggers do NOT have `includeDropdown`
-- [ ] Webhook triggers use `buildTriggerSubBlocks`; polling triggers (`polling: true`) declare subBlocks manually
+- [ ] Webhook triggers use `buildTriggerSubBlocks` (directly or through a service wrapper) unless they deliberately keep a custom layout, as `triggers/airtable/webhook.ts` does; polling triggers (`polling: true`) declare subBlocks manually
 - [ ] Every trigger's `id` matches the convention `{service}_{event_name}`
 - [ ] Every trigger's `provider` matches the service name used in the handler registry
 - [ ] `index.ts` barrel exports all triggers
diff --git a/.agents/skills/you-might-not-need-url-state/SKILL.md b/.agents/skills/you-might-not-need-url-state/SKILL.md
index e23c91fcfdf..3ceee91a97d 100644
--- a/.agents/skills/you-might-not-need-url-state/SKILL.md
+++ b/.agents/skills/you-might-not-need-url-state/SKILL.md
@@ -35,7 +35,7 @@ Read these before analyzing:
 5. **Objects in the URL**: serializing a `TableDefinition`/`SkillDefinition`/etc. Store the id and derive the object from the loaded list (`items.find(i => i.id === id)`).
 6. **High-frequency / large state in the URL**: cursor, pan/zoom, un-debounced keystrokes, big JSON blobs. Debounce text search via `useDebouncedSearchSetter` (never a local `useState` mirror + reconcile effect, and never inline `limitUrlUpdates` wiring); keep canvas/presence/resize state in Zustand.
 7. **Shareable view-state trapped in `useState`**: a tab/filter/sort/pagination/selected-entity that should be a link but lives in local state. Migrate it to the URL.
-8. **Missing Suspense boundary**: a component newly calling `useQueryState`/`useQueryStates` whose page entry has no `<Suspense>` wrapper (Next.js requires it for `useSearchParams`). Add one whose fallback is the route's `loading.tsx` default export (never `fallback={null}` on a page entry; see `sim-url-state.md` "Suspense boundary").
+8. **Missing Suspense boundary**: a component newly calling `useQueryState`/`useQueryStates` whose page entry has no `<Suspense>` wrapper (Next.js requires it for `useSearchParams`). Add one whose fallback is the route's `loading.tsx` default export, or a real in-page fallback for a continuity-focused peer switch that deliberately has no `loading.tsx` (never `fallback={null}` on a page entry; see `sim-url-state.md` "Suspense boundary").
 9. **`import { z }` for param validation in client code**: use nuqs parsers instead.
 10. **Re-implemented shared wiring**: a hand-rolled `SORT_DIRECTIONS`/default-sort constants/`activeSort` derivation instead of `createSortParams` + `useUrlSort`, or an inline debounced-search setter instead of `useDebouncedSearchSetter`/`useSettingsSearch`.
 
diff --git a/.claude/rules/sim-architecture.md b/.claude/rules/sim-architecture.md
index a765e891765..ac3fdd4a229 100644
--- a/.claude/rules/sim-architecture.md
+++ b/.claude/rules/sim-architecture.md
@@ -10,7 +10,7 @@ Repository layout, package boundaries, the application operation boundary, namin
 
 ## The `'use client'` server boundary
 
-Server-evaluated code (RSC pages/layouts, `prefetch.ts`, route handlers, block definitions, triggers) can render an export of a `'use client'` module but never call it; the call throws at runtime and `next build` does not catch it. Keep anything a server module calls (key factories, fetchers, mappers, constants) in a non-`'use client'` module. Detail and the escape hatch: `.claude/rules/sim-queries.md`. Enforced by `bun run check:client-boundary`.
+Server-evaluated code (RSC pages/layouts, `prefetch.ts`, route handlers, block definitions, triggers) can render an export of a `'use client'` module but never call it; the call throws at runtime and `next build` does not catch it. Keep anything a server module calls (key factories, fetchers, mappers, constants) in a non-`'use client'` module. Detail and the escape hatch: `.claude/rules/sim-queries.md`. `bun run check:client-boundary` enforces it for `prefetch*.ts`, API route handlers, triggers, and blocks; nothing checks pages and layouts.
 
 ## The app/worker runtime boundary
 
diff --git a/.claude/rules/sim-integrations.md b/.claude/rules/sim-integrations.md
index 90d6ebd6c33..558978c96cd 100644
--- a/.claude/rules/sim-integrations.md
+++ b/.claude/rules/sim-integrations.md
@@ -17,8 +17,8 @@ The full authoring instructions — tool/block/icon/trigger scaffolding, SubBloc
 - Tool IDs and the two registration/coercion rules are in the root `CLAUDE.md` → Integrations. `blocks/registry.ts` holds only the accessor functions; triggers register in `triggers/registry.ts`.
 - Give every subblock a unique `id`: duplicates collide silently (the last definition wins). `blocks.test.ts` fails a duplicate within one condition unless the copies are a basic/advanced mode-swap pair, one basic plus trigger-mode copies, or all carry `canonicalParamId`. The only sanctioned cross-condition reuse is the hosted-key `apiKey` pair (`/add-hosted-key`), where both fields deliberately share one value.
 - Keep block outputs aligned with what the referenced tools actually return, and block `tools.access` aligned with the registered tool IDs.
-- `canonicalParamId` must NOT match any subblock's `id`, must be unique **block-wide** (groups are keyed by canonical id across every subblock and hold exactly one `basicId`, so two operations that each need a pair need two different canonical ids), and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs — the serializer deletes the subblock IDs and republishes the active member's value under the canonical ID.
+- `canonicalParamId` must NOT match the `id` of a subblock that has no `canonicalParamId` (a group member may share it, as the `add-block` skill's `channel` example does), must be unique **block-wide** (groups are keyed by canonical id across every subblock and hold exactly one `basicId`, so two operations that each need a pair need two different canonical ids), and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs — the serializer deletes the subblock IDs and republishes the active member's value under the canonical ID.
 - A canonical pair carries ONE concept. For files that is upload (basic) + file reference (advanced), normalized with `normalizeFileInput`, as in Gmail attachments (`blocks/blocks/gmail.ts`). Never overload the advanced side with alternate identifiers (URL, provider asset ID) — give those their own subblocks, mark mutually exclusive sources `required: false`, and enforce "exactly one" at execution.
 - A sub-block's option list is EITHER `selectorKey` (a registered selector — the only way to load a remote list, and the only one that works off the canvas) OR `options` (a static array, or a pure function of the block's own values). Never fetch from a block definition, and never read the workflow stores there. A credential sub-block needs `canonicalParamId: 'oauthCredential'` for its dependants' selectors to resolve. A secret must never appear in a selector's `getQueryKey`. `bun run check:fork-dependent-coverage` fails a `dependsOn` under a credential/KB/table anchor that the fork sync modal cannot offer.
-- Blocks must also set the catalog/UI metadata fields `integrationType`, `authMode`, `docsLink`, and export a `{Service}BlockMeta` (with `tags`) — see the `/add-block` skill's BlockMeta section. `{Service}BlockMeta.skills` must be grounded in operations the block exposes via `tools.access` and sourced from real, popular use cases found online — never invented.
+- Integration blocks (`category: 'tools'`) must set `integrationType` (`integration-catalog:check` fails without it) and export a `{Service}BlockMeta` (with `tags`); set `authMode` and `docsLink` too, which otherwise fall back to a credential-subblock guess and the generated docs page — see the `/add-block` skill's BlockMeta section. `{Service}BlockMeta.skills` must be grounded in operations the block exposes via `tools.access` and sourced from real, popular use cases found online — never invented.
 - Every block declares canvas sentences: `apps/sim/blocks/AGENTS.md` → "Canvas sentences".
diff --git a/.claude/rules/sim-testing.md b/.claude/rules/sim-testing.md
index 996b5106ae6..dbbb381daac 100644
--- a/.claude/rules/sim-testing.md
+++ b/.claude/rules/sim-testing.md
@@ -36,7 +36,7 @@ contracts, and demonstrated regressions.
 | `*.integration.ts` | real PostgreSQL (`TEST_DATABASE_URL`), optionally Redis (`TEST_REDIS_URL`) | `vitest run --mode integration` | `PostgreSQL integration` job, by glob |
 | `*.live.test.ts` | provider APIs, hosted sandboxes, local runtimes, or sibling checkouts | `vitest run --mode live <file>` (apps/sim) | never |
 | `apps/desktop/e2e/*.spec.ts` | the packaged Electron app | Playwright | desktop E2E workflow |
-| `apps/sim/scripts/test-*-e2e.ts` | a running app over HTTP | `bun scripts/test-<suite>-e2e.ts` from apps/sim (`bun run test:scim:e2e` for SCIM) | End-to-end over real HTTP job |
+| `apps/sim/scripts/test-*-e2e.ts` | a running app over HTTP | its `package.json` script when one exists (`bun run test:scim:e2e`; `test:workflow-version-compare:e2e` adds `--no-env-file`), else `bun scripts/test-<suite>-e2e.ts` from apps/sim | End-to-end over real HTTP job |
 
 - A unit test lives next to its source: `feature.ts` → `feature.test.ts`. No network, no database,
   no real timers.
diff --git a/.cursor/rules/sim-architecture.mdc b/.cursor/rules/sim-architecture.mdc
index c5a0e6f118d..b31a64e55f1 100644
--- a/.cursor/rules/sim-architecture.mdc
+++ b/.cursor/rules/sim-architecture.mdc
@@ -11,7 +11,7 @@ Repository layout, package boundaries, the application operation boundary, namin
 
 ## The `'use client'` server boundary
 
-Server-evaluated code (RSC pages/layouts, `prefetch.ts`, route handlers, block definitions, triggers) can render an export of a `'use client'` module but never call it; the call throws at runtime and `next build` does not catch it. Keep anything a server module calls (key factories, fetchers, mappers, constants) in a non-`'use client'` module. Detail and the escape hatch: `.claude/rules/sim-queries.md`. Enforced by `bun run check:client-boundary`.
+Server-evaluated code (RSC pages/layouts, `prefetch.ts`, route handlers, block definitions, triggers) can render an export of a `'use client'` module but never call it; the call throws at runtime and `next build` does not catch it. Keep anything a server module calls (key factories, fetchers, mappers, constants) in a non-`'use client'` module. Detail and the escape hatch: `.claude/rules/sim-queries.md`. `bun run check:client-boundary` enforces it for `prefetch*.ts`, API route handlers, triggers, and blocks; nothing checks pages and layouts.
 
 ## The app/worker runtime boundary
 
diff --git a/.cursor/rules/sim-integrations.mdc b/.cursor/rules/sim-integrations.mdc
index c6700f46048..cfe5ed66d92 100644
--- a/.cursor/rules/sim-integrations.mdc
+++ b/.cursor/rules/sim-integrations.mdc
@@ -16,8 +16,8 @@ The full authoring instructions — tool/block/icon/trigger scaffolding, SubBloc
 - Tool IDs and the two registration/coercion rules are in the root `CLAUDE.md` → Integrations. `blocks/registry.ts` holds only the accessor functions; triggers register in `triggers/registry.ts`.
 - Give every subblock a unique `id`: duplicates collide silently (the last definition wins). `blocks.test.ts` fails a duplicate within one condition unless the copies are a basic/advanced mode-swap pair, one basic plus trigger-mode copies, or all carry `canonicalParamId`. The only sanctioned cross-condition reuse is the hosted-key `apiKey` pair (`/add-hosted-key`), where both fields deliberately share one value.
 - Keep block outputs aligned with what the referenced tools actually return, and block `tools.access` aligned with the registered tool IDs.
-- `canonicalParamId` must NOT match any subblock's `id`, must be unique **block-wide** (groups are keyed by canonical id across every subblock and hold exactly one `basicId`, so two operations that each need a pair need two different canonical ids), and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs — the serializer deletes the subblock IDs and republishes the active member's value under the canonical ID.
+- `canonicalParamId` must NOT match the `id` of a subblock that has no `canonicalParamId` (a group member may share it, as the `add-block` skill's `channel` example does), must be unique **block-wide** (groups are keyed by canonical id across every subblock and hold exactly one `basicId`, so two operations that each need a pair need two different canonical ids), and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs — the serializer deletes the subblock IDs and republishes the active member's value under the canonical ID.
 - A canonical pair carries ONE concept. For files that is upload (basic) + file reference (advanced), normalized with `normalizeFileInput`, as in Gmail attachments (`blocks/blocks/gmail.ts`). Never overload the advanced side with alternate identifiers (URL, provider asset ID) — give those their own subblocks, mark mutually exclusive sources `required: false`, and enforce "exactly one" at execution.
 - A sub-block's option list is EITHER `selectorKey` (a registered selector — the only way to load a remote list, and the only one that works off the canvas) OR `options` (a static array, or a pure function of the block's own values). Never fetch from a block definition, and never read the workflow stores there. A credential sub-block needs `canonicalParamId: 'oauthCredential'` for its dependants' selectors to resolve. A secret must never appear in a selector's `getQueryKey`. `bun run check:fork-dependent-coverage` fails a `dependsOn` under a credential/KB/table anchor that the fork sync modal cannot offer.
-- Blocks must also set the catalog/UI metadata fields `integrationType`, `authMode`, `docsLink`, and export a `{Service}BlockMeta` (with `tags`) — see the `/add-block` skill's BlockMeta section. `{Service}BlockMeta.skills` must be grounded in operations the block exposes via `tools.access` and sourced from real, popular use cases found online — never invented.
+- Integration blocks (`category: 'tools'`) must set `integrationType` (`integration-catalog:check` fails without it) and export a `{Service}BlockMeta` (with `tags`); set `authMode` and `docsLink` too, which otherwise fall back to a credential-subblock guess and the generated docs page — see the `/add-block` skill's BlockMeta section. `{Service}BlockMeta.skills` must be grounded in operations the block exposes via `tools.access` and sourced from real, popular use cases found online — never invented.
 - Every block declares canvas sentences: `apps/sim/blocks/AGENTS.md` → "Canvas sentences".
diff --git a/.cursor/rules/sim-testing.mdc b/.cursor/rules/sim-testing.mdc
index 5411f0bac5d..e4cc023d9f4 100644
--- a/.cursor/rules/sim-testing.mdc
+++ b/.cursor/rules/sim-testing.mdc
@@ -34,7 +34,7 @@ contracts, and demonstrated regressions.
 | `*.integration.ts` | real PostgreSQL (`TEST_DATABASE_URL`), optionally Redis (`TEST_REDIS_URL`) | `vitest run --mode integration` | `PostgreSQL integration` job, by glob |
 | `*.live.test.ts` | provider APIs, hosted sandboxes, local runtimes, or sibling checkouts | `vitest run --mode live <file>` (apps/sim) | never |
 | `apps/desktop/e2e/*.spec.ts` | the packaged Electron app | Playwright | desktop E2E workflow |
-| `apps/sim/scripts/test-*-e2e.ts` | a running app over HTTP | `bun scripts/test-<suite>-e2e.ts` from apps/sim (`bun run test:scim:e2e` for SCIM) | End-to-end over real HTTP job |
+| `apps/sim/scripts/test-*-e2e.ts` | a running app over HTTP | its `package.json` script when one exists (`bun run test:scim:e2e`; `test:workflow-version-compare:e2e` adds `--no-env-file`), else `bun scripts/test-<suite>-e2e.ts` from apps/sim | End-to-end over real HTTP job |
 
 - A unit test lives next to its source: `feature.ts` → `feature.test.ts`. No network, no database,
   no real timers.
diff --git a/CLAUDE.md b/CLAUDE.md
index 5c0b615110a..87172b4fd6a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -145,6 +145,7 @@ bun run type-check      # every workspace
 bun run check:audits    # every check:* audit plus the generated-artifact checks
 bun run test            # script tests, then every workspace's Vitest suite
 bun run docs-manifest:check
+git fetch origin staging  # the block-registry check diffs against it
 bun run apps/sim/scripts/check-block-registry.ts origin/staging
 ```
 

From 351622b4211dc695fbe62bcd68779568de0337cd Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Fri, 2 Oct 2026 01:09:14 -0700
Subject: [PATCH 15/18] fix(audits): resolve import specifiers to module files
 only; tighten review-flagged guidance

---
 .agents/skills/add-connector/SKILL.md         |  2 +-
 .../skills/add-permission-group-item/SKILL.md |  2 +-
 .agents/skills/babysit/SKILL.md               |  6 ++--
 .claude/rules/sim-architecture.md             |  2 +-
 .cursor/rules/sim-architecture.mdc            |  2 +-
 scripts/check-guidance-refs.ts                | 32 ++++++++++++++-----
 6 files changed, 31 insertions(+), 15 deletions(-)

diff --git a/.agents/skills/add-connector/SKILL.md b/.agents/skills/add-connector/SKILL.md
index cfc24489aee..801ef6ee4fe 100644
--- a/.agents/skills/add-connector/SKILL.md
+++ b/.agents/skills/add-connector/SKILL.md
@@ -541,7 +541,7 @@ If `ExternalDocument.sourceUrl` is set, the sync engine stores it on the documen
 
 If `listDocuments` can ever return **less than the full source set** on a non-incremental sync — a `maxItems`/`maxDocuments`-style cap, or a transient per-item error that drops a still-existing document from the listing — it MUST set `syncContext.listingCapped = true` when that happens.
 
-The engine reconciles deletions only when the listing is marked safe (`checkpoint.unsafe` in `lib/knowledge/connectors/listing-checkpoint.ts`): `syncContext.listingCapped`, `ExternalDocumentList.reconciliationSafe: false` (required for offset/unstable pagination), or a non-null `listingFailures` marks it unsafe. Anything absent from a safe listing is tombstoned on that sync and hard-deleted when the next sync still does not see it — so a truncated listing without this flag eventually removes every real document beyond the cap.
+The engine reconciles deletions only when the listing is marked safe (`checkpoint.unsafe` in `lib/knowledge/connectors/listing-checkpoint.ts`): `syncContext.listingCapped`, `syncContext.listingTruncated`, `syncContext.reconciliationUnsafe`, `ExternalDocumentList.reconciliationSafe: false` (required for offset/unstable pagination), or a non-null `listingFailures` marks it unsafe. Anything absent from a safe listing is tombstoned on that sync and hard-deleted when the next sync still does not see it — so a truncated listing without this flag eventually removes every real document beyond the cap.
 
 ```typescript
 if (hitLimit && syncContext) {
diff --git a/.agents/skills/add-permission-group-item/SKILL.md b/.agents/skills/add-permission-group-item/SKILL.md
index e5a90a007b9..68ae7fba2a3 100644
--- a/.agents/skills/add-permission-group-item/SKILL.md
+++ b/.agents/skills/add-permission-group-item/SKILL.md
@@ -41,7 +41,7 @@ Allowlist when the safe posture is "only what the admin named" and the member se
 | `'executor'` | Read per block/tool/model at run time by `assertPermissionsAllowed` in `ee/access-control/utils/permission-check.ts`. Governs what a *run* may do, which no operation gate can express (one API call executes fifty blocks). Only `allowedIntegrations`, `allowedModelProviders`, `deniedModels`, `deniedTools` live here. The matching primitives these four keys are compared with live in `lib/permission-groups/` — `block-access.ts` (exemptions, superseded-version resolution), `operation-access.ts` (`createToolAccessGate`), `model-access.ts` (`createModelAccessGate`), `integration-allowlist.ts` — shared so the run-time gate and the editor/Copilot projections cannot drift. `allowedIntegrations` alone is also asserted outside a run, by `assertSelectorIntegrationAllowed` (`lib/selectors/server/integration-access.ts`) ahead of the provider call in `selectors.execute`, against the selector's own `resourceServiceId` / `integrationBlockTypes` rather than the credentials it accepts — reaching a provider API is a use of the integration, so a key here can still need a non-run enforcement site |
 | `'ui-only'` | Hides a surface without withholding it. **Almost never right** — nothing ships as `ui-only`. Justify in the `enforcement` comment why a determined caller reaching the data is acceptable, and expect review to question it |
 
-**Is it per-operation at all?** `personal_api_key.use` and `oauth_apps.use` are principal-wide (`PRINCIPAL_WIDE_CAPABILITIES` in `lib/core/application/operation.ts`): they withhold a principal kind across every operation, checked in the funnel's `personal_api_key` / `oauth_access_token` branches (`workspace-authorization.ts`) and in `app/api/v1/middleware.ts`. Declaring one on an operation throws at definition time, so its absence from every `capability:` field is correct.
+**Is it per-operation at all?** `personal_api_key.use` and `oauth_apps.use` are principal-wide (`PRINCIPAL_WIDE_CAPABILITIES` in `lib/core/application/operation.ts`): they withhold a principal kind across every operation, checked in the funnel's `personal_api_key` / `oauth_access_token` branches (`workspace-authorization.ts`); `app/api/v1/middleware.ts` repeats only the `personal_api_key.use` check, since v1 accepts API keys, not OAuth tokens. Declaring one on an operation throws at definition time, so its absence from every `capability:` field is correct.
 
 **Is the decision knowable from the config alone?** A rule needing a request value (an auth mode, a connector id) is *parameterized* and cannot be declared on an operation — see Step 3.
 
diff --git a/.agents/skills/babysit/SKILL.md b/.agents/skills/babysit/SKILL.md
index 7a4dbca020f..a8f44bdf75d 100644
--- a/.agents/skills/babysit/SKILL.md
+++ b/.agents/skills/babysit/SKILL.md
@@ -88,9 +88,9 @@ conditions freshly after every push.
    across all pages has `isResolved: true`, and every check has finished and passed, stop —
    report the outcome (see "Reporting" below) and skip the rest of this list.
 
-2. **If the PR has a merge conflict**, merge `origin/staging`, resolve the conflicts, then
-   follow steps 6–8 on the merge result: the full sync check plus `/ship` steps 4–6, push, and
-   re-trigger review.
+2. **If the PR has a merge conflict**, resolve it with step 6 (its rebase-based sync flow and
+   the `/ship` gates; a merge commit would be discarded by that rebase), then steps 7–8: push
+   with `--force-with-lease` and re-trigger review.
 
 3. **If no review has run yet** (fresh PR, no bot comments): both run automatically on PR open —
    confirm via `gh pr checks <n>` (look for `Greptile Review` and `cubic · AI code reviewer`) and
diff --git a/.claude/rules/sim-architecture.md b/.claude/rules/sim-architecture.md
index ac3fdd4a229..fd1bda06f19 100644
--- a/.claude/rules/sim-architecture.md
+++ b/.claude/rules/sim-architecture.md
@@ -10,7 +10,7 @@ Repository layout, package boundaries, the application operation boundary, namin
 
 ## The `'use client'` server boundary
 
-Server-evaluated code (RSC pages/layouts, `prefetch.ts`, route handlers, block definitions, triggers) can render an export of a `'use client'` module but never call it; the call throws at runtime and `next build` does not catch it. Keep anything a server module calls (key factories, fetchers, mappers, constants) in a non-`'use client'` module. Detail and the escape hatch: `.claude/rules/sim-queries.md`. `bun run check:client-boundary` enforces it for `prefetch*.ts`, API route handlers, triggers, and blocks; nothing checks pages and layouts.
+Server-evaluated code (RSC pages/layouts, `prefetch.ts`, route handlers, block definitions, triggers) can render an export of a `'use client'` module but never call it; the call throws at runtime and `next build` does not catch it. Keep anything a server module calls (key factories, fetchers, mappers, constants) in a non-`'use client'` module. Detail and the escape hatch: `.claude/rules/sim-queries.md`. `bun run check:client-boundary` checks the direct imports of `prefetch*.ts`, API route handlers, triggers, and blocks; it does not follow transitive imports, and nothing checks pages and layouts.
 
 ## The app/worker runtime boundary
 
diff --git a/.cursor/rules/sim-architecture.mdc b/.cursor/rules/sim-architecture.mdc
index b31a64e55f1..740e9601df1 100644
--- a/.cursor/rules/sim-architecture.mdc
+++ b/.cursor/rules/sim-architecture.mdc
@@ -11,7 +11,7 @@ Repository layout, package boundaries, the application operation boundary, namin
 
 ## The `'use client'` server boundary
 
-Server-evaluated code (RSC pages/layouts, `prefetch.ts`, route handlers, block definitions, triggers) can render an export of a `'use client'` module but never call it; the call throws at runtime and `next build` does not catch it. Keep anything a server module calls (key factories, fetchers, mappers, constants) in a non-`'use client'` module. Detail and the escape hatch: `.claude/rules/sim-queries.md`. `bun run check:client-boundary` enforces it for `prefetch*.ts`, API route handlers, triggers, and blocks; nothing checks pages and layouts.
+Server-evaluated code (RSC pages/layouts, `prefetch.ts`, route handlers, block definitions, triggers) can render an export of a `'use client'` module but never call it; the call throws at runtime and `next build` does not catch it. Keep anything a server module calls (key factories, fetchers, mappers, constants) in a non-`'use client'` module. Detail and the escape hatch: `.claude/rules/sim-queries.md`. `bun run check:client-boundary` checks the direct imports of `prefetch*.ts`, API route handlers, triggers, and blocks; it does not follow transitive imports, and nothing checks pages and layouts.
 
 ## The app/worker runtime boundary
 
diff --git a/scripts/check-guidance-refs.ts b/scripts/check-guidance-refs.ts
index 6b8ae8097ba..d4b02be150e 100644
--- a/scripts/check-guidance-refs.ts
+++ b/scripts/check-guidance-refs.ts
@@ -20,7 +20,7 @@
  * Run: `bun run check:guidance-refs`
  */
 import { execFileSync } from 'node:child_process'
-import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
 import path from 'node:path'
 import { parseRule } from './sync-skills'
 
@@ -124,6 +124,26 @@ function resolvesFrom(base: string, ref: string): boolean {
   return SOURCE_EXTENSIONS.some((ext) => existsSync(path.join(base, `${ref}${ext}`)))
 }
 
+const MODULE_CANDIDATES = [
+  '',
+  '.ts',
+  '.tsx',
+  '.js',
+  '.mjs',
+  '.json',
+  '/index.ts',
+  '/index.tsx',
+  '/index.js',
+]
+
+/** An import specifier resolves only to a module file, never to a bare directory. */
+function moduleResolves(base: string, ref: string): boolean {
+  return MODULE_CANDIDATES.some((suffix) => {
+    const candidate = path.join(base, `${ref}${suffix}`)
+    return existsSync(candidate) && statSync(candidate).isFile()
+  })
+}
+
 const PATH_PREFIXES = ['apps/', 'packages/', 'scripts/', '.claude/', '.agents/', '.github/']
 
 /**
@@ -151,16 +171,12 @@ function importResolves(spec: string, packages: Map<string, WorkspacePackage>):
   const clean = spec.replace(/\/$/, '')
   if (clean === '@' || clean === '@sim') return true
   if (clean.startsWith('@/')) {
-    const rel = clean.slice(2)
-    return (
-      resolvesFrom(APP_ROOT, rel) ||
-      ['/index.ts', '/index.tsx'].some((index) => existsSync(path.join(APP_ROOT, `${rel}${index}`)))
-    )
+    return moduleResolves(APP_ROOT, clean.slice(2))
   }
   const [scope, name, ...rest] = clean.split('/')
   const pkg = packages.get(`${scope}/${name}`)
   if (!pkg) return false
-  if (!pkg.exports) return rest.length === 0 || resolvesFrom(pkg.dir, rest.join('/'))
+  if (!pkg.exports) return rest.length === 0 || moduleResolves(pkg.dir, rest.join('/'))
   const subpath = rest.length === 0 ? '.' : `./${rest.join('/')}`
   return Object.entries(pkg.exports).some(([key, value]) => {
     const [head, tail] = key.split('*')
@@ -169,7 +185,7 @@ function importResolves(spec: string, packages: Map<string, WorkspacePackage>):
     // A wildcard export only proves the pattern; the file it maps to must also exist.
     const target = exportTarget(value)
     const matched = subpath.slice(head.length, subpath.length - tail.length)
-    return target !== null && resolvesFrom(pkg.dir, target.replace('*', matched))
+    return target !== null && moduleResolves(pkg.dir, target.replace('*', matched))
   })
 }
 

From 5c0d278a1e521f57b73e00de0b0db33fe2f4c409 Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Fri, 2 Oct 2026 01:17:47 -0700
Subject: [PATCH 16/18] docs(agents): keep the repo-wide ES2023 ban in
 sim-components after rebase

---
 .claude/rules/sim-components.md  | 2 +-
 .cursor/rules/sim-components.mdc | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude/rules/sim-components.md b/.claude/rules/sim-components.md
index 1c59df5be25..194359e448b 100644
--- a/.claude/rules/sim-components.md
+++ b/.claude/rules/sim-components.md
@@ -40,7 +40,7 @@ When rendering or sorting a list of rows against a lookup collection (members, f
 react-doctor diagnostics are hypotheses, not verdicts — confirm against the code before acting, and preserve behavior. Known repo-specific false positives to NOT "fix":
 
 - `no-barrel-import` — barrel imports are the repo convention (see sim-imports.md, "Barrel Exports"). Keep them.
-- `js-tosorted-immutable` — won't-fix in `'use client'` code (see "List-render performance" above); apply it only in server-only modules.
+- `js-tosorted-immutable` — won't-fix anywhere; `check:utils` bans the ES2023 array methods repo-wide.
 - `rerender-state-only-in-handlers` / "state set but never rendered" — a false positive when the `useState` is consumed by a `useEffect`/`useLayoutEffect` dependency (the effect must re-run on change). Only convert to a ref when nothing reads the value reactively.
 - `no-render-in-render` — a helper *called inline* (`{renderRow()}`) is reconciled by position and does **not** remount, so extracting it to a component is usually pure churn and can regress behavior (prop-drilling many closures, focus/scroll loss on the inner `<input>`). Apply it only when the helper is genuinely a *component defined during render*, or when the move is mechanical (a stateless, ref-free helper whose closures become a small, explicit prop set).
 - `async-await-in-loop` on an upload/progress loop where sequential execution is intentional (per-item progress, server backpressure) — leave it.
diff --git a/.cursor/rules/sim-components.mdc b/.cursor/rules/sim-components.mdc
index 13dfcfbac78..15be6706173 100644
--- a/.cursor/rules/sim-components.mdc
+++ b/.cursor/rules/sim-components.mdc
@@ -41,7 +41,7 @@ When rendering or sorting a list of rows against a lookup collection (members, f
 react-doctor diagnostics are hypotheses, not verdicts — confirm against the code before acting, and preserve behavior. Known repo-specific false positives to NOT "fix":
 
 - `no-barrel-import` — barrel imports are the repo convention (see sim-imports.md, "Barrel Exports"). Keep them.
-- `js-tosorted-immutable` — won't-fix in `'use client'` code (see "List-render performance" above); apply it only in server-only modules.
+- `js-tosorted-immutable` — won't-fix anywhere; `check:utils` bans the ES2023 array methods repo-wide.
 - `rerender-state-only-in-handlers` / "state set but never rendered" — a false positive when the `useState` is consumed by a `useEffect`/`useLayoutEffect` dependency (the effect must re-run on change). Only convert to a ref when nothing reads the value reactively.
 - `no-render-in-render` — a helper *called inline* (`{renderRow()}`) is reconciled by position and does **not** remount, so extracting it to a component is usually pure churn and can regress behavior (prop-drilling many closures, focus/scroll loss on the inner `<input>`). Apply it only when the helper is genuinely a *component defined during render*, or when the move is mechanical (a stateless, ref-free helper whose closures become a small, explicit prop set).
 - `async-await-in-loop` on an upload/progress loop where sequential execution is intentional (per-item progress, server backpressure) — leave it.

From 30e80f9b83679815ecbf16852004cb2c38f7d1dd Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Fri, 2 Oct 2026 01:34:30 -0700
Subject: [PATCH 17/18] fix(audits): require exact export targets to exist and
 resolve markdown links strictly

---
 scripts/check-guidance-refs.ts | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/scripts/check-guidance-refs.ts b/scripts/check-guidance-refs.ts
index d4b02be150e..1b3c0fba984 100644
--- a/scripts/check-guidance-refs.ts
+++ b/scripts/check-guidance-refs.ts
@@ -178,14 +178,15 @@ function importResolves(spec: string, packages: Map<string, WorkspacePackage>):
   if (!pkg) return false
   if (!pkg.exports) return rest.length === 0 || moduleResolves(pkg.dir, rest.join('/'))
   const subpath = rest.length === 0 ? '.' : `./${rest.join('/')}`
+  // An export key only proves the specifier is declared; the file it maps to must also exist.
   return Object.entries(pkg.exports).some(([key, value]) => {
+    const target = exportTarget(value)
+    if (target === null) return false
     const [head, tail] = key.split('*')
-    if (tail === undefined) return key === subpath
+    if (tail === undefined) return key === subpath && moduleResolves(pkg.dir, target)
     if (!subpath.startsWith(head) || !subpath.endsWith(tail)) return false
-    // A wildcard export only proves the pattern; the file it maps to must also exist.
-    const target = exportTarget(value)
     const matched = subpath.slice(head.length, subpath.length - tail.length)
-    return target !== null && moduleResolves(pkg.dir, target.replace('*', matched))
+    return moduleResolves(pkg.dir, target.replace('*', matched))
   })
 }
 
@@ -309,8 +310,18 @@ function auditDocument(relFile: string, workspaces: Workspaces, files: string[])
     for (const match of text.matchAll(MD_LINK)) {
       const target = match[1]
       if (/^(mailto:|#)/.test(target)) continue
-      // A leading `/` in a link is the repo root.
-      checkPath(line, target.replace(/^\//, ''))
+      if (isPlaceholder(target) || /^[a-z]+:\/\//i.test(target)) continue
+      if (target.startsWith('@/') || target.startsWith('@sim/')) {
+        checkPath(line, target)
+        continue
+      }
+      // A link names its destination explicitly, so there is no prose fallback: it resolves from
+      // the repo root (leading `/`) or from the document's own folder.
+      const dest = target.replace(/[#?].*$/, '')
+      const base = dest.startsWith('/') ? ROOT : docDir
+      if (dest && !resolvesFrom(base, dest.replace(/^\//, '').replace(/\/$/, ''))) {
+        report(line, 'path', target)
+      }
     }
 
     const outsideSpans = text.replace(/`[^`\n]*`/g, (span) =>

From ffccca6a7a16ed762b2fc98fc5294a1f4694c052 Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Fri, 2 Oct 2026 01:46:59 -0700
Subject: [PATCH 18/18] fix(audits): check require() specifiers and keep path
 resolution inside the repo

---
 scripts/check-guidance-refs.ts | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/scripts/check-guidance-refs.ts b/scripts/check-guidance-refs.ts
index 1b3c0fba984..bfd9c1e6513 100644
--- a/scripts/check-guidance-refs.ts
+++ b/scripts/check-guidance-refs.ts
@@ -120,8 +120,12 @@ function isPlaceholder(ref: string): boolean {
   return /[<>{}*$]|\.\.\.|…|\bfoo\b|\bxxx?\b/i.test(ref)
 }
 
+/** A file or directory inside the repo; a path escaping the root never resolves. */
 function resolvesFrom(base: string, ref: string): boolean {
-  return SOURCE_EXTENSIONS.some((ext) => existsSync(path.join(base, `${ref}${ext}`)))
+  return SOURCE_EXTENSIONS.some((ext) => {
+    const candidate = path.resolve(base, `${ref}${ext}`)
+    return !path.relative(ROOT, candidate).startsWith('..') && existsSync(candidate)
+  })
 }
 
 const MODULE_CANDIDATES = [
@@ -285,7 +289,7 @@ function auditDocument(relFile: string, workspaces: Workspaces, files: string[])
     for (const match of text.matchAll(REPO_PATH)) checkPath(line, trimProse(match[1]))
     if (inFence) {
       // Example code: only imports are concrete enough to check.
-      if (/\b(?:from|import|mock|vi\.mock|doMock)\b/.test(text)) {
+      if (/\b(?:from|import|require|mock|vi\.mock|doMock)\b/.test(text)) {
         for (const match of text.matchAll(IMPORT_SPEC)) checkPath(line, match[2])
       }
       return