merge: sync organization search with staging

Preserve organization invitation and navigation behavior alongside staging OAuth and provenance changes. Enforce the OAuth app capability for organization-scoped reads, with regression coverage.

Keep staging migration history intact, regenerate snapshots 0326-0328, and retain the reviewed search, approval, and connected-account SQL unchanged. Update migration fixtures and documentation references.

Author: waleedlatif1

.agents/skills/v2-api-conventions/SKILL.md

@@ -149,6 +149,16 @@ Order matters because each layer is checked against the one before it.
 3. **Route** with `defineV2JsonRoute`, declaring `contract`, `auth: v2ApiKeyAuth`, `operation`, `rateLimit`, `errorPolicy`, `mapInput`, `useCase`, `present`. Auth and rate limiting run before parsing.
 4. **OpenAPI description** in `lib/api/contracts/v2/openapi/<domain>.ts`, then `bun run generate:openapi`. A description that claims behaviour the route does not have is the same class of bug as a wrong schema.
 
+### Public descriptions
+
+Use the [API description conventions](../../../apps/sim/lib/api/contracts/v2/openapi/README.md) when writing or auditing endpoint and field descriptions. Keep a short action-and-resource summary; use the description for behavior that changes the caller's choice, input, interpretation, or next action. Ordinary operations usually need one to three sentences, with no mandatory minimum.
+
+Keep archive versus permanent-delete behavior, replacement versus partial-update semantics, partial success, retry safety, redaction, and asynchronous completion explicit. Verify these claims against the implementation. Describe observable behavior without exposing storage formats, locking mechanisms, internal identifiers, deployment architecture, or implementation history unless that detail changes how the caller must use the API.
+
+Reuse wording across resource families when behavior matches: “Omitted fields remain unchanged,” “Archive,” and “permanently delete.” Prefer “during the request” or “asynchronously” to “settled inline.” Preserve real semantic differences; do not standardize them away.
+
+Put field-specific rules in the source schema and reuse shared authentication and pagination wording. Shared schema descriptions also feed CLI help, so refer to related operation names rather than HTTP paths. Regenerate OpenAPI, CLI metadata, and CLI docs after changing their source descriptions; never hand-edit generated output.
+
 ## Rule 6 — a transient failure says when to come back
 
 A response the caller is *expected* to retry must say how long to wait. Two statuses qualify, and both are wired:
@@ -186,11 +196,14 @@ Audited against the primary specs and against Stripe, GitHub, and Google's AIPs.
 
 ## Idempotency: at-most-once, not replay
 
-`POST /workflows/{id}/execute` accepts `X-Run-Id`, a caller-supplied run identifier claimed through the `idempotency_key` table (`execution-id-claim.ts`). It is a **uniqueness claim, not an idempotency key**, and the distinction is deliberate and already published in the operation description:
+`POST /workflows/{id}/execute` accepts `X-Run-Id` from API-key and OAuth callers; anonymous requests ignore it. It is a **uniqueness claim, not an idempotency key**:
+
+- An available ID is claimed before execution starts.
+- An already claimed ID returns **409** with `error.details.code: "RUN_ID_CONFLICT"`, the run id in `error.details.runId`, and an `X-Run-Id` response header. It never replays the earlier run's result. Get Workflow Run can retrieve an existing run, but a claim does not guarantee a retrievable run.
+- IDs of runs that started remain reserved after their execution logs are deleted.
+- An ambiguous enqueue can retain the claim indefinitely without creating a retrievable run. A **409** followed by **404** is an unresolved outcome, not proof that execution never started or that the ID will become reusable.
 
-- First use wins and runs.
-- Any reuse returns **409** with `error.details.code: "RUN_ID_CONFLICT"`, the run id in `error.details.runId`, and an `X-Run-Id` response header. It never replays the earlier run's result — the client recovers it by polling the runs resource.
-- Claims are durable tombstones, so deleting execution logs cannot make an id reusable.
+For an uncertain execution outcome, reuse the same run ID if retrying and check Get Workflow Run. Do not promise polling will eventually find a run. If the outcome cannot be verified, do not automatically restart with a fresh ID or an omitted header: either can start another execution. Failures before a run starts can release the claim, so phrase the conflict rule as an ID that is already claimed.
 
 That makes the money path safe against double-execution **for callers that opt in**. What it is not: a Stripe-style `Idempotency-Key` that stores and replays the original status and body. Building that means a request fingerprint, a retention window, an in-flight-vs-completed distinction (the expired IETF draft would have these be 422 and 409 respectively), and somewhere to put a large synchronous execution body. It is a designed piece of work, not an increment — do not half-build it by aliasing the header name, which would invite clients written against Stripe semantics to treat our 409 as a hard failure.
 

.github/workflows/test-build.yml

@@ -9,7 +9,7 @@ permissions:
 
 jobs:
   oauth-postgres:
-    name: OAuth PostgreSQL (${{ matrix.provision }})
+    name: PostgreSQL integration (${{ matrix.provision }})
     runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-8vcpu-ubuntu-2404' || 'ubuntu-latest' }}
     timeout-minutes: 15
     strategy:
@@ -22,19 +22,18 @@ jobs:
         env:
           POSTGRES_USER: postgres
           POSTGRES_PASSWORD: postgres
-          POSTGRES_DB: sim_oauth
+          POSTGRES_DB: sim_auth_scim
         ports:
           - 5432:5432
         options: >-
-          --health-cmd "pg_isready -U postgres -d sim_oauth"
+          --health-cmd "pg_isready -U postgres -d sim_auth_scim"
           --health-interval 5s
           --health-timeout 5s
           --health-retries 10
     env:
-      DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/sim_oauth
-      OAUTH_TOKEN_FAMILY_TEST_DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/sim_oauth
+      DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/sim_auth_scim
+      OAUTH_TOKEN_FAMILY_TEST_DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/sim_auth_scim
       BETTER_AUTH_SECRET: oauth-postgres-ci-secret-at-least-32-characters
-      OAUTH_PROVIDER_ENABLED: 'true'
       NEXT_PUBLIC_APP_URL: https://test.sim.ai
       ENCRYPTION_KEY: '0000000000000000000000000000000000000000000000000000000000000000'
 
@@ -73,14 +72,86 @@ jobs:
         working-directory: packages/db
         run: bun run db:migrate
 
-      - name: Verify provider issuance and token lifecycle in PostgreSQL
+      - name: Verify OAuth lifecycle and SCIM membership guards in PostgreSQL
         working-directory: apps/sim
         run: >-
           bunx vitest run
           lib/auth/oauth-token-family.postgres.test.ts
           lib/auth/oauth-provider-lifecycle.postgres.test.ts
           app/api/auth/oauth2/token/route.postgres.test.ts
           lib/auth/sim-auth-adapter.test.ts
+          ee/scim/lib/managed-membership.postgres.test.ts
+          lib/auth/sso/application/admit-sso-user.postgres.test.ts
+
+      - name: Verify SCIM and administration over real HTTP
+        working-directory: apps/sim
+        env:
+          NEXT_PUBLIC_APP_URL: http://127.0.0.1:3017
+          BETTER_AUTH_URL: http://127.0.0.1:3017
+          NEXT_PUBLIC_FORCE_HOSTED: 'true'
+          BILLING_ENABLED: 'true'
+          NEXT_PUBLIC_BILLING_ENABLED: 'true'
+          ENTERPRISE_ENABLED: 'true'
+          NEXT_PUBLIC_ENTERPRISE_ENABLED: 'true'
+          SCIM_ENABLED: 'true'
+          NEXT_PUBLIC_SCIM_ENABLED: 'true'
+          SSO_ENABLED: 'true'
+          NEXT_PUBLIC_SSO_ENABLED: 'true'
+          ORGANIZATIONS_ENABLED: 'true'
+          NEXT_PUBLIC_ORGANIZATIONS_ENABLED: 'true'
+          INTERNAL_API_SECRET: scim-http-ci-local-secret-at-least-32-characters
+          DB_TX_TRIPWIRE: throw
+          DISABLE_TELEMETRY: 'true'
+          NEXT_TELEMETRY_DISABLED: '1'
+          NEXT_PUBLIC_CHAT_DISABLED: 'true'
+        run: |
+          server_log="$RUNNER_TEMP/scim-next.log"
+          node ../../node_modules/next/dist/bin/next dev --hostname 127.0.0.1 --port 3017 > "$server_log" 2>&1 &
+          server_pid=$!
+          finish() {
+            kill "$server_pid" 2>/dev/null || true
+            wait "$server_pid" 2>/dev/null || true
+            awk '/^ (GET|POST|PUT|PATCH|DELETE|HEAD) \/api\// { print }' "$server_log" > "$RUNNER_TEMP/scim-http-status.log"
+          }
+          trap finish EXIT
+          deadline=$((SECONDS + 120))
+          until curl --fail --silent --max-time 3 http://127.0.0.1:3017/api/health > /dev/null; do
+            if ! kill -0 "$server_pid" 2>/dev/null; then
+              echo 'Local SCIM app exited during startup.'
+              exit 1
+            fi
+            if [ "$SECONDS" -ge "$deadline" ]; then
+              echo 'Local SCIM app did not become ready within 120 seconds.'
+              exit 1
+            fi
+            sleep 2
+          done
+          SCIM_E2E_BASE_URL="$NEXT_PUBLIC_APP_URL" \
+          SCIM_E2E_DATABASE_URL="$DATABASE_URL" \
+          SCIM_E2E_AUTH_SECRET="$BETTER_AUTH_SECRET" \
+          SCIM_E2E_REPORT_PATH="$RUNNER_TEMP/scim-e2e-report.json" \
+            bun run test:scim:e2e
+
+      - name: Upload SCIM failure report and HTTP status log
+        if: failure()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: scim-failure-${{ matrix.provision }}
+          path: |
+            ${{ runner.temp }}/scim-e2e-report.json
+            ${{ runner.temp }}/scim-http-status.log
+          if-no-files-found: ignore
+          retention-days: 7
+
+      - name: Verify durable provenance bindings and concurrent memory writes
+        working-directory: apps/sim
+        env:
+          TABLE_PROVENANCE_TEST_DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/sim_auth_scim
+          MEMORY_PROVENANCE_TEST_DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/sim_auth_scim
+        run: >-
+          bunx vitest run
+          lib/table/rows/secret-provenance.postgres.test.ts
+          lib/memory/message-provenance.postgres.test.ts
 
   test-build:
     name: Lint and Test

apps/docs/content/docs/cli/authentication.mdx

@@ -5,17 +5,35 @@ description: Sign in from the terminal, authenticate CI with an API key, and kee
 
 import { Callout } from 'fumadocs-ui/components/callout'
 
-`sim login` signs you in through your browser and stores a short-lived login
-that renews itself and can be revoked at any time. In CI you supply an API key
-through the environment instead.
+`sim login` signs you in through your browser. It prefers OAuth, which stores a
+short-lived login that renews itself, and selects API-key pairing for remote
+terminals or servers without OAuth support. In CI you supply an existing API
+key through the environment instead.
 
 ## Signing in
 
 ```bash
 sim login
 ```
 
-The CLI opens your browser on Sim's sign-in page, then on a consent page that
+Choose a method explicitly when the credential type matters:
+
+```bash
+sim login --method oauth
+sim login --method api-key
+```
+
+`--method oauth` requires a server with OAuth support and authentication enabled;
+it never falls back to an API key. Explicit OAuth selection also overrides
+SSH/headless detection; your browser still needs to reach the CLI's
+local callback. `--method api-key` uses pairing-code approval to create a new
+permanent API key. To supply an existing key, set `SIM_API_KEY` instead.
+
+API-key pairing requires a server that supports `platform` API keys. Upgrade
+older deployments that only issue `copilot` keys before starting login; those
+keys cannot authenticate the platform CLI.
+
+OAuth login opens your browser on Sim's sign-in page, then on a consent page that
 names the Sim CLI and what it will be able to do. Approve, and the browser hands
 control back to the terminal:
 
@@ -46,21 +64,21 @@ your login.
 
 | Option | What it does |
 | --- | --- |
-| `--no-browser` | Print the URL instead of opening a browser |
-| `--browserless` | Use the pairing-code handoff instead (see below) |
+| `--method <method>` | `oauth` requires OAuth login; `api-key` creates a permanent key through pairing. Auto-selects when omitted |
+| `--no-browser` | Print the approval URL without opening it; works with either method |
 | `--read-only` | Ask only for permission to read, never to change anything |
 | `--callback-port <port>` | Pin the loopback callback port, primarily for an SSH session that forwards the same fixed port |
-| `--scope <scope>` | Key space for the pairing-code handoff. Only `copilot` changes anything, and it forces that flow |
 | `-y, --yes` | Overwrite an existing API-key profile without prompting |
 
 ### Over SSH or in a container
 
-The browser login needs your browser to reach a listener on the machine running
+OAuth login needs your browser to reach a listener on the machine running
 `sim`. When it cannot — an SSH session, a dev container, a remote box — use the
-pairing-code handoff, which the CLI selects automatically in an SSH session:
+API-key pairing flow. The CLI selects it automatically in an SSH session when
+no method or callback port is specified:
 
 ```bash
-sim login --browserless
+sim login --method api-key --no-browser
 ```
 
 The terminal prints a pairing code and a URL you can open on any device:
@@ -85,16 +103,18 @@ approving. That check is what binds the approval to your terminal.
 
 The handoff issues a permanent personal API key rather than a renewing login,
 so revoke it under **Settings → API keys** when you are done with that machine.
-It is also the path for a deployment that predates OAuth sign-in, or one with
-the provider switched off; the CLI detects that and falls back on its own.
+It also works when OAuth is unavailable or switched off, provided the server
+supports platform API-key pairing. When `--method` is omitted, the CLI checks
+OAuth availability and selects pairing if unavailable; that discovery does not
+verify pairing compatibility. An explicit `--method oauth` fails in that case.
 
-`--read-only` and `--callback-port` belong to the browser login and have no
+`--read-only` and `--callback-port` belong to OAuth login and have no
 meaning here, so combining either with the handoff stops the login rather than
 storing a credential you did not ask for. If your SSH session forwards a port
-from the remote loopback interface to the browser's machine, pass that same
-`--callback-port <port>` on its own. An ordinary container port publication
+from the remote loopback interface to the browser's machine, use
+`--method oauth --callback-port <port>` with that port. An ordinary container port publication
 cannot reach a listener bound to the container's own loopback interface; use
-`--browserless` there.
+`--method api-key` there.
 
 ### Picking a workspace
 
@@ -160,7 +180,7 @@ authentication profile entirely is refused until its workspace profiles are
 removed, so it cannot leave dangling references.
 
 <Callout type="warn">
-For a login created with `--browserless`, `sim logout` removes the API key from
+For a login created with `--method api-key`, `sim logout` removes the API key from
 disk but does **not** revoke it. Revoke keys under **Settings → API keys**.
 </Callout>
 
@@ -237,13 +257,11 @@ Save it to avoid repeating the flag:
 sim configure --set-endpoint http://localhost:3000 --profile local
 ```
 
-A deployment offers OAuth sign-in when its global `oauth-provider` feature flag
-is enabled. With AppConfig, enable it in the existing `feature-flags` document
-using `"oauth-provider": { "enabled": true }`. When AppConfig is disabled or no
-AppConfig document has been loaded, `OAUTH_PROVIDER_ENABLED=true` supplies the fallback.
-With the provider off, the CLI uses the pairing-code handoff; `DISABLE_AUTH=true`
-always forces OAuth off. Operators must apply the database migration and drain
-older app instances before enabling it. See [Sign in with Sim](/platform/self-hosting/authentication#sign-in-with-sim).
+OAuth sign-in is available by default when server authentication is enabled.
+`DISABLE_AUTH=true` disables OAuth. Older servers without OAuth support use the
+pairing-code handoff. Keep the database schema current and drain app instances
+that predate the OAuth token-family lifecycle before accepting OAuth traffic.
+See [Sign in with Sim](/platform/self-hosting/authentication#sign-in-with-sim).
 
 ## Where the login is stored
 
@@ -279,5 +297,5 @@ a copied token from surviving an ambiguous refresh.
 ## Organization audit logs
 
 `sim audit-logs` requires a **personal** credential — an OAuth login, or the
-personal API key `sim login --browserless` issues. A workspace-scoped key cannot
+personal API key `sim login --method api-key` issues. A workspace-scoped key cannot
 read organization-level audit logs.

apps/docs/content/docs/cli/blocks.mdx

@@ -38,7 +38,7 @@ sim blocks list [options]
 | `--search <value>` | No | Case-insensitive substring match against the block id, name, and description. |
 | `--category <value>` | No | Restrict to one toolbar category. Accepted values: `blocks`, `tools`, `triggers`. |
 | `--capability <value>` | No | Restrict to blocks that can start a workflow — the `triggers` category, blocks declaring `triggerAllowed`, and blocks with trigger-mode fields. Accepted values: `trigger`. |
-| `--source <value>` | No | Restrict to shipped blocks or to this workspace’s deployed custom blocks. Accepted values: `builtin`, `custom`. |
+| `--source <value>` | No | Restrict to built-in blocks or this workspace's deployed custom blocks. Accepted values: `builtin`, `custom`. |
 | `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `id`, `name`, `category`. |
 | `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |

apps/docs/content/docs/cli/commands.mdx

@@ -64,9 +64,8 @@ sim login [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--scope <scope>` | No | Key space for the pairing-code handoff; only "copilot" changes anything, and it forces that flow. Defaults to `platform`. |
-| `--no-browser` | No | Print the URL instead of opening a browser. |
-| `--browserless` | No | Use the pairing-code handoff for a terminal whose browser cannot reach it (SSH, containers). |
+| `--method <method>` | No | Credential to obtain: oauth requires OAuth support; api-key creates a permanent key through pairing (auto-selects when omitted). Accepted values: `oauth`, `api-key`. |
+| `--no-browser` | No | Print the approval URL without opening it (either login method). |
 | `--read-only` | No | Ask only for permission to read, never to change anything. |
 | `--callback-port <port>` | No | Pin the local port the browser returns to. |
 | `-y, --yes` | No | Overwrite an existing API-key profile without prompting. |

apps/docs/content/docs/cli/files.mdx

@@ -286,7 +286,7 @@ sim files list [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
-| `--recursive` | No | Whether the folder filter includes files in subfolders. Defaults to true when a search is set, false otherwise, so listing a folder shows that folder while searching one looks through everything in it. Ignored when no folder filter is set, which already spans the workspace. |
+| `--recursive` | No | Include subfolders in the folder filter. Defaults to true when searching and false otherwise. Ignored without a folder filter. |
 | `--no-recursive` | No | Send --recursive as false. |
 | `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live files, `archived` for files a delete soft-deleted. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
 | `--search <value>` | No | Case-insensitive substring match against the file name. |