cc: gate on DB readiness + real healthchecks (start.sh has no set -e and wait-for-it passes mid-initdb)

- database: pg_isready healthcheck; calcom depends_on service_healthy
- calcom: healthcheck probes /auth/login with redirects (upstream wget --spider / fails on 307)

.changeset/tender-birds-think.md

@@ -0,0 +1,5 @@
+---
+"@calcom/atoms": patch
+---
+
+fix: unlocked fields not saved for managed event type

.claude/rules

@@ -0,0 +1 @@
+../agents/rules

.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}

.claude/skills

@@ -0,0 +1 @@
+../agents/skills

.cursor/rules

@@ -0,0 +1 @@
+../agents/rules

.cursor/skills

@@ -0,0 +1 @@
+../agents/skills

.easignore

@@ -1,57 +0,0 @@
-# EAS Build ignore file for monorepo
-# Only upload the companion app folder
-
-# ===========================================
-# IGNORE EVERYTHING AT ROOT LEVEL
-# ===========================================
-/*
-
-# ===========================================
-# EXCEPT THE COMPANION APP
-# ===========================================
-!companion
-
-# ===========================================
-# BUT IGNORE THESE INSIDE COMPANION
-# ===========================================
-
-# Native folders - EAS generates these during builds (~2.1 GB)
-companion/ios
-companion/android
-
-# Dependencies - EAS installs these during builds (~1.6 GB)
-companion/node_modules
-
-# Expo build cache
-companion/.expo
-companion/dist
-companion/web-build
-
-# Metro
-companion/.metro-health-check*
-
-# WXT Chrome Extension outputs (not needed for mobile builds)
-companion/.output
-companion/.wxt
-companion/dev
-
-# Kotlin cache
-companion/.kotlin
-
-# Build artifacts
-companion/*.jks
-companion/*.p8
-companion/*.p12
-companion/*.key
-companion/*.mobileprovision
-
-# Debug logs
-companion/*.log
-
-# TypeScript build info
-companion/*.tsbuildinfo
-
-# Environment files
-companion/.env
-companion/.env.*
-!companion/.env.example

.env.appStore.example

@@ -129,14 +129,6 @@ ZOHOCRM_CLIENT_ID=""
 ZOHOCRM_CLIENT_SECRET=""
 
 
-#   - REVERT
-# Used for the Pipedrive integration (via/ Revert (https://revert.dev))
-# @see https://github.com/calcom/cal.com/#obtaining-revert-api-keys
-REVERT_API_KEY=
-REVERT_PUBLIC_TOKEN=
-
-# NOTE: If you're self hosting Revert, update this URL to point to your own instance.
-REVERT_API_URL=https://api.revert.dev/
 # *********************************************************************************************************
 
 #   - Huddle01

.env.example

@@ -33,12 +33,6 @@ DATABASE_URL="postgresql://postgres:@localhost:5450/calendso"
 DATABASE_DIRECT_URL="postgresql://postgres:@localhost:5450/calendso"
 INSIGHTS_DATABASE_URL=
 
-# Uncomment to enable a dedicated connection pool for Prisma using Prisma Data Proxy
-# Cold boots will be faster and you'll be able to scale your DB independently of your app.
-# @see https://www.prisma.io/docs/data-platform/data-proxy/use-data-proxy
-# PRISMA_GENERATE_DATAPROXY=true
-PRISMA_GENERATE_DATAPROXY=
-
 # ***********************************************************************************************************
 
 # - SHARED **************************************************************************************************
@@ -47,7 +41,6 @@ PRISMA_GENERATE_DATAPROXY=
 NEXT_PUBLIC_WEBAPP_URL='http://localhost:3000'
 # Change to 'http://localhost:3001' if running the website simultaneously
 NEXT_PUBLIC_WEBSITE_URL='http://localhost:3000'
-NEXT_PUBLIC_CONSOLE_URL='http://localhost:3004'
 NEXT_PUBLIC_EMBED_LIB_URL='http://localhost:3000/embed/embed.js'
 
 # To enable SAML login, set both these variables
@@ -216,11 +209,13 @@ NEXT_PUBLIC_STRIPE_PREMIUM_PLAN_PRICE=
 NEXT_PUBLIC_IS_PREMIUM_NEW_PLAN=0
 NEXT_PUBLIC_STRIPE_PREMIUM_NEW_PLAN_PRICE=
 STRIPE_TEAM_MONTHLY_PRICE_ID=
+STRIPE_TEAM_ANNUAL_PRICE_ID=
 NEXT_PUBLIC_STRIPE_CREDITS_PRICE_ID=
 ORG_MONTHLY_CREDITS=
 STRIPE_TEAM_PRODUCT_ID=
 # It is a price ID in the product with id STRIPE_ORG_PRODUCT_ID
 STRIPE_ORG_MONTHLY_PRICE_ID=
+STRIPE_ORG_ANNUAL_PRICE_ID=
 STRIPE_ORG_PRODUCT_ID=
 # Used to pass trial days for orgs during the Stripe checkout session
 STRIPE_ORG_TRIAL_DAYS=
@@ -398,7 +393,10 @@ NEXT_PUBLIC_API_V2_URL="http://localhost:5555/api/v2"
 TASKER_ENABLE_WEBHOOKS=0
 TASKER_ENABLE_EMAILS=0
 
-# Ratelimiting via unkey
+# Ratelimiting via Unkey (https://unkey.com)
+# Optional: Only required if you want to enable rate limiting
+# Not needed for testing or self-hosting unless you specifically want rate limiting features
+# Sign up at https://unkey.com to get your Root key
 UNKEY_ROOT_KEY=
 
 # Used for Cal.ai Voice AI Agents
@@ -501,6 +499,10 @@ TZ=UTC
 SEED_PLATFORM_OAUTH_CLIENT_ID=
 SEED_PLATFORM_OAUTH_CLIENT_SECRET=
 
+# test oauth2 client for `packages/platform/examples/base` (optional)
+SEED_OAUTH2_CLIENT_ID=
+SEED_OAUTH2_CLIENT_SECRET_HASHED=
+
 # Trigger.dev
 ENABLE_ASYNC_TASKER="false" # set to "true" to enable
 TRIGGER_SECRET_KEY=

.github/CODEOWNERS

@@ -9,6 +9,7 @@
 /apps/web/lib/core/**/* @calcom/Foundation
 /apps/web/lib/booking.ts @calcom/Foundation
 /apps/web/lib/handleOrgRedirect.ts @calcom/Foundation
+/apps/web/modules/shell/Shell.tsx @calcom/Foundation
 /apps/web/proxy.ts @calcom/Foundation
 /deploy/**/* @calcom/Foundation
 /packages/app-store/applecalendar/**/* @calcom/Foundation
@@ -36,3 +37,11 @@
 /packages/trpc/server/routers/viewer/bookings/get.handler.ts @calcom/Foundation
 /packages/trpc/server/routers/viewer/slots/**/* @calcom/Foundation
 /packages/ui/**/* @calcom/Consumer @calcom/Foundation
+
+# Exclude test files from requiring foundation/consumer approval
+**/*.spec.*
+**/*.e2e.*
+**/*.e2e-spec.*
+**/*.test.*
+**/*.test-suite.*
+**/*.integration-test.*

.github/ISSUE_TEMPLATE/platform.md

@@ -1,58 +0,0 @@
----
-name: Cal.com/platform request
-about: Suggest a feature or bug report for cal.com/platform
-title: ""
-labels: ["platform", "🚨 needs approval"]
-assignees: ""
----
-
-### Is your proposal related to a problem?
-
-<!--
-  Provide a clear and concise description of what the problem is.
-  For example, "I'm always frustrated when..."
--->
-
-(Write your answer here.)
-
-### Describe the solution you'd like
-
-<!--
-  Provide a clear and concise description of what you want to happen.
--->
-
-(Describe your proposed solution here.)
-
-### Describe alternatives you've considered
-
-<!--
-  Let us know about other solutions you've tried or researched.
--->
-
-(Write your answer here.)
-
-### Additional context
-
-<!--
-  Is there anything else you can add about the proposal?
-  You might want to link to related issues here, if you haven't already.
--->
-
-(Write your answer here.)
-
-### Requirement/Document
-
-<!--
-  Is there any type of document that could support that feature?
--->
-
-(Share it here.)
-
----
-
-##### House rules
-
-- If this issue has a `🚨 needs approval` label, don't start coding yet. Wait until a core member approves feature request by removing this label, then you can start coding.
-  - For clarity: Non-core member issues automatically get the `🚨 needs approval` label.
-  - Your feature ideas are invaluable to us! However, they undergo review to ensure alignment with the product's direction.
-  - Follow Best Practices lined out in our [Contributor Docs](https://github.com/calcom/cal.com/blob/main/CONTRIBUTING.md)

.github/PULL_REQUEST_TEMPLATE.md

@@ -42,3 +42,4 @@ A visual demonstration is strongly recommended, for both the original and new ch
 - My code doesn't follow the style guidelines of this project
 - I haven't commented my code, particularly in hard-to-understand areas
 - I haven't checked if my changes generate no new warnings
+- My PR is too large (>500 lines or >10 files) and should be split into smaller PRs

.github/actions/devin-session/action.yml

@@ -0,0 +1,124 @@
+name: 'Devin Session Checker'
+description: 'Check for existing Devin sessions on a PR'
+
+inputs:
+  devin-api-key:
+    description: 'Devin API key'
+    required: true
+  github-token:
+    description: 'GitHub token for API calls'
+    required: true
+  pr-number:
+    description: 'PR number to check for existing sessions'
+    required: true
+
+outputs:
+  has-existing-session:
+    description: 'Whether an existing active session was found (true/false)'
+    value: ${{ steps.check-session.outputs.has-existing-session }}
+  session-id:
+    description: 'ID of the existing session (if found)'
+    value: ${{ steps.check-session.outputs.session-id }}
+  session-url:
+    description: 'URL of the existing session (if found)'
+    value: ${{ steps.check-session.outputs.session-url }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Check for existing Devin session
+      id: check-session
+      uses: actions/github-script@v7
+      env:
+        DEVIN_API_KEY: ${{ inputs.devin-api-key }}
+        PR_NUMBER: ${{ inputs.pr-number }}
+      with:
+        github-token: ${{ inputs.github-token }}
+        script: |
+          const { owner, repo } = context.repo;
+          const prNumber = parseInt(process.env.PR_NUMBER, 10);
+          const SESSION_URL_REGEX = /app\.devin\.ai\/sessions\/([a-f0-9-]+)/;
+          const ACTIVE_STATUSES = ['working', 'blocked', 'resumed'];
+
+          async function checkSessionStatus(sessionId) {
+            const response = await fetch(`https://api.devin.ai/v1/sessions/${sessionId}`, {
+              headers: {
+                'Authorization': `Bearer ${process.env.DEVIN_API_KEY}`,
+                'Content-Type': 'application/json'
+              }
+            });
+
+            if (!response.ok) {
+              console.log(`Failed to fetch session ${sessionId}: ${response.status}`);
+              return null;
+            }
+
+            return await response.json();
+          }
+
+          const { data: pr } = await github.rest.pulls.get({
+            owner,
+            repo,
+            pull_number: prNumber
+          });
+
+          const prBody = pr.body || '';
+          const prSessionMatch = prBody.match(SESSION_URL_REGEX);
+
+          if (prSessionMatch) {
+            const sessionId = prSessionMatch[1];
+            console.log(`PR was created by Devin session: ${sessionId}`);
+            const session = await checkSessionStatus(sessionId);
+            if (session) {
+              console.log(`PR creator session status: ${session.status_enum}`);
+              if (ACTIVE_STATUSES.includes(session.status_enum)) {
+                core.setOutput('has-existing-session', 'true');
+                core.setOutput('session-id', sessionId);
+                core.setOutput('session-url', `https://app.devin.ai/sessions/${sessionId}`);
+                return;
+              } else {
+                console.log(`PR creator session ${sessionId} is not active, will check comments`);
+              }
+            }
+          }
+
+          const devinSessionPatterns = [
+            'Devin AI is completing this stale PR',
+            'Devin AI is addressing Cubic AI',
+            'Devin AI is resolving merge conflicts'
+          ];
+
+          const comments = await github.rest.issues.listComments({
+            owner,
+            repo,
+            issue_number: prNumber
+          });
+
+          for (const comment of comments.data.reverse()) {
+            const hasDevinSession = devinSessionPatterns.some(pattern => comment.body?.includes(pattern));
+            if (hasDevinSession) {
+              const match = comment.body?.match(SESSION_URL_REGEX);
+              if (match) {
+                const sessionId = match[1];
+                console.log(`Found existing Devin session from comment: ${sessionId}`);
+
+                  const session = await checkSessionStatus(sessionId);
+                  if (session) {
+                    if (ACTIVE_STATUSES.includes(session.status_enum)) {
+                    console.log(`Session ${sessionId} is active (status: ${session.status_enum})`);
+                    core.setOutput('has-existing-session', 'true');
+                    core.setOutput('session-id', sessionId);
+                    core.setOutput('session-url', `https://app.devin.ai/sessions/${sessionId}`);
+                    return;
+                  } else {
+                    console.log(`Session ${sessionId} is not active (status: ${session.status_enum})`);
+                  }
+                }
+              }
+            }
+          }
+
+          console.log('No existing active Devin session found');
+          core.setOutput('has-existing-session', 'false');
+          core.setOutput('session-id', '');
+          core.setOutput('session-url', '');

.github/oasdiff-err-ignore.txt

@@ -7,4 +7,11 @@ GET /v2/bookings/{bookingUid} added 'subschema #3, subschema #6' to the 'data' r
 POST /v2/bookings/{bookingUid}/cancel added 'subschema #3, subschema #6' to the 'data' response property 'oneOf' list for the response status '200'
 POST /v2/bookings/{bookingUid}/confirm added 'subschema #3, subschema #6' to the 'data' response property 'oneOf' list for the response status '200'
 POST /v2/bookings/{bookingUid}/decline added 'subschema #3, subschema #6' to the 'data' response property 'oneOf' list for the response status '200'
-POST /v2/bookings/{bookingUid}/guests added 'subschema #3, subschema #6' to the 'data' response property 'oneOf' list for the response status '200'
+POST /v2/bookings/{bookingUid}/guests added 'subschema #3, subschema #6' to the 'data' response property 'oneOf' list for the response status '200'
+DELETE /v2/event-types/{eventTypeId}/webhooks/{webhookId} added the new path request parameter 'webhookId'
+GET /v2/event-types/{eventTypeId}/webhooks/{webhookId} added the new path request parameter 'webhookId'
+DELETE /v2/oauth-clients/{clientId}/webhooks/{webhookId} added the new path request parameter 'webhookId'
+GET /v2/oauth-clients/{clientId}/webhooks/{webhookId} added the new path request parameter 'webhookId'
+DELETE /v2/teams/{teamId}/event-types/{eventTypeId}/webhooks/{webhookId} added the new path request parameter 'webhookId'
+GET /v2/teams/{teamId}/event-types/{eventTypeId}/webhooks/{webhookId} added the new path request parameter 'webhookId'
+GET /v2/webhooks/{webhookId} added the new path request parameter 'webhookId'

.github/workflows/check-api-v2-breaking-changes.yml

@@ -39,6 +39,16 @@ jobs:
       - uses: ./.github/actions/cache-checkout
       - uses: ./.github/actions/yarn-install
 
+      - name: Build platform packages
+        run: |
+          yarn turbo run build \
+            --filter=@calcom/platform-constants \
+            --filter=@calcom/platform-enums \
+            --filter=@calcom/platform-utils \
+            --filter=@calcom/platform-types \
+            --filter=@calcom/platform-libraries \
+            --filter=@calcom/trpc
+
       - name: Generate Swagger
         working-directory: apps/api/v2
         run: |

.github/workflows/check-prisma-migrations.yml

@@ -0,0 +1,41 @@
+name: Check Prisma Migrations
+on:
+  workflow_call:
+
+env:
+  DATABASE_URL: ${{ secrets.CI_DATABASE_URL }}
+
+jobs:
+  check-prisma-migrations:
+    name: Check migrations match schema
+    runs-on: blacksmith-2vcpu-ubuntu-2404
+    services:
+      postgres:
+        image: postgres:13
+        credentials:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: calendso
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: .github
+      - uses: ./.github/actions/cache-checkout
+      - uses: ./.github/actions/yarn-install
+      - name: Check if migrations match schema
+        working-directory: packages/prisma
+        run: |
+          npx prisma migrate diff --exit-code \
+            --from-migrations ./migrations \
+            --to-schema-datamodel ./schema.prisma \
+            --shadow-database-url ${{ env.DATABASE_URL }}

.github/workflows/check-types.yml

@@ -2,7 +2,7 @@ name: Check types
 on:
   workflow_call:
 env:
-  NODE_OPTIONS: --max-old-space-size=4096
+  NODE_OPTIONS: --max-old-space-size=12288
   TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
   TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
 permissions:

.github/workflows/companion-build.yml

@@ -1,44 +0,0 @@
-name: Companion Builds
-
-on:
-  workflow_call:
-
-permissions:
-  contents: read
-
-env:
-  EXPO_PUBLIC_CAL_API_KEY: ${{ secrets.CI_EXPO_PUBLIC_CAL_API_KEY || vars.CI_EXPO_PUBLIC_CAL_API_KEY || vars.EXPO_PUBLIC_CAL_API_KEY }}
-
-jobs:
-  build:
-    name: Build Companion App & Extension
-    runs-on: blacksmith-4vcpu-ubuntu-2404
-    timeout-minutes: 30
-
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          sparse-checkout: .github
-      - uses: ./.github/actions/cache-checkout
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v1
-        with:
-          bun-version: 1.3.0
-          cache: true
-          cache-dependency-path: companion/bun.lock
-
-      - name: Install dependencies
-        working-directory: companion
-        run: bun install --frozen-lockfile
-
-      - name: Build Expo web app
-        working-directory: companion
-        env:
-          EXPO_NO_TELEMETRY: 1
-          CI: true
-        run: bunx expo export --platform web
-
-      - name: Build browser extension
-        working-directory: companion
-        run: bun run ext:build

.github/workflows/cubic-devin-review-trigger.yml

@@ -0,0 +1,32 @@
+name: Cubic AI Review Trigger
+
+on:
+  pull_request_review:
+    types: [submitted]
+
+# This workflow triggers on pull_request_review events (including from forks)
+# and saves the review context as an artifact. The main cubic-devin-review.yml
+# workflow then runs via workflow_run with full permissions and secrets access.
+
+jobs:
+  save-review-context:
+    name: Save Review Context
+    if: github.event.review.user.login == 'cubic-dev-ai[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Save review context to artifact
+        run: |
+          cat > review-context.json << 'EOF'
+          {
+            "pr_number": ${{ github.event.pull_request.number }},
+            "review_body": ${{ toJSON(github.event.review.body) }},
+            "repository": "${{ github.repository }}"
+          }
+          EOF
+
+      - name: Upload review context
+        uses: actions/upload-artifact@v4
+        with:
+          name: cubic-review-context
+          path: review-context.json
+          retention-days: 1

.github/workflows/cubic-devin-review.yml

@@ -1,33 +1,66 @@
-name: Cubic AI to Devin Review
+name: Cubic feedback addressed by Devin
 
 on:
-  pull_request_review:
-    types: [submitted]
+  workflow_run:
+    workflows: ["Cubic AI Review Trigger"]
+    types:
+      - completed
 
 permissions:
   contents: read
   pull-requests: write
+  actions: read
 
 jobs:
   trigger-devin:
     name: Trigger Devin to Address Cubic AI Review
-    # Only run if the review is from cubic-dev-ai bot and contains the AI prompt
-    if: github.event.review.user.login == 'cubic-dev-ai[bot]'
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
     runs-on: blacksmith-2vcpu-ubuntu-2404
     steps:
+      - name: Download review context artifact
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              run_id: context.payload.workflow_run.id,
+            });
+            
+            const matchArtifact = artifacts.data.artifacts.find(
+              artifact => artifact.name === 'cubic-review-context'
+            );
+            
+            if (!matchArtifact) {
+              core.setFailed('No cubic-review-context artifact found');
+              return;
+            }
+            
+            const download = await github.rest.actions.downloadArtifact({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              artifact_id: matchArtifact.id,
+              archive_format: 'zip',
+            });
+            
+            const fs = require('fs');
+            fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/context.zip`, Buffer.from(download.data));
+
+      - name: Unzip artifact
+        run: unzip context.zip
+
       - name: Extract AI prompt from Cubic review
         id: extract-prompt
         uses: actions/github-script@v7
         with:
           script: |
-            const reviewBody = context.payload.review.body || '';
+            const fs = require('fs');
+            const contextData = JSON.parse(fs.readFileSync('review-context.json', 'utf8'));
+            const reviewBody = contextData.review_body || '';
+            const prNumber = contextData.pr_number;
+            
+            core.setOutput('pr-number', prNumber);
             
-            // Look for the AI prompt section in Cubic's review
-            // Format: <details><summary>Prompt for AI agents (all issues)</summary>
-            //         ```text
-            //         ... prompt content ...
-            //         ```
-            //         </details>
             const promptMatch = reviewBody.match(/<details>\s*<summary>Prompt for AI agents[^<]*<\/summary>\s*```(?:text)?\s*([\s\S]*?)```\s*<\/details>/i);
             
             if (!promptMatch || !promptMatch[1]) {
@@ -40,115 +73,37 @@ jobs:
             const prompt = promptMatch[1].trim();
             console.log('Extracted prompt:', prompt);
             
-            // Save prompt to file to avoid shell escaping issues
-            const fs = require('fs');
             fs.writeFileSync('/tmp/cubic-prompt.txt', prompt);
             
             core.setOutput('has-prompt', 'true');
 
+      - name: Checkout repository
+        if: steps.extract-prompt.outputs.has-prompt == 'true'
+        uses: actions/checkout@v4
+
       - name: Check for existing Devin session
         if: steps.extract-prompt.outputs.has-prompt == 'true'
         id: check-session
-        uses: actions/github-script@v7
-        env:
-          DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}
+        uses: ./.github/actions/devin-session
         with:
-          script: |
-            async function checkSessionStatus(sessionId) {
-              const response = await fetch(`https://api.devin.ai/v1/sessions/${sessionId}`, {
-                headers: {
-                  'Authorization': `Bearer ${process.env.DEVIN_API_KEY}`,
-                  'Content-Type': 'application/json'
-                }
-              });
-              
-              if (!response.ok) {
-                console.log(`Failed to fetch session ${sessionId}: ${response.status}`);
-                return null;
-              }
-              
-              return await response.json();
-            }
-            
-            // If PR was created through Devin, always use that session
-            const prBody = context.payload.pull_request.body || '';
-            const prSessionMatch = prBody.match(/app\.devin\.ai\/sessions\/([a-f0-9-]+)/);
-            
-            if (prSessionMatch) {
-              const sessionId = prSessionMatch[1];
-              console.log(`PR was created by Devin session: ${sessionId}`);
-              
-              const session = await checkSessionStatus(sessionId);
-              if (session) {
-                console.log(`PR creator session status: ${session.status_enum}`);
-                core.exportVariable('EXISTING_SESSION_ID', sessionId);
-                core.exportVariable('SESSION_URL', `https://app.devin.ai/sessions/${sessionId}`);
-                core.setOutput('has-active-session', 'true');
-                return;
-              }
-            }
-            
-            // PR was not created through Devin - check for existing Devin session from PR comments
-            // Look for any Devin session comment (cubic review, conflict resolution, stale PR completion, etc.)
-            const devinSessionPatterns = [
-              'Devin AI is addressing Cubic AI',
-              'Devin AI is resolving merge conflicts',
-              'Devin AI is completing this stale PR'
-            ];
-            
-            const comments = await github.rest.issues.listComments({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: context.payload.pull_request.number
-            });
-            
-            let sessionId = null;
-            for (const comment of comments.data.reverse()) {
-              const hasDevinSession = devinSessionPatterns.some(pattern => comment.body.includes(pattern));
-              if (hasDevinSession) {
-                const match = comment.body.match(/app\.devin\.ai\/sessions\/([a-f0-9-]+)/);
-                if (match) {
-                  sessionId = match[1];
-                  console.log(`Found existing Devin session from comment: ${sessionId}`);
-                  break;
-                }
-              }
-            }
-            
-            if (!sessionId) {
-              console.log('No existing Devin session found in PR comments');
-              core.setOutput('has-active-session', 'false');
-              return;
-            }
-            
-            console.log(`Found session ID from comment: ${sessionId}`);
-            
-            const session = await checkSessionStatus(sessionId);
-            if (!session) {
-              core.setOutput('has-active-session', 'false');
-              return;
-            }
-            
-            const activeStatuses = ['working', 'blocked', 'resumed'];
-            
-            if (activeStatuses.includes(session.status_enum)) {
-              console.log(`Session ${sessionId} is active (status: ${session.status_enum})`);
-              core.exportVariable('EXISTING_SESSION_ID', sessionId);
-              core.exportVariable('SESSION_URL', `https://app.devin.ai/sessions/${sessionId}`);
-              core.setOutput('has-active-session', 'true');
-            } else {
-              console.log(`Session ${sessionId} is not active (status: ${session.status_enum})`);
-              core.setOutput('has-active-session', 'false');
-            }
+          devin-api-key: ${{ secrets.DEVIN_API_KEY }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          pr-number: ${{ steps.extract-prompt.outputs.pr-number }}
+
+      - name: Set session environment variables
+        if: steps.extract-prompt.outputs.has-prompt == 'true' && steps.check-session.outputs.has-existing-session == 'true'
+        run: |
+          echo "EXISTING_SESSION_ID=${{ steps.check-session.outputs.session-id }}" >> $GITHUB_ENV
+          echo "SESSION_URL=${{ steps.check-session.outputs.session-url }}" >> $GITHUB_ENV
 
       - name: Send message to existing Devin session
-        if: steps.extract-prompt.outputs.has-prompt == 'true' && steps.check-session.outputs.has-active-session == 'true'
+        if: steps.extract-prompt.outputs.has-prompt == 'true' && steps.check-session.outputs.has-existing-session == 'true'
         env:
           DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}
         run: |
           CUBIC_PROMPT=$(cat /tmp/cubic-prompt.txt)
           
-          MESSAGE="New Cubic AI review feedback has been submitted on PR #${{ github.event.pull_request.number }}.
+          MESSAGE="New Cubic AI review feedback has been submitted on PR #${{ steps.extract-prompt.outputs.pr-number }}.
 
           IMPORTANT: Before fixing any issue, check the individual Cubic comment on the PR for that issue's confidence score. The confidence score appears as 'Fix confidence (alpha): X/10' in each comment. Note that the (alpha) may or not be there. Don't be picky about that text. But only fix issues where the confidence score is 9/10 or higher. If you cannot find a confidence score for an issue, skip it.
 
@@ -172,13 +127,13 @@ jobs:
           echo "Message sent to existing session successfully"
 
       - name: Create new Devin session
-        if: steps.extract-prompt.outputs.has-prompt == 'true' && steps.check-session.outputs.has-active-session == 'false'
+        if: steps.extract-prompt.outputs.has-prompt == 'true' && steps.check-session.outputs.has-existing-session == 'false'
         env:
           DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}
         run: |
           CUBIC_PROMPT=$(cat /tmp/cubic-prompt.txt)
           
-          FULL_PROMPT="You are addressing code review feedback from Cubic AI on PR #${{ github.event.pull_request.number }} in repository ${{ github.repository }}.
+          FULL_PROMPT="You are addressing code review feedback from Cubic AI on PR #${{ steps.extract-prompt.outputs.pr-number }} in repository ${{ github.repository }}.
 
           Your tasks:
           1. Clone the repository ${{ github.repository }} locally.
@@ -203,11 +158,11 @@ jobs:
             -H "Content-Type: application/json" \
             -d "$(jq -n \
               --arg prompt "$FULL_PROMPT" \
-              --arg title "Cubic AI Review: PR #${{ github.event.pull_request.number }}" \
+              --arg title "Cubic AI Review: PR #${{ steps.extract-prompt.outputs.pr-number }}" \
               '{
                 prompt: $prompt,
                 title: $title,
-                tags: ["cubic-ai-review", "pr-${{ github.event.pull_request.number }}"]
+                tags: ["cubic-ai-review", "pr-${{ steps.extract-prompt.outputs.pr-number }}"]
               }')")
           
           if [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 300 ]; then
@@ -225,6 +180,7 @@ jobs:
 
       - name: Post comment with Devin session link
         if: steps.extract-prompt.outputs.has-prompt == 'true' && env.SESSION_URL != ''
+        id: post-comment
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -236,9 +192,54 @@ jobs:
               ? `### Devin AI is addressing Cubic AI's review feedback\n\nA Devin session has been created to address the issues identified by Cubic AI.\n\n[View Devin Session](${sessionUrl})`
               : `### Devin AI is addressing Cubic AI's review feedback\n\nNew feedback has been sent to the existing Devin session.\n\n[View Devin Session](${sessionUrl})`;
             
-            await github.rest.issues.createComment({
+            // Use the PR number from the extract-prompt step output instead of reading the file
+            // (the file was deleted by the checkout step)
+            const prNumber = parseInt('${{ steps.extract-prompt.outputs.pr-number }}', 10);
+            
+            const { data: comment } = await github.rest.issues.createComment({
               owner: context.repo.owner,
               repo: context.repo.repo,
-              issue_number: context.payload.pull_request.number,
+              issue_number: prNumber,
               body: message
             });
+            
+            core.setOutput('comment-id', comment.id);
+
+      - name: Send completion instructions to Devin
+        if: steps.extract-prompt.outputs.has-prompt == 'true' && env.SESSION_URL != '' && steps.post-comment.outputs.comment-id != ''
+        env:
+          DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}
+        run: |
+          SESSION_ID="${EXISTING_SESSION_ID:-}"
+          if [ -z "$SESSION_ID" ]; then
+            SESSION_ID=$(cat /tmp/devin-response.json | jq -r '.session_id // .id // empty')
+          fi
+          
+          if [ -z "$SESSION_ID" ]; then
+            echo "No session ID found, skipping completion instructions"
+            exit 0
+          fi
+          
+          COMMENT_ID="${{ steps.post-comment.outputs.comment-id }}"
+          
+          MESSAGE="IMPORTANT: When you have finished addressing Cubic AI's feedback (whether you pushed changes or not), you MUST update the GitHub comment to show completion status.
+
+          Use the GitHub API to update comment ID ${COMMENT_ID} on PR #${{ steps.extract-prompt.outputs.pr-number }} in repository ${{ github.repository }}.
+
+          Add a completion status section at the bottom of the comment:
+          - If you pushed changes: Add '\n\n---\n:white_check_mark: Pushed commit [\`{SHORT_HASH}\`](https://github.com/${{ github.repository }}/commit/{FULL_HASH})' where {SHORT_HASH} is the first 7 characters of the commit hash and {FULL_HASH} is the full commit hash.
+          - If no changes were needed: Add '\n\n---\n:white_check_mark: No changes pushed'
+
+          To update the comment, use: gh api repos/${{ github.repository }}/issues/comments/${COMMENT_ID} -X PATCH -f body='<updated comment body>'"
+
+          HTTP_CODE=$(curl -s -o /tmp/devin-instructions-response.json -w "%{http_code}" -X POST "https://api.devin.ai/v1/sessions/${SESSION_ID}/message" \
+            -H "Authorization: Bearer ${DEVIN_API_KEY}" \
+            -H "Content-Type: application/json" \
+            -d "$(jq -n --arg message "$MESSAGE" '{message: $message}')")
+          
+          if [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 300 ]; then
+            echo "Warning: Failed to send completion instructions to Devin session: HTTP $HTTP_CODE"
+            cat /tmp/devin-instructions-response.json
+          else
+            echo "Completion instructions sent to Devin session successfully"
+          fi

.github/workflows/devin-conflict-resolver.yml

@@ -216,11 +216,27 @@ jobs:
             
             console.log(`Posted comment and removed label for PR #${prNumber}`);
 
+      - name: Checkout repository
+        if: steps.get-pr.outputs.has-pr == 'true' && steps.get-pr.outputs.needs-maintainer-access != 'true' && steps.get-pr.outputs.has-conflicts == 'true'
+        uses: actions/checkout@v4
+
+      - name: Check for existing Devin session
+        if: steps.get-pr.outputs.has-pr == 'true' && steps.get-pr.outputs.needs-maintainer-access != 'true' && steps.get-pr.outputs.has-conflicts == 'true'
+        id: check-session
+        uses: ./.github/actions/devin-session
+        with:
+          devin-api-key: ${{ secrets.DEVIN_API_KEY }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          pr-number: ${{ steps.get-pr.outputs.pr-number }}
+
       - name: Create Devin session for conflict resolution
         if: steps.get-pr.outputs.has-pr == 'true' && steps.get-pr.outputs.needs-maintainer-access != 'true' && steps.get-pr.outputs.has-conflicts == 'true'
         env:
           DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HAS_EXISTING_SESSION: ${{ steps.check-session.outputs.has-existing-session }}
+          EXISTING_SESSION_ID: ${{ steps.check-session.outputs.session-id }}
+          EXISTING_SESSION_URL: ${{ steps.check-session.outputs.session-url }}
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -229,75 +245,12 @@ jobs:
             const pr = JSON.parse(fs.readFileSync('/tmp/pr-data.json', 'utf8'));
             const { owner, repo } = context.repo;
             
-            async function checkSessionStatus(sessionId) {
-              const response = await fetch(`https://api.devin.ai/v1/sessions/${sessionId}`, {
-                headers: {
-                  'Authorization': `Bearer ${process.env.DEVIN_API_KEY}`,
-                  'Content-Type': 'application/json'
-                }
-              });
-              
-              if (!response.ok) {
-                console.log(`Failed to fetch session ${sessionId}: ${response.status}`);
-                return null;
-              }
-              
-              return await response.json();
-            }
-            
-            async function findExistingSession(prNumber, prBody) {
-              // First check if PR was created through Devin
-              const prSessionMatch = prBody?.match(/app\.devin\.ai\/sessions\/([a-f0-9-]+)/);
-              if (prSessionMatch) {
-                const sessionId = prSessionMatch[1];
-                console.log(`PR #${prNumber} was created by Devin session: ${sessionId}`);
-                const session = await checkSessionStatus(sessionId);
-                if (session) {
-                  return { sessionId, sessionUrl: `https://app.devin.ai/sessions/${sessionId}`, isFromPrBody: true };
-                }
-              }
-              
-              // Check PR comments for existing Devin session (conflict resolution or Cubic AI review)
-              const comments = await github.rest.issues.listComments({
-                owner,
-                repo,
-                issue_number: prNumber
-              });
-              
-              const sessionPatterns = [
-                'Devin AI is resolving merge conflicts',
-                'Devin AI is addressing Cubic AI'
-              ];
-              
-              for (const comment of comments.data.reverse()) {
-                const hasDevinSession = sessionPatterns.some(pattern => comment.body?.includes(pattern));
-                if (hasDevinSession) {
-                  const match = comment.body?.match(/app\.devin\.ai\/sessions\/([a-f0-9-]+)/);
-                  if (match) {
-                    const sessionId = match[1];
-                    console.log(`Found existing session from comment: ${sessionId}`);
-                    
-                    const session = await checkSessionStatus(sessionId);
-                    if (session) {
-                      const activeStatuses = ['working', 'blocked', 'resumed'];
-                      if (activeStatuses.includes(session.status_enum)) {
-                        console.log(`Session ${sessionId} is active (status: ${session.status_enum})`);
-                        return { sessionId, sessionUrl: `https://app.devin.ai/sessions/${sessionId}`, isFromPrBody: false };
-                      } else {
-                        console.log(`Session ${sessionId} is not active (status: ${session.status_enum})`);
-                      }
-                    }
-                  }
-                }
-              }
-              
-              return null;
-            }
+            const hasExistingSession = process.env.HAS_EXISTING_SESSION === 'true';
+            const existingSessionId = process.env.EXISTING_SESSION_ID;
+            const existingSessionUrl = process.env.EXISTING_SESSION_URL;
             
             console.log(`Processing PR #${pr.number}: ${pr.title}${pr.is_fork ? ' (fork)' : ''}`);
             
-            const existingSession = await findExistingSession(pr.number, pr.body);
-            
             const forkInstructions = pr.is_fork ? `
             IMPORTANT: This PR is from a fork.
             - Clone the FORK repository: ${pr.head_repo_owner}/${pr.head_repo_name}
@@ -386,8 +339,8 @@ jobs:
               let sessionUrl;
               let isNewSession = false;
               
-              if (existingSession) {
-                console.log(`Sending message to existing session ${existingSession.sessionId} for PR #${pr.number}`);
+              if (hasExistingSession) {
+                console.log(`Sending message to existing session ${existingSessionId} for PR #${pr.number}`);
                 
                 const message = `PR #${pr.number} has merge conflicts that need to be resolved.
 
@@ -395,7 +348,7 @@ jobs:
 
             Continue working on the same PR branch and push your fixes.`;
                 
-                const response = await fetch(`https://api.devin.ai/v1/sessions/${existingSession.sessionId}/message`, {
+                const response = await fetch(`https://api.devin.ai/v1/sessions/${existingSessionId}/message`, {
                   method: 'POST',
                   headers: {
                     'Authorization': `Bearer ${process.env.DEVIN_API_KEY}`,
@@ -405,11 +358,11 @@ jobs:
                 });
                 
                 if (!response.ok) {
-                  console.error(`Failed to send message to session ${existingSession.sessionId}: ${response.status}`);
+                  console.error(`Failed to send message to session ${existingSessionId}: ${response.status}`);
                   throw new Error(`Failed to send message to existing session: ${response.status}`);
                 }
                 
-                sessionUrl = existingSession.sessionUrl;
+                sessionUrl = existingSessionUrl;
                 console.log(`Message sent to existing session for PR #${pr.number}`);
               } else {
                 console.log(`Creating new Devin session for PR #${pr.number}`);

.github/workflows/draft-release.yml

@@ -55,6 +55,23 @@ jobs:
 
       - uses: ./.github/actions/yarn-install
 
+      # 1. Generate Prisma Client
+      # This is required so Trigger.dev can find the database types during bundling
+      - name: Generate Prisma Client
+        run: yarn prisma generate
+
+      # 2. Deploy Trigger.dev tasks
+      # We use --skip-promotion to get a version without making it live yet
+      - name: Deploy Trigger.dev
+        id: deploy-trigger
+        env:
+          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
+          TRIGGER_DEV_PROJECT_REF: ${{ secrets.TRIGGER_DEV_PROJECT_REF }}
+        run: |
+          # The CLI outputs the version; id allows us to access outputs.deploymentVersion
+          cd packages/features
+          yarn deploy:trigger:ci
+
       - name: Bump version
         env:
           VERSION: ${{ inputs.next_version }}
@@ -62,10 +79,30 @@ jobs:
           cd apps/web
           yarn version "$VERSION"
 
+      # 3. Update .env.production files
+      # We inject the Trigger version into the apps so they stay in sync
+      - name: Update Env Files
+        run: |
+          VERSION="${{ steps.deploy-trigger.outputs.deploymentVersion }}"
+    
+          # Create the TypeScript content
+          CONTENT="export const TRIGGER_VERSION = '$VERSION';"
+    
+          # Write to the specific paths
+          echo "$CONTENT" > apps/web/trigger.version.ts
+          echo "$CONTENT" > apps/api/v2/trigger.version.ts
+          echo "$CONTENT" > apps/api/v1/trigger.version.js
+    
+          # Force add to git since these are likely in .gitignore
+          git add -f apps/web/trigger.version.ts apps/api/v2/trigger.version.ts apps/api/v1/trigger.version.js
+
+      # 4. Commit everything together
       - name: Commit changes
         env:
           VERSION: ${{ inputs.next_version }}
+          GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
         run: |
+          gh auth setup-git
           git add .
           git commit -m "chore: release v$VERSION"
           git push
@@ -73,5 +110,5 @@ jobs:
       - name: Draft release
         run: gh release create v$VERSION --generate-notes --draft
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
           VERSION: ${{ inputs.next_version }}

.github/workflows/i18n.yml

@@ -35,3 +35,4 @@ jobs:
         with:
           api-key: ${{ secrets.CI_LINGO_DOT_DEV_API_KEY }}
           pull-request: true
+          parallel: true

.github/workflows/lint.yml

@@ -16,4 +16,3 @@ jobs:
       - uses: ./.github/actions/yarn-install
       - name: Run Lint
         run: yarn lint
-        continue-on-error: true

.github/workflows/pr.yml

@@ -166,9 +166,10 @@ jobs:
     permissions:
       pull-requests: read
     outputs:
-      has-files-requiring-all-checks: ${{ steps.filter.outputs.has-files-requiring-all-checks }}
-      has_companion: ${{ steps.filter.outputs.has_companion }}
-      has-api-v2-changes: ${{ steps.filter.outputs.has-api-v2-changes }}
+      has-files-requiring-all-checks: ${{ steps.filter-exclusions.outputs.has-files-requiring-all-checks }}
+      has-api-v2-changes: ${{ steps.filter-inclusions.outputs.has-api-v2-changes }}
+      has-prisma-changes: ${{ steps.filter-inclusions.outputs.has-prisma-changes }}
+      has-agents-changes: ${{ steps.filter-inclusions.outputs.has-agents-changes }}
       commit-sha: ${{ steps.get_sha.outputs.commit-sha }}
       run-e2e: ${{ steps.check-if-pr-has-label.outputs.run-e2e == 'true' }}
       db-cache-hit: ${{ steps.cache-db-check.outputs.cache-hit }}
@@ -187,23 +188,29 @@ jobs:
           path: backups/backup.sql
           key: ${{ steps.cache-db-key.outputs.key }}
           lookup-only: true
-      - uses: dorny/paths-filter@v3
-        id: filter
+      - name: Check for files requiring all checks (with exclusions)
+        uses: dorny/paths-filter@v3
+        id: filter-exclusions
         with:
           predicate-quantifier: "every"
           filters: |
             has-files-requiring-all-checks:
               - '**'
-              - '!companion/**'
+              - '!.vscode/**'
               - '!**/*.md'
               - '!**/*.mdx'
               - '!.github/CODEOWNERS'
               - '!docs/**'
               - '!help/**'
-              - '!apps/web/public/static/locales/**/common.json'
+              - '!packages/i18n/locales/**/common.json'
               - '!i18n.lock'
-            has_companion:
-              - "companion/**"
+      - name: Check for specific path changes
+        uses: dorny/paths-filter@v3
+        id: filter-inclusions
+        with:
+          filters: |
+            has-agents-changes:
+              - "agents/**"
             has-api-v2-changes:
               - "apps/api/v2/**"
               - "packages/platform-constants/**"
@@ -214,6 +221,9 @@ jobs:
               - "packages/trpc/**"
               - "packages/prisma/schema.prisma"
               - "docs/api-reference/v2/**"
+            has-prisma-changes:
+              - "packages/prisma/schema.prisma"
+              - "packages/prisma/migrations/**"
       - name: Get Latest Commit SHA
         id: get_sha
         run: |
@@ -279,16 +289,23 @@ jobs:
             console.log('Found the label?', labelFound);
             core.setOutput('run-e2e', labelFound);
       - uses: ./.github/actions/yarn-install
-        if: ${{ steps.filter.outputs.has-files-requiring-all-checks == 'true' }}
+        if: ${{ steps.filter-exclusions.outputs.has-files-requiring-all-checks == 'true' }}
         with:
           skip-install-if-cache-hit: "true"
       - uses: ./.github/actions/yarn-playwright-install
-        if: ${{ steps.filter.outputs.has-files-requiring-all-checks == 'true' }}
+        if: ${{ steps.filter-exclusions.outputs.has-files-requiring-all-checks == 'true' }}
         with:
           skip-install-if-cache-hit: "true"
 
+  validate-agents-format:
+    name: Validate agents/ format
+    needs: [trust-check, prepare]
+    if: needs.trust-check.outputs.is-trusted == 'true' && needs.prepare.outputs.has-agents-changes == 'true' && github.event.pull_request
+    uses: ./.github/workflows/validate-agents-format.yml
+    secrets: inherit
+
   type-check:
-    name: Type check
+    name: Type Checks
     needs: [prepare]
     if: ${{ needs.prepare.outputs.has-files-requiring-all-checks == 'true' }}
     uses: ./.github/workflows/check-types.yml
@@ -315,6 +332,20 @@ jobs:
     uses: ./.github/workflows/api-v2-unit-tests.yml
     secrets: inherit
 
+  security-audit:
+    name: Security Audit
+    needs: [prepare]
+    if: ${{ needs.prepare.outputs.has-files-requiring-all-checks == 'true' }}
+    uses: ./.github/workflows/security-audit.yml
+    secrets: inherit
+
+  check-prisma-migrations:
+    name: Check Prisma Migrations
+    needs: [prepare]
+    if: ${{ needs.prepare.outputs.has-prisma-changes == 'true' }}
+    uses: ./.github/workflows/check-prisma-migrations.yml
+    secrets: inherit
+
   setup-db:
     name: Setup Database
     needs: [prepare]
@@ -352,13 +383,6 @@ jobs:
     uses: ./.github/workflows/docs-build.yml
     secrets: inherit
 
-  build-companion:
-    name: Companion builds
-    needs: [prepare]
-    if: needs.prepare.outputs.has_companion == 'true'
-    uses: ./.github/workflows/companion-build.yml
-    secrets: inherit
-
   build:
     name: Production builds
     needs: [prepare]
@@ -426,18 +450,20 @@ jobs:
       [
         trust-check,
         prepare,
+        validate-agents-format,
         lint,
         type-check,
         unit-test,
         api-v2-unit-test,
+        security-audit,
         check-api-v2-breaking-changes,
+        check-prisma-migrations,
         integration-test,
         build,
         build-api-v1,
         build-api-v2,
         build-atoms,
         build-docs,
-        build-companion,
         setup-db,
         e2e,
         e2e-api-v2,
@@ -469,7 +495,9 @@ jobs:
             needs.type-check.result != 'success' ||
             needs.unit-test.result != 'success' ||
             needs.api-v2-unit-test.result != 'success' ||
+            needs.security-audit.result != 'success' ||
             (needs.prepare.outputs.has-api-v2-changes == 'true' && needs.check-api-v2-breaking-changes.result != 'success') ||
+            (needs.prepare.outputs.has-prisma-changes == 'true' && needs.check-prisma-migrations.result != 'success') ||
               needs.build.result != 'success' ||
               needs.build-api-v1.result != 'success' ||
               needs.build-api-v2.result != 'success' ||
@@ -485,6 +513,6 @@ jobs:
             )
           ) ||
           (
-            needs.prepare.outputs.has_companion == 'true' &&
-            needs.build-companion.result != 'success'
+            needs.prepare.outputs.has-agents-changes == 'true' &&
+            needs.validate-agents-format.result != 'success'
           )

.github/workflows/security-audit.yml

@@ -0,0 +1,19 @@
+name: Security Audit
+on:
+  workflow_call:
+permissions:
+  actions: write
+  contents: read
+jobs:
+  audit:
+    runs-on: blacksmith-2vcpu-ubuntu-2404
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: .github
+      - uses: ./.github/actions/cache-checkout
+      - uses: ./.github/actions/yarn-install
+      - name: Report all vulnerabilities
+        run: yarn npm audit --all --recursive || true
+      - name: Fail on critical vulnerabilities
+        run: yarn npm audit --all --recursive --severity critical

.github/workflows/stale-pr-devin-completion.yml

@@ -1,7 +1,7 @@
 name: Stale Community PR Devin Completion
 
 on:
-  pull_request:
+  pull_request_target:
     types: [labeled]
   workflow_dispatch:
     inputs:
@@ -17,11 +17,12 @@ permissions:
 jobs:
   complete-stale-pr:
     name: Trigger Devin to Complete Stale Community PR
-    # For labeled events: only run if 'stale' label was added
+    # For labeled events: only run if 'Stale' or 'devin-finish-pr' label was added
     # For workflow_dispatch: always run (we'll validate the PR in the steps)
     if: >
       github.event_name == 'workflow_dispatch' ||
-      github.event.label.name == 'stale'
+      github.event.label.name == 'Stale' ||
+      github.event.label.name == 'devin-finish-pr'
     runs-on: blacksmith-2vcpu-ubuntu-2404
     steps:
       - name: Get PR details
@@ -60,7 +61,6 @@ jobs:
 
             const isFork = pr.head.repo.fork || pr.head.repo.full_name !== pr.base.repo.full_name;
             const maintainerCanModify = pr.maintainer_can_modify;
-            const canProceed = !isFork || maintainerCanModify;
             const needsMaintainerAccess = isFork && !maintainerCanModify;
 
             const headRepoFullName = pr.head.repo.full_name;
@@ -74,7 +74,6 @@ jobs:
             core.setOutput('head_repo_full_name', headRepoFullName);
             core.setOutput('head_repo_clone_url', headRepoCloneUrl);
             core.setOutput('maintainer_can_modify', maintainerCanModify);
-            core.setOutput('can_proceed', canProceed);
             core.setOutput('needs_maintainer_access', needsMaintainerAccess);
 
             console.log(`PR #${prNumber}: "${pr.title}"`);
@@ -142,8 +141,18 @@ jobs:
 
             core.setFailed(`Cannot complete this fork PR: the fork owner has not enabled "Allow edits from maintainers". A comment has been posted requesting access.`);
 
-      - name: Create Devin session
-        if: steps.pr.outputs.can_proceed == 'true'
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Check for existing Devin session
+        id: check-session
+        uses: ./.github/actions/devin-session
+        with:
+          devin-api-key: ${{ secrets.DEVIN_API_KEY }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          pr-number: ${{ steps.pr.outputs.pr_number }}
+
+      - name: Create or reuse Devin session
         env:
           DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}
           PR_NUMBER: ${{ steps.pr.outputs.pr_number }}
@@ -153,6 +162,9 @@ jobs:
           IS_FORK: ${{ steps.pr.outputs.is_fork }}
           HEAD_REPO_FULL_NAME: ${{ steps.pr.outputs.head_repo_full_name }}
           REPO_NAME: ${{ github.repository }}
+          HAS_EXISTING_SESSION: ${{ steps.check-session.outputs.has-existing-session }}
+          EXISTING_SESSION_ID: ${{ steps.check-session.outputs.session-id }}
+          EXISTING_SESSION_URL: ${{ steps.check-session.outputs.session-url }}
         run: |
           if [ "$IS_FORK" = "true" ]; then
             CLONE_INSTRUCTIONS="This is a fork PR. Clone from the fork repository: ${HEAD_REPO_FULL_NAME}
@@ -190,8 +202,8 @@ jobs:
           6. Run the appropriate checks (lint, type-check, tests) to ensure the PR is ready for review.
           7. Commit your changes with clear commit messages.
           8. Push your changes to the PR branch.
-          9. Post a summary comment on the PR explaining what you completed.
-          10. Remove the 'stale' label from the PR if you've completed the work.
+          9. After successfully pushing, remove the 'Stale' or 'devin-finish-pr' label from the PR (whichever was used to trigger this workflow).
+          10. Post a summary comment on the PR explaining what you completed.
           11. Mark the PR as ready for review if applicable.
 
           Rules and Guidelines:
@@ -203,25 +215,54 @@ jobs:
           6. Credit the original author in your commit messages where appropriate.
           7. CRITICAL: If this is a fork PR and you encounter ANY error when pushing (permission denied, authentication failure, etc.) even after using the DEVIN_ACTIONS_PAT, you MUST fail the task immediately. Do NOT attempt to push to a new branch in the main repository as a workaround. Simply report the error and stop."
 
-          RESPONSE=$(curl -s -X POST "https://api.devin.ai/v1/sessions" \
-            -H "Authorization: Bearer ${DEVIN_API_KEY}" \
-            -H "Content-Type: application/json" \
-            -d "$(jq -n \
-              --arg prompt "$FULL_PROMPT" \
-              --arg title "Complete Stale PR #${PR_NUMBER}: ${PR_TITLE}" \
-              '{
-                prompt: $prompt,
-                title: $title,
-                tags: ["stale-pr-completion", "pr-'${PR_NUMBER}'"]
-              }')")
+          if [ "$HAS_EXISTING_SESSION" = "true" ]; then
+            echo "Sending message to existing session ${EXISTING_SESSION_ID}"
 
-          SESSION_URL=$(echo "$RESPONSE" | jq -r '.url // .session_url // empty')
-          if [ -n "$SESSION_URL" ]; then
-            echo "Devin session created: $SESSION_URL"
-            echo "SESSION_URL=$SESSION_URL" >> $GITHUB_ENV
+            MESSAGE="This PR has been marked as stale and needs to be completed.
+
+          ${FULL_PROMPT}
+
+          Continue working on the same PR branch and push your fixes."
+
+            HTTP_CODE=$(curl -s -o /tmp/devin-response.json -w "%{http_code}" -X POST "https://api.devin.ai/v1/sessions/${EXISTING_SESSION_ID}/message" \
+              -H "Authorization: Bearer ${DEVIN_API_KEY}" \
+              -H "Content-Type: application/json" \
+              -d "$(jq -n --arg message "$MESSAGE" '{message: $message}')")
+
+            if [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 300 ]; then
+              echo "Failed to send message to Devin session: HTTP $HTTP_CODE"
+              cat /tmp/devin-response.json
+              exit 1
+            fi
+
+            echo "Message sent to existing session successfully"
+            echo "SESSION_URL=$EXISTING_SESSION_URL" >> $GITHUB_ENV
+            echo "IS_NEW_SESSION=false" >> $GITHUB_ENV
           else
-            echo "Failed to create Devin session"
-            exit 1
+            echo "Creating new Devin session"
+
+            RESPONSE=$(curl -s -X POST "https://api.devin.ai/v1/sessions" \
+              -H "Authorization: Bearer ${DEVIN_API_KEY}" \
+              -H "Content-Type: application/json" \
+              -d "$(jq -n \
+                --arg prompt "$FULL_PROMPT" \
+                --arg title "Complete Stale PR #${PR_NUMBER}: ${PR_TITLE}" \
+                '{
+                  prompt: $prompt,
+                  title: $title,
+                  tags: ["stale-pr-completion", "pr-'${PR_NUMBER}'"]
+                }')")
+
+            SESSION_URL=$(echo "$RESPONSE" | jq -r '.url // .session_url // empty')
+            if [ -n "$SESSION_URL" ]; then
+              echo "Devin session created: $SESSION_URL"
+              echo "SESSION_URL=$SESSION_URL" >> $GITHUB_ENV
+              echo "IS_NEW_SESSION=true" >> $GITHUB_ENV
+            else
+              echo "Failed to create Devin session"
+              echo "$RESPONSE"
+              exit 1
+            fi
           fi
 
       - name: Post comment with Devin session link
@@ -236,9 +277,15 @@ jobs:
             const sessionUrl = process.env.SESSION_URL;
             const prAuthor = process.env.PR_AUTHOR;
             const prNumber = process.env.PR_NUMBER;
+            const isNewSession = process.env.IS_NEW_SESSION === 'true';
+
+            const message = isNewSession
+              ? `### Devin AI is completing this stale PR\n\nThis PR by @${prAuthor} has been marked as stale. A Devin session has been created to complete the remaining work.\n\n[View Devin Session](${sessionUrl})\n\n---\n*Devin will review the PR, address any feedback, and push updates to complete this PR.*`
+              : `### Devin AI is completing this stale PR\n\nThis PR by @${prAuthor} has been marked as stale. The existing Devin session has been notified to complete the remaining work.\n\n[View Devin Session](${sessionUrl})\n\n---\n*Devin will review the PR, address any feedback, and push updates to complete this PR.*`;
+
             await github.rest.issues.createComment({
               owner: context.repo.owner,
               repo: context.repo.repo,
               issue_number: parseInt(prNumber),
-              body: `### Devin AI is completing this stale PR\n\nThis PR by @${prAuthor} has been marked as stale. A Devin session has been created to complete the remaining work.\n\n[View Devin Session](${sessionUrl})\n\n---\n*Devin will review the PR, address any feedback, and push updates to complete this PR.*`
+              body: message
             });

.github/workflows/sync-agents-to-devin.yml

@@ -0,0 +1,31 @@
+name: Sync Agents to Devin Knowledge
+
+on:
+  push:
+    paths:
+      - "agents/**"
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  sync:
+    if: false
+    name: Sync to Devin Knowledge
+    runs-on: blacksmith-2vcpu-ubuntu-2404
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: .github
+      - uses: ./.github/actions/cache-checkout
+      - uses: ./.github/actions/yarn-install
+
+      - name: Generate knowledge JSON
+        run: npx tsx scripts/devin/parse-local-knowledge.ts
+
+      - name: Sync to Devin
+        env:
+          DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}
+        run: npx tsx scripts/devin/sync-knowledge-to-devin.ts

.github/workflows/validate-agents-format.yml

@@ -0,0 +1,20 @@
+name: Validate Agents Format
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  validate-agents-format:
+    runs-on: blacksmith-2vcpu-ubuntu-2404
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: .github
+      - uses: ./.github/actions/cache-checkout
+      - uses: ./.github/actions/yarn-install
+
+      - name: Validate format
+        run: npx tsx scripts/devin/validate-local-knowledge.ts

.gitignore

@@ -60,7 +60,7 @@ yarn-error.log*
 .history/
 
 # Typescript
-tsconfig.tsbuildinfo
+*.tsbuildinfo
 
 # turbo
 .turbo
@@ -75,6 +75,7 @@ packages/prisma/enums
 
 # Builds
 dist
+packages/app-store/types
 
 # Linting
 lint-results
@@ -103,8 +104,13 @@ apps/auth
 i18n.cache
 packages/**/.yarn/ci-cache/
 
-# AI
-.claude
+# AI - session/user specific files (keep CLAUDE.md and .cursor/skills tracked)
+.claude/plans/
+.claude/settings.local.json
+
+# Spec drafts (rough work, not ready for review)
+specs/**/_drafts/
 
 # trigger.dev
-.trigger
+.trigger
+agents/devin-knowledge.json

.husky/pre-commit

@@ -3,5 +3,5 @@ if [ -f .git/MERGE_HEAD ]; then
   exit 0
 fi
 
-yarn lint-staged
+yarn lint-staged --verbose
 yarn app-store:build && git add packages/app-store/*.generated.*

.opencode/skill/vercel-react-best-practices/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: vercel-react-best-practices
+description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+license: MIT
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel React Best Practices
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+- `async-api-routes` - Start promises early, await late in API routes
+- `async-suspense-boundaries` - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-dynamic-imports` - Use next/dynamic for heavy components
+- `bundle-defer-third-party` - Load analytics/logging after hydration
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- `server-cache-react` - Use React.cache() for per-request deduplication
+- `server-cache-lru` - Use LRU cache for cross-request caching
+- `server-serialization` - Minimize data passed to client components
+- `server-parallel-fetching` - Restructure components to parallelize fetches
+- `server-after-nonblocking` - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Use SWR for automatic request deduplication
+- `client-event-listeners` - Deduplicate global event listeners
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-transitions` - Use startTransition for non-urgent updates
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-hydration-no-flicker` - Use inline script for client-only data
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+rules/_sections.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`

.opencode/skill/vercel-react-best-practices/rules/advanced-event-handler-refs.md

@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: () => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: () => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = () => handlerRef.current()
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: () => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.

.opencode/skill/vercel-react-best-practices/rules/advanced-use-latest.md

@@ -0,0 +1,49 @@
+---
+title: useLatest for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useLatest, refs, optimization
+---
+
+## useLatest for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Implementation:**
+
+```typescript
+function useLatest<T>(value: T) {
+  const ref = useRef(value)
+  useEffect(() => {
+    ref.current = value
+  }, [value])
+  return ref
+}
+```
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct (stable effect, fresh callback):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchRef = useLatest(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchRef.current(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```

.opencode/skill/vercel-react-best-practices/rules/async-api-routes.md

@@ -0,0 +1,38 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**Correct (auth and config start immediately):**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).

.opencode/skill/vercel-react-best-practices/rules/async-defer-await.md

@@ -0,0 +1,80 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+  
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+  
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  const permissions = await fetchPermissions(userId)
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.

.opencode/skill/vercel-react-best-practices/rules/async-dependencies.md

@@ -0,0 +1,36 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)

.opencode/skill/vercel-react-best-practices/rules/async-parallel.md

@@ -0,0 +1,28 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```

.opencode/skill/vercel-react-best-practices/rules/async-suspense-boundaries.md

@@ -0,0 +1,99 @@
+---
+title: Strategic Suspense Boundaries
+impact: HIGH
+impactDescription: faster initial paint
+tags: async, suspense, streaming, layout-shift
+---
+
+## Strategic Suspense Boundaries
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect (wrapper blocked by data fetching):**
+
+```tsx
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct (wrapper shows immediately, data streams in):**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative (share promise across components):**
+
+```tsx
+function Page() {
+  // Start fetch immediately, but don't await
+  const dataPromise = fetchData()
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Unwraps the promise
+  return <div>{data.content}</div>
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Reuses the same promise
+  return <div>{data.summary}</div>
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+- SEO-critical content above the fold
+- Small, fast queries where suspense overhead isn't worth it
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.

.opencode/skill/vercel-react-best-practices/rules/bundle-barrel-imports.md

@@ -0,0 +1,59 @@
+---
+title: Avoid Barrel File Imports
+impact: CRITICAL
+impactDescription: 200-800ms import cost, slow builds
+tags: bundle, imports, tree-shaking, barrel-files, performance
+---
+
+## Avoid Barrel File Imports
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect (imports entire library):**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct (imports only what you need):**
+
+```tsx
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+import Menu from 'lucide-react/dist/esm/icons/menu'
+// Loads only 3 modules (~2KB vs ~1MB)
+
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+**Alternative (Next.js 13.5+):**
+
+```js
+// next.config.js - use optimizePackageImports
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material']
+  }
+}
+
+// Then you can keep the ergonomic barrel imports:
+import { Check, X, Menu } from 'lucide-react'
+// Automatically transformed to direct imports at build time
+```
+
+Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)

.opencode/skill/vercel-react-best-practices/rules/bundle-conditional.md

@@ -0,0 +1,31 @@
+---
+title: Conditional Module Loading
+impact: HIGH
+impactDescription: loads large data only when needed
+tags: bundle, conditional-loading, lazy-loading
+---
+
+## Conditional Module Loading
+
+Load large data or modules only when a feature is activated.
+
+**Example (lazy-load animation frames):**
+
+```tsx
+function AnimationPlayer({ enabled }: { enabled: boolean }) {
+  const [frames, setFrames] = useState<Frame[] | null>(null)
+
+  useEffect(() => {
+    if (enabled && !frames && typeof window !== 'undefined') {
+      import('./animation-frames.js')
+        .then(mod => setFrames(mod.frames))
+        .catch(() => setEnabled(false))
+    }
+  }, [enabled, frames])
+
+  if (!frames) return <Skeleton />
+  return <Canvas frames={frames} />
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.

.opencode/skill/vercel-react-best-practices/rules/bundle-defer-third-party.md

@@ -0,0 +1,49 @@
+---
+title: Defer Non-Critical Third-Party Libraries
+impact: MEDIUM
+impactDescription: loads after hydration
+tags: bundle, third-party, analytics, defer
+---
+
+## Defer Non-Critical Third-Party Libraries
+
+Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
+
+**Incorrect (blocks initial bundle):**
+
+```tsx
+import { Analytics } from '@vercel/analytics/react'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+**Correct (loads after hydration):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const Analytics = dynamic(
+  () => import('@vercel/analytics/react').then(m => m.Analytics),
+  { ssr: false }
+)
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```

.opencode/skill/vercel-react-best-practices/rules/bundle-dynamic-imports.md

@@ -0,0 +1,35 @@
+---
+title: Dynamic Imports for Heavy Components
+impact: CRITICAL
+impactDescription: directly affects TTI and LCP
+tags: bundle, dynamic-import, code-splitting, next-dynamic
+---
+
+## Dynamic Imports for Heavy Components
+
+Use `next/dynamic` to lazy-load large components not needed on initial render.
+
+**Incorrect (Monaco bundles with main chunk ~300KB):**
+
+```tsx
+import { MonacoEditor } from './monaco-editor'
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+**Correct (Monaco loads on demand):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```

.opencode/skill/vercel-react-best-practices/rules/bundle-preload.md

@@ -0,0 +1,50 @@
+---
+title: Preload Based on User Intent
+impact: MEDIUM
+impactDescription: reduces perceived latency
+tags: bundle, preload, user-intent, hover
+---
+
+## Preload Based on User Intent
+
+Preload heavy bundles before they're needed to reduce perceived latency.
+
+**Example (preload on hover/focus):**
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    if (typeof window !== 'undefined') {
+      void import('./monaco-editor')
+    }
+  }
+
+  return (
+    <button
+      onMouseEnter={preload}
+      onFocus={preload}
+      onClick={onClick}
+    >
+      Open Editor
+    </button>
+  )
+}
+```
+
+**Example (preload when feature flag is enabled):**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+  useEffect(() => {
+    if (flags.editorEnabled && typeof window !== 'undefined') {
+      void import('./monaco-editor').then(mod => mod.init())
+    }
+  }, [flags.editorEnabled])
+
+  return <FlagsContext.Provider value={flags}>
+    {children}
+  </FlagsContext.Provider>
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.

.opencode/skill/vercel-react-best-practices/rules/client-event-listeners.md

@@ -0,0 +1,74 @@
+---
+title: Deduplicate Global Event Listeners
+impact: LOW
+impactDescription: single listener for N components
+tags: client, swr, event-listeners, subscription
+---
+
+## Deduplicate Global Event Listeners
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect (N instances = N listeners):**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) {
+        callback()
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [key, callback])
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct (N instances = 1 listener):**
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map<string, Set<() => void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+  // Register this callback in the Map
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) {
+      keyCallbacks.set(key, new Set())
+    }
+    keyCallbacks.get(key)!.add(callback)
+
+    return () => {
+      const set = keyCallbacks.get(key)
+      if (set) {
+        set.delete(callback)
+        if (set.size === 0) {
+          keyCallbacks.delete(key)
+        }
+      }
+    }
+  }, [key, callback])
+
+  useSWRSubscription('global-keydown', () => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key)!.forEach(cb => cb())
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  })
+}
+
+function Profile() {
+  // Multiple shortcuts will share the same listener
+  useKeyboardShortcut('p', () => { /* ... */ }) 
+  useKeyboardShortcut('k', () => { /* ... */ })
+  // ...
+}
+```

.opencode/skill/vercel-react-best-practices/rules/client-swr-dedup.md

@@ -0,0 +1,56 @@
+---
+title: Use SWR for Automatic Deduplication
+impact: MEDIUM-HIGH
+impactDescription: automatic deduplication
+tags: client, swr, deduplication, data-fetching
+---
+
+## Use SWR for Automatic Deduplication
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect (no deduplication, each instance fetches):**
+
+```tsx
+function UserList() {
+  const [users, setUsers] = useState([])
+  useEffect(() => {
+    fetch('/api/users')
+      .then(r => r.json())
+      .then(setUsers)
+  }, [])
+}
+```
+
+**Correct (multiple instances share one request):**
+
+```tsx
+import useSWR from 'swr'
+
+function UserList() {
+  const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from '@/lib/swr'
+
+function StaticContent() {
+  const { data } = useImmutableSWR('/api/config', fetcher)
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from 'swr/mutation'
+
+function UpdateButton() {
+  const { trigger } = useSWRMutation('/api/user', updateUser)
+  return <button onClick={() => trigger()}>Update</button>
+}
+```
+
+Reference: [https://swr.vercel.app](https://swr.vercel.app)

.opencode/skill/vercel-react-best-practices/rules/js-batch-dom-css.md

@@ -0,0 +1,82 @@
+---
+title: Batch DOM CSS Changes
+impact: MEDIUM
+impactDescription: reduces reflows/repaints
+tags: javascript, dom, css, performance, reflow
+---
+
+## Batch DOM CSS Changes
+
+Avoid changing styles one property at a time. Group multiple CSS changes together via classes or `cssText` to minimize browser reflows.
+
+**Incorrect (multiple reflows):**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Each line triggers a reflow
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+}
+```
+
+**Correct (add class - single reflow):**
+
+```typescript
+// CSS file
+.highlighted-box {
+  width: 100px;
+  height: 200px;
+  background-color: blue;
+  border: 1px solid black;
+}
+
+// JavaScript
+function updateElementStyles(element: HTMLElement) {
+  element.classList.add('highlighted-box')
+}
+```
+
+**Correct (change cssText - single reflow):**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.style.cssText = `
+    width: 100px;
+    height: 200px;
+    background-color: blue;
+    border: 1px solid black;
+  `
+}
+```
+
+**React example:**
+
+```tsx
+// Incorrect: changing styles one by one
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  const ref = useRef<HTMLDivElement>(null)
+  
+  useEffect(() => {
+    if (ref.current && isHighlighted) {
+      ref.current.style.width = '100px'
+      ref.current.style.height = '200px'
+      ref.current.style.backgroundColor = 'blue'
+    }
+  }, [isHighlighted])
+  
+  return <div ref={ref}>Content</div>
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  return (
+    <div className={isHighlighted ? 'highlighted-box' : ''}>
+      Content
+    </div>
+  )
+}
+```
+
+Prefer CSS classes over inline styles when possible. Classes are cached by the browser and provide better separation of concerns.

.opencode/skill/vercel-react-best-practices/rules/js-cache-function-results.md

@@ -0,0 +1,80 @@
+---
+title: Cache Repeated Function Calls
+impact: MEDIUM
+impactDescription: avoid redundant computation
+tags: javascript, cache, memoization, performance
+---
+
+## Cache Repeated Function Calls
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect (redundant computation):**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // slugify() called 100+ times for same project names
+        const slug = slugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Correct (cached results):**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map<string, string>()
+
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) {
+    return slugifyCache.get(text)!
+  }
+  const result = slugify(text)
+  slugifyCache.set(text, result)
+  return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // Computed only once per unique project name
+        const slug = cachedSlugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null
+
+function isLoggedIn(): boolean {
+  if (isLoggedInCache !== null) {
+    return isLoggedInCache
+  }
+  
+  isLoggedInCache = document.cookie.includes('auth=')
+  return isLoggedInCache
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+  isLoggedInCache = null
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)

.opencode/skill/vercel-react-best-practices/rules/js-cache-property-access.md

@@ -0,0 +1,28 @@
+---
+title: Cache Property Access in Loops
+impact: LOW-MEDIUM
+impactDescription: reduces lookups
+tags: javascript, loops, optimization, caching
+---
+
+## Cache Property Access in Loops
+
+Cache object property lookups in hot paths.
+
+**Incorrect (3 lookups × N iterations):**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+```
+
+**Correct (1 lookup total):**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```

.opencode/skill/vercel-react-best-practices/rules/js-cache-storage.md

@@ -0,0 +1,70 @@
+---
+title: Cache Storage API Calls
+impact: LOW-MEDIUM
+impactDescription: reduces expensive I/O
+tags: javascript, localStorage, storage, caching, performance
+---
+
+## Cache Storage API Calls
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect (reads storage on every call):**
+
+```typescript
+function getTheme() {
+  return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct (Map cache):**
+
+```typescript
+const storageCache = new Map<string, string | null>()
+
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value)  // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record<string, string> | null = null
+
+function getCookie(name: string) {
+  if (!cookieCache) {
+    cookieCache = Object.fromEntries(
+      document.cookie.split('; ').map(c => c.split('='))
+    )
+  }
+  return cookieCache[name]
+}
+```
+
+**Important (invalidate on external changes):**
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+```typescript
+window.addEventListener('storage', (e) => {
+  if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'visible') {
+    storageCache.clear()
+  }
+})
+```

.opencode/skill/vercel-react-best-practices/rules/js-combine-iterations.md

@@ -0,0 +1,32 @@
+---
+title: Combine Multiple Array Iterations
+impact: LOW-MEDIUM
+impactDescription: reduces iterations
+tags: javascript, arrays, loops, performance
+---
+
+## Combine Multiple Array Iterations
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect (3 iterations):**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct (1 iteration):**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```

.opencode/skill/vercel-react-best-practices/rules/js-early-exit.md

@@ -0,0 +1,50 @@
+---
+title: Early Return from Functions
+impact: LOW-MEDIUM
+impactDescription: avoids unnecessary computation
+tags: javascript, functions, optimization, early-return
+---
+
+## Early Return from Functions
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect (processes all items even after finding answer):**
+
+```typescript
+function validateUsers(users: User[]) {
+  let hasError = false
+  let errorMessage = ''
+  
+  for (const user of users) {
+    if (!user.email) {
+      hasError = true
+      errorMessage = 'Email required'
+    }
+    if (!user.name) {
+      hasError = true
+      errorMessage = 'Name required'
+    }
+    // Continues checking all users even after error found
+  }
+  
+  return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct (returns immediately on first error):**
+
+```typescript
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) {
+      return { valid: false, error: 'Email required' }
+    }
+    if (!user.name) {
+      return { valid: false, error: 'Name required' }
+    }
+  }
+
+  return { valid: true }
+}
+```

.opencode/skill/vercel-react-best-practices/rules/js-hoist-regexp.md

@@ -0,0 +1,45 @@
+---
+title: Hoist RegExp Creation
+impact: LOW-MEDIUM
+impactDescription: avoids recreation
+tags: javascript, regexp, optimization, memoization
+---
+
+## Hoist RegExp Creation
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect (new RegExp every render):**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+  const regex = new RegExp(`(${query})`, 'gi')
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Correct (memoize or hoist):**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+  const regex = useMemo(
+    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+    [query]
+  )
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Warning (global regex has mutable state):**
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+```typescript
+const regex = /foo/g
+regex.test('foo')  // true, lastIndex = 3
+regex.test('foo')  // false, lastIndex = 0
+```

.opencode/skill/vercel-react-best-practices/rules/js-index-maps.md

@@ -0,0 +1,37 @@
+---
+title: Build Index Maps for Repeated Lookups
+impact: LOW-MEDIUM
+impactDescription: 1M ops to 2K ops
+tags: javascript, map, indexing, optimization, performance
+---
+
+## Build Index Maps for Repeated Lookups
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  return orders.map(order => ({
+    ...order,
+    user: users.find(u => u.id === order.userId)
+  }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  const userById = new Map(users.map(u => [u.id, u]))
+
+  return orders.map(order => ({
+    ...order,
+    user: userById.get(order.userId)
+  }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+For 1000 orders × 1000 users: 1M ops → 2K ops.

.opencode/skill/vercel-react-best-practices/rules/js-length-check-first.md

@@ -0,0 +1,49 @@
+---
+title: Early Length Check for Array Comparisons
+impact: MEDIUM-HIGH
+impactDescription: avoids expensive operations when lengths differ
+tags: javascript, arrays, performance, optimization, comparison
+---
+
+## Early Length Check for Array Comparisons
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect (always runs expensive comparison):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Always sorts and joins, even when lengths differ
+  return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Early return if lengths differ
+  if (current.length !== original.length) {
+    return true
+  }
+  // Only sort/join when lengths match
+  const currentSorted = current.toSorted()
+  const originalSorted = original.toSorted()
+  for (let i = 0; i < currentSorted.length; i++) {
+    if (currentSorted[i] !== originalSorted[i]) {
+      return true
+    }
+  }
+  return false
+}
+```
+
+This new approach is more efficient because:
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+- It avoids mutating the original arrays
+- It returns early when a difference is found

.opencode/skill/vercel-react-best-practices/rules/js-min-max-loop.md

@@ -0,0 +1,82 @@
+---
+title: Use Loop for Min/Max Instead of Sort
+impact: LOW
+impactDescription: O(n) instead of O(n log n)
+tags: javascript, arrays, performance, sorting, algorithms
+---
+
+## Use Loop for Min/Max Instead of Sort
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+  id: string
+  name: string
+  updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+  return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+  return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+  if (projects.length === 0) return null
+  
+  let latest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt > latest.updatedAt) {
+      latest = projects[i]
+    }
+  }
+  
+  return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+  if (projects.length === 0) return { oldest: null, newest: null }
+  
+  let oldest = projects[0]
+  let newest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+    if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+  }
+  
+  return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative (Math.min/Math.max for small arrays):**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays but can be slower for very large arrays due to spread operator limitations. Use the loop approach for reliability.

.opencode/skill/vercel-react-best-practices/rules/js-set-map-lookups.md

@@ -0,0 +1,24 @@
+---
+title: Use Set/Map for O(1) Lookups
+impact: LOW-MEDIUM
+impactDescription: O(n) to O(1)
+tags: javascript, set, map, data-structures, performance
+---
+
+## Use Set/Map for O(1) Lookups
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```

.opencode/skill/vercel-react-best-practices/rules/js-tosorted-immutable.md

@@ -0,0 +1,57 @@
+---
+title: Use toSorted() Instead of sort() for Immutability
+impact: MEDIUM-HIGH
+impactDescription: prevents mutation bugs in React state
+tags: javascript, arrays, immutability, react, state, mutation
+---
+
+## Use toSorted() Instead of sort() for Immutability
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect (mutates original array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Mutates the users prop array!
+  const sorted = useMemo(
+    () => users.sort((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Correct (creates new array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Creates new sorted array, original unchanged
+  const sorted = useMemo(
+    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support (fallback for older browsers):**
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+- `.toReversed()` - immutable reverse
+- `.toSpliced()` - immutable splice
+- `.with()` - immutable element replacement

.opencode/skill/vercel-react-best-practices/rules/rendering-activity.md

@@ -0,0 +1,26 @@
+---
+title: Use Activity Component for Show/Hide
+impact: MEDIUM
+impactDescription: preserves state/DOM
+tags: rendering, activity, visibility, state-preservation
+---
+
+## Use Activity Component for Show/Hide
+
+Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Avoids expensive re-renders and state loss.

.opencode/skill/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md

@@ -0,0 +1,47 @@
+---
+title: Animate SVG Wrapper Instead of SVG Element
+impact: LOW
+impactDescription: enables hardware acceleration
+tags: rendering, svg, css, animation, performance
+---
+
+## Animate SVG Wrapper Instead of SVG Element
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
+
+**Incorrect (animating SVG directly - no hardware acceleration):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <svg 
+      className="animate-spin"
+      width="24" 
+      height="24" 
+      viewBox="0 0 24 24"
+    >
+      <circle cx="12" cy="12" r="10" stroke="currentColor" />
+    </svg>
+  )
+}
+```
+
+**Correct (animating wrapper div - hardware accelerated):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <div className="animate-spin">
+      <svg 
+        width="24" 
+        height="24" 
+        viewBox="0 0 24 24"
+      >
+        <circle cx="12" cy="12" r="10" stroke="currentColor" />
+      </svg>
+    </div>
+  )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.

.opencode/skill/vercel-react-best-practices/rules/rendering-conditional-render.md

@@ -0,0 +1,40 @@
+---
+title: Use Explicit Conditional Rendering
+impact: LOW
+impactDescription: prevents rendering 0 or NaN
+tags: rendering, conditional, jsx, falsy-values
+---
+
+## Use Explicit Conditional Rendering
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect (renders "0" when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count && <span className="badge">{count}</span>}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div>0</div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+**Correct (renders nothing when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count > 0 ? <span className="badge">{count}</span> : null}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div></div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```

.opencode/skill/vercel-react-best-practices/rules/rendering-content-visibility.md

@@ -0,0 +1,38 @@
+---
+title: CSS content-visibility for Long Lists
+impact: HIGH
+impactDescription: faster initial render
+tags: rendering, css, content-visibility, long-lists
+---
+
+## CSS content-visibility for Long Lists
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+  return (
+    <div className="overflow-y-auto h-screen">
+      {messages.map(msg => (
+        <div key={msg.id} className="message-item">
+          <Avatar user={msg.author} />
+          <div>{msg.content}</div>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).

.opencode/skill/vercel-react-best-practices/rules/rendering-hoist-jsx.md

@@ -0,0 +1,46 @@
+---
+title: Hoist Static JSX Elements
+impact: LOW
+impactDescription: avoids re-creation
+tags: rendering, jsx, static, optimization
+---
+
+## Hoist Static JSX Elements
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect (recreates element every render):**
+
+```tsx
+function LoadingSkeleton() {
+  return <div className="animate-pulse h-20 bg-gray-200" />
+}
+
+function Container() {
+  return (
+    <div>
+      {loading && <LoadingSkeleton />}
+    </div>
+  )
+}
+```
+
+**Correct (reuses same element):**
+
+```tsx
+const loadingSkeleton = (
+  <div className="animate-pulse h-20 bg-gray-200" />
+)
+
+function Container() {
+  return (
+    <div>
+      {loading && loadingSkeleton}
+    </div>
+  )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.

.opencode/skill/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md

@@ -0,0 +1,82 @@
+---
+title: Prevent Hydration Mismatch Without Flickering
+impact: MEDIUM
+impactDescription: avoids visual flicker and hydration errors
+tags: rendering, ssr, hydration, localStorage, flicker
+---
+
+## Prevent Hydration Mismatch Without Flickering
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
+
+**Incorrect (breaks SSR):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  // localStorage is not available on server - throws error
+  const theme = localStorage.getItem('theme') || 'light'
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect (visual flickering):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState('light')
+  
+  useEffect(() => {
+    // Runs after hydration - causes visible flash
+    const stored = localStorage.getItem('theme')
+    if (stored) {
+      setTheme(stored)
+    }
+  }, [])
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct (no flicker, no hydration mismatch):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <div id="theme-wrapper">
+        {children}
+      </div>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `
+            (function() {
+              try {
+                var theme = localStorage.getItem('theme') || 'light';
+                var el = document.getElementById('theme-wrapper');
+                if (el) el.className = theme;
+              } catch (e) {}
+            })();
+          `,
+        }}
+      />
+    </>
+  )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.

.opencode/skill/vercel-react-best-practices/rules/rendering-svg-precision.md

@@ -0,0 +1,28 @@
+---
+title: Optimize SVG Precision
+impact: LOW
+impactDescription: reduces file size
+tags: rendering, svg, optimization, svgo
+---
+
+## Optimize SVG Precision
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect (excessive precision):**
+
+```svg
+<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
+```
+
+**Correct (1 decimal place):**
+
+```svg
+<path d="M 10.3 20.8 L 30.9 40.2" />
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```

.opencode/skill/vercel-react-best-practices/rules/rerender-defer-reads.md

@@ -0,0 +1,39 @@
+---
+title: Defer State Reads to Usage Point
+impact: MEDIUM
+impactDescription: avoids unnecessary subscriptions
+tags: rerender, searchParams, localStorage, optimization
+---
+
+## Defer State Reads to Usage Point
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect (subscribes to all searchParams changes):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const searchParams = useSearchParams()
+
+  const handleShare = () => {
+    const ref = searchParams.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+**Correct (reads on demand, no subscription):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const handleShare = () => {
+    const params = new URLSearchParams(window.location.search)
+    const ref = params.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```

.opencode/skill/vercel-react-best-practices/rules/rerender-dependencies.md

@@ -0,0 +1,45 @@
+---
+title: Narrow Effect Dependencies
+impact: LOW
+impactDescription: minimizes effect re-runs
+tags: rerender, useEffect, dependencies, optimization
+---
+
+## Narrow Effect Dependencies
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect (re-runs on any user field change):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user])
+```
+
+**Correct (re-runs only when id changes):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+  if (width < 768) {
+    enableMobileMode()
+  }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+  if (isMobile) {
+    enableMobileMode()
+  }
+}, [isMobile])
+```

.opencode/skill/vercel-react-best-practices/rules/rerender-derived-state.md

@@ -0,0 +1,29 @@
+---
+title: Subscribe to Derived State
+impact: MEDIUM
+impactDescription: reduces re-render frequency
+tags: rerender, derived-state, media-query, optimization
+---
+
+## Subscribe to Derived State
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect (re-renders on every pixel change):**
+
+```tsx
+function Sidebar() {
+  const width = useWindowWidth()  // updates continuously
+  const isMobile = width < 768
+  return <nav className={isMobile ? 'mobile' : 'desktop'}>
+}
+```
+
+**Correct (re-renders only when boolean changes):**
+
+```tsx
+function Sidebar() {
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  return <nav className={isMobile ? 'mobile' : 'desktop'}>
+}
+```

.opencode/skill/vercel-react-best-practices/rules/rerender-functional-setstate.md

@@ -0,0 +1,74 @@
+---
+title: Use Functional setState Updates
+impact: MEDIUM
+impactDescription: prevents stale closures and unnecessary callback recreations
+tags: react, hooks, useState, useCallback, callbacks, closures
+---
+
+## Use Functional setState Updates
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect (requires state as dependency):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Callback must depend on items, recreated on every items change
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems([...items, ...newItems])
+  }, [items])  // ❌ items dependency causes recreations
+  
+  // Risk of stale closure if dependency is forgotten
+  const removeItem = useCallback((id: string) => {
+    setItems(items.filter(item => item.id !== id))
+  }, [])  // ❌ Missing items dependency - will use stale items!
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
+
+**Correct (stable callbacks, no stale closures):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Stable callback, never recreated
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems(curr => [...curr, ...newItems])
+  }, [])  // ✅ No dependencies needed
+  
+  // Always uses latest state, no stale closure risk
+  const removeItem = useCallback((id: string) => {
+    setItems(curr => curr.filter(item => item.id !== id))
+  }, [])  // ✅ Safe and stable
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+**Benefits:**
+
+1. **Stable callback references** - Callbacks don't need to be recreated when state changes
+2. **No stale closures** - Always operates on the latest state value
+3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
+4. **Prevents bugs** - Eliminates the most common source of React closure bugs
+
+**When to use functional updates:**
+
+- Any setState that depends on the current state value
+- Inside useCallback/useMemo when state is needed
+- Event handlers that reference state
+- Async operations that update state
+
+**When direct updates are fine:**
+
+- Setting state to a static value: `setCount(0)`
+- Setting state from props/arguments only: `setName(newName)`
+- State doesn't depend on previous value
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.

.opencode/skill/vercel-react-best-practices/rules/rerender-lazy-state-init.md

@@ -0,0 +1,58 @@
+---
+title: Use Lazy State Initialization
+impact: MEDIUM
+impactDescription: wasted computation on every render
+tags: react, hooks, useState, performance, initialization
+---
+
+## Use Lazy State Initialization
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
+
+**Incorrect (runs on every render):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs on EVERY render, even after initialization
+  const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  // When query changes, buildSearchIndex runs again unnecessarily
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs on every render
+  const [settings, setSettings] = useState(
+    JSON.parse(localStorage.getItem('settings') || '{}')
+  )
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+**Correct (runs only once):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs ONLY on initial render
+  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs only on initial render
+  const [settings, setSettings] = useState(() => {
+    const stored = localStorage.getItem('settings')
+    return stored ? JSON.parse(stored) : {}
+  })
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
+
+For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.

.opencode/skill/vercel-react-best-practices/rules/rerender-memo.md

@@ -0,0 +1,44 @@
+---
+title: Extract to Memoized Components
+impact: MEDIUM
+impactDescription: enables early returns
+tags: rerender, memo, useMemo, optimization
+---
+
+## Extract to Memoized Components
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+**Incorrect (computes avatar even when loading):**
+
+```tsx
+function Profile({ user, loading }: Props) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user)
+    return <Avatar id={id} />
+  }, [user])
+
+  if (loading) return <Skeleton />
+  return <div>{avatar}</div>
+}
+```
+
+**Correct (skips computation when loading):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user])
+  return <Avatar id={id} />
+})
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />
+  return (
+    <div>
+      <UserAvatar user={user} />
+    </div>
+  )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.

.opencode/skill/vercel-react-best-practices/rules/rerender-transitions.md

@@ -0,0 +1,40 @@
+---
+title: Use Transitions for Non-Urgent Updates
+impact: MEDIUM
+impactDescription: maintains UI responsiveness
+tags: rerender, transitions, startTransition, performance
+---
+
+## Use Transitions for Non-Urgent Updates
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect (blocks UI on every scroll):**
+
+```tsx
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+**Correct (non-blocking updates):**
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```

.opencode/skill/vercel-react-best-practices/rules/server-after-nonblocking.md

@@ -0,0 +1,73 @@
+---
+title: Use after() for Non-Blocking Operations
+impact: MEDIUM
+impactDescription: faster response times
+tags: server, async, logging, analytics, side-effects
+---
+
+## Use after() for Non-Blocking Operations
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect (blocks response):**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Logging blocks the response
+  const userAgent = request.headers.get('user-agent') || 'unknown'
+  await logUserAction({ userAgent })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent') || 'unknown'
+    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+    
+    logUserAction({ sessionCookie, userAgent })
+  })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+- Audit logging
+- Sending notifications
+- Cache invalidation
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)

.opencode/skill/vercel-react-best-practices/rules/server-cache-lru.md

@@ -0,0 +1,41 @@
+---
+title: Cross-Request LRU Caching
+impact: HIGH
+impactDescription: caches across requests
+tags: server, cache, lru, cross-request
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)

.opencode/skill/vercel-react-best-practices/rules/server-cache-react.md

@@ -0,0 +1,26 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.

.opencode/skill/vercel-react-best-practices/rules/server-parallel-fetching.md

@@ -0,0 +1,79 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Layout({ children }: { children: ReactNode }) {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      {children}
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```

.opencode/skill/vercel-react-best-practices/rules/server-serialization.md

@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```

.opencode/skill/web-design-guidelines/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
+argument-hint: <file-or-pattern>
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Web Interface Guidelines
+
+Review files for compliance with Web Interface Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.

.vscode/settings.json

@@ -3,7 +3,8 @@
   "editor.formatOnSave": true,
   "editor.defaultFormatter": "biomejs.biome",
   "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": "explicit"
+    "source.fixAll.biome": "explicit",
+    "source.organizeImports.biome": "explicit"
   },
   "typescript.preferences.importModuleSpecifier": "non-relative",
   "spellright.language": ["en"],

.yarnrc.yml

@@ -4,4 +4,10 @@ enableGlobalCache: false
 
 nodeLinker: node-modules
 
+# fast-xml-parser 4.4.1 via @boxyhq/saml-jackson → @aws-sdk/core@3.816.0 (transitive).
+# Only parses trusted AWS API responses, not user input. No practical attack vector.
+# Upstream fix pending: ory/polis (saml-jackson) has bumped to @aws-sdk@3.994.0 on main but hasn't released yet.
+npmAuditIgnoreAdvisories:
+  - "1113407"
+
 yarnPath: .yarn/releases/yarn-4.12.0.cjs

AGENTS.md

@@ -12,11 +12,12 @@ You are a senior Cal.com engineer working in a Yarn/Turbo monorepo. You prioriti
 - Create PRs in draft mode by default
 - Run `yarn type-check:ci --force` before concluding CI failures are unrelated to your changes
 - Import directly from source files, not barrel files (e.g., `@calcom/ui/components/button` not `@calcom/ui`)
-- Add translations to `apps/web/public/static/locales/en/common.json` for all UI strings
+- Add translations to `packages/i18n/locales/en/common.json` for all UI strings
 - Use `date-fns` or native `Date` instead of Day.js when timezone awareness isn't needed
 - Put permission checks in `page.tsx`, never in `layout.tsx`
 - Use `ast-grep` for searching if available; otherwise use `rg` (ripgrep), then fall back to `grep`
 - Use Biome for formatting and linting
+- Only add code comments that explain **why**, not **what** — see [code comment guidelines](agents/rules/quality-code-comments.md)
 
 
 ## Don't
@@ -29,63 +30,60 @@ You are a senior Cal.com engineer working in a Yarn/Turbo monorepo. You prioriti
 - Never use barrel imports from index.ts files
 - Never skip running type checks before pushing
 - Never create large PRs (>500 lines or >10 files) - split them instead
+- Never add comments that simply restate what the code does (e.g., `// Get the user` above a `getUser()` call)
+
+## PR Size Guidelines
+
+Large PRs are difficult to review, prone to errors, and slow down the development process. Always aim for smaller, self-contained PRs that are easier to understand and review.
+
+### Size Limits
+
+- **Lines changed**: Keep PRs under 500 lines of code (additions + deletions)
+- **Files changed**: Keep PRs under 10 code files
+- **Single responsibility**: Each PR should do one thing well
+
+**Note**: These limits apply to code files only. Non-code files like documentation (README.md, CHANGELOG.md), lock files (yarn.lock, package-lock.json), and auto-generated files are excluded from the count.
+
+### How to Split Large Changes
+
+When a task requires extensive changes, break it into multiple PRs:
+
+1. **By layer**: Separate database/schema changes, backend logic, and frontend UI into different PRs
+2. **By feature component**: Split a feature into its constituent parts (e.g., API endpoint PR, then UI PR, then integration PR)
+3. **By refactor vs feature**: Do preparatory refactoring in a separate PR before adding new functionality
+4. **By dependency order**: Create PRs in the order they can be merged (base infrastructure first, then features that depend on it)
+
+### Examples of Good PR Splits
+
+**Instead of one large "Add booking notifications" PR:**
+- PR 1: Add notification preferences schema and migration
+- PR 2: Add notification service and API endpoints
+- PR 3: Add notification UI components
+- PR 4: Integrate notifications into booking flow
+
+**Instead of one large "Refactor calendar sync" PR:**
+- PR 1: Extract calendar sync logic into dedicated service
+- PR 2: Add new calendar provider abstraction
+- PR 3: Migrate existing providers to new abstraction
+- PR 4: Add new calendar provider support
+
+### Benefits of Smaller PRs
+
+- Faster review cycles and quicker feedback
+- Easier to identify and fix issues
+- Lower risk of merge conflicts
+- Simpler to revert if problems arise
+- Better git history and easier debugging
 
 ## Commands
 
-### File-scoped (preferred for speed)
+See [agents/commands.md](agents/commands.md) for full reference. Key commands:
 
 ```bash
-# Type check - always run on changed files
-yarn type-check:ci --force
-
-# Lint and format single file
-yarn biome check --write path/to/file.tsx
-
-# Unit test specific file
-yarn vitest run path/to/file.test.ts
-
-# Unit test specific file + specific test
-yarn vitest run path/to/file.test.ts --testNamePattern="specific test name"
-
-# Integration test specific file
-yarn test path/to/file.integration-test.ts -- --integrationTestsOnly
-
-# Integration test specific file + specific test
-yarn test path/to/file.integration-test.ts --testNamePattern="specific test name" -- --integrationTestsOnly
-
-# E2E test specific file
-PLAYWRIGHT_HEADLESS=1 yarn e2e path/to/file.e2e.ts
-
-# E2E test specific file + specific test
-PLAYWRIGHT_HEADLESS=1 yarn e2e path/to/file.e2e.ts --grep "specific test name"
-```
-
-### Project-wide (use sparingly)
-
-```bash
-# Development
-yarn dev              # Start dev server
-yarn dx               # Dev with database setup
-
-# Build & check
-yarn build                   # Build all packages
-yarn biome check --write .   # Lint and format all
-yarn type-check              # Type check all
-
-# Tests (use TZ=UTC for consistency)
-TZ=UTC yarn test      # All unit tests
-yarn e2e              # All E2E tests
-
-# Database
-yarn prisma generate  # Regenerate types after schema changes
-yarn workspace @calcom/prisma db-migrate  # Run migrations
-```
-
-### Biome focused workflow
-+
-```bash
-yarn biome check --write .
-yarn type-check:ci --force
+yarn type-check:ci --force  # Type check (always run before pushing)
+yarn biome check --write .  # Lint and format
+TZ=UTC yarn test            # Run unit tests
+yarn prisma generate        # Regenerate types after schema changes
 ```
 
 
@@ -128,7 +126,7 @@ packages/lib/                # Shared utilities
 - Routes: `apps/web/app/` (App Router)
 - Database schema: `packages/prisma/schema.prisma`
 - tRPC routers: `packages/trpc/server/routers/`
-- Translations: `apps/web/public/static/locales/en/common.json`
+- Translations: `packages/i18n/locales/en/common.json`
 - Workflow constants: `packages/features/ee/workflows/lib/constants.ts`
 
 ## Tech Stack
@@ -154,7 +152,7 @@ throw new Error(`Unable to create booking: User ${userId} has no available time
 throw new Error("Booking failed");
 ```
 
-For which error class to use (`ErrorWithCode` vs `TRPCError`) and concrete examples, see [Error Types in knowledge-base.md](agents/knowledge-base.md#error-types).
+For which error class to use (`ErrorWithCode` vs `TRPCError`) and concrete examples, see [quality-error-handling](agents/rules/quality-error-handling.md).
 
 ### Good Prisma query
 
@@ -228,11 +226,19 @@ import { ProfileRepository } from "@calcom/features/profile/repositories/Profile
 - Fix type errors before test failures - they're often the root cause
 - Run `yarn prisma generate` if you see missing enum/type errors
 
+## Spec-Driven Development (Opt-In)
+
+For complex features, you can use spec-driven development when explicitly requested.
+
+**To enable:** Tell the AI "use spec-driven development" or "follow the spec workflow"
+
+See [SPEC-WORKFLOW.md](SPEC-WORKFLOW.md) for the full workflow documentation.
+
 ## Extended Documentation
 
 For detailed information, see the `agents/` directory:
 
-- **[agents/README.md](agents/README.md)** - Architecture overview and patterns
+- **[agents/README.md](agents/README.md)** - Rules index and architecture overview
+- **[agents/rules/](agents/rules/)** - Modular engineering rules
 - **[agents/commands.md](agents/commands.md)** - Complete command reference
-- **[agents/knowledge-base.md](agents/knowledge-base.md)** - Domain knowledge and best practices
-- **[agents/coding-standards.md](agents/coding-standards.md)** - Coding standards with examples
+- **[agents/knowledge-base.md](agents/knowledge-base.md)** - Domain knowledge and business rules

CONTRIBUTING.md

@@ -190,6 +190,22 @@ If you get errors, be sure to fix them before committing.
 
 ## Making a Pull Request
 
+### Keep PRs Small and Focused
+
+Large PRs are difficult to review and more prone to errors. We strongly encourage smaller, self-contained PRs:
+
+- **Size limits**: Keep PRs under 500 lines of code changed and under 10 code files modified (excludes documentation, lock files, and auto-generated files)
+- **Single responsibility**: Each PR should address one concern (one feature, one bug fix, or one refactor)
+- **Split large changes**: If your task requires extensive changes, break it into multiple PRs that can be reviewed and merged independently
+
+**How to split large changes:**
+- Separate database/schema changes from application logic
+- Split frontend and backend changes when possible
+- Do preparatory refactoring in a separate PR before adding new features
+- Create PRs in dependency order (infrastructure first, then features)
+
+### PR Checklist
+
 - Be sure to [check the "Allow edits from maintainers" option](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) when creating your PR. (This option isn't available if you're [contributing from a fork belonging to an organization](https://github.com/orgs/community/discussions/5634))
 - If your PR refers to or fixes an issue, add `refs #XXX` or `fixes #XXX` to the PR description. Replace `XXX` with the respective issue number. See more about [linking a pull request to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
 - Fill out the PR template accordingly.

README.md

@@ -123,7 +123,7 @@ Here is what you need to be able to run Cal.com.
 
 ### Setup
 
-1. Clone the repo into a public GitHub repository (or fork https://github.com/calcom/cal.com/fork). If you plan to distribute the code, keep the source code public to comply with [AGPLv3](https://github.com/calcom/cal.com/blob/main/LICENSE). To clone in a private repository, [acquire a commercial license](https://cal.com/sales)
+1. Clone the repo (or fork https://github.com/calcom/cal.com/fork). The code is licensed under [AGPLv3](https://github.com/calcom/cal.com/blob/main/LICENSE), which requires you to provide source code to users who interact with the software over a network. For commercial use without these requirements, [acquire a commercial license](https://cal.com/sales)
 
    ```sh
    git clone https://github.com/calcom/cal.com.git
@@ -149,6 +149,13 @@ Here is what you need to be able to run Cal.com.
    - Duplicate `.env.example` to `.env`
    - Use `openssl rand -base64 32` to generate a key and add it under `NEXTAUTH_SECRET` in the `.env` file.
    - Use `openssl rand -base64 24` to generate a key and add it under `CALENDSO_ENCRYPTION_KEY` in the `.env` file.
+     
+ > **Windows users:** Replace the `packages/prisma/.env` symlink with a real copy to avoid a Prisma error (`unexpected character / in variable name`):
+ >
+ > ```sh
+ > # Git Bash / WSL
+ > rm packages/prisma/.env && cp .env packages/prisma/.env
+ > ```
 
 5. Setup Node
    If your Node version does not meet the project's requirements as instructed by the docs, "nvm" (Node Version Manager) allows using Node at the version required by the project:
@@ -384,6 +391,50 @@ Executable doesn't exist at /Users/alice/Library/Caches/ms-playwright/chromium-1
    ```
 
 1. Enjoy the new version.
+
+## AI-Assisted Development
+
+This repository includes configuration for AI coding assistants. All AI configuration lives in the `agents/` directory as a single source of truth.
+
+### Structure
+
+```
+agents/
+├── rules/           # Modular engineering rules
+├── skills/          # Reusable skills/prompts
+├── commands.md      # Command reference
+└── knowledge-base.md # Domain knowledge
+
+AGENTS.md            # Main agent instructions
+```
+
+### Tool Configuration
+
+We use symlinks to share configuration across tools:
+
+```
+.claude/
+├── rules -> ../agents/rules
+└── skills -> ../agents/skills
+
+.cursor/
+├── rules -> ../agents/rules
+└── skills -> ../agents/skills
+```
+
+### Using Other Tools
+
+If you prefer other AI tools (Windsurf, Goose, OpenCode, etc.), you can create your own dot folders and exclude them from git:
+
+```bash
+# Add to .git/info/exclude (local only, not committed)
+.windsurf/
+.goose/
+.opencode/
+```
+
+This keeps the repository clean while allowing personal tool preferences.
+
 <!-- DEPLOYMENT -->
 
 ## Deployment
@@ -627,7 +678,7 @@ Certain versions may have trouble creating a user if the field `metadata` is emp
 
 ##### CLIENT_FETCH_ERROR
 
-If you experience this error, it may be the way the default Auth callback in the server is using the WEBAPP_URL as a base url. The container does not necessarily have access to the same DNS as your local machine, and therefor needs to be configured to resolve to itself. You may be able to correct this by configuring `NEXTAUTH_URL=http://localhost:3000/api/auth`, to help the backend loop back to itself.
+If you experience this error, it may be the way the default Auth callback in the server is using the WEBAPP_URL as a base url. The container does not necessarily have access to the same DNS as your local machine, and therefore needs to be configured to resolve to itself. You may be able to correct this by configuring `NEXTAUTH_URL=http://localhost:3000/api/auth`, to help the backend loop back to itself.
 
 ```
 docker-calcom-1  | @calcom/web:start: [next-auth][error][CLIENT_FETCH_ERROR]
@@ -723,11 +774,14 @@ Cal.com, Inc. is a commercial open source company, which means some parts of thi
 
 <img width="100%" src="https://repobeats.axiom.co/api/embed/6bfca2f20f39738048b6e70ca205efde46352c3d.svg" />
 
-<!-- CONTRIBUTING -->
-
 ## Contributing
+We ❤️ contributions! Whether it’s fixing a typo, improving documentation, or building new features, your help makes Cal.com better.
 
-Please see our [contributing guide](/CONTRIBUTING.md).
+- Check out our [Contributing Guide](./CONTRIBUTING.md) for detailed steps.
+- Join the discussion on [GitHub Discussions](https://github.com/calcom/cal.com/discussions) or our community channels.
+- Please follow our coding standards and commit message conventions to keep the project consistent.
+
+Even small improvements matter — thank you for helping us grow!
 
 ### Good First Issues
 
@@ -888,6 +942,19 @@ following
 
 [Follow these steps](./packages/app-store/pipedrive-crm/)
 
+### Rate Limiting with Unkey
+
+Cal.com uses [Unkey](https://unkey.com) for rate limiting. This is an optional feature and is not required for testing or self-hosting.
+
+If you want to enable rate limiting:
+
+1. Sign up for an account at [unkey.com](https://unkey.com)
+2. Create a Root key with permissions for 
+   `ratelimit.create_namespace` and `ratelimit.limit`
+3. Copy the root key to your `.env` file into the `UNKEY_ROOT_KEY` field
+
+Note: If you don't configure Unkey, Cal.com will work normally without rate limiting enabled.
+
 ## Workflows
 
 ### Setting up SendGrid for Email reminders
@@ -927,12 +994,6 @@ An example of good readme is [atoms readme](https://github.com/calcom/cal.com/bl
 1. Follow semantic versioning when using changesets.
 2. Mark breaking changes using `❗️Breaking change`
 
-<!-- LICENSE -->
-
-## License
-
-Distributed under the [AGPLv3 License](https://github.com/calcom/cal.com/blob/main/LICENSE). See `LICENSE` for more information.
-
 <!-- ACKNOWLEDGEMENTS -->
 
 ## Acknowledgements

SPEC-WORKFLOW.md

@@ -0,0 +1,105 @@
+# Spec-Driven Development Workflow
+
+This workflow is **opt-in**. Use it when explicitly requested by saying "use spec-driven development" or "follow the spec workflow".
+
+## Design Documents
+
+The `specs/` folder contains design documents for features in development.
+
+Each spec follows this structure:
+
+```
+specs/{feature}/
+├── CLAUDE.md           # Feature-specific instructions (read this first)
+├── design.md           # The specification
+├── implementation.md   # Current status and what's done
+├── decisions.md        # Why decisions were made
+├── prompts.md          # Reusable prompts
+├── future-work.md      # What's deferred
+└── docs/               # Documentation with screenshots
+```
+
+**Workflow:**
+
+1. Read the spec's `CLAUDE.md` for specific instructions
+2. Read `design.md` to understand what we're building
+3. Check `implementation.md` for current status
+4. Find the relevant code in the codebase
+5. Implement in small pieces, update `implementation.md` after each
+
+---
+
+## When Implementing Features (Spec Mode)
+
+1. **Check for design doc** in `specs/` — if it exists, follow it
+2. **If no spec exists** — ask if you should create one first
+3. **Look at existing patterns** — find similar code and follow conventions
+4. **Update implementation.md** — mark what's done after each piece
+5. **Update decisions.md** — when choosing between approaches
+
+---
+
+## Creating a New Spec
+
+When user asks to build a new feature:
+
+1. Copy the template: `cp -r specs/_templates specs/{feature-name}`
+2. Explore the codebase to understand existing patterns
+3. Write `design.md` with technical spec
+4. Write `CLAUDE.md` with feature-specific instructions
+5. Initialize `implementation.md` with "not-started" status
+6. Ask user to review before implementing
+
+---
+
+## Updating Spec Files
+
+### implementation.md — After completing each piece:
+
+```markdown
+## Status: in-progress
+
+## Completed
+- [x] Database schema
+- [x] Migration file
+
+## In Progress
+- tRPC endpoints
+
+## Next Steps
+1. UI components
+2. Tests
+
+## Session Notes
+### 2024-01-15
+- Done: Added schema, created migration
+- Next: Implement tRPC router
+```
+
+### decisions.md — When choosing between approaches:
+
+```markdown
+## ADR-001: Use Separate Table for Custom Locations
+
+### Context
+Need to store user-defined locations.
+
+### Options
+1. JSON field — simpler, but harder to query
+2. Separate table — more flexible, better indexing
+
+### Decision
+Separate table for better querying.
+
+### Consequences
+- Need migration
+- Need new tRPC router
+```
+
+---
+
+## Don't (When Using Spec-Driven Development)
+
+- Don't implement features without checking for a design doc first
+- Don't skip updating implementation.md after completing work
+- Don't make architectural decisions without recording them in decisions.md

agents/README.md

@@ -1,82 +1,78 @@
-# Cal.com Development Guide for AI Agents
+# Cal.com Agent Documentation Index
 
-This directory contains comprehensive documentation for AI agents working on the Cal.com codebase.
+- **[../AGENTS.md](../AGENTS.md)** - Main guide (structure, tech stack, commands, examples)
+- **[commands.md](commands.md)** - Command reference
+- **[knowledge-base.md](knowledge-base.md)** - Domain knowledge and business rules
 
-## Quick Navigation
+## Rules Index
 
-- **[Commands](commands.md)** - Build, test, and development commands
-- **[Knowledge Base](knowledge-base.md)** - Knowledge base & best practices
-- **[Architecture Overview](#architecture-overview)** - System structure and patterns
+### Architecture
 
-## Getting Started
+- [architecture-vertical-slices](rules/architecture-vertical-slices.md) - Vertical slice architecture
+- [architecture-feature-boundaries](rules/architecture-feature-boundaries.md) - Feature boundaries
+- [architecture-page-level-auth](rules/architecture-page-level-auth.md) - Auth in page.tsx, not layout.tsx
+- [architecture-features-modules](rules/architecture-features-modules.md) - packages/features vs apps/web/modules
 
-Cal.com is a monorepo using Yarn workspaces and Turbo for build orchestration. The main application is in `apps/web/` with shared packages in `packages/`.
+### Quality
 
-### Key Directories
+- [quality-avoid-barrel-imports](rules/quality-avoid-barrel-imports.md) - Avoid index.ts barrel imports
+- [quality-simplicity](rules/quality-simplicity.md) - Keep code simple
+- [quality-no-followup-prs](rules/quality-no-followup-prs.md) - Complete work in PR
+- [quality-thorough-code-review](rules/quality-thorough-code-review.md) - Code review standards
+- [quality-error-handling](rules/quality-error-handling.md) - ErrorWithCode vs TRPCError
+- [quality-imports](rules/quality-imports.md) - Import patterns and named exports
+- [quality-pr-creation](rules/quality-pr-creation.md) - PR best practices
+- [quality-code-comments](rules/quality-code-comments.md) - Comment guidelines
+- [quality-code-review](rules/quality-code-review.md) - Code review focus
 
-- `apps/web/` - Main Next.js application
-- `packages/prisma/` - Database schema and migrations
-- `packages/trpc/` - API layer using tRPC
-- `packages/ui/` - Shared UI components
-- `packages/features/` - Feature-specific code
-- `packages/app-store/` - Third-party app integrations
+### Data Layer
 
-## Architecture Overview
+- [data-prefer-select-over-include](rules/data-prefer-select-over-include.md) - Use select in Prisma queries
+- [data-repository-pattern](rules/data-repository-pattern.md) - Repository pattern
+- [data-repository-methods](rules/data-repository-methods.md) - Repository method standards
+- [data-dto-boundaries](rules/data-dto-boundaries.md) - DTO boundaries
+- [data-prisma-migrations](rules/data-prisma-migrations.md) - Schema changes and migrations
+- [data-prisma-feature-flags](rules/data-prisma-feature-flags.md) - Feature flag seeding
 
-### Database Layer
+### API
 
-- **Prisma ORM** with PostgreSQL
-- Schema in `packages/prisma/schema.prisma`
-- Always use `select` instead of `include` for better performance
-- Never expose `credential.key` field in API responses
-
-### API Layer
-
-- **tRPC** for type-safe APIs
-- Routers in `packages/trpc/server/routers/`
-- Authentication handled via NextAuth.js
-
-### Frontend
-
-- **Next.js 13+** with App Router in some areas
-- **React 18** with TypeScript
-- **Tailwind CSS** for styling
-- Internationalization with `next-i18next`
-
-## Common Patterns
-
-### Error Handling
-
-- Use early returns to reduce nesting
-- Throw descriptive errors with proper error codes
-- Prefer composition over prop drilling
+- [api-no-breaking-changes](rules/api-no-breaking-changes.md) - API stability
+- [api-thin-controllers](rules/api-thin-controllers.md) - Thin controller pattern
 
 ### Performance
 
-- Avoid O(n²) logic in backend code
-- Minimize Day.js usage in performance-critical paths
-- Use `select` queries to only fetch needed data
-- Consider using `.utc()` for Day.js operations
+- [performance-avoid-quadratic](rules/performance-avoid-quadratic.md) - Avoid O(n²) algorithms
+- [performance-dayjs-usage](rules/performance-dayjs-usage.md) - Day.js optimization
+- [performance-scheduling-complexity](rules/performance-scheduling-complexity.md) - Scheduling performance
 
-### Security
+### Testing
 
-- Never commit secrets or API keys
-- Always validate input data
-- Use proper authentication checks
-- Never expose sensitive credential fields
+- [testing-coverage-requirements](rules/testing-coverage-requirements.md) - Test coverage standards
+- [testing-playwright](rules/testing-playwright.md) - Playwright test execution
+- [testing-mocking](rules/testing-mocking.md) - Mock services and integrations
+- [testing-timezone](rules/testing-timezone.md) - Timezone handling (TZ=UTC)
+- [testing-incremental](rules/testing-incremental.md) - Incremental test fixing
 
-## Testing Strategy
+### CI/CD
 
-- **Unit tests** with Vitest
-- **Integration tests** for complex workflows
-- **E2E tests** with Playwright
-- Test files use `.test.ts` or `.spec.ts` extensions
+- [ci-check-failures](rules/ci-check-failures.md) - Handling CI failures
+- [ci-type-check-first](rules/ci-type-check-first.md) - Type-check before tests
+- [ci-git-workflow](rules/ci-git-workflow.md) - Git and CI workflow
 
-## Pull Request Guidelines
+### Patterns
 
-For large PRs (>500 lines or >10 files):
+- [patterns-dependency-injection](rules/patterns-dependency-injection.md) - DI patterns
+- [patterns-factory-pattern](rules/patterns-factory-pattern.md) - Factory pattern
+- [patterns-workflow-triggers](rules/patterns-workflow-triggers.md) - Workflow implementation
+- [patterns-app-store](rules/patterns-app-store.md) - App store integration patterns
+- [patterns-trigger-dev](rules/patterns-trigger-dev.md) - Trigger.dev task implementation
 
-- Split by feature boundaries
-- Separate database migrations, backend logic, frontend components
-- Create dependency chains that can be merged sequentially
-- Pattern: Database → Backend → Frontend → Tests
+### Culture
+
+- [culture-accountability](rules/culture-accountability.md) - Engineering accountability
+- [culture-leverage-ai](rules/culture-leverage-ai.md) - AI tooling practices
+
+### Reference
+
+- [reference-file-locations](rules/reference-file-locations.md) - Key file paths
+- [reference-local-dev](rules/reference-local-dev.md) - Local development setup

agents/coding-standards.md

@@ -1,62 +0,0 @@
-# Coding Standards & Best Practices
-
-
-
-## Import Guidelines
-
-### Type Imports
-
-```typescript
-// ✅ Good - Use type imports for TypeScript types
-import type { User } from "@prisma/client";
-import type { NextApiRequest, NextApiResponse } from "next";
-
-// ❌ Bad - Regular import for types
-import { User } from "@prisma/client";
-```
-
-
-
-## Code Structure
-
-### Early Returns
-
-- Prefer early returns to reduce nesting: `if (!booking) return null;`
-
-### Composition Over Prop Drilling
-
-- Use React children and context instead of passing props through multiple components
-
-### ORM and Types
-
-- Never import `@calcom/prisma/client` in features, services, UI, or handlers.
-- Use repository DTOs or domain types instead.
-- See "Repository + DTO Pattern and Method Conventions" in the knowledge base for details and examples.
-
-### Security Rules
-
-```typescript
-// ❌ NEVER expose credential keys
-const user = await prisma.user.findFirst({
-  select: {
-    credentials: {
-      select: {
-        key: true, // ❌ NEVER do this
-      }
-    }
-  }
-});
-
-// ✅ Good - Never select credential.key field
-const user = await prisma.user.findFirst({
-  select: {
-    credentials: {
-      select: {
-        id: true,
-        type: true,
-        // key field is excluded for security
-      }
-    }
-  }
-});
-```

agents/commands.md

@@ -34,9 +34,9 @@
 
 ### Integration Tests
 
-- `yarn test -- --integrationTestsOnly` - Run integration tests (vitest)
-- `yarn test <filename> -- --integrationTestsOnly` - Run integration tests for specific file
-- `yarn test <filename> -t "<testName>" -- --integrationTestsOnly` - Run specific integration test by name for specific file
+- `VITEST_MODE=integration yarn test` - Run integration tests (vitest)
+- `VITEST_MODE=integration yarn test <filename>` - Run integration tests for specific file
+- `VITEST_MODE=integration yarn test <filename> -t "<testName>"` - Run specific integration test by name for specific file
 
 
 ### End-to-End Tests
@@ -73,7 +73,7 @@
 yarn vitest run packages/lib/some-file.test.ts
 
 # Integration test specific file
-yarn test routing-form-response-denormalized.integration-test.ts -- --integrationTestsOnly
+VITEST_MODE=integration yarn test routing-form-response-denormalized.integration-test.ts
 
 # E2E test specific file
 yarn e2e tests/booking-flow.e2e.ts

agents/knowledge-base.md

@@ -1,738 +1,94 @@
-# Knowledge Base - Product & Domain-Specific Information
+# Knowledge Base - Domain & Product-Specific Information
 
-## Repo note for calcom/cal.com
+This file contains domain knowledge about the Cal.com product and codebase. For coding guidelines and rules, see [`rules/`](rules/).
 
-The whole thing is a monorepo. You need to be working in the apps/web folder.
+## When working with managed event types
 
-Linting and Formatting
-- Run lint with report generation: `yarn lint:report`
-- Run type checking: `yarn type-check:ci --force`
-- Run auto-fix: `yarn lint -- --fix`
+When a managed event type is created, we create:
+- A **parent managed event type** for the team (has `teamId` set in EventType table)
+- A **child managed event type** for each assigned user (has `userId` set in EventType table)
 
-Development
-- Install dependencies: `yarn`
-- Set up environment:
-  - Copy `.env.example` to `.env`
-  - Generate NEXTAUTH_SECRET with `openssl rand -base64 32`
-  - Generate CALENDSO_ENCRYPTION_KEY with `openssl rand -base64 24` (must be 32 characters for AES256)
-  - Configure Postgres database URL in `.env`
-  - Set DATABASE_DIRECT_URL to the same value as DATABASE_URL
+Example: If we create a managed event type and assign Alice and Bob, three rows will be inserted in the EventType table (1 parent + 2 children).
 
-Database Setup
-- Development: `yarn workspace @calcom/prisma db-migrate`
-- Production: `yarn workspace @calcom/prisma db-deploy`
+**Important**: Only child managed event types can be booked.
 
-When setting up local development database, it'll create a bunch of users for you. The passwords are the same as the username. e.g. 'free:free' and 'pro:pro'
+## When working with organizations and teams
 
-PR Requirements
-- PR title must follow Conventional Commits specification
-- For most PRs, you only need to run linting and type checking
-- E2E tests will only run if PR has "ready-for-e2e" label
+Both organizations and teams are stored in the `Team` table:
+- **Organizations**: Have `isOrganization` set to `true`
+- **Teams within an organization**: Have `parentId` set (pointing to the organization)
 
-Logging
-- Control logging verbosity by setting `NEXT_PUBLIC_LOGGER_LEVEL` in .env:
-  - 0: silly
-  - 1: trace
-  - 2: debug
-  - 3: info
-  - 4: warn
-  - 5: error
-  - 6: fatal
+## When working with OAuth clients
 
-## When addressing issues in the Cal.com repository
+There are two types of OAuth clients:
 
-When working on the Cal.com repository, prioritize fixing type issues before addressing failing tests. Running `yarn type-check:ci --force` to identify and fix TypeScript errors should be done first, as these errors are often the root cause of test failures. Only after resolving type issues should you move on to fixing failing tests with `TZ=UTC yarn test`.
+| Type | Table | Purpose |
+|------|-------|---------|
+| OAuth client | `OAuthClient` | Allows 3rd party apps to connect users' cal.com accounts |
+| Platform OAuth client | `PlatformOAuthClient` | Used by platform customers integrating cal.com scheduling directly in their platforms |
 
-## When creating pull requests
+If someone says "platform OAuth client" they mean the one in the `PlatformOAuthClient` table.
 
-Create pull requests in draft mode by default, so that actual human can mark it as ready for review only when it is.
+## When you need product or codebase context
 
-## When developing Playwright tests in the Cal.com repository
+### Monorepo Structure
 
-Always ensure Playwright tests pass locally before pushing code. The user requires fast local e2e feedback loops instead of relying on CI, which is too slow for development iteration. Never push test code until those tests are passing locally first.
+The whole repository is a monorepo. The main web app is in `apps/web` folder.
 
-## When fixing failing tests in the Cal.com repository
+### Local Development Database
 
-When fixing failing tests in the Cal.com repository, take an incremental approach by addressing one file at a time rather than attempting to fix all issues simultaneously. This methodical approach makes it easier to identify and resolve specific issues without getting overwhelmed by the complexity of multiple failing tests across different files. Focus on getting each file's tests passing completely before moving on to the next file.
+When setting up local development database, it creates test users. The passwords are the same as the username:
+- `free:free`
+- `pro:pro`
 
-To identify and fix issues in the Cal.com codebase:
+### Logging Levels
 
-1. Run `yarn type-check:ci --force` to identify TypeScript type errors and get fresh results always, bypassing any caching issues
-2. Run `yarn test` to identify failing unit tests
-3. Address both type errors and failing tests before considering the task complete
-4. Type errors often need to be fixed first as they may be causing the test failures
+Control logging verbosity by setting `NEXT_PUBLIC_LOGGER_LEVEL` in .env:
+- 0: silly
+- 1: trace
+- 2: debug
+- 3: info
+- 4: warn
+- 5: error
+- 6: fatal
 
-## When implementing mock services in the Cal.com test files
+### Cal.com Event Identification
 
-When mocking calendar services in Cal.com test files, implement the Calendar interface rather than adding individual properties from each specific calendar service type (like FeishuCalendarService). Since all calendar services implement the Calendar interface and are stored in a map, the mock service should also implement this interface to ensure type compatibility. This approach is more maintainable than trying to add all properties from each specific calendar service implementation. For complex mocks that cause type compatibility issues with deep mocks, consider using simpler fake implementations that directly implement the required interfaces instead of trying to match all properties of the original service classes. When needed, you can modify other mock files to support your implementation rather than trying to force compatibility with existing mocks.
+Cal.com events in Google Calendar can be identified by checking if the iCalUID ends with `@Cal.com` (e.g., `2GBXSdEixretciJfKVmYN8@Cal.com`). This identifier is used to distinguish Cal.com bookings from other calendar events for data storage and privacy purposes.
 
-## When implementing mocks for Cal.com app-store integrations
+### UI Component Locations
 
-When mocking app-store resources in Cal.com tests, prefer implementing simpler mock designs that directly implement the required interfaces rather than trying to match complex deep mock structures created with mockDeep. This approach is more maintainable and helps resolve type compatibility issues. The user encourages creative solutions and refactoring to better designs when the standard mocking approach causes persistent type errors.
+- Event types page: `apps/web/modules/event-types/views/event-types-listing-view.tsx`
+- Bookings page: `apps/web/modules/bookings/views/bookings-view.tsx`
+- Shared elements (tabs, search bars, filter buttons) should maintain consistent alignment across views
 
-## When implementing workflow triggers in the Cal.com repository
+### DataTable
 
-To trigger workflows in Cal.com, use the `scheduleWorkflowReminders` function. This is the standard approach used throughout the codebase for triggering any workflow. Before implementing new workflow triggers, examine existing implementations in the codebase to understand the pattern. The function filters workflows by trigger type and processes each workflow step. Key locations where this is used include booking handlers, confirmation processes, and other booking-related events.
+Refer to the DataTable guide at `packages/features/data-table/GUIDE.md` for implementation patterns and best practices.
 
-## When making changes to Prisma schema in Cal.com
+### Round-Robin Scheduling
 
-After making changes to the Prisma schema in Cal.com and creating migrations, you need to run `yarn prisma generate` to update the TypeScript types. This is especially important when switching Node.js versions, after adding new fields to models, or after pulling changes that include Prisma schema updates, as it ensures the TypeScript compiler recognizes the updated schema structure. If you encounter errors related to missing enum values (like CreationSource.WEBAPP), running `yarn prisma generate` will typically resolve these issues by regenerating the TypeScript types from the schema.
+Reuse existing code in `packages/features/bookings/lib/getLuckyUser.ts` which handles:
+- Weight-based selection
+- Priority ranking
+- Round-robin fairness algorithms
 
-If you encounter enum generator errors during the Prisma generate step (like "Cannot find module './enum-generator.ts'"), run `yarn install` first before trying to generate. This ensures all dependencies are properly installed before the generation process.
+Check if existing functions can be extended before creating new implementations.
 
-Whenever you change the schema.prisma file, remember to always consolidate migrations by squashing them as declared in the Prisma docs: https://www.prisma.io/docs/orm/prisma-migrate/workflows/squashing-migrations. This helps maintain a clean migration history and prevents accumulation of multiple migration files.
+### Calendar Cache System
 
-## When reviewing PRs in the Cal.com repository
+The calendar cache system follows specific patterns in `packages/features/calendar-cache-sql`. When implementing provider-specific calendar cache services (like for Outlook/Office365), place the provider-specific code in the corresponding provider directory (e.g., `packages/app-store/office365calendar`).
 
-When asked to review a PR, focus on providing a clear summary of what the PR is doing and its core functionality. Avoid getting sidetracked by CI failures, testing issues, or technical implementation details unless specifically requested. The user prefers concise, focused reviews that prioritize understanding the main purpose and changes of the PR.
+### API Documentation
 
-## When running Playwright tests in the Cal.com repository
+The OpenAPI specification at `docs/api-reference/v2/openapi.json` is auto-generated from NestJS controllers. Manual edits will be wiped out.
 
-Use the command format `PLAYWRIGHT_HEADLESS=1 yarn e2e [test-file.e2e.ts]` to run Playwright tests instead of the standard `yarn playwright test` command. This format includes the proper timezone setting, virtual display server, and uses the repository's e2e runner.
+To make persistent changes to API documentation, use NestJS decorators (`@ApiQuery`, `@ApiOperation`, etc.) in the controller files at `apps/api/v2/src/modules/*/controllers/*.controller.ts`.
 
-## When running tests in the Cal.com repository
+### Workflows vs Webhooks
 
-When running tests in the Cal.com repository, use the TZ=UTC environment variable (e.g., `TZ=UTC yarn test`) to ensure consistent timezone handling. This prevents timezone-related test failures that might occur when tests are run in different environments or by different developers with varying local timezone settings.
+Workflows and webhooks are two completely separate features in Cal.com with different implementations and file structures:
+- Workflow constants: `packages/features/ee/workflows/lib/constants.ts`
+- NOT in the webhooks directory
 
-## When working on calendar cache features in the Cal.com codebase
-
-The calendar cache system follows specific patterns in `packages/features/calendar-cache-sql`. When implementing provider-specific calendar cache services (like for Outlook/Office365), the provider-specific code should be placed in the corresponding provider directory (e.g., `packages/app-store/office365calendar`).
-
-## When working on PRs in the Cal.com repository
-
-When making changes to the Cal.com codebase, always run type checks locally using `yarn type-check:ci` before concluding that CI failures are unrelated to your changes. Even if errors appear in files you haven't directly modified, your changes might still be causing type issues through dependencies or type inference. Compare type check results between the main branch and your feature branch to confirm whether you've introduced new type errors.
-
-## When working on type issues in the Cal.com repository
-
-Type casting with "as any" is strictly forbidden in the Cal.com codebase. When encountering Prisma type incompatibilities or other TypeScript type issues, proper type-safe solutions must be used instead, such as Prisma extensions system, type parameter constraints, repository pattern isolation, explicit type definitions, and extension composition patterns that are already established in the codebase.
-
-## When working on UI layout changes in the Cal.com web application
-
-The event types page UI components are located in `apps/web/modules/event-types/views/event-types-listing-view.tsx`. This file contains the layout implementation for the search bar and team tabs components on the event types listing page.
-
-Changes to shared UI patterns (like tab layouts and button alignments) need to be checked across multiple views to maintain consistency:
-- Event types page layout: `apps/web/modules/event-types/views/event-types-listing-view.tsx`
-- Bookings page layout: `apps/web/modules/bookings/views/bookings-view.tsx`
-- Common elements like tabs, search bars, and filter buttons should maintain consistent alignment across views
-
-## When working on workflow triggers or similar enum-based features in the Cal.com codebase
-
-To add new workflow triggers:
-
-1. Check packages/prisma/schema.prisma for existing webhooks and workflow trigger enums as reference
-2. Add the same enums to workflows (only when asked by user specifically, or else focus on users requirement)
-3. Add enums to packages/features/ee/workflows/lib/constants.ts for UI display
-4. Add translations to en/locale.json using the format {enum}_trigger (all lowercase). Webhook triggers serve as the reference implementation pattern for workflow triggers.
-
-## When working with app-store integrations in Cal.com
-
-The Cal.com repository uses generated files (*.generated.ts) for app-store integrations. These files are created by the app-store-cli tool. When making structural changes to how integrations are imported or used, you need to update CLI code that generates these files. Typically manual changes to the *.generated.ts files are not made. That was only for PR 19771 for a proof-of-concept. Recent changes have moved from dynamic imports to static map-based imports for better performance. When working with browser components in the app-store, static imports should be used rather than dynamic imports (using Next.js' dynamic function) to maintain consistency with the performance improvements.
-
-When modifying the app-store-cli build.ts file, you must ensure it correctly handles all types of generated files:
-1. Regular service files (calendar.services.generated.ts, crm.services.generated.ts, etc.) need default imports
-2. Browser component files (apps.browser-addon.generated.tsx, etc.) may require dynamic imports with Next.js
-3. After making changes to build.ts, always verify all generated files have the correct imports by checking each file type
-
-The lazyImport parameter in getExportedObject() determines whether to use dynamic imports (for browser components) or static imports (for server-side services).
-
-## When working with branches in the Cal.com repository
-
-When asked to move changes to a different branch in the Cal.com repository, use git commands to commit existing changes to the specified branch rather than redoing the work. This is more efficient and prevents duplication of effort. The user prefers direct branch operations over reimplementing the same changes multiple times.
-
-## When working with calendar events in the Cal.com codebase
-
-Cal.com events in Google Calendar can be identified by checking if the iCalUID ends with "@Cal.com" (e.g., "2GBXSdEixretciJfKVmYN8@Cal.com"). This identifier is used to distinguish Cal.com bookings from other calendar events for data storage and privacy purposes.
-
-## When working with CI/CD in the Cal.com repository
-
-When reviewing CI check failures in Cal.com:
-1. E2E tests can be flaky and may fail intermittently
-2. Focus only on CI failures that are directly related to your code changes
-3. Infrastructure-related failures (like dependency installation issues) can be disregarded if all code-specific checks (type checking, linting, unit tests) are passing
-
-## When working with database models in Cal.com
-
-Database models in Cal.com are defined in `packages/prisma/schema.prisma`. When adding new fields to models:
-
-1. For timestamp fields like `createdAt` and `updatedAt`:
-   - Do not set default values if you want existing records to have null values
-   - Only new records should get timestamps automatically
-   - For `updatedAt` fields, ensure they're updated when records are modified
-
-2. Create a migration using `npx prisma migrate dev --name migration_name` to update the database schema
-
-3. When implementing cache-related features that require timestamp tracking, always update the database schema first before modifying application code that references those fields. The schema changes must be completed and migrated before the application can successfully query or use the new fields.
-
-## When working with generated files in the Cal.com repository
-
-When fixing imports in Cal.com's generated files (like packages/app-store/apps.browser-*.generated.tsx), always check the actual exports in the source files first. For EventTypeAppCardInterface components, they likely use named exports rather than default exports, requiring imports like `import * as ComponentName from "./path"` instead of `import ComponentName from "./path"`. This verification step is crucial when working with browser-addon, browser-appsettings, browser-eventtypesettings, and browser-install generated files. For these files, if you're seeing import errors, check whether the components are exported as default exports in their source files and adjust your import statements accordingly.
-
-## When working with git and CI systems
-
-Always push committed changes to the remote repository before waiting for or checking CI status. Waiting for CI checks on unpushed local commits is backwards - the CI runs on the remote repository state, not local commits. The proper sequence is: commit locally, run local checks, push to remote, then monitor CI status.
-
-## When working with imports/exports in the Cal.com codebase
-
-When working with imports in the Cal.com codebase, particularly in app-store integrations, pay attention to whether modules use named exports or default exports. Many services like VideoApiAdapter, CalendarService, and PaymentService are exported as named exports, but the actual export name may differ from the generic service type (e.g., `export class AppleCalendarService` instead of `export class CalendarService`). When importing these services, verify the actual export name in the source file and use the appropriate named import syntax (e.g., `import { AppleCalendarService } from "./applecalendar/lib/CalendarService"` or with renaming `import { AppleCalendarService as ApplecalendarCalendarService } from "./applecalendar/lib/CalendarService"`). Always check the actual export pattern and name in the source file to determine the correct import syntax.
-
-## When working with tRPC components in the Cal.com repository
-
-When making changes that affect tRPC components or after pulling updates that modify tRPC-related files, you need to follow a specific build order:
-1. First run `yarn prisma generate` to ensure all database types are up-to-date
-2. Then run `cd packages/trpc && yarn build` to rebuild the tRPC package
-This sequence ensures that type definitions are properly generated before building the tRPC components that depend on them, preventing type errors during compilation.
-
-## When working with workflows or webhooks in the Cal.com repository
-
-Workflows and webhooks are two completely separate features in Cal.com with different implementations and file structures. The workflow constants file is located at `packages/features/ee/workflows/lib/constants.ts`, not in the webhooks directory. When working on workflow triggers, do not reference or use webhook trigger implementations - they are distinct systems that should not be confused or mixed.
-
-## When adding new feature flags to the Cal.com repository
-
-To seed new feature flags in Cal.com, create a Prisma migration using the command `yarn prisma migrate dev --create-only --name seed_[feature_name]_feature`. The migration file should be placed in `packages/prisma/migrations/` with a timestamp prefix format like `20250724210733_seed_calendar_cache_sql_features/migration.sql`. Follow the pattern from existing feature seeding migrations like `packages/prisma/migrations/20241216000000_add_calendar_cache_serve/migration.sql` for the SQL structure. The migration should INSERT the new features into the `Feature` table with appropriate type (like `OPERATIONAL`) and default `enabled` status for manual team enablement.
-
-## When adding new UI elements or text strings to Cal.com
-
-All UI strings in Cal.com must be properly translated using the i18n system. This includes:
-- Labels for new UI elements (like dropdown labels, settings headers)
-- Option values that are displayed to users
-- Any text that appears in the interface
-
-Even if some related strings are already translated (like "Bookings" and "Insights"), new strings must be explicitly added to the translation system.
-
-## When creating a pull request
-
-### Title
-
-- Use conventional commits: `feat:`, `fix:`, `refactor:`
-- Be specific: `fix: handle timezone edge case in booking creation`
-- Not generic: `fix: booking bug`
-
-### Size Limits
-
-- **Large PRs** (>500 lines or >10 files) are not recommended.
-- Guide the user how to split large PRs into smaller ones.
-
-## When handling errors
-
-### Descriptive Errors
-
-```typescript
-// ✅ Good - Descriptive error with context
-throw new Error(`Unable to create booking: User ${userId} has no available time slots for ${date}`);
-
-// ❌ Bad - Generic error
-throw new Error("Booking failed");
-```
-
-### Error Types
-
-Use `ErrorWithCode` for files that are not directly coupled to tRPC. The tRPC package has a middleware called `errorConversionMiddleware` that automatically converts `ErrorWithCode` instances into `TRPCError` instances.
-
-```typescript
-// ✅ Good - Use ErrorWithCode in non-tRPC files (services, repositories, utilities)
-import { ErrorCode } from "@calcom/lib/errorCodes";
-import { ErrorWithCode } from "@calcom/lib/errors";
-
-// Option 1: Using constructor with ErrorCode enum
-throw new ErrorWithCode(ErrorCode.BookingNotFound, "Booking not found");
-
-// Option 2: Using the Factory pattern for common HTTP errors
-throw ErrorWithCode.Factory.Forbidden("You don't have permission to view this");
-throw ErrorWithCode.Factory.NotFound("Resource not found");
-throw ErrorWithCode.Factory.BadRequest("Invalid input");
-
-// ✅ Good - Use TRPCError only in tRPC routers/procedures
-import { TRPCError } from "@trpc/server";
-
-throw new TRPCError({
-  code: "BAD_REQUEST",
-  message: "Invalid booking time slot",
-});
-
-// ❌ Bad - Using TRPCError in non-tRPC files
-import { TRPCError } from "@trpc/server";
-// Don't use TRPCError in services, repositories, or utility files
-```
-
-### packages/features Import Restrictions
-
-Files in `packages/features/**` should NOT import from `@calcom/trpc`. This keeps the features package decoupled from the tRPC layer, making the code more reusable and testable. Use `ErrorWithCode` for error handling in these files, and let the tRPC middleware handle the conversion.
-
-**Architecture: packages/features vs apps/web/modules**
-
-The `packages/features` package should contain only framework-agnostic code:
-- Repositories (data access layer)
-- Services (business logic)
-- Core utilities and helpers
-- Types and interfaces
-
-Web-specific code, particularly anything that uses tRPC, should live in `apps/web/modules/...`. This includes:
-- React hooks that use tRPC queries/mutations
-- tRPC-specific utilities
-- Web-only UI components that depend on tRPC
-
-**Example:**
-
-If you have a feature called `feature-opt-in`:
-
-```
-packages/features/feature-opt-in/
-├── repository/
-│   └── FeatureOptInRepository.ts    # Data access - OK here
-├── service/
-│   └── FeatureOptInService.ts       # Business logic - OK here
-└── types.ts                          # Types - OK here
-
-apps/web/modules/feature-opt-in/
-└── hooks/
-    └── useFeatureOptIn.ts           # tRPC hook - MUST be here, not in packages/features
-```
-
-```typescript
-// ❌ Bad - tRPC hook in packages/features
-// packages/features/feature-opt-in/hooks/useFeatureOptIn.ts
-import { trpc } from "@calcom/trpc/react";
-export function useFeatureOptIn() {
-  return trpc.viewer.featureOptIn.useQuery();
-}
-
-// ✅ Good - tRPC hook in apps/web/modules
-// apps/web/modules/feature-opt-in/hooks/useFeatureOptIn.ts
-import { trpc } from "@calcom/trpc/react";
-export function useFeatureOptIn() {
-  return trpc.viewer.featureOptIn.useQuery();
-}
-```
-
-This separation ensures that `packages/features` remains portable and can be used by other apps (like `apps/api/v2`) without pulling in web-specific dependencies like tRPC React hooks.
-
-## Basic Performance Guidelines
-
-- Aim for O(n) or O(n log n) complexity, avoid O(n²)
-- Use database-level filtering instead of JavaScript filtering
-- Consider pagination for large datasets
-- Use database transactions for related operations
-
-## When querying database
-
-Prefer Select over Include:
-
-```typescript
-// ✅ Good - Use select for performance and security
-const booking = await prisma.booking.findFirst({
-  select: {
-    id: true,
-    title: true,
-    user: {
-      select: {
-        id: true,
-        name: true,
-        email: true,
-      }
-    }
-  }
-});
-
-// ❌ Bad - Include fetches all fields
-const booking = await prisma.booking.findFirst({
-  include: {
-    user: true, // This gets ALL user fields
-  }
-});
-```
-
-## Avoid barrel imports
-
-```typescript
-// ❌ Bad - Avoid importing from index.ts barrel files
-import { BookingService, UserService } from "./services";
-
-// ✅ Good - Import directly from source files
-import { BookingService } from "./services/BookingService";
-import { UserService } from "./services/UserService";
-
-
-// ❌ Bad
-import { Button } from "@calcom/ui";
-
-// ✅ Good - Import directly from source files
-import { Button } from "@calcom/ui/components/button";
-```
-
-## File Naming Conventions
-
-### Repository Files
-
-- **Must** include `Repository` suffix, PascalCase matching class: `PrismaBookingRepository.ts`
-
-### Service Files
-
-- **Must** include `Service` suffix, PascalCase matching class, avoid generic names: `MembershipService.ts`
-
-### General Files
-
-- **Components**: PascalCase (e.g., `BookingForm.tsx`)
-- **Utilities**: kebab-case (e.g., `date-utils.ts`)
-- **Types**: PascalCase with `.types.ts` suffix (e.g., `Booking.types.ts`)
-- **Tests**: Same as source file + `.test.ts` or `.spec.ts`
-- **Avoid**: Dot-suffixes like `.service.ts`, `.repository.ts` (except for tests, types, specs)
-
-## Repository + DTO Pattern and Method Conventions
-
-We use a Repository + DTO pattern to isolate Prisma and the database from business logic. Repositories are the only layer that talks to Prisma and database models. All services, tRPC handlers, API controllers, workflows, and UI should depend on DTOs or domain types, not Prisma types.
-
-DTOs (Data Transfer Objects) are simple TypeScript types or interfaces that represent our domain data in an ORM-agnostic way and are returned from repositories.
-
-### Why this pattern?
-
-- **Prevent type leaks**: Prisma type changes stay inside repositories instead of breaking services, handlers, and UI across dozens of files.
-- **Enable safe refactors**: Business logic works against stable DTOs, so you can change storage details without touching higher layers.
-- **Keep ORM swappable**: If we ever change ORM, only repository implementations change; services and handlers stay the same.
-
-### What not to do: tight Prisma coupling in business logic
-
-Do not import Prisma types in business logic. Prisma types belong only in the data access layer.
-
-```typescript
-// ❌ Bad – business logic depends on Prisma
-import type { Webhook } from "@calcom/prisma/client";
-export function sendPayload(webhook: Webhook) { /* ... */ }
-
-// ✅ Good – business logic depends on DTO + repository
-export interface WebhookDTO { id: string; url: string; }
-export interface IWebhookRepository { findById(id: string): Promise<WebhookDTO | null>; }
-export async function sendPayload(repo: IWebhookRepository, id: string) {
-  const webhook = await repo.findById(id);
-  // ...
-}
-```
-
-### DTOs in repositories
-
-Repositories should expose DTOs from their public methods and keep Prisma types internal. Inside the repository, use `Prisma.*GetPayload` and map rows to DTOs. The public methods should only return DTOs, never Prisma models.
-
-```typescript
-// DTO – ORM-agnostic type exported from the repository module
-export interface BookingDTO {
-  id: string;
-  userId: number;
-  startTime: Date;
-  status: "PENDING" | "CONFIRMED" | "CANCELLED";
-}
-```
-
-### DTO Location and Naming
-
-**Location**: All DTOs go in `packages/lib/dto/`
-
-**Naming conventions**:
-- Base entity: `{Entity}Dto` (e.g., `BookingDto`)
-- With relations: `{Entity}With{Relations}Dto` (e.g., `BookingWithAttendeesDto`)
-- For specific projections: `{Entity}For{Purpose}Dto` (e.g., `BookingForConfirmationDto`)
-- Avoid: `{Entity}Dto2`, `{Entity}DtoForHandler`, or other use-case-specific names
-
-**Enum/union pattern** – use string literal unions to stay ORM-agnostic:
-
-```typescript
-// ✅ Good - ORM-agnostic string literal union
-export type BookingStatusDto = "CANCELLED" | "ACCEPTED" | "REJECTED" | "PENDING";
-
-// ❌ Bad - importing Prisma enum
-import { BookingStatus } from "@calcom/prisma/client";
-```
-
-**Type safety** – never use `as any` in DTO mapping functions. If types don't align, fix the mapping explicitly.
-
-### Prisma boundaries
-
-- **Allowed**: `packages/prisma`, repository implementations (`packages/features/**/repositories/*Repository.ts`), and low-level data access infrastructure.
-- **Not allowed**: `packages/features/**` business logic (non-repository), `packages/trpc/**` handlers, `apps/web/**`, `apps/api/v2/**` services/controllers, and workflow/webhook/service layers.
-
-### Method Naming Rules
-
-**1. Don't include the repository's entity name in method names**
-
-Method names should be concise and avoid redundancy since the repository class name already indicates the entity type.
-
-```typescript
-// ✅ Good - Concise method names
-class BookingRepository {
-  findById(id: string) { ... }
-  findByUserId(userId: string) { ... }
-  create(data: BookingCreateInput) { ... }
-  delete(id: string) { ... }
-}
-
-// ❌ Bad - Redundant entity name in methods
-class BookingRepository {
-  findBookingById(id: string) { ... }
-  findBookingByUserId(userId: string) { ... }
-  createBooking(data: BookingCreateInput) { ... }
-  deleteBooking(id: string) { ... }
-}
-```
-
-**2. Use `include` or similar keywords for methods that fetch relational data**
-
-When a method retrieves additional related entities, make this explicit in the method name using keywords like `include`, `with`, or `andRelations`.
-
-```typescript
-// ✅ Good - Clear indication of included relations
-class EventTypeRepository {
-  findById(id: string) {
-    return prisma.eventType.findUnique({
-      where: { id },
-    });
-  }
-
-  findByIdIncludeHosts(id: string) {
-    return prisma.eventType.findUnique({
-      where: { id },
-      include: {
-        hosts: true,
-      },
-    });
-  }
-
-  findByIdIncludeHostsAndSchedule(id: string) {
-    return prisma.eventType.findUnique({
-      where: { id },
-      include: {
-        hosts: true,
-        schedule: true,
-      },
-    });
-  }
-}
-
-// ❌ Bad - Unclear what data is included
-class EventTypeRepository {
-  findById(id: string) {
-    return prisma.eventType.findUnique({
-      where: { id },
-      include: {
-        hosts: true,
-        schedule: true,
-      },
-    });
-  }
-
-  findByIdForReporting(id: string) {
-    return prisma.eventType.findUnique({
-      where: { id },
-      include: {
-        hosts: true,
-      },
-    });
-  }
-}
-```
-
-**3. Keep methods generic and reusable - avoid use-case-specific names**
-
-Repository methods should be general-purpose and describe what data they return, not how or where it's used. This promotes code reuse across different features.
-
-```typescript
-// ✅ Good - Generic, reusable methods
-class BookingRepository {
-  findByUserIdIncludeAttendees(userId: string) {
-    return prisma.booking.findMany({
-      where: { userId },
-      include: {
-        attendees: true,
-      },
-    });
-  }
-
-  findByDateRangeIncludeEventType(startDate: Date, endDate: Date) {
-    return prisma.booking.findMany({
-      where: {
-        startTime: { gte: startDate },
-        endTime: { lte: endDate },
-      },
-      include: {
-        eventType: true,
-      },
-    });
-  }
-}
-
-// ❌ Bad - Use-case-specific method names
-class BookingRepository {
-  findBookingsForReporting(userId: string) {
-    return prisma.booking.findMany({
-      where: { userId },
-      include: {
-        attendees: true,
-      },
-    });
-  }
-
-  findBookingsForDashboard(startDate: Date, endDate: Date) {
-    return prisma.booking.findMany({
-      where: {
-        startTime: { gte: startDate },
-        endTime: { lte: endDate },
-      },
-      include: {
-        eventType: true,
-      },
-    });
-  }
-}
-```
-
-**4. No business logic in repositories**
-
-Repositories should only handle data access. Business logic, validations, and complex transformations belong in the Service layer.
-
-```typescript
-// ✅ Good - Repository only handles data access
-class BookingRepository {
-  findByIdIncludeAttendees(id: string) {
-    return prisma.booking.findUnique({
-      where: { id },
-      include: {
-        attendees: true,
-      },
-    });
-  }
-
-  updateStatus(id: string, status: BookingStatus) {
-    return prisma.booking.update({
-      where: { id },
-      data: { status },
-    });
-  }
-}
-
-class BookingService {
-  async confirmBooking(bookingId: string) {
-    const booking = await this.bookingRepository.findByIdIncludeAttendees(bookingId);
-    
-    if (!booking) {
-      throw new Error("Booking not found");
-    }
-
-    if (booking.status !== "PENDING") {
-      throw new Error("Only pending bookings can be confirmed");
-    }
-
-    // Business logic: send confirmation emails
-    await this.emailService.sendConfirmationToAttendees(booking.attendees);
-    
-    // Update status through repository
-    return this.bookingRepository.updateStatus(bookingId, "CONFIRMED");
-  }
-}
-
-// ❌ Bad - Business logic in repository
-class BookingRepository {
-  async confirmBooking(bookingId: string) {
-    const booking = await prisma.booking.findUnique({
-      where: { id: bookingId },
-      include: {
-        attendees: true,
-      },
-    });
-
-    if (!booking) {
-      throw new Error("Booking not found");
-    }
-
-    if (booking.status !== "PENDING") {
-      throw new Error("Only pending bookings can be confirmed");
-    }
-
-    // ❌ Business logic shouldn't be here
-    await sendEmailToAttendees(booking.attendees);
-
-    return prisma.booking.update({
-      where: { id: bookingId },
-      data: { status: "CONFIRMED" },
-    });
-  }
-}
-```
-
-### Summary
-
-- Method names should be concise: `findById` not `findBookingById`
-- Use `include`/`with` keywords when fetching relations: `findByIdIncludeHosts`
-- Keep methods generic and reusable: `findByUserIdIncludeAttendees` not `findBookingsForReporting`
-- No business logic in repositories - that belongs in Services
-
-## When using Day.js
-
-```typescript
-// ⚠️ Slow in performance-critical code (loops)
-dates.map((date) => dayjs(date).add(1, "day").format());
-
-// ✅ Better - Use .utc() for performance
-dates.map((date) => dayjs.utc(date).add(1, "day").format());
-
-// ✅ Best - Use native Date when possible
-dates.map((date) => new Date(date.valueOf() + 24 * 60 * 60 * 1000));
-```
-
-## Next.js App Directory: Authorisation Checks in Pages
-
-This can include checking session.user exists or session.org etc.
-
-### TL;DR:
-
-Don’t put permission checks in layout.tsx! Always put them directly inside your page.tsx or relevant server components for every restricted route.
-
-
-### Why Not to Use Layouts for Permission Checks
-
-* Layouts don’t intercept all requests: If a user navigates directly or refreshes a protected route, layout checks might be skipped, exposing sensitive content.
-* APIs and server actions bypass layouts: Sensitive operations running on the server can’t be guarded by checks in the layout.
-* Risk of data leaks: Only page/server-level checks ensure that unauthorized users never get protected data.
-
-### ✅ How To Secure Routes (The Right Way)
-
-* Check permissions inside page.tsx or the actual server component.
-* Perform all session/user/role validation before querying or rendering sensitive content.
-* Redirect or return nothing to unauthorized users, before running restricted code.
-
-### 🛠️ Example: Page-Level Permission Check
-
-
-```tsx
-// app/admin/page.tsx
-
-import { redirect } from "next/navigation";
-import { getUserSession } from "@/lib/auth";
-
-export default async function AdminPage() {
-  const session = await getUserSession();
-
-  if (!session || session.user.role !== "admin") {
-    redirect("/"); // Or show an error
-  }
-
-  // Protected content here
-  return <div>Welcome, Admin!</div>;
-}
-```
-
-### 🧠 Key Reminders
-
-* Put permission guards in every restricted page.tsx.
-* Never assume layouts are secure for guarding data.
-* Validate users before any sensitive queries or rendering.
-
-
-## Avoid using Dayjs if you don’t need to be strictly tz aware.
-
-When doing logic like Dayjs.startOf(".."), you can instead use date-fns' `startOfMonth(dateObj)` / `endOfDay(dateObj)`;
-When doing logic that depends on Browser locale, use i18n.language (prefer to deconstruct) like: `const { i18n: { language } } = useLocale();`, in combination with built-in Intl.
-
-Note that with Date, you’re dealing with System time, so it’s not suited to everywhere (such as in the Booker, where instead we’ll likely migrate to Temporal) - but in most cases the above are suitable.
-
-The main reason for doing so is that Dayjs uses a useful, but highly risky plugin system, which has led us to create `@calcom/dayjs` - this is heavy however, because it pre-loads ALL plugins, including locale handling. It's a non-ideal solution to a problem that unfortunately exists due to Dayjs.
-
-## Dependency Injection (DI) Pattern
-
-See [di-pattern.md](./di-pattern.md) for the complete guide on using the type-safe moduleLoader pattern for dependency injection.
+When working on workflow triggers, do not reference or use webhook trigger implementations - they are distinct systems.

agents/rules/README.md

@@ -0,0 +1,79 @@
+# Cal.com Engineering Rules
+
+This directory contains modular, machine-readable engineering rules derived from [Cal.com's Engineering Standards for 2026 and Beyond](https://cal.com/blog/engineering-in-2026-and-beyond).
+
+## Structure
+
+Rules are organized by section prefix, as defined in `_sections.md`:
+
+| Prefix | Section | Impact |
+|--------|---------|--------|
+| `architecture-` | Architecture | CRITICAL |
+| `quality-` | Code Quality | CRITICAL |
+| `data-` | Data Layer | HIGH |
+| `api-` | API Design | HIGH |
+| `performance-` | Performance | HIGH |
+| `testing-` | Testing | MEDIUM-HIGH |
+| `patterns-` | Design Patterns | MEDIUM |
+| `culture-` | Team Culture | MEDIUM |
+
+## Files
+
+- `_sections.md` - Defines all sections, their ordering, and impact levels
+- `_template.md` - Template for creating new rules
+- `{section}-{rule-name}.md` - Individual rule files
+
+## Rule Format
+
+Each rule file follows a consistent format with YAML frontmatter:
+
+```markdown
+---
+title: Rule Title Here
+impact: CRITICAL | HIGH | MEDIUM | LOW
+impactDescription: Optional description (e.g., "20-50% improvement")
+tags: tag1, tag2, tag3
+---
+
+## Rule Title Here
+
+**Impact: LEVEL (optional description)**
+
+Brief explanation of the rule and why it matters.
+
+**Incorrect (description):**
+\`\`\`typescript
+// Bad code example
+\`\`\`
+
+**Correct (description):**
+\`\`\`typescript
+// Good code example
+\`\`\`
+
+Reference: [Link](url)
+```
+
+## Adding New Rules
+
+1. Copy `_template.md` to a new file with the appropriate section prefix
+2. Fill in the frontmatter (title, impact, tags)
+3. Write a clear explanation of the rule
+4. Provide incorrect and correct code examples
+5. Add a reference link if applicable
+
+## Usage
+
+These rules are designed to be:
+- **Human-readable**: Engineers can browse and learn from them
+- **Machine-readable**: AI agents can parse and apply them
+- **Modular**: Individual rules can be updated without affecting others
+- **Versionable**: Changes are tracked in git history
+
+## Core Principles
+
+From the blog post, our engineering philosophy is:
+
+> We are building infrastructure that must almost never fail. To achieve this, we move fast while shipping amazing quality software with no shortcuts or compromises.
+
+The rules in this directory encode the specific practices that enable this philosophy.

agents/rules/_sections.md

@@ -0,0 +1,56 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Architecture (architecture)
+
+**Impact:** CRITICAL
+**Description:** Vertical Slice Architecture and Domain-Driven Design patterns that form the foundation of our codebase organization.
+
+## 2. Code Quality (quality)
+
+**Impact:** CRITICAL
+**Description:** Standards for maintaining high-quality, maintainable code including PR reviews, testing, and accountability.
+
+## 3. Data Layer (data)
+
+**Impact:** HIGH
+**Description:** Repository patterns, DTOs, and technology isolation to prevent coupling and enable maintainability.
+
+## 4. API Design (api)
+
+**Impact:** HIGH
+**Description:** Controller patterns, API stability, and proper separation of HTTP concerns from business logic.
+
+## 5. Performance (performance)
+
+**Impact:** HIGH
+**Description:** Algorithm complexity, data structure choices, and performance patterns for enterprise scale.
+
+## 6. Testing (testing)
+
+**Impact:** MEDIUM-HIGH
+**Description:** Test coverage requirements and testing strategies for maintaining code quality.
+
+## 7. Design Patterns (patterns)
+
+**Impact:** MEDIUM
+**Description:** Factory patterns, dependency injection, and other design patterns for clean, maintainable code.
+
+## 8. Team Culture (culture)
+
+**Impact:** MEDIUM
+**Description:** Engineering culture, accountability, and collaboration standards.
+
+## 9. CI/CD (ci)
+
+**Impact:** HIGH
+**Description:** Continuous integration practices, type checking priorities, and git workflow standards.
+
+## 10. Reference (reference)
+
+**Impact:** LOW
+**Description:** Informational lookups, file locations, and local development setup guides.

agents/rules/_template.md

@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)

agents/rules/api-no-breaking-changes.md

@@ -0,0 +1,60 @@
+---
+title: Never Introduce Breaking API Changes
+impact: CRITICAL
+impactDescription: Maintains developer trust and prevents integration nightmares
+tags: api, stability, versioning, backwards-compatibility
+---
+
+## Never Introduce Breaking API Changes
+
+**Impact: CRITICAL**
+
+Once an API endpoint is public, it must remain stable. Breaking changes destroy developer trust and create integration nightmares for our users.
+
+**Strategies for avoiding breaking changes:**
+- Always add new fields as optional
+- Use API versioning when you must change existing behavior
+- Deprecate old endpoints gracefully with clear migration paths
+- Maintain backward compatibility for at least two major versions
+
+**Incorrect (breaking change):**
+
+```typescript
+// v1 - Original response
+interface BookingResponse {
+  id: number;
+  startTime: string; // ISO string
+}
+
+// v1 - Breaking change: renamed field
+interface BookingResponse {
+  id: number;
+  start: string; // Renamed from startTime - BREAKS CLIENTS
+}
+```
+
+**Correct (non-breaking evolution):**
+
+```typescript
+// v1 - Original response
+interface BookingResponse {
+  id: number;
+  startTime: string;
+}
+
+// v1 - Non-breaking: add new field, keep old one
+interface BookingResponse {
+  id: number;
+  startTime: string; // Keep for backwards compatibility
+  start: string; // New preferred field
+}
+```
+
+**When you must make breaking changes:**
+- Create a new API version using date-specific versioning in API v2
+- Run both versions simultaneously during transition
+- Provide automated migration tools when possible
+- Give users ample time to migrate (minimum 6 months for public APIs)
+- Document exactly what changed and why
+
+Reference: [Cal.com Engineering Blog](https://cal.com/blog/engineering-in-2026-and-beyond)

agents/rules/api-thin-controllers.md

@@ -0,0 +1,73 @@
+---
+title: Keep Controllers Thin - HTTP Concerns Only
+impact: HIGH
+impactDescription: Enables technology-agnostic business logic
+tags: api, controllers, http, separation-of-concerns
+---
+
+## Keep Controllers Thin - HTTP Concerns Only
+
+**Impact: HIGH**
+
+Controllers are thin layers that handle only HTTP concerns. They take requests, process them, and map data to DTOs that are passed to core application logic. No application or core logic should be seen in API routes or tRPC handlers.
+
+**Controller responsibilities (and ONLY these):**
+- Receive and validate incoming requests
+- Extract data from request parameters, body, headers
+- Transform request data into DTOs
+- Call appropriate application services with those DTOs
+- Transform application service responses into response DTOs
+- Return HTTP responses with proper status codes
+
+**Controllers should NOT:**
+- Contain business logic or domain rules
+- Directly access databases or external services
+- Perform complex data transformations or calculations
+- Make decisions about what the application should do
+- Know about implementation details of the domain
+
+**Incorrect (business logic in controller):**
+
+```typescript
+export async function POST(request: Request) {
+  const body = await request.json();
+  
+  // Business logic in controller - BAD
+  const user = await prisma.user.findFirst({ where: { id: body.userId } });
+  if (!user.canBook) {
+    return Response.json({ error: "Cannot book" }, { status: 403 });
+  }
+  
+  const booking = await prisma.booking.create({
+    data: {
+      title: body.title,
+      startTime: new Date(body.startTime),
+      // Complex logic here...
+    }
+  });
+  
+  return Response.json(booking);
+}
+```
+
+**Correct (thin controller):**
+
+```typescript
+export async function POST(request: Request) {
+  const body = await request.json();
+  
+  // Validate input
+  const input = CreateBookingSchema.parse(body);
+  
+  // Delegate to service
+  const result = await bookingService.createBooking(input);
+  
+  // Transform and return
+  return Response.json(BookingResponseSchema.parse(result));
+}
+```
+
+**The principle:**
+We must detach HTTP technology from our application. The way we transfer data between client and server (whether REST, tRPC, etc.) should not influence how our core application works. HTTP is a delivery mechanism, not an architectural driver.
+
+Reference: [Cal.com Engineering Blog](https://cal.com/blog/engineering-in-2026-and-beyond)

agents/rules/architecture-circular-dependencies.md

@@ -0,0 +1,193 @@
+---
+title: Prevent Circular Dependencies Between Packages
+impact: CRITICAL
+impactDescription: Prevents build failures, type errors, ensures honest implementation, and maintains clean dependency graph
+tags: architecture, dependencies, packages, imports, circular
+---
+
+## Prevent Circular Dependencies Between Packages
+
+**Impact: CRITICAL**
+
+Circular dependencies between packages cause build failures, type errors, and make the codebase unmaintainable. The dependency graph must be acyclic, with clear layers from low-level utilities up to high-level features.
+
+The dependency hierarchy (from lowest to highest):
+```
+packages/lib (lowest - no feature dependencies)
+  ↓
+packages/app-store
+  ↓
+packages/features
+  ↓
+packages/trpc
+  ↓
+apps/web (highest - can depend on all packages)
+```
+
+**Benefits:**
+- **Honest implementation**: The dependency graph accurately reflects what code depends on what, with no hidden or circular relationships that create false expectations
+- **Predictable behavior**: Code behaves as the dependency structure suggests - no surprises from circular imports
+- **Clear mental model**: Developers can reason about the system without tracking complex circular relationships
+- **Build reliability**: No circular dependency errors during compilation or bundling
+- **Easier testing**: Lower-level packages can be tested independently without pulling in the entire codebase
+
+### `packages/lib`
+
+**Rules:**
+1. No files in `packages/lib` import from `@calcom/app-store` or `../app-store/**`
+2. No files in `packages/lib` import from `@calcom/features` or `../features/**`
+3. No files in `packages/lib` import from `@calcom/trpc` or `../trpc/**`
+4. No files in `packages/lib` import from `@trpc/server`
+5. **BONUS:** No repository files allowed in `packages/lib` (repositories belong in features or app-store)
+
+**Incorrect:**
+
+```typescript
+// Bad - lib importing from features
+import { getBooking } from "@calcom/features/bookings";
+import { EventRepository } from "@calcom/features/events/repositories";
+
+// Bad - lib importing from app-store
+import { googleCalendarHandler } from "@calcom/app-store/googlecalendar";
+
+// Bad - lib importing from trpc
+import { router } from "@calcom/trpc/server/trpc";
+```
+
+**Correct:**
+
+```typescript
+// Good - lib only imports from other lib files or external packages
+import { logger } from "@calcom/lib/logger";
+import { prisma } from "@calcom/prisma";
+import type { User } from "@prisma/client";
+```
+
+### `packages/app-store`
+
+**Rules:**
+6. No files in `packages/app-store` import from `@calcom/features` or `../features/**`
+7. No files in `packages/app-store` import from `@calcom/trpc` or `../trpc/**`
+
+**Incorrect:**
+
+```typescript
+// Bad - app-store importing from features
+import { BookingService } from "@calcom/features/bookings/services";
+
+// Bad - app-store importing from trpc
+import { publicProcedure } from "@calcom/trpc/server/trpc";
+```
+
+**Correct:**
+
+```typescript
+// Good - app-store imports from lib and prisma
+import { logger } from "@calcom/lib/logger";
+import { prisma } from "@calcom/prisma";
+import type { Credential } from "@prisma/client";
+```
+
+### `packages/features`
+
+**Rules:**
+8. No files in `packages/features` import from `@calcom/trpc` or `../trpc/**`
+9. No files in `packages/features` import from `@calcom/web` or `@calcom/web/**`
+10. No files in `packages/features` import from `../../apps/web/**`
+
+**Incorrect:**
+
+```typescript
+// Bad - features importing from trpc
+import { router } from "@calcom/trpc/server/trpc";
+
+// Bad - features importing from web app
+import { getServerSession } from "@calcom/web/lib/auth";
+import { WebComponent } from "../../apps/web/components/WebComponent";
+```
+
+**Correct:**
+
+```typescript
+// Good - features import from lib, app-store, and prisma
+import { logger } from "@calcom/lib/logger";
+import { prisma } from "@calcom/prisma";
+import { googleCalendarHandler } from "@calcom/app-store/googlecalendar";
+```
+
+### `packages/trpc`
+
+**Rules:**
+11. No files in `packages/trpc` import from `../apps/web/**`
+
+**Incorrect:**
+
+```typescript
+// Bad - trpc importing from web app
+import { getServerSession } from "../../apps/web/lib/auth";
+```
+
+**Correct:**
+
+```typescript
+// Good - trpc imports from features, lib, and prisma
+import { BookingService } from "@calcom/features/bookings/services";
+import { logger } from "@calcom/lib/logger";
+import { prisma } from "@calcom/prisma";
+```
+
+### `packages/testing`
+
+**Rules:**
+12. No files in `packages/testing` import from `@calcom/web` or `@calcom/web/**`
+13. No files in `packages/testing` import from `@calcom/features` or `@calcom/features/**`
+14. No files in `packages/testing` import from `../../apps/web/**`
+15. No files in `packages/testing` import from `../features/**`
+
+**Incorrect:**
+
+```typescript
+// Bad - testing importing from web or features
+import { WebComponent } from "@calcom/web/components";
+import { BookingService } from "@calcom/features/bookings";
+```
+
+**Correct:**
+
+```typescript
+// Good - testing imports from lib and prisma
+import { prisma } from "@calcom/prisma";
+import { logger } from "@calcom/lib/logger";
+```
+
+### `packages/platform/atoms`
+
+**Rules:**
+16. No files in `packages/platform/atoms` import from `@calcom/trpc` or `@calcom/trpc/**`
+17. No files in `packages/platform/atoms` import from `../../trpc` or `../../trpc/**`
+18. No files in `packages/platform/atoms` import from `@calcom/web`
+
+**Incorrect:**
+
+```typescript
+// Bad - platform/atoms importing from trpc or web
+import { router } from "@calcom/trpc/server/trpc";
+import { trpc } from "../../trpc";
+import { WebComponent } from "@calcom/web";
+```
+
+**Correct:**
+
+```typescript
+// Good - platform/atoms imports from lib, features, and ui
+import { logger } from "@calcom/lib/logger";
+import { Button } from "@calcom/ui/components/button";
+import type { Booking } from "@calcom/features/bookings/types";
+```
+
+## Enforcement
+
+These rules should be enforced through:
+- ESLint rules that detect forbidden import paths
+- CI checks that fail on circular dependencies
+- Code review guidelines that flag violations

agents/rules/architecture-feature-boundaries.md

@@ -0,0 +1,42 @@
+---
+title: Enforce Feature Boundaries Through Public APIs
+impact: CRITICAL
+impactDescription: Prevents architectural erosion and maintains loose coupling
+tags: architecture, boundaries, imports, coupling
+---
+
+## Enforce Feature Boundaries Through Public APIs
+
+**Impact: CRITICAL**
+
+Features communicate through well-defined interfaces. If bookings needs availability data, it imports from `@calcom/features/availability` through exported interfaces, not by reaching into internal implementation details.
+
+**Incorrect (reaching into internals):**
+
+```typescript
+// Bad - Importing internal implementation details
+import { calculateSlots } from "@calcom/features/availability/services/internal/slotCalculator";
+import { AvailabilityCache } from "@calcom/features/availability/lib/cache";
+```
+
+**Correct (using public API):**
+
+```typescript
+// Good - Import through the feature's public API
+import { getAvailability } from "@calcom/features/availability";
+import type { AvailabilityResult } from "@calcom/features/availability";
+```
+
+**Shared code placement:**
+- Domain-agnostic utilities and cross-cutting concerns (auth, logging): `packages/lib`
+- Shared UI primitives: `packages/ui`
+
+**Enforcement:**
+Domain boundaries are enforced automatically through linting. If `packages/features/bookings` tries to import from `packages/features/availability/services/internal`, the linter will block it. All cross-feature dependencies must go through the feature's public API.
+
+**Benefits:**
+- Discoverability: Looking for booking logic? It's all in `packages/features/bookings`
+- Easier testing: Test the entire feature as a unit with all pieces in one place
+- Clearer dependencies: When you see `import { getAvailability } from '@calcom/features/availability'`, you know exactly which feature you're depending on
+
+Reference: [Cal.com Engineering Blog](https://cal.com/blog/engineering-in-2026-and-beyond)

agents/rules/architecture-features-modules.md

@@ -0,0 +1,54 @@
+---
+title: packages/features vs apps/web/modules
+impact: HIGH
+impactDescription: Wrong placement causes tight coupling and import issues
+tags: architecture, features, modules, trpc
+---
+
+# packages/features vs apps/web/modules
+
+## packages/features
+
+The `packages/features` package should contain only framework-agnostic code:
+- Repositories (data access layer)
+- Services (business logic)
+- Core utilities and helpers
+- Types and interfaces
+
+**Files in `packages/features/**` should NOT import from `@calcom/trpc`.**
+
+## apps/web/modules
+
+Web-specific code, particularly anything that uses tRPC, should live in `apps/web/modules/...`:
+- React hooks that use tRPC queries/mutations
+- tRPC-specific utilities
+- Web-only UI components that depend on tRPC
+
+## Example Structure
+
+```
+packages/features/feature-opt-in/
+├── repository/
+│   └── FeatureOptInRepository.ts    # Data access - OK here
+├── service/
+│   └── FeatureOptInService.ts       # Business logic - OK here
+└── types.ts                          # Types - OK here
+
+apps/web/modules/feature-opt-in/
+└── hooks/
+    └── useFeatureOptIn.ts           # tRPC hook - MUST be here
+```
+
+## Why This Matters
+
+```typescript
+// ❌ Bad - tRPC hook in packages/features
+// packages/features/feature-opt-in/hooks/useFeatureOptIn.ts
+import { trpc } from "@calcom/trpc/react";
+
+// ✅ Good - tRPC hook in apps/web/modules
+// apps/web/modules/feature-opt-in/hooks/useFeatureOptIn.ts
+import { trpc } from "@calcom/trpc/react";
+```
+
+This separation ensures that `packages/features` remains portable and can be used by other apps (like `apps/api/v2`) without pulling in web-specific dependencies.

agents/rules/architecture-page-level-auth.md

@@ -0,0 +1,56 @@
+---
+title: Page-Level Authorization Checks in Next.js
+impact: CRITICAL
+impactDescription: Prevents unauthorized access to sensitive data
+tags: security, nextjs, authorization, architecture
+---
+
+## Page-Level Authorization Checks in Next.js
+
+**Impact: CRITICAL (Prevents unauthorized access to sensitive data)**
+
+Authorization checks must be performed in `page.tsx` or server components, never in `layout.tsx`. Layouts don't intercept all requests and can be bypassed.
+
+**Incorrect (auth checks in layout):**
+
+```tsx
+// app/admin/layout.tsx - DON'T DO THIS
+export default async function AdminLayout({ children }) {
+  const session = await getUserSession();
+  if (!session?.user.role === "admin") {
+    redirect("/");
+  }
+  return <div>{children}</div>;
+}
+```
+
+**Correct (auth checks in page):**
+
+```tsx
+// app/admin/page.tsx
+import { redirect } from "next/navigation";
+import { getUserSession } from "@/lib/auth";
+
+export default async function AdminPage() {
+  const session = await getUserSession();
+
+  if (!session || session.user.role !== "admin") {
+    redirect("/"); // Or show an error
+  }
+
+  // Protected content here
+  return <div>Welcome, Admin!</div>;
+}
+```
+
+**Why layouts are unsafe for auth:**
+- Layouts don't intercept all requests (direct navigation, refreshes)
+- APIs and server actions bypass layouts entirely
+- Risk of data leaks if layout check is skipped
+
+**Key rules:**
+- Check permissions inside every restricted `page.tsx`
+- Validate session/user/role before querying sensitive data
+- Redirect or return nothing to unauthorized users before running restricted code
+
+Reference: [Next.js Security Best Practices](https://nextjs.org/docs/app/building-your-application/authentication)

agents/rules/architecture-vertical-slices.md

@@ -0,0 +1,61 @@
+---
+title: Organize Code by Domain Using Vertical Slices
+impact: CRITICAL
+impactDescription: Dramatically improves discoverability and reduces cross-team conflicts
+tags: architecture, vertical-slices, ddd, organization
+---
+
+## Organize Code by Domain Using Vertical Slices
+
+**Impact: CRITICAL**
+
+Our codebase is organized by domain, not by technical layer. The `packages/features` directory is the heart of this architectural approach. Each folder inside represents a complete vertical slice of the application, driven by the domain it touches.
+
+**Incorrect (traditional layered architecture):**
+
+```
+src/
+  controllers/
+    bookingController.ts
+    availabilityController.ts
+  services/
+    bookingService.ts
+    availabilityService.ts
+  repositories/
+    bookingRepository.ts
+    availabilityRepository.ts
+```
+
+This creates problems: changes to one feature require touching files scattered across multiple directories, it's hard to understand what a feature does because its code is fragmented, and teams step on each other's toes.
+
+**Correct (vertical slice architecture):**
+
+```
+packages/features/
+  bookings/
+    services/
+    repositories/
+    components/
+    tests/
+  availability/
+    services/
+    repositories/
+    components/
+    tests/
+```
+
+Each feature folder is a self-contained vertical slice that includes:
+- Domain logic: Core business rules and entities specific to that feature
+- Application services: Use case orchestration for that domain
+- Repositories: Data access specific to that feature's needs
+- DTOs: Data transfer objects for crossing boundaries
+- UI components: Frontend components related to this feature
+- Tests: Unit, integration, and e2e tests for this feature
+
+**Benefits:**
+- Everything related to a feature lives in one directory
+- You can understand the entire feature by exploring one directory
+- Teams can work on different features without conflicts
+- Features are loosely coupled and can evolve independently
+
+Reference: [Cal.com Engineering Blog](https://cal.com/blog/engineering-in-2026-and-beyond)

agents/rules/ci-check-failures.md

@@ -0,0 +1,33 @@
+---
+title: CI Check Failure Handling
+impact: HIGH
+impactDescription: Misinterpreting CI failures wastes debugging time
+tags: ci, debugging, workflow
+---
+
+# CI Check Failure Handling
+
+## What to Focus On
+
+When reviewing CI check failures in Cal.com:
+
+1. **E2E tests can be flaky** and may fail intermittently
+2. **Focus only on CI failures that are directly related to your code changes**
+3. Infrastructure-related failures (like dependency installation issues) can be disregarded if all code-specific checks pass
+
+## Known CI Issues to Ignore
+
+These errors are related to SAML database misconfiguration on CI and should be ignored:
+- "password authentication failed for user postgres"
+- "Invalid URL"
+
+## E2E Tests Skipping
+
+**E2E tests skipping is expected behavior:**
+- When E2E tests are skipped, it's because the `ready-for-e2e` label has not been added to the PR
+- The "required" check intentionally fails when E2E tests are skipped to prevent merging without E2E
+- Do not try to fix anything related to skipped E2E tests - this is completely expected and normal
+
+## Before Blaming CI
+
+Always run type checks locally using `yarn type-check:ci --force` before concluding that CI failures are unrelated to your changes. Even if errors appear in files you haven't directly modified, your changes might still be causing type issues through dependencies or type inference.