Merge branch 'dev' into codex/tanstack-start-integration

Author: mantrakp04

.claude/CLAUDE-KNOWLEDGE.md

@@ -217,6 +217,9 @@ A: Check the error location:
 - Callback endpoint (400 error) - Validation failed during callback
 - Token endpoint (400 error) - Validation failed during token exchange
 
+### Q: How should connected-account OAuth access-token refresh errors be classified?
+A: In `apps/backend/src/oauth/providers/base.tsx`, invalid/revoked refresh-token provider errors such as `invalid_grant` return `Result.error({ type: "invalid-refresh-token", ... })` so `access-token-helpers.tsx` can invalidate that stored refresh token and try another. Transient provider/network failures such as openid-client `RPError: outgoing request timed out after 3500ms` return `Result.error({ type: "temporarily-unavailable", cause })`; the connected-account helper converts that to `OAuthProviderTemporarilyUnavailable` without invalidating the refresh token. Expected refresh outcomes should be represented in the provider return type instead of thrown as known/status errors. Refresh requests use a 6s openid-client HTTP timeout and retry transient failures once. If a retry sees `invalid_grant` after an ambiguous transient failure, keep treating it as temporarily unavailable rather than invalidating the refresh token, because the first request may have reached the provider and rotated the token before our client timed out. Sentry should capture non-revocation refresh issues (temporary provider failure, invalid client, unexpected) with provider id/class, attempts, retry count, ambiguity state, final cause, and all provider errors seen during attempts; normal revoked/expired refresh tokens should not be reported.
+
 ## Git and Development Workflow
 
 ### Q: How should you format git commit messages in this project?
@@ -394,3 +397,12 @@ A: The environment override endpoint validates the new environment override agai
 
 ## Q: Why can `pnpm run dev` fail with `ERR_MODULE_NOT_FOUND` for `@stackframe/stack/dist/esm/index.js` during OpenAPI docs generation?
 A: Root `dev` starts the OpenAPI docs watcher at the same time as package `dev` watchers. If a package `dev` script removes `dist` before `tsdown --watch` recreates it, the docs generator can import `apps/backend/src/stack.tsx` while `@stackframe/stack`'s ESM entrypoint is temporarily missing. Package watch scripts should update `dist` in place, and eager generators should wait for package imports to resolve before running.
+
+## Q: How do SDK source tests replace the compile-time client version sentinel?
+A: `packages/template/vitest.config.ts` installs a Vite transform plugin for Vitest that replaces `STACK_COMPILE_TIME_CLIENT_PACKAGE_VERSION_SENTINEL` with `js <package-name>@<version>` from the local package.json. Keep the plugin in `packages/template` so `pnpm pre`/`scripts/generate-sdks.ts` propagates it to `packages/js`, `packages/react`, and `packages/stack`; otherwise tests importing `common.ts` throw `Client version was not replaced` before test collection.
+
+## Q: How does the Mintlify apps sidebar filter stay in sync with theme changes?
+A: `docs-mintlify/apps-sidebar-filter.js` injects the Apps filter with inline styles, so the MutationObserver must reapply `applySidebarAppsFilterTheme` when an existing input is found. Theme detection should handle both `html.dark` and `data-theme="dark"` signals.
+
+## Q: How should `StackAssertionError` preserve an underlying thrown error?
+A: Pass the underlying error as the `cause` property in the second argument. The `StackAssertionError` constructor only forwards `cause` into `ErrorOptions`, so storing a caught error under an `error` property captures it as ordinary metadata instead of preserving the error cause chain.

.github/workflows/db-migration-backwards-compatibility.yaml

@@ -169,6 +169,16 @@ jobs:
           wait-for: 30s
           log-output-if: true
 
+      - name: Start stack-mcp in background
+        uses: JarvusInnovations/background-action@v1.0.7
+        with:
+          run: pnpm run start:mcp --log-order=stream &
+          wait-on: |
+            http://localhost:8144/health
+          tail: true
+          wait-for: 30s
+          log-output-if: true
+
       - name: Start stack-dashboard in background
         uses: JarvusInnovations/background-action@v1.0.7
         with:
@@ -366,6 +376,16 @@ jobs:
           wait-for: 30s
           log-output-if: true
 
+      - name: Start stack-mcp in background
+        uses: JarvusInnovations/background-action@v1.0.7
+        with:
+          run: pnpm run start:mcp --log-order=stream &
+          wait-on: |
+            http://localhost:8144/health
+          tail: true
+          wait-for: 30s
+          log-output-if: true
+
       - name: Start stack-dashboard in background
         uses: JarvusInnovations/background-action@v1.0.7
         with:

.github/workflows/e2e-api-tests-local-emulator.yaml

@@ -119,6 +119,15 @@ jobs:
           tail: true
           wait-for: 30s
           log-output-if: true
+      - name: Start stack-mcp in background
+        uses: JarvusInnovations/background-action@v1.0.7
+        with:
+          run: pnpm run start:mcp --log-order=stream &
+          wait-on: |
+            http://localhost:8144/health
+          tail: true
+          wait-for: 30s
+          log-output-if: true
 
       - name: Start stack-dashboard in background
         uses: JarvusInnovations/background-action@v1.0.7

.github/workflows/e2e-api-tests.yaml

@@ -125,6 +125,15 @@ jobs:
           tail: true
           wait-for: 30s
           log-output-if: true
+      - name: Start stack-mcp in background
+        uses: JarvusInnovations/background-action@v1.0.7
+        with:
+          run: pnpm run start:mcp --log-order=stream &
+          wait-on: |
+            http://localhost:8144/health
+          tail: true
+          wait-for: 30s
+          log-output-if: true
       - name: Start stack-dashboard in background
         uses: JarvusInnovations/background-action@v1.0.7
         with:

.github/workflows/e2e-custom-base-port-api-tests.yaml

@@ -118,6 +118,15 @@ jobs:
           tail: true
           wait-for: 30s
           log-output-if: true
+      - name: Start stack-mcp in background
+        uses: JarvusInnovations/background-action@v1.0.7
+        with:
+          run: pnpm run start:mcp --log-order=stream &
+          wait-on: |
+            http://localhost:6744/health
+          tail: true
+          wait-for: 30s
+          log-output-if: true
       - name: Start stack-dashboard in background
         uses: JarvusInnovations/background-action@v1.0.7
         with:

apps/backend/.env

@@ -34,6 +34,8 @@ STACK_SPOTIFY_CLIENT_SECRET=# client secret
 
 STACK_ALLOW_SHARED_OAUTH_ACCESS_TOKENS=# allow shared oauth provider to also use connected account access token, this should only be used for development and testing
 
+STACK_DISABLE_PLAN_LIMITS=# set to "true" to bypass enforcement of Stack Auth's own internal-tenancy plan limits (analytics_events, session_replays, emails_per_month, dashboard_admins seat cap, auth_users soft cap, analytics_timeout_seconds). Default unset/false preserves enforcement. Intended as a temporary cutover safety net while the plan-limits infrastructure rolls out — customer projects' own item APIs are unaffected by this flag.
+
 # Email
 # For local development, you can spin up a local SMTP server like inbucket
 STACK_EMAIL_HOST=# for local inbucket: 127.0.0.1

apps/backend/.env.development

@@ -43,6 +43,12 @@ STACK_SPOTIFY_CLIENT_SECRET=MOCK
 
 STACK_ALLOW_SHARED_OAUTH_ACCESS_TOKENS=true
 
+# Default to enforcing plan limits in local dev so behavior matches prod.
+# Flip to "true" to bypass every Stack-Auth-internal plan-limit enforcement
+# site (e.g. session_replays, analytics_events, emails_per_month). See
+# apps/backend/src/lib/plan-entitlements.ts:arePlanLimitsEnforced.
+STACK_DISABLE_PLAN_LIMITS=false
+
 STACK_DATABASE_CONNECTION_STRING=postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}28/stackframe
 STACK_DATABASE_REPLICA_CONNECTION_STRING=postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}34/stackframe
 STACK_DATABASE_REPLICATION_WAIT_STRATEGY=pg-stat-replication

apps/backend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stackframe/backend",
   "version": "2.8.88",
-  "repository": "https://github.com/stack-auth/stack-auth",
+  "repository": "https://github.com/hexclave/stack-auth",
   "private": true,
   "type": "module",
   "scripts": {
@@ -87,7 +87,6 @@
     "@stackframe/stack-shared": "workspace:*",
     "@upstash/qstash": "^2.8.2",
     "@vercel/functions": "^2.0.0",
-    "@vercel/mcp-adapter": "^1.0.0",
     "@vercel/otel": "^1.10.4",
     "@vercel/sandbox": "^1.2.0",
     "ai": "^6.0.0",

apps/backend/prisma/migrations/20260420000000_add_project_onboarding_state/tests/default-and-updates.ts

@@ -34,12 +34,12 @@ export const postMigration = async (sql: Sql, ctx: Awaited<ReturnType<typeof pre
   `;
 
   const updatedRows = await sql`
-    SELECT "onboardingState"
+    SELECT "onboardingState"::text AS "onboardingState"
     FROM "Project"
     WHERE "id" = ${ctx.projectId}
   `;
   expect(updatedRows).toHaveLength(1);
-  expect(updatedRows[0].onboardingState).toMatchInlineSnapshot(`
+  expect(JSON.parse(updatedRows[0].onboardingState)).toMatchInlineSnapshot(`
     {
       "selected_apps": [
         "authentication",