fix(server): backport relationTargetFieldMetadataId column-add to 2.4 fast instance

Backport of the column-add to a new 2.4 fast instance command so that users sitting on a v2.3.x baseline can upgrade past v2.4 without later hitting the 2.5 workspace command NormalizeCompositeFieldDefaults failing on `column ViewFilterEntity.relationTargetFieldMetadataId does not exist`. Same fix as main #20721, scoped to the 2.4 file only for this release. ADD COLUMN IF NOT EXISTS keeps it idempotent.
fix(ai-agent-node) - agent node execution error (#20534 )
2026-05-19 15:34:27 +02:00 · 2026-05-13 15:37:27 +02:00 · 2026-05-12 13:28:24 +02:00 · 2026-05-11 14:15:28 +02:00 · 2026-05-11 06:46:09 +02:00 · 2026-05-10 22:35:26 +02:00
2903 changed files with 117971 additions and 55656 deletions
@@ -106,34 +106,35 @@ Replace `{VERSION}` with the actual version number (e.g., `1.9.0`)
 ### 2. Create File Structure

 **Create changelog file:**
- Path: `packages/twenty-website/src/content/releases/{VERSION}.mdx`
- Example: `packages/twenty-website/src/content/releases/1.9.0.mdx`
+- Path: `packages/twenty-website-new/src/content/releases/{VERSION}.mdx`
+- Example: `packages/twenty-website-new/src/content/releases/1.9.0.mdx`

 **Create image folder:**
- Path: `packages/twenty-website/public/images/releases/{MINOR_VERSION}/`
- Example for version 1.9.0: `packages/twenty-website/public/images/releases/1.9/`
- Example for version 2.0.0: `packages/twenty-website/public/images/releases/2.0/`
+- Path: `packages/twenty-website-new/public/images/releases/{MINOR_VERSION}/`
+- Example for version 1.9.0: `packages/twenty-website-new/public/images/releases/1.9/`
+- Example for version 2.0.0: `packages/twenty-website-new/public/images/releases/2.0/`

 ```bash
 # Create the image folder
-mkdir -p packages/twenty-website/public/images/releases/{MINOR_VERSION}
+mkdir -p packages/twenty-website-new/public/images/releases/{MINOR_VERSION}
 ```

 ### 3. Move Illustration Files

 **Source:** `/Users/thomascolasdesfrancs/Downloads/🆕`

-**Destination:** `packages/twenty-website/public/images/releases/{MINOR_VERSION}/`
+**Destination:** `packages/twenty-website-new/public/images/releases/{MINOR_VERSION}/`

-**Naming Convention:** `{VERSION}-descriptive-name.png`
+**Naming Convention:** `{VERSION}-descriptive-name.webp`

 Examples:
- `1.9.0-feature-name.png`
- `1.9.0-another-feature.png`
+- `1.9.0-feature-name.webp`
+- `1.9.0-another-feature.webp`

 ```bash
-# Move and rename files
-cp ~/Downloads/🆕/source-file.png packages/twenty-website/public/images/releases/{MINOR_VERSION}/{VERSION}-feature-name.png
+# Move and rename source files, then convert to webp if needed
+cp ~/Downloads/🆕/source-file.png packages/twenty-website-new/public/images/releases/{MINOR_VERSION}/{VERSION}-feature-name.png
+cd packages/twenty-website-new && node scripts/convert-png-to-webp.mjs
 ```

 ### 4. Research Features (if needed)
@@ -158,19 +159,19 @@ Date: {YYYY-MM-DD}

 Short description explaining what the feature does and why it's useful. Keep it user-focused and concise (1-2 sentences).

-![](/images/releases/{MINOR_VERSION}/{VERSION}-feature-1.png)
+![](/images/releases/{MINOR_VERSION}/{VERSION}-feature-1.webp)

 # Feature 2 Name

 Another short description of the second feature.

-![](/images/releases/{MINOR_VERSION}/{VERSION}-feature-2.png)
+![](/images/releases/{MINOR_VERSION}/{VERSION}-feature-2.webp)

 # Feature 3 Name

 Description of the third feature.

-![](/images/releases/{MINOR_VERSION}/{VERSION}-feature-3.png)
+![](/images/releases/{MINOR_VERSION}/{VERSION}-feature-3.webp)
 ```

 **Style Guidelines:**
@@ -182,7 +183,7 @@ Description of the third feature.
 - **NEVER mention the brand name "Twenty"** in changelog text - use "your workspace", "the platform", or similar neutral references instead

 **Reference Previous Changelogs:**
- Check `packages/twenty-website/src/content/releases/` for examples
+- Check `packages/twenty-website-new/src/content/releases/` for examples
 - Recent releases: 1.7.0.mdx, 1.6.0.mdx, 1.5.0.mdx

 ### 6. Review
@@ -190,10 +191,10 @@ Description of the third feature.
 Open the changelog file for review:
 ```bash
 # Open in Cursor
-cursor packages/twenty-website/src/content/releases/{VERSION}.mdx
+cursor packages/twenty-website-new/src/content/releases/{VERSION}.mdx

 # Open image folder to verify illustrations
-open packages/twenty-website/public/images/releases/{MINOR_VERSION}
+open packages/twenty-website-new/public/images/releases/{MINOR_VERSION}
 ```

 Review checklist:
@@ -221,8 +222,8 @@ I've created the changelog for version {VERSION}. Here's the content for your re
 [Show full MDX content]

 Images moved to:
- packages/twenty-website/public/images/releases/{MINOR_VERSION}/{VERSION}-feature-1.png
- packages/twenty-website/public/images/releases/{MINOR_VERSION}/{VERSION}-feature-2.png
+- packages/twenty-website-new/public/images/releases/{MINOR_VERSION}/{VERSION}-feature-1.webp
+- packages/twenty-website-new/public/images/releases/{MINOR_VERSION}/{VERSION}-feature-2.webp

 Please review the content. Once you approve, I'll commit the changes and create the pull request.
 ```
@@ -241,8 +242,8 @@ Possible user responses:
 git status

 # Add files
-git add packages/twenty-website/src/content/releases/{VERSION}.mdx
-git add packages/twenty-website/public/images/releases/{MINOR_VERSION}/
+git add packages/twenty-website-new/src/content/releases/{VERSION}.mdx
+git add packages/twenty-website-new/public/images/releases/{MINOR_VERSION}/

 # Commit
 git commit -m "Add {VERSION} release changelog"
@@ -265,7 +266,7 @@ This release includes:
 - Feature 2
 - Feature 3

-Changelog file: \`packages/twenty-website/src/content/releases/{VERSION}.mdx\`
+Changelog file: \`packages/twenty-website-new/src/content/releases/{VERSION}.mdx\`
 Release date: {DATE}" \
  --base main \
  --head {VERSION}
@@ -279,21 +280,21 @@ Or visit: `https://github.com/twentyhq/twenty/pull/new/{VERSION}`
 - **Format**: `{MAJOR}.{MINOR}.{PATCH}.mdx`
 - **Convention**: One file per complete version
 - **Examples**: `1.6.0.mdx`, `1.7.0.mdx`, `2.0.0.mdx`
- **Location**: `packages/twenty-website/src/content/releases/`
+- **Location**: `packages/twenty-website-new/src/content/releases/`

 ### Image Folders
 - **Format**: `{MAJOR}.{MINOR}/`
 - **Convention**: One folder per minor version (shared across patches)
 - **Examples**: `1.6/`, `1.7/`, `2.0/`
- **Location**: `packages/twenty-website/public/images/releases/`
+- **Location**: `packages/twenty-website-new/public/images/releases/`

 ### Image Files
- **Format**: `{VERSION}-descriptive-name.png`
+- **Format**: `{VERSION}-descriptive-name.webp`
 - **Convention**: Kebab-case descriptive names
 - **Examples**: 
-  - `1.8.0-workflow-iterator.png`
-  - `1.8.0-bulk-select.png`
-  - `1.9.0-new-feature.png`
+  - `1.8.0-workflow-iterator.webp`
+  - `1.8.0-bulk-select.webp`
+  - `1.9.0-new-feature.webp`

 ## Quick Reference Template

@@ -310,8 +311,8 @@ Features to document:
 3. ___________________________

 Branch name: {VERSION}
-Changelog path: packages/twenty-website/src/content/releases/{VERSION}.mdx
-Images path: packages/twenty-website/public/images/releases/{MINOR_VERSION}/
+Changelog path: packages/twenty-website-new/src/content/releases/{VERSION}.mdx
+Images path: packages/twenty-website-new/public/images/releases/{MINOR_VERSION}/
 ```

 ## Tips
@@ -4,20 +4,19 @@
 # See https://crowdin.github.io/crowdin-cli/configuration for more information
 #

-"preserve_hierarchy": true
-"base_path": ".."
-
-files: [
-  {
-    #
-    # Source files filter - PO files for Lingui
-    #
-    "source": "**/en.po",
+preserve_hierarchy: true
+base_path: ..

+files:
+  #
+  # Source files filter - PO files for Lingui
+  #
+  - source: packages/twenty-front/src/locales/en.po
    #
    # Translation files path
    #
-    "translation": "%original_path%/%locale%.po",
-  }
-]
-
+    translation: '%original_path%/%locale%.po'
+  - source: packages/twenty-server/src/engine/core-modules/i18n/locales/en.po
+    translation: '%original_path%/%locale%.po'
+  - source: packages/twenty-emails/src/locales/en.po
+    translation: '%original_path%/%locale%.po'
@@ -0,0 +1,23 @@
+#
+# Crowdin CLI configuration for Website translations (twenty-website-new)
+# Project ID: 4
+# See https://crowdin.github.io/crowdin-cli/configuration for more information
+#
+
+project_id: 4
+preserve_hierarchy: true
+base_url: 'https://twenty.api.crowdin.com'
+base_path: ..
+languages_mapping:
+  locale:
+    fr: fr-FR
+
+files:
+  #
+  # Source file - PO file for Lingui
+  #
+  - source: packages/twenty-website-new/src/locales/en.po
+    #
+    # Translation files path
+    #
+    translation: '%original_path%/%locale%.po'
@@ -105,7 +105,7 @@ jobs:
          create-twenty-app --version
          mkdir -p /tmp/e2e-test-workspace
          cd /tmp/e2e-test-workspace
-          create-twenty-app test-app --display-name "Test scaffolded app" --description "E2E test scaffolded app" --skip-local-instance
+          create-twenty-app test-app --display-name "Test scaffolded app" --description "E2E test scaffolded app" --skip-local-instance --yes

      - name: Install scaffolded app dependencies
        run: |
@@ -1,12 +1,12 @@
 name: CI Website

-permissions:
-  contents: read
-
 on:
  pull_request:
  merge_group:

+permissions:
+  contents: read
+
 concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
@@ -18,53 +18,40 @@ jobs:
    with:
      files: |
        package.json
-        packages/twenty-website/**
-  website-build:
+        yarn.lock
+        packages/twenty-website-new/**
+        packages/twenty-shared/**
+  website-task:
    needs: changed-files-check
    if: needs.changed-files-check.outputs.any_changed == 'true'
-    timeout-minutes: 10
+    timeout-minutes: 30
    runs-on: ubuntu-latest
-    services:
-      postgres:
-        image: postgres:18
-        env:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
+    env:
+      NODE_OPTIONS: '--max-old-space-size=6144'
+    strategy:
+      matrix:
+        task: [lint, typecheck, test]
    steps:
-      - uses: actions/checkout@v4
+      - 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: Server / Create DB
-        run: PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
-
-      - name: Website / Run migrations
-        run: npx nx database:migrate twenty-website
-        env:
-          DATABASE_PG_URL: postgres://postgres:postgres@localhost:5432/default
-      - name: Website / Build Website
-        run: npx nx build twenty-website
-        env:
-          DATABASE_PG_URL: postgres://postgres:postgres@localhost:5432/default
-          KEYSTATIC_GITHUB_CLIENT_ID: xxx
-          KEYSTATIC_GITHUB_CLIENT_SECRET: xxx
-          KEYSTATIC_SECRET: xxx
-          NEXT_PUBLIC_KEYSTATIC_GITHUB_APP_SLUG: xxx
+      - name: Run ${{ matrix.task }} task
+        uses: ./.github/actions/nx-affected
+        with:
+          tag: scope:website
+          tasks: ${{ matrix.task }}
  ci-website-status-check:
    if: always() && !cancelled()
    timeout-minutes: 5
    runs-on: ubuntu-latest
-    needs: [changed-files-check, website-build]
+    needs: [changed-files-check, website-task]
    steps:
      - name: Fail job if any needs failed
        if: contains(needs.*.result, 'failure')
@@ -0,0 +1,28 @@
+name: Auto-Draft External PRs
+
+on:
+  pull_request_target:
+    types: [opened]
+
+permissions: {}
+
+jobs:
+  dispatch:
+    if: |
+      github.event.pull_request.draft == false &&
+      github.event.pull_request.author_association != 'MEMBER' &&
+      github.event.pull_request.author_association != 'OWNER' &&
+      github.event.pull_request.author_association != 'COLLABORATOR'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Dispatch to ci-privileged
+        env:
+          GH_TOKEN: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_NODE_ID: ${{ github.event.pull_request.node_id }}
+        run: |
+          gh api repos/twentyhq/ci-privileged/dispatches \
+            -f event_type=convert-pr-to-draft \
+            -f "client_payload[pr_number]=$PR_NUMBER" \
+            -f "client_payload[pr_node_id]=$PR_NODE_ID"
@@ -58,7 +58,6 @@ jobs:
          npx nx run twenty-server:lingui:compile --strict
          npx nx run twenty-emails:lingui:compile --strict
          npx nx run twenty-front:lingui:compile --strict
-          npx nx run twenty-website-new:lingui:compile --strict
        continue-on-error: true

      - name: Stash any changes before pulling translations
@@ -75,8 +74,6 @@ jobs:
          upload_sources: false
          upload_translations: false
          download_translations: true
-          source: '**/en.po'
-          translation: '%original_path%/%locale%.po'
          export_only_approved: false
          localization_branch_name: i18n
          base_url: 'https://twenty.api.crowdin.com'
@@ -116,7 +113,6 @@ jobs:
          npx nx run twenty-server:lingui:compile
          npx nx run twenty-emails:lingui:compile
          npx nx run twenty-front:lingui:compile
-          npx nx run twenty-website-new:lingui:compile
          git status
          git add .
          if ! git diff --staged --quiet --exit-code; then
@@ -41,7 +41,6 @@ jobs:
          npx nx run twenty-server:lingui:extract
          npx nx run twenty-emails:lingui:extract
          npx nx run twenty-front:lingui:extract
-          npx nx run twenty-website-new:lingui:extract

      - name: Check and commit extracted files
        id: check_extract_changes
@@ -61,7 +60,6 @@ jobs:
          npx nx run twenty-server:lingui:compile
          npx nx run twenty-emails:lingui:compile
          npx nx run twenty-front:lingui:compile
-          npx nx run twenty-website-new:lingui:compile

      - name: Check and commit compiled files
        id: check_compile_changes
@@ -0,0 +1,26 @@
+name: PR Review Dispatch
+
+on:
+  pull_request_target:
+    types: [ready_for_review, synchronize]
+
+permissions: {}
+
+concurrency:
+  group: pr-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  dispatch:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Dispatch to ci-privileged
+        env:
+          GH_TOKEN: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          gh api repos/twentyhq/ci-privileged/dispatches \
+            -f event_type=pr-review \
+            -f "client_payload[pr_number]=$PR_NUMBER"
@@ -0,0 +1,135 @@
+# Pull down website translations from Crowdin every two hours or when triggered manually.
+# When force_pull input is true, translations will be pulled regardless of compilation status.
+
+name: 'Pull website translations from Crowdin'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+on:
+  schedule:
+    - cron: '0 */2 * * *' # Every two hours.
+  workflow_dispatch:
+    inputs:
+      force_pull:
+        description: 'Force pull translations regardless of compilation status'
+        required: false
+        type: boolean
+        default: false
+  workflow_call:
+    inputs:
+      force_pull:
+        description: 'Force pull translations regardless of compilation status'
+        required: false
+        type: boolean
+        default: false
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  pull_website_translations:
+    name: Pull website translations
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          token: ${{ github.token }}
+          ref: ${{ github.head_ref || github.ref_name }}
+
+      - name: Setup website i18n branch
+        run: |
+          git fetch origin i18n-website || true
+          git checkout -B i18n-website origin/i18n-website || git checkout -b i18n-website
+
+      - name: Install dependencies
+        uses: ./.github/actions/yarn-install
+
+      - name: Build twenty-shared
+        run: npx nx build twenty-shared
+
+      # Strict mode fails if there are missing website translations.
+      - name: Compile website translations
+        id: compile_translations_strict
+        run: npx nx run twenty-website-new:lingui:compile --strict
+        continue-on-error: true
+
+      - name: Stash any changes before pulling translations
+        run: |
+          git config --global user.name 'github-actions'
+          git config --global user.email 'github-actions@twenty.com'
+          git add .
+          git stash
+
+      - name: Pull website translations from Crowdin
+        if: inputs.force_pull || steps.compile_translations_strict.outcome == 'failure'
+        uses: crowdin/github-action@v2
+        with:
+          upload_sources: false
+          upload_translations: false
+          download_translations: true
+          source: 'packages/twenty-website-new/src/locales/en.po'
+          translation: 'packages/twenty-website-new/src/locales/%locale%.po'
+          export_only_approved: false
+          localization_branch_name: i18n-website
+          base_url: 'https://twenty.api.crowdin.com'
+          auto_approve_imported: false
+          import_eq_suggestions: false
+          download_sources: false
+          push_sources: false
+          skip_untranslated_strings: false
+          skip_untranslated_files: false
+          push_translations: false
+          create_pull_request: false
+          skip_ref_checkout: true
+          dryrun_action: false
+          config: '.github/crowdin-website.yml'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          # Website translations project
+          CROWDIN_PROJECT_ID: '4'
+          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
+
+      # As the files are extracted from a Docker container, they belong to root:root.
+      # We need to fix this before the next steps.
+      - name: Fix file permissions
+        run: sudo chown -R runner:docker .
+
+      - name: Compile website translations
+        id: compile_translations
+        run: |
+          npx nx run twenty-website-new:lingui:compile
+          git status
+          git add packages/twenty-website-new/src/locales
+          if ! git diff --staged --quiet --exit-code; then
+            git commit -m "chore: compile website translations"
+            echo "changes_detected=true" >> $GITHUB_OUTPUT
+          else
+            echo "changes_detected=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Push changes
+        if: steps.compile_translations.outputs.changes_detected == 'true'
+        run: git push origin HEAD:i18n-website
+
+      - name: Create pull request
+        if: steps.compile_translations.outputs.changes_detected == 'true'
+        run: |
+          if git diff --name-only origin/main..HEAD | grep -q .; then
+            gh pr create -B main -H i18n-website --title 'i18n - website translations' --body 'Created by Github action' || true
+          else
+            echo "No file differences between branches, skipping PR creation"
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Trigger i18n automerge
+        if: steps.compile_translations.outputs.changes_detected == 'true'
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.TWENTY_INFRA_TOKEN }}
+          repository: twentyhq/twenty-infra
+          event-type: i18n-pr-ready
@@ -0,0 +1,111 @@
+name: 'Push website translations to Crowdin'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+on:
+  workflow_dispatch:
+  workflow_call:
+  push:
+    branches: ['main']
+    paths:
+      - 'packages/twenty-website-new/**'
+      - '.github/crowdin-website.yml'
+      - '.github/workflows/website-i18n-push.yaml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  extract_website_translations:
+    name: Extract and upload website translations
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          token: ${{ github.token }}
+          ref: main
+
+      - name: Setup website i18n branch
+        run: |
+          git fetch origin i18n-website || true
+          git checkout -B i18n-website origin/i18n-website || git checkout -b i18n-website
+
+      - name: Install dependencies
+        uses: ./.github/actions/yarn-install
+
+      - name: Build dependencies
+        run: npx nx build twenty-shared
+
+      - name: Extract website translations
+        run: npx nx run twenty-website-new:lingui:extract
+
+      - name: Check and commit extracted files
+        id: check_extract_changes
+        run: |
+          git config --global user.name 'github-actions'
+          git config --global user.email 'github-actions@twenty.com'
+          git add packages/twenty-website-new/src/locales
+          if ! git diff --staged --quiet --exit-code; then
+            git commit -m "chore: extract website translations"
+            echo "changes_detected=true" >> $GITHUB_OUTPUT
+          else
+            echo "changes_detected=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Compile website translations
+        run: npx nx run twenty-website-new:lingui:compile
+
+      - name: Check and commit compiled files
+        id: check_compile_changes
+        run: |
+          git config --global user.name 'github-actions'
+          git config --global user.email 'github-actions@twenty.com'
+          git add packages/twenty-website-new/src/locales/generated
+          if ! git diff --staged --quiet --exit-code; then
+            git commit -m "chore: compile website translations"
+            echo "changes_detected=true" >> $GITHUB_OUTPUT
+          else
+            echo "changes_detected=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Push changes and create remote branch if needed
+        if: steps.check_extract_changes.outputs.changes_detected == 'true' || steps.check_compile_changes.outputs.changes_detected == 'true'
+        run: git push origin HEAD:i18n-website
+
+      - name: Upload missing website translations
+        if: steps.check_extract_changes.outputs.changes_detected == 'true'
+        uses: crowdin/github-action@v2
+        with:
+          upload_sources: true
+          upload_translations: true
+          download_translations: false
+          localization_branch_name: i18n-website
+          base_url: 'https://twenty.api.crowdin.com'
+          config: '.github/crowdin-website.yml'
+        env:
+          # Website translations project
+          CROWDIN_PROJECT_ID: '4'
+          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
+
+      - name: Create a pull request
+        if: steps.check_extract_changes.outputs.changes_detected == 'true' || steps.check_compile_changes.outputs.changes_detected == 'true'
+        run: |
+          if git diff --name-only origin/main..HEAD | grep -q .; then
+            gh pr create -B main -H i18n-website --title 'i18n - website translations' --body 'Created by Github action' || true
+          else
+            echo "No file differences between branches, skipping PR creation"
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Trigger i18n automerge
+        if: steps.check_extract_changes.outputs.changes_detected == 'true' || steps.check_compile_changes.outputs.changes_detected == 'true'
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.TWENTY_INFRA_TOKEN }}
+          repository: twentyhq/twenty-infra
+          event-type: i18n-pr-ready
@@ -110,7 +110,8 @@ packages/
 ├── twenty-ui/             # Shared UI components library
 ├── twenty-shared/         # Common types and utilities
 ├── twenty-emails/         # Email templates with React Email
-├── twenty-website/        # Next.js documentation website
+├── twenty-website-new/    # Next.js marketing website
+├── twenty-docs/           # Documentation website
 ├── twenty-zapier/         # Zapier integration
 └── twenty-e2e-testing/    # Playwright E2E tests
 ```
@@ -1,19 +1,19 @@
 <p align="center">
  <a href="https://www.twenty.com">
-    <img src="./packages/twenty-website/public/images/core/logo.svg" width="100px" alt="Twenty logo" />
+    <img src="./packages/twenty-website-new/public/images/core/logo.svg" width="100px" alt="Twenty logo" />
  </a>
 </p>

 <h2 align="center" >The #1 Open-Source CRM</h2>

-<p align="center"><a href="https://twenty.com"><img src="./packages/twenty-website/public/images/readme/globe-icon.svg" width="12" height="12"/> Website</a> · <a href="https://docs.twenty.com"><img src="./packages/twenty-website/public/images/readme/book-icon.svg" width="12" height="12"/> Documentation</a> · <a href="https://github.com/orgs/twentyhq/projects/1"><img src="./packages/twenty-website/public/images/readme/map-icon.svg" width="12" height="12"/> Roadmap </a> · <a href="https://discord.gg/cx5n4Jzs57"><img src="./packages/twenty-website/public/images/readme/discord-icon.svg" width="12" height="12"/> Discord</a> · <a href="https://www.figma.com/file/xt8O9mFeLl46C5InWwoMrN/Twenty"><img src="./packages/twenty-website/public/images/readme/figma-icon.png"  width="12" height="12"/>  Figma</a></p>
+<p align="center"><a href="https://twenty.com"><img src="./packages/twenty-website-new/public/images/readme/globe-icon.svg" width="12" height="12"/> Website</a> · <a href="https://docs.twenty.com"><img src="./packages/twenty-website-new/public/images/readme/book-icon.svg" width="12" height="12"/> Documentation</a> · <a href="https://github.com/orgs/twentyhq/projects/1"><img src="./packages/twenty-website-new/public/images/readme/map-icon.svg" width="12" height="12"/> Roadmap </a> · <a href="https://discord.gg/cx5n4Jzs57"><img src="./packages/twenty-website-new/public/images/readme/discord-icon.svg" width="12" height="12"/> Discord</a> · <a href="https://www.figma.com/file/xt8O9mFeLl46C5InWwoMrN/Twenty"><img src="./packages/twenty-website-new/public/images/readme/figma-icon.webp"  width="12" height="12"/>  Figma</a></p>

 <p align="center">
  <a href="https://www.twenty.com">
    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website/public/images/readme/github-cover-dark.png" />
-      <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website/public/images/readme/github-cover-light.png" />
-      <img src="./packages/twenty-website/public/images/readme/github-cover-light.png" alt="Twenty banner" />
+      <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website-new/public/images/readme/github-cover-dark.webp" />
+      <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website-new/public/images/readme/github-cover-light.webp" />
+      <img src="./packages/twenty-website-new/public/images/readme/github-cover-light.webp" alt="Twenty banner" />
    </picture>
  </a>
 </p>
@@ -24,17 +24,17 @@

 Twenty gives technical teams the building blocks for a custom CRM that meets complex business needs and quickly adapts as the business evolves. Twenty is the CRM you build, ship, and version like the rest of your stack.

-<a href="https://twenty.com/why-twenty"><img src="./packages/twenty-website/public/images/readme/star-icon.svg" width="14" height="14"/> Learn more about why we built Twenty</a>
+<a href="https://twenty.com/resources/why-twenty"><img src="./packages/twenty-website-new/public/images/readme/star-icon.svg" width="14" height="14"/> Learn more about why we built Twenty</a>

 <br />

 # Installation

-### <img src="./packages/twenty-website/public/images/readme/globe-icon.svg" width="14" height="14"/> Cloud
+### <img src="./packages/twenty-website-new/public/images/readme/globe-icon.svg" width="14" height="14"/> Cloud

 The fastest way to get started. Sign up at [twenty.com](https://twenty.com) and spin up a workspace in under a minute, with no infrastructure to manage and always up to date.

-### <img src="./packages/twenty-website/public/images/readme/book-icon.svg" width="14" height="14"/> Build an app
+### <img src="./packages/twenty-website-new/public/images/readme/book-icon.svg" width="14" height="14"/> Build an app

 Scaffold a new app with the Twenty CLI:

@@ -68,7 +68,7 @@ npx twenty deploy

 See the [app development guide](https://docs.twenty.com/developers/extend/apps/getting-started) for objects, views, agents, and logic functions.

-### <img src="./packages/twenty-website/public/images/readme/rocket-icon.svg" width="14" height="14"/> Self-hosting
+### <img src="./packages/twenty-website-new/public/images/readme/rocket-icon.svg" width="14" height="14"/> Self-hosting

 Run Twenty on your own infrastructure with [Docker Compose](https://docs.twenty.com/developers/self-host/capabilities/docker-compose), or contribute locally via the [local setup guide](https://docs.twenty.com/developers/contribute/capabilities/local-setup).

@@ -79,61 +79,61 @@ Run Twenty on your own infrastructure with [Docker Compose](https://docs.twenty.

 Twenty gives you the building blocks of a modern CRM (objects, views, workflows, and agents) and lets you extend them as code. Here's a tour of what's in the box.

-Want to go deeper? Read the <a href="https://docs.twenty.com/user-guide/introduction"><img src="./packages/twenty-website/public/images/readme/planner-icon.svg" width="14" height="14"/> User Guide</a> for product walkthroughs, or the <a href="https://docs.twenty.com"><img src="./packages/twenty-website/public/images/readme/book-icon.svg" width="14" height="14"/> Documentation</a> for developer reference.
+Want to go deeper? Read the <a href="https://docs.twenty.com/user-guide/introduction"><img src="./packages/twenty-website-new/public/images/readme/planner-icon.svg" width="14" height="14"/> User Guide</a> for product walkthroughs, or the <a href="https://docs.twenty.com"><img src="./packages/twenty-website-new/public/images/readme/book-icon.svg" width="14" height="14"/> Documentation</a> for developer reference.

 <table align="center">
  <tr>
    <td width="50%">
      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website/public/images/readme/v2-build-apps-dark.png" />
-        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website/public/images/readme/v2-build-apps-light.png" />
-        <img src="./packages/twenty-website/public/images/readme/v2-build-apps-light.png" alt="Create your apps" />
+        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website-new/public/images/readme/v2-build-apps-dark.webp" />
+        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website-new/public/images/readme/v2-build-apps-light.webp" />
+        <img src="./packages/twenty-website-new/public/images/readme/v2-build-apps-light.webp" alt="Create your apps" />
      </picture>
-      <p align="center"><a href="https://docs.twenty.com/developers/extend/apps/getting-started"><img src="./packages/twenty-website/public/images/readme/code-icon.svg" width="16" height="16"/> Learn more about apps in doc</a></p>
+      <p align="center"><a href="https://docs.twenty.com/developers/extend/apps/getting-started"><img src="./packages/twenty-website-new/public/images/readme/code-icon.svg" width="16" height="16"/> Learn more about apps in doc</a></p>
    </td>
    <td width="50%">
      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website/public/images/readme/v2-version-control-dark.png" />
-        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website/public/images/readme/v2-version-control-light.png" />
-        <img src="./packages/twenty-website/public/images/readme/v2-version-control-light.png" alt="Stay on top with version control" />
+        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website-new/public/images/readme/v2-version-control-dark.webp" />
+        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website-new/public/images/readme/v2-version-control-light.webp" />
+        <img src="./packages/twenty-website-new/public/images/readme/v2-version-control-light.webp" alt="Stay on top with version control" />
      </picture>
-      <p align="center"><a href="https://docs.twenty.com/developers/extend/apps/publishing"><img src="./packages/twenty-website/public/images/readme/monitor-icon.svg" width="16" height="16"/> Learn more about version control in doc</a></p>
+      <p align="center"><a href="https://docs.twenty.com/developers/extend/apps/publishing"><img src="./packages/twenty-website-new/public/images/readme/monitor-icon.svg" width="16" height="16"/> Learn more about version control in doc</a></p>
    </td>
  </tr>
  <tr>
    <td width="50%">
      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website/public/images/readme/v2-all-tools-dark.png" />
-        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website/public/images/readme/v2-all-tools-light.png" />
-        <img src="./packages/twenty-website/public/images/readme/v2-all-tools-light.png" alt="All the tools you need to build anything" />
+        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website-new/public/images/readme/v2-all-tools-dark.webp" />
+        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website-new/public/images/readme/v2-all-tools-light.webp" />
+        <img src="./packages/twenty-website-new/public/images/readme/v2-all-tools-light.webp" alt="All the tools you need to build anything" />
      </picture>
-      <p align="center"><a href="https://docs.twenty.com/developers/extend/apps/building"><img src="./packages/twenty-website/public/images/readme/rocket-icon.svg" width="16" height="16"/> Learn more about primitives in doc</a></p>
+      <p align="center"><a href="https://docs.twenty.com/developers/extend/apps/building"><img src="./packages/twenty-website-new/public/images/readme/rocket-icon.svg" width="16" height="16"/> Learn more about primitives in doc</a></p>
    </td>
    <td width="50%">
      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website/public/images/readme/v2-tools-dark.png" />
-        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website/public/images/readme/v2-tools-light.png" />
-        <img src="./packages/twenty-website/public/images/readme/v2-tools-light.png" alt="Customize your layouts" />
+        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website-new/public/images/readme/v2-tools-dark.webp" />
+        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website-new/public/images/readme/v2-tools-light.webp" />
+        <img src="./packages/twenty-website-new/public/images/readme/v2-tools-light.webp" alt="Customize your layouts" />
      </picture>
-      <p align="center"><a href="https://docs.twenty.com/user-guide/layout/overview"><img src="./packages/twenty-website/public/images/readme/planner-icon.svg" width="16" height="16"/> Learn more about layouts in doc</a></p>
+      <p align="center"><a href="https://docs.twenty.com/user-guide/layout/overview"><img src="./packages/twenty-website-new/public/images/readme/planner-icon.svg" width="16" height="16"/> Learn more about layouts in doc</a></p>
    </td>
  </tr>
  <tr>
    <td width="50%">
      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website/public/images/readme/v2-ai-agents-dark.png" />
-        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website/public/images/readme/v2-ai-agents-light.png" />
-        <img src="./packages/twenty-website/public/images/readme/v2-ai-agents-light.png" alt="AI agents and chats" />
+        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website-new/public/images/readme/v2-ai-agents-dark.webp" />
+        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website-new/public/images/readme/v2-ai-agents-light.webp" />
+        <img src="./packages/twenty-website-new/public/images/readme/v2-ai-agents-light.webp" alt="AI agents and chats" />
      </picture>
-      <p align="center"><a href="https://docs.twenty.com/user-guide/ai/overview"><img src="./packages/twenty-website/public/images/readme/message-icon.svg" width="16" height="16"/> Learn more about AI in doc</a></p>
+      <p align="center"><a href="https://docs.twenty.com/user-guide/ai/overview"><img src="./packages/twenty-website-new/public/images/readme/message-icon.svg" width="16" height="16"/> Learn more about AI in doc</a></p>
    </td>
    <td width="50%">
      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website/public/images/readme/v2-crm-tools-dark.png" />
-        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website/public/images/readme/v2-crm-tools-light.png" />
-        <img src="./packages/twenty-website/public/images/readme/v2-crm-tools-light.png" alt="Plus all the tools of a good CRM" />
+        <source media="(prefers-color-scheme: dark)" srcset="./packages/twenty-website-new/public/images/readme/v2-crm-tools-dark.webp" />
+        <source media="(prefers-color-scheme: light)" srcset="./packages/twenty-website-new/public/images/readme/v2-crm-tools-light.webp" />
+        <img src="./packages/twenty-website-new/public/images/readme/v2-crm-tools-light.webp" alt="Plus all the tools of a good CRM" />
      </picture>
-      <p align="center"><a href="https://docs.twenty.com/user-guide/introduction"><img src="./packages/twenty-website/public/images/readme/star-icon.svg" width="16" height="16"/> Learn more about CRM features in doc</a></p>
+      <p align="center"><a href="https://docs.twenty.com/user-guide/introduction"><img src="./packages/twenty-website-new/public/images/readme/star-icon.svg" width="16" height="16"/> Learn more about CRM features in doc</a></p>
    </td>
  </tr>
 </table>
@@ -142,23 +142,23 @@ Want to go deeper? Read the <a href="https://docs.twenty.com/user-guide/introduc

 # Stack

- <a href="https://www.typescriptlang.org/"><img src="./packages/twenty-website/public/images/readme/stack-typescript.svg" width="14" height="14"/> TypeScript</a>
- <a href="https://nx.dev/"><img src="./packages/twenty-website/public/images/readme/stack-nx.svg" width="14" height="14"/> Nx</a>
- <a href="https://nestjs.com/"><img src="./packages/twenty-website/public/images/readme/stack-nestjs.svg" width="14" height="14"/> NestJS</a>, with <a href="https://bullmq.io/">BullMQ</a>, <a href="https://www.postgresql.org/"><img src="./packages/twenty-website/public/images/readme/stack-postgresql.svg" width="14" height="14"/> PostgreSQL</a>, <a href="https://redis.io/"><img src="./packages/twenty-website/public/images/readme/stack-redis.svg" width="14" height="14"/> Redis</a>
- <a href="https://reactjs.org/"><img src="./packages/twenty-website/public/images/readme/stack-react.svg" width="14" height="14"/> React</a>, with <a href="https://jotai.org/">Jotai</a>, <a href="https://linaria.dev/">Linaria</a> and <a href="https://lingui.dev/">Lingui</a>
+- <a href="https://www.typescriptlang.org/"><img src="./packages/twenty-website-new/public/images/readme/stack-typescript.svg" width="14" height="14"/> TypeScript</a>
+- <a href="https://nx.dev/"><img src="./packages/twenty-website-new/public/images/readme/stack-nx.svg" width="14" height="14"/> Nx</a>
+- <a href="https://nestjs.com/"><img src="./packages/twenty-website-new/public/images/readme/stack-nestjs.svg" width="14" height="14"/> NestJS</a>, with <a href="https://bullmq.io/">BullMQ</a>, <a href="https://www.postgresql.org/"><img src="./packages/twenty-website-new/public/images/readme/stack-postgresql.svg" width="14" height="14"/> PostgreSQL</a>, <a href="https://redis.io/"><img src="./packages/twenty-website-new/public/images/readme/stack-redis.svg" width="14" height="14"/> Redis</a>
+- <a href="https://reactjs.org/"><img src="./packages/twenty-website-new/public/images/readme/stack-react.svg" width="14" height="14"/> React</a>, with <a href="https://jotai.org/">Jotai</a>, <a href="https://linaria.dev/">Linaria</a> and <a href="https://lingui.dev/">Lingui</a>



 # Thanks

 <p align="center">
-  <a href="https://www.chromatic.com/"><img src="./packages/twenty-website/public/images/readme/chromatic.png" height="28" alt="Chromatic" /></a>
+  <a href="https://www.chromatic.com/"><img src="./packages/twenty-website-new/public/images/readme/chromatic.webp" height="28" alt="Chromatic" /></a>
  &nbsp;&nbsp;&nbsp;&nbsp;
-  <a href="https://greptile.com"><img src="./packages/twenty-website/public/images/readme/greptile.png" height="28" alt="Greptile" /></a>
+  <a href="https://greptile.com"><img src="./packages/twenty-website-new/public/images/readme/greptile.webp" height="28" alt="Greptile" /></a>
  &nbsp;&nbsp;&nbsp;&nbsp;
-  <a href="https://sentry.io/"><img src="./packages/twenty-website/public/images/readme/sentry.png" height="28" alt="Sentry" /></a>
+  <a href="https://sentry.io/"><img src="./packages/twenty-website-new/public/images/readme/sentry.webp" height="28" alt="Sentry" /></a>
  &nbsp;&nbsp;&nbsp;&nbsp;
-  <a href="https://crowdin.com/"><img src="./packages/twenty-website/public/images/readme/crowdin.png" height="28" alt="Crowdin" /></a>
+  <a href="https://crowdin.com/"><img src="./packages/twenty-website-new/public/images/readme/crowdin.webp" height="28" alt="Crowdin" /></a>
 </p>

  Thanks to these amazing services that we use and recommend for UI testing (Chromatic), code review (Greptile), catching bugs (Sentry) and translating (Crowdin).
@@ -166,4 +166,4 @@ Want to go deeper? Read the <a href="https://docs.twenty.com/user-guide/introduc

 # Join the Community

-<p><a href="https://github.com/twentyhq/twenty"><img src="./packages/twenty-website/public/images/readme/star-icon.svg" width="12" height="12"/> Star the repo</a> · <a href="https://discord.gg/cx5n4Jzs57"><img src="./packages/twenty-website/public/images/readme/discord-icon.svg" width="12" height="12"/> Discord</a> · <a href="https://github.com/twentyhq/twenty/discussions"><img src="./packages/twenty-website/public/images/readme/message-icon.svg" width="12" height="12"/> Feature requests</a> · <a href="https://github.com/orgs/twentyhq/projects/1/views/35"><img src="./packages/twenty-website/public/images/readme/rocket-icon.svg" width="12" height="12"/> Releases</a> · <a href="https://twitter.com/twentycrm"><img src="./packages/twenty-website/public/images/readme/x-icon.svg" width="12" height="12"/> X</a> · <a href="https://www.linkedin.com/company/twenty/"><img src="./packages/twenty-website/public/images/readme/linkedin-icon.svg" width="12" height="12"/> LinkedIn</a> · <a href="https://twenty.crowdin.com/twenty"><img src="./packages/twenty-website/public/images/readme/language-icon.svg" width="12" height="12"/> Crowdin</a> · <a href="https://github.com/twentyhq/twenty/contribute"><img src="./packages/twenty-website/public/images/readme/code-icon.svg" width="12" height="12"/> Contribute</a></p>
+<p><a href="https://github.com/twentyhq/twenty"><img src="./packages/twenty-website-new/public/images/readme/star-icon.svg" width="12" height="12"/> Star the repo</a> · <a href="https://discord.gg/cx5n4Jzs57"><img src="./packages/twenty-website-new/public/images/readme/discord-icon.svg" width="12" height="12"/> Discord</a> · <a href="https://github.com/twentyhq/twenty/discussions"><img src="./packages/twenty-website-new/public/images/readme/message-icon.svg" width="12" height="12"/> Feature requests</a> · <a href="https://github.com/orgs/twentyhq/projects/1/views/35"><img src="./packages/twenty-website-new/public/images/readme/rocket-icon.svg" width="12" height="12"/> Releases</a> · <a href="https://twitter.com/twentycrm"><img src="./packages/twenty-website-new/public/images/readme/x-icon.svg" width="12" height="12"/> X</a> · <a href="https://www.linkedin.com/company/twenty/"><img src="./packages/twenty-website-new/public/images/readme/linkedin-icon.svg" width="12" height="12"/> LinkedIn</a> · <a href="https://twenty.crowdin.com/twenty"><img src="./packages/twenty-website-new/public/images/readme/language-icon.svg" width="12" height="12"/> Crowdin</a> · <a href="https://github.com/twentyhq/twenty/contribute"><img src="./packages/twenty-website-new/public/images/readme/code-icon.svg" width="12" height="12"/> Contribute</a></p>
@@ -9,9 +9,11 @@
    "@nx/web": "22.5.4",
    "@types/react": "^18.2.39",
    "@types/react-dom": "^18.2.15",
+    "@yarnpkg/types": "^4.0.0",
    "concurrently": "^8.2.2",
    "http-server": "^14.1.1",
    "nx": "22.5.4",
+    "tsx": "^4.17.0",
    "verdaccio": "^6.3.1"
  },
  "engines": {
@@ -31,7 +33,9 @@
    "@lingui/core": "5.1.2",
    "@types/qs": "6.9.16",
    "@wyw-in-js/transform@npm:0.6.0": "patch:@wyw-in-js/transform@npm%3A0.7.0#~/.yarn/patches/@wyw-in-js-transform-npm-0.7.0-ba641dc99f.patch",
-    "@wyw-in-js/transform@npm:0.7.0": "patch:@wyw-in-js/transform@npm%3A0.7.0#~/.yarn/patches/@wyw-in-js-transform-npm-0.7.0-ba641dc99f.patch"
+    "@wyw-in-js/transform@npm:0.7.0": "patch:@wyw-in-js/transform@npm%3A0.7.0#~/.yarn/patches/@wyw-in-js-transform-npm-0.7.0-ba641dc99f.patch",
+    "@opentelemetry/api": "1.9.1",
+    "chokidar": "^3.6.0"
  },
  "version": "0.2.1",
  "nx": {},
@@ -49,7 +53,6 @@
      "packages/twenty-ui",
      "packages/twenty-utils",
      "packages/twenty-zapier",
-      "packages/twenty-website",
      "packages/twenty-website-new",
      "packages/twenty-docs",
      "packages/twenty-e2e-testing",
@@ -57,7 +60,6 @@
      "packages/twenty-sdk",
      "packages/twenty-front-component-renderer",
      "packages/twenty-client-sdk",
-      "packages/twenty-apps",
      "packages/twenty-cli",
      "packages/create-twenty-app",
      "packages/twenty-oxlint-rules",
@@ -1,7 +1,7 @@
 <div align="center">
  <a href="https://twenty.com">
    <picture>
-      <img alt="Twenty logo" src="https://raw.githubusercontent.com/twentyhq/twenty/2f25922f4cd5bd61e1427c57c4f8ea224e1d552c/packages/twenty-website/public/images/core/logo.svg" height="128">
+      <img alt="Twenty logo" src="https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-website-new/public/images/core/logo.svg" height="128">
    </picture>
  </a>
  <h1>Create Twenty App</h1>
@@ -48,11 +48,11 @@ Examples are sourced from [twentyhq/twenty/packages/twenty-apps/examples](https:

 ## Documentation

-Full documentation is available at **[docs.twenty.com/developers/extend/apps](https://docs.twenty.com/developers/extend/apps/getting-started)**:
+Full documentation is available at **[docs.twenty.com/developers/extend/apps](https://docs.twenty.com/developers/extend/apps/getting-started/quick-start)**:

- [Getting Started](https://docs.twenty.com/developers/extend/apps/getting-started) — step-by-step setup, project structure, server management, CI
- [Building Apps](https://docs.twenty.com/developers/extend/apps/building) — entity definitions, API clients, testing
- [Publishing](https://docs.twenty.com/developers/extend/apps/publishing) — deploy, npm publish, marketplace
+- [Quick Start](https://docs.twenty.com/developers/extend/apps/getting-started/quick-start) — scaffold, run a local server, sync your code
+- [Concepts](https://docs.twenty.com/developers/extend/apps/getting-started/concepts) — how apps work: entity model, sandboxing, lifecycle
+- [Operations](https://docs.twenty.com/developers/extend/apps/operations/overview) — CLI, testing, CI, deploy and publish

 ## Troubleshooting

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

 ## Learn More

- [Twenty Apps documentation](https://docs.twenty.com/developers/extend/apps/getting-started)
+- [Twenty Apps documentation](https://docs.twenty.com/developers/extend/apps/getting-started/quick-start)
 - [twenty-sdk CLI reference](https://www.npmjs.com/package/twenty-sdk)
 - [Discord](https://discord.gg/cx5n4Jzs57)
@@ -4,12 +4,10 @@ import {
  APP_DESCRIPTION,
  APP_DISPLAY_NAME,
  APPLICATION_UNIVERSAL_IDENTIFIER,
-  DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
 } from 'src/constants/universal-identifiers';

 export default defineApplication({
  universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
  displayName: APP_DISPLAY_NAME,
  description: APP_DESCRIPTION,
-  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
 });
@@ -1,11 +1,11 @@
-import { defineRole } from 'twenty-sdk/define';
+import { defineApplicationRole } from 'twenty-sdk/define';

 import {
  APP_DISPLAY_NAME,
  DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
 } from 'src/constants/universal-identifiers';

-export default defineRole({
+export default defineApplicationRole({
  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
  label: `${APP_DISPLAY_NAME} default function role`,
  description: `${APP_DISPLAY_NAME} default function role`,
@@ -16,7 +16,6 @@ import {
  containerExists,
  detectLocalServer,
  serverStart,
-  type ServerStartResult,
 } from 'twenty-sdk/cli';
 import { isDefined } from 'twenty-shared/utils';

@@ -33,6 +32,8 @@ type CreateAppOptions = {
 };

 export class CreateAppCommand {
+  private static TOTAL_STEPS = 4;
+
  async execute(options: CreateAppOptions = {}): Promise<void> {
    const { appName, appDisplayName, appDirectory, appDescription } =
      await this.getAppInfos(options);
@@ -40,9 +41,26 @@ export class CreateAppCommand {
    try {
      await this.validateDirectory(appDirectory);

-      this.logCreationInfo({ appDirectory, appName });
+      const confirmed = await this.promptScaffoldConfirmation({
+        appName,
+        appDisplayName,
+        appDescription,
+        appDirectory,
+        autoConfirm: options.yes,
+      });

+      if (!confirmed) {
+        console.log(chalk.gray('\nScaffolding cancelled.'));
+        process.exit(0);
+      }
+
+      console.log('');
+
+      this.logStep(1, 'Creating project directory');
      await fs.ensureDir(appDirectory);
+      this.logDetail(appDirectory);
+
+      this.logStep(2, 'Scaffolding project files');

      if (options.example) {
        const exampleSucceeded = await this.tryDownloadExample(
@@ -56,6 +74,7 @@ export class CreateAppCommand {
            appDisplayName,
            appDescription,
            appDirectory,
+            onProgress: (message) => this.logDetail(message),
          });
        }
      } else {
@@ -64,33 +83,59 @@ export class CreateAppCommand {
          appDisplayName,
          appDescription,
          appDirectory,
+          onProgress: (message) => this.logDetail(message),
        });
      }

-      await install(appDirectory);
+      this.logStep(3, 'Installing dependencies');
+      await install(appDirectory, (message) => this.logDetail(message));

-      await tryGitInit(appDirectory);
+      this.logStep(4, 'Initializing Git repository');
+      const gitInitialized = await tryGitInit(appDirectory);

-      let serverResult: ServerStartResult | undefined;
+      if (gitInitialized) {
+        this.logDetail('Initialized on branch main');
+        this.logDetail('Created initial commit');
+      } else {
+        this.logDetail(
+          'Skipped (Git unavailable, initialization failed, or already in a repository)',
+        );
+      }
+
+      console.log('');
+
+      let hasLocalServer = false;
+      let authSucceeded = false;

      if (!options.skipLocalInstance) {
-        const shouldStartServer = await this.shouldStartServer(options.yes);
+        const existingServerUrl = await detectLocalServer();

-        if (shouldStartServer) {
-          const startResult = await serverStart({
-            onProgress: (message: string) => console.log(chalk.gray(message)),
-          });
+        if (existingServerUrl) {
+          hasLocalServer = true;
+          authSucceeded = await this.promptConnectToLocal(existingServerUrl);
+        } else {
+          const shouldStart = await this.shouldStartServer(options.yes);

-          if (startResult.success) {
-            serverResult = startResult.data;
-            await this.promptConnectToLocal(serverResult.url);
+          if (shouldStart) {
+            const startResult = await serverStart({
+              onProgress: (message: string) => console.log(chalk.gray(message)),
+            });
+
+            if (startResult.success) {
+              hasLocalServer = true;
+              authSucceeded = await this.promptConnectToLocal(
+                startResult.data.url,
+              );
+            } else {
+              console.log(chalk.yellow(`\n${startResult.error.message}`));
+            }
          } else {
-            console.log(chalk.yellow(`\n${startResult.error.message}`));
+            this.logServerSkipped();
          }
        }
      }

-      this.logSuccess(appDirectory, serverResult);
+      this.logSuccess(appDirectory, hasLocalServer, authSucceeded);
    } catch (error) {
      console.error(
        chalk.red('\nCreate application failed:'),
@@ -213,25 +258,80 @@ export class CreateAppCommand {
    }
  }

-  private logCreationInfo({
-    appDirectory,
+  private async promptScaffoldConfirmation({
    appName,
+    appDisplayName,
+    appDescription,
+    appDirectory,
+    autoConfirm,
  }: {
-    appDirectory: string;
    appName: string;
-  }): void {
+    appDisplayName: string;
+    appDescription: string;
+    appDirectory: string;
+    autoConfirm?: boolean;
+  }): Promise<boolean> {
+    console.log(chalk.blue('\nCreating Twenty Application\n'));
+    console.log(chalk.white(`  Name:           ${appName}`));
+    console.log(chalk.white(`  Display name:   ${appDisplayName}`));
+
+    if (appDescription) {
+      console.log(chalk.white(`  Description:    ${appDescription}`));
+    }
+
+    console.log(chalk.white(`  Directory:      ${appDirectory}`));
+
+    console.log(chalk.white('\nThe following steps will be performed:\n'));
+    console.log(chalk.gray('  1. Create project directory'));
    console.log(
-      chalk.blue('\n', 'Creating Twenty Application\n'),
-      chalk.gray(`- Directory: ${appDirectory}\n`, `- Name: ${appName}\n`),
+      chalk.gray(
+        '  2. Scaffold project files from base template\n' +
+          '     - Copy template files\n' +
+          '     - Configure dotfiles (.gitignore, .github)\n' +
+          '     - Generate unique application identifiers\n' +
+          '     - Update package.json with app name and SDK versions',
+      ),
+    );
+    console.log(chalk.gray('  3. Install dependencies (yarn)'));
+    console.log(
+      chalk.gray('  4. Initialize Git repository with initial commit'),
+    );
+    console.log('');
+
+    if (autoConfirm) {
+      return true;
+    }
+
+    const { proceed } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'proceed',
+        message: 'Proceed?',
+        default: true,
+      },
+    ]);
+
+    return proceed;
+  }
+
+  private logStep(step: number, title: string): void {
+    console.log(
+      chalk.blue(`\n[${step}/${CreateAppCommand.TOTAL_STEPS}]`) +
+        chalk.white(` ${title}...`),
    );
  }

-  private async shouldStartServer(autoConfirm?: boolean): Promise<boolean> {
-    const existingServerUrl = await detectLocalServer();
+  private logDetail(message: string): void {
+    console.log(chalk.gray(`      → ${message}`));
+  }

-    if (existingServerUrl) {
-      return true;
-    }
+  private async shouldStartServer(autoConfirm?: boolean): Promise<boolean> {
+    console.log(
+      chalk.white(
+        '\n  A local Twenty instance is required for app development.\n' +
+          '  It provides the API and schema your application connects to.\n',
+      ),
+    );

    if (checkDockerRunning() && containerExists()) {
      if (autoConfirm) {
@@ -268,12 +368,31 @@ export class CreateAppCommand {
    return startDocker;
  }

-  private async promptConnectToLocal(serverUrl: string): Promise<void> {
+  private logServerSkipped(): void {
+    console.log(
+      chalk.gray(
+        '\n  To start a Twenty instance later:\n' +
+          '     yarn twenty server start\n\n' +
+          '  To connect to a remote instance instead:\n' +
+          '     yarn twenty remote add\n',
+      ),
+    );
+  }
+
+  private async promptConnectToLocal(serverUrl: string): Promise<boolean> {
+    console.log(
+      chalk.white(
+        '\n  Authentication links your app to a Twenty instance so you can\n' +
+          '  sync custom objects, fields, and roles during development.\n' +
+          '  This will open a browser window to complete the OAuth flow.\n',
+      ),
+    );
+
    const { shouldAuthenticate } = await inquirer.prompt([
      {
        type: 'confirm',
        name: 'shouldAuthenticate',
-        message: `Would you like to authenticate to the local Twenty instance (${serverUrl})?`,
+        message: `Authenticate to the local Twenty instance (${serverUrl})?`,
        default: true,
      },
    ]);
@@ -281,13 +400,22 @@ export class CreateAppCommand {
    if (!shouldAuthenticate) {
      console.log(
        chalk.gray(
-          'Authentication skipped. Run `yarn twenty remote add --local` manually.',
+          '\n  Authentication skipped. To authenticate later:\n' +
+            `     yarn twenty remote add --local\n`,
        ),
      );

-      return;
+      return false;
    }

+    await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'confirm',
+        message: 'Press Enter to open the browser for authentication...',
+      },
+    ]);
+
    try {
      const result = await authLoginOAuth({
        apiUrl: serverUrl,
@@ -298,12 +426,16 @@ export class CreateAppCommand {
        const configService = new ConfigService();

        await configService.setDefaultRemote('local');
+
+        return true;
      } else {
        console.log(
          chalk.yellow(
            'Authentication failed. Run `yarn twenty remote add --local` manually.',
          ),
        );
+
+        return false;
      }
    } catch {
      console.log(
@@ -311,28 +443,44 @@ export class CreateAppCommand {
          'Authentication failed. Run `yarn twenty remote add` manually.',
        ),
      );
+
+      return false;
    }
  }

  private logSuccess(
    appDirectory: string,
-    serverResult?: ServerStartResult,
+    hasLocalServer: boolean,
+    authSucceeded: boolean,
  ): void {
    const dirName = basename(appDirectory);

-    console.log(chalk.blue('\nApplication created. Next steps:'));
-    console.log(chalk.gray(`- cd ${dirName}`));
+    console.log(chalk.green('\n✔ Application created successfully!\n'));
+    console.log(chalk.white('  Next steps:\n'));

-    if (!serverResult) {
-      console.log(
-        chalk.gray(
-          '- yarn twenty remote add          # Authenticate with Twenty',
-        ),
-      );
+    let stepNumber = 1;
+
+    console.log(chalk.white(`  ${stepNumber}. Navigate to your project`));
+    console.log(chalk.cyan(`     cd ${dirName}\n`));
+    stepNumber++;
+
+    if (!authSucceeded) {
+      const remoteCommand = hasLocalServer
+        ? 'yarn twenty remote add --local'
+        : 'yarn twenty remote add';
+
+      console.log(chalk.white(`  ${stepNumber}. Connect to a Twenty instance`));
+      console.log(chalk.cyan(`     ${remoteCommand}\n`));
+      stepNumber++;
    }

+    console.log(chalk.white(`  ${stepNumber}. Start developing`));
+    console.log(chalk.cyan('     yarn twenty dev\n'));
+
    console.log(
-      chalk.gray('- yarn twenty dev                  # Start dev mode'),
+      chalk.gray(
+        '  Documentation: https://docs.twenty.com/developers/extend/capabilities/apps',
+      ),
    );
  }
 }
@@ -76,11 +76,16 @@ describe('copyBaseApplicationProject', () => {
      appDirectory: testAppDirectory,
    });

-    expect(fs.copy).toHaveBeenCalledTimes(1);
+    // Two fs.copy calls: (1) the template directory, (2) AGENTS.md → CLAUDE.md
+    expect(fs.copy).toHaveBeenCalledTimes(2);
    expect(fs.copy).toHaveBeenCalledWith(
      expect.stringContaining('template'),
      testAppDirectory,
    );
+    expect(fs.copy).toHaveBeenCalledWith(
+      join(testAppDirectory, 'AGENTS.md'),
+      join(testAppDirectory, 'CLAUDE.md'),
+    );
  });

  it('should replace placeholders in universal-identifiers.ts with real values', async () => {
@@ -3,7 +3,6 @@ import { join } from 'path';
 import { v4 } from 'uuid';

 import createTwentyAppPackageJson from 'package.json';
-import chalk from 'chalk';

 const SRC_FOLDER = 'src';

@@ -12,25 +11,33 @@ export const copyBaseApplicationProject = async ({
  appDisplayName,
  appDescription,
  appDirectory,
+  onProgress,
 }: {
  appName: string;
  appDisplayName: string;
  appDescription: string;
  appDirectory: string;
+  onProgress?: (message: string) => void;
 }) => {
-  console.log(chalk.gray('Generating application project...'));
+  onProgress?.('Copying base template');
  await fs.copy(join(__dirname, './constants/template'), appDirectory);

+  onProgress?.('Configuring dotfiles (.gitignore, .github)');
  await renameDotfiles({ appDirectory });

+  onProgress?.('Mirroring AGENTS.md to CLAUDE.md');
+  await mirrorAgentsToClaude({ appDirectory });
+
  await addEmptyPublicDirectory({ appDirectory });

+  onProgress?.('Generating unique application identifiers');
  await generateUniversalIdentifiers({
    appDisplayName,
    appDescription,
    appDirectory,
  });

+  onProgress?.('Updating package.json');
  await updatePackageJson({ appName, appDirectory });
 };

@@ -51,6 +58,19 @@ const renameDotfiles = async ({ appDirectory }: { appDirectory: string }) => {
  }
 };

+// AGENTS.md is the cross-tool standard; Claude Code prefers CLAUDE.md and only
+// falls back to AGENTS.md, so we mirror the file to keep a single source of truth.
+const mirrorAgentsToClaude = async ({
+  appDirectory,
+}: {
+  appDirectory: string;
+}) => {
+  await fs.copy(
+    join(appDirectory, 'AGENTS.md'),
+    join(appDirectory, 'CLAUDE.md'),
+  );
+};
+
 const addEmptyPublicDirectory = async ({
  appDirectory,
 }: {
@@ -4,14 +4,18 @@ import { exec } from 'child_process';

 const execPromise = promisify(exec);

-export const install = async (root: string) => {
-  console.log(chalk.gray('Installing yarn dependencies...'));
+export const install = async (
+  root: string,
+  onProgress?: (message: string) => void,
+) => {
+  onProgress?.('Enabling corepack');
  try {
    await execPromise('corepack enable', { cwd: root });
  } catch (error: any) {
-    console.warn(chalk.yellow('corepack enabled failed:'), error.stderr);
+    console.warn(chalk.yellow('corepack enable failed:'), error.stderr);
  }

+  onProgress?.('Running yarn install');
  try {
    await execPromise('yarn install', { cwd: root });
  } catch (error: any) {
@@ -19,8 +19,8 @@
    "test:watch": "vitest"
  },
  "dependencies": {
-    "twenty-client-sdk": "0.9.0",
-    "twenty-sdk": "0.9.0"
+    "twenty-client-sdk": "2.2.0",
+    "twenty-sdk": "2.2.0"
  },
  "devDependencies": {
    "@types/node": "^24.7.2",
@@ -1,8 +1,12 @@
 import { useEffect } from 'react';
 import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId, updateProgress, enqueueSnackbar, unmountFrontComponent } from 'twenty-sdk/front-component';
+import {
+  enqueueSnackbar,
+  unmountFrontComponent,
+  updateProgress,
+  useRecordId,
+} from 'twenty-sdk/front-component';
 import { CoreApiClient } from 'twenty-client-sdk/core';
-import { isDefined } from 'twenty-shared/utils';
 import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';

 const SYSTEM_PROMPT =
@@ -14,9 +18,9 @@ const GeneratePostCardEffect = () => {
  const recordId = useRecordId();

  useEffect(() => {
-    if (!isDefined(recordId)) {
+    if (recordId === null) {
      enqueueSnackbar({
-        message: 'No record selected',
+        message: 'Please select exactly one record',
        variant: 'error',
      });
      unmountFrontComponent();
@@ -1,8 +1,12 @@
 import { useEffect } from 'react';
 import { defineFrontComponent } from 'twenty-sdk/define';
-import { useRecordId, updateProgress, enqueueSnackbar, unmountFrontComponent } from 'twenty-sdk/front-component';
+import {
+  enqueueSnackbar,
+  unmountFrontComponent,
+  updateProgress,
+  useRecordId,
+} from 'twenty-sdk/front-component';
 import { CoreApiClient } from 'twenty-client-sdk/core';
-import { isDefined } from 'twenty-shared/utils';
 import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';

 const SendPostCardsEffect = () => {
@@ -14,55 +18,25 @@ const SendPostCardsEffect = () => {
        await updateProgress(0.1);
        const client = new CoreApiClient();

-        let idsToSend: string[] = [];
-
-        if (isDefined(recordId)) {
-          idsToSend = [recordId];
-        } else {
-          const { postCards } = await client.query({
-            postCards: {
-              __args: {
-                filter: { status: { eq: 'DRAFT' } },
-              },
-              edges: { node: { id: true } },
-            },
-          });
-
-          idsToSend =
-            postCards?.edges?.map(
-              (edge: { node: { id: string; status: true } }) => edge.node.id,
-            ) ?? [];
-        }
-
-        if (idsToSend.length === 0) {
-          await updateProgress(1);
-          await unmountFrontComponent();
-          return;
-        }
-
        await updateProgress(0.3);

-        for (let i = 0; i < idsToSend.length; i++) {
+        if (recordId) {
          await client.mutation({
            updatePostCard: {
              __args: {
-                id: idsToSend[i],
+                id: recordId,
                data: { status: 'SENT' },
              },
              id: true,
            },
          });

-          await updateProgress(0.3 + (0.7 * (i + 1)) / idsToSend.length);
+          await enqueueSnackbar({
+            message: `Postcard sent`,
+            variant: 'success',
+          });
        }

-        const count = idsToSend.length;
-
-        await enqueueSnackbar({
-          message: `${count} postcard${count > 1 ? 's' : ''} sent`,
-          variant: 'success',
-        });
-
        await unmountFrontComponent();
      } catch (error) {
        const message =
@@ -3317,8 +3317,8 @@ __metadata:
    oxlint: "npm:^0.16.0"
    react: "npm:^19.0.0"
    react-dom: "npm:^19.0.0"
-    twenty-client-sdk: "npm:0.9.0"
-    twenty-sdk: "npm:0.9.0"
+    twenty-client-sdk: "npm:2.2.0"
+    twenty-sdk: "npm:2.2.0"
    typescript: "npm:^5.9.3"
    vite-tsconfig-paths: "npm:^4.2.1"
    vitest: "npm:^3.1.1"
@@ -4059,21 +4059,21 @@ __metadata:
  languageName: node
  linkType: hard

-"twenty-client-sdk@npm:0.9.0":
-  version: 0.9.0
-  resolution: "twenty-client-sdk@npm:0.9.0"
+"twenty-client-sdk@npm:2.2.0":
+  version: 2.2.0
+  resolution: "twenty-client-sdk@npm:2.2.0"
  dependencies:
    "@genql/cli": "npm:^3.0.3"
    "@genql/runtime": "npm:^2.10.0"
    esbuild: "npm:^0.25.0"
    graphql: "npm:^16.8.1"
-  checksum: 10c0/4b42a6622a9852fc3eca50c1131b116c5602af006ee5f1d3b4f1e97721bbc8ef5c2f3b60d9dee3ca9ca8c3c7ad4b292a7b55007b779b4c042997dbc29940ba54
+  checksum: 10c0/90122593efa53440ae386960211a2c274b13a410942bf6f9bc35cf952ae55fe83280e29074677fd284fa3c79069fc578980db06a92a143c08e043f865dbbbd3c
  languageName: node
  linkType: hard

-"twenty-sdk@npm:0.9.0":
-  version: 0.9.0
-  resolution: "twenty-sdk@npm:0.9.0"
+"twenty-sdk@npm:2.2.0":
+  version: 2.2.0
+  resolution: "twenty-sdk@npm:2.2.0"
  dependencies:
    "@genql/cli": "npm:^3.0.3"
    "@genql/runtime": "npm:^2.10.0"
@@ -4093,7 +4093,7 @@ __metadata:
    react: "npm:^19.0.0"
    react-dom: "npm:^19.0.0"
    tinyglobby: "npm:^0.2.15"
-    twenty-client-sdk: "npm:0.9.0"
+    twenty-client-sdk: "npm:2.2.0"
    typescript: "npm:^5.9.2"
    uuid: "npm:^13.0.0"
    vite: "npm:^7.0.0"
@@ -4101,7 +4101,7 @@ __metadata:
    zod: "npm:^4.1.11"
  bin:
    twenty: dist/cli.cjs
-  checksum: 10c0/27f93e5edac3265f819abacc853598435718020258a95d55518562e086e42daabae784964b42005d8e4ff30d1d6f13a12a38c656e18c60bad98da3f579a8e1c3
+  checksum: 10c0/8978b4b0aa5ea282c8f76799347d9d1812901ec609bc2bd9270261a6bc5589ad361f6102a06900a4511a29a8378cd3811c2c0bad9f01cb8adadabca6d96dfd0b
  languageName: node
  linkType: hard

@@ -10,5 +10,13 @@ export default defineLogicFunction({
  description: 'Look up a recipient by name to find their details',
  timeoutSeconds: 5,
  handler,
-  isTool: true,
+  toolTriggerSettings: {
+    inputSchema: {
+      type: 'object',
+      properties: {
+        recipientName: { type: 'string' },
+      },
+      required: ['recipientName'],
+    },
+  },
 });
@@ -30,31 +30,31 @@ export default defineView({
  ],
  groups: [
    {
-      universalIdentifier: 'bg1a2b3c-0001-4a7b-8c9d-0e1f2a3b4c5d',
+      universalIdentifier: 'e9ed34f1-3c3d-41b1-869b-00aae0033d9c',
      fieldValue: 'DRAFT',
      position: 0,
      isVisible: true,
    },
    {
-      universalIdentifier: 'bg1a2b3c-0002-4a7b-8c9d-0e1f2a3b4c5d',
+      universalIdentifier: '19b1a3c1-53f0-4d32-b072-d645dac98e38',
      fieldValue: 'SENT',
      position: 1,
      isVisible: true,
    },
    {
-      universalIdentifier: 'bg1a2b3c-0003-4a7b-8c9d-0e1f2a3b4c5d',
+      universalIdentifier: 'f545cb5a-370d-423f-9b4e-278a9a465bdf',
      fieldValue: 'DELIVERED',
      position: 2,
      isVisible: true,
    },
    {
-      universalIdentifier: 'bg1a2b3c-0004-4a7b-8c9d-0e1f2a3b4c5d',
+      universalIdentifier: '5d4c6d5f-af53-4cd0-a843-df38915561b2',
      fieldValue: 'RETURNED',
      position: 3,
      isVisible: true,
    },
    {
-      universalIdentifier: 'bg1a2b3c-0005-4a7b-8c9d-0e1f2a3b4c5d',
+      universalIdentifier: '5ebbd7dc-9939-4594-b2a0-519269b4531f',
      fieldValue: 'LOST',
      position: 4,
      isVisible: true,
@@ -111,7 +111,8 @@ export default defineLogicFunction({
  description:
    'Structured web search powered by Exa. Returns entity-aware results with category filtering (companies, people, research papers, news, and other content types). Prefer this when the query benefits from structured data or a specific category. For general real-time web browsing, prefer the native `web_search` tool when it is available.',
  timeoutSeconds: 30,
-  isTool: true,
-  toolInputSchema: exaWebSearchInputSchema,
+  toolTriggerSettings: {
+    inputSchema: exaWebSearchInputSchema,
+  },
  handler,
 });
@@ -60,9 +60,20 @@ If you're working on this app rather than installing the published version:

 ```bash
 cd packages/twenty-apps/internal/twenty-linear
+
+# For day-to-day development (publish + install + watch in one):
+yarn twenty dev
+
+# Manual publish flow (deploy registers the app, install activates it):
 yarn twenty deploy
+yarn twenty install
 ```

+`twenty dev` is recommended for iteration — it publishes, installs, and
+watches for changes in one command. Use `twenty deploy` + `twenty install`
+when you want to control each step separately (e.g. deploying to a
+production server without auto-installing).
+
 This serves as the reference implementation for Twenty's
 `defineConnectionProvider({ type: 'oauth' })` flow — useful as a template
 when adding OAuth integrations for other providers.
@@ -20,7 +20,7 @@
    "test:watch": "vitest --config vitest.unit.config.ts"
  },
  "dependencies": {
-    "twenty-sdk": "2.1.0"
+    "twenty-sdk": "2.3.0"
  },
  "devDependencies": {
    "@types/node": "^24.7.2",
@@ -10,24 +10,56 @@ export default defineLogicFunction({
    'Create a Linear issue on behalf of the connected user. Requires a teamId (call list-linear-teams to discover one) and a title.',
  timeoutSeconds: 30,
  handler: createLinearIssueHandler,
-  isTool: true,
-  toolInputSchema: {
-    type: 'object',
-    properties: {
-      teamId: {
-        type: 'string',
-        description:
-          'The Linear team ID to create the issue in. Use list-linear-teams to discover available teams.',
-      },
-      title: {
-        type: 'string',
-        description: 'The issue title.',
-      },
-      description: {
-        type: 'string',
-        description: 'Optional issue description (Markdown supported).',
+  toolTriggerSettings: {
+    inputSchema: {
+      type: 'object',
+      properties: {
+        teamId: {
+          type: 'string',
+          description:
+            'The Linear team ID to create the issue in. Use list-linear-teams to discover available teams.',
+        },
+        title: {
+          type: 'string',
+          description: 'The issue title.',
+        },
+        description: {
+          type: 'string',
+          description: 'Optional issue description (Markdown supported).',
+        },
      },
+      required: ['teamId', 'title'],
    },
-    required: ['teamId', 'title'],
+  },
+  workflowActionTriggerSettings: {
+    label: 'Create Linear Issue',
+    inputSchema: [
+      {
+        type: 'object',
+        properties: {
+          teamId: { type: 'string' },
+          title: { type: 'string' },
+          description: { type: 'string' },
+        },
+      },
+    ],
+    outputSchema: [
+      {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean' },
+          issue: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+              identifier: { type: 'string' },
+              title: { type: 'string' },
+              url: { type: 'string' },
+            },
+          },
+          error: { type: 'string' },
+        },
+      },
+    ],
  },
 });
@@ -10,9 +10,10 @@ export default defineLogicFunction({
    "Returns the connected user's Linear teams. Useful for picking a teamId to pass to create-linear-issue.",
  timeoutSeconds: 15,
  handler: listLinearTeamsHandler,
-  isTool: true,
-  toolInputSchema: {
-    type: 'object',
-    properties: {},
+  toolTriggerSettings: {
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
  },
 });
@@ -1 +0,0 @@
-{"tags": ["scope:apps"]}
@@ -1,6 +1,6 @@
 {
  "name": "twenty-client-sdk",
-  "version": "2.2.0",
+  "version": "2.3.0",
  "sideEffects": false,
  "license": "AGPL-3.0",
  "scripts": {
@@ -51,6 +51,7 @@ type ApplicationRegistration {
  logoUrl: String
  createdAt: DateTime!
  updatedAt: DateTime!
+  isConfigured: Boolean!
 }

 enum ApplicationRegistrationSourceType {
@@ -324,6 +325,115 @@ type FrontComponent {
  applicationTokenPair: ApplicationTokenPair
 }

+type CommandMenuItem {
+  id: UUID!
+  workflowVersionId: UUID
+  frontComponentId: UUID
+  frontComponent: FrontComponent
+  engineComponentKey: EngineComponentKey!
+  label: String!
+  icon: String
+  shortLabel: String
+  position: Float!
+  isPinned: Boolean!
+  availabilityType: CommandMenuItemAvailabilityType!
+  payload: CommandMenuItemPayload
+  hotKeys: [String!]
+  conditionalAvailabilityExpression: String
+  availabilityObjectMetadataId: UUID
+  pageLayoutId: UUID
+  universalIdentifier: UUID
+  applicationId: UUID
+  createdAt: DateTime!
+  updatedAt: DateTime!
+}
+
+enum EngineComponentKey {
+  NAVIGATE_TO_NEXT_RECORD
+  NAVIGATE_TO_PREVIOUS_RECORD
+  CREATE_NEW_RECORD
+  DELETE_RECORDS
+  RESTORE_RECORDS
+  DESTROY_RECORDS
+  ADD_TO_FAVORITES
+  REMOVE_FROM_FAVORITES
+  EXPORT_NOTE_TO_PDF
+  EXPORT_RECORDS
+  UPDATE_MULTIPLE_RECORDS
+  MERGE_MULTIPLE_RECORDS
+  IMPORT_RECORDS
+  EXPORT_VIEW
+  SEE_DELETED_RECORDS
+  CREATE_NEW_VIEW
+  HIDE_DELETED_RECORDS
+  EDIT_RECORD_PAGE_LAYOUT
+  EDIT_DASHBOARD_LAYOUT
+  SAVE_DASHBOARD_LAYOUT
+  CANCEL_DASHBOARD_LAYOUT
+  DUPLICATE_DASHBOARD
+  ACTIVATE_WORKFLOW
+  DEACTIVATE_WORKFLOW
+  DISCARD_DRAFT_WORKFLOW
+  TEST_WORKFLOW
+  SEE_ACTIVE_VERSION_WORKFLOW
+  SEE_RUNS_WORKFLOW
+  SEE_VERSIONS_WORKFLOW
+  ADD_NODE_WORKFLOW
+  TIDY_UP_WORKFLOW
+  DUPLICATE_WORKFLOW
+  SEE_VERSION_WORKFLOW_RUN
+  SEE_WORKFLOW_WORKFLOW_RUN
+  STOP_WORKFLOW_RUN
+  SEE_RUNS_WORKFLOW_VERSION
+  SEE_WORKFLOW_WORKFLOW_VERSION
+  USE_AS_DRAFT_WORKFLOW_VERSION
+  SEE_VERSIONS_WORKFLOW_VERSION
+  SEARCH_RECORDS
+  SEARCH_RECORDS_FALLBACK
+  ASK_AI
+  VIEW_PREVIOUS_AI_CHATS
+  NAVIGATION
+  TRIGGER_WORKFLOW_VERSION
+  FRONT_COMPONENT_RENDERER
+  REPLY_TO_EMAIL_THREAD
+  COMPOSE_EMAIL
+  GO_TO_PEOPLE
+  GO_TO_COMPANIES
+  GO_TO_DASHBOARDS
+  GO_TO_OPPORTUNITIES
+  GO_TO_SETTINGS
+  GO_TO_TASKS
+  GO_TO_NOTES
+  GO_TO_WORKFLOWS
+  GO_TO_RUNS
+  DELETE_SINGLE_RECORD
+  DELETE_MULTIPLE_RECORDS
+  RESTORE_SINGLE_RECORD
+  RESTORE_MULTIPLE_RECORDS
+  DESTROY_SINGLE_RECORD
+  DESTROY_MULTIPLE_RECORDS
+  EXPORT_FROM_RECORD_INDEX
+  EXPORT_FROM_RECORD_SHOW
+  EXPORT_MULTIPLE_RECORDS
+}
+
+enum CommandMenuItemAvailabilityType {
+  GLOBAL
+  GLOBAL_OBJECT_CONTEXT
+  RECORD_SELECTION
+  FALLBACK
+}
+
+union CommandMenuItemPayload = PathCommandMenuItemPayload | ObjectMetadataCommandMenuItemPayload
+
+type PathCommandMenuItemPayload {
+  path: String!
+}
+
+type ObjectMetadataCommandMenuItemPayload {
+  objectMetadataItemId: UUID!
+}
+
 type LogicFunction {
  id: UUID!
  name: String!
@@ -332,11 +442,11 @@ type LogicFunction {
  timeoutSeconds: Float!
  sourceHandlerPath: String!
  handlerName: String!
-  toolInputSchema: JSON
-  isTool: Boolean!
  cronTriggerSettings: JSON
  databaseEventTriggerSettings: JSON
  httpRouteTriggerSettings: JSON
+  toolTriggerSettings: JSON
+  workflowActionTriggerSettings: JSON
  applicationId: UUID
  universalIdentifier: UUID
  createdAt: DateTime!
@@ -595,6 +705,7 @@ type Application {
  defaultLogicFunctionRole: Role
  agents: [Agent!]!
  frontComponents: [FrontComponent!]!
+  commandMenuItems: [CommandMenuItem!]!
  logicFunctions: [LogicFunction!]!
  objects: [Object!]!
  applicationVariables: [ApplicationVariable!]!
@@ -863,7 +974,6 @@ type User {
  firstName: String!
  lastName: String!
  email: String!
-  defaultAvatarUrl: String
  isEmailVerified: Boolean!
  disabled: Boolean
  canImpersonate: Boolean!
@@ -1374,6 +1484,7 @@ enum BillingUsageType {
 """The different billing products available"""
 enum BillingProductKey {
  BASE_PRODUCT
+  RESOURCE_CREDIT
  WORKFLOW_NODE_EXECUTION
 }

@@ -1382,6 +1493,7 @@ type BillingPriceLicensed {
  unitAmount: Float!
  stripePriceId: String!
  priceUsageType: BillingUsageType!
+  creditAmount: Float
 }

 enum SubscriptionInterval {
@@ -1480,7 +1592,8 @@ type BillingMeteredProductUsage {

 type BillingPlan {
  planKey: BillingPlanKey!
-  licensedProducts: [BillingLicensedProduct!]!
+  baseProducts: [BillingLicensedProduct!]!
+  resourceCreditProducts: [BillingLicensedProduct!]!
  meteredProducts: [BillingMeteredProduct!]!
 }

@@ -1639,11 +1752,13 @@ enum FeatureFlagKey {
  IS_RECORD_PAGE_LAYOUT_EDITING_ENABLED
  IS_PUBLIC_DOMAIN_ENABLED
  IS_EMAILING_DOMAIN_ENABLED
+  IS_EMAIL_GROUP_ENABLED
  IS_JUNCTION_RELATIONS_ENABLED
  IS_CONNECTED_ACCOUNT_MIGRATED
  IS_RICH_TEXT_V1_MIGRATED
  IS_RECORD_PAGE_LAYOUT_GLOBAL_EDITION_ENABLED
  IS_DATASOURCE_MIGRATED
+  IS_BILLING_V2_ENABLED
 }

 type WorkspaceUrls {
@@ -1812,6 +1927,7 @@ type ClientConfig {
  isGoogleCalendarEnabled: Boolean!
  isConfigVariablesInDbEnabled: Boolean!
  isImapSmtpCaldavEnabled: Boolean!
+  isEmailGroupEnabled: Boolean!
  allowRequestsToTwentyIcons: Boolean!
  calendarBookingPageId: String
  isCloudflareIntegrationEnabled: Boolean!
@@ -2240,6 +2356,7 @@ type PublicDomain {
  id: UUID!
  domain: String!
  isValidated: Boolean!
+  applicationId: UUID
  createdAt: DateTime!
 }

@@ -2325,114 +2442,6 @@ type PostgresCredentials {
  workspaceId: UUID!
 }

-type CommandMenuItem {
-  id: UUID!
-  workflowVersionId: UUID
-  frontComponentId: UUID
-  frontComponent: FrontComponent
-  engineComponentKey: EngineComponentKey!
-  label: String!
-  icon: String
-  shortLabel: String
-  position: Float!
-  isPinned: Boolean!
-  availabilityType: CommandMenuItemAvailabilityType!
-  payload: CommandMenuItemPayload
-  hotKeys: [String!]
-  conditionalAvailabilityExpression: String
-  availabilityObjectMetadataId: UUID
-  pageLayoutId: UUID
-  applicationId: UUID
-  createdAt: DateTime!
-  updatedAt: DateTime!
-}
-
-enum EngineComponentKey {
-  NAVIGATE_TO_NEXT_RECORD
-  NAVIGATE_TO_PREVIOUS_RECORD
-  CREATE_NEW_RECORD
-  DELETE_RECORDS
-  RESTORE_RECORDS
-  DESTROY_RECORDS
-  ADD_TO_FAVORITES
-  REMOVE_FROM_FAVORITES
-  EXPORT_NOTE_TO_PDF
-  EXPORT_RECORDS
-  UPDATE_MULTIPLE_RECORDS
-  MERGE_MULTIPLE_RECORDS
-  IMPORT_RECORDS
-  EXPORT_VIEW
-  SEE_DELETED_RECORDS
-  CREATE_NEW_VIEW
-  HIDE_DELETED_RECORDS
-  EDIT_RECORD_PAGE_LAYOUT
-  EDIT_DASHBOARD_LAYOUT
-  SAVE_DASHBOARD_LAYOUT
-  CANCEL_DASHBOARD_LAYOUT
-  DUPLICATE_DASHBOARD
-  ACTIVATE_WORKFLOW
-  DEACTIVATE_WORKFLOW
-  DISCARD_DRAFT_WORKFLOW
-  TEST_WORKFLOW
-  SEE_ACTIVE_VERSION_WORKFLOW
-  SEE_RUNS_WORKFLOW
-  SEE_VERSIONS_WORKFLOW
-  ADD_NODE_WORKFLOW
-  TIDY_UP_WORKFLOW
-  DUPLICATE_WORKFLOW
-  SEE_VERSION_WORKFLOW_RUN
-  SEE_WORKFLOW_WORKFLOW_RUN
-  STOP_WORKFLOW_RUN
-  SEE_RUNS_WORKFLOW_VERSION
-  SEE_WORKFLOW_WORKFLOW_VERSION
-  USE_AS_DRAFT_WORKFLOW_VERSION
-  SEE_VERSIONS_WORKFLOW_VERSION
-  SEARCH_RECORDS
-  SEARCH_RECORDS_FALLBACK
-  ASK_AI
-  VIEW_PREVIOUS_AI_CHATS
-  NAVIGATION
-  TRIGGER_WORKFLOW_VERSION
-  FRONT_COMPONENT_RENDERER
-  REPLY_TO_EMAIL_THREAD
-  COMPOSE_EMAIL
-  GO_TO_PEOPLE
-  GO_TO_COMPANIES
-  GO_TO_DASHBOARDS
-  GO_TO_OPPORTUNITIES
-  GO_TO_SETTINGS
-  GO_TO_TASKS
-  GO_TO_NOTES
-  GO_TO_WORKFLOWS
-  GO_TO_RUNS
-  DELETE_SINGLE_RECORD
-  DELETE_MULTIPLE_RECORDS
-  RESTORE_SINGLE_RECORD
-  RESTORE_MULTIPLE_RECORDS
-  DESTROY_SINGLE_RECORD
-  DESTROY_MULTIPLE_RECORDS
-  EXPORT_FROM_RECORD_INDEX
-  EXPORT_FROM_RECORD_SHOW
-  EXPORT_MULTIPLE_RECORDS
-}
-
-enum CommandMenuItemAvailabilityType {
-  GLOBAL
-  GLOBAL_OBJECT_CONTEXT
-  RECORD_SELECTION
-  FALLBACK
-}
-
-union CommandMenuItemPayload = PathCommandMenuItemPayload | ObjectMetadataCommandMenuItemPayload
-
-type PathCommandMenuItemPayload {
-  path: String!
-}
-
-type ObjectMetadataCommandMenuItemPayload {
-  objectMetadataItemId: UUID!
-}
-
 type ToolIndexEntry {
  name: String!
  description: String!
@@ -2551,7 +2560,7 @@ type ConnectedAccountDTO {
  connectionParameters: ImapSmtpCaldavConnectionParameters
  lastSignedInAt: DateTime
  userWorkspaceId: UUID!
-  applicationConnectionProviderId: UUID
+  connectionProviderId: UUID
  applicationId: UUID
  name: String
  visibility: String!
@@ -2582,7 +2591,7 @@ type ConnectedAccountPublicDTO {
  scopes: [String!]
  lastSignedInAt: DateTime
  userWorkspaceId: UUID!
-  applicationConnectionProviderId: UUID
+  connectionProviderId: UUID
  applicationId: UUID
  name: String
  visibility: String!
@@ -2771,6 +2780,7 @@ type MessageChannel {
  connectedAccountId: UUID!
  createdAt: DateTime!
  updatedAt: DateTime!
+  connectedAccount: ConnectedAccountPublicDTO
 }

 enum MessageChannelVisibility {
@@ -2782,6 +2792,7 @@ enum MessageChannelVisibility {
 enum MessageChannelType {
  EMAIL
  SMS
+  EMAIL_GROUP
 }

 enum MessageChannelContactAutoCreationPolicy {
@@ -2820,6 +2831,11 @@ enum MessageChannelSyncStage {
  FAILED
 }

+type CreateEmailGroupChannelOutput {
+  messageChannel: MessageChannel!
+  forwardingAddress: String!
+}
+
 type MessageFolder {
  id: UUID!
  name: String
@@ -2871,6 +2887,8 @@ enum AllMetadataName {
  fieldPermission
  frontComponent
  webhook
+  applicationVariable
+  connectionProvider
 }

 type MinimalObjectMetadata {
@@ -3235,6 +3253,8 @@ type Mutation {
  updateMessageFolder(input: UpdateMessageFolderInput!): MessageFolder!
  updateMessageFolders(input: UpdateMessageFoldersInput!): [MessageFolder!]!
  updateMessageChannel(input: UpdateMessageChannelInput!): MessageChannel!
+  createEmailGroupChannel(input: CreateEmailGroupChannelInput!): CreateEmailGroupChannelOutput!
+  deleteEmailGroupChannel(id: UUID!): MessageChannel!
  deleteConnectedAccount(id: UUID!): ConnectedAccountDTO!
  updateCalendarChannel(input: UpdateCalendarChannelInput!): CalendarChannel!
  createWebhook(input: CreateWebhookInput!): Webhook!
@@ -3308,7 +3328,8 @@ type Mutation {
  updateLabPublicFeatureFlag(input: UpdateLabPublicFeatureFlagInput!): FeatureFlag!
  enablePostgresProxy: PostgresCredentials!
  disablePostgresProxy: PostgresCredentials!
-  createPublicDomain(domain: String!): PublicDomain!
+  createPublicDomain(domain: String!, applicationId: String): PublicDomain!
+  updatePublicDomain(domain: String!, applicationId: String): PublicDomain!
  deletePublicDomain(domain: String!): Boolean!
  checkPublicDomainValidRecords(domain: String!): DomainValidRecords
  createEmailingDomain(domain: String!, driver: EmailingDomainDriver!): EmailingDomain!
@@ -3779,12 +3800,12 @@ input CreateLogicFunctionFromSourceInput {
  name: String!
  description: String
  timeoutSeconds: Float
-  toolInputSchema: JSON
-  isTool: Boolean
  source: JSON
  cronTriggerSettings: JSON
  databaseEventTriggerSettings: JSON
  httpRouteTriggerSettings: JSON
+  toolTriggerSettings: JSON
+  workflowActionTriggerSettings: JSON
 }

 input ExecuteOneLogicFunctionInput {
@@ -3808,13 +3829,13 @@ input UpdateLogicFunctionFromSourceInputUpdates {
  description: String
  timeoutSeconds: Float
  sourceHandlerCode: String
-  toolInputSchema: JSON
  handlerName: String
  sourceHandlerPath: String
-  isTool: Boolean
  cronTriggerSettings: JSON
  databaseEventTriggerSettings: JSON
  httpRouteTriggerSettings: JSON
+  toolTriggerSettings: JSON
+  workflowActionTriggerSettings: JSON
 }

 input CreateCommandMenuItemInput {
@@ -4163,6 +4184,10 @@ input UpdateMessageChannelInputUpdates {
  excludeGroupEmails: Boolean
 }

+input CreateEmailGroupChannelInput {
+  handle: String!
+}
+
 input UpdateCalendarChannelInput {
  id: UUID!
  update: UpdateCalendarChannelInputUpdates!
@@ -55,6 +55,7 @@ export interface ApplicationRegistration {
    logoUrl?: Scalars['String']
    createdAt: Scalars['DateTime']
    updatedAt: Scalars['DateTime']
+    isConfigured: Scalars['Boolean']
    __typename: 'ApplicationRegistration'
 }

@@ -278,6 +279,46 @@ export interface FrontComponent {
    __typename: 'FrontComponent'
 }

+export interface CommandMenuItem {
+    id: Scalars['UUID']
+    workflowVersionId?: Scalars['UUID']
+    frontComponentId?: Scalars['UUID']
+    frontComponent?: FrontComponent
+    engineComponentKey: EngineComponentKey
+    label: Scalars['String']
+    icon?: Scalars['String']
+    shortLabel?: Scalars['String']
+    position: Scalars['Float']
+    isPinned: Scalars['Boolean']
+    availabilityType: CommandMenuItemAvailabilityType
+    payload?: CommandMenuItemPayload
+    hotKeys?: Scalars['String'][]
+    conditionalAvailabilityExpression?: Scalars['String']
+    availabilityObjectMetadataId?: Scalars['UUID']
+    pageLayoutId?: Scalars['UUID']
+    universalIdentifier?: Scalars['UUID']
+    applicationId?: Scalars['UUID']
+    createdAt: Scalars['DateTime']
+    updatedAt: Scalars['DateTime']
+    __typename: 'CommandMenuItem'
+}
+
+export type EngineComponentKey = 'NAVIGATE_TO_NEXT_RECORD' | 'NAVIGATE_TO_PREVIOUS_RECORD' | 'CREATE_NEW_RECORD' | 'DELETE_RECORDS' | 'RESTORE_RECORDS' | 'DESTROY_RECORDS' | 'ADD_TO_FAVORITES' | 'REMOVE_FROM_FAVORITES' | 'EXPORT_NOTE_TO_PDF' | 'EXPORT_RECORDS' | 'UPDATE_MULTIPLE_RECORDS' | 'MERGE_MULTIPLE_RECORDS' | 'IMPORT_RECORDS' | 'EXPORT_VIEW' | 'SEE_DELETED_RECORDS' | 'CREATE_NEW_VIEW' | 'HIDE_DELETED_RECORDS' | 'EDIT_RECORD_PAGE_LAYOUT' | 'EDIT_DASHBOARD_LAYOUT' | 'SAVE_DASHBOARD_LAYOUT' | 'CANCEL_DASHBOARD_LAYOUT' | 'DUPLICATE_DASHBOARD' | 'ACTIVATE_WORKFLOW' | 'DEACTIVATE_WORKFLOW' | 'DISCARD_DRAFT_WORKFLOW' | 'TEST_WORKFLOW' | 'SEE_ACTIVE_VERSION_WORKFLOW' | 'SEE_RUNS_WORKFLOW' | 'SEE_VERSIONS_WORKFLOW' | 'ADD_NODE_WORKFLOW' | 'TIDY_UP_WORKFLOW' | 'DUPLICATE_WORKFLOW' | 'SEE_VERSION_WORKFLOW_RUN' | 'SEE_WORKFLOW_WORKFLOW_RUN' | 'STOP_WORKFLOW_RUN' | 'SEE_RUNS_WORKFLOW_VERSION' | 'SEE_WORKFLOW_WORKFLOW_VERSION' | 'USE_AS_DRAFT_WORKFLOW_VERSION' | 'SEE_VERSIONS_WORKFLOW_VERSION' | 'SEARCH_RECORDS' | 'SEARCH_RECORDS_FALLBACK' | 'ASK_AI' | 'VIEW_PREVIOUS_AI_CHATS' | 'NAVIGATION' | 'TRIGGER_WORKFLOW_VERSION' | 'FRONT_COMPONENT_RENDERER' | 'REPLY_TO_EMAIL_THREAD' | 'COMPOSE_EMAIL' | 'GO_TO_PEOPLE' | 'GO_TO_COMPANIES' | 'GO_TO_DASHBOARDS' | 'GO_TO_OPPORTUNITIES' | 'GO_TO_SETTINGS' | 'GO_TO_TASKS' | 'GO_TO_NOTES' | 'GO_TO_WORKFLOWS' | 'GO_TO_RUNS' | 'DELETE_SINGLE_RECORD' | 'DELETE_MULTIPLE_RECORDS' | 'RESTORE_SINGLE_RECORD' | 'RESTORE_MULTIPLE_RECORDS' | 'DESTROY_SINGLE_RECORD' | 'DESTROY_MULTIPLE_RECORDS' | 'EXPORT_FROM_RECORD_INDEX' | 'EXPORT_FROM_RECORD_SHOW' | 'EXPORT_MULTIPLE_RECORDS'
+
+export type CommandMenuItemAvailabilityType = 'GLOBAL' | 'GLOBAL_OBJECT_CONTEXT' | 'RECORD_SELECTION' | 'FALLBACK'
+
+export type CommandMenuItemPayload = (PathCommandMenuItemPayload | ObjectMetadataCommandMenuItemPayload) & { __isUnion?: true }
+
+export interface PathCommandMenuItemPayload {
+    path: Scalars['String']
+    __typename: 'PathCommandMenuItemPayload'
+}
+
+export interface ObjectMetadataCommandMenuItemPayload {
+    objectMetadataItemId: Scalars['UUID']
+    __typename: 'ObjectMetadataCommandMenuItemPayload'
+}
+
 export interface LogicFunction {
    id: Scalars['UUID']
    name: Scalars['String']
@@ -286,11 +327,11 @@ export interface LogicFunction {
    timeoutSeconds: Scalars['Float']
    sourceHandlerPath: Scalars['String']
    handlerName: Scalars['String']
-    toolInputSchema?: Scalars['JSON']
-    isTool: Scalars['Boolean']
    cronTriggerSettings?: Scalars['JSON']
    databaseEventTriggerSettings?: Scalars['JSON']
    httpRouteTriggerSettings?: Scalars['JSON']
+    toolTriggerSettings?: Scalars['JSON']
+    workflowActionTriggerSettings?: Scalars['JSON']
    applicationId?: Scalars['UUID']
    universalIdentifier?: Scalars['UUID']
    createdAt: Scalars['DateTime']
@@ -429,6 +470,7 @@ export interface Application {
    defaultLogicFunctionRole?: Role
    agents: Agent[]
    frontComponents: FrontComponent[]
+    commandMenuItems: CommandMenuItem[]
    logicFunctions: LogicFunction[]
    objects: Object[]
    applicationVariables: ApplicationVariable[]
@@ -648,7 +690,6 @@ export interface User {
    firstName: Scalars['String']
    lastName: Scalars['String']
    email: Scalars['String']
-    defaultAvatarUrl?: Scalars['String']
    isEmailVerified: Scalars['Boolean']
    disabled?: Scalars['Boolean']
    canImpersonate: Scalars['Boolean']
@@ -1104,13 +1145,14 @@ export type BillingUsageType = 'METERED' | 'LICENSED'


 /** The different billing products available */
-export type BillingProductKey = 'BASE_PRODUCT' | 'WORKFLOW_NODE_EXECUTION'
+export type BillingProductKey = 'BASE_PRODUCT' | 'RESOURCE_CREDIT' | 'WORKFLOW_NODE_EXECUTION'

 export interface BillingPriceLicensed {
    recurringInterval: SubscriptionInterval
    unitAmount: Scalars['Float']
    stripePriceId: Scalars['String']
    priceUsageType: BillingUsageType
+    creditAmount?: Scalars['Float']
    __typename: 'BillingPriceLicensed'
 }

@@ -1203,7 +1245,8 @@ export interface BillingMeteredProductUsage {

 export interface BillingPlan {
    planKey: BillingPlanKey
-    licensedProducts: BillingLicensedProduct[]
+    baseProducts: BillingLicensedProduct[]
+    resourceCreditProducts: BillingLicensedProduct[]
    meteredProducts: BillingMeteredProduct[]
    __typename: 'BillingPlan'
 }
@@ -1345,7 +1388,7 @@ export interface FeatureFlag {
    __typename: 'FeatureFlag'
 }

-export type FeatureFlagKey = 'IS_UNIQUE_INDEXES_ENABLED' | 'IS_JSON_FILTER_ENABLED' | 'IS_COMMAND_MENU_ITEM_ENABLED' | 'IS_MARKETPLACE_SETTING_TAB_VISIBLE' | 'IS_RECORD_PAGE_LAYOUT_EDITING_ENABLED' | 'IS_PUBLIC_DOMAIN_ENABLED' | 'IS_EMAILING_DOMAIN_ENABLED' | 'IS_JUNCTION_RELATIONS_ENABLED' | 'IS_CONNECTED_ACCOUNT_MIGRATED' | 'IS_RICH_TEXT_V1_MIGRATED' | 'IS_RECORD_PAGE_LAYOUT_GLOBAL_EDITION_ENABLED' | 'IS_DATASOURCE_MIGRATED'
+export type FeatureFlagKey = 'IS_UNIQUE_INDEXES_ENABLED' | 'IS_JSON_FILTER_ENABLED' | 'IS_COMMAND_MENU_ITEM_ENABLED' | 'IS_MARKETPLACE_SETTING_TAB_VISIBLE' | 'IS_RECORD_PAGE_LAYOUT_EDITING_ENABLED' | 'IS_PUBLIC_DOMAIN_ENABLED' | 'IS_EMAILING_DOMAIN_ENABLED' | 'IS_EMAIL_GROUP_ENABLED' | 'IS_JUNCTION_RELATIONS_ENABLED' | 'IS_CONNECTED_ACCOUNT_MIGRATED' | 'IS_RICH_TEXT_V1_MIGRATED' | 'IS_RECORD_PAGE_LAYOUT_GLOBAL_EDITION_ENABLED' | 'IS_DATASOURCE_MIGRATED' | 'IS_BILLING_V2_ENABLED'

 export interface WorkspaceUrls {
    customUrl?: Scalars['String']
@@ -1511,6 +1554,7 @@ export interface ClientConfig {
    isGoogleCalendarEnabled: Scalars['Boolean']
    isConfigVariablesInDbEnabled: Scalars['Boolean']
    isImapSmtpCaldavEnabled: Scalars['Boolean']
+    isEmailGroupEnabled: Scalars['Boolean']
    allowRequestsToTwentyIcons: Scalars['Boolean']
    calendarBookingPageId?: Scalars['String']
    isCloudflareIntegrationEnabled: Scalars['Boolean']
@@ -1982,6 +2026,7 @@ export interface PublicDomain {
    id: Scalars['UUID']
    domain: Scalars['String']
    isValidated: Scalars['Boolean']
+    applicationId?: Scalars['UUID']
    createdAt: Scalars['DateTime']
    __typename: 'PublicDomain'
 }
@@ -2071,45 +2116,6 @@ export interface PostgresCredentials {
    __typename: 'PostgresCredentials'
 }

-export interface CommandMenuItem {
-    id: Scalars['UUID']
-    workflowVersionId?: Scalars['UUID']
-    frontComponentId?: Scalars['UUID']
-    frontComponent?: FrontComponent
-    engineComponentKey: EngineComponentKey
-    label: Scalars['String']
-    icon?: Scalars['String']
-    shortLabel?: Scalars['String']
-    position: Scalars['Float']
-    isPinned: Scalars['Boolean']
-    availabilityType: CommandMenuItemAvailabilityType
-    payload?: CommandMenuItemPayload
-    hotKeys?: Scalars['String'][]
-    conditionalAvailabilityExpression?: Scalars['String']
-    availabilityObjectMetadataId?: Scalars['UUID']
-    pageLayoutId?: Scalars['UUID']
-    applicationId?: Scalars['UUID']
-    createdAt: Scalars['DateTime']
-    updatedAt: Scalars['DateTime']
-    __typename: 'CommandMenuItem'
-}
-
-export type EngineComponentKey = 'NAVIGATE_TO_NEXT_RECORD' | 'NAVIGATE_TO_PREVIOUS_RECORD' | 'CREATE_NEW_RECORD' | 'DELETE_RECORDS' | 'RESTORE_RECORDS' | 'DESTROY_RECORDS' | 'ADD_TO_FAVORITES' | 'REMOVE_FROM_FAVORITES' | 'EXPORT_NOTE_TO_PDF' | 'EXPORT_RECORDS' | 'UPDATE_MULTIPLE_RECORDS' | 'MERGE_MULTIPLE_RECORDS' | 'IMPORT_RECORDS' | 'EXPORT_VIEW' | 'SEE_DELETED_RECORDS' | 'CREATE_NEW_VIEW' | 'HIDE_DELETED_RECORDS' | 'EDIT_RECORD_PAGE_LAYOUT' | 'EDIT_DASHBOARD_LAYOUT' | 'SAVE_DASHBOARD_LAYOUT' | 'CANCEL_DASHBOARD_LAYOUT' | 'DUPLICATE_DASHBOARD' | 'ACTIVATE_WORKFLOW' | 'DEACTIVATE_WORKFLOW' | 'DISCARD_DRAFT_WORKFLOW' | 'TEST_WORKFLOW' | 'SEE_ACTIVE_VERSION_WORKFLOW' | 'SEE_RUNS_WORKFLOW' | 'SEE_VERSIONS_WORKFLOW' | 'ADD_NODE_WORKFLOW' | 'TIDY_UP_WORKFLOW' | 'DUPLICATE_WORKFLOW' | 'SEE_VERSION_WORKFLOW_RUN' | 'SEE_WORKFLOW_WORKFLOW_RUN' | 'STOP_WORKFLOW_RUN' | 'SEE_RUNS_WORKFLOW_VERSION' | 'SEE_WORKFLOW_WORKFLOW_VERSION' | 'USE_AS_DRAFT_WORKFLOW_VERSION' | 'SEE_VERSIONS_WORKFLOW_VERSION' | 'SEARCH_RECORDS' | 'SEARCH_RECORDS_FALLBACK' | 'ASK_AI' | 'VIEW_PREVIOUS_AI_CHATS' | 'NAVIGATION' | 'TRIGGER_WORKFLOW_VERSION' | 'FRONT_COMPONENT_RENDERER' | 'REPLY_TO_EMAIL_THREAD' | 'COMPOSE_EMAIL' | 'GO_TO_PEOPLE' | 'GO_TO_COMPANIES' | 'GO_TO_DASHBOARDS' | 'GO_TO_OPPORTUNITIES' | 'GO_TO_SETTINGS' | 'GO_TO_TASKS' | 'GO_TO_NOTES' | 'GO_TO_WORKFLOWS' | 'GO_TO_RUNS' | 'DELETE_SINGLE_RECORD' | 'DELETE_MULTIPLE_RECORDS' | 'RESTORE_SINGLE_RECORD' | 'RESTORE_MULTIPLE_RECORDS' | 'DESTROY_SINGLE_RECORD' | 'DESTROY_MULTIPLE_RECORDS' | 'EXPORT_FROM_RECORD_INDEX' | 'EXPORT_FROM_RECORD_SHOW' | 'EXPORT_MULTIPLE_RECORDS'
-
-export type CommandMenuItemAvailabilityType = 'GLOBAL' | 'GLOBAL_OBJECT_CONTEXT' | 'RECORD_SELECTION' | 'FALLBACK'
-
-export type CommandMenuItemPayload = (PathCommandMenuItemPayload | ObjectMetadataCommandMenuItemPayload) & { __isUnion?: true }
-
-export interface PathCommandMenuItemPayload {
-    path: Scalars['String']
-    __typename: 'PathCommandMenuItemPayload'
-}
-
-export interface ObjectMetadataCommandMenuItemPayload {
-    objectMetadataItemId: Scalars['UUID']
-    __typename: 'ObjectMetadataCommandMenuItemPayload'
-}
-
 export interface ToolIndexEntry {
    name: Scalars['String']
    description: Scalars['String']
@@ -2239,7 +2245,7 @@ export interface ConnectedAccountDTO {
    connectionParameters?: ImapSmtpCaldavConnectionParameters
    lastSignedInAt?: Scalars['DateTime']
    userWorkspaceId: Scalars['UUID']
-    applicationConnectionProviderId?: Scalars['UUID']
+    connectionProviderId?: Scalars['UUID']
    applicationId?: Scalars['UUID']
    name?: Scalars['String']
    visibility: Scalars['String']
@@ -2273,7 +2279,7 @@ export interface ConnectedAccountPublicDTO {
    scopes?: Scalars['String'][]
    lastSignedInAt?: Scalars['DateTime']
    userWorkspaceId: Scalars['UUID']
-    applicationConnectionProviderId?: Scalars['UUID']
+    connectionProviderId?: Scalars['UUID']
    applicationId?: Scalars['UUID']
    name?: Scalars['String']
    visibility: Scalars['String']
@@ -2455,12 +2461,13 @@ export interface MessageChannel {
    connectedAccountId: Scalars['UUID']
    createdAt: Scalars['DateTime']
    updatedAt: Scalars['DateTime']
+    connectedAccount?: ConnectedAccountPublicDTO
    __typename: 'MessageChannel'
 }

 export type MessageChannelVisibility = 'METADATA' | 'SUBJECT' | 'SHARE_EVERYTHING'

-export type MessageChannelType = 'EMAIL' | 'SMS'
+export type MessageChannelType = 'EMAIL' | 'SMS' | 'EMAIL_GROUP'

 export type MessageChannelContactAutoCreationPolicy = 'SENT_AND_RECEIVED' | 'SENT' | 'NONE'

@@ -2472,6 +2479,12 @@ export type MessageChannelSyncStatus = 'NOT_SYNCED' | 'ONGOING' | 'ACTIVE' | 'FA

 export type MessageChannelSyncStage = 'PENDING_CONFIGURATION' | 'MESSAGE_LIST_FETCH_PENDING' | 'MESSAGE_LIST_FETCH_SCHEDULED' | 'MESSAGE_LIST_FETCH_ONGOING' | 'MESSAGES_IMPORT_PENDING' | 'MESSAGES_IMPORT_SCHEDULED' | 'MESSAGES_IMPORT_ONGOING' | 'FAILED'

+export interface CreateEmailGroupChannelOutput {
+    messageChannel: MessageChannel
+    forwardingAddress: Scalars['String']
+    __typename: 'CreateEmailGroupChannelOutput'
+}
+
 export interface MessageFolder {
    id: Scalars['UUID']
    name?: Scalars['String']
@@ -2494,7 +2507,7 @@ export interface CollectionHash {
    __typename: 'CollectionHash'
 }

-export type AllMetadataName = 'fieldMetadata' | 'objectMetadata' | 'view' | 'viewField' | 'viewFieldGroup' | 'viewGroup' | 'viewSort' | 'rowLevelPermissionPredicate' | 'rowLevelPermissionPredicateGroup' | 'viewFilterGroup' | 'index' | 'logicFunction' | 'viewFilter' | 'role' | 'roleTarget' | 'agent' | 'skill' | 'pageLayout' | 'pageLayoutWidget' | 'pageLayoutTab' | 'commandMenuItem' | 'navigationMenuItem' | 'permissionFlag' | 'objectPermission' | 'fieldPermission' | 'frontComponent' | 'webhook'
+export type AllMetadataName = 'fieldMetadata' | 'objectMetadata' | 'view' | 'viewField' | 'viewFieldGroup' | 'viewGroup' | 'viewSort' | 'rowLevelPermissionPredicate' | 'rowLevelPermissionPredicateGroup' | 'viewFilterGroup' | 'index' | 'logicFunction' | 'viewFilter' | 'role' | 'roleTarget' | 'agent' | 'skill' | 'pageLayout' | 'pageLayoutWidget' | 'pageLayoutTab' | 'commandMenuItem' | 'navigationMenuItem' | 'permissionFlag' | 'objectPermission' | 'fieldPermission' | 'frontComponent' | 'webhook' | 'applicationVariable' | 'connectionProvider'

 export interface MinimalObjectMetadata {
    id: Scalars['UUID']
@@ -2768,6 +2781,8 @@ export interface Mutation {
    updateMessageFolder: MessageFolder
    updateMessageFolders: MessageFolder[]
    updateMessageChannel: MessageChannel
+    createEmailGroupChannel: CreateEmailGroupChannelOutput
+    deleteEmailGroupChannel: MessageChannel
    deleteConnectedAccount: ConnectedAccountDTO
    updateCalendarChannel: CalendarChannel
    createWebhook: Webhook
@@ -2842,6 +2857,7 @@ export interface Mutation {
    enablePostgresProxy: PostgresCredentials
    disablePostgresProxy: PostgresCredentials
    createPublicDomain: PublicDomain
+    updatePublicDomain: PublicDomain
    deletePublicDomain: Scalars['Boolean']
    checkPublicDomainValidRecords?: DomainValidRecords
    createEmailingDomain: EmailingDomain
@@ -2925,6 +2941,7 @@ export interface ApplicationRegistrationGenqlSelection{
    logoUrl?: boolean | number
    createdAt?: boolean | number
    updatedAt?: boolean | number
+    isConfigured?: boolean | number
    __typename?: boolean | number
    __scalar?: boolean | number
 }
@@ -3146,6 +3163,49 @@ export interface FrontComponentGenqlSelection{
    __scalar?: boolean | number
 }

+export interface CommandMenuItemGenqlSelection{
+    id?: boolean | number
+    workflowVersionId?: boolean | number
+    frontComponentId?: boolean | number
+    frontComponent?: FrontComponentGenqlSelection
+    engineComponentKey?: boolean | number
+    label?: boolean | number
+    icon?: boolean | number
+    shortLabel?: boolean | number
+    position?: boolean | number
+    isPinned?: boolean | number
+    availabilityType?: boolean | number
+    payload?: CommandMenuItemPayloadGenqlSelection
+    hotKeys?: boolean | number
+    conditionalAvailabilityExpression?: boolean | number
+    availabilityObjectMetadataId?: boolean | number
+    pageLayoutId?: boolean | number
+    universalIdentifier?: boolean | number
+    applicationId?: boolean | number
+    createdAt?: boolean | number
+    updatedAt?: boolean | number
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
+export interface CommandMenuItemPayloadGenqlSelection{
+    on_PathCommandMenuItemPayload?:PathCommandMenuItemPayloadGenqlSelection,
+    on_ObjectMetadataCommandMenuItemPayload?:ObjectMetadataCommandMenuItemPayloadGenqlSelection,
+    __typename?: boolean | number
+}
+
+export interface PathCommandMenuItemPayloadGenqlSelection{
+    path?: boolean | number
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
+export interface ObjectMetadataCommandMenuItemPayloadGenqlSelection{
+    objectMetadataItemId?: boolean | number
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
 export interface LogicFunctionGenqlSelection{
    id?: boolean | number
    name?: boolean | number
@@ -3154,11 +3214,11 @@ export interface LogicFunctionGenqlSelection{
    timeoutSeconds?: boolean | number
    sourceHandlerPath?: boolean | number
    handlerName?: boolean | number
-    toolInputSchema?: boolean | number
-    isTool?: boolean | number
    cronTriggerSettings?: boolean | number
    databaseEventTriggerSettings?: boolean | number
    httpRouteTriggerSettings?: boolean | number
+    toolTriggerSettings?: boolean | number
+    workflowActionTriggerSettings?: boolean | number
    applicationId?: boolean | number
    universalIdentifier?: boolean | number
    createdAt?: boolean | number
@@ -3334,6 +3394,7 @@ export interface ApplicationGenqlSelection{
    defaultLogicFunctionRole?: RoleGenqlSelection
    agents?: AgentGenqlSelection
    frontComponents?: FrontComponentGenqlSelection
+    commandMenuItems?: CommandMenuItemGenqlSelection
    logicFunctions?: LogicFunctionGenqlSelection
    objects?: ObjectGenqlSelection
    applicationVariables?: ApplicationVariableGenqlSelection
@@ -3543,7 +3604,6 @@ export interface UserGenqlSelection{
    firstName?: boolean | number
    lastName?: boolean | number
    email?: boolean | number
-    defaultAvatarUrl?: boolean | number
    isEmailVerified?: boolean | number
    disabled?: boolean | number
    canImpersonate?: boolean | number
@@ -4033,6 +4093,7 @@ export interface BillingPriceLicensedGenqlSelection{
    unitAmount?: boolean | number
    stripePriceId?: boolean | number
    priceUsageType?: boolean | number
+    creditAmount?: boolean | number
    __typename?: boolean | number
    __scalar?: boolean | number
 }
@@ -4131,7 +4192,8 @@ export interface BillingMeteredProductUsageGenqlSelection{

 export interface BillingPlanGenqlSelection{
    planKey?: boolean | number
-    licensedProducts?: BillingLicensedProductGenqlSelection
+    baseProducts?: BillingLicensedProductGenqlSelection
+    resourceCreditProducts?: BillingLicensedProductGenqlSelection
    meteredProducts?: BillingMeteredProductGenqlSelection
    __typename?: boolean | number
    __scalar?: boolean | number
@@ -4445,6 +4507,7 @@ export interface ClientConfigGenqlSelection{
    isGoogleCalendarEnabled?: boolean | number
    isConfigVariablesInDbEnabled?: boolean | number
    isImapSmtpCaldavEnabled?: boolean | number
+    isEmailGroupEnabled?: boolean | number
    allowRequestsToTwentyIcons?: boolean | number
    calendarBookingPageId?: boolean | number
    isCloudflareIntegrationEnabled?: boolean | number
@@ -4974,6 +5037,7 @@ export interface PublicDomainGenqlSelection{
    id?: boolean | number
    domain?: boolean | number
    isValidated?: boolean | number
+    applicationId?: boolean | number
    createdAt?: boolean | number
    __typename?: boolean | number
    __scalar?: boolean | number
@@ -5070,48 +5134,6 @@ export interface PostgresCredentialsGenqlSelection{
    __scalar?: boolean | number
 }

-export interface CommandMenuItemGenqlSelection{
-    id?: boolean | number
-    workflowVersionId?: boolean | number
-    frontComponentId?: boolean | number
-    frontComponent?: FrontComponentGenqlSelection
-    engineComponentKey?: boolean | number
-    label?: boolean | number
-    icon?: boolean | number
-    shortLabel?: boolean | number
-    position?: boolean | number
-    isPinned?: boolean | number
-    availabilityType?: boolean | number
-    payload?: CommandMenuItemPayloadGenqlSelection
-    hotKeys?: boolean | number
-    conditionalAvailabilityExpression?: boolean | number
-    availabilityObjectMetadataId?: boolean | number
-    pageLayoutId?: boolean | number
-    applicationId?: boolean | number
-    createdAt?: boolean | number
-    updatedAt?: boolean | number
-    __typename?: boolean | number
-    __scalar?: boolean | number
-}
-
-export interface CommandMenuItemPayloadGenqlSelection{
-    on_PathCommandMenuItemPayload?:PathCommandMenuItemPayloadGenqlSelection,
-    on_ObjectMetadataCommandMenuItemPayload?:ObjectMetadataCommandMenuItemPayloadGenqlSelection,
-    __typename?: boolean | number
-}
-
-export interface PathCommandMenuItemPayloadGenqlSelection{
-    path?: boolean | number
-    __typename?: boolean | number
-    __scalar?: boolean | number
-}
-
-export interface ObjectMetadataCommandMenuItemPayloadGenqlSelection{
-    objectMetadataItemId?: boolean | number
-    __typename?: boolean | number
-    __scalar?: boolean | number
-}
-
 export interface ToolIndexEntryGenqlSelection{
    name?: boolean | number
    description?: boolean | number
@@ -5252,7 +5274,7 @@ export interface ConnectedAccountDTOGenqlSelection{
    connectionParameters?: ImapSmtpCaldavConnectionParametersGenqlSelection
    lastSignedInAt?: boolean | number
    userWorkspaceId?: boolean | number
-    applicationConnectionProviderId?: boolean | number
+    connectionProviderId?: boolean | number
    applicationId?: boolean | number
    name?: boolean | number
    visibility?: boolean | number
@@ -5289,7 +5311,7 @@ export interface ConnectedAccountPublicDTOGenqlSelection{
    scopes?: boolean | number
    lastSignedInAt?: boolean | number
    userWorkspaceId?: boolean | number
-    applicationConnectionProviderId?: boolean | number
+    connectionProviderId?: boolean | number
    applicationId?: boolean | number
    name?: boolean | number
    visibility?: boolean | number
@@ -5479,6 +5501,14 @@ export interface MessageChannelGenqlSelection{
    connectedAccountId?: boolean | number
    createdAt?: boolean | number
    updatedAt?: boolean | number
+    connectedAccount?: ConnectedAccountPublicDTOGenqlSelection
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
+export interface CreateEmailGroupChannelOutputGenqlSelection{
+    messageChannel?: MessageChannelGenqlSelection
+    forwardingAddress?: boolean | number
    __typename?: boolean | number
    __scalar?: boolean | number
 }
@@ -5820,6 +5850,8 @@ export interface MutationGenqlSelection{
    updateMessageFolder?: (MessageFolderGenqlSelection & { __args: {input: UpdateMessageFolderInput} })
    updateMessageFolders?: (MessageFolderGenqlSelection & { __args: {input: UpdateMessageFoldersInput} })
    updateMessageChannel?: (MessageChannelGenqlSelection & { __args: {input: UpdateMessageChannelInput} })
+    createEmailGroupChannel?: (CreateEmailGroupChannelOutputGenqlSelection & { __args: {input: CreateEmailGroupChannelInput} })
+    deleteEmailGroupChannel?: (MessageChannelGenqlSelection & { __args: {id: Scalars['UUID']} })
    deleteConnectedAccount?: (ConnectedAccountDTOGenqlSelection & { __args: {id: Scalars['UUID']} })
    updateCalendarChannel?: (CalendarChannelGenqlSelection & { __args: {input: UpdateCalendarChannelInput} })
    createWebhook?: (WebhookGenqlSelection & { __args: {input: CreateWebhookInput} })
@@ -5893,7 +5925,8 @@ export interface MutationGenqlSelection{
    updateLabPublicFeatureFlag?: (FeatureFlagGenqlSelection & { __args: {input: UpdateLabPublicFeatureFlagInput} })
    enablePostgresProxy?: PostgresCredentialsGenqlSelection
    disablePostgresProxy?: PostgresCredentialsGenqlSelection
-    createPublicDomain?: (PublicDomainGenqlSelection & { __args: {domain: Scalars['String']} })
+    createPublicDomain?: (PublicDomainGenqlSelection & { __args: {domain: Scalars['String'], applicationId?: (Scalars['String'] | null)} })
+    updatePublicDomain?: (PublicDomainGenqlSelection & { __args: {domain: Scalars['String'], applicationId?: (Scalars['String'] | null)} })
    deletePublicDomain?: { __args: {domain: Scalars['String']} }
    checkPublicDomainValidRecords?: (DomainValidRecordsGenqlSelection & { __args: {domain: Scalars['String']} })
    createEmailingDomain?: (EmailingDomainGenqlSelection & { __args: {domain: Scalars['String'], driver: EmailingDomainDriver} })
@@ -6078,7 +6111,7 @@ export interface CreatePageLayoutWidgetInput {pageLayoutTabId: Scalars['UUID'],t

 export interface UpdatePageLayoutWidgetInput {pageLayoutTabId?: (Scalars['UUID'] | null),title?: (Scalars['String'] | null),type?: (WidgetType | null),objectMetadataId?: (Scalars['UUID'] | null),gridPosition?: (GridPositionInput | null),position?: (Scalars['JSON'] | null),configuration?: (Scalars['JSON'] | null),conditionalDisplay?: (Scalars['JSON'] | null),conditionalAvailabilityExpression?: (Scalars['String'] | null)}

-export interface CreateLogicFunctionFromSourceInput {id?: (Scalars['UUID'] | null),universalIdentifier?: (Scalars['UUID'] | null),name: Scalars['String'],description?: (Scalars['String'] | null),timeoutSeconds?: (Scalars['Float'] | null),toolInputSchema?: (Scalars['JSON'] | null),isTool?: (Scalars['Boolean'] | null),source?: (Scalars['JSON'] | null),cronTriggerSettings?: (Scalars['JSON'] | null),databaseEventTriggerSettings?: (Scalars['JSON'] | null),httpRouteTriggerSettings?: (Scalars['JSON'] | null)}
+export interface CreateLogicFunctionFromSourceInput {id?: (Scalars['UUID'] | null),universalIdentifier?: (Scalars['UUID'] | null),name: Scalars['String'],description?: (Scalars['String'] | null),timeoutSeconds?: (Scalars['Float'] | null),source?: (Scalars['JSON'] | null),cronTriggerSettings?: (Scalars['JSON'] | null),databaseEventTriggerSettings?: (Scalars['JSON'] | null),httpRouteTriggerSettings?: (Scalars['JSON'] | null),toolTriggerSettings?: (Scalars['JSON'] | null),workflowActionTriggerSettings?: (Scalars['JSON'] | null)}

 export interface ExecuteOneLogicFunctionInput {
 /** Id of the logic function to execute */
@@ -6092,7 +6125,7 @@ id: Scalars['UUID'],
 /** The logic function updates */
 update: UpdateLogicFunctionFromSourceInputUpdates}

-export interface UpdateLogicFunctionFromSourceInputUpdates {name?: (Scalars['String'] | null),description?: (Scalars['String'] | null),timeoutSeconds?: (Scalars['Float'] | null),sourceHandlerCode?: (Scalars['String'] | null),toolInputSchema?: (Scalars['JSON'] | null),handlerName?: (Scalars['String'] | null),sourceHandlerPath?: (Scalars['String'] | null),isTool?: (Scalars['Boolean'] | null),cronTriggerSettings?: (Scalars['JSON'] | null),databaseEventTriggerSettings?: (Scalars['JSON'] | null),httpRouteTriggerSettings?: (Scalars['JSON'] | null)}
+export interface UpdateLogicFunctionFromSourceInputUpdates {name?: (Scalars['String'] | null),description?: (Scalars['String'] | null),timeoutSeconds?: (Scalars['Float'] | null),sourceHandlerCode?: (Scalars['String'] | null),handlerName?: (Scalars['String'] | null),sourceHandlerPath?: (Scalars['String'] | null),cronTriggerSettings?: (Scalars['JSON'] | null),databaseEventTriggerSettings?: (Scalars['JSON'] | null),httpRouteTriggerSettings?: (Scalars['JSON'] | null),toolTriggerSettings?: (Scalars['JSON'] | null),workflowActionTriggerSettings?: (Scalars['JSON'] | null)}

 export interface CreateCommandMenuItemInput {workflowVersionId?: (Scalars['UUID'] | null),frontComponentId?: (Scalars['UUID'] | null),engineComponentKey: EngineComponentKey,label: Scalars['String'],icon?: (Scalars['String'] | null),shortLabel?: (Scalars['String'] | null),position?: (Scalars['Float'] | null),isPinned?: (Scalars['Boolean'] | null),availabilityType?: (CommandMenuItemAvailabilityType | null),hotKeys?: (Scalars['String'][] | null),conditionalAvailabilityExpression?: (Scalars['String'] | null),availabilityObjectMetadataId?: (Scalars['UUID'] | null),payload?: (Scalars['JSON'] | null),pageLayoutId?: (Scalars['UUID'] | null)}

@@ -6198,6 +6231,8 @@ export interface UpdateMessageChannelInput {id: Scalars['UUID'],update: UpdateMe

 export interface UpdateMessageChannelInputUpdates {visibility?: (MessageChannelVisibility | null),isContactAutoCreationEnabled?: (Scalars['Boolean'] | null),contactAutoCreationPolicy?: (MessageChannelContactAutoCreationPolicy | null),messageFolderImportPolicy?: (MessageFolderImportPolicy | null),isSyncEnabled?: (Scalars['Boolean'] | null),excludeNonProfessionalEmails?: (Scalars['Boolean'] | null),excludeGroupEmails?: (Scalars['Boolean'] | null)}

+export interface CreateEmailGroupChannelInput {handle: Scalars['String']}
+
 export interface UpdateCalendarChannelInput {id: Scalars['UUID'],update: UpdateCalendarChannelInputUpdates}

 export interface UpdateCalendarChannelInputUpdates {visibility?: (CalendarChannelVisibility | null),isContactAutoCreationEnabled?: (Scalars['Boolean'] | null),contactAutoCreationPolicy?: (CalendarChannelContactAutoCreationPolicy | null),isSyncEnabled?: (Scalars['Boolean'] | null)}
@@ -6443,6 +6478,38 @@ export interface LogicFunctionLogsInput {applicationId?: (Scalars['UUID'] | null
    


+    const CommandMenuItem_possibleTypes: string[] = ['CommandMenuItem']
+    export const isCommandMenuItem = (obj?: { __typename?: any } | null): obj is CommandMenuItem => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isCommandMenuItem"')
+      return CommandMenuItem_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
+    const CommandMenuItemPayload_possibleTypes: string[] = ['PathCommandMenuItemPayload','ObjectMetadataCommandMenuItemPayload']
+    export const isCommandMenuItemPayload = (obj?: { __typename?: any } | null): obj is CommandMenuItemPayload => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isCommandMenuItemPayload"')
+      return CommandMenuItemPayload_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
+    const PathCommandMenuItemPayload_possibleTypes: string[] = ['PathCommandMenuItemPayload']
+    export const isPathCommandMenuItemPayload = (obj?: { __typename?: any } | null): obj is PathCommandMenuItemPayload => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isPathCommandMenuItemPayload"')
+      return PathCommandMenuItemPayload_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
+    const ObjectMetadataCommandMenuItemPayload_possibleTypes: string[] = ['ObjectMetadataCommandMenuItemPayload']
+    export const isObjectMetadataCommandMenuItemPayload = (obj?: { __typename?: any } | null): obj is ObjectMetadataCommandMenuItemPayload => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isObjectMetadataCommandMenuItemPayload"')
+      return ObjectMetadataCommandMenuItemPayload_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
    const LogicFunction_possibleTypes: string[] = ['LogicFunction']
    export const isLogicFunction = (obj?: { __typename?: any } | null): obj is LogicFunction => {
      if (!obj?.__typename) throw new Error('__typename is missing in "isLogicFunction"')
@@ -7875,38 +7942,6 @@ export interface LogicFunctionLogsInput {applicationId?: (Scalars['UUID'] | null
    


-    const CommandMenuItem_possibleTypes: string[] = ['CommandMenuItem']
-    export const isCommandMenuItem = (obj?: { __typename?: any } | null): obj is CommandMenuItem => {
-      if (!obj?.__typename) throw new Error('__typename is missing in "isCommandMenuItem"')
-      return CommandMenuItem_possibleTypes.includes(obj.__typename)
-    }
-    
-
-
-    const CommandMenuItemPayload_possibleTypes: string[] = ['PathCommandMenuItemPayload','ObjectMetadataCommandMenuItemPayload']
-    export const isCommandMenuItemPayload = (obj?: { __typename?: any } | null): obj is CommandMenuItemPayload => {
-      if (!obj?.__typename) throw new Error('__typename is missing in "isCommandMenuItemPayload"')
-      return CommandMenuItemPayload_possibleTypes.includes(obj.__typename)
-    }
-    
-
-
-    const PathCommandMenuItemPayload_possibleTypes: string[] = ['PathCommandMenuItemPayload']
-    export const isPathCommandMenuItemPayload = (obj?: { __typename?: any } | null): obj is PathCommandMenuItemPayload => {
-      if (!obj?.__typename) throw new Error('__typename is missing in "isPathCommandMenuItemPayload"')
-      return PathCommandMenuItemPayload_possibleTypes.includes(obj.__typename)
-    }
-    
-
-
-    const ObjectMetadataCommandMenuItemPayload_possibleTypes: string[] = ['ObjectMetadataCommandMenuItemPayload']
-    export const isObjectMetadataCommandMenuItemPayload = (obj?: { __typename?: any } | null): obj is ObjectMetadataCommandMenuItemPayload => {
-      if (!obj?.__typename) throw new Error('__typename is missing in "isObjectMetadataCommandMenuItemPayload"')
-      return ObjectMetadataCommandMenuItemPayload_possibleTypes.includes(obj.__typename)
-    }
-    
-
-
    const ToolIndexEntry_possibleTypes: string[] = ['ToolIndexEntry']
    export const isToolIndexEntry = (obj?: { __typename?: any } | null): obj is ToolIndexEntry => {
      if (!obj?.__typename) throw new Error('__typename is missing in "isToolIndexEntry"')
@@ -8155,6 +8190,14 @@ export interface LogicFunctionLogsInput {applicationId?: (Scalars['UUID'] | null
    


+    const CreateEmailGroupChannelOutput_possibleTypes: string[] = ['CreateEmailGroupChannelOutput']
+    export const isCreateEmailGroupChannelOutput = (obj?: { __typename?: any } | null): obj is CreateEmailGroupChannelOutput => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isCreateEmailGroupChannelOutput"')
+      return CreateEmailGroupChannelOutput_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
    const MessageFolder_possibleTypes: string[] = ['MessageFolder']
    export const isMessageFolder = (obj?: { __typename?: any } | null): obj is MessageFolder => {
      if (!obj?.__typename) throw new Error('__typename is missing in "isMessageFolder"')
@@ -8306,6 +8349,82 @@ export const enumWorkspaceMemberNumberFormatEnum = {
   APOSTROPHE_AND_DOT: 'APOSTROPHE_AND_DOT' as const
 }

+export const enumEngineComponentKey = {
+   NAVIGATE_TO_NEXT_RECORD: 'NAVIGATE_TO_NEXT_RECORD' as const,
+   NAVIGATE_TO_PREVIOUS_RECORD: 'NAVIGATE_TO_PREVIOUS_RECORD' as const,
+   CREATE_NEW_RECORD: 'CREATE_NEW_RECORD' as const,
+   DELETE_RECORDS: 'DELETE_RECORDS' as const,
+   RESTORE_RECORDS: 'RESTORE_RECORDS' as const,
+   DESTROY_RECORDS: 'DESTROY_RECORDS' as const,
+   ADD_TO_FAVORITES: 'ADD_TO_FAVORITES' as const,
+   REMOVE_FROM_FAVORITES: 'REMOVE_FROM_FAVORITES' as const,
+   EXPORT_NOTE_TO_PDF: 'EXPORT_NOTE_TO_PDF' as const,
+   EXPORT_RECORDS: 'EXPORT_RECORDS' as const,
+   UPDATE_MULTIPLE_RECORDS: 'UPDATE_MULTIPLE_RECORDS' as const,
+   MERGE_MULTIPLE_RECORDS: 'MERGE_MULTIPLE_RECORDS' as const,
+   IMPORT_RECORDS: 'IMPORT_RECORDS' as const,
+   EXPORT_VIEW: 'EXPORT_VIEW' as const,
+   SEE_DELETED_RECORDS: 'SEE_DELETED_RECORDS' as const,
+   CREATE_NEW_VIEW: 'CREATE_NEW_VIEW' as const,
+   HIDE_DELETED_RECORDS: 'HIDE_DELETED_RECORDS' as const,
+   EDIT_RECORD_PAGE_LAYOUT: 'EDIT_RECORD_PAGE_LAYOUT' as const,
+   EDIT_DASHBOARD_LAYOUT: 'EDIT_DASHBOARD_LAYOUT' as const,
+   SAVE_DASHBOARD_LAYOUT: 'SAVE_DASHBOARD_LAYOUT' as const,
+   CANCEL_DASHBOARD_LAYOUT: 'CANCEL_DASHBOARD_LAYOUT' as const,
+   DUPLICATE_DASHBOARD: 'DUPLICATE_DASHBOARD' as const,
+   ACTIVATE_WORKFLOW: 'ACTIVATE_WORKFLOW' as const,
+   DEACTIVATE_WORKFLOW: 'DEACTIVATE_WORKFLOW' as const,
+   DISCARD_DRAFT_WORKFLOW: 'DISCARD_DRAFT_WORKFLOW' as const,
+   TEST_WORKFLOW: 'TEST_WORKFLOW' as const,
+   SEE_ACTIVE_VERSION_WORKFLOW: 'SEE_ACTIVE_VERSION_WORKFLOW' as const,
+   SEE_RUNS_WORKFLOW: 'SEE_RUNS_WORKFLOW' as const,
+   SEE_VERSIONS_WORKFLOW: 'SEE_VERSIONS_WORKFLOW' as const,
+   ADD_NODE_WORKFLOW: 'ADD_NODE_WORKFLOW' as const,
+   TIDY_UP_WORKFLOW: 'TIDY_UP_WORKFLOW' as const,
+   DUPLICATE_WORKFLOW: 'DUPLICATE_WORKFLOW' as const,
+   SEE_VERSION_WORKFLOW_RUN: 'SEE_VERSION_WORKFLOW_RUN' as const,
+   SEE_WORKFLOW_WORKFLOW_RUN: 'SEE_WORKFLOW_WORKFLOW_RUN' as const,
+   STOP_WORKFLOW_RUN: 'STOP_WORKFLOW_RUN' as const,
+   SEE_RUNS_WORKFLOW_VERSION: 'SEE_RUNS_WORKFLOW_VERSION' as const,
+   SEE_WORKFLOW_WORKFLOW_VERSION: 'SEE_WORKFLOW_WORKFLOW_VERSION' as const,
+   USE_AS_DRAFT_WORKFLOW_VERSION: 'USE_AS_DRAFT_WORKFLOW_VERSION' as const,
+   SEE_VERSIONS_WORKFLOW_VERSION: 'SEE_VERSIONS_WORKFLOW_VERSION' as const,
+   SEARCH_RECORDS: 'SEARCH_RECORDS' as const,
+   SEARCH_RECORDS_FALLBACK: 'SEARCH_RECORDS_FALLBACK' as const,
+   ASK_AI: 'ASK_AI' as const,
+   VIEW_PREVIOUS_AI_CHATS: 'VIEW_PREVIOUS_AI_CHATS' as const,
+   NAVIGATION: 'NAVIGATION' as const,
+   TRIGGER_WORKFLOW_VERSION: 'TRIGGER_WORKFLOW_VERSION' as const,
+   FRONT_COMPONENT_RENDERER: 'FRONT_COMPONENT_RENDERER' as const,
+   REPLY_TO_EMAIL_THREAD: 'REPLY_TO_EMAIL_THREAD' as const,
+   COMPOSE_EMAIL: 'COMPOSE_EMAIL' as const,
+   GO_TO_PEOPLE: 'GO_TO_PEOPLE' as const,
+   GO_TO_COMPANIES: 'GO_TO_COMPANIES' as const,
+   GO_TO_DASHBOARDS: 'GO_TO_DASHBOARDS' as const,
+   GO_TO_OPPORTUNITIES: 'GO_TO_OPPORTUNITIES' as const,
+   GO_TO_SETTINGS: 'GO_TO_SETTINGS' as const,
+   GO_TO_TASKS: 'GO_TO_TASKS' as const,
+   GO_TO_NOTES: 'GO_TO_NOTES' as const,
+   GO_TO_WORKFLOWS: 'GO_TO_WORKFLOWS' as const,
+   GO_TO_RUNS: 'GO_TO_RUNS' as const,
+   DELETE_SINGLE_RECORD: 'DELETE_SINGLE_RECORD' as const,
+   DELETE_MULTIPLE_RECORDS: 'DELETE_MULTIPLE_RECORDS' as const,
+   RESTORE_SINGLE_RECORD: 'RESTORE_SINGLE_RECORD' as const,
+   RESTORE_MULTIPLE_RECORDS: 'RESTORE_MULTIPLE_RECORDS' as const,
+   DESTROY_SINGLE_RECORD: 'DESTROY_SINGLE_RECORD' as const,
+   DESTROY_MULTIPLE_RECORDS: 'DESTROY_MULTIPLE_RECORDS' as const,
+   EXPORT_FROM_RECORD_INDEX: 'EXPORT_FROM_RECORD_INDEX' as const,
+   EXPORT_FROM_RECORD_SHOW: 'EXPORT_FROM_RECORD_SHOW' as const,
+   EXPORT_MULTIPLE_RECORDS: 'EXPORT_MULTIPLE_RECORDS' as const
+}
+
+export const enumCommandMenuItemAvailabilityType = {
+   GLOBAL: 'GLOBAL' as const,
+   GLOBAL_OBJECT_CONTEXT: 'GLOBAL_OBJECT_CONTEXT' as const,
+   RECORD_SELECTION: 'RECORD_SELECTION' as const,
+   FALLBACK: 'FALLBACK' as const
+}
+
 export const enumFieldMetadataType = {
   ACTOR: 'ACTOR' as const,
   ADDRESS: 'ADDRESS' as const,
@@ -8549,6 +8668,7 @@ export const enumBillingUsageType = {

 export const enumBillingProductKey = {
   BASE_PRODUCT: 'BASE_PRODUCT' as const,
+   RESOURCE_CREDIT: 'RESOURCE_CREDIT' as const,
   WORKFLOW_NODE_EXECUTION: 'WORKFLOW_NODE_EXECUTION' as const
 }

@@ -8606,11 +8726,13 @@ export const enumFeatureFlagKey = {
   IS_RECORD_PAGE_LAYOUT_EDITING_ENABLED: 'IS_RECORD_PAGE_LAYOUT_EDITING_ENABLED' as const,
   IS_PUBLIC_DOMAIN_ENABLED: 'IS_PUBLIC_DOMAIN_ENABLED' as const,
   IS_EMAILING_DOMAIN_ENABLED: 'IS_EMAILING_DOMAIN_ENABLED' as const,
+   IS_EMAIL_GROUP_ENABLED: 'IS_EMAIL_GROUP_ENABLED' as const,
   IS_JUNCTION_RELATIONS_ENABLED: 'IS_JUNCTION_RELATIONS_ENABLED' as const,
   IS_CONNECTED_ACCOUNT_MIGRATED: 'IS_CONNECTED_ACCOUNT_MIGRATED' as const,
   IS_RICH_TEXT_V1_MIGRATED: 'IS_RICH_TEXT_V1_MIGRATED' as const,
   IS_RECORD_PAGE_LAYOUT_GLOBAL_EDITION_ENABLED: 'IS_RECORD_PAGE_LAYOUT_GLOBAL_EDITION_ENABLED' as const,
-   IS_DATASOURCE_MIGRATED: 'IS_DATASOURCE_MIGRATED' as const
+   IS_DATASOURCE_MIGRATED: 'IS_DATASOURCE_MIGRATED' as const,
+   IS_BILLING_V2_ENABLED: 'IS_BILLING_V2_ENABLED' as const
 }

 export const enumIdentityProviderType = {
@@ -8665,82 +8787,6 @@ export const enumEmailingDomainStatus = {
   TEMPORARY_FAILURE: 'TEMPORARY_FAILURE' as const
 }

-export const enumEngineComponentKey = {
-   NAVIGATE_TO_NEXT_RECORD: 'NAVIGATE_TO_NEXT_RECORD' as const,
-   NAVIGATE_TO_PREVIOUS_RECORD: 'NAVIGATE_TO_PREVIOUS_RECORD' as const,
-   CREATE_NEW_RECORD: 'CREATE_NEW_RECORD' as const,
-   DELETE_RECORDS: 'DELETE_RECORDS' as const,
-   RESTORE_RECORDS: 'RESTORE_RECORDS' as const,
-   DESTROY_RECORDS: 'DESTROY_RECORDS' as const,
-   ADD_TO_FAVORITES: 'ADD_TO_FAVORITES' as const,
-   REMOVE_FROM_FAVORITES: 'REMOVE_FROM_FAVORITES' as const,
-   EXPORT_NOTE_TO_PDF: 'EXPORT_NOTE_TO_PDF' as const,
-   EXPORT_RECORDS: 'EXPORT_RECORDS' as const,
-   UPDATE_MULTIPLE_RECORDS: 'UPDATE_MULTIPLE_RECORDS' as const,
-   MERGE_MULTIPLE_RECORDS: 'MERGE_MULTIPLE_RECORDS' as const,
-   IMPORT_RECORDS: 'IMPORT_RECORDS' as const,
-   EXPORT_VIEW: 'EXPORT_VIEW' as const,
-   SEE_DELETED_RECORDS: 'SEE_DELETED_RECORDS' as const,
-   CREATE_NEW_VIEW: 'CREATE_NEW_VIEW' as const,
-   HIDE_DELETED_RECORDS: 'HIDE_DELETED_RECORDS' as const,
-   EDIT_RECORD_PAGE_LAYOUT: 'EDIT_RECORD_PAGE_LAYOUT' as const,
-   EDIT_DASHBOARD_LAYOUT: 'EDIT_DASHBOARD_LAYOUT' as const,
-   SAVE_DASHBOARD_LAYOUT: 'SAVE_DASHBOARD_LAYOUT' as const,
-   CANCEL_DASHBOARD_LAYOUT: 'CANCEL_DASHBOARD_LAYOUT' as const,
-   DUPLICATE_DASHBOARD: 'DUPLICATE_DASHBOARD' as const,
-   ACTIVATE_WORKFLOW: 'ACTIVATE_WORKFLOW' as const,
-   DEACTIVATE_WORKFLOW: 'DEACTIVATE_WORKFLOW' as const,
-   DISCARD_DRAFT_WORKFLOW: 'DISCARD_DRAFT_WORKFLOW' as const,
-   TEST_WORKFLOW: 'TEST_WORKFLOW' as const,
-   SEE_ACTIVE_VERSION_WORKFLOW: 'SEE_ACTIVE_VERSION_WORKFLOW' as const,
-   SEE_RUNS_WORKFLOW: 'SEE_RUNS_WORKFLOW' as const,
-   SEE_VERSIONS_WORKFLOW: 'SEE_VERSIONS_WORKFLOW' as const,
-   ADD_NODE_WORKFLOW: 'ADD_NODE_WORKFLOW' as const,
-   TIDY_UP_WORKFLOW: 'TIDY_UP_WORKFLOW' as const,
-   DUPLICATE_WORKFLOW: 'DUPLICATE_WORKFLOW' as const,
-   SEE_VERSION_WORKFLOW_RUN: 'SEE_VERSION_WORKFLOW_RUN' as const,
-   SEE_WORKFLOW_WORKFLOW_RUN: 'SEE_WORKFLOW_WORKFLOW_RUN' as const,
-   STOP_WORKFLOW_RUN: 'STOP_WORKFLOW_RUN' as const,
-   SEE_RUNS_WORKFLOW_VERSION: 'SEE_RUNS_WORKFLOW_VERSION' as const,
-   SEE_WORKFLOW_WORKFLOW_VERSION: 'SEE_WORKFLOW_WORKFLOW_VERSION' as const,
-   USE_AS_DRAFT_WORKFLOW_VERSION: 'USE_AS_DRAFT_WORKFLOW_VERSION' as const,
-   SEE_VERSIONS_WORKFLOW_VERSION: 'SEE_VERSIONS_WORKFLOW_VERSION' as const,
-   SEARCH_RECORDS: 'SEARCH_RECORDS' as const,
-   SEARCH_RECORDS_FALLBACK: 'SEARCH_RECORDS_FALLBACK' as const,
-   ASK_AI: 'ASK_AI' as const,
-   VIEW_PREVIOUS_AI_CHATS: 'VIEW_PREVIOUS_AI_CHATS' as const,
-   NAVIGATION: 'NAVIGATION' as const,
-   TRIGGER_WORKFLOW_VERSION: 'TRIGGER_WORKFLOW_VERSION' as const,
-   FRONT_COMPONENT_RENDERER: 'FRONT_COMPONENT_RENDERER' as const,
-   REPLY_TO_EMAIL_THREAD: 'REPLY_TO_EMAIL_THREAD' as const,
-   COMPOSE_EMAIL: 'COMPOSE_EMAIL' as const,
-   GO_TO_PEOPLE: 'GO_TO_PEOPLE' as const,
-   GO_TO_COMPANIES: 'GO_TO_COMPANIES' as const,
-   GO_TO_DASHBOARDS: 'GO_TO_DASHBOARDS' as const,
-   GO_TO_OPPORTUNITIES: 'GO_TO_OPPORTUNITIES' as const,
-   GO_TO_SETTINGS: 'GO_TO_SETTINGS' as const,
-   GO_TO_TASKS: 'GO_TO_TASKS' as const,
-   GO_TO_NOTES: 'GO_TO_NOTES' as const,
-   GO_TO_WORKFLOWS: 'GO_TO_WORKFLOWS' as const,
-   GO_TO_RUNS: 'GO_TO_RUNS' as const,
-   DELETE_SINGLE_RECORD: 'DELETE_SINGLE_RECORD' as const,
-   DELETE_MULTIPLE_RECORDS: 'DELETE_MULTIPLE_RECORDS' as const,
-   RESTORE_SINGLE_RECORD: 'RESTORE_SINGLE_RECORD' as const,
-   RESTORE_MULTIPLE_RECORDS: 'RESTORE_MULTIPLE_RECORDS' as const,
-   DESTROY_SINGLE_RECORD: 'DESTROY_SINGLE_RECORD' as const,
-   DESTROY_MULTIPLE_RECORDS: 'DESTROY_MULTIPLE_RECORDS' as const,
-   EXPORT_FROM_RECORD_INDEX: 'EXPORT_FROM_RECORD_INDEX' as const,
-   EXPORT_FROM_RECORD_SHOW: 'EXPORT_FROM_RECORD_SHOW' as const,
-   EXPORT_MULTIPLE_RECORDS: 'EXPORT_MULTIPLE_RECORDS' as const
-}
-
-export const enumCommandMenuItemAvailabilityType = {
-   GLOBAL: 'GLOBAL' as const,
-   GLOBAL_OBJECT_CONTEXT: 'GLOBAL_OBJECT_CONTEXT' as const,
-   RECORD_SELECTION: 'RECORD_SELECTION' as const,
-   FALLBACK: 'FALLBACK' as const
-}
-
 export const enumCalendarChannelSyncStatus = {
   NOT_SYNCED: 'NOT_SYNCED' as const,
   ONGOING: 'ONGOING' as const,
@@ -8780,7 +8826,8 @@ export const enumMessageChannelVisibility = {

 export const enumMessageChannelType = {
   EMAIL: 'EMAIL' as const,
-   SMS: 'SMS' as const
+   SMS: 'SMS' as const,
+   EMAIL_GROUP: 'EMAIL_GROUP' as const
 }

 export const enumMessageChannelContactAutoCreationPolicy = {
@@ -8851,7 +8898,9 @@ export const enumAllMetadataName = {
   objectPermission: 'objectPermission' as const,
   fieldPermission: 'fieldPermission' as const,
   frontComponent: 'frontComponent' as const,
-   webhook: 'webhook' as const
+   webhook: 'webhook' as const,
+   applicationVariable: 'applicationVariable' as const,
+   connectionProvider: 'connectionProvider' as const
 }

 export const enumEventLogTable = {
@@ -26,11 +26,11 @@ prod-run:
 prod-postgres-run:
 	@docker run -d -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres --name twenty-postgres twenty-postgres:$(TAG)

-prod-website-build:
-	@cd ../.. && docker build -f ./packages/twenty-docker/twenty-website/Dockerfile --platform $(PLATFORM) --tag twenty-website:$(TAG) . && cd -
+prod-website-new-build:
+	@cd ../.. && docker build -f ./packages/twenty-docker/twenty-website-new/Dockerfile --platform $(PLATFORM) --tag twenty-website-new:$(TAG) . && cd -

-prod-website-run:
-	@docker run -d -p 3000:3000 --name twenty-website twenty-website:$(TAG)
+prod-website-new-run:
+	@docker run -d -p 3000:3000 --name twenty-website-new twenty-website-new:$(TAG)

 # =============================================================================
 # Local Development Services
@@ -34,25 +34,27 @@ has_schema=$(PGPASSWORD=twenty psql -h localhost -U twenty -d default -tAc \
  "SELECT EXISTS (SELECT 1 FROM information_schema.schemata WHERE schema_name = 'core')")

 if [ "$has_schema" = "f" ]; then
-  step_start "Running initial database setup"
-  NODE_OPTIONS="--max-old-space-size=1500" node ./dist/database/scripts/setup-db.js
+  step_start "Running initial database setup and migrations"
+  yarn database:init:prod
  step_done
 fi

-step_start "Running migrations"
-yarn database:migrate:prod --force
-step_done
-
 step_start "Flushing cache"
-yarn command:prod cache:flush
+if ! yarn command:prod cache:flush; then
+  echo "Warning: Failed to flush cache before upgrade, but continuing startup..."
+fi
 step_done

 step_start "Running upgrade"
-yarn command:prod upgrade
+if ! yarn command:prod upgrade; then
+  echo "Warning: Upgrade completed with errors. Some workspaces may not be fully migrated. Check logs for details."
+fi
 step_done

 step_start "Flushing cache"
-yarn command:prod cache:flush
+if ! yarn command:prod cache:flush; then
+  echo "Warning: Failed to flush cache after upgrade, but continuing startup..."
+fi
 step_done

 # Only seed on first boot — check if the dev workspace already exists
@@ -1,43 +0,0 @@
-FROM node:24-alpine AS twenty-website-build
-
-
-WORKDIR /app
-
-COPY ./package.json .
-COPY ./yarn.lock .
-COPY ./.yarnrc.yml .
-COPY ./.yarn/releases /app/.yarn/releases
-COPY ./.yarn/patches /app/.yarn/patches
-COPY ./packages/twenty-oxlint-rules /app/packages/twenty-oxlint-rules
-COPY ./packages/twenty-ui/package.json /app/packages/twenty-ui/
-COPY ./packages/twenty-shared/package.json /app/packages/twenty-shared/
-COPY ./packages/twenty-website/package.json /app/packages/twenty-website/package.json
-
-RUN yarn
-
-ENV KEYSTATIC_GITHUB_CLIENT_ID="<fake build value>"
-ENV KEYSTATIC_GITHUB_CLIENT_SECRET="<fake build value>"
-ENV KEYSTATIC_SECRET="<fake build value>"
-ENV NEXT_PUBLIC_KEYSTATIC_GITHUB_APP_SLUG="<fake build value>"
-
-COPY ./packages/twenty-ui /app/packages/twenty-ui
-COPY ./packages/twenty-website /app/packages/twenty-website
-RUN npx nx build twenty-website
-
-FROM node:24-alpine AS twenty-website
-
-WORKDIR /app/packages/twenty-website
-
-COPY --from=twenty-website-build /app /app
-
-WORKDIR /app/packages/twenty-website
-
-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 website."
-
-RUN chown -R 1000 /app
-
-# Use non root user with uid 1000
-USER 1000
-
-CMD ["/bin/sh", "-c", "npx nx start"]
@@ -1,8 +1,26 @@
 # ===========================================================================
-# Shared build stages (used by both targets)
+# Dependency stages
 # ===========================================================================

-FROM node:24-alpine AS common-deps
+FROM node:24-alpine AS front-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-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-front-component-renderer/package.json /app/packages/twenty-front-component-renderer/
+COPY ./packages/twenty-sdk/package.json /app/packages/twenty-sdk/
+COPY ./packages/twenty-client-sdk/package.json /app/packages/twenty-client-sdk/
+
+RUN yarn workspaces focus twenty twenty-front twenty-front-component-renderer twenty-ui twenty-shared twenty-sdk twenty-client-sdk && yarn cache clean && npx nx reset
+
+
+FROM node:24-alpine AS server-deps

 WORKDIR /app

@@ -13,22 +31,16 @@ 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-front-component-renderer/package.json /app/packages/twenty-front-component-renderer/
-COPY ./packages/twenty-sdk/package.json /app/packages/twenty-sdk/
 COPY ./packages/twenty-client-sdk/package.json /app/packages/twenty-client-sdk/

-RUN yarn && yarn cache clean && npx nx reset
+RUN yarn workspaces focus twenty twenty-server twenty-emails twenty-shared twenty-client-sdk && yarn cache clean && npx nx reset


-FROM common-deps AS twenty-server-build
+FROM server-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-client-sdk /app/packages/twenty-client-sdk
 COPY ./packages/twenty-server /app/packages/twenty-server

@@ -44,10 +56,10 @@ RUN npx nx run twenty-server:build
 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
+RUN yarn workspaces focus --production twenty-emails twenty-shared twenty-client-sdk twenty-server


-FROM common-deps AS twenty-front-build
+FROM front-deps AS twenty-front-build

 COPY ./packages/twenty-front /app/packages/twenty-front
 COPY ./packages/twenty-front-component-renderer /app/packages/twenty-front-component-renderer
@@ -99,11 +111,8 @@ COPY --chown=1000 --from=twenty-server-build /app/packages/twenty-shared/package
 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/

 LABEL org.opencontainers.image.source=https://github.com/twentyhq/twenty
 LABEL org.opencontainers.image.description="Twenty server image (no frontend)."
@@ -208,11 +217,8 @@ COPY --from=twenty-server-build /app/packages/twenty-shared/package.json /app/pa
 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
@@ -16,9 +16,17 @@ setup_and_migrate_db() {
        yarn database:init:prod
    fi

-    yarn command:prod cache:flush
-    yarn command:prod upgrade
-    yarn command:prod cache:flush
+    if ! yarn command:prod cache:flush; then
+        echo "Warning: Failed to flush cache before upgrade, but continuing startup..."
+    fi
+
+    if ! yarn command:prod upgrade; then
+        echo "Warning: Upgrade completed with errors. Some workspaces may not be fully migrated. Check logs for details."
+    fi
+
+    if ! yarn command:prod cache:flush; then
+        echo "Warning: Failed to flush cache after upgrade, but continuing startup..."
+    fi

    echo "Successfully migrated DB!"
 }
@@ -77,14 +77,10 @@ To deploy to Mintlify:
 3. Set subdirectory to `packages/twenty-docs`
 4. Mintlify will auto-deploy and generate search embeddings

-## Next Steps
+## Status

-1. **Manual Review** - Check for any component conversion issues
-2. **Fix Image Paths** - Verify all images render correctly
-3. **Test Navigation** - Ensure all internal links work
-4. **Deploy** - Push to production Mintlify
-5. **Update Helper Agent** - Verify searchArticles tool works with full content
-6. **Deprecate twenty-website docs** - Once migration is confirmed working
+This migration has been completed. The legacy `packages/twenty-website` package
+has been removed, and documentation now lives in `packages/twenty-docs`.

 ## Known Issues to Review

@@ -92,4 +88,3 @@ To deploy to Mintlify:
 - Some images may have incorrect paths
 - Custom styled components may need adjustment
 - Video embeds might need review
-
@@ -37,7 +37,7 @@ Both are available as REST and GraphQL. GraphQL adds batch upserts and the abili
 Authorization: Bearer YOUR_API_KEY
 ```

-Create an API key in **Settings → API & Webhooks → + Create key**. Copy it immediately — it's shown once. Keys can be scoped to a specific role under **Settings → Roles → Assignment tab** to limit what they can access.
+Create an API key in **Settings → API & Webhooks → + Create key**. Copy it immediately — it's shown once. Keys can be scoped to a specific role under **Settings → Members → Roles → Assignment tab** to limit what they can access.

 <VimeoEmbed videoId="928786722" title="Creating API key" />

@@ -0,0 +1,63 @@
+---
+title: Application Config
+description: Declare your app's identity, default role, variables, and marketplace metadata with defineApplication.
+icon: "rocket"
+---
+
+Every app must have exactly one `defineApplication` call. It declares:
+
+- **Identity** — universal identifier, display name, description.
+- **Permissions** — which role its logic functions and front components run under.
+- **Variables** *(optional)* — key–value pairs exposed to your code as environment variables.
+- **Pre-install / post-install hooks** *(optional)* — see [Logic Functions](/developers/extend/apps/logic/logic-functions).
+
+```ts src/application-config.ts
+import { defineApplication } from 'twenty-sdk/define';
+
+export default defineApplication({
+  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
+  displayName: 'My Twenty App',
+  description: 'My first Twenty app',
+  applicationVariables: {
+    DEFAULT_RECIPIENT_NAME: {
+      universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
+      description: 'Default recipient name for postcards',
+      value: 'Jane Doe',
+      isSecret: false,
+    },
+  },
+});
+```
+
+Notes:
+- `universalIdentifier` fields are deterministic IDs you own. Generate them once and keep them stable across syncs.
+- `applicationVariables` become environment variables for your functions and front components (e.g., `DEFAULT_RECIPIENT_NAME` is available as `process.env.DEFAULT_RECIPIENT_NAME`).
+- The default role is detected automatically from the role file marked with [`defineApplicationRole()`](/developers/extend/apps/config/roles) — you do not need to reference it from `defineApplication()`.
+- Pre-install and post-install functions are detected automatically during the manifest build — you do not need to reference them in `defineApplication()`.
+- Passing `defaultRoleUniversalIdentifier` explicitly is still supported for backward compatibility, but is deprecated in favor of `defineApplicationRole()`.
+
+## Default function role
+
+The role declared with [`defineApplicationRole()`](/developers/extend/apps/config/roles) controls what the app's logic functions and front components can access:
+
+- The runtime token injected as `TWENTY_APP_ACCESS_TOKEN` is derived from this role.
+- The typed API client is restricted to the permissions granted to that role.
+- Follow least-privilege: declare only the permissions your functions need.
+
+When you scaffold a new app, the CLI creates a starter role file at `src/roles/default-role.ts`. See [Roles & Permissions](/developers/extend/apps/config/roles) for the full reference.
+
+## Marketplace metadata
+
+If you plan to [publish your app](/developers/extend/apps/operations/publishing), these optional fields control how it appears in the marketplace:
+
+| Field | Description |
+|-------|-------------|
+| `author` | Author or company name |
+| `category` | App category for marketplace filtering |
+| `logoUrl` | Path to your app logo (e.g., `public/logo.png`) |
+| `screenshots` | Array of screenshot paths (e.g., `public/screenshot-1.png`) |
+| `aboutDescription` | Longer markdown description for the "About" tab. If omitted, the marketplace uses the package's `README.md` from npm |
+| `websiteUrl` | Link to your website |
+| `termsUrl` | Link to terms of service |
+| `emailSupport` | Support email address |
+| `issueReportUrl` | Link to issue tracker |
@@ -0,0 +1,206 @@
+---
+title: Install Hooks
+description: Run logic before or after the install — seed data, back up records, validate the upgrade.
+icon: "wrench"
+---
+
+Install hooks are special logic functions that run during the install or upgrade lifecycle. They share the same handler runtime as regular [logic functions](/developers/extend/apps/logic/logic-functions) and receive an `InstallPayload`, but they're declared with their own define functions — `definePostInstallLogicFunction()` and `definePreInstallLogicFunction()` — and live outside the normal trigger model (HTTP, cron, database events).
+
+Each app may define **at most one pre-install** and **at most one post-install** function. The manifest build will error if more than one of either is detected.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ install flow                                                │
+│                                                             │
+│   upload package → [pre-install] → metadata migration →     │
+│   generate SDK → [post-install]                             │
+│                                                             │
+│                  old schema visible    new schema visible   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+<AccordionGroup>
+<Accordion title="definePostInstallLogicFunction" description="Runs after the workspace metadata migration is applied">
+
+A post-install function runs automatically once your app has finished installing on a workspace. The server executes it **after** the app's metadata has been synchronized and the SDK client has been generated, so the workspace is fully ready to use and the new schema is in place. Typical use cases include seeding default data, creating initial records, configuring workspace settings, or provisioning resources on third-party services.
+
+```ts src/logic-functions/post-install.ts
+import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
+
+const handler = async (payload: InstallPayload): Promise<void> => {
+  console.log('Post install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePostInstallLogicFunction({
+  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
+  name: 'post-install',
+  description: 'Runs after installation to set up the application.',
+  timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: false,
+  shouldRunSynchronously: false,
+  handler,
+});
+```
+
+You can also manually execute the post-install function at any time using the CLI:
+
+```bash filename="Terminal"
+yarn twenty exec --postInstall
+```
+
+Key points:
+- Post-install functions use `definePostInstallLogicFunction()` — a specialized variant that omits trigger settings (`cronTriggerSettings`, `databaseEventTriggerSettings`, `httpRouteTriggerSettings`, `toolTriggerSettings`, `workflowActionTriggerSettings`).
+- The handler receives an `InstallPayload` with `{ previousVersion?: string; newVersion: string }` — `newVersion` is the version being installed, and `previousVersion` is the version that was previously installed (or `undefined` on a fresh install). Use these values to distinguish fresh installs from upgrades and to run version-specific migration logic.
+- **When the hook runs**: on fresh installs only, by default. Pass `shouldRunOnVersionUpgrade: true` if you also want it to run when the app is upgraded from a previous version. When omitted, the flag defaults to `false` and upgrades skip the hook.
+- **Execution model — async by default, sync opt-in**: the `shouldRunSynchronously` flag controls *how* post-install is executed.
+  - `shouldRunSynchronously: false` *(default)* — the hook is **enqueued on the message queue** with `retryLimit: 3` and runs asynchronously in a worker. The install response returns as soon as the job is enqueued, so a slow or failing handler does not block the caller. The worker will retry up to three times. **Use this for long-running jobs** — seeding large datasets, calling slow third-party APIs, provisioning external resources, anything that might exceed a reasonable HTTP response window.
+  - `shouldRunSynchronously: true` — the hook is executed **inline during the install flow** (same executor as pre-install). The install request blocks until the handler finishes, and if it throws, the install caller receives a `POST_INSTALL_ERROR`. No automatic retries. **Use this for fast, must-complete-before-response work** — for example, emitting a validation error to the user, or quick setup that the client will rely on immediately after the install call returns. Keep in mind the metadata migration has already been applied by the time post-install runs, so a sync-mode failure does **not** roll back the schema changes — it only surfaces the error.
+- Make sure your handler is idempotent. In async mode the queue may retry up to three times; in either mode the hook may run again on upgrades when `shouldRunOnVersionUpgrade: true`.
+- The environment variables `APPLICATION_ID`, `APP_ACCESS_TOKEN`, and `API_URL` are available inside the handler (same as any other logic function), so you can call the Twenty API with an application access token scoped to your app.
+- Only one post-install function is allowed per application. The manifest build will error if more than one is detected.
+- The function's `universalIdentifier`, `shouldRunOnVersionUpgrade`, and `shouldRunSynchronously` are automatically attached to the application manifest under the `postInstallLogicFunction` field during the build — you do not need to reference them in [`defineApplication()`](/developers/extend/apps/config/application).
+- The default timeout is set to 300 seconds (5 minutes) to allow for longer setup tasks like data seeding.
+- **Not executed in dev mode**: when an app is registered locally (via `yarn twenty dev`), the server skips the install flow entirely and syncs files directly through the CLI watcher — so post-install never runs in dev mode, regardless of `shouldRunSynchronously`. Use `yarn twenty exec --postInstall` to trigger it manually against a running workspace.
+
+</Accordion>
+<Accordion title="definePreInstallLogicFunction" description="Runs before the workspace metadata migration is applied">
+
+A pre-install function runs automatically during installation, **before the workspace metadata migration is applied**. It shares the same payload shape as post-install (`InstallPayload`), but it is positioned earlier in the install flow so it can prepare state that the upcoming migration depends on — typical uses include backing up data, validating compatibility with the new schema, or archiving records that are about to be restructured or dropped.
+
+```ts src/logic-functions/pre-install.ts
+import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
+
+const handler = async (payload: InstallPayload): Promise<void> => {
+  console.log('Pre install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePreInstallLogicFunction({
+  universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
+  name: 'pre-install',
+  description: 'Runs before installation to prepare the application.',
+  timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: true,
+  handler,
+});
+```
+
+You can also manually execute the pre-install function at any time using the CLI:
+
+```bash filename="Terminal"
+yarn twenty exec --preInstall
+```
+
+Key points:
+- Pre-install functions use `definePreInstallLogicFunction()` — same specialized config as post-install, just attached to a different lifecycle slot.
+- Both pre- and post-install handlers receive the same `InstallPayload` type: `{ previousVersion?: string; newVersion: string }`. Import it once and reuse it for both hooks.
+- **When the hook runs**: positioned just before the workspace metadata migration (`synchronizeFromManifest`). Before executing, the server runs a purely additive "pared-down sync" that registers the **new** version's pre-install function in the workspace metadata — nothing else is touched — and then executes it. Because this sync is additive-only, the previous version's objects, fields, and data are still intact when your handler runs: you can safely read and back up pre-migration state.
+- **Execution model**: pre-install is executed **synchronously** and **blocks the install**. If the handler throws, the install is aborted before any schema changes are applied — the workspace stays on the previous version in a consistent state. This is intentional: pre-install is your last chance to refuse a risky upgrade.
+- As with post-install, only one pre-install function is allowed per application. It is attached to the application manifest under `preInstallLogicFunction` automatically during the build.
+- **Not executed in dev mode**: same as post-install — the install flow is skipped entirely for locally-registered apps, so pre-install never runs under `yarn twenty dev`. Use `yarn twenty exec --preInstall` to trigger it manually.
+
+</Accordion>
+<Accordion title="Pre-install vs post-install: when to use which" description="Choosing the right install hook">
+
+Both hooks are part of the same install flow and receive the same `InstallPayload`. The difference is **when** they run relative to the workspace metadata migration, and that changes what data they can safely touch.
+
+Pre-install is always **synchronous** (it blocks the install and can abort it). Post-install is **asynchronous by default** — enqueued on a worker with automatic retries — but can opt into synchronous execution with `shouldRunSynchronously: true`. See the `definePostInstallLogicFunction` accordion above for when to use each mode.
+
+**Use `post-install` for anything that needs the new schema to exist.** This is the common case:
+
+- Seeding default data (creating initial records, default views, demo content) against newly-added objects and fields.
+- Registering webhooks with third-party services now that the app has its credentials.
+- Calling your own API to finish setup that depends on the synchronized metadata.
+- Idempotent "ensure this exists" logic that should reconcile state on every upgrade — combine with `shouldRunOnVersionUpgrade: true`.
+
+Example — seed a default `PostCard` record after install:
+
+```ts src/logic-functions/post-install.ts
+import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
+import { createClient } from './generated/client';
+
+const handler = async ({ previousVersion }: InstallPayload): Promise<void> => {
+  if (previousVersion) return; // fresh installs only
+
+  const client = createClient();
+  await client.postCard.create({
+    data: { title: 'Welcome to Postcard', content: 'Your first card!' },
+  });
+};
+
+export default definePostInstallLogicFunction({
+  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
+  name: 'post-install',
+  description: 'Seeds a welcome post card after install.',
+  timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: false,
+  handler,
+});
+```
+
+**Use `pre-install` when a migration would otherwise destroy or corrupt existing data.** Because pre-install runs against the *previous* schema and its failure rolls back the upgrade, it is the right place for anything risky:
+
+- **Backing up data that is about to be dropped or restructured** — e.g. you are removing a field in v2 and need to copy its values into another field or export them to storage before the migration runs.
+- **Archiving records that a new constraint would invalidate** — e.g. a field is becoming `NOT NULL` and you need to delete or fix rows with null values first.
+- **Validating compatibility and refusing the upgrade if the current data cannot be migrated cleanly** — throw from the handler and the install aborts with no changes applied. This is safer than discovering the incompatibility mid-migration.
+- **Renaming or rekeying data** ahead of a schema change that would lose the association.
+
+Example — archive records before a destructive migration:
+
+```ts src/logic-functions/pre-install.ts
+import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
+import { createClient } from './generated/client';
+
+const handler = async ({ previousVersion, newVersion }: InstallPayload): Promise<void> => {
+  // Only the 1.x → 2.x upgrade drops the legacy `notes` field.
+  if (!previousVersion?.startsWith('1.') || !newVersion.startsWith('2.')) {
+    return;
+  }
+
+  const client = createClient();
+  const legacyRecords = await client.postCard.findMany({
+    where: { notes: { isNotNull: true } },
+  });
+
+  if (legacyRecords.length === 0) return;
+
+  // Copy legacy `notes` into the new `description` field before the migration
+  // drops the `notes` column. If this fails, the upgrade is aborted and the
+  // workspace stays on v1 with all data intact.
+  await Promise.all(
+    legacyRecords.map((record) =>
+      client.postCard.update({
+        where: { id: record.id },
+        data: { description: record.notes },
+      }),
+    ),
+  );
+};
+
+export default definePreInstallLogicFunction({
+  universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
+  name: 'pre-install',
+  description: 'Backs up legacy notes into description before the v2 migration.',
+  timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: true,
+  handler,
+});
+```
+
+**Rule of thumb:**
+
+| You want to... | Use |
+|---|---|
+| Seed default data, configure the workspace, register external resources | `post-install` |
+| Run long-running seeding or third-party calls that shouldn't block the install response | `post-install` (default — `shouldRunSynchronously: false`, with worker retries) |
+| Run fast setup that the caller will rely on immediately after the install call returns | `post-install` with `shouldRunSynchronously: true` |
+| Read or back up data that the upcoming migration would lose | `pre-install` |
+| Reject an upgrade that would corrupt existing data | `pre-install` (throw from the handler) |
+| Run reconciliation on every upgrade | `post-install` with `shouldRunOnVersionUpgrade: true` |
+| Do one-off setup on the first install only | `post-install` with `shouldRunOnVersionUpgrade: false` (default) |
+
+<Note>
+If in doubt, default to **post-install**. Only reach for pre-install when the migration itself is destructive and you need to intercept the previous state before it is gone.
+</Note>
+
+</Accordion>
+</AccordionGroup>
@@ -0,0 +1,51 @@
+---
+title: Overview
+description: Configure the app itself — its identity, default permissions, and what runs at install time.
+icon: "screwdriver-wrench"
+---
+
+A Twenty app's **config layer** is what describes the app *to the platform* — its identity, the permissions it holds, and the code that runs during install or upgrade. These declarations don't add new data shapes or runtime behavior; they tell Twenty *who the app is* and *how to set it up*.
+
+```text
+┌────────────────────────────────────────────────────────┐
+│ Application — identity, default role, variables,       │
+│               marketplace metadata                     │
+│                                                        │
+│   ┌──────────────────────────────────────────────────┐ │
+│   │ Role — what the app's logic functions can read   │ │
+│   │ and write (referenced by Application)            │ │
+│   └──────────────────────────────────────────────────┘ │
+└────────────────────────────────────────────────────────┘
+                          │
+                          ▼  (at install / upgrade time)
+       ┌──────────────────────────────────┐
+       │ Pre-install hook                 │  before metadata migration
+       └──────────────────────────────────┘
+       ┌──────────────────────────────────┐
+       │ Post-install hook                │  after metadata migration
+       └──────────────────────────────────┘
+```
+
+## In this section
+
+<CardGroup cols={2}>
+  <Card title="Application Config" icon="rocket" href="/developers/extend/apps/config/application">
+    `defineApplication` — identity, default role, variables, marketplace metadata.
+  </Card>
+  <Card title="Roles & Permissions" icon="shield-halved" href="/developers/extend/apps/config/roles">
+    `defineRole` — declare what your app's logic functions can read and write.
+  </Card>
+  <Card title="Install Hooks" icon="wrench" href="/developers/extend/apps/config/install-hooks">
+    `definePreInstallLogicFunction` and `definePostInstallLogicFunction` — back up data, seed defaults, validate upgrades.
+  </Card>
+</CardGroup>
+
+## How the pieces relate
+
+- **Application** is the entry point. Every app has exactly one `defineApplication()` call, and it points at one **Role** as its default.
+- The **Role** controls what the app's logic functions and front components can read and write. Follow least-privilege: only grant the permissions your code actually needs.
+- **Install Hooks** run during install or upgrade — pre-install before the metadata migration (so it can refuse a risky upgrade), post-install after the migration (so it can seed default data against the new schema).
+
+<Note>
+Install hooks share the [logic function](/developers/extend/apps/logic/logic-functions) runtime — same handler signature, same environment variables, same typed API client — but they're declared with their own define functions and live outside the regular trigger model (HTTP, cron, database events).
+</Note>
@@ -0,0 +1,59 @@
+---
+title: Public Assets
+description: Ship static files — images, icons, fonts — alongside your app via the public/ folder.
+icon: "folder-open"
+---
+
+The `public/` folder at the root of your app holds static files — images, icons, fonts, or any other assets your app needs at runtime. These files are automatically included in builds, synced during dev mode, and uploaded to the server.
+
+Files placed in `public/` are:
+
+- **Publicly accessible** — once synced to the server, assets are served at a public URL. No authentication is needed to access them.
+- **Available in front components** — use asset URLs to display images, icons, or any media inside your React components.
+- **Available in logic functions** — reference asset URLs in emails, API responses, or any server-side logic.
+- **Used for marketplace metadata** — the `logoUrl` and `screenshots` fields in `defineApplication()` reference files from this folder (e.g., `public/logo.png`). These are displayed in the marketplace when your app is published.
+- **Auto-synced in dev mode** — when you add, update, or delete a file in `public/`, it is synced to the server automatically. No restart needed.
+- **Included in builds** — `yarn twenty build` bundles all public assets into the distribution output.
+
+## Accessing public assets with `getPublicAssetUrl`
+
+Use the `getPublicAssetUrl` helper from `twenty-sdk` to get the full URL of a file in your `public/` directory. It works in both **logic functions** and **front components**.
+
+**In a logic function:**
+
+```ts src/logic-functions/send-invoice.ts
+import { defineLogicFunction, getPublicAssetUrl } from 'twenty-sdk/define';
+
+const handler = async (): Promise<any> => {
+  const logoUrl = getPublicAssetUrl('logo.png');
+  const invoiceUrl = getPublicAssetUrl('templates/invoice.png');
+
+  // Fetch the file content (no auth required — public endpoint)
+  const response = await fetch(invoiceUrl);
+  const buffer = await response.arrayBuffer();
+
+  return { logoUrl, size: buffer.byteLength };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'a1b2c3d4-...',
+  name: 'send-invoice',
+  description: 'Sends an invoice with the app logo',
+  timeoutSeconds: 10,
+  handler,
+});
+```
+
+**In a front component:**
+
+```tsx src/front-components/company-card.tsx
+import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk/define';
+
+export default defineFrontComponent(() => {
+  const logoUrl = getPublicAssetUrl('logo.png');
+
+  return <img src={logoUrl} alt="App logo" />;
+});
+```
+
+The `path` argument is relative to your app's `public/` folder. Both `getPublicAssetUrl('logo.png')` and `getPublicAssetUrl('public/logo.png')` resolve to the same URL — the `public/` prefix is stripped automatically if present.
@@ -0,0 +1,92 @@
+---
+title: Roles & Permissions
+description: Declare what objects and fields your app's logic functions and front components can read and write.
+icon: "shield-halved"
+---
+
+A **role** is a permission set: which objects an app can read or write, which fields it can see, and which platform-level capabilities it can use. Every app's logic functions and front components inherit the permissions of the role marked with `defineApplicationRole()` (see [The default function role](#the-default-function-role) below).
+
+```ts src/roles/restricted-company-role.ts
+import {
+  defineRole,
+  PermissionFlag,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk/define';
+
+export default defineRole({
+  universalIdentifier: '2c80f640-2083-4803-bb49-003e38279de6',
+  label: 'My new role',
+  description: 'A role that can be used in your workspace',
+  canReadAllObjectRecords: false,
+  canUpdateAllObjectRecords: false,
+  canSoftDeleteAllObjectRecords: false,
+  canDestroyAllObjectRecords: false,
+  canUpdateAllSettings: false,
+  canBeAssignedToAgents: false,
+  canBeAssignedToUsers: false,
+  canBeAssignedToApiKeys: false,
+  objectPermissions: [
+    {
+      objectUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+      canReadObjectRecords: true,
+      canUpdateObjectRecords: true,
+      canSoftDeleteObjectRecords: false,
+      canDestroyObjectRecords: false,
+    },
+  ],
+  fieldPermissions: [
+    {
+      objectUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+      fieldUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.name.universalIdentifier,
+      canReadFieldValue: false,
+      canUpdateFieldValue: false,
+    },
+  ],
+  permissionFlags: [PermissionFlag.APPLICATIONS],
+});
+```
+
+## The default function role
+
+When you scaffold a new app, the CLI creates a default role file declared with `defineApplicationRole()`:
+
+```ts src/roles/default-role.ts
+import { defineApplicationRole, PermissionFlag } from 'twenty-sdk/define';
+
+export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
+  'b648f87b-1d26-4961-b974-0908fd991061';
+
+export default defineApplicationRole({
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  label: 'Default function role',
+  description: 'Default role for function Twenty client',
+  canReadAllObjectRecords: true,
+  canUpdateAllObjectRecords: false,
+  canSoftDeleteAllObjectRecords: false,
+  canDestroyAllObjectRecords: false,
+  canUpdateAllSettings: false,
+  canBeAssignedToAgents: false,
+  canBeAssignedToUsers: false,
+  canBeAssignedToApiKeys: false,
+  objectPermissions: [],
+  fieldPermissions: [],
+  permissionFlags: [],
+});
+```
+
+`defineApplicationRole()` is a thin wrapper around `defineRole()` that flags **the** role used as your application's default at install time. Validation is identical to `defineRole`, but the build pipeline auto-wires its `universalIdentifier` into the application manifest's `defaultRoleUniversalIdentifier` — so you do not need to reference it from [`defineApplication`](/developers/extend/apps/config/application) yourself.
+
+Notes:
+- Exactly **one** `defineApplicationRole(...)` is allowed per app — the manifest build will fail if it finds more than one.
+- Use `defineRole()` (not `defineApplicationRole()`) for any **additional** roles your app ships.
+- Setting `defaultRoleUniversalIdentifier` explicitly on `defineApplication()` is still supported for backward compatibility, but is deprecated in favor of `defineApplicationRole()`.
+
+## Best practices
+
+- Start from the scaffolded role, then progressively restrict it — the default grants broad read access, which is rarely what you want in production.
+- Replace `objectPermissions` and `fieldPermissions` with the exact objects and fields your functions actually need.
+- `permissionFlags` control access to platform-level capabilities. Keep them minimal.
+- See a working example: [`hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).
@@ -1,493 +0,0 @@
---
-title: Data Model
-description: Define objects, fields, roles, and application metadata with the Twenty SDK.
-icon: "database"
---
-
-The `twenty-sdk` package provides `defineEntity` functions to declare your app's data model. You must use `export default defineEntity({...})` for the SDK to detect your entities. These functions validate your configuration at build time and provide IDE autocompletion and type safety.
-
-<Note>
-  **File organization is up to you.**
-  Entity detection is AST-based — the SDK finds `export default defineEntity(...)` calls regardless of where the file lives. Grouping files by type (e.g., `logic-functions/`, `roles/`) is just a convention, not a requirement.
-</Note>
-
-<AccordionGroup>
-<Accordion title="defineRole" description="Configure role permissions and object access">
-
-Roles encapsulate permissions on your workspace's objects and actions.
-
-```ts restricted-company-role.ts
-import {
-  defineRole,
-  PermissionFlag,
-  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-} from 'twenty-sdk/define';
-
-export default defineRole({
-  universalIdentifier: '2c80f640-2083-4803-bb49-003e38279de6',
-  label: 'My new role',
-  description: 'A role that can be used in your workspace',
-  canReadAllObjectRecords: false,
-  canUpdateAllObjectRecords: false,
-  canSoftDeleteAllObjectRecords: false,
-  canDestroyAllObjectRecords: false,
-  canUpdateAllSettings: false,
-  canBeAssignedToAgents: false,
-  canBeAssignedToUsers: false,
-  canBeAssignedToApiKeys: false,
-  objectPermissions: [
-    {
-      objectUniversalIdentifier:
-        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
-      canReadObjectRecords: true,
-      canUpdateObjectRecords: true,
-      canSoftDeleteObjectRecords: false,
-      canDestroyObjectRecords: false,
-    },
-  ],
-  fieldPermissions: [
-    {
-      objectUniversalIdentifier:
-        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
-      fieldUniversalIdentifier:
-        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.name.universalIdentifier,
-      canReadFieldValue: false,
-      canUpdateFieldValue: false,
-    },
-  ],
-  permissionFlags: [PermissionFlag.APPLICATIONS],
-});
-```
-
-</Accordion>
-<Accordion title="defineApplication" description="Configure application metadata (required, one per app)">
-
-Every app must have exactly one `defineApplication` call that describes:
-
- **Identity**: identifiers, display name, and description.
- **Permissions**: which role its functions and front components use.
- **(Optional) Variables**: key–value pairs exposed to your functions as environment variables.
- **(Optional) Pre-install / post-install functions**: logic functions that run before or after installation.
-
-```ts src/application-config.ts
-import { defineApplication } from 'twenty-sdk/define';
-import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
-
-export default defineApplication({
-  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
-  displayName: 'My Twenty App',
-  description: 'My first Twenty app',
-  applicationVariables: {
-    DEFAULT_RECIPIENT_NAME: {
-      universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
-      description: 'Default recipient name for postcards',
-      value: 'Jane Doe',
-      isSecret: false,
-    },
-  },
-  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
-});
-```
-
-Notes:
- `universalIdentifier` fields are deterministic IDs you own. Generate them once and keep them stable across syncs.
- `applicationVariables` become environment variables for your functions and front components (e.g., `DEFAULT_RECIPIENT_NAME` is available as `process.env.DEFAULT_RECIPIENT_NAME`).
- `defaultRoleUniversalIdentifier` must reference a role defined with `defineRole()` (see above).
- Pre-install and post-install functions are detected automatically during the manifest build — you do not need to reference them in `defineApplication()`.
-
-#### Marketplace metadata
-
-If you plan to [publish your app](/developers/extend/apps/publishing), these optional fields control how it appears in the marketplace:
-
-| Field | Description |
-|-------|-------------|
-| `author` | Author or company name |
-| `category` | App category for marketplace filtering |
-| `logoUrl` | Path to your app logo (e.g., `public/logo.png`) |
-| `screenshots` | Array of screenshot paths (e.g., `public/screenshot-1.png`) |
-| `aboutDescription` | Longer markdown description for the "About" tab. If omitted, the marketplace uses the package's `README.md` from npm |
-| `websiteUrl` | Link to your website |
-| `termsUrl` | Link to terms of service |
-| `emailSupport` | Support email address |
-| `issueReportUrl` | Link to issue tracker |
-
-#### Roles and permissions
-
-The `defaultRoleUniversalIdentifier` in `application-config.ts` designates the default role used by your app's logic functions and front components. See `defineRole` above for details.
-
- The runtime token injected as `TWENTY_APP_ACCESS_TOKEN` is derived from this role.
- The typed client is restricted to the permissions granted to that role.
- Follow least-privilege: create a dedicated role with only the permissions your functions need.
-
-##### Default function role
-
-When you scaffold a new app, the CLI creates a default role file:
-
-```ts src/roles/default-role.ts
-import { defineRole, PermissionFlag } from 'twenty-sdk/define';
-
-export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
-  'b648f87b-1d26-4961-b974-0908fd991061';
-
-export default defineRole({
-  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
-  label: 'Default function role',
-  description: 'Default role for function Twenty client',
-  canReadAllObjectRecords: true,
-  canUpdateAllObjectRecords: false,
-  canSoftDeleteAllObjectRecords: false,
-  canDestroyAllObjectRecords: false,
-  canUpdateAllSettings: false,
-  canBeAssignedToAgents: false,
-  canBeAssignedToUsers: false,
-  canBeAssignedToApiKeys: false,
-  objectPermissions: [],
-  fieldPermissions: [],
-  permissionFlags: [],
-});
-```
-
-This role's `universalIdentifier` is referenced in `application-config.ts` as `defaultRoleUniversalIdentifier`:
-
- **\*.role.ts** defines what the role can do.
- **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.
- Replace `objectPermissions` and `fieldPermissions` with the objects and fields your functions actually need.
- `permissionFlags` control access to platform-level capabilities. Keep them minimal.
- See a working example: [`hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).
-
-</Accordion>
-<Accordion title="defineObject" description="Define custom objects with fields">
-
-Custom objects describe both schema and behavior for records in your workspace. Use `defineObject()` to define objects with built-in validation:
-
-```ts postCard.object.ts
-import { defineObject, FieldType } from 'twenty-sdk/define';
-
-enum PostCardStatus {
-  DRAFT = 'DRAFT',
-  SENT = 'SENT',
-  DELIVERED = 'DELIVERED',
-  RETURNED = 'RETURNED',
-}
-
-export default defineObject({
-  universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
-  nameSingular: 'postCard',
-  namePlural: 'postCards',
-  labelSingular: 'Post Card',
-  labelPlural: 'Post Cards',
-  description: 'A post card object',
-  icon: 'IconMail',
-  fields: [
-    {
-      universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
-      name: 'content',
-      type: FieldType.TEXT,
-      label: 'Content',
-      description: "Postcard's content",
-      icon: 'IconAbc',
-    },
-    {
-      universalIdentifier: 'c6aa31f3-da76-4ac6-889f-475e226009ac',
-      name: 'recipientName',
-      type: FieldType.FULL_NAME,
-      label: 'Recipient name',
-      icon: 'IconUser',
-    },
-    {
-      universalIdentifier: '95045777-a0ad-49ec-98f9-22f9fc0c8266',
-      name: 'recipientAddress',
-      type: FieldType.ADDRESS,
-      label: 'Recipient address',
-      icon: 'IconHome',
-    },
-    {
-      universalIdentifier: '87b675b8-dd8c-4448-b4ca-20e5a2234a1e',
-      name: 'status',
-      type: FieldType.SELECT,
-      label: 'Status',
-      icon: 'IconSend',
-      defaultValue: `'${PostCardStatus.DRAFT}'`,
-      options: [
-        { value: PostCardStatus.DRAFT, label: 'Draft', position: 0, color: 'gray' },
-        { value: PostCardStatus.SENT, label: 'Sent', position: 1, color: 'orange' },
-        { value: PostCardStatus.DELIVERED, label: 'Delivered', position: 2, color: 'green' },
-        { value: PostCardStatus.RETURNED, label: 'Returned', position: 3, color: 'orange' },
-      ],
-    },
-    {
-      universalIdentifier: 'e06abe72-5b44-4e7f-93be-afc185a3c433',
-      name: 'deliveredAt',
-      type: FieldType.DATE_TIME,
-      label: 'Delivered at',
-      icon: 'IconCheck',
-      isNullable: true,
-      defaultValue: null,
-    },
-  ],
-});
-```
-
-Key points:
-
- Use `defineObject()` for built-in validation and better IDE support.
- 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 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
-  such as `id`, `name`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy` and `deletedAt`.
-  You don't need to define these in your `fields` array — only add your custom fields.
-  You can override default fields by defining a field with the same name in your `fields` array,
-  but this is not recommended.
-</Note>
-
-</Accordion>
-<Accordion title="defineField — Standard fields" description="Extend existing objects with additional fields">
-
-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:
-
-```ts src/fields/company-loyalty-tier.field.ts
-import { defineField, FieldType } from 'twenty-sdk/define';
-
-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()`.
-
-</Accordion>
-<Accordion title="defineField — Relation fields" description="Connect objects together with bidirectional 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):
-
-```ts src/fields/post-card-recipients-on-post-card.field.ts
-import { defineField, FieldType, RelationType } from 'twenty-sdk/define';
-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):
-
-```ts src/fields/post-card-on-post-card-recipient.field.ts
-import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk/define';
-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`:
-
-```ts src/fields/person-on-self-hosting-user.field.ts
-import {
-  defineField,
-  FieldType,
-  RelationType,
-  OnDeleteAction,
-  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-} from 'twenty-sdk/define';
-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:
-
-```ts
-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
-  ],
-});
-```
-</Accordion>
-</AccordionGroup>
-
-## Scaffolding entities with `yarn twenty add`
-
-Instead of creating entity files by hand, you can use the interactive scaffolder:
-
-```bash filename="Terminal"
-yarn twenty add
-```
-
-This prompts you to pick an entity type and walks you through the required fields. It generates a ready-to-use file with a stable `universalIdentifier` and the correct `defineEntity()` call.
-
-You can also pass the entity type directly to skip the first prompt:
-
-```bash filename="Terminal"
-yarn twenty add object
-yarn twenty add logicFunction
-yarn twenty add frontComponent
-```
-
-### Available entity types
-
-| Entity type | Command | Generated file |
-|-------------|---------|----------------|
-| Object | `yarn twenty add object` | `src/objects/<name>.ts` |
-| Field | `yarn twenty add field` | `src/fields/<name>.ts` |
-| Logic function | `yarn twenty add logicFunction` | `src/logic-functions/<name>.ts` |
-| Front component | `yarn twenty add frontComponent` | `src/front-components/<name>.tsx` |
-| Role | `yarn twenty add role` | `src/roles/<name>.ts` |
-| Skill | `yarn twenty add skill` | `src/skills/<name>.ts` |
-| Agent | `yarn twenty add agent` | `src/agents/<name>.ts` |
-| View | `yarn twenty add view` | `src/views/<name>.ts` |
-| Navigation menu item | `yarn twenty add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |
-| Page layout | `yarn twenty add pageLayout` | `src/page-layouts/<name>.ts` |
-
-### What the scaffolder generates
-
-Each entity type has its own template. For example, `yarn twenty add object` asks for:
-
-1. **Name (singular)** — e.g., `invoice`
-2. **Name (plural)** — e.g., `invoices`
-3. **Label (singular)** — auto-populated from the name (e.g., `Invoice`)
-4. **Label (plural)** — auto-populated (e.g., `Invoices`)
-5. **Create a view and navigation item?** — if you answer yes, the scaffolder also generates a matching view and sidebar link for the new object.
-
-Other entity types have simpler prompts — most only ask for a name.
-
-The `field` entity type is more detailed: it asks for the field name, label, type (from a list of all available field types like `TEXT`, `NUMBER`, `SELECT`, `RELATION`, etc.), and the target object's `universalIdentifier`.
-
-### Custom output path
-
-Use the `--path` flag to place the generated file in a custom location:
-
-```bash filename="Terminal"
-yarn twenty add logicFunction --path src/custom-folder
-```
@@ -0,0 +1,46 @@
+---
+title: Extending Objects
+description: Add fields to standard Twenty objects (Person, Company, …) or to objects from other apps using defineField.
+icon: "wand-magic-sparkles"
+---
+
+Use `defineField()` to add a field to an object you don't own — a standard Twenty object like Person or Company, or an object shipped by another installed app. Unlike inline fields declared inside [`defineObject`](/developers/extend/apps/data/objects), standalone fields require an `objectUniversalIdentifier` to specify which object they extend.
+
+```ts src/fields/company-loyalty-tier.field.ts
+import { defineField, FieldType } from 'twenty-sdk/define';
+
+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 Twenty objects, import the constant from `twenty-sdk`:
+
+  ```ts
+  import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';
+
+  // STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier
+  // STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier
+  // STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.opportunity.universalIdentifier
+  // …
+  ```
+
+- When defining fields **inline inside `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()`.
+- File location is up to you. The convention is `src/fields/<name>.field.ts`, but the SDK detects fields anywhere in `src/`.
+
+## Adding a relation to an existing object
+
+To add a relation field (e.g. linking your custom object to a standard `Person`), use `defineField()` with `FieldType.RELATION`. The pattern is the same as for inline relations but with `objectUniversalIdentifier` set explicitly. See [Relations](/developers/extend/apps/data/relations) for the bidirectional pattern.
@@ -0,0 +1,93 @@
+---
+title: Objects
+description: Declare new record types — custom tables with their own fields — using defineObject.
+icon: "table"
+---
+
+Custom **objects** are new record types your app adds to a workspace — Post Card, Invoice, Subscription, anything specific to your domain. Each object declares its schema (fields, relations, default values) and a stable universal identifier that survives across syncs and deploys.
+
+```ts src/objects/post-card.object.ts
+import { defineObject, FieldType } from 'twenty-sdk/define';
+
+enum PostCardStatus {
+  DRAFT = 'DRAFT',
+  SENT = 'SENT',
+  DELIVERED = 'DELIVERED',
+  RETURNED = 'RETURNED',
+}
+
+export default defineObject({
+  universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
+  nameSingular: 'postCard',
+  namePlural: 'postCards',
+  labelSingular: 'Post Card',
+  labelPlural: 'Post Cards',
+  description: 'A post card object',
+  icon: 'IconMail',
+  fields: [
+    {
+      universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
+      name: 'content',
+      type: FieldType.TEXT,
+      label: 'Content',
+      description: "Postcard's content",
+      icon: 'IconAbc',
+    },
+    {
+      universalIdentifier: 'c6aa31f3-da76-4ac6-889f-475e226009ac',
+      name: 'recipientName',
+      type: FieldType.FULL_NAME,
+      label: 'Recipient name',
+      icon: 'IconUser',
+    },
+    {
+      universalIdentifier: '95045777-a0ad-49ec-98f9-22f9fc0c8266',
+      name: 'recipientAddress',
+      type: FieldType.ADDRESS,
+      label: 'Recipient address',
+      icon: 'IconHome',
+    },
+    {
+      universalIdentifier: '87b675b8-dd8c-4448-b4ca-20e5a2234a1e',
+      name: 'status',
+      type: FieldType.SELECT,
+      label: 'Status',
+      icon: 'IconSend',
+      defaultValue: `'${PostCardStatus.DRAFT}'`,
+      options: [
+        { value: PostCardStatus.DRAFT, label: 'Draft', position: 0, color: 'gray' },
+        { value: PostCardStatus.SENT, label: 'Sent', position: 1, color: 'orange' },
+        { value: PostCardStatus.DELIVERED, label: 'Delivered', position: 2, color: 'green' },
+        { value: PostCardStatus.RETURNED, label: 'Returned', position: 3, color: 'orange' },
+      ],
+    },
+    {
+      universalIdentifier: 'e06abe72-5b44-4e7f-93be-afc185a3c433',
+      name: 'deliveredAt',
+      type: FieldType.DATE_TIME,
+      label: 'Delivered at',
+      icon: 'IconCheck',
+      isNullable: true,
+      defaultValue: null,
+    },
+  ],
+});
+```
+
+## 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.
+- Inline fields defined here do **not** need an `objectUniversalIdentifier` — it's inherited from the parent object. Use [`defineField()`](/developers/extend/apps/data/extending-objects) to add fields to objects you don't own.
+- You can scaffold new objects with `yarn twenty add object`, which guides you through naming, fields, and relationships. See [Architecture → Scaffolding entities](/developers/extend/apps/getting-started/scaffolding).
+
+<Note>
+**Base fields are added automatically.** When you define a custom object, Twenty creates standard fields like `id`, `name`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy`, and `deletedAt` for you. You don't need to declare them in your `fields` array — only your custom fields. You can override a default field by declaring one with the same name, but this is rarely a good idea.
+</Note>
+
+## What's next
+
+- **Connect this object to others** — see [Relations](/developers/extend/apps/data/relations) for the bidirectional relation pattern.
+- **Add fields to objects from other apps** — see [Extending Objects](/developers/extend/apps/data/extending-objects) for `defineField()`.
+- **Display this object in the UI** — see [Views](/developers/extend/apps/layout/views) and [Navigation Menu Items](/developers/extend/apps/layout/navigation-menu-items) to put it in the sidebar.
@@ -0,0 +1,52 @@
+---
+title: Overview
+description: Shape the data your app adds to a workspace — objects, fields, and relations.
+icon: "database"
+---
+
+A Twenty app's **data layer** is the data your app *adds* to a workspace — the new record types it declares, the columns it adds to existing objects, and how those records connect to each other.
+
+```text
+┌──────────────────────────────────────────────────┐
+│ Object — a record type, e.g. PostCard            │
+│    ├─ Field     (name, type, label)              │
+│    ├─ Field                                      │
+│    └─ Relation  (link to another object)         │
+└──────────────────────────────────────────────────┘
+            │
+            ├── lives in your app, OR
+            │
+            ▼
+┌──────────────────────────────────────────────────┐
+│ Standard / other apps' objects                   │
+│    └─ Field added by your app via defineField    │
+└──────────────────────────────────────────────────┘
+```
+
+## In this section
+
+<CardGroup cols={2}>
+  <Card title="Objects" icon="table" href="/developers/extend/apps/data/objects">
+    `defineObject` — declare new record types with their own fields.
+  </Card>
+  <Card title="Extending Objects" icon="wand-magic-sparkles" href="/developers/extend/apps/data/extending-objects">
+    `defineField` — add fields to standard or other apps' objects.
+  </Card>
+  <Card title="Relations" icon="diagram-project" href="/developers/extend/apps/data/relations">
+    Bidirectional `MANY_TO_ONE` / `ONE_TO_MANY` connections between objects.
+  </Card>
+</CardGroup>
+
+## Entities at a glance
+
+| Entity | Purpose | Defined with |
+|--------|---------|--------------|
+| **Object** | A new custom record type (e.g. PostCard, Invoice) with its own fields | `defineObject()` |
+| **Field** | A column on an object. Standalone fields can extend objects you didn't create (e.g. add `loyaltyTier` to Company) | `defineField()` |
+| **Relation** | A bidirectional link between two objects — both sides declared as fields | `defineField()` with `FieldType.RELATION` |
+
+The SDK detects these via AST analysis at build time, so file organization is up to you — the convention is `src/objects/` and `src/fields/`. Stable `universalIdentifier` UUIDs tie everything together across deploys.
+
+<Note>
+Looking for **Application Config** or **Roles & Permissions**? Those describe the app itself rather than the data it adds — they live under [Config](/developers/extend/apps/config/overview). Looking for **Connections** (Linear, GitHub, Slack OAuth)? Those exist to be called *from* logic functions and live under [Logic](/developers/extend/apps/logic/connections).
+</Note>
@@ -0,0 +1,160 @@
+---
+title: Relations
+description: Connect objects together with bidirectional MANY_TO_ONE / ONE_TO_MANY relations.
+icon: "diagram-project"
+---
+
+Relations connect two objects together. In Twenty, relations are always **bidirectional** — every relation has two sides, and each side is declared as a field that references the other.
+
+| 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 (the 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
+
+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):
+
+```ts src/fields/post-card-recipients-on-post-card.field.ts
+import { defineField, FieldType, RelationType } from 'twenty-sdk/define';
+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):
+
+```ts src/fields/post-card-on-post-card-recipient.field.ts
+import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk/define';
+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. 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`:
+
+```ts src/fields/person-on-self-hosting-user.field.ts
+import {
+  defineField,
+  FieldType,
+  RelationType,
+  OnDeleteAction,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk/define';
+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
+
+You can also declare a relation directly inside [`defineObject`](/developers/extend/apps/data/objects). When inline, omit `objectUniversalIdentifier` — it's inherited from the parent object:
+
+```ts
+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
+  ],
+});
+```
@@ -1,295 +0,0 @@
---
-title: Getting Started
-icon: "rocket"
-description: Create your first Twenty app in minutes.
---
-
-## What are apps?
-
-Apps let you extend Twenty with custom objects, fields, logic functions, front components, AI skills, and more — all managed as code. Instead of configuring everything through the UI, you define your data model and logic in TypeScript and deploy it to one or more workspaces.
-
-## Prerequisites
-
-Before you begin, make sure the following is installed on your machine:
-
- **Node.js 24+** — [Download here](https://nodejs.org/)
- **Yarn 4** — Comes with Node.js via Corepack. Enable it by running `corepack enable`
- **Docker** — [Download here](https://www.docker.com/products/docker-desktop/). Required to run a local Twenty instance. Not needed if you already have a Twenty server running.
-
-## Create your first app
-
-### Scaffold your app
-
-Open a terminal and run:
-
-```bash filename="Terminal"
-npx create-twenty-app@latest my-twenty-app
-```
-
-You will be prompted to enter a name and a description for your app. Press **Enter** to accept the defaults.
-
-This creates a new folder called `my-twenty-app` with everything you need.
-
-### Set up a local Twenty instance
-
-The scaffolder will ask:
-
-> **Would you like to set up a local Twenty instance?**
-
- **Type `yes`** (recommended) — This pulls the `twenty-app-dev` Docker image and starts a local Twenty server on port `2020`. Make sure Docker is running before you continue.
- **Type `no`** — Choose this if you already have a Twenty server running locally.
-
-<div style={{textAlign: 'center'}}>
-  <img src="/images/docs/developers/extends/apps/start-instance.png" alt="Should start local instance?" />
-</div>
-
-### Sign in to your workspace
-
-Next, a browser window will open with the Twenty login page. Sign in with the pre-seeded demo account:
-
- **Email:** `tim@apple.dev`
- **Password:** `tim@apple.dev`
-
-<div style={{textAlign: 'center'}}>
-  <img src="/images/docs/developers/extends/apps/login.png" alt="Twenty login screen" />
-</div>
-
-### Authorize the app
-
-After you sign in, you will see an authorization screen. This lets your app interact with your workspace.
-
-Click **Authorize** to continue.
-
-<div style={{textAlign: 'center'}}>
-  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI authorization screen" />
-</div>
-
-Once authorized, your terminal will confirm that everything is set up.
-
-<div style={{textAlign: 'center'}}>
-  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App scaffolded successfully" />
-</div>
-
-### Start developing
-
-Go into your new app folder and start the development server:
-
-```bash filename="Terminal"
-cd my-twenty-app
-yarn twenty dev
-```
-
-This watches your source files, rebuilds on every change, and syncs your app to the local Twenty server automatically. You should see a live status panel in your terminal.
-
-For more detailed output (build logs, sync requests, error traces), use the `--verbose` flag:
-
-```bash filename="Terminal"
-yarn twenty dev --verbose
-```
-
-<Warning>
-Dev mode is only available on Twenty instances running in development (`NODE_ENV=development`). Production instances reject dev sync requests. Use `yarn twenty deploy` to deploy to production servers — see [Publishing Apps](/developers/extend/apps/publishing) for details.
-</Warning>
-
-<div style={{textAlign: 'center'}}>
-  <img src="/images/docs/developers/extends/apps/dev.png" alt="Dev mode terminal output" />
-</div>
-
-#### One-shot sync with `yarn twenty dev --once`
-
-If you do not want a watcher running in the background (for example in a CI pipeline, a git hook, or a scripted workflow), pass the `--once` flag. It runs the same pipeline as `yarn twenty dev` — build manifest, bundle files, upload, sync, regenerate the typed API client — but **exits as soon as the sync completes**:
-
-```bash filename="Terminal"
-yarn twenty dev --once
-```
-
-| Command | Behavior | When to use |
-|---------|----------|-------------|
-| `yarn twenty dev` | Watches your source files and re-syncs on every change. Keeps running until you stop it. | Interactive local development — you want the live status panel and instant feedback loop. |
-| `yarn twenty dev --once` | Performs a single build + sync, then exits with code `0` on success or `1` on failure. | Scripts, CI, pre-commit hooks, AI agents, and any non-interactive workflow. |
-
-Both modes require a Twenty server running in development mode and an authenticated remote — the same prerequisites apply.
-
-### See your app in Twenty
-
-Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) in your browser. Navigate to **Settings > Apps** and select the **Developer** tab. You should see your app listed under **Your Apps**:
-
-<div style={{textAlign: 'center'}}>
-  <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Your Apps list showing My twenty app" />
-</div>
-
-Click on **My twenty app** to open its **application registration**. A registration is a server-level record that describes your app — its name, unique identifier, OAuth credentials, and source (local, npm, or tarball). It lives on the server, not inside any specific workspace. When you install an app into a workspace, Twenty creates a workspace-scoped **application** that points back to this registration. One registration can be installed across multiple workspaces on the same server.
-
-<div style={{textAlign: 'center'}}>
-  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Application registration details" />
-</div>
-
-Click **View installed app** to see the installed app. The **About** tab shows the current version and management options:
-
-<div style={{textAlign: 'center'}}>
-  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Installed app" />
-</div>
-
-You are all set! Edit any file in `src/` and the changes will be picked up automatically.
-
---
-
-## What you can build
-
-Apps are composed of **entities** — each defined as a TypeScript file with a single `export default`:
-
-| Entity | What it does |
-|--------|-------------|
-| **Objects & Fields** | Define custom data models (like Post Card, Invoice) with typed fields |
-| **Logic functions** | Server-side TypeScript functions triggered by HTTP routes, cron schedules, or database events |
-| **Front components** | React components that render inside Twenty's UI (side panel, widgets, command menu) |
-| **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants |
-| **Views & Navigation** | Pre-configured list views and sidebar menu items for your objects |
-| **Page layouts** | Custom record detail pages with tabs and widgets |
-
-Head over to [Building Apps](/developers/extend/apps/building) for a detailed guide on each entity type.
-
---
-
-## Project structure
-
-The scaffolder generates the following file structure:
-
-```text filename="my-twenty-app/"
-my-twenty-app/
-  package.json
-  yarn.lock
-  .gitignore
-  .nvmrc
-  .yarnrc.yml
-  .oxlintrc.json
-  tsconfig.json
-  tsconfig.spec.json                          # TypeScript config for tests
-  vitest.config.ts                            # Vitest test runner configuration
-  LLMS.md
-  README.md
-  .github/
-    └── workflows/
-        └── ci.yml                            # GitHub Actions CI workflow
-  public/                                     # Public assets (images, fonts, etc.)
-  src/
-  ├── application-config.ts                   # Required — main application configuration
-  ├── default-role.ts                         # Default role for logic functions
-  ├── constants/
-  │   └── universal-identifiers.ts            # Auto-generated UUIDs and app metadata
-  └── __tests__/
-      ├── setup-test.ts                       # Test setup (server health check, config)
-      └── app-install.integration-test.ts     # Integration test
-```
-
-### Starting from an example
-
-To start from a more complete example with custom objects, fields, logic functions, front components, and more, use the `--example` flag:
-
-```bash filename="Terminal"
-npx create-twenty-app@latest my-twenty-app --example postcard
-```
-
-Examples are sourced from the [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) directory on GitHub. You can also scaffold individual entities into an existing project with `yarn twenty add` (see [Building Apps](/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add)).
-
-### Key files
-
-| File / Folder | Purpose |
-|---|---|
-| `package.json` | Declares your app name, version, and dependencies. Includes a `twenty` script so you can run `yarn twenty help` to see all commands. |
-| `src/application-config.ts` | **Required.** The main configuration file for your app. |
-| `src/default-role.ts` | Default role that controls what your logic functions can access. |
-| `src/constants/universal-identifiers.ts` | Auto-generated UUIDs and app metadata (display name, description). |
-| `src/__tests__/` | Integration tests (setup + example test). |
-| `public/` | Static assets (images, fonts) served with your app. |
-
-## Local development server
-
-The scaffolder already started a local Twenty server for you. To manage it later, use `yarn twenty server`:
-
-| Command | Description |
-|---------|-------------|
-| `yarn twenty server start` | Start the local server (pulls image if needed) |
-| `yarn twenty server start --port 3030` | Start on a custom port |
-| `yarn twenty server start --test` | Start a separate test instance on port 2021 |
-| `yarn twenty server stop` | Stop the server (preserves data) |
-| `yarn twenty server status` | Show server status, URL, version, and credentials |
-| `yarn twenty server logs` | Stream server logs |
-| `yarn twenty server logs --lines 100` | Show the last 100 log lines |
-| `yarn twenty server reset` | Delete all data and start fresh |
-| `yarn twenty server upgrade` | Pull the latest `twenty-app-dev` image and recreate the container |
-| `yarn twenty server upgrade 2.2.0` | Upgrade to a specific version |
-
-Data is persisted across restarts in two Docker volumes (`twenty-app-dev-data` for PostgreSQL, `twenty-app-dev-storage` for files). Use `reset` to wipe everything and start fresh.
-
-### Upgrading the server image
-
-Use `yarn twenty server upgrade` to check for a newer `twenty-app-dev` Docker image and update the container. The command pulls the image, compares it against the one the container was created from, and only recreates the container if the image actually changed. Your data volumes are preserved — only the container is replaced.
-
-```bash filename="Terminal"
-# Upgrade to the latest version (skips recreation if already up to date)
-yarn twenty server upgrade
-
-# Upgrade to a specific version
-yarn twenty server upgrade 2.2.0
-```
-
-If a newer image is available and the container was running, the upgrade command automatically starts a new container with the updated image. Run `yarn twenty server start` afterward to wait for it to become healthy. If the image hasn't changed, the container is left untouched.
-
-You can verify the running version with `yarn twenty server status`, which displays the `APP_VERSION` from the container.
-
-### Running a test instance
-
-Pass `--test` to any `server` command to manage a second, fully isolated instance — useful for running integration tests or experimenting without touching your main dev data.
-
-| Command | Description |
-|---------|-------------|
-| `yarn twenty server start --test` | Start the test instance (defaults to port 2021) |
-| `yarn twenty server stop --test` | Stop the test instance |
-| `yarn twenty server status --test` | Show test instance status, URL, version, and credentials |
-| `yarn twenty server logs --test` | Stream test instance logs |
-| `yarn twenty server reset --test` | Wipe test data and start fresh |
-| `yarn twenty server upgrade --test` | Upgrade the test instance image |
-
-The test instance runs in its own Docker container (`twenty-app-dev-test`) with dedicated volumes (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) and config, so it can run in parallel with your main instance without conflicts. Combine `--test` with `--port` to override the default 2021.
-
-<Note>
-  The server requires **Docker** to be running. If you see a "Docker not running" error, make sure Docker Desktop (or the Docker daemon) is started.
-</Note>
-
-## Manual setup (without the scaffolder)
-
-If you prefer to set things up yourself instead of using `create-twenty-app`, you can do it in two steps.
-
-**1. Add `twenty-sdk` and `twenty-client-sdk` as dependencies:**
-
-```bash filename="Terminal"
-yarn add twenty-sdk twenty-client-sdk
-```
-
-**2. Add a `twenty` script to your `package.json`:**
-
-```json filename="package.json"
-{
-  "scripts": {
-    "twenty": "twenty"
-  }
-}
-```
-
-You can now run `yarn twenty dev`, `yarn twenty help`, and all other commands.
-
-<Note>
-Do not install `twenty-sdk` globally. Always use it as a local project dependency so that each project can pin its own version.
-</Note>
-
-## Troubleshooting
-
-If you run into issues:
-
- Make sure **Docker is running** before starting the scaffolder with a local instance.
- Make sure you are using **Node.js 24+** (`node -v` to check).
- Make sure **Corepack is enabled** (`corepack enable`) so Yarn 4 is available.
- Try deleting `node_modules` and running `yarn install` again if dependencies seem broken.
-
-Still stuck? Ask for help on the [Twenty Discord](https://discord.com/channels/1130383047699738754/1130386664812982322).
@@ -1,6 +1,6 @@
 ---
-title: Architecture
-description: How Twenty apps work — sandboxing, lifecycle, and the building blocks.
+title: Concepts
+description: How Twenty apps work — entity model, sandboxing, and the install lifecycle.
 icon: "sitemap"
 ---

@@ -8,7 +8,7 @@ Twenty apps are TypeScript packages that extend your workspace with custom objec

 ## How apps work

-An app is a collection of **entities** declared using `defineEntity()` functions from the `twenty-sdk` package. The SDK detects these declarations via AST analysis at build time and produces a **manifest** — a complete description of what your app adds to a workspace.
+An app is a collection of **entities** declared using `defineEntity()` functions from the `twenty-sdk` package. The SDK detects these declarations via AST analysis at build time and produces a **manifest** — a complete description of what your app adds to a workspace. These functions validate your configuration at build time and provide IDE autocompletion and type safety.

 ```
 your-app/
@@ -36,17 +36,20 @@ your-app/

 | Entity | Purpose | Docs |
 |--------|---------|------|
-| **Application** | App identity, permissions, variables | [Data Model](/developers/extend/apps/data-model) |
-| **Role** | Permission sets for objects and fields | [Data Model](/developers/extend/apps/data-model) |
-| **Object** | Custom data tables with fields | [Data Model](/developers/extend/apps/data-model) |
-| **Field** | Extend existing objects, define relations | [Data Model](/developers/extend/apps/data-model) |
-| **Logic Function** | Server-side TypeScript with triggers | [Logic Functions](/developers/extend/apps/logic-functions) |
-| **Front Component** | Sandboxed React UI in Twenty's page | [Front Components](/developers/extend/apps/front-components) |
-| **Skill** | Reusable AI agent instructions | [Skills & Agents](/developers/extend/apps/skills-and-agents) |
-| **Agent** | AI assistants with custom prompts | [Skills & Agents](/developers/extend/apps/skills-and-agents) |
-| **View** | Pre-configured record list views | [Layout](/developers/extend/apps/layout) |
-| **Navigation Menu Item** | Custom sidebar entries | [Layout](/developers/extend/apps/layout) |
-| **Page Layout** | Custom record page tabs and widgets | [Layout](/developers/extend/apps/layout) |
+| **Application** | App identity, default role, variables | [Application Config](/developers/extend/apps/config/application) |
+| **Role** | Permission sets on objects and fields | [Roles & Permissions](/developers/extend/apps/config/roles) |
+| **Object** | Custom record types with fields | [Objects](/developers/extend/apps/data/objects) |
+| **Field** | Add fields to objects from other apps | [Extending Objects](/developers/extend/apps/data/extending-objects) |
+| **Relation** | Bidirectional links between objects | [Relations](/developers/extend/apps/data/relations) |
+| **Logic Function** | Server-side TypeScript with triggers | [Logic Functions](/developers/extend/apps/logic/logic-functions) |
+| **Skill** | Reusable AI agent instructions | [Skills & Agents](/developers/extend/apps/logic/skills-and-agents) |
+| **Agent** | AI assistants with custom prompts | [Skills & Agents](/developers/extend/apps/logic/skills-and-agents) |
+| **Connection Provider** | OAuth credentials for third-party APIs | [Connections](/developers/extend/apps/logic/connections) |
+| **View** | Pre-configured record list views | [Views](/developers/extend/apps/layout/views) |
+| **Navigation Menu Item** | Custom sidebar entries | [Navigation Menu Items](/developers/extend/apps/layout/navigation-menu-items) |
+| **Page Layout** | Tabs and widgets on a record's detail page | [Page Layouts](/developers/extend/apps/layout/page-layouts) |
+| **Front Component** | Sandboxed React UI inside Twenty | [Front Components](/developers/extend/apps/layout/front-components) |
+| **Command Menu Item** | Quick actions and Cmd+K entries | [Command Menu Items](/developers/extend/apps/layout/command-menu-items) |

 ## Sandboxing

@@ -75,30 +78,24 @@ your-app/

 - **`yarn twenty dev`** — watches your source files and live-syncs changes to a connected Twenty server. The typed API client is regenerated automatically when the schema changes.
 - **`yarn twenty build`** — compiles TypeScript, bundles logic functions and front components with esbuild, and produces a manifest.
- **Pre/post-install hooks** — optional logic functions that run during installation. See [Logic Functions](/developers/extend/apps/logic-functions) for details.
+- **Pre/post-install hooks** — optional functions that run during installation. See [Install Hooks](/developers/extend/apps/config/install-hooks) for details.

 ## Next steps

 <CardGroup cols={2}>
-  <Card title="Data Model" icon="database" href="/developers/extend/apps/data-model">
-    Define objects, fields, roles, and relations.
+  <Card title="Config" icon="screwdriver-wrench" href="/developers/extend/apps/config/overview">
+    Application identity, default role, and install hooks.
  </Card>
-  <Card title="Logic Functions" icon="bolt" href="/developers/extend/apps/logic-functions">
-    Server-side functions with HTTP, cron, and event triggers.
+  <Card title="Data" icon="database" href="/developers/extend/apps/data/overview">
+    Objects, fields, and bidirectional relations.
  </Card>
-  <Card title="Front Components" icon="window-maximize" href="/developers/extend/apps/front-components">
-    Sandboxed React components inside Twenty's UI.
+  <Card title="Logic" icon="bolt" href="/developers/extend/apps/logic/overview">
+    Logic functions, skills, agents, and OAuth connections.
  </Card>
-  <Card title="Layout" icon="table-columns" href="/developers/extend/apps/layout">
-    Views, navigation items, and record page layouts.
+  <Card title="Layout" icon="table-columns" href="/developers/extend/apps/layout/overview">
+    Views, navigation, page layouts, front components.
  </Card>
-  <Card title="Skills & Agents" icon="robot" href="/developers/extend/apps/skills-and-agents">
-    AI skills and agents with custom prompts.
-  </Card>
-  <Card title="CLI & Testing" icon="terminal" href="/developers/extend/apps/cli-and-testing">
-    CLI commands, testing, assets, remotes, and CI.
-  </Card>
-  <Card title="Publishing" icon="rocket" href="/developers/extend/apps/publishing">
-    Deploy to a server or publish to the marketplace.
+  <Card title="Operations" icon="rocket" href="/developers/extend/apps/operations/overview">
+    CLI, testing, remotes, CI, and publishing your app.
  </Card>
 </CardGroup>
@@ -0,0 +1,72 @@
+---
+title: Local Server
+description: Manage the local Twenty Docker server — start, stop, upgrade, parallel test instance, and manual SDK setup.
+icon: "server"
+---
+
+## Managing the local server
+
+Use `yarn twenty server` to control the local Twenty container:
+
+| Command | What it does |
+|---------|--------------|
+| `yarn twenty server start` | Start the server (pulls the image if needed) |
+| `yarn twenty server start --port 3030` | Start on a custom port |
+| `yarn twenty server stop` | Stop the server (preserves data) |
+| `yarn twenty server status` | Show URL, version, and login credentials |
+| `yarn twenty server logs` | Stream server logs |
+| `yarn twenty server reset` | Wipe data and start fresh |
+| `yarn twenty server upgrade` | Pull the latest `twenty-app-dev` image |
+| `yarn twenty server upgrade 2.2.0` | Upgrade to a specific version |
+
+Data persists across restarts in two Docker volumes (`twenty-app-dev-data` for PostgreSQL, `twenty-app-dev-storage` for files). Use `reset` to wipe everything.
+
+## Upgrading the server image
+
+`yarn twenty server upgrade` pulls the latest image, compares digests, and only recreates the container if anything actually changed. Volumes are preserved — only the container is replaced. If a new image was pulled and the container was running, the upgrade automatically starts a new container; run `yarn twenty server start` afterward to wait for it to become healthy.
+
+```bash filename="Terminal"
+yarn twenty server upgrade            # Latest
+yarn twenty server upgrade 2.2.0      # Specific version
+```
+
+Verify the running version with `yarn twenty server status` (it shows the `APP_VERSION` baked into the container).
+
+## Running a parallel test instance
+
+Pass `--test` to any `server` command to manage a second, fully isolated instance — useful for integration tests or experiments without touching your main dev data:
+
+| Command | What it does |
+|---------|--------------|
+| `yarn twenty server start --test` | Start the test instance (defaults to port 2021) |
+| `yarn twenty server stop --test` | Stop it |
+| `yarn twenty server status --test` | Show its status |
+| `yarn twenty server logs --test` | Stream its logs |
+| `yarn twenty server reset --test` | Wipe its data |
+| `yarn twenty server upgrade --test` | Upgrade its image |
+
+The test instance has its own container (`twenty-app-dev-test`), volumes (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`), and config — it runs alongside your main instance without conflicts. Combine `--test` with `--port` to override 2021.
+
+## Manual setup (without the scaffolder)
+
+Skip the scaffolder if you're adding the SDK to an existing project:
+
+```bash filename="Terminal"
+yarn add twenty-sdk twenty-client-sdk
+```
+
+Add the script to `package.json`:
+
+```json filename="package.json"
+{
+  "scripts": {
+    "twenty": "twenty"
+  }
+}
+```
+
+You can now run `yarn twenty dev`, `yarn twenty server start`, and the rest.
+
+<Note>
+Don't install `twenty-sdk` globally — pin it per project so each app uses its own version.
+</Note>
@@ -0,0 +1,40 @@
+---
+title: Project Structure
+description: What's inside a scaffolded Twenty app — files, folders, and what each one does.
+icon: "folder-tree"
+---
+
+A new app generated by `npx create-twenty-app` looks like this:
+
+```text filename="my-twenty-app/"
+my-twenty-app/
+  package.json
+  src/
+    application-config.ts                   # Required — your app's entry point
+    default-role.ts                         # Permissions for logic functions
+    constants/
+      universal-identifiers.ts              # Auto-generated UUIDs and metadata
+    __tests__/
+      setup-test.ts
+      app-install.integration-test.ts
+  .github/workflows/ci.yml                  # GitHub Actions
+  public/                                   # Static assets
+  vitest.config.ts                          # Test runner config
+  tsconfig.json, tsconfig.spec.json
+  .nvmrc, .yarnrc.yml, .oxlintrc.json
+  README.md, LLMS.md
+```
+
+## Key files
+
+| File / Folder | Purpose |
+|---|---|
+| `src/application-config.ts` | **Required.** The main configuration file for your app. |
+| `src/default-role.ts` | Default role controlling what your logic functions can access. |
+| `src/constants/universal-identifiers.ts` | Auto-generated UUIDs and metadata (display name, description). |
+| `src/__tests__/` | Integration tests (setup + example test). |
+| `public/` | Static assets (images, fonts) served with your app. |
+
+<Note>
+**File organization is up to you.** The folders above are conventions — the SDK detects entities via AST analysis on `export default defineEntity(...)` calls regardless of where the file lives.
+</Note>
@@ -0,0 +1,184 @@
+---
+title: Quick Start
+icon: "rocket"
+description: Create your first Twenty app in minutes.
+---
+
+## Prerequisites
+
+- **Node.js 24+** — [Download](https://nodejs.org/)
+- **Yarn 4** — bundled with Node via Corepack. Enable it: `corepack enable`
+- **Docker** — [Download](https://www.docker.com/products/docker-desktop/). Needed to run a local Twenty server. Skip if you already have Twenty running elsewhere.
+
+Building a Twenty app has three phases. The scaffolder collapses them into one happy-path command, but each phase is a separate concept — when something fails, knowing which phase you're in tells you what to fix.
+
+| Phase | What you do | Tool | Result |
+|---|---|---|---|
+| **1. Scaffold** | Generate the app's source code | `npx create-twenty-app` | A TypeScript project on disk |
+| **2. Run a server** | Start a Twenty server to sync into | Docker + `yarn twenty server` | A running Twenty instance |
+| **3. Sync** | Live-sync your code to the server | `yarn twenty dev` | Your changes appear in the UI |
+
+---
+
+## Phase 1 — Scaffold your project
+
+Create a new app from the template:
+
+```bash filename="Terminal"
+npx create-twenty-app@latest my-twenty-app
+```
+
+You'll be prompted for a name and description — press **Enter** for the defaults. This generates a TypeScript project in `my-twenty-app/` with a starter `application-config.ts`, a default role, a CI workflow, and an integration test.
+
+**After this phase:** you have an app's source code on your machine. It isn't running yet — that's Phase 2.
+
+---
+
+## Phase 2 — Run a local Twenty server
+
+Your app needs a Twenty server to sync into. The server is a full Twenty instance — UI, GraphQL API, PostgreSQL — running locally in Docker. Your local code uploads its definitions to that server, which makes them appear in the UI.
+
+The scaffolder offers to start one for you:
+
+> **Would you like to set up a local Twenty instance?**
+
+- **Yes (recommended)** — pulls the `twentycrm/twenty-app-dev` Docker image and starts it on port `2020`. Make sure Docker is running first.
+- **No** — choose this if you already have a Twenty server you want to connect to. You can wire it up later with `yarn twenty remote add`.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/start-instance.png" alt="Should start local instance?" />
+</div>
+
+Once the server is up, a browser opens for sign-in. Use the pre-seeded demo account:
+
+- **Email:** `tim@apple.dev`
+- **Password:** `tim@apple.dev`
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/login.png" alt="Twenty login screen" />
+</div>
+
+Click **Authorize** on the next screen — this gives the CLI access to your workspace.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI authorization screen" />
+</div>
+
+Your terminal will confirm everything is set up.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App scaffolded successfully" />
+</div>
+
+**After this phase:** you have a running Twenty server at [http://localhost:2020](http://localhost:2020) with your CLI authorized to sync to it.
+
+<Note>
+If Docker isn't installed or running, the scaffolder will tell you the right start command for your OS. Once Docker is up, you can resume with `yarn twenty server start` — no need to re-scaffold.
+</Note>
+
+---
+
+## Phase 3 — Sync your changes
+
+This is the inner loop you'll spend most of your time in.
+
+```bash filename="Terminal"
+cd my-twenty-app
+yarn twenty dev
+```
+
+This watches `src/`, rebuilds on every change, and syncs the result to the server. Edit a file, save, and within a second the server reflects the change. You'll see a live status panel in your terminal.
+
+For more detailed output (build logs, sync requests, error traces), add `--verbose`.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/dev.png" alt="Dev mode terminal output" />
+</div>
+
+Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). You should see your app under **Your Apps**.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Your Apps list showing My twenty app" />
+</div>
+
+Click **My twenty app** to see its **application registration** — a server-level record describing your app (name, identifier, OAuth credentials, source). One registration can be installed across multiple workspaces on the same server.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Application registration details" />
+</div>
+
+Click **View installed app** to see the workspace install. The **About** tab shows version and management options.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Installed app" />
+</div>
+
+**After this phase:** you have a live development loop. Edit any file in `src/` and it appears in the UI.
+
+### One-shot sync for CI and scripts
+
+Pass `--once` to run a single build + sync and exit — same pipeline, no watcher:
+
+```bash filename="Terminal"
+yarn twenty dev --once
+```
+
+| Command | Behavior | When to use |
+|---------|----------|-------------|
+| `yarn twenty dev` | Watches and re-syncs on every change. Runs until you stop it. | Interactive local development. |
+| `yarn twenty dev --once` | Single build + sync, exits `0` on success, `1` on failure. | CI, pre-commit hooks, AI agents, scripted workflows. |
+
+Both modes need a server in development mode and an authenticated remote.
+
+<Warning>
+Dev mode is only available on Twenty instances running in development (`NODE_ENV=development`). Production instances reject dev sync requests — use `yarn twenty deploy` to deploy to production servers. See [Publishing](/developers/extend/apps/operations/publishing).
+</Warning>
+
+---
+
+## Starting from an example
+
+Use `--example` to start with a more complete project (custom objects, fields, logic functions, front components):
+
+```bash filename="Terminal"
+npx create-twenty-app@latest my-twenty-app --example postcard
+```
+
+Examples live in [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples). You can also scaffold individual entities into an existing project with `yarn twenty add` — see [Scaffolding](/developers/extend/apps/getting-started/scaffolding).
+
+---
+
+## What you can build
+
+Apps are composed of **entities** — each defined as a TypeScript file with a single `export default`:
+
+| Entity | What it does |
+|--------|-------------|
+| **Objects & Fields** | Custom data models (Post Card, Invoice, etc.) with typed fields |
+| **Logic functions** | Server-side TypeScript triggered by HTTP routes, cron schedules, or database events |
+| **Front components** | React components that render inside Twenty's UI (side panel, widgets, command menu) |
+| **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants |
+| **Views & Navigation** | Pre-configured list views and sidebar menu items |
+| **Page layouts** | Custom record detail pages with tabs and widgets |
+
+Full reference: [Concepts](/developers/extend/apps/getting-started/concepts).
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Config" icon="screwdriver-wrench" href="/developers/extend/apps/config/overview">
+    Application identity, default role, install hooks, public assets.
+  </Card>
+  <Card title="Data" icon="database" href="/developers/extend/apps/data/overview">
+    Objects, fields, and bidirectional relations.
+  </Card>
+  <Card title="Logic" icon="bolt" href="/developers/extend/apps/logic/overview">
+    Logic functions, skills, agents, and OAuth connections.
+  </Card>
+  <Card title="Layout" icon="table-columns" href="/developers/extend/apps/layout/overview">
+    Views, navigation, page layouts, front components.
+  </Card>
+  <Card title="Operations" icon="rocket" href="/developers/extend/apps/operations/overview">
+    CLI, testing, remotes, CI, and publishing your app.
+  </Card>
+</CardGroup>
@@ -0,0 +1,58 @@
+---
+title: Scaffolding
+description: Generate entity files interactively with yarn twenty add — objects, fields, views, logic functions, and more.
+icon: "wand-magic-sparkles"
+---
+
+Instead of creating entity files by hand, use the interactive scaffolder:
+
+```bash filename="Terminal"
+yarn twenty add
+```
+
+It prompts you to pick an entity type and walks you through the required fields, then writes a ready-to-use file with a stable `universalIdentifier` and the correct `defineEntity()` call.
+
+You can also pass the entity type directly to skip the first prompt:
+
+```bash filename="Terminal"
+yarn twenty add object
+yarn twenty add logicFunction
+yarn twenty add frontComponent
+```
+
+## Available entity types
+
+| Entity type | Command | Generated file |
+|-------------|---------|----------------|
+| Object | `yarn twenty add object` | `src/objects/<name>.ts` |
+| Field | `yarn twenty add field` | `src/fields/<name>.ts` |
+| Logic function | `yarn twenty add logicFunction` | `src/logic-functions/<name>.ts` |
+| Front component | `yarn twenty add frontComponent` | `src/front-components/<name>.tsx` |
+| Role | `yarn twenty add role` | `src/roles/<name>.ts` |
+| Skill | `yarn twenty add skill` | `src/skills/<name>.ts` |
+| Agent | `yarn twenty add agent` | `src/agents/<name>.ts` |
+| View | `yarn twenty add view` | `src/views/<name>.ts` |
+| Navigation menu item | `yarn twenty add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |
+| Page layout | `yarn twenty add pageLayout` | `src/page-layouts/<name>.ts` |
+
+## What the scaffolder generates
+
+Each entity type has its own template. For example, `yarn twenty add object` asks for:
+
+1. **Name (singular)** — e.g., `invoice`
+2. **Name (plural)** — e.g., `invoices`
+3. **Label (singular)** — auto-populated from the name (e.g., `Invoice`)
+4. **Label (plural)** — auto-populated (e.g., `Invoices`)
+5. **Create a view and navigation item?** — if you answer yes, the scaffolder also generates a matching view and sidebar link for the new object.
+
+Other entity types have simpler prompts — most only ask for a name.
+
+The `field` entity type is more detailed: it asks for the field name, label, type (from a list of all available field types like `TEXT`, `NUMBER`, `SELECT`, `RELATION`, etc.), and the target object's `universalIdentifier`.
+
+## Custom output path
+
+Use the `--path` flag to place the generated file in a custom location:
+
+```bash filename="Terminal"
+yarn twenty add logicFunction --path src/custom-folder
+```
@@ -0,0 +1,12 @@
+---
+title: Troubleshooting
+description: Common first-run issues — Docker, Node version, Yarn, dependencies.
+icon: "wrench"
+---
+
+- **Docker errors** — Make sure Docker Desktop (or the daemon) is running before `yarn twenty server start`. The error message will show the right start command for your OS.
+- **Wrong Node version** — Need 24+. Check with `node -v`.
+- **Yarn 4 missing** — Run `corepack enable`.
+- **Dependencies broken** — `rm -rf node_modules && yarn install`.
+
+Stuck? Ask on the [Twenty Discord](https://discord.com/channels/1130383047699738754/1130386664812982322).
@@ -1,178 +0,0 @@
---
-title: Layout
-description: Define views, navigation menu items, and page layouts to shape how your app appears in Twenty.
-icon: "table-columns"
---
-
-Layout entities control how your app surfaces inside Twenty's UI — what lives in the sidebar, which saved views ship with the app, and how a record detail page is arranged.
-
-## Layout concepts
-
-| Concept | What it controls | Entity |
-|---------|------------------|--------|
-| **View** | A saved list configuration for an object — visible fields, order, filters, groups | `defineView` |
-| **Navigation Menu Item** | An entry in the left sidebar that links to a view or an external URL | `defineNavigationMenuItem` |
-| **Page Layout** | The tabs and widgets that make up a record's detail page | `definePageLayout` |
-| **Page Layout Tab** | A standalone tab attached to an existing page layout (standard or your own app's) | `definePageLayoutTab` |
-
-Views, navigation items, and page layouts reference each other by `universalIdentifier`:
-
- A **navigation menu item** of type `VIEW` points at a `defineView` identifier, so the sidebar link opens that saved view.
- A **page layout** of type `RECORD_PAGE` targets an object and can embed [front components](/developers/extend/apps/front-components) inside its tabs as widgets.
-
-<AccordionGroup>
-<Accordion title="defineView" description="Define saved views for objects">
-
-Views are saved configurations for how records of an object are displayed — including which fields are visible, their order, and any filters or groups applied. Use `defineView()` to ship pre-configured views with your app:
-
-```ts src/views/example-view.ts
-import { defineView, ViewKey } from 'twenty-sdk/define';
-import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
-import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
-
-export default defineView({
-  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
-  name: 'All example items',
-  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
-  icon: 'IconList',
-  key: ViewKey.INDEX,
-  position: 0,
-  fields: [
-    {
-      universalIdentifier: 'f926bdb7-6af7-4683-9a09-adbca56c29f0',
-      fieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
-      position: 0,
-      isVisible: true,
-      size: 200,
-    },
-  ],
-});
-```
-
-Key points:
- `objectUniversalIdentifier` specifies which object this view applies to.
- `key` determines the view type (e.g., `ViewKey.INDEX` for the main list view).
- `fields` controls which columns appear and their order. Each field references a `fieldMetadataUniversalIdentifier`.
- You can also define `filters`, `filterGroups`, `groups`, and `fieldGroups` for more advanced configurations.
- `position` controls the ordering when multiple views exist for the same object.
-
-</Accordion>
-<Accordion title="defineNavigationMenuItem" description="Define sidebar navigation links">
-
-Navigation menu items add custom entries to the workspace sidebar. Use `defineNavigationMenuItem()` to link to views, external URLs, or objects:
-
-```ts src/navigation-menu-items/example-navigation-menu-item.ts
-import { defineNavigationMenuItem, NavigationMenuItemType } from 'twenty-sdk/define';
-import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from '../views/example-view';
-
-export default defineNavigationMenuItem({
-  universalIdentifier: '9327db91-afa1-41b6-bd9d-2b51a26efb4c',
-  name: 'example-navigation-menu-item',
-  icon: 'IconList',
-  color: 'blue',
-  position: 0,
-  type: NavigationMenuItemType.VIEW,
-  viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
-});
-```
-
-Key points:
- `type` determines what the menu item links to: `NavigationMenuItemType.VIEW` for a saved view, or `NavigationMenuItemType.LINK` for an external URL.
- For view links, set `viewUniversalIdentifier`. For external links, set `link`.
- `position` controls the ordering in the sidebar.
- `icon` and `color` (optional) customize the appearance.
-
-</Accordion>
-<Accordion title="definePageLayout" description="Define custom page layouts for record views">
-
-Page layouts let you customize how a record detail page looks — which tabs appear, what widgets are inside each tab, and how they are arranged. Use `definePageLayout()` to ship custom layouts with your app:
-
-```ts src/page-layouts/example-record-page-layout.ts
-import { definePageLayout, PageLayoutTabLayoutMode } from 'twenty-sdk/define';
-import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
-import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
-
-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,
-          },
-        },
-      ],
-    },
-  ],
-});
-```
-
-Key points:
- `type` is typically `'RECORD_PAGE'` to customize the detail view of a specific object.
- `objectUniversalIdentifier` specifies which object this layout applies to.
- Each `tab` defines a section of the page with a `title`, `position`, and `layoutMode` (`CANVAS` for free-form layout).
- Each `widget` inside a tab can render a front component, a relation list, or other built-in widget types.
- `position` on tabs controls their order. Use higher values (e.g., 50) to place custom tabs after built-in ones.
-
-</Accordion>
-<Accordion title="definePageLayoutTab" description="Add a tab to an existing page layout">
-
-`definePageLayoutTab` lets your app attach a single tab — with optional widgets — to an **existing** page layout. The most common use case is adding a custom tab (for example, an analytics or AI summary tab) to one of Twenty's built-in record pages, or to a page layout your own app already ships.
-
-The targeted page layout must be either a **standard** Twenty page layout or one defined by **your own app**; cross-app references to page layouts owned by another installed app are not supported today.
-
-```ts src/page-layouts/example-extra-tab.ts
-import {
-  definePageLayoutTab,
-  PageLayoutTabLayoutMode,
-} from 'twenty-sdk/define';
-import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
-
-const COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER =
-  '20202020-ab01-4001-8001-c0aba11c0100';
-
-export default definePageLayoutTab({
-  universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
-  pageLayoutUniversalIdentifier:
-    COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
-  title: 'Hello World',
-  position: 1000,
-  icon: 'IconWorld',
-  layoutMode: PageLayoutTabLayoutMode.CANVAS,
-  widgets: [
-    {
-      universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000002',
-      title: 'Hello World',
-      type: 'FRONT_COMPONENT',
-      configuration: {
-        configurationType: 'FRONT_COMPONENT',
-        frontComponentUniversalIdentifier:
-          HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
-      },
-    },
-  ],
-});
-```
-
-Key points:
- `pageLayoutUniversalIdentifier` is **required** when using `definePageLayoutTab` and must point to a page layout that already exists at install time (standard or your app's). When the parent page layout is missing, installation fails with a clear validation error.
- `widgets` are scoped to this tab only — they reference front components, views, etc. exactly like widgets defined inline in `definePageLayout`.
- `position` controls ordering against existing tabs on the targeted layout. Pick a value that places your tab where you want it relative to built-in tabs.
- Use this instead of `definePageLayout` when you only want to **add** to an existing layout. Use `definePageLayout` when you own the entire layout (typically a `RECORD_PAGE` for an object you ship in your app, or a `STANDALONE_PAGE`).
-
-</Accordion>
-</AccordionGroup>
@@ -0,0 +1,144 @@
+---
+title: Command Menu Items
+description: Surface front components as quick actions and command menu (Cmd+K) entries with defineCommandMenuItem.
+icon: "terminal"
+---
+
+A **command menu item** is the bridge between the user and a [front component](/developers/extend/apps/layout/front-components). It registers the component in Twenty's command menu (Cmd+K) and, optionally, as a pinned quick-action button in the top-right corner of the page.
+
+```ts src/command-menu-items/open-dashboard.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  label: 'Open Dashboard',
+  shortLabel: 'Dashboard',
+  icon: 'IconLayoutDashboard',
+  isPinned: true,
+  availabilityType: 'GLOBAL',
+  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
+});
+```
+
+## Configuration fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `universalIdentifier` | Yes | Stable unique ID for the command |
+| `label` | Yes | Full label shown in the command menu (Cmd+K) |
+| `frontComponentUniversalIdentifier` | Yes | The `universalIdentifier` of the front component this command opens |
+| `shortLabel` | No | Shorter label displayed on the pinned quick-action button |
+| `icon` | No | Icon name displayed next to the label (e.g. `'IconBolt'`, `'IconSend'`) |
+| `isPinned` | No | When `true`, shows the command as a quick-action button in the top-right corner of the page |
+| `availabilityType` | No | Controls where the command appears: `'GLOBAL'` (always available), `'RECORD_SELECTION'` (only when records are selected), or `'FALLBACK'` (shown when no other commands match) |
+| `availabilityObjectUniversalIdentifier` | No | Restrict the command to pages of a specific object type (e.g. only on Company records) |
+| `conditionalAvailabilityExpression` | No | A boolean expression that dynamically controls visibility (see below) |
+
+## Headless commands
+
+A command menu item paired with a [headless front component](/developers/extend/apps/layout/front-components#headless-vs-non-headless) is the idiomatic way to ship a one-click action — run code, navigate, or confirm and execute. The Front Components page covers the [SDK Command components](/developers/extend/apps/layout/front-components#sdk-command-components) (`Command`, `CommandLink`, `CommandModal`, `CommandOpenSidePanelPage`) that handle the action-and-unmount pattern.
+
+A typical flow:
+
+```tsx src/front-components/run-action.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { Command } from 'twenty-sdk/command';
+import { CoreApiClient } from 'twenty-sdk/clients';
+
+const RunAction = () => {
+  const execute = async () => {
+    const client = new CoreApiClient();
+    await client.mutation({
+      createTask: {
+        __args: { data: { title: 'Created by my app' } },
+        id: true,
+      },
+    });
+  };
+
+  return <Command execute={execute} />;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
+  name: 'run-action',
+  description: 'Creates a task from the command menu',
+  component: RunAction,
+  isHeadless: true,
+});
+```
+
+```ts src/command-menu-items/run-action.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
+  label: 'Run my action',
+  icon: 'IconPlayerPlay',
+  frontComponentUniversalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
+});
+```
+
+## Conditional availability expressions
+
+The `conditionalAvailabilityExpression` field lets you control when a command is visible based on the current page context. Import typed variables and operators from `twenty-sdk` to build expressions:
+
+```ts src/command-menu-items/bulk-update.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+import {
+  objectPermissions,
+  everyEquals,
+} from 'twenty-sdk/front-component';
+
+export default defineCommandMenuItem({
+  universalIdentifier: '...',
+  label: 'Bulk Update',
+  availabilityType: 'RECORD_SELECTION',
+  frontComponentUniversalIdentifier: '...',
+  conditionalAvailabilityExpression: everyEquals(
+    objectPermissions,
+    'canUpdateObjectRecords',
+    true,
+  ),
+});
+```
+
+### Context variables
+
+These represent the current state of the page:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `pageType` | `string` | Current page type (e.g. `'RecordIndexPage'`, `'RecordShowPage'`) |
+| `isInSidePanel` | `boolean` | Whether the component is rendered in a side panel |
+| `numberOfSelectedRecords` | `number` | Number of currently selected records |
+| `isSelectAll` | `boolean` | Whether "select all" is active |
+| `selectedRecords` | `array` | The selected record objects |
+| `favoriteRecordIds` | `array` | IDs of favorited records |
+| `objectPermissions` | `object` | Permissions for the current object type |
+| `targetObjectReadPermissions` | `object` | Read permissions for the target object |
+| `targetObjectWritePermissions` | `object` | Write permissions for the target object |
+| `featureFlags` | `object` | Active feature flags |
+| `objectMetadataItem` | `object` | Metadata of the current object type |
+| `hasAnySoftDeleteFilterOnView` | `boolean` | Whether the current view has a soft-delete filter |
+
+### Operators
+
+Combine variables into boolean expressions:
+
+| Operator | Description |
+|----------|-------------|
+| `isDefined(value)` | `true` if the value is not null/undefined |
+| `isNonEmptyString(value)` | `true` if the value is a non-empty string |
+| `includes(array, value)` | `true` if the array contains the value |
+| `includesEvery(array, prop, value)` | `true` if every item's property includes the value |
+| `every(array, prop)` | `true` if the property is truthy on every item |
+| `everyDefined(array, prop)` | `true` if the property is defined on every item |
+| `everyEquals(array, prop, value)` | `true` if the property equals the value on every item |
+| `some(array, prop)` | `true` if the property is truthy on at least one item |
+| `someDefined(array, prop)` | `true` if the property is defined on at least one item |
+| `someEquals(array, prop, value)` | `true` if the property equals the value on at least one item |
+| `someNonEmptyString(array, prop)` | `true` if the property is a non-empty string on at least one item |
+| `none(array, prop)` | `true` if the property is falsy on every item |
+| `noneDefined(array, prop)` | `true` if the property is undefined on every item |
+| `noneEquals(array, prop, value)` | `true` if the property does not equal the value on any item |
@@ -11,11 +11,16 @@ Front components are React components that render directly inside Twenty's UI. T
 Front components can render in two locations within Twenty:

 - **Side panel** — Non-headless front components open in the right-hand side panel. This is the default behavior when a front component is triggered from the command menu.
- **Widgets (dashboards and record pages)** — Front components can be embedded as widgets inside page layouts. When configuring a dashboard or a record page layout, users can add a front component widget.
+- **Widgets (dashboards and record pages)** — Front components can be embedded as widgets inside [page layouts](/developers/extend/apps/layout/page-layouts). When configuring a dashboard or a record page layout, users can add a front component widget.
+
+A front component on its own isn't reachable from the UI — you need to *surface* it. The two ways to do that are:
+
+- **Pair it with a [command menu item](/developers/extend/apps/layout/command-menu-items)** — registers it in the command menu (Cmd+K) and, optionally, as a pinned quick-action.
+- **Embed it as a widget in a [page layout](/developers/extend/apps/layout/page-layouts)** — places it on a record's detail page or dashboard.

 ## Basic example

-The quickest way to see a front component in action is to register it as a **command**. Adding a `command` field with `isPinned: true` makes it appear as a quick-action button in the top-right corner of the page — no page layout needed:
+The quickest way to see a front component in action is to pair it with a [`defineCommandMenuItem`](/developers/extend/apps/layout/command-menu-items), so it appears as a quick-action button in the top-right corner of the page:

 ```tsx src/front-components/hello-world.tsx
 import { defineFrontComponent } from 'twenty-sdk/define';
@@ -34,14 +39,20 @@ export default defineFrontComponent({
  name: 'hello-world',
  description: 'A simple front component',
  component: HelloWorld,
-  command: {
-    universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
-    shortLabel: 'Hello',
-    label: 'Hello World',
-    icon: 'IconBolt',
-    isPinned: true,
-    availabilityType: 'GLOBAL',
-  },
+});
+```
+
+```ts src/command-menu-items/hello-world.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
+  shortLabel: 'Hello',
+  label: 'Hello World',
+  icon: 'IconBolt',
+  isPinned: true,
+  availabilityType: 'GLOBAL',
+  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
 });
 ```

@@ -62,11 +73,10 @@ Click it to render the component inline.
 | `name` | No | Display name |
 | `description` | No | Description of what the component does |
 | `isHeadless` | No | Set to `true` if the component has no visible UI (see below) |
-| `command` | No | Register the component as a command (see [command options](#command-options) below) |

 ## Placing a front component on a page

-Beyond commands, you can embed a front component directly into a record page by adding it as a widget in a **page layout**. See the [definePageLayout](/developers/extend/apps/skills-and-agents#definepagelayout) section for details.
+Beyond commands, you can embed a front component directly into a record page by adding it as a widget in a **page layout**. See [Page Layouts](/developers/extend/apps/layout/page-layouts) for details.

 ## Headless vs non-headless

@@ -141,11 +151,17 @@ export default defineFrontComponent({
  description: 'Creates a task from the command menu',
  component: RunAction,
  isHeadless: true,
-  command: {
-    universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
-    label: 'Run my action',
-    icon: 'IconPlayerPlay',
-  },
+});
+```
+
+```ts src/command-menu-items/run-action.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
+  label: 'Run my action',
+  icon: 'IconPlayerPlay',
+  frontComponentUniversalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
 });
 ```

@@ -177,11 +193,6 @@ export default defineFrontComponent({
  description: 'Deletes a draft with confirmation',
  component: DeleteDraft,
  isHeadless: true,
-  command: {
-    universalIdentifier: 'b8c9d0e1-f2a3-4567-bcde-678901234567',
-    label: 'Delete draft',
-    icon: 'IconTrash',
-  },
 });
 ```

@@ -223,7 +234,8 @@ Available hooks:
 | Hook | Returns | Description |
 |------|---------|-------------|
 | `useUserId()` | `string` or `null` | The current user's ID |
-| `useRecordId()` | `string` or `null` | The current record's ID (when placed on a record page) |
+| `useSelectedRecordIds()` | `string[]` | All selected record IDs (empty array if none selected) |
+| `useRecordId()` | `string` or `null` | **Deprecated.** Use `useSelectedRecordIds()` instead |
 | `useFrontComponentId()` | `string` | This component instance's ID |
 | `useFrontComponentExecutionContext(selector)` | varies | Access the full execution context with a selector function |

@@ -286,88 +298,61 @@ export default defineFrontComponent({
 });
 ```

-## Command options
+### Working with multiple records

-Adding a `command` field to `defineFrontComponent` registers the component in the command menu (Cmd+K). If `isPinned` is `true`, it also appears as a quick-action button in the top-right corner of the page.
+Use `useSelectedRecordIds()` to handle multiple selected records. This is useful for bulk operations:

-| Field | Required | Description |
-|-------|----------|-------------|
-| `universalIdentifier` | Yes | Stable unique ID for the command |
-| `label` | Yes | Full label shown in the command menu (Cmd+K) |
-| `shortLabel` | No | Shorter label displayed on the pinned quick-action button |
-| `icon` | No | Icon name displayed next to the label (e.g. `'IconBolt'`, `'IconSend'`) |
-| `isPinned` | No | When `true`, shows the command as a quick-action button in the top-right corner of the page |
-| `availabilityType` | No | Controls where the command appears: `'GLOBAL'` (always available), `'RECORD_SELECTION'` (only when records are selected), or `'FALLBACK'` (shown when no other commands match) |
-| `availabilityObjectUniversalIdentifier` | No | Restrict the command to pages of a specific object type (e.g. only on Company records) |
-| `conditionalAvailabilityExpression` | No | A boolean expression to dynamically control whether the command is visible (see below) |
-
-## Conditional availability expressions
-
-The `conditionalAvailabilityExpression` field lets you control when a command is visible based on the current page context. Import typed variables and operators from `twenty-sdk` to build expressions:
-
-```tsx
+```tsx src/front-components/bulk-export.tsx
 import { defineFrontComponent } from 'twenty-sdk/define';
-import {
-  pageType,
-  numberOfSelectedRecords,
-  objectPermissions,
-  everyEquals,
-  isDefined,
-} from 'twenty-sdk/front-component';
+import { useSelectedRecordIds, numberOfSelectedRecords } from 'twenty-sdk/front-component';
+import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
+import { CoreApiClient } from 'twenty-sdk/clients';
+
+const BulkExport = () => {
+  const selectedRecordIds = useSelectedRecordIds();
+
+  const handleExport = async () => {
+    const client = new CoreApiClient();
+
+    for (const recordId of selectedRecordIds) {
+      await client.mutation({
+        updateTask: {
+          __args: { id: recordId, data: { exported: true } },
+          id: true,
+        },
+      });
+    }
+
+    await enqueueSnackbar({
+      message: `Exported ${selectedRecordIds.length} records`,
+      variant: 'success',
+    });
+
+    await closeSidePanel();
+  };
+
+  return (
+    <div style={{ padding: '20px' }}>
+      <p>Export {selectedRecordIds.length} selected record(s)?</p>
+      <button onClick={handleExport}>Export</button>
+    </div>
+  );
+};

 export default defineFrontComponent({
-  universalIdentifier: '...',
-  name: 'bulk-action',
-  component: BulkAction,
+  universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
+  name: 'bulk-export',
+  description: 'Export selected records',
+  component: BulkExport,
  command: {
-    universalIdentifier: '...',
-    label: 'Bulk Update',
+    universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678902',
+    label: 'Bulk Export',
    availabilityType: 'RECORD_SELECTION',
-    conditionalAvailabilityExpression: everyEquals(
-      objectPermissions,
-      'canUpdateObjectRecords',
-      true,
-    ),
+    conditionalAvailabilityExpression: numberOfSelectedRecords > 0,
  },
 });
 ```

-**Context variables** — these represent the current state of the page:
-
-| Variable | Type | Description |
-|----------|------|-------------|
-| `pageType` | `string` | Current page type (e.g. `'RecordIndexPage'`, `'RecordShowPage'`) |
-| `isInSidePanel` | `boolean` | Whether the component is rendered in a side panel |
-| `numberOfSelectedRecords` | `number` | Number of currently selected records |
-| `isSelectAll` | `boolean` | Whether "select all" is active |
-| `selectedRecords` | `array` | The selected record objects |
-| `favoriteRecordIds` | `array` | IDs of favorited records |
-| `objectPermissions` | `object` | Permissions for the current object type |
-| `targetObjectReadPermissions` | `object` | Read permissions for the target object |
-| `targetObjectWritePermissions` | `object` | Write permissions for the target object |
-| `featureFlags` | `object` | Active feature flags |
-| `objectMetadataItem` | `object` | Metadata of the current object type |
-| `hasAnySoftDeleteFilterOnView` | `boolean` | Whether the current view has a soft-delete filter |
-
-**Operators** — combine variables into boolean expressions:
-
-| Operator | Description |
-|----------|-------------|
-| `isDefined(value)` | `true` if the value is not null/undefined |
-| `isNonEmptyString(value)` | `true` if the value is a non-empty string |
-| `includes(array, value)` | `true` if the array contains the value |
-| `includesEvery(array, prop, value)` | `true` if every item's property includes the value |
-| `every(array, prop)` | `true` if the property is truthy on every item |
-| `everyDefined(array, prop)` | `true` if the property is defined on every item |
-| `everyEquals(array, prop, value)` | `true` if the property equals the value on every item |
-| `some(array, prop)` | `true` if the property is truthy on at least one item |
-| `someDefined(array, prop)` | `true` if the property is defined on at least one item |
-| `someEquals(array, prop, value)` | `true` if the property equals the value on at least one item |
-| `someNonEmptyString(array, prop)` | `true` if the property is a non-empty string on at least one item |
-| `none(array, prop)` | `true` if the property is falsy on every item |
-| `noneDefined(array, prop)` | `true` if the property is undefined on every item |
-| `noneEquals(array, prop, value)` | `true` if the property does not equal the value on any item |
-
 ## Public assets

 Front components can access files from the app's `public/` directory using `getPublicAssetUrl`:
@@ -384,7 +369,7 @@ export default defineFrontComponent({
 });
 ```

-See the [public assets section](/developers/extend/apps/cli-and-testing#public-assets-public-folder) for details.
+See the [public assets section](/developers/extend/apps/config/public-assets) for details.

 ## Styling

@@ -0,0 +1,42 @@
+---
+title: Navigation Menu Items
+description: Add custom entries to the workspace sidebar — links to saved views or external URLs.
+icon: "bars"
+---
+
+A **navigation menu item** is an entry in the left sidebar. Use `defineNavigationMenuItem()` to ship custom sidebar links — typically one per [view](/developers/extend/apps/layout/views) you ship — or to point at external URLs.
+
+```ts src/navigation-menu-items/example-navigation-menu-item.ts
+import { defineNavigationMenuItem, NavigationMenuItemType } from 'twenty-sdk/define';
+import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from '../views/example-view';
+
+export default defineNavigationMenuItem({
+  universalIdentifier: '9327db91-afa1-41b6-bd9d-2b51a26efb4c',
+  name: 'example-navigation-menu-item',
+  icon: 'IconList',
+  color: 'blue',
+  position: 0,
+  type: NavigationMenuItemType.VIEW,
+  viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
+});
+```
+
+## Key points
+
+- `type` determines what the menu item links to. Each type pairs with a specific identifier field:
+
+  | Type | What it does | Required field |
+  |------|--------------|----------------|
+  | `NavigationMenuItemType.VIEW` | Opens a saved view | `viewUniversalIdentifier` |
+  | `NavigationMenuItemType.LINK` | Opens an external URL | `link` |
+  | `NavigationMenuItemType.FOLDER` | Groups nested items under a label | `name` (and child items reference the folder via `folderUniversalIdentifier`) |
+  | `NavigationMenuItemType.OBJECT` | Opens an object's default index page | `targetObjectUniversalIdentifier` |
+  | `NavigationMenuItemType.PAGE_LAYOUT` | Opens a standalone page layout | `pageLayoutUniversalIdentifier` |
+
+- `position` controls ordering in the sidebar.
+- `icon` and `color` are optional and customize how the entry looks.
+- `folderUniversalIdentifier` is also available on any item to nest it inside a `FOLDER`-type parent.
+
+<Note>
+**Common pitfall:** creating an object without an associated view + navigation menu item makes that object invisible to users. Unless it's a technical/internal object, every custom object should have a default view *and* a sidebar entry pointing at it.
+</Note>
@@ -0,0 +1,56 @@
+---
+title: Overview
+description: Place your app inside Twenty's UI — sidebar entries, saved views, record page tabs, and sandboxed React components.
+icon: "table-columns"
+---
+
+A Twenty app's **layout layer** is everything the user sees: where the app surfaces in the sidebar, which list views it ships, how its record detail pages are arranged, and which custom React components render inside those pages.
+
+```text
+   Sidebar               Record list            Record detail page
+   ───────               ───────────            ──────────────────
+   [📋 My View]    ────▶ ┌──────────┐          ┌─────────────────────┐
+   [📋 Drafts ]          │ Companies│          │ Tabs: [Overview ]   │
+   [📋 Inbox  ]          │ ──────── │          │       [Notes    ]   │
+        ▲                │  Apple   │          │       [Hello    ]◀──── definePageLayoutTab
+        │                │  Acme    │          │                     │   adds a tab...
+        └ defineNavi-    │  …       │          │  ┌────────────────┐ │
+          gationMenu-    └────▲─────┘          │  │                │ │
+          Item points         │                │  │   React UI     │◀── …with a
+          to a defineView     │                │  │  (sandboxed in │ │   defineFrontComponent
+                              └ defineView     │  │   a Worker)    │ │   widget inside
+                                picks columns  │  └────────────────┘ │
+                                and filters    └─────────────────────┘
+```
+
+## In this section
+
+<CardGroup cols={2}>
+  <Card title="Views" icon="list" href="/developers/extend/apps/layout/views">
+    `defineView` — saved list configurations: visible columns, filters, groups.
+  </Card>
+  <Card title="Navigation Menu Items" icon="bars" href="/developers/extend/apps/layout/navigation-menu-items">
+    `defineNavigationMenuItem` — sidebar entries pointing at views or external URLs.
+  </Card>
+  <Card title="Page Layouts" icon="table-columns" href="/developers/extend/apps/layout/page-layouts">
+    `definePageLayout` and `definePageLayoutTab` — tabs and widgets on a record's detail page.
+  </Card>
+  <Card title="Front Components" icon="window-maximize" href="/developers/extend/apps/layout/front-components">
+    `defineFrontComponent` — sandboxed React components that render inside Twenty.
+  </Card>
+  <Card title="Command Menu Items" icon="terminal" href="/developers/extend/apps/layout/command-menu-items">
+    `defineCommandMenuItem` — register front components as Cmd+K entries and quick actions.
+  </Card>
+</CardGroup>
+
+## Where the app surfaces
+
+| Surface | What it controls | Entity |
+|---------|------------------|--------|
+| **Sidebar** | A custom entry linking to a saved view or external URL | `defineNavigationMenuItem` |
+| **Record list** | A saved configuration for an object — visible columns, order, filters, groups | `defineView` |
+| **Record detail page** | The tabs and widgets on a record page (your own object's, or a standard one) | `definePageLayout`, `definePageLayoutTab` |
+| **Inside any of the above** | A custom React widget — buttons, forms, dashboards, integrations | `defineFrontComponent` |
+| **Command menu (Cmd+K)** | A pinned quick action or hidden command | `defineCommandMenuItem` |
+
+Front components run inside an isolated Web Worker using Remote DOM — they render *natively* in the page (not inside an iframe), but cannot reach the host page or DOM directly. Communication with Twenty happens through a message-passing host API.
@@ -0,0 +1,102 @@
+---
+title: Page Layouts
+description: Customize record detail pages — tabs, widgets, and where front components render — using definePageLayout and definePageLayoutTab.
+icon: "table-columns"
+---
+
+A **page layout** controls how a record's detail page is arranged: which tabs appear and what widgets they contain. Use `definePageLayout()` to declare a layout for an object you own, or `definePageLayoutTab()` to add a single tab to a layout that already exists (yours or a standard Twenty one).
+
+| Use case | Entity |
+|----------|--------|
+| Define the entire layout for a record page on an object you own | `definePageLayout` |
+| Add one tab to an existing layout (your own object, or a standard one) | `definePageLayoutTab` |
+
+## definePageLayout
+
+Use this when you own the entire detail page — typically for a custom object you defined yourself.
+
+```ts src/page-layouts/example-record-page-layout.ts
+import { definePageLayout, PageLayoutTabLayoutMode } from 'twenty-sdk/define';
+import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
+import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
+
+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,
+          },
+        },
+      ],
+    },
+  ],
+});
+```
+
+### Key points
+
+- `type` is typically `'RECORD_PAGE'` to customize the detail view of a specific object.
+- `objectUniversalIdentifier` specifies which object this layout applies to.
+- Each `tab` defines a section of the page with a `title`, `position`, and `layoutMode` (`CANVAS` for free-form layout).
+- Each `widget` inside a tab can render a [front component](/developers/extend/apps/layout/front-components), a relation list, or other built-in widget types.
+- `position` on tabs controls their order. Use higher values (e.g., 50) to place custom tabs after built-in ones.
+
+## definePageLayoutTab
+
+Use this when you only want to **add** a tab to an existing layout — for example, an analytics tab on the standard Company page, or an AI summary tab attached to your own object's layout.
+
+```ts src/page-layouts/example-extra-tab.ts
+import {
+  definePageLayoutTab,
+  PageLayoutTabLayoutMode,
+} from 'twenty-sdk/define';
+import { HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER } from '../front-components/hello-world';
+
+const COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER =
+  '20202020-ab01-4001-8001-c0aba11c0100';
+
+export default definePageLayoutTab({
+  universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000001',
+  pageLayoutUniversalIdentifier:
+    COMPANY_RECORD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
+  title: 'Hello World',
+  position: 1000,
+  icon: 'IconWorld',
+  layoutMode: PageLayoutTabLayoutMode.CANVAS,
+  widgets: [
+    {
+      universalIdentifier: 'b1b2b3b4-b5b6-4000-8000-000000000002',
+      title: 'Hello World',
+      type: 'FRONT_COMPONENT',
+      configuration: {
+        configurationType: 'FRONT_COMPONENT',
+        frontComponentUniversalIdentifier:
+          HELLO_WORLD_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+      },
+    },
+  ],
+});
+```
+
+### Key points
+
+- `pageLayoutUniversalIdentifier` is **required** and must point to a page layout that already exists at install time — either a standard Twenty layout or one defined by your own app. Cross-app references to layouts owned by another installed app are not supported today. When the parent layout is missing, installation fails with a clear validation error.
+- `widgets` are scoped to this tab only — they reference [front components](/developers/extend/apps/layout/front-components), views, etc. exactly like widgets defined inline in `definePageLayout`.
+- `position` controls ordering against existing tabs on the targeted layout. Pick a value that places your tab where you want it relative to built-in tabs.
+- Use this instead of `definePageLayout` when you only want to add to an existing layout. Use `definePageLayout` when you own the entire layout.
@@ -0,0 +1,43 @@
+---
+title: Views
+description: Ship pre-configured saved views — column order, filters, groups — for objects in your app.
+icon: "list"
+---
+
+A **view** is a saved configuration for how records of an object are displayed: which fields appear, their order, whether they're visible, and any filters or groups applied. Use `defineView()` to ship pre-configured views with your app — typically a default index view for each custom object you create.
+
+```ts src/views/example-view.ts
+import { defineView, ViewKey } from 'twenty-sdk/define';
+import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
+import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
+
+export default defineView({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  name: 'All example items',
+  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
+  icon: 'IconList',
+  key: ViewKey.INDEX,
+  position: 0,
+  fields: [
+    {
+      universalIdentifier: 'f926bdb7-6af7-4683-9a09-adbca56c29f0',
+      fieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
+      position: 0,
+      isVisible: true,
+      size: 200,
+    },
+  ],
+});
+```
+
+## Key points
+
+- `objectUniversalIdentifier` specifies which object this view applies to. It can be a custom object you defined or a standard Twenty object.
+- `key` determines the view type — `ViewKey.INDEX` is the main list view for the object.
+- `fields` controls which columns appear and in what order. Each field references a `fieldMetadataUniversalIdentifier`.
+- You can also declare `filters`, `filterGroups`, `groups`, and `fieldGroups` for advanced configurations.
+- `position` controls ordering when multiple views exist for the same object.
+
+## How views show up in the UI
+
+A view by itself isn't reachable from the sidebar. To make it appear there, pair it with a [navigation menu item](/developers/extend/apps/layout/navigation-menu-items) of type `VIEW` that points at the view's `universalIdentifier`. That's the canonical pattern: every custom object typically ships a default view + a sidebar entry that opens it.
@@ -1,562 +0,0 @@
---
-title: Logic Functions
-description: Define server-side TypeScript functions with HTTP, cron, and database event triggers.
-icon: "bolt"
---
-
-Logic functions are server-side TypeScript functions that run on the Twenty platform. They can be triggered by HTTP requests, cron schedules, or database events — and can also be exposed as tools for AI agents.
-
-<AccordionGroup>
-<Accordion title="defineLogicFunction" description="Define logic functions and their triggers">
-
-Each function file uses `defineLogicFunction()` to export a configuration with a handler and optional triggers.
-
-```ts src/logic-functions/createPostCard.logic-function.ts
-import { defineLogicFunction } from 'twenty-sdk/define';
-import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk/define';
-import { CoreApiClient, type Person } from 'twenty-client-sdk/core';
-
-const handler = async (params: RoutePayload) => {
-  const client = new CoreApiClient();
-  const name = 'name' in params.queryStringParameters
-    ? params.queryStringParameters.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world'
-    : 'Hello world';
-
-  const result = await client.mutation({
-    createPostCard: {
-      __args: { data: { name } },
-      id: true,
-      name: true,
-    },
-  });
-  return result;
-};
-
-export default defineLogicFunction({
-  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
-  name: 'create-new-post-card',
-  timeoutSeconds: 2,
-  handler,
-  httpRouteTriggerSettings: {
-    path: '/post-card/create',
-    httpMethod: 'GET',
-    isAuthRequired: true,
-  },
-  /*databaseEventTriggerSettings: {
-    eventName: 'people.created',
-  },*/
-  /*cronTriggerSettings: {
-    pattern: '0 0 1 1 *',
-  },*/
-});
-```
-
-Available trigger types:
- **httpRoute**: Exposes your function on an HTTP path and method **under the `/s/` endpoint**:
-> e.g. `path: '/post-card/create'` is callable at `https://your-twenty-server.com/s/post-card/create`
- **cron**: Runs your function on a schedule using a CRON expression.
- **databaseEvent**: Runs on workspace object lifecycle events. When the event operation is `updated`, specific fields to listen to can be specified in the `updatedFields` array. If left undefined or empty, any update will trigger the function.
-> e.g. `person.updated`, `*.created`, `company.*`
-
-<Note>
-You can also manually execute a function using the CLI:
-
-```bash filename="Terminal"
-yarn twenty exec -n create-new-post-card -p '{"key": "value"}'
-```
-
-```bash filename="Terminal"
-yarn twenty exec -y e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
-```
-
-You can watch logs with:
-
-```bash filename="Terminal"
-yarn twenty logs
-```
-</Note>
-
-#### Route trigger payload
-
-When a route trigger invokes your logic function, it receives a `RoutePayload` object that follows the
-[AWS HTTP API v2 format](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html).
-Import the `RoutePayload` type from `twenty-sdk`:
-
-```ts
-import { defineLogicFunction, type RoutePayload } from 'twenty-sdk/define';
-
-const handler = async (event: RoutePayload) => {
-  const { headers, queryStringParameters, pathParameters, body } = event;
-  const { method, path } = event.requestContext.http;
-
-  return { message: 'Success' };
-};
-```
-
-The `RoutePayload` type has the following structure:
-
-  | Property | Type | Description | Example |
-  |----------|------|-------------|---------|
-  | `headers` | `Record<string, string \| undefined>` | HTTP headers (only those listed in `forwardedRequestHeaders`) | see section below |
-  | `queryStringParameters` | `Record<string, string \| undefined>` | Query string parameters (multiple values joined with commas)  | `/users?ids=1&ids=2&ids=3&name=Alice` -> `{ ids: '1,2,3', name: 'Alice' }`|
-  | `pathParameters` | `Record<string, string \| undefined>` | Path parameters extracted from the route pattern | `/users/:id`, `/users/123` -> `{ id: '123' }` |
-  | `body` | `object \| null` | Parsed request body (JSON) | `{ id: 1 }` -> `{ id: 1 }` |
-  | `rawBody` | `string \| undefined` | Original UTF-8 request body, before JSON parsing. Useful for verifying HMAC-style webhook signatures (e.g. GitHub's `X-Hub-Signature-256`, Stripe). `undefined` when the runtime did not preserve it. | |
-  | `isBase64Encoded` | `boolean` | Whether the body is base64 encoded | |
-  | `requestContext.http.method` | `string` | HTTP method (GET, POST, PUT, PATCH, DELETE) | |
-  | `requestContext.http.path` | `string` | Raw request path | |
-
-
-#### forwardedRequestHeaders
-
-By default, HTTP headers from incoming requests are **not** passed to your logic function for security reasons.
-To access specific headers, list them in the `forwardedRequestHeaders` array:
-
-```ts
-export default defineLogicFunction({
-  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
-  name: 'webhook-handler',
-  handler,
-  httpRouteTriggerSettings: {
-    path: '/webhook',
-    httpMethod: 'POST',
-    isAuthRequired: false,
-    forwardedRequestHeaders: ['x-webhook-signature', 'content-type'],
-  },
-});
-```
-
-In your handler, access the forwarded headers like this:
-
-```ts
-const handler = async (event: RoutePayload) => {
-  const signature = event.headers['x-webhook-signature'];
-  const contentType = event.headers['content-type'];
-
-  // Validate webhook signature...
-  return { received: true };
-};
-```
-
-<Note>
-Header names are normalized to lowercase. Access them using lowercase keys (e.g., `event.headers['content-type']`).
-</Note>
-
-#### Exposing a function as a tool
-
-Logic functions can be exposed as **tools** for AI agents and workflows. When marked as a tool, a function becomes discoverable by Twenty's AI features and can be used in workflow automations.
-
-To mark a logic function as a tool, set `isTool: true`:
-
-```ts src/logic-functions/enrich-company.logic-function.ts
-import { defineLogicFunction } from 'twenty-sdk/define';
-import { CoreApiClient } from 'twenty-client-sdk/core';
-
-const handler = async (params: { companyName: string; domain?: string }) => {
-  const client = new CoreApiClient();
-
-  const result = await client.mutation({
-    createTask: {
-      __args: {
-        data: {
-          title: `Enrich data for ${params.companyName}`,
-          body: `Domain: ${params.domain ?? 'unknown'}`,
-        },
-      },
-      id: true,
-    },
-  });
-
-  return { taskId: result.createTask.id };
-};
-
-export default defineLogicFunction({
-  universalIdentifier: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
-  name: 'enrich-company',
-  description: 'Enrich a company record with external data',
-  timeoutSeconds: 10,
-  handler,
-  isTool: true,
-});
-```
-
-Key points:
-
- You can combine `isTool` with triggers — a function can be both a tool (callable by AI agents) and triggered by events at the same time.
- **`toolInputSchema`** (optional): A JSON Schema object describing the parameters your function accepts. The schema is computed automatically from source code static analysis, but you can set it explicitly:
-
-```ts
-export default defineLogicFunction({
-  ...,
-  toolInputSchema: {
-    type: 'object',
-    properties: {
-      companyName: {
-        type: 'string',
-        description: 'The name of the company to enrich',
-      },
-      domain: {
-        type: 'string',
-        description: 'The company website domain (optional)',
-      },
-    },
-    required: ['companyName'],
-  },
-});
-```
-
-<Note>
-**Write a good `description`.** AI agents rely on the function's `description` field to decide when to use the tool. Be specific about what the tool does and when it should be called.
-</Note>
-
-</Accordion>
-<Accordion title="definePostInstallLogicFunction" description="Define a post-install logic function (one per app)">
-
-A post-install function is a logic function that runs automatically once your app has finished installing on a workspace. The server executes it **after** the app's metadata has been synchronized and the SDK client has been generated, so the workspace is fully ready to use and the new schema is in place. Typical use cases include seeding default data, creating initial records, configuring workspace settings, or provisioning resources on third-party services.
-
-```ts src/logic-functions/post-install.ts
-import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
-
-const handler = async (payload: InstallPayload): Promise<void> => {
-  console.log('Post install logic function executed successfully!', payload.previousVersion);
-};
-
-export default definePostInstallLogicFunction({
-  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
-  name: 'post-install',
-  description: 'Runs after installation to set up the application.',
-  timeoutSeconds: 300,
-  shouldRunOnVersionUpgrade: false,
-  shouldRunSynchronously: false,
-  handler,
-});
-```
-
-You can also manually execute the post-install function at any time using the CLI:
-
-```bash filename="Terminal"
-yarn twenty exec --postInstall
-```
-
-Key points:
- Post-install functions use `definePostInstallLogicFunction()` — a specialized variant that omits trigger settings (`cronTriggerSettings`, `databaseEventTriggerSettings`, `httpRouteTriggerSettings`, `isTool`).
- The handler receives an `InstallPayload` with `{ previousVersion?: string; newVersion: string }` — `newVersion` is the version being installed, and `previousVersion` is the version that was previously installed (or `undefined` on a fresh install). Use these values to distinguish fresh installs from upgrades and to run version-specific migration logic.
- **When the hook runs**: on fresh installs only, by default. Pass `shouldRunOnVersionUpgrade: true` if you also want it to run when the app is upgraded from a previous version. When omitted, the flag defaults to `false` and upgrades skip the hook.
- **Execution model — async by default, sync opt-in**: the `shouldRunSynchronously` flag controls *how* post-install is executed.
-  - `shouldRunSynchronously: false` *(default)* — the hook is **enqueued on the message queue** with `retryLimit: 3` and runs asynchronously in a worker. The install response returns as soon as the job is enqueued, so a slow or failing handler does not block the caller. The worker will retry up to three times. **Use this for long-running jobs** — seeding large datasets, calling slow third-party APIs, provisioning external resources, anything that might exceed a reasonable HTTP response window.
-  - `shouldRunSynchronously: true` — the hook is executed **inline during the install flow** (same executor as pre-install). The install request blocks until the handler finishes, and if it throws, the install caller receives a `POST_INSTALL_ERROR`. No automatic retries. **Use this for fast, must-complete-before-response work** — for example, emitting a validation error to the user, or quick setup that the client will rely on immediately after the install call returns. Keep in mind the metadata migration has already been applied by the time post-install runs, so a sync-mode failure does **not** roll back the schema changes — it only surfaces the error.
- Make sure your handler is idempotent. In async mode the queue may retry up to three times; in either mode the hook may run again on upgrades when `shouldRunOnVersionUpgrade: true`.
- The environment variables `APPLICATION_ID`, `APP_ACCESS_TOKEN`, and `API_URL` are available inside the handler (same as any other logic function), so you can call the Twenty API with an application access token scoped to your app.
- Only one post-install function is allowed per application. The manifest build will error if more than one is detected.
- The function's `universalIdentifier`, `shouldRunOnVersionUpgrade`, and `shouldRunSynchronously` are automatically attached to the application manifest under the `postInstallLogicFunction` field during the build — you do not need to reference them in `defineApplication()`.
- The default timeout is set to 300 seconds (5 minutes) to allow for longer setup tasks like data seeding.
- **Not executed in dev mode**: when an app is registered locally (via `yarn twenty dev`), the server skips the install flow entirely and syncs files directly through the CLI watcher — so post-install never runs in dev mode, regardless of `shouldRunSynchronously`. Use `yarn twenty exec --postInstall` to trigger it manually against a running workspace.
-
-</Accordion>
-<Accordion title="definePreInstallLogicFunction" description="Define a pre-install logic function (one per app)">
-
-A pre-install function is a logic function that runs automatically during installation, **before the workspace metadata migration is applied**. It shares the same payload shape as post-install (`InstallPayload`), but it is positioned earlier in the install flow so it can prepare state that the upcoming migration depends on — typical uses include backing up data, validating compatibility with the new schema, or archiving records that are about to be restructured or dropped.
-
-```ts src/logic-functions/pre-install.ts
-import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
-
-const handler = async (payload: InstallPayload): Promise<void> => {
-  console.log('Pre install logic function executed successfully!', payload.previousVersion);
-};
-
-export default definePreInstallLogicFunction({
-  universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
-  name: 'pre-install',
-  description: 'Runs before installation to prepare the application.',
-  timeoutSeconds: 300,
-  shouldRunOnVersionUpgrade: true,
-  handler,
-});
-```
-
-You can also manually execute the pre-install function at any time using the CLI:
-
-```bash filename="Terminal"
-yarn twenty exec --preInstall
-```
-
-Key points:
- Pre-install functions use `definePreInstallLogicFunction()` — same specialized config as post-install, just attached to a different lifecycle slot.
- Both pre- and post-install handlers receive the same `InstallPayload` type: `{ previousVersion?: string; newVersion: string }`. Import it once and reuse it for both hooks.
- **When the hook runs**: positioned just before the workspace metadata migration (`synchronizeFromManifest`). Before executing, the server runs a purely additive "pared-down sync" that registers the **new** version's pre-install function in the workspace metadata — nothing else is touched — and then executes it. Because this sync is additive-only, the previous version's objects, fields, and data are still intact when your handler runs: you can safely read and back up pre-migration state.
- **Execution model**: pre-install is executed **synchronously** and **blocks the install**. If the handler throws, the install is aborted before any schema changes are applied — the workspace stays on the previous version in a consistent state. This is intentional: pre-install is your last chance to refuse a risky upgrade.
- As with post-install, only one pre-install function is allowed per application. It is attached to the application manifest under `preInstallLogicFunction` automatically during the build.
- **Not executed in dev mode**: same as post-install — the install flow is skipped entirely for locally-registered apps, so pre-install never runs under `yarn twenty dev`. Use `yarn twenty exec --preInstall` to trigger it manually.
-
-</Accordion>
-<Accordion title="Pre-install vs post-install: when to use which" description="Choosing the right install hook">
-
-Both hooks are part of the same install flow and receive the same `InstallPayload`. The difference is **when** they run relative to the workspace metadata migration, and that changes what data they can safely touch.
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ install flow                                                │
-│                                                             │
-│   upload package → [pre-install] → metadata migration →     │
-│   generate SDK → [post-install]                             │
-│                                                             │
-│                  old schema visible    new schema visible   │
-└─────────────────────────────────────────────────────────────┘
-```
-
-Pre-install is always **synchronous** (it blocks the install and can abort it). Post-install is **asynchronous by default** — enqueued on a worker with automatic retries — but can opt into synchronous execution with `shouldRunSynchronously: true`. See the `definePostInstallLogicFunction` accordion above for when to use each mode.
-
-**Use `post-install` for anything that needs the new schema to exist.** This is the common case:
-
- Seeding default data (creating initial records, default views, demo content) against newly-added objects and fields.
- Registering webhooks with third-party services now that the app has its credentials.
- Calling your own API to finish setup that depends on the synchronized metadata.
- Idempotent "ensure this exists" logic that should reconcile state on every upgrade — combine with `shouldRunOnVersionUpgrade: true`.
-
-Example — seed a default `PostCard` record after install:
-
-```ts src/logic-functions/post-install.ts
-import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
-import { createClient } from './generated/client';
-
-const handler = async ({ previousVersion }: InstallPayload): Promise<void> => {
-  if (previousVersion) return; // fresh installs only
-
-  const client = createClient();
-  await client.postCard.create({
-    data: { title: 'Welcome to Postcard', content: 'Your first card!' },
-  });
-};
-
-export default definePostInstallLogicFunction({
-  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
-  name: 'post-install',
-  description: 'Seeds a welcome post card after install.',
-  timeoutSeconds: 300,
-  shouldRunOnVersionUpgrade: false,
-  handler,
-});
-```
-
-**Use `pre-install` when a migration would otherwise destroy or corrupt existing data.** Because pre-install runs against the *previous* schema and its failure rolls back the upgrade, it is the right place for anything risky:
-
- **Backing up data that is about to be dropped or restructured** — e.g. you are removing a field in v2 and need to copy its values into another field or export them to storage before the migration runs.
- **Archiving records that a new constraint would invalidate** — e.g. a field is becoming `NOT NULL` and you need to delete or fix rows with null values first.
- **Validating compatibility and refusing the upgrade if the current data cannot be migrated cleanly** — throw from the handler and the install aborts with no changes applied. This is safer than discovering the incompatibility mid-migration.
- **Renaming or rekeying data** ahead of a schema change that would lose the association.
-
-Example — archive records before a destructive migration:
-
-```ts src/logic-functions/pre-install.ts
-import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
-import { createClient } from './generated/client';
-
-const handler = async ({ previousVersion, newVersion }: InstallPayload): Promise<void> => {
-  // Only the 1.x → 2.x upgrade drops the legacy `notes` field.
-  if (!previousVersion?.startsWith('1.') || !newVersion.startsWith('2.')) {
-    return;
-  }
-
-  const client = createClient();
-  const legacyRecords = await client.postCard.findMany({
-    where: { notes: { isNotNull: true } },
-  });
-
-  if (legacyRecords.length === 0) return;
-
-  // Copy legacy `notes` into the new `description` field before the migration
-  // drops the `notes` column. If this fails, the upgrade is aborted and the
-  // workspace stays on v1 with all data intact.
-  await Promise.all(
-    legacyRecords.map((record) =>
-      client.postCard.update({
-        where: { id: record.id },
-        data: { description: record.notes },
-      }),
-    ),
-  );
-};
-
-export default definePreInstallLogicFunction({
-  universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
-  name: 'pre-install',
-  description: 'Backs up legacy notes into description before the v2 migration.',
-  timeoutSeconds: 300,
-  shouldRunOnVersionUpgrade: true,
-  handler,
-});
-```
-
-**Rule of thumb:**
-
-| You want to... | Use |
-|---|---|
-| Seed default data, configure the workspace, register external resources | `post-install` |
-| Run long-running seeding or third-party calls that shouldn't block the install response | `post-install` (default — `shouldRunSynchronously: false`, with worker retries) |
-| Run fast setup that the caller will rely on immediately after the install call returns | `post-install` with `shouldRunSynchronously: true` |
-| Read or back up data that the upcoming migration would lose | `pre-install` |
-| Reject an upgrade that would corrupt existing data | `pre-install` (throw from the handler) |
-| Run reconciliation on every upgrade | `post-install` with `shouldRunOnVersionUpgrade: true` |
-| Do one-off setup on the first install only | `post-install` with `shouldRunOnVersionUpgrade: false` (default) |
-
-<Note>
-If in doubt, default to **post-install**. Only reach for pre-install when the migration itself is destructive and you need to intercept the previous state before it is gone.
-</Note>
-
-</Accordion>
-</AccordionGroup>
-
-## Typed API clients (twenty-client-sdk)
-
-The `twenty-client-sdk` package provides two typed GraphQL clients for interacting with the Twenty API from your logic functions and front components.
-
-| 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 |
-
-<AccordionGroup>
-<Accordion title="CoreApiClient" description="Query and mutate workspace data (records, objects)">
-
-`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 is fully typed to match your objects and fields.
-
-```ts
-import { CoreApiClient } from 'twenty-client-sdk/core';
-
-const client = new CoreApiClient();
-
-// Query records
-const { companies } = await client.query({
-  companies: {
-    edges: {
-      node: {
-        id: true,
-        name: true,
-        domainName: {
-          primaryLinkLabel: true,
-          primaryLinkUrl: true,
-        },
-      },
-    },
-  },
-});
-
-// Create a record
-const { createCompany } = await client.mutation({
-  createCompany: {
-    __args: {
-      data: {
-        name: 'Acme Corp',
-      },
-    },
-    id: true,
-    name: true,
-  },
-});
-```
-
-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.
-
-<Note>
-**CoreApiClient is generated at dev/build time.** If you 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 and generates a typed client using `@genql/cli`.
-</Note>
-
-#### Using CoreSchema for type annotations
-
-`CoreSchema` provides TypeScript types matching your workspace objects — useful for typing component state or function parameters:
-
-```ts
-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);
-```
-
-</Accordion>
-<Accordion title="MetadataApiClient" description="Workspace config, applications, and file uploads">
-
-`MetadataApiClient` ships pre-built with the SDK (no generation required). It queries the `/metadata` endpoint for workspace configuration, applications, and file uploads.
-
-```ts
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
-
-const metadataClient = new MetadataApiClient();
-
-// List first 10 objects in the workspace
-const { objects } = await metadataClient.query({
-  objects: {
-    edges: {
-      node: {
-        id: true,
-        nameSingular: true,
-        namePlural: true,
-        labelSingular: true,
-        isCustom: true,
-      },
-    },
-    __args: {
-      filter: {},
-      paging: { first: 10 },
-    },
-  },
-});
-```
-
-#### Uploading files
-
-`MetadataApiClient` includes an `uploadFile` method for attaching files to file-type fields:
-
-```ts
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
-import * as fs from 'fs';
-
-const metadataClient = new MetadataApiClient();
-
-const fileBuffer = fs.readFileSync('./invoice.pdf');
-
-const uploadedFile = await metadataClient.uploadFile(
-  fileBuffer,                                         // file contents as a Buffer
-  'invoice.pdf',                                      // filename
-  'application/pdf',                                  // MIME type
-  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
-);
-
-console.log(uploadedFile);
-// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `fileBuffer` | `Buffer` | The raw file contents |
-| `filename` | `string` | The name of the file (used for storage and display) |
-| `contentType` | `string` | MIME type (defaults to `application/octet-stream` if omitted) |
-| `fieldMetadataUniversalIdentifier` | `string` | The `universalIdentifier` of the file-type field on your object |
-
-Key points:
- 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.
-
-</Accordion>
-</AccordionGroup>
-
-
-<Note>
-  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_APP_ACCESS_TOKEN` — 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`.
-</Note>
@@ -52,7 +52,6 @@ export default defineApplication({
  universalIdentifier: '...',
  displayName: 'Linear',
  description: 'Connect Linear to Twenty.',
-  defaultRoleUniversalIdentifier: '...',
  // OAuth client credentials live on the app registration (one OAuth app per
  // Twenty server, configured by the admin) — not per-workspace. Declare them
  // as serverVariables so the admin can fill them in once for all installs.
@@ -0,0 +1,376 @@
+---
+title: Logic Functions
+description: Define server-side TypeScript functions with HTTP, cron, and database event triggers.
+icon: "bolt"
+---
+
+Logic functions are server-side TypeScript functions that run on the Twenty platform. They can be triggered by HTTP requests, cron schedules, or database events — and can also be exposed as tools for AI agents.
+
+<AccordionGroup>
+<Accordion title="defineLogicFunction" description="Define logic functions and their triggers">
+
+Each function file uses `defineLogicFunction()` to export a configuration with a handler and optional triggers.
+
+```ts src/logic-functions/createPostCard.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk/define';
+import { CoreApiClient, type Person } from 'twenty-client-sdk/core';
+
+const handler = async (params: RoutePayload) => {
+  const client = new CoreApiClient();
+  const body = (params.body ?? {}) as { name?: string };
+  const name = body.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world';
+
+  const result = await client.mutation({
+    createPostCard: {
+      __args: { data: { name } },
+      id: true,
+      name: true,
+    },
+  });
+  return result;
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
+  name: 'create-new-post-card',
+  timeoutSeconds: 2,
+  handler,
+  httpRouteTriggerSettings: {
+    path: '/post-card/create',
+    httpMethod: 'POST',
+    isAuthRequired: true,
+  },
+  /*databaseEventTriggerSettings: {
+    eventName: 'people.created',
+  },*/
+  /*cronTriggerSettings: {
+    pattern: '0 0 1 1 *',
+  },*/
+});
+```
+
+Available trigger types:
+- **httpRoute**: Exposes your function on an HTTP path and method **under the `/s/` endpoint**:
+> e.g. `path: '/post-card/create'` is callable at `https://your-twenty-server.com/s/post-card/create`
+- **cron**: Runs your function on a schedule using a CRON expression.
+- **databaseEvent**: Runs on workspace object lifecycle events. When the event operation is `updated`, specific fields to listen to can be specified in the `updatedFields` array. If left undefined or empty, any update will trigger the function.
+> e.g. `person.updated`, `*.created`, `company.*`
+
+<Note>
+You can also manually execute a function using the CLI:
+
+```bash filename="Terminal"
+yarn twenty exec -n create-new-post-card -p '{"key": "value"}'
+```
+
+```bash filename="Terminal"
+yarn twenty exec -y e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
+```
+
+You can watch logs with:
+
+```bash filename="Terminal"
+yarn twenty logs
+```
+</Note>
+
+#### Route trigger payload
+
+When a route trigger invokes your logic function, it receives a `RoutePayload` object that follows the
+[AWS HTTP API v2 format](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html).
+Import the `RoutePayload` type from `twenty-sdk`:
+
+```ts
+import { defineLogicFunction, type RoutePayload } from 'twenty-sdk/define';
+
+const handler = async (event: RoutePayload) => {
+  const { headers, queryStringParameters, pathParameters, body } = event;
+  const { method, path } = event.requestContext.http;
+
+  return { message: 'Success' };
+};
+```
+
+The `RoutePayload` type has the following structure:
+
+  | Property | Type | Description | Example |
+  |----------|------|-------------|---------|
+  | `headers` | `Record<string, string \| undefined>` | HTTP headers (only those listed in `forwardedRequestHeaders`) | see section below |
+  | `queryStringParameters` | `Record<string, string \| undefined>` | Query string parameters (multiple values joined with commas)  | `/users?ids=1&ids=2&ids=3&name=Alice` -> `{ ids: '1,2,3', name: 'Alice' }`|
+  | `pathParameters` | `Record<string, string \| undefined>` | Path parameters extracted from the route pattern | `/users/:id`, `/users/123` -> `{ id: '123' }` |
+  | `body` | `object \| null` | Parsed request body (JSON) | `{ id: 1 }` -> `{ id: 1 }` |
+  | `rawBody` | `string \| undefined` | Original UTF-8 request body, before JSON parsing. Useful for verifying HMAC-style webhook signatures (e.g. GitHub's `X-Hub-Signature-256`, Stripe). `undefined` when the runtime did not preserve it. | |
+  | `isBase64Encoded` | `boolean` | Whether the body is base64 encoded | |
+  | `requestContext.http.method` | `string` | HTTP method (GET, POST, PUT, PATCH, DELETE) | |
+  | `requestContext.http.path` | `string` | Raw request path | |
+
+
+#### forwardedRequestHeaders
+
+By default, HTTP headers from incoming requests are **not** passed to your logic function for security reasons.
+To access specific headers, list them in the `forwardedRequestHeaders` array:
+
+```ts
+export default defineLogicFunction({
+  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
+  name: 'webhook-handler',
+  handler,
+  httpRouteTriggerSettings: {
+    path: '/webhook',
+    httpMethod: 'POST',
+    isAuthRequired: false,
+    forwardedRequestHeaders: ['x-webhook-signature', 'content-type'],
+  },
+});
+```
+
+In your handler, access the forwarded headers like this:
+
+```ts
+const handler = async (event: RoutePayload) => {
+  const signature = event.headers['x-webhook-signature'];
+  const contentType = event.headers['content-type'];
+
+  // Validate webhook signature...
+  return { received: true };
+};
+```
+
+<Note>
+Header names are normalized to lowercase. Access them using lowercase keys (e.g., `event.headers['content-type']`).
+</Note>
+
+#### Exposing a function as an AI tool or workflow action
+
+Logic functions can be exposed on two surfaces, each with its own trigger:
+
+- **`toolTriggerSettings`** — makes the function discoverable by Twenty's AI features (chat, MCP, function calling). Uses standard JSON Schema, the format LLMs natively understand.
+- **`workflowActionTriggerSettings`** — makes the function appear as a step in the visual workflow builder. Uses Twenty's rich `InputSchema` so the builder can render proper field editors, variable pickers, and labels.
+
+A function can opt into one, the other, or both. They sit alongside `cronTriggerSettings`, `databaseEventTriggerSettings`, and `httpRouteTriggerSettings` — same pattern, same shape.
+
+```ts src/logic-functions/enrich-company.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const handler = async (params: { companyName: string; domain?: string }) => {
+  const client = new CoreApiClient();
+
+  const result = await client.mutation({
+    createTask: {
+      __args: {
+        data: {
+          title: `Enrich data for ${params.companyName}`,
+          body: `Domain: ${params.domain ?? 'unknown'}`,
+        },
+      },
+      id: true,
+    },
+  });
+
+  return { taskId: result.createTask.id };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
+  name: 'enrich-company',
+  description: 'Enrich a company record with external data',
+  timeoutSeconds: 10,
+  handler,
+  toolTriggerSettings: {},
+});
+```
+
+Key points:
+
+- A function can mix surfaces — declare both `toolTriggerSettings` and `workflowActionTriggerSettings` to expose it in chat AND in the workflow builder.
+- `toolTriggerSettings.inputSchema` and `workflowActionTriggerSettings.inputSchema` are both optional. When omitted, the manifest builder infers them from the handler source code (JSON Schema for the AI tool, Twenty's `InputSchema` for the workflow action). Provide one explicitly when you want richer typing — for example, with `FieldMetadataType`-aware fields like `CURRENCY` or `RELATION` for the workflow builder, or with `description` fields the AI agent can read:
+
+```ts
+export default defineLogicFunction({
+  ...,
+  toolTriggerSettings: {
+    inputSchema: {
+      type: 'object',
+      properties: {
+        companyName: {
+          type: 'string',
+          description: 'The name of the company to enrich',
+        },
+        domain: {
+          type: 'string',
+          description: 'The company website domain (optional)',
+        },
+      },
+      required: ['companyName'],
+    },
+  },
+});
+```
+
+<Note>
+**Write a good `description`.** AI agents rely on the function's `description` field to decide when to use the tool. Be specific about what the tool does and when it should be called.
+</Note>
+
+</Accordion>
+</AccordionGroup>
+
+<Note>
+**Install hooks** — pre-install and post-install handlers — share this runtime but are declared with their own define functions and don't take trigger settings. See [Install Hooks](/developers/extend/apps/config/install-hooks) for `definePreInstallLogicFunction` and `definePostInstallLogicFunction`.
+</Note>
+
+## Typed API clients (twenty-client-sdk)
+
+The `twenty-client-sdk` package provides two typed GraphQL clients for interacting with the Twenty API from your logic functions and front components.
+
+| 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 |
+
+<AccordionGroup>
+<Accordion title="CoreApiClient" description="Query and mutate workspace data (records, objects)">
+
+`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 is fully typed to match your objects and fields.
+
+```ts
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const client = new CoreApiClient();
+
+// Query records
+const { companies } = await client.query({
+  companies: {
+    edges: {
+      node: {
+        id: true,
+        name: true,
+        domainName: {
+          primaryLinkLabel: true,
+          primaryLinkUrl: true,
+        },
+      },
+    },
+  },
+});
+
+// Create a record
+const { createCompany } = await client.mutation({
+  createCompany: {
+    __args: {
+      data: {
+        name: 'Acme Corp',
+      },
+    },
+    id: true,
+    name: true,
+  },
+});
+```
+
+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.
+
+<Note>
+**CoreApiClient is generated at dev/build time.** If you 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 and generates a typed client using `@genql/cli`.
+</Note>
+
+#### Using CoreSchema for type annotations
+
+`CoreSchema` provides TypeScript types matching your workspace objects — useful for typing component state or function parameters:
+
+```ts
+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);
+```
+
+</Accordion>
+<Accordion title="MetadataApiClient" description="Workspace config, applications, and file uploads">
+
+`MetadataApiClient` ships pre-built with the SDK (no generation required). It queries the `/metadata` endpoint for workspace configuration, applications, and file uploads.
+
+```ts
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+
+const metadataClient = new MetadataApiClient();
+
+// List first 10 objects in the workspace
+const { objects } = await metadataClient.query({
+  objects: {
+    edges: {
+      node: {
+        id: true,
+        nameSingular: true,
+        namePlural: true,
+        labelSingular: true,
+        isCustom: true,
+      },
+    },
+    __args: {
+      filter: {},
+      paging: { first: 10 },
+    },
+  },
+});
+```
+
+#### Uploading files
+
+`MetadataApiClient` includes an `uploadFile` method for attaching files to file-type fields:
+
+```ts
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import * as fs from 'fs';
+
+const metadataClient = new MetadataApiClient();
+
+const fileBuffer = fs.readFileSync('./invoice.pdf');
+
+const uploadedFile = await metadataClient.uploadFile(
+  fileBuffer,                                         // file contents as a Buffer
+  'invoice.pdf',                                      // filename
+  'application/pdf',                                  // MIME type
+  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
+);
+
+console.log(uploadedFile);
+// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fileBuffer` | `Buffer` | The raw file contents |
+| `filename` | `string` | The name of the file (used for storage and display) |
+| `contentType` | `string` | MIME type (defaults to `application/octet-stream` if omitted) |
+| `fieldMetadataUniversalIdentifier` | `string` | The `universalIdentifier` of the file-type field on your object |
+
+Key points:
+- 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.
+
+</Accordion>
+</AccordionGroup>
+
+
+<Note>
+  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_APP_ACCESS_TOKEN` — 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 declared with `defineApplicationRole()` (or referenced via `defaultRoleUniversalIdentifier` in `application-config.ts`).
+</Note>
@@ -0,0 +1,55 @@
+---
+title: Overview
+description: Server-side TypeScript that runs inside Twenty — triggered by HTTP routes, cron schedules, database events, AI tools, or workflow actions.
+icon: "bolt"
+---
+
+A Twenty app's **logic layer** is the code that *runs* — server-side TypeScript handlers reacting to HTTP requests, cron schedules, and record changes; AI skills and agents that live inside the workspace; and OAuth connections that let your functions act on a user's behalf in third-party services.
+
+```text
+            ┌─ HTTP route      ──┐
+            │  Cron schedule     │
+            │  Database event    │      ┌────────────────────┐
+  triggers ─┤  AI tool call      ├─────▶│ Logic function     │
+            │  Workflow action   │      │ (your handler)     │
+            │  Manual exec       │      └────────────────────┘
+            └────────────────────┘                │
+                                                  ▼
+                                  ┌────────────────────────────┐
+                                  │ Twenty API (records)       │
+                                  │ Third-party API            │
+                                  │   (via Connection token)   │
+                                  └────────────────────────────┘
+```
+
+## In this section
+
+<CardGroup cols={2}>
+  <Card title="Logic Functions" icon="bolt" href="/developers/extend/apps/logic/logic-functions">
+    The core building block — trigger types, payloads, and the typed API client.
+  </Card>
+  <Card title="Skills & Agents" icon="robot" href="/developers/extend/apps/logic/skills-and-agents">
+    Reusable AI agent instructions and assistants with custom system prompts.
+  </Card>
+  <Card title="Connections" icon="plug" href="/developers/extend/apps/logic/connections">
+    OAuth credentials your app holds for third-party services — Linear, GitHub, Slack, and more.
+  </Card>
+</CardGroup>
+
+## Trigger types at a glance
+
+A logic function picks one or more triggers — every entry below is a separate field on `defineLogicFunction()`:
+
+| Trigger | When it runs | Setting |
+|---------|--------------|---------|
+| **HTTP route** | A request hits your `/s/<path>` endpoint | `httpRouteTriggerSettings` |
+| **Cron** | A CRON expression matches | `cronTriggerSettings` |
+| **Database event** | A workspace record is created, updated, or deleted | `databaseEventTriggerSettings` |
+| **AI tool** | A Twenty AI feature decides to call your function | `toolTriggerSettings` |
+| **Workflow action** | A workflow step invokes your function | `workflowActionTriggerSettings` |
+
+Functions run sandboxed in isolated Node.js processes and access the workspace through a typed API client scoped to the role declared on [`defineApplication()`](/developers/extend/apps/config/application).
+
+<Note>
+**Install-time hooks** — code that runs before or after the install — share this runtime but use their own define functions and live under [Config → Install Hooks](/developers/extend/apps/config/install-hooks).
+</Note>
@@ -0,0 +1,78 @@
+---
+title: CLI
+description: yarn twenty commands for executing functions, streaming logs, managing app installations, and switching remotes.
+icon: "terminal"
+---
+
+Beyond `dev`, `build`, `add`, and `typecheck`, the `yarn twenty` CLI provides commands for executing functions, viewing logs, and managing app installations.
+
+## Executing functions (`yarn twenty exec`)
+
+Run a logic function manually without triggering it via HTTP, cron, or database event:
+
+```bash filename="Terminal"
+# Execute by function name
+yarn twenty exec -n create-new-post-card
+
+# Execute by universalIdentifier
+yarn twenty exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
+
+# Pass a JSON payload
+yarn twenty exec -n create-new-post-card -p '{"name": "Hello"}'
+
+# Execute the post-install function
+yarn twenty exec --postInstall
+```
+
+## Viewing function logs (`yarn twenty logs`)
+
+Stream execution logs for your app's logic functions:
+
+```bash filename="Terminal"
+# Stream all function logs
+yarn twenty logs
+
+# Filter by function name
+yarn twenty logs -n create-new-post-card
+
+# Filter by universalIdentifier
+yarn twenty logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
+```
+
+<Note>
+This is different from `yarn twenty server logs`, which shows the Docker container logs. `yarn twenty logs` shows your app's function execution logs from the Twenty server.
+</Note>
+
+## Uninstalling an app (`yarn twenty uninstall`)
+
+Remove your app from the active workspace:
+
+```bash filename="Terminal"
+yarn twenty uninstall
+
+# Skip the confirmation prompt
+yarn twenty uninstall --yes
+```
+
+## Managing remotes
+
+A **remote** is a Twenty server that your app connects to. During setup, the scaffolder creates one for you automatically. You can add more remotes or switch between them at any time.
+
+```bash filename="Terminal"
+# Add a new remote (opens a browser for OAuth login)
+yarn twenty remote add
+
+# Connect to a local Twenty server (auto-detects port 2020 or 3000)
+yarn twenty remote add --local
+
+# Add a remote non-interactively (useful for CI)
+yarn twenty remote add --api-url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote
+
+# List all configured remotes
+yarn twenty remote list
+
+# Switch the active remote
+yarn twenty remote switch <name>
+```
+
+Your credentials are stored in `~/.twenty/config.json`.
@@ -0,0 +1,29 @@
+---
+title: Overview
+description: Build, test, and ship your app — CLI commands, integration tests, CI, and publishing to a server or to npm.
+icon: "rocket"
+---
+
+The **operations layer** is everything you do *to* your app rather than *with* it: invoking CLI commands, running integration tests against a real Twenty server, configuring CI, and shipping releases — either as a tarball deployed to a single server or as an npm package listed in the marketplace.
+
+```text
+   develop ─▶ test ─▶ build ─▶ deploy / publish
+   ───────    ────    ─────    ─────────────────
+   yarn       yarn    yarn     yarn twenty deploy   (tarball → one server)
+   twenty     test    twenty
+   dev                build    yarn twenty publish  (npm → marketplace)
+```
+
+## In this section
+
+<CardGroup cols={2}>
+  <Card title="CLI" icon="terminal" href="/developers/extend/apps/operations/cli">
+    `yarn twenty` reference — exec, logs, uninstall, remotes.
+  </Card>
+  <Card title="Testing" icon="flask" href="/developers/extend/apps/operations/testing">
+    Vitest setup, integration tests, type checking, CI workflow.
+  </Card>
+  <Card title="Publishing" icon="upload" href="/developers/extend/apps/operations/publishing">
+    Build, deploy a tarball, publish to npm, install.
+  </Card>
+</CardGroup>
@@ -6,7 +6,7 @@ description: Distribute your Twenty app to the marketplace or deploy it internal

 ## Overview

-Once your app is [built and tested locally](/developers/extend/apps/building), you have two paths for distributing it:
+Once your app is [built and tested locally](/developers/extend/apps/getting-started/concepts), you have two paths for distributing it:

 - **Deploy a tarball** — upload your app directly to a specific Twenty server for internal or private use.
 - **Publish to npm** — list your app in the Twenty marketplace for any workspace to discover and install.
@@ -77,6 +77,39 @@ Pre-release tags work as expected: bumping `1.0.0-rc.1` → `1.0.0-rc.2` is allo

 {/* TODO: add screenshot of the Upgrade button */}

+### Server version compatibility
+
+If your app uses a feature introduced in a specific Twenty server version (for example, OAuth providers added in v2.3.0), you should declare the minimum server version your app requires using the `engines.twenty` field in `package.json`:
+
+```json filename="package.json"
+{
+  "name": "twenty-my-app",
+  "version": "1.0.0",
+  "engines": {
+    "node": "^24.5.0",
+    "twenty": ">=2.3.0"
+  }
+}
+```
+
+The value is a standard [semver range](https://github.com/npm/node-semver#ranges). Common patterns:
+
+| Range | Meaning |
+|-------|---------|
+| `>=2.3.0` | Any server from 2.3.0 onward |
+| `>=2.3.0 <3.0.0` | 2.3.0 or later, but below the next major |
+| `^2.3.0` | Same as `>=2.3.0 <3.0.0` |
+
+**What happens at deploy and install time:**
+
+- If `engines.twenty` is set and the target server's version does not satisfy the range, the deploy (tarball upload) or install is rejected with a `SERVER_VERSION_INCOMPATIBLE` error and a message indicating both the required range and the actual server version.
+- If `engines.twenty` is **not set**, the app is accepted on any server version (backward-compatible with existing apps).
+- If the server has no `APP_VERSION` configured, the check is skipped.
+
+<Note>
+The server is the authoritative check — it validates `engines.twenty` on both tarball upload and workspace install. If you deploy a tarball out-of-band or install from the marketplace, the server still enforces compatibility.
+</Note>
+
 ## Automated CI/CD (scaffolded workflows)

 Apps generated with `create-twenty-app` ship with two GitHub Actions workflows out of the box, under `.github/workflows/`. They are ready to run as soon as you push the repo to GitHub — no extra setup is needed for CI, and CD only requires a single secret.
@@ -154,7 +187,6 @@ export default defineApplication({
  universalIdentifier: '...',
  displayName: 'My App',
  description: 'A great app',
-  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
  logoUrl: 'public/logo.png',
  screenshots: [
    'public/screenshot-1.png',
@@ -163,7 +195,15 @@ export default defineApplication({
 });
 ```

-See the [defineApplication accordion](/developers/extend/apps/building#defineentity-functions) in the Building Apps page for the full list of marketplace fields (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl`, etc.).
+See the [defineApplication accordion](/developers/extend/apps/config/application#marketplace-metadata) in the Building Apps page for the full list of marketplace fields (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl`, etc.).
+
+#### Recommended screenshot dimensions
+
+The marketplace renders `screenshots` in a fixed `8:5` container (for example, `1600×1000 px`).
+
+<Note>
+Screenshots of any aspect ratio are displayed in full and are never cropped, but anything significantly taller or narrower than `8:5` will show empty bands on the sides.
+</Note>

 ### Publish

@@ -184,9 +224,9 @@ The Twenty server syncs its marketplace catalog from the npm registry **every ho
 You can trigger the sync immediately instead of waiting:

 ```bash filename="Terminal"
-yarn twenty catalog-sync
+yarn twenty server catalog-sync
 # To target a specific remote:
-# yarn twenty catalog-sync --remote production
+# yarn twenty server catalog-sync --remote production
 ```

 The metadata shown in the marketplace comes from your `defineApplication()` config — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
@@ -1,64 +1,10 @@
 ---
-title: CLI & Testing
-description: CLI commands, testing setup, public assets, npm packages, remotes, and CI configuration.
-icon: "terminal"
+title: Testing
+description: Vitest setup, integration tests against a real Twenty server, type checking, and CI with GitHub Actions.
+icon: "flask"
 ---

-## Public assets (`public/` folder)
-
-The `public/` folder at the root of your app holds static files — images, icons, fonts, or any other assets your app needs at runtime. These files are automatically included in builds, synced during dev mode, and uploaded to the server.
-
-Files placed in `public/` are:
-
- **Publicly accessible** — once synced to the server, assets are served at a public URL. No authentication is needed to access them.
- **Available in front components** — use asset URLs to display images, icons, or any media inside your React components.
- **Available in logic functions** — reference asset URLs in emails, API responses, or any server-side logic.
- **Used for marketplace metadata** — the `logoUrl` and `screenshots` fields in `defineApplication()` reference files from this folder (e.g., `public/logo.png`). These are displayed in the marketplace when your app is published.
- **Auto-synced in dev mode** — when you add, update, or delete a file in `public/`, it is synced to the server automatically. No restart needed.
- **Included in builds** — `yarn twenty build` bundles all public assets into the distribution output.
-
-### Accessing public assets with `getPublicAssetUrl`
-
-Use the `getPublicAssetUrl` helper from `twenty-sdk` to get the full URL of a file in your `public/` directory. It works in both **logic functions** and **front components**.
-
-**In a logic function:**
-
-```ts src/logic-functions/send-invoice.ts
-import { defineLogicFunction, getPublicAssetUrl } from 'twenty-sdk/define';
-
-const handler = async (): Promise<any> => {
-  const logoUrl = getPublicAssetUrl('logo.png');
-  const invoiceUrl = getPublicAssetUrl('templates/invoice.png');
-
-  // Fetch the file content (no auth required — public endpoint)
-  const response = await fetch(invoiceUrl);
-  const buffer = await response.arrayBuffer();
-
-  return { logoUrl, size: buffer.byteLength };
-};
-
-export default defineLogicFunction({
-  universalIdentifier: 'a1b2c3d4-...',
-  name: 'send-invoice',
-  description: 'Sends an invoice with the app logo',
-  timeoutSeconds: 10,
-  handler,
-});
-```
-
-**In a front component:**
-
-```tsx src/front-components/company-card.tsx
-import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk/define';
-
-export default defineFrontComponent(() => {
-  const logoUrl = getPublicAssetUrl('logo.png');
-
-  return <img src={logoUrl} alt="App logo" />;
-});
-```
-
-The `path` argument is relative to your app's `public/` folder. Both `getPublicAssetUrl('logo.png')` and `getPublicAssetUrl('public/logo.png')` resolve to the same URL — the `public/` prefix is stripped automatically if present.
+The SDK provides programmatic APIs that let you build, deploy, install, and uninstall your app from test code. Combined with [Vitest](https://vitest.dev/) and the typed API clients, you can write integration tests that verify your app works end-to-end against a real Twenty server.

 ## Using npm packages

@@ -118,11 +64,7 @@ The build step uses esbuild to produce a single self-contained file per logic fu

 Both environments have `twenty-client-sdk/core` and `twenty-client-sdk/metadata` available as pre-provided modules — these are not bundled but resolved at runtime by the server.

-## Testing your app
-
-The SDK provides programmatic APIs that let you build, deploy, install, and uninstall your app from test code. Combined with [Vitest](https://vitest.dev/) and the typed API clients, you can write integration tests that verify your app works end-to-end against a real Twenty server.
-
-### Setup
+## Setup

 The scaffolded app already includes Vitest. If you set it up manually, install the dependencies:

@@ -196,7 +138,7 @@ beforeAll(async () => {
 });
 ```

-### Programmatic SDK APIs
+## Programmatic SDK APIs

 The `twenty-sdk/cli` subpath exports functions you can call directly from test code:

@@ -209,7 +151,7 @@ The `twenty-sdk/cli` subpath exports functions you can call directly from test c

 Each function returns a result object with `success: boolean` and either `data` or `error`.

-### Writing an integration test
+## Writing an integration test

 Here is a full example that builds, deploys, and installs the app, then verifies it appears in the workspace:

@@ -274,7 +216,7 @@ describe('App installation', () => {
 });
 ```

-### Running tests
+## Running tests

 Make sure your local Twenty server is running, then:

@@ -288,7 +230,7 @@ Or in watch mode during development:
 yarn test:watch
 ```

-### Type checking
+## Type checking

 You can also run type checking on your app without running tests:

@@ -298,81 +240,6 @@ yarn twenty typecheck

 This runs `tsc --noEmit` and reports any type errors.

-## CLI reference
-
-Beyond `dev`, `build`, `add`, and `typecheck`, the CLI provides commands for executing functions, viewing logs, and managing app installations.
-
-### Executing functions (`yarn twenty exec`)
-
-Run a logic function manually without triggering it via HTTP, cron, or database event:
-
-```bash filename="Terminal"
-# Execute by function name
-yarn twenty exec -n create-new-post-card
-
-# Execute by universalIdentifier
-yarn twenty exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
-
-# Pass a JSON payload
-yarn twenty exec -n create-new-post-card -p '{"name": "Hello"}'
-
-# Execute the post-install function
-yarn twenty exec --postInstall
-```
-
-### Viewing function logs (`yarn twenty logs`)
-
-Stream execution logs for your app's logic functions:
-
-```bash filename="Terminal"
-# Stream all function logs
-yarn twenty logs
-
-# Filter by function name
-yarn twenty logs -n create-new-post-card
-
-# Filter by universalIdentifier
-yarn twenty logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
-```
-
-<Note>
-This is different from `yarn twenty server logs`, which shows the Docker container logs. `yarn twenty logs` shows your app's function execution logs from the Twenty server.
-</Note>
-
-### Uninstalling an app (`yarn twenty uninstall`)
-
-Remove your app from the active workspace:
-
-```bash filename="Terminal"
-yarn twenty uninstall
-
-# Skip the confirmation prompt
-yarn twenty uninstall --yes
-```
-
-## Managing remotes
-
-A **remote** is a Twenty server that your app connects to. During setup, the scaffolder creates one for you automatically. You can add more remotes or switch between them at any time.
-
-```bash filename="Terminal"
-# Add a new remote (opens a browser for OAuth login)
-yarn twenty remote add
-
-# Connect to a local Twenty server (auto-detects port 2020 or 3000)
-yarn twenty remote add --local
-
-# Add a remote non-interactively (useful for CI)
-yarn twenty remote add --api-url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote
-
-# List all configured remotes
-yarn twenty remote list
-
-# Switch the active remote
-yarn twenty remote switch <name>
-```
-
-Your credentials are stored in `~/.twenty/config.json`.
-
 ## CI with GitHub Actions

 The scaffolder generates a ready-to-use GitHub Actions workflow at `.github/workflows/ci.yml`. It runs your integration tests automatically on every push to `main` and on pull requests.
@@ -83,7 +83,7 @@ Your API key grants access to sensitive data. Don't share it with untrusted serv

 For better security, assign a specific role to limit access:

-1. Go to **Settings → Roles**
+1. Go to **Settings → Members → Roles**
 2. Click on the role to assign
 3. Open the **Assignment** tab
 4. Under **API Keys**, click **+ Assign to API key**
@@ -35,14 +35,8 @@ Everything is detected via AST analysis at build time — no config files, no re

 ## The developer experience

-```bash
-npx create-twenty-app@latest my-app
-cd my-app
-yarn twenty dev
-```
-
-`yarn twenty dev` watches your source files, rebuilds on change, and live-syncs to a local Twenty instance. The typed API client regenerates automatically when the schema changes. When you're ready, `yarn twenty deploy` pushes to production. Apps can also be published to npm and listed in the Twenty marketplace.
+You write your app as a TypeScript project on your machine. The CLI watches your source files and live-syncs them to a running Twenty server — edit a file, see the change in the UI within a second. The typed API client regenerates automatically when the schema changes. When you're ready, `yarn twenty deploy` pushes to a production server, or `yarn twenty publish` lists your app on npm and the Twenty marketplace.

 <Card title="Build your first app" icon="arrow-right" href="/developers/extend/apps/getting-started">
-  Full walkthrough — scaffold, develop, deploy.
+  Three-phase walkthrough — scaffold, run a local server, sync your changes.
 </Card>
@@ -37,7 +37,7 @@ Beide sind als REST und GraphQL verfügbar. GraphQL bietet Batch-Upserts und die
 Authorization: Bearer YOUR_API_KEY
 ```

-Erstellen Sie einen API-Schlüssel unter **Settings > APIs & Webhooks > + Create key**. Kopieren Sie ihn sofort — er wird nur einmal angezeigt. Schlüssel können unter **Settings > Roles > Assignment tab** auf eine bestimmte Rolle beschränkt werden, um ihren Zugriff einzuschränken.
+Erstellen Sie einen API-Schlüssel unter **Settings > APIs & Webhooks > + Create key**. Kopieren Sie ihn sofort — er wird nur einmal angezeigt. Schlüssel können unter **Settings → Members → Roles → Assignment tab** auf eine bestimmte Rolle beschränkt werden, um ihren Zugriff einzuschränken.

 <VimeoEmbed videoId="928786722" title="API-Schlüssel erstellen" />

@@ -0,0 +1,64 @@
+---
+title: App-Konfiguration
+description: Deklarieren Sie die Identität, die Standardrolle, Variablen und Marktplatz-Metadaten Ihrer App mit `defineApplication`.
+icon: rocket
+---
+
+Jede App muss genau einen Aufruf von `defineApplication` haben. Dieser deklariert:
+
+* **Identität** — universeller Bezeichner, Anzeigename, Beschreibung.
+* **Berechtigungen** — unter welcher Rolle ihre Logikfunktionen und Frontend-Komponenten ausgeführt werden.
+* **Variablen** *(optional)* — Schlüssel–Wert-Paare, die Ihrem Code als Umgebungsvariablen zur Verfügung gestellt werden.
+* **Pre-install-/Post-install-Hooks** *(optional)* — siehe [Logikfunktionen](/l/de/developers/extend/apps/logic/logic-functions).
+
+```ts src/application-config.ts
+import { defineApplication } from 'twenty-sdk/define';
+
+export default defineApplication({
+  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
+  displayName: 'My Twenty App',
+  description: 'My first Twenty app',
+  applicationVariables: {
+    DEFAULT_RECIPIENT_NAME: {
+      universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
+      description: 'Default recipient name for postcards',
+      value: 'Jane Doe',
+      isSecret: false,
+    },
+  },
+});
+```
+
+Notizen:
+
+* `universalIdentifier`-Felder sind deterministische IDs, die Ihnen gehören. Erzeugen Sie sie einmal und halten Sie sie über Synchronisierungen hinweg stabil.
+* `applicationVariables` werden zu Umgebungsvariablen für Ihre Funktionen und Frontend-Komponenten (z. B. ist `DEFAULT_RECIPIENT_NAME` als `process.env.DEFAULT_RECIPIENT_NAME` verfügbar).
+* Die Standardrolle wird automatisch aus der Rollen-Datei erkannt, die mit [`defineApplicationRole()`](/l/de/developers/extend/apps/config/roles) markiert ist – Sie müssen sie nicht aus `defineApplication()` referenzieren.
+* Pre- und Post-Installationsfunktionen werden während des Manifest-Builds automatisch erkannt — Sie müssen sie in `defineApplication()` nicht referenzieren.
+* Die explizite Übergabe von `defaultRoleUniversalIdentifier` wird für die Abwärtskompatibilität weiterhin unterstützt, ist jedoch zugunsten von `defineApplicationRole()` veraltet.
+
+## Standard-Funktionsrolle
+
+Die mit [`defineApplicationRole()`](/l/de/developers/extend/apps/config/roles) deklarierte Rolle steuert, worauf die Logikfunktionen und Frontend-Komponenten der App zugreifen können:
+
+* Das zur Laufzeit als `TWENTY_APP_ACCESS_TOKEN` injizierte Token wird aus dieser Rolle abgeleitet.
+* Der typisierte API-Client ist auf die dieser Rolle gewährten Berechtigungen beschränkt.
+* Befolgen Sie das Least-Privilege-Prinzip: Deklarieren Sie nur die Berechtigungen, die Ihre Funktionen benötigen.
+
+Wenn Sie eine neue App erzeugen, erstellt die CLI eine Starter-Rolldatei unter `src/roles/default-role.ts`. Die vollständige Referenz finden Sie unter [Rollen & Berechtigungen](/l/de/developers/extend/apps/config/roles).
+
+## Marktplatz-Metadaten
+
+Wenn Sie planen, [Ihre App zu veröffentlichen](/l/de/developers/extend/apps/operations/publishing), steuern diese optionalen Felder, wie Ihre App im Marktplatz erscheint:
+
+| Feld               | Beschreibung                                                                                                                    |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `author`           | Name des Autors oder des Unternehmens                                                                                           |
+| `category`         | App-Kategorie für die Filterung im Marktplatz                                                                                   |
+| `logoUrl`          | Pfad zu Ihrem App-Logo (z. B. `public/logo.png`)                                                                                |
+| `screenshots`      | Array von Screenshot-Pfaden (z. B. `public/screenshot-1.png`)                                                                   |
+| `aboutDescription` | Längere Markdown-Beschreibung für den Tab "Info". Wenn weggelassen, verwendet der Marktplatz die `README.md` des Pakets von npm |
+| `websiteUrl`       | Link zu Ihrer Website                                                                                                           |
+| `termsUrl`         | Link zu den Nutzungsbedingungen                                                                                                 |
+| `emailSupport`     | Support-E-Mail-Adresse                                                                                                          |
+| `issueReportUrl`   | Link zum Issue-Tracker                                                                                                          |
@@ -0,0 +1,206 @@
+---
+title: Installations-Hooks
+description: Führen Sie Logik vor oder nach der Installation aus – befüllen Sie Daten, sichern Sie Datensätze und validieren Sie das Upgrade.
+icon: Schraubenschlüssel
+---
+
+Installations-Hooks sind spezielle Logikfunktionen, die während des Installations- oder Upgrade-Lebenszyklus ausgeführt werden. Sie verwenden dieselbe Handler-Laufzeit wie reguläre [Logikfunktionen](/l/de/developers/extend/apps/logic/logic-functions) und erhalten ein `InstallPayload`, werden jedoch mit eigenen Define-Funktionen deklariert – `definePostInstallLogicFunction()` und `definePreInstallLogicFunction()` – und sind vom normalen Trigger-Modell (HTTP, Cron, Datenbankereignisse) getrennt.
+
+Jede App darf **höchstens eine Pre-Install-Funktion** und **höchstens eine Post-Install-Funktion** definieren. Der Manifest-Build schlägt fehl, wenn mehr als eine von beiden erkannt wird.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ install flow                                                │
+│                                                             │
+│   upload package → [pre-install] → metadata migration →     │
+│   generate SDK → [post-install]                             │
+│                                                             │
+│                  old schema visible    new schema visible   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+<AccordionGroup>
+<Accordion title="definePostInstallLogicFunction" description="Wird ausgeführt, nachdem die Metadatenmigration des Arbeitsbereichs angewendet wurde">
+
+Eine Post-Install-Funktion wird automatisch ausgeführt, sobald Ihre App die Installation in einem Arbeitsbereich abgeschlossen hat. Der Server führt sie **nach** der Synchronisierung der Metadaten der App und der Generierung des SDK-Clients aus, sodass der Arbeitsbereich vollständig einsatzbereit ist und das neue Schema bereitsteht. Typische Anwendungsfälle umfassen das Befüllen von Standarddaten, das Erstellen anfänglicher Datensätze, das Konfigurieren von Arbeitsbereichseinstellungen oder das Bereitstellen von Ressourcen bei Diensten von Drittanbietern.
+
+```ts src/logic-functions/post-install.ts
+import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
+
+const handler = async (payload: InstallPayload): Promise<void> => {
+  console.log('Post install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePostInstallLogicFunction({
+  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
+  name: 'post-install',
+  description: 'Runs after installation to set up the application.',
+  timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: false,
+  shouldRunSynchronously: false,
+  handler,
+});
+```
+
+Sie können die Post-Installationsfunktion auch jederzeit manuell über die CLI ausführen:
+
+```bash filename="Terminal"
+yarn twenty exec --postInstall
+```
+
+Hauptpunkte:
+* Post-Installationsfunktionen verwenden `definePostInstallLogicFunction()` — eine spezialisierte Variante, die Trigger-Einstellungen (`cronTriggerSettings`, `databaseEventTriggerSettings`, `httpRouteTriggerSettings`, `toolTriggerSettings`, `workflowActionTriggerSettings`) weglässt.
+* Der Handler erhält ein `InstallPayload` mit `{ previousVersion?: string; newVersion: string }` — `newVersion` ist die zu installierende Version, und `previousVersion` ist die zuvor installierte Version (oder `undefined` bei einer Neuinstallation). Verwenden Sie diese Werte, um Neuinstallationen von Upgrades zu unterscheiden und versionsspezifische Migrationslogik auszuführen.
+* **Wann der Hook ausgeführt wird**: standardmäßig nur bei Neuinstallationen. Übergeben Sie `shouldRunOnVersionUpgrade: true`, wenn er auch beim Upgrade der App von einer vorherigen Version ausgeführt werden soll. Wenn weggelassen, ist das Flag standardmäßig `false` und Upgrades überspringen den Hook.
+* **Ausführungsmodell — standardmäßig asynchron, synchron optional**: Das Flag `shouldRunSynchronously` steuert, *wie* Post-Install ausgeführt wird.
+  * `shouldRunSynchronously: false` *(Standard)* — der Hook wird **in die Nachrichtenwarteschlange eingereiht** mit `retryLimit: 3` und läuft asynchron in einem Worker. Die Installationsantwort kommt zurück, sobald der Job eingereiht ist, sodass ein langsamer oder fehlschlagender Handler den Aufrufer nicht blockiert. Der Worker versucht es bis zu dreimal erneut. **Verwenden Sie dies für lang laufende Jobs** — das Befüllen großer Datensätze, Aufrufe langsamer Drittanbieter-APIs, Bereitstellung externer Ressourcen, alles, was ein vernünftiges HTTP-Antwortfenster überschreiten könnte.
+  * `shouldRunSynchronously: true` — der Hook wird **inline während des Installationsablaufs** ausgeführt (gleicher Executor wie bei Pre-Install). Die Installationsanforderung blockiert, bis der Handler fertig ist, und wenn er einen Fehler wirft, erhält der Installationsaufrufer einen `POST_INSTALL_ERROR`. Keine automatischen Wiederholungen. **Verwenden Sie dies für schnelle Aufgaben, die vor der Antwort abgeschlossen sein müssen** — z. B. um dem Benutzer einen Validierungsfehler auszugeben oder für eine schnelle Einrichtung, auf die der Client unmittelbar nach der Rückkehr des Installationsaufrufs angewiesen ist. Beachten Sie, dass die Metadatenmigration bereits angewendet wurde, wenn Post-Install läuft, sodass ein Fehler im Synchronmodus die Schemaänderungen **nicht** rückgängig macht — er zeigt lediglich den Fehler an.
+* Stellen Sie sicher, dass Ihr Handler idempotent ist. Im asynchronen Modus kann die Warteschlange bis zu dreimal erneut versuchen; in beiden Modi kann der Hook bei Upgrades erneut laufen, wenn `shouldRunOnVersionUpgrade: true`.
+* Die Umgebungsvariablen `APPLICATION_ID`, `APP_ACCESS_TOKEN` und `API_URL` sind im Handler verfügbar (wie bei jeder anderen Logikfunktion), sodass Sie die Twenty API mit einem auf Ihre App beschränkten Anwendungszugriffstoken aufrufen können.
+* Pro Anwendung ist nur eine Post-Installationsfunktion zulässig. Der Manifest-Build schlägt fehl, wenn mehr als eine erkannt wird.
+* Die `universalIdentifier`, `shouldRunOnVersionUpgrade` und `shouldRunSynchronously` der Funktion werden während des Builds automatisch dem Anwendungsmanifest unter dem Feld `postInstallLogicFunction` hinzugefügt – Sie müssen sie in [`defineApplication()`](/l/de/developers/extend/apps/config/application) nicht referenzieren.
+* Das standardmäßige Timeout ist auf 300 Sekunden (5 Minuten) festgelegt, um längere Einrichtungsvorgänge wie Daten-Seeding zu ermöglichen.
+* **Nicht im Dev-Modus ausgeführt**: Wenn eine App lokal registriert ist (über `yarn twenty dev`), überspringt der Server den Installationsablauf vollständig und synchronisiert Dateien direkt über den CLI-Watcher — daher läuft Post-Install im Dev-Modus nie, unabhängig von `shouldRunSynchronously`. Verwenden Sie `yarn twenty exec --postInstall`, um es manuell gegen einen laufenden Arbeitsbereich auszulösen.
+
+</Accordion>
+<Accordion title="definePreInstallLogicFunction" description="Wird ausgeführt, bevor die Metadatenmigration des Arbeitsbereichs angewendet wird">
+
+Eine Pre-Install-Funktion wird automatisch während der Installation ausgeführt, **bevor die Metadatenmigration des Arbeitsbereichs angewendet wird**. Sie hat die gleiche Payload-Struktur wie Post-Install (`InstallPayload`), ist aber früher im Installationsablauf positioniert, sodass sie Zustände vorbereiten kann, von denen die bevorstehende Migration abhängt — typische Anwendungsfälle sind das Sichern von Daten, die Validierung der Kompatibilität mit dem neuen Schema oder das Archivieren von Datensätzen, die umstrukturiert oder entfernt werden sollen.
+
+```ts src/logic-functions/pre-install.ts
+import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
+
+const handler = async (payload: InstallPayload): Promise<void> => {
+  console.log('Pre install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePreInstallLogicFunction({
+  universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
+  name: 'pre-install',
+  description: 'Runs before installation to prepare the application.',
+  timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: true,
+  handler,
+});
+```
+
+Sie können die Pre-Installationsfunktion auch jederzeit manuell über die CLI ausführen:
+
+```bash filename="Terminal"
+yarn twenty exec --preInstall
+```
+
+Hauptpunkte:
+* Pre-Install-Funktionen verwenden `definePreInstallLogicFunction()` — dieselbe spezialisierte Konfiguration wie bei Post-Install, nur an einen anderen Lifecycle-Slot gebunden.
+* Sowohl Pre- als auch Post-Install-Handler erhalten denselben `InstallPayload`-Typ: `{ previousVersion?: string; newVersion: string }`. Importieren Sie ihn einmal und verwenden Sie ihn für beide Hooks wieder.
+* **Wann der Hook ausgeführt wird**: positioniert direkt vor der Metadatenmigration des Arbeitsbereichs (`synchronizeFromManifest`). Vor der Ausführung führt der Server einen rein additiven "pared-down sync" durch, der die Pre-Install-Funktion der **neuen** Version in den Metadaten des Arbeitsbereichs registriert — sonst wird nichts angefasst — und führt sie dann aus. Da dieser Sync nur additiv ist, sind die Objekte, Felder und Daten der vorherigen Version noch intakt, wenn Ihr Handler läuft: Sie können den Zustand vor der Migration gefahrlos lesen und sichern.
+* **Ausführungsmodell**: Pre-Install wird **synchron** ausgeführt und **blockiert die Installation**. Wenn der Handler einen Fehler wirft, wird die Installation abgebrochen, bevor Schemaänderungen angewendet werden — der Arbeitsbereich verbleibt in der vorherigen Version in einem konsistenten Zustand. Das ist beabsichtigt: Pre-Install ist Ihre letzte Chance, ein riskantes Upgrade abzulehnen.
+* Wie bei Post-Install ist pro Anwendung nur eine Pre-Installationsfunktion zulässig. Sie wird während des Builds automatisch dem Anwendungsmanifest unter `preInstallLogicFunction` hinzugefügt.
+* **Nicht im Dev-Modus ausgeführt**: wie bei Post-Install — der Installationsablauf wird für lokal registrierte Apps vollständig übersprungen, daher läuft Pre-Install unter `yarn twenty dev` nie. Verwenden Sie `yarn twenty exec --preInstall`, um es manuell auszulösen.
+
+</Accordion>
+<Accordion title="Pre-Install vs. Post-Install: wann was verwenden" description="Den richtigen Installations-Hook wählen">
+
+Beide Hooks sind Teil desselben Installationsablaufs und erhalten dasselbe `InstallPayload`. Der Unterschied besteht darin, **wann** sie relativ zur Metadatenmigration des Workspaces ausgeführt werden, und das ändert, auf welche Daten sie gefahrlos zugreifen können.
+
+Pre-Install ist immer **synchron** (blockiert die Installation und kann sie abbrechen). Post-Install ist **standardmäßig asynchron** — in einen Worker eingereiht mit automatischen Wiederholungen — kann aber per `shouldRunSynchronously: true` in die synchrone Ausführung wechseln. Siehe das Akkordeon zu `definePostInstallLogicFunction` oben, wann welcher Modus zu verwenden ist.
+
+**Verwenden Sie `post-install` für alles, wofür das neue Schema existieren muss.** Dies ist der Regelfall:
+
+* Standarddaten befüllen (Anlegen anfänglicher Datensätze, Standardansichten, Demo-Inhalte) für neu hinzugefügte Objekte und Felder.
+* Registrieren von Webhooks bei Drittanbieter-Diensten, jetzt, da die App ihre Anmeldedaten hat.
+* Aufrufen Ihrer eigenen API, um eine Einrichtung abzuschließen, die von den synchronisierten Metadaten abhängt.
+* Idempotente "Stelle sicher, dass dies existiert"-Logik, die bei jedem Upgrade den Zustand abgleichen soll — kombinieren Sie dies mit `shouldRunOnVersionUpgrade: true`.
+
+Beispiel — nach der Installation einen Standard-`PostCard`-Datensatz anlegen:
+
+```ts src/logic-functions/post-install.ts
+import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
+import { createClient } from './generated/client';
+
+const handler = async ({ previousVersion }: InstallPayload): Promise<void> => {
+  if (previousVersion) return; // fresh installs only
+
+  const client = createClient();
+  await client.postCard.create({
+    data: { title: 'Welcome to Postcard', content: 'Your first card!' },
+  });
+};
+
+export default definePostInstallLogicFunction({
+  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
+  name: 'post-install',
+  description: 'Seeds a welcome post card after install.',
+  timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: false,
+  handler,
+});
+```
+
+**Verwenden Sie `pre-install`, wenn eine Migration ansonsten vorhandene Daten löschen oder beschädigen würde.** Da Pre-Install gegen das vorherige Schema läuft und ein Fehlschlag das Upgrade zurückrollt, ist es der richtige Ort für alles Riskante:
+
+* **Sichern von Daten, die gleich gelöscht oder umstrukturiert werden** — z. B. Sie entfernen in v2 ein Feld und müssen dessen Werte vor der Migration in ein anderes Feld kopieren oder in einen Speicher exportieren.
+* **Archivieren von Datensätzen, die eine neue Einschränkung ungültig machen würde** — z. B. ein Feld wird `NOT NULL` und Sie müssen zuerst Zeilen mit Null-Werten löschen oder korrigieren.
+* **Kompatibilität validieren und das Upgrade ablehnen, wenn die aktuellen Daten nicht sauber migriert werden können** — werfen Sie im Handler einen Fehler, und die Installation wird ohne Änderungen abgebrochen. Das ist sicherer, als die Inkompatibilität mitten in der Migration zu entdecken.
+* **Daten umbenennen oder Schlüssel neu zuweisen** vor einer Schemaänderung, bei der sonst die Zuordnung verloren ginge.
+
+Beispiel — Datensätze vor einer destruktiven Migration archivieren:
+
+```ts src/logic-functions/pre-install.ts
+import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
+import { createClient } from './generated/client';
+
+const handler = async ({ previousVersion, newVersion }: InstallPayload): Promise<void> => {
+  // Only the 1.x → 2.x upgrade drops the legacy `notes` field.
+  if (!previousVersion?.startsWith('1.') || !newVersion.startsWith('2.')) {
+    return;
+  }
+
+  const client = createClient();
+  const legacyRecords = await client.postCard.findMany({
+    where: { notes: { isNotNull: true } },
+  });
+
+  if (legacyRecords.length === 0) return;
+
+  // Copy legacy `notes` into the new `description` field before the migration
+  // drops the `notes` column. If this fails, the upgrade is aborted and the
+  // workspace stays on v1 with all data intact.
+  await Promise.all(
+    legacyRecords.map((record) =>
+      client.postCard.update({
+        where: { id: record.id },
+        data: { description: record.notes },
+      }),
+    ),
+  );
+};
+
+export default definePreInstallLogicFunction({
+  universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
+  name: 'pre-install',
+  description: 'Backs up legacy notes into description before the v2 migration.',
+  timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: true,
+  handler,
+});
+```
+
+**Faustregel:**
+
+| Sie möchten ...                                                                                                                 | Verwenden                                                                              |
+| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Standarddaten befüllen, den Arbeitsbereich konfigurieren, externe Ressourcen registrieren                                       | `post-install`                                                                         |
+| Lang laufendes Seeding oder Drittanbieteraufrufe ausführen, die die Installationsantwort nicht blockieren sollten               | `post-install` (Standard — `shouldRunSynchronously: false`, mit Worker-Wiederholungen) |
+| Schnelle Einrichtung ausführen, auf die sich der Aufrufer unmittelbar nach der Rückkehr des Installationsaufrufs verlassen wird | `post-install` mit `shouldRunSynchronously: true`                                      |
+| Daten lesen oder sichern, die bei der bevorstehenden Migration verloren gingen                                                  | `pre-install`                                                                          |
+| Ein Upgrade ablehnen, das vorhandene Daten beschädigen würde                                                                    | `pre-install` (`throw` im Handler)                                                     |
+| Bei jedem Upgrade einen Abgleich ausführen                                                                                      | `post-install` mit `shouldRunOnVersionUpgrade: true`                                   |
+| Einmalige Einrichtung nur bei der ersten Installation durchführen                                                               | `post-install` mit `shouldRunOnVersionUpgrade: false` (Standard)                       |
+
+<Note>
+Im Zweifel auf **Post-Install** setzen. Greifen Sie nur zu Pre-Install, wenn die Migration selbst destruktiv ist und Sie den vorherigen Zustand abfangen müssen, bevor er verloren geht.
+</Note>
+
+</Accordion>
+</AccordionGroup>
@@ -0,0 +1,51 @@
+---
+title: Übersicht
+description: Konfigurieren Sie die App selbst – ihre Identität, Standardberechtigungen und das, was zur Installationszeit ausgeführt wird.
+icon: screwdriver-wrench
+---
+
+Die **Konfigurationsebene** einer Twenty-App beschreibt die App *für die Plattform* – ihre Identität, die Berechtigungen, die sie hält, und den Code, der während der Installation oder Aktualisierung ausgeführt wird. Diese Deklarationen fügen keine neuen Datentypen oder Laufzeitverhalten hinzu; sie teilen Twenty mit, *wer die App ist* und *wie sie eingerichtet werden soll*.
+
+```text
+┌────────────────────────────────────────────────────────┐
+│ Application — identity, default role, variables,       │
+│               marketplace metadata                     │
+│                                                        │
+│   ┌──────────────────────────────────────────────────┐ │
+│   │ Role — what the app's logic functions can read   │ │
+│   │ and write (referenced by Application)            │ │
+│   └──────────────────────────────────────────────────┘ │
+└────────────────────────────────────────────────────────┘
+                          │
+                          ▼  (at install / upgrade time)
+       ┌──────────────────────────────────┐
+       │ Pre-install hook                 │  before metadata migration
+       └──────────────────────────────────┘
+       ┌──────────────────────────────────┐
+       │ Post-install hook                │  after metadata migration
+       └──────────────────────────────────┘
+```
+
+## In diesem Abschnitt
+
+<CardGroup cols={2}>
+  <Card title="App-Konfiguration" icon="rocket" href="/l/de/developers/extend/apps/config/application">
+    `defineApplication` – Identität, Standardrolle, Variablen, Marketplace-Metadaten.
+  </Card>
+  <Card title="Rollen & Berechtigungen" icon="shield-halved" href="/l/de/developers/extend/apps/config/roles">
+    `defineRole` – deklariert, was die Logikfunktionen Ihrer App lesen und schreiben können.
+  </Card>
+  <Card title="Installations-Hooks" icon="Schraubenschlüssel" href="/l/de/developers/extend/apps/config/install-hooks">
+    `definePreInstallLogicFunction` und `definePostInstallLogicFunction` – Daten sichern, Standardwerte befüllen, Aktualisierungen validieren.
+  </Card>
+</CardGroup>
+
+## Wie die Bausteine zusammenhängen
+
+* **Application** ist der Einstiegspunkt. Jede App hat genau einen `defineApplication()`-Aufruf, und dieser verweist auf eine **Rolle** als Standard.
+* Die **Rolle** steuert, was die Logikfunktionen und Frontend-Komponenten der App lesen und schreiben können. Folgen Sie dem Prinzip der geringsten Privilegien: Gewähren Sie nur die Berechtigungen, die Ihr Code tatsächlich benötigt.
+* **Install Hooks** laufen während der Installation oder Aktualisierung – Pre-Install vor der Metadatenmigration (so kann ein riskantes Upgrade abgelehnt werden), Post-Install nach der Migration (so können Standarddaten gegen das neue Schema befüllt werden).
+
+<Note>
+Installations-Hooks nutzen die Laufzeit der [Logikfunktion](/l/de/developers/extend/apps/logic/logic-functions) – gleiche Handler-Signatur, gleiche Umgebungsvariablen, gleicher typisierter API-Client –, werden aber mit ihren eigenen Define-Funktionen deklariert und leben außerhalb des regulären Trigger-Modells (HTTP, Cron, Datenbankereignisse).
+</Note>
@@ -0,0 +1,59 @@
+---
+title: Öffentliche Assets
+description: Liefern Sie statische Dateien — Bilder, Icons, Schriftarten — zusammen mit Ihrer App über den Ordner public/ aus.
+icon: folder-open
+---
+
+Der Ordner `public/` im Stammverzeichnis Ihrer App enthält statische Dateien — Bilder, Icons, Schriftarten oder sonstige Assets, die Ihre App zur Laufzeit benötigt. Diese Dateien werden automatisch in Builds aufgenommen, während des Dev-Modus synchronisiert und auf den Server hochgeladen.
+
+Für Dateien im Verzeichnis `public/` gilt:
+
+* **Öffentlich zugänglich** — nach der Synchronisierung mit dem Server werden Assets unter einer öffentlichen URL bereitgestellt. Zum Zugriff ist keine Authentifizierung erforderlich.
+* **In Frontend-Komponenten verfügbar** — verwenden Sie Asset-URLs, um Bilder, Icons oder andere Medien in Ihren React-Komponenten anzuzeigen.
+* **In Logikfunktionen verfügbar** — referenzieren Sie Asset-URLs in E-Mails, API-Antworten oder in beliebiger serverseitiger Logik.
+* **Für Marketplace-Metadaten verwendet** — die Felder `logoUrl` und `screenshots` in `defineApplication()` referenzieren Dateien aus diesem Ordner (z. B. `public/logo.png`). Diese werden im Marketplace angezeigt, wenn Ihre App veröffentlicht wird.
+* **Im Dev-Modus automatisch synchronisiert** — wenn Sie in `public/` eine Datei hinzufügen, aktualisieren oder löschen, wird sie automatisch mit dem Server synchronisiert. Kein Neustart erforderlich.
+* **In Builds enthalten** — `yarn twenty build` bündelt alle öffentlichen Assets in der Distributionsausgabe.
+
+## Zugriff auf öffentliche Assets mit `getPublicAssetUrl`
+
+Verwenden Sie den Helper `getPublicAssetUrl` aus `twenty-sdk`, um die vollständige URL einer Datei in Ihrem `public/`-Verzeichnis zu erhalten. Dies funktioniert sowohl in Logikfunktionen als auch in Frontend-Komponenten.
+
+**In einer Logikfunktion:**
+
+```ts src/logic-functions/send-invoice.ts
+import { defineLogicFunction, getPublicAssetUrl } from 'twenty-sdk/define';
+
+const handler = async (): Promise<any> => {
+  const logoUrl = getPublicAssetUrl('logo.png');
+  const invoiceUrl = getPublicAssetUrl('templates/invoice.png');
+
+  // Fetch the file content (no auth required — public endpoint)
+  const response = await fetch(invoiceUrl);
+  const buffer = await response.arrayBuffer();
+
+  return { logoUrl, size: buffer.byteLength };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'a1b2c3d4-...',
+  name: 'send-invoice',
+  description: 'Sends an invoice with the app logo',
+  timeoutSeconds: 10,
+  handler,
+});
+```
+
+**In einer Frontend-Komponente:**
+
+```tsx src/front-components/company-card.tsx
+import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk/define';
+
+export default defineFrontComponent(() => {
+  const logoUrl = getPublicAssetUrl('logo.png');
+
+  return <img src={logoUrl} alt="App logo" />;
+});
+```
+
+Das Argument `path` ist relativ zum `public/`-Ordner Ihrer App. Sowohl `getPublicAssetUrl('logo.png')` als auch `getPublicAssetUrl('public/logo.png')` ergeben dieselbe URL — das Präfix `public/` wird, falls vorhanden, automatisch entfernt.
@@ -0,0 +1,93 @@
+---
+title: Rollen & Berechtigungen
+description: Legen Sie fest, welche Objekte und Felder die Logikfunktionen und Frontend-Komponenten Ihrer App lesen und schreiben können.
+icon: shield-halved
+---
+
+Eine **Rolle** ist ein Berechtigungssatz: welche Objekte eine App lesen oder schreiben kann, welche Felder sie sehen kann und welche plattformbezogenen Funktionen sie nutzen kann. Alle Logikfunktionen und Frontend-Komponenten einer App erben die Berechtigungen der Rolle, die mit `defineApplicationRole()` markiert ist (siehe [Die Standardfunktionsrolle](#the-default-function-role) unten).
+
+```ts src/roles/restricted-company-role.ts
+import {
+  defineRole,
+  PermissionFlag,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk/define';
+
+export default defineRole({
+  universalIdentifier: '2c80f640-2083-4803-bb49-003e38279de6',
+  label: 'My new role',
+  description: 'A role that can be used in your workspace',
+  canReadAllObjectRecords: false,
+  canUpdateAllObjectRecords: false,
+  canSoftDeleteAllObjectRecords: false,
+  canDestroyAllObjectRecords: false,
+  canUpdateAllSettings: false,
+  canBeAssignedToAgents: false,
+  canBeAssignedToUsers: false,
+  canBeAssignedToApiKeys: false,
+  objectPermissions: [
+    {
+      objectUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+      canReadObjectRecords: true,
+      canUpdateObjectRecords: true,
+      canSoftDeleteObjectRecords: false,
+      canDestroyObjectRecords: false,
+    },
+  ],
+  fieldPermissions: [
+    {
+      objectUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+      fieldUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.name.universalIdentifier,
+      canReadFieldValue: false,
+      canUpdateFieldValue: false,
+    },
+  ],
+  permissionFlags: [PermissionFlag.APPLICATIONS],
+});
+```
+
+## Die Standard-Funktionsrolle
+
+Wenn Sie eine neue App erzeugen, erstellt die CLI eine Datei für die Standardrolle, die mit `defineApplicationRole()` deklariert ist:
+
+```ts src/roles/default-role.ts
+import { defineApplicationRole, PermissionFlag } from 'twenty-sdk/define';
+
+export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
+  'b648f87b-1d26-4961-b974-0908fd991061';
+
+export default defineApplicationRole({
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  label: 'Default function role',
+  description: 'Default role for function Twenty client',
+  canReadAllObjectRecords: true,
+  canUpdateAllObjectRecords: false,
+  canSoftDeleteAllObjectRecords: false,
+  canDestroyAllObjectRecords: false,
+  canUpdateAllSettings: false,
+  canBeAssignedToAgents: false,
+  canBeAssignedToUsers: false,
+  canBeAssignedToApiKeys: false,
+  objectPermissions: [],
+  fieldPermissions: [],
+  permissionFlags: [],
+});
+```
+
+`defineApplicationRole()` ist ein dünner Wrapper um `defineRole()`, der **die** Rolle kennzeichnet, die zum Installationszeitpunkt als Standardrolle Ihrer Anwendung verwendet wird. Die Validierung ist identisch zu `defineRole`, aber die Build-Pipeline verdrahtet deren `universalIdentifier` automatisch in das `defaultRoleUniversalIdentifier` des Anwendungsmanifests – sodass Sie es nicht selbst aus [`defineApplication`](/l/de/developers/extend/apps/config/application) referenzieren müssen.
+
+Notizen:
+
+* Genau **eine** `defineApplicationRole(...)` ist pro App zulässig – der Manifest-Build schlägt fehl, wenn mehr als eine gefunden wird.
+* Verwenden Sie `defineRole()` (nicht `defineApplicationRole()`) für alle **zusätzlichen** Rollen, die Ihre App mitliefert.
+* Das explizite Setzen von `defaultRoleUniversalIdentifier` in `defineApplication()` wird für die Abwärtskompatibilität weiterhin unterstützt, ist aber zugunsten von `defineApplicationRole()` veraltet.
+
+## Beste Praktiken
+
+* Beginnen Sie mit der vorgegebenen Rolle und schränken Sie sie dann schrittweise ein – standardmäßig wird umfangreicher Lesezugriff gewährt, was selten das ist, was Sie in Produktionsumgebungen möchten.
+* Ersetzen Sie `objectPermissions` und `fieldPermissions` durch die genauen Objekte und Felder, die Ihre Funktionen tatsächlich benötigen.
+* `permissionFlags` steuern den Zugriff auf Funktionen auf Plattformebene. Halten Sie sie minimal.
+* Ein funktionierendes Beispiel finden Sie unter: [`hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).
@@ -0,0 +1,193 @@
+---
+title: Verbindungen
+description: Ermöglichen Sie Ihrer App, im Namen eines Benutzers über OAuth in Diensten von Drittanbietern zu handeln.
+icon: plug
+---
+
+Verbindungen sind Anmeldedaten, die ein Benutzer für einen externen Dienst besitzt (Linear, GitHub, Slack, ...). Ihre App legt fest, **wie** diese Anmeldedaten bezogen werden — ein **Verbindungsanbieter** — und verwendet sie zur Laufzeit, um authentifizierte Aufrufe an die Drittanbieter-API zu tätigen.
+
+Derzeit wird nur OAuth 2.0 unterstützt. Zukünftige Anmeldedatentypen (Personal Access Tokens, API-Schlüssel, Basic Auth) werden in dieselbe Oberfläche integriert — Apps, die bereits `defineConnectionProvider({ type: 'oauth', ... })` müssen nicht migriert werden.
+
+<AccordionGroup>
+
+<Accordion title="defineConnectionProvider" description="Legen Sie fest, wie die Verbindungen Ihrer App bezogen werden">
+
+Ein Verbindungsanbieter beschreibt den OAuth-Handshake, den Ihre App benötigt. Der Benutzer klickt in den Einstellungen Ihrer App auf "Verbindung hinzufügen", schließt den Zustimmungsbildschirm des Anbieters ab, und in seinem Arbeitsbereich wird eine `ConnectedAccount`-Zeile erstellt.
+
+Eine funktionierende Einrichtung benötigt **zwei Dateien** — den Verbindungsanbieter und eine passende `serverVariables`-Deklaration in `defineApplication`, die die OAuth-Client-Anmeldedaten enthält.
+
+```ts src/connection-providers/linear-connection.ts
+import { defineConnectionProvider } from 'twenty-sdk/define';
+
+export default defineConnectionProvider({
+  universalIdentifier: '9c7d1f5e-6a0b-4d44-be0c-3f8b5a9d4e6f',
+  name: 'linear',
+  displayName: 'Linear',
+  icon: 'IconBrandLinear',
+  type: 'oauth',
+  oauth: {
+    authorizationEndpoint: 'https://linear.app/oauth/authorize',
+    tokenEndpoint: 'https://api.linear.app/oauth/token',
+    scopes: ['read', 'write'],
+    // These must match keys in `defineApplication.serverVariables` below.
+    clientIdVariable: 'LINEAR_CLIENT_ID',
+    clientSecretVariable: 'LINEAR_CLIENT_SECRET',
+    // Optional: defaults to 'json'. Some providers (Linear, Slack) want
+    // 'form-urlencoded' for the token request.
+    tokenRequestContentType: 'form-urlencoded',
+    // Optional: defaults to true. Disable only if the provider rejects PKCE.
+    usePkce: false,
+    // Optional: extra query params on the authorize URL.
+    // authorizationParams: { prompt: 'consent' },
+    // Optional: provider's RFC 7009 token revocation endpoint, called on disconnect.
+    // revokeEndpoint: 'https://example.com/oauth/revoke',
+  },
+});
+```
+
+```ts src/application.config.ts
+import { defineApplication } from 'twenty-sdk/define';
+
+export default defineApplication({
+  universalIdentifier: '...',
+  displayName: 'Linear',
+  description: 'Connect Linear to Twenty.',
+  defaultRoleUniversalIdentifier: '...',
+  // OAuth client credentials live on the app registration (one OAuth app per
+  // Twenty server, configured by the admin) — not per-workspace. Declare them
+  // as serverVariables so the admin can fill them in once for all installs.
+  serverVariables: {
+    LINEAR_CLIENT_ID: {
+      description: 'OAuth client ID from your Linear OAuth application.',
+      isSecret: false,
+      isRequired: true,
+    },
+    LINEAR_CLIENT_SECRET: {
+      description: 'OAuth client secret from your Linear OAuth application.',
+      isSecret: true,
+      isRequired: true,
+    },
+  },
+});
+```
+
+Hauptpunkte:
+
+* `name` ist die eindeutige Bezeichner-Zeichenfolge, die in `listConnections({ providerName })` verwendet wird (kebab-case, muss `^[a-z][a-z0-9-]*$` entsprechen).
+* `displayName` wird im Einstellungs-Tab der jeweiligen App und in der KI-Toolliste angezeigt.
+* `clientIdVariable` / `clientSecretVariable` sind **Namen**, keine Werte — sie müssen den in `defineApplication.serverVariables` deklarierten Schlüsseln entsprechen. Die tatsächlichen `client_id` und `client_secret` werden vom Serveradministrator über die App-Registrierungsoberfläche eingegeben und niemals in Ihr Repository eingecheckt.
+* Verwenden Sie `serverVariables` (nicht `applicationVariables`) — OAuth-Anmeldedaten gelten serverweit und es gibt eine OAuth-App pro Twenty-Server.
+* Solange beide `serverVariables` nicht ausgefüllt sind, zeigt der Einstellungs-Tab pro App den Hinweis "Benötigt Server-Admin" an und der Button "Verbindung hinzufügen" ist deaktiviert.
+* `type: 'oauth'` ist derzeit der einzige unterstützte Wert. Der Diskriminator ist vorwärtskompatibel: zukünftige Typen (`'pat'`, `'api-key'`, ...) werden neue Unterkonfigurationsblöcke neben `oauth` hinzufügen.
+
+Die OAuth-Callback-URL, die Ihr Anbieter auf die Whitelist setzen muss, lautet:
+
+```
+https://<your-twenty-server>/apps/oauth/callback
+```
+
+</Accordion>
+
+<Accordion title="listConnections / getConnection" description="Verbindungen aus einer Logikfunktion verwenden">
+
+Innerhalb eines Logikfunktions-Handlers gibt `listConnections({ providerName })` die `ConnectedAccount`-Zeilen dieser App für den angegebenen Anbieter zurück, mit aktualisierten Zugriffstoken.
+
+```ts src/logic-functions/handlers/create-linear-issue-handler.ts
+import { listConnections } from 'twenty-sdk/logic-function';
+
+export const createLinearIssueHandler = async (input: {
+  teamId?: string;
+  title?: string;
+}) => {
+  if (!input.teamId || !input.title) {
+    return { success: false, error: 'teamId and title are required' };
+  }
+
+  const connections = await listConnections({ providerName: 'linear' });
+
+  // Workspace-shared credentials win when present; fall back to the first
+  // user-visibility one. For HTTP-route triggers you typically pick the
+  // request user's connection via event.userWorkspaceId instead.
+  const connection =
+    connections.find((c) => c.visibility === 'workspace') ?? connections[0];
+
+  if (!connection) {
+    return {
+      success: false,
+      error:
+        'Linear is not connected. Open the app settings and click "Add connection".',
+    };
+  }
+
+  // Use connection.accessToken to call the third-party API.
+  const response = await fetch('https://api.linear.app/graphql', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${connection.accessToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      query: `mutation { issueCreate(input: { teamId: "${input.teamId}", title: "${input.title}" }) { success } }`,
+    }),
+  });
+
+  return { success: response.ok };
+};
+```
+
+Jede Verbindung hat:
+
+| Feld               | Beschreibung                                                                                                                       |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `id`               | Eindeutige Zeilen-ID; an `getConnection(id)` übergeben, um eine einzelne Verbindung erneut abzurufen                               |
+| `sichtbarkeit`     | `'user'` (privat für ein Mitglied des Arbeitsbereichs) oder `'workspace'` (mit allen Mitgliedern geteilt)                          |
+| `geltungsbereiche` | Vom Upstream-Anbieter gewährte OAuth-Berechtigungen (unabhängig von `visibility` — diese sind nicht miteinander verknüpft)         |
+| `userWorkspaceId`  | Die userWorkspace-ID des Eigentümers — nützlich, um "die Verbindung des anfragenden Benutzers" in HTTP-Routen-Triggern auszuwählen |
+| `accessToken`      | Frisches OAuth-Zugriffstoken (wird bei Ablauf automatisch erneuert)                                                                |
+| `name` / `handle`  | Anzeigename der Verbindung (automatisch beim OAuth-Callback abgeleitet, vom Benutzer umbenennbar)                                  |
+| `authFailedAt`     | Gesetzt, wenn die jüngste Aktualisierung fehlgeschlagen ist; der Benutzer muss die Verbindung erneut herstellen                    |
+
+Hauptpunkte:
+
+* Übergeben Sie `{ providerName }`, um nach Anbieter zu filtern; lassen Sie es weg, um alle Verbindungen dieser App über alle Anbieter hinweg zu erhalten.
+* Der Server aktualisiert das Zugriffstoken vor der Rückgabe transparent. Ihr Handler sieht stets ein verwendbares Token (oder `authFailedAt` ist gesetzt).
+* `getConnection(id)` ist das Pendant für eine einzelne Zeile.
+
+</Accordion>
+
+<Accordion title="Sichtbarkeit: pro Benutzer vs. im Arbeitsbereich geteilt" description="Wie Benutzer zwischen privaten und geteilten Anmeldedaten wählen">
+
+Wenn ein Benutzer auf "Verbindung hinzufügen" klickt, wird er aufgefordert, eine Sichtbarkeit auszuwählen:
+
+* **Nur für mich** — die Anmeldedaten sind für den sich verbindenden Benutzer privat. Jede Logikfunktion, die in seinem/ihrem Auftrag aufgerufen wird (HTTP-Routen-Trigger mit `isAuthRequired: true`), sieht sie; Cron-Trigger und Datenbankereignisse nicht.
+* **Im Arbeitsbereich geteilt** — jedes Arbeitsbereichsmitglied kann die Anmeldedaten verwenden. Cron-/Datenbank-Trigger sehen sie ebenfalls, da sie keinen anfragenden Benutzer haben.
+
+Verwenden Sie für jeden Handler die richtige Option:
+
+```ts
+// HTTP-route trigger — prefer the request user's own connection.
+const conn =
+  connections.find((c) => c.userWorkspaceId === event.userWorkspaceId) ??
+  connections.find((c) => c.visibility === 'workspace');
+
+// Cron trigger — no request user; only shared credentials are sensible.
+const conn = connections.find((c) => c.visibility === 'workspace');
+```
+
+Mehrere Verbindungen pro (Benutzer, Anbieter) sind erlaubt, sodass derselbe Benutzer "Persönliches Linear" und "Arbeits-Linear" nebeneinander haben kann.
+
+</Accordion>
+
+<Accordion title="Einmalige Anbietereinrichtung" description="Registrieren Sie Ihre OAuth-App beim Drittanbieterdienst">
+
+Für jeden Verbindungsanbieter muss der Serveradministrator zunächst eine OAuth-App beim Drittanbieter registrieren.
+
+1. Gehen Sie zu den Entwickler-Einstellungen des Anbieters (z. B. https://linear.app/settings/api/applications/new).
+2. Setzen Sie die **Redirect-URI** auf `\<SERVER_URL>/apps/oauth/callback`.
+3. Kopieren Sie die generierte **Client ID** und das **Client Secret**.
+4. Öffnen Sie die installierte App in Twenty als Serveradministrator → setzen Sie die Werte in den entsprechenden `serverVariables`.
+5. Mitglieder des Arbeitsbereichs können dann Verbindungen im **Verbindungen**-Abschnitt der jeweiligen App hinzufügen.
+
+</Accordion>
+
+</AccordionGroup>
@@ -0,0 +1,48 @@
+---
+title: Objekte erweitern
+description: Fügen Sie Standard-Twenty-Objekten Felder hinzu (Person, Company, …) oder zu Objekten aus anderen Apps mit `defineField`.
+icon: wand-magic-sparkles
+---
+
+Verwenden Sie `defineField()`, um einem Objekt, das Ihnen nicht gehört, ein Feld hinzuzufügen – ein Standard-Twenty-Objekt wie Person oder Company oder ein Objekt, das von einer anderen installierten App bereitgestellt wird. Im Gegensatz zu Inline-Feldern, die innerhalb von [`defineObject`](/l/de/developers/extend/apps/data/objects) deklariert werden, benötigen eigenständige Felder einen `objectUniversalIdentifier`, um anzugeben, welches Objekt sie erweitern.
+
+```ts src/fields/company-loyalty-tier.field.ts
+import { defineField, FieldType } from 'twenty-sdk/define';
+
+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' },
+  ],
+});
+```
+
+## Hauptpunkte
+
+* Der `objectUniversalIdentifier` identifiziert das Zielobjekt. Für Standard-Twenty-Objekte importieren Sie die Konstante aus `twenty-sdk`:
+
+  ```ts
+  import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';
+
+  // STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier
+  // STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier
+  // STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.opportunity.universalIdentifier
+  // …
+  ```
+
+* Wenn Sie Felder **inline innerhalb von `defineObject()`** definieren, benötigen Sie `objectUniversalIdentifier` **nicht** – es wird vom übergeordneten Objekt geerbt.
+
+* `defineField()` ist die einzige Möglichkeit, Felder zu Objekten hinzuzufügen, die Sie nicht mit `defineObject()` erstellt haben.
+
+* Der Speicherort der Datei liegt bei Ihnen. Die Konvention ist `src/fields/\<name>.field.ts`, aber das SDK erkennt Felder überall in `src/`.
+
+## Hinzufügen einer Relation zu einem bestehenden Objekt
+
+Um ein Relationsfeld hinzuzufügen (z. B. zur Verknüpfung Ihres benutzerdefinierten Objekts mit einer Standard-`Person`), verwenden Sie `defineField()` mit `FieldType.RELATION`. Das Muster ist dasselbe wie bei Inline-Relationen, jedoch mit explizit gesetztem `objectUniversalIdentifier`. Siehe [Relations](/l/de/developers/extend/apps/data/relations) für das bidirektionale Muster.
@@ -0,0 +1,93 @@
+---
+title: Objekte
+description: Deklarieren Sie neue Datensatztypen — benutzerdefinierte Tabellen mit eigenen Feldern — mit defineObject.
+icon: table
+---
+
+Benutzerdefinierte **Objekte** sind neue Datensatztypen, die Ihre App zu einem Arbeitsbereich hinzufügt – Postkarte, Rechnung, Abonnement, alles, was spezifisch für Ihre Domäne ist. Jedes Objekt deklariert sein Schema (Felder, Relationen, Standardwerte) und einen stabilen universellen Bezeichner, der über Synchronisierungen und Deployments hinweg bestehen bleibt.
+
+```ts src/objects/post-card.object.ts
+import { defineObject, FieldType } from 'twenty-sdk/define';
+
+enum PostCardStatus {
+  DRAFT = 'DRAFT',
+  SENT = 'SENT',
+  DELIVERED = 'DELIVERED',
+  RETURNED = 'RETURNED',
+}
+
+export default defineObject({
+  universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
+  nameSingular: 'postCard',
+  namePlural: 'postCards',
+  labelSingular: 'Post Card',
+  labelPlural: 'Post Cards',
+  description: 'A post card object',
+  icon: 'IconMail',
+  fields: [
+    {
+      universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
+      name: 'content',
+      type: FieldType.TEXT,
+      label: 'Content',
+      description: "Postcard's content",
+      icon: 'IconAbc',
+    },
+    {
+      universalIdentifier: 'c6aa31f3-da76-4ac6-889f-475e226009ac',
+      name: 'recipientName',
+      type: FieldType.FULL_NAME,
+      label: 'Recipient name',
+      icon: 'IconUser',
+    },
+    {
+      universalIdentifier: '95045777-a0ad-49ec-98f9-22f9fc0c8266',
+      name: 'recipientAddress',
+      type: FieldType.ADDRESS,
+      label: 'Recipient address',
+      icon: 'IconHome',
+    },
+    {
+      universalIdentifier: '87b675b8-dd8c-4448-b4ca-20e5a2234a1e',
+      name: 'status',
+      type: FieldType.SELECT,
+      label: 'Status',
+      icon: 'IconSend',
+      defaultValue: `'${PostCardStatus.DRAFT}'`,
+      options: [
+        { value: PostCardStatus.DRAFT, label: 'Draft', position: 0, color: 'gray' },
+        { value: PostCardStatus.SENT, label: 'Sent', position: 1, color: 'orange' },
+        { value: PostCardStatus.DELIVERED, label: 'Delivered', position: 2, color: 'green' },
+        { value: PostCardStatus.RETURNED, label: 'Returned', position: 3, color: 'orange' },
+      ],
+    },
+    {
+      universalIdentifier: 'e06abe72-5b44-4e7f-93be-afc185a3c433',
+      name: 'deliveredAt',
+      type: FieldType.DATE_TIME,
+      label: 'Delivered at',
+      icon: 'IconCheck',
+      isNullable: true,
+      defaultValue: null,
+    },
+  ],
+});
+```
+
+## Hauptpunkte
+
+* Der `universalIdentifier` muss eindeutig und über Deployments hinweg stabil sein.
+* Jedes Feld benötigt `name`, `type`, `label` und einen eigenen stabilen `universalIdentifier`.
+* Das Array `fields` ist optional — Sie können Objekte ohne benutzerdefinierte Felder definieren.
+* Inline definierte Felder benötigen **kein** `objectUniversalIdentifier` – er wird vom übergeordneten Objekt geerbt. Verwenden Sie [`defineField()`](/l/de/developers/extend/apps/data/extending-objects), um Objekten Felder hinzuzufügen, die Ihnen nicht gehören.
+* Sie können mit `yarn twenty add object` neue Objekte erzeugen; der Assistent führt Sie durch Benennung, Felder und Beziehungen. Siehe [Architektur → Gerüste für Entitäten](/l/de/developers/extend/apps/getting-started/scaffolding).
+
+<Note>
+**Basisfelder werden automatisch hinzugefügt.** Wenn Sie ein benutzerdefiniertes Objekt definieren, erstellt Twenty Standardfelder wie `id`, `name`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy` und `deletedAt` für Sie. Sie müssen diese nicht in Ihrem `fields`-Array deklarieren – nur Ihre benutzerdefinierten Felder. Sie können ein Standardfeld überschreiben, indem Sie eines mit demselben Namen deklarieren, aber das ist nur selten eine gute Idee.
+</Note>
+
+## Was kommt als Nächstes
+
+* **Verbinden Sie dieses Objekt mit anderen** – siehe [Relationen](/l/de/developers/extend/apps/data/relations) für das bidirektionale Relationsmuster.
+* **Fügen Sie Objekten aus anderen Apps Felder hinzu** – siehe [Objekte erweitern](/l/de/developers/extend/apps/data/extending-objects) für `defineField()`.
+* **Zeigen Sie dieses Objekt in der UI an** – siehe [Ansichten](/l/de/developers/extend/apps/layout/views) und [Navigationsmenüeinträge](/l/de/developers/extend/apps/layout/navigation-menu-items), um es in der Seitenleiste zu platzieren.
@@ -0,0 +1,52 @@
+---
+title: Übersicht
+description: Gestalten Sie die Daten, die Ihre App zu einem Workspace hinzufügt – Objekte, Felder und Beziehungen.
+icon: database
+---
+
+Die **Datenebene** einer Twenty-App umfasst die Daten, die Ihre App zu einem Workspace *hinzufügt* – die neuen Datensatztypen, die sie deklariert, die Spalten, die sie zu bestehenden Objekten hinzufügt, und wie diese Datensätze miteinander verknüpft sind.
+
+```text
+┌──────────────────────────────────────────────────┐
+│ Object — a record type, e.g. PostCard            │
+│    ├─ Field     (name, type, label)              │
+│    ├─ Field                                      │
+│    └─ Relation  (link to another object)         │
+└──────────────────────────────────────────────────┘
+            │
+            ├── lives in your app, OR
+            │
+            ▼
+┌──────────────────────────────────────────────────┐
+│ Standard / other apps' objects                   │
+│    └─ Field added by your app via defineField    │
+└──────────────────────────────────────────────────┘
+```
+
+## In diesem Abschnitt
+
+<CardGroup cols={2}>
+  <Card title="Objekte" icon="table" href="/l/de/developers/extend/apps/data/objects">
+    `defineObject` – deklarieren Sie neue Datensatztypen mit eigenen Feldern.
+  </Card>
+  <Card title="Objekte erweitern" icon="wand-magic-sparkles" href="/l/de/developers/extend/apps/data/extending-objects">
+    `defineField` – fügen Sie Standardobjekten oder Objekten anderer Apps Felder hinzu.
+  </Card>
+  <Card title="Beziehungen" icon="diagram-project" href="/l/de/developers/extend/apps/data/relations">
+    Bidirektionale `MANY_TO_ONE`- / `ONE_TO_MANY`-Verbindungen zwischen Objekten.
+  </Card>
+</CardGroup>
+
+## Entitäten im Überblick
+
+| Entität       | Zweck                                                                                                                                                | Definiert mit                            |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| **Objekt**    | Ein neuer benutzerdefinierter Datensatztyp (z. B. PostCard, Invoice) mit eigenen Feldern                                                             | `defineObject()`                         |
+| **Feld**      | Eine Spalte in einem Objekt. Eigenständige Felder können Objekte erweitern, die Sie nicht erstellt haben (z. B. `loyaltyTier` zu Company hinzufügen) | `defineField()`                          |
+| **Beziehung** | Eine bidirektionale Verknüpfung zwischen zwei Objekten – beide Seiten werden als Felder deklariert                                                   | `defineField()` mit `FieldType.RELATION` |
+
+Das SDK erkennt diese zur Build-Zeit über eine AST-Analyse, sodass die Dateiorganisation Ihnen überlassen ist – die Konvention ist `src/objects/` und `src/fields/`. Stabile `universalIdentifier`-UUIDs verknüpfen alles über Deploys hinweg.
+
+<Note>
+Suchen Sie nach **Application Config** oder **Roles & Permissions**? Diese beschreiben die App selbst und nicht die Daten, die sie hinzufügt – sie befinden sich unter [Config](/l/de/developers/extend/apps/config/overview). Suchen Sie nach **Connections** (Linear, GitHub, Slack OAuth)? Diese existieren, um *von* Logikfunktionen aufgerufen zu werden, und befinden sich unter [Logic](/l/de/developers/extend/apps/logic/connections).
+</Note>
@@ -0,0 +1,160 @@
+---
+title: Beziehungen
+description: Objekte mit bidirektionalen MANY_TO_ONE-/ONE_TO_MANY-Relationen verbinden.
+icon: diagram-project
+---
+
+Relationen verbinden zwei Objekte miteinander. In Twenty sind Relationen stets **bidirektional** — jede Relation hat zwei Seiten, und jede Seite wird als Feld deklariert, das auf die andere verweist.
+
+| Beziehungstyp | Beschreibung                                                            | Fremdschlüssel vorhanden? |
+| ------------- | ----------------------------------------------------------------------- | ------------------------- |
+| `MANY_TO_ONE` | Viele Datensätze dieses Objekts verweisen auf einen Datensatz des Ziels | Ja (`joinColumnName`)     |
+| `ONE_TO_MANY` | Ein Datensatz dieses Objekts hat viele Datensätze des Ziels             | Nein (die inverse Seite)  |
+
+## Wie Relationen funktionieren
+
+Jede Relation erfordert **zwei Felder**, die sich gegenseitig referenzieren:
+
+1. Die **MANY_TO_ONE**-Seite — befindet sich auf dem Objekt, das den Fremdschlüssel hält.
+2. Die **ONE_TO_MANY**-Seite — befindet sich auf dem Objekt, dem die Sammlung gehört.
+
+Beide Felder verwenden `FieldType.RELATION` und verweisen über `relationTargetFieldMetadataUniversalIdentifier` gegenseitig aufeinander.
+
+## Beispiel: Postkarte hat viele Empfänger
+
+Eine `PostCard` kann an viele `PostCardRecipient`-Datensätze gesendet werden. Jeder Empfänger gehört genau zu einer Postkarte.
+
+**Schritt 1: Definieren Sie die ONE_TO_MANY-Seite auf PostCard** (die "eine" Seite):
+
+```ts src/fields/post-card-recipients-on-post-card.field.ts
+import { defineField, FieldType, RelationType } from 'twenty-sdk/define';
+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,
+  },
+});
+```
+
+**Schritt 2: Definieren Sie die MANY_TO_ONE-Seite auf PostCardRecipient** (die "viele" Seite — hält den Fremdschlüssel):
+
+```ts src/fields/post-card-on-post-card-recipient.field.ts
+import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk/define';
+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>
+**Zyklische Importe:** Beide Relationsfelder referenzieren gegenseitig den `universalIdentifier` des jeweils anderen. Um Probleme mit zyklischen Importen zu vermeiden, exportieren Sie Ihre Feld-IDs als benannte Konstanten aus jeder Datei und importieren Sie sie in der jeweils anderen. Das Build-System löst dies zur Kompilierzeit auf.
+</Note>
+
+## Relationen zu Standardobjekten
+
+Um eine Relation mit einem integrierten Twenty-Objekt (Person, Company usw.) zu erstellen, verwenden Sie `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`:
+
+```ts src/fields/person-on-self-hosting-user.field.ts
+import {
+  defineField,
+  FieldType,
+  RelationType,
+  OnDeleteAction,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk/define';
+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',
+  },
+});
+```
+
+## Eigenschaften von Relationsfeldern
+
+| Eigenschaft                                       | Erforderlich        | Beschreibung                                                                                                     |
+| ------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `type`                                            | Ja                  | Muss `FieldType.RELATION` sein                                                                                   |
+| `relationTargetObjectMetadataUniversalIdentifier` | Ja                  | Der `universalIdentifier` des Zielobjekts                                                                        |
+| `relationTargetFieldMetadataUniversalIdentifier`  | Ja                  | Der `universalIdentifier` des entsprechenden Felds auf dem Zielobjekt                                            |
+| `universalSettings.relationType`                  | Ja                  | `RelationType.MANY_TO_ONE` oder `RelationType.ONE_TO_MANY`                                                       |
+| `universalSettings.onDelete`                      | Nur für MANY_TO_ONE | Was passiert, wenn der referenzierte Datensatz gelöscht wird: `CASCADE`, `SET_NULL`, `RESTRICT` oder `NO_ACTION` |
+| `universalSettings.joinColumnName`                | Nur für MANY_TO_ONE | Datenbankspaltenname für den Fremdschlüssel (z. B. `postCardId`)                                                 |
+
+## Inline-Relationsfelder
+
+Sie können eine Relation auch direkt innerhalb von [`defineObject`](/l/de/developers/extend/apps/data/objects) deklarieren. Wenn inline, lassen Sie `objectUniversalIdentifier` weg — er wird vom übergeordneten Objekt geerbt:
+
+```ts
+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
+  ],
+});
+```
@@ -15,7 +15,7 @@ Front-Komponenten können an zwei Stellen innerhalb von Twenty gerendert werden:

 ## Einfaches Beispiel

-Der schnellste Weg, eine Front-Komponente in Aktion zu sehen, ist, sie als Befehl zu registrieren. Das Hinzufügen eines `command`-Felds mit `isPinned: true` lässt sie als Schnellaktionsschaltfläche oben rechts auf der Seite erscheinen — kein Seitenlayout erforderlich:
+Der schnellste Weg, eine Front-Komponente in Aktion zu sehen, ist, sie als **Befehlsmenüeintrag** zu registrieren. Verwende `defineCommandMenuItem` in einer separaten Datei, damit die Komponente als Schnellaktionsschaltfläche oben rechts auf der Seite erscheint:

 ```tsx src/front-components/hello-world.tsx
 import { defineFrontComponent } from 'twenty-sdk/define';
@@ -34,14 +34,20 @@ export default defineFrontComponent({
  name: 'hello-world',
  description: 'A simple front component',
  component: HelloWorld,
-  command: {
-    universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
-    shortLabel: 'Hello',
-    label: 'Hello World',
-    icon: 'IconBolt',
-    isPinned: true,
-    availabilityType: 'GLOBAL',
-  },
+});
+```
+
+```ts src/command-menu-items/hello-world.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
+  shortLabel: 'Hello',
+  label: 'Hello World',
+  icon: 'IconBolt',
+  isPinned: true,
+  availabilityType: 'GLOBAL',
+  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
 });
 ```

@@ -55,14 +61,13 @@ Klicken Sie darauf, um die Komponente inline zu rendern.

 ## Konfigurationsfelder

-| Feld                  | Erforderlich | Beschreibung                                                                             |
-| --------------------- | ------------ | ---------------------------------------------------------------------------------------- |
-| `universalIdentifier` | Ja           | Stabile eindeutige ID für diese Komponente                                               |
-| `component`           | Ja           | Eine React-Komponentenfunktion                                                           |
-| `name`                | Nein         | Anzeigename                                                                              |
-| `description`         | Nein         | Beschreibung dessen, was die Komponente macht                                            |
-| `isHeadless`          | Nein         | Auf `true` setzen, wenn die Komponente keine sichtbare UI hat (siehe unten)              |
-| `command`             | Nein         | Die Komponente als Befehl registrieren (siehe unten [Befehlsoptionen](#command-options)) |
+| Feld                  | Erforderlich | Beschreibung                                                                |
+| --------------------- | ------------ | --------------------------------------------------------------------------- |
+| `universalIdentifier` | Ja           | Stabile eindeutige ID für diese Komponente                                  |
+| `component`           | Ja           | Eine React-Komponentenfunktion                                              |
+| `name`                | Nein         | Anzeigename                                                                 |
+| `description`         | Nein         | Beschreibung dessen, was die Komponente macht                               |
+| `isHeadless`          | Nein         | Auf `true` setzen, wenn die Komponente keine sichtbare UI hat (siehe unten) |

 ## Eine Front-Komponente auf einer Seite platzieren

@@ -141,11 +146,17 @@ export default defineFrontComponent({
  description: 'Creates a task from the command menu',
  component: RunAction,
  isHeadless: true,
-  command: {
-    universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
-    label: 'Run my action',
-    icon: 'IconPlayerPlay',
-  },
+});
+```
+
+```ts src/command-menu-items/run-action.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
+  label: 'Run my action',
+  icon: 'IconPlayerPlay',
+  frontComponentUniversalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
 });
 ```

@@ -177,11 +188,6 @@ export default defineFrontComponent({
  description: 'Deletes a draft with confirmation',
  component: DeleteDraft,
  isHeadless: true,
-  command: {
-    universalIdentifier: 'b8c9d0e1-f2a3-4567-bcde-678901234567',
-    label: 'Delete draft',
-    icon: 'IconTrash',
-  },
 });
 ```

@@ -223,7 +229,8 @@ Verfügbare Hooks:
 | Hook                                          | Gibt zurück          | Beschreibung                                                                |
 | --------------------------------------------- | -------------------- | --------------------------------------------------------------------------- |
 | `useUserId()`                                 | `string` oder `null` | Die ID des aktuellen Benutzers                                              |
-| `useRecordId()`                               | `string` oder `null` | Die ID des aktuellen Datensatzes (wenn auf einer Datensatzseite platziert)  |
+| `useSelectedRecordIds()`                      | `Zeichenkette[]`     | Alle ausgewählten Datensatz-IDs (leeres Array, wenn keine ausgewählt sind)  |
+| `useRecordId()`                               | `string` oder `null` | **Veraltet.** Verwenden Sie stattdessen `useSelectedRecordIds()`            |
 | `useFrontComponentId()`                       | `string`             | Die ID dieser Komponenteninstanz                                            |
 | `useFrontComponentExecutionContext(selector)` | variiert             | Zugriff auf den vollständigen Ausführungskontext mit einer Selektorfunktion |

@@ -286,14 +293,84 @@ export default defineFrontComponent({
 });
 ```

-## Befehlsoptionen
+### Mit mehreren Datensätzen arbeiten

-Das Hinzufügen eines `command`-Felds zu `defineFrontComponent` registriert die Komponente im Befehlsmenü (Cmd+K). Wenn `isPinned` `true` ist, erscheint sie außerdem als Schnellaktionsschaltfläche oben rechts auf der Seite.
+Verwenden Sie `useSelectedRecordIds()`, um mehrere ausgewählte Datensätze zu verwalten. Dies ist nützlich für Stapelvorgänge:
+
+```tsx src/front-components/bulk-export.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { useSelectedRecordIds, numberOfSelectedRecords } from 'twenty-sdk/front-component';
+import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
+import { CoreApiClient } from 'twenty-sdk/clients';
+
+const BulkExport = () => {
+  const selectedRecordIds = useSelectedRecordIds();
+
+  const handleExport = async () => {
+    const client = new CoreApiClient();
+
+    for (const recordId of selectedRecordIds) {
+      await client.mutation({
+        updateTask: {
+          __args: { id: recordId, data: { exported: true } },
+          id: true,
+        },
+      });
+    }
+
+    await enqueueSnackbar({
+      message: `Exported ${selectedRecordIds.length} records`,
+      variant: 'success',
+    });
+
+    await closeSidePanel();
+  };
+
+  return (
+    <div style={{ padding: '20px' }}>
+      <p>Export {selectedRecordIds.length} selected record(s)?</p>
+      <button onClick={handleExport}>Export</button>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
+  name: 'bulk-export',
+  description: 'Export selected records',
+  component: BulkExport,
+  command: {
+    universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678902',
+    label: 'Bulk Export',
+    availabilityType: 'RECORD_SELECTION',
+    conditionalAvailabilityExpression: numberOfSelectedRecords > 0,
+  },
+});
+```
+
+## defineCommandMenuItem
+
+Verwende `defineCommandMenuItem`, um eine Front-Komponente im Befehlsmenü (Cmd+K) zu registrieren. Wenn `isPinned` `true` ist, erscheint sie außerdem als Schnellaktionsschaltfläche oben rechts auf der Seite.
+
+```ts src/command-menu-items/open-dashboard.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
+
+export default defineCommandMenuItem({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  label: 'Open Dashboard',
+  shortLabel: 'Dashboard',
+  icon: 'IconLayoutDashboard',
+  isPinned: true,
+  availabilityType: 'GLOBAL',
+  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
+});
+```

 | Feld                                    | Erforderlich | Beschreibung                                                                                                                                                                               |
 | --------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `universalIdentifier`                   | Ja           | Stabile eindeutige ID für den Befehl                                                                                                                                                       |
 | `label`                                 | Ja           | Vollständiges Label, das im Befehlsmenü (Cmd+K) angezeigt wird                                                                                                                             |
+| `frontComponentUniversalIdentifier`     | Ja           | Der `universalIdentifier` der Front-Komponente, die dieser Befehl öffnet                                                                                                                   |
 | `shortLabel`                            | Nein         | Kürzeres Label, das auf der angehefteten Schnellaktionsschaltfläche angezeigt wird                                                                                                         |
 | `icon`                                  | Nein         | Neben dem Label angezeigter Icon-Name (z. B. 'IconBolt', 'IconSend')                                                                                                                       |
 | `isPinned`                              | Nein         | Bei `true` wird der Befehl als Schnellaktionsschaltfläche oben rechts auf der Seite angezeigt                                                                                              |
@@ -305,30 +382,23 @@ Das Hinzufügen eines `command`-Felds zu `defineFrontComponent` registriert die

 Mit dem Feld `conditionalAvailabilityExpression` können Sie basierend auf dem aktuellen Seitenkontext steuern, wann ein Befehl sichtbar ist. Importieren Sie typisierte Variablen und Operatoren aus `twenty-sdk`, um Ausdrücke zu erstellen:

-```tsx
-import { defineFrontComponent } from 'twenty-sdk/define';
+```ts src/command-menu-items/bulk-update.command-menu-item.ts
+import { defineCommandMenuItem } from 'twenty-sdk/define';
 import {
-  pageType,
-  numberOfSelectedRecords,
  objectPermissions,
  everyEquals,
-  isDefined,
 } from 'twenty-sdk/front-component';

-export default defineFrontComponent({
+export default defineCommandMenuItem({
  universalIdentifier: '...',
-  name: 'bulk-action',
-  component: BulkAction,
-  command: {
-    universalIdentifier: '...',
-    label: 'Bulk Update',
-    availabilityType: 'RECORD_SELECTION',
-    conditionalAvailabilityExpression: everyEquals(
-      objectPermissions,
-      'canUpdateObjectRecords',
-      true,
-    ),
-  },
+  label: 'Bulk Update',
+  availabilityType: 'RECORD_SELECTION',
+  frontComponentUniversalIdentifier: '...',
+  conditionalAvailabilityExpression: everyEquals(
+    objectPermissions,
+    'canUpdateObjectRecords',
+    true,
+  ),
 });
 ```

@@ -4,48 +4,52 @@ icon: rocket
 description: Erstellen Sie in wenigen Minuten Ihre erste Twenty-App.
 ---

-## Was sind Apps?
-
-Apps ermöglichen es Ihnen, Twenty mit benutzerdefinierten Objekten, Feldern, Logikfunktionen, Frontend-Komponenten, KI-Fähigkeiten und mehr zu erweitern — alles als Code verwaltet. Anstatt alles über die UI zu konfigurieren, definieren Sie Ihr Datenmodell und Ihre Logik in TypeScript und stellen es in einem oder mehreren Workspaces bereit.
-
 ## Voraussetzungen

-Bevor Sie beginnen, stellen Sie sicher, dass Folgendes auf Ihrem Rechner installiert ist:
-
 * **Node.js 24+** — [Hier herunterladen](https://nodejs.org/)
-* **Yarn 4** — Wird mit Node.js über Corepack mitgeliefert. Aktivieren Sie es, indem Sie `corepack enable` ausführen
-* **Docker** — [Hier herunterladen](https://www.docker.com/products/docker-desktop/). Erforderlich, um eine lokale Twenty-Instanz auszuführen. Nicht erforderlich, wenn bereits ein Twenty-Server läuft.
+* **Yarn 4** — Wird mit Node.js über Corepack mitgeliefert. Aktivieren Sie es: `corepack enable`
+* **Docker** — [Hier herunterladen](https://www.docker.com/products/docker-desktop/). Erforderlich, um einen lokalen Twenty-Server auszuführen. Überspringen Sie dies, wenn Twenty bereits anderswo läuft.

-## Erstellen Sie Ihre erste App
+Das Erstellen einer Twenty-App umfasst drei Phasen. Das Scaffolding-Tool fasst sie zu einem einzigen Happy-Path-Befehl zusammen, aber jede Phase ist ein eigenes Konzept — wenn etwas fehlschlägt, hilft Ihnen das Wissen, in welcher Phase Sie sich befinden, zu erkennen, was zu beheben ist.

-### App-Gerüst erstellen
+| Phase                   | Was Sie tun                                             | Tool                          | Ergebnis                                             |
+| ----------------------- | ------------------------------------------------------- | ----------------------------- | ---------------------------------------------------- |
+| **1. Gerüst erstellen** | Den Quellcode der App erzeugen                          | `npx create-twenty-app`       | Ein TypeScript-Projekt auf der Festplatte            |
+| **2. Server starten**   | Einen Twenty-Server starten, in den synchronisiert wird | Docker + `yarn twenty server` | Eine laufende Twenty-Instanz                         |
+| **3. Synchronisieren**  | Ihren Code live mit dem Server synchronisieren          | `yarn twenty dev`             | Ihre Änderungen erscheinen in der Benutzeroberfläche |

-Öffnen Sie ein Terminal und führen Sie Folgendes aus:
+---
+
+## Phase 1 — Projektgerüst erstellen
+
+Erstellen Sie eine neue App aus der Vorlage:

 ```bash filename="Terminal"
 npx create-twenty-app@latest my-twenty-app
 ```

-Sie werden aufgefordert, einen Namen und eine Beschreibung für Ihre App einzugeben. Drücken Sie **Enter**, um die Standardwerte zu übernehmen.
+Sie werden nach einem Namen und einer Beschreibung gefragt — drücken Sie **Enter** für die Standardwerte. Dadurch wird ein TypeScript-Projekt in `my-twenty-app/` erzeugt, mit einer Startdatei `application-config.ts`, einer Standardrolle, einem CI-Workflow und einem Integrationstest.

-Dadurch wird ein neuer Ordner namens `my-twenty-app` mit allem erstellt, was Sie benötigen.
+**Nach dieser Phase:** Sie haben den Quellcode einer App auf Ihrem Rechner. Es läuft noch nicht — das ist Phase 2.

-### Lokale Twenty-Instanz einrichten
+---

-Das Scaffolding-Tool fragt:
+## Phase 2 — Einen lokalen Twenty-Server starten
+
+Ihre App benötigt einen Twenty-Server, in den sie synchronisieren kann. Der Server ist eine vollständige Twenty-Instanz — UI, GraphQL-API, PostgreSQL — die lokal in Docker läuft. Ihr lokaler Code lädt seine Definitionen auf diesen Server hoch, wodurch sie in der Benutzeroberfläche erscheinen.
+
+Das Scaffolding-Tool bietet an, einen für Sie zu starten:

 > **Möchten Sie eine lokale Twenty-Instanz einrichten?**

-* **Geben Sie `yes` ein** (empfohlen) — Dadurch wird das Docker-Image `twenty-app-dev` heruntergeladen und ein lokaler Twenty-Server auf Port `2020` gestartet. Stellen Sie sicher, dass Docker läuft, bevor Sie fortfahren.
-* **Geben Sie `no` ein** — Wählen Sie dies, wenn bereits ein Twenty-Server lokal läuft.
+* **Ja (empfohlen)** — lädt das Docker-Image `twentycrm/twenty-app-dev` herunter und startet es auf Port `2020`. Stellen Sie sicher, dass Docker läuft.
+* **Nein** — wählen Sie dies, wenn Sie bereits einen Twenty-Server haben, mit dem Sie sich verbinden möchten. Sie können die Verbindung später mit `yarn twenty remote add` herstellen.

 <div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/start-instance.png" alt="Soll die lokale Instanz gestartet werden?" />
 </div>

-### Melden Sie sich bei Ihrem Arbeitsbereich an
-
-Anschließend öffnet sich ein Browserfenster mit der Twenty-Anmeldeseite. Melden Sie sich mit dem vorab eingerichteten Demo-Konto an:
+Sobald der Server läuft, öffnet sich ein Browser zur Anmeldung. Verwenden Sie das vorab eingerichtete Demo-Konto:

 * **E-Mail:** `tim@apple.dev`
 * **Passwort:** `tim@apple.dev`
@@ -54,83 +58,81 @@ Anschließend öffnet sich ein Browserfenster mit der Twenty-Anmeldeseite. Melde
  <img src="/images/docs/developers/extends/apps/login.png" alt="Twenty-Anmeldebildschirm" />
 </div>

-### Autorisieren Sie die App
-
-Nach der Anmeldung sehen Sie einen Autorisierungsbildschirm. Dadurch kann Ihre App mit Ihrem Arbeitsbereich interagieren.
-
-Klicken Sie auf **Authorize**, um fortzufahren.
+Klicken Sie auf dem nächsten Bildschirm auf **Authorize** — dadurch erhält die CLI Zugriff auf Ihren Arbeitsbereich.

 <div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty-CLI-Autorisierungsbildschirm" />
 </div>

-Nach der Autorisierung bestätigt Ihr Terminal, dass alles eingerichtet ist.
+Ihr Terminal bestätigt, dass alles eingerichtet ist.

 <div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App-Gerüst erfolgreich erstellt" />
 </div>

-### Beginnen Sie mit der Entwicklung
+**Nach dieser Phase:** Sie haben einen laufenden Twenty-Server unter [http://localhost:2020](http://localhost:2020), und Ihre CLI ist autorisiert, mit ihm zu synchronisieren.

-Wechseln Sie in Ihren neuen App-Ordner und starten Sie den Entwicklungsserver:
+<Note>
+Wenn Docker nicht installiert ist oder nicht läuft, zeigt das Scaffolding-Tool den richtigen Startbefehl für Ihr Betriebssystem an. Sobald Docker läuft, können Sie mit `yarn twenty server start` fortfahren — ein erneutes Scaffolding ist nicht nötig.
+</Note>
+
+---
+
+## Phase 3 — Ihre Änderungen synchronisieren
+
+Das ist die innere Schleife, in der Sie die meiste Zeit verbringen werden.

 ```bash filename="Terminal"
 cd my-twenty-app
 yarn twenty dev
 ```

-Dadurch werden Ihre Quelldateien überwacht, bei jeder Änderung neu gebaut und Ihre App automatisch mit dem lokalen Twenty-Server synchronisiert. In Ihrem Terminal sollte eine Live-Statusanzeige angezeigt werden.
+Dies überwacht `src/`, baut bei jeder Änderung neu und synchronisiert das Ergebnis mit dem Server. Bearbeiten Sie eine Datei, speichern Sie, und innerhalb einer Sekunde spiegelt der Server die Änderung wider. Sie sehen eine Live-Statusanzeige in Ihrem Terminal.

-Für ausführlichere Ausgaben (Build-Protokolle, Sync-Anfragen, Fehlerspuren) verwenden Sie das Flag `--verbose`:
-
-```bash filename="Terminal"
-yarn twenty dev --verbose
-```
-
-<Warning>
-Der Dev-Modus ist nur auf Twenty-Instanzen verfügbar, die im Entwicklungsmodus laufen (`NODE_ENV=development`). Produktionsinstanzen lehnen Dev-Synchronisierungsanfragen ab. Verwenden Sie `yarn twenty deploy`, um auf Produktionsservern bereitzustellen — Details finden Sie unter [Apps veröffentlichen](/l/de/developers/extend/apps/publishing).
-</Warning>
+Für ausführlichere Ausgaben (Build-Protokolle, Sync-Anfragen, Fehlerspuren) fügen Sie `--verbose` hinzu.

 <div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/dev.png" alt="Terminalausgabe im Dev-Modus" />
 </div>

-#### Einmalige Synchronisierung mit `yarn twenty dev --once`
-
-Wenn Sie keinen Watcher im Hintergrund ausführen lassen möchten (zum Beispiel in einer CI-Pipeline, einem Git-Hook oder einem skriptgesteuerten Workflow), geben Sie das Flag `--once` an. Es führt dieselbe Pipeline aus wie `yarn twenty dev` — Build-Manifest erstellen, Dateien bündeln, hochladen, synchronisieren, den typisierten API-Client neu generieren — beendet sich jedoch, **sobald die Synchronisierung abgeschlossen ist**:
-
-```bash filename="Terminal"
-yarn twenty dev --once
-```
-
-| Befehl                   | Verhalten                                                                                                               | Wann verwenden                                                                                           |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `yarn twenty dev`        | Überwacht Ihre Quelldateien und synchronisiert bei jeder Änderung erneut. Läuft weiter, bis Sie es stoppen.             | Interaktive lokale Entwicklung — Sie möchten das Live-Status-Panel und eine sofortige Feedback-Schleife. |
-| `yarn twenty dev --once` | Führt einen einzelnen Build + Sync aus und beendet sich anschließend mit Code `0` bei Erfolg oder `1` bei einem Fehler. | Skripte, CI, Pre-Commit-Hooks, KI-Agenten und jeder nicht-interaktive Workflow.                          |
-
-Beide Modi erfordern einen Twenty-Server, der im Entwicklungsmodus läuft, und ein authentifiziertes Remote — es gelten dieselben Voraussetzungen.
-
-### Sehen Sie sich Ihre App in Twenty an
-
-Öffnen Sie [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) in Ihrem Browser. Navigieren Sie zu **Settings > Apps** und wählen Sie die Registerkarte **Developer**. Unter **Your Apps** sollte Ihre App aufgeführt sein:
+Öffnen Sie [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Unter **Your Apps** sollte Ihre App angezeigt werden.

 <div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Liste &#x22;Your Apps&#x22;, die &#x22;My twenty app&#x22; anzeigt" />
 </div>

-Klicken Sie auf **My twenty app**, um die **Anwendungsregistrierung** zu öffnen. Eine Registrierung ist ein Servereintrag, der Ihre App beschreibt — ihren Namen, den eindeutigen Bezeichner, OAuth-Zugangsdaten und die Quelle (lokal, npm oder Tarball). Sie befindet sich auf dem Server, nicht in einem bestimmten Arbeitsbereich. Wenn Sie eine App in einen Arbeitsbereich installieren, erstellt Twenty eine arbeitsbereichsbezogene Anwendung, die auf diese Registrierung verweist. Eine Registrierung kann in mehreren Arbeitsbereichen auf demselben Server installiert werden.
+Klicken Sie auf **My twenty app**, um die **Anwendungsregistrierung** anzuzeigen — ein serverseitiger Datensatz, der Ihre App beschreibt (Name, Bezeichner, OAuth-Anmeldedaten, Quelle). Eine Registrierung kann in mehreren Arbeitsbereichen auf demselben Server installiert werden.

 <div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Details der Anwendungsregistrierung" />
 </div>

-Klicken Sie auf **View installed app**, um die installierte App anzuzeigen. Die Registerkarte **About** zeigt die aktuelle Version und Verwaltungsoptionen:
+Klicken Sie auf **View installed app**, um die Installation im Arbeitsbereich anzuzeigen. Die Registerkarte **About** zeigt die Version und Verwaltungsoptionen.

 <div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Installierte App" />
 </div>

-Alles erledigt! Bearbeiten Sie eine beliebige Datei in `src/`, und die Änderungen werden automatisch übernommen.
+**Nach dieser Phase:** Sie haben eine Live-Entwicklungsschleife. Bearbeiten Sie eine beliebige Datei in `src/`, und sie erscheint in der Benutzeroberfläche.
+
+### Einmalige Synchronisierung für CI und Skripte
+
+Verwenden Sie `--once`, um einen einzelnen Build + Sync auszuführen und zu beenden — gleiche Pipeline, kein Watcher:
+
+```bash filename="Terminal"
+yarn twenty dev --once
+```
+
+| Befehl                   | Verhalten                                                                          | Wann verwenden                                                |
+| ------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `yarn twenty dev`        | Überwacht und synchronisiert bei jeder Änderung erneut. Läuft, bis Sie es stoppen. | Interaktive lokale Entwicklung.                               |
+| `yarn twenty dev --once` | Einmaliger Build + Sync, beendet sich mit `0` bei Erfolg, mit `1` bei Fehler.      | CI, Pre-Commit-Hooks, KI-Agenten, skriptgesteuerte Workflows. |
+
+Beide Modi benötigen einen Server im Entwicklungsmodus und eine authentifizierte Remote-Verbindung.
+
+<Warning>
+Der Dev-Modus ist nur auf Twenty-Instanzen verfügbar, die im Entwicklungsmodus laufen (`NODE_ENV=development`). Produktionsinstanzen lehnen Dev-Sync-Anfragen ab — verwenden Sie `yarn twenty deploy`, um auf Produktionsserver bereitzustellen. Siehe [Apps veröffentlichen](/l/de/developers/extend/apps/publishing).
+</Warning>

 ---

@@ -138,136 +140,112 @@ Alles erledigt! Bearbeiten Sie eine beliebige Datei in `src/`, und die Änderung

 Apps bestehen aus **Entitäten** — jede ist als TypeScript-Datei mit einem einzigen `export default` definiert:

-| Entität                    | Was sie macht                                                                                                        |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| **Objekte & Felder**       | Definieren Sie benutzerdefinierte Datenmodelle (wie Post Card, Invoice) mit typisierten Feldern                      |
-| **Logikfunktionen**        | Serverseitige TypeScript-Funktionen, die durch HTTP-Routen, Cron-Zeitpläne oder Datenbankereignisse ausgelöst werden |
-| **Frontend-Komponenten**   | React-Komponenten, die in der UI von Twenty gerendert werden (Seitenleiste, Widgets, Befehlsmenü)                    |
-| **Fähigkeiten & Agenten**  | KI-Funktionen — wiederverwendbare Anweisungen und autonome Assistenten                                               |
-| **Ansichten & Navigation** | Vorkonfigurierte Listenansichten und Seitenleisteneinträge für Ihre Objekte                                          |
-| **Seitenlayouts**          | Benutzerdefinierte Datensatz-Detailseiten mit Tabs und Widgets                                                       |
+| Entität                    | Was sie macht                                                                                     |
+| -------------------------- | ------------------------------------------------------------------------------------------------- |
+| **Objekte & Felder**       | Benutzerdefinierte Datenmodelle (Postkarte, Rechnung usw.) mit typisierten Feldern                |
+| **Logikfunktionen**        | Serverseitiges TypeScript, ausgelöst durch HTTP-Routen, Cron-Zeitpläne oder Datenbankereignisse   |
+| **Frontend-Komponenten**   | React-Komponenten, die in der UI von Twenty gerendert werden (Seitenleiste, Widgets, Befehlsmenü) |
+| **Fähigkeiten & Agenten**  | KI-Funktionen — wiederverwendbare Anweisungen und autonome Assistenten                            |
+| **Ansichten & Navigation** | Vorkonfigurierte Listenansichten und Seitenleisteneinträge                                        |
+| **Seitenlayouts**          | Benutzerdefinierte Datensatz-Detailseiten mit Tabs und Widgets                                    |

-Wechseln Sie zu [Apps erstellen](/l/de/developers/extend/apps/building) für eine ausführliche Anleitung zu jedem Entitätstyp.
-
---
+Vollständige Referenz: [Apps entwickeln](/l/de/developers/extend/apps/building).

 ## Projektstruktur

-Der Scaffolder erzeugt die folgende Verzeichnisstruktur:
-
 ```text filename="my-twenty-app/"
 my-twenty-app/
  package.json
-  yarn.lock
-  .gitignore
-  .nvmrc
-  .yarnrc.yml
-  .oxlintrc.json
-  tsconfig.json
-  tsconfig.spec.json                          # TypeScript config for tests
-  vitest.config.ts                            # Vitest test runner configuration
-  LLMS.md
-  README.md
-  .github/
-    └── workflows/
-        └── ci.yml                            # GitHub Actions CI workflow
-  public/                                     # Public assets (images, fonts, etc.)
  src/
-  ├── application-config.ts                   # Required — main application configuration
-  ├── default-role.ts                         # Default role for logic functions
-  ├── constants/
-  │   └── universal-identifiers.ts            # Auto-generated UUIDs and app metadata
-  └── __tests__/
-      ├── setup-test.ts                       # Test setup (server health check, config)
-      └── app-install.integration-test.ts     # Integration test
+    application-config.ts                   # Required — your app's entry point
+    default-role.ts                         # Permissions for logic functions
+    constants/
+      universal-identifiers.ts              # Auto-generated UUIDs and metadata
+    __tests__/
+      setup-test.ts
+      app-install.integration-test.ts
+  .github/workflows/ci.yml                  # GitHub Actions
+  public/                                   # Static assets
+  vitest.config.ts                          # Test runner config
+  tsconfig.json, tsconfig.spec.json
+  .nvmrc, .yarnrc.yml, .oxlintrc.json
+  README.md, LLMS.md
 ```

+| Datei / Ordner                           | Zweck                                                                           |
+| ---------------------------------------- | ------------------------------------------------------------------------------- |
+| `src/application-config.ts`              | **Erforderlich.** Die Hauptkonfigurationsdatei für Ihre App.                    |
+| `src/default-role.ts`                    | Standardrolle, die steuert, worauf Ihre Logikfunktionen zugreifen können.       |
+| `src/constants/universal-identifiers.ts` | Automatisch erzeugte UUIDs und Metadaten (Anzeigename, Beschreibung).           |
+| `src/__tests__/`                         | Integrationstests (Setup + Beispieltest).                                       |
+| `public/`                                | Statische Assets (Bilder, Schriftarten), die mit Ihrer App ausgeliefert werden. |
+
 ### Mit einem Beispiel beginnen

-Um mit einem umfassenderen Beispiel mit benutzerdefinierten Objekten, Feldern, Logikfunktionen, Frontend-Komponenten und mehr zu starten, verwenden Sie die Option `--example`:
+Verwenden Sie `--example`, um mit einem vollständigeren Projekt zu starten (benutzerdefinierte Objekte, Felder, Logikfunktionen, Front-End-Komponenten):

 ```bash filename="Terminal"
 npx create-twenty-app@latest my-twenty-app --example postcard
 ```

-Die Beispiele stammen aus dem Verzeichnis [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) auf GitHub. Sie können auch einzelne Entitäten in einem bestehenden Projekt mit `yarn twenty add` erzeugen (siehe [Apps erstellen](/l/de/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add)).
+Die Beispiele befinden sich unter [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples). Sie können auch einzelne Entitäten in einem bestehenden Projekt mit `yarn twenty add` erzeugen — siehe [Apps entwickeln](/l/de/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add).

-### Wichtige Dateien
+---

-| Datei / Ordner                           | Zweck                                                                                                                                                              |
-| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `package.json`                           | Deklariert den App-Namen, die Version und Abhängigkeiten. Enthält ein `twenty`-Skript, sodass Sie `yarn twenty help` ausführen können, um alle Befehle anzuzeigen. |
-| `src/application-config.ts`              | **Erforderlich.** Die Hauptkonfigurationsdatei für Ihre App.                                                                                                       |
-| `src/default-role.ts`                    | Standardrolle, die steuert, worauf Ihre Logikfunktionen zugreifen können.                                                                                          |
-| `src/constants/universal-identifiers.ts` | Automatisch erzeugte UUIDs und App-Metadaten (Anzeigename, Beschreibung).                                                                                          |
-| `src/__tests__/`                         | Integrationstests (Setup + Beispieltest).                                                                                                                          |
-| `public/`                                | Statische Assets (Bilder, Schriftarten), die mit Ihrer App ausgeliefert werden.                                                                                    |
+## Lokalen Server verwalten

-## Lokaler Entwicklungsserver
+Verwenden Sie `yarn twenty server`, um den lokalen Twenty-Container zu steuern:

-Der Scaffolder hat bereits einen lokalen Twenty-Server für Sie gestartet. Um ihn später zu verwalten, verwenden Sie `yarn twenty server`:
+| Befehl                                 | Was es tut                                          |
+| -------------------------------------- | --------------------------------------------------- |
+| `yarn twenty server start`             | Server starten (lädt das Image bei Bedarf herunter) |
+| `yarn twenty server start --port 3030` | Auf einem benutzerdefinierten Port starten          |
+| `yarn twenty server stop`              | Server stoppen (Daten bleiben erhalten)             |
+| `yarn twenty server status`            | URL, Version und Anmeldedaten anzeigen              |
+| `yarn twenty server logs`              | Serverprotokolle streamen                           |
+| `yarn twenty server reset`             | Alle Daten löschen und neu starten                  |
+| `yarn twenty server upgrade`           | Das neueste `twenty-app-dev`-Image herunterladen    |
+| `yarn twenty server upgrade 2.2.0`     | Auf eine bestimmte Version aktualisieren            |

-| Befehl                                 | Beschreibung                                                                     |
-| -------------------------------------- | -------------------------------------------------------------------------------- |
-| `yarn twenty server start`             | Lokalen Server starten (lädt das Image bei Bedarf herunter)                      |
-| `yarn twenty server start --port 3030` | Auf einem benutzerdefinierten Port starten                                       |
-| `yarn twenty server start --test`      | Starten Sie eine separate Testinstanz auf Port 2021                              |
-| `yarn twenty server stop`              | Server stoppen (Daten bleiben erhalten)                                          |
-| `yarn twenty server status`            | Serverstatus, URL, Version und Anmeldedaten anzeigen                             |
-| `yarn twenty server logs`              | Serverprotokolle streamen                                                        |
-| `yarn twenty server logs --lines 100`  | Die letzten 100 Protokollzeilen anzeigen                                         |
-| `yarn twenty server reset`             | Alle Daten löschen und neu starten                                               |
-| `yarn twenty server upgrade`           | Das neueste `twenty-app-dev`-Image herunterladen und den Container neu erstellen |
-| `yarn twenty server upgrade 2.2.0`     | Auf eine bestimmte Version aktualisieren                                         |
-
-Daten bleiben über Neustarts hinweg in zwei Docker-Volumes bestehen (`twenty-app-dev-data` für PostgreSQL, `twenty-app-dev-storage` für Dateien). Verwenden Sie `reset`, um alles zu löschen und neu zu beginnen.
+Daten bleiben über Neustarts hinweg in zwei Docker-Volumes bestehen (`twenty-app-dev-data` für PostgreSQL, `twenty-app-dev-storage` für Dateien). Verwenden Sie `reset`, um alles zu löschen.

 ### Aktualisieren des Server-Images

-Verwenden Sie `yarn twenty server upgrade`, um nach einem neueren `twenty-app-dev`-Docker-Image zu suchen und den Container zu aktualisieren. Der Befehl lädt das Image herunter, vergleicht es mit dem, aus dem der Container erstellt wurde, und erstellt den Container nur neu, wenn sich das Image tatsächlich geändert hat. Ihre Daten-Volumes bleiben erhalten — nur der Container wird ersetzt.
+`yarn twenty server upgrade` lädt das neueste Image herunter, vergleicht die Digests und erstellt den Container nur neu, wenn sich tatsächlich etwas geändert hat. Die Volumes bleiben erhalten — nur der Container wird ersetzt. Wenn ein neues Image heruntergeladen wurde und der Container lief, startet das Upgrade automatisch einen neuen Container; führen Sie anschließend `yarn twenty server start` aus, um zu warten, bis er betriebsbereit ist.

 ```bash filename="Terminal"
-# Upgrade to the latest version (skips recreation if already up to date)
-yarn twenty server upgrade
-
-# Upgrade to a specific version
-yarn twenty server upgrade 2.2.0
+yarn twenty server upgrade            # Latest
+yarn twenty server upgrade 2.2.0      # Specific version
 ```

-Wenn ein neueres Image verfügbar ist und der Container lief, startet der Upgrade-Befehl automatisch einen neuen Container mit dem aktualisierten Image. Führen Sie anschließend `yarn twenty server start` aus, um zu warten, bis er betriebsbereit ist. Wenn sich das Image nicht geändert hat, bleibt der Container unverändert.
+Überprüfen Sie die laufende Version mit `yarn twenty server status` (dies zeigt die im Container enthaltene `APP_VERSION` an).

-Sie können die laufende Version mit `yarn twenty server status` überprüfen; dieser Befehl zeigt die `APP_VERSION` des Containers an.
+### Eine parallele Testinstanz ausführen

-### Eine Testinstanz ausführen
+Übergeben Sie `--test` an jeden `server`-Befehl, um eine zweite, vollständig isolierte Instanz zu verwalten — nützlich für Integrationstests oder Experimente, ohne Ihre Hauptentwicklungsdaten anzutasten:

-Übergeben Sie `--test` an jeden `server`-Befehl, um eine zweite, vollständig isolierte Instanz zu verwalten — nützlich, um Integrationstests auszuführen oder zu experimentieren, ohne Ihre Hauptentwicklungsdaten anzutasten.
+| Befehl                              | Was es tut                                        |
+| ----------------------------------- | ------------------------------------------------- |
+| `yarn twenty server start --test`   | Die Testinstanz starten (standardmäßig Port 2021) |
+| `yarn twenty server stop --test`    | Anhalten                                          |
+| `yarn twenty server status --test`  | Status anzeigen                                   |
+| `yarn twenty server logs --test`    | Protokolle streamen                               |
+| `yarn twenty server reset --test`   | Daten löschen                                     |
+| `yarn twenty server upgrade --test` | Image aktualisieren                               |

-| Befehl                              | Beschreibung                                                   |
-| ----------------------------------- | -------------------------------------------------------------- |
-| `yarn twenty server start --test`   | Die Testinstanz starten (standardmäßig Port 2021)              |
-| `yarn twenty server stop --test`    | Die Testinstanz stoppen                                        |
-| `yarn twenty server status --test`  | Status, URL, Version und Anmeldedaten der Testinstanz anzeigen |
-| `yarn twenty server logs --test`    | Protokolle der Testinstanz streamen                            |
-| `yarn twenty server reset --test`   | Alle Testdaten löschen und neu starten                         |
-| `yarn twenty server upgrade --test` | Das Image der Testinstanz aktualisieren                        |
+Die Testinstanz hat ihren eigenen Container (`twenty-app-dev-test`), eigene Volumes (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) und eine eigene Konfiguration — sie läuft parallel zu Ihrer Hauptinstanz ohne Konflikte. Kombinieren Sie `--test` mit `--port`, um den Port 2021 zu überschreiben.

-Die Testinstanz läuft in einem eigenen Docker-Container (`twenty-app-dev-test`) mit dedizierten Volumes (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) und eigener Konfiguration, sodass sie parallel zu Ihrer Hauptinstanz ohne Konflikte ausgeführt werden kann. Kombinieren Sie `--test` mit `--port`, um den Standardport 2021 zu überschreiben.
-
-<Note>
-  Der Server erfordert, dass **Docker** läuft. Wenn der Fehler "Docker not running" angezeigt wird, stellen Sie sicher, dass Docker Desktop (oder der Docker-Daemon) gestartet ist.
-</Note>
+---

 ## Manuelle Einrichtung (ohne Scaffolder)

-Wenn Sie die Einrichtung lieber selbst vornehmen möchten, anstatt `create-twenty-app` zu verwenden, können Sie dies in zwei Schritten tun.
-
-**1. Fügen Sie `twenty-sdk` und `twenty-client-sdk` als Abhängigkeiten hinzu:**
+Überspringen Sie das Scaffolding-Tool, wenn Sie das SDK zu einem bestehenden Projekt hinzufügen:

 ```bash filename="Terminal"
 yarn add twenty-sdk twenty-client-sdk
 ```

-**2. Fügen Sie Ihrer `package.json` ein `twenty`-Skript hinzu:**
+Fügen Sie der `package.json` das Skript hinzu:

 ```json filename="package.json"
 {
@@ -277,19 +255,19 @@ yarn add twenty-sdk twenty-client-sdk
 }
 ```

-Sie können jetzt `yarn twenty dev`, `yarn twenty help` und alle anderen Befehle ausführen.
+Sie können jetzt `yarn twenty dev`, `yarn twenty server start` und den Rest ausführen.

 <Note>
-Installieren Sie `twenty-sdk` nicht global. Verwenden Sie es immer als lokale Projektabhängigkeit, damit jedes Projekt seine eigene Version festlegen kann.
+Installieren Sie `twenty-sdk` nicht global — fixieren Sie es pro Projekt, damit jede App ihre eigene Version verwendet.
 </Note>

+---
+
 ## Fehlerbehebung

-Wenn Probleme auftreten:
+* **Docker-Fehler** — Stellen Sie sicher, dass Docker Desktop (oder der Daemon) läuft, bevor Sie `yarn twenty server start` ausführen. Die Fehlermeldung zeigt den richtigen Startbefehl für Ihr Betriebssystem an.
+* **Falsche Node-Version** — 24+ erforderlich. Prüfen Sie mit `node -v`.
+* **Yarn 4 fehlt** — Führen Sie `corepack enable` aus.
+* **Abhängigkeiten defekt** — `rm -rf node_modules && yarn install`.

-* Stellen Sie sicher, dass **Docker läuft**, bevor Sie das Scaffolding-Tool mit einer lokalen Instanz starten.
-* Stellen Sie sicher, dass Sie **Node.js 24+** verwenden (`node -v` zur Überprüfung).
-* Stellen Sie sicher, dass **Corepack aktiviert ist** (`corepack enable`), damit Yarn 4 verfügbar ist.
-* Versuchen Sie, `node_modules` zu löschen und `yarn install` erneut auszuführen, wenn Abhängigkeiten fehlerhaft erscheinen.
-
-Hängen Sie immer noch fest? Bitten Sie im [Twenty-Discord](https://discord.com/channels/1130383047699738754/1130386664812982322) um Hilfe.
+Hängen Sie fest? Bitten Sie im [Twenty-Discord](https://discord.com/channels/1130383047699738754/1130386664812982322) um Hilfe.
--- a/Show More
+++ b/Show More