@@ -19,6 +19,10 @@ When the user asks you to create a block:
 
 Blocks depend on tool outputs. If the underlying tool response schema is not documented or live-verified, you MUST tell the user instead of guessing block outputs.
 
+When block work changes tool execution, same-process work must use a registered
+`InternalToolConfig.operation`. Never add a Sim `/api/...` self-hop or the retired
+`directExecution` property.
+
 - Do NOT invent block outputs for undocumented tool responses
 - Do NOT describe unknown JSON shapes as if they were confirmed
 - Do NOT wire fields into the block just because they seem likely to exist
@@ -52,6 +56,12 @@ export const {ServiceName}Block: BlockConfig = {
   // Auth mode
   authMode: AuthMode.OAuth,             // or AuthMode.ApiKey
 
+  // Card summary sentences — see "Canvas Sentences" below
+  canvasPresentation: {
+    defaultTitle: '{Default Operation}',
+    sentences: { byOperation: { /* one per operation dropdown option id */ } },
+  },
+
   subBlocks: [
     // Define all UI fields here
   ],
@@ -163,13 +173,41 @@ export const {ServiceName}Block: BlockConfig = {
 
 Optional companions: `credentialLabels` (override the picker's section/connect-row copy) and `allowServiceAccounts: true` (trigger-mode only — list service accounts, which triggers otherwise exclude; set only when the trigger's polling path can resolve a service-account token). The connect modal, provider families (Google JSON key, Atlassian token, token-paste, client-credential, Slack bot), and the preview gate are all resolved from `serviceAccountProviderId` — you don't wire them per block.
 
+### OAuth deployment availability (required for integration blocks)
+
+A visible tools-category block with OAuth is deployment-gated. Its `oauth-input.serviceId` is
+projected into `packages/deployment-config/src/integrations.json`, then resolved through
+`resolveOAuthClientCapabilityId()` in `packages/deployment-config/src/env-capabilities.ts`.
+
+When adding or changing an OAuth integration block:
+
+1. Keep exactly one distinct OAuth `serviceId` across the block's `oauth-input` subBlocks.
+2. Confirm that service ID resolves to an entry in `OAUTH_CLIENT_CAPABILITIES`. Google and
+   Microsoft service IDs intentionally share their provider-level capability; do not add duplicate
+   entries for those aliases.
+3. For a new capability, add its required client fields to `OAUTH_CLIENT_CAPABILITIES` and ensure
+   every referenced field exists in the env schema in `apps/sim/lib/core/config/env.ts`. Then add
+   the matching `text` or `secret` input modes to `OAUTH_CLIENT_SETUP_FIELDS` in
+   `packages/sim-setup/src/capability-config.ts`. The CLI catalog is exhaustively typed and checked
+   against the runtime field list; do not infer secrecy from the field name.
+4. If the canonical OAuth service declares `serviceAccountProviderId`, run
+   `bun run deployment-config:generate`; this regenerates the provider-ID facts in
+   `packages/deployment-config/src/service-account-providers.generated.ts`. Never hand-edit that
+   generated map. Add `deploymentRequirement` policy in
+   `packages/deployment-config/src/service-account-metadata.ts` only when the service-account path
+   is preview-gated or depends on the OAuth client fields; otherwise omit it.
+
+Missing capability metadata is a runtime configuration error, not a reason to make the integration
+silently available.
+
 ### Selectors (with dynamic options)
 ```typescript
 // Channel selector (Slack, Discord, etc.)
 {
   id: 'channel',
   title: 'Channel',
   type: 'channel-selector',
+  selectorKey: '{service}.channels',
   serviceId: '{service}',
   placeholder: 'Select channel',
   dependsOn: ['credential'],
@@ -180,6 +218,7 @@ Optional companions: `credentialLabels` (override the picker's section/connect-r
   id: 'project',
   title: 'Project',
   type: 'project-selector',
+  selectorKey: '{service}.projects',
   serviceId: '{service}',
   dependsOn: ['credential'],
 }
@@ -189,6 +228,7 @@ Optional companions: `credentialLabels` (override the picker's section/connect-r
   id: 'file',
   title: 'File',
   type: 'file-selector',
+  selectorKey: '{service}.files',
   serviceId: '{service}',
   mimeType: 'application/pdf',
   dependsOn: ['credential'],
@@ -199,6 +239,7 @@ Optional companions: `credentialLabels` (override the picker's section/connect-r
   id: 'user',
   title: 'User',
   type: 'user-selector',
+  selectorKey: '{service}.users',
   serviceId: '{service}',
   dependsOn: ['credential'],
 }
@@ -919,6 +960,62 @@ Derive templates from the service's real use cases. Each prompt should name a co
 - **Ground every skill in operations the block actually exposes** — cross-check each skill's steps against `tools.access`. Never describe an action the integration cannot perform.
 - **Derive skills from real, popular use cases found online — never invent them.** Web-search the service's documented use cases (vendor use-case/solutions pages, official docs describing the workflow, reputable "top automations for X" articles) and only add a skill you can source as something people genuinely do with the service. Do not hallucinate skills.
 
+## Canvas Sentences
+
+Every block declares a one-line prose summary that replaces its card's field rows:
+
+```
+Slack                                    ← header (already names the block)
+Posts ⟨Ship it 🚀⟩ to ⟨#eng⟩             ← the sentence; ⟨…⟩ are live value chips
+```
+
+Write one `byOperation` entry per operation dropdown option (or a single `default`
+when the block has no operation dropdown).
+
+**The full authoring contract — voice, structure, and the two mistakes that break
+cards silently — is `apps/sim/blocks/AGENTS.md` → "Canvas sentences". Read it
+before writing any.** The two failures worth repeating here, because both are
+invisible at runtime:
+
+1. A clause naming only one member of a `canonicalParamId` pair drops the sentence
+   for every advanced-mode user. List all members:
+   `field: ['channelSelector', 'manualChannel']`.
+2. A clause referencing a subblock whose `condition` excludes that operation can
+   never render.
+
+Validate before finishing:
+
+```bash
+bun run apps/sim/scripts/check-canvas-sentences.ts --block={service}
+```
+
+## Generated artifacts
+
+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 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 now reads those from the generated metadata rather than 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.
+
 ## Checklist Before Finishing
 
 - [ ] `integrationType` is set to the correct `IntegrationType` enum value
@@ -928,18 +1025,26 @@ Derive templates from the service's real use cases. Each prompt should name a co
 - [ ] DependsOn set for fields that need other values
 - [ ] Required fields marked correctly (boolean or condition)
 - [ ] OAuth inputs have correct `serviceId` and `requiredScopes: getScopesForService(serviceId)`
+- [ ] Every OAuth `serviceId` resolves through `resolveOAuthClientCapabilityId()` to the correct `OAUTH_CLIENT_CAPABILITIES` entry
+- [ ] Any new OAuth capability fields exist in `apps/sim/lib/core/config/env.ts`
+- [ ] If the OAuth service supports service accounts, `SERVICE_ACCOUNT_METADATA_BY_OAUTH_SERVICE_ID` matches its canonical `serviceAccountProviderId` and deployment requirement
 - [ ] Scope descriptions added to `SCOPE_DESCRIPTIONS` in `lib/oauth/utils.ts` for any new scopes
 - [ ] Tools.access lists all tool IDs (snake_case)
 - [ ] Tools.config.tool returns correct tool ID (snake_case)
 - [ ] Outputs match tool outputs
 - [ ] Block + meta registered in registry-maps.ts (`BLOCK_REGISTRY` / `BLOCK_META_REGISTRY`)
+- [ ] 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'`
 - [ ] Timestamps and complex inputs have `wandConfig` enabled
 - [ ] Exported `{Service}BlockMeta` with at least 7 templates
 - [ ] `url` set on `{Service}BlockMeta` to the external service's verified homepage (omit only for first-party blocks with no external service)
 - [ ] `skills` added to `{Service}BlockMeta`, each grounded in `tools.access` and sourced from a real online use case (not invented)
+- [ ] `canvasPresentation.sentences` covers every operation, and `bun run apps/sim/scripts/check-canvas-sentences.ts --block={service}` passes with 100% coverage
 
 ## Final Validation (Required)
 
@@ -955,3 +1060,49 @@ After creating the block, you MUST validate it against every tool it references:
 4. **Verify conditions** — each subBlock should only show for the operations that actually use it
 5. **Verify `{Service}BlockMeta` is exported** with at least 7 templates, each having `icon`, `title`, `prompt`, `modules`, `category`, and `tags`
 6. **If any tool outputs are still unknown**, explicitly tell the user instead of guessing block outputs
+7. **Verify the tool execution boundary** — blocks never create or call API routes. Every referenced
+   tool must already be either a registered `InternalToolConfig.operation` or an absolute external
+   HTTP(S) `ToolConfig.request`. If transport needs to change, use the `add-tools` skill; do not add a
+   same-origin `/api/...` hop from the block.
+
+## 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 browser-safe metadata in
+`apps/sim/lib/selectors/manifest.ts`. Attach `provider-server` selectors under
+`apps/sim/lib/selectors/server/providers/` and `internal-server` selectors in
+`apps/sim/lib/selectors/server/internal.ts`. Point the sub-block at that key. 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 projects only active `dependsOn` values and keys canonical pairs by their
+canonical id. Exact environment references such as `{{GMAIL_CREDENTIAL_ID}}` stay unresolved in the
+browser and are resolved only by the authorized server executor. The builder does not infer a
+nonstandard credential id from `type: 'oauth-input'`; give it
+`canonicalParamId: 'oauthCredential'`, or declare an explicit 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 context values.** This includes credential IDs, raw secrets,
+  unresolved references, and hashes of those values; the shared facade uses an opaque local revision.
+- **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.