Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
81 commits
Select commit Hold shift + click to select a range
bc8f09c
feat(workflow-code): workflows and workspace as code (#10129)
waleedlatif1 Nov 19, 2026
76fa5b5
feat(mothership): expose owner entitlements to the workbench as SIM_E…
waleedlatif1 Nov 19, 2026
b3e928f
fix(redis): give chat its own per-user byte budget and name sizes in …
waleedlatif1 Nov 20, 2026
6856efa
fix(workflow-code): staging QA fixes for workflows and workspace as c…
waleedlatif1 Nov 20, 2026
86db551
feat(mcp): enable code mode for every caller and remove the mcp-code-…
waleedlatif1 Nov 20, 2026
1ace34f
feat(computer-use): find and update reminders through app commands (#…
waleedlatif1 Nov 20, 2026
892d8d8
improvement(ci): run the large permission import e2e beside organizat…
waleedlatif1 Nov 20, 2026
645a8d2
feat(comparisons): add Sim vs Dify and Sim vs Relevance AI comparison…
waleedlatif1 Nov 20, 2026
8d37e10
fix(mcp): word the code-mode deadline timeout like any other timeout …
waleedlatif1 Nov 20, 2026
bb43072
chore(ci): document the search-permissions acceptance job (#10230)
waleedlatif1 Nov 20, 2026
5d0cb3e
chore(ci): correct how the search-permissions job exercises the CLI (…
waleedlatif1 Nov 20, 2026
017ac49
feat(computer-use): edit calendar events and add to contacts through …
waleedlatif1 Nov 20, 2026
d0dc01c
improvement(hooks): check only changed files and affected workspaces …
waleedlatif1 Nov 20, 2026
a8d591e
fix(desktop): fix the races behind retried e2e checks and stop retryi…
waleedlatif1 Nov 20, 2026
5929764
fix(workflow-code): DX fixes from the staging A/B runs (#10229)
waleedlatif1 Nov 20, 2026
11cd2cb
fix(computer-use): tighten app-command update confirmations (#10236)
waleedlatif1 Nov 20, 2026
4a0f2e4
fix(executor): selected outputs no longer fail runs that call a child…
waleedlatif1 Nov 20, 2026
02fb744
fix(workflow-code): correctness, safety and speed for workflows and w…
waleedlatif1 Nov 20, 2026
9ca9ace
feat(diff): render diffs with Pierre diffs and share one syntax palet…
waleedlatif1 Nov 20, 2026
ee5e418
docs(library): update best-ai-agents-web-scraping-market-research (#1…
waleedlatif1 Nov 20, 2026
a86e8f5
docs(library): update best-ai-agents-support-ticket-triage (#10240)
waleedlatif1 Nov 20, 2026
2d15ae9
feat(library): Visual AI Agent Builder vs Code First Framework: How T…
waleedlatif1 Nov 20, 2026
20b06b0
feat(library): How to Migrate From OpenAI Agent Builder Before the No…
waleedlatif1 Nov 20, 2026
4c0ac32
feat(library): How Do You Build a Twilio SMS AI Agent for Customer No…
waleedlatif1 Nov 20, 2026
26caf90
refactor(workflow-code): source pipeline plan/commit split, one findi…
waleedlatif1 Nov 20, 2026
170279a
improvement(ci): start http e2e jobs beside the e2e build (#10244)
waleedlatif1 Nov 20, 2026
d34c7cd
docs(workflows): add large data page with size limits and loop result…
waleedlatif1 Nov 20, 2026
c34a82f
chore(whitelabeling): remove whitelabeling and its branding plumbing …
waleedlatif1 Nov 20, 2026
774eed3
feat(models): add Gemini 4 Neon/Hydrogen/Carbon, GPT-6.2 Astra/Sol, G…
waleedlatif1 Nov 20, 2026
5cb1769
chore(models): regenerate SDK fixture catalog (#10252)
waleedlatif1 Nov 20, 2026
1d1ff5b
chore(sdk): generate the SDK fixture catalog from a script and add a …
waleedlatif1 Nov 20, 2026
8d8606e
chore(scripts): enforce generate/check pairs and regenerate every art…
waleedlatif1 Nov 20, 2026
9743e49
fix(ci): bound the e2e build wait and the suite separately (#10257)
waleedlatif1 Nov 20, 2026
0a61e14
improvement(models): retire deep research, refresh model lifecycle, p…
waleedlatif1 Nov 20, 2026
8d12171
feat(editor): replace monaco with pierre's editor, parse user code wi…
waleedlatif1 Nov 20, 2026
126da70
fix(workspace-source): retry blobs a sweep kept even when the next sw…
waleedlatif1 Nov 20, 2026
74eca43
improvement(ci): turn off crash durability on throwaway CI postgres (…
waleedlatif1 Nov 20, 2026
9f5d117
fix(editor): apply external updates to the code editor as the span th…
waleedlatif1 Nov 20, 2026
2689d4e
improvement(ci): install e2e browser system packages from a per-image…
waleedlatif1 Nov 20, 2026
9964728
fix(markdown): preserve formatting and literal text on paste (#10261)
waleedlatif1 Nov 21, 2026
1734687
fix(files): keep the reader's caret when the markdown editor settles …
waleedlatif1 Nov 21, 2026
2edb436
chore(mothership): take the remaining contracts from the worker and d…
waleedlatif1 Nov 21, 2026
f095a34
fix(e2e): restore the keyboard-only markdown selection and wait for i…
waleedlatif1 Nov 21, 2026
f96af7c
chore(ci): refresh integration shard weights from the latest staging …
waleedlatif1 Nov 21, 2026
4e7840d
test(knowledge): report the window walk's index condition, filter and…
waleedlatif1 Nov 21, 2026
6695fa6
improvement(library): answer OpenAI SDK, Assistants API, and worth-it…
waleedlatif1 Nov 21, 2026
a0aca94
fix(files): avoid stale editor views on cached navigation (#10266)
waleedlatif1 Nov 21, 2026
3153f6e
fix(e2e): distinguish WebKit viewport diagnostics from editor errors …
waleedlatif1 Nov 21, 2026
287a110
chore(cleanup): remove dead chart options, the playground and legacy …
waleedlatif1 Nov 21, 2026
e6f6a0f
improvement(config): derive enterprise flags from one registry, add R…
waleedlatif1 Nov 21, 2026
6787693
fix(workflow-code): staging QA fixes for runtime, promote, workspace …
waleedlatif1 Nov 21, 2026
85ea094
chore(redis): require Redis and remove the no-Redis fallbacks (#10272)
waleedlatif1 Nov 21, 2026
188d06f
fix(executor): keep the condition-join loop test off the Redis-backed…
waleedlatif1 Nov 21, 2026
68f8aba
fix(public-shares): retry a public read when the shared file is saved…
waleedlatif1 Nov 21, 2026
a009b7c
fix(docs): close the Redis client so the docs provider e2e exits (#10…
waleedlatif1 Nov 21, 2026
07938f0
chore(cleanup): drop leftover white-labeling claims and fix the Helm …
waleedlatif1 Nov 21, 2026
dfff8c3
refactor(workflow-code): simplify the source dir lock release and dro…
waleedlatif1 Nov 21, 2026
754a28e
fix(executor): a loop whose condition cannot be evaluated fails inste…
waleedlatif1 Nov 21, 2026
66938dd
Revert "fix(files): keep the reader's caret when the markdown editor …
waleedlatif1 Nov 21, 2026
534c8ba
chore(mothership): take the worker's typed stream contract, own telem…
waleedlatif1 Nov 21, 2026
7a902fc
improvement(ci): drop the e2e build's persistent compiler cache (#10281)
waleedlatif1 Nov 21, 2026
825a419
chore(cleanup): simplify what the Redis, config and removal changes l…
waleedlatif1 Nov 21, 2026
8bc0ce2
fix(sim-cli): publish when bundled packages change, complete third-pa…
waleedlatif1 Nov 21, 2026
93555ff
fix(workflow-code): bound lock parsing and rename inference, and clos…
waleedlatif1 Nov 21, 2026
293ec1b
improvement(workflow-code): server hardening, flaky test root causes,…
waleedlatif1 Nov 21, 2026
ebbe171
docs(library): update salesforce-ai-agent-lead-scoring-workflow (#10288)
waleedlatif1 Nov 21, 2026
4ae3f75
docs(library): update control-ai-agent-spend-across-teams (#10289)
waleedlatif1 Nov 21, 2026
c0a2c0d
docs(library): update ai-agents-asana-monday-task-automation (#10290)
waleedlatif1 Nov 21, 2026
8a0bddd
docs(library): update best-chatgpt-alternatives-ai-agents-workflow-au…
waleedlatif1 Nov 21, 2026
4b4ed8b
docs(library): update best-voice-ai-agent-builders-phone-support-2026…
waleedlatif1 Nov 21, 2026
d329d12
feat(library): Shadow AI Detection and Governance: A Practical Guide …
waleedlatif1 Nov 21, 2026
5a9537d
feat(library): AI Agent Hosting: Where Should IT Run Production Agent…
waleedlatif1 Nov 21, 2026
9ffbcad
feat(library): How Do Enterprises Build an Internal AI Agent Registry…
waleedlatif1 Nov 21, 2026
61f0d14
feat(library): What Are the Main Security Risks of AI Agents and How …
waleedlatif1 Nov 21, 2026
71d7db5
fix(cli): read @file arguments saved as UTF-16LE or with a byte-order…
b84330808 Nov 21, 2026
29b63df
fix(providers): bill cached prompt tokens at the cached rate for the …
waleedlatif1 Nov 21, 2026
976e3c3
fix(sim-cli): take over a stale source lock whose owner file was left…
waleedlatif1 Nov 21, 2026
7e6a296
fix(models): keep retired models out of catalog recommendations and r…
waleedlatif1 Nov 21, 2026
92aee6b
fix(hooks): skip local lint and type-check when the working tree diff…
waleedlatif1 Nov 22, 2026
cdac23d
fix(workflow-code): release review follow-ups for the knowledge downl…
waleedlatif1 Nov 22, 2026
bf6bc31
improvement(workflow-code): agent DX and check/server parity from the…
waleedlatif1 Nov 22, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
6 changes: 4 additions & 2 deletions .agents/skills/add-block/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -1018,13 +1018,15 @@ When adding or changing `sunset.replacedBy`, run `bun run generate:block-success
map to resolve legacy and current block IDs consistently without importing the executable registry.
Verify it with `bun run check:block-successors`.

A new block type also needs `bun run generate:sdk-names` (commit the new `apps/sim/blocks/sdk-names/<type>.json` and the regenerated `apps/sim/blocks/sdk-names.generated.ts`; names are add-only, and a merge conflict in the generated module is resolved by rerunning the generator) so workflow source gets a typed builder for it; `check:sdk-names` fails CI until it runs.

Adding a block on its own needs no **tool metadata** regeneration — a block references existing
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 generate:tool-metadata` 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:
`bun run generate:tool-metadata` (only when a tool changed), `bun run scripts/generate-docs.ts`,
`bun run generate:tool-metadata` (only when a tool changed), `bun run generate:docs`,
`bun run generate:deployment-config`, then `bun run check:audits`. Also run
`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 →
Expand All @@ -1049,7 +1051,7 @@ Regenerate Derived Artifacts.
- [ ] Block + meta registered in registry-maps.ts (`BLOCK_REGISTRY` / `BLOCK_META_REGISTRY`)
- [ ] If `sunset.replacedBy` changed: regenerated and committed the block successor map; `bun run check:block-successors` passes
- [ ] If any tool was added, changed or removed alongside the block: ran `bun run generate:tool-metadata` and committed the artifacts
- [ ] Ran `bun run scripts/generate-docs.ts`, reviewed the generated diff, and committed the integration catalog changes
- [ ] Ran `bun run generate:docs`, reviewed the generated diff, and committed the integration catalog changes
- [ ] `bun run check:integration-catalog` passes
- [ ] `bun run check:docs` passes (CI gate — fails on any stale generated docs page)
- [ ] If icon missing: asked user to provide SVG
Expand Down
9 changes: 9 additions & 0 deletions .agents/skills/add-column-type/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,15 @@ Registering the *type* is compiler-enforced. Registering its *metadata* is not,

Copy `currency`'s service function and orchestration branch.

## Workspace source and the workflow SDK

The workspace source table codec reads the registry, but the SDK restates each type: add the
`column.<type>()` helper to `packages/workflow-sdk/src/workspace/table.d.ts` (the drift test in
`apps/sim/lib/workspace-source/application/kinds/table/codec.test.ts` fails until you do), map the
type's row value in `valueType()` (`packages/workflow-sdk/src/codegen/workspace.ts`, which defaults to
`string`), and regenerate the embedded text (`bun packages/workflow-sdk/scripts/generate-embedded-text.ts`).
See `.claude/rules/sim-workflow-code.md`.

## Checklist Before Finishing

- [ ] Id appended to `COLUMN_TYPES` in `column-types/types.ts`
Expand Down
12 changes: 7 additions & 5 deletions .agents/skills/add-integration/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,8 +111,8 @@ service id:
`mode: 'advanced'`. An existing block that already takes the secret inline is never edited in
place: add a credential-only successor (`add-block` → Credential-only successor).

Then run `generate-docs`, `generate:block-successors`, `generate:deployment-config`, and
`generate:tool-metadata`, and `check-block-registry.ts origin/staging`. This pattern does not fit
Then run `bun run generate` (every generated artifact, docs included) and
`check-block-registry.ts origin/staging`. This pattern does not fit
hosted-key tools, model-provider keys, two-secret or username/password logins, or a host chosen
per call.

Expand Down Expand Up @@ -371,6 +371,8 @@ export const BLOCK_META_REGISTRY: Record<string, BlockMeta> = {
}
```

Then run `bun run generate:sdk-names` and commit the new `apps/sim/blocks/sdk-names/<type>.json` and the regenerated `apps/sim/blocks/sdk-names.generated.ts` (names are add-only: never edit or delete an existing entry; on a merge conflict in the generated module, rerun the generator), so workflow source gets a typed builder for the new block (`check:sdk-names` fails CI until it runs).

### Trigger Registry (`apps/sim/triggers/registry.ts`) - If triggers exist

```typescript
Expand Down Expand Up @@ -436,7 +438,7 @@ a resolvable capability must fail validation; an independent service account use

## Step 8: Generate and Validate the Catalog

Run `bun run generate:tool-metadata`, `bun run scripts/generate-docs.ts`,
Run `bun run generate:tool-metadata`, `bun run generate:docs`,
`bun run generate:deployment-config`, then `bun run check:audits` (see the `validate-integration`
skill → Regenerate Derived Artifacts for the full list and what each check verifies).

Expand All @@ -462,7 +464,7 @@ In Sim, the {Service} block lets your agents {concrete workflow uses}.

Group the bullets by what the user gets done, not one bullet per tool. Only describe operations the
block actually ships. Follow `.claude/rules/constitution.md` for voice. Re-run
`bun run scripts/generate-docs.ts` afterwards and confirm the section survived unchanged.
`bun run generate:docs` afterwards and confirm the section survived unchanged.

The docs generator refreshes `packages/deployment-config/src/integrations.json`, and the deployment
config generator projects service-account provider IDs from that catalog plus the canonical OAuth
Expand Down Expand Up @@ -580,7 +582,7 @@ If creating V2 versions (API-aligned outputs):
- [ ] Registered all triggers in `triggers/registry.ts`

### Docs and deployment metadata
- [ ] Ran `bun run scripts/generate-docs.ts`
- [ ] Ran `bun run generate:docs`
- [ ] Ran `bun run generate:deployment-config` for OAuth or service-account changes
- [ ] Verified docs file created
- [ ] Wrote the `{/* MANUAL-CONTENT-START:intro */}` section under `<BlockInfoCard />` and confirmed it survives a regenerate
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/add-tools/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -620,7 +620,7 @@ If creating V2 tools (API-aligned outputs), use `_v2` suffix:
- [ ] Index.ts exports all tools and re-exports types (`export * from './types'`)
- [ ] Tools registered in `tools/registry.ts`
- [ ] `bun run generate:tool-metadata` run and the regenerated artifacts committed
- [ ] `bun run scripts/generate-docs.ts` run and the refreshed docs committed — the integration's
- [ ] `bun run generate:docs` 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 check:docs` fails on stale pages
- [ ] Block wired: `tools.access`, dropdown options, subBlocks, `tools.config`, outputs, inputs
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/add-trigger/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -543,6 +543,6 @@ registered `InternalToolConfig.operation`; a `directExecution` property fails
- [ ] `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
- [ ] Ran `bun run generate:docs` and committed the refreshed pages — trigger sections
render into the owning integration's docs page, and CI's `bun run check:docs` fails on stale
pages
2 changes: 1 addition & 1 deletion .agents/skills/db-migrate/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ The lint flags risky *shapes*; it cannot know whether a given drop is *safe righ
```
The reason must be specific and name the PR/version that removed the dependency. An empty reason fails the lint.
- **Warnings** (`data-backfill`): non-blocking, but confirm the batching/idempotency before merging.
4. Regenerate the test schema mock: `bun run scripts/generate-schema-mock.ts` (`check:schema-mock` in `check:audits` fails after any `schema.ts` change until you do).
4. Regenerate the test schema mock: `bun run generate:schema-mock` (`check:schema-mock` in `check:audits` fails after any `schema.ts` change until you do).
5. Re-run `(cd packages/db && bunx drizzle-kit generate)` once your migration is written: it must report no schema changes and write no new file, or CI fails on the schema and migrations disagreeing.
6. Verify locally: `cd packages/db && bun run db:migrate` against a dev DB.

Expand Down
19 changes: 7 additions & 12 deletions .agents/skills/ship/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,24 +47,19 @@ When the user runs `/ship`:
- 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 && 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` 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.
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` job enforces. Both phases abort ship if any generator or audit fails: their runners (`scripts/generate-all.ts`, `scripts/run-audits.ts`) collect each job's exit code and exit non-zero, so never replace them with a backgrounded loop and a bare `wait`, which swallows child exit codes.

**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 — `generate:agent-stream-docs` (derives from the provider model registry), `generate:docs-manifest` (derives from docs page paths), `generate:tool-metadata` (derives from the tool registry), and `skills:sync` (derives from `.agents/skills/**`). They write disjoint outputs (`apps/docs/…/agent.mdx`, `apps/sim/lib/mothership/generated/docs-manifest.ts`, `apps/sim/tools/generated/*`, 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, then let step 7 stage whatever changed.** Run the umbrella generator. It derives its list from package.json (every `generate:<x>` that has a matching `check:<x>`, plus `skills:sync`; see the header of `scripts/generate-all.ts`), so it covers every repo-local generator an ordinary code change can drift (a `models.ts` edit drifts `agent-stream-docs` and the SDK fixture catalog, a tool change drifts `tool-metadata`), runs them in the order their inputs require, and each is idempotent (a no-op when already in sync):
```bash
rm -f /tmp/ship-gen-results
for g in generate:agent-stream-docs generate:docs-manifest generate:tool-metadata skills:sync; do
( bun run "$g" >"/tmp/ship-gen-${g//:/-}.log" 2>&1; echo "$? $g" >>/tmp/ship-gen-results ) &
done
wait
# any non-zero line is a FAILED generator — read /tmp/ship-gen-<name>.log and fix before shipping;
# a silently-failed generate leaves a stale artifact that Phase B / CI then rejects. Keep the
# `exit 1`: it is what makes the block's own status non-zero so a caller actually stops.
if grep -vE '^0 ' /tmp/ship-gen-results; then echo "❌ generator(s) failed — do not ship"; exit 1; fi
# A non-zero exit means a generator FAILED: the summary names it and its output is above. Fix it
# before shipping; a silently-failed generate leaves a stale artifact that Phase B / CI then
# rejects. Keep the `exit 1`: it makes the block's own status non-zero so a caller actually stops.
bun run generate || { echo "❌ generator(s) failed — do not ship"; exit 1; }
echo "✅ artifacts regenerated"
```
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/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 `check:integration-catalog` 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-tools:generate` merges Sim's tool contracts into the base tool catalog in the **external** Mothership worker checkout (`<mothership>/worker/packages/contracts/tool-catalog-v1.json`), which most worktrees lack, so it hard-fails with `ENOENT` and would abort ship for an unrelated reason. The other mothership contracts in `apps/sim/lib/mothership/generated/` are copied in by the worker's `contracts:sync`, never generated here. `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 `check:integration-catalog` 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` (e.g. `bun run mship-tools: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/checks.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
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/v2-api-conventions/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,7 @@ Audited against the primary specs and against Stripe, GitHub, and Google's AIPs.
| **`X-RateLimit-Reset` as delta-seconds** | No | It is an absolute ISO 8601 timestamp, so it is clock-skew sensitive — but the response where timing actually decides behaviour (429) also carries `Retry-After`, which is skew-free. The absolute value stays useful for scheduling. |
| **422 for semantic validation** | No | RFC 9110 §15.5.21 defines 422, but Appendix B.3 records that 9110 **deleted** RFC 4918's clause saying 400 was inappropriate. 400 covers "cannot or will not process… perceived to be a client error". The split is convention, not requirement — GitHub splits, Stripe and Google do not. Our machine-readable `error.code` already carries the distinction, and restatusing now breaks clients. |
| **`Location` on 201** | No | §9.3.3 makes this a `SHOULD` **for POST**; the status code itself (§15.3.2) requires nothing and defines the fallback — absent `Location`, the target URI identifies the resource. Declined knowingly: several 201 responses (signed upload sessions, table exports, knowledge folders) have no canonical single-resource GET, so a `Location` would 404, and adopting it on some of the 19 is worse for a client than on none. Every 201 returns the full representation including its `id`. Revisit per-route if one gains a canonical GET. |
| **ETag / `If-None-Match` / `If-Match`** | No | Every v2 response is `Cache-Control: private, no-store` per-caller data, so `If-None-Match` buys nothing. For writes, `If-Match` needs a **strong** validator: §8.8.3.2's strong comparison fails if *either* tag is weak, so a weak ETag silently makes every `If-Match` fail. None of the three surveyed APIs does HTTP optimistic concurrency — Google does the semantics via a resource `etag` **field** (AIP-154), deliberately not the header. If Sim needs optimistic concurrency, do it that way. |
| **ETag / `If-None-Match` / `If-Match`** | No | Every v2 response is `Cache-Control: private, no-store` per-caller data, so `If-None-Match` buys nothing. The exception is a content-addressed read (the source catalog) that sets the route builder's `entityTag`: its 200 and 304 say `private, no-cache`, so the client keeps the body and revalidates it. For writes, `If-Match` needs a **strong** validator: §8.8.3.2's strong comparison fails if *either* tag is weak, so a weak ETag silently makes every `If-Match` fail. None of the three surveyed APIs does HTTP optimistic concurrency — Google does the semantics via a resource `etag` **field** (AIP-154), deliberately not the header. If Sim needs optimistic concurrency, do it that way. |
| **`Deprecation` / `Sunset` on v1** | Not yet | RFC 9745 (Standards Track) and RFC 8594 (Informational) both apply, and GitHub emits both. But `Sunset` is a timestamp and 9745 §4 makes `Sunset >= Deprecation` a `MUST`, so emitting either commits Sim to a v1 retirement date — a product decision, not an engineering one. When that date exists: `Deprecation` is an RFC 9651 Structured Field **Date** (`@1688169599`); `Sunset` is an **HTTP-date** (`Sat, 31 Dec 2033 23:59:59 GMT`). Two encodings in one response — the most common implementation error here. |
| **`application/merge-patch+json`** | No | v2 PATCH bodies are merge-patch *shaped* — absent means unchanged, `null` clears — but they are `.strict()`, so unknown members are rejected where RFC 7396 §2 would merge them, and nested objects are replaced wholesale rather than merged. Advertising the media type would over-claim. Document the semantics per contract instead. |

Expand Down
Loading
Loading