GeezerVison is showing github.com — docs(skills): require docs:check in the integration authoring skills · simstudioai/sim@ccedbb2
File treeExpand file treeCollapse file tree Open diff view settings Expand file treeCollapse file tree Open diff view settings Collapse file Copy file name to clipboardExpand all lines: .agents/skills/add-block/SKILL.md +7-2Lines changed: 7 additions & 2 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
@@ -993,11 +993,15 @@ After adding or changing one, run: | 993 | 993 | ```bash | 994 | 994 | bun run scripts/generate-docs.ts | 995 | 995 | bun run integration-catalog:check | | 996 | +bun run docs:check | 996 | 997 | ``` | 997 | 998 |
| 998 | 999 | The catalog check independently derives deployment metadata from the executable block registry and | 999 | | -compares it with the committed `apps/sim/lib/integrations/integrations.json`. Review the generated | 1000 | | -diff and keep only intentional changes. | | 1000 | +compares it with the committed `apps/sim/lib/integrations/integrations.json`. `docs:check` re-renders | | 1001 | +every generated docs artifact in memory and fails on any committed file that differs — it runs in CI | | 1002 | +via `check:audits`, so commit the full generator output. If the generator also trues up pages an | | 1003 | +earlier PR left stale, commit that catch-up too; reverting it as "unrelated drift" makes `docs:check` | | 1004 | +fail. | 1001 | 1005 | ## Checklist Before Finishing | 1002 | 1006 |
| 1003 | 1007 | - [ ] `integrationType` is set to the correct `IntegrationType` enum value | @@ -1018,6 +1022,7 @@ diff and keep only intentional changes. | 1018 | 1022 | - [ ] If any tool was added, changed or removed alongside the block: ran `bun run tool-metadata:generate` and committed the artifacts | 1019 | 1023 | - [ ] Ran `bun run scripts/generate-docs.ts`, reviewed the generated diff, and committed the integration catalog changes | 1020 | 1024 | - [ ] `bun run integration-catalog:check` passes | | 1025 | +- [ ] `bun run docs:check` passes (CI gate — fails on any stale generated docs page) | 1021 | 1026 | - [ ] If icon missing: asked user to provide SVG | 1022 | 1027 | - [ ] If triggers exist: `triggers` config set, trigger subBlocks spread | 1023 | 1028 | - [ ] Optional/rarely-used fields set to `mode: 'advanced'` | |
Collapse file Copy file name to clipboardExpand all lines: .agents/skills/add-integration/SKILL.md +4Lines changed: 4 additions & 0 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
@@ -561,6 +561,7 @@ Run the documentation generator: | 561 | 561 | ```bash | 562 | 562 | bun run scripts/generate-docs.ts | 563 | 563 | bun run integration-catalog:check | | 564 | +bun run docs:check | 564 | 565 | ``` | 565 | 566 |
| 566 | 567 | 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): | 651 | 652 | - [ ] Verified docs file created | 652 | 653 | - [ ] Reviewed and committed the generated `apps/sim/lib/integrations/integrations.json` change | 653 | 654 | - [ ] `bun run integration-catalog:check` passes | | 655 | +- [ ] `bun run docs:check` passes — CI fails on stale generated docs, so commit the full generator | | 656 | + output, including catch-up regeneration for pages another PR left stale (never revert it as | | 657 | + "unrelated drift") | 654 | 658 |
| 655 | 659 | ### Final Validation (Required) | 656 | 660 | - [ ] Read every tool file and cross-referenced inputs/outputs against the API docs | |
Collapse file Copy file name to clipboardExpand all lines: .agents/skills/add-tools/SKILL.md +3Lines changed: 3 additions & 0 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
@@ -475,6 +475,9 @@ All tool IDs MUST use `snake_case`: `{service}_{action}` (e.g., `x_create_tweet` | 475 | 475 | - [ ] Index.ts exports all tools and re-exports types (`export * from './types'`) | 476 | 476 | - [ ] Tools registered in `tools/registry.ts` | 477 | 477 | - [ ] `bun run tool-metadata:generate` run and the regenerated artifacts committed | | 478 | +- [ ] `bun run scripts/generate-docs.ts` run and the refreshed docs committed — the integration's | | 479 | + docs page is rendered from each tool's description, params, and outputs, and CI's | | 480 | + `bun run docs:check` fails on stale pages | 478 | 481 | - [ ] Block wired: `tools.access`, dropdown options, subBlocks, `tools.config`, outputs, inputs | 479 | 482 | - [ ] Model, durable-storage, and internal-execution boundaries use the shared provenance mechanisms | 480 | 483 | only where a concrete Sim `{{...}}` resolution path requires them | |
Collapse file Copy file name to clipboardExpand all lines: .agents/skills/add-trigger/SKILL.md +3Lines changed: 3 additions & 0 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
@@ -511,3 +511,6 @@ Add to `helm/sim/values.yaml` under the existing polling cron jobs: | 511 | 511 | - [ ] `bun run type-check` passes | 512 | 512 | - [ ] Manually verify output keys match trigger `outputs` keys | 513 | 513 | - [ ] Trigger UI shows correctly in the block | | 514 | +- [ ] Ran `bun run scripts/generate-docs.ts` and committed the refreshed pages — trigger sections | | 515 | + render into the owning integration's docs page, and CI's `bun run docs:check` fails on stale | | 516 | + pages |
Collapse file Copy file name to clipboardExpand all lines: .agents/skills/validate-integration/SKILL.md +17-6Lines changed: 17 additions & 6 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
@@ -388,15 +388,25 @@ Several files are generated from tool and block definitions. Editing a tool or b | 388 | 388 | bun run tool-metadata:generate # repo root — apps/sim/tools/generated/* | 389 | 389 | bun run scripts/generate-docs.ts # docs .mdx + lib/integrations/integrations.json + docs icons | 390 | 390 | bun run integration-catalog:check # registry ↔ committed deployment metadata drift | | 391 | +bun run docs:check # committed docs ↔ what the generator renders today | 391 | 392 | ``` | 392 | 393 |
| 393 | 394 | - **`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. | 394 | 395 | - **`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`. | 395 | 396 | - **`integration-catalog:check`** — loads the executable block registry, derives visible integration | 396 | 397 | deployment fields, and compares them with the committed catalog. It catches missing/unexpected | 397 | 398 | entries and stale auth/service IDs without loading the executable registry in client code. | 398 | | - | 399 | | -**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. | | 399 | +- **`docs:check`** — check mode of `generate-docs.ts`: renders every generated docs artifact in | | 400 | + memory and fails listing any committed file that differs. Runs in CI via `check:audits`. | | 401 | + | | 402 | +**Always diff the regen output before committing — but commit all of it.** These generators rewrite | | 403 | +every file they own, so they also true up drift that accumulated on the base branch (pages whose | | 404 | +source changed without a regen). That catch-up is correct output, not a regression: `docs:check` | | 405 | +fails CI on any page left stale, so reverting swept-in hunks with `git checkout --` reintroduces the | | 406 | +failure. Review the diff to confirm each hunk is explained by a real source change (yours or an | | 407 | +upstream PR that skipped regeneration), and investigate anything that looks like content loss — a | | 408 | +page losing a section usually means its source block moved or a generator input broke, not that the | | 409 | +hunk should be reverted. | 400 | 410 |
| 401 | 411 | 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. | 402 | 412 |
| @@ -408,9 +418,10 @@ After fixing, confirm: | 408 | 418 | 3. The integration's tests pass, and any test you added actually fails without its fix (revert it once and watch it go red) | 409 | 419 | 4. Derived artifacts regenerated and their diffs reviewed (see above) | 410 | 420 | 5. `bun run integration-catalog:check` passes | 411 | | -6. For OAuth or service-account changes, `bun test apps/sim/lib/integrations/availability.server.test.ts` passes | 412 | | -7. Re-read all modified files to verify fixes are correct | 413 | | -8. Any remaining unknown response schemas were explicitly reported to the user instead of guessed | | 421 | +6. `bun run docs:check` passes | | 422 | +7. For OAuth or service-account changes, `bun test apps/sim/lib/integrations/availability.server.test.ts` passes | | 423 | +8. Re-read all modified files to verify fixes are correct | | 424 | +9. Any remaining unknown response schemas were explicitly reported to the user instead of guessed | 414 | 425 |
| 415 | 426 | ## Checklist Summary | 416 | 427 |
| @@ -439,7 +450,7 @@ After fixing, confirm: | 439 | 450 | - [ ] Reported all issues grouped by severity | 440 | 451 | - [ ] Fixed all critical and warning issues | 441 | 452 | - [ ] Ran `bun run tool-metadata:generate` if any tool outputs/params changed, and confirmed `bun run tool-metadata:check` passes | 442 | | -- [ ] Ran `bun run generate-docs` if any block metadata changed, and reverted unrelated drift the generator swept in | | 453 | +- [ ] 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) | 443 | 454 | - [ ] Ran `bun run lint` after fixes | 444 | 455 | - [ ] Verified TypeScript compiles clean | 445 | 456 | - [ ] Verified added tests fail without their fix |
Collapse file Copy file name to clipboardExpand all lines: .claude/commands/add-block.md +7-2Lines changed: 7 additions & 2 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
@@ -992,11 +992,15 @@ After adding or changing one, run: | 992 | 992 | ```bash | 993 | 993 | bun run scripts/generate-docs.ts | 994 | 994 | bun run integration-catalog:check | | 995 | +bun run docs:check | 995 | 996 | ``` | 996 | 997 |
| 997 | 998 | The catalog check independently derives deployment metadata from the executable block registry and | 998 | | -compares it with the committed `apps/sim/lib/integrations/integrations.json`. Review the generated | 999 | | -diff and keep only intentional changes. | | 999 | +compares it with the committed `apps/sim/lib/integrations/integrations.json`. `docs:check` re-renders | | 1000 | +every generated docs artifact in memory and fails on any committed file that differs — it runs in CI | | 1001 | +via `check:audits`, so commit the full generator output. If the generator also trues up pages an | | 1002 | +earlier PR left stale, commit that catch-up too; reverting it as "unrelated drift" makes `docs:check` | | 1003 | +fail. | 1000 | 1004 | ## Checklist Before Finishing | 1001 | 1005 |
| 1002 | 1006 | - [ ] `integrationType` is set to the correct `IntegrationType` enum value | @@ -1017,6 +1021,7 @@ diff and keep only intentional changes. | 1017 | 1021 | - [ ] If any tool was added, changed or removed alongside the block: ran `bun run tool-metadata:generate` and committed the artifacts | 1018 | 1022 | - [ ] Ran `bun run scripts/generate-docs.ts`, reviewed the generated diff, and committed the integration catalog changes | 1019 | 1023 | - [ ] `bun run integration-catalog:check` passes | | 1024 | +- [ ] `bun run docs:check` passes (CI gate — fails on any stale generated docs page) | 1020 | 1025 | - [ ] If icon missing: asked user to provide SVG | 1021 | 1026 | - [ ] If triggers exist: `triggers` config set, trigger subBlocks spread | 1022 | 1027 | - [ ] Optional/rarely-used fields set to `mode: 'advanced'` | |
Collapse file Copy file name to clipboardExpand all lines: .claude/commands/add-integration.md +4Lines changed: 4 additions & 0 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
@@ -560,6 +560,7 @@ Run the documentation generator: | 560 | 560 | ```bash | 561 | 561 | bun run scripts/generate-docs.ts | 562 | 562 | bun run integration-catalog:check | | 563 | +bun run docs:check | 563 | 564 | ``` | 564 | 565 |
| 565 | 566 | 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`). | @@ -650,6 +651,9 @@ If creating V2 versions (API-aligned outputs): | 650 | 651 | - [ ] Verified docs file created | 651 | 652 | - [ ] Reviewed and committed the generated `apps/sim/lib/integrations/integrations.json` change | 652 | 653 | - [ ] `bun run integration-catalog:check` passes | | 654 | +- [ ] `bun run docs:check` passes — CI fails on stale generated docs, so commit the full generator | | 655 | + output, including catch-up regeneration for pages another PR left stale (never revert it as | | 656 | + "unrelated drift") | 653 | 657 |
| 654 | 658 | ### Final Validation (Required) | 655 | 659 | - [ ] Read every tool file and cross-referenced inputs/outputs against the API docs | |
Collapse file Copy file name to clipboardExpand all lines: .claude/commands/add-tools.md +3Lines changed: 3 additions & 0 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
@@ -474,6 +474,9 @@ All tool IDs MUST use `snake_case`: `{service}_{action}` (e.g., `x_create_tweet` | 474 | 474 | - [ ] Index.ts exports all tools and re-exports types (`export * from './types'`) | 475 | 475 | - [ ] Tools registered in `tools/registry.ts` | 476 | 476 | - [ ] `bun run tool-metadata:generate` run and the regenerated artifacts committed | | 477 | +- [ ] `bun run scripts/generate-docs.ts` run and the refreshed docs committed — the integration's | | 478 | + docs page is rendered from each tool's description, params, and outputs, and CI's | | 479 | + `bun run docs:check` fails on stale pages | 477 | 480 | - [ ] Block wired: `tools.access`, dropdown options, subBlocks, `tools.config`, outputs, inputs | 478 | 481 | - [ ] Model, durable-storage, and internal-execution boundaries use the shared provenance mechanisms | 479 | 482 | only where a concrete Sim `{{...}}` resolution path requires them | |
Collapse file Copy file name to clipboardExpand all lines: .claude/commands/add-trigger.md +3Lines changed: 3 additions & 0 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
@@ -510,3 +510,6 @@ Add to `helm/sim/values.yaml` under the existing polling cron jobs: | 510 | 510 | - [ ] `bun run type-check` passes | 511 | 511 | - [ ] Manually verify output keys match trigger `outputs` keys | 512 | 512 | - [ ] Trigger UI shows correctly in the block | | 513 | +- [ ] Ran `bun run scripts/generate-docs.ts` and committed the refreshed pages — trigger sections | | 514 | + render into the owning integration's docs page, and CI's `bun run docs:check` fails on stale | | 515 | + pages |
Collapse file Copy file name to clipboardExpand all lines: .claude/commands/validate-integration.md +17-6Lines changed: 17 additions & 6 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
@@ -387,15 +387,25 @@ Several files are generated from tool and block definitions. Editing a tool or b | 387 | 387 | bun run tool-metadata:generate # repo root — apps/sim/tools/generated/* | 388 | 388 | bun run scripts/generate-docs.ts # docs .mdx + lib/integrations/integrations.json + docs icons | 389 | 389 | bun run integration-catalog:check # registry ↔ committed deployment metadata drift | | 390 | +bun run docs:check # committed docs ↔ what the generator renders today | 390 | 391 | ``` | 391 | 392 |
| 392 | 393 | - **`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. | 393 | 394 | - **`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`. | 394 | 395 | - **`integration-catalog:check`** — loads the executable block registry, derives visible integration | 395 | 396 | deployment fields, and compares them with the committed catalog. It catches missing/unexpected | 396 | 397 | entries and stale auth/service IDs without loading the executable registry in client code. | 397 | | - | 398 | | -**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. | | 398 | +- **`docs:check`** — check mode of `generate-docs.ts`: renders every generated docs artifact in | | 399 | + memory and fails listing any committed file that differs. Runs in CI via `check:audits`. | | 400 | + | | 401 | +**Always diff the regen output before committing — but commit all of it.** These generators rewrite | | 402 | +every file they own, so they also true up drift that accumulated on the base branch (pages whose | | 403 | +source changed without a regen). That catch-up is correct output, not a regression: `docs:check` | | 404 | +fails CI on any page left stale, so reverting swept-in hunks with `git checkout --` reintroduces the | | 405 | +failure. Review the diff to confirm each hunk is explained by a real source change (yours or an | | 406 | +upstream PR that skipped regeneration), and investigate anything that looks like content loss — a | | 407 | +page losing a section usually means its source block moved or a generator input broke, not that the | | 408 | +hunk should be reverted. | 399 | 409 |
| 400 | 410 | 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. | 401 | 411 |
| @@ -407,9 +417,10 @@ After fixing, confirm: | 407 | 417 | 3. The integration's tests pass, and any test you added actually fails without its fix (revert it once and watch it go red) | 408 | 418 | 4. Derived artifacts regenerated and their diffs reviewed (see above) | 409 | 419 | 5. `bun run integration-catalog:check` passes | 410 | | -6. For OAuth or service-account changes, `bun test apps/sim/lib/integrations/availability.server.test.ts` passes | 411 | | -7. Re-read all modified files to verify fixes are correct | 412 | | -8. Any remaining unknown response schemas were explicitly reported to the user instead of guessed | | 420 | +6. `bun run docs:check` passes | | 421 | +7. For OAuth or service-account changes, `bun test apps/sim/lib/integrations/availability.server.test.ts` passes | | 422 | +8. Re-read all modified files to verify fixes are correct | | 423 | +9. Any remaining unknown response schemas were explicitly reported to the user instead of guessed | 413 | 424 |
| 414 | 425 | ## Checklist Summary | 415 | 426 |
| @@ -438,7 +449,7 @@ After fixing, confirm: | 438 | 449 | - [ ] Reported all issues grouped by severity | 439 | 450 | - [ ] Fixed all critical and warning issues | 440 | 451 | - [ ] Ran `bun run tool-metadata:generate` if any tool outputs/params changed, and confirmed `bun run tool-metadata:check` passes | 441 | | -- [ ] Ran `bun run generate-docs` if any block metadata changed, and reverted unrelated drift the generator swept in | | 452 | +- [ ] 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) | 442 | 453 | - [ ] Ran `bun run lint` after fixes | 443 | 454 | - [ ] Verified TypeScript compiles clean | 444 | 455 | - [ ] Verified added tests fail without their fix |
|