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.

Author: waleedlatif1

.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

.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`

.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)

.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/'`.

.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
 

.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
 

.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.
 

.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.
 

.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

.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.