fix: handle Redis session storage connection failure gracefully with retry logic

https://sonarly.com/issue/19636?type=bug

The session storage Redis client throws inside a `.catch()` callback on connection timeout, creating an unhandled promise rejection that crashes the Node.js process.

Fix: **Three changes in `session-storage.module-factory.ts`:**

1. **Added `reconnectStrategy` to the Redis client config** — on connection failure, the client will retry with exponential backoff (500ms, 1000ms, ... capped at 5000ms) instead of giving up immediately. This matches the resilience behavior of the `ioredis` client used elsewhere in the codebase (`RedisClientService` with `maxRetriesPerRequest: null`).

2. **Replaced `throw new Error(...)` inside `.catch()` with `logger.error()`** — the original pattern created an unhandled promise rejection (throwing inside `.catch()` produces a new rejected promise with no handler), which crashed the Node.js process. Now the error is logged properly without crashing the server.

3. **Added `redisClient.on('error', ...)` handler** — the node-redis v4 client emits `error` events on connection issues. Without a handler, these become unhandled error events. The handler logs errors at the appropriate level using NestJS Logger.

These changes allow the server to survive transient Redis connectivity issues during startup (e.g., pod restarts where Redis isn't immediately available) while providing clear log output for debugging.

.claude/settings.json

@@ -1,7 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(git stash:*)"
-    ]
-  }
-}

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

@@ -3,12 +3,13 @@ description: >
   Starts a full Twenty instance (server, worker, database, redis) using Docker
   Compose. The server is available at http://localhost:3000 for subsequent steps
   in the caller's job.
-  Pulls the specified semver image tag from Docker Hub.
+  Accepts "latest" (pulls the latest Docker Hub image, checks out main) or a
+  semver tag (e.g., v0.40.0).
   Designed to be consumed from external repositories (e.g., twenty-app).
 
 inputs:
   twenty-version:
-    description: 'Twenty Docker Hub image tag as semver (e.g., v0.40.0, v1.0.0).'
+    description: 'Twenty Docker Hub image tag — either "latest" or a semver tag (e.g., v0.40.0).'
     required: true
   twenty-repository:
     description: 'Twenty repository to checkout docker compose files from.'
@@ -30,12 +31,19 @@ outputs:
 runs:
   using: 'composite'
   steps:
-    - name: Validate version
+    - name: Resolve version
+      id: resolve
       shell: bash
       run: |
         VERSION="${{ inputs.twenty-version }}"
-        if ! echo "$VERSION" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
-          echo "::error::twenty-version must be a semver tag (e.g., v0.40.0). Got: '$VERSION'"
+        if [ "$VERSION" = "latest" ]; then
+          echo "docker-tag=latest" >> "$GITHUB_OUTPUT"
+          echo "git-ref=main" >> "$GITHUB_OUTPUT"
+        elif echo "$VERSION" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
+          echo "docker-tag=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "git-ref=$VERSION" >> "$GITHUB_OUTPUT"
+        else
+          echo "::error::twenty-version must be \"latest\" or a semver tag (e.g., v0.40.0). Got: '$VERSION'"
           exit 1
         fi
 
@@ -43,7 +51,7 @@ runs:
       uses: actions/checkout@v4
       with:
         repository: ${{ inputs.twenty-repository }}
-        ref: ${{ inputs.twenty-version }}
+        ref: ${{ steps.resolve.outputs.git-ref }}
         token: ${{ inputs.github-token }}
         sparse-checkout: |
           packages/twenty-docker
@@ -56,7 +64,7 @@ runs:
       run: |
         cp .env.example .env
         echo "" >> .env
-        echo "TAG=${{ inputs.twenty-version }}" >> .env
+        echo "TAG=${{ steps.resolve.outputs.docker-tag }}" >> .env
         echo "APP_SECRET=replace_me_with_a_random_string" >> .env
         echo "SERVER_URL=http://localhost:3000" >> .env
 

.github/verdaccio-config.yaml

@@ -10,6 +10,9 @@ packages:
   'twenty-sdk':
     access: $all
     publish: $all
+  'twenty-client-sdk':
+    access: $all
+    publish: $all
   'create-twenty-app':
     access: $all
     publish: $all

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

@@ -36,6 +36,9 @@ jobs:
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
           PGUSER_SUPERUSER: postgres
           PGPASSWORD_SUPERUSER: postgres
@@ -50,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"
@@ -143,7 +152,6 @@ jobs:
           set_env_var "CLICKHOUSE_PASSWORD" "clickhousePassword"
 
           npx nx run twenty-server:database:init:prod
-          npx nx run twenty-server:database:migrate:prod
 
       - name: Seed current branch database with test data
         run: |
@@ -296,7 +304,6 @@ jobs:
           set_env_var "CLICKHOUSE_PASSWORD" "clickhousePassword"
 
           npx nx run twenty-server:database:init:prod
-          npx nx run twenty-server:database:migrate:prod
 
       - name: Seed main branch database with test data
         run: |
@@ -395,6 +402,12 @@ jobs:
           # Clean up temp directory
           rm -rf /tmp/current-branch-files
 
+      - 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

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

@@ -21,10 +21,12 @@ jobs:
       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:
@@ -35,6 +37,9 @@ jobs:
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
           PGUSER_SUPERUSER: postgres
           PGPASSWORD_SUPERUSER: postgres
@@ -49,8 +54,13 @@ jobs:
           --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
@@ -64,12 +74,13 @@ jobs:
         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 twenty-sdk create-twenty-app --releaseVersion=$CI_VERSION
+          npx nx run-many -t set-local-version -p $PUBLISHABLE_PACKAGES --releaseVersion=$CI_VERSION
 
       - name: Build packages
         run: |
-          npx nx build twenty-sdk
-          npx nx build create-twenty-app
+          for pkg in $PUBLISHABLE_PACKAGES; do
+            npx nx build $pkg
+          done
 
       - name: Install and start Verdaccio
         run: |
@@ -86,11 +97,13 @@ jobs:
 
       - name: Publish packages to local registry
         run: |
-          npm set //localhost:4873/:_authToken "ci-auth-token"
+          yarn config set npmRegistryServer http://localhost:4873
+          yarn config set unsafeHttpWhitelist --json '["localhost"]'
+          yarn config set npmAuthToken ci-auth-token
 
-          for pkg in twenty-sdk create-twenty-app; do
+          for pkg in $PUBLISHABLE_PACKAGES; do
             cd packages/$pkg
-            npm publish --registry http://localhost:4873 --tag ci
+            yarn npm publish --tag ci
             cd ../..
           done
 
@@ -153,11 +166,15 @@ jobs:
           cd /tmp/e2e-test-workspace/test-app
           npx --no-install twenty remote add --token $SEED_API_KEY --url http://localhost:3000
 
-      - name: Build scaffolded app
+      - name: Deploy scaffolded app
         run: |
           cd /tmp/e2e-test-workspace/test-app
-          npx --no-install twenty build
-          test -d .twenty/output
+          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: |
@@ -166,6 +183,13 @@ jobs:
           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"
+
       - name: Run scaffolded app integration test
         env:
           TWENTY_API_URL: http://localhost:3000

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

@@ -26,6 +26,9 @@ jobs:
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
           PGUSER_SUPERUSER: postgres
           PGPASSWORD_SUPERUSER: postgres
@@ -40,6 +43,9 @@ jobs:
           --health-retries 5
       redis:
         image: redis
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         ports:
           - 6379:6379
     steps:

.github/workflows/ci-sdk.yaml

@@ -57,6 +57,9 @@ jobs:
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
           PGUSER_SUPERUSER: postgres
           PGPASSWORD_SUPERUSER: postgres
@@ -71,6 +74,9 @@ jobs:
           --health-retries 5
       redis:
         image: redis
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         ports:
           - 6379:6379
     env:

.github/workflows/ci-server.yaml

@@ -25,7 +25,7 @@ jobs:
         packages/twenty-server/**
         packages/twenty-front/src/generated/**
         packages/twenty-front/src/generated-metadata/**
-        packages/twenty-sdk/src/clients/generated/metadata/**
+        packages/twenty-client-sdk/**
         packages/twenty-emails/**
         packages/twenty-shared/**
 
@@ -84,6 +84,9 @@ jobs:
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
           PGUSER_SUPERUSER: postgres
           PGPASSWORD_SUPERUSER: postgres
@@ -98,6 +101,9 @@ jobs:
           --health-retries 5
       redis:
         image: redis
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         ports:
           - 6379:6379
     steps:
@@ -122,7 +128,6 @@ jobs:
           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:init:prod
-          npx nx run twenty-server:database:migrate:prod
       - name: Worker / Run
         run: |
           timeout 30s npx nx run twenty-server:worker || exit_code=$?
@@ -177,14 +182,14 @@ jobs:
             HAS_ERRORS=true
           fi
 
-          npx nx run twenty-sdk:generate-metadata-client
+          npx nx run twenty-client-sdk:generate-metadata-client
 
-          if ! git diff --quiet -- packages/twenty-sdk/src/clients/generated/metadata; then
-            echo "::error::SDK metadata client changes detected. Please run 'npx nx run twenty-sdk:generate-metadata-client' and commit the changes."
+          if ! git diff --quiet -- packages/twenty-client-sdk/src/metadata/generated; then
+            echo "::error::SDK metadata client changes detected. Please run 'npx nx run twenty-client-sdk:generate-metadata-client' and commit the changes."
             echo ""
             echo "The following SDK metadata client changes were detected:"
             echo "==================================================="
-            git diff -- packages/twenty-sdk/src/clients/generated/metadata
+            git diff -- packages/twenty-client-sdk/src/metadata/generated
             echo "==================================================="
             echo ""
             HAS_ERRORS=true
@@ -227,6 +232,9 @@ jobs:
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
           PGUSER_SUPERUSER: postgres
           PGPASSWORD_SUPERUSER: postgres
@@ -241,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"

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

@@ -1,4 +1,4 @@
-name: CI Docker Compose
+name: CI Docker
 
 permissions:
   contents: read
@@ -19,7 +19,7 @@ jobs:
       files: |
         packages/twenty-docker/**
         docker-compose.yml
-  test:
+  test-compose:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
@@ -27,13 +27,18 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
       - name: Run compose
         run: |
           echo "Patching docker-compose.yml..."
-          # change image to localbuild using yq
           yq eval 'del(.services.server.image)' -i docker-compose.yml
           yq eval '.services.server.build.context = "../../"' -i docker-compose.yml
           yq eval '.services.server.build.dockerfile = "./packages/twenty-docker/twenty/Dockerfile"' -i docker-compose.yml
+          yq eval '.services.server.build.target = "twenty"' -i docker-compose.yml
           yq eval '.services.server.restart = "no"' -i docker-compose.yml
 
           echo "Setting up .env file..."
@@ -89,11 +94,69 @@ jobs:
               echo "Still waiting for server... (${count}/300s)"
           done
         working-directory: ./packages/twenty-docker/
-  ci-test-docker-compose-status-check:
+  test-app-dev:
+    needs: changed-files-check
+    if: needs.changed-files-check.outputs.any_changed == 'true'
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
+      - name: Create frontend placeholder
+        run: |
+          mkdir -p packages/twenty-front/build
+          echo '<html><body>CI placeholder</body></html>' > packages/twenty-front/build/index.html
+      - name: Build app-dev image
+        run: |
+          docker build \
+            --target twenty-app-dev \
+            -f packages/twenty-docker/twenty/Dockerfile \
+            -t twenty-app-dev-ci \
+            .
+      - name: Start container
+        run: |
+          docker run -d --name twenty-app-dev \
+            -p 3000:3000 \
+            twenty-app-dev-ci
+          docker logs twenty-app-dev -f &
+      - name: Wait for server health
+        run: |
+          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:3000/healthz 2>/dev/null || echo "000")
+            if [ "$status" = "200" ]; then
+              echo "Server is healthy!"
+              curl -s http://localhost:3000/healthz
+              break
+            fi
+
+            container_status=$(docker inspect --format='{{.State.Status}}' twenty-app-dev 2>/dev/null || echo "unknown")
+            if [ "$container_status" = "exited" ]; then
+              echo "Container exited unexpectedly"
+              docker logs twenty-app-dev
+              exit 1
+            fi
+
+            count=$((count+1))
+            if [ $count -gt 300 ]; then
+              echo "Server did not become healthy within 5 minutes"
+              docker logs twenty-app-dev
+              exit 1
+            fi
+            echo "Still waiting... (${count}/300s) [HTTP ${status}]"
+            sleep 1
+          done
+  ci-test-docker-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
     runs-on: ubuntu-latest
-    needs: [changed-files-check, test]
+    needs: [changed-files-check, test-compose, test-app-dev]
     steps:
       - name: Fail job if any needs failed
         if: contains(needs.*.result, 'failure')

.github/workflows/ci-ui.yaml

@@ -0,0 +1,112 @@
+name: CI UI
+
+on:
+  pull_request:
+  merge_group:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  changed-files-check:
+    if: github.event_name != 'merge_group'
+    uses: ./.github/workflows/changed-files.yaml
+    with:
+      files: |
+        package.json
+        yarn.lock
+        packages/twenty-ui/**
+        packages/twenty-shared/**
+  ui-task:
+    needs: changed-files-check
+    if: needs.changed-files-check.outputs.any_changed == 'true'
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    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@v4
+        with:
+          fetch-depth: 10
+      - name: Install dependencies
+        uses: ./.github/actions/yarn-install
+      - name: Run ${{ matrix.task }}
+        run: npx nx ${{ matrix.task }} twenty-ui
+  ui-sb-build:
+    needs: changed-files-check
+    if: needs.changed-files-check.outputs.any_changed == 'true'
+    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@v4
+        with:
+          fetch-depth: 10
+      - name: Install dependencies
+        uses: ./.github/actions/yarn-install
+      - name: Build storybook
+        run: npx nx storybook:build twenty-ui
+      - name: Upload storybook build
+        uses: actions/upload-artifact@v4
+        with:
+          name: storybook-twenty-ui
+          path: packages/twenty-ui/storybook-static
+          retention-days: 1
+  ui-sb-test:
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    needs: ui-sb-build
+    env:
+      STORYBOOK_URL: http://localhost:6007
+    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: Build dependencies
+        run: npx nx build twenty-shared
+      - name: Download storybook build
+        uses: actions/download-artifact@v4
+        with:
+          name: storybook-twenty-ui
+          path: packages/twenty-ui/storybook-static
+      - name: Install Playwright
+        run: |
+          cd packages/twenty-ui
+          npx playwright install
+      - name: Serve storybook & run tests
+        run: |
+          npx http-server packages/twenty-ui/storybook-static --port 6007 --silent &
+          timeout 30 bash -c 'until curl -sf http://localhost:6007 > /dev/null 2>&1; do sleep 1; done'
+          npx nx storybook:test twenty-ui
+  ci-ui-status-check:
+    if: always() && !cancelled()
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    needs:
+      [
+        changed-files-check,
+        ui-task,
+        ui-sb-build,
+        ui-sb-test,
+      ]
+    steps:
+      - name: Fail job if any needs failed
+        if: contains(needs.*.result, 'failure')
+        run: exit 1

.github/workflows/ci-website.yaml

@@ -27,6 +27,9 @@ jobs:
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
           PGUSER_SUPERUSER: postgres
           PGPASSWORD_SUPERUSER: postgres

.github/workflows/ci-zapier.yaml

@@ -30,6 +30,9 @@ jobs:
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         env:
           PGUSER_SUPERUSER: postgres
           PGPASSWORD_SUPERUSER: postgres
@@ -44,6 +47,9 @@ jobs:
           --health-retries 5
       redis:
         image: redis
+        credentials:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
         ports:
           - 6379:6379
     steps:

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

@@ -17,6 +17,12 @@ jobs:
         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..."
@@ -24,10 +30,12 @@ jobs:
           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

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

@@ -0,0 +1,144 @@
+name: Visual Regression Dispatch
+
+# Uses workflow_run to dispatch visual regression to ci-privileged.
+# This runs in the context of the base repo (not the fork), so it has
+# access to secrets — making it work for external contributor PRs.
+
+on:
+  workflow_run:
+    workflows: ['CI Front', 'CI UI']
+    types: [completed]
+
+permissions:
+  actions: read
+  pull-requests: read
+
+jobs:
+  dispatch:
+    if: >-
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Determine project and artifact name
+        id: project
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const workflowName = context.payload.workflow_run.name;
+            if (workflowName === 'CI Front') {
+              core.setOutput('project', 'twenty-front');
+              core.setOutput('artifact_name', 'storybook-static');
+              core.setOutput('tarball_name', 'storybook-twenty-front-tarball');
+              core.setOutput('tarball_file', 'storybook-twenty-front.tar.gz');
+            } else if (workflowName === 'CI UI') {
+              core.setOutput('project', 'twenty-ui');
+              core.setOutput('artifact_name', 'storybook-twenty-ui');
+              core.setOutput('tarball_name', 'storybook-twenty-ui-tarball');
+              core.setOutput('tarball_file', 'storybook-twenty-ui.tar.gz');
+            } else {
+              core.setFailed(`Unexpected workflow: ${workflowName}`);
+            }
+
+      - name: Check if storybook artifact exists
+        id: check-artifact
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const artifactName = '${{ steps.project.outputs.artifact_name }}';
+            const runId = context.payload.workflow_run.id;
+
+            const { data: artifacts } = await github.rest.actions.listWorkflowRunArtifacts({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              run_id: runId,
+            });
+
+            const found = artifacts.artifacts.some(a => a.name === artifactName);
+            core.setOutput('exists', found ? 'true' : 'false');
+
+            if (!found) {
+              core.info(`Artifact "${artifactName}" not found in run ${runId} — storybook build was likely skipped`);
+            }
+
+      - name: Get PR number
+        if: steps.check-artifact.outputs.exists == 'true'
+        id: pr-info
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const headBranch = context.payload.workflow_run.head_branch;
+            const headRepo = context.payload.workflow_run.head_repository;
+
+            // workflow_run.pull_requests is empty for fork PRs,
+            // so fall back to searching by head label (owner:branch)
+            let pullRequests = context.payload.workflow_run.pull_requests;
+            let prNumber;
+
+            if (pullRequests && pullRequests.length > 0) {
+              prNumber = pullRequests[0].number;
+            } else {
+              const headLabel = `${headRepo.owner.login}:${headBranch}`;
+              core.info(`pull_requests is empty (likely a fork PR), searching by head label: ${headLabel}`);
+
+              const { data: prs } = await github.rest.pulls.list({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                state: 'open',
+                head: headLabel,
+                per_page: 1,
+              });
+
+              if (prs.length > 0) {
+                prNumber = prs[0].number;
+              }
+            }
+
+            if (!prNumber) {
+              core.info('No pull request found for this workflow run — skipping');
+              core.setOutput('has_pr', 'false');
+              return;
+            }
+
+            core.setOutput('pr_number', prNumber);
+            core.setOutput('has_pr', 'true');
+            core.info(`PR #${prNumber}`);
+
+      - 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@v4
+        with:
+          name: ${{ steps.project.outputs.artifact_name }}
+          path: storybook-static
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+
+      - name: Package storybook
+        if: steps.check-artifact.outputs.exists == 'true' && steps.pr-info.outputs.has_pr == 'true'
+        run: tar -czf /tmp/${{ steps.project.outputs.tarball_file }} -C storybook-static .
+
+      - name: Upload storybook tarball
+        if: steps.check-artifact.outputs.exists == 'true' && steps.pr-info.outputs.has_pr == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ steps.project.outputs.tarball_name }}
+          path: /tmp/${{ steps.project.outputs.tarball_file }}
+          retention-days: 1
+
+      - name: Dispatch to ci-privileged
+        if: steps.check-artifact.outputs.exists == 'true' && steps.pr-info.outputs.has_pr == 'true'
+        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 }}"
+            }

.gitignore

@@ -1,6 +1,7 @@
 **/**/.env
 .DS_Store
 /.idea
+.claude/settings.json
 **/**/node_modules/
 .cache
 

.yarnrc.yml

@@ -6,4 +6,4 @@ enableInlineHunks: true
 
 nodeLinker: node-modules
 
-yarnPath: .yarn/releases/yarn-4.9.2.cjs
+yarnPath: .yarn/releases/yarn-4.13.0.cjs

package.json

@@ -175,7 +175,7 @@
   },
   "license": "AGPL-3.0",
   "name": "twenty",
-  "packageManager": "yarn@4.9.2",
+  "packageManager": "yarn@4.13.0",
   "resolutions": {
     "graphql": "16.8.1",
     "type-fest": "4.10.1",
@@ -203,14 +203,17 @@
       "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-client-sdk",
       "packages/twenty-apps",
       "packages/twenty-cli",
       "packages/create-twenty-app",
-      "packages/twenty-oxlint-rules"
+      "packages/twenty-oxlint-rules",
+      "packages/twenty-companion"
     ]
   },
   "prettier": {

packages/create-twenty-app/README.md

@@ -41,9 +41,10 @@ cd my-twenty-app
 
 # Or do it manually:
 yarn twenty server start          # Start local Twenty server
-yarn twenty remote add --local    # Authenticate via OAuth
+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
@@ -124,10 +125,10 @@ The server is pre-seeded with a workspace and user (`tim@apple.dev` / `tim@apple
 ## Next steps
 
 - Run `yarn twenty help` to see all available commands.
-- Use `yarn twenty remote add --local` to authenticate with your Twenty workspace via OAuth.
+- 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` (for workspace data via `/graphql`) 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, MetadataApiClient } from 'twenty-sdk/clients'`.
+- `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
 
@@ -168,7 +169,7 @@ Our team reviews contributions for quality, security, and reusability before mer
 ## Troubleshooting
 
 - 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 --local`.
+- 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": "0.8.0-canary.1",
+  "version": "0.8.0-canary.6",
   "description": "Command-line interface to create Twenty application",
   "main": "dist/cli.cjs",
   "bin": "dist/cli.cjs",
@@ -36,6 +36,7 @@
     "lodash.camelcase": "^4.3.0",
     "lodash.kebabcase": "^4.1.1",
     "lodash.startcase": "^4.4.0",
+    "twenty-sdk": "workspace:*",
     "uuid": "^13.0.0"
   },
   "devDependencies": {
@@ -45,7 +46,6 @@
     "@types/lodash.kebabcase": "^4.1.7",
     "@types/lodash.startcase": "^4",
     "@types/node": "^20.0.0",
-    "twenty-sdk": "workspace:*",
     "twenty-shared": "workspace:*",
     "typescript": "^5.9.2",
     "vite": "^7.0.0",

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

@@ -1,17 +1,18 @@
 import { copyBaseApplicationProject } from '@/utils/app-template';
 import { convertToLabel } from '@/utils/convert-to-label';
 import { install } from '@/utils/install';
-import {
-  type LocalInstanceResult,
-  setupLocalInstance,
-} from '@/utils/setup-local-instance';
 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 { execSync } from 'node:child_process';
 import * as path from 'path';
+import { basename } from 'path';
+import {
+  authLoginOAuth,
+  serverStart,
+  type ServerStartResult,
+} from 'twenty-sdk/cli';
 import { isDefined } from 'twenty-shared/utils';
 
 import {
@@ -32,10 +33,10 @@ type CreateAppOptions = {
 
 export class CreateAppCommand {
   async execute(options: CreateAppOptions = {}): Promise<void> {
-    try {
-      const { appName, appDisplayName, appDirectory, appDescription } =
-        await this.getAppInfos(options);
+    const { appName, appDisplayName, appDirectory, appDescription } =
+      await this.getAppInfos(options);
 
+    try {
       const exampleOptions = this.resolveExampleOptions(
         options.mode ?? 'exhaustive',
       );
@@ -46,7 +47,6 @@ export class CreateAppCommand {
 
       await fs.ensureDir(appDirectory);
 
-      console.log(chalk.gray('  Scaffolding project files...'));
       await copyBaseApplicationProject({
         appName,
         appDisplayName,
@@ -55,27 +55,29 @@ export class CreateAppCommand {
         exampleOptions,
       });
 
-      console.log(chalk.gray('  Installing dependencies...'));
       await install(appDirectory);
 
-      console.log(chalk.gray('  Initializing git repository...'));
       await tryGitInit(appDirectory);
 
-      let localResult: LocalInstanceResult = { running: false };
+      let serverResult: ServerStartResult | undefined;
 
       if (!options.skipLocalInstance) {
-        // Auto-detect a running server first
-        localResult = await setupLocalInstance(appDirectory);
+        const startResult = await serverStart({
+          onProgress: (message: string) => console.log(chalk.gray(message)),
+        });
 
-        if (localResult.running && localResult.serverUrl) {
-          await this.connectToLocal(appDirectory, localResult.serverUrl);
+        if (startResult.success) {
+          serverResult = startResult.data;
+          await this.connectToLocal(serverResult.url);
+        } else {
+          console.log(chalk.yellow(`\n${startResult.error.message}`));
         }
       }
 
-      this.logSuccess(appDirectory, localResult);
+      this.logSuccess(appDirectory, serverResult);
     } catch (error) {
       console.error(
-        chalk.red('Initialization failed:'),
+        chalk.red('\nCreate application failed:'),
         error instanceof Error ? error.message : error,
       );
       process.exit(1);
@@ -193,29 +195,30 @@ export class CreateAppCommand {
     appDirectory: string;
     appName: string;
   }): void {
-    console.log(chalk.blue('Creating Twenty Application'));
-    console.log(chalk.gray(`  Directory: ${appDirectory}`));
-    console.log(chalk.gray(`  Name: ${appName}`));
-    console.log('');
+    console.log(
+      chalk.blue('\n', 'Creating Twenty Application\n'),
+      chalk.gray(`- Directory: ${appDirectory}\n`, `- Name: ${appName}\n`),
+    );
   }
 
-  private async connectToLocal(
-    appDirectory: string,
-    serverUrl: string,
-  ): Promise<void> {
+  private async connectToLocal(serverUrl: string): Promise<void> {
     try {
-      execSync(
-        `npx nx run twenty-sdk:start -- remote add ${serverUrl} --as local`,
-        {
-          cwd: appDirectory,
-          stdio: 'inherit',
-        },
-      );
-      console.log(chalk.green('Authenticated with local Twenty instance.'));
+      const result = await authLoginOAuth({
+        apiUrl: serverUrl,
+        remote: 'local',
+      });
+
+      if (!result.success) {
+        console.log(
+          chalk.yellow(
+            'Authentication skipped. Run `yarn twenty remote add` manually.',
+          ),
+        );
+      }
     } catch {
       console.log(
         chalk.yellow(
-          'Authentication skipped. Run `npx nx run twenty-sdk:start -- remote add --local` manually.',
+          'Authentication skipped. Run `yarn twenty remote add` manually.',
         ),
       );
     }
@@ -223,25 +226,23 @@ export class CreateAppCommand {
 
   private logSuccess(
     appDirectory: string,
-    localResult: LocalInstanceResult,
+    serverResult?: ServerStartResult,
   ): void {
-    const dirName = appDirectory.split('/').reverse()[0] ?? '';
+    const dirName = basename(appDirectory);
 
-    console.log(chalk.green('Application created!'));
-    console.log('');
-    console.log(chalk.blue('Next steps:'));
-    console.log(chalk.gray(`  cd ${dirName}`));
+    console.log(chalk.blue('\nApplication created. Next steps:'));
+    console.log(chalk.gray(`- cd ${dirName}`));
 
-    if (!localResult.running) {
+    if (!serverResult) {
       console.log(
         chalk.gray(
-          '  yarn twenty remote add --local  # Authenticate with Twenty',
+          '- yarn twenty remote add          # Authenticate with Twenty',
         ),
       );
     }
 
     console.log(
-      chalk.gray('  yarn twenty dev                  # Start dev mode'),
+      chalk.gray('- yarn twenty dev                  # Start dev mode'),
     );
   }
 }

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

@@ -106,6 +106,9 @@ describe('copyBaseApplicationProject', () => {
     expect(packageJson.devDependencies['twenty-sdk']).toBe(
       createTwentyAppPackageJson.version,
     );
+    expect(packageJson.devDependencies['twenty-client-sdk']).toBe(
+      createTwentyAppPackageJson.version,
+    );
     expect(packageJson.scripts['twenty']).toBe('twenty');
   });
 
@@ -362,11 +365,21 @@ describe('copyBaseApplicationProject', () => {
             join(srcPath, 'logic-functions', 'hello-world.ts'),
           ),
         ).toBe(true);
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'logic-functions', 'create-hello-world-company.ts'),
+          ),
+        ).toBe(true);
         expect(
           await fs.pathExists(
             join(srcPath, 'front-components', 'hello-world.tsx'),
           ),
         ).toBe(true);
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'page-layouts', 'example-record-page-layout.ts'),
+          ),
+        ).toBe(true);
         expect(
           await fs.pathExists(join(srcPath, 'views', 'example-view.ts')),
         ).toBe(true);
@@ -448,11 +461,21 @@ describe('copyBaseApplicationProject', () => {
             join(srcPath, 'logic-functions', 'hello-world.ts'),
           ),
         ).toBe(false);
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'logic-functions', 'create-hello-world-company.ts'),
+          ),
+        ).toBe(false);
         expect(
           await fs.pathExists(
             join(srcPath, 'front-components', 'hello-world.tsx'),
           ),
         ).toBe(false);
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'page-layouts', 'example-record-page-layout.ts'),
+          ),
+        ).toBe(false);
         expect(
           await fs.pathExists(join(srcPath, 'views', 'example-view.ts')),
         ).toBe(false);
@@ -480,7 +503,7 @@ describe('copyBaseApplicationProject', () => {
     });
 
     describe('selective examples', () => {
-      it('should create only front component when only that option is enabled', async () => {
+      it('should create front component and page layout when only front component option is enabled', async () => {
         await copyBaseApplicationProject({
           appName: 'my-test-app',
           appDisplayName: 'My Test App',
@@ -506,6 +529,11 @@ describe('copyBaseApplicationProject', () => {
             join(srcPath, 'front-components', 'hello-world.tsx'),
           ),
         ).toBe(true);
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'page-layouts', 'example-record-page-layout.ts'),
+          ),
+        ).toBe(true);
         expect(
           await fs.pathExists(join(srcPath, 'objects', 'example-object.ts')),
         ).toBe(false);
@@ -545,6 +573,11 @@ describe('copyBaseApplicationProject', () => {
             join(srcPath, 'logic-functions', 'hello-world.ts'),
           ),
         ).toBe(true);
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'logic-functions', 'create-hello-world-company.ts'),
+          ),
+        ).toBe(true);
         expect(
           await fs.pathExists(join(srcPath, 'objects', 'example-object.ts')),
         ).toBe(false);

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

@@ -47,15 +47,17 @@ describe('scaffoldIntegrationTest', () => {
       const content = await fs.readFile(testPath, 'utf8');
 
       expect(content).toContain(
-        "import { appBuild, appUninstall } from 'twenty-sdk/cli'",
+        "import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli'",
       );
       expect(content).toContain(
-        "import { MetadataApiClient } from 'twenty-sdk/clients'",
+        "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');
@@ -136,7 +138,7 @@ describe('scaffoldIntegrationTest', () => {
       expect(content).toContain('yarn install --immutable');
       expect(content).toContain('yarn test');
       expect(content).toContain('TWENTY_API_URL');
-      expect(content).toContain('TWENTY_TEST_API_KEY');
+      expect(content).toContain('TWENTY_API_KEY');
     });
   });
 

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

@@ -34,6 +34,8 @@ export const copyBaseApplicationProject = async ({
 
   await createGitignore(appDirectory);
 
+  await createNvmrc(appDirectory);
+
   await createPublicAssetDirectory(appDirectory);
 
   const sourceFolderPath = join(appDirectory, SRC_FOLDER);
@@ -69,6 +71,12 @@ export const copyBaseApplicationProject = async ({
       fileFolder: 'logic-functions',
       fileName: 'hello-world.ts',
     });
+
+    await createCreateCompanyFunction({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'logic-functions',
+      fileName: 'create-hello-world-company.ts',
+    });
   }
 
   if (exampleOptions.includeExampleFrontComponent) {
@@ -77,6 +85,12 @@ export const copyBaseApplicationProject = async ({
       fileFolder: 'front-components',
       fileName: 'hello-world.tsx',
     });
+
+    await createExamplePageLayout({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'page-layouts',
+      fileName: 'example-record-page-layout.ts',
+    });
   }
 
   if (exampleOptions.includeExampleView) {
@@ -186,6 +200,10 @@ yarn-error.log*
   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,
@@ -230,19 +248,59 @@ const createDefaultFrontComponent = async ({
 }) => {
   const universalIdentifier = v4();
 
-  const content = `import { defineFrontComponent } from 'twenty-sdk';
+  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>
   );
 };
 
 export default defineFrontComponent({
-  universalIdentifier: '${universalIdentifier}',
+  universalIdentifier: HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
   name: 'hello-world-front-component',
   description: 'A sample front component',
   component: HelloWorld,
@@ -253,6 +311,56 @@ export default defineFrontComponent({
   await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
 };
 
+const createExamplePageLayout = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  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 createDefaultFunction = async ({
   appDirectory,
   fileFolder,
@@ -288,6 +396,58 @@ export default defineLogicFunction({
   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,
+    },
+  });
+
+  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,
@@ -615,6 +775,7 @@ const createPackageJson = async ({
     'react-dom': '^19.0.0',
     oxlint: '^0.16.0',
     'twenty-sdk': createTwentyAppPackageJson.version,
+    'twenty-client-sdk': createTwentyAppPackageJson.version,
   };
 
   if (includeExampleIntegrationTest) {
@@ -633,6 +794,7 @@ const createPackageJson = async ({
       npm: 'please-use-yarn',
       yarn: '>=4.0.2',
     },
+    keywords: ['twenty-app'],
     packageManager: 'yarn@4.9.2',
     scripts,
     devDependencies,

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

@@ -5,6 +5,7 @@ import { exec } from 'child_process';
 const execPromise = promisify(exec);
 
 export const install = async (root: string) => {
+  console.log(chalk.gray('Installing yarn dependencies...'));
   try {
     await execPromise('corepack enable', { cwd: root });
   } catch (error: any) {
@@ -14,6 +15,6 @@ export const install = async (root: string) => {
   try {
     await execPromise('yarn install', { cwd: root });
   } catch (error: any) {
-    console.error(chalk.red('yarn install failed:'), error.stdout);
+    console.warn(chalk.yellow('yarn install failed:'), error.stdout);
   }
 };

packages/create-twenty-app/src/utils/setup-local-instance.ts

@@ -1,101 +0,0 @@
-import chalk from 'chalk';
-import { execSync } from 'node:child_process';
-import { platform } from 'node:os';
-
-const DEFAULT_PORT = 2020;
-
-// Minimal health check — the full implementation lives in twenty-sdk
-const isServerReady = async (port: number): Promise<boolean> => {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), 3000);
-
-  try {
-    const response = await fetch(`http://localhost:${port}/healthz`, {
-      signal: controller.signal,
-    });
-
-    const body = await response.json();
-
-    return body.status === 'ok';
-  } catch {
-    return false;
-  } finally {
-    clearTimeout(timeoutId);
-  }
-};
-
-export type LocalInstanceResult = {
-  running: boolean;
-  serverUrl?: string;
-};
-
-export const setupLocalInstance = async (
-  appDirectory: string,
-): Promise<LocalInstanceResult> => {
-  console.log('');
-  console.log(chalk.blue('Setting up local Twenty instance...'));
-
-  if (await isServerReady(DEFAULT_PORT)) {
-    const serverUrl = `http://localhost:${DEFAULT_PORT}`;
-
-    console.log(chalk.green(`Twenty server detected on ${serverUrl}.`));
-
-    return { running: true, serverUrl };
-  }
-
-  // Delegate to `twenty server start` from the scaffolded app
-  console.log(chalk.gray('Starting local Twenty server...'));
-
-  try {
-    execSync('yarn twenty server start', {
-      cwd: appDirectory,
-      stdio: 'inherit',
-    });
-  } catch {
-    console.log(
-      chalk.yellow(
-        'Failed to start Twenty server. Run `yarn twenty server start` manually.',
-      ),
-    );
-
-    return { running: false };
-  }
-
-  console.log(chalk.gray('Waiting for Twenty to be ready...'));
-
-  const startTime = Date.now();
-  const timeoutMs = 180 * 1000;
-
-  while (Date.now() - startTime < timeoutMs) {
-    if (await isServerReady(DEFAULT_PORT)) {
-      const serverUrl = `http://localhost:${DEFAULT_PORT}`;
-
-      console.log(chalk.green(`Twenty server is running on ${serverUrl}.`));
-      console.log(
-        chalk.gray(
-          'Workspace ready — login with tim@apple.dev / tim@apple.dev',
-        ),
-      );
-
-      const openCommand = platform() === 'darwin' ? 'open' : 'xdg-open';
-
-      try {
-        execSync(`${openCommand} ${serverUrl}`, { stdio: 'ignore' });
-      } catch {
-        // Ignore if browser can't be opened
-      }
-
-      return { running: true, serverUrl };
-    }
-
-    await new Promise((resolve) => setTimeout(resolve, 2000));
-  }
-
-  console.log(
-    chalk.yellow(
-      'Twenty server did not become healthy in time. Check: yarn twenty server logs',
-    ),
-  );
-
-  return { running: false };
-};

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

@@ -149,18 +149,17 @@ const createIntegrationTest = async ({
   fileName: string;
 }) => {
   const content = `import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config';
-import { appBuild, appUninstall } from 'twenty-sdk/cli';
-import { MetadataApiClient } from 'twenty-sdk/clients';
+import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli';
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 
 const APP_PATH = process.cwd();
 
 describe('App installation', () => {
-  let appInstalled = false;
-
   beforeAll(async () => {
     const buildResult = await appBuild({
       appPath: APP_PATH,
+      tarball: true,
       onProgress: (message: string) => console.log(\`[build] \${message}\`),
     });
 
@@ -170,14 +169,27 @@ describe('App installation', () => {
       );
     }
 
-    appInstalled = true;
+    const deployResult = await appDeploy({
+      tarballPath: buildResult.data.tarballPath!,
+      onProgress: (message: string) => console.log(\`[deploy] \${message}\`),
+    });
+
+    if (!deployResult.success) {
+      throw new Error(
+        \`Deploy failed: \${deployResult.error?.message ?? 'Unknown error'}\`,
+      );
+    }
+
+    const installResult = await appInstall({ appPath: APP_PATH });
+
+    if (!installResult.success) {
+      throw new Error(
+        \`Install failed: \${installResult.error?.message ?? 'Unknown error'}\`,
+      );
+    }
   });
 
   afterAll(async () => {
-    if (!appInstalled) {
-      return;
-    }
-
     const uninstallResult = await appUninstall({ appPath: APP_PATH });
 
     if (!uninstallResult.success) {
@@ -257,7 +269,7 @@ jobs:
         run: yarn test
         env:
           TWENTY_API_URL: \${{ steps.twenty.outputs.server-url }}
-          TWENTY_TEST_API_KEY: \${{ steps.twenty.outputs.access-token }}
+          TWENTY_API_KEY: \${{ steps.twenty.outputs.access-token }}
 `;
 
   const workflowDir = join(appDirectory, '.github', 'workflows');

packages/twenty-apps/community/apollo-enrich/README.md

@@ -5,7 +5,7 @@ This is a [Twenty](https://twenty.com) application project bootstrapped with [`c
 First, authenticate to your workspace:
 
 ```bash
-yarn twenty remote add --local
+yarn twenty remote add http://localhost:2020 --as local
 ```
 
 Then, start development mode to sync your app and watch for changes:
@@ -22,7 +22,7 @@ Run `yarn twenty help` to list all available commands. Common commands:
 
 ```bash
 # Remotes & Authentication
-yarn twenty remote add --local     # Authenticate with Twenty
+yarn twenty remote add http://localhost:2020 --as local     # Authenticate with Twenty
 yarn twenty remote status         # Check auth status
 yarn twenty remote switch         # Switch default remote
 yarn twenty remote list           # List all configured remotes

packages/twenty-apps/fixtures/postcard-app/package.json

@@ -9,22 +9,11 @@
   },
   "packageManager": "yarn@4.9.2",
   "scripts": {
-    "remote:add": "twenty remote add --local",
-    "remote:status": "twenty remote status",
-    "remote:switch": "twenty remote switch",
-    "remote:list": "twenty remote list",
-    "remote:remove": "twenty remote remove",
-    "dev": "twenty dev",
-    "add": "twenty add",
-    "logs": "twenty logs",
-    "exec": "twenty exec",
-    "uninstall": "twenty uninstall",
-    "help": "twenty help",
-    "lint": "oxlint -c .oxlintrc.json .",
-    "lint:fix": "oxlint --fix -c .oxlintrc.json ."
+    "twenty": "twenty"
   },
   "dependencies": {
-    "twenty-sdk": "latest"
+    "twenty-sdk": "latest",
+    "twenty-client-sdk": "latest"
   },
   "devDependencies": {
     "typescript": "^5.9.3",

packages/twenty-apps/fixtures/postcard-app/src/fields/postCardCategoryField.ts

@@ -3,7 +3,7 @@ import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
 
 export default defineField({
   objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  universalIdentifier: '8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e',
+  universalIdentifier: 'b602dbd9-e511-49ce-b6d3-b697218dc69c',
   type: FieldType.SELECT,
   name: 'category',
   label: 'Category',

packages/twenty-apps/fixtures/postcard-app/src/fields/postCardNumber.field.ts

@@ -3,7 +3,7 @@ import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
 
 export default defineField({
   objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  universalIdentifier: '7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d',
+  universalIdentifier: '7b57bd63-5a4c-46ca-9d52-42c8f02d1df6',
   type: FieldType.NUMBER,
   name: 'priority',
   label: 'Priority',

packages/twenty-apps/fixtures/postcard-app/src/objects/recipient.object.ts

@@ -25,8 +25,8 @@ export default defineObject({
     {
       universalIdentifier: 'd3a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5d',
       type: FieldType.ADDRESS,
-      label: 'Address',
-      name: 'address',
+      label: 'Mailing Address',
+      name: 'mailingAddress',
       icon: 'IconHome',
     },
   ],

packages/twenty-apps/hello-world/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request: {}
+
+env:
+  TWENTY_VERSION: latest
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Spawn Twenty instance
+        id: twenty
+        uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main
+        with:
+          twenty-version: ${{ env.TWENTY_VERSION }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - 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.access-token }}

packages/twenty-apps/hello-world/LLMS.md

@@ -4,6 +4,7 @@
 - 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

packages/twenty-apps/hello-world/README.md

@@ -5,7 +5,7 @@ This is a [Twenty](https://twenty.com) application project bootstrapped with [`c
 First, authenticate to your workspace:
 
 ```bash
-yarn twenty remote add --local
+yarn twenty remote add http://localhost:2020 --as local
 ```
 
 Then, start development mode to sync your app and watch for changes:
@@ -22,7 +22,7 @@ Run `yarn twenty help` to list all available commands. Common commands:
 
 ```bash
 # Remotes & Authentication
-yarn twenty remote add --local     # Authenticate with Twenty
+yarn twenty remote add http://localhost:2020 --as local     # Authenticate with Twenty
 yarn twenty remote status         # Check auth status
 yarn twenty remote switch         # Switch default remote
 yarn twenty remote list           # List all configured remotes

packages/twenty-apps/hello-world/package.json

@@ -20,7 +20,8 @@
     "@types/react": "^18.2.0",
     "oxlint": "^0.16.0",
     "react": "^18.2.0",
-    "twenty-sdk": "0.6.4",
+    "twenty-client-sdk": "portal:../../twenty-client-sdk",
+    "twenty-sdk": "portal:../../twenty-sdk",
     "typescript": "^5.9.3",
     "vite-tsconfig-paths": "^4.2.1",
     "vitest": "^3.1.1"

packages/twenty-apps/hello-world/src/__tests__/app-install.integration-test.ts

@@ -1,16 +1,15 @@
 import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config';
-import { appBuild, appUninstall } from 'twenty-sdk/cli';
-import { MetadataApiClient } from 'twenty-sdk/clients';
+import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli';
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 
 const APP_PATH = process.cwd();
 
 describe('App installation', () => {
-  let appInstalled = false;
-
   beforeAll(async () => {
     const buildResult = await appBuild({
       appPath: APP_PATH,
+      tarball: true,
       onProgress: (message: string) => console.log(`[build] ${message}`),
     });
 
@@ -20,14 +19,27 @@ describe('App installation', () => {
       );
     }
 
-    appInstalled = true;
+    const deployResult = await appDeploy({
+      tarballPath: buildResult.data.tarballPath!,
+      onProgress: (message: string) => console.log(`[deploy] ${message}`),
+    });
+
+    if (!deployResult.success) {
+      throw new Error(
+        `Deploy failed: ${deployResult.error?.message ?? 'Unknown error'}`,
+      );
+    }
+
+    const installResult = await appInstall({ appPath: APP_PATH });
+
+    if (!installResult.success) {
+      throw new Error(
+        `Install failed: ${installResult.error?.message ?? 'Unknown error'}`,
+      );
+    }
   });
 
   afterAll(async () => {
-    if (!appInstalled) {
-      return;
-    }
-
     const uninstallResult = await appUninstall({ appPath: APP_PATH });
 
     if (!uninstallResult.success) {

packages/twenty-apps/hello-world/src/agents/example-agent.ts

@@ -0,0 +1,13 @@
+import { defineAgent } from 'twenty-sdk';
+
+export const EXAMPLE_AGENT_UNIVERSAL_IDENTIFIER =
+  '110bebc2-f116-46b6-a35d-61e91c3c0a43';
+
+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.',
+});

packages/twenty-apps/hello-world/src/application-config.ts

@@ -2,7 +2,7 @@ import { defineApplication } from 'twenty-sdk';
 import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
 
 export const APPLICATION_UNIVERSAL_IDENTIFIER =
-  '6563e091-9f5b-4026-a3ea-7e3b3d09e218';
+  'bb1decf6-dee5-43ef-b881-9799f97b02a8';
 
 export default defineApplication({
   universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,

packages/twenty-apps/hello-world/src/fields/example-field.ts

@@ -3,7 +3,7 @@ import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from 'src/objects/example-object'
 
 export default defineField({
   objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
-  universalIdentifier: '770d32c2-cf12-4ab2-b66d-73f92dc239b5',
+  universalIdentifier: 'be08a7c6-2586-4d91-9fa7-0a44e6eae30c',
   type: FieldType.NUMBER,
   name: 'priority',
   label: 'Priority',

packages/twenty-apps/hello-world/src/front-components/hello-world.tsx

@@ -1,16 +1,56 @@
+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 =
+  '7a758f23-5e7d-497d-98c9-7ca8d6c085b0';
+
 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>
   );
 };
 
 export default defineFrontComponent({
-  universalIdentifier: 'd371f098-5b2c-42f0-898d-94459f1ee337',
+  universalIdentifier: HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
   name: 'hello-world-front-component',
   description: 'A sample front component',
   component: HelloWorld,

packages/twenty-apps/hello-world/src/logic-functions/create-hello-world-company.ts

@@ -0,0 +1,35 @@
+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,
+    },
+  });
+
+  return {
+    message: `Created company "${createCompany?.name}" with id ${createCompany?.id}`,
+  };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: '94abaa53-d265-4fa4-ae52-1d7ea711ecf2',
+  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,
+  },
+});

packages/twenty-apps/hello-world/src/logic-functions/hello-world.ts

@@ -5,7 +5,7 @@ const handler = async (): Promise<{ message: string }> => {
 };
 
 export default defineLogicFunction({
-  universalIdentifier: '2baa26eb-9aaf-4856-a4f4-30d6fd6480ee',
+  universalIdentifier: 'b05e4b30-72d4-4d7f-8091-32e037b601da',
   name: 'hello-world-logic-function',
   description: 'A simple logic function',
   timeoutSeconds: 5,

packages/twenty-apps/hello-world/src/logic-functions/post-install.ts

@@ -5,7 +5,7 @@ const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
 };
 
 export default definePostInstallLogicFunction({
-  universalIdentifier: '7a3f4684-51db-494d-833b-a747a3b90507',
+  universalIdentifier: '8c726dcc-1709-4eac-aa8b-f99960a9ec1b',
   name: 'post-install',
   description: 'Runs after installation to set up the application.',
   timeoutSeconds: 300,

packages/twenty-apps/hello-world/src/logic-functions/pre-install.ts

@@ -5,7 +5,7 @@ const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
 };
 
 export default definePreInstallLogicFunction({
-  universalIdentifier: '1272ffdb-8e2f-492c-ab37-66c2b97e9c23',
+  universalIdentifier: 'f8ad4b09-6a12-4b12-a52a-3472d3a78dc7',
   name: 'pre-install',
   description: 'Runs before installation to prepare the application.',
   timeoutSeconds: 300,

packages/twenty-apps/hello-world/src/navigation-menu-items/example-navigation-menu-item.ts

@@ -3,7 +3,7 @@ import { NavigationMenuItemType } from 'twenty-shared/types';
 import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from 'src/views/example-view';
 
 export default defineNavigationMenuItem({
-  universalIdentifier: '10f90627-e9c2-44b7-9742-bed77e3d1b17',
+  universalIdentifier: '9327db91-afa1-41b6-bd9d-2b51a26efb4c',
   name: 'example-navigation-menu-item',
   icon: 'IconList',
   color: 'blue',

packages/twenty-apps/hello-world/src/objects/example-object.ts

@@ -1,10 +1,10 @@
 import { defineObject, FieldType } from 'twenty-sdk';
 
 export const EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER =
-  'dfd43356-39b3-4b55-b4a7-279bec689928';
+  '47fd9bd9-392b-4d9f-9091-9a91b1edf519';
 
 export const NAME_FIELD_UNIVERSAL_IDENTIFIER =
-  'd2d7f6cd-33f6-456f-bf00-17adeca926ba';
+  '2d9ff841-cf8e-44ec-ad8e-468455f7eebd';
 
 export default defineObject({
   universalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,

packages/twenty-apps/hello-world/src/page-layouts/example-record-page-layout.ts

@@ -0,0 +1,31 @@
+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: '203aeb94-6701-46d6-9af1-be2bbcc9e134',
+  name: 'Example Record Page',
+  type: 'RECORD_PAGE',
+  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
+  tabs: [
+    {
+      universalIdentifier: '6ed26b60-a51d-4ad7-86dd-1c04c7f3cac5',
+      title: 'Hello World',
+      position: 50,
+      icon: 'IconWorld',
+      layoutMode: PageLayoutTabLayoutMode.CANVAS,
+      widgets: [
+        {
+          universalIdentifier: 'aa4234e0-2e5f-4c02-a96a-573449e2351d',
+          title: 'Hello World',
+          type: 'FRONT_COMPONENT',
+          configuration: {
+            configurationType: 'FRONT_COMPONENT',
+            frontComponentUniversalIdentifier:
+              HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+          },
+        },
+      ],
+    },
+  ],
+});

packages/twenty-apps/hello-world/src/roles/default-role.ts

@@ -1,7 +1,7 @@
 import { defineRole } from 'twenty-sdk';
 
 export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
-  '9238bc7b-d38f-4a1c-9d19-31ab7bc67a2f';
+  'c38f4d11-760c-4d5c-89ed-e569c28b7b70';
 
 export default defineRole({
   universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,

packages/twenty-apps/hello-world/src/skills/example-skill.ts

@@ -1,7 +1,7 @@
 import { defineSkill } from 'twenty-sdk';
 
 export const EXAMPLE_SKILL_UNIVERSAL_IDENTIFIER =
-  'd0940029-9d3c-40be-903a-52d65393028f';
+  '90cf9144-4811-4653-93a2-9a6780fe6aac';
 
 export default defineSkill({
   universalIdentifier: EXAMPLE_SKILL_UNIVERSAL_IDENTIFIER,

packages/twenty-apps/hello-world/src/views/example-view.ts

@@ -1,7 +1,7 @@
 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 = 'e004df40-29f3-47ba-b39d-d3a5c444367a';
+export const EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER = '965e3776-b966-4be8-83f7-6cd3bce5e1bd';
 
 export default defineView({
   universalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
@@ -12,7 +12,7 @@ export default defineView({
   position: 0,
   fields: [
     {
-      universalIdentifier: '496c40c2-5766-419c-93bf-20fdad3f34bb',
+      universalIdentifier: 'f926bdb7-6af7-4683-9a09-adbca56c29f0',
       fieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
       position: 0,
       isVisible: true,

packages/twenty-apps/hello-world/yarn.lock

@@ -352,9 +352,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/aix-ppc64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/aix-ppc64@npm:0.27.3"
+"@esbuild/aix-ppc64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/aix-ppc64@npm:0.27.4"
   conditions: os=aix & cpu=ppc64
   languageName: node
   linkType: hard
@@ -366,9 +366,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/android-arm64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/android-arm64@npm:0.27.3"
+"@esbuild/android-arm64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/android-arm64@npm:0.27.4"
   conditions: os=android & cpu=arm64
   languageName: node
   linkType: hard
@@ -380,9 +380,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/android-arm@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/android-arm@npm:0.27.3"
+"@esbuild/android-arm@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/android-arm@npm:0.27.4"
   conditions: os=android & cpu=arm
   languageName: node
   linkType: hard
@@ -394,9 +394,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/android-x64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/android-x64@npm:0.27.3"
+"@esbuild/android-x64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/android-x64@npm:0.27.4"
   conditions: os=android & cpu=x64
   languageName: node
   linkType: hard
@@ -408,9 +408,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/darwin-arm64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/darwin-arm64@npm:0.27.3"
+"@esbuild/darwin-arm64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/darwin-arm64@npm:0.27.4"
   conditions: os=darwin & cpu=arm64
   languageName: node
   linkType: hard
@@ -422,9 +422,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/darwin-x64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/darwin-x64@npm:0.27.3"
+"@esbuild/darwin-x64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/darwin-x64@npm:0.27.4"
   conditions: os=darwin & cpu=x64
   languageName: node
   linkType: hard
@@ -436,9 +436,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/freebsd-arm64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/freebsd-arm64@npm:0.27.3"
+"@esbuild/freebsd-arm64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/freebsd-arm64@npm:0.27.4"
   conditions: os=freebsd & cpu=arm64
   languageName: node
   linkType: hard
@@ -450,9 +450,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/freebsd-x64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/freebsd-x64@npm:0.27.3"
+"@esbuild/freebsd-x64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/freebsd-x64@npm:0.27.4"
   conditions: os=freebsd & cpu=x64
   languageName: node
   linkType: hard
@@ -464,9 +464,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/linux-arm64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/linux-arm64@npm:0.27.3"
+"@esbuild/linux-arm64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/linux-arm64@npm:0.27.4"
   conditions: os=linux & cpu=arm64
   languageName: node
   linkType: hard
@@ -478,9 +478,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/linux-arm@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/linux-arm@npm:0.27.3"
+"@esbuild/linux-arm@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/linux-arm@npm:0.27.4"
   conditions: os=linux & cpu=arm
   languageName: node
   linkType: hard
@@ -492,9 +492,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/linux-ia32@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/linux-ia32@npm:0.27.3"
+"@esbuild/linux-ia32@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/linux-ia32@npm:0.27.4"
   conditions: os=linux & cpu=ia32
   languageName: node
   linkType: hard
@@ -506,9 +506,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/linux-loong64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/linux-loong64@npm:0.27.3"
+"@esbuild/linux-loong64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/linux-loong64@npm:0.27.4"
   conditions: os=linux & cpu=loong64
   languageName: node
   linkType: hard
@@ -520,9 +520,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/linux-mips64el@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/linux-mips64el@npm:0.27.3"
+"@esbuild/linux-mips64el@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/linux-mips64el@npm:0.27.4"
   conditions: os=linux & cpu=mips64el
   languageName: node
   linkType: hard
@@ -534,9 +534,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/linux-ppc64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/linux-ppc64@npm:0.27.3"
+"@esbuild/linux-ppc64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/linux-ppc64@npm:0.27.4"
   conditions: os=linux & cpu=ppc64
   languageName: node
   linkType: hard
@@ -548,9 +548,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/linux-riscv64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/linux-riscv64@npm:0.27.3"
+"@esbuild/linux-riscv64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/linux-riscv64@npm:0.27.4"
   conditions: os=linux & cpu=riscv64
   languageName: node
   linkType: hard
@@ -562,9 +562,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/linux-s390x@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/linux-s390x@npm:0.27.3"
+"@esbuild/linux-s390x@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/linux-s390x@npm:0.27.4"
   conditions: os=linux & cpu=s390x
   languageName: node
   linkType: hard
@@ -576,9 +576,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/linux-x64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/linux-x64@npm:0.27.3"
+"@esbuild/linux-x64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/linux-x64@npm:0.27.4"
   conditions: os=linux & cpu=x64
   languageName: node
   linkType: hard
@@ -590,9 +590,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/netbsd-arm64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/netbsd-arm64@npm:0.27.3"
+"@esbuild/netbsd-arm64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/netbsd-arm64@npm:0.27.4"
   conditions: os=netbsd & cpu=arm64
   languageName: node
   linkType: hard
@@ -604,9 +604,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/netbsd-x64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/netbsd-x64@npm:0.27.3"
+"@esbuild/netbsd-x64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/netbsd-x64@npm:0.27.4"
   conditions: os=netbsd & cpu=x64
   languageName: node
   linkType: hard
@@ -618,9 +618,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/openbsd-arm64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/openbsd-arm64@npm:0.27.3"
+"@esbuild/openbsd-arm64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/openbsd-arm64@npm:0.27.4"
   conditions: os=openbsd & cpu=arm64
   languageName: node
   linkType: hard
@@ -632,9 +632,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/openbsd-x64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/openbsd-x64@npm:0.27.3"
+"@esbuild/openbsd-x64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/openbsd-x64@npm:0.27.4"
   conditions: os=openbsd & cpu=x64
   languageName: node
   linkType: hard
@@ -646,9 +646,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/openharmony-arm64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/openharmony-arm64@npm:0.27.3"
+"@esbuild/openharmony-arm64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/openharmony-arm64@npm:0.27.4"
   conditions: os=openharmony & cpu=arm64
   languageName: node
   linkType: hard
@@ -660,9 +660,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/sunos-x64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/sunos-x64@npm:0.27.3"
+"@esbuild/sunos-x64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/sunos-x64@npm:0.27.4"
   conditions: os=sunos & cpu=x64
   languageName: node
   linkType: hard
@@ -674,9 +674,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/win32-arm64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/win32-arm64@npm:0.27.3"
+"@esbuild/win32-arm64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/win32-arm64@npm:0.27.4"
   conditions: os=win32 & cpu=arm64
   languageName: node
   linkType: hard
@@ -688,9 +688,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/win32-ia32@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/win32-ia32@npm:0.27.3"
+"@esbuild/win32-ia32@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/win32-ia32@npm:0.27.4"
   conditions: os=win32 & cpu=ia32
   languageName: node
   linkType: hard
@@ -702,9 +702,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@esbuild/win32-x64@npm:0.27.3":
-  version: 0.27.3
-  resolution: "@esbuild/win32-x64@npm:0.27.3"
+"@esbuild/win32-x64@npm:0.27.4":
+  version: 0.27.4
+  resolution: "@esbuild/win32-x64@npm:0.27.4"
   conditions: os=win32 & cpu=x64
   languageName: node
   linkType: hard
@@ -1541,11 +1541,11 @@ __metadata:
   linkType: hard
 
 "@types/node@npm:*":
-  version: 25.3.5
-  resolution: "@types/node@npm:25.3.5"
+  version: 25.5.0
+  resolution: "@types/node@npm:25.5.0"
   dependencies:
     undici-types: "npm:~7.18.0"
-  checksum: 10c0/4cf0834a6f6933bf0aca6afead117ae3db3b8f02a5f7187a24f871db0fb9344e5e46573ba387bc53b7505e1e219c4c535cbe67221ced95bb5ad98573223b19d0
+  checksum: 10c0/70c508165b6758c4f88d4f91abca526c3985eee1985503d4c2bd994dbaf588e52ac57e571160f18f117d76e963570ac82bd20e743c18987e82564312b3b62119
   languageName: node
   linkType: hard
 
@@ -3408,35 +3408,35 @@ __metadata:
   linkType: hard
 
 "esbuild@npm:^0.27.0":
-  version: 0.27.3
-  resolution: "esbuild@npm:0.27.3"
+  version: 0.27.4
+  resolution: "esbuild@npm:0.27.4"
   dependencies:
-    "@esbuild/aix-ppc64": "npm:0.27.3"
-    "@esbuild/android-arm": "npm:0.27.3"
-    "@esbuild/android-arm64": "npm:0.27.3"
-    "@esbuild/android-x64": "npm:0.27.3"
-    "@esbuild/darwin-arm64": "npm:0.27.3"
-    "@esbuild/darwin-x64": "npm:0.27.3"
-    "@esbuild/freebsd-arm64": "npm:0.27.3"
-    "@esbuild/freebsd-x64": "npm:0.27.3"
-    "@esbuild/linux-arm": "npm:0.27.3"
-    "@esbuild/linux-arm64": "npm:0.27.3"
-    "@esbuild/linux-ia32": "npm:0.27.3"
-    "@esbuild/linux-loong64": "npm:0.27.3"
-    "@esbuild/linux-mips64el": "npm:0.27.3"
-    "@esbuild/linux-ppc64": "npm:0.27.3"
-    "@esbuild/linux-riscv64": "npm:0.27.3"
-    "@esbuild/linux-s390x": "npm:0.27.3"
-    "@esbuild/linux-x64": "npm:0.27.3"
-    "@esbuild/netbsd-arm64": "npm:0.27.3"
-    "@esbuild/netbsd-x64": "npm:0.27.3"
-    "@esbuild/openbsd-arm64": "npm:0.27.3"
-    "@esbuild/openbsd-x64": "npm:0.27.3"
-    "@esbuild/openharmony-arm64": "npm:0.27.3"
-    "@esbuild/sunos-x64": "npm:0.27.3"
-    "@esbuild/win32-arm64": "npm:0.27.3"
-    "@esbuild/win32-ia32": "npm:0.27.3"
-    "@esbuild/win32-x64": "npm:0.27.3"
+    "@esbuild/aix-ppc64": "npm:0.27.4"
+    "@esbuild/android-arm": "npm:0.27.4"
+    "@esbuild/android-arm64": "npm:0.27.4"
+    "@esbuild/android-x64": "npm:0.27.4"
+    "@esbuild/darwin-arm64": "npm:0.27.4"
+    "@esbuild/darwin-x64": "npm:0.27.4"
+    "@esbuild/freebsd-arm64": "npm:0.27.4"
+    "@esbuild/freebsd-x64": "npm:0.27.4"
+    "@esbuild/linux-arm": "npm:0.27.4"
+    "@esbuild/linux-arm64": "npm:0.27.4"
+    "@esbuild/linux-ia32": "npm:0.27.4"
+    "@esbuild/linux-loong64": "npm:0.27.4"
+    "@esbuild/linux-mips64el": "npm:0.27.4"
+    "@esbuild/linux-ppc64": "npm:0.27.4"
+    "@esbuild/linux-riscv64": "npm:0.27.4"
+    "@esbuild/linux-s390x": "npm:0.27.4"
+    "@esbuild/linux-x64": "npm:0.27.4"
+    "@esbuild/netbsd-arm64": "npm:0.27.4"
+    "@esbuild/netbsd-x64": "npm:0.27.4"
+    "@esbuild/openbsd-arm64": "npm:0.27.4"
+    "@esbuild/openbsd-x64": "npm:0.27.4"
+    "@esbuild/openharmony-arm64": "npm:0.27.4"
+    "@esbuild/sunos-x64": "npm:0.27.4"
+    "@esbuild/win32-arm64": "npm:0.27.4"
+    "@esbuild/win32-ia32": "npm:0.27.4"
+    "@esbuild/win32-x64": "npm:0.27.4"
   dependenciesMeta:
     "@esbuild/aix-ppc64":
       optional: true
@@ -3492,7 +3492,7 @@ __metadata:
       optional: true
   bin:
     esbuild: bin/esbuild
-  checksum: 10c0/fdc3f87a3f08b3ef98362f37377136c389a0d180fda4b8d073b26ba930cf245521db0a368f119cc7624bc619248fff1439f5811f062d853576f8ffa3df8ee5f1
+  checksum: 10c0/2a1c2bcccda279f2afd72a7f8259860cb4483b32453d17878e1ecb4ac416b9e7c1001e7aa0a25ba4c29c1e250a3ceaae5d8bb72a119815bc8db4e9b5f5321490
   languageName: node
   linkType: hard
 
@@ -3906,6 +3906,7 @@ __metadata:
     "@types/react": "npm:^18.2.0"
     oxlint: "npm:^0.16.0"
     react: "npm:^18.2.0"
+    twenty-client-sdk: "portal:../../twenty-client-sdk"
     twenty-sdk: "portal:../../twenty-sdk"
     typescript: "npm:^5.9.3"
     vite-tsconfig-paths: "npm:^4.2.1"
@@ -4952,9 +4953,9 @@ __metadata:
   linkType: hard
 
 "preact@npm:^10.28.3":
-  version: 10.28.4
-  resolution: "preact@npm:10.28.4"
-  checksum: 10c0/712384e92d6c676c8f4c230eab81329a66acfecf700390aebfe5fc46168fa3686345d47f2292068dcc0a6d86425a3d9a3d743730e356e867a8402442afb989db
+  version: 10.29.0
+  resolution: "preact@npm:10.29.0"
+  checksum: 10c0/d111381e5b48335e3a797a03adb83521cf5e9bdf880570fb2eff4fe9da9c82e6dedcbdf54538b1ed8f60bf813a0df0f4891b03dc32140ad93f8f720a8812dd5c
   languageName: node
   linkType: hard
 
@@ -5750,6 +5751,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"twenty-client-sdk@portal:../../twenty-client-sdk::locator=hello-world%40workspace%3A.":
+  version: 0.0.0-use.local
+  resolution: "twenty-client-sdk@portal:../../twenty-client-sdk::locator=hello-world%40workspace%3A."
+  dependencies:
+    "@genql/cli": "npm:^3.0.3"
+    "@genql/runtime": "npm:^2.10.0"
+    esbuild: "npm:^0.25.0"
+    graphql: "npm:^16.8.1"
+  languageName: node
+  linkType: soft
+
 "twenty-sdk@portal:../../twenty-sdk::locator=hello-world%40workspace%3A.":
   version: 0.0.0-use.local
   resolution: "twenty-sdk@portal:../../twenty-sdk::locator=hello-world%40workspace%3A."

packages/twenty-apps/internal/call-recording/README.md

@@ -5,7 +5,7 @@ This is a [Twenty](https://twenty.com) application project bootstrapped with [`c
 First, authenticate to your workspace:
 
 ```bash
-yarn twenty remote add --local
+yarn twenty remote add http://localhost:2020 --as local
 ```
 
 Then, start development mode to sync your app and watch for changes:
@@ -22,7 +22,7 @@ Run `yarn twenty help` to list all available commands. Common commands:
 
 ```bash
 # Remotes & Authentication
-yarn twenty remote add --local     # Authenticate with Twenty
+yarn twenty remote add http://localhost:2020 --as local     # Authenticate with Twenty
 yarn twenty remote status         # Check auth status
 yarn twenty remote switch         # Switch default remote
 yarn twenty remote list           # List all configured remotes

packages/twenty-client-sdk/.oxlintrc.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "import", "unicorn"],
+  "categories": {
+    "correctness": "off"
+  },
+  "ignorePatterns": ["node_modules", "dist", "generated"],
+  "rules": {
+    "func-style": ["error", "declaration", { "allowArrowFunctions": true }],
+    "no-console": "off",
+    "no-control-regex": "off",
+    "no-debugger": "error",
+    "no-duplicate-imports": "error",
+    "no-undef": "off",
+    "no-unused-vars": "off",
+    "no-redeclare": "off",
+    "import/no-duplicates": "error",
+    "typescript/no-redeclare": "error",
+    "typescript/ban-ts-comment": "error",
+    "typescript/consistent-type-imports": [
+      "error",
+      {
+        "prefer": "type-imports",
+        "fixStyle": "inline-type-imports"
+      }
+    ],
+    "typescript/explicit-function-return-type": "off",
+    "typescript/explicit-module-boundary-types": "off",
+    "typescript/no-empty-object-type": [
+      "error",
+      {
+        "allowInterfaces": "with-single-extends"
+      }
+    ],
+    "typescript/no-empty-function": "off",
+    "typescript/no-explicit-any": "off",
+    "typescript/no-unused-vars": [
+      "warn",
+      {
+        "vars": "all",
+        "varsIgnorePattern": "^_",
+        "args": "after-used",
+        "argsIgnorePattern": "^_"
+      }
+    ]
+  }
+}

packages/twenty-client-sdk/.prettierignore

@@ -0,0 +1,2 @@
+dist
+generated

packages/twenty-client-sdk/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "twenty-client-sdk",
+  "version": "0.8.0-canary.6",
+  "sideEffects": false,
+  "license": "AGPL-3.0",
+  "scripts": {
+    "build": "npx rimraf dist && npx vite build && tsgo -p tsconfig.lib.json --declaration --emitDeclarationOnly --noEmit false --outDir dist --rootDir src && npx tsc-alias -p tsconfig.lib.json --outDir dist"
+  },
+  "exports": {
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core.mjs",
+      "require": "./dist/core.cjs"
+    },
+    "./metadata": {
+      "types": "./dist/metadata/index.d.ts",
+      "import": "./dist/metadata.mjs",
+      "require": "./dist/metadata.cjs"
+    },
+    "./generate": {
+      "types": "./dist/generate/index.d.ts",
+      "import": "./dist/generate.mjs",
+      "require": "./dist/generate.cjs"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "core": [
+        "dist/core/index.d.ts"
+      ],
+      "metadata": [
+        "dist/metadata/index.d.ts"
+      ],
+      "generate": [
+        "dist/generate/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@genql/cli": "^3.0.3",
+    "@genql/runtime": "^2.10.0",
+    "esbuild": "^0.25.0",
+    "graphql": "^16.8.1"
+  },
+  "devDependencies": {
+    "twenty-shared": "workspace:*",
+    "typescript": "^5.9.2",
+    "vite": "^7.0.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-tsconfig-paths": "^4.2.1",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": "^24.5.0",
+    "yarn": "^4.0.2"
+  }
+}

packages/twenty-client-sdk/project.json

@@ -0,0 +1,44 @@
+{
+  "name": "twenty-client-sdk",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/twenty-client-sdk/src",
+  "projectType": "library",
+  "tags": ["scope:sdk"],
+  "targets": {
+    "build": {
+      "executor": "nx:run-commands",
+      "cache": true,
+      "inputs": ["production", "^production"],
+      "dependsOn": ["^build"],
+      "outputs": ["{projectRoot}/dist"],
+      "options": {
+        "cwd": "{projectRoot}",
+        "commands": [
+          "npx rimraf dist && npx vite build",
+          "tsgo -p tsconfig.lib.json --declaration --emitDeclarationOnly --noEmit false --outDir dist --rootDir src && npx tsc-alias -p tsconfig.lib.json --outDir dist"
+        ],
+        "parallel": false
+      }
+    },
+    "generate-metadata-client": {
+      "executor": "nx:run-commands",
+      "cache": false,
+      "dependsOn": ["^build"],
+      "outputs": ["{projectRoot}/src/metadata/generated"],
+      "options": {
+        "cwd": "packages/twenty-client-sdk",
+        "command": "tsx scripts/generate-metadata-client.ts"
+      }
+    },
+    "test": {
+      "executor": "@nx/vitest:test",
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "config": "{projectRoot}/vitest.config.ts"
+      }
+    },
+    "set-local-version": {},
+    "typecheck": {},
+    "lint": {}
+  }
+}

packages/twenty-client-sdk/scripts/generate-metadata-client.ts

@@ -0,0 +1,65 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getIntrospectionQuery, buildClientSchema, printSchema } from 'graphql';
+
+import { generateMetadataClient } from '../src/generate/generate-metadata-client';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const TEMPLATE_PATH = path.resolve(
+  __dirname,
+  '..',
+  'src',
+  'generate',
+  'twenty-client-template.ts',
+);
+
+const introspectSchema = async (url: string): Promise<string> => {
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query: getIntrospectionQuery() }),
+  });
+
+  const json = await response.json();
+
+  if (json.errors) {
+    throw new Error(
+      `GraphQL introspection errors: ${JSON.stringify(json.errors)}`,
+    );
+  }
+
+  return printSchema(buildClientSchema(json.data));
+};
+
+const main = async () => {
+  const serverUrl = process.env.TWENTY_API_URL ?? 'http://localhost:3000';
+
+  const schema = await introspectSchema(`${serverUrl}/metadata`);
+
+  const clientWrapperTemplateSource = await readFile(TEMPLATE_PATH, 'utf-8');
+
+  const outputPath = path.resolve(
+    __dirname,
+    '..',
+    'src',
+    'metadata',
+    'generated',
+  );
+
+  await generateMetadataClient({
+    schema,
+    outputPath,
+    clientWrapperTemplateSource,
+  });
+
+  console.log(`Metadata client generated at ${outputPath}`);
+};
+
+main().catch((error) => {
+  console.error('Failed to generate metadata client:', error);
+  process.exit(1);
+});

packages/twenty-client-sdk/src/core/generated/index.ts

@@ -0,0 +1,10 @@
+// Stub — replaced at runtime by the generated client when the app
+// is installed on a Twenty instance or during `twenty app:dev`.
+export class CoreApiClient {
+  constructor() {
+    throw new Error(
+      'CoreApiClient was not generated. ' +
+        'Install this app on a Twenty instance or run `twenty app:dev`.',
+    );
+  }
+}

packages/twenty-client-sdk/src/core/index.ts

@@ -0,0 +1,2 @@
+export { CoreApiClient } from './generated/index';
+export * as CoreSchema from './generated/schema';

packages/twenty-client-sdk/src/generate/__tests__/client-wrapper-auth.test.ts

@@ -1,8 +1,10 @@
-import { transform } from 'esbuild';
-import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
+
+import { transform } from 'esbuild';
 import {
   afterAll,
   beforeAll,
@@ -13,17 +15,12 @@ import {
   vi,
 } from 'vitest';
 
-vi.mock('@/cli/constants/clients-dir', () => ({
-  CLIENTS_GENERATED_DIR: 'src/clients/generated',
-}));
+import { buildClientWrapperSource } from '../client-wrapper';
 
-vi.mock('twenty-shared/application', () => ({
-  DEFAULT_APP_ACCESS_TOKEN_NAME: 'TWENTY_APP_ACCESS_TOKEN',
-  DEFAULT_API_KEY_NAME: 'TWENTY_API_KEY',
-  DEFAULT_API_URL_NAME: 'TWENTY_API_URL',
-}));
-
-import { ClientService } from '@/cli/utilities/client/client-service';
+const twentyClientTemplateSource = readFileSync(
+  join(__dirname, '..', 'twenty-client-template.ts'),
+  'utf-8',
+);
 
 type TwentyClassType = new (options?: {
   url?: string;
@@ -110,59 +107,33 @@ const getAuthorizationHeaderValue = (requestInit: RequestInit | undefined) => {
   return new Headers(requestInit?.headers).get('Authorization');
 };
 
-describe('ClientService generated Twenty auth behavior', () => {
-  let temporaryGeneratedClientDirectory: string;
+describe('Generated client wrapper auth behavior', () => {
+  let temporaryDir: string;
   let TwentyClass: TwentyClassType;
 
   beforeAll(async () => {
-    temporaryGeneratedClientDirectory = await mkdtemp(
-      join(tmpdir(), 'twenty-generated-client-'),
-    );
+    temporaryDir = await mkdtemp(join(tmpdir(), 'twenty-generated-client-'));
 
-    const temporaryGeneratedIndexTsPath = join(
-      temporaryGeneratedClientDirectory,
-      'index.ts',
-    );
-
-    await writeFile(temporaryGeneratedIndexTsPath, stubGeneratedIndexSource);
-
-    const clientService = new ClientService();
-    await (
-      clientService as unknown as {
-        injectClientWrapper: (
-          output: string,
-          options: {
-            apiClientName: string;
-            defaultUrl: string;
-            includeUploadFile: boolean;
-          },
-        ) => Promise<void>;
-      }
-    ).injectClientWrapper(temporaryGeneratedClientDirectory, {
+    const wrapperSource = buildClientWrapperSource(twentyClientTemplateSource, {
       apiClientName: 'MetadataApiClient',
       defaultUrl: '`${process.env.TWENTY_API_URL}/metadata`',
       includeUploadFile: true,
     });
 
-    const generatedIndexContent = await readFile(
-      temporaryGeneratedIndexTsPath,
-      'utf-8',
-    );
+    const fullSource = stubGeneratedIndexSource + wrapperSource;
 
-    const transpiledModule = await transform(generatedIndexContent, {
+    const transpiledModule = await transform(fullSource, {
       loader: 'ts',
       format: 'esm',
       target: 'es2022',
     });
 
-    const temporaryGeneratedIndexMjsPath = join(
-      temporaryGeneratedClientDirectory,
-      'index.mjs',
-    );
-    await writeFile(temporaryGeneratedIndexMjsPath, transpiledModule.code);
+    const outputPath = join(temporaryDir, 'index.mjs');
+
+    await writeFile(outputPath, transpiledModule.code);
 
     const generatedModule = await import(
-      `${pathToFileURL(temporaryGeneratedIndexMjsPath).href}?t=${Date.now()}`
+      `${pathToFileURL(outputPath).href}?t=${Date.now()}`
     );
 
     TwentyClass = generatedModule.MetadataApiClient as TwentyClassType;
@@ -176,11 +147,8 @@ describe('ClientService generated Twenty auth behavior', () => {
   });
 
   afterAll(async () => {
-    if (temporaryGeneratedClientDirectory) {
-      await rm(temporaryGeneratedClientDirectory, {
-        recursive: true,
-        force: true,
-      });
+    if (temporaryDir) {
+      await rm(temporaryDir, { recursive: true, force: true });
     }
   });
 
@@ -303,6 +271,7 @@ describe('ClientService generated Twenty auth behavior', () => {
       .fn<() => Promise<string>>()
       .mockImplementation(async () => {
         await Promise.resolve();
+
         return 'fresh-token';
       });
 

packages/twenty-client-sdk/src/generate/client-wrapper.ts

@@ -0,0 +1,51 @@
+type ClientWrapperOptions = {
+  apiClientName: string;
+  defaultUrl: string;
+  includeUploadFile: boolean;
+};
+
+const STRIPPED_TYPES_START = '// __STRIPPED_DURING_INJECTION_START__';
+const STRIPPED_TYPES_END = '// __STRIPPED_DURING_INJECTION_END__';
+const UPLOAD_FILE_START = '// __UPLOAD_FILE_START__';
+const UPLOAD_FILE_END = '// __UPLOAD_FILE_END__';
+
+const escapeRegExp = (value: string): string =>
+  value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+export const buildClientWrapperSource = (
+  templateSource: string,
+  options: ClientWrapperOptions,
+): string => {
+  let source = templateSource;
+
+  source = source.replace(
+    new RegExp(
+      `${escapeRegExp(STRIPPED_TYPES_START)}[\\s\\S]*?${escapeRegExp(STRIPPED_TYPES_END)}\\n?`,
+    ),
+    '',
+  );
+
+  source = source.replace("'__TWENTY_DEFAULT_URL__'", options.defaultUrl);
+
+  source = source.replace(/TwentyGeneratedClient/g, options.apiClientName);
+
+  if (!options.includeUploadFile) {
+    source = source.replace(
+      new RegExp(
+        `\\s*${escapeRegExp(UPLOAD_FILE_START)}[\\s\\S]*?${escapeRegExp(UPLOAD_FILE_END)}\\n?`,
+      ),
+      '\n',
+    );
+  } else {
+    source = source.replace(
+      new RegExp(`\\s*${escapeRegExp(UPLOAD_FILE_START)}\\n`),
+      '\n',
+    );
+    source = source.replace(
+      new RegExp(`\\s*${escapeRegExp(UPLOAD_FILE_END)}\\n`),
+      '\n',
+    );
+  }
+
+  return `\n// ${options.apiClientName} (auto-injected by twenty-client-sdk)\n${source}`;
+};

packages/twenty-client-sdk/src/generate/fs-utils.ts

@@ -0,0 +1,41 @@
+import { cp, mkdir, readdir, rename as fsRename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export const ensureDir = (dirPath: string) =>
+  mkdir(dirPath, { recursive: true });
+
+export const emptyDir = async (dirPath: string): Promise<void> => {
+  let entries: string[];
+
+  try {
+    entries = await readdir(dirPath);
+  } catch (error: unknown) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      await mkdir(dirPath, { recursive: true });
+      return;
+    }
+    throw error;
+  }
+
+  await Promise.all(
+    entries.map((entry) =>
+      rm(join(dirPath, entry), { recursive: true, force: true }),
+    ),
+  );
+};
+
+export const move = async (src: string, dest: string): Promise<void> => {
+  try {
+    await fsRename(src, dest);
+  } catch (error: unknown) {
+    if (error instanceof Error && 'code' in error && error.code === 'EXDEV') {
+      await cp(src, dest, { recursive: true });
+      await rm(src, { recursive: true, force: true });
+    } else {
+      throw error;
+    }
+  }
+};
+
+export const remove = (filePath: string) =>
+  rm(filePath, { recursive: true, force: true });

packages/twenty-client-sdk/src/generate/generate-core-client.ts

@@ -0,0 +1,122 @@
+import { appendFile, copyFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { generate } from '@genql/cli';
+import { build } from 'esbuild';
+import { DEFAULT_API_URL_NAME } from 'twenty-shared/application';
+
+import { buildClientWrapperSource } from './client-wrapper';
+import { emptyDir, ensureDir, move, remove } from './fs-utils';
+import twentyClientTemplateSource from './twenty-client-template.ts?raw';
+
+const COMMON_SCALAR_TYPES = {
+  DateTime: 'string',
+  JSON: 'Record<string, unknown>',
+  UUID: 'string',
+};
+
+export const GENERATED_CORE_DIR = 'core/generated';
+
+// Generates the core API client from a GraphQL schema string.
+// Produces both TypeScript source and compiled ESM/CJS bundles.
+export const generateCoreClientFromSchema = async ({
+  schema,
+  outputPath,
+  clientWrapperTemplateSource,
+}: {
+  schema: string;
+  outputPath: string;
+  clientWrapperTemplateSource?: string;
+}): Promise<void> => {
+  const templateSource =
+    clientWrapperTemplateSource ?? twentyClientTemplateSource;
+  const tempPath = `${outputPath}.tmp`;
+
+  await ensureDir(tempPath);
+  await emptyDir(tempPath);
+
+  try {
+    await generate({
+      schema,
+      output: tempPath,
+      scalarTypes: COMMON_SCALAR_TYPES,
+    });
+
+    const clientContent = buildClientWrapperSource(templateSource, {
+      apiClientName: 'CoreApiClient',
+      defaultUrl: `\`\${process.env.${DEFAULT_API_URL_NAME}}/graphql\``,
+      includeUploadFile: true,
+    });
+
+    await appendFile(join(tempPath, 'index.ts'), clientContent);
+
+    await remove(outputPath);
+    await move(tempPath, outputPath);
+
+    await compileGeneratedClient(outputPath);
+  } catch (error) {
+    await remove(tempPath);
+    throw error;
+  }
+};
+
+// Generates the core client and replaces the pre-built stub inside
+// an installed twenty-client-sdk package (dist/core.mjs and dist/core.cjs).
+// Generated source files are kept in dist/generated-core/ for consumers
+// that need the raw .ts files (e.g. the app:dev upload step).
+export const replaceCoreClient = async ({
+  packageRoot,
+  schema,
+}: {
+  packageRoot: string;
+  schema: string;
+}): Promise<void> => {
+  const generatedPath = join(packageRoot, 'dist', GENERATED_CORE_DIR);
+
+  await generateCoreClientFromSchema({ schema, outputPath: generatedPath });
+
+  await copyFile(
+    join(generatedPath, 'index.mjs'),
+    join(packageRoot, 'dist', 'core.mjs'),
+  );
+  await copyFile(
+    join(generatedPath, 'index.cjs'),
+    join(packageRoot, 'dist', 'core.cjs'),
+  );
+};
+
+const compileGeneratedClient = async (generatedDir: string): Promise<void> => {
+  const entryPoint = join(generatedDir, 'index.ts');
+  const outfile = join(generatedDir, 'index.mjs');
+
+  await build({
+    entryPoints: [entryPoint],
+    outfile,
+    bundle: true,
+    format: 'esm',
+    platform: 'node',
+    target: 'node18',
+    sourcemap: false,
+    minify: false,
+  });
+
+  await build({
+    entryPoints: [entryPoint],
+    outfile: join(generatedDir, 'index.cjs'),
+    bundle: true,
+    format: 'cjs',
+    platform: 'node',
+    target: 'node18',
+    sourcemap: false,
+    minify: false,
+  });
+
+  await writeFile(
+    join(generatedDir, 'package.json'),
+    JSON.stringify(
+      { type: 'module', main: 'index.mjs', module: 'index.mjs' },
+      null,
+      2,
+    ),
+  );
+};

packages/twenty-client-sdk/src/generate/generate-metadata-client.ts

@@ -0,0 +1,48 @@
+import { appendFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { generate } from '@genql/cli';
+import { DEFAULT_API_URL_NAME } from 'twenty-shared/application';
+
+import { buildClientWrapperSource } from './client-wrapper';
+import { emptyDir, ensureDir } from './fs-utils';
+import twentyClientTemplateSource from './twenty-client-template.ts?raw';
+
+const COMMON_SCALAR_TYPES = {
+  DateTime: 'string',
+  JSON: 'Record<string, unknown>',
+  UUID: 'string',
+};
+
+export const generateMetadataClient = async ({
+  schema,
+  outputPath,
+  clientWrapperTemplateSource,
+}: {
+  schema: string;
+  outputPath: string;
+  clientWrapperTemplateSource?: string;
+}): Promise<void> => {
+  const templateSource =
+    clientWrapperTemplateSource ?? twentyClientTemplateSource;
+
+  await ensureDir(outputPath);
+  await emptyDir(outputPath);
+
+  await generate({
+    schema,
+    output: outputPath,
+    scalarTypes: {
+      ...COMMON_SCALAR_TYPES,
+      Upload: 'File',
+    },
+  });
+
+  const clientContent = buildClientWrapperSource(templateSource, {
+    apiClientName: 'MetadataApiClient',
+    defaultUrl: `\`\${process.env.${DEFAULT_API_URL_NAME}}/metadata\``,
+    includeUploadFile: true,
+  });
+
+  await appendFile(join(outputPath, 'index.ts'), clientContent);
+};

packages/twenty-client-sdk/src/generate/index.ts

@@ -0,0 +1,6 @@
+export {
+  GENERATED_CORE_DIR,
+  generateCoreClientFromSchema,
+  replaceCoreClient,
+} from './generate-core-client';
+export { generateMetadataClient } from './generate-metadata-client';

packages/twenty-client-sdk/src/generate/raw-imports.d.ts

@@ -0,0 +1,4 @@
+declare module '*.ts?raw' {
+  const content: string;
+  export default content;
+}

packages/twenty-client-sdk/src/generate/twenty-client-template.ts

@@ -0,0 +1,434 @@
+// Ambient type stubs for the genql-generated code this template gets
+// injected into. They enable full typecheck/lint on this file.
+// __STRIPPED_DURING_INJECTION_START__
+type QueryGenqlSelection = Record<string, unknown>;
+type MutationGenqlSelection = Record<string, unknown>;
+type GraphqlOperation = Record<string, unknown>;
+
+type ClientOptions = {
+  url?: string;
+  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+  fetcher?: (
+    operation: GraphqlOperation | GraphqlOperation[],
+  ) => Promise<unknown>;
+  fetch?: typeof globalThis.fetch;
+  batch?: unknown;
+};
+
+type Client = {
+  query: (
+    request: QueryGenqlSelection & { __name?: string },
+  ) => Promise<unknown>;
+  mutation: (
+    request: MutationGenqlSelection & { __name?: string },
+  ) => Promise<unknown>;
+};
+
+declare function createClient(options: ClientOptions): Client;
+
+declare class GenqlError extends Error {
+  constructor(errors: unknown, data: unknown);
+}
+// __STRIPPED_DURING_INJECTION_END__
+
+const APP_ACCESS_TOKEN_ENV_KEY = 'TWENTY_APP_ACCESS_TOKEN';
+const API_KEY_ENV_KEY = 'TWENTY_API_KEY';
+
+type TwentyGeneratedClientOptions = ClientOptions;
+
+type ProcessEnvironment = Record<string, string | undefined>;
+
+type GraphqlErrorPayloadEntry = {
+  message?: string;
+  extensions?: { code?: string };
+};
+
+type GraphqlResponsePayload = {
+  data?: Record<string, unknown>;
+  errors?: GraphqlErrorPayloadEntry[];
+};
+
+type GraphqlResponse = {
+  status: number;
+  statusText: string;
+  payload: GraphqlResponsePayload | null;
+  rawBody: string;
+};
+
+const getProcessEnvironment = (): ProcessEnvironment => {
+  const processObject = (
+    globalThis as { process?: { env?: ProcessEnvironment } }
+  ).process;
+
+  return processObject?.env ?? {};
+};
+
+const getTokenFromAuthorizationHeader = (
+  authorizationHeader: string | undefined,
+): string | null => {
+  if (typeof authorizationHeader !== 'string') {
+    return null;
+  }
+
+  const trimmedAuthorizationHeader = authorizationHeader.trim();
+
+  if (trimmedAuthorizationHeader.length === 0) {
+    return null;
+  }
+
+  if (trimmedAuthorizationHeader === 'Bearer') {
+    return null;
+  }
+
+  if (trimmedAuthorizationHeader.startsWith('Bearer ')) {
+    return trimmedAuthorizationHeader.slice('Bearer '.length).trim();
+  }
+
+  return trimmedAuthorizationHeader;
+};
+
+const getTokenFromHeaders = (
+  headers: HeadersInit | undefined,
+): string | null => {
+  if (!headers) {
+    return null;
+  }
+
+  if (headers instanceof Headers) {
+    return getTokenFromAuthorizationHeader(
+      headers.get('Authorization') ?? undefined,
+    );
+  }
+
+  if (Array.isArray(headers)) {
+    const matchedAuthorizationHeader = headers.find(
+      ([headerName]) => headerName.toLowerCase() === 'authorization',
+    );
+
+    return getTokenFromAuthorizationHeader(matchedAuthorizationHeader?.[1]);
+  }
+
+  const headersRecord = headers as Record<string, string | undefined>;
+
+  return getTokenFromAuthorizationHeader(
+    headersRecord.Authorization ?? headersRecord.authorization,
+  );
+};
+
+const hasAuthenticationErrorInGraphqlPayload = (
+  payload: GraphqlResponsePayload | null,
+): boolean => {
+  if (!payload?.errors) {
+    return false;
+  }
+
+  return payload.errors.some((graphqlError) => {
+    return (
+      graphqlError.extensions?.code === 'UNAUTHENTICATED' ||
+      graphqlError.message?.toLowerCase() === 'unauthorized'
+    );
+  });
+};
+
+const defaultOptions: TwentyGeneratedClientOptions = {
+  url: '__TWENTY_DEFAULT_URL__',
+  headers: {
+    'Content-Type': 'application/json',
+  },
+};
+
+export class TwentyGeneratedClient {
+  private client: Client;
+  private url: string;
+  private requestOptions: RequestInit;
+  private headers: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+  private fetchImplementation: typeof globalThis.fetch | null;
+  private authorizationToken: string | null;
+  private refreshAccessTokenPromise: Promise<string | null> | null = null;
+
+  constructor(options?: TwentyGeneratedClientOptions) {
+    const merged: TwentyGeneratedClientOptions = {
+      ...defaultOptions,
+      ...options,
+    };
+
+    const {
+      url,
+      headers,
+      fetch: customFetchImplementation,
+      fetcher: _fetcher,
+      batch: _batch,
+      ...requestOptions
+    } = merged;
+
+    this.url = url ?? '';
+    this.requestOptions = requestOptions;
+    this.headers = headers ?? {};
+    this.fetchImplementation =
+      customFetchImplementation ?? globalThis.fetch ?? null;
+
+    const processEnvironment = getProcessEnvironment();
+    const tokenFromHeaders = getTokenFromHeaders(
+      typeof headers === 'function' ? undefined : headers,
+    );
+
+    // Priority: explicit header > app access token > api key (legacy).
+    this.authorizationToken =
+      tokenFromHeaders ??
+      processEnvironment[APP_ACCESS_TOKEN_ENV_KEY] ??
+      processEnvironment[API_KEY_ENV_KEY] ??
+      null;
+
+    this.client = createClient({
+      ...merged,
+      headers: undefined,
+      fetcher: async (operation) =>
+        this.executeGraphqlRequestWithOptionalRefresh({
+          operation,
+        }),
+    });
+  }
+
+  query<R extends QueryGenqlSelection>(request: R & { __name?: string }) {
+    return this.client.query(request);
+  }
+
+  mutation<R extends MutationGenqlSelection>(request: R & { __name?: string }) {
+    return this.client.mutation(request);
+  }
+
+  // __UPLOAD_FILE_START__
+  async uploadFile(
+    fileBuffer: Buffer,
+    filename: string,
+    contentType: string = 'application/octet-stream',
+    fieldMetadataUniversalIdentifier: string,
+  ): Promise<{
+    id: string;
+    path: string;
+    size: number;
+    createdAt: string;
+    url: string;
+  }> {
+    const form = new FormData();
+
+    form.append(
+      'operations',
+      JSON.stringify({
+        query: `mutation UploadFilesFieldFileByUniversalIdentifier($file: Upload!, $fieldMetadataUniversalIdentifier: String!) {
+        uploadFilesFieldFileByUniversalIdentifier(file: $file, fieldMetadataUniversalIdentifier: $fieldMetadataUniversalIdentifier) { id path size createdAt url }
+      }`,
+        variables: {
+          file: null,
+          fieldMetadataUniversalIdentifier,
+        },
+      }),
+    );
+    form.append('map', JSON.stringify({ '0': ['variables.file'] }));
+    form.append(
+      '0',
+      new Blob([fileBuffer as BlobPart], { type: contentType }),
+      filename,
+    );
+
+    const result = await this.executeGraphqlRequestWithOptionalRefresh({
+      operation: form,
+      headers: {},
+      requestInit: {
+        method: 'POST',
+      },
+    });
+
+    if (result.errors) {
+      throw new GenqlError(result.errors, result.data);
+    }
+
+    const data = result.data as Record<string, unknown>;
+
+    return data.uploadFilesFieldFileByUniversalIdentifier as {
+      id: string;
+      path: string;
+      size: number;
+      createdAt: string;
+      url: string;
+    };
+  }
+  // __UPLOAD_FILE_END__
+
+  private async executeGraphqlRequestWithOptionalRefresh({
+    operation,
+    headers,
+    requestInit,
+  }: {
+    operation: GraphqlOperation | GraphqlOperation[] | FormData;
+    headers?: HeadersInit;
+    requestInit?: RequestInit;
+  }) {
+    const firstResponse = await this.executeGraphqlRequest({
+      operation,
+      headers,
+      requestInit,
+      token: this.authorizationToken,
+    });
+
+    if (this.shouldRefreshToken(firstResponse)) {
+      const refreshedAccessToken = await this.requestRefreshedAccessToken();
+
+      if (refreshedAccessToken) {
+        const retryResponse = await this.executeGraphqlRequest({
+          operation,
+          headers,
+          requestInit,
+          token: refreshedAccessToken,
+        });
+
+        return this.assertResponseIsSuccessful(retryResponse);
+      }
+    }
+
+    return this.assertResponseIsSuccessful(firstResponse);
+  }
+
+  private async executeGraphqlRequest({
+    operation,
+    headers,
+    requestInit,
+    token,
+  }: {
+    operation: GraphqlOperation | GraphqlOperation[] | FormData;
+    headers?: HeadersInit;
+    requestInit?: RequestInit;
+    token: string | null;
+  }): Promise<GraphqlResponse> {
+    if (!this.fetchImplementation) {
+      throw new Error(
+        'Global `fetch` function is not available, ' +
+          'pass a fetch implementation to the Twenty client',
+      );
+    }
+
+    const resolvedHeaders = await this.resolveHeaders();
+    const requestHeaders = new Headers(resolvedHeaders);
+
+    if (headers) {
+      new Headers(headers).forEach((value, key) =>
+        requestHeaders.set(key, value),
+      );
+    }
+
+    if (operation instanceof FormData) {
+      requestHeaders.delete('Content-Type');
+    } else {
+      requestHeaders.set('Content-Type', 'application/json');
+    }
+
+    if (token) {
+      requestHeaders.set('Authorization', `Bearer ${token}`);
+    } else {
+      requestHeaders.delete('Authorization');
+    }
+
+    const response = await this.fetchImplementation.call(globalThis, this.url, {
+      ...this.requestOptions,
+      ...requestInit,
+      method: requestInit?.method ?? 'POST',
+      headers: requestHeaders,
+      body:
+        operation instanceof FormData ? operation : JSON.stringify(operation),
+    });
+
+    const rawBody = await response.text();
+    let payload: GraphqlResponsePayload | null = null;
+
+    if (rawBody.trim().length > 0) {
+      try {
+        payload = JSON.parse(rawBody) as GraphqlResponsePayload;
+      } catch {
+        payload = null;
+      }
+    }
+
+    return {
+      status: response.status,
+      statusText: response.statusText,
+      payload,
+      rawBody,
+    };
+  }
+
+  private async resolveHeaders(): Promise<HeadersInit> {
+    if (typeof this.headers === 'function') {
+      return (await this.headers()) ?? {};
+    }
+
+    return this.headers ?? {};
+  }
+
+  private shouldRefreshToken(response: GraphqlResponse): boolean {
+    if (response.status === 401) {
+      return true;
+    }
+
+    return hasAuthenticationErrorInGraphqlPayload(response.payload);
+  }
+
+  private assertResponseIsSuccessful(response: GraphqlResponse) {
+    if (response.status < 200 || response.status >= 300) {
+      throw new Error(`${response.statusText}: ${response.rawBody}`);
+    }
+
+    if (response.payload === null) {
+      throw new Error('Invalid JSON response');
+    }
+
+    return response.payload;
+  }
+
+  private async requestRefreshedAccessToken(): Promise<string | null> {
+    const refreshAccessTokenFunction = (
+      globalThis as {
+        frontComponentHostCommunicationApi?: {
+          requestAccessTokenRefresh?: () => Promise<string>;
+        };
+      }
+    ).frontComponentHostCommunicationApi?.requestAccessTokenRefresh;
+
+    if (typeof refreshAccessTokenFunction !== 'function') {
+      return null;
+    }
+
+    if (!this.refreshAccessTokenPromise) {
+      this.refreshAccessTokenPromise = refreshAccessTokenFunction()
+        .then((refreshedAccessToken) => {
+          if (
+            typeof refreshedAccessToken !== 'string' ||
+            refreshedAccessToken.length === 0
+          ) {
+            return null;
+          }
+
+          this.setAuthorizationToken(refreshedAccessToken);
+
+          return refreshedAccessToken;
+        })
+        .catch((refreshError: unknown) => {
+          console.error('Twenty client: token refresh failed', refreshError);
+
+          return null;
+        })
+        .finally(() => {
+          this.refreshAccessTokenPromise = null;
+        });
+    }
+
+    return this.refreshAccessTokenPromise;
+  }
+
+  private setAuthorizationToken(token: string) {
+    this.authorizationToken = token;
+
+    const processEnvironment = getProcessEnvironment();
+
+    processEnvironment[APP_ACCESS_TOKEN_ENV_KEY] = token;
+  }
+}

packages/twenty-client-sdk/src/metadata/generated/index.ts

@@ -78,7 +78,7 @@ export const generateSubscriptionOp: (
   )
 }
 
-// MetadataApiClient (auto-injected by twenty-sdk)
+// MetadataApiClient (auto-injected by twenty-client-sdk)
 // Ambient type stubs for the genql-generated code this template gets
 // injected into. They enable full typecheck/lint on this file.
 

packages/twenty-client-sdk/src/metadata/index.ts

@@ -0,0 +1,2 @@
+export { MetadataApiClient } from './generated/index';
+export * as MetadataSchema from './generated/schema';

packages/twenty-client-sdk/tsconfig.json

@@ -0,0 +1,32 @@
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "rootDir": ".",
+    "sourceMap": true,
+    "declaration": false,
+    "moduleResolution": "node",
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "importHelpers": true,
+    "target": "es2018",
+    "module": "esnext",
+    "lib": ["es2020", "dom"],
+    "skipLibCheck": true,
+    "skipDefaultLibCheck": true,
+    "resolveJsonModule": true,
+    "allowJs": false,
+    "esModuleInterop": false,
+    "allowSyntheticDefaultImports": true,
+    "strictNullChecks": true,
+    "alwaysStrict": true,
+    "noImplicitAny": true,
+    "strictBindCallApply": false,
+    "noEmit": true,
+    "types": ["node"],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*.ts", "vite.config.ts"],
+  "exclude": ["node_modules", "dist"]
+}

packages/twenty-client-sdk/tsconfig.lib.json

@@ -0,0 +1,17 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "declaration": false,
+    "sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}

packages/twenty-client-sdk/vite.config.ts

@@ -0,0 +1,78 @@
+import path from 'path';
+import { defineConfig } from 'vite';
+import tsconfigPaths from 'vite-tsconfig-paths';
+import packageJson from './package.json';
+
+const entries = [
+  'src/core/index.ts',
+  'src/metadata/index.ts',
+  'src/generate/index.ts',
+];
+
+const entryFileNames = (chunk: any, extension: 'cjs' | 'mjs') => {
+  if (!chunk.isEntry) {
+    throw new Error(
+      `Should never occur, encountered a non entry chunk ${chunk.facadeModuleId}`,
+    );
+  }
+
+  const splitFaceModuleId = chunk.facadeModuleId?.split('/');
+  if (splitFaceModuleId === undefined) {
+    throw new Error(
+      `Should never occur, splitFaceModuleId is undefined ${chunk.facadeModuleId}`,
+    );
+  }
+
+  const moduleDirectory = splitFaceModuleId[splitFaceModuleId?.length - 2];
+  if (moduleDirectory === 'src') {
+    return `${chunk.name}.${extension}`;
+  }
+  return `${moduleDirectory}.${extension}`;
+};
+
+export default defineConfig(() => {
+  return {
+    root: __dirname,
+    cacheDir: '../../node_modules/.vite/packages/twenty-client-sdk',
+    resolve: {
+      alias: {
+        '@/': path.resolve(__dirname, 'src') + '/',
+      },
+    },
+    plugins: [
+      tsconfigPaths({
+        root: __dirname,
+      }),
+    ],
+    build: {
+      emptyOutDir: false,
+      outDir: 'dist',
+      lib: { entry: entries, name: 'twenty-client-sdk' },
+      rollupOptions: {
+        external: [
+          ...Object.keys((packageJson as any).dependencies || {}),
+          ...Object.keys((packageJson as any).devDependencies || {}).filter(
+            (dep: string) => dep !== 'twenty-shared',
+          ),
+          'node:fs/promises',
+          'node:fs',
+          'node:path',
+        ],
+        output: [
+          {
+            format: 'es',
+            entryFileNames: (chunk) => entryFileNames(chunk, 'mjs'),
+          },
+          {
+            format: 'cjs',
+            interop: 'auto',
+            esModule: true,
+            exports: 'named',
+            entryFileNames: (chunk) => entryFileNames(chunk, 'cjs'),
+          },
+        ],
+      },
+    },
+    logLevel: 'warn',
+  };
+});

packages/twenty-client-sdk/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    name: 'twenty-client-sdk',
+    environment: 'node',
+    include: [
+      'src/**/__tests__/**/*.{test,spec}.{ts,tsx}',
+      'src/**/*.{test,spec}.{ts,tsx}',
+    ],
+    exclude: ['**/node_modules/**', '**/.git/**'],
+    globals: true,
+  },
+});

packages/twenty-companion/package.json

@@ -5,7 +5,7 @@
   "description": "Twenty meeting recorder",
   "main": ".webpack/main",
   "scripts": {
-    "start": "concurrently \"npm run start:server\" \"npm run start:electron\"",
+    "start": "concurrently \"yarn start:server\" \"yarn start:electron\"",
     "start:electron": "electron-forge start",
     "package": "electron-forge package",
     "make": "electron-forge make",
@@ -37,10 +37,8 @@
     "node-loader": "^2.1.0",
     "style-loader": "^3.3.4"
   },
-  "overrides": {
-    "@electron/packager": {
-      "@electron/osx-sign": "github:recallai/osx-sign"
-    }
+  "resolutions": {
+    "@electron/packager/@electron/osx-sign": "github:recallai/osx-sign"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.40.1",

packages/twenty-docker/.env.example

@@ -16,3 +16,5 @@ STORAGE_TYPE=local
 # STORAGE_S3_REGION=eu-west3
 # STORAGE_S3_NAME=my-bucket
 # STORAGE_S3_ENDPOINT=
+# STORAGE_S3_ACCESS_KEY_ID=
+# STORAGE_S3_SECRET_ACCESS_KEY=

packages/twenty-docker/Makefile

@@ -18,7 +18,7 @@ DOCKER_NETWORK=twenty_network
 # =============================================================================
 
 prod-build:
-	@cd ../.. && docker build -f ./packages/twenty-docker/twenty/Dockerfile --platform $(PLATFORM) --tag twenty:$(TAG) . && cd -
+	@cd ../.. && docker build --target twenty -f ./packages/twenty-docker/twenty/Dockerfile --platform $(PLATFORM) --tag twenty:$(TAG) . && cd -
 
 prod-run:
 	@docker run -d -p 3000:3000 --name twenty twenty:$(TAG)

packages/twenty-docker/twenty-app-dev/Dockerfile

@@ -1,130 +0,0 @@
-ARG APP_VERSION
-
-# === Stage 1: Common dependencies ===
-FROM node:22-alpine AS common-deps
-
-WORKDIR /app
-
-COPY ./package.json ./yarn.lock ./.yarnrc.yml ./tsconfig.base.json ./nx.json /app/
-COPY ./.yarn/releases /app/.yarn/releases
-COPY ./.yarn/patches /app/.yarn/patches
-
-COPY ./packages/twenty-emails/package.json /app/packages/twenty-emails/
-COPY ./packages/twenty-server/package.json /app/packages/twenty-server/
-COPY ./packages/twenty-server/patches /app/packages/twenty-server/patches
-COPY ./packages/twenty-ui/package.json /app/packages/twenty-ui/
-COPY ./packages/twenty-shared/package.json /app/packages/twenty-shared/
-COPY ./packages/twenty-front/package.json /app/packages/twenty-front/
-COPY ./packages/twenty-sdk/package.json /app/packages/twenty-sdk/
-
-RUN yarn && yarn cache clean && npx nx reset
-
-# === Stage 2: Build server from source ===
-FROM common-deps AS twenty-server-build
-
-COPY ./packages/twenty-emails /app/packages/twenty-emails
-COPY ./packages/twenty-shared /app/packages/twenty-shared
-COPY ./packages/twenty-ui /app/packages/twenty-ui
-COPY ./packages/twenty-sdk /app/packages/twenty-sdk
-COPY ./packages/twenty-server /app/packages/twenty-server
-
-RUN npx nx run twenty-server:build
-RUN yarn workspaces focus --production twenty-emails twenty-shared twenty-sdk twenty-server
-
-# === Stage 3: Build frontend from source ===
-# Requires ~10GB Docker memory. To skip, pre-build on host first:
-#   npx nx build twenty-front
-# The COPY below will pick up packages/twenty-front/build/ if it exists.
-FROM common-deps AS twenty-front-build
-COPY --from=twenty-server-build /app/package.json /tmp/.build-sentinel
-
-COPY ./packages/twenty-front /app/packages/twenty-front
-COPY ./packages/twenty-ui /app/packages/twenty-ui
-COPY ./packages/twenty-shared /app/packages/twenty-shared
-COPY ./packages/twenty-sdk /app/packages/twenty-sdk
-RUN if [ -d /app/packages/twenty-front/build ]; then \
-      echo "Using pre-built frontend from host"; \
-    else \
-      NODE_OPTIONS="--max-old-space-size=8192" npx nx build twenty-front; \
-    fi
-
-# === Stage 4: s6-overlay ===
-FROM alpine:3.20 AS s6-fetch
-ARG S6_OVERLAY_VERSION=3.2.0.2
-ARG TARGETARCH
-RUN if [ "$TARGETARCH" = "arm64" ]; then echo "aarch64" > /tmp/s6arch; \
-    else echo "x86_64" > /tmp/s6arch; fi
-RUN S6_ARCH=$(cat /tmp/s6arch) && \
-    wget -O /tmp/s6-overlay-noarch.tar.xz \
-      "https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-noarch.tar.xz" && \
-    wget -O /tmp/s6-overlay-noarch.tar.xz.sha256 \
-      "https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-noarch.tar.xz.sha256" && \
-    wget -O /tmp/s6-overlay-arch.tar.xz \
-      "https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-${S6_ARCH}.tar.xz" && \
-    wget -O /tmp/s6-overlay-arch.tar.xz.sha256 \
-      "https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-${S6_ARCH}.tar.xz.sha256" && \
-    cd /tmp && \
-    NOARCH_SUM=$(awk '{print $1}' s6-overlay-noarch.tar.xz.sha256) && \
-    ARCH_SUM=$(awk '{print $1}' s6-overlay-arch.tar.xz.sha256) && \
-    echo "$NOARCH_SUM  s6-overlay-noarch.tar.xz" | sha256sum -c - && \
-    echo "$ARCH_SUM  s6-overlay-arch.tar.xz" | sha256sum -c -
-
-# === Stage 5: Final all-in-one image ===
-FROM node:22-alpine
-
-# s6-overlay
-COPY --from=s6-fetch /tmp/s6-overlay-noarch.tar.xz /tmp/
-COPY --from=s6-fetch /tmp/s6-overlay-arch.tar.xz /tmp/
-RUN tar -C / -Jxpf /tmp/s6-overlay-noarch.tar.xz \
- && tar -C / -Jxpf /tmp/s6-overlay-arch.tar.xz \
- && rm /tmp/s6-overlay-*.tar.xz
-
-# Infrastructure: Postgres, Redis, and utilities
-RUN apk add --no-cache \
-    postgresql16 postgresql16-contrib \
-    redis \
-    curl jq su-exec
-
-# tsx for database setup scripts
-RUN npm install -g tsx
-
-# Twenty application (both server and frontend built from source)
-COPY --from=twenty-server-build /app /app
-COPY --from=twenty-front-build /app/packages/twenty-front/build /app/packages/twenty-server/dist/front
-
-# s6 service definitions
-COPY packages/twenty-docker/twenty-app-dev/rootfs/ /
-
-# Data directories
-RUN mkdir -p /data/postgres /data/redis /app/.local-storage \
- && chown -R postgres:postgres /data/postgres \
- && chown 1000:1000 /data/redis /app/.local-storage
-
-ARG REACT_APP_SERVER_BASE_URL
-ARG APP_VERSION=0.0.0
-
-# Tell s6-overlay to preserve container environment variables
-ENV S6_KEEP_ENV=1
-
-# Environment defaults
-ENV PG_DATABASE_URL=postgres://twenty:twenty@localhost:5432/default \
-    SERVER_URL=http://localhost:2020 \
-    REDIS_URL=redis://localhost:6379 \
-    STORAGE_TYPE=local \
-    APP_SECRET=twenty-app-dev-secret-not-for-production \
-    REACT_APP_SERVER_BASE_URL=$REACT_APP_SERVER_BASE_URL \
-    APP_VERSION=$APP_VERSION \
-    NODE_ENV=development \
-    NODE_PORT=3000 \
-    DISABLE_DB_MIGRATIONS=true \
-    DISABLE_CRON_JOBS_REGISTRATION=true \
-    IS_BILLING_ENABLED=false \
-    SIGN_IN_PREFILLED=true
-
-EXPOSE 3000
-VOLUME ["/data/postgres", "/app/.local-storage"]
-
-LABEL org.opencontainers.image.source=https://github.com/twentyhq/twenty
-LABEL org.opencontainers.image.description="All-in-one Twenty image for local development and SDK usage. Includes PostgreSQL, Redis, server, and worker."
-
-ENTRYPOINT ["/init"]

packages/twenty-docker/twenty-app-dev/rootfs/etc/s6-overlay/scripts/init-db.sh

@@ -32,11 +32,11 @@ has_schema=$(PGPASSWORD=twenty psql -h localhost -U twenty -d default -tAc \
 
 if [ "$has_schema" = "f" ]; then
   echo "Database appears to be empty, running initial setup..."
-  NODE_OPTIONS="--max-old-space-size=1500" tsx ./scripts/setup-db.ts
+  NODE_OPTIONS="--max-old-space-size=1500" node ./dist/database/scripts/setup-db.js
 fi
 
 # Always run migrations (idempotent — skips already-applied ones)
-yarn database:migrate:prod
+yarn database:migrate:prod --force
 
 yarn command:prod cache:flush
 yarn command:prod upgrade

packages/twenty-docker/twenty/Dockerfile

@@ -1,9 +1,11 @@
-# Base image for common dependencies
+# ===========================================================================
+# Shared build stages (used by both targets)
+# ===========================================================================
+
 FROM node:24-alpine AS common-deps
 
 WORKDIR /app
 
-# Copy only the necessary files for dependency resolution
 COPY ./package.json ./yarn.lock ./.yarnrc.yml ./tsconfig.base.json ./nx.json /app/
 COPY ./.yarn/releases /app/.yarn/releases
 COPY ./.yarn/patches /app/.yarn/patches
@@ -15,19 +17,18 @@ COPY ./packages/twenty-ui/package.json /app/packages/twenty-ui/
 COPY ./packages/twenty-shared/package.json /app/packages/twenty-shared/
 COPY ./packages/twenty-front/package.json /app/packages/twenty-front/
 COPY ./packages/twenty-sdk/package.json /app/packages/twenty-sdk/
+COPY ./packages/twenty-client-sdk/package.json /app/packages/twenty-client-sdk/
 
-# Install all dependencies
 RUN yarn && yarn cache clean && npx nx reset
 
 
-# Build the back
 FROM common-deps AS twenty-server-build
 
-# Copy sourcecode after installing dependences to accelerate subsequents builds
 COPY ./packages/twenty-emails /app/packages/twenty-emails
 COPY ./packages/twenty-shared /app/packages/twenty-shared
 COPY ./packages/twenty-ui /app/packages/twenty-ui
 COPY ./packages/twenty-sdk /app/packages/twenty-sdk
+COPY ./packages/twenty-client-sdk /app/packages/twenty-client-sdk
 COPY ./packages/twenty-server /app/packages/twenty-server
 
 RUN npx nx run twenty-server:lingui:extract && \
@@ -37,9 +38,14 @@ RUN npx nx run twenty-server:lingui:extract && \
 
 RUN npx nx run twenty-server:build
 
-RUN yarn workspaces focus --production twenty-emails twenty-shared twenty-sdk twenty-server
+# Clean server build output (type declarations and compiled tests are not needed at runtime;
+# source maps are kept because twenty-infra extracts them from the image for Sentry uploads)
+RUN find /app/packages/twenty-server/dist -name '*.d.ts' -delete \
+ && rm -rf /app/packages/twenty-server/dist/packages/twenty-server/test
+
+RUN yarn workspaces focus --production twenty-emails twenty-shared twenty-sdk twenty-client-sdk twenty-server
+
 
-# Build the front
 FROM common-deps AS twenty-front-build
 
 ARG REACT_APP_SERVER_BASE_URL
@@ -48,20 +54,27 @@ COPY ./packages/twenty-front /app/packages/twenty-front
 COPY ./packages/twenty-ui /app/packages/twenty-ui
 COPY ./packages/twenty-shared /app/packages/twenty-shared
 COPY ./packages/twenty-sdk /app/packages/twenty-sdk
+COPY ./packages/twenty-client-sdk /app/packages/twenty-client-sdk
 RUN npx nx run twenty-front:lingui:extract && \
     npx nx run twenty-front:lingui:compile
-RUN npx nx build twenty-front
+# To skip the memory-intensive frontend build, pre-build on the host:
+#   npx nx build twenty-front
+# The check below will use packages/twenty-front/build/ if it already exists.
+RUN if [ -d /app/packages/twenty-front/build ]; then \
+      echo "Using pre-built frontend from host"; \
+    else \
+      NODE_OPTIONS="--max-old-space-size=8192" npx nx build twenty-front; \
+    fi
 
 
-# Final stage: Run the application
+# ===========================================================================
+# Target: twenty (production)
+#   docker build --target twenty -f packages/twenty-docker/twenty/Dockerfile .
+# ===========================================================================
+
 FROM node:24-alpine AS twenty
 
-# Used to run healthcheck in docker
-RUN apk add --no-cache curl jq
-
-RUN npm install -g tsx
-
-RUN apk add --no-cache postgresql-client
+RUN apk add --no-cache curl jq postgresql-client
 
 COPY ./packages/twenty-docker/twenty/entrypoint.sh /app/entrypoint.sh
 RUN chmod +x /app/entrypoint.sh
@@ -73,20 +86,139 @@ ENV REACT_APP_SERVER_BASE_URL=$REACT_APP_SERVER_BASE_URL
 ARG APP_VERSION
 ENV APP_VERSION=$APP_VERSION
 
-# Copy built applications from previous stages
-COPY --chown=1000 --from=twenty-server-build /app /app
-COPY --chown=1000 --from=twenty-server-build /app/packages/twenty-server /app/packages/twenty-server
+# Workspace root config
+COPY --chown=1000 --from=twenty-server-build /app/package.json /app/yarn.lock /app/.yarnrc.yml /app/
+COPY --chown=1000 --from=twenty-server-build /app/tsconfig.base.json /app/nx.json /app/
+COPY --chown=1000 --from=twenty-server-build /app/.yarn /app/.yarn
+COPY --chown=1000 --from=twenty-server-build /app/node_modules /app/node_modules
+
+# Server package (compiled dist + package.json only, no src/)
+COPY --chown=1000 --from=twenty-server-build /app/packages/twenty-server/package.json /app/packages/twenty-server/
+COPY --chown=1000 --from=twenty-server-build /app/packages/twenty-server/dist /app/packages/twenty-server/dist
+COPY --chown=1000 --from=twenty-server-build /app/packages/twenty-server/patches /app/packages/twenty-server/patches
+
+# Workspace packages (dist + package.json; node_modules symlinks resolve to these)
+COPY --chown=1000 --from=twenty-server-build /app/packages/twenty-shared/package.json /app/packages/twenty-shared/
+COPY --chown=1000 --from=twenty-server-build /app/packages/twenty-shared/dist /app/packages/twenty-shared/dist
+COPY --chown=1000 --from=twenty-server-build /app/packages/twenty-emails/package.json /app/packages/twenty-emails/
+COPY --chown=1000 --from=twenty-server-build /app/packages/twenty-emails/dist /app/packages/twenty-emails/dist
+COPY --chown=1000 --from=twenty-server-build /app/packages/twenty-sdk/package.json /app/packages/twenty-sdk/
+COPY --chown=1000 --from=twenty-server-build /app/packages/twenty-client-sdk/package.json /app/packages/twenty-client-sdk/
+COPY --chown=1000 --from=twenty-server-build /app/packages/twenty-client-sdk/dist /app/packages/twenty-client-sdk/dist
+COPY --chown=1000 --from=twenty-server-build /app/packages/twenty-ui/package.json /app/packages/twenty-ui/
+COPY --chown=1000 --from=twenty-server-build /app/packages/twenty-front/package.json /app/packages/twenty-front/
+
+# Frontend static build
 COPY --chown=1000 --from=twenty-front-build /app/packages/twenty-front/build /app/packages/twenty-server/dist/front
 
-# Set metadata and labels
 LABEL org.opencontainers.image.source=https://github.com/twentyhq/twenty
-LABEL org.opencontainers.image.description="This image provides a consistent and reproducible environment for the backend and frontend, ensuring it deploys faster and runs the same way regardless of the deployment environment."
+LABEL org.opencontainers.image.description="Production Twenty image with backend and frontend."
 
 RUN mkdir -p /app/.local-storage /app/packages/twenty-server/.local-storage && \
-    chown -R 1000:1000 /app
+    chown 1000:1000 /app/.local-storage /app/packages/twenty-server/.local-storage
 
-# Use non root user with uid 1000
 USER 1000
 
 CMD ["node", "dist/main"]
 ENTRYPOINT ["/app/entrypoint.sh"]
+
+
+# ===========================================================================
+# Target: twenty-app-dev (all-in-one with Postgres + Redis)
+#   docker build --target twenty-app-dev -f packages/twenty-docker/twenty/Dockerfile .
+# ===========================================================================
+
+FROM alpine:3.20 AS s6-fetch
+ARG S6_OVERLAY_VERSION=3.2.0.2
+ARG TARGETARCH
+RUN if [ "$TARGETARCH" = "arm64" ]; then echo "aarch64" > /tmp/s6arch; \
+    else echo "x86_64" > /tmp/s6arch; fi
+RUN S6_ARCH=$(cat /tmp/s6arch) && \
+    wget -O /tmp/s6-overlay-noarch.tar.xz \
+      "https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-noarch.tar.xz" && \
+    wget -O /tmp/s6-overlay-noarch.tar.xz.sha256 \
+      "https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-noarch.tar.xz.sha256" && \
+    wget -O /tmp/s6-overlay-arch.tar.xz \
+      "https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-${S6_ARCH}.tar.xz" && \
+    wget -O /tmp/s6-overlay-arch.tar.xz.sha256 \
+      "https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-${S6_ARCH}.tar.xz.sha256" && \
+    cd /tmp && \
+    NOARCH_SUM=$(awk '{print $1}' s6-overlay-noarch.tar.xz.sha256) && \
+    ARCH_SUM=$(awk '{print $1}' s6-overlay-arch.tar.xz.sha256) && \
+    echo "$NOARCH_SUM  s6-overlay-noarch.tar.xz" | sha256sum -c - && \
+    echo "$ARCH_SUM  s6-overlay-arch.tar.xz" | sha256sum -c -
+
+FROM node:24-alpine AS twenty-app-dev
+
+# s6-overlay
+COPY --from=s6-fetch /tmp/s6-overlay-noarch.tar.xz /tmp/
+COPY --from=s6-fetch /tmp/s6-overlay-arch.tar.xz /tmp/
+RUN tar -C / -Jxpf /tmp/s6-overlay-noarch.tar.xz \
+ && tar -C / -Jxpf /tmp/s6-overlay-arch.tar.xz \
+ && rm /tmp/s6-overlay-*.tar.xz
+
+RUN apk add --no-cache \
+    postgresql16 postgresql16-contrib \
+    redis \
+    curl jq su-exec
+
+# Workspace root config
+COPY --from=twenty-server-build /app/package.json /app/yarn.lock /app/.yarnrc.yml /app/
+COPY --from=twenty-server-build /app/tsconfig.base.json /app/nx.json /app/
+COPY --from=twenty-server-build /app/.yarn /app/.yarn
+COPY --from=twenty-server-build /app/node_modules /app/node_modules
+
+# Server package (compiled dist + package.json only, no src/)
+COPY --from=twenty-server-build /app/packages/twenty-server/package.json /app/packages/twenty-server/
+COPY --from=twenty-server-build /app/packages/twenty-server/dist /app/packages/twenty-server/dist
+COPY --from=twenty-server-build /app/packages/twenty-server/patches /app/packages/twenty-server/patches
+
+# Workspace packages (dist + package.json; node_modules symlinks resolve to these)
+COPY --from=twenty-server-build /app/packages/twenty-shared/package.json /app/packages/twenty-shared/
+COPY --from=twenty-server-build /app/packages/twenty-shared/dist /app/packages/twenty-shared/dist
+COPY --from=twenty-server-build /app/packages/twenty-emails/package.json /app/packages/twenty-emails/
+COPY --from=twenty-server-build /app/packages/twenty-emails/dist /app/packages/twenty-emails/dist
+COPY --from=twenty-server-build /app/packages/twenty-sdk/package.json /app/packages/twenty-sdk/
+COPY --from=twenty-server-build /app/packages/twenty-client-sdk/package.json /app/packages/twenty-client-sdk/
+COPY --from=twenty-server-build /app/packages/twenty-client-sdk/dist /app/packages/twenty-client-sdk/dist
+COPY --from=twenty-server-build /app/packages/twenty-ui/package.json /app/packages/twenty-ui/
+COPY --from=twenty-server-build /app/packages/twenty-front/package.json /app/packages/twenty-front/
+
+# Frontend static build
+COPY --from=twenty-front-build /app/packages/twenty-front/build /app/packages/twenty-server/dist/front
+
+# Source maps are not needed in the dev image (no Sentry)
+RUN find /app/packages/twenty-server/dist -name '*.js.map' -delete
+
+# s6 service definitions
+COPY packages/twenty-docker/twenty-app-dev/rootfs/ /
+
+RUN mkdir -p /data/postgres /data/redis /app/.local-storage \
+ && chown -R postgres:postgres /data/postgres \
+ && chown 1000:1000 /data/redis /app/.local-storage
+
+ARG REACT_APP_SERVER_BASE_URL
+ARG APP_VERSION=0.0.0
+
+ENV S6_KEEP_ENV=1
+ENV PG_DATABASE_URL=postgres://twenty:twenty@localhost:5432/default \
+    SERVER_URL=http://localhost:2020 \
+    REDIS_URL=redis://localhost:6379 \
+    STORAGE_TYPE=local \
+    APP_SECRET=twenty-app-dev-secret-not-for-production \
+    REACT_APP_SERVER_BASE_URL=$REACT_APP_SERVER_BASE_URL \
+    APP_VERSION=$APP_VERSION \
+    NODE_ENV=development \
+    NODE_PORT=3000 \
+    DISABLE_DB_MIGRATIONS=true \
+    DISABLE_CRON_JOBS_REGISTRATION=true \
+    IS_BILLING_ENABLED=false \
+    SIGN_IN_PREFILLED=true
+
+EXPOSE 3000
+VOLUME ["/data/postgres", "/app/.local-storage"]
+
+LABEL org.opencontainers.image.source=https://github.com/twentyhq/twenty
+LABEL org.opencontainers.image.description="All-in-one Twenty image for local development and SDK usage. Includes PostgreSQL, Redis, server, and worker."
+
+ENTRYPOINT ["/init"]

packages/twenty-docker/twenty/entrypoint.sh

@@ -13,8 +13,7 @@ setup_and_migrate_db() {
     has_schema=$(psql -tAc "SELECT EXISTS (SELECT 1 FROM information_schema.schemata WHERE schema_name = 'core')" ${PG_DATABASE_URL})
     if [ "$has_schema" = "f" ]; then
         echo "Database appears to be empty, running migrations."
-        NODE_OPTIONS="--max-old-space-size=1500" tsx ./scripts/setup-db.ts
-        yarn database:migrate:prod
+        yarn database:init:prod
     fi
 
     yarn command:prod cache:flush

packages/twenty-docs/developers/extend/apps/building.mdx

@@ -19,15 +19,17 @@ The SDK provides helper functions for defining your app entities. As described i
 |----------|---------|
 | `defineApplication` | Configure application metadata (required, one per app) |
 | `defineObject` | Define custom objects with fields |
+| `defineField` | Extend existing objects with additional fields or define standalone relation fields |
 | `defineLogicFunction` | Define logic functions with handlers |
 | `definePreInstallLogicFunction` | Define a pre-install logic function (one per app) |
 | `definePostInstallLogicFunction` | Define a post-install logic function (one per app) |
 | `defineFrontComponent` | Define front components for custom UI |
 | `defineRole` | Configure role permissions and object access |
-| `defineField` | Extend existing objects with additional fields |
 | `defineView` | Define saved views for objects |
 | `defineNavigationMenuItem` | Define sidebar navigation links |
 | `defineSkill` | Define AI agent skills |
+| `defineAgent` | Define AI agents |
+| `definePageLayout` | Define custom page layouts |
 
 These functions validate your configuration at build time and provide IDE autocompletion and type safety.
 
@@ -36,7 +38,7 @@ These functions validate your configuration at build time and provide IDE autoco
 Custom objects describe both schema and behavior for records in your workspace. Use `defineObject()` to define objects with built-in validation:
 
 ```typescript
-// src/app/postCard.object.ts
+// src/objects/postCard.object.ts
 import { defineObject, FieldType } from 'twenty-sdk';
 
 enum PostCardStatus {
@@ -110,7 +112,7 @@ Key points:
 - The `universalIdentifier` must be unique and stable across deployments.
 - Each field requires a `name`, `type`, `label`, and its own stable `universalIdentifier`.
 - The `fields` array is optional — you can define objects without custom fields.
-- You can scaffold new objects using `yarn twenty entity:add`, which guides you through naming, fields, and relationships.
+- You can scaffold new objects using `yarn twenty add`, which guides you through naming, fields, and relationships.
 
 <Note>
 **Base fields are created automatically.** When you define a custom object, Twenty automatically adds standard fields
@@ -120,6 +122,195 @@ Key points:
   but this is not recommended.
 </Note>
 
+### Defining fields on existing objects
+
+Use `defineField()` to add fields to objects you don't own — such as standard Twenty objects (Person, Company, etc.) or objects from other apps. Unlike inline fields in `defineObject()`, standalone fields require an `objectUniversalIdentifier` to specify which object they extend:
+
+```typescript
+// src/fields/company-loyalty-tier.field.ts
+import { defineField, FieldType } from 'twenty-sdk';
+
+export default defineField({
+  universalIdentifier: 'f2a1b3c4-d5e6-7890-abcd-ef1234567890',
+  objectUniversalIdentifier: '701aecb9-eb1c-4d84-9d94-b954b231b64b', // Company object
+  name: 'loyaltyTier',
+  type: FieldType.SELECT,
+  label: 'Loyalty Tier',
+  icon: 'IconStar',
+  options: [
+    { value: 'BRONZE', label: 'Bronze', position: 0, color: 'orange' },
+    { value: 'SILVER', label: 'Silver', position: 1, color: 'gray' },
+    { value: 'GOLD', label: 'Gold', position: 2, color: 'yellow' },
+  ],
+});
+```
+
+Key points:
+- `objectUniversalIdentifier` identifies the target object. For standard objects, use `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` exported from `twenty-sdk`.
+- When defining fields inline in `defineObject()`, you do **not** need `objectUniversalIdentifier` — it's inherited from the parent object.
+- `defineField()` is the only way to add fields to objects you didn't create with `defineObject()`.
+
+### Relations
+
+Relations connect objects together. In Twenty, relations are always **bidirectional** — you define both sides, and each side references the other.
+
+There are two relation types:
+
+| Relation type | Description | Has foreign key? |
+|---------------|-------------|-----------------|
+| `MANY_TO_ONE` | Many records of this object point to one record of the target | Yes (`joinColumnName`) |
+| `ONE_TO_MANY` | One record of this object has many records of the target | No (inverse side) |
+
+#### How relations work
+
+Every relation requires **two fields** that reference each other:
+
+1. The **MANY_TO_ONE** side — lives on the object that holds the foreign key
+2. The **ONE_TO_MANY** side — lives on the object that owns the collection
+
+Both fields use `FieldType.RELATION` and cross-reference each other via `relationTargetFieldMetadataUniversalIdentifier`.
+
+#### Example: Post Card has many Recipients
+
+Suppose a `PostCard` can be sent to many `PostCardRecipient` records. Each recipient belongs to exactly one post card.
+
+**Step 1: Define the ONE_TO_MANY side on PostCard** (the "one" side):
+
+```typescript
+// src/fields/post-card-recipients-on-post-card.field.ts
+import { defineField, FieldType, RelationType } from 'twenty-sdk';
+import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
+import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
+
+// Export so the other side can reference it
+export const POST_CARD_RECIPIENTS_FIELD_ID = 'a1111111-1111-1111-1111-111111111111';
+// Import from the other side
+import { POST_CARD_FIELD_ID } from './post-card-on-post-card-recipient.field';
+
+export default defineField({
+  universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
+  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
+  type: FieldType.RELATION,
+  name: 'postCardRecipients',
+  label: 'Post Card Recipients',
+  icon: 'IconUsers',
+  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
+  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
+  universalSettings: {
+    relationType: RelationType.ONE_TO_MANY,
+  },
+});
+```
+
+**Step 2: Define the MANY_TO_ONE side on PostCardRecipient** (the "many" side — holds the foreign key):
+
+```typescript
+// src/fields/post-card-on-post-card-recipient.field.ts
+import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk';
+import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
+import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
+
+// Export so the other side can reference it
+export const POST_CARD_FIELD_ID = 'b2222222-2222-2222-2222-222222222222';
+// Import from the other side
+import { POST_CARD_RECIPIENTS_FIELD_ID } from './post-card-recipients-on-post-card.field';
+
+export default defineField({
+  universalIdentifier: POST_CARD_FIELD_ID,
+  objectUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
+  type: FieldType.RELATION,
+  name: 'postCard',
+  label: 'Post Card',
+  icon: 'IconMail',
+  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
+  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
+  universalSettings: {
+    relationType: RelationType.MANY_TO_ONE,
+    onDelete: OnDeleteAction.CASCADE,
+    joinColumnName: 'postCardId',
+  },
+});
+```
+
+<Note>
+**Circular imports:** Both relation fields reference each other's `universalIdentifier`. To avoid circular import issues, export your field IDs as named constants from each file, and import them in the other file. The build system resolves these at compile time.
+</Note>
+
+#### Relating to standard objects
+
+To create a relation with a built-in Twenty object (Person, Company, etc.), use `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`:
+
+```typescript
+// src/fields/person-on-self-hosting-user.field.ts
+import {
+  defineField,
+  FieldType,
+  RelationType,
+  OnDeleteAction,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk';
+import { SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER } from '../objects/self-hosting-user.object';
+
+export const PERSON_FIELD_ID = 'c3333333-3333-3333-3333-333333333333';
+export const SELF_HOSTING_USER_REVERSE_FIELD_ID = 'd4444444-4444-4444-4444-444444444444';
+
+export default defineField({
+  universalIdentifier: PERSON_FIELD_ID,
+  objectUniversalIdentifier: SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER,
+  type: FieldType.RELATION,
+  name: 'person',
+  label: 'Person',
+  description: 'Person matching with the self hosting user',
+  isNullable: true,
+  relationTargetObjectMetadataUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
+  relationTargetFieldMetadataUniversalIdentifier: SELF_HOSTING_USER_REVERSE_FIELD_ID,
+  universalSettings: {
+    relationType: RelationType.MANY_TO_ONE,
+    onDelete: OnDeleteAction.SET_NULL,
+    joinColumnName: 'personId',
+  },
+});
+```
+
+#### Relation field properties
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `type` | Yes | Must be `FieldType.RELATION` |
+| `relationTargetObjectMetadataUniversalIdentifier` | Yes | The `universalIdentifier` of the target object |
+| `relationTargetFieldMetadataUniversalIdentifier` | Yes | The `universalIdentifier` of the matching field on the target object |
+| `universalSettings.relationType` | Yes | `RelationType.MANY_TO_ONE` or `RelationType.ONE_TO_MANY` |
+| `universalSettings.onDelete` | MANY_TO_ONE only | What happens when the referenced record is deleted: `CASCADE`, `SET_NULL`, `RESTRICT`, or `NO_ACTION` |
+| `universalSettings.joinColumnName` | MANY_TO_ONE only | Database column name for the foreign key (e.g., `postCardId`) |
+
+#### Inline relation fields in defineObject
+
+You can also define relation fields directly inside `defineObject()`. In that case, omit `objectUniversalIdentifier` — it's inherited from the parent object:
+
+```typescript
+export default defineObject({
+  universalIdentifier: '...',
+  nameSingular: 'postCardRecipient',
+  // ...
+  fields: [
+    {
+      universalIdentifier: POST_CARD_FIELD_ID,
+      type: FieldType.RELATION,
+      name: 'postCard',
+      label: 'Post Card',
+      relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
+      relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
+      universalSettings: {
+        relationType: RelationType.MANY_TO_ONE,
+        onDelete: OnDeleteAction.CASCADE,
+        joinColumnName: 'postCardId',
+      },
+    },
+    // ... other fields
+  ],
+});
+```
 
 ### Application config (application-config.ts)
 
@@ -161,13 +352,29 @@ Notes:
 - `defaultRoleUniversalIdentifier` must match the role file (see below).
 - Pre-install and post-install functions are automatically detected during the manifest build. See [Pre-install functions](#pre-install-functions) and [Post-install functions](#post-install-functions).
 
+#### Marketplace metadata
+
+If you plan to [publish your app](/developers/extend/apps/publishing), these optional fields control how your app appears in the marketplace:
+
+| Field | Description |
+|-------|-------------|
+| `author` | Author or company name |
+| `category` | App category for marketplace filtering |
+| `logoUrl` | Path to your app logo (relative to `./assets/`) |
+| `screenshots` | Array of screenshot paths (relative to `./assets/`) |
+| `aboutDescription` | Longer markdown description for the "About" tab |
+| `websiteUrl` | Link to your website |
+| `termsUrl` | Link to terms of service |
+| `emailSupport` | Support email address |
+| `issueReportUrl` | Link to issue tracker |
+
 #### Roles and permissions
 
 Applications can define roles that encapsulate permissions on your workspace's objects and actions. The field `defaultRoleUniversalIdentifier` in `application-config.ts` designates the default role used by your app's logic functions.
 
 - The runtime API key injected as `TWENTY_API_KEY` is derived from this default function role.
 - The typed client will be restricted to the permissions granted to that role.
-- Follow least‑privilege: create a dedicated role with only the permissions your functions need, then reference its universal identifier.
+- Follow least-privilege: create a dedicated role with only the permissions your functions need, then reference its universal identifier.
 
 ##### Default function role (*.role.ts)
 
@@ -219,7 +426,7 @@ The `universalIdentifier` of this role is then referenced in `application-config
 - **application-config.ts** points to that role so your functions inherit its permissions.
 
 Notes:
-- Start from the scaffolded role, then progressively restrict it following least‑privilege.
+- Start from the scaffolded role, then progressively restrict it following least-privilege.
 - Replace the `objectPermissions` and `fieldPermissions` with the objects/fields your functions need.
 - `permissionFlags` control access to platform-level capabilities. Keep them minimal; add only what you need.
 - See a working example in the Hello World app: [`packages/twenty-apps/hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).
@@ -229,7 +436,7 @@ Notes:
 Each function file uses `defineLogicFunction()` to export a configuration with a handler and optional triggers.
 
 ```typescript
-// src/app/createPostCard.logic-function.ts
+// src/logic-functions/createPostCard.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
 import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk';
 import { CoreApiClient, type Person } from 'twenty-sdk/generated';
@@ -318,7 +525,7 @@ export default definePreInstallLogicFunction({
 You can also manually execute the pre-install function at any time using the CLI:
 
 ```bash filename="Terminal"
-yarn twenty function:execute --preInstall
+yarn twenty exec --preInstall
 ```
 
 Key points:
@@ -327,7 +534,7 @@ Key points:
 - Only one pre-install function is allowed per application. The manifest build will error if more than one is detected.
 - The function's `universalIdentifier` is automatically set as `preInstallLogicFunctionUniversalIdentifier` on the application manifest during the build — you do not need to reference it in `defineApplication()`.
 - The default timeout is set to 300 seconds (5 minutes) to allow for longer preparation tasks.
-- Pre-install functions do not need triggers — they are invoked by the platform before installation or manually via `function:execute --preInstall`.
+- Pre-install functions do not need triggers — they are invoked by the platform before installation or manually via `exec --preInstall`.
 
 ### Post-install functions
 
@@ -355,7 +562,7 @@ export default definePostInstallLogicFunction({
 You can also manually execute the post-install function at any time using the CLI:
 
 ```bash filename="Terminal"
-yarn twenty function:execute --postInstall
+yarn twenty exec --postInstall
 ```
 
 Key points:
@@ -364,7 +571,7 @@ Key points:
 - Only one post-install function is allowed per application. The manifest build will error if more than one is detected.
 - The function's `universalIdentifier` is automatically set as `postInstallLogicFunctionUniversalIdentifier` on the application manifest during the build — you do not need to reference it in `defineApplication()`.
 - The default timeout is set to 300 seconds (5 minutes) to allow for longer setup tasks like data seeding.
-- Post-install functions do not need triggers — they are invoked by the platform during installation or manually via `function:execute --postInstall`.
+- Post-install functions do not need triggers — they are invoked by the platform during installation or manually via `exec --postInstall`.
 
 ### Route trigger payload
 
@@ -412,7 +619,7 @@ The `RoutePayload` type has the following structure:
 |----------|------|-------------|
 | `headers` | `Record<string, string \| undefined>` | HTTP headers (only those listed in `forwardedRequestHeaders`) |
 | `queryStringParameters` | `Record<string, string \| undefined>` | Query string parameters (multiple values joined with commas) |
-| `pathParameters` | `Record<string, string \| undefined>` | Path parameters extracted from the route pattern (e.g., `/users/:id` → `{ id: '123' }`) |
+| `pathParameters` | `Record<string, string \| undefined>` | Path parameters extracted from the route pattern (e.g., `/users/:id` -> `{ id: '123' }`) |
 | `body` | `object \| null` | Parsed request body (JSON) |
 | `isBase64Encoded` | `boolean` | Whether the body is base64 encoded |
 | `requestContext.http.method` | `string` | HTTP method (GET, POST, PUT, PATCH, DELETE) |
@@ -458,7 +665,7 @@ const handler = async (event: RoutePayload) => {
 
 You can create new functions in two ways:
 
-- **Scaffolded**: Run `yarn twenty entity:add` and choose the option to add a new logic function. This generates a starter file with a handler and config.
+- **Scaffolded**: Run `yarn twenty add` and choose the option to add a new logic function. This generates a starter file with a handler and config.
 - **Manual**: Create a new `*.logic-function.ts` file and use `defineLogicFunction()`, following the same pattern.
 
 ### Marking a logic function as a tool
@@ -470,7 +677,7 @@ To mark a logic function as a tool, set `isTool: true` and provide a `toolInputS
 ```typescript
 // src/logic-functions/enrich-company.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-sdk/generated';
+import { CoreApiClient } from 'twenty-client-sdk/core';
 
 const handler = async (params: { companyName: string; domain?: string }) => {
   const client = new CoreApiClient();
@@ -554,11 +761,11 @@ export default defineFrontComponent({
 Key points:
 - Front components are React components that render in isolated contexts within Twenty.
 - The `component` field references your React component.
-- Components are built and synced automatically during `yarn twenty app:dev`.
+- Components are built and synced automatically during `yarn twenty dev`.
 
 You can create new front components in two ways:
 
-- **Scaffolded**: Run `yarn twenty entity:add` and choose the option to add a new front component.
+- **Scaffolded**: Run `yarn twenty add` and choose the option to add a new front component.
 - **Manual**: Create a new `.tsx` file and use `defineFrontComponent()`, following the same pattern.
 
 ### Skills
@@ -592,46 +799,122 @@ Key points:
 
 You can create new skills in two ways:
 
-- **Scaffolded**: Run `yarn twenty entity:add` and choose the option to add a new skill.
+- **Scaffolded**: Run `yarn twenty add` and choose the option to add a new skill.
 - **Manual**: Create a new file and use `defineSkill()`, following the same pattern.
 
-### Generated typed clients
+### Typed API clients (`twenty-client-sdk`)
 
-Two typed clients are auto-generated by `yarn twenty app:dev` and stored in `node_modules/twenty-sdk/generated` based on your workspace schema:
+The `twenty-client-sdk` package provides two typed GraphQL clients for interacting with the Twenty API from your logic functions and front components:
 
-- **`CoreApiClient`** — queries the `/graphql` endpoint for workspace data
-- **`MetadataApiClient`** — queries the `/metadata` endpoint for workspace configuration and file uploads
+| Client | Import | Endpoint | Generated? |
+|--------|--------|----------|------------|
+| `CoreApiClient` | `twenty-client-sdk/core` | `/graphql` — workspace data (records, objects) | Yes, at dev/build time |
+| `MetadataApiClient` | `twenty-client-sdk/metadata` | `/metadata` — workspace config, file uploads | No, ships pre-built |
+
+#### CoreApiClient
+
+`CoreApiClient` is the main client for querying and mutating workspace data. It is **generated from your workspace schema** during `yarn twenty dev` or `yarn twenty build`, so it's fully typed to match your objects and fields.
 
 ```typescript
-import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';
+import { CoreApiClient } from 'twenty-client-sdk/core';
 
 const client = new CoreApiClient();
-const { me } = await client.query({ me: { id: true, displayName: true } });
 
-const metadataClient = new MetadataApiClient();
-const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
+// Query records
+const { companies } = await client.query({
+  companies: {
+    edges: {
+      node: {
+        id: true,
+        name: true,
+        domainName: true,
+      },
+    },
+  },
+});
+
+// Create a record
+const { createCompany } = await client.mutation({
+  createCompany: {
+    __args: {
+      data: {
+        name: 'Acme Corp',
+      },
+    },
+    id: true,
+    name: true,
+  },
+});
 ```
 
-Both clients are re-generated automatically by `yarn twenty app:dev` whenever your objects or fields change.
+The client uses a selection-set syntax: pass `true` to include a field, use `__args` for arguments, and nest objects for relations. You get full autocompletion and type checking based on your workspace schema.
 
-#### Runtime credentials in logic functions
+<Note>
+**CoreApiClient is generated at dev/build time.** If you try to use it without running `yarn twenty dev` or `yarn twenty build` first, it throws an error. The generation happens automatically — the CLI introspects your workspace's GraphQL schema, generates a typed client using `@genql/cli`, writes the generated sources to `node_modules/twenty-client-sdk/dist/core/generated/`, and replaces the stubs in `node_modules/twenty-client-sdk/dist/core.mjs` and `node_modules/twenty-client-sdk/dist/core.cjs`.
+</Note>
 
-When your function runs on Twenty, the platform injects credentials as environment variables before your code executes:
+#### Using CoreSchema for type annotations
 
-- `TWENTY_API_URL`: Base URL of the Twenty API your app targets.
-- `TWENTY_API_KEY`: Short‑lived key scoped to your application's default function role.
+`CoreSchema` provides TypeScript types matching your workspace objects, useful for typing component state or function parameters:
 
-Notes:
-- You do not need to pass URL or API key to the generated client. It reads `TWENTY_API_URL` and `TWENTY_API_KEY` from process.env at runtime.
-- The API key's permissions are determined by the role referenced in your `application-config.ts` via `defaultRoleUniversalIdentifier`. This is the default role used by logic functions of your application.
-- Applications can define roles to follow least‑privilege. Grant only the permissions your functions need, then point `defaultRoleUniversalIdentifier` to that role's universal identifier.
+```typescript
+import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
+import { useState } from 'react';
+
+const [company, setCompany] = useState<
+  Pick<CoreSchema.Company, 'id' | 'name'> | undefined
+>(undefined);
+
+const client = new CoreApiClient();
+const result = await client.query({
+  company: {
+    __args: { filter: { position: { eq: 1 } } },
+    id: true,
+    name: true,
+  },
+});
+setCompany(result.company);
+```
+
+#### MetadataApiClient
+
+`MetadataApiClient` ships pre-built with the SDK (no generation required). It queries the `/metadata` endpoint for workspace configuration, applications, and file uploads:
+
+```typescript
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+
+const metadataClient = new MetadataApiClient();
+
+// Query workspace info
+const { currentWorkspace } = await metadataClient.query({
+  currentWorkspace: { id: true, displayName: true },
+});
+
+// List installed applications
+const { findManyApplications } = await metadataClient.query({
+  findManyApplications: {
+    id: true,
+    name: true,
+    version: true,
+  },
+});
+```
+
+#### Runtime credentials
+
+When your code runs on Twenty (logic functions or front components), the platform injects credentials as environment variables:
+
+- `TWENTY_API_URL` — Base URL of the Twenty API
+- `TWENTY_API_KEY` — Short-lived key scoped to your application's default function role
+
+You do **not** need to pass these to the clients — they read from `process.env` automatically. The API key's permissions are determined by the role referenced in `defaultRoleUniversalIdentifier` in your `application-config.ts`.
 
 #### Uploading files
 
-The generated `MetadataApiClient` includes an `uploadFile` method for attaching files to file-type fields on your workspace objects. Because standard GraphQL clients do not support multipart file uploads natively, the client provides this dedicated method that implements the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec) under the hood.
+`MetadataApiClient` includes an `uploadFile` method for attaching files to file-type fields. It implements the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec):
 
 ```typescript
-import { MetadataApiClient } from 'twenty-sdk/generated';
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
 import * as fs from 'fs';
 
 const metadataClient = new MetadataApiClient();
@@ -641,25 +924,14 @@ const fileBuffer = fs.readFileSync('./invoice.pdf');
 const uploadedFile = await metadataClient.uploadFile(
   fileBuffer,                                         // file contents as a Buffer
   'invoice.pdf',                                      // filename
-  'application/pdf',                                  // MIME type (defaults to 'application/octet-stream')
-  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universal identifier
+  'application/pdf',                                  // MIME type
+  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
 );
 
 console.log(uploadedFile);
 // { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
 ```
 
-The method signature:
-
-```typescript
-uploadFile(
-  fileBuffer: Buffer,
-  filename: string,
-  contentType: string,
-  fieldMetadataUniversalIdentifier: string,
-): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
-```
-
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `fileBuffer` | `Buffer` | The raw file contents |
@@ -668,8 +940,7 @@ uploadFile(
 | `fieldMetadataUniversalIdentifier` | `string` | The `universalIdentifier` of the file-type field on your object |
 
 Key points:
-- The `uploadFile` method is available on `MetadataApiClient` because the upload mutation is resolved by the `/metadata` endpoint.
-- It uses the field's `universalIdentifier` (not its workspace-specific ID), so your upload code works across any workspace where your app is installed — consistent with how apps reference fields everywhere else.
+- Uses the field's `universalIdentifier` (not its workspace-specific ID), so your upload code works across any workspace where your app is installed.
 - The returned `url` is a signed URL you can use to access the uploaded file.
 
 ### Hello World example

packages/twenty-docs/developers/extend/apps/getting-started.mdx

@@ -19,7 +19,7 @@ Apps let you extend Twenty with custom objects, fields, logic functions, AI skil
 ## Prerequisites
 
 - Node.js 24+ and Yarn 4
-- A Twenty workspace and an API key (create one at https://app.twenty.com/settings/api-webhooks)
+- Docker (for the local Twenty dev server)
 
 ## Getting Started
 
@@ -31,13 +31,13 @@ npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app
 
 # Start dev mode: automatically syncs local changes to your workspace
-yarn twenty app:dev
+yarn twenty dev
 ```
 
 The scaffolder supports two modes for controlling which example files are included:
 
 ```bash filename="Terminal"
-# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item, skill)
+# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item, skill, agent)
 npx create-twenty-app@latest my-app
 
 # Minimal: only core files (application-config.ts and default-role.ts)
@@ -48,7 +48,7 @@ From here you can:
 
 ```bash filename="Terminal"
 # Add a new entity to your application (guided)
-yarn twenty entity:add
+yarn twenty add
 
 # Watch your application's function logs
 yarn twenty function:logs
@@ -63,7 +63,7 @@ yarn twenty function:execute --preInstall
 yarn twenty function:execute --postInstall
 
 # Uninstall the application from the current workspace
-yarn twenty app:uninstall
+yarn twenty uninstall
 
 # Display commands' help
 yarn twenty help
@@ -122,7 +122,7 @@ With `--minimal`, only the core files are created (`application-config.ts`, `rol
 At a high level:
 
 - **package.json**: Declares the app name, version, engines (Node 24+, Yarn 4), and adds `twenty-sdk` plus a `twenty` script that delegates to the local `twenty` CLI. Run `yarn twenty help` to list all available commands.
-- **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `generated/` (typed client), `dist/`, `build/`, coverage folders, log files, and `.env*` files.
+- **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, coverage folders, log files, and `.env*` files.
 - **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Lock and configure the Yarn 4 toolchain used by the project.
 - **.nvmrc**: Pins the Node.js version expected by the project.
 - **.oxlintrc.json** and **tsconfig.json**: Provide linting and TypeScript configuration for your app's TypeScript sources.
@@ -165,8 +165,8 @@ export default defineObject({
 
 Later commands will add more files and folders:
 
-- `yarn twenty app:dev` will auto-generate two typed API clients in `node_modules/twenty-sdk/generated`: `CoreApiClient` (for workspace data via `/graphql`) and `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`).
-- `yarn twenty entity:add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
+- `yarn twenty dev` will auto-generate the typed `CoreApiClient` (for workspace data via `/graphql`) into `node_modules/twenty-client-sdk/`. The `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`) ships pre-built and is available immediately. Import them from `twenty-client-sdk/core` and `twenty-client-sdk/metadata` respectively.
+- `yarn twenty add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
 
 ## Authentication
 
@@ -219,13 +219,25 @@ Then add a `twenty` script:
 }
 ```
 
-Now you can run all commands via `yarn twenty <command>`, e.g. `yarn twenty app:dev`, `yarn twenty help`, etc.
+Now you can run all commands via `yarn twenty <command>`, e.g. `yarn twenty dev`, `yarn twenty help`, etc.
+
+## How to use a local Twenty instance
+
+If you're already running a Twenty instance locally (e.g. via `npx nx start twenty-server`), you can connect to it instead of using Docker:
+
+```bash filename="Terminal"
+# During scaffolding — skip Docker, connect to your running instance
+npx create-twenty-app@latest my-app --port 3000
+
+# Or after scaffolding — add a remote pointing to your instance
+yarn twenty remote add --local --port 3000
+```
 
 ## Troubleshooting
 
 - Authentication errors: run `yarn twenty auth:login` and ensure your API key has the required permissions.
 - Cannot connect to server: verify the API URL and that the Twenty server is reachable.
-- Types or client missing/outdated: restart `yarn twenty app:dev` — it auto-generates the typed client.
-- Dev mode not syncing: ensure `yarn twenty app:dev` is running and that changes are not ignored by your environment.
+- Types or client missing/outdated: restart `yarn twenty dev` — it auto-generates the typed client.
+- Dev mode not syncing: ensure `yarn twenty dev` is running and that changes are not ignored by your environment.
 
 Discord Help Channel: https://discord.com/channels/1130383047699738754/1130386664812982322

packages/twenty-docs/developers/extend/apps/publishing.mdx

@@ -12,7 +12,25 @@ Apps are currently in alpha testing. The feature is functional but still evolvin
 Once your app is [built and tested locally](/developers/extend/apps/building), you have two paths for distributing it:
 
 - **Publish to npm** — list your app in the Twenty marketplace for any workspace to discover and install.
-- **Push a tarball** — deploy your app to a specific Twenty server for internal use without making it publicly available.
+- **Deploy a tarball** — upload your app directly to a specific Twenty server for internal or private use.
+
+Both paths start from the same **build** step.
+
+## Building your app
+
+The `build` command compiles your TypeScript sources, transpiles logic functions and front components, and generates a `manifest.json` that describes your app's contents:
+
+```bash filename="Terminal"
+yarn twenty build
+```
+
+The output is written to `.twenty/output/`. This directory contains everything needed for distribution: compiled code, assets, the manifest, and a copy of your `package.json`.
+
+To also create a `.tgz` tarball (used by the deploy command internally, or for manual distribution):
+
+```bash filename="Terminal"
+yarn twenty build --tarball
+```
 
 ## Publishing to npm
 
@@ -21,29 +39,72 @@ Publishing to npm makes your app discoverable in the Twenty marketplace. Any Twe
 ### Requirements
 
 - An [npm](https://www.npmjs.com) account
-- Your package name **must** use the `twenty-app-` prefix (e.g., `twenty-app-postcard-sender`)
+- The `twenty-app` keyword **must** be listed in your `package.json` `keywords` array
+
+### Adding the required keyword
+
+The Twenty marketplace discovers apps by searching the npm registry for packages with the `twenty-app` keyword. Add it to your `package.json`:
+
+```json filename="package.json"
+{
+  "name": "twenty-app-postcard-sender",
+  "version": "1.0.0",
+  "keywords": ["twenty-app"],
+  ...
+}
+```
+
+<Note>
+The marketplace searches for `keywords:twenty-app` on the npm registry. Without this keyword, your package won't appear in the marketplace even if it has the `twenty-app-` name prefix.
+</Note>
 
 ### Steps
 
-1. **Build your app** — the CLI compiles your TypeScript sources and generates the application manifest:
+1. **Build your app:**
 
 ```bash filename="Terminal"
-yarn twenty app:build
+yarn twenty build
 ```
 
-2. **Publish to npm** — push the built package to the npm registry:
+2. **Publish to npm:**
 
 ```bash filename="Terminal"
-npx twenty app:publish
+yarn twenty publish
 ```
 
-### Auto-discovery
+This runs `npm publish` from the `.twenty/output/` directory.
 
-Packages with the `twenty-app-` prefix are automatically discovered by the Twenty marketplace catalog. Once published, your app appears in the marketplace within a few minutes — no manual registration or approval required.
+To publish under a specific dist-tag (e.g., `beta` or `next`):
+
+```bash filename="Terminal"
+yarn twenty publish --tag beta
+```
+
+### How marketplace discovery works
+
+The Twenty server syncs its marketplace catalog from the npm registry **every hour**:
+
+1. It searches for all npm packages with the `keywords:twenty-app` keyword
+2. For each package, it fetches the `manifest.json` from the npm CDN
+3. The app's metadata (name, description, author, logo, screenshots, category) is extracted from the manifest and displayed in the marketplace
+
+After publishing, your app can take up to one hour to appear in the marketplace. To trigger the sync immediately instead of waiting for the next hourly run:
+
+```bash filename="Terminal"
+yarn twenty catalog-sync
+```
+
+To target a specific remote:
+
+```bash filename="Terminal"
+yarn twenty catalog-sync -r production
+```
+
+The metadata shown in the marketplace comes from your `defineApplication()` call in your app source code — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
 
 ### CI publishing
 
-The scaffolded project includes a GitHub Actions workflow that publishes on every release. It runs `app:build`, then `npm publish --provenance` from the build output:
+The scaffolded project includes a GitHub Actions workflow that publishes on every release:
 
 ```yaml filename=".github/workflows/publish.yml"
 name: Publish
@@ -65,55 +126,124 @@ jobs:
           node-version: "24"
           registry-url: https://registry.npmjs.org
       - run: yarn install --immutable
-      - run: npx twenty app:build
+      - run: npx twenty build
       - run: npm publish --provenance --access public
         working-directory: .twenty/output
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```
 
-For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: `yarn install`, `npx twenty app:build`, then `npm publish` from `.twenty/output`.
+For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: `yarn install`, `yarn twenty build`, then `npm publish` from `.twenty/output`.
 
 <Tip>
 **npm provenance** is optional but recommended. Publishing with `--provenance` adds a trust badge to your npm listing, letting users verify the package was built from a specific commit in a public CI pipeline. See the [npm provenance docs](https://docs.npmjs.com/generating-provenance-statements) for setup instructions.
 </Tip>
 
-## Internal distribution
+## Deploying to a server (tarball)
 
-For apps you don't want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can push a tarball directly to a Twenty server.
+For apps you don't want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can deploy a tarball directly to a Twenty server.
 
-### Push a tarball
+### Prerequisites
 
-Build your app and deploy it to a specific server in one step:
+Before deploying, you need a configured remote pointing to the target server. Remotes store the server URL and authentication credentials locally in `~/.twenty/config.json`.
+
+Add a remote:
 
 ```bash filename="Terminal"
-npx twenty app:publish --server <server-url>
+yarn twenty remote add --url https://your-twenty-server.com --as production
 ```
 
-Any workspace on that server can then install and upgrade the app from the **Applications** settings page.
+For a local development server:
+
+```bash filename="Terminal"
+yarn twenty remote add --local --as local
+```
+
+You can also authenticate with an API key for non-interactive environments:
+
+```bash filename="Terminal"
+yarn twenty remote add --url https://your-twenty-server.com --token <api-key> --as production
+```
+
+Manage your remotes:
+
+```bash filename="Terminal"
+yarn twenty remote list       # List all configured remotes
+yarn twenty remote switch prod # Set the default remote
+yarn twenty remote status     # Show active remote and auth status
+yarn twenty remote remove old # Remove a remote
+```
+
+### Deploying
+
+Build and upload your app to the server in one step:
+
+```bash filename="Terminal"
+yarn twenty deploy
+```
+
+This builds the app with `--tarball`, then uploads the tarball to the default remote via a GraphQL multipart upload.
+
+To deploy to a specific remote:
+
+```bash filename="Terminal"
+yarn twenty deploy -r production
+```
+
+### Sharing a deployed app
+
+Tarball apps are not listed in the public marketplace, so other workspaces on the same server won't discover them by browsing. To share a deployed app:
+
+1. Go to **Settings > Applications > Registrations** and open your app
+2. In the **Distribution** tab, click **Copy share link**
+3. Share this link with users on other workspaces — it takes them directly to the app's install page
+
+The share link uses the server's base URL (without any workspace subdomain) so it works for any workspace on the server.
 
 ### Version management
 
 To release an update:
 
 1. Bump the `version` field in your `package.json`
-2. Push a new tarball with `npx twenty app:publish --server <server-url>`
-3. Workspaces on that server will see the upgrade available in their settings
+2. Run `yarn twenty deploy` (or `yarn twenty deploy -r production`)
+3. Workspaces that have the app installed will see the upgrade available in their settings
 
-<Note>
-Internal apps are scoped to the server they're pushed to. They won't appear in the public marketplace and can't be installed by workspaces on other servers.
-</Note>
+## Installing apps
 
-## App categories
+Once an app is published (npm) or deployed (tarball), workspaces install it through the UI:
+
+```bash filename="Terminal"
+yarn twenty install
+```
+
+Or from the **Settings > Applications** page in the Twenty UI, where both marketplace and tarball-deployed apps can be browsed and installed.
+
+## App distribution categories
 
 Twenty organizes apps into three categories based on how they're distributed:
 
 | Category | How it works | Visible in marketplace? |
 |----------|-------------|------------------------|
-| **Development** | Local dev mode apps running via `yarn twenty app:dev`. Used for building and testing. | No |
-| **Published** | Apps published to npm with the `twenty-app-` prefix. Listed in the marketplace for any workspace to install. | Yes |
-| **Internal** | Apps deployed via tarball to a specific server. Available only to workspaces on that server. | No |
+| **Development** | Local dev mode apps running via `yarn twenty dev`. Used for building and testing. | No |
+| **Published (npm)** | Apps published to npm with the `twenty-app` keyword. Listed in the marketplace for any workspace to install. | Yes |
+| **Internal (tarball)** | Apps deployed via tarball to a specific server. Available only to workspaces on that server via a share link. | No |
 
 <Tip>
 Start in **Development** mode while building your app. When it's ready, choose **Published** (npm) for broad distribution or **Internal** (tarball) for private deployment.
 </Tip>
+
+## CLI reference
+
+| Command | Description | Key flags |
+|---------|-------------|-----------|
+| `yarn twenty build` | Compile app and generate manifest | `--tarball` — also create a `.tgz` package |
+| `yarn twenty publish` | Build and publish to npm | `--tag <tag>` — npm dist-tag (e.g., `beta`, `next`) |
+| `yarn twenty deploy` | Build and upload tarball to a server | `-r, --remote <name>` — target remote |
+| `yarn twenty catalog-sync` | Trigger marketplace catalog sync on the server | `-r, --remote <name>` — target remote |
+| `yarn twenty install` | Install a deployed app on a workspace | `-r, --remote <name>` — target remote |
+| `yarn twenty dev` | Watch and sync local changes | Uses default remote |
+| `yarn twenty remote add` | Add a server connection | `--url`, `--token`, `--as`, `--local`, `--port` |
+| `yarn twenty remote list` | List configured remotes | — |
+| `yarn twenty remote switch` | Set default remote | — |
+| `yarn twenty remote status` | Show connection status | — |
+| `yarn twenty remote remove` | Remove a remote | — |

packages/twenty-docs/developers/extend/capabilities/apps.mdx

@@ -77,6 +77,18 @@ npx create-twenty-app@latest my-app
 npx create-twenty-app@latest my-app --minimal
 ```
 
+### How to use a local Twenty instance
+
+If you're already running a local Twenty instance, you can connect to it instead of using Docker. Pass the port your local server is listening on (default: `3000`):
+
+```bash filename="Terminal"
+# During scaffolding
+npx create-twenty-app@latest my-app --port 3000
+
+# Or after scaffolding
+yarn twenty remote add --local --port 3000
+```
+
 From here you can:
 
 ```bash filename="Terminal"
@@ -96,13 +108,13 @@ yarn twenty function:execute --preInstall
 yarn twenty function:execute --postInstall
 
 # Build the app for distribution
-yarn twenty app:build
+yarn twenty build
 
 # Publish the app to npm or a Twenty server
-yarn twenty app:publish
+yarn twenty publish
 
 # Uninstall the application from the current workspace
-yarn twenty app:uninstall
+yarn twenty uninstall
 
 # Display commands' help
 yarn twenty help
@@ -207,7 +219,7 @@ export default defineObject({
 
 Later commands will add more files and folders:
 
-- `yarn twenty app:dev` will auto-generate two typed API clients in `node_modules/twenty-sdk/clients`: `CoreApiClient` (for workspace data via `/graphql`) and `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`).
+- `yarn twenty dev` will auto-generate two typed API clients in `node_modules/twenty-sdk/clients`: `CoreApiClient` (for workspace data via `/graphql`) and `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`).
 - `yarn twenty entity:add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
 
 ## Authentication
@@ -534,7 +546,7 @@ Each function file uses `defineLogicFunction()` to export a configuration with a
 // src/app/createPostCard.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
 import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk';
-import { CoreApiClient, type Person } from 'twenty-sdk/clients';
+import { CoreApiClient, type Person } from 'twenty-client-sdk/core';
 
 const handler = async (params: RoutePayload) => {
   const client = new CoreApiClient();
@@ -772,7 +784,7 @@ To mark a logic function as a tool, set `isTool: true` and provide a `toolInputS
 ```typescript
 // src/logic-functions/enrich-company.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-sdk/clients';
+import { CoreApiClient } from 'twenty-client-sdk/core';
 
 const handler = async (params: { companyName: string; domain?: string }) => {
   const client = new CoreApiClient();
@@ -856,7 +868,7 @@ export default defineFrontComponent({
 Key points:
 - Front components are React components that render in isolated contexts within Twenty.
 - The `component` field references your React component.
-- Components are built and synced automatically during `yarn twenty app:dev`.
+- Components are built and synced automatically during `yarn twenty dev`.
 
 You can create new front components in two ways:
 
@@ -1182,14 +1194,14 @@ You can create new agents in two ways:
 
 ### Generated typed clients
 
-Two typed clients are auto-generated by `yarn twenty app:dev` and stored in `node_modules/twenty-sdk/clients` based on your workspace schema:
+Two typed clients are auto-generated by `yarn twenty dev` and stored in `node_modules/twenty-sdk/clients` based on your workspace schema:
 
 - **`CoreApiClient`** — queries the `/graphql` endpoint for workspace data
 - **`MetadataApiClient`** — queries the `/metadata` endpoint for workspace configuration and file uploads
 
 ```typescript
-import { CoreApiClient } from 'twenty-sdk/clients';
-import { MetadataApiClient } from 'twenty-sdk/clients';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
 
 const client = new CoreApiClient();
 const { me } = await client.query({ me: { id: true, displayName: true } });
@@ -1198,7 +1210,7 @@ const metadataClient = new MetadataApiClient();
 const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
 ```
 
-`CoreApiClient` is re-generated automatically by `yarn twenty app:dev` whenever your objects or fields change. `MetadataApiClient` ships pre-built with the SDK.
+`CoreApiClient` is re-generated automatically by `yarn twenty dev` whenever your objects or fields change. `MetadataApiClient` ships pre-built with the SDK.
 
 #### Runtime credentials in logic functions
 
@@ -1217,7 +1229,7 @@ Notes:
 The `MetadataApiClient` includes an `uploadFile` method for attaching files to file-type fields on your workspace objects. Because standard GraphQL clients do not support multipart file uploads natively, the client provides this dedicated method that implements the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec) under the hood.
 
 ```typescript
-import { MetadataApiClient } from 'twenty-sdk/clients';
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
 import * as fs from 'fs';
 
 const metadataClient = new MetadataApiClient();
@@ -1268,10 +1280,10 @@ Once you've developed your app with `app:dev`, use `app:build` to compile it int
 
 ```bash filename="Terminal"
 # Build the app (output goes to .twenty/output/)
-yarn twenty app:build
+yarn twenty build
 
 # Build and create a tarball (.tgz) for distribution
-yarn twenty app:build --tarball
+yarn twenty build --tarball
 ```
 
 The build process:
@@ -1311,10 +1323,10 @@ Use `app:publish` to distribute your app — either to the npm registry or direc
 
 ```bash filename="Terminal"
 # Publish to npm (requires npm login)
-yarn twenty app:publish
+yarn twenty publish
 
 # Publish with a dist-tag (e.g. beta, next)
-yarn twenty app:publish --tag beta
+yarn twenty publish --tag beta
 ```
 
 This builds the app and runs `npm publish` from the `.twenty/output/` directory. The published package can then be installed from the Twenty marketplace by any workspace.
@@ -1323,7 +1335,7 @@ This builds the app and runs `npm publish` from the `.twenty/output/` directory.
 
 ```bash filename="Terminal"
 # Publish directly to a Twenty server
-yarn twenty app:publish --server https://app.twenty.com
+yarn twenty publish --server https://app.twenty.com
 ```
 
 This builds the app with a tarball, uploads it to the server via the `uploadAppTarball` GraphQL mutation, and triggers installation in one step. This is useful for private deployments or testing against a specific server.
@@ -1387,13 +1399,13 @@ Then add a `twenty` script:
 }
 ```
 
-Now you can run all commands via `yarn twenty <command>`, e.g. `yarn twenty app:dev`, `yarn twenty help`, etc.
+Now you can run all commands via `yarn twenty <command>`, e.g. `yarn twenty dev`, `yarn twenty help`, etc.
 
 ## Troubleshooting
 
 - Authentication errors: run `yarn twenty auth:login` and ensure your API key has the required permissions.
 - Cannot connect to server: verify the API URL and that the Twenty server is reachable.
-- Types or client missing/outdated: restart `yarn twenty app:dev` — it auto-generates the typed client.
-- Dev mode not syncing: ensure `yarn twenty app:dev` is running and that changes are not ignored by your environment.
+- Types or client missing/outdated: restart `yarn twenty dev` — it auto-generates the typed client.
+- Dev mode not syncing: ensure `yarn twenty dev` is running and that changes are not ignored by your environment.
 
 Discord Help Channel: https://discord.com/channels/1130383047699738754/1130386664812982322