chore(files): align Project backend with current foundation

Author: mzxchandra

.agents/skills/add-integration/SKILL.md

@@ -26,11 +26,79 @@ Before writing any code:
 1. Use Context7 to find official documentation: `mcp__context7__resolve-library-id`, then fetch with `mcp__context7__query-docs`
 2. Or use WebFetch to read API docs directly
 3. Identify:
-   - Authentication method (OAuth, API Key, both)
+   - Supported authentication grants, who owns the app, and which permissions each operation needs
    - Available operations (CRUD, search, etc.)
    - Required vs optional parameters
    - Response structures
 
+### Choose the connection flow before building tools
+
+Read the provider's current authentication documentation first. “OAuth” describes a protocol;
+it does not imply a browser redirect or a deployment-wide client ID and secret. Compare the
+supported paths and choose the simplest supported setup for the intended user:
+
+| Provider method | Sim connection pattern | Verify in the provider docs |
+| --- | --- | --- |
+| Authorization code | Shared OAuth app and consent flow | Partner approval, redirect URIs, tenant consent, scopes, refresh-token rotation |
+| Customer-owned client credentials | Saved `service_account` credential with a client ID and secret | Internal-app eligibility, grant activation, scope syntax, token lifetime and revocation behavior |
+| API token or personal access token | Saved token service account when reusable connections are useful | Token permissions, identity verification, expiry and rotation |
+| Private key, certificate, or service-account JSON | Existing key-based service-account framework | Signing algorithm, audience, subject, tenant binding and key rotation |
+
+Do not present customer-owned credentials as a way around a provider's approval requirements
+for a shared public integration. Explain the supported account/app type in the setup docs. Keep
+existing OAuth connections usable when other users depend on them, unless a migration or removal is explicitly authorized.
+
+For client credentials, extend the existing descriptors and minter registry under
+`apps/sim/lib/credentials/client-credential-accounts/`; for token credentials, use
+`token-service-accounts/`. Reuse the connect modal, encrypted storage, authorized credential
+operations, and execution-time token resolver. Do not collect reusable secrets on every block,
+invent a credential route, or store a short-lived access token as if it were permanent.
+
+Verify the complete lifecycle, including connect-time verification, concurrent executions on
+different workers, expiry, secret rotation, and permission changes. Some providers invalidate the
+previous token whenever another is minted. Those providers require shared coordination keyed by
+the provider application identity, including across duplicate saved credentials; a process-local
+or per-scope token cache is insufficient. A cache hit must never authenticate a wrong secret or
+silently grant broader permissions. Bound token responses and retries, prevent credential-bearing
+redirects, and never include provider response bodies or secrets in errors.
+
+Use explicit permission choices when the supported operations have different access needs. Keep
+region and permission selections on reconnect unless the user changes them. Verify documented
+identity endpoints rather than guessing which person a client-credentials token represents.
+
+### Pair saved credentials with block and resource selectors
+
+`oauth-input` is the shared saved-credential picker, including for service accounts that never
+redirect to OAuth. Give its basic/advanced pair one `canonicalParamId: 'oauthCredential'`, with
+the correct `serviceId`, and wire tool OAuth metadata to that same service. Tokens and trusted
+API origins are hidden execution inputs; the model receives a credential ID, never a secret.
+Use `credentialKind: 'service-account'` when only service accounts are supported, including in
+tool OAuth metadata. Use `credentialKind: 'any'` on the picker when both browser OAuth and saved
+service accounts are supported; omitting it defaults the connect action to browser OAuth. Per-connection scope
+choices belong in the descriptor and encrypted credential, not an all-permissions block
+`requiredScopes` array that would reject read-only connections.
+
+When a documented list endpoint makes a resource ID discoverable, pair the saved credential
+with a dynamic resource selector using the `add-selector` and `validate-selector` skills:
+
+- Declare the credential subblock and any parent resource in `dependsOn`, and give the resource
+  selector and its manual advanced input the same canonical parameter.
+- Register browser-safe selector metadata and a server attachment through the shared selector
+  framework. Resolve the credential with the expected provider binding and use a fixed or
+  credential-bound destination; selectors and execution must use the same auth/region policy.
+- Exercise switching credentials, parent resources, pagination, expired tokens, denied access,
+  and the advanced environment-reference path. Check that stale choices cannot survive a change
+  of account. Do not fetch provider data or mint tokens in the browser.
+- Keep a manual ID path when the provider cannot enumerate a resource. Do not invent an endpoint
+  solely to provide a dropdown.
+
+For an existing integration, inspect persisted workflow serialization as well as the visible
+form before removing old auth fields. Establish whether existing users need a migration or
+compatibility path; do not add permanent legacy branches speculatively when removal is authorized.
+When compatibility is needed, prove that old values survive serialization and execution; hiding
+a field is not proof. If the user authorizes a production usage check, query only the aggregate usage/auth-shape evidence
+needed and keep identities, secrets, and local evidence out of commits and PRs.
+
 ### Hard Rule: No Guessed Response Schemas
 
 If the official docs do not clearly show the response JSON shape for an endpoint, you MUST stop and tell the user exactly which outputs are unknown.
@@ -274,18 +342,28 @@ export const TRIGGER_REGISTRY: TriggerRegistry = {
 
 ## Step 7: Configure Deployment Availability
 
-Do this for every visible OAuth integration. API-key and unauthenticated integrations do not need
-an OAuth client capability.
+Do this for every integration that uses the shared credential picker. Only a connection that
+depends on deployment-wide OAuth client fields needs an OAuth client capability; a customer-owned
+service account must remain available without those fields.
 
 The block's `oauth-input.serviceId` is the canonical link between the generated integration catalog,
 the OAuth service configuration, deployment availability, and the setup CLI.
 
-1. Ensure the block has exactly one distinct OAuth `serviceId` and that it matches the canonical
-   service entry in `apps/sim/lib/oauth/oauth.ts`.
-2. Confirm `resolveOAuthClientCapabilityId(serviceId)` resolves to the intended provider entry in
+1. Set `authMode: AuthMode.OAuth` for integrations using browser OAuth or customer-owned OAuth
+   client credentials. Token-only service accounts can retain `AuthMode.ApiKey` with the shared
+   picker, as Coda does; `oauth-input` alone does not determine the authentication protocol.
+   Register a new token-only service ID and block type in `tokenCredentialIntegrationTypes` in
+   `packages/deployment-config/src/integration-availability.ts` so availability and integration
+   policy recognize the saved credential path.
+   For OAuth integrations, this value lets the catalog discover the connection flow instead of
+   routing "Add to Sim" to chat. Ensure the block has exactly one distinct OAuth `serviceId`
+   matching the canonical service in `apps/sim/lib/oauth/oauth.ts`. The canonical service's
+   `authType` selects browser OAuth or the service-account modal. Verify the resulting catalog
+   and block connection actions for the chosen authentication method.
+2. For browser OAuth, confirm `resolveOAuthClientCapabilityId(serviceId)` resolves to the intended provider entry in
    `OAUTH_CLIENT_CAPABILITIES` in `packages/deployment-config/src/env-capabilities.ts`. Google and
    Microsoft service IDs deliberately share provider-level capabilities.
-3. For a new OAuth provider, add the required client fields to `OAUTH_CLIENT_CAPABILITIES`, add
+3. For a new browser OAuth provider, add the required client fields to `OAUTH_CLIENT_CAPABILITIES`, add
    every referenced field to the env schema in `apps/sim/lib/core/config/env.ts`, and add the
    matching `text` or `secret` entries to `OAUTH_CLIENT_SETUP_FIELDS` in
    `packages/sim-setup/src/capability-config.ts`. Do not create integration-specific setup logic or
@@ -298,9 +376,13 @@ the OAuth service configuration, deployment availability, and the setup CLI.
    - no `deploymentRequirement` when the service-account path works independently of OAuth client fields;
    - `'oauth-client'` when it requires the same deployment OAuth client fields;
    - `'preview-gated'` when availability is controlled by the service-account preview block.
+   For a service-account-only default, set the canonical service's `authType: 'service_account'`
+   and `serviceAccountProviderId`. Verify both block availability and the connect modal with no
+   deployment OAuth credentials configured. An existing browser OAuth path may remain for legacy
+   credentials without becoming a prerequisite for the new path.
 
-Never add a permissive fallback for missing capability metadata. A visible OAuth integration without
-a resolvable capability must fail validation.
+Never add a permissive fallback for missing capability metadata. A browser OAuth connection without
+a resolvable capability must fail validation; an independent service account uses its own metadata.
 
 ## Step 8: Generate and Validate the Catalog
 
@@ -389,7 +471,8 @@ If creating V2 versions (API-aligned outputs):
 - [ ] Set `integrationType` to the correct `IntegrationType` enum value
 - [ ] `{Service}BlockMeta.tags` lists every applicable `IntegrationTag` (tags live on the meta, not the block)
 - [ ] Defined operation dropdown with all operations
-- [ ] Added credential field with `requiredScopes: getScopesForService('{service}')`
+- [ ] Added the saved-credential picker with the supported `credentialKind`; browser OAuth scopes
+      use `getScopesForService('{service}')`, while variable service-account permissions stay on the credential
 - [ ] Added conditional fields per operation
 - [ ] Every `short-input`, `long-input`, `code`, and selector subBlock has a `placeholder`
 - [ ] Set up dependsOn for cascading selectors
@@ -407,15 +490,25 @@ If creating V2 versions (API-aligned outputs):
 - [ ] `canvasPresentation.sentences` covers every operation; `bun run apps/sim/scripts/check-canvas-sentences.ts --block={service}` passes
 - [ ] `{Service}BlockMeta` also sets `url` (verified external homepage) and `skills` (grounded in `tools.access`, sourced from real use cases) — see add-block → BlockMeta
 
-### OAuth Scopes (if OAuth service)
+### Authentication and saved credentials
+- [ ] Compared documented authorization code, client credentials, token, and key-based methods
+- [ ] Chosen app ownership and approval requirements match the intended user
+- [ ] Saved credential picker, tools, and resource selectors share the same provider/region binding
+- [ ] Connect verification, expiry, concurrent workers, secret rotation, and scope changes are sound
+- [ ] Existing usage and the migration/removal decision are established; any required compatibility is verified through serialization and execution
+- [ ] New connection and reconnect flows verified in the running UI
+
+### Browser OAuth Scopes (if authorization-code flow is supported)
 - [ ] Defined scopes in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS`
 - [ ] Added scope descriptions in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
 - [ ] Used `getCanonicalScopesForProvider()` in `lib/auth/connectors/providers.ts` (never hardcode)
-- [ ] Used `getScopesForService()` in block `requiredScopes` (never hardcode)
+- [ ] Used `getScopesForService()` for the browser OAuth permissions the block needs (never hardcode)
+- [ ] A picker that also accepts service accounts does not require broader scopes than every supported
+      connection needs; per-connection service-account permissions are validated by the descriptor/minter
 
-### Deployment Availability (if OAuth service)
+### Deployment Availability (if using the saved-credential picker)
 - [ ] Block declares exactly one distinct `oauth-input.serviceId`
-- [ ] `resolveOAuthClientCapabilityId(serviceId)` resolves to the intended `OAUTH_CLIENT_CAPABILITIES` entry
+- [ ] Browser OAuth resolves to the intended `OAUTH_CLIENT_CAPABILITIES` entry; independent service accounts work without deployment OAuth fields
 - [ ] Every new OAuth capability field exists in `apps/sim/lib/core/config/env.ts`
 - [ ] Runtime OAuth fields live in `OAUTH_CLIENT_CAPABILITIES`; matching CLI input modes live in the exhaustively checked `OAUTH_CLIENT_SETUP_FIELDS`
 - [ ] If `serviceAccountProviderId` is configured, `SERVICE_ACCOUNT_METADATA_BY_OAUTH_SERVICE_ID` has the matching projection and deployment requirement

.agents/skills/add-settings-page/SKILL.md

@@ -66,8 +66,8 @@ Each grep lists candidates; review every match against the expected ones named b
    - Editable pages: confirm Save/Discard go through `saveDiscardActions()` and
      dirty is wired via `useSettingsUnsavedGuard` (called before early-return
      gates) — flag any hand-rolled Save button, `beforeunload`, or unsaved modal.
-     `git grep -n "beforeunload" -- 'apps/sim/**/settings/**' 'apps/sim/ee/'`
-     should only hit the centralized `use-settings-before-unload.ts`.
+     `git grep -n "beforeunload" -- 'apps/sim/**/settings/**' 'apps/sim/ee/' 'apps/sim/components/settings/' ':(exclude,glob)**/*.test.*'`
+     should only hit the centralized `use-settings-browser-navigation.ts`.
 5. Fix each finding with the smallest structural change that satisfies the checklist;
    do not touch handlers, state, queries, or gate returns. A pixel-size fix swaps
    only the size class for its exact-pixel token (`text-[12px]` → `text-caption`).

.agents/skills/ship/SKILL.md

@@ -47,7 +47,7 @@ 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 and Test` 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 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.
 
   **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 — `agent-stream-docs:generate` (derives from the provider model registry), `docs-manifest:generate` (derives from docs page paths), and `skills:sync` (derives from `.agents/skills/**`). They write disjoint outputs (`apps/docs/…/agent.mdx`, `apps/sim/lib/mothership/generated/docs-manifest.ts`, and `.claude/skills` links), so they parallelize safely, and each is idempotent (a no-op when already in sync):
   ```bash
@@ -66,7 +66,7 @@ When the user runs `/ship`:
 
   **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 `integration-catalog:check` 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.
 
-  **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/test-build.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:
+  **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
   # autofix formatting first (mutating; not parallel-safe with the audits). Gate its exit too —
   # a non-zero lint (unfixable errors) must abort before the audits run, not be ignored.
@@ -77,6 +77,9 @@ When the user runs `/ship`:
   }
   # Runs every audit CI runs, concurrently, and replays the output of any that fail.
   # The audit list is derived in scripts/run-audits.ts — do not hand-list audits here.
+  # Install CI's pinned actionlint version for the host OS/architecture and verify its
+  # artifact against the official release checksums in a local mktemp directory.
+  # Preserve CI's -shellcheck= -pyflakes= flags; lint all workflows and abort ship if it fails.
   bun run check:audits || { echo "❌ audit(s) failed — do not ship"; exit 1; }
   bun run type-check || { echo "❌ type-check failed — do not ship"; exit 1; }
   # CI's "Verify docs manifest is in sync" step is not a `check:*` script, so the runner above