simstudioai · waleedlatif1 · Aug 15, 2026 · Aug 15, 2026 · Aug 15, 2026 · Aug 15, 2026
diff --git a/.agents/skills/add-block/SKILL.md b/.agents/skills/add-block/SKILL.md
@@ -993,11 +993,15 @@ After adding or changing one, run:
 ```bash
 bun run scripts/generate-docs.ts
 bun run integration-catalog:check
+bun run docs:check
 ```
 
 The catalog check independently derives deployment metadata from the executable block registry and
-compares it with the committed `apps/sim/lib/integrations/integrations.json`. Review the generated
-diff and keep only intentional changes.
+compares it with the committed `apps/sim/lib/integrations/integrations.json`. `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.
 ## Checklist Before Finishing
 
 - [ ] `integrationType` is set to the correct `IntegrationType` enum value
@@ -1018,6 +1022,7 @@ diff and keep only intentional changes.
 - [ ] If any tool was added, changed or removed alongside the block: ran `bun run tool-metadata:generate` and committed the artifacts
 - [ ] Ran `bun run scripts/generate-docs.ts`, reviewed the generated diff, and committed the integration catalog changes
 - [ ] `bun run integration-catalog:check` passes
+- [ ] `bun run docs:check` passes (CI gate — fails on any stale generated docs page)
 - [ ] If icon missing: asked user to provide SVG
 - [ ] If triggers exist: `triggers` config set, trigger subBlocks spread
 - [ ] Optional/rarely-used fields set to `mode: 'advanced'`

diff --git a/.agents/skills/add-integration/SKILL.md b/.agents/skills/add-integration/SKILL.md
@@ -561,6 +561,7 @@ Run the documentation generator:
 ```bash
 bun run scripts/generate-docs.ts
 bun run integration-catalog:check
+bun run docs:check
 ```
 
 This creates `apps/docs/content/docs/en/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`).
@@ -651,6 +652,9 @@ If creating V2 versions (API-aligned outputs):
 - [ ] Verified docs file created
 - [ ] Reviewed and committed the generated `apps/sim/lib/integrations/integrations.json` change
 - [ ] `bun run integration-catalog:check` passes
+- [ ] `bun run docs:check` passes — CI fails on stale generated docs, so commit the full generator
+      output, including catch-up regeneration for pages another PR left stale (never revert it as
+      "unrelated drift")
 
 ### Final Validation (Required)
 - [ ] Read every tool file and cross-referenced inputs/outputs against the API docs

diff --git a/.agents/skills/add-tools/SKILL.md b/.agents/skills/add-tools/SKILL.md
@@ -475,6 +475,9 @@ All tool IDs MUST use `snake_case`: `{service}_{action}` (e.g., `x_create_tweet`
 - [ ] Index.ts exports all tools and re-exports types (`export * from './types'`)
 - [ ] Tools registered in `tools/registry.ts`
 - [ ] `bun run tool-metadata:generate` run and the regenerated artifacts committed
+- [ ] `bun run scripts/generate-docs.ts` run and the refreshed docs committed — the integration's
+      docs page is rendered from each tool's description, params, and outputs, and CI's
+      `bun run docs:check` fails on stale pages
 - [ ] Block wired: `tools.access`, dropdown options, subBlocks, `tools.config`, outputs, inputs
 - [ ] Model, durable-storage, and internal-execution boundaries use the shared provenance mechanisms
       only where a concrete Sim `{{...}}` resolution path requires them

diff --git a/.agents/skills/add-trigger/SKILL.md b/.agents/skills/add-trigger/SKILL.md
@@ -511,3 +511,6 @@ Add to `helm/sim/values.yaml` under the existing polling cron jobs:
 - [ ] `bun run type-check` passes
 - [ ] Manually verify output keys match trigger `outputs` keys
 - [ ] Trigger UI shows correctly in the block
+- [ ] Ran `bun run scripts/generate-docs.ts` and committed the refreshed pages — trigger sections
+      render into the owning integration's docs page, and CI's `bun run docs:check` fails on stale
+      pages
diff --git a/.agents/skills/migrate-application-operation/SKILL.md b/.agents/skills/migrate-application-operation/SKILL.md
@@ -78,6 +78,43 @@ Classify each as `migrate`, `defer`, or `non-goal`. Do not migrate adjacent oper
 
 Preserve behavior unless the task explicitly changes it. Stop and report a decision when surfaces currently disagree on security or compatibility behavior; do not silently choose one.
 
+## Freeze observable behavior before editing
+
+Treat the legacy route or tool as an ordered program, not merely a bag of business logic. Before moving code, write a compact baseline for every in-scope entry point and add focused characterization tests for behavior not already pinned down.
+
+Capture all of these when they apply:
+
+- Accepted inputs, including trimming, blank omission, duplicate query keys, aliases, defaults, and bounds.
+- Authentication and authorization order, minimum roles, resource membership, concealment, and exact error/status mapping.
+- Exact success bodies, optional fields, status codes, redirects, cookies, headers, and binary or stream behavior.
+- Mutation ordering, transaction boundaries, idempotency, no-ops, and observable state after each possible partial failure.
+- Audit, notification, analytics, and billing timing plus exact semantic dimensions and attribution.
+- Browser or protocol state ownership, concurrency isolation, expiry, callback ordering, and cleanup behavior.
+- Every value newly crossing into HTML, JavaScript, SQL, URLs, logs, provider payloads, or another encoding context.
+
+Compare the old statement order with the proposed application lifecycle explicitly:
+
+```text
+legacy parse/normalize
+  -> legacy authorization checks
+  -> branch-specific canonical lookup
+  -> mutation(s)
+  -> per-step side effects
+  -> response or redirect catch
+```
+
+Moving those steps under a wrapper may change behavior even when each individual call is reused. In particular:
+
+- `projectAudit` and `afterSuccess` run only after `execute` returns. They cannot describe earlier committed mutations when a later step throws. Make the compound mutation atomic or define explicit partial-result/failure projection semantics before migrating it.
+- Operation metadata is executable policy. Adding a resource role to a workspace-only legacy read is an authorization change, not an architectural cleanup.
+- A shared error policy does not automatically preserve route-local concealment, subclass ordering, browser redirects, or branch-specific messages.
+- A shared contract does not automatically preserve manual `URLSearchParams` normalization or exact legacy response unions.
+- A shared use case may own domain behavior while separate surface presenters still preserve different wire shapes.
+- Per-flow identity is insufficient when another part of the flow remains in browser-global state such as one cookie.
+- Passing a newly supported parameter through old rendering code creates a new security boundary even when the renderer itself is unchanged.
+
+Fail fast if the baseline cannot be established from code, tests, or an explicit product decision. Do not infer that behavior is unimportant because it was previously implicit.
+
 ## Keep the layers distinct
 
 Use these responsibilities:
@@ -270,6 +307,10 @@ Add focused tests for every migrated surface and principal kind allowed by the o
 - Public API: personal and workspace keys, rate and rollout behavior, concealment, exact external envelope, and rate headers.
 - Copilot or tools: trusted context, exact registered operation membership, rejected forged scope, aliases and resume paths, permission re-check, safe errors, and unchanged tool result shapes.
 - Side effects: audit derives from authoritative results; shared notifications follow audit; neither occurs for rejection or no-op.
+- Compatibility characterization: legacy normalization, exact response/redirect/cookie behavior, concealment, error subclass precedence, and branch-specific output.
+- Failure sequencing: inject a failure after each independently committing step and assert persisted state plus audit, analytics, and notification effects.
+- Concurrency: overlap stateful browser or provider flows and prove each callback consumes only its own state and return destination.
+- Rendering boundaries: exercise hostile values for every newly connected input that reaches HTML, inline JavaScript, URLs, logs, or provider requests.
 
 Run at minimum:
 

diff --git a/.agents/skills/validate-integration/SKILL.md b/.agents/skills/validate-integration/SKILL.md
@@ -388,15 +388,25 @@ Several files are generated from tool and block definitions. Editing a tool or b
 bun run tool-metadata:generate       # repo root — apps/sim/tools/generated/*
 bun run scripts/generate-docs.ts     # docs .mdx + lib/integrations/integrations.json + docs icons
 bun run integration-catalog:check    # registry ↔ committed deployment metadata drift
+bun run docs:check                   # committed docs ↔ what the generator renders today
 ```
 
 - **`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.
 - **`generate-docs`** — required whenever block metadata changes (`bgColor`, `name`, `description`, operations, outputs). Regenerates the integration `.mdx`, `integrations.json`, and the docs copy of `components/icons.tsx`.
 - **`integration-catalog:check`** — loads the executable block registry, derives visible integration
   deployment fields, and compares them with the committed catalog. It catches missing/unexpected
   entries and stale auth/service IDs without loading the executable registry in client code.
-
-**Always diff the regen output before committing.** These generators rewrite every file they own, so they will also sweep in unrelated drift that accumulated on the base branch — pages losing sections, unrelated icons appearing. Keep only the hunks belonging to the integration under validation and `git checkout --` the rest, otherwise an unrelated doc regression rides along in the PR. Verify no page was silently dropped by comparing the directory listing before and after.
+- **`docs:check`** — check mode of `generate-docs.ts`: renders every generated docs artifact in
+  memory and fails listing any committed file that differs. Runs in CI via `check:audits`.
+
+**Always diff the regen output before committing — but commit all of it.** These generators rewrite
+every file they own, so they also true up drift that accumulated on the base branch (pages whose
+source changed without a regen). That catch-up is correct output, not a regression: `docs:check`
+fails CI on any page left stale, so reverting swept-in hunks with `git checkout --` reintroduces the
+failure. Review the diff to confirm each hunk is explained by a real source change (yours or an
+upstream PR that skipped regeneration), and investigate anything that looks like content loss — a
+page losing a section usually means its source block moved or a generator input broke, not that the
+hunk should be reverted.
 
 If an icon changed, `apps/sim/components/icons.tsx` is the source of truth and `apps/docs/components/icons.tsx` is its generated mirror — they must end up byte-identical for that component.
 
@@ -408,9 +418,10 @@ After fixing, confirm:
 3. The integration's tests pass, and any test you added actually fails without its fix (revert it once and watch it go red)
 4. Derived artifacts regenerated and their diffs reviewed (see above)
 5. `bun run integration-catalog:check` passes
-6. For OAuth or service-account changes, `bun test apps/sim/lib/integrations/availability.server.test.ts` passes
-7. Re-read all modified files to verify fixes are correct
-8. Any remaining unknown response schemas were explicitly reported to the user instead of guessed
+6. `bun run docs:check` passes
+7. For OAuth or service-account changes, `bun test apps/sim/lib/integrations/availability.server.test.ts` passes
+8. Re-read all modified files to verify fixes are correct
+9. Any remaining unknown response schemas were explicitly reported to the user instead of guessed
 
 ## Checklist Summary
 
@@ -439,7 +450,7 @@ After fixing, confirm:
 - [ ] Reported all issues grouped by severity
 - [ ] Fixed all critical and warning issues
 - [ ] Ran `bun run tool-metadata:generate` if any tool outputs/params changed, and confirmed `bun run tool-metadata:check` passes
-- [ ] Ran `bun run generate-docs` if any block metadata changed, and reverted unrelated drift the generator swept in
+- [ ] Ran `bun run generate-docs` if any block metadata changed, and committed the full generated diff — including stale-page catch-up for other integrations (`bun run docs:check` fails CI on reverted generator output)
 - [ ] Ran `bun run lint` after fixes
 - [ ] Verified TypeScript compiles clean
 - [ ] Verified added tests fail without their fix
diff --git a/.claude/commands/add-block-preview.md b/.claude/commands/add-block-preview.md