chore

.cursor/rules/README.mdc

@@ -12,7 +12,7 @@ This directory contains Twenty's development guidelines and best practices in th
 ### Core Guidelines
 - **architecture.mdc** - Project overview, technology stack, and infrastructure setup (Always Applied)
 - **nx-rules.mdc** - Nx workspace guidelines and best practices (Auto-attached to Nx files)
-- **server-migrations.mdc** - Upgrade command guidelines (instance commands and workspace commands) for `twenty-server` (Auto-attached to server entities and upgrade command files)
+- **server-migrations.mdc** - Backend migration and TypeORM guidelines for `twenty-server` (Auto-attached to server entities and migration files)
 - **creating-syncable-entity.mdc** - Comprehensive guide for creating new syncable entities (with universalIdentifier and applicationId) in the workspace migration system (Agent-requested for metadata-modules and workspace-migration files)
 
 ### Code Quality
@@ -81,8 +81,11 @@ npx nx run twenty-server:typecheck         # Type checking
 npx nx run twenty-server:test              # Run unit tests
 npx nx run twenty-server:test:integration:with-db-reset # Run integration tests
 
-# Upgrade commands (instance + workspace)
-npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>
+# Migrations
+npx nx run twenty-server:typeorm migration:generate src/database/typeorm/core/migrations/[name] -d src/database/typeorm/core/core.datasource.ts
+
+# Workspace
+npx nx run twenty-server:command workspace:sync-metadata -f  # Sync metadata
 ```
 
 ## Usage Guidelines

.cursor/rules/changelog-process.mdc

@@ -55,8 +55,7 @@ If feature descriptions are not provided or need enhancement, research the codeb
 - Services: Look for `*.service.ts` files
 
 **For Database/ORM Changes:**
-- Instance commands (fast/slow): `packages/twenty-server/src/database/commands/upgrade-version-command/`
-- Legacy TypeORM migrations: `packages/twenty-server/src/database/typeorm/`
+- Migrations: `packages/twenty-server/src/database/typeorm/`
 - Entities: `packages/twenty-server/src/entities/`
 
 ### Research Commands
@@ -125,16 +124,15 @@ mkdir -p packages/twenty-website/public/images/releases/{MINOR_VERSION}
 
 **Destination:** `packages/twenty-website/public/images/releases/{MINOR_VERSION}/`
 
-**Naming Convention:** `{VERSION}-descriptive-name.webp`
+**Naming Convention:** `{VERSION}-descriptive-name.png`
 
 Examples:
-- `1.9.0-feature-name.webp`
-- `1.9.0-another-feature.webp`
+- `1.9.0-feature-name.png`
+- `1.9.0-another-feature.png`
 
 ```bash
-# Move and rename source files, then convert to webp if needed
+# Move and rename files
 cp ~/Downloads/🆕/source-file.png packages/twenty-website/public/images/releases/{MINOR_VERSION}/{VERSION}-feature-name.png
-cd packages/twenty-website && node scripts/convert-png-to-webp.mjs
 ```
 
 ### 4. Research Features (if needed)
@@ -159,19 +157,19 @@ Date: {YYYY-MM-DD}
 
 Short description explaining what the feature does and why it's useful. Keep it user-focused and concise (1-2 sentences).
 
-![](/images/releases/{MINOR_VERSION}/{VERSION}-feature-1.webp)
+![](/images/releases/{MINOR_VERSION}/{VERSION}-feature-1.png)
 
 # Feature 2 Name
 
 Another short description of the second feature.
 
-![](/images/releases/{MINOR_VERSION}/{VERSION}-feature-2.webp)
+![](/images/releases/{MINOR_VERSION}/{VERSION}-feature-2.png)
 
 # Feature 3 Name
 
 Description of the third feature.
 
-![](/images/releases/{MINOR_VERSION}/{VERSION}-feature-3.webp)
+![](/images/releases/{MINOR_VERSION}/{VERSION}-feature-3.png)
 ```
 
 **Style Guidelines:**
@@ -222,8 +220,8 @@ I've created the changelog for version {VERSION}. Here's the content for your re
 [Show full MDX content]
 
 Images moved to:
-- packages/twenty-website/public/images/releases/{MINOR_VERSION}/{VERSION}-feature-1.webp
-- packages/twenty-website/public/images/releases/{MINOR_VERSION}/{VERSION}-feature-2.webp
+- packages/twenty-website/public/images/releases/{MINOR_VERSION}/{VERSION}-feature-1.png
+- packages/twenty-website/public/images/releases/{MINOR_VERSION}/{VERSION}-feature-2.png
 
 Please review the content. Once you approve, I'll commit the changes and create the pull request.
 ```
@@ -289,12 +287,12 @@ Or visit: `https://github.com/twentyhq/twenty/pull/new/{VERSION}`
 - **Location**: `packages/twenty-website/public/images/releases/`
 
 ### Image Files
-- **Format**: `{VERSION}-descriptive-name.webp`
+- **Format**: `{VERSION}-descriptive-name.png`
 - **Convention**: Kebab-case descriptive names
 - **Examples**: 
-  - `1.8.0-workflow-iterator.webp`
-  - `1.8.0-bulk-select.webp`
-  - `1.9.0-new-feature.webp`
+  - `1.8.0-workflow-iterator.png`
+  - `1.8.0-bulk-select.png`
+  - `1.9.0-new-feature.png`
 
 ## Quick Reference Template
 

.cursor/rules/creating-syncable-entity.mdc

@@ -22,7 +22,7 @@ This main guide provides a high-level overview and navigation hub.
 
 A syncable entity is a metadata entity that:
 - Has a **`universalIdentifier`**: A unique identifier used for syncing entities across workspaces/applications
-- Has an **`applicationId`**: Links the entity to an application (Standard or Custom applications)
+- Has an **`applicationId`**: Links the entity to an application (Twenty Standard or Custom applications)
 - Participates in the **workspace migration system**: Can be created, updated, and deleted through the migration pipeline
 - Is **cached as a flat entity**: Denormalized representation for efficient validation and change detection
 

.cursor/rules/github-actions-security.mdc

@@ -1,72 +0,0 @@
----
-description: GitHub Actions security guidelines for supply chain protection
-globs: **/.github/**/*.yml, **/.github/**/*.yaml
-alwaysApply: false
----
-
-# GitHub Actions Security
-
-## Pin Third-Party Actions to Commit SHAs
-
-Always reference external actions and reusable workflows by their full commit SHA, never by a mutable tag or branch. Tags can be force-pushed by a compromised maintainer account.
-
-```yaml
-# ❌ Mutable tag — vulnerable to supply chain attacks
-uses: actions/checkout@v4
-uses: actions/setup-node@v4
-
-# ✅ Pinned to commit SHA with tag comment for readability
-uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-```
-
-## Prefer `gh api` Over Third-Party Dispatch Actions
-
-For repository dispatch calls, use `gh api` directly instead of third-party actions like `peter-evans/repository-dispatch`. This eliminates a supply-chain dependency entirely.
-
-```yaml
-# ✅ Use env vars + bracket notation to prevent injection
-- name: Dispatch to target repo
-  env:
-    GH_TOKEN: ${{ secrets.DISPATCH_TOKEN }}
-    PR_NUMBER: ${{ github.event.pull_request.number }}
-    BRANCH: ${{ github.event.workflow_run.head_branch }}
-  run: |
-    gh api repos/org/repo/dispatches \
-      -f event_type=my-event \
-      -f "client_payload[pr_number]=$PR_NUMBER" \
-      -f "client_payload[branch]=$BRANCH"
-
-# ✅ Simple dispatch without payload
-- name: Trigger workflow
-  env:
-    GH_TOKEN: ${{ secrets.DISPATCH_TOKEN }}
-  run: |
-    gh api repos/org/repo/dispatches -f event_type=my-event
-
-# ❌ Third-party action dependency
-- uses: peter-evans/repository-dispatch@v2
-  with:
-    token: ${{ secrets.DISPATCH_TOKEN }}
-    repository: org/repo
-    event-type: my-event
-
-# ❌ Inline ${{ }} in shell — vulnerable to injection
-- run: |
-    gh api repos/org/repo/dispatches --input - <<EOF
-    {"event_type": "x", "client_payload": {"branch": "${{ github.head_ref }}"}}
-    EOF
-```
-
-## Minimal Permissions
-
-Always declare explicit `permissions` at the job level with the least privilege required. Never rely on the default `GITHUB_TOKEN` permissions.
-
-```yaml
-# ✅ Explicit minimal permissions
-permissions:
-  contents: read
-
-# ❌ Overly broad or implicit permissions
-permissions: write-all
-```

.cursor/rules/server-migrations.mdc

@@ -1,46 +1,29 @@
 ---
-description: Guidelines for generating and managing upgrade commands (instance commands and workspace commands) in twenty-server
+description: Guidelines for generating and managing TypeORM migrations in twenty-server
 globs: [
   "packages/twenty-server/src/**/*.entity.ts",
-  "packages/twenty-server/src/database/commands/upgrade-version-command/**/*.ts"
+  "packages/twenty-server/src/database/typeorm/**/*.ts"
 ]
 alwaysApply: false
 ---
 
-## Upgrade Commands (twenty-server)
+## Server Migrations (twenty-server)
 
-The upgrade system uses two types of commands instead of raw TypeORM migrations:
-- **Instance commands** — schema and data migrations that run once at the instance level.
-- **Workspace commands** — commands that iterate over all active/suspended workspaces.
-
-See `packages/twenty-server/docs/UPGRADE_COMMANDS.md` for full documentation.
-
-### Instance Commands
-
-- **When changing a `*.entity.ts` file**, generate an instance command:
+- **When changing an entity, always generate a migration**
+  - If you modify a `*.entity.ts` file in `packages/twenty-server/src`, you **must** generate a corresponding TypeORM migration instead of manually editing the database schema.
+  - Use the Nx + TypeORM command from the project root:
 
     ```bash
-    npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>
+    npx nx run twenty-server:typeorm migration:generate src/database/typeorm/core/migrations/common/[name] -d src/database/typeorm/core/core.datasource.ts
     ```
 
-- **Fast commands** (`--type fast`, default) are for schema-only changes that must run immediately. They implement `FastInstanceCommand` with `up`/`down` methods and use the `@RegisteredInstanceCommand` decorator.
+  - Replace `[name]` with a descriptive, kebab-case migration name that reflects the change (for example, `add-agent-turn-evaluation`).
 
-- **Slow commands** (`--type slow`) add a `runDataMigration` method for potentially long-running data backfills that execute before `up`. They only run when `--include-slow` is passed. Use the decorator with `{ type: 'slow' }`.
+- **Prefer generated migrations over manual edits**
+  - Let TypeORM infer schema changes from the updated entities; only adjust the generated migration file manually if absolutely necessary (for example, for data backfills or complex constraints).
+  - Keep schema changes (DDL) in these generated migrations and avoid mixing in heavy data migrations unless there is a strong reason and clear comments.
 
-- The generator auto-registers the command in `instance-commands.constant.ts` — do not edit that file manually.
-
-- **Keep commands consistent and reversible**: include both `up` and `down` logic. Do not delete or rewrite existing, committed commands unless on a pre-release branch.
-
-### Workspace Commands
-
-- Use the `@RegisteredWorkspaceCommand` decorator alongside nest-commander's `@Command` decorator.
-- Extend `ActiveOrSuspendedWorkspaceCommandRunner` and implement `runOnWorkspace`.
-- The base class provides `--dry-run`, `--verbose`, and workspace filter options automatically.
-
-### Execution Order
-
-Within a given version, commands run in this order (timestamp-sorted within each group):
-1. Instance fast commands
-2. Instance slow commands (only with `--include-slow`)
-3. Workspace commands
+- **Keep migrations consistent and reversible**
+  - Ensure the generated migration includes both `up` and `down` logic that correctly applies and reverts the entity change when possible.
+  - Do not delete or rewrite existing, committed migrations unless you are explicitly working on a pre-release branch where history rewrites are allowed by team conventions.
 

.github/CODEOWNERS

@@ -1,6 +0,0 @@
-/.github/              @charlesBochet @FelixMalfait @Weiko @prastoin @bosiraphael @etiennejouan @ijreilly @martmull @thomtrp
-/.github/CODEOWNERS    @charlesBochet @FelixMalfait @Weiko @prastoin @bosiraphael @etiennejouan @ijreilly @martmull @thomtrp
-/.github/workflows/    @charlesBochet @FelixMalfait @Weiko @prastoin @bosiraphael @etiennejouan @ijreilly @martmull @thomtrp
-/.github/actions/      @charlesBochet @FelixMalfait @Weiko @prastoin @bosiraphael @etiennejouan @ijreilly @martmull @thomtrp
-/.github/dependabot.yml @charlesBochet @FelixMalfait @Weiko @prastoin @bosiraphael @etiennejouan @ijreilly @martmull @thomtrp
-/.yarnrc.yml           @charlesBochet @FelixMalfait @Weiko @prastoin @bosiraphael @etiennejouan @ijreilly @martmull @thomtrp

.github/actions/deploy-twenty-app/action.yml

@@ -1,53 +0,0 @@
-name: Deploy Twenty App
-description: Build and deploy a Twenty app to a remote instance
-
-inputs:
-  api-url:
-    description: Base URL of the target Twenty instance (e.g. https://my.twenty.instance)
-    required: true
-  api-key:
-    description: API key or access token for the target instance
-    required: true
-  app-path:
-    description: Path to the app directory (relative to repo root). Defaults to repo root.
-    required: false
-    default: '.'
-
-runs:
-  using: composite
-  steps:
-    - name: Enable Corepack
-      shell: bash
-      run: corepack enable
-
-    - name: Setup Node.js
-      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-      with:
-        node-version-file: '${{ inputs.app-path }}/.nvmrc'
-        cache: yarn
-        cache-dependency-path: '${{ inputs.app-path }}/yarn.lock'
-
-    - name: Install dependencies
-      shell: bash
-      working-directory: ${{ inputs.app-path }}
-      run: yarn install --immutable
-
-    - name: Configure remote
-      shell: bash
-      run: |
-        mkdir -p ~/.twenty
-        node -e "
-          const fs = require('fs'), path = require('path'), os = require('os');
-          fs.writeFileSync(path.join(os.homedir(), '.twenty', 'config.json'), JSON.stringify({
-            version: 1,
-            remotes: { target: { apiUrl: process.env.API_URL, apiKey: process.env.API_KEY } }
-          }, null, 2));
-        "
-      env:
-        API_URL: ${{ inputs.api-url }}
-        API_KEY: ${{ inputs.api-key }}
-
-    - name: Deploy
-      shell: bash
-      working-directory: ${{ inputs.app-path }}
-      run: yarn twenty app:publish --private --remote target

.github/actions/install-twenty-app/action.yml

@@ -1,53 +0,0 @@
-name: Install Twenty App
-description: Install (or upgrade) a Twenty app on a specific workspace
-
-inputs:
-  api-url:
-    description: Base URL of the target Twenty instance (e.g. https://my.twenty.instance)
-    required: true
-  api-key:
-    description: API key or access token for the target workspace
-    required: true
-  app-path:
-    description: Path to the app directory (relative to repo root). Defaults to repo root.
-    required: false
-    default: '.'
-
-runs:
-  using: composite
-  steps:
-    - name: Enable Corepack
-      shell: bash
-      run: corepack enable
-
-    - name: Setup Node.js
-      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-      with:
-        node-version-file: '${{ inputs.app-path }}/.nvmrc'
-        cache: yarn
-        cache-dependency-path: '${{ inputs.app-path }}/yarn.lock'
-
-    - name: Install dependencies
-      shell: bash
-      working-directory: ${{ inputs.app-path }}
-      run: yarn install --immutable
-
-    - name: Configure remote
-      shell: bash
-      run: |
-        mkdir -p ~/.twenty
-        node -e "
-          const fs = require('fs'), path = require('path'), os = require('os');
-          fs.writeFileSync(path.join(os.homedir(), '.twenty', 'config.json'), JSON.stringify({
-            version: 1,
-            remotes: { target: { apiUrl: process.env.API_URL, apiKey: process.env.API_KEY } }
-          }, null, 2));
-        "
-      env:
-        API_URL: ${{ inputs.api-url }}
-        API_KEY: ${{ inputs.api-key }}
-
-    - name: Install
-      shell: bash
-      working-directory: ${{ inputs.app-path }}
-      run: yarn twenty app:install --remote target

.github/actions/nx-affected/action.yaml

@@ -20,7 +20,7 @@ runs:
       run: git fetch origin main --depth=1
     - name: Get last successful commit
       if: env.NX_BASE == ''
-      uses: nrwl/nx-set-shas@3e9ad7370203c1e93d109be57f3b72eb0eb511b1 # v4
+      uses: nrwl/nx-set-shas@v4
     - name: Fallback to origin/main if no base found
       if: env.NX_BASE == ''
       shell: bash

.github/actions/restore-cache/action.yaml

@@ -25,7 +25,7 @@ runs:
       run: |
         echo "CACHE_PRIMARY_KEY_PREFIX=v4-${CACHE_KEY}-${REF_NAME}" >> "${GITHUB_OUTPUT}"
     - name: Restore cache
-      uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0 (restore)
+      uses: actions/cache/restore@v4
       id: restore-cache
       with:
         key: ${{ steps.cache-primary-key-builder.outputs.CACHE_PRIMARY_KEY_PREFIX }}-${{ github.sha }}

.github/actions/save-cache/action.yaml

@@ -9,11 +9,8 @@ inputs:
 runs:
   using: "composite"
   steps:
-    # Fork PRs on pull_request already can't write to the base repo's cache (GitHub built-in).
-    # The fork guard is defense-in-depth for pull_request_target, which does have write access.
     - name: Save cache
-      if: ${{ format('{0}', github.event.pull_request.head.repo.fork) != 'true' }}
-      uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0 (save)
+      uses: actions/cache/save@v4
       with:
         key: ${{ inputs.key }}
         path: |

.github/actions/spawn-twenty-app-dev-test/action.yml

@@ -1,47 +0,0 @@
-name: Spawn Twenty App Dev Test
-description: >
-  Starts a Twenty all-in-one test instance (server, worker, database, redis)
-  using the twentycrm/twenty-app-dev Docker image on port 2021.
-  The server is available at http://localhost:2021 with seeded demo data.
-
-inputs:
-  twenty-version:
-    description: 'Twenty Docker Hub image tag for twenty-app-dev (e.g., "latest" or "v1.20.0").'
-    required: false
-    default: 'latest'
-
-outputs:
-  server-url:
-    description: 'URL where the Twenty test server can be reached'
-    value: http://localhost:2021
-  api-key:
-    description: 'API key (type: API_KEY) for the seeded Twenty dev workspace'
-    value: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC0xYzI1LTRkMDItYmYyNS02YWVjY2Y3ZWE0MTkiLCJ0eXBlIjoiQVBJX0tFWSIsIndvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWMyNS00ZDAyLWJmMjUtNmFlY2NmN2VhNDE5IiwiaWF0IjoxNzM1Njg5NjAwLCJleHAiOjQ4OTE0NDk2MDAsImp0aSI6IjIwMjAyMDIwLWY0MDEtNGQ4YS1hNzMxLTY0ZDAwN2MyN2JhZCJ9.bfQjfyN0NEtTCLE_xPyNcwonDzlSXFoP8kdCQTdnuDc
-
-runs:
-  using: 'composite'
-  steps:
-    - name: Start twenty-app-dev-test container
-      shell: bash
-      run: |
-        docker run -d \
-          --name twenty-app-dev-test \
-          -p 2021:2021 \
-          -e NODE_PORT=2021 \
-          -e SERVER_URL=http://localhost:2021 \
-          twentycrm/twenty-app-dev:${{ inputs.twenty-version }}
-
-        echo "Waiting for Twenty test instance to become healthy…"
-        TIMEOUT=180
-        ELAPSED=0
-        until curl -sf http://localhost:2021/healthz > /dev/null 2>&1; do
-          if [ "$ELAPSED" -ge "$TIMEOUT" ]; then
-            echo "::error::Twenty did not become healthy within ${TIMEOUT}s"
-            docker logs twenty-app-dev-test 2>&1 | tail -80
-            exit 1
-          fi
-          sleep 3
-          ELAPSED=$((ELAPSED + 3))
-          echo "  … waited ${ELAPSED}s"
-        done
-        echo "Twenty test instance is ready at http://localhost:2021 (took ~${ELAPSED}s)"

.github/actions/spawn-twenty-docker-image/action.yaml

@@ -48,7 +48,7 @@ runs:
         fi
 
     - name: Checkout docker compose files
-      uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      uses: actions/checkout@v4
       with:
         repository: ${{ inputs.twenty-repository }}
         ref: ${{ steps.resolve.outputs.git-ref }}

.github/actions/yarn-install/action.yaml

@@ -7,17 +7,6 @@ inputs:
 runs:
   using: 'composite'
   steps:
-    - name: Free disk space for install
-      if: runner.os == 'Linux'
-      shell: bash
-      run: |
-        # Default GitHub images ship large SDKs this repo does not use; removing
-        # them avoids ENOSPC when restoring or linking a full Yarn node_modules.
-        sudo rm -rf /usr/share/dotnet
-        sudo rm -rf /usr/local/lib/android
-        sudo rm -rf /opt/ghc
-        sudo rm -rf /opt/hostedtoolcache/CodeQL
-        df -h
     - name: Cache primary key builder
       id: globals
       shell: bash
@@ -29,12 +18,12 @@ runs:
         echo "packages/*/node_modules" >> $GITHUB_OUTPUT
         echo 'EOF' >> $GITHUB_OUTPUT
     - name: Setup Node.js and get yarn cache
-      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+      uses: actions/setup-node@v4
       with:
         node-version: ${{ inputs.node-version }}
     - name: Restore node_modules
       id: cache-node-modules
-      uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0 (restore)
+      uses: actions/cache/restore@v4
       with:
         key: v4-${{ steps.globals.outputs.CACHE_KEY_PREFIX }}-${{github.sha}}
         restore-keys: v4-${{ steps.globals.outputs.CACHE_KEY_PREFIX }}-
@@ -44,13 +33,10 @@ runs:
       shell: ${{ steps.globals.outputs.ACTION_SHELL }}
       run: |
         yarn config set enableHardenedMode true
-        yarn config set enableScripts false
         yarn --immutable --check-cache
-    # Fork PRs on pull_request already can't write to the base repo's cache (GitHub built-in).
-    # The fork guard is defense-in-depth for pull_request_target, which does have write access.
     - name: Save cache
-      if: ${{ steps.cache-node-modules.outputs.cache-hit != 'true' && steps.cache-node-modules.outputs.cache-matched-key == '' && format('{0}', github.event.pull_request.head.repo.fork) != 'true' }}
-      uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0 (save)
+      if: ${{ steps.cache-node-modules.outputs.cache-hit != 'true' && steps.cache-node-modules.outputs.cache-matched-key == '' }}
+      uses: actions/cache/save@v4
       with:
         key: ${{ steps.cache-node-modules.outputs.cache-primary-key }}
         path: ${{ steps.globals.outputs.PATH_TO_CACHE }}

.github/crowdin-app.yml

@@ -4,19 +4,20 @@
 # See https://crowdin.github.io/crowdin-cli/configuration for more information
 #
 
-preserve_hierarchy: true
-base_path: ..
+"preserve_hierarchy": true
+"base_path": ".."
+
+files: [
+  {
+    #
+    # Source files filter - PO files for Lingui
+    #
+    "source": "**/en.po",
 
-files:
-  #
-  # Source files filter - PO files for Lingui
-  #
-  - source: packages/twenty-front/src/locales/en.po
     #
     # Translation files path
     #
-    translation: '%original_path%/%locale%.po'
-  - source: packages/twenty-server/src/engine/core-modules/i18n/locales/en.po
-    translation: '%original_path%/%locale%.po'
-  - source: packages/twenty-emails/src/locales/en.po
-    translation: '%original_path%/%locale%.po'
+    "translation": "%original_path%/%locale%.po",
+  }
+]
+

.github/crowdin-website.yml

@@ -1,23 +0,0 @@
-#
-# Crowdin CLI configuration for Website translations (twenty-website)
-# Project ID: 4
-# See https://crowdin.github.io/crowdin-cli/configuration for more information
-#
-
-project_id: 4
-preserve_hierarchy: true
-base_url: 'https://twenty.api.crowdin.com'
-base_path: ..
-languages_mapping:
-  locale:
-    fr: fr-FR
-
-files:
-  #
-  # Source file - PO file for Lingui
-  #
-  - source: packages/twenty-website/src/locales/en.po
-    #
-    # Translation files path
-    #
-    translation: '%original_path%/%locale%.po'

.github/workflows/cd-deploy-main.yaml

@@ -14,8 +14,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Repository Dispatch
-        env:
-          GH_TOKEN: ${{ secrets.TWENTY_INFRA_TOKEN }}
-        run: |
-          gh api repos/twentyhq/twenty-infra/dispatches \
-            -f event_type=auto-deploy-main
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.TWENTY_INFRA_TOKEN }}
+          repository: twentyhq/twenty-infra
+          event-type: auto-deploy-main
+          client-payload: '{"github": ${{ toJson(github) }}}' # Passes the entire github context to the downstream workflow

.github/workflows/cd-deploy-tag.yaml

@@ -14,10 +14,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Repository Dispatch
-        env:
-          GH_TOKEN: ${{ secrets.TWENTY_INFRA_TOKEN }}
-          REF_NAME: ${{ github.ref_name }}
-        run: |
-          gh api repos/twentyhq/twenty-infra/dispatches \
-            -f event_type=auto-deploy-tag \
-            -f "client_payload[github][ref_name]=$REF_NAME"
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.TWENTY_INFRA_TOKEN }}
+          repository: twentyhq/twenty-infra
+          event-type: auto-deploy-tag
+          client-payload: '{"github": ${{ toJson(github) }}}' # Passes the entire github context to the downstream workflow

.github/workflows/changed-files.yaml

@@ -21,11 +21,11 @@ jobs:
       any_changed: ${{ steps.changed-files.outputs.any_changed }}
     steps:
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Check for changed files
         id: changed-files
-        uses: tj-actions/changed-files@48d8f15b2aaa3d255ca5af3eba4870f807ce6b3c # v45.0.9
+        uses: tj-actions/changed-files@v45
         with:
           files: ${{ inputs.files }}

.github/workflows/ci-ai-catalog-sync.yaml

@@ -17,7 +17,7 @@ jobs:
       NODE_OPTIONS: '--max-old-space-size=4096'
     steps:
       - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           ref: main
 
@@ -41,7 +41,7 @@ jobs:
 
       - name: Create pull request
         if: steps.changes.outputs.changed == 'true'
-        uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676 # v7.0.6
+        uses: peter-evans/create-pull-request@v7
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           commit-message: 'chore: sync AI model catalog from models.dev'
@@ -61,7 +61,8 @@ jobs:
 
       - name: Trigger automerge
         if: steps.changes.outputs.changed == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.TWENTY_INFRA_TOKEN }}
-        run: |
-          gh api repos/twentyhq/twenty-infra/dispatches -f event_type=automated-pr-ready
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.TWENTY_INFRA_TOKEN }}
+          repository: twentyhq/twenty-infra
+          event-type: automated-pr-ready

.github/workflows/ci-breaking-changes.yaml

@@ -35,10 +35,15 @@ jobs:
     runs-on: ubuntu-latest
     services:
       postgres:
-        image: postgres:18
+        image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
+          PGUSER_SUPERUSER: postgres
+          PGPASSWORD_SUPERUSER: postgres
+          ALLOW_NOSSL: 'true'
+          SPILO_PROVIDER: 'local'
         ports:
           - 5432:5432
         options: >-
@@ -48,10 +53,16 @@ jobs:
           --health-retries 5
       redis:
         image: redis
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         ports:
           - 6379:6379
       clickhouse:
         image: clickhouse/clickhouse-server:25.8.8
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
           CLICKHOUSE_PASSWORD: clickhousePassword
           CLICKHOUSE_URL: "http://default:clickhousePassword@localhost:8123/twenty"
@@ -66,7 +77,7 @@ jobs:
 
     steps:
       - name: Checkout current branch
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
 
@@ -144,9 +155,6 @@ jobs:
 
           npx nx run twenty-server:database:init:prod
 
-      - name: Flush cache before seeding current branch
-        run: npx nx command-no-deps twenty-server -- cache:flush
-
       - name: Seed current branch database with test data
         run: |
           npx nx command-no-deps twenty-server -- workspace:seed:dev
@@ -163,21 +171,13 @@ jobs:
       - name: Wait for current branch server to be ready
         run: |
           echo "Waiting for current branch server to start..."
-          timeout=60
+          timeout=300
           interval=5
           elapsed=0
 
-          ADMIN_TOKEN=$(jq -r '.APPLE_JANE_ADMIN_ACCESS_TOKEN' packages/twenty-server/test/integration/constants/test-tokens.json)
-
           while [ $elapsed -lt $timeout ]; do
-            GRAPHQL_RESPONSE=$(curl -s -X POST "http://localhost:${{ env.CURRENT_SERVER_PORT }}/graphql" \
-              -H "Content-Type: application/json" \
-              -H "Authorization: Bearer ${ADMIN_TOKEN}" \
-              -d '{"query":"{ __schema { queryType { name } } }"}' 2>/dev/null || echo '{}')
-
-            if echo "$GRAPHQL_RESPONSE" | jq -e '.data.__schema' > /dev/null 2>&1 && \
-               curl -fsS "http://localhost:${{ env.CURRENT_SERVER_PORT }}/rest/open-api/core" \
-                 -H "Authorization: Bearer ${ADMIN_TOKEN}" > /dev/null 2>&1; then
+            if curl -s "http://localhost:${{ env.CURRENT_SERVER_PORT }}/graphql" > /dev/null 2>&1 && \
+               curl -s "http://localhost:${{ env.CURRENT_SERVER_PORT }}/rest/open-api/core" > /dev/null 2>&1; then
               echo "Current branch server is ready!"
               break
             fi
@@ -188,7 +188,7 @@ jobs:
           done
 
           if [ $elapsed -ge $timeout ]; then
-            echo "❌ Timed out waiting for current branch server to serve a valid schema."
+            echo "Timeout waiting for current branch server to start"
             echo "Current server log:"
             cat /tmp/current-server.log || echo "No current server log found"
             exit 1
@@ -262,14 +262,6 @@ jobs:
             rm -f /tmp/current-server.pid
           fi
 
-      - name: Flush Redis between server runs
-        run: |
-          # Clear all Redis caches to prevent stale data from the current branch
-          # server contaminating the main branch server. Both servers share the
-          # same Redis instance, and CoreEntityCacheService/WorkspaceCacheService
-          # persist cached entities across process restarts.
-          redis-cli -h localhost -p 6379 FLUSHALL || echo "::warning::Failed to flush Redis"
-
       - name: Checkout main branch
         run: |
           git stash
@@ -315,9 +307,6 @@ jobs:
 
           npx nx run twenty-server:database:init:prod
 
-      - name: Flush cache before seeding main branch
-        run: npx nx command-no-deps twenty-server -- cache:flush
-
       - name: Seed main branch database with test data
         run: |
           npx nx command-no-deps twenty-server -- workspace:seed:dev
@@ -338,17 +327,9 @@ jobs:
           interval=5
           elapsed=0
 
-          ADMIN_TOKEN=$(jq -r '.APPLE_JANE_ADMIN_ACCESS_TOKEN' packages/twenty-server/test/integration/constants/test-tokens.json)
-
           while [ $elapsed -lt $timeout ]; do
-            GRAPHQL_RESPONSE=$(curl -s -X POST "http://localhost:${{ env.MAIN_SERVER_PORT }}/graphql" \
-              -H "Content-Type: application/json" \
-              -H "Authorization: Bearer ${ADMIN_TOKEN}" \
-              -d '{"query":"{ __schema { queryType { name } } }"}' 2>/dev/null || echo '{}')
-
-            if echo "$GRAPHQL_RESPONSE" | jq -e '.data.__schema' > /dev/null 2>&1 && \
-               curl -fsS "http://localhost:${{ env.MAIN_SERVER_PORT }}/rest/open-api/core" \
-                 -H "Authorization: Bearer ${ADMIN_TOKEN}" > /dev/null 2>&1; then
+            if curl -s "http://localhost:${{ env.MAIN_SERVER_PORT }}/graphql" > /dev/null 2>&1 && \
+               curl -s "http://localhost:${{ env.MAIN_SERVER_PORT }}/rest/open-api/core" > /dev/null 2>&1; then
               echo "Main branch server is ready!"
               break
             fi
@@ -359,7 +340,7 @@ jobs:
           done
 
           if [ $elapsed -ge $timeout ]; then
-            echo "❌ Timed out waiting for main branch server to serve a valid schema."
+            echo "Timeout waiting for main branch server to start"
             echo "Main server log:"
             cat /tmp/main-server.log || echo "No main server log found"
             exit 1
@@ -429,36 +410,29 @@ jobs:
           valid=true
 
           for file in main-schema-introspection.json current-schema-introspection.json \
-                      main-metadata-schema-introspection.json current-metadata-schema-introspection.json; do
-            if [ ! -f "$file" ]; then
-              echo "::warning::Missing GraphQL schema file: $file"
-              valid=false
-            elif ! jq -e '.data.__schema' "$file" >/dev/null 2>&1; then
-              echo "::warning::File $file is not a valid GraphQL introspection result. First 200 bytes: $(head -c 200 "$file")"
-              valid=false
-            fi
-          done
-
-          for file in main-rest-api.json current-rest-api.json \
+                      main-metadata-schema-introspection.json current-metadata-schema-introspection.json \
+                      main-rest-api.json current-rest-api.json \
                       main-rest-metadata-api.json current-rest-metadata-api.json; do
-            if [ ! -f "$file" ]; then
-              echo "::warning::Missing OpenAPI spec file: $file"
-              valid=false
-            elif ! jq -e '.openapi // .swagger' "$file" >/dev/null 2>&1; then
-              echo "::warning::File $file is not a valid OpenAPI spec. First 200 bytes: $(head -c 200 "$file")"
+            if [ ! -f "$file" ] || ! jq empty "$file" 2>/dev/null; then
+              echo "::warning::Invalid or missing schema file: $file"
               valid=false
             fi
           done
 
           echo "valid=$valid" >> $GITHUB_OUTPUT
 
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
+
       - name: Install OpenAPI Diff Tool
         run: |
           # Using the Java-based OpenAPITools/openapi-diff via Docker
           echo "Using OpenAPITools/openapi-diff via Docker"
 
       - name: Generate GraphQL Schema Diff Reports
-        id: graphql-diff
         if: steps.validate-schemas.outputs.valid == 'true'
         run: |
           echo "=== INSTALLING GRAPHQL INSPECTOR CLI ==="
@@ -472,7 +446,6 @@ jobs:
             echo "✅ No changes in GraphQL schema"
           else
             echo "⚠️ Changes detected in GraphQL schema, generating report..."
-            echo "core_breaking=true" >> $GITHUB_OUTPUT
             echo "# GraphQL Schema Changes" > graphql-schema-diff.md
             echo "" >> graphql-schema-diff.md
             graphql-inspector diff main-schema-introspection.json current-schema-introspection.json >> graphql-schema-diff.md 2>&1 || {
@@ -490,7 +463,6 @@ jobs:
             echo "✅ No changes in GraphQL metadata schema"
           else
             echo "⚠️ Changes detected in GraphQL metadata schema, generating report..."
-            echo "metadata_breaking=true" >> $GITHUB_OUTPUT
             echo "# GraphQL Metadata Schema Changes" > graphql-metadata-diff.md
             echo "" >> graphql-metadata-diff.md
             graphql-inspector diff main-metadata-schema-introspection.json current-metadata-schema-introspection.json >> graphql-metadata-diff.md 2>&1 || {
@@ -507,7 +479,6 @@ jobs:
           ls -la *-diff.md 2>/dev/null || echo "No diff files generated (no changes detected)"
 
       - name: Check REST API Breaking Changes
-        id: rest-diff
         if: steps.validate-schemas.outputs.valid == 'true'
         run: |
           echo "=== CHECKING REST API FOR BREAKING CHANGES ==="
@@ -530,7 +501,6 @@ jobs:
 
             if [ "$incompatible" = "true" ]; then
               echo "❌ Breaking changes detected in REST API"
-              echo "breaking=true" >> $GITHUB_OUTPUT
 
               # Generate breaking changes report
               echo "# REST API Breaking Changes" > rest-api-diff.md
@@ -578,7 +548,6 @@ jobs:
           fi
 
       - name: Check REST Metadata API Breaking Changes
-        id: rest-metadata-diff
         if: steps.validate-schemas.outputs.valid == 'true'
         run: |
           echo "=== CHECKING REST METADATA API FOR BREAKING CHANGES ==="
@@ -601,7 +570,6 @@ jobs:
 
             if [ "$incompatible" = "true" ]; then
               echo "❌ Breaking changes detected in REST Metadata API"
-              echo "breaking=true" >> $GITHUB_OUTPUT
 
               # Generate breaking changes report (only for breaking changes)
               echo "# REST Metadata API Breaking Changes" > rest-metadata-api-diff.md
@@ -647,82 +615,9 @@ jobs:
             echo "::warning::REST Metadata API analysis tool error - continuing workflow"
           fi
 
-      - name: Fail on breaking changes
-        if: steps.validate-schemas.outputs.valid == 'true'
-        run: |
-          breaking=false
-
-          if [ "${{ steps.graphql-diff.outputs.core_breaking }}" = "true" ]; then
-            echo "❌ GraphQL core schema has breaking changes"
-            breaking=true
-            if [ -f graphql-schema-diff.md ]; then
-              echo ""
-              cat graphql-schema-diff.md
-              echo ""
-            fi
-          fi
-
-          if [ "${{ steps.graphql-diff.outputs.metadata_breaking }}" = "true" ]; then
-            echo "❌ GraphQL metadata schema has breaking changes"
-            breaking=true
-            if [ -f graphql-metadata-diff.md ]; then
-              echo ""
-              cat graphql-metadata-diff.md
-              echo ""
-            fi
-          fi
-
-          if [ "${{ steps.rest-diff.outputs.breaking }}" = "true" ]; then
-            echo "❌ REST core API has breaking changes"
-            breaking=true
-            if [ -f rest-api-diff.json ]; then
-              echo ""
-              jq -r '
-                (if (.missingEndpoints | length) > 0 then
-                  "  Removed endpoints:\n" +
-                  (.missingEndpoints | map("    - " + (.method // "?") + " " + (.pathUrl // "?")) | join("\n"))
-                else "" end),
-                (if (.changedOperations | length) > 0 then
-                  "  Changed operations:\n" +
-                  (.changedOperations | map("    - " + (.method // "?") + " " + (.pathUrl // "?")) | join("\n"))
-                else "" end)
-              ' rest-api-diff.json | sed '/^$/d'
-              echo ""
-            fi
-          fi
-
-          if [ "${{ steps.rest-metadata-diff.outputs.breaking }}" = "true" ]; then
-            echo "❌ REST metadata API has breaking changes"
-            breaking=true
-            if [ -f rest-metadata-api-diff.json ]; then
-              echo ""
-              jq -r '
-                (if (.missingEndpoints | length) > 0 then
-                  "  Removed endpoints:\n" +
-                  (.missingEndpoints | map("    - " + (.method // "?") + " " + (.pathUrl // "?")) | join("\n"))
-                else "" end),
-                (if (.changedOperations | length) > 0 then
-                  "  Changed operations:\n" +
-                  (.changedOperations | map("    - " + (.method // "?") + " " + (.pathUrl // "?")) | join("\n"))
-                else "" end)
-              ' rest-metadata-api-diff.json | sed '/^$/d'
-              echo ""
-            fi
-          fi
-
-          if [ "$breaking" = "true" ]; then
-            echo ""
-            echo "This PR introduces breaking changes to the public API."
-            echo "If intentional, deprecate the old endpoint and introduce a new one."
-            echo "See the breaking changes report artifact and PR comment for details."
-            exit 1
-          fi
-
-          echo "✅ No breaking API changes detected"
-
       - name: Upload breaking changes report
         if: always()
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@v4
         with:
           name: breaking-changes-report
           path: |
@@ -740,3 +635,5 @@ jobs:
           if [ -f /tmp/main-server.pid ]; then
             kill $(cat /tmp/main-server.pid) || true
           fi
+
+

.github/workflows/ci-create-app-e2e-minimal.yaml

@@ -1,171 +0,0 @@
-name: CI Create App E2E minimal
-
-on:
-  push:
-    branches:
-      - main
-
-  pull_request:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
-
-jobs:
-  changed-files-check:
-    uses: ./.github/workflows/changed-files.yaml
-    with:
-      files: |
-        packages/create-twenty-app/**
-        packages/twenty-sdk/**
-        packages/twenty-client-sdk/**
-        packages/twenty-shared/**
-        !packages/create-twenty-app/package.json
-        !packages/twenty-sdk/package.json
-        !packages/twenty-client-sdk/package.json
-        !packages/twenty-shared/package.json
-  create-app-e2e-minimal:
-    needs: changed-files-check
-    if: needs.changed-files-check.outputs.any_changed == 'true'
-    timeout-minutes: 30
-    runs-on: ubuntu-latest-4-cores
-    services:
-      postgres:
-        image: postgres:18
-        env:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-      redis:
-        image: redis
-        ports:
-          - 6379:6379
-    env:
-      PUBLISHABLE_PACKAGES: twenty-client-sdk twenty-sdk create-twenty-app
-      TWENTY_API_URL: http://localhost:3000
-      TWENTY_API_KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdik
-    steps:
-      - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-        with:
-          fetch-depth: 10
-
-      - name: Install dependencies
-        uses: ./.github/actions/yarn-install
-
-      - name: Set CI version and prepare packages for publish
-        run: |
-          CI_VERSION="0.0.0-ci.$(date +%s)"
-          echo "CI_VERSION=$CI_VERSION" >> $GITHUB_ENV
-          npx nx run-many -t set-local-version -p $PUBLISHABLE_PACKAGES --releaseVersion=$CI_VERSION
-
-      - name: Build packages
-        run: |
-          for pkg in $PUBLISHABLE_PACKAGES; do
-            npx nx build $pkg
-          done
-
-      - name: Install and start Verdaccio
-        run: |
-          npx verdaccio --config .github/verdaccio-config.yaml &
-
-          for i in $(seq 1 30); do
-            if curl -s http://localhost:4873 > /dev/null 2>&1; then
-              echo "Verdaccio is ready"
-              break
-            fi
-            echo "Waiting for Verdaccio... ($i/30)"
-            sleep 1
-          done
-
-      - name: Publish packages to local registry
-        run: |
-          yarn config set npmRegistryServer http://localhost:4873
-          yarn config set unsafeHttpWhitelist --json '["localhost"]'
-          yarn config set npmAuthToken ci-auth-token
-
-          for pkg in $PUBLISHABLE_PACKAGES; do
-            cd packages/$pkg
-            yarn npm publish --tag ci
-            cd ../..
-          done
-
-      - name: Scaffold app using published create-twenty-app
-        run: |
-          npm install -g create-twenty-app@$CI_VERSION --registry http://localhost:4873
-          create-twenty-app --version
-          mkdir -p /tmp/e2e-test-workspace
-          cd /tmp/e2e-test-workspace
-          create-twenty-app test-app --display-name "Test scaffolded app" --description "E2E test scaffolded app" --url http://localhost:3000
-
-      - name: Install scaffolded app dependencies
-        run: |
-          cd /tmp/e2e-test-workspace/test-app
-          echo 'npmRegistryServer: "http://localhost:4873"' >> .yarnrc.yml
-          echo 'unsafeHttpWhitelist: ["localhost"]' >> .yarnrc.yml
-          YARN_ENABLE_IMMUTABLE_INSTALLS=false yarn install --no-immutable
-
-      - name: Verify installed app versions
-        run: |
-          cd /tmp/e2e-test-workspace/test-app
-          echo "--- Checking package.json references correct SDK version ---"
-          node -e "
-            const pkg = require('./package.json');
-            const sdkVersion = pkg.dependencies['twenty-sdk'];
-            if (!sdkVersion.startsWith('0.0.0-ci.')) {
-              console.error('Expected twenty-sdk version to start with 0.0.0-ci., got:', sdkVersion);
-              process.exit(1);
-            }
-            console.log('SDK version in scaffolded app:', sdkVersion);
-          "
-
-      - name: Verify SDK CLI is available
-        run: |
-          cd /tmp/e2e-test-workspace/test-app
-          npx --no-install twenty --version
-
-      - name: Setup server environment
-        run: npx nx reset:env:e2e-testing-server twenty-server
-
-      - name: Create databases
-        run: |
-          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
-          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
-
-      - name: Setup database
-        run: npx nx run twenty-server:database:reset
-
-      - name: Start server
-        run: nohup npx nx start:ci twenty-server &
-
-      - name: Wait for server to be ready
-        run: npx wait-on http://localhost:3000/healthz --timeout 120000 --interval 1000
-
-      - name: Authenticate with twenty-server
-        run: |
-          cd /tmp/e2e-test-workspace/test-app
-          npx --no-install twenty remote:add --api-key ${{ env.TWENTY_API_KEY }} --url ${{ env.TWENTY_API_URL }}
-
-      - name: Run scaffolded app integration test (deploys, installs, and verifies the app)
-        run: |
-          cd /tmp/e2e-test-workspace/test-app
-          yarn test
-
-  ci-create-app-e2e-minimal-status-check:
-    if: always() && !cancelled()
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-    needs: [changed-files-check, create-app-e2e-minimal]
-    steps:
-      - name: Fail job if any needs failed
-        if: contains(needs.*.result, 'failure')
-        run: exit 1

.github/workflows/ci-create-app-e2e.yaml

@@ -0,0 +1,208 @@
+name: CI Create App E2E
+
+on:
+  push:
+    branches:
+      - main
+
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  changed-files-check:
+    uses: ./.github/workflows/changed-files.yaml
+    with:
+      files: |
+        packages/create-twenty-app/**
+        packages/twenty-sdk/**
+        packages/twenty-client-sdk/**
+        packages/twenty-shared/**
+        packages/twenty-server/**
+        !packages/create-twenty-app/package.json
+        !packages/twenty-sdk/package.json
+        !packages/twenty-client-sdk/package.json
+        !packages/twenty-shared/package.json
+        !packages/twenty-server/package.json
+  create-app-e2e:
+    needs: changed-files-check
+    if: needs.changed-files-check.outputs.any_changed == 'true'
+    timeout-minutes: 30
+    runs-on: ubuntu-latest-4-cores
+    services:
+      postgres:
+        image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
+        env:
+          PGUSER_SUPERUSER: postgres
+          PGPASSWORD_SUPERUSER: postgres
+          ALLOW_NOSSL: 'true'
+          SPILO_PROVIDER: 'local'
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      redis:
+        image: redis
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
+        ports:
+          - 6379:6379
+    env:
+      PUBLISHABLE_PACKAGES: twenty-client-sdk twenty-sdk create-twenty-app
+    steps:
+      - name: Fetch custom Github Actions and base branch history
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 10
+
+      - name: Install dependencies
+        uses: ./.github/actions/yarn-install
+
+      - name: Set CI version and prepare packages for publish
+        run: |
+          CI_VERSION="0.0.0-ci.$(date +%s)"
+          echo "CI_VERSION=$CI_VERSION" >> $GITHUB_ENV
+          npx nx run-many -t set-local-version -p $PUBLISHABLE_PACKAGES --releaseVersion=$CI_VERSION
+
+      - name: Build packages
+        run: |
+          for pkg in $PUBLISHABLE_PACKAGES; do
+            npx nx build $pkg
+          done
+
+      - name: Install and start Verdaccio
+        run: |
+          npx verdaccio --config .github/verdaccio-config.yaml &
+
+          for i in $(seq 1 30); do
+            if curl -s http://localhost:4873 > /dev/null 2>&1; then
+              echo "Verdaccio is ready"
+              break
+            fi
+            echo "Waiting for Verdaccio... ($i/30)"
+            sleep 1
+          done
+
+      - name: Publish packages to local registry
+        run: |
+          yarn config set npmRegistryServer http://localhost:4873
+          yarn config set unsafeHttpWhitelist --json '["localhost"]'
+          yarn config set npmAuthToken ci-auth-token
+
+          for pkg in $PUBLISHABLE_PACKAGES; do
+            cd packages/$pkg
+            yarn npm publish --tag ci
+            cd ../..
+          done
+
+      - name: Scaffold app using published create-twenty-app
+        run: |
+          npm install -g create-twenty-app@$CI_VERSION --registry http://localhost:4873
+          create-twenty-app --version
+          mkdir -p /tmp/e2e-test-workspace
+          cd /tmp/e2e-test-workspace
+          create-twenty-app test-app --exhaustive --display-name "Test App" --description "E2E test app" --skip-local-instance
+
+      - name: Install scaffolded app dependencies
+        run: |
+          cd /tmp/e2e-test-workspace/test-app
+          echo 'npmRegistryServer: "http://localhost:4873"' >> .yarnrc.yml
+          echo 'unsafeHttpWhitelist: ["localhost"]' >> .yarnrc.yml
+          YARN_ENABLE_IMMUTABLE_INSTALLS=false yarn install --no-immutable
+
+      - name: Verify installed app versions
+        run: |
+          cd /tmp/e2e-test-workspace/test-app
+          echo "--- Checking package.json references correct SDK version ---"
+          node -e "
+            const pkg = require('./package.json');
+            const sdkVersion = pkg.devDependencies['twenty-sdk'];
+            if (!sdkVersion.startsWith('0.0.0-ci.')) {
+              console.error('Expected twenty-sdk version to start with 0.0.0-ci., got:', sdkVersion);
+              process.exit(1);
+            }
+            console.log('SDK version in scaffolded app:', sdkVersion);
+          "
+
+      - name: Verify SDK CLI is available
+        run: |
+          cd /tmp/e2e-test-workspace/test-app
+          npx --no-install twenty --version
+
+      - name: Setup server environment
+        run: npx nx reset:env:e2e-testing-server twenty-server
+
+      - name: Build server
+        run: npx nx build twenty-server
+
+      - name: Create and setup database
+        run: |
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
+          npx nx run twenty-server:database:reset
+
+      - name: Start server
+        run: |
+          npx nx start twenty-server &
+          echo "Waiting for server to be ready..."
+          timeout 60 bash -c 'until curl -s http://localhost:3000/health; do sleep 2; done'
+
+      - name: Authenticate with twenty-server
+        env:
+          SEED_API_KEY: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdik'
+        run: |
+          cd /tmp/e2e-test-workspace/test-app
+          npx --no-install twenty remote add --token $SEED_API_KEY --url http://localhost:3000
+
+      - name: Deploy scaffolded app
+        run: |
+          cd /tmp/e2e-test-workspace/test-app
+          npx --no-install twenty deploy
+
+      - name: Install scaffolded app
+        run: |
+          cd /tmp/e2e-test-workspace/test-app
+          npx --no-install twenty install
+
+      - name: Execute hello-world logic function
+        run: |
+          cd /tmp/e2e-test-workspace/test-app
+          EXEC_OUTPUT=$(npx --no-install twenty exec --functionName hello-world-logic-function)
+          echo "$EXEC_OUTPUT"
+          echo "$EXEC_OUTPUT" | grep -q "Hello, World!"
+
+      - name: Execute create-hello-world-company logic function
+        run: |
+          cd /tmp/e2e-test-workspace/test-app
+          EXEC_OUTPUT=$(npx --no-install twenty exec --functionName create-hello-world-company)
+          echo "$EXEC_OUTPUT"
+          echo "$EXEC_OUTPUT" | grep -q 'Created company.*Hello World.*with id'
+
+      - name: Run scaffolded app integration test
+        env:
+          TWENTY_API_URL: http://localhost:3000
+        run: |
+          cd /tmp/e2e-test-workspace/test-app
+          yarn test
+
+  ci-create-app-e2e-status-check:
+    if: always() && !cancelled()
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    needs: [changed-files-check, create-app-e2e]
+    steps:
+      - name: Fail job if any needs failed
+        if: contains(needs.*.result, 'failure')
+        run: exit 1

.github/workflows/ci-create-app.yaml

@@ -30,8 +30,12 @@ jobs:
       matrix:
         task: [lint, typecheck, test]
     steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies

.github/workflows/ci-docs.yaml

@@ -28,8 +28,13 @@ jobs:
     timeout-minutes: 10
     runs-on: ubuntu-latest
     steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
+
       - name: Fetch local actions
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
 

.github/workflows/ci-emails.yaml

@@ -28,7 +28,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies

.github/workflows/ci-example-app-hello-world.yaml

@@ -1,94 +0,0 @@
-name: CI Example App Hello World
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
-
-jobs:
-  changed-files-check:
-    uses: ./.github/workflows/changed-files.yaml
-    with:
-      files: |
-        packages/twenty-apps/examples/hello-world/**
-        packages/twenty-sdk/**
-        packages/twenty-client-sdk/**
-        packages/twenty-shared/**
-        !packages/twenty-sdk/package.json
-        !packages/twenty-client-sdk/package.json
-        !packages/twenty-shared/package.json
-
-  example-app-hello-world:
-    needs: changed-files-check
-    if: needs.changed-files-check.outputs.any_changed == 'true'
-    timeout-minutes: 30
-    runs-on: ubuntu-latest
-    services:
-      postgres:
-        image: postgres:18
-        env:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-      redis:
-        image: redis
-        ports:
-          - 6379:6379
-    env:
-      TWENTY_API_URL: http://localhost:3000
-      TWENTY_API_KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdik
-    steps:
-      - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-
-      - name: Install dependencies
-        uses: ./.github/actions/yarn-install
-
-      - name: Build SDK packages
-        run: npx nx build twenty-sdk
-
-      - name: Setup server environment
-        run: npx nx reset:env:e2e-testing-server twenty-server
-
-      - name: Create databases
-        run: |
-          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
-          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
-
-      - name: Setup database
-        run: npx nx run twenty-server:database:reset
-
-      - name: Start server
-        run: nohup npx nx start:ci twenty-server &
-
-      - name: Wait for server to be ready
-        run: npx wait-on http://localhost:3000/healthz --timeout 120000 --interval 1000
-
-      - name: Run integration tests
-        working-directory: packages/twenty-apps/examples/hello-world
-        run: npx vitest run
-
-  ci-example-app-hello-world-status-check:
-    if: always() && !cancelled()
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-    needs: [changed-files-check, example-app-hello-world]
-    steps:
-      - name: Fail job if any needs failed
-        if: contains(needs.*.result, 'failure')
-        run: exit 1

.github/workflows/ci-example-app-postcard.yaml

@@ -1,121 +0,0 @@
-name: CI Example App Postcard
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
-
-jobs:
-  changed-files-check:
-    uses: ./.github/workflows/changed-files.yaml
-    with:
-      files: |
-        packages/twenty-apps/examples/postcard/**
-        packages/twenty-sdk/**
-        packages/twenty-client-sdk/**
-        packages/twenty-shared/**
-        packages/twenty-server/**
-        !packages/twenty-sdk/package.json
-        !packages/twenty-client-sdk/package.json
-        !packages/twenty-shared/package.json
-        !packages/twenty-server/package.json
-
-  example-app-postcard:
-    needs: changed-files-check
-    if: needs.changed-files-check.outputs.any_changed == 'true'
-    timeout-minutes: 30
-    runs-on: ubuntu-latest
-    services:
-      postgres:
-        image: postgres:18
-        env:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-      redis:
-        image: redis
-        ports:
-          - 6379:6379
-    env:
-      TWENTY_API_URL: http://localhost:3000
-      TWENTY_API_KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdik
-    steps:
-      - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-
-      - name: Install dependencies
-        uses: ./.github/actions/yarn-install
-
-      - name: Build SDK packages
-        run: npx nx build twenty-sdk
-
-      - name: Setup server environment
-        run: npx nx reset:env:e2e-testing-server twenty-server
-
-      - name: Create databases
-        run: |
-          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
-          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
-
-      - name: Setup database
-        run: npx nx run twenty-server:database:reset
-
-      - name: Start server
-        run: nohup npx nx start:ci twenty-server &
-
-      - name: Wait for server to be ready
-        run: npx wait-on http://localhost:3000/healthz --timeout 120000 --interval 1000
-
-      - name: Run integration tests
-        working-directory: packages/twenty-apps/examples/postcard
-        run: npx vitest run
-
-      - name: Configure remote for SDK CLI
-        run: |
-          mkdir -p ~/.twenty
-          cat > ~/.twenty/config.json <<EOF
-          {
-            "version": 1,
-            "remotes": {
-              "target": {
-                "apiUrl": "${TWENTY_API_URL}",
-                "apiKey": "${TWENTY_API_KEY}",
-                "accessToken": "${TWENTY_API_KEY}"
-              }
-            },
-            "defaultRemote": "target"
-          }
-          EOF
-
-      - name: Deploy postcard app (registry install path)
-        working-directory: packages/twenty-apps/examples/postcard
-        run: node ${{ github.workspace }}/packages/twenty-sdk/dist/cli.cjs deploy --remote target
-
-      - name: Install postcard app (registry install path)
-        working-directory: packages/twenty-apps/examples/postcard
-        run: node ${{ github.workspace }}/packages/twenty-sdk/dist/cli.cjs install --remote target
-
-  ci-example-app-postcard-status-check:
-    if: always() && !cancelled()
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-    needs: [changed-files-check, example-app-postcard]
-    steps:
-      - name: Fail job if any needs failed
-        if: contains(needs.*.result, 'failure')
-        run: exit 1

.github/workflows/ci-front-component-renderer.yaml

@@ -32,8 +32,12 @@ jobs:
       matrix:
         task: [build, typecheck, lint]
     steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -46,8 +50,12 @@ jobs:
     timeout-minutes: 30
     runs-on: ubuntu-latest
     steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -55,7 +63,7 @@ jobs:
       - name: Build storybook
         run: npx nx storybook:build twenty-front-component-renderer
       - name: Upload storybook build
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@v4
         with:
           name: storybook-twenty-front-component-renderer
           path: packages/twenty-front-component-renderer/storybook-static
@@ -68,7 +76,7 @@ jobs:
       STORYBOOK_URL: http://localhost:6008
     steps:
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -76,24 +84,14 @@ jobs:
       - name: Build dependencies
         run: npx nx build twenty-sdk
       - name: Download storybook build
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        uses: actions/download-artifact@v4
         with:
           name: storybook-twenty-front-component-renderer
           path: packages/twenty-front-component-renderer/storybook-static
-      - name: Resolve Playwright version
-        id: playwright-version
-        run: echo "version=$(node -p "require('@playwright/test/package.json').version")" >> "$GITHUB_OUTPUT"
-      - name: Cache Playwright browsers
-        id: playwright-cache
-        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
-        with:
-          path: ~/.cache/ms-playwright
-          key: v4-playwright-browsers-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}
       - name: Install Playwright
-        if: steps.playwright-cache.outputs.cache-hit != 'true'
         run: |
           cd packages/twenty-front-component-renderer
-          npx playwright install chromium
+          npx playwright install
       - name: Serve storybook & run tests
         run: |
           npx http-server packages/twenty-front-component-renderer/storybook-static --port 6008 --silent &

.github/workflows/ci-front.yaml

@@ -38,8 +38,12 @@ jobs:
     env:
       REACT_APP_SERVER_BASE_URL: http://localhost:3000
     steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
       - name: Fetch local actions
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -51,7 +55,7 @@ jobs:
       - name: Front / Build storybook
         run: npx nx storybook:build twenty-front
       - name: Upload storybook build
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@v4
         with:
           name: storybook-static
           path: packages/twenty-front/storybook-static
@@ -75,7 +79,7 @@ jobs:
       STORYBOOK_URL: http://localhost:6006
     steps:
       - name: Fetch local actions
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -92,24 +96,14 @@ jobs:
           npx nx build twenty-ui
           npx nx build twenty-front-component-renderer
       - name: Download storybook build
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        uses: actions/download-artifact@v4
         with:
           name: storybook-static
           path: packages/twenty-front/storybook-static
-      - name: Resolve Playwright version
-        id: playwright-version
-        run: echo "version=$(node -p "require('@playwright/test/package.json').version")" >> "$GITHUB_OUTPUT"
-      - name: Cache Playwright browsers
-        id: playwright-cache
-        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
-        with:
-          path: ~/.cache/ms-playwright
-          key: v4-playwright-browsers-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}
       - name: Install Playwright
-        if: steps.playwright-cache.outputs.cache-hit != 'true'
         run: |
           cd packages/twenty-front
-          npx playwright install chromium
+          npx playwright install
       - name: Front / Write .env
         run: npx nx reset:env twenty-front
       - name: Serve storybook & run tests
@@ -127,7 +121,7 @@ jobs:
       #       exit 1
       #     fi
       # - name: Upload coverage artifact
-      #   uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+      #   uses: actions/upload-artifact@v4
       #   with:
       #     retention-days: 1
       #     name: coverage-artifacts-${{ matrix.storybook_scope }}-${{ github.run_id }}-${{ matrix.shard }}
@@ -142,12 +136,12 @@ jobs:
   #     matrix:
   #       storybook_scope: [modules, pages, performance]
   #   steps:
-  #     - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+  #     - uses: actions/checkout@v4
   #       with:
   #         fetch-depth: 10
   #     - name: Install dependencies
   #       uses: ./.github/actions/yarn-install
-  #     - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+  #     - uses: actions/download-artifact@v4
   #       with:
   #         pattern: coverage-artifacts-${{ matrix.storybook_scope }}-${{ github.run_id }}-*
   #         merge-multiple: true
@@ -164,14 +158,18 @@ jobs:
     timeout-minutes: 30
     runs-on: ubuntu-latest
     env:
-      NODE_OPTIONS: '--max-old-space-size=6144'
+      NODE_OPTIONS: '--max-old-space-size=4096'
       TASK_CACHE_KEY: front-task-${{ matrix.task }}
     strategy:
       matrix:
         task: [lint, typecheck, test]
     steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -205,8 +203,12 @@ jobs:
       NODE_OPTIONS: "--max-old-space-size=10240"
       ANALYZE: "true"
     steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -216,7 +218,7 @@ jobs:
       - name: Build frontend
         run: npx nx build twenty-front
       # - name: Upload frontend build artifact
-      #   uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+      #   uses: actions/upload-artifact@v4
       #   with:
       #     name: frontend-build
       #     path: packages/twenty-front/build

.github/workflows/ci-merge-queue.yaml

@@ -25,10 +25,15 @@ jobs:
       NODE_OPTIONS: "--max-old-space-size=10240"
     services:
       postgres:
-        image: postgres:18
+        image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
+          PGUSER_SUPERUSER: postgres
+          PGPASSWORD_SUPERUSER: postgres
+          ALLOW_NOSSL: "true"
+          SPILO_PROVIDER: "local"
         ports:
           - 5432:5432
         options: >-
@@ -38,14 +43,17 @@ jobs:
           --health-retries 5
       redis:
         image: redis
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         ports:
           - 6379:6379
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 10
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+      - uses: actions/setup-node@v4
         with:
           node-version: lts/*
 
@@ -53,7 +61,7 @@ jobs:
         uses: ./.github/actions/yarn-install
 
       - name: Restore Nx build cache
-        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0 (restore)
+        uses: actions/cache/restore@v4
         with:
           key: v4-e2e-build-${{ github.ref_name }}-${{ github.sha }}
           restore-keys: |
@@ -83,7 +91,7 @@ jobs:
 
       - name: Save Nx build cache
         if: always()
-        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0 (save)
+        uses: actions/cache/save@v4
         with:
           key: v4-e2e-build-${{ github.ref_name }}-${{ github.sha }}
           path: |
@@ -119,7 +127,7 @@ jobs:
 
       - name: Upload Playwright results
         if: always()
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@v4
         with:
           name: playwright-results
           path: |

.github/workflows/ci-release-create.yaml

@@ -28,7 +28,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           ref: ${{ github.event.inputs.ref }}
 
@@ -47,7 +47,7 @@ jobs:
           printf '%s\n' "$VERSION" > version.txt
 
       - name: Create Pull Request
-        uses: peter-evans/create-pull-request@c5a7806660adbe173f04e3e038b0ccdcd758773c # v6.1.0
+        uses: peter-evans/create-pull-request@v6
         with:
           branch: release/${{ steps.sanitize.outputs.version }}
           commit-message: "chore: release v${{ steps.sanitize.outputs.version }}"

.github/workflows/ci-release-merge.yaml

@@ -30,7 +30,7 @@ jobs:
           fi
 
       - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           ref: main
 
@@ -55,7 +55,7 @@ jobs:
           git tag "v${{ env.VERSION }}"
           git push origin "v${{ env.VERSION }}"
 
-      - uses: release-drafter/release-drafter@09c613e259eb8d4e7c81c2cb00618eb5fc4575a7 # v5
+      - uses: release-drafter/release-drafter@v5
         if: contains(github.event.pull_request.labels.*.name, 'create_release')
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/ci-sdk.yaml

@@ -19,7 +19,6 @@ jobs:
       files: |
         packages/twenty-sdk/**
         packages/twenty-server/**
-        .github/workflows/ci-sdk.yaml
         !packages/twenty-sdk/package.json
   sdk-test:
     needs: changed-files-check
@@ -30,8 +29,12 @@ jobs:
       matrix:
         task: [lint, typecheck, test:unit, test:integration]
     steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -50,10 +53,15 @@ jobs:
     if: needs.changed-files-check.outputs.any_changed == 'true'
     services:
       postgres:
-        image: postgres:18
+        image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
+          PGUSER_SUPERUSER: postgres
+          PGPASSWORD_SUPERUSER: postgres
+          ALLOW_NOSSL: 'true'
+          SPILO_PROVIDER: 'local'
         ports:
           - 5432:5432
         options: >-
@@ -63,38 +71,30 @@ jobs:
           --health-retries 5
       redis:
         image: redis
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         ports:
           - 6379:6379
     env:
-      TWENTY_API_URL: http://localhost:3000
-      TWENTY_API_KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdik
+      NODE_ENV: test
     steps:
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
         uses: ./.github/actions/yarn-install
-      - name: Build SDK
+      - name: Build
         run: npx nx build twenty-sdk
-      - name: Setup server environment
-        run: npx nx reset:env:e2e-testing-server twenty-server
-      - name: Create databases
+      - name: Server / Create Test DB
         run: |
-          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
           PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
-      - name: Setup database
-        run: npx nx run twenty-server:database:reset
-      - name: Start server
-        run: nohup npx nx start:ci twenty-server > /tmp/twenty-server.log 2>&1 &
-      - name: Wait for server to be ready
-        run: npx wait-on http://localhost:3000/healthz --timeout 120000 --interval 1000
       - name: SDK / Run e2e Tests
-        run: NODE_ENV=test npx vitest run --config ./vitest.e2e.config.ts
-        working-directory: packages/twenty-sdk
-      - name: Server / Dump logs on failure
-        if: failure()
-        run: tail -100 /tmp/twenty-server.log || echo "No server log file found"
+        uses: ./.github/actions/nx-affected
+        with:
+          tag: scope:sdk
+          tasks: test:e2e
   ci-sdk-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5

.github/workflows/ci-server.yaml

@@ -25,7 +25,6 @@ jobs:
         packages/twenty-server/**
         packages/twenty-front/src/generated/**
         packages/twenty-front/src/generated-metadata/**
-        packages/twenty-front/src/generated-admin/**
         packages/twenty-client-sdk/**
         packages/twenty-emails/**
         packages/twenty-shared/**
@@ -37,7 +36,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -65,7 +64,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -78,93 +77,21 @@ jobs:
           tag: scope:backend
           tasks: lint,typecheck
 
-  server-previous-version-upgrade-mutation-guard:
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-    steps:
-      - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-        with:
-          fetch-depth: 10
-      - name: Get changed upgrade-version-command files
-        id: changed-files
-        uses: tj-actions/changed-files@48d8f15b2aaa3d255ca5af3eba4870f807ce6b3c # v45.0.9
-        with:
-          files: |
-            packages/twenty-server/src/database/commands/upgrade-version-command/**
-      - name: Check upgrade version commands are in current version only
-        if: >
-          steps.changed-files.outputs.any_changed == 'true' &&
-          !contains(github.event.pull_request.labels.*.name, 'ci:allow-previous-version-upgrade-mutation')
-        run: |
-          VERSION_CONSTANT_FILE="packages/twenty-server/src/engine/core-modules/upgrade/constants/twenty-current-version.constant.ts"
-
-          CURRENT_VERSION=$(sed -n "s/.*TWENTY_CURRENT_VERSION = '\([0-9.]*\)'.*/\1/p" "$VERSION_CONSTANT_FILE")
-
-          if [ -z "$CURRENT_VERSION" ]; then
-            echo "::error::Could not extract TWENTY_CURRENT_VERSION from $VERSION_CONSTANT_FILE"
-            exit 1
-          fi
-
-          CURRENT_DIR=$(echo "$CURRENT_VERSION" | sed -E 's/^([0-9]+)\.([0-9]+)\..*/\1-\2/')
-
-          echo "Current version: $CURRENT_VERSION (directory: $CURRENT_DIR)"
-
-          ADDED_OFFENDERS=""
-          MODIFIED_OFFENDERS=""
-
-          check_files() {
-            local category="$1"
-            shift
-            for file in "$@"; do
-              VERSION_DIR=$(echo "$file" | sed -n 's|.*upgrade-version-command/\([0-9]*-[0-9]*\)/.*|\1|p')
-
-              if [ -n "$VERSION_DIR" ] && [ "$VERSION_DIR" != "$CURRENT_DIR" ]; then
-                if [ "$category" = "added" ]; then
-                  ADDED_OFFENDERS="$ADDED_OFFENDERS\n  - $file (version directory: $VERSION_DIR)"
-                else
-                  MODIFIED_OFFENDERS="$MODIFIED_OFFENDERS\n  - $file (version directory: $VERSION_DIR)"
-                fi
-              fi
-            done
-          }
-
-          check_files "added" ${{ steps.changed-files.outputs.added_files }}
-          check_files "modified" ${{ steps.changed-files.outputs.modified_files }}
-
-          if [ -n "$ADDED_OFFENDERS" ] || [ -n "$MODIFIED_OFFENDERS" ]; then
-            echo "This PR touches upgrade command files outside the current version directory ($CURRENT_DIR / $CURRENT_VERSION)."
-
-            if [ -n "$ADDED_OFFENDERS" ]; then
-              echo ""
-              echo "New files added to non-current version directories:"
-              echo -e "$ADDED_OFFENDERS"
-            fi
-
-            if [ -n "$MODIFIED_OFFENDERS" ]; then
-              echo ""
-              echo "Existing files modified in non-current version directories:"
-              echo -e "$MODIFIED_OFFENDERS"
-            fi
-
-            echo ""
-            echo "If this is intentional, add the label 'ci:allow-previous-version-upgrade-mutation' to this PR and re-run CI."
-            echo "Otherwise, please move your changes to the current version directory ($CURRENT_DIR)."
-
-            echo "::error::Upgrade commands were added or modified in non-current version directories."
-            exit 1
-          fi
-
   server-validation:
     needs: server-build
     timeout-minutes: 30
     runs-on: ubuntu-latest
     services:
       postgres:
-        image: postgres:18
+        image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
+          PGUSER_SUPERUSER: postgres
+          PGPASSWORD_SUPERUSER: postgres
+          ALLOW_NOSSL: 'true'
+          SPILO_PROVIDER: 'local'
         ports:
           - 5432:5432
         options: >-
@@ -174,11 +101,14 @@ jobs:
           --health-retries 5
       redis:
         image: redis
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         ports:
           - 6379:6379
     steps:
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -222,18 +152,15 @@ jobs:
           exit 1
       - name: Server / Check for Pending Migrations
         run: |
-          npx nx database:migrate:generate twenty-server -- --name pending-migration-check || true
+          CORE_MIGRATION_OUTPUT=$(npx nx run twenty-server:typeorm migration:generate core-migration-check -d src/database/typeorm/core/core.datasource.ts || true)
 
-          if ! git diff --quiet; then
-            echo "::error::Unexpected migration files were generated. Please run 'npx nx database:migrate:generate twenty-server -- --name <migration-name>' and commit the result."
-            echo ""
-            echo "The following migration changes were detected:"
-            echo "==================================================="
-            git diff
-            echo "==================================================="
-            echo ""
+          CORE_MIGRATION_FILE=$(ls packages/twenty-server/*core-migration-check.ts 2>/dev/null || echo "")
 
-            git checkout -- .
+          if [ -n "$CORE_MIGRATION_FILE" ]; then
+            echo "::error::Unexpected migration files were generated. Please create a proper migration manually."
+            echo "$CORE_MIGRATION_OUTPUT"
+
+            rm -f packages/twenty-server/*core-migration-check.ts
 
             exit 1
           fi
@@ -243,14 +170,13 @@ jobs:
 
           npx nx run twenty-front:graphql:generate
           npx nx run twenty-front:graphql:generate --configuration=metadata
-          npx nx run twenty-front:graphql:generate --configuration=admin
 
-          if ! git diff --quiet -- packages/twenty-front/src/generated packages/twenty-front/src/generated-metadata packages/twenty-front/src/generated-admin; then
-            echo "::error::GraphQL schema changes detected. Please run the three graphql:generate configurations ('data', 'metadata', 'admin') and commit the changes."
+          if ! git diff --quiet -- packages/twenty-front/src/generated packages/twenty-front/src/generated-metadata; then
+            echo "::error::GraphQL schema changes detected. Please run 'npx nx run twenty-front:graphql:generate' and 'npx nx run twenty-front:graphql:generate --configuration=metadata' and commit the changes."
             echo ""
             echo "The following GraphQL schema changes were detected:"
             echo "==================================================="
-            git diff -- packages/twenty-front/src/generated packages/twenty-front/src/generated-metadata packages/twenty-front/src/generated-admin
+            git diff -- packages/twenty-front/src/generated packages/twenty-front/src/generated-metadata
             echo "==================================================="
             echo ""
             HAS_ERRORS=true
@@ -278,7 +204,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -305,10 +231,15 @@ jobs:
         shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
     services:
       postgres:
-        image: postgres:18
+        image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
+          PGUSER_SUPERUSER: postgres
+          PGPASSWORD_SUPERUSER: postgres
+          ALLOW_NOSSL: 'true'
+          SPILO_PROVIDER: 'local'
         ports:
           - 5432:5432
         options: >-
@@ -318,10 +249,16 @@ jobs:
           --health-retries 5
       redis:
         image: redis
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         ports:
           - 6379:6379
       clickhouse:
         image: clickhouse/clickhouse-server:25.8.8
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
           CLICKHOUSE_PASSWORD: clickhousePassword
           CLICKHOUSE_URL: "http://default:clickhousePassword@localhost:8123/twenty"
@@ -341,7 +278,7 @@ jobs:
       SHARD_COUNTER: 10
     steps:
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -388,7 +325,6 @@ jobs:
         changed-files-check,
         server-build,
         server-lint-typecheck,
-        server-previous-version-upgrade-mutation-guard,
         server-validation,
         server-test,
         server-integration-test,

.github/workflows/ci-shared.yaml

@@ -29,8 +29,12 @@ jobs:
       matrix:
         task: [lint, typecheck, test]
     steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies

.github/workflows/ci-test-docker-compose.yaml

@@ -26,9 +26,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
       - name: Login to Docker Hub
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        uses: docker/login-action@v3
         with:
           username: ${{ vars.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_PASSWORD }}
@@ -101,9 +101,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
       - name: Login to Docker Hub
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        uses: docker/login-action@v3
         with:
           username: ${{ vars.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_PASSWORD }}
@@ -121,7 +121,7 @@ jobs:
       - name: Start container
         run: |
           docker run -d --name twenty-app-dev \
-            -p 2020:2020 \
+            -p 3000:3000 \
             twenty-app-dev-ci
           docker logs twenty-app-dev -f &
       - name: Wait for server health
@@ -129,10 +129,10 @@ jobs:
           echo "Waiting for twenty-app-dev to become healthy..."
           count=0
           while true; do
-            status=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:2020/healthz 2>/dev/null || echo "000")
+            status=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:3000/healthz 2>/dev/null || echo "000")
             if [ "$status" = "200" ]; then
               echo "Server is healthy!"
-              curl -s http://localhost:2020/healthz
+              curl -s http://localhost:3000/healthz
               break
             fi
 

.github/workflows/ci-ui.yaml

@@ -30,8 +30,12 @@ jobs:
       matrix:
         task: [lint, typecheck, test]
     steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -44,8 +48,12 @@ jobs:
     timeout-minutes: 30
     runs-on: ubuntu-latest
     steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -53,7 +61,7 @@ jobs:
       - name: Build storybook
         run: npx nx storybook:build twenty-ui
       - name: Upload storybook build
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@v4
         with:
           name: storybook-twenty-ui
           path: packages/twenty-ui/storybook-static
@@ -66,7 +74,7 @@ jobs:
       STORYBOOK_URL: http://localhost:6007
     steps:
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -74,7 +82,7 @@ jobs:
       - name: Build dependencies
         run: npx nx build twenty-shared
       - name: Download storybook build
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        uses: actions/download-artifact@v4
         with:
           name: storybook-twenty-ui
           path: packages/twenty-ui/storybook-static

.github/workflows/ci-utils.yaml

@@ -25,7 +25,7 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event.action != 'closed'
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/checkout@v4
       - name: Install dependencies
         uses: ./.github/actions/yarn-install
       - name: Utils / Run Danger.js
@@ -38,7 +38,7 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event.action == 'closed' && github.event.pull_request.merged == true
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/checkout@v4
       - name: Install dependencies
         uses: ./.github/actions/yarn-install
       - name: Run congratulate-dangerfile.js

.github/workflows/ci-website.yaml

@@ -1,12 +1,12 @@
 name: CI Website
 
+permissions:
+  contents: read
+
 on:
   pull_request:
   merge_group:
 
-permissions:
-  contents: read
-
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
@@ -18,36 +18,58 @@ jobs:
     with:
       files: |
         package.json
-        yarn.lock
         packages/twenty-website/**
-        packages/twenty-shared/**
-  website-task:
+  website-build:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
-    timeout-minutes: 30
+    timeout-minutes: 10
     runs-on: ubuntu-latest
-    env:
-      NODE_OPTIONS: '--max-old-space-size=6144'
-    strategy:
-      matrix:
-        task: [lint, typecheck, test]
+    services:
+      postgres:
+        image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
+        env:
+          PGUSER_SUPERUSER: postgres
+          PGPASSWORD_SUPERUSER: postgres
+          ALLOW_NOSSL: 'true'
+          SPILO_PROVIDER: 'local'
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     steps:
-      - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 10
+
       - name: Install dependencies
         uses: ./.github/actions/yarn-install
-      - name: Run ${{ matrix.task }} task
-        uses: ./.github/actions/nx-affected
-        with:
-          tag: scope:website
-          tasks: ${{ matrix.task }}
+
+      - name: Server / Create DB
+        run: PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
+
+      - name: Website / Run migrations
+        run: npx nx database:migrate twenty-website
+        env:
+          DATABASE_PG_URL: postgres://postgres:postgres@localhost:5432/default
+      - name: Website / Build Website
+        run: npx nx build twenty-website
+        env:
+          DATABASE_PG_URL: postgres://postgres:postgres@localhost:5432/default
+          KEYSTATIC_GITHUB_CLIENT_ID: xxx
+          KEYSTATIC_GITHUB_CLIENT_SECRET: xxx
+          KEYSTATIC_SECRET: xxx
+          NEXT_PUBLIC_KEYSTATIC_GITHUB_APP_SLUG: xxx
   ci-website-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
     runs-on: ubuntu-latest
-    needs: [changed-files-check, website-task]
+    needs: [changed-files-check, website-build]
     steps:
       - name: Fail job if any needs failed
         if: contains(needs.*.result, 'failure')

.github/workflows/ci-zapier.yaml

@@ -29,10 +29,15 @@ jobs:
     runs-on: ubuntu-latest
     services:
       postgres:
-        image: postgres:18
+        image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
+          PGUSER_SUPERUSER: postgres
+          PGPASSWORD_SUPERUSER: postgres
+          ALLOW_NOSSL: 'true'
+          SPILO_PROVIDER: 'local'
         ports:
           - 5432:5432
         options: >-
@@ -42,11 +47,14 @@ jobs:
           --health-retries 5
       redis:
         image: redis
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         ports:
           - 6379:6379
     steps:
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies
@@ -69,14 +77,13 @@ jobs:
 
       - name: Server / Start
         run: |
-          npx nx run twenty-server:start:ci &
+          npx nx start twenty-server &
           echo "Waiting for server to be ready..."
-          timeout 60 bash -c 'until curl -sf http://localhost:3000/healthz; do sleep 2; done'
+          timeout 60 bash -c 'until curl -s http://localhost:3000/health; do sleep 2; done'
 
       - name: Start worker
-        working-directory: packages/twenty-server
         run: |
-          NODE_ENV=development node dist/queue-worker/queue-worker.js &
+          npx nx run twenty-server:worker &
           echo "Worker started"
 
       - name: Zapier / Build
@@ -97,8 +104,12 @@ jobs:
       matrix:
         task: [lint, typecheck, validate]
     steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
       - name: Fetch custom Github Actions and base branch history
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 10
       - name: Install dependencies

.github/workflows/claude.yml

@@ -8,12 +8,10 @@ on:
   pull_request_review:
     types: [submitted]
   issues:
-    types: [opened]
+    types: [opened, assigned]
   repository_dispatch:
     types: [claude-core-team-issues]
 
-permissions: {}
-
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.issue.number || github.event.pull_request.number || github.event.client_payload.issue_number }}
   cancel-in-progress: false
@@ -21,30 +19,10 @@ concurrency:
 jobs:
   claude:
     if: |
-      (
-        github.event_name == 'issue_comment' &&
-        contains(github.event.comment.body, '@claude') &&
-        github.event.comment.user.type != 'Bot' &&
-        contains(fromJson('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
-      ) ||
-      (
-        github.event_name == 'pull_request_review_comment' &&
-        contains(github.event.comment.body, '@claude') &&
-        github.event.comment.user.type != 'Bot' &&
-        contains(fromJson('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
-      ) ||
-      (
-        github.event_name == 'pull_request_review' &&
-        contains(github.event.review.body, '@claude') &&
-        github.event.review.user.type != 'Bot' &&
-        contains(fromJson('["OWNER","MEMBER","COLLABORATOR"]'), github.event.review.author_association)
-      ) ||
-      (
-        github.event_name == 'issues' &&
-        github.event.action == 'opened' &&
-        (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')) &&
-        contains(fromJson('["OWNER","MEMBER","COLLABORATOR"]'), github.event.issue.author_association)
-      )
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude') && github.event.comment.user.type != 'Bot') ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude') && github.event.comment.user.type != 'Bot') ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude') && github.event.review.user.type != 'Bot') ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
     runs-on: ubuntu-latest
     timeout-minutes: 60
     permissions:
@@ -72,14 +50,14 @@ jobs:
           - 6379:6379
     steps:
       - name: Checkout repository
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Install dependencies
         uses: ./.github/actions/yarn-install
       - name: Run Claude Code
         id: claude-code
-        uses: anthropics/claude-code-action@dde2242db6af13460b916652159b6ba19a598f30 # v1
+        uses: anthropics/claude-code-action@v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           additional_permissions: |
@@ -144,14 +122,14 @@ jobs:
         ports:
           - 6379:6379
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Install dependencies
         uses: ./.github/actions/yarn-install
       - name: Build prompt from dispatch payload
         id: prompt
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        uses: actions/github-script@v7
         with:
           script: |
             const p = context.payload.client_payload;
@@ -166,7 +144,7 @@ jobs:
             core.setOutput('issue_number', p.issue_number);
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@dde2242db6af13460b916652159b6ba19a598f30 # v1
+        uses: anthropics/claude-code-action@v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           prompt: ${{ steps.prompt.outputs.prompt }}
@@ -181,16 +159,9 @@ jobs:
             }
       - name: Dispatch response to ci-privileged
         if: always()
-        env:
-          GH_TOKEN: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
-          REPO: ${{ steps.prompt.outputs.repo }}
-          ISSUE_NUMBER: ${{ steps.prompt.outputs.issue_number }}
-          RUN_ID: ${{ github.run_id }}
-          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-        run: |
-          gh api repos/twentyhq/ci-privileged/dispatches \
-            -f event_type=claude-cross-repo-response \
-            -f "client_payload[repo]=$REPO" \
-            -f "client_payload[issue_number]=$ISSUE_NUMBER" \
-            -f "client_payload[run_id]=$RUN_ID" \
-            -f "client_payload[run_url]=$RUN_URL"
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
+          repository: twentyhq/ci-privileged
+          event-type: claude-cross-repo-response
+          client-payload: '{"repo": ${{ toJSON(steps.prompt.outputs.repo) }}, "issue_number": ${{ toJSON(steps.prompt.outputs.issue_number) }}, "run_id": ${{ toJSON(github.run_id) }}, "run_url": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"}'

.github/workflows/docs-i18n-pull.yaml

@@ -37,7 +37,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           token: ${{ github.token }}
           repository: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name || github.repository }}
@@ -153,7 +153,8 @@ jobs:
 
       - name: Trigger i18n automerge
         if: github.event_name != 'pull_request' && steps.check_changes.outputs.changes_detected == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.TWENTY_INFRA_TOKEN }}
-        run: |
-          gh api repos/twentyhq/twenty-infra/dispatches -f event_type=i18n-pr-ready
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.TWENTY_INFRA_TOKEN }}
+          repository: twentyhq/twenty-infra
+          event-type: i18n-pr-ready

.github/workflows/docs-i18n-push.yaml

@@ -24,7 +24,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           token: ${{ github.token }}
           ref: ${{ github.ref }}
@@ -36,7 +36,7 @@ jobs:
         run: yarn docs:generate-navigation-template
 
       - name: Upload docs to Crowdin
-        uses: crowdin/github-action@8868a33591d21088edfc398968173a3b98d51706 # v2
+        uses: crowdin/github-action@v2
         with:
           upload_sources: true
           upload_translations: false

.github/workflows/external-contributor-pr-auto-draft.yaml

@@ -1,28 +0,0 @@
-name: Auto-Draft External PRs
-
-on:
-  pull_request_target:
-    types: [opened]
-
-permissions: {}
-
-jobs:
-  dispatch:
-    if: |
-      github.event.pull_request.draft == false &&
-      github.event.pull_request.author_association != 'MEMBER' &&
-      github.event.pull_request.author_association != 'OWNER' &&
-      github.event.pull_request.author_association != 'COLLABORATOR'
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - name: Dispatch to ci-privileged
-        env:
-          GH_TOKEN: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-          PR_NODE_ID: ${{ github.event.pull_request.node_id }}
-        run: |
-          gh api repos/twentyhq/ci-privileged/dispatches \
-            -f event_type=convert-pr-to-draft \
-            -f "client_payload[pr_number]=$PR_NUMBER" \
-            -f "client_payload[pr_node_id]=$PR_NODE_ID"

.github/workflows/i18n-pull.yaml

@@ -35,7 +35,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           token: ${{ github.token }}
           ref: ${{ github.head_ref || github.ref_name }}
@@ -69,11 +69,13 @@ jobs:
 
       - name: Pull translations from Crowdin
         if: inputs.force_pull || steps.compile_translations_strict.outcome == 'failure'
-        uses: crowdin/github-action@8868a33591d21088edfc398968173a3b98d51706 # v2
+        uses: crowdin/github-action@v2
         with:
           upload_sources: false
           upload_translations: false
           download_translations: true
+          source: '**/en.po'
+          translation: '%original_path%/%locale%.po'
           export_only_approved: false
           localization_branch_name: i18n
           base_url: 'https://twenty.api.crowdin.com'
@@ -139,7 +141,8 @@ jobs:
 
       - name: Trigger i18n automerge
         if: steps.compile_translations.outputs.changes_detected == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.TWENTY_INFRA_TOKEN }}
-        run: |
-          gh api repos/twentyhq/twenty-infra/dispatches -f event_type=i18n-pr-ready
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.TWENTY_INFRA_TOKEN }}
+          repository: twentyhq/twenty-infra
+          event-type: i18n-pr-ready

.github/workflows/i18n-push.yaml

@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        uses: actions/checkout@v4
         with:
           token: ${{ github.token }}
           ref: main
@@ -80,7 +80,7 @@ jobs:
 
       - name: Upload missing translations
         if: steps.check_extract_changes.outputs.changes_detected == 'true'
-        uses: crowdin/github-action@8868a33591d21088edfc398968173a3b98d51706 # v2
+        uses: crowdin/github-action@v2
         with:
           upload_sources: true
           upload_translations: true
@@ -105,7 +105,8 @@ jobs:
 
       - name: Trigger i18n automerge
         if: steps.check_extract_changes.outputs.changes_detected == 'true' || steps.check_compile_changes.outputs.changes_detected == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.TWENTY_INFRA_TOKEN }}
-        run: |
-          gh api repos/twentyhq/twenty-infra/dispatches -f event_type=i18n-pr-ready
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.TWENTY_INFRA_TOKEN }}
+          repository: twentyhq/twenty-infra
+          event-type: i18n-pr-ready

.github/workflows/post-ci-comments.yaml

@@ -16,7 +16,7 @@ jobs:
     steps:
       - name: Get PR number from workflow run
         id: pr-info
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        uses: actions/github-script@v7
         with:
           script: |
             const runId = context.payload.workflow_run.id;
@@ -63,16 +63,9 @@ jobs:
 
       - name: Dispatch to ci-privileged
         if: steps.pr-info.outputs.has_pr == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
-          PR_NUMBER: ${{ steps.pr-info.outputs.pr_number }}
-          RUN_ID: ${{ steps.pr-info.outputs.run_id }}
-          REPOSITORY: ${{ github.repository }}
-          BRANCH_STATE: ${{ github.event.workflow_run.head_branch }}
-        run: |
-          gh api repos/twentyhq/ci-privileged/dispatches \
-            -f event_type=breaking-changes-report \
-            -f "client_payload[pr_number]=$PR_NUMBER" \
-            -f "client_payload[run_id]=$RUN_ID" \
-            -f "client_payload[repo]=$REPOSITORY" \
-            -f "client_payload[branch_state]=$BRANCH_STATE"
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
+          repository: twentyhq/ci-privileged
+          event-type: breaking-changes-report
+          client-payload: '{"pr_number": ${{ toJSON(steps.pr-info.outputs.pr_number) }}, "run_id": ${{ toJSON(steps.pr-info.outputs.run_id) }}, "repo": ${{ toJSON(github.repository) }}, "branch_state": ${{ toJSON(github.event.workflow_run.head_branch) }}}'

.github/workflows/pr-auto-review-dispatch.yaml

@@ -1,26 +0,0 @@
-name: PR Review Dispatch
-
-on:
-  pull_request_target:
-    types: [ready_for_review, synchronize]
-
-permissions: {}
-
-concurrency:
-  group: pr-review-${{ github.event.pull_request.number }}
-  cancel-in-progress: true
-
-jobs:
-  dispatch:
-    if: github.event.pull_request.draft == false
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - name: Dispatch to ci-privileged
-        env:
-          GH_TOKEN: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-        run: |
-          gh api repos/twentyhq/ci-privileged/dispatches \
-            -f event_type=pr-review \
-            -f "client_payload[pr_number]=$PR_NUMBER"

.github/workflows/preview-env-dispatch.yaml

@@ -1,6 +1,7 @@
 name: 'Preview Environment Dispatch'
 
-permissions: {}
+permissions:
+  contents: write
 
 on:
   pull_request_target:
@@ -10,6 +11,7 @@ on:
       - packages/twenty-server/**
       - packages/twenty-front/**
       - .github/workflows/preview-env-dispatch.yaml
+      - .github/workflows/preview-env-keepalive.yaml
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -33,15 +35,18 @@ jobs:
     timeout-minutes: 5
     runs-on: ubuntu-latest
     steps:
-      - name: Dispatch preview-env to ci-privileged
-        env:
-          GH_TOKEN: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-          REPOSITORY: ${{ github.repository }}
-        run: |
-          gh api repos/twentyhq/ci-privileged/dispatches \
-            -f event_type=preview-environment \
-            -f "client_payload[pr_number]=$PR_NUMBER" \
-            -f "client_payload[pr_head_sha]=$PR_HEAD_SHA" \
-            -f "client_payload[repo]=$REPOSITORY"
+      - name: Trigger preview environment workflow
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          event-type: preview-environment
+          client-payload: '{"pr_number": "${{ github.event.pull_request.number }}", "pr_head_sha": "${{ github.event.pull_request.head.sha }}", "repo_full_name": "${{ github.repository }}"}'
+
+      - name: Dispatch to ci-privileged for PR comment
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
+          repository: twentyhq/ci-privileged
+          event-type: preview-env-url
+          client-payload: '{"pr_number": ${{ toJSON(github.event.pull_request.number) }}, "keepalive_dispatch_time": ${{ toJSON(github.event.pull_request.updated_at) }}, "repo": ${{ toJSON(github.repository) }}}'

.github/workflows/preview-env-keepalive.yaml

@@ -0,0 +1,139 @@
+name: 'Preview Environment Keep Alive'
+
+permissions:
+  contents: read
+
+on:
+  repository_dispatch:
+    types: [preview-environment]
+
+jobs:
+  preview-environment:
+    timeout-minutes: 310
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.client_payload.pr_head_sha }}
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
+
+      - name: Run compose setup
+        run: |
+          echo "Patching docker-compose.yml..."
+          # change image to localbuild using yq
+          yq eval 'del(.services.server.image)' -i packages/twenty-docker/docker-compose.yml
+          yq eval '.services.server.build.context = "../../"' -i packages/twenty-docker/docker-compose.yml
+          yq eval '.services.server.build.dockerfile = "./packages/twenty-docker/twenty/Dockerfile"' -i packages/twenty-docker/docker-compose.yml
+          yq eval '.services.server.build.target = "twenty"' -i packages/twenty-docker/docker-compose.yml
+
+          yq eval 'del(.services.worker.image)' -i packages/twenty-docker/docker-compose.yml
+          yq eval '.services.worker.build.context = "../../"' -i packages/twenty-docker/docker-compose.yml
+          yq eval '.services.worker.build.dockerfile = "./packages/twenty-docker/twenty/Dockerfile"' -i packages/twenty-docker/docker-compose.yml
+          yq eval '.services.worker.build.target = "twenty"' -i packages/twenty-docker/docker-compose.yml
+
+          echo "Adding SIGN_IN_PREFILLED environment variable to server service..."
+          yq eval '.services.server.environment.SIGN_IN_PREFILLED = "${SIGN_IN_PREFILLED}"' -i packages/twenty-docker/docker-compose.yml
+
+          echo "Setting up .env file..."
+          cp packages/twenty-docker/.env.example packages/twenty-docker/.env
+
+          echo "Generating secrets..."
+          echo "" >> packages/twenty-docker/.env
+          echo "# === Randomly generated secrets ===" >> packages/twenty-docker/.env
+          echo "APP_SECRET=$(openssl rand -base64 32)" >> packages/twenty-docker/.env
+          echo "PG_DATABASE_PASSWORD=$(openssl rand -hex 16)" >> packages/twenty-docker/.env
+          echo "SIGN_IN_PREFILLED=true" >> packages/twenty-docker/.env
+          echo "Docker compose build..."
+          cd packages/twenty-docker/
+          docker compose build
+        working-directory: ./
+
+      - name: Create Tunnel
+        id: expose-tunnel
+        uses: codetalkio/expose-tunnel@v1.5.0
+        with:
+          service: bore.pub
+          port: 3000
+
+      - name: Start services with correct SERVER_URL
+        env:
+          TUNNEL_URL: ${{ steps.expose-tunnel.outputs.tunnel-url }}
+        run: |
+          cd packages/twenty-docker/
+
+          echo "Setting SERVER_URL to $TUNNEL_URL"
+          sed -i '/SERVER_URL=/d' .env
+          echo "" >> .env
+          echo "SERVER_URL=$TUNNEL_URL" >> .env
+
+          # Start the services
+          echo "Docker compose up..."
+          docker compose up -d || {
+              echo "Docker compose failed to start"
+              docker compose logs
+              exit 1
+          }
+
+          echo "Waiting for services to be ready..."
+          count=0
+          while [ ! $(docker inspect --format='{{.State.Health.Status}}' twenty-db-1) = "healthy" ] || [ ! $(docker inspect --format='{{.State.Health.Status}}' twenty-server-1) = "healthy" ]; do
+              sleep 5
+              count=$((count+1))
+              if [ $count -gt 60 ]; then
+                  echo "Timeout waiting for services to be ready"
+                  docker compose logs
+                  exit 1
+              fi
+              echo "Still waiting for services... ($count/60)"
+          done
+
+          echo "All services are up and running!"
+        working-directory: ./
+
+      - name: Seed Dev Workspace
+        run: |
+          cd packages/twenty-docker/
+          echo "Seeding full dev workspace..."
+          if ! docker compose exec -T server yarn command:prod -- workspace:seed:dev; then
+            echo "❌ Seeding full dev workspace failed. Dumping server logs..."
+            docker compose logs server
+            exit 1
+          fi
+        working-directory: ./
+
+      - name: Output tunnel URL
+        env:
+          TUNNEL_URL: ${{ steps.expose-tunnel.outputs.tunnel-url }}
+        run: |
+          echo "✅ Preview Environment Ready!"
+          echo "🔗 Preview URL: $TUNNEL_URL"
+          echo "⏱️ This environment will be available for 5 hours"
+          echo "## 🚀 Preview Environment Ready!" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "Preview URL: $TUNNEL_URL" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "This environment will automatically shut down after 5 hours." >> "$GITHUB_STEP_SUMMARY"
+          echo "$TUNNEL_URL" > tunnel-url.txt
+
+      - name: Upload tunnel URL artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: tunnel-url
+          path: tunnel-url.txt
+          retention-days: 1
+
+      - name: Keep tunnel alive for 5 hours
+        run: timeout 300m sleep 18000 # Stop on whichever we reach first (300m or 5hour sleep)
+
+      - name: Cleanup
+        if: always()
+        run: |
+          cd packages/twenty-docker/
+          docker compose down -v
+        working-directory: ./

.github/workflows/visual-regression-dispatch.yaml

@@ -23,7 +23,7 @@ jobs:
     steps:
       - name: Determine project and artifact name
         id: project
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        uses: actions/github-script@v7
         with:
           script: |
             const workflowName = context.payload.workflow_run.name;
@@ -43,7 +43,7 @@ jobs:
 
       - name: Check if storybook artifact exists
         id: check-artifact
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        uses: actions/github-script@v7
         with:
           script: |
             const artifactName = '${{ steps.project.outputs.artifact_name }}';
@@ -65,7 +65,7 @@ jobs:
       - name: Get PR number
         if: steps.check-artifact.outputs.exists == 'true'
         id: pr-info
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        uses: actions/github-script@v7
         with:
           script: |
             const headBranch = context.payload.workflow_run.head_branch;
@@ -107,7 +107,7 @@ jobs:
 
       - name: Download storybook artifact from triggering run
         if: steps.check-artifact.outputs.exists == 'true' && steps.pr-info.outputs.has_pr == 'true'
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        uses: actions/download-artifact@v4
         with:
           name: ${{ steps.project.outputs.artifact_name }}
           path: storybook-static
@@ -120,7 +120,7 @@ jobs:
 
       - name: Upload storybook tarball
         if: steps.check-artifact.outputs.exists == 'true' && steps.pr-info.outputs.has_pr == 'true'
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@v4
         with:
           name: ${{ steps.project.outputs.tarball_name }}
           path: /tmp/${{ steps.project.outputs.tarball_file }}
@@ -128,20 +128,17 @@ jobs:
 
       - name: Dispatch to ci-privileged
         if: steps.check-artifact.outputs.exists == 'true' && steps.pr-info.outputs.has_pr == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
-          PR_NUMBER: ${{ steps.pr-info.outputs.pr_number }}
-          RUN_ID: ${{ github.run_id }}
-          REPOSITORY: ${{ github.repository }}
-          PROJECT: ${{ steps.project.outputs.project }}
-          BRANCH: ${{ github.event.workflow_run.head_branch }}
-          COMMIT: ${{ github.event.workflow_run.head_sha }}
-        run: |
-          gh api repos/twentyhq/ci-privileged/dispatches \
-            -f event_type=visual-regression \
-            -f "client_payload[pr_number]=$PR_NUMBER" \
-            -f "client_payload[run_id]=$RUN_ID" \
-            -f "client_payload[repo]=$REPOSITORY" \
-            -f "client_payload[project]=$PROJECT" \
-            -f "client_payload[branch]=$BRANCH" \
-            -f "client_payload[commit]=$COMMIT"
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
+          repository: twentyhq/ci-privileged
+          event-type: visual-regression
+          client-payload: >-
+            {
+              "pr_number": "${{ steps.pr-info.outputs.pr_number }}",
+              "run_id": "${{ github.run_id }}",
+              "repo": "${{ github.repository }}",
+              "project": "${{ steps.project.outputs.project }}",
+              "branch": "${{ github.event.workflow_run.head_branch }}",
+              "commit": "${{ github.event.workflow_run.head_sha }}"
+            }

.github/workflows/website-i18n-pull.yaml

@@ -1,134 +0,0 @@
-# Pull down website translations from Crowdin every two hours or when triggered manually.
-# When force_pull input is true, translations will be pulled regardless of compilation status.
-
-name: 'Pull website translations from Crowdin'
-
-permissions:
-  contents: write
-  pull-requests: write
-
-on:
-  schedule:
-    - cron: '0 */2 * * *' # Every two hours.
-  workflow_dispatch:
-    inputs:
-      force_pull:
-        description: 'Force pull translations regardless of compilation status'
-        required: false
-        type: boolean
-        default: false
-  workflow_call:
-    inputs:
-      force_pull:
-        description: 'Force pull translations regardless of compilation status'
-        required: false
-        type: boolean
-        default: false
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
-
-jobs:
-  pull_website_translations:
-    name: Pull website translations
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-        with:
-          token: ${{ github.token }}
-          ref: ${{ github.head_ref || github.ref_name }}
-
-      - name: Setup website i18n branch
-        run: |
-          git fetch origin i18n-website || true
-          git checkout -B i18n-website origin/i18n-website || git checkout -b i18n-website
-
-      - name: Install dependencies
-        uses: ./.github/actions/yarn-install
-
-      - name: Build twenty-shared
-        run: npx nx build twenty-shared
-
-      # Strict mode fails if there are missing website translations.
-      - name: Compile website translations
-        id: compile_translations_strict
-        run: npx nx run twenty-website:lingui:compile --strict
-        continue-on-error: true
-
-      - name: Stash any changes before pulling translations
-        run: |
-          git config --global user.name 'github-actions'
-          git config --global user.email 'github-actions@twenty.com'
-          git add .
-          git stash
-
-      - name: Pull website translations from Crowdin
-        if: inputs.force_pull || steps.compile_translations_strict.outcome == 'failure'
-        uses: crowdin/github-action@8868a33591d21088edfc398968173a3b98d51706 # v2
-        with:
-          upload_sources: false
-          upload_translations: false
-          download_translations: true
-          source: 'packages/twenty-website/src/locales/en.po'
-          translation: 'packages/twenty-website/src/locales/%locale%.po'
-          export_only_approved: false
-          localization_branch_name: i18n-website
-          base_url: 'https://twenty.api.crowdin.com'
-          auto_approve_imported: false
-          import_eq_suggestions: false
-          download_sources: false
-          push_sources: false
-          skip_untranslated_strings: false
-          skip_untranslated_files: false
-          push_translations: false
-          create_pull_request: false
-          skip_ref_checkout: true
-          dryrun_action: false
-          config: '.github/crowdin-website.yml'
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
-          # Website translations project
-          CROWDIN_PROJECT_ID: '4'
-          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
-
-      # As the files are extracted from a Docker container, they belong to root:root.
-      # We need to fix this before the next steps.
-      - name: Fix file permissions
-        run: sudo chown -R runner:docker .
-
-      - name: Compile website translations
-        id: compile_translations
-        run: |
-          npx nx run twenty-website:lingui:compile
-          git status
-          git add packages/twenty-website/src/locales
-          if ! git diff --staged --quiet --exit-code; then
-            git commit -m "chore: compile website translations"
-            echo "changes_detected=true" >> $GITHUB_OUTPUT
-          else
-            echo "changes_detected=false" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Push changes
-        if: steps.compile_translations.outputs.changes_detected == 'true'
-        run: git push origin HEAD:i18n-website
-
-      - name: Create pull request
-        if: steps.compile_translations.outputs.changes_detected == 'true'
-        run: |
-          if git diff --name-only origin/main..HEAD | grep -q .; then
-            gh pr create -B main -H i18n-website --title 'i18n - website translations' --body 'Created by Github action' || true
-          else
-            echo "No file differences between branches, skipping PR creation"
-          fi
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Trigger i18n automerge
-        if: steps.compile_translations.outputs.changes_detected == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.TWENTY_INFRA_TOKEN }}
-        run: |
-          gh api repos/twentyhq/twenty-infra/dispatches -f event_type=i18n-pr-ready

.github/workflows/website-i18n-push.yaml

@@ -1,110 +0,0 @@
-name: 'Push website translations to Crowdin'
-
-permissions:
-  contents: write
-  pull-requests: write
-
-on:
-  workflow_dispatch:
-  workflow_call:
-  push:
-    branches: ['main']
-    paths:
-      - 'packages/twenty-website/**'
-      - '.github/crowdin-website.yml'
-      - '.github/workflows/website-i18n-push.yaml'
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
-
-jobs:
-  extract_website_translations:
-    name: Extract and upload website translations
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-        with:
-          token: ${{ github.token }}
-          ref: main
-
-      - name: Setup website i18n branch
-        run: |
-          git fetch origin i18n-website || true
-          git checkout -B i18n-website origin/i18n-website || git checkout -b i18n-website
-
-      - name: Install dependencies
-        uses: ./.github/actions/yarn-install
-
-      - name: Build dependencies
-        run: npx nx build twenty-shared
-
-      - name: Extract website translations
-        run: npx nx run twenty-website:lingui:extract
-
-      - name: Check and commit extracted files
-        id: check_extract_changes
-        run: |
-          git config --global user.name 'github-actions'
-          git config --global user.email 'github-actions@twenty.com'
-          git add packages/twenty-website/src/locales
-          if ! git diff --staged --quiet --exit-code; then
-            git commit -m "chore: extract website translations"
-            echo "changes_detected=true" >> $GITHUB_OUTPUT
-          else
-            echo "changes_detected=false" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Compile website translations
-        run: npx nx run twenty-website:lingui:compile
-
-      - name: Check and commit compiled files
-        id: check_compile_changes
-        run: |
-          git config --global user.name 'github-actions'
-          git config --global user.email 'github-actions@twenty.com'
-          git add packages/twenty-website/src/locales/generated
-          if ! git diff --staged --quiet --exit-code; then
-            git commit -m "chore: compile website translations"
-            echo "changes_detected=true" >> $GITHUB_OUTPUT
-          else
-            echo "changes_detected=false" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Push changes and create remote branch if needed
-        if: steps.check_extract_changes.outputs.changes_detected == 'true' || steps.check_compile_changes.outputs.changes_detected == 'true'
-        run: git push origin HEAD:i18n-website
-
-      - name: Upload missing website translations
-        if: steps.check_extract_changes.outputs.changes_detected == 'true'
-        uses: crowdin/github-action@8868a33591d21088edfc398968173a3b98d51706 # v2
-        with:
-          upload_sources: true
-          upload_translations: true
-          download_translations: false
-          localization_branch_name: i18n-website
-          base_url: 'https://twenty.api.crowdin.com'
-          config: '.github/crowdin-website.yml'
-        env:
-          # Website translations project
-          CROWDIN_PROJECT_ID: '4'
-          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
-
-      - name: Create a pull request
-        if: steps.check_extract_changes.outputs.changes_detected == 'true' || steps.check_compile_changes.outputs.changes_detected == 'true'
-        run: |
-          if git diff --name-only origin/main..HEAD | grep -q .; then
-            gh pr create -B main -H i18n-website --title 'i18n - website translations' --body 'Created by Github action' || true
-          else
-            echo "No file differences between branches, skipping PR creation"
-          fi
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Trigger i18n automerge
-        if: steps.check_extract_changes.outputs.changes_detected == 'true' || steps.check_compile_changes.outputs.changes_detected == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.TWENTY_INFRA_TOKEN }}
-        run: |
-          gh api repos/twentyhq/twenty-infra/dispatches -f event_type=i18n-pr-ready

.github/workflows/website-preview-dispatch.yaml

@@ -1,69 +0,0 @@
-name: 'Website Preview Dispatch'
-
-permissions:
-  contents: read
-
-on:
-  pull_request:
-    types: [opened, synchronize, reopened, closed, labeled]
-    paths:
-      - packages/twenty-website/**
-      - .github/workflows/website-preview-dispatch.yaml
-
-concurrency:
-  # Keyed on PR number so independent PRs don't cancel each other. `github.ref`
-  # would resolve to the base branch under pull_request and collide.
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
-  cancel-in-progress: true
-
-jobs:
-  trigger-build:
-    # Same fork PRs from outside the org don't have `secrets.*` so the dispatch
-    # call would fail anyway — skip explicitly to avoid noise.
-    if: |
-      github.event.pull_request.head.repo.full_name == github.repository &&
-      github.event.action != 'closed' && (
-        (github.event.action == 'labeled' && github.event.label.name == 'preview-website') ||
-        (
-          (
-            github.event.pull_request.author_association == 'MEMBER' ||
-            github.event.pull_request.author_association == 'OWNER' ||
-            github.event.pull_request.author_association == 'COLLABORATOR'
-          ) && contains(fromJSON('["opened","synchronize","reopened"]'), github.event.action)
-        )
-      )
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - name: Dispatch website-preview-build to ci-privileged
-        env:
-          GH_TOKEN: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-          PR_HEAD_REF: ${{ github.event.pull_request.head.ref }}
-        run: |
-          gh api repos/twentyhq/ci-privileged/dispatches \
-            -f event_type=website-preview-build \
-            -f "client_payload[pr_number]=$PR_NUMBER" \
-            -f "client_payload[pr_head_sha]=$PR_HEAD_SHA" \
-            -f "client_payload[pr_head_ref]=$PR_HEAD_REF"
-
-  trigger-cleanup:
-    # Covers both merge and close-without-merge — pull_request `closed` fires
-    # for both. PRs left open forever are covered by OpenNext's
-    # `maxVersionAgeDays: 14` + `maxNumberOfVersions: 50` auto-pruning in
-    # open-next.config.ts, so nothing leaks even if cleanup never runs.
-    if: |
-      github.event.pull_request.head.repo.full_name == github.repository &&
-      github.event.action == 'closed'
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - name: Dispatch website-preview-cleanup to ci-privileged
-        env:
-          GH_TOKEN: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-        run: |
-          gh api repos/twentyhq/ci-privileged/dispatches \
-            -f event_type=website-preview-cleanup \
-            -f "client_payload[pr_number]=$PR_NUMBER"

.gitignore

@@ -1,8 +1,7 @@
 **/**/.env
 .DS_Store
 /.idea
-.claude/
-.cursor/debug-*.log
+.claude/settings.json
 **/**/node_modules/
 .cache
 
@@ -53,5 +52,3 @@ mcp.json
 /.junie/
 TRANSLATION_QA_REPORT.md
 .playwright-mcp/
-.playwright-cli/
-output/playwright/

.oxfmtrc.jsonc

@@ -1,27 +0,0 @@
-{
-  "$schema": "./node_modules/oxfmt/configuration_schema.json",
-  "singleQuote": true,
-  "trailingComma": "all",
-  "endOfLine": "lf",
-  "printWidth": 80,
-  "sortPackageJson": false,
-  "ignorePatterns": [
-    "**/dist/**",
-    "**/build/**",
-    "**/lib/**",
-    "**/.next/**",
-    "**/coverage/**",
-    "**/generated/**",
-    "**/generated-admin/**",
-    "**/generated-metadata/**",
-    "**/.cache/**",
-    "**/node_modules/**",
-    "**/*.min.js",
-    "**/*.snap",
-    "**/*.md",
-    "**/*.mdx",
-    "**/seed-project/**/*.mjs",
-    "packages/twenty-zapier/build/**",
-    "**/upgrade-version-command/**"
-  ]
-}

.vscode/twenty.code-workspace

@@ -43,46 +43,6 @@
     {
       "name": "packages/twenty-e2e-testing",
       "path": "../packages/twenty-e2e-testing"
-    },
-    {
-      "name": "packages/twenty-docs",
-      "path": "../packages/twenty-docs"
-    },
-    {
-      "name": "packages/create-twenty-app",
-      "path": "../packages/create-twenty-app"
-    },
-    {
-      "name": "packages/twenty-apps",
-      "path": "../packages/twenty-apps"
-    },
-    {
-      "name": "packages/twenty-claude-skills",
-      "path": "../packages/twenty-claude-skills"
-    },
-    {
-      "name": "packages/twenty-cli",
-      "path": "../packages/twenty-cli"
-    },
-    {
-      "name": "packages/twenty-client-sdk",
-      "path": "../packages/twenty-client-sdk"
-    },
-    {
-      "name": "packages/twenty-companion",
-      "path": "../packages/twenty-companion"
-    },
-    {
-      "name": "packages/twenty-front-component-renderer",
-      "path": "../packages/twenty-front-component-renderer"
-    },
-    {
-      "name": "packages/twenty-sdk",
-      "path": "../packages/twenty-sdk"
-    },
-    {
-      "name": "packages/twenty-website",
-      "path": "../packages/twenty-website"
     }
   ],
   "settings": {

.yarnrc.yml

@@ -4,14 +4,6 @@ enableHardenedMode: true
 
 enableInlineHunks: true
 
-enableScripts: false
-
 nodeLinker: node-modules
 
-npmMinimalAgeGate: 3d
-
-npmPreapprovedPackages:
-  - twenty-sdk
-  - twenty-client-sdk
-
 yarnPath: .yarn/releases/yarn-4.13.0.cjs

CLAUDE.md

@@ -71,10 +71,13 @@ npx nx build twenty-server
 # Database management
 npx nx database:reset twenty-server         # Reset database
 npx nx run twenty-server:database:init:prod # Initialize database
-npx nx run twenty-server:database:migrate:prod # Run instance commands (fast only)
+npx nx run twenty-server:database:migrate:prod # Run migrations
 
-# Generate an instance command (fast or slow)
-npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>
+# Generate migration (replace [name] with kebab-case descriptive name)
+npx nx run twenty-server:typeorm migration:generate src/database/typeorm/core/migrations/common/[name] -d src/database/typeorm/core/core.datasource.ts
+
+# Sync metadata
+npx nx run twenty-server:command workspace:sync-metadata
 ```
 
 ### Database Inspection (Postgres MCP)
@@ -84,7 +87,7 @@ A read-only Postgres MCP server is configured in `.mcp.json`. Use it to:
 - Verify migration results (columns, types, constraints) after running migrations
 - Explore the multi-tenant schema structure (core, metadata, workspace-specific schemas)
 - Debug issues by querying raw data to confirm whether a bug is frontend, backend, or data-level
-- Inspect metadata tables to debug GraphQL schema generation issues
+- Inspect metadata tables to debug GraphQL schema generation or `workspace:sync-metadata` issues
 
 This server is read-only — for write operations (reset, migrations, sync), use the CLI commands above.
 
@@ -110,8 +113,7 @@ packages/
 ├── twenty-ui/             # Shared UI components library
 ├── twenty-shared/         # Common types and utilities
 ├── twenty-emails/         # Email templates with React Email
-├── twenty-website/    # Next.js marketing website
-├── twenty-docs/           # Documentation website
+├── twenty-website/        # Next.js documentation website
 ├── twenty-zapier/         # Zapier integration
 └── twenty-e2e-testing/    # Playwright E2E tests
 ```
@@ -159,17 +161,14 @@ packages/
 - **Redis** for caching and session management
 - **BullMQ** for background job processing
 
-### Database & Upgrade Commands
+### Database & Migrations
 - **PostgreSQL** as primary database
 - **Redis** for caching and sessions
 - **ClickHouse** for analytics (when enabled)
-- When changing entity files, generate an **instance command** (`database:migrate:generate --name <name> --type <fast|slow>`)
-- **Fast** instance commands handle schema changes; **slow** ones add a `runDataMigration` step for data backfills
-- **Workspace commands** iterate over all active/suspended workspaces for per-workspace upgrades
-- Commands use `@RegisteredInstanceCommand` and `@RegisteredWorkspaceCommand` decorators for automatic discovery
-- Include both `up` and `down` logic in instance commands
-- Never delete or rewrite committed instance command `up`/`down` logic
-- See `packages/twenty-server/docs/UPGRADE_COMMANDS.md` for full documentation
+- Always generate migrations when changing entity files
+- Migration names must be kebab-case (e.g. `add-agent-turn-evaluation`)
+- Include both `up` and `down` logic in migrations
+- Never delete or rewrite committed migrations
 
 ### Utility Helpers
 Use existing helpers from `twenty-shared` instead of manual type guards:
@@ -182,7 +181,7 @@ IMPORTANT: Use Context7 for code generation, setup or configuration steps, or li
 ### Before Making Changes
 1. Always run linting (`lint:diff-with-main`) and type checking after code changes
 2. Test changes with relevant test suites (prefer single-file test runs)
-3. Ensure instance commands are generated for entity changes (`database:migrate:generate`)
+3. Ensure database migrations are generated for entity changes
 4. Check that GraphQL schema changes are backward compatible
 5. Run `graphql:generate` after any GraphQL schema changes
 

README.md

@@ -4,161 +4,123 @@
   </a>
 </p>
 
-<h2 align="center" >The #1 Open-Source CRM</h2>
+<h2 align="center" >The #1 Open-Source CRM </h2>
+
+<p align="center"><a href="https://twenty.com">🌐 Website</a> · <a href="https://docs.twenty.com">📚 Documentation</a> · <a href="https://github.com/orgs/twentyhq/projects/1"><img src="./packages/twenty-website/public/images/readme/planner-icon.svg" width="12" height="12"/> Roadmap </a> · <a href="https://discord.gg/cx5n4Jzs57"><img src="./packages/twenty-website/public/images/readme/discord-icon.svg" width="12" height="12"/> Discord</a> · <a href="https://www.figma.com/file/xt8O9mFeLl46C5InWwoMrN/Twenty"><img src="./packages/twenty-website/public/images/readme/figma-icon.png"  width="12" height="12"/>  Figma</a></p>
+<br />
 
-<p align="center"><a href="https://twenty.com"><img src="./packages/twenty-website/public/images/readme/globe-icon.svg" width="12" height="12"/> Website</a> · <a href="https://docs.twenty.com"><img src="./packages/twenty-website/public/images/readme/book-icon.svg" width="12" height="12"/> Documentation</a> · <a href="https://github.com/orgs/twentyhq/projects/1"><img src="./packages/twenty-website/public/images/readme/map-icon.svg" width="12" height="12"/> Roadmap </a> · <a href="https://discord.gg/cx5n4Jzs57"><img src="./packages/twenty-website/public/images/readme/discord-icon.svg" width="12" height="12"/> Discord</a> · <a href="https://www.figma.com/file/xt8O9mFeLl46C5InWwoMrN/Twenty"><img src="./packages/twenty-website/public/images/readme/figma-icon.webp"  width="12" height="12"/>  Figma</a></p>
 
 <p align="center">
   <a href="https://www.twenty.com">
     <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website/public/images/readme/github-cover-dark.webp" />
-      <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website/public/images/readme/github-cover-light.webp" />
-      <img src="./packages/twenty-website/public/images/readme/github-cover-light.webp" alt="Twenty banner" />
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-website/public/images/readme/github-cover-dark.png" />
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-website/public/images/readme/github-cover-light.png" />
+      <img src="./packages/twenty-website/public/images/readme/github-cover-light.png" alt="Cover" />
     </picture>
   </a>
 </p>
 
 <br />
 
-# Why Twenty
-
-Twenty gives technical teams the building blocks for a custom CRM that meets complex business needs and quickly adapts as the business evolves. Twenty is the CRM you build, ship, and version like the rest of your stack.
-
-<a href="https://twenty.com/resources/why-twenty"><img src="./packages/twenty-website/public/images/readme/star-icon.svg" width="14" height="14"/> Learn more about why we built Twenty</a>
-
-<br />
-
 # Installation
 
-### <img src="./packages/twenty-website/public/images/readme/globe-icon.svg" width="14" height="14"/> Cloud
+See:
+🚀 [Self-hosting](https://docs.twenty.com/developers/self-host/capabilities/docker-compose)
+🖥️ [Local Setup](https://docs.twenty.com/developers/contribute/capabilities/local-setup)
 
-The fastest way to get started. Sign up at [twenty.com](https://twenty.com) and spin up a workspace in under a minute, with no infrastructure to manage and always up to date.
+# Why Twenty
 
-### <img src="./packages/twenty-website/public/images/readme/book-icon.svg" width="14" height="14"/> Build an app
+We built Twenty for three reasons:
 
-Scaffold a new app with the Twenty CLI:
+**CRMs are too expensive, and users are trapped.** Companies use locked-in customer data to hike prices. It shouldn't be that way.
 
-```bash
-npx create-twenty-app my-app
-```
+**A fresh start is required to build a better experience.** We can learn from past mistakes and craft a cohesive experience inspired by new UX patterns from tools like Notion, Airtable or Linear.
 
-Define objects, fields, and views as code:
-
-```ts
-import { defineObject, FieldType } from 'twenty-sdk/define';
-
-export default defineObject({
-  nameSingular: 'deal',
-  namePlural: 'deals',
-  labelSingular: 'Deal',
-  labelPlural: 'Deals',
-  fields: [
-    { name: 'name', label: 'Name', type: FieldType.TEXT },
-    { name: 'amount', label: 'Amount', type: FieldType.CURRENCY },
-    { name: 'closeDate', label: 'Close Date', type: FieldType.DATE_TIME },
-  ],
-});
-```
-
-Then ship it to your workspace:
-
-```bash
-npx twenty app:publish --private
-```
-
-See the [app development guide](https://docs.twenty.com/developers/extend/apps/getting-started) for objects, views, agents, and logic functions.
-
-### <img src="./packages/twenty-website/public/images/readme/rocket-icon.svg" width="14" height="14"/> Self-hosting
-
-Run Twenty on your own infrastructure with [Docker Compose](https://docs.twenty.com/developers/self-host/capabilities/docker-compose), or contribute locally via the [local setup guide](https://docs.twenty.com/developers/contribute/capabilities/local-setup).
+**We believe in open-source and community.** Hundreds of developers are already building Twenty together. Once we have plugin capabilities, a whole ecosystem will grow around it.
 
-<br />
 <br />
 
-# Everything you need
+# What You Can Do With Twenty
 
-Twenty gives you the building blocks of a modern CRM (objects, views, workflows, and agents) and lets you extend them as code. Here's a tour of what's in the box.
+Please feel free to flag any specific needs you have by creating an issue.
 
-Want to go deeper? Read the <a href="https://docs.twenty.com/user-guide/introduction"><img src="./packages/twenty-website/public/images/readme/planner-icon.svg" width="14" height="14"/> User Guide</a> for product walkthroughs, or the <a href="https://docs.twenty.com"><img src="./packages/twenty-website/public/images/readme/book-icon.svg" width="14" height="14"/> Documentation</a> for developer reference.
+Below are a few features we have implemented to date:
 
-<table align="center">
-  <tr>
-    <td width="50%">
-      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website/public/images/readme/v2-build-apps-dark.webp" />
-        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website/public/images/readme/v2-build-apps-light.webp" />
-        <img src="./packages/twenty-website/public/images/readme/v2-build-apps-light.webp" alt="Create your apps" />
-      </picture>
-      <p align="center"><a href="https://docs.twenty.com/developers/extend/apps/getting-started"><img src="./packages/twenty-website/public/images/readme/code-icon.svg" width="16" height="16"/> Learn more about apps in doc</a></p>
-    </td>
-    <td width="50%">
-      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website/public/images/readme/v2-version-control-dark.webp" />
-        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website/public/images/readme/v2-version-control-light.webp" />
-        <img src="./packages/twenty-website/public/images/readme/v2-version-control-light.webp" alt="Stay on top with version control" />
-      </picture>
-      <p align="center"><a href="https://docs.twenty.com/developers/extend/apps/publishing"><img src="./packages/twenty-website/public/images/readme/monitor-icon.svg" width="16" height="16"/> Learn more about version control in doc</a></p>
-    </td>
-  </tr>
-  <tr>
-    <td width="50%">
-      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website/public/images/readme/v2-all-tools-dark.webp" />
-        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website/public/images/readme/v2-all-tools-light.webp" />
-        <img src="./packages/twenty-website/public/images/readme/v2-all-tools-light.webp" alt="All the tools you need to build anything" />
-      </picture>
-      <p align="center"><a href="https://docs.twenty.com/developers/extend/apps/building"><img src="./packages/twenty-website/public/images/readme/rocket-icon.svg" width="16" height="16"/> Learn more about primitives in doc</a></p>
-    </td>
-    <td width="50%">
-      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website/public/images/readme/v2-tools-dark.webp" />
-        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website/public/images/readme/v2-tools-light.webp" />
-        <img src="./packages/twenty-website/public/images/readme/v2-tools-light.webp" alt="Customize your layouts" />
-      </picture>
-      <p align="center"><a href="https://docs.twenty.com/user-guide/layout/overview"><img src="./packages/twenty-website/public/images/readme/planner-icon.svg" width="16" height="16"/> Learn more about layouts in doc</a></p>
-    </td>
-  </tr>
-  <tr>
-    <td width="50%">
-      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website/public/images/readme/v2-ai-agents-dark.webp" />
-        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website/public/images/readme/v2-ai-agents-light.webp" />
-        <img src="./packages/twenty-website/public/images/readme/v2-ai-agents-light.webp" alt="AI agents and chats" />
-      </picture>
-      <p align="center"><a href="https://docs.twenty.com/user-guide/ai/overview"><img src="./packages/twenty-website/public/images/readme/message-icon.svg" width="16" height="16"/> Learn more about AI in doc</a></p>
-    </td>
-    <td width="50%">
-      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website/public/images/readme/v2-crm-tools-dark.webp" />
-        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website/public/images/readme/v2-crm-tools-light.webp" />
-        <img src="./packages/twenty-website/public/images/readme/v2-crm-tools-light.webp" alt="Plus all the tools of a good CRM" />
-      </picture>
-      <p align="center"><a href="https://docs.twenty.com/user-guide/introduction"><img src="./packages/twenty-website/public/images/readme/star-icon.svg" width="16" height="16"/> Learn more about CRM features in doc</a></p>
-    </td>
-  </tr>
-</table>
++ [Personalize layouts with filters, sort, group by, kanban and table views](#personalize-layouts-with-filters-sort-group-by-kanban-and-table-views)
++ [Customize your objects and fields](#customize-your-objects-and-fields)
++ [Create and manage permissions with custom roles](#create-and-manage-permissions-with-custom-roles)
++ [Automate workflow with triggers and actions](#automate-workflow-with-triggers-and-actions)
++ [Emails, calendar events, files, and more](#emails-calendar-events-files-and-more)
+
+
+## Personalize layouts with filters, sort, group by, kanban and table views
+
+<p align="center">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-website/public/images/readme/views-dark.png" />
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-website/public/images/readme/views-light.png" />
+      <img src="./packages/twenty-website/public/images/readme/views-light.png" alt="Companies Kanban Views" />
+    </picture>
+</p>
+
+## Customize your objects and fields
+
+<p align="center">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-website/public/images/readme/data-model-dark.png" />
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-website/public/images/readme/data-model-light.png" />
+      <img src="./packages/twenty-website/public/images/readme/data-model-light.png" alt="Setting Custom Objects" />
+    </picture>
+</p>
+
+## Create and manage permissions with custom roles
+
+<p align="center">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-website/public/images/readme/permissions-dark.png" />
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-website/public/images/readme/permissions-light.png" />
+      <img src="./packages/twenty-website/public/images/readme/permissions-light.png" alt="Permissions" />
+    </picture>
+</p>
+
+## Automate workflow with triggers and actions
+
+<p align="center">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-website/public/images/readme/workflows-dark.png" />
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-website/public/images/readme/workflows-light.png" />
+      <img src="./packages/twenty-website/public/images/readme/workflows-light.png" alt="Workflows" />
+    </picture>
+</p>
+
+## Emails, calendar events, files, and more
+
+<p align="center">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-website/public/images/readme/plus-other-features-dark.png" />
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-website/public/images/readme/plus-other-features-light.png" />
+      <img src="./packages/twenty-website/public/images/readme/plus-other-features-light.png" alt="Other Features" />
+    </picture>
+</p>
 
 <br />
 
 # Stack
-
-- <a href="https://www.typescriptlang.org/"><img src="./packages/twenty-website/public/images/readme/stack-typescript.svg" width="14" height="14"/> TypeScript</a>
-- <a href="https://nx.dev/"><img src="./packages/twenty-website/public/images/readme/stack-nx.svg" width="14" height="14"/> Nx</a>
-- <a href="https://nestjs.com/"><img src="./packages/twenty-website/public/images/readme/stack-nestjs.svg" width="14" height="14"/> NestJS</a>, with <a href="https://bullmq.io/">BullMQ</a>, <a href="https://www.postgresql.org/"><img src="./packages/twenty-website/public/images/readme/stack-postgresql.svg" width="14" height="14"/> PostgreSQL</a>, <a href="https://redis.io/"><img src="./packages/twenty-website/public/images/readme/stack-redis.svg" width="14" height="14"/> Redis</a>
-- <a href="https://reactjs.org/"><img src="./packages/twenty-website/public/images/readme/stack-react.svg" width="14" height="14"/> React</a>, with <a href="https://jotai.org/">Jotai</a>, <a href="https://linaria.dev/">Linaria</a> and <a href="https://lingui.dev/">Lingui</a>
+- [TypeScript](https://www.typescriptlang.org/)
+- [Nx](https://nx.dev/)
+- [NestJS](https://nestjs.com/), with [BullMQ](https://bullmq.io/), [PostgreSQL](https://www.postgresql.org/), [Redis](https://redis.io/)
+- [React](https://reactjs.org/), with [Jotai](https://jotai.org/), [Linaria](https://linaria.dev/) and [Lingui](https://lingui.dev/)
 
 
 
 # Thanks
 
 <p align="center">
-  <a href="https://www.chromatic.com/"><img src="./packages/twenty-website/public/images/readme/chromatic.webp" height="28" alt="Chromatic" /></a>
-  &nbsp;&nbsp;&nbsp;&nbsp;
-  <a href="https://greptile.com"><img src="./packages/twenty-website/public/images/readme/greptile.webp" height="28" alt="Greptile" /></a>
-  &nbsp;&nbsp;&nbsp;&nbsp;
-  <a href="https://sentry.io/"><img src="./packages/twenty-website/public/images/readme/sentry.webp" height="28" alt="Sentry" /></a>
-  &nbsp;&nbsp;&nbsp;&nbsp;
-  <a href="https://crowdin.com/"><img src="./packages/twenty-website/public/images/readme/crowdin.webp" height="28" alt="Crowdin" /></a>
+  <a href="https://www.chromatic.com/"><img src="./packages/twenty-website/public/images/readme/chromatic.png" height="30" alt="Chromatic" /></a>
+  <a href="https://greptile.com"><img src="./packages/twenty-website/public/images/readme/greptile.png" height="30" alt="Greptile" /></a>
+  <a href="https://sentry.io/"><img src="./packages/twenty-website/public/images/readme/sentry.png" height="30" alt="Sentry" /></a>
+  <a href="https://crowdin.com/"><img src="./packages/twenty-website/public/images/readme/crowdin.png" height="30" alt="Crowdin" /></a>
+  <a href="https://e2b.dev/"><img src="./packages/twenty-website/public/images/readme/e2b.svg" height="30" alt="E2B" /></a>
 </p>
 
   Thanks to these amazing services that we use and recommend for UI testing (Chromatic), code review (Greptile), catching bugs (Sentry) and translating (Crowdin).
@@ -166,4 +128,9 @@ Want to go deeper? Read the <a href="https://docs.twenty.com/user-guide/introduc
 
 # Join the Community
 
-<p><a href="https://github.com/twentyhq/twenty"><img src="./packages/twenty-website/public/images/readme/star-icon.svg" width="12" height="12"/> Star the repo</a> · <a href="https://discord.gg/cx5n4Jzs57"><img src="./packages/twenty-website/public/images/readme/discord-icon.svg" width="12" height="12"/> Discord</a> · <a href="https://github.com/twentyhq/twenty/discussions"><img src="./packages/twenty-website/public/images/readme/message-icon.svg" width="12" height="12"/> Feature requests</a> · <a href="https://github.com/orgs/twentyhq/projects/1/views/35"><img src="./packages/twenty-website/public/images/readme/rocket-icon.svg" width="12" height="12"/> Releases</a> · <a href="https://twitter.com/twentycrm"><img src="./packages/twenty-website/public/images/readme/x-icon.svg" width="12" height="12"/> X</a> · <a href="https://www.linkedin.com/company/twenty/"><img src="./packages/twenty-website/public/images/readme/linkedin-icon.svg" width="12" height="12"/> LinkedIn</a> · <a href="https://twenty.crowdin.com/twenty"><img src="./packages/twenty-website/public/images/readme/language-icon.svg" width="12" height="12"/> Crowdin</a> · <a href="https://github.com/twentyhq/twenty/contribute"><img src="./packages/twenty-website/public/images/readme/code-icon.svg" width="12" height="12"/> Contribute</a></p>
+- Star the repo
+- Subscribe to releases (watch -> custom -> releases)
+- Follow us on [Twitter](https://twitter.com/twentycrm) or [LinkedIn](https://www.linkedin.com/company/twenty/)
+- Join our [Discord](https://discord.gg/cx5n4Jzs57)
+- Improve translations on [Crowdin](https://twenty.crowdin.com/twenty)
+- [Contributions](https://github.com/twentyhq/twenty/contribute) are, of course, most welcome!

docs/upgrade-experience-v2.md

@@ -0,0 +1,808 @@
+# Upgrade Experience V2 -- Design Document
+
+## Problem Statement
+
+The current upgrade system has several pain points:
+
+- **No cross-version upgrade**: a workspace must be on exactly the previous minor version to upgrade. Skipping versions requires stepping through each intermediate release.
+- **Opaque errors**: failures surface as raw stack traces with no structured reporting or actionable diagnostics.
+- **Misleading abstractions**: the command runner inheritance chain (`MigrationCommandRunner` -> `WorkspacesMigrationCommandRunner` -> `ActiveOrSuspendedWorkspacesMigrationCommandRunner` -> `UpgradeCommandRunner`) conflates global operations with per-workspace operations under a single hierarchy.
+- **No post-upgrade health check**: after upgrade, there is no validation that the workspace is in a consistent state.
+- **No workspace status visibility**: end users (self-hosted admins) have no way to see their workspace version or whether it is out of date.
+
+## Success Metrics
+
+- **Cross-version upgrade** works across the ordered list of supported versions (a workspace on `1.18.0` targeting `1.20.0` runs `1.19.0` then `1.20.0` bundles sequentially).
+- **Major.minor bundle identity**: the orchestrator groups upgrade commands by `major.minor`. Patch releases do not create new bundles, but they may patch an existing version line by adding new corrective commands inside the existing `major.minor` bundle.
+- **Post-upgrade health check** validates workspace consistency after migration.
+- **Improved developer experience** for twenty-eng: clear command taxonomy, scoped responsibilities, easy to add new version bundles and commands.
+- **Report-a-problem template** that gathers workspace status including upgrade stack traces.
+- **Settings page** (follow-up) shows current workspace version; if it differs from the installed server version, prompts the user to contact their administrator.
+
+---
+
+## Core Principles
+
+- **Sequentiality**: the upgrade processes one version bundle at a time, fully completing it (`instanceCommands`, stamp `instanceVersion`, then `perWorkspaceCommands` for all workspaces) before moving to the next. There is no cross-version interleaving -- the instance must finish upgrading all workspaces to version N before any version N+1 commands run.
+- **Idempotency**: all upgrade commands -- both `GlobalCommand` (in `instanceCommands`) and `PerWorkspaceCommand` (in `perWorkspaceCommands`) -- must be idempotent. Running the same command twice on the same workspace (or the same global state) produces the same result as running it once. This is critical because re-runs after partial failures must be safe, and single-workspace upgrades re-run global commands that may have already been applied.
+- **`instanceVersion` advancement guard**: `instanceVersion` can only advance to N+1 if **all workspace versions equal `instanceVersion`** (i.e. all workspaces are at N). If any workspace is behind -- because it failed a previous `perWorkspaceCommands` pass -- the orchestrator refuses to run the next bundle's `instanceCommands`. The operator must fix the failing workspace and re-run before the instance can move forward.
+- **Forward compatibility of global changes**: global commands (especially `instanceCommands` like TypeORM migrations) must produce a schema that is compatible with workspaces still at `instanceVersion - 1`. Since `instanceVersion` is stamped after `instanceCommands`, workspaces are still at the previous version when the global schema changes land. A global schema change that breaks those workspaces violates the upgrade contract.
+- **Breaking change backward compatibility**: a breaking change introduced in version N's `instanceCommands` must not invalidate any upgrade command in a version bundle still present in `UPGRADE_COMMAND_SUPPORTED_VERSIONS`. During a cross-version upgrade, older bundles' `perWorkspaceCommands` run against the global schema that all preceding `instanceCommands` (including N's) have already modified. If a breaking change in N makes a command in bundle M (where M < N) fail -- e.g. dropping a column that M's command reads -- then M and every version below it must be removed from `UPGRADE_COMMAND_SUPPORTED_VERSIONS`. This narrows the supported upgrade range, so breaking changes should be avoided or deferred whenever possible.
+- **No downgrade support**: the upgrade path is forward-only.
+
+---
+
+## Upgrade Command Golden Rules
+
+These rules define how upgrade commands evolve over time. They exist to avoid
+history collisions, make patching safe, and keep command intent readable months
+after a release shipped.
+
+1. **A command name is a contract**: once a command has shipped, its name
+   becomes part of the upgrade history contract. A successful history row for
+   `commandName = foo` means "the logical operation `foo` already ran".
+2. **Do not silently change the meaning of a released command**: if a command
+   already shipped and later turns out to be incomplete, buggy, or wrongly
+   ordered, do not keep the same name and change the implementation in place.
+3. **New intent requires new identity**: if behavior materially changes, create
+   a new command name (`foo-fix-missing-bar`, `foo-v2`,
+   `rebuild-foo-after-order-fix`, etc.). This lets the new command run once
+   without colliding with prior successful history rows.
+4. **Ordering fixes are modeled as new commands**: if a command was released in
+   the wrong order, fix the workflow by adding a new compensating command in the
+   correct position, not by trying to reinterpret the old history row.
+5. **Prefer additive repair over replaying history**: if production data needs
+   correction after release, prefer adding a new corrective command rather than
+   renaming or deleting history rows.
+6. **Idempotency still applies**: even when introducing corrective commands, the
+   new command must still be safe to re-run after partial failure.
+
+These rules are especially important for patching an existing version line. If
+`1.20.1` needs to fix work already attempted by `1.20.0`, the fix should
+generally be represented as a **new command in the `1.20` bundle**, not as a
+silent rewrite of the old command's meaning.
+
+---
+
+## Instance Version
+
+The upgrade system introduces a new concept: **`instanceVersion`** -- the version the instance's global state (schema, core data) has been upgraded to. This is distinct from:
+
+- **`APP_VERSION`**: the version of the deployed Twenty codebase (set at build time, read from env/package).
+- **Workspace version**: the version each individual workspace has been upgraded to.
+
+`instanceVersion` tracks how far the shared database has progressed through the upgrade timeline. It is the gate that controls which workspaces are eligible for upgrade.
+
+### Storage
+
+Stored in the existing `KeyValuePair` table (`core` schema) as a `CONFIG_VARIABLE` entry with `userId = null` and `workspaceId = null`, key = `INSTANCE_VERSION`. This leverages the existing `ConfigStorageService` / `ConfigVariables` infrastructure -- no new table or schema change required.
+
+### Lifecycle
+
+1. Before any upgrade, `instanceVersion` reflects the last fully-completed version bundle (e.g. `1.18.0`).
+2. The orchestrator verifies all workspace versions equal `instanceVersion` (advancement guard).
+3. The orchestrator picks the next version bundle in `UPGRADE_COMMAND_SUPPORTED_VERSIONS` (e.g. `bundle_1190`).
+4. The `instanceCommands` run (global schema changes).
+5. `instanceVersion` is stamped to `1.19.0`. The shared database is now at this version's global state.
+6. The `perWorkspaceCommands` run for all workspaces at `1.18.0` (i.e. `instanceVersion - 1`).
+7. Once all workspaces succeed, the orchestrator moves to the next version bundle.
+
+`instanceVersion` advances after `instanceCommands` complete -- it reflects the global schema state. Workspace versions catch up via `perWorkspaceCommands`. During cloud development, `instanceVersion` is **not** bumped on deploys -- only `instanceCommands` are executed (with skip-if-completed via `instance_upgrade_history`). `instanceVersion` stays at the previous stable version until the release owner runs the full orchestrator (see "Deploying a Partial Next Version to Cloud Production").
+
+### Workspace Eligibility
+
+A workspace can only be upgraded by a version bundle if it is at exactly `instanceVersion - 1` -- the version immediately before the current instance version in `UPGRADE_COMMAND_SUPPORTED_VERSIONS`. Workspaces that are further behind are not eligible and must be addressed before the instance can proceed to the next version.
+
+### Initial Value
+
+On a fresh install, `instanceVersion` is set to `APP_VERSION` (no upgrade needed). On an existing instance that predates this feature, the migration that introduces `instanceVersion` seeds it from the current `APP_VERSION` at the time of deployment.
+
+### New Workspace Version
+
+When a new workspace is created, it receives `instanceVersion` as its workspace version -- not `APP_VERSION`. This ensures the workspace is aligned with the last fully-completed upgrade state. During cloud development, `APP_VERSION` may be ahead of `instanceVersion` (e.g. `APP_VERSION = 1.21.0` while `instanceVersion = 1.20.0`), so using `instanceVersion` prevents creating workspaces at a version that hasn't been fully upgraded to yet.
+
+---
+
+## Command Taxonomy
+
+Replace the current deep inheritance chain with explicit base classes and an orchestrator.
+
+### Terminology
+
+- **UpgradeCommandOrchestrator**: the top-level orchestrator that resolves versions, processes version bundles sequentially, and manages the upgrade flow.
+- **UpgradeVersionBundle**: the per-version `{ instanceCommands, perWorkspaceCommands }` object (e.g. `bundle_1200`). Groups all commands needed to upgrade workspaces *to* that version.
+- **UpgradeCommand**: an individual command within a bundle's `instanceCommands` or `perWorkspaceCommands` array. Base class for all upgrade commands. Subtypes:
+  - **GlobalCommand**: runs once, globally, workspace-agnostic. Used **only in `instanceCommands`**. Example: TypeORM core migrations, breaking schema changes.
+  - **PerWorkspaceCommand**: iterates over all active/suspended workspaces and executes per-workspace logic. Used **only in `perWorkspaceCommands`**. Example: backfilling data, migrating workspace schemas.
+
+### Command Contract
+
+Every `UpgradeCommand` (both `GlobalCommand` and `PerWorkspaceCommand`) must follow a strict contract:
+
+**Return type -- discriminated union**:
+
+```typescript
+type UpgradeCommandResult =
+  | { status: 'success' }
+  | { status: 'failure'; error: string };
+```
+
+- Commands must **never throw**. They return `{ status: 'failure', error }` instead.
+- The orchestrator wraps each command execution in a try/catch to handle unexpected exceptions -- these are converted into a `failure` result with the caught error message and stack.
+
+**Log capture via correlation ID**:
+
+Commands use the standard NestJS `Logger` (`this.logger`) -- no custom callback or API change. The orchestrator captures all logs emitted during a command's execution using a correlation ID:
+
+- Before executing a command, the orchestrator sets a correlation ID (e.g. `commandName + workspaceId`) in async local storage.
+- The global `LoggerService` includes this correlation ID in every log line, regardless of which Logger instance or service emits it (command code, TypeORM, repositories, framework internals).
+- A per-command buffer captures all correlated log lines during execution. This gives true per-command log isolation -- ORM queries, SQL errors, service calls, and the command's own narrative all appear in one unified stream.
+- Tail-truncated to last 5,000 lines if exceeded. A `[TRUNCATED]` header is prepended when truncation occurs.
+- On **failure**: the buffer is stored in the `logs` column of the relevant history table (`instance_upgrade_history` or `workspace_upgrade_history`).
+- On **success**: the buffer is discarded (already written to stdout).
+
+This approach avoids the fragility of wrapping individual Logger instances and naturally supports future parallelized workspace upgrades (each command execution has its own correlation ID).
+
+**Orchestrator error handling**:
+
+```typescript
+let result: UpgradeCommandResult;
+
+try {
+  result = await command.execute(context);
+} catch (unexpectedError) {
+  result = {
+    status: 'failure',
+    error: `${unexpectedError.message}\n${unexpectedError.stack}`,
+  };
+}
+```
+
+### Version Bundles
+
+Each version defines its upgrade bundle as two ordered arrays:
+
+- **`instanceCommands`**: Global commands that must execute quickly (e.g. breaking schema changes, TypeORM migrations). Contains **only `GlobalCommand` entries**. These run first, before any workspace is touched.
+- **`perWorkspaceCommands`**: Per-workspace commands that may take longer (backfills, data migrations). Contains **only `PerWorkspaceCommand` entries**. These run after `instanceCommands` completes, iterating over all eligible workspaces.
+
+```typescript
+const bundle_1200: UpgradeVersionBundle = {
+  instanceCommands: [
+    { type: 'global', command: this.typeOrmMigrationCommandA },
+    { type: 'global', command: this.typeOrmMigrationCommandB },
+    { type: 'global', command: this.typeOrmMigrationCommandC },
+  ],
+  perWorkspaceCommands: [
+    { type: 'per-workspace', command: this.backfillCommandMenuItemsCommand },
+    { type: 'per-workspace', command: this.migrateRichTextToTextCommand },
+    { type: 'per-workspace', command: this.backfillSelectFieldOptionIdsCommand },
+  ],
+};
+```
+
+### TypeORM Migration Generation
+
+TypeORM migrations are no longer generated directly through the raw TypeORM
+CLI. They now go through a dedicated NestJS command that associates each newly
+generated migration with the **latest known version line**.
+
+**Why**:
+
+- TypeORM migrations are part of `instanceCommands`, so they must belong to a
+  specific upgrade bundle.
+- We want one canonical place to decide which version line a new migration
+  belongs to.
+- This avoids developers generating a migration and then manually forgetting to
+  associate it with the latest bundle.
+
+**How it works**:
+
+1. A developer runs a NestJS command to generate the migration.
+2. That command resolves the latest known version from
+   `UPGRADE_COMMAND_SUPPORTED_VERSIONS`.
+3. The generated migration is associated with that latest known version line.
+4. The matching `TypeOrmMigrationCommand` for that bundle will execute it as
+   part of the bundle's `instanceCommands`.
+
+### Orchestrator
+
+`UpgradeCommandOrchestrator` (renamed from `UpgradeCommand`) is responsible for:
+
+1. Resolving the current `APP_VERSION`, `instanceVersion`, and the supported upgrade range.
+2. For each version bundle from `instanceVersion + 1` to `APP_VERSION` (sequentially):
+   a. Run the `instanceCommands` array (global commands). Skip commands already recorded as `completed` in `instance_upgrade_history`.
+   b. Stamp `instanceVersion` to this version.
+   c. Run the `perWorkspaceCommands` array for all workspaces at `instanceVersion - 1`. Skip commands already recorded as `completed` in `workspace_upgrade_history` for each workspace. Stamp each workspace's version after its commands complete.
+   d. Verify all workspaces succeeded before moving to the next version bundle.
+
+---
+
+## Cross-Version Upgrade
+
+### How It Works
+
+`UPGRADE_COMMAND_SUPPORTED_VERSIONS` remains an ordered list of versions (e.g. `['1.18.0', '1.19.0', '1.20.0']`). The orchestrator uses it as a timeline, combined with `instanceVersion` to determine where to start:
+
+1. Read `instanceVersion` from the database.
+2. Find the next version after `instanceVersion` in the ordered list.
+3. Process each version bundle sequentially up to `APP_VERSION`, fully completing one before starting the next.
+
+No per-version allowlist is needed. The ordered list itself defines the upgrade path. The oldest entry in the list is the oldest supported source version -- anything below it is out of range.
+
+The `1.20.0` codebase must ship all version bundles back to the oldest supported version. If `UPGRADE_COMMAND_SUPPORTED_VERSIONS` is `['1.17.0', '1.18.0', '1.19.0', '1.20.0']`, then the `1.20.0` release includes `bundle_1180`, `bundle_1190`, and `bundle_1200`.
+
+### Execution Flow
+
+The upgrade processes **one version bundle at a time**, fully completing it before moving to the next:
+
+**For each version bundle** (from `instanceVersion + 1` to `APP_VERSION`):
+
+1. **Run `instanceCommands` array** (global commands). Commands already recorded as `completed` in `instance_upgrade_history` are skipped. If any command fails, the upgrade aborts immediately. There is no rollback of previously completed commands; each runs in its own transaction. The operator must fix the issue and re-run.
+
+2. **Stamp `instanceVersion`** to this version. The shared database is now at this version's global state.
+
+3. **Run `perWorkspaceCommands` array** for all workspaces at `instanceVersion - 1`. The orchestrator queries for workspaces at exactly the previous version and runs each `PerWorkspaceCommand` in order. Commands already recorded as `completed` in `workspace_upgrade_history` for a given workspace are skipped. Each workspace's version is stamped after all its per-workspace commands complete. If a workspace fails, the orchestrator records the failure and **continues to the next workspace** -- it does not stop at the first failure.
+
+4. **All workspaces must succeed** before the orchestrator moves to the next version bundle. After attempting all workspaces, if any failed, the upgrade halts. The `instanceVersion` advancement guard enforces this: the next bundle cannot start because not all workspace versions equal `instanceVersion`. The operator must fix the failing workspaces and re-run.
+
+### No Straggler Rescue
+
+Unlike a model where the orchestrator walks behind-workspaces through multiple intermediate bundles, the sequential model requires workspaces to be at exactly `instanceVersion - 1` to be eligible for upgrade. Workspaces that are further behind (e.g. they failed a previous upgrade cycle) are **not eligible** -- they block the instance from proceeding to the next version.
+
+This is intentional: the hard-block forces operators to resolve failures before moving forward, preventing a growing tail of broken workspaces across versions.
+
+### Real-World Example
+
+**Context**: the server was previously running `1.18.0` (`instanceVersion = 1.18.0`). We are now deploying `1.20.0`.
+
+**Supported versions**: `['1.17.0', '1.18.0', '1.19.0', '1.20.0']`
+
+**Workspaces**: all at `1.18.0` (A, B, C).
+
+**Version bundles shipped with `1.20.0`**:
+
+```typescript
+this.allBundles = {
+  '1.18.0': bundle_1180,  // for workspaces on 1.17.0
+  '1.19.0': bundle_1190,  // for workspaces on 1.18.0
+  '1.20.0': bundle_1200,  // for workspaces on 1.19.0
+};
+```
+
+**Version bundle 1.19.0**:
+
+```
+> instanceVersion = 1.18.0, target = 1.20.0
+> Processing bundle_1190...
+
+  instanceCommands:
+    [global] TypeORM migrations for 1.19.0    OK
+    [global] Schema change ABC                OK
+  instanceVersion stamped to 1.19.0
+
+  perWorkspaceCommands (workspaces at 1.18.0: A, B, C):
+    > Workspace A:
+      [per-workspace] backfill feature flags    OK
+      Workspace A stamped to 1.19.0
+    > Workspace B:
+      [per-workspace] backfill feature flags    FAILED
+      Workspace B stays at 1.18.0
+    > Workspace C:
+      [per-workspace] backfill feature flags    OK
+      Workspace C stamped to 1.19.0
+  *** 1 workspace failed. Upgrade halts after this bundle. ***
+```
+
+**The upgrade halts.** `instanceVersion` is `1.19.0` (stamped after `instanceCommands`). Workspaces A and C are at `1.19.0`, but workspace B is still at `1.18.0`. All three workspaces were attempted -- the orchestrator did not stop at B's failure.
+
+The operator investigates workspace B's failure (using the `workspace_upgrade_history` table and its captured logs), fixes the underlying issue, and re-runs the upgrade command.
+
+**Re-run**:
+
+```
+> instanceVersion = 1.19.0, target = 1.20.0
+> Advancement guard: all workspace versions must equal instanceVersion (1.19.0)
+>   Workspace B is at 1.18.0 -- NOT OK
+> Processing bundle_1190 (perWorkspaceCommands only, instanceCommands already completed)...
+
+  instanceCommands:
+    [global] TypeORM migrations for 1.19.0    SKIP (completed in history)
+    [global] Schema change ABC                SKIP (completed in history)
+  instanceVersion already at 1.19.0 (no-op)
+
+  perWorkspaceCommands (workspaces at 1.18.0: B):
+    > Workspace A: already at 1.19.0 (skipped)
+    > Workspace B:
+      [per-workspace] backfill feature flags    OK (fixed)
+      Workspace B stamped to 1.19.0
+    > Workspace C: already at 1.19.0 (skipped)
+
+> Processing bundle_1200...
+
+  instanceCommands:
+    [global] TypeORM migrations for 1.20.0    OK
+    [global] Breaking schema change XYZ       OK
+  instanceVersion stamped to 1.20.0
+
+  perWorkspaceCommands (workspaces at 1.19.0: A, B, C):
+    > Workspace A:
+      [per-workspace] backfillCommandMenuItems  OK
+      [per-workspace] migrateRichTextToText     OK
+      Workspace A stamped to 1.20.0
+    > Workspace B:
+      [per-workspace] backfillCommandMenuItems  OK
+      [per-workspace] migrateRichTextToText     OK
+      Workspace B stamped to 1.20.0
+    > Workspace C:
+      [per-workspace] backfillCommandMenuItems  OK
+      [per-workspace] migrateRichTextToText     OK
+      Workspace C stamped to 1.20.0
+```
+
+**Key observations**:
+
+- The upgrade is strictly sequential: `bundle_1190` must fully complete (`instanceCommands` + all workspaces `perWorkspaceCommands`) before `bundle_1200` starts.
+- `instanceVersion` is stamped after `instanceCommands` complete -- it advanced to `1.19.0` even though workspace B failed. On re-run, the orchestrator sees `instanceVersion = 1.19.0` and skips `instanceCommands` for `bundle_1190`.
+- All workspaces are attempted even when one fails. Workspace C was upgraded successfully despite workspace B's failure. This maximizes progress per run.
+- On re-run, instance commands are skipped (recorded as `completed` in `instance_upgrade_history`). Workspaces A and C are already at `1.19.0` so they're skipped. Only workspace B is re-attempted.
+- The `instanceVersion` advancement guard blocked `bundle_1200` from starting because workspace B was still at `1.18.0` (not equal to `instanceVersion = 1.19.0`). Once B succeeds on re-run, all workspaces are at `1.19.0` and the guard passes.
+- `perWorkspaceCommands` contains only `PerWorkspaceCommand` entries. Any global work belongs in `instanceCommands`.
+
+### Failure Behavior
+
+- **Instance command failure**: the upgrade aborts immediately. `instanceVersion` is not stamped (the failing command's transaction is rolled back, previously completed commands remain applied). No per-workspace commands run.
+- **Per-workspace command failure (any workspace)**: the orchestrator **continues attempting all remaining workspaces** -- it does not stop at the first failure. `instanceVersion` was already stamped (after `instanceCommands`). Failed workspaces keep their current version. Successfully upgraded workspaces keep their new version stamp. After all workspaces have been attempted, the upgrade halts. The `instanceVersion` advancement guard prevents the next bundle from starting: since the failed workspace's version is still at `instanceVersion - 1` (not equal to `instanceVersion`), the orchestrator will refuse to advance further until all workspaces catch up. The operator must fix the failing workspaces and re-run -- already-completed commands (including successful workspaces) are skipped via the history tables.
+
+The final report includes per-workspace status (success / failure).
+
+### Guard Logic
+
+Before running `instanceCommands` for a version bundle, the orchestrator verifies that **all workspace versions equal `instanceVersion`**. If any workspace is behind (e.g. it failed during the previous bundle's `perWorkspaceCommands`), the orchestrator refuses to advance. This is the primary guard -- `instanceVersion` never moves forward while any workspace is lagging.
+
+On the very first bundle (or after a fresh deploy), the orchestrator also checks for workspaces below `instanceVersion`. These workspaces are too far behind to be eligible:
+
+- **Self-hosted (default)**: the upgrade refuses to start. A clear message lists the affected workspaces and the minimum required version.
+- **Self-hosted (`--force`)**: the upgrade proceeds, but ineligible workspaces are skipped and reported as "refused". The hard-block on workspace failure still applies to eligible workspaces.
+
+### Single-Workspace Upgrade (`-w`)
+
+When targeting a single workspace, the orchestrator still runs all `instanceCommands` (global) for the relevant version bundle because they affect the shared database, and stamps `instanceVersion`. Then only the targeted workspace's `perWorkspaceCommands` run. Other workspaces remain at their current version. This means global changes "leak" to all other workspaces. This is acceptable because:
+
+- All commands are idempotent -- when other workspaces are upgraded later, global commands no-op.
+- Global schema changes are forward-compatible by design -- workspaces at `instanceVersion - 1` continue to work against the new schema.
+
+The orchestrator logs a clear warning when running in single-workspace mode: global commands will be applied to the shared database and affect all workspaces.
+
+Note: after a single-workspace upgrade, the non-targeted workspaces are still at the previous version. The `instanceVersion` advancement guard will block the next bundle until all workspaces are upgraded to `instanceVersion`. The operator must run the full orchestrator (or target each remaining workspace individually) before the instance can advance further.
+
+### Breaking Changes and Stale Versions
+
+Breaking changes in the upgrade history are avoided unless they would break the cross-version upgrade path. When a breaking change is unavoidable:
+
+- The breaking change may make one or more commands in an older version bundle **stale** (e.g. a command that backfills a column that no longer exists after the breaking change).
+- When any command in a version bundle becomes stale, the **entire version must be dropped** from `UPGRADE_COMMAND_SUPPORTED_VERSIONS` -- not just the individual stale command. A workspace on that version needs all of its bundle's commands to upgrade successfully; if even one command is broken, the full upgrade path from that version is invalid.
+- The entire version bundle (`instanceCommands` and `perWorkspaceCommands`) is removed from the codebase as a unit.
+
+Since the supported range is a contiguous upgrade path, invalidating a version also invalidates **every version below it** -- those workspaces would need to pass through the invalidated version bundle to reach the target.
+
+Example: `bundle_1190` has a command that backfills column `X`. In `1.21.0`, a breaking change drops column `X`. That single stale command invalidates the entire `1.19.0` version bundle. But `1.18.0` and `1.17.0` are also invalidated because they depend on the `1.19.0` bundle to reach the target. All three versions and their bundles are removed from `UPGRADE_COMMAND_SUPPORTED_VERSIONS`. The oldest supported source version becomes `1.20.0`.
+
+### Workspace Recap Tooling
+
+A dedicated recap/status command should provide visibility into this:
+
+- List all workspaces with their current version.
+- Flag workspaces that are **below the supported range** (too far behind to be upgraded by the current version).
+- Flag workspaces that are **at risk** of falling out of range if the next version introduces a breaking change.
+- Warn when a version is about to be or has been dropped from the supported list, and which workspaces are affected.
+
+This recap is also the foundation for the "report-a-problem" template and the settings page workspace status (follow-up).
+
+---
+
+## Upgrade History
+
+Two tables in the **core schema** (shared, not per-workspace) that record command executions. Splitting mirrors the taxonomy: `instanceCommands` -> `instance_upgrade_history`, `perWorkspaceCommands` -> `workspace_upgrade_history`. This avoids nullable foreign keys and makes each table's schema tight and query-friendly.
+
+### `instance_upgrade_history` Table
+
+Tracks execution of `GlobalCommand` entries from `instanceCommands` arrays.
+
+**Columns**:
+
+- `id` (uuid, PK)
+- `version` (varchar -- the version bundle this command belongs to, e.g. `1.20.0`)
+- `commandName` (varchar -- unique identifier for the command, e.g. `typeOrmMigration`)
+- `status` (varchar -- `completed` / `failed`)
+- `retry` (integer, NOT NULL, default `0` -- zero-indexed retry counter. The first execution is `0`, the first re-run is `1`, etc.)
+- `runByVersion` (varchar -- the `APP_VERSION` of the Twenty instance that executed this command, e.g. `1.20.1`. Useful for debugging: if a command was completed by a buggy version, this tells you which build ran it.)
+- `error` (text, nullable -- full error string from `UpgradeCommandResult.error` on failure, including stack trace)
+- `logs` (text, nullable -- all log output correlated to this command execution via correlation ID. Tail-truncated to last 5,000 lines if exceeded; when truncated, a `[TRUNCATED - showing last 5000 of N total lines]` header is prepended. Stored on failure only.)
+- `createdAt` / `updatedAt` (timestamps)
+
+**Index**: `(commandName, version)` -- not unique, since multiple rows can exist for the same command across retries.
+
+### `workspace_upgrade_history` Table
+
+Tracks execution of `PerWorkspaceCommand` entries from `perWorkspaceCommands` arrays.
+
+**Columns**:
+
+- `id` (uuid, PK)
+- `workspaceId` (uuid, NOT NULL)
+- `version` (varchar -- the version bundle this command belongs to, e.g. `1.20.0`)
+- `commandName` (varchar -- unique identifier for the command, e.g. `backfillCommandMenuItems`)
+- `status` (varchar -- `completed` / `failed`)
+- `retry` (integer, NOT NULL, default `0` -- zero-indexed retry counter. The first execution is `0`, the first re-run is `1`, etc.)
+- `runByVersion` (varchar -- the `APP_VERSION` of the Twenty instance that executed this command, e.g. `1.20.1`.)
+- `error` (text, nullable -- full error string from `UpgradeCommandResult.error` on failure, including stack trace)
+- `logs` (text, nullable -- all log output correlated to this command execution via correlation ID. Tail-truncated to last 5,000 lines if exceeded; when truncated, a `[TRUNCATED - showing last 5000 of N total lines]` header is prepended. Stored on failure only.)
+- `createdAt` / `updatedAt` (timestamps)
+
+**Index**: `(commandName, version, workspaceId)` -- not unique, since multiple rows can exist for the same command across retries.
+
+### Shared Lifecycle
+
+Both tables are **append-only and immutable** -- rows are inserted once and never updated:
+
+- On completion: insert a row with `status: completed`, `retry: 0`.
+- On failure: insert a row with `status: failed`, `error`, and `logs`, `retry: 0`.
+- On re-run: insert a **new row** with `retry` incremented. The new row gets its own final `status` (`completed` or `failed`). Previous rows are never touched.
+
+There is no `started` status. A row is only written once the command finishes (successfully or not). A crash mid-command leaves no row at all -- the orchestrator treats the absence of a `completed` row as "not completed" on re-run.
+
+Previous failure rows are preserved across retries. This gives operators a full execution history for debugging: they can see every attempt, what error occurred, and which `runByVersion` executed it. The orchestrator determines the current state of a command by looking at the row with the **highest `retry` value** for a given `(commandName, version)` or `(commandName, version, workspaceId)` tuple.
+
+### Re-Run Behavior and Skip-If-Completed
+
+The orchestrator uses the history tables as a **control mechanism**: before running a command, it checks whether the **latest row** (highest `retry`) for that command is `completed` in the relevant history table and skips it if so. This is essential for two reasons:
+
+1. **Partial failure recovery**: on re-run after a failure, already-completed commands are skipped rather than re-executed. This avoids redundant work on expensive commands (e.g. full table scans that would no-op row by row).
+2. **Cloud development workflow**: during incremental cloud deploys, commands may be run individually before the stable release. When the release owner runs the full orchestrator, the history tables tell it exactly which commands have already been applied. See "Deploying a Partial Next Version to Cloud Production" for the full workflow.
+
+A `--force-rerun` flag overrides this and re-executes all commands regardless of history. This is useful for debugging or when a command was recorded as `completed` but produced incorrect results (e.g. a buggy version ran it). All commands must still be idempotent -- `--force-rerun` relies on this guarantee.
+
+### Row Eviction
+
+Because the tables are append-only, rows accumulate over time. In practice the volume is modest -- a version bundle has ~5-10 commands, retries are rare, and even cloud environments with thousands of workspaces produce manageable row counts. Still, stale rows serve no operational purpose once their version is no longer part of the upgrade path.
+
+**Policy**: when a version is dropped from `UPGRADE_COMMAND_SUPPORTED_VERSIONS` (see "Breaking Changes and Stale Versions"), all history rows for that version are deleted from both `instance_upgrade_history` and `workspace_upgrade_history`. The commands those rows reference no longer exist in the codebase and can never be re-run -- the history is purely archival at that point.
+
+**Timing**: eviction runs at the start of the upgrade orchestrator, before processing any version bundle. The orchestrator compares the versions present in the history tables against `UPGRADE_COMMAND_SUPPORTED_VERSIONS` and deletes rows whose `version` is not in the list. This keeps the tables tight without requiring a separate cleanup job or manual intervention.
+
+**No time-based eviction**: rows are not evicted by age. A version may stay in `UPGRADE_COMMAND_SUPPORTED_VERSIONS` for a long time (e.g. the oldest supported source version), and its history rows must remain queryable for the skip-if-completed mechanism to work. Version-based eviction is the only safe trigger.
+
+---
+
+## Deploying a Partial Next Version to Cloud Production
+
+During the development cycle for a new version (e.g. `1.21.0`), the cloud production environment receives incremental deploys before the stable release. Each deploy ships `APP_VERSION = 1.21.0` (not pre-release tags like `1.21.0-alpha.3`). This means new commands may be added to `bundle_1210` between deploys.
+
+### How It Works
+
+- **`instanceCommands` run automatically on each deploy** via a dedicated CLI mode (similar to `database:reset --force`). Each deploy runs the full `instanceCommands` array for the current version bundle. Commands already recorded as `completed` in `instance_upgrade_history` are skipped. New commands added since the last deploy are executed. **`instanceVersion` is not stamped** -- it stays at the previous stable version (e.g. `1.20.0`) throughout the development cycle. The skip-if-completed mechanism (via `instance_upgrade_history`) is what prevents re-running already-applied commands on subsequent deploys, not the version stamp.
+- **`perWorkspaceCommands` are run manually** by developers via CLI as needed. This gives developers control over when workspace-level migrations run during the development cycle.
+- **New workspaces** created during the development cycle get `instanceVersion` as their workspace version (e.g. `1.20.0`). Since `instanceVersion` is not stamped during deploys, this is always the last fully-completed version -- not `APP_VERSION`. These workspaces will be upgraded when the release owner runs the full orchestrator.
+- **At stable release**, the release owner runs the full upgrade orchestrator. The orchestrator processes `bundle_1210`: `instanceCommands` are all skipped (already `completed` in history), `instanceVersion` is then stamped to `1.21.0`, and `perWorkspaceCommands` run for all workspaces still at `1.20.0` (commands already applied manually during the dev cycle are skipped via `workspace_upgrade_history`). This is the first and only time `instanceVersion` advances.
+
+### Real-World Example
+
+**Context**: `1.20.0` is the current stable release. `instanceVersion = 1.20.0`. All workspaces at `1.20.0`. The team is developing `1.21.0`.
+
+**Deploy 1** (ships `APP_VERSION = 1.21.0`, `bundle_1210` has 2 instance commands and 3 per-workspace commands):
+
+```
+> APP_VERSION = 1.21.0, instanceVersion = 1.20.0
+> Running instanceCommands for bundle_1210 (auto-deploy mode)...
+
+  instanceCommands:
+    [global] TypeORM migrations for 1.21.0    OK
+    [global] Add new core index              OK
+  instanceVersion not stamped (auto-deploy mode)
+
+  perWorkspaceCommands: not run (auto-deploy mode only runs instanceCommands)
+```
+
+**Deploy 2** (a developer adds a new instance command to `bundle_1210`):
+
+```
+> APP_VERSION = 1.21.0, instanceVersion = 1.20.0
+> Running instanceCommands for bundle_1210 (auto-deploy mode)...
+
+  instanceCommands:
+    [global] TypeORM migrations for 1.21.0    SKIP (completed in history)
+    [global] Add new core index              SKIP (completed in history)
+    [global] Seed new config variable        OK  (new command)
+  instanceVersion not stamped (auto-deploy mode)
+```
+
+**Developer manually runs perWorkspaceCommands** for a specific workspace during testing:
+
+```
+> Running perWorkspaceCommands for bundle_1210 on workspace D (manual CLI)...
+
+  perWorkspaceCommands:
+    > Workspace D:
+      [per-workspace] backfillNewField        OK
+      [per-workspace] migrateCalendarEvents   OK
+      [per-workspace] updateSearchIndex       OK
+      Workspace D stamped to 1.21.0
+```
+
+**New workspace E is created** during the dev cycle. It gets workspace version `1.20.0`.
+
+**Stable release** -- the release owner runs the full upgrade orchestrator:
+
+```
+> APP_VERSION = 1.21.0, instanceVersion = 1.20.0
+> Processing bundle_1210...
+
+  instanceCommands:
+    [global] TypeORM migrations for 1.21.0    SKIP (completed in history)
+    [global] Add new core index              SKIP (completed in history)
+    [global] Seed new config variable        SKIP (completed in history)
+  instanceVersion stamped to 1.21.0
+
+  perWorkspaceCommands (workspaces at 1.20.0: A, B, C, E):
+    > Workspace A:
+      [per-workspace] backfillNewField        OK
+      [per-workspace] migrateCalendarEvents   OK
+      [per-workspace] updateSearchIndex       OK
+      Workspace A stamped to 1.21.0
+    > Workspace B:
+      [per-workspace] backfillNewField        OK
+      [per-workspace] migrateCalendarEvents   OK
+      [per-workspace] updateSearchIndex       OK
+      Workspace B stamped to 1.21.0
+    > Workspace C:
+      [per-workspace] backfillNewField        OK
+      [per-workspace] migrateCalendarEvents   OK
+      [per-workspace] updateSearchIndex       OK
+      Workspace C stamped to 1.21.0
+    > Workspace D: already at 1.21.0, not eligible (skipped)
+    > Workspace E:
+      [per-workspace] backfillNewField        OK
+      [per-workspace] migrateCalendarEvents   OK
+      [per-workspace] updateSearchIndex       OK
+      Workspace E stamped to 1.21.0
+```
+
+**Key observations**:
+
+- All `instanceCommands` were skipped -- they were already applied across the two deploys during development. The `skipIfCompleted` mechanism (via `instance_upgrade_history`) is what makes this possible, not the version stamp.
+- `instanceVersion` stayed at `1.20.0` throughout the entire development cycle. It is only stamped to `1.21.0` now, during the full orchestrator run.
+- Workspace D was manually upgraded during development and is skipped (already at `1.21.0`).
+- Workspace E was created during the dev cycle with version `1.20.0` and is upgraded now.
+
+---
+
+## Post-Upgrade Health Check
+
+After all version bundles complete, the orchestrator runs a health check:
+
+- **Instance version**: confirm `instanceVersion` matches `APP_VERSION`.
+- **Workspace versions**: confirm all workspace versions match `APP_VERSION`.
+- **Command completion**: verify all expected commands have a `completed` row (highest `retry`) in both `instance_upgrade_history` and `workspace_upgrade_history`. A missing row for an expected command indicates a crash mid-execution.
+
+Health check results are included in the upgrade report. Failures are warnings (the upgrade itself already succeeded), not rollback triggers.
+
+Note: broader workspace health (metadata consistency, runtime checks, etc.) is a separate concern from upgrade validation and is out of scope here.
+
+---
+
+## Error Reporting and Logging
+
+### Structured Upgrade Report
+
+Replace raw stack traces with a structured report, built from the `instance_upgrade_history` and `workspace_upgrade_history` tables:
+
+- Per-workspace status: success / failure / not-attempted / refused (below supported range, with `--force`).
+- For failures: the command that failed, a human-readable error message, and the full stack trace captured (not dumped to stdout).
+- Summary: total workspaces, succeeded, failed, not-attempted.
+- Instance version before and after the upgrade.
+
+### Report-a-Problem Template (follow-up)
+
+A template that gathers:
+
+- Current workspace version vs installed server version.
+- Upgrade report (if available).
+- Stack traces from the last failed upgrade attempt.
+- Environment info (Postgres version, Redis status, etc.).
+
+---
+
+## Frontend (Follow-Up)
+
+Out of scope for this doc but planned:
+
+- **General Settings page**: display current workspace version. If it differs from the installed server version, show a banner prompting the user to contact their administrator.
+- **Report-a-problem**: pre-filled template using the workspace status endpoint.
+
+---
+
+## Testing Strategy
+
+### Orchestrator Unit Tests
+
+The orchestrator motor is covered by unit tests that exercise the full state machine in isolation -- no real database, no real commands. Commands are stubbed to return `completed` or `failed` as needed, and the tests verify the orchestrator's decisions and side effects.
+
+**Edge cases covered**:
+
+- **Happy path**: single-version upgrade, multi-version cross-version upgrade, all workspaces succeed.
+- **Instance command failure**: verify `instanceVersion` is not stamped, no `perWorkspaceCommands` run.
+- **Per-workspace command failure (single workspace)**: verify the orchestrator continues to all remaining workspaces, records the failure, and halts after the full pass.
+- **Per-workspace command failure (multiple workspaces)**: verify all failures are collected and reported.
+- **`instanceVersion` advancement guard**: verify the orchestrator refuses to start the next bundle when any workspace version != `instanceVersion`.
+- **Skip-if-completed**: verify already-completed commands (both instance and per-workspace) are skipped on re-run.
+- **Retry counter**: verify re-run inserts a new row with incremented `retry`, previous rows untouched.
+- **`--force-rerun`**: verify all commands re-execute regardless of history.
+- **`--force` with straggler workspaces**: verify ineligible workspaces are skipped and reported as "refused".
+- **Single-workspace mode (`-w`)**: verify `instanceCommands` run, only the targeted workspace's `perWorkspaceCommands` run, other workspaces untouched.
+- **No-op upgrade**: `instanceVersion` == `APP_VERSION`, nothing to do.
+- **Log capture**: verify failure logs are stored in the history row, success logs are discarded.
+- **Row eviction**: verify rows for versions not in `UPGRADE_COMMAND_SUPPORTED_VERSIONS` are deleted at the start of the run.
+
+### Pre-Release CI: Full Cross-Version Upgrade
+
+A CI pipeline runs before every release to validate the entire cross-version upgrade path end-to-end. This catches breaking changes that would silently narrow the supported upgrade range.
+
+**What it does**:
+
+1. Starts a Twenty instance at the **oldest version in `UPGRADE_COMMAND_SUPPORTED_VERSIONS`** (e.g. `1.17.0`) with a seeded database containing representative workspace data.
+2. Deploys the **latest release candidate** (`APP_VERSION` = target version).
+3. Runs the full upgrade orchestrator.
+4. Verifies: `instanceVersion` matches `APP_VERSION`, all workspace versions match `APP_VERSION`, all commands recorded as `completed` in both history tables, post-upgrade health check passes.
+
+**Why this matters**: the orchestrator unit tests validate the motor's logic, but they don't catch stale commands -- e.g. a `perWorkspaceCommand` in `bundle_1190` that reads a column dropped by `bundle_1210`'s `instanceCommands`. Only a real end-to-end run against actual version bundles surfaces these. This CI is the safety net for the breaking change backward compatibility principle.
+
+**Trigger**: runs as a pre-release gate. A failure blocks the release until the breaking change is resolved (either by fixing the command or by dropping the affected versions from `UPGRADE_COMMAND_SUPPORTED_VERSIONS`).
+
+---
+
+## Incremental Implementation Roadmap
+
+The refactor is designed to be shipped incrementally, phase by phase, without requiring a big-bang rewrite.
+
+### Phase 1: Command Taxonomy Refactor (start here)
+
+**Goal**: Introduce `GlobalCommand` and `PerWorkspaceCommand` base classes and the `UpgradeVersionBundle` (`instanceCommands`/`perWorkspaceCommands`) format, applied to the current version's upgrade bundle.
+
+**What changes**:
+
+- Create `GlobalCommand` and `PerWorkspaceCommand` abstract base classes.
+- Refactor the current `commands_1200` array into a typed `bundle_1200: UpgradeVersionBundle` with `instanceCommands` (global-only) and `perWorkspaceCommands` (per-workspace-only) arrays.
+- TypeORM migration becomes a `GlobalCommand` entry in the `instanceCommands` array.
+- The orchestrator (`UpgradeCommandOrchestrator`) replaces `UpgradeCommandRunner` and walks `instanceCommands` then `perWorkspaceCommands`, dispatching each entry based on its type.
+- Individual upgrade commands (e.g. `backfillCommandMenuItems`) are migrated to extend `PerWorkspaceCommand`.
+- The old inheritance chain (`MigrationCommandRunner` -> `WorkspacesMigrationCommandRunner` -> `ActiveOrSuspendedWorkspacesMigrationCommandRunner` -> `UpgradeCommandRunner`) is removed.
+
+**What stays the same**:
+
+- `UpgradeCommand` remains the nest-commander entry point, delegating to the orchestrator.
+- Version comparison still uses major.minor.
+- Only the current version bundle is refactored; older version entries (e.g. `1.19.0: []`) are left as-is or trivially wrapped.
+
+**Going forward**: the next version's upgrade commands (e.g. `1.21.0`) should be written directly against the new pattern -- extending `GlobalCommand` or `PerWorkspaceCommand` and registered in an `UpgradeVersionBundle`. This validates the new taxonomy on a real upgrade cycle.
+
+**Validation**: the upgrade command produces the same outcome as before -- same TypeORM migrations run, same per-workspace commands execute in the same order.
+
+### Phase 2: Cross-Version Upgrade and Instance Version
+
+**Goal**: Allow an instance to upgrade across multiple minor versions in a single run, with strict sequential version-by-version processing.
+
+**What changes**:
+
+- Introduce `instanceVersion` stored in the `KeyValuePair` table (`CONFIG_VARIABLE`, `userId = null`, `workspaceId = null`, key = `INSTANCE_VERSION`). Seed it from `APP_VERSION` on first deployment.
+- The orchestrator iterates through `UPGRADE_COMMAND_SUPPORTED_VERSIONS` from `instanceVersion + 1` to `APP_VERSION`, processing one version bundle at a time: `instanceCommands`, stamp `instanceVersion`, `perWorkspaceCommands` for all workspaces at `instanceVersion - 1`, verify all succeeded.
+- `instanceVersion` advancement guard: before running `instanceCommands` for a bundle, verify all workspace versions equal `instanceVersion`. If any workspace is behind, the orchestrator refuses to advance.
+- Workspace eligibility: only workspaces at exactly `instanceVersion - 1` are upgraded. No straggler rescue.
+- Hard-block on failure: if any workspace fails during per-workspace commands, the upgrade stops entirely.
+- Version comparison remains major.minor at the bundle identity level. Patch releases can patch an existing version line, but corrective work should generally be introduced as **new command identities inside the same major.minor bundle** rather than by mutating previously shipped commands in place.
+- Guard logic: workspaces below `instanceVersion` block the upgrade (self-hosted default) or are skipped with `--force`.
+
+### Phase 3: Health Check and Error Reporting
+
+**Goal**: Structured post-upgrade validation and actionable error output.
+
+**What changes**:
+
+- Post-upgrade health check runs after all version bundles complete (instance version, workspace versions, command completion).
+- Structured upgrade report replaces raw stack traces: per-workspace status, failure details with captured stack traces, summary counts.
+- Report-a-problem template groundwork (workspace status endpoint).
+
+### Phase 4: Frontend (Follow-Up)
+
+- Settings page: workspace version display, version mismatch banner.
+- Report-a-problem: pre-filled template from workspace status endpoint.
+
+---
+
+## Migration Path from Current Architecture
+
+The current inheritance chain in `command-runners/` is replaced in Phase 1:
+
+- `MigrationCommandRunner` -- Removed (options like `--dry-run` move to orchestrator)
+- `WorkspacesMigrationCommandRunner` -- Becomes the `PerWorkspaceCommand` base class
+- `ActiveOrSuspendedWorkspacesMigrationCommandRunner` -- Folded into `PerWorkspaceCommand` (active/suspended is the default filter)
+- `UpgradeCommandRunner` -- Becomes `UpgradeCommandOrchestrator`
+- `UpgradeCommand` -- Stays as the nest-commander entry point, delegates to orchestrator
+
+Individual commands (e.g. `backfillCommandMenuItems`) keep their current granularity but extend either `GlobalCommand` or `PerWorkspaceCommand` explicitly.
+
+---
+
+## Real-World Scenarios
+
+### 1. Happy Path
+
+`APP_VERSION = 1.21.0`, `instanceVersion = 1.20.0`, all workspaces at
+`1.20.0`.
+
+- The orchestrator runs `bundle_1210.instanceCommands`.
+- `instanceVersion` is stamped to `1.21.0`.
+- The orchestrator runs `bundle_1210.perWorkspaceCommands` for every workspace.
+- All workspaces succeed and are stamped to `1.21.0`.
+- Final state: `instanceVersion = 1.21.0`, all workspace versions = `1.21.0`.
+
+### 2. One Command Failed
+
+`APP_VERSION = 1.21.0`, `instanceVersion = 1.20.0`, workspaces A/B/C at
+`1.20.0`.
+
+- `bundle_1210.instanceCommands` succeed and `instanceVersion` is stamped to
+  `1.21.0`.
+- Workspace A succeeds and is stamped to `1.21.0`.
+- Workspace B fails on `backfill-new-field` and stays at `1.20.0`.
+- Workspace C is still attempted and succeeds, ending at `1.21.0`.
+- The upgrade halts after the full workspace pass.
+- On re-run, instance commands are skipped by history; only workspace B is
+  retried.
+- The next bundle cannot start until B also reaches `1.21.0`.
+
+### 3. `1.20.0` to `1.20.1`: Add a New Command
+
+`1.20.0` shipped with:
+
+- `foo`
+- `bar`
+
+After release, we realize some data still needs a missing backfill. In
+`1.20.1`, we keep the existing `1.20` bundle identity and add:
+
+- `foo`
+- `bar`
+- `backfill-missing-baz`
+
+Expected behavior:
+
+- History already contains successful rows for `foo` and `bar`.
+- Those commands are skipped.
+- `backfill-missing-baz` has never run, so it executes once.
+- History remains readable: the patch added a new corrective operation instead
+  of reinterpreting an old one.
+
+### 4. `1.20.0` to `1.20.1`: Rename a Previously Released Command
+
+`1.20.0` shipped with a command named `foo`.
+
+Later we discover `foo` was semantically wrong: maybe it updated the right data
+set but missed a required transformation, or maybe it should have run after
+another command. In `1.20.1`, we **do not** keep the name `foo` and change its
+meaning silently. Instead we introduce a new command such as:
+
+- `foo`
+- `foo-fix-missing-transformation`
+
+or:
+
+- `foo`
+- `rebuild-foo-after-order-fix`
+
+Expected behavior:
+
+- The successful `foo` history rows remain valid and untouched.
+- The new corrective command runs once because it has a new identity.
+- Operators can clearly see what happened in history: first `foo`, then the
+  later repair command.
+- This avoids history collisions and makes the patch behavior explicit.

nx.json

@@ -44,12 +44,12 @@
       "cache": true,
       "options": {
         "cwd": "{projectRoot}",
-        "command": "npx oxlint -c .oxlintrc.json . && (npx oxfmt --check . || (echo 'ERROR: oxfmt formatting check failed! Fix with: npx nx lint --configuration=fix' && false))"
+        "command": "npx oxlint -c .oxlintrc.json . && (prettier . --check --cache --cache-location ../../.cache/prettier/{projectRoot} --cache-strategy metadata || (echo 'ERROR: Prettier formatting check failed! Fix with: npx nx lint --configuration=fix' && false))"
       },
       "configurations": {
         "ci": {},
         "fix": {
-          "command": "npx oxlint --fix -c .oxlintrc.json . && npx oxfmt ."
+          "command": "npx oxlint --fix -c .oxlintrc.json . && prettier . --write --cache --cache-location ../../.cache/prettier/{projectRoot} --cache-strategy metadata"
         }
       },
       "dependsOn": ["^build", "twenty-oxlint-rules:build"]
@@ -57,14 +57,13 @@
     "lint:diff-with-main": {
       "executor": "nx:run-commands",
       "cache": false,
-      "dependsOn": ["twenty-oxlint-rules:build"],
       "options": {
-        "command": "FILES=$(git diff --name-only --diff-filter=d main -- {projectRoot}/ | grep -E '{args.pattern}'); [ -z \"$FILES\" ] && echo 'No changed files.' || (npx oxlint -c {projectRoot}/.oxlintrc.json $FILES && (npx oxfmt --check $FILES || (echo 'ERROR: oxfmt formatting check failed! Fix with: npx nx lint:diff-with-main --configuration=fix' && false)))",
+        "command": "FILES=$(git diff --name-only --diff-filter=d main -- {projectRoot}/ | grep -E '{args.pattern}'); [ -z \"$FILES\" ] && echo 'No changed files.' || (npx oxlint -c {projectRoot}/.oxlintrc.json $FILES && (prettier --check $FILES || (echo 'ERROR: Prettier formatting check failed! Fix with: npx nx lint:diff-with-main --configuration=fix' && false)))",
         "pattern": "\\.(ts|tsx|js|jsx)$"
       },
       "configurations": {
         "fix": {
-          "command": "FILES=$(git diff --name-only --diff-filter=d main -- {projectRoot}/ | grep -E '{args.pattern}'); [ -z \"$FILES\" ] && echo 'No changed files.' || (npx oxlint --fix -c {projectRoot}/.oxlintrc.json $FILES && npx oxfmt $FILES)"
+          "command": "FILES=$(git diff --name-only --diff-filter=d main -- {projectRoot}/ | grep -E '{args.pattern}'); [ -z \"$FILES\" ] && echo 'No changed files.' || (npx oxlint --fix -c {projectRoot}/.oxlintrc.json $FILES && prettier --write $FILES)"
         }
       }
     },
@@ -73,14 +72,18 @@
       "cache": true,
       "options": {
         "cwd": "{projectRoot}",
-        "command": "npx oxfmt --check {args.files} {args.write}",
-        "files": ".",
-        "write": ""
+        "command": "prettier {args.files} --check --cache {args.cache} --cache-location {args.cacheLocation} --write {args.write} --cache-strategy {args.cacheStrategy}",
+        "cache": true,
+        "cacheLocation": "../../.cache/prettier/{projectRoot}",
+        "cacheStrategy": "metadata",
+        "write": false
       },
       "configurations": {
-        "ci": {},
+        "ci": {
+          "cacheStrategy": "content"
+        },
         "fix": {
-          "command": "npx oxfmt {args.files}"
+          "write": true
         }
       },
       "dependsOn": ["^build"]
@@ -138,7 +141,7 @@
       "cache": false,
       "options": {
         "cwd": "{projectRoot}",
-        "command": "node -e \"const fs=require('fs'),p=JSON.parse(fs.readFileSync('package.json','utf8'));p.version='{args.releaseVersion}';fs.writeFileSync('package.json',JSON.stringify(p,null,2)+'\\n');\""
+        "command": "npm pkg set version={args.releaseVersion}"
       }
     },
     "storybook:build": {

package.json

@@ -1,21 +1,172 @@
 {
   "private": true,
+  "dependencies": {
+    "@apollo/client": "^4.0.0",
+    "@floating-ui/react": "^0.24.3",
+    "@linaria/core": "^6.2.0",
+    "@linaria/react": "^6.2.1",
+    "@radix-ui/colors": "^3.0.0",
+    "@sniptt/guards": "^0.2.0",
+    "@tabler/icons-react": "^3.31.0",
+    "@wyw-in-js/babel-preset": "^1.0.6",
+    "@wyw-in-js/vite": "^0.7.0",
+    "archiver": "^7.0.1",
+    "danger-plugin-todos": "^1.3.1",
+    "date-fns": "^2.30.0",
+    "date-fns-tz": "^2.0.0",
+    "deep-equal": "^2.2.2",
+    "file-type": "16.5.4",
+    "framer-motion": "^11.18.0",
+    "fuse.js": "^7.1.0",
+    "googleapis": "105",
+    "hex-rgb": "^5.0.0",
+    "immer": "^10.1.1",
+    "jotai": "^2.17.1",
+    "libphonenumber-js": "^1.10.26",
+    "lodash.camelcase": "^4.3.0",
+    "lodash.chunk": "^4.2.0",
+    "lodash.compact": "^3.0.1",
+    "lodash.escaperegexp": "^4.1.2",
+    "lodash.groupby": "^4.6.0",
+    "lodash.identity": "^3.0.0",
+    "lodash.isempty": "^4.4.0",
+    "lodash.isequal": "^4.5.0",
+    "lodash.isobject": "^3.0.2",
+    "lodash.kebabcase": "^4.1.1",
+    "lodash.mapvalues": "^4.6.0",
+    "lodash.merge": "^4.6.2",
+    "lodash.omit": "^4.5.0",
+    "lodash.pickby": "^4.6.0",
+    "lodash.snakecase": "^4.1.1",
+    "lodash.upperfirst": "^4.3.1",
+    "microdiff": "^1.3.2",
+    "next-with-linaria": "^1.3.0",
+    "planer": "^1.2.0",
+    "pluralize": "^8.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-responsive": "^9.0.2",
+    "react-router-dom": "^6.30.3",
+    "react-tooltip": "^5.13.1",
+    "remark-gfm": "^4.0.1",
+    "rxjs": "^7.2.0",
+    "semver": "^7.5.4",
+    "slash": "^5.1.0",
+    "temporal-polyfill": "^0.3.0",
+    "ts-key-enum": "^2.0.12",
+    "tslib": "^2.8.1",
+    "type-fest": "4.10.1",
+    "typescript": "5.9.2",
+    "uuid": "^9.0.0",
+    "vite-tsconfig-paths": "^4.2.1",
+    "xlsx-ugnis": "^0.19.3",
+    "zod": "^4.1.11"
+  },
   "devDependencies": {
+    "@babel/core": "^7.14.5",
+    "@babel/preset-react": "^7.14.5",
+    "@babel/preset-typescript": "^7.24.6",
+    "@chromatic-com/storybook": "^4.1.3",
+    "@graphql-codegen/cli": "^3.3.1",
+    "@graphql-codegen/client-preset": "^4.1.0",
+    "@graphql-codegen/typescript": "^3.0.4",
+    "@graphql-codegen/typescript-operations": "^3.0.4",
+    "@graphql-codegen/typescript-react-apollo": "^3.3.7",
     "@nx/jest": "22.5.4",
     "@nx/js": "22.5.4",
     "@nx/react": "22.5.4",
     "@nx/storybook": "22.5.4",
     "@nx/vite": "22.5.4",
     "@nx/web": "22.5.4",
+    "@oxlint/plugins": "^1.51.0",
+    "@sentry/types": "^8",
+    "@storybook-community/storybook-addon-cookie": "^5.0.0",
+    "@storybook/addon-coverage": "^3.0.0",
+    "@storybook/addon-docs": "^10.2.13",
+    "@storybook/addon-links": "^10.2.13",
+    "@storybook/addon-vitest": "^10.2.13",
+    "@storybook/icons": "^2.0.1",
+    "@storybook/react-vite": "^10.2.13",
+    "@storybook/test-runner": "^0.24.2",
+    "@swc-node/register": "^1.11.1",
+    "@swc/cli": "^0.7.10",
+    "@swc/core": "^1.15.11",
+    "@swc/helpers": "~0.5.19",
+    "@swc/jest": "^0.2.39",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@types/addressparser": "^1.0.3",
+    "@types/bcrypt": "^5.0.0",
+    "@types/bytes": "^3.1.1",
+    "@types/chrome": "^0.0.267",
+    "@types/deep-equal": "^1.0.1",
+    "@types/fs-extra": "^11.0.4",
+    "@types/graphql-fields": "^1.3.6",
+    "@types/inquirer": "^9.0.9",
+    "@types/jest": "^30.0.0",
+    "@types/lodash.camelcase": "^4.3.7",
+    "@types/lodash.compact": "^3.0.9",
+    "@types/lodash.escaperegexp": "^4.1.9",
+    "@types/lodash.groupby": "^4.6.9",
+    "@types/lodash.identity": "^3.0.9",
+    "@types/lodash.isempty": "^4.4.7",
+    "@types/lodash.isequal": "^4.5.7",
+    "@types/lodash.isobject": "^3.0.7",
+    "@types/lodash.kebabcase": "^4.1.7",
+    "@types/lodash.mapvalues": "^4.6.9",
+    "@types/lodash.omit": "^4.5.9",
+    "@types/lodash.pickby": "^4.6.9",
+    "@types/lodash.snakecase": "^4.1.7",
+    "@types/lodash.upperfirst": "^4.3.7",
+    "@types/ms": "^0.7.31",
+    "@types/node": "^24.0.0",
+    "@types/passport-google-oauth20": "^2.0.11",
+    "@types/passport-jwt": "^3.0.8",
+    "@types/passport-microsoft": "^2.1.0",
+    "@types/pluralize": "^0.0.33",
     "@types/react": "^18.2.39",
+    "@types/react-datepicker": "^6.2.0",
     "@types/react-dom": "^18.2.15",
+    "@types/supertest": "^2.0.11",
+    "@types/uuid": "^9.0.2",
+    "@typescript/native-preview": "^7.0.0-dev.20260116.1",
+    "@vitejs/plugin-react-swc": "4.2.3",
+    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/coverage-istanbul": "^4.0.18",
+    "@vitest/coverage-v8": "^4.0.18",
     "@yarnpkg/types": "^4.0.0",
+    "chromatic": "^6.18.0",
     "concurrently": "^8.2.2",
+    "danger": "^13.0.4",
+    "dotenv-cli": "^7.4.4",
+    "esbuild": "^0.25.10",
     "http-server": "^14.1.1",
+    "jest": "29.7.0",
+    "jest-environment-jsdom": "30.0.0-beta.3",
+    "jest-environment-node": "^29.4.1",
+    "jest-fetch-mock": "^3.0.3",
+    "jsdom": "~22.1.0",
+    "msw": "^2.12.7",
+    "msw-storybook-addon": "^2.0.6",
     "nx": "22.5.4",
-    "oxfmt": "0.50.0",
+    "prettier": "^3.1.1",
+    "raw-loader": "^4.0.2",
+    "rimraf": "^5.0.5",
+    "source-map-support": "^0.5.20",
+    "storybook": "^10.2.13",
+    "storybook-addon-mock-date": "2.0.0",
+    "storybook-addon-pseudo-states": "^10.2.13",
+    "supertest": "^6.1.3",
+    "ts-jest": "^29.1.1",
+    "ts-loader": "^9.2.3",
+    "ts-node": "10.9.1",
+    "tsc-alias": "^1.8.16",
+    "tsconfig-paths": "^4.2.0",
     "tsx": "^4.17.0",
-    "verdaccio": "^6.3.1"
+    "verdaccio": "^6.3.1",
+    "vite": "^7.0.0",
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": "^24.5.0",
@@ -28,15 +179,12 @@
   "resolutions": {
     "graphql": "16.8.1",
     "type-fest": "4.10.1",
-    "typescript": "5.9.3",
-    "nodemailer": "8.0.4",
+    "typescript": "5.9.2",
     "graphql-redis-subscriptions/ioredis": "^5.6.0",
     "@lingui/core": "5.1.2",
     "@types/qs": "6.9.16",
     "@wyw-in-js/transform@npm:0.6.0": "patch:@wyw-in-js/transform@npm%3A0.7.0#~/.yarn/patches/@wyw-in-js-transform-npm-0.7.0-ba641dc99f.patch",
-    "@wyw-in-js/transform@npm:0.7.0": "patch:@wyw-in-js/transform@npm%3A0.7.0#~/.yarn/patches/@wyw-in-js-transform-npm-0.7.0-ba641dc99f.patch",
-    "@opentelemetry/api": "1.9.1",
-    "chokidar": "^3.6.0"
+    "@wyw-in-js/transform@npm:0.7.0": "patch:@wyw-in-js/transform@npm%3A0.7.0#~/.yarn/patches/@wyw-in-js-transform-npm-0.7.0-ba641dc99f.patch"
   },
   "version": "0.2.1",
   "nx": {},
@@ -55,17 +203,18 @@
       "packages/twenty-utils",
       "packages/twenty-zapier",
       "packages/twenty-website",
+      "packages/twenty-website-new",
       "packages/twenty-docs",
       "packages/twenty-e2e-testing",
       "packages/twenty-shared",
       "packages/twenty-sdk",
       "packages/twenty-front-component-renderer",
       "packages/twenty-client-sdk",
+      "packages/twenty-apps",
       "packages/twenty-cli",
       "packages/create-twenty-app",
       "packages/twenty-oxlint-rules",
-      "packages/twenty-companion",
-      "packages/twenty-claude-skills"
+      "packages/twenty-companion"
     ]
   },
   "prettier": {

packages/create-twenty-app/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <a href="https://twenty.com">
     <picture>
-      <img alt="Twenty logo" src="https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-website/public/images/core/logo.svg" height="128">
+      <img alt="Twenty logo" src="https://raw.githubusercontent.com/twentyhq/twenty/2f25922f4cd5bd61e1427c57c4f8ea224e1d552c/packages/twenty-website/public/images/core/logo.svg" height="128">
     </picture>
   </a>
   <h1>Create Twenty App</h1>
@@ -12,44 +12,164 @@
 
 </div>
 
-The official scaffolding CLI for building apps on top of [Twenty CRM](https://twenty.com). Sets up a ready-to-run project with [twenty-sdk](https://www.npmjs.com/package/twenty-sdk).
+Create Twenty App is the official scaffolding CLI for building apps on top of [Twenty CRM](https://twenty.com). It sets up a ready‑to‑run project that works seamlessly with the [twenty-sdk](https://www.npmjs.com/package/twenty-sdk).
+
+- Zero‑config project bootstrap
+- Preconfigured scripts for auth, dev mode (watch & sync), uninstall, and function management
+- Strong TypeScript support and typed client generation
+
+## Documentation
+
+See Twenty application documentation https://docs.twenty.com/developers/extend/capabilities/apps
+
+## Prerequisites
+
+- Node.js 24+ (recommended) and Yarn 4
+- Docker (for the local Twenty dev server)
 
 ## Quick start
 
 ```bash
+# Scaffold a new app — the CLI will offer to start a local Twenty server
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app
+
+# The scaffolder can automatically:
+# 1. Start a local Twenty server (Docker)
+# 2. Open the browser to log in (tim@apple.dev / tim@apple.dev)
+# 3. Authenticate your app via OAuth
+
+# Or do it manually:
+yarn twenty server start          # Start local Twenty server
+yarn twenty remote add http://localhost:2020 --as local  # Authenticate via OAuth
+
+# Start dev mode: watches, builds, and syncs local changes to your workspace
+# (also auto-generates typed CoreApiClient — MetadataApiClient ships pre-built — both available via `twenty-client-sdk`)
 yarn twenty dev
+
+# Watch your application's function logs
+yarn twenty logs
+
+# Execute a function with a JSON payload
+yarn twenty exec -n my-function -p '{"key": "value"}'
+
+# Execute the pre-install function
+yarn twenty exec --preInstall
+
+# Execute the post-install function
+yarn twenty exec --postInstall
+
+# Build the app for distribution
+yarn twenty build
+
+# Publish the app to npm or directly to a Twenty server
+yarn twenty publish
+
+# Uninstall the application from the current workspace
+yarn twenty uninstall
 ```
 
-The scaffolder will:
+## Scaffolding modes
 
-1. Create a new project with TypeScript, linting, tests, and a preconfigured `twenty` CLI
-2. Start a local Twenty server via Docker (pulls the latest image automatically)
-3. Authenticate with the development API key
+Control which example files are included when creating a new app:
 
-## Options
+| Flag               | Behavior                                                                |
+| ------------------ | ----------------------------------------------------------------------- |
+| `-e, --exhaustive` | **(default)** Creates all example files                                 |
+| `-m, --minimal`    | Creates only core files (`application-config.ts` and `default-role.ts`) |
 
-| Flag                               | Description                                                           |
-| ---------------------------------- | --------------------------------------------------------------------- |
-| `--name <name>`                    | Set the app name                                                      |
-| `--display-name <displayName>`     | Set the display name                                                  |
-| `--description <description>`      | Set the description                                                   |
-| `--url <url>`                      | Twenty workspace URL (default: `http://localhost:2020`)               |
-| `--authentication-method <method>` | `oauth` or `apiKey` (default: `apiKey` for local, `oauth` for remote) |
+```bash
+# Default: all examples included
+npx create-twenty-app@latest my-app
 
-## Documentation
+# Minimal: only core files
+npx create-twenty-app@latest my-app -m
+```
 
-Full documentation is available at **[docs.twenty.com/developers/extend/apps](https://docs.twenty.com/developers/extend/apps/getting-started/quick-start)**:
+## What gets scaffolded
 
-- [Quick Start](https://docs.twenty.com/developers/extend/apps/getting-started/quick-start) — scaffold, run a local server, sync your code
-- [Concepts](https://docs.twenty.com/developers/extend/apps/getting-started/concepts) — how apps work: entity model, sandboxing, lifecycle
-- [Operations](https://docs.twenty.com/developers/extend/apps/operations/overview) — CLI, testing, CI, deploy and publish
+**Core files (always created):**
+
+- `application-config.ts` — Application metadata configuration
+- `roles/default-role.ts` — Default role for logic functions
+- `logic-functions/pre-install.ts` — Pre-install logic function (runs before app installation)
+- `logic-functions/post-install.ts` — Post-install logic function (runs after app installation)
+- TypeScript configuration, Oxlint, package.json, .gitignore
+- A prewired `twenty` script that delegates to the `twenty` CLI from twenty-sdk
+
+**Example files (controlled by scaffolding mode):**
+
+- `objects/example-object.ts` — Example custom object with a text field
+- `fields/example-field.ts` — Example standalone field extending the example object
+- `logic-functions/hello-world.ts` — Example logic function with HTTP trigger
+- `front-components/hello-world.tsx` — Example front component
+- `views/example-view.ts` — Example saved view for the example object
+- `navigation-menu-items/example-navigation-menu-item.ts` — Example sidebar navigation link
+- `skills/example-skill.ts` — Example AI agent skill definition
+- `__tests__/app-install.integration-test.ts` — Integration test that builds, installs, and verifies the app (includes `vitest.config.ts`, `tsconfig.spec.json`, and a setup file)
+
+## Local server
+
+The scaffolder can start a local Twenty dev server for you (all-in-one Docker image with PostgreSQL, Redis, server, and worker on port 2020). These commands only apply to the Docker-based dev server — they do not manage a Twenty instance started from source (e.g. `npx nx start twenty-server` on port 3000). You can also manage it manually:
+
+```bash
+yarn twenty server start     # Start (pulls image if needed)
+yarn twenty server status    # Check if it's healthy
+yarn twenty server logs      # Stream logs
+yarn twenty server stop      # Stop (data is preserved)
+yarn twenty server reset     # Wipe all data and start fresh
+```
+
+The server is pre-seeded with a workspace and user (`tim@apple.dev` / `tim@apple.dev`).
+
+## Next steps
+
+- Run `yarn twenty help` to see all available commands.
+- Use `yarn twenty remote add <url>` to authenticate with your Twenty workspace via OAuth.
+- Explore the generated project and add your first entity with `yarn twenty add` (logic functions, front components, objects, roles, views, navigation menu items, skills).
+- Use `yarn twenty dev` while you iterate — it watches, builds, and syncs changes to your workspace in real time.
+- `CoreApiClient` is auto-generated by `yarn twenty dev`. `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`) ships pre-built with the SDK. Both are available via `import { CoreApiClient } from 'twenty-client-sdk/core'` and `import { MetadataApiClient } from 'twenty-client-sdk/metadata'`.
+
+## Build and publish your application
+
+Once your app is ready, build and publish it using the CLI:
+
+```bash
+# Build the app (output goes to .twenty/output/)
+yarn twenty build
+
+# Build and create a tarball (.tgz) for distribution
+yarn twenty build --tarball
+
+# Publish to npm (requires npm login)
+yarn twenty publish
+
+# Publish with a dist-tag (e.g. beta, next)
+yarn twenty publish --tag beta
+
+# Deploy directly to a Twenty server (builds, uploads, and installs in one step)
+yarn twenty deploy
+```
+
+### Publish to the Twenty marketplace
+
+You can also contribute your application to the curated marketplace:
+
+```bash
+git clone https://github.com/twentyhq/twenty.git
+cd twenty
+git checkout -b feature/my-awesome-app
+```
+
+- Copy your app folder into `twenty/packages/twenty-apps`.
+- Commit your changes and open a pull request on https://github.com/twentyhq/twenty
+
+Our team reviews contributions for quality, security, and reusability before merging.
 
 ## Troubleshooting
 
-- Server not starting: check Docker is running (`docker info`), then try `yarn twenty docker:logs`.
-- Auth not working: run `yarn twenty remote:add --local` to re-authenticate.
+- Server not starting: check Docker is running (`docker info`), then try `yarn twenty server logs`.
+- Auth not working: make sure you're logged in to Twenty in the browser first, then run `yarn twenty remote add <url>`.
 - Types not generated: ensure `yarn twenty dev` is running — it auto-generates the typed client.
 
 ## Contributing

packages/create-twenty-app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-twenty-app",
-  "version": "2.9.0",
+  "version": "0.8.0-canary.7",
   "description": "Command-line interface to create Twenty application",
   "main": "dist/cli.cjs",
   "bin": "dist/cli.cjs",
@@ -32,6 +32,7 @@
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "fs-extra": "^11.2.0",
+    "inquirer": "^10.0.0",
     "lodash.camelcase": "^4.3.0",
     "lodash.kebabcase": "^4.1.1",
     "lodash.startcase": "^4.4.0",
@@ -39,18 +40,14 @@
     "uuid": "^13.0.0"
   },
   "devDependencies": {
-    "@swc/core": "^1.15.11",
-    "@swc/jest": "^0.2.39",
     "@types/fs-extra": "^11.0.0",
-    "@types/jest": "^30.0.0",
+    "@types/inquirer": "^9.0.0",
     "@types/lodash.camelcase": "^4.3.7",
     "@types/lodash.kebabcase": "^4.1.7",
     "@types/lodash.startcase": "^4",
     "@types/node": "^20.0.0",
-    "jest": "29.7.0",
-    "jest-environment-node": "^29.4.1",
     "twenty-shared": "workspace:*",
-    "typescript": "^5.9.3",
+    "typescript": "^5.9.2",
     "vite": "^7.0.0",
     "vite-plugin-dts": "^4.5.4",
     "vite-tsconfig-paths": "^4.2.1"

packages/create-twenty-app/src/cli.ts

@@ -1,10 +1,8 @@
 #!/usr/bin/env node
 import chalk from 'chalk';
 import { Command, CommanderError } from 'commander';
-import {
-  type AuthenticationMethod,
-  CreateAppCommand,
-} from '@/create-app.command';
+import { CreateAppCommand } from '@/create-app.command';
+import { type ScaffoldingMode } from '@/types/scaffolding-options';
 import packageJson from '../package.json';
 
 const program = new Command(packageJson.name)
@@ -15,28 +13,48 @@ const program = new Command(packageJson.name)
     'Output the current version of create-twenty-app.',
   )
   .argument('[directory]')
-  .option('-n, --name <name>', 'Application name')
-  .option('-d, --display-name <displayName>', 'Application display name')
-  .option('--description <description>', 'Application description')
-  .option('--url <url>', 'Twenty server URL (default: http://localhost:2020)')
-  .option('--api-url <apiUrl>', '[deprecated: use --url]')
+  .option('-e, --exhaustive', 'Create all example entities (default)')
   .option(
-    '--authentication-method <method>',
-    'Authentication method: oauth or apiKey (default: apiKey for local, oauth for remote)',
+    '-m, --minimal',
+    'Create only core entities (application-config and default-role)',
+  )
+  .option('-n, --name <name>', 'Application name (skips prompt)')
+  .option(
+    '-d, --display-name <displayName>',
+    'Application display name (skips prompt)',
+  )
+  .option(
+    '--description <description>',
+    'Application description (skips prompt)',
+  )
+  .option(
+    '--skip-local-instance',
+    'Skip the local Twenty instance setup prompt',
   )
   .helpOption('-h, --help', 'Display this help message.')
   .action(
     async (
       directory?: string,
       options?: {
+        exhaustive?: boolean;
+        minimal?: boolean;
         name?: string;
         displayName?: string;
         description?: string;
-        url?: string;
-        apiUrl?: string;
-        authenticationMethod?: AuthenticationMethod;
+        skipLocalInstance?: boolean;
       },
     ) => {
+      const modeFlags = [options?.exhaustive, options?.minimal].filter(Boolean);
+
+      if (modeFlags.length > 1) {
+        console.error(
+          chalk.red(
+            'Error: --exhaustive and --minimal are mutually exclusive.',
+          ),
+        );
+        process.exit(1);
+      }
+
       if (directory && !/^[a-z0-9-]+$/.test(directory)) {
         console.error(
           chalk.red(
@@ -51,33 +69,15 @@ const program = new Command(packageJson.name)
         process.exit(1);
       }
 
-      if (
-        options?.authenticationMethod &&
-        !['oauth', 'apiKey'].includes(options.authenticationMethod)
-      ) {
-        console.error(
-          chalk.red(
-            'Error: --authentication-method must be "oauth" or "apiKey".',
-          ),
-        );
-        process.exit(1);
-      }
-
-      if (options?.apiUrl) {
-        console.warn(
-          chalk.yellow('Warning: --api-url is deprecated. Use --url instead.'),
-        );
-      }
-
-      const serverUrl = (options?.url ?? options?.apiUrl)?.replace(/\/+$/, '');
+      const mode: ScaffoldingMode = options?.minimal ? 'minimal' : 'exhaustive';
 
       await new CreateAppCommand().execute({
         directory,
+        mode,
         name: options?.name,
         displayName: options?.displayName,
         description: options?.description,
-        serverUrl,
-        authenticationMethod: options?.authenticationMethod,
+        skipLocalInstance: options?.skipLocalInstance,
       });
     },
   );

packages/create-twenty-app/src/constants/base-application/LLMS.md

@@ -0,0 +1,14 @@
+## Base documentation
+
+- Documentation: https://docs.twenty.com/developers/extend/capabilities/apps
+- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/app-seeds/rich-app
+
+## UUID requirement
+
+- All generated UUIDs must be valid UUID v4.
+
+## Common Pitfalls
+
+- Creating an object without an index view associated. Unless this is a technical object, user will need to visualize it.
+- Creating a view without a navigationMenuItem associated. This will make the view available on the left sidebar.
+- Creating a front-end component that has a scroll instead of being responsive to its fixed widget height and width, unless it is specifically meant to be used in a canvas tab.

packages/create-twenty-app/src/constants/base-application/README.md

@@ -0,0 +1,11 @@
+This is a [Twenty](https://twenty.com) application bootstrapped with [`create-twenty-app`](https://www.npmjs.com/package/create-twenty-app).
+
+## Getting Started
+
+Run `yarn twenty help` to list all available commands.
+
+## Learn More
+
+- [Twenty Apps documentation](https://docs.twenty.com/developers/extend/capabilities/apps)
+- [twenty-sdk CLI reference](https://www.npmjs.com/package/twenty-sdk)
+- [Discord](https://discord.gg/cx5n4Jzs57)

packages/create-twenty-app/src/constants/base-application/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "sourceMap": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "jsx": "react-jsx",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "importHelpers": true,
+    "allowUnreachableCode": false,
+    "strict": true,
+    "alwaysStrict": true,
+    "noImplicitAny": true,
+    "strictBindCallApply": false,
+    "target": "es2018",
+    "module": "esnext",
+    "lib": ["es2020", "dom"],
+    "skipLibCheck": true,
+    "skipDefaultLibCheck": true,
+    "resolveJsonModule": true,
+    "paths": {
+      "src/*": ["./src/*"],
+      "~/*": ["./*"]
+    }
+  },
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "**/*.integration-test.ts"
+  ]
+}

packages/create-twenty-app/src/constants/template/.oxlintrc.json

@@ -1,37 +0,0 @@
-{
-  "$schema": "./node_modules/oxlint/configuration_schema.json",
-  "plugins": ["typescript"],
-  "categories": {
-    "correctness": "off"
-  },
-  "ignorePatterns": ["node_modules", "dist"],
-  "rules": {
-    "no-unused-vars": "off",
-
-    "typescript/no-unused-vars": [
-      "warn",
-      {
-        "argsIgnorePattern": "^_"
-      }
-    ],
-    "typescript/no-explicit-any": "off"
-  },
-  "overrides": [
-    {
-      "files": ["**/*.logic-function.ts", "**/logic-functions/**/*.ts"],
-      "rules": {
-        "no-restricted-imports": [
-          "error",
-          {
-            "patterns": [
-              {
-                "group": ["twenty-shared", "twenty-shared/*"],
-                "message": "Logic functions must not import from twenty-shared directly. Import runtime types and helpers from `twenty-sdk/logic-function` instead so the logic-function bundle stays minimal."
-              }
-            ]
-          }
-        ]
-      }
-    }
-  ]
-}

packages/create-twenty-app/src/constants/template/AGENTS.md

@@ -1,67 +0,0 @@
-## Base documentation
-
-- Getting started:
-  - https://docs.twenty.com/developers/extend/apps/getting-started/quick-start.md
-  - https://docs.twenty.com/developers/extend/apps/getting-started/concepts.md
-  - https://docs.twenty.com/developers/extend/apps/getting-started/project-structure.md
-  - https://docs.twenty.com/developers/extend/apps/getting-started/local-server.md
-  - https://docs.twenty.com/developers/extend/apps/getting-started/scaffolding.md
-  - https://docs.twenty.com/developers/extend/apps/getting-started/troubleshooting.md
-- Config:
-  - https://docs.twenty.com/developers/extend/apps/config/overview.md
-  - https://docs.twenty.com/developers/extend/apps/config/application.md
-  - https://docs.twenty.com/developers/extend/apps/config/roles.md
-  - https://docs.twenty.com/developers/extend/apps/config/install-hooks.md
-  - https://docs.twenty.com/developers/extend/apps/config/public-assets.md
-- Data:
-  - https://docs.twenty.com/developers/extend/apps/data/overview.md
-  - https://docs.twenty.com/developers/extend/apps/data/objects.md
-  - https://docs.twenty.com/developers/extend/apps/data/extending-objects.md
-  - https://docs.twenty.com/developers/extend/apps/data/relations.md
-- Logic:
-  - https://docs.twenty.com/developers/extend/apps/logic/overview.md
-  - https://docs.twenty.com/developers/extend/apps/logic/logic-functions.md
-  - https://docs.twenty.com/developers/extend/apps/logic/skills-and-agents.md
-  - https://docs.twenty.com/developers/extend/apps/logic/connections.md
-- Layout:
-  - https://docs.twenty.com/developers/extend/apps/layout/overview.md
-  - https://docs.twenty.com/developers/extend/apps/layout/views.md
-  - https://docs.twenty.com/developers/extend/apps/layout/navigation-menu-items.md
-  - https://docs.twenty.com/developers/extend/apps/layout/page-layouts.md
-  - https://docs.twenty.com/developers/extend/apps/layout/front-components.md
-  - https://docs.twenty.com/developers/extend/apps/layout/command-menu-items.md
-- Operations:
-  - https://docs.twenty.com/developers/extend/apps/operations/overview.md
-  - https://docs.twenty.com/developers/extend/apps/operations/cli.md
-  - https://docs.twenty.com/developers/extend/apps/operations/testing.md
-  - https://docs.twenty.com/developers/extend/apps/operations/publishing.md
-- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples/postcard
-
-## UUID requirement
-
-- All generated UUIDs must be valid UUID v4.
-
-## Common Pitfalls
-
-- Creating an object without an index view associated. Unless this is a technical object, user will need to visualize it.
-- Creating a view without a navigationMenuItem associated. This will make the view available on the left sidebar.
-- Creating a front-end component that has a scroll instead of being responsive to its fixed widget height and width, unless it is specifically meant to be used in a canvas tab.
-
-## Best practice
-
-It's highly recommended to create new app entities using `yarn twenty dev:add`. These are the options:
-
-| Entity type          | Command                                  | Generated file                        |
-| -------------------- | ---------------------------------------- | ------------------------------------- |
-| Object               | `yarn twenty dev:add object`             | `src/objects/<name>.ts`               |
-| Field                | `yarn twenty dev:add field`              | `src/fields/<name>.ts`                |
-| Logic function       | `yarn twenty dev:add logicFunction`      | `src/logic-functions/<name>.ts`       |
-| Front component      | `yarn twenty dev:add frontComponent`     | `src/front-components/<name>.tsx`     |
-| Role                 | `yarn twenty dev:add role`               | `src/roles/<name>.ts`                 |
-| Skill                | `yarn twenty dev:add skill`              | `src/skills/<name>.ts`                |
-| Agent                | `yarn twenty dev:add agent`              | `src/agents/<name>.ts`                |
-| View                 | `yarn twenty dev:add view`               | `src/views/<name>.ts`                 |
-| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |
-| Page layout          | `yarn twenty dev:add pageLayout`         | `src/page-layouts/<name>.ts`          |
-
-This helps automatically generate required IDs etc.

packages/create-twenty-app/src/constants/template/README.md

@@ -1,22 +0,0 @@
-This is a [Twenty](https://twenty.com) application bootstrapped with [`create-twenty-app`](https://www.npmjs.com/package/create-twenty-app).
-
-## Getting Started
-
-This app was scaffolded with a local Twenty server running at [http://localhost:2020](http://localhost:2020).
-
-Login with the default development credentials: `tim@apple.dev` / `tim@apple.dev`.
-
-Run `yarn twenty help` to list all available commands.
-
-## Useful Commands
-
-- `yarn twenty dev` - Start the development server and sync your app
-- `yarn twenty docker:status` - Check the local Twenty server status
-- `yarn twenty docker:start` - Start the local Twenty server
-- `yarn test` - Run integration tests
-
-## Learn More
-
-- [Twenty Apps documentation](https://docs.twenty.com/developers/extend/apps/getting-started/quick-start)
-- [twenty-sdk CLI reference](https://www.npmjs.com/package/twenty-sdk)
-- [Discord](https://discord.gg/cx5n4Jzs57)

packages/create-twenty-app/src/constants/template/github/workflows/cd.yml

@@ -1,42 +0,0 @@
-name: CD
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    types: [labeled]
-
-permissions:
-  contents: read
-
-env:
-  TWENTY_DEPLOY_URL: http://localhost:2020
-
-concurrency:
-  group: cd-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  deploy-and-install:
-    if: >-
-      github.event_name == 'push' ||
-      (github.event_name == 'pull_request' && github.event.label.name == 'deploy')
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ github.event.pull_request.head.sha || github.sha }}
-
-      - name: Deploy
-        uses: twentyhq/twenty/.github/actions/deploy-twenty-app@main
-        with:
-          api-url: ${{ env.TWENTY_DEPLOY_URL }}
-          api-key: ${{ secrets.TWENTY_DEPLOY_API_KEY }}
-
-      - name: Install
-        uses: twentyhq/twenty/.github/actions/install-twenty-app@main
-        with:
-          api-url: ${{ env.TWENTY_DEPLOY_URL }}
-          api-key: ${{ secrets.TWENTY_DEPLOY_API_KEY }}

packages/create-twenty-app/src/constants/template/github/workflows/ci.yml

@@ -1,48 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches:
-      - main
-  pull_request: {}
-
-permissions:
-  contents: read
-
-env:
-  TWENTY_VERSION: latest
-
-concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Spawn Twenty test instance
-        id: twenty
-        uses: twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main
-        with:
-          twenty-version: ${{ env.TWENTY_VERSION }}
-
-      - name: Enable Corepack
-        run: corepack enable
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version-file: '.nvmrc'
-          cache: yarn
-
-      - name: Install dependencies
-        run: yarn install --immutable
-
-      - name: Run integration tests
-        run: yarn test
-        env:
-          TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }}
-          TWENTY_API_KEY: ${{ steps.twenty.outputs.api-key }}

packages/create-twenty-app/src/constants/template/gitignore

@@ -1,38 +0,0 @@
-# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
-
-# dependencies
-/node_modules
-/.pnp
-.pnp.*
-.yarn
-
-# codegen
-generated
-
-# testing
-/coverage
-
-# dev
-/dist/
-
-.twenty
-
-# production
-/build
-
-# misc
-.DS_Store
-*.pem
-
-# debug
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-.pnpm-debug.log*
-
-# env files (can opt-in for committing if needed)
-.env*
-
-# typescript
-*.tsbuildinfo
-*.d.ts

packages/create-twenty-app/src/constants/template/package.json

@@ -1,33 +0,0 @@
-{
-  "name": "TO-BE-GENERATED",
-  "version": "0.1.0",
-  "license": "MIT",
-  "engines": {
-    "node": "^24.5.0",
-    "npm": "please-use-yarn",
-    "yarn": ">=4.0.2"
-  },
-  "keywords": [],
-  "packageManager": "yarn@4.9.2",
-  "scripts": {
-    "twenty": "twenty",
-    "lint": "oxlint -c .oxlintrc.json .",
-    "lint:fix": "oxlint --fix -c .oxlintrc.json .",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
-  "dependencies": {
-    "twenty-client-sdk": "TO-BE-GENERATED",
-    "twenty-sdk": "TO-BE-GENERATED"
-  },
-  "devDependencies": {
-    "@types/node": "^24.7.2",
-    "@types/react": "^19.0.0",
-    "oxlint": "^0.16.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "typescript": "^5.9.3",
-    "vite-tsconfig-paths": "^4.2.1",
-    "vitest": "^3.1.1"
-  }
-}

packages/create-twenty-app/src/constants/template/public/logo.svg

@@ -1,7 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 80" fill="none">
-  <rect width="80" height="80" rx="16" fill="#141414"/>
-  <rect x="20" y="20" width="16" height="16" rx="4" fill="#FAFAFA"/>
-  <rect x="44" y="20" width="16" height="16" rx="4" fill="#FAFAFA" opacity="0.6"/>
-  <rect x="20" y="44" width="16" height="16" rx="4" fill="#FAFAFA" opacity="0.6"/>
-  <rect x="44" y="44" width="16" height="16" rx="4" fill="#FAFAFA" opacity="0.3"/>
-</svg>

packages/create-twenty-app/src/constants/template/src/__tests__/global-setup.ts

@@ -1,87 +0,0 @@
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-
-import { appDevOnce, appUninstall } from 'twenty-sdk/cli';
-
-const APP_PATH = process.cwd();
-const CONFIG_DIR = path.join(os.homedir(), '.twenty');
-
-function validateEnv(): { apiUrl: string; apiKey: string } {
-  const apiUrl = process.env.TWENTY_API_URL;
-  const apiKey = process.env.TWENTY_API_KEY;
-
-  if (!apiUrl || !apiKey) {
-    throw new Error(
-      'TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +
-        'Start a local server: yarn twenty docker:start\n' +
-        'Or set them in vitest env config.',
-    );
-  }
-
-  return { apiUrl, apiKey };
-}
-
-async function checkServer(apiUrl: string) {
-  let response: Response;
-
-  try {
-    response = await fetch(`${apiUrl}/healthz`);
-  } catch {
-    throw new Error(
-      `Twenty server is not reachable at ${apiUrl}. ` +
-        'Make sure the server is running before executing integration tests.',
-    );
-  }
-
-  if (!response.ok) {
-    throw new Error(`Server at ${apiUrl} returned ${response.status}`);
-  }
-}
-
-function writeConfig(apiUrl: string, apiKey: string) {
-  const payload = JSON.stringify(
-    {
-      remotes: {
-        local: { apiUrl, apiKey, accessToken: apiKey },
-      },
-      defaultRemote: 'local',
-    },
-    null,
-    2,
-  );
-
-  fs.mkdirSync(CONFIG_DIR, { recursive: true });
-  fs.writeFileSync(path.join(CONFIG_DIR, 'config.test.json'), payload);
-}
-
-export async function setup() {
-  const { apiUrl, apiKey } = validateEnv();
-
-  await checkServer(apiUrl);
-
-  writeConfig(apiUrl, apiKey);
-
-  await appUninstall({ appPath: APP_PATH }).catch(() => {});
-
-  const result = await appDevOnce({
-    appPath: APP_PATH,
-    onProgress: (message: string) => console.log(`[dev] ${message}`),
-  });
-
-  if (!result.success) {
-    throw new Error(
-      `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,
-    );
-  }
-}
-
-export async function teardown() {
-  const uninstallResult = await appUninstall({ appPath: APP_PATH });
-
-  if (!uninstallResult.success) {
-    console.warn(
-      `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,
-    );
-  }
-}

packages/create-twenty-app/src/constants/template/src/__tests__/schema.integration-test.ts

@@ -1,46 +0,0 @@
-import { CoreApiClient } from 'twenty-client-sdk/core';
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
-import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
-import { describe, expect, it } from 'vitest';
-
-describe('App installation', () => {
-  it('should find the installed app in the applications list', async () => {
-    const client = new MetadataApiClient();
-
-    const result = await client.query({
-      findManyApplications: {
-        id: true,
-        name: true,
-        universalIdentifier: true,
-      },
-    });
-
-    const app = result.findManyApplications.find(
-      (a: { universalIdentifier: string }) =>
-        a.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER,
-    );
-
-    expect(app).toBeDefined();
-  });
-});
-
-describe('CoreApiClient', () => {
-  it('should support CRUD on standard objects', async () => {
-    const client = new CoreApiClient();
-
-    const created = await client.mutation({
-      createNote: {
-        __args: { data: { title: 'Integration test note' } },
-        id: true,
-      },
-    });
-    expect(created.createNote.id).toBeDefined();
-
-    await client.mutation({
-      destroyNote: {
-        __args: { id: created.createNote.id },
-        id: true,
-      },
-    });
-  });
-});

packages/create-twenty-app/src/constants/template/src/application-config.ts

@@ -1,13 +0,0 @@
-import { defineApplication } from 'twenty-sdk/define';
-
-import {
-  APP_DESCRIPTION,
-  APP_DISPLAY_NAME,
-  APPLICATION_UNIVERSAL_IDENTIFIER,
-} from 'src/constants/universal-identifiers';
-
-export default defineApplication({
-  universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
-  displayName: APP_DISPLAY_NAME,
-  description: APP_DESCRIPTION,
-});

packages/create-twenty-app/src/constants/template/src/constants/universal-identifiers.ts

@@ -1,11 +0,0 @@
-export const APP_DISPLAY_NAME = 'DISPLAY-NAME-TO-BE-GENERATED';
-export const APP_DESCRIPTION = 'DESCRIPTION-TO-BE-GENERATED';
-export const APPLICATION_UNIVERSAL_IDENTIFIER = 'UUID-TO-BE-GENERATED';
-export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER = 'UUID-TO-BE-GENERATED';
-export const MAIN_PAGE_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER =
-  'UUID-TO-BE-GENERATED';
-export const MAIN_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER = 'UUID-TO-BE-GENERATED';
-export const MAIN_PAGE_LAYOUT_TAB_UNIVERSAL_IDENTIFIER = 'UUID-TO-BE-GENERATED';
-export const MAIN_PAGE_WIDGET_UNIVERSAL_IDENTIFIER = 'UUID-TO-BE-GENERATED';
-export const MAIN_PAGE_NAVIGATION_MENU_ITEM_UNIVERSAL_IDENTIFIER =
-  'UUID-TO-BE-GENERATED';

packages/create-twenty-app/src/constants/template/src/default-role.ts

@@ -1,16 +0,0 @@
-import { defineApplicationRole } from 'twenty-sdk/define';
-
-import {
-  APP_DISPLAY_NAME,
-  DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
-} from 'src/constants/universal-identifiers';
-
-export default defineApplicationRole({
-  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
-  label: `${APP_DISPLAY_NAME} default function role`,
-  description: `${APP_DISPLAY_NAME} default function role`,
-  canReadAllObjectRecords: true,
-  canUpdateAllObjectRecords: true,
-  canSoftDeleteAllObjectRecords: true,
-  canDestroyAllObjectRecords: false,
-});

packages/create-twenty-app/src/constants/template/src/front-components/main-page.tsx

@@ -1,291 +0,0 @@
-import { defineFrontComponent } from 'twenty-sdk/define';
-import {
-  Avatar,
-  IconBox,
-  IconHierarchy,
-  IconLayout,
-  IconSettingsAutomation,
-} from 'twenty-sdk/ui';
-import { useState } from 'react';
-
-import {
-  APP_DISPLAY_NAME,
-  MAIN_PAGE_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
-} from 'src/constants/universal-identifiers';
-
-const DOCS_BASE_URL = 'https://docs.twenty.com/developers/extend/apps';
-
-const CATEGORIES = [
-  {
-    title: 'Data model',
-    color: '#73D08D',
-    items: [
-      { label: 'CUSTOM OBJECT', href: `${DOCS_BASE_URL}/data/objects` },
-      {
-        label: 'CUSTOM FIELDS',
-        href: `${DOCS_BASE_URL}/data/extending-objects`,
-      },
-    ],
-    rotation: '2.4deg',
-  },
-  {
-    title: 'Logic',
-    color: '#F4D345',
-    items: [
-      {
-        label: 'TOOLS',
-        href: `${DOCS_BASE_URL}/logic/logic-functions`,
-      },
-      {
-        label: 'LOGIC FUNCTION',
-        href: `${DOCS_BASE_URL}/logic/logic-functions`,
-      },
-      {
-        label: 'SKILLS',
-        href: `${DOCS_BASE_URL}/logic/skills-and-agents`,
-      },
-    ],
-    rotation: '0deg',
-  },
-  {
-    title: 'Layout',
-    color: '#C4A2E0',
-    items: [
-      { label: 'VIEWS', href: `${DOCS_BASE_URL}/layout/views` },
-      { label: 'WIDGETS', href: `${DOCS_BASE_URL}/layout/page-layouts` },
-      {
-        label: 'LAYOUT PAGES',
-        href: `${DOCS_BASE_URL}/layout/page-layouts`,
-      },
-      {
-        label: 'COMMANDS',
-        href: `${DOCS_BASE_URL}/layout/command-menu-items`,
-      },
-    ],
-    rotation: '-2.8deg',
-  },
-] as const;
-
-const ArrowUpRight = ({ color = '#999' }: { color?: string }) => (
-  <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
-    <path
-      d="M4.5 3.5H10.5V9.5M10.5 3.5L3.5 10.5"
-      stroke={color}
-      strokeWidth="1.2"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    />
-  </svg>
-);
-
-const CategoryCard = ({
-  title,
-  color,
-  items,
-  rotation,
-}: {
-  title: string;
-  color: string;
-  items: ReadonlyArray<{ label: string; href: string }>;
-  rotation: string;
-}) => {
-  const [hoveredItem, setHoveredItem] = useState<string | null>(null);
-
-  const CategoryIcon = () => {
-    if (title === 'Data model') {
-      return <IconHierarchy color={color} size={'20px'} />;
-    }
-    if (title === 'Logic') {
-      return <IconSettingsAutomation color={color} size={'20px'} />;
-    }
-    if (title === 'Layout') {
-      return <IconLayout color={color} size={'20px'} />;
-    }
-  };
-
-  return (
-    <div
-      style={{
-        display: 'flex',
-        flexDirection: 'column',
-        border: `1px solid ${color}80`,
-        borderRadius: '12px',
-        overflow: 'hidden',
-        width: '240px',
-        background: '#FFFFFF',
-        transform: `rotate(${rotation})`,
-        boxShadow: '0 2px 8px rgba(0, 0, 0, 0.04)',
-      }}
-    >
-      <div
-        style={{
-          padding: '16px 20px',
-          background: `${color}22`,
-          display: 'flex',
-          alignItems: 'center',
-          gap: '12px',
-        }}
-      >
-        <CategoryIcon />
-        <span
-          style={{
-            fontSize: '16px',
-            fontWeight: 600,
-            color: color,
-          }}
-        >
-          {title}
-        </span>
-      </div>
-      <div
-        style={{
-          display: 'flex',
-          flexDirection: 'column',
-          padding: '8px',
-          gap: '4px',
-        }}
-      >
-        {items.map((item) => {
-          const isHovered = hoveredItem === item.label;
-
-          return (
-            <a
-              key={item.label}
-              href={item.href}
-              target="_blank"
-              rel="noopener noreferrer"
-              onMouseEnter={() => setHoveredItem(item.label)}
-              onMouseLeave={() => setHoveredItem(null)}
-              style={{
-                display: 'flex',
-                alignItems: 'center',
-                gap: '10px',
-                textDecoration: 'none',
-                cursor: 'pointer',
-                padding: '10px 12px',
-                borderRadius: '8px',
-                background: isHovered ? '#0000000A' : 'transparent',
-                transition: 'background 0.15s',
-              }}
-            >
-              <IconBox color={color} size={'20px'} />
-              <span
-                style={{
-                  fontSize: '13px',
-                  fontWeight: 300,
-                  color: '#333',
-                  letterSpacing: '0.5px',
-                  flex: 1,
-                }}
-              >
-                {item.label}
-              </span>
-              {isHovered && <ArrowUpRight />}
-            </a>
-          );
-        })}
-      </div>
-    </div>
-  );
-};
-
-const MainPage = () => {
-  return (
-    <div
-      style={{
-        display: 'flex',
-        flexDirection: 'column',
-        alignItems: 'center',
-        justifyContent: 'center',
-        height: '100%',
-        fontFamily:
-          'Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
-        gap: '8px',
-        padding: '40px',
-      }}
-    >
-      <Avatar
-        placeholder={APP_DISPLAY_NAME}
-        placeholderColorSeed={APP_DISPLAY_NAME}
-        size="xl"
-      />
-      <span
-        style={{
-          fontSize: '24px',
-          fontWeight: 600,
-          color: '#333',
-          marginTop: '8px',
-        }}
-      >
-        {APP_DISPLAY_NAME}
-      </span>
-      <span
-        style={{
-          fontSize: '13px',
-          color: '#888',
-          textAlign: 'center',
-          lineHeight: '1.5',
-        }}
-      >
-        Was installed successfully.
-        <br />
-        You can now add content to your app.
-      </span>
-      <a
-        href="/settings/applications#installed"
-        style={{
-          display: 'inline-flex',
-          alignItems: 'center',
-          gap: '6px',
-          marginTop: '16px',
-          fontSize: '13px',
-          color: '#333',
-          textDecoration: 'none',
-          padding: '8px 16px',
-          borderRadius: '8px',
-          border: '1px solid #e0e0e0',
-          background: '#fafafa',
-          transition: 'background 0.15s, border-color 0.15s',
-        }}
-        onMouseEnter={(e) => {
-          e.currentTarget.style.background = '#f0f0f0';
-          e.currentTarget.style.borderColor = '#ccc';
-        }}
-        onMouseLeave={(e) => {
-          e.currentTarget.style.background = '#fafafa';
-          e.currentTarget.style.borderColor = '#e0e0e0';
-        }}
-      >
-        Open app settings
-        <ArrowUpRight color="#333" />
-      </a>
-      <div
-        style={{
-          display: 'flex',
-          gap: '16px',
-          marginTop: '32px',
-          flexWrap: 'wrap',
-          justifyContent: 'center',
-          alignItems: 'flex-start',
-        }}
-      >
-        {CATEGORIES.map((category) => (
-          <CategoryCard
-            key={category.title}
-            title={category.title}
-            color={category.color}
-            items={category.items}
-            rotation={category.rotation}
-          />
-        ))}
-      </div>
-    </div>
-  );
-};
-
-export default defineFrontComponent({
-  universalIdentifier: MAIN_PAGE_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
-  name: APP_DISPLAY_NAME,
-  description: `${APP_DISPLAY_NAME} front component displaying the app logo and name`,
-  component: MainPage,
-});

packages/create-twenty-app/src/constants/template/src/navigation-menu-items/main-page.navigation-menu-item.ts

@@ -1,19 +0,0 @@
-import {
-  defineNavigationMenuItem,
-  NavigationMenuItemType,
-} from 'twenty-sdk/define';
-
-import {
-  APP_DISPLAY_NAME,
-  MAIN_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
-  MAIN_PAGE_NAVIGATION_MENU_ITEM_UNIVERSAL_IDENTIFIER,
-} from 'src/constants/universal-identifiers';
-
-export default defineNavigationMenuItem({
-  universalIdentifier: MAIN_PAGE_NAVIGATION_MENU_ITEM_UNIVERSAL_IDENTIFIER,
-  name: APP_DISPLAY_NAME,
-  icon: 'IconFile',
-  position: -1,
-  type: NavigationMenuItemType.PAGE_LAYOUT,
-  pageLayoutUniversalIdentifier: MAIN_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
-});

packages/create-twenty-app/src/constants/template/src/page-layouts/main-page.page-layout.ts

@@ -1,37 +0,0 @@
-import { definePageLayout, PageLayoutTabLayoutMode } from 'twenty-sdk/define';
-
-import {
-  APP_DISPLAY_NAME,
-  MAIN_PAGE_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
-  MAIN_PAGE_LAYOUT_TAB_UNIVERSAL_IDENTIFIER,
-  MAIN_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
-  MAIN_PAGE_WIDGET_UNIVERSAL_IDENTIFIER,
-} from 'src/constants/universal-identifiers';
-
-export default definePageLayout({
-  universalIdentifier: MAIN_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
-  name: APP_DISPLAY_NAME,
-  type: 'STANDALONE_PAGE',
-  tabs: [
-    {
-      universalIdentifier: MAIN_PAGE_LAYOUT_TAB_UNIVERSAL_IDENTIFIER,
-      title: 'Overview',
-      position: 0,
-      icon: 'IconApps',
-      layoutMode: PageLayoutTabLayoutMode.CANVAS,
-      widgets: [
-        {
-          universalIdentifier: MAIN_PAGE_WIDGET_UNIVERSAL_IDENTIFIER,
-          title: ' ',
-          type: 'FRONT_COMPONENT',
-          gridPosition: { row: 0, column: 0, rowSpan: 12, columnSpan: 12 },
-          configuration: {
-            configurationType: 'FRONT_COMPONENT',
-            frontComponentUniversalIdentifier:
-              MAIN_PAGE_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
-          },
-        },
-      ],
-    },
-  ],
-});

packages/create-twenty-app/src/constants/template/tsconfig.json

@@ -1,42 +0,0 @@
-{
-  "compileOnSave": false,
-  "compilerOptions": {
-    "sourceMap": true,
-    "declaration": true,
-    "outDir": "./dist",
-    "rootDir": ".",
-    "jsx": "react-jsx",
-    "moduleResolution": "node",
-    "allowSyntheticDefaultImports": true,
-    "emitDecoratorMetadata": true,
-    "experimentalDecorators": true,
-    "importHelpers": true,
-    "allowUnreachableCode": false,
-    "strict": true,
-    "alwaysStrict": true,
-    "noImplicitAny": true,
-    "strictBindCallApply": false,
-    "target": "es2018",
-    "module": "esnext",
-    "lib": ["es2020", "dom"],
-    "skipLibCheck": true,
-    "skipDefaultLibCheck": true,
-    "resolveJsonModule": true,
-    "paths": {
-      "src/*": ["./src/*"],
-      "~/*": ["./*"]
-    }
-  },
-  "exclude": [
-    "node_modules",
-    "dist",
-    "**/*.test.ts",
-    "**/*.spec.ts",
-    "**/*.integration-test.ts"
-  ],
-  "references": [
-    {
-      "path": "./tsconfig.spec.json"
-    }
-  ]
-}

packages/create-twenty-app/src/constants/template/tsconfig.spec.json

@@ -1,9 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "composite": true,
-    "types": ["vitest/globals", "node"]
-  },
-  "include": ["src/**/*.ts", "src/**/*.tsx"],
-  "exclude": ["node_modules", "dist"]
-}

packages/create-twenty-app/src/constants/template/vitest.config.ts

@@ -1,31 +0,0 @@
-import tsconfigPaths from 'vite-tsconfig-paths';
-import { defineConfig } from 'vitest/config';
-
-const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020';
-const TWENTY_API_KEY =
-  process.env.TWENTY_API_KEY ??
-  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC0xYzI1LTRkMDItYmYyNS02YWVjY2Y3ZWE0MTkiLCJ0eXBlIjoiQVBJX0tFWSIsIndvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWMyNS00ZDAyLWJmMjUtNmFlY2NmN2VhNDE5IiwiaWF0IjoxNzM1Njg5NjAwLCJleHAiOjQ4OTE0NDk2MDAsImp0aSI6IjIwMjAyMDIwLWY0MDEtNGQ4YS1hNzMxLTY0ZDAwN2MyN2JhZCJ9.bfQjfyN0NEtTCLE_xPyNcwonDzlSXFoP8kdCQTdnuDc';
-
-// Make env vars available to globalSetup (test.env only applies to workers)
-process.env.TWENTY_API_URL = TWENTY_API_URL;
-process.env.TWENTY_API_KEY = TWENTY_API_KEY;
-
-export default defineConfig({
-  plugins: [
-    tsconfigPaths({
-      projects: ['tsconfig.spec.json'],
-      ignoreConfigErrors: true,
-    }),
-  ],
-  test: {
-    testTimeout: 120_000,
-    hookTimeout: 120_000,
-    fileParallelism: false,
-    include: ['src/**/*.integration-test.ts'],
-    globalSetup: ['src/__tests__/global-setup.ts'],
-    env: {
-      TWENTY_API_URL,
-      TWENTY_API_KEY,
-    },
-  },
-});

packages/create-twenty-app/src/constants/template/yarn.lock

@@ -1,2 +0,0 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
-# yarn lockfile v1

packages/create-twenty-app/src/create-app.command.ts

@@ -4,169 +4,82 @@ import { install } from '@/utils/install';
 import { tryGitInit } from '@/utils/try-git-init';
 import chalk from 'chalk';
 import * as fs from 'fs-extra';
+import inquirer from 'inquirer';
 import kebabCase from 'lodash.kebabcase';
 import * as path from 'path';
 import { basename } from 'path';
-import { spawn } from 'node:child_process';
 import {
-  authLogin,
   authLoginOAuth,
-  checkDockerRunning,
-  ConfigService,
-  DEV_API_KEY,
-  DEV_API_URL,
+  detectLocalServer,
   serverStart,
+  type ServerStartResult,
 } from 'twenty-sdk/cli';
-import { isDefined, normalizeUrl } from 'twenty-shared/utils';
+import { isDefined } from 'twenty-shared/utils';
+
 import {
-  getDockerInstallInstructions,
-  isDockerInstalled,
-} from '@/utils/docker-install';
+  type ExampleOptions,
+  type ScaffoldingMode,
+} from '@/types/scaffolding-options';
 
 const CURRENT_EXECUTION_DIRECTORY = process.env.INIT_CWD || process.cwd();
-const IMAGE = 'twentycrm/twenty-app-dev:latest';
-
-export type AuthenticationMethod = 'oauth' | 'apiKey';
 
 type CreateAppOptions = {
   directory?: string;
+  mode?: ScaffoldingMode;
   name?: string;
   displayName?: string;
   description?: string;
-  serverUrl?: string;
-  authenticationMethod?: AuthenticationMethod;
+  skipLocalInstance?: boolean;
 };
 
 export class CreateAppCommand {
-  private stepCounter = 0;
-  private totalSteps = 0;
-
   async execute(options: CreateAppOptions = {}): Promise<void> {
     const { appName, appDisplayName, appDirectory, appDescription } =
-      this.getAppInfos(options);
-
-    const serverUrl = options.serverUrl ?? DEV_API_URL;
-
-    const skipLocalInstance = serverUrl !== DEV_API_URL;
-
-    if (!skipLocalInstance && !isDockerInstalled()) {
-      console.log(chalk.yellow('\n' + getDockerInstallInstructions() + '\n'));
-      process.exit(1);
-    }
-
-    if (skipLocalInstance && options.authenticationMethod === 'apiKey') {
-      console.log(
-        chalk.yellow(
-          'API key authentication is only supported on a local Docker instance. Ignoring and switching to OAuth authentication.',
-        ),
-      );
-    }
-
-    const authenticationMethod = skipLocalInstance
-      ? 'oauth'
-      : (options.authenticationMethod ?? 'apiKey');
+      await this.getAppInfos(options);
 
     try {
+      const exampleOptions = this.resolveExampleOptions(
+        options.mode ?? 'exhaustive',
+      );
+
       await this.validateDirectory(appDirectory);
 
-      this.totalSteps = this.computeTotalSteps({
-        skipLocalInstance,
-      });
-
-      this.stepCounter = 0;
-
-      const dockerPullPromise =
-        !skipLocalInstance && checkDockerRunning()
-          ? this.pullImageInBackground()
-          : Promise.resolve(false);
-
-      this.logPlan({ appName, appDisplayName, appDescription, appDirectory });
-
-      this.logNextStep('Creating project directory');
+      this.logCreationInfo({ appDirectory, appName });
 
       await fs.ensureDir(appDirectory);
 
-      this.logDetail(appDirectory);
-
-      this.logNextStep('Scaffolding project files');
-
       await copyBaseApplicationProject({
         appName,
         appDisplayName,
         appDescription,
         appDirectory,
-        onProgress: (message) => this.logDetail(message),
+        exampleOptions,
       });
 
-      this.logNextStep('Installing dependencies');
+      await install(appDirectory);
 
-      await install(appDirectory, (message) => this.logDetail(message));
+      await tryGitInit(appDirectory);
 
-      this.logNextStep('Initializing Git repository');
+      let serverResult: ServerStartResult | undefined;
 
-      const gitInitialized = await tryGitInit(appDirectory);
+      if (!options.skipLocalInstance) {
+        const shouldStartServer = await this.shouldStartServer();
 
-      if (gitInitialized) {
-        this.logDetail('Initialized on branch main');
-        this.logDetail('Created initial commit');
-      } else {
-        this.logDetail(
-          'Skipped (Git unavailable, initialization failed, or already in a repository)',
-        );
-      }
+        if (shouldStartServer) {
+          const startResult = await serverStart({
+            onProgress: (message: string) => console.log(chalk.gray(message)),
+          });
 
-      console.log('');
-
-      let authSucceeded = false;
-      let resolvedServerUrl = serverUrl;
-      let serverReady = skipLocalInstance;
-
-      if (!skipLocalInstance) {
-        this.logNextStep('Starting Twenty server');
-        const serverResult = await this.ensureDockerServer(dockerPullPromise);
-
-        if (isDefined(serverResult.url)) {
-          resolvedServerUrl = serverResult.url;
-          serverReady = true;
+          if (startResult.success) {
+            serverResult = startResult.data;
+            await this.promptConnectToLocal(serverResult.url);
+          } else {
+            console.log(chalk.yellow(`\n${startResult.error.message}`));
+          }
         }
       }
 
-      if (serverReady) {
-        this.logNextStep('Authenticating');
-
-        authSucceeded = await this.tryExistingAuth(resolvedServerUrl);
-
-        if (authSucceeded) {
-          this.logDetail('Reusing existing credentials');
-        } else if (authenticationMethod === 'oauth') {
-          this.logDetail('Starting OAuth flow');
-          authSucceeded = await this.authenticateWithOAuth(resolvedServerUrl);
-        } else {
-          this.logDetail('Using development API key');
-          authSucceeded = await this.authenticateWithDevKey(resolvedServerUrl);
-        }
-      }
-
-      this.logNextStep('Installing application');
-
-      let syncSucceeded = false;
-
-      if (serverReady && authSucceeded) {
-        syncSucceeded = await this.syncApplication(appDirectory);
-
-        if (!syncSucceeded) {
-          this.logDetail('Sync failed. Run `yarn twenty dev --once` manually.');
-          return;
-        }
-      } else {
-        this.logDetail('Skipped (server or authentication not available)');
-      }
-
-      if (syncSucceeded) {
-        await this.openMainPage(appDirectory, resolvedServerUrl);
-      }
-
-      this.logSuccess(appDirectory, resolvedServerUrl, authSucceeded);
+      this.logSuccess(appDirectory, serverResult);
     } catch (error) {
       console.error(
         chalk.red('\nCreate application failed:'),
@@ -176,47 +89,97 @@ export class CreateAppCommand {
     }
   }
 
-  private computeTotalSteps({
-    skipLocalInstance,
-  }: {
-    skipLocalInstance: boolean;
-  }): number {
-    let steps = 4; // directory, scaffold, install, git
-
-    if (!skipLocalInstance) {
-      steps += 1; // start server
-    }
-
-    steps += 1; // authenticate (oauth or apiKey)
-    steps += 1; // sync application
-
-    return steps;
-  }
-
-  private getAppInfos(options: CreateAppOptions): {
+  private async getAppInfos(options: CreateAppOptions): Promise<{
     appName: string;
     appDisplayName: string;
     appDescription: string;
     appDirectory: string;
-  } {
+  }> {
+    const { directory } = options;
+
+    const hasName = isDefined(options.name) || isDefined(directory);
+    const hasDisplayName = isDefined(options.displayName);
+    const hasDescription = isDefined(options.description);
+
+    const { name, displayName, description } = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'name',
+        message: 'Application name:',
+        when: () => !hasName,
+        default: 'my-twenty-app',
+        validate: (input) => {
+          if (input.length === 0) return 'Application name is required';
+          return true;
+        },
+      },
+      {
+        type: 'input',
+        name: 'displayName',
+        message: 'Application display name:',
+        when: () => !hasDisplayName,
+        default: (answers: { name?: string }) => {
+          return convertToLabel(
+            answers?.name ?? options.name ?? directory ?? '',
+          );
+        },
+      },
+      {
+        type: 'input',
+        name: 'description',
+        message: 'Application description (optional):',
+        when: () => !hasDescription,
+        default: '',
+      },
+    ]);
+
     const appName = (
       options.name ??
-      options.directory ??
+      name ??
+      directory ??
       'my-twenty-app'
     ).trim();
 
     const appDisplayName =
-      options.displayName?.trim() || convertToLabel(appName);
+      (options.displayName ?? displayName)?.trim() || convertToLabel(appName);
 
-    const appDescription = (options.description ?? '').trim();
+    const appDescription = (options.description ?? description ?? '').trim();
 
-    const appDirectory = options.directory
-      ? path.join(CURRENT_EXECUTION_DIRECTORY, options.directory)
+    const appDirectory = directory
+      ? path.join(CURRENT_EXECUTION_DIRECTORY, directory)
       : path.join(CURRENT_EXECUTION_DIRECTORY, kebabCase(appName));
 
     return { appName, appDisplayName, appDirectory, appDescription };
   }
 
+  private resolveExampleOptions(mode: ScaffoldingMode): ExampleOptions {
+    if (mode === 'minimal') {
+      return {
+        includeExampleObject: false,
+        includeExampleField: false,
+        includeExampleLogicFunction: false,
+        includeExampleFrontComponent: false,
+        includeExampleView: false,
+        includeExampleNavigationMenuItem: false,
+        includeExampleSkill: false,
+        includeExampleAgent: false,
+        includeExampleIntegrationTest: false,
+      };
+    }
+
+    return {
+      includeExampleObject: true,
+      includeExampleField: true,
+      includeExampleLogicFunction: true,
+      includeExampleFrontComponent: true,
+      includeExampleView: true,
+      includeExampleNavigationMenuItem: true,
+      includeExampleSkill: true,
+      includeExampleIntegrationTest: true,
+      includeExampleAgent: true,
+    };
+  }
+
   private async validateDirectory(appDirectory: string): Promise<void> {
     if (!(await fs.pathExists(appDirectory))) {
       return;
@@ -230,446 +193,100 @@ export class CreateAppCommand {
     }
   }
 
-  private logPlan({
-    appName,
-    appDisplayName,
-    appDescription,
+  private logCreationInfo({
     appDirectory,
+    appName,
   }: {
-    appName: string;
-    appDisplayName: string;
-    appDescription: string;
     appDirectory: string;
+    appName: string;
   }): void {
-    console.log(chalk.blue('\nCreating Twenty Application\n'));
-    console.log(chalk.white(`  Name:           ${appName}`));
-    console.log(chalk.white(`  Display name:   ${appDisplayName}`));
-
-    if (appDescription) {
-      console.log(chalk.white(`  Description:    ${appDescription}`));
-    }
-
-    console.log(chalk.white(`  Directory:      ${appDirectory}`));
-    console.log('');
-  }
-
-  private logNextStep(title: string): void {
-    this.stepCounter++;
     console.log(
-      chalk.blue(`\n[${this.stepCounter}/${this.totalSteps}]`) +
-        chalk.white(` ${title}...`),
+      chalk.blue('\n', 'Creating Twenty Application\n'),
+      chalk.gray(`- Directory: ${appDirectory}\n`, `- Name: ${appName}\n`),
     );
   }
 
-  private logDetail(message: string): void {
-    console.log(chalk.gray(`      → ${message}`));
+  private async shouldStartServer(): Promise<boolean> {
+    const existingServerUrl = await detectLocalServer();
+
+    if (existingServerUrl) {
+      return true;
+    }
+
+    const { startDocker } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'startDocker',
+        message:
+          'No running Twenty instance found. Would you like to start one using Docker?',
+        default: true,
+      },
+    ]);
+
+    return startDocker;
   }
 
-  private pullImageInBackground(): Promise<boolean> {
-    return new Promise((resolve) => {
-      const child = spawn('docker', ['pull', IMAGE], { stdio: 'ignore' });
+  private async promptConnectToLocal(serverUrl: string): Promise<void> {
+    const { shouldAuthenticate } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'shouldAuthenticate',
+        message: `Would you like to authenticate to the local Twenty instance (${serverUrl})?`,
+        default: true,
+      },
+    ]);
 
-      child.on('close', (code) => resolve(code === 0));
-      child.on('error', () => resolve(false));
-    });
-  }
-
-  private async ensureDockerServer(
-    dockerPullPromise: Promise<boolean>,
-  ): Promise<{ url?: string }> {
-    if (!checkDockerRunning()) {
+    if (!shouldAuthenticate) {
       console.log(
-        chalk.yellow(
-          '\n  Docker is installed but not running.\n' +
-            '  Please start Docker and run this command again.\n',
+        chalk.gray(
+          'Authentication skipped. Run `yarn twenty remote add` manually.',
         ),
       );
 
-      return {};
-    }
-
-    this.logDetail('Ensuring latest Twenty server image...');
-
-    const pullSucceeded = await dockerPullPromise;
-
-    if (!pullSucceeded) {
-      this.logDetail(
-        'Image pull failed, continuing with cached image if available...',
-      );
-    }
-
-    const startResult = await serverStart({
-      onProgress: (message: string) => this.logDetail(message),
-    });
-
-    if (startResult.success) {
-      return { url: startResult.data.url };
-    }
-
-    console.log(chalk.yellow(`\n  ${startResult.error.message}`));
-
-    return {};
-  }
-
-  private async openMainPage(
-    appDirectory: string,
-    serverUrl: string,
-  ): Promise<void> {
-    try {
-      const configService = new ConfigService();
-      const config = await configService.getConfig();
-      const token = config.twentyCLIAccessToken ?? config.apiKey;
-
-      if (!token) {
-        return;
-      }
-
-      const [universalIdentifier, frontUrl] = await Promise.all([
-        this.readMainPageLayoutUniversalIdentifier(appDirectory),
-        this.resolveWorkspaceFrontUrl(serverUrl, token),
-      ]);
-
-      if (!universalIdentifier || !frontUrl) {
-        return;
-      }
-
-      const pageLayoutId = await this.resolvePageLayoutId(
-        serverUrl,
-        universalIdentifier,
-        token,
-      );
-
-      if (!pageLayoutId) {
-        return;
-      }
-
-      const url = `${frontUrl}/page/${pageLayoutId}`;
-
-      this.logDetail(`Opening app welcome page: ${url}`);
-      this.openInBrowser(url);
-    } catch {
-      // Best-effort — don't fail the scaffold if browser open fails
-    }
-  }
-
-  private async resolveWorkspaceFrontUrl(
-    serverUrl: string,
-    token: string,
-  ): Promise<string | null> {
-    const query = `{ currentWorkspace { workspaceUrls { subdomainUrl customUrl } } }`;
-
-    const response = await fetch(`${serverUrl}/metadata`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${token}`,
-      },
-      body: JSON.stringify({ query }),
-    });
-
-    if (!response.ok) {
-      return null;
-    }
-
-    const body = (await response.json()) as {
-      data?: {
-        currentWorkspace?: {
-          workspaceUrls?: { subdomainUrl?: string; customUrl?: string };
-        };
-      };
-    };
-
-    const urls = body.data?.currentWorkspace?.workspaceUrls;
-
-    if (!urls) {
-      return null;
-    }
-
-    const frontUrl = urls.customUrl ?? urls.subdomainUrl;
-
-    return frontUrl ? normalizeUrl(frontUrl) : null;
-  }
-
-  private async readMainPageLayoutUniversalIdentifier(
-    appDirectory: string,
-  ): Promise<string | null> {
-    const filePath = path.join(
-      appDirectory,
-      'src',
-      'constants',
-      'universal-identifiers.ts',
-    );
-    const content = await fs.readFile(filePath, 'utf-8');
-    const match = content.match(
-      /MAIN_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER\s*=\s*'([^']+)'/,
-    );
-
-    return match?.[1] ?? null;
-  }
-
-  private async resolvePageLayoutId(
-    serverUrl: string,
-    universalIdentifier: string,
-    token: string,
-  ): Promise<string | null> {
-    const query = `{ getPageLayouts { id universalIdentifier } }`;
-
-    const response = await fetch(`${serverUrl}/metadata`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${token}`,
-      },
-      body: JSON.stringify({ query }),
-    });
-
-    if (!response.ok) {
-      return null;
-    }
-
-    const body = (await response.json()) as {
-      data?: {
-        getPageLayouts?: { id: string; universalIdentifier: string }[];
-      };
-    };
-
-    const matching = body.data?.getPageLayouts?.find(
-      (layout) => layout.universalIdentifier === universalIdentifier,
-    );
-
-    return matching?.id ?? null;
-  }
-
-  private sanitizeBrowserUrl(url: string): string | null {
-    if (/[^\u0020-\u007E]/.test(url)) {
-      return null;
-    }
-
-    try {
-      const parsed = new URL(url);
-
-      if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
-        return null;
-      }
-
-      return parsed.toString();
-    } catch {
-      return null;
-    }
-  }
-
-  private openInBrowser(url: string): void {
-    const safeUrl = this.sanitizeBrowserUrl(url);
-
-    if (!safeUrl) {
       return;
     }
 
-    const isWindows = process.platform === 'win32';
-    const command = isWindows
-      ? 'rundll32'
-      : process.platform === 'darwin'
-        ? 'open'
-        : 'xdg-open';
-    const args = isWindows
-      ? ['url.dll,FileProtocolHandler', safeUrl]
-      : [safeUrl];
-
-    const child = spawn(command, args, {
-      stdio: 'ignore',
-      detached: !isWindows,
-    });
-    child.on('error', () => undefined);
-    if (!isWindows) {
-      child.unref();
-    }
-  }
-
-  private async syncApplication(appDirectory: string): Promise<boolean> {
-    this.logDetail('Running `yarn twenty dev --once`...');
-    return new Promise((resolve) => {
-      const child = spawn('yarn', ['twenty', 'dev', '--once'], {
-        cwd: appDirectory,
-        stdio: ['inherit', 'pipe', 'pipe'],
-      });
-
-      child.stdout?.resume();
-      child.stderr?.resume();
-
-      child.on('close', (code) => resolve(code === 0));
-      child.on('error', () => resolve(false));
-    });
-  }
-
-  private async tryExistingAuth(serverUrl: string): Promise<boolean> {
     try {
-      const configService = new ConfigService();
-      const remoteNames = await configService.getRemotes();
-
-      for (const remoteName of remoteNames) {
-        const remoteConfig = await configService.getConfigForRemote(remoteName);
-
-        if (remoteConfig.apiUrl !== serverUrl) {
-          continue;
-        }
-
-        const token = remoteConfig.twentyCLIAccessToken ?? remoteConfig.apiKey;
-
-        if (!token) {
-          continue;
-        }
-
-        const response = await fetch(`${serverUrl}/metadata`, {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${token}`,
-          },
-          body: JSON.stringify({
-            query: '{ currentWorkspace { id } }',
-          }),
-        });
-
-        if (!response.ok) {
-          continue;
-        }
-
-        const body = (await response.json()) as {
-          data?: { currentWorkspace?: { id: string } };
-          errors?: unknown[];
-        };
-
-        if (isDefined(body.data?.currentWorkspace) && !body.errors) {
-          ConfigService.setActiveRemote(remoteName);
-          await configService.setDefaultRemote(remoteName);
-
-          return true;
-        }
-      }
-
-      return false;
-    } catch {
-      return false;
-    }
-  }
-
-  private async authenticateWithDevKey(serverUrl: string): Promise<boolean> {
-    try {
-      const result = await authLogin({
-        apiKey: DEV_API_KEY,
+      const result = await authLoginOAuth({
         apiUrl: serverUrl,
         remote: 'local',
       });
 
-      if (result.success) {
-        const configService = new ConfigService();
-
-        await configService.setDefaultRemote('local');
-        this.logDetail('Authenticated as tim@apple.dev (development API key)');
-
-        return true;
+      if (!result.success) {
+        console.log(
+          chalk.yellow(
+            'Authentication failed. Run `yarn twenty remote add` manually.',
+          ),
+        );
       }
-
-      console.log(
-        chalk.yellow(
-          '  Authentication failed. Run `yarn twenty remote:add --local` manually.',
-        ),
-      );
-
-      return false;
     } catch {
       console.log(
         chalk.yellow(
-          '  Authentication failed. Run `yarn twenty remote:add --local` manually.',
+          'Authentication failed. Run `yarn twenty remote add` manually.',
         ),
       );
-
-      return false;
-    }
-  }
-
-  private deriveRemoteName(url: string): string {
-    try {
-      return new URL(url).hostname.replace(/\./g, '-');
-    } catch {
-      return 'remote';
-    }
-  }
-
-  private async authenticateWithOAuth(serverUrl: string): Promise<boolean> {
-    try {
-      const remoteName = this.deriveRemoteName(serverUrl);
-
-      ConfigService.setActiveRemote(remoteName);
-
-      this.logDetail('Opening browser for OAuth...');
-
-      const result = await authLoginOAuth({ apiUrl: serverUrl });
-
-      if (result.success) {
-        const configService = new ConfigService();
-
-        await configService.setDefaultRemote(remoteName);
-        this.logDetail(`Authenticated via OAuth to ${serverUrl}`);
-
-        return true;
-      }
-
-      console.log(
-        chalk.yellow(
-          `  OAuth failed: ${result.error.message}\n` +
-            `  Run \`yarn twenty remote:add --url ${serverUrl}\` manually.`,
-        ),
-      );
-
-      return false;
-    } catch {
-      console.log(
-        chalk.yellow(
-          `  Authentication failed. Run \`yarn twenty remote:add --url ${serverUrl}\` manually.`,
-        ),
-      );
-
-      return false;
     }
   }
 
   private logSuccess(
     appDirectory: string,
-    serverUrl: string,
-    authSucceeded: boolean,
+    serverResult?: ServerStartResult,
   ): void {
     const dirName = basename(appDirectory);
 
-    console.log(chalk.green('\n✔ Application created successfully!\n'));
+    console.log(chalk.blue('\nApplication created. Next steps:'));
+    console.log(chalk.gray(`- cd ${dirName}`));
 
-    console.log(chalk.white('  Next steps:\n'));
-
-    let stepNumber = 1;
-
-    console.log(chalk.white(`  ${stepNumber}. Navigate to your project`));
-    console.log(chalk.cyan(`     cd ${dirName}\n`));
-    stepNumber++;
-
-    if (!authSucceeded) {
-      console.log(chalk.white(`  ${stepNumber}. Connect to a Twenty instance`));
+    if (!serverResult) {
       console.log(
-        chalk.cyan('     yarn twenty remote:add --url <your-instance-url>\n'),
+        chalk.gray(
+          '- yarn twenty remote add          # Authenticate with Twenty',
+        ),
       );
-      stepNumber++;
     }
 
-    console.log(chalk.white(`  ${stepNumber}. Start developing`));
-    console.log(chalk.cyan('     yarn twenty dev\n'));
-    stepNumber++;
-
-    console.log(chalk.white(`  ${stepNumber}. Open your twenty instance`));
-    console.log(chalk.cyan(`     ${serverUrl}\n`));
-
     console.log(
-      chalk.gray(
-        '  Documentation: https://docs.twenty.com/developers/extend/capabilities/apps',
-      ),
+      chalk.gray('- yarn twenty dev                  # Start dev mode'),
     );
   }
 }

packages/create-twenty-app/src/types/scaffolding-options.ts

@@ -0,0 +1,13 @@
+export type ScaffoldingMode = 'exhaustive' | 'minimal';
+
+export type ExampleOptions = {
+  includeExampleObject: boolean;
+  includeExampleField: boolean;
+  includeExampleLogicFunction: boolean;
+  includeExampleFrontComponent: boolean;
+  includeExampleView: boolean;
+  includeExampleNavigationMenuItem: boolean;
+  includeExampleSkill: boolean;
+  includeExampleAgent: boolean;
+  includeExampleIntegrationTest: boolean;
+};

packages/create-twenty-app/src/utils/__tests__/test-template.spec.ts

@@ -0,0 +1,177 @@
+import { scaffoldIntegrationTest } from '@/utils/test-template';
+import * as fs from 'fs-extra';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+describe('scaffoldIntegrationTest', () => {
+  let testAppDirectory: string;
+  let sourceFolderPath: string;
+
+  beforeEach(async () => {
+    testAppDirectory = join(
+      tmpdir(),
+      `test-twenty-app-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    sourceFolderPath = join(testAppDirectory, 'src');
+    await fs.ensureDir(sourceFolderPath);
+
+    await fs.writeJson(join(testAppDirectory, 'tsconfig.json'), {
+      compilerOptions: {
+        paths: { 'src/*': ['./src/*'] },
+      },
+      exclude: ['node_modules', 'dist', '**/*.integration-test.ts'],
+    });
+  });
+
+  afterEach(async () => {
+    if (testAppDirectory && (await fs.pathExists(testAppDirectory))) {
+      await fs.remove(testAppDirectory);
+    }
+  });
+
+  describe('integration test file', () => {
+    it('should create app-install.integration-test.ts with correct structure', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const testPath = join(
+        sourceFolderPath,
+        '__tests__',
+        'app-install.integration-test.ts',
+      );
+
+      expect(await fs.pathExists(testPath)).toBe(true);
+
+      const content = await fs.readFile(testPath, 'utf8');
+
+      expect(content).toContain(
+        "import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli'",
+      );
+      expect(content).toContain(
+        "import { MetadataApiClient } from 'twenty-client-sdk/metadata'",
+      );
+      expect(content).toContain(
+        "import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config'",
+      );
+      expect(content).toContain('appBuild');
+      expect(content).toContain('appDeploy');
+      expect(content).toContain('appInstall');
+      expect(content).toContain('appUninstall');
+      expect(content).toContain('new MetadataApiClient()');
+      expect(content).toContain('findManyApplications');
+      expect(content).toContain('APPLICATION_UNIVERSAL_IDENTIFIER');
+    });
+  });
+
+  describe('setup-test file', () => {
+    it('should create setup-test.ts with SDK config bootstrap', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const setupTestPath = join(
+        sourceFolderPath,
+        '__tests__',
+        'setup-test.ts',
+      );
+
+      expect(await fs.pathExists(setupTestPath)).toBe(true);
+
+      const content = await fs.readFile(setupTestPath, 'utf8');
+
+      expect(content).toContain('.twenty-sdk-test');
+      expect(content).toContain('config.json');
+      expect(content).toContain('process.env.TWENTY_API_URL');
+      expect(content).toContain('process.env.TWENTY_API_KEY');
+      expect(content).toContain('assertServerIsReachable');
+    });
+  });
+
+  describe('vitest config', () => {
+    it('should create vitest.config.ts with env vars and setup file', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const vitestConfigPath = join(testAppDirectory, 'vitest.config.ts');
+
+      expect(await fs.pathExists(vitestConfigPath)).toBe(true);
+
+      const content = await fs.readFile(vitestConfigPath, 'utf8');
+
+      expect(content).toContain('TWENTY_API_KEY');
+      expect(content).not.toContain('TWENTY_TEST_API_KEY');
+      expect(content).toContain('setup-test.ts');
+      expect(content).toContain('tsconfig.spec.json');
+      expect(content).toContain('integration-test.ts');
+    });
+  });
+
+  describe('github workflow', () => {
+    it('should create .github/workflows/ci.yml with correct structure', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const workflowPath = join(
+        testAppDirectory,
+        '.github',
+        'workflows',
+        'ci.yml',
+      );
+
+      expect(await fs.pathExists(workflowPath)).toBe(true);
+
+      const content = await fs.readFile(workflowPath, 'utf8');
+
+      expect(content).toContain('name: CI');
+      expect(content).toContain('TWENTY_VERSION: latest');
+      expect(content).toContain('twenty-version: ${{ env.TWENTY_VERSION }}');
+      expect(content).toContain('actions/checkout@v4');
+      expect(content).toContain('spawn-twenty-docker-image@main');
+      expect(content).toContain('actions/setup-node@v4');
+      expect(content).toContain('yarn install --immutable');
+      expect(content).toContain('yarn test');
+      expect(content).toContain('TWENTY_API_URL');
+      expect(content).toContain('TWENTY_API_KEY');
+    });
+  });
+
+  describe('tsconfig.spec.json', () => {
+    it('should create tsconfig.spec.json extending the base tsconfig', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const tsconfigSpecPath = join(testAppDirectory, 'tsconfig.spec.json');
+
+      expect(await fs.pathExists(tsconfigSpecPath)).toBe(true);
+
+      const tsconfigSpec = await fs.readJson(tsconfigSpecPath);
+
+      expect(tsconfigSpec.extends).toBe('./tsconfig.json');
+      expect(tsconfigSpec.compilerOptions.composite).toBe(true);
+      expect(tsconfigSpec.include).toContain('src/**/*.ts');
+      expect(tsconfigSpec.exclude).not.toContain('**/*.integration-test.ts');
+    });
+
+    it('should add a reference to tsconfig.spec.json in tsconfig.json', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const tsconfig = await fs.readJson(
+        join(testAppDirectory, 'tsconfig.json'),
+      );
+
+      expect(tsconfig.references).toEqual([{ path: './tsconfig.spec.json' }]);
+    });
+  });
+});

packages/create-twenty-app/src/utils/app-template.ts

@@ -1,7 +1,10 @@
 import * as fs from 'fs-extra';
 import { join } from 'path';
+import { ASSETS_DIR } from 'twenty-shared/application';
 import { v4 } from 'uuid';
 
+import { type ExampleOptions } from '@/types/scaffolding-options';
+import { scaffoldIntegrationTest } from '@/utils/test-template';
 import createTwentyAppPackageJson from 'package.json';
 
 const SRC_FOLDER = 'src';
@@ -11,118 +14,795 @@ export const copyBaseApplicationProject = async ({
   appDisplayName,
   appDescription,
   appDirectory,
-  onProgress,
+  exampleOptions,
 }: {
   appName: string;
   appDisplayName: string;
   appDescription: string;
   appDirectory: string;
-  onProgress?: (message: string) => void;
+  exampleOptions: ExampleOptions;
 }) => {
-  onProgress?.('Copying base template');
-  await fs.copy(join(__dirname, './constants/template'), appDirectory);
+  await fs.copy(join(__dirname, './constants/base-application'), appDirectory);
 
-  onProgress?.('Configuring dotfiles (.gitignore, .github, .yarnrc.yml)');
-  await renameDotfiles({ appDirectory });
-
-  onProgress?.('Mirroring AGENTS.md to CLAUDE.md');
-  await mirrorAgentsToClaude({ appDirectory });
-
-  await addEmptyPublicDirectory({ appDirectory });
-
-  onProgress?.('Generating unique application identifiers');
-  await generateUniversalIdentifiers({
-    appDisplayName,
-    appDescription,
+  await createPackageJson({
+    appName,
     appDirectory,
+    includeExampleIntegrationTest: exampleOptions.includeExampleIntegrationTest,
   });
 
-  onProgress?.('Updating package.json');
-  await updatePackageJson({ appName, appDirectory });
-};
+  await createYarnLock(appDirectory);
 
-// npm strips dotfiles/dotdirs (.gitignore, .github/) from published packages,
-// so we store them without the leading dot and rename after copying.
-const renameDotfiles = async ({ appDirectory }: { appDirectory: string }) => {
-  const renames = [
-    { from: 'gitignore', to: '.gitignore' },
-    { from: 'github', to: '.github' },
-    { from: 'yarnrc.yml', to: '.yarnrc.yml' },
-  ];
+  await createGitignore(appDirectory);
 
-  for (const { from, to } of renames) {
-    const sourcePath = join(appDirectory, from);
+  await createNvmrc(appDirectory);
 
-    if (await fs.pathExists(sourcePath)) {
-      await fs.rename(sourcePath, join(appDirectory, to));
-    }
+  await createPublicAssetDirectory(appDirectory);
+
+  const sourceFolderPath = join(appDirectory, SRC_FOLDER);
+
+  await fs.ensureDir(sourceFolderPath);
+
+  await createDefaultRoleConfig({
+    displayName: appDisplayName,
+    appDirectory: sourceFolderPath,
+    fileFolder: 'roles',
+    fileName: 'default-role.ts',
+  });
+
+  if (exampleOptions.includeExampleObject) {
+    await createExampleObject({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'objects',
+      fileName: 'example-object.ts',
+    });
   }
+
+  if (exampleOptions.includeExampleField) {
+    await createExampleField({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'fields',
+      fileName: 'example-field.ts',
+    });
+  }
+
+  if (exampleOptions.includeExampleLogicFunction) {
+    await createDefaultFunction({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'logic-functions',
+      fileName: 'hello-world.ts',
+    });
+
+    await createCreateCompanyFunction({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'logic-functions',
+      fileName: 'create-hello-world-company.ts',
+    });
+  }
+
+  if (exampleOptions.includeExampleFrontComponent) {
+    await createDefaultFrontComponent({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'front-components',
+      fileName: 'hello-world.tsx',
+    });
+
+    await createExamplePageLayout({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'page-layouts',
+      fileName: 'example-record-page-layout.ts',
+    });
+  }
+
+  if (exampleOptions.includeExampleView) {
+    await createExampleView({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'views',
+      fileName: 'example-view.ts',
+    });
+  }
+
+  if (exampleOptions.includeExampleNavigationMenuItem) {
+    await createExampleNavigationMenuItem({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'navigation-menu-items',
+      fileName: 'example-navigation-menu-item.ts',
+    });
+  }
+
+  if (exampleOptions.includeExampleSkill) {
+    await createExampleSkill({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'skills',
+      fileName: 'example-skill.ts',
+    });
+  }
+
+  if (exampleOptions.includeExampleAgent) {
+    await createExampleAgent({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'agents',
+      fileName: 'example-agent.ts',
+    });
+  }
+
+  if (exampleOptions.includeExampleIntegrationTest) {
+    await scaffoldIntegrationTest({
+      appDirectory,
+      sourceFolderPath,
+    });
+  }
+
+  await createDefaultPreInstallFunction({
+    appDirectory: sourceFolderPath,
+    fileFolder: 'logic-functions',
+    fileName: 'pre-install.ts',
+  });
+
+  await createDefaultPostInstallFunction({
+    appDirectory: sourceFolderPath,
+    fileFolder: 'logic-functions',
+    fileName: 'post-install.ts',
+  });
+
+  await createApplicationConfig({
+    displayName: appDisplayName,
+    description: appDescription,
+    appDirectory: sourceFolderPath,
+    fileName: 'application-config.ts',
+  });
 };
 
-// AGENTS.md is the cross-tool standard; Claude Code prefers CLAUDE.md and only
-// falls back to AGENTS.md, so we mirror the file to keep a single source of truth.
-const mirrorAgentsToClaude = async ({
+const createPublicAssetDirectory = async (appDirectory: string) => {
+  await fs.ensureDir(join(appDirectory, ASSETS_DIR));
+};
+
+const createGitignore = async (appDirectory: string) => {
+  const gitignoreContent = `# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn
+
+# codegen
+generated
+
+# testing
+/coverage
+
+# dev
+/dist/
+
+.twenty
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# typescript
+*.tsbuildinfo
+*.d.ts
+`;
+
+  await fs.writeFile(join(appDirectory, '.gitignore'), gitignoreContent);
+};
+
+const createNvmrc = async (appDirectory: string) => {
+  await fs.writeFile(join(appDirectory, '.nvmrc'), '24.5.0\n');
+};
+
+const createDefaultRoleConfig = async ({
+  displayName,
   appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  displayName: string;
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { defineRole } from 'twenty-sdk';
+
+export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
+  '${universalIdentifier}';
+
+export default defineRole({
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  label: '${displayName} default function role',
+  description: '${displayName} default function role',
+  canReadAllObjectRecords: true,
+  canUpdateAllObjectRecords: true,
+  canSoftDeleteAllObjectRecords: true,
+  canDestroyAllObjectRecords: false,
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createDefaultFrontComponent = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
 }: {
   appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
 }) => {
-  await fs.copy(
-    join(appDirectory, 'AGENTS.md'),
-    join(appDirectory, 'CLAUDE.md'),
+  const universalIdentifier = v4();
+
+  const content = `import { useEffect, useState } from 'react';
+import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
+import { defineFrontComponent } from 'twenty-sdk';
+
+export const HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER =
+  '${universalIdentifier}';
+
+export const HelloWorld = () => {
+  const client = new CoreApiClient();
+  const [data, setData] = useState<
+    Pick<CoreSchema.Company, 'name' | 'id'> | undefined
+  >(undefined);
+
+  useEffect(() => {
+    const fetchData = async () => {
+      const response = await client.query({
+        company: {
+          name: true,
+          id: true,
+          __args: {
+            filter: {
+              position: {
+                eq: 1,
+              },
+            },
+          },
+        },
+      });
+
+      setData(response.company);
+    };
+
+    fetchData();
+  }, []);
+
+  return (
+    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
+      <h1>Hello, World!</h1>
+      <p>This is your first front component.</p>
+      {data ? (
+        <div>
+          <p>Company name: {data.name}</p>
+          <p>Company id: {data.id}</p>
+        </div>
+      ) : (
+        <p>Company not found</p>
+      )}
+    </div>
   );
 };
 
-const addEmptyPublicDirectory = async ({
+export default defineFrontComponent({
+  universalIdentifier: HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+  name: 'hello-world-front-component',
+  description: 'A sample front component',
+  component: HelloWorld,
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createExamplePageLayout = async ({
   appDirectory,
+  fileFolder,
+  fileName,
 }: {
   appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
 }) => {
-  await fs.ensureDir(join(appDirectory, 'public'));
+  const pageLayoutUniversalIdentifier = v4();
+  const tabUniversalIdentifier = v4();
+  const widgetUniversalIdentifier = v4();
+
+  const content = `import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from 'src/objects/example-object';
+import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from 'src/front-components/hello-world';
+import { definePageLayout, PageLayoutTabLayoutMode } from 'twenty-sdk';
+
+export default definePageLayout({
+  universalIdentifier: '${pageLayoutUniversalIdentifier}',
+  name: 'Example Record Page',
+  type: 'RECORD_PAGE',
+  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
+  tabs: [
+    {
+      universalIdentifier: '${tabUniversalIdentifier}',
+      title: 'Hello World',
+      position: 50,
+      icon: 'IconWorld',
+      layoutMode: PageLayoutTabLayoutMode.CANVAS,
+      widgets: [
+        {
+          universalIdentifier: '${widgetUniversalIdentifier}',
+          title: 'Hello World',
+          type: 'FRONT_COMPONENT',
+          configuration: {
+            configurationType: 'FRONT_COMPONENT',
+            frontComponentUniversalIdentifier:
+              HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+          },
+        },
+      ],
+    },
+  ],
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
 };
 
-const generateUniversalIdentifiers = async ({
-  appDisplayName,
-  appDescription,
+const createDefaultFunction = async ({
   appDirectory,
+  fileFolder,
+  fileName,
 }: {
-  appDisplayName: string;
-  appDescription: string;
   appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
 }) => {
-  const universalIdentifiersPath = join(
-    appDirectory,
-    SRC_FOLDER,
-    'constants',
-    'universal-identifiers.ts',
-  );
+  const universalIdentifier = v4();
 
-  const universalIdentifiersFileContent = await fs.readFile(
-    universalIdentifiersPath,
-    'utf-8',
-  );
+  const content = `import { defineLogicFunction } from 'twenty-sdk';
 
-  await fs.writeFile(
-    universalIdentifiersPath,
-    universalIdentifiersFileContent
-      .replace('DISPLAY-NAME-TO-BE-GENERATED', appDisplayName)
-      .replace('DESCRIPTION-TO-BE-GENERATED', appDescription)
-      .replace(/UUID-TO-BE-GENERATED/g, () => v4()),
-  );
+const handler = async (): Promise<{ message: string }> => {
+  return { message: 'Hello, World!' };
 };
 
-const updatePackageJson = async ({
+export default defineLogicFunction({
+  universalIdentifier: '${universalIdentifier}',
+  name: 'hello-world-logic-function',
+  description: 'A simple logic function',
+  timeoutSeconds: 5,
+  handler,
+  httpRouteTriggerSettings: {
+    path: '/hello-world-logic-function',
+    httpMethod: 'GET',
+    isAuthRequired: false,
+  },
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createCreateCompanyFunction = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { CoreApiClient } from 'twenty-client-sdk/core';
+import { defineLogicFunction } from 'twenty-sdk';
+
+const handler = async (): Promise<{ message: string }> => {
+  const client = new CoreApiClient();
+
+  const { createCompany } = await client.mutation({
+    createCompany: {
+      __args: {
+        data: {
+          name: 'Hello World',
+        },
+      },
+      id: true,
+      name: true,
+    },
+  });
+
+  if (!createCompany?.id || !createCompany?.name) {
+    throw new Error('Failed to create company: missing id or name in response');
+  }
+
+  return {
+    message: \`Created company "\${createCompany.name}" with id \${createCompany.id}\`,
+  };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: '${universalIdentifier}',
+  name: 'create-hello-world-company',
+  description: 'Creates a company called Hello World',
+  timeoutSeconds: 5,
+  handler,
+  httpRouteTriggerSettings: {
+    path: '/create-hello-world-company',
+    httpMethod: 'POST',
+    isAuthRequired: true,
+  },
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createDefaultPreInstallFunction = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { definePreInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+
+const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+  console.log('Pre install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePreInstallLogicFunction({
+  universalIdentifier: '${universalIdentifier}',
+  name: 'pre-install',
+  description: 'Runs before installation to prepare the application.',
+  timeoutSeconds: 300,
+  handler,
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createDefaultPostInstallFunction = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { definePostInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+
+const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+  console.log('Post install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePostInstallLogicFunction({
+  universalIdentifier: '${universalIdentifier}',
+  name: 'post-install',
+  description: 'Runs after installation to set up the application.',
+  timeoutSeconds: 300,
+  handler,
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createExampleObject = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const objectUniversalIdentifier = v4();
+  const nameFieldUniversalIdentifier = v4();
+
+  const content = `import { defineObject, FieldType } from 'twenty-sdk';
+
+export const EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER =
+  '${objectUniversalIdentifier}';
+
+export const NAME_FIELD_UNIVERSAL_IDENTIFIER =
+  '${nameFieldUniversalIdentifier}';
+
+export default defineObject({
+  universalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
+  nameSingular: 'exampleItem',
+  namePlural: 'exampleItems',
+  labelSingular: 'Example item',
+  labelPlural: 'Example items',
+  description: 'A sample custom object',
+  icon: 'IconBox',
+  labelIdentifierFieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
+  fields: [
+    {
+      universalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
+      type: FieldType.TEXT,
+      name: 'name',
+      label: 'Name',
+      description: 'Name of the example item',
+      icon: 'IconAbc',
+    },
+  ],
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createExampleField = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { defineField, FieldType } from 'twenty-sdk';
+import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from 'src/objects/example-object';
+
+export default defineField({
+  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
+  universalIdentifier: '${universalIdentifier}',
+  type: FieldType.NUMBER,
+  name: 'priority',
+  label: 'Priority',
+  description: 'Priority level for the example item (1-10)',
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createExampleView = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+  const viewFieldUniversalIdentifier = v4();
+
+  const content = `import { defineView, ViewKey } from 'twenty-sdk';
+import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER, NAME_FIELD_UNIVERSAL_IDENTIFIER } from 'src/objects/example-object';
+
+export const EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER = '${universalIdentifier}';
+
+export default defineView({
+  universalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
+  name: 'All example items',
+  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
+  icon: 'IconList',
+  key: ViewKey.INDEX,
+  position: 0,
+  fields: [
+    {
+      universalIdentifier: '${viewFieldUniversalIdentifier}',
+      fieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
+      position: 0,
+      isVisible: true,
+      size: 200,
+    },
+  ],
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createExampleNavigationMenuItem = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { defineNavigationMenuItem } from 'twenty-sdk';
+import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from 'src/views/example-view';
+
+export default defineNavigationMenuItem({
+  universalIdentifier: '${universalIdentifier}',
+  name: 'example-navigation-menu-item',
+  icon: 'IconList',
+  color: 'blue',
+  position: 0,
+  type: 'VIEW',
+  viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createExampleSkill = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { defineSkill } from 'twenty-sdk';
+
+export const EXAMPLE_SKILL_UNIVERSAL_IDENTIFIER =
+  '${universalIdentifier}';
+
+export default defineSkill({
+  universalIdentifier: EXAMPLE_SKILL_UNIVERSAL_IDENTIFIER,
+  name: 'example-skill',
+  label: 'Example Skill',
+  description: 'A sample skill for your application',
+  icon: 'IconBrain',
+  content: 'Add your skill instructions here. Skills provide context and capabilities to AI agents.',
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createExampleAgent = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { defineAgent } from 'twenty-sdk';
+
+export const EXAMPLE_AGENT_UNIVERSAL_IDENTIFIER =
+  '${universalIdentifier}';
+
+export default defineAgent({
+  universalIdentifier: EXAMPLE_AGENT_UNIVERSAL_IDENTIFIER,
+  name: 'example-agent',
+  label: 'Example Agent',
+  description: 'A sample AI agent for your application',
+  icon: 'IconRobot',
+  prompt: 'You are a helpful assistant. Help users with their questions and tasks.',
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createApplicationConfig = async ({
+  displayName,
+  description,
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  displayName: string;
+  description?: string;
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { defineApplication } from 'twenty-sdk';
+import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
+
+export const APPLICATION_UNIVERSAL_IDENTIFIER =
+  '${universalIdentifier}';
+
+export default defineApplication({
+  universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
+  displayName: '${displayName}',
+  description: '${description ?? ''}',
+  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createYarnLock = async (appDirectory: string) => {
+  const yarnLockContent = `# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+`;
+
+  await fs.writeFile(join(appDirectory, 'yarn.lock'), yarnLockContent);
+};
+
+const createPackageJson = async ({
   appName,
   appDirectory,
+  includeExampleIntegrationTest,
 }: {
   appName: string;
   appDirectory: string;
+  includeExampleIntegrationTest: boolean;
 }) => {
-  const packageJson = await fs.readJson(join(appDirectory, 'package.json'));
+  const scripts: Record<string, string> = {
+    twenty: 'twenty',
+    lint: 'oxlint -c .oxlintrc.json .',
+    'lint:fix': 'oxlint --fix -c .oxlintrc.json .',
+  };
 
-  packageJson.name = appName;
-  packageJson.dependencies['twenty-sdk'] = createTwentyAppPackageJson.version;
-  packageJson.dependencies['twenty-client-sdk'] =
-    createTwentyAppPackageJson.version;
+  const devDependencies: Record<string, string> = {
+    typescript: '^5.9.3',
+    '@types/node': '^24.7.2',
+    '@types/react': '^19.0.0',
+    react: '^19.0.0',
+    'react-dom': '^19.0.0',
+    oxlint: '^0.16.0',
+    'twenty-sdk': createTwentyAppPackageJson.version,
+    'twenty-client-sdk': createTwentyAppPackageJson.version,
+  };
+
+  if (includeExampleIntegrationTest) {
+    scripts.test = 'vitest run';
+    scripts['test:watch'] = 'vitest';
+    devDependencies.vitest = '^3.1.1';
+    devDependencies['vite-tsconfig-paths'] = '^4.2.1';
+  }
+
+  const packageJson = {
+    name: appName,
+    version: '0.1.0',
+    license: 'MIT',
+    engines: {
+      node: '^24.5.0',
+      npm: 'please-use-yarn',
+      yarn: '>=4.0.2',
+    },
+    keywords: ['twenty-app'],
+    packageManager: 'yarn@4.9.2',
+    scripts,
+    devDependencies,
+  };
 
   await fs.writeFile(
     join(appDirectory, 'package.json'),

packages/create-twenty-app/src/utils/docker-install.ts

@@ -1,33 +0,0 @@
-import { execSync } from 'node:child_process';
-
-const DOCKER_DOWNLOAD_URLS: Record<string, string> = {
-  darwin: 'https://docs.docker.com/desktop/setup/install/mac-install/',
-  win32: 'https://docs.docker.com/desktop/setup/install/windows-install/',
-  linux: 'https://docs.docker.com/engine/install/',
-};
-
-export const isDockerInstalled = (): boolean => {
-  try {
-    execSync('docker --version', { stdio: 'ignore' });
-
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-export const getDockerInstallInstructions = (): string => {
-  const url =
-    DOCKER_DOWNLOAD_URLS[process.platform] ?? DOCKER_DOWNLOAD_URLS.linux;
-
-  return [
-    '  Docker is required but not installed.',
-    '',
-    `  Install Docker: ${url}`,
-    '',
-    '  Then run this command again.',
-    '',
-    '  Alternatively, connect to an existing Twenty instance:',
-    '  npx create-twenty-app@latest my-twenty-app --url <your-instance-url>',
-  ].join('\n');
-};