Skip backfill record page layouts for missing standard objects (#19799)

Previously this blocked users who only had SMTP configured to send
outbound emails, this fixes it by making messageChannel and persist
layer conditional

.claude-pr/.mcp.json

@@ -0,0 +1,22 @@
+{
+  "mcpServers": {
+    "postgres": {
+      "type": "stdio",
+      "command": "bash",
+      "args": ["-c", "source packages/twenty-server/.env && npx -y @modelcontextprotocol/server-postgres \"$PG_DATABASE_URL\""],
+      "env": {}
+    },
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@playwright/mcp@latest", "--no-sandbox", "--headless"],
+      "env": {}
+    },
+    "context7": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"],
+      "env": {}
+    }
+  }
+}

.claude-pr/CLAUDE.md

@@ -0,0 +1,223 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Twenty is an open-source CRM built with modern technologies in a monorepo structure. The codebase is organized as an Nx workspace with multiple packages.
+
+## Key Commands
+
+### Development
+```bash
+# Start development environment (frontend + backend + worker)
+yarn start
+
+# Individual package development
+npx nx start twenty-front     # Start frontend dev server
+npx nx start twenty-server    # Start backend server
+npx nx run twenty-server:worker  # Start background worker
+```
+
+### Testing
+```bash
+# Preferred: run a single test file (fast)
+npx jest path/to/test.test.ts --config=packages/PROJECT/jest.config.mjs
+
+# Run all tests for a package
+npx nx test twenty-front      # Frontend unit tests
+npx nx test twenty-server     # Backend unit tests
+npx nx run twenty-server:test:integration:with-db-reset  # Integration tests with DB reset
+# To run an indivual test or a pattern of tests, use the following command:
+cd packages/{workspace} && npx jest "pattern or filename"
+
+# Storybook
+npx nx storybook:build twenty-front
+npx nx storybook:test twenty-front
+
+# When testing the UI end to end, click on "Continue with Email" and use the prefilled credentials.
+```
+
+### Code Quality
+```bash
+# Linting (diff with main - fastest, always prefer this)
+npx nx lint:diff-with-main twenty-front
+npx nx lint:diff-with-main twenty-server
+npx nx lint:diff-with-main twenty-front --configuration=fix  # Auto-fix
+
+# Linting (full project - slower, use only when needed)
+npx nx lint twenty-front
+npx nx lint twenty-server
+
+# Type checking
+npx nx typecheck twenty-front
+npx nx typecheck twenty-server
+
+# Format code
+npx nx fmt twenty-front
+npx nx fmt twenty-server
+```
+
+### Build
+```bash
+# Build packages (twenty-shared must be built first)
+npx nx build twenty-shared
+npx nx build twenty-front
+npx nx build twenty-server
+```
+
+### Database Operations
+```bash
+# Database management
+npx nx database:reset twenty-server         # Reset database
+npx nx run twenty-server:database:init:prod # Initialize database
+npx nx run twenty-server:database:migrate:prod # Run instance commands (fast only)
+
+# Generate an instance command (fast or slow)
+npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>
+```
+
+### Database Inspection (Postgres MCP)
+
+A read-only Postgres MCP server is configured in `.mcp.json`. Use it to:
+- Inspect workspace data, metadata, and object definitions while developing
+- Verify migration results (columns, types, constraints) after running migrations
+- Explore the multi-tenant schema structure (core, metadata, workspace-specific schemas)
+- Debug issues by querying raw data to confirm whether a bug is frontend, backend, or data-level
+- Inspect metadata tables to debug GraphQL schema generation issues
+
+This server is read-only — for write operations (reset, migrations, sync), use the CLI commands above.
+
+### GraphQL
+```bash
+# Generate GraphQL types (run after schema changes)
+npx nx run twenty-front:graphql:generate
+npx nx run twenty-front:graphql:generate --configuration=metadata
+```
+
+## Architecture Overview
+
+### Tech Stack
+- **Frontend**: React 18, TypeScript, Jotai (state management), Linaria (styling), Vite
+- **Backend**: NestJS, TypeORM, PostgreSQL, Redis, GraphQL (with GraphQL Yoga)
+- **Monorepo**: Nx workspace managed with Yarn 4
+
+### Package Structure
+```
+packages/
+├── twenty-front/          # React frontend application
+├── twenty-server/         # NestJS backend API
+├── 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-zapier/         # Zapier integration
+└── twenty-e2e-testing/    # Playwright E2E tests
+```
+
+### Key Development Principles
+- **Functional components only** (no class components)
+- **Named exports only** (no default exports)
+- **Types over interfaces** (except when extending third-party interfaces)
+- **String literals over enums** (except for GraphQL enums)
+- **No 'any' type allowed** — strict TypeScript enforced
+- **Event handlers preferred over useEffect** for state updates
+- **Props down, events up** — unidirectional data flow
+- **Composition over inheritance**
+- **No abbreviations** in variable names (`user` not `u`, `fieldMetadata` not `fm`)
+
+### Naming Conventions
+- **Variables/functions**: camelCase
+- **Constants**: SCREAMING_SNAKE_CASE
+- **Types/Classes**: PascalCase (suffix component props with `Props`, e.g. `ButtonProps`)
+- **Files/directories**: kebab-case with descriptive suffixes (`.component.tsx`, `.service.ts`, `.entity.ts`, `.dto.ts`, `.module.ts`)
+- **TypeScript generics**: descriptive names (`TData` not `T`)
+
+### File Structure
+- Components under 300 lines, services under 500 lines
+- Components in their own directories with tests and stories
+- Use `index.ts` barrel exports for clean imports
+- Import order: external libraries first, then internal (`@/`), then relative
+
+### Comments
+- Use short-form comments (`//`), not JSDoc blocks
+- Explain WHY (business logic), not WHAT
+- Do not comment obvious code
+- Multi-line comments use multiple `//` lines, not `/** */`
+
+### State Management
+- **Jotai** for global state: atoms for primitive state, selectors for derived state, atom families for dynamic collections
+- Component-specific state with React hooks (`useState`, `useReducer` for complex logic)
+- GraphQL cache managed by Apollo Client
+- Use functional state updates: `setState(prev => prev + 1)`
+
+### Backend Architecture
+- **NestJS modules** for feature organization
+- **TypeORM** for database ORM with PostgreSQL
+- **GraphQL** API with code-first approach
+- **Redis** for caching and session management
+- **BullMQ** for background job processing
+
+### Database & Upgrade Commands
+- **PostgreSQL** as primary database
+- **Redis** for caching and sessions
+- **ClickHouse** for analytics (when enabled)
+- When changing entity files, generate an **instance command** (`database:migrate:generate --name <name> --type <fast|slow>`)
+- **Fast** instance commands handle schema changes; **slow** ones add a `runDataMigration` step for data backfills
+- **Workspace commands** iterate over all active/suspended workspaces for per-workspace upgrades
+- Commands use `@RegisteredInstanceCommand` and `@RegisteredWorkspaceCommand` decorators for automatic discovery
+- Include both `up` and `down` logic in instance commands
+- Never delete or rewrite committed instance command `up`/`down` logic
+- See `packages/twenty-server/docs/UPGRADE_COMMANDS.md` for full documentation
+
+### Utility Helpers
+Use existing helpers from `twenty-shared` instead of manual type guards:
+- `isDefined()`, `isNonEmptyString()`, `isNonEmptyArray()`
+
+## Development Workflow
+
+IMPORTANT: Use Context7 for code generation, setup or configuration steps, or library/API documentation. Automatically use the Context7 MCP tools to resolve library IDs and get library docs without waiting for explicit requests.
+
+### Before Making Changes
+1. Always run linting (`lint:diff-with-main`) and type checking after code changes
+2. Test changes with relevant test suites (prefer single-file test runs)
+3. Ensure instance commands are generated for entity changes (`database:migrate:generate`)
+4. Check that GraphQL schema changes are backward compatible
+5. Run `graphql:generate` after any GraphQL schema changes
+
+### Code Style Notes
+- Use **Linaria** for styling with zero-runtime CSS-in-JS (styled-components pattern)
+- Follow **Nx** workspace conventions for imports
+- Use **Lingui** for internationalization
+- Apply security first, then formatting (sanitize before format)
+
+### Testing Strategy
+- **Test behavior, not implementation** — focus on user perspective
+- **Test pyramid**: 70% unit, 20% integration, 10% E2E
+- Query by user-visible elements (text, roles, labels) over test IDs
+- Use `@testing-library/user-event` for realistic interactions
+- Descriptive test names: "should [behavior] when [condition]"
+- Clear mocks between tests with `jest.clearAllMocks()`
+
+## Dev Environment Setup
+
+All dev environments (Claude Code web, Cursor, local) use one script:
+
+```bash
+bash packages/twenty-utils/setup-dev-env.sh
+```
+
+This handles everything: starts Postgres + Redis (auto-detects local services vs Docker), creates databases, and copies `.env` files. Idempotent — safe to run multiple times.
+
+- `--docker` — force Docker mode (uses `packages/twenty-docker/docker-compose.dev.yml`)
+- `--down` — stop services
+- `--reset` — wipe data and restart fresh
+- **Skip the setup script** for tasks that only read code — architecture questions, code review, documentation, etc.
+
+**Note:** CI workflows (GitHub Actions) manage services via Actions service containers and run setup steps individually — they don't use this script.
+
+## Important Files
+- `nx.json` - Nx workspace configuration with task definitions
+- `tsconfig.base.json` - Base TypeScript configuration
+- `package.json` - Root package with workspace definitions
+- `.cursor/rules/` - Detailed development guidelines and best practices

.cursor/rules/README.mdc

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

.cursor/rules/changelog-process.mdc

@@ -55,7 +55,8 @@ If feature descriptions are not provided or need enhancement, research the codeb
 - Services: Look for `*.service.ts` files
 
 **For Database/ORM Changes:**
-- Migrations: `packages/twenty-server/src/database/typeorm/`
+- Instance commands (fast/slow): `packages/twenty-server/src/database/commands/upgrade-version-command/`
+- Legacy TypeORM migrations: `packages/twenty-server/src/database/typeorm/`
 - Entities: `packages/twenty-server/src/entities/`
 
 ### Research Commands

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

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

.cursor/rules/server-migrations.mdc

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

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

@@ -8,6 +8,10 @@ inputs:
   api-key:
     description: API key or access token for the target instance
     required: true
+  app-path:
+    description: Path to the app directory (relative to repo root). Defaults to repo root.
+    required: false
+    default: '.'
 
 runs:
   using: composite
@@ -19,11 +23,13 @@ runs:
     - name: Setup Node.js
       uses: actions/setup-node@v4
       with:
-        node-version-file: '.nvmrc'
+        node-version-file: '${{ inputs.app-path }}/.nvmrc'
         cache: yarn
+        cache-dependency-path: '${{ inputs.app-path }}/yarn.lock'
 
     - name: Install dependencies
       shell: bash
+      working-directory: ${{ inputs.app-path }}
       run: yarn install --immutable
 
     - name: Configure remote
@@ -43,4 +49,5 @@ runs:
 
     - name: Deploy
       shell: bash
+      working-directory: ${{ inputs.app-path }}
       run: yarn twenty deploy --remote target

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

@@ -8,6 +8,10 @@ inputs:
   api-key:
     description: API key or access token for the target workspace
     required: true
+  app-path:
+    description: Path to the app directory (relative to repo root). Defaults to repo root.
+    required: false
+    default: '.'
 
 runs:
   using: composite
@@ -19,11 +23,13 @@ runs:
     - name: Setup Node.js
       uses: actions/setup-node@v4
       with:
-        node-version-file: '.nvmrc'
+        node-version-file: '${{ inputs.app-path }}/.nvmrc'
         cache: yarn
+        cache-dependency-path: '${{ inputs.app-path }}/yarn.lock'
 
     - name: Install dependencies
       shell: bash
+      working-directory: ${{ inputs.app-path }}
       run: yarn install --immutable
 
     - name: Configure remote
@@ -43,4 +49,5 @@ runs:
 
     - name: Install
       shell: bash
+      working-directory: ${{ inputs.app-path }}
       run: yarn twenty install --remote target

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

@@ -15,8 +15,8 @@ outputs:
     description: 'URL where the Twenty test server can be reached'
     value: http://localhost:2021
   api-key:
-    description: 'API key for the Twenty test instance'
-    value: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC05ZTNiLTQ2ZDQtYTU1Ni04OGI5ZGRjMmIwMzQiLCJ1c2VySWQiOiIyMDIwMjAyMC05ZTNiLTQ2ZDQtYTU1Ni04OGI5ZGRjMmIwMzQiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtMDY4Ny00YzQxLWI3MDctZWQxYmZjYTk3MmE3IiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtOWUzYi00NmQ0LWE1NTYtODhiOWRkYzJiMDM1IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjQ5MDQ4ODE3MDR9.9S4wc0MOr5iczsomlFxZdOHD1IRDS4dnRSwNVNpctF4
+    description: 'API key (type: API_KEY) for the seeded Twenty dev workspace'
+    value: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC0xYzI1LTRkMDItYmYyNS02YWVjY2Y3ZWE0MTkiLCJ0eXBlIjoiQVBJX0tFWSIsIndvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWMyNS00ZDAyLWJmMjUtNmFlY2NmN2VhNDE5IiwiaWF0IjoxNzM1Njg5NjAwLCJleHAiOjQ4OTE0NDk2MDAsImp0aSI6IjIwMjAyMDIwLWY0MDEtNGQ4YS1hNzMxLTY0ZDAwN2MyN2JhZCJ9.bfQjfyN0NEtTCLE_xPyNcwonDzlSXFoP8kdCQTdnuDc
 
 runs:
   using: 'composite'

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

@@ -251,6 +251,14 @@ jobs:
             rm -f /tmp/current-server.pid
           fi
 
+      - name: Flush Redis between server runs
+        run: |
+          # Clear all Redis caches to prevent stale data from the current branch
+          # server contaminating the main branch server. Both servers share the
+          # same Redis instance, and CoreEntityCacheService/WorkspaceCacheService
+          # persist cached entities across process restarts.
+          redis-cli -h localhost -p 6379 FLUSHALL || echo "::warning::Failed to flush Redis"
+
       - name: Checkout main branch
         run: |
           git stash

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

@@ -139,11 +139,19 @@ jobs:
           cd /tmp/e2e-test-workspace/test-app
           npx --no-install twenty --version
 
-      - name: Create test database
-        run: PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
+      - name: Setup server environment
+        run: npx nx reset:env:e2e-testing-server twenty-server
 
-      - name: Setup database and start server
-        run: npx nx run twenty-server:database:reset && nohup npx nx start:ci twenty-server &
+      - name: Create databases
+        run: |
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
+
+      - name: Setup database
+        run: npx nx run twenty-server:database:reset
+
+      - name: Start server
+        run: nohup npx nx start:ci twenty-server &
 
       - name: Wait for server to be ready
         run: npx wait-on http://localhost:3000/healthz --timeout 120000 --interval 1000

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

@@ -133,11 +133,19 @@ jobs:
           cd /tmp/e2e-test-workspace/test-app
           npx --no-install twenty --version
 
-      - name: Create test database
-        run: PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
+      - name: Setup server environment
+        run: npx nx reset:env:e2e-testing-server twenty-server
 
-      - name: Setup database and start server
-        run: npx nx run twenty-server:database:reset && nohup npx nx start:ci twenty-server &
+      - name: Create databases
+        run: |
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
+
+      - name: Setup database
+        run: npx nx run twenty-server:database:reset
+
+      - name: Start server
+        run: nohup npx nx start:ci twenty-server &
 
       - name: Wait for server to be ready
         run: npx wait-on http://localhost:3000/healthz --timeout 120000 --interval 1000
@@ -147,17 +155,7 @@ jobs:
           cd /tmp/e2e-test-workspace/test-app
           npx --no-install twenty remote add --api-key ${{ env.TWENTY_API_KEY }} --api-url ${{ env.TWENTY_API_URL }}
 
-      - name: Deploy scaffolded app
-        run: |
-          cd /tmp/e2e-test-workspace/test-app
-          npx --no-install twenty deploy
-
-      - name: Install scaffolded app
-        run: |
-          cd /tmp/e2e-test-workspace/test-app
-          npx --no-install twenty install
-
-      - name: Run scaffolded app integration test
+      - name: Run scaffolded app integration test (deploys, installs, and verifies the app)
         run: |
           cd /tmp/e2e-test-workspace/test-app
           yarn test

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

@@ -137,11 +137,19 @@ jobs:
           cd /tmp/e2e-test-workspace/test-app
           npx --no-install twenty --version
 
-      - name: Create test database
-        run: PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
+      - name: Setup server environment
+        run: npx nx reset:env:e2e-testing-server twenty-server
 
-      - name: Setup database and start server
-        run: npx nx run twenty-server:database:reset && nohup npx nx start:ci twenty-server &
+      - name: Create databases
+        run: |
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
+
+      - name: Setup database
+        run: npx nx run twenty-server:database:reset
+
+      - name: Start server
+        run: nohup npx nx start:ci twenty-server &
 
       - name: Wait for server to be ready
         run: npx wait-on http://localhost:3000/healthz --timeout 120000 --interval 1000

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

@@ -62,11 +62,19 @@ jobs:
       - name: Build SDK packages
         run: npx nx build twenty-sdk
 
-      - name: Create test database
-        run: PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
+      - name: Setup server environment
+        run: npx nx reset:env:e2e-testing-server twenty-server
 
-      - name: Setup database and start server
-        run: npx nx run twenty-server:database:reset && nohup npx nx start:ci twenty-server &
+      - name: Create databases
+        run: |
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
+
+      - name: Setup database
+        run: npx nx run twenty-server:database:reset
+
+      - name: Start server
+        run: nohup npx nx start:ci twenty-server &
 
       - name: Wait for server to be ready
         run: npx wait-on http://localhost:3000/healthz --timeout 120000 --interval 1000

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

@@ -62,11 +62,19 @@ jobs:
       - name: Build SDK packages
         run: npx nx build twenty-sdk
 
-      - name: Create test database
-        run: PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
+      - name: Setup server environment
+        run: npx nx reset:env:e2e-testing-server twenty-server
 
-      - name: Setup database and start server
-        run: npx nx run twenty-server:database:reset && nohup npx nx start:ci twenty-server &
+      - name: Create databases
+        run: |
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
+
+      - name: Setup database
+        run: npx nx run twenty-server:database:reset
+
+      - name: Start server
+        run: nohup npx nx start:ci twenty-server &
 
       - name: Wait for server to be ready
         run: npx wait-on http://localhost:3000/healthz --timeout 120000 --interval 1000

.github/workflows/ci-sdk.yaml

@@ -19,6 +19,7 @@ jobs:
       files: |
         packages/twenty-sdk/**
         packages/twenty-server/**
+        .github/workflows/ci-sdk.yaml
         !packages/twenty-sdk/package.json
   sdk-test:
     needs: changed-files-check
@@ -69,7 +70,6 @@ jobs:
         ports:
           - 6379:6379
     env:
-      NODE_ENV: test
       TWENTY_API_URL: http://localhost:3000
       TWENTY_API_KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdik
     steps:
@@ -79,16 +79,26 @@ jobs:
           fetch-depth: 10
       - name: Install dependencies
         uses: ./.github/actions/yarn-install
-      - name: Build
+      - name: Build SDK
         run: npx nx build twenty-sdk
-      - name: Server / Create Test DB
+      - name: Setup server environment
+        run: npx nx reset:env:e2e-testing-server twenty-server
+      - name: Create databases
         run: |
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
           PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
+      - name: Setup database
+        run: npx nx run twenty-server:database:reset
+      - name: Start server
+        run: nohup npx nx start:ci twenty-server > /tmp/twenty-server.log 2>&1 &
+      - name: Wait for server to be ready
+        run: npx wait-on http://localhost:3000/healthz --timeout 120000 --interval 1000
       - name: SDK / Run e2e Tests
-        uses: ./.github/actions/nx-affected
-        with:
-          tag: scope:sdk
-          tasks: test:e2e
+        run: NODE_ENV=test npx vitest run --config ./vitest.e2e.config.ts
+        working-directory: packages/twenty-sdk
+      - name: Server / Dump logs on failure
+        if: failure()
+        run: tail -100 /tmp/twenty-server.log || echo "No server log file found"
   ci-sdk-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5

.github/workflows/ci-server.yaml

@@ -144,15 +144,18 @@ jobs:
           exit 1
       - name: Server / Check for Pending Migrations
         run: |
-          CORE_MIGRATION_OUTPUT=$(npx nx database:migrate:generate twenty-server -- --name core-migration-check || true)
+          npx nx database:migrate:generate twenty-server -- --name pending-migration-check || true
 
-          CORE_MIGRATION_FILE=$(ls packages/twenty-server/src/database/typeorm/core/migrations/common/*core-migration-check.ts 2>/dev/null || echo "")
-
-          if [ -n "$CORE_MIGRATION_FILE" ]; then
+          if ! git diff --quiet; then
             echo "::error::Unexpected migration files were generated. Please run 'npx nx database:migrate:generate twenty-server -- --name <migration-name>' and commit the result."
-            echo "$CORE_MIGRATION_OUTPUT"
+            echo ""
+            echo "The following migration changes were detected:"
+            echo "==================================================="
+            git diff
+            echo "==================================================="
+            echo ""
 
-            rm -f packages/twenty-server/src/database/typeorm/core/migrations/common/*core-migration-check.ts
+            git checkout -- .
 
             exit 1
           fi

.github/workflows/ci-zapier.yaml

@@ -69,13 +69,14 @@ jobs:
 
       - name: Server / Start
         run: |
-          npx nx start twenty-server &
+          npx nx run twenty-server:start:ci &
           echo "Waiting for server to be ready..."
-          timeout 60 bash -c 'until curl -s http://localhost:3000/health; do sleep 2; done'
+          timeout 60 bash -c 'until curl -sf http://localhost:3000/healthz; do sleep 2; done'
 
       - name: Start worker
+        working-directory: packages/twenty-server
         run: |
-          npx nx run twenty-server:worker &
+          NODE_ENV=development node dist/queue-worker/queue-worker.js &
           echo "Worker started"
 
       - name: Zapier / Build

.gitignore

@@ -53,3 +53,4 @@ mcp.json
 TRANSLATION_QA_REPORT.md
 .playwright-mcp/
 .playwright-cli/
+output/playwright/

CLAUDE.md

@@ -71,10 +71,10 @@ npx nx build twenty-server
 # Database management
 npx nx database:reset twenty-server         # Reset database
 npx nx run twenty-server:database:init:prod # Initialize database
-npx nx run twenty-server:database:migrate:prod # Run migrations
+npx nx run twenty-server:database:migrate:prod # Run instance commands (fast only)
 
-# Generate migration (replace [name] with kebab-case descriptive name)
-npx nx run twenty-server:typeorm migration:generate src/database/typeorm/core/migrations/common/[name] -d src/database/typeorm/core/core.datasource.ts
+# Generate an instance command (fast or slow)
+npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>
 ```
 
 ### Database Inspection (Postgres MCP)
@@ -158,14 +158,17 @@ packages/
 - **Redis** for caching and session management
 - **BullMQ** for background job processing
 
-### Database & Migrations
+### Database & Upgrade Commands
 - **PostgreSQL** as primary database
 - **Redis** for caching and sessions
 - **ClickHouse** for analytics (when enabled)
-- Always generate migrations when changing entity files
-- Migration names must be kebab-case (e.g. `add-agent-turn-evaluation`)
-- Include both `up` and `down` logic in migrations
-- Never delete or rewrite committed migrations
+- When changing entity files, generate an **instance command** (`database:migrate:generate --name <name> --type <fast|slow>`)
+- **Fast** instance commands handle schema changes; **slow** ones add a `runDataMigration` step for data backfills
+- **Workspace commands** iterate over all active/suspended workspaces for per-workspace upgrades
+- Commands use `@RegisteredInstanceCommand` and `@RegisteredWorkspaceCommand` decorators for automatic discovery
+- Include both `up` and `down` logic in instance commands
+- Never delete or rewrite committed instance command `up`/`down` logic
+- See `packages/twenty-server/docs/UPGRADE_COMMANDS.md` for full documentation
 
 ### Utility Helpers
 Use existing helpers from `twenty-shared` instead of manual type guards:
@@ -178,7 +181,7 @@ IMPORTANT: Use Context7 for code generation, setup or configuration steps, or li
 ### Before Making Changes
 1. Always run linting (`lint:diff-with-main`) and type checking after code changes
 2. Test changes with relevant test suites (prefer single-file test runs)
-3. Ensure database migrations are generated for entity changes
+3. Ensure instance commands are generated for entity changes (`database:migrate:generate`)
 4. Check that GraphQL schema changes are backward compatible
 5. Run `graphql:generate` after any GraphQL schema changes
 

packages/create-twenty-app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-twenty-app",
-  "version": "0.9.0-canary.0",
+  "version": "1.22.0",
   "description": "Command-line interface to create Twenty application",
   "main": "dist/cli.cjs",
   "bin": "dist/cli.cjs",

packages/create-twenty-app/src/constants/template/github/actions/install/action.yml

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

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

@@ -30,13 +30,13 @@ jobs:
           ref: ${{ github.event.pull_request.head.sha || github.sha }}
 
       - name: Deploy
-        uses: ./.github/actions/deploy
+        uses: twentyhq/twenty/.github/actions/deploy-twenty-app@main
         with:
           api-url: ${{ env.TWENTY_DEPLOY_URL }}
           api-key: ${{ secrets.TWENTY_DEPLOY_API_KEY }}
 
       - name: Install
-        uses: ./.github/actions/install
+        uses: twentyhq/twenty/.github/actions/install-twenty-app@main
         with:
           api-url: ${{ env.TWENTY_DEPLOY_URL }}
           api-key: ${{ secrets.TWENTY_DEPLOY_API_KEY }}

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

@@ -7,9 +7,7 @@
     "npm": "please-use-yarn",
     "yarn": ">=4.0.2"
   },
-  "keywords": [
-    "twenty-app"
-  ],
+  "keywords": [],
   "packageManager": "yarn@4.9.2",
   "scripts": {
     "twenty": "twenty",

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

@@ -1,70 +0,0 @@
-import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
-import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli';
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
-import { afterAll, beforeAll, describe, expect, it } from 'vitest';
-
-const APP_PATH = process.cwd();
-
-describe('App installation', () => {
-  beforeAll(async () => {
-    const buildResult = await appBuild({
-      appPath: APP_PATH,
-      tarball: true,
-      onProgress: (message: string) => console.log(`[build] ${message}`),
-    });
-
-    if (!buildResult.success) {
-      throw new Error(
-        `Build failed: ${buildResult.error?.message ?? 'Unknown error'}`,
-      );
-    }
-
-    const deployResult = await appDeploy({
-      tarballPath: buildResult.data.tarballPath!,
-      onProgress: (message: string) => console.log(`[deploy] ${message}`),
-    });
-
-    if (!deployResult.success) {
-      throw new Error(
-        `Deploy failed: ${deployResult.error?.message ?? 'Unknown error'}`,
-      );
-    }
-
-    const installResult = await appInstall({ appPath: APP_PATH });
-
-    if (!installResult.success) {
-      throw new Error(
-        `Install failed: ${installResult.error?.message ?? 'Unknown error'}`,
-      );
-    }
-  });
-
-  afterAll(async () => {
-    const uninstallResult = await appUninstall({ appPath: APP_PATH });
-
-    if (!uninstallResult.success) {
-      console.warn(
-        `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,
-      );
-    }
-  });
-
-  it('should find the installed app in the applications list', async () => {
-    const metadataClient = new MetadataApiClient();
-
-    const result = await metadataClient.query({
-      findManyApplications: {
-        id: true,
-        name: true,
-        universalIdentifier: true,
-      },
-    });
-
-    const installedApp = result.findManyApplications.find(
-      (application: { universalIdentifier: string }) =>
-        application.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER,
-    );
-
-    expect(installedApp).toBeDefined();
-  });
-});

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

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

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

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

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

@@ -1,6 +1,15 @@
 import tsconfigPaths from 'vite-tsconfig-paths';
 import { defineConfig } from 'vitest/config';
 
+const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020';
+const TWENTY_API_KEY =
+  process.env.TWENTY_API_KEY ??
+  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC0xYzI1LTRkMDItYmYyNS02YWVjY2Y3ZWE0MTkiLCJ0eXBlIjoiQVBJX0tFWSIsIndvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWMyNS00ZDAyLWJmMjUtNmFlY2NmN2VhNDE5IiwiaWF0IjoxNzM1Njg5NjAwLCJleHAiOjQ4OTE0NDk2MDAsImp0aSI6IjIwMjAyMDIwLWY0MDEtNGQ4YS1hNzMxLTY0ZDAwN2MyN2JhZCJ9.bfQjfyN0NEtTCLE_xPyNcwonDzlSXFoP8kdCQTdnuDc';
+
+// Make env vars available to globalSetup (test.env only applies to workers)
+process.env.TWENTY_API_URL = TWENTY_API_URL;
+process.env.TWENTY_API_KEY = TWENTY_API_KEY;
+
 export default defineConfig({
   plugins: [
     tsconfigPaths({
@@ -11,14 +20,12 @@ export default defineConfig({
   test: {
     testTimeout: 120_000,
     hookTimeout: 120_000,
+    fileParallelism: false,
     include: ['src/**/*.integration-test.ts'],
-    setupFiles: ['src/__tests__/setup-test.ts'],
+    globalSetup: ['src/__tests__/global-setup.ts'],
     env: {
-      TWENTY_API_URL: process.env.TWENTY_API_URL ?? 'http://localhost:2020',
-      TWENTY_API_KEY:
-        process.env.TWENTY_API_KEY ??
-        // Tim Apple (admin) access token for twenty-app-dev
-        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC05ZTNiLTQ2ZDQtYTU1Ni04OGI5ZGRjMmIwMzQiLCJ1c2VySWQiOiIyMDIwMjAyMC05ZTNiLTQ2ZDQtYTU1Ni04OGI5ZGRjMmIwMzQiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtMDY4Ny00YzQxLWI3MDctZWQxYmZjYTk3MmE3IiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtOWUzYi00NmQ0LWE1NTYtODhiOWRkYzJiMDM1IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjQ5MDQ4ODE3MDR9.9S4wc0MOr5iczsomlFxZdOHD1IRDS4dnRSwNVNpctF4',
+      TWENTY_API_URL,
+      TWENTY_API_KEY,
     },
   },
 });

packages/twenty-apps/examples/hello-world/.github/actions/deploy/action.yml

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

packages/twenty-apps/examples/hello-world/.github/actions/install/action.yml

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

packages/twenty-apps/examples/hello-world/.github/workflows/cd.yml

@@ -30,13 +30,13 @@ jobs:
           ref: ${{ github.event.pull_request.head.sha || github.sha }}
 
       - name: Deploy
-        uses: ./.github/actions/deploy
+        uses: twentyhq/twenty/.github/actions/deploy-twenty-app@main
         with:
           api-url: ${{ env.TWENTY_DEPLOY_URL }}
           api-key: ${{ secrets.TWENTY_DEPLOY_API_KEY }}
 
       - name: Install
-        uses: ./.github/actions/install
+        uses: twentyhq/twenty/.github/actions/install-twenty-app@main
         with:
           api-url: ${{ env.TWENTY_DEPLOY_URL }}
           api-key: ${{ secrets.TWENTY_DEPLOY_API_KEY }}

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

@@ -16,8 +16,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "twenty-client-sdk": "0.8.0-canary.5",
-    "twenty-sdk": "0.8.0-canary.5"
+    "twenty-client-sdk": "0.9.0",
+    "twenty-sdk": "0.9.0"
   },
   "devDependencies": {
     "@types/node": "^24.7.2",

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

@@ -1,13 +1,19 @@
-import { definePostInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+import {
+  definePostInstallLogicFunction,
+  type InstallLogicFunctionPayload,
+} from 'twenty-sdk';
 
 const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
-  console.log('Post install logic function executed successfully!', payload.previousVersion);
+  console.log(
+    'Post install logic function executed successfully!',
+    payload.previousVersion,
+  );
 };
 
 export default definePostInstallLogicFunction({
   universalIdentifier: '8c726dcc-1709-4eac-aa8b-f99960a9ec1b',
   name: 'post-install',
   description: 'Runs after installation to set up the application.',
-  timeoutSeconds: 300,
+  timeoutSeconds: 30,
   handler,
 });

packages/twenty-apps/examples/hello-world/vitest.config.ts

@@ -17,8 +17,7 @@ export default defineConfig({
       TWENTY_API_URL: process.env.TWENTY_API_URL ?? 'http://localhost:2020',
       TWENTY_API_KEY:
         process.env.TWENTY_API_KEY ??
-        // Tim Apple (admin) access token for twenty-app-dev
-        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC05ZTNiLTQ2ZDQtYTU1Ni04OGI5ZGRjMmIwMzQiLCJ1c2VySWQiOiIyMDIwMjAyMC05ZTNiLTQ2ZDQtYTU1Ni04OGI5ZGRjMmIwMzQiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtMDY4Ny00YzQxLWI3MDctZWQxYmZjYTk3MmE3IiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtOWUzYi00NmQ0LWE1NTYtODhiOWRkYzJiMDM1IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjQ5MDQ4ODE3MDR9.9S4wc0MOr5iczsomlFxZdOHD1IRDS4dnRSwNVNpctF4',
+        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC0xYzI1LTRkMDItYmYyNS02YWVjY2Y3ZWE0MTkiLCJ0eXBlIjoiQVBJX0tFWSIsIndvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWMyNS00ZDAyLWJmMjUtNmFlY2NmN2VhNDE5IiwiaWF0IjoxNzM1Njg5NjAwLCJleHAiOjQ4OTE0NDk2MDAsImp0aSI6IjIwMjAyMDIwLWY0MDEtNGQ4YS1hNzMxLTY0ZDAwN2MyN2JhZCJ9.bfQjfyN0NEtTCLE_xPyNcwonDzlSXFoP8kdCQTdnuDc',
     },
   },
 });

packages/twenty-apps/examples/postcard/.github/actions/deploy/action.yml

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

packages/twenty-apps/examples/postcard/.github/workflows/cd.yml

@@ -30,13 +30,13 @@ jobs:
           ref: ${{ github.event.pull_request.head.sha || github.sha }}
 
       - name: Deploy
-        uses: ./.github/actions/deploy
+        uses: twentyhq/twenty/.github/actions/deploy-twenty-app@main
         with:
           api-url: ${{ env.TWENTY_DEPLOY_URL }}
           api-key: ${{ secrets.TWENTY_DEPLOY_API_KEY }}
 
       - name: Install
-        uses: ./.github/actions/install
+        uses: twentyhq/twenty/.github/actions/install-twenty-app@main
         with:
           api-url: ${{ env.TWENTY_DEPLOY_URL }}
           api-key: ${{ secrets.TWENTY_DEPLOY_API_KEY }}

packages/twenty-apps/examples/postcard/package.json

@@ -19,8 +19,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "twenty-client-sdk": "0.8.0-canary.8",
-    "twenty-sdk": "0.8.0-canary.8"
+    "twenty-client-sdk": "0.9.0",
+    "twenty-sdk": "0.9.0"
   },
   "devDependencies": {
     "@types/node": "^24.7.2",

packages/twenty-apps/examples/postcard/src/__tests__/global-setup.ts

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

packages/twenty-apps/examples/postcard/src/__tests__/schema.integration-test.ts

@@ -0,0 +1,63 @@
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application.config';
+import { describe, expect, it } from 'vitest';
+
+describe('App installation', () => {
+  it('should find the installed app in the applications list', async () => {
+    const client = new MetadataApiClient();
+
+    const result = await client.query({
+      findManyApplications: {
+        id: true,
+        name: true,
+        universalIdentifier: true,
+      },
+    });
+
+    const app = result.findManyApplications.find(
+      (a: { universalIdentifier: string }) =>
+        a.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER,
+    );
+
+    expect(app).toBeDefined();
+  });
+});
+
+describe('PostCard object', () => {
+  it('should exist with expected fields and relations', async () => {
+    const client = new MetadataApiClient();
+
+    const { objects } = await client.query({
+      objects: {
+        __args: {
+          filter: { isCustom: { is: true } },
+          paging: { first: 50 },
+        },
+        edges: {
+          node: {
+            nameSingular: true,
+            fields: {
+              __args: { paging: { first: 500 } },
+              edges: { node: { name: true } },
+            },
+          },
+        },
+      },
+    });
+
+    const obj = objects.edges
+      .map((e: { node: { nameSingular: string } }) => e.node)
+      .find((n: { nameSingular: string }) => n.nameSingular === 'postCard');
+    expect(obj).toBeDefined();
+
+    const names = obj!.fields.edges.map(
+      (e: { node: { name: string } }) => e.node.name,
+    );
+    expect(names).toContain('name');
+    expect(names).toContain('content');
+    expect(names).toContain('status');
+    expect(names).toContain('deliveredAt');
+    expect(names).toContain('recipient');
+  });
+
+});

packages/twenty-apps/examples/postcard/src/__tests__/setup-test.ts

@@ -1,53 +0,0 @@
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-import { beforeAll } from 'vitest';
-
-const CONFIG_DIR = path.join(os.homedir(), '.twenty');
-const CONFIG_PATH = path.join(CONFIG_DIR, 'config.test.json');
-
-beforeAll(async () => {
-  const apiUrl = process.env.TWENTY_API_URL!;
-  const token = process.env.TWENTY_API_KEY!;
-
-  if (!apiUrl || !token) {
-    throw new Error(
-      'TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +
-        'Start a local server: yarn twenty server start\n' +
-        'Or set them in vitest env config.',
-    );
-  }
-
-  let response: Response;
-
-  try {
-    response = await fetch(`${apiUrl}/healthz`);
-  } catch {
-    throw new Error(
-      `Twenty server is not reachable at ${apiUrl}. ` +
-        'Make sure the server is running before executing integration tests.',
-    );
-  }
-
-  if (!response.ok) {
-    throw new Error(`Server at ${apiUrl} returned ${response.status}`);
-  }
-
-  fs.mkdirSync(CONFIG_DIR, { recursive: true });
-
-  fs.writeFileSync(
-    CONFIG_PATH,
-    JSON.stringify(
-      {
-        remotes: {
-          local: { apiUrl, apiKey: token },
-        },
-        defaultRemote: 'local',
-      },
-      null,
-      2,
-    ),
-  );
-
-  process.env.TWENTY_APP_ACCESS_TOKEN ??= token;
-});

packages/twenty-apps/examples/postcard/src/logic-functions/post-install.ts

@@ -0,0 +1,35 @@
+import { CoreApiClient } from 'twenty-client-sdk/core';
+import { definePostInstallLogicFunction } from 'twenty-sdk';
+
+const SEED_POST_CARDS = [
+  {
+    name: 'Greetings from Paris',
+    content: 'Wish you were here! The Eiffel Tower is breathtaking.',
+  },
+  {
+    name: 'Hello from Tokyo',
+    content: 'Cherry blossoms are in full bloom. Sending love!',
+  },
+];
+
+const handler = async () => {
+  const client = new CoreApiClient();
+
+  await client.mutation({
+    createPostCards: {
+      __args: { data: SEED_POST_CARDS as any },
+      id: true,
+    },
+  } as any);
+
+  console.log(`Seeded ${SEED_POST_CARDS.length} post cards on install.`);
+  return {};
+};
+
+export default definePostInstallLogicFunction({
+  universalIdentifier: '852c6321-1563-4396-b7c5-9d370f3d30a9',
+  name: 'post-install',
+  description: 'Runs after installation to set up the application.',
+  timeoutSeconds: 30,
+  handler,
+});

packages/twenty-apps/examples/postcard/src/logic-functions/pre-install.ts

@@ -0,0 +1,17 @@
+import { definePreInstallLogicFunction } from 'twenty-sdk';
+
+const handler = async (params: any) => {
+  console.log(
+    `Pre-install logic function executed successfully with params`,
+    params,
+  );
+  return {};
+};
+
+export default definePreInstallLogicFunction({
+  universalIdentifier: 'bf27f558-4ec6-481f-b76e-1dbcd05aef1f',
+  name: 'pre-install',
+  description: 'Runs before migrations to set up the application.',
+  timeoutSeconds: 10,
+  handler,
+});

packages/twenty-apps/examples/postcard/src/roles/default-function.role.ts

@@ -33,7 +33,7 @@ export default defineRole({
       objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
       fieldUniversalIdentifier: CONTENT_FIELD_UNIVERSAL_IDENTIFIER,
       canReadFieldValue: false,
-      canUpdateFieldValue: false,
+      canUpdateFieldValue: true,
     },
   ],
   permissionFlags: [PermissionFlag.APPLICATIONS],

packages/twenty-apps/examples/postcard/vitest.config.ts

@@ -1,6 +1,15 @@
 import tsconfigPaths from 'vite-tsconfig-paths';
 import { defineConfig } from 'vitest/config';
 
+const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020';
+const TWENTY_API_KEY =
+  process.env.TWENTY_API_KEY ??
+  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC0xYzI1LTRkMDItYmYyNS02YWVjY2Y3ZWE0MTkiLCJ0eXBlIjoiQVBJX0tFWSIsIndvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWMyNS00ZDAyLWJmMjUtNmFlY2NmN2VhNDE5IiwiaWF0IjoxNzM1Njg5NjAwLCJleHAiOjQ4OTE0NDk2MDAsImp0aSI6IjIwMjAyMDIwLWY0MDEtNGQ4YS1hNzMxLTY0ZDAwN2MyN2JhZCJ9.bfQjfyN0NEtTCLE_xPyNcwonDzlSXFoP8kdCQTdnuDc';
+
+// Make env vars available to globalSetup (test.env only applies to workers)
+process.env.TWENTY_API_URL = TWENTY_API_URL;
+process.env.TWENTY_API_KEY = TWENTY_API_KEY;
+
 export default defineConfig({
   plugins: [
     tsconfigPaths({
@@ -11,14 +20,12 @@ export default defineConfig({
   test: {
     testTimeout: 120_000,
     hookTimeout: 120_000,
+    fileParallelism: false,
     include: ['src/**/*.integration-test.ts'],
-    setupFiles: ['src/__tests__/setup-test.ts'],
+    globalSetup: ['src/__tests__/global-setup.ts'],
     env: {
-      TWENTY_API_URL: process.env.TWENTY_API_URL ?? 'http://localhost:2020',
-      TWENTY_API_KEY:
-        process.env.TWENTY_API_KEY ??
-        // Tim Apple (admin) access token for twenty-app-dev
-        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC05ZTNiLTQ2ZDQtYTU1Ni04OGI5ZGRjMmIwMzQiLCJ1c2VySWQiOiIyMDIwMjAyMC05ZTNiLTQ2ZDQtYTU1Ni04OGI5ZGRjMmIwMzQiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtMDY4Ny00YzQxLWI3MDctZWQxYmZjYTk3MmE3IiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtOWUzYi00NmQ0LWE1NTYtODhiOWRkYzJiMDM1IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjQ5MDQ4ODE3MDR9.9S4wc0MOr5iczsomlFxZdOHD1IRDS4dnRSwNVNpctF4',
+      TWENTY_API_URL,
+      TWENTY_API_KEY,
     },
   },
 });

packages/twenty-apps/examples/postcard/yarn.lock

@@ -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.8.0-canary.8"
-    twenty-sdk: "npm:0.8.0-canary.8"
+    twenty-client-sdk: "npm:0.9.0"
+    twenty-sdk: "npm:0.9.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.8.0-canary.8":
-  version: 0.8.0-canary.8
-  resolution: "twenty-client-sdk@npm:0.8.0-canary.8"
+"twenty-client-sdk@npm:0.9.0":
+  version: 0.9.0
+  resolution: "twenty-client-sdk@npm:0.9.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/acb5bf952a9729811235a3474ccb4db82630c53a2caed03176bfb4f442576ee2ef7e625886f63714e2534f7ec83b03d83e4c0b1170a0eb816c531acfc2c98010
+  checksum: 10c0/4b42a6622a9852fc3eca50c1131b116c5602af006ee5f1d3b4f1e97721bbc8ef5c2f3b60d9dee3ca9ca8c3c7ad4b292a7b55007b779b4c042997dbc29940ba54
   languageName: node
   linkType: hard
 
-"twenty-sdk@npm:0.8.0-canary.8":
-  version: 0.8.0-canary.8
-  resolution: "twenty-sdk@npm:0.8.0-canary.8"
+"twenty-sdk@npm:0.9.0":
+  version: 0.9.0
+  resolution: "twenty-sdk@npm:0.9.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.8.0-canary.8"
+    twenty-client-sdk: "npm:0.9.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/a22cf071f41c19d769e68a995912a0bda0f087bd9a295534bf9e545544f6dfc84f284a477f9011fc135f2a44de9372b977a66de06454e760822119e76921ea69
+  checksum: 10c0/27f93e5edac3265f819abacc853598435718020258a95d55518562e086e42daabae784964b42005d8e4ff30d1d6f13a12a38c656e18c60bad98da3f579a8e1c3
   languageName: node
   linkType: hard
 

packages/twenty-apps/fixtures/function-execute-app/package.json

@@ -16,7 +16,8 @@
     "lint:fix": "oxlint --fix -c .oxlintrc.json ."
   },
   "dependencies": {
-    "twenty-sdk": "latest"
+    "twenty-sdk": "latest",
+    "twenty-client-sdk": "latest"
   },
   "devDependencies": {
     "typescript": "^5.9.3",

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

@@ -14,7 +14,8 @@
     "lint:fix": "oxlint --fix -c .oxlintrc.json ."
   },
   "dependencies": {
-    "twenty-sdk": "latest"
+    "twenty-sdk": "latest",
+    "twenty-client-sdk": "latest"
   },
   "devDependencies": {
     "typescript": "^5.9.3",

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

@@ -14,7 +14,8 @@
     "lint:fix": "oxlint --fix -c .oxlintrc.json ."
   },
   "dependencies": {
-    "twenty-sdk": "latest"
+    "twenty-sdk": "latest",
+    "twenty-client-sdk": "latest"
   },
   "devDependencies": {
     "typescript": "^5.9.3",

packages/twenty-apps/internal/self-hosting/.github/workflows/cd.yml

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

packages/twenty-apps/internal/self-hosting/.github/workflows/ci.yml

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

packages/twenty-apps/internal/self-hosting/.gitignore

@@ -35,3 +35,4 @@ yarn-error.log*
 
 # typescript
 *.tsbuildinfo
+*.d.ts

packages/twenty-apps/internal/self-hosting/.nvmrc

@@ -0,0 +1 @@
+24.5.0

packages/twenty-apps/internal/self-hosting/.oxlintrc.json

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

packages/twenty-apps/internal/self-hosting/.yarnrc.yml

@@ -1,5 +1 @@
-yarnPath: .yarn/releases/yarn-4.9.2.cjs
-
 nodeLinker: node-modules
-
-enableTransparentWorkspaces: false

packages/twenty-apps/internal/self-hosting/AGENT.md

@@ -0,0 +1,14 @@
+## Base documentation
+
+- Documentation: https://docs.twenty.com/developers/extend/apps/getting-started
+- 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.

packages/twenty-apps/internal/self-hosting/CLAUDE.md

@@ -0,0 +1,14 @@
+## Base documentation
+
+- Documentation: https://docs.twenty.com/developers/extend/apps/getting-started
+- 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.

packages/twenty-apps/internal/self-hosting/LLMS.md

@@ -0,0 +1,14 @@
+## Base documentation
+
+- Documentation: https://docs.twenty.com/developers/extend/apps/getting-started
+- 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.

packages/twenty-apps/internal/self-hosting/README.md

@@ -1,44 +1,11 @@
-# Self Hosting
+This is a [Twenty](https://twenty.com) application bootstrapped with [`create-twenty-app`](https://www.npmjs.com/package/create-twenty-app).
 
-Used to manage billing and telemetry of self-hosted instances
+## Getting Started
 
-## Features
+Run `yarn twenty help` to list all available commands.
 
-### Telemetry Webhook
+## Learn More
 
-Receives user signup telemetry events from self-hosted Twenty instances and creates/updates selfHostingUser records.
-
-**Endpoint:** `POST /webhook/telemetry`
-
-**Payload Structure:**
-```json
-{
-  "action": "user_signup",
-  "timestamp": "2025-11-21T...",
-  "version": "1",
-  "payload": {
-    "userId": "uuid",
-    "workspaceId": "uuid",
-    "payload": {
-      "events": [
-        {
-          "userEmail": "user@example.com",
-          "userId": "uuid",
-          "userFirstName": "John",
-          "userLastName": "Doe",
-          "locale": "en",
-          "serverUrl": "https://self-hosted.example.com"
-        }
-      ]
-    }
-  }
-}
-```
-
-**Response:**
-```json
-{
-  "success": true,
-  "message": "Self hosting user created/updated: uuid"
-}
-```
+- [Twenty Apps documentation](https://docs.twenty.com/developers/extend/apps/getting-started)
+- [twenty-sdk CLI reference](https://www.npmjs.com/package/twenty-sdk)
+- [Discord](https://discord.gg/cx5n4Jzs57)

packages/twenty-apps/internal/self-hosting/package.json

@@ -1,6 +1,6 @@
 {
   "name": "self-hosting",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "license": "MIT",
   "engines": {
     "node": "^24.5.0",
@@ -11,13 +11,22 @@
   "scripts": {
     "twenty": "twenty",
     "lint": "oxlint -c .oxlintrc.json .",
-    "lint:fix": "oxlint --fix -c .oxlintrc.json ."
+    "lint:fix": "oxlint --fix -c .oxlintrc.json .",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "twenty-client-sdk": "1.22.0-canary.6",
+    "twenty-sdk": "1.22.0-canary.6"
   },
   "devDependencies": {
     "@types/node": "^24.7.2",
+    "@types/react": "^19.0.0",
     "oxlint": "^0.16.0",
-    "twenty-sdk": "0.6.2"
-  },
-  "$schema": "https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-cli/src/constants/schemas/appManifest.schema.json",
-  "universalIdentifier": "a7070f46-3158-4b40-828f-8e6b1febc233"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.9.3",
+    "vite-tsconfig-paths": "^4.2.1",
+    "vitest": "^3.1.1"
+  }
 }

packages/twenty-apps/internal/self-hosting/src/__tests__/app-install.integration-test.ts

@@ -1,7 +1,7 @@
-import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application.config';
 import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli';
 import { MetadataApiClient } from 'twenty-client-sdk/metadata';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application.config';
 
 const APP_PATH = process.cwd();
 
@@ -44,7 +44,9 @@ describe('App installation', () => {
 
     if (!uninstallResult.success) {
       console.warn(
-        `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,
+        `App uninstall failed: ${
+          uninstallResult.error?.message ?? 'Unknown error'
+        }`,
       );
     }
   });

packages/twenty-apps/internal/self-hosting/src/application.config.ts

@@ -1,6 +1,9 @@
 import { defineApplication } from 'twenty-sdk';
 import { UNIVERSAL_IDENTIFIERS } from 'src/constants/universal-identifiers.constant';
 
+export const APPLICATION_UNIVERSAL_IDENTIFIER =
+  '94f7db30-59e5-4b09-a5fe-64cd3d4a65b0';
+
 export default defineApplication({
   universalIdentifier: '94f7db30-59e5-4b09-a5fe-64cd3d4a65b0',
   displayName: 'Self Hosting',

packages/twenty-apps/internal/self-hosting/src/logic-functions/match-telemetry-event-with-people.ts

@@ -5,7 +5,7 @@ import {
   type ObjectRecordUpdateEvent,
 } from 'twenty-sdk';
 import { SELF_HOSTING_USER_NAME_SINGULAR } from 'src/objects/selfHostingUser.object';
-import { CoreApiClient } from 'twenty-sdk/clients';
+import { CoreApiClient } from 'twenty-client-sdk/core';
 
 type SelfHostingUser = {
   id: string;

packages/twenty-apps/internal/self-hosting/src/logic-functions/telemetryWebhook.function.ts

@@ -1,5 +1,5 @@
 import { defineLogicFunction, type RoutePayload } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-sdk/clients';
+import { CoreApiClient } from 'twenty-client-sdk/core';
 import { type TelemetryEvent } from 'src/logic-functions/types/telemetry-event.type';
 
 export const main = async (

packages/twenty-apps/internal/self-hosting/src/roles/default-role.ts

@@ -4,7 +4,7 @@ import { UNIVERSAL_IDENTIFIERS } from 'src/constants/universal-identifiers.const
 export default defineRole({
   universalIdentifier:
     UNIVERSAL_IDENTIFIERS.roles.defaultRole.universalIdentifier,
-  label: 'default role',
+  label: 'Self hosting default role',
   description: 'Add a description for your role',
   canReadAllObjectRecords: true,
   canUpdateAllObjectRecords: true,

packages/twenty-apps/internal/self-hosting/tsconfig.json

@@ -27,5 +27,16 @@
       "~/*": ["./*"]
     }
   },
-  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "**/*.integration-test.ts"
+  ],
+  "references": [
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
 }

packages/twenty-apps/internal/self-hosting/tsconfig.spec.json

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

packages/twenty-apps/internal/self-hosting/vitest.config.ts

@@ -0,0 +1,24 @@
+import tsconfigPaths from 'vite-tsconfig-paths';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  plugins: [
+    tsconfigPaths({
+      projects: ['tsconfig.spec.json'],
+      ignoreConfigErrors: true,
+    }),
+  ],
+  test: {
+    testTimeout: 120_000,
+    hookTimeout: 120_000,
+    include: ['src/**/*.integration-test.ts'],
+    setupFiles: ['src/__tests__/setup-test.ts'],
+    env: {
+      TWENTY_API_URL: process.env.TWENTY_API_URL ?? 'http://localhost:2020',
+      TWENTY_API_KEY:
+        process.env.TWENTY_API_KEY ??
+        // Tim Apple (admin) access token for twenty-app-dev
+        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC05ZTNiLTQ2ZDQtYTU1Ni04OGI5ZGRjMmIwMzQiLCJ1c2VySWQiOiIyMDIwMjAyMC05ZTNiLTQ2ZDQtYTU1Ni04OGI5ZGRjMmIwMzQiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtMDY4Ny00YzQxLWI3MDctZWQxYmZjYTk3MmE3IiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtOWUzYi00NmQ0LWE1NTYtODhiOWRkYzJiMDM1IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjQ5MDQ4ODE3MDR9.9S4wc0MOr5iczsomlFxZdOHD1IRDS4dnRSwNVNpctF4',
+    },
+  },
+});

packages/twenty-client-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twenty-client-sdk",
-  "version": "0.9.0-canary.0",
+  "version": "1.22.0",
   "sideEffects": false,
   "license": "AGPL-3.0",
   "scripts": {

packages/twenty-client-sdk/src/metadata/generated/schema.graphql

@@ -583,8 +583,9 @@ type ViewField {
   workspaceId: UUID!
   createdAt: DateTime!
   updatedAt: DateTime!
+  isActive: Boolean!
   deletedAt: DateTime
-  isOverridden: Boolean!
+  isOverridden: Boolean @deprecated(reason: "isOverridden is deprecated")
 }
 
 enum AggregateOperations {
@@ -691,9 +692,10 @@ type ViewFieldGroup {
   workspaceId: UUID!
   createdAt: DateTime!
   updatedAt: DateTime!
+  isActive: Boolean!
   deletedAt: DateTime
   viewFields: [ViewField!]!
-  isOverridden: Boolean!
+  isOverridden: Boolean! @deprecated(reason: "isOverridden is deprecated")
 }
 
 type View {
@@ -733,6 +735,7 @@ enum ViewType {
   KANBAN
   CALENDAR
   FIELDS_WIDGET
+  TABLE_WIDGET
 }
 
 enum ViewKey {
@@ -790,7 +793,6 @@ type Workspace {
   isCustomDomainEnabled: Boolean!
   editableProfileFields: [String!]
   defaultRole: Role
-  version: String
   fastModel: String!
   smartModel: String!
   aiAdditionalInstructions: String
@@ -896,10 +898,12 @@ type PageLayoutWidget {
   position: PageLayoutWidgetPosition
   configuration: WidgetConfiguration!
   conditionalDisplay: JSON
+  conditionalAvailabilityExpression: String
   createdAt: DateTime!
   updatedAt: DateTime!
+  isActive: Boolean!
   deletedAt: DateTime
-  isOverridden: Boolean!
+  isOverridden: Boolean @deprecated(reason: "isOverridden is deprecated")
 }
 
 enum WidgetType {
@@ -1169,6 +1173,7 @@ type FieldConfiguration {
 """Display mode for field configuration widgets"""
 enum FieldDisplayMode {
   CARD
+  EDITOR
   FIELD
   VIEW
 }
@@ -1232,8 +1237,9 @@ type PageLayoutTab {
   layoutMode: PageLayoutTabLayoutMode
   createdAt: DateTime!
   updatedAt: DateTime!
+  isActive: Boolean!
   deletedAt: DateTime
-  isOverridden: Boolean!
+  isOverridden: Boolean @deprecated(reason: "isOverridden is deprecated")
 }
 
 type PageLayout {
@@ -1252,6 +1258,7 @@ enum PageLayoutType {
   RECORD_INDEX
   RECORD_PAGE
   DASHBOARD
+  STANDALONE_PAGE
 }
 
 type Analytics {
@@ -1259,6 +1266,37 @@ type Analytics {
   success: Boolean!
 }
 
+type ApprovedAccessDomain {
+  id: UUID!
+  domain: String!
+  isValidated: Boolean!
+  createdAt: DateTime!
+}
+
+type FileWithSignedUrl {
+  id: UUID!
+  path: String!
+  size: Float!
+  createdAt: DateTime!
+  url: String!
+}
+
+type EnterpriseLicenseInfoDTO {
+  isValid: Boolean!
+  licensee: String
+  expiresAt: DateTime
+  subscriptionId: String
+}
+
+type EnterpriseSubscriptionStatusDTO {
+  status: String!
+  licensee: String
+  expiresAt: DateTime
+  cancelAt: DateTime
+  currentPeriodEnd: DateTime
+  isCancellationScheduled: Boolean!
+}
+
 type BillingSubscriptionSchedulePhaseItem {
   price: String!
   quantity: Float
@@ -1412,42 +1450,11 @@ type BillingUpdate {
   billingSubscriptions: [BillingSubscription!]!
 }
 
-type EnterpriseLicenseInfoDTO {
-  isValid: Boolean!
-  licensee: String
-  expiresAt: DateTime
-  subscriptionId: String
-}
-
-type EnterpriseSubscriptionStatusDTO {
-  status: String!
-  licensee: String
-  expiresAt: DateTime
-  cancelAt: DateTime
-  currentPeriodEnd: DateTime
-  isCancellationScheduled: Boolean!
-}
-
 type OnboardingStepSuccess {
   """Boolean that confirms query was dispatched"""
   success: Boolean!
 }
 
-type ApprovedAccessDomain {
-  id: UUID!
-  domain: String!
-  isValidated: Boolean!
-  createdAt: DateTime!
-}
-
-type FileWithSignedUrl {
-  id: UUID!
-  path: String!
-  size: Float!
-  createdAt: DateTime!
-  url: String!
-}
-
 type WorkspaceInvitation {
   id: UUID!
   email: String!
@@ -1480,6 +1487,7 @@ type NavigationMenuItem {
   icon: String
   color: String
   folderId: UUID
+  pageLayoutId: UUID
   position: Float!
   applicationId: UUID
   createdAt: DateTime!
@@ -1493,6 +1501,7 @@ enum NavigationMenuItemType {
   LINK
   OBJECT
   RECORD
+  PAGE_LAYOUT
 }
 
 type ObjectRecordEventProperties {
@@ -1571,9 +1580,26 @@ enum LogicFunctionExecutionStatus {
   ERROR
 }
 
-type BillingTrialPeriod {
-  duration: Float!
-  isCreditCardRequired: Boolean!
+type FeatureFlag {
+  key: FeatureFlagKey!
+  value: Boolean!
+}
+
+enum FeatureFlagKey {
+  IS_UNIQUE_INDEXES_ENABLED
+  IS_JSON_FILTER_ENABLED
+  IS_AI_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_DRAFT_EMAIL_ENABLED
+  IS_CONNECTED_ACCOUNT_MIGRATED
+  IS_RICH_TEXT_V1_MIGRATED
+  IS_RECORD_PAGE_LAYOUT_GLOBAL_EDITION_ENABLED
+  IS_DATASOURCE_MIGRATED
 }
 
 type WorkspaceUrls {
@@ -1581,6 +1607,89 @@ type WorkspaceUrls {
   subdomainUrl: String!
 }
 
+type UserInfo {
+  id: UUID!
+  email: String!
+  firstName: String
+  lastName: String
+  createdAt: DateTime!
+}
+
+type WorkspaceInfo {
+  id: UUID!
+  name: String!
+  allowImpersonation: Boolean!
+  logo: String
+  totalUsers: Float!
+  activationStatus: WorkspaceActivationStatus!
+  createdAt: DateTime!
+  workspaceUrls: WorkspaceUrls!
+  users: [UserInfo!]!
+  featureFlags: [FeatureFlag!]!
+}
+
+type UserLookup {
+  user: UserInfo!
+  workspaces: [WorkspaceInfo!]!
+}
+
+type AdminPanelRecentUser {
+  id: UUID!
+  email: String!
+  firstName: String
+  lastName: String
+  createdAt: DateTime!
+  workspaceName: String
+  workspaceId: UUID
+}
+
+type AdminPanelTopWorkspace {
+  id: UUID!
+  name: String!
+  totalUsers: Int!
+  subdomain: String!
+}
+
+type AdminWorkspaceChatThread {
+  id: UUID!
+  title: String
+  totalInputTokens: Int!
+  totalOutputTokens: Int!
+  conversationSize: Int!
+  createdAt: DateTime!
+  updatedAt: DateTime!
+}
+
+type AdminChatMessagePart {
+  type: String!
+  textContent: String
+  toolName: String
+}
+
+type AdminChatMessage {
+  id: UUID!
+  role: AgentMessageRole!
+  parts: [AdminChatMessagePart!]!
+  createdAt: DateTime!
+}
+
+"""Role of a message in a chat thread"""
+enum AgentMessageRole {
+  SYSTEM
+  USER
+  ASSISTANT
+}
+
+type AdminChatThreadMessages {
+  thread: AdminWorkspaceChatThread!
+  messages: [AdminChatMessage!]!
+}
+
+type BillingTrialPeriod {
+  duration: Float!
+  isCreditCardRequired: Boolean!
+}
+
 type SSOIdentityProvider {
   id: UUID!
   name: String!
@@ -1623,6 +1732,12 @@ type PublicWorkspaceData {
   workspaceUrls: WorkspaceUrls!
 }
 
+type PublicWorkspaceDataSummary {
+  id: UUID!
+  logo: String
+  displayName: String
+}
+
 type NativeModelCapabilities {
   webSearch: Boolean
   twitterSearch: Boolean
@@ -1634,12 +1749,15 @@ type ClientAIModelConfig {
   modelFamily: ModelFamily
   modelFamilyLabel: String
   sdkPackage: String
-  inputCostPerMillionTokensInCredits: Float!
-  outputCostPerMillionTokensInCredits: Float!
+  inputCostPerMillionTokens: Float
+  outputCostPerMillionTokens: Float
   nativeCapabilities: NativeModelCapabilities
   isDeprecated: Boolean
   isRecommended: Boolean
   providerName: String
+  providerLabel: String
+  contextWindowTokens: Float
+  maxOutputTokens: Float
   dataResidency: String
 }
 
@@ -1724,25 +1842,6 @@ type PublicFeatureFlag {
   metadata: PublicFeatureFlagMetadata!
 }
 
-enum FeatureFlagKey {
-  IS_UNIQUE_INDEXES_ENABLED
-  IS_JSON_FILTER_ENABLED
-  IS_AI_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_DRAFT_EMAIL_ENABLED
-  IS_CONNECTED_ACCOUNT_MIGRATED
-  IS_USAGE_ANALYTICS_ENABLED
-  IS_RICH_TEXT_V1_MIGRATED
-  IS_RECORD_PAGE_LAYOUT_GLOBAL_EDITION_ENABLED
-  IS_RECORD_TABLE_WIDGET_ENABLED
-  IS_DATASOURCE_MIGRATED
-}
-
 type ClientConfigMaintenanceMode {
   startAt: DateTime!
   endAt: DateTime!
@@ -1926,34 +2025,6 @@ type SystemHealth {
   services: [SystemHealthService!]!
 }
 
-type FeatureFlag {
-  key: FeatureFlagKey!
-  value: Boolean!
-}
-
-type UserInfo {
-  id: UUID!
-  email: String!
-  firstName: String
-  lastName: String
-}
-
-type WorkspaceInfo {
-  id: UUID!
-  name: String!
-  allowImpersonation: Boolean!
-  logo: String
-  totalUsers: Float!
-  workspaceUrls: WorkspaceUrls!
-  users: [UserInfo!]!
-  featureFlags: [FeatureFlag!]!
-}
-
-type UserLookup {
-  user: UserInfo!
-  workspaces: [WorkspaceInfo!]!
-}
-
 type VersionInfo {
   currentVersion: String
   latestVersion: String!
@@ -2135,30 +2206,18 @@ type DeletedWorkspaceMember {
   userWorkspaceId: UUID
 }
 
-type BillingEntitlement {
-  key: BillingEntitlementKey!
-  value: Boolean!
+type Relation {
+  type: RelationType!
+  sourceObjectMetadata: Object!
+  targetObjectMetadata: Object!
+  sourceFieldMetadata: Field!
+  targetFieldMetadata: Field!
 }
 
-enum BillingEntitlementKey {
-  SSO
-  CUSTOM_DOMAIN
-  RLS
-  AUDIT_LOGS
-}
-
-type DomainRecord {
-  validationType: String!
-  type: String!
-  status: String!
-  key: String!
-  value: String!
-}
-
-type DomainValidRecords {
-  id: UUID!
-  domain: String!
-  records: [DomainRecord!]!
+"""Relation type"""
+enum RelationType {
+  ONE_TO_MANY
+  MANY_TO_ONE
 }
 
 type IndexEdge {
@@ -2260,25 +2319,6 @@ type ObjectFieldsConnection {
   edges: [FieldEdge!]!
 }
 
-type UpsertRowLevelPermissionPredicatesResult {
-  predicates: [RowLevelPermissionPredicate!]!
-  predicateGroups: [RowLevelPermissionPredicateGroup!]!
-}
-
-type Relation {
-  type: RelationType!
-  sourceObjectMetadata: Object!
-  targetObjectMetadata: Object!
-  sourceFieldMetadata: Field!
-  targetFieldMetadata: Field!
-}
-
-"""Relation type"""
-enum RelationType {
-  ONE_TO_MANY
-  MANY_TO_ONE
-}
-
 type FieldConnection {
   """Paging information"""
   pageInfo: PageInfo!
@@ -2287,6 +2327,37 @@ type FieldConnection {
   edges: [FieldEdge!]!
 }
 
+type BillingEntitlement {
+  key: BillingEntitlementKey!
+  value: Boolean!
+}
+
+enum BillingEntitlementKey {
+  SSO
+  CUSTOM_DOMAIN
+  RLS
+  AUDIT_LOGS
+}
+
+type DomainRecord {
+  validationType: String!
+  type: String!
+  status: String!
+  key: String!
+  value: String!
+}
+
+type DomainValidRecords {
+  id: UUID!
+  domain: String!
+  records: [DomainRecord!]!
+}
+
+type UpsertRowLevelPermissionPredicatesResult {
+  predicates: [RowLevelPermissionPredicate!]!
+  predicateGroups: [RowLevelPermissionPredicateGroup!]!
+}
+
 type AuthToken {
   token: String!
   expiresAt: DateTime!
@@ -2522,6 +2593,7 @@ type Location {
 }
 
 type PlaceDetailsResult {
+  street: String
   state: String
   postcode: String
   city: String
@@ -2579,6 +2651,7 @@ type CommandMenuItem {
   hotKeys: [String!]
   conditionalAvailabilityExpression: String
   availabilityObjectMetadataId: UUID
+  pageLayoutId: UUID
   applicationId: UUID
   createdAt: DateTime!
   updatedAt: DateTime!
@@ -2655,6 +2728,7 @@ enum EngineComponentKey {
 
 enum CommandMenuItemAvailabilityType {
   GLOBAL
+  GLOBAL_OBJECT_CONTEXT
   RECORD_SELECTION
   FALLBACK
 }
@@ -2790,6 +2864,34 @@ type ConnectedAccountDTO {
   updatedAt: DateTime!
 }
 
+type PublicConnectionParametersOutput {
+  host: String!
+  port: Float!
+  username: String
+  secure: Boolean
+}
+
+type PublicImapSmtpCaldavConnectionParameters {
+  IMAP: PublicConnectionParametersOutput
+  SMTP: PublicConnectionParametersOutput
+  CALDAV: PublicConnectionParametersOutput
+}
+
+type ConnectedAccountPublicDTO {
+  id: UUID!
+  handle: String!
+  provider: String!
+  lastCredentialsRefreshedAt: DateTime
+  authFailedAt: DateTime
+  handleAliases: [String!]
+  scopes: [String!]
+  lastSignedInAt: DateTime
+  userWorkspaceId: UUID!
+  createdAt: DateTime!
+  updatedAt: DateTime!
+  connectionParameters: PublicImapSmtpCaldavConnectionParameters
+}
+
 type SendEmailOutput {
   success: Boolean!
   error: String
@@ -3208,6 +3310,7 @@ type Query {
   myMessageFolders(messageChannelId: UUID): [MessageFolder!]!
   myMessageChannels(connectedAccountId: UUID): [MessageChannel!]!
   myConnectedAccounts: [ConnectedAccountDTO!]!
+  connectedAccountById(id: UUID!): ConnectedAccountPublicDTO
   connectedAccounts: [ConnectedAccountDTO!]!
   myCalendarChannels(connectedAccountId: UUID): [CalendarChannel!]!
   webhooks: [Webhook!]!
@@ -3248,10 +3351,14 @@ type Query {
   currentUser: User!
   currentWorkspace: Workspace!
   getPublicWorkspaceDataByDomain(origin: String): PublicWorkspaceData!
+  getPublicWorkspaceDataById(id: UUID!): PublicWorkspaceDataSummary!
   getSSOIdentityProviders: [FindAvailableSSOIDP!]!
   getConnectedImapSmtpCaldavAccount(id: UUID!): ConnectedImapSmtpCaldavAccount!
   getAutoCompleteAddress(address: String!, token: String!, country: String, isFieldCity: Boolean): [AutocompleteResult!]!
   getAddressDetails(placeId: String!, token: String!): PlaceDetailsResult!
+  userLookupAdminPanel(userIdentifier: String!): UserLookup!
+  adminPanelRecentUsers(searchTerm: String = ""): [AdminPanelRecentUser!]!
+  adminPanelTopWorkspaces(searchTerm: String = ""): [AdminPanelTopWorkspace!]!
   getConfigVariablesGrouped: ConfigVariables!
   getSystemHealthStatus: SystemHealth!
   getIndicatorHealthStatus(indicatorId: HealthIndicatorId!): AdminPanelHealthServiceData!
@@ -3266,6 +3373,10 @@ type Query {
   getModelsDevSuggestions(providerType: String!): [ModelsDevModelSuggestion!]!
   getAdminAiUsageByWorkspace(periodStart: DateTime, periodEnd: DateTime): [UsageBreakdownItem!]!
   getMaintenanceMode: MaintenanceMode
+  workspaceLookupAdminPanel(workspaceId: UUID!): UserLookup!
+  getAdminWorkspaceChatThreads(workspaceId: UUID!): [AdminWorkspaceChatThread!]!
+  getAdminChatThreadMessages(threadId: UUID!): AdminChatThreadMessages!
+  findOneAdminApplicationRegistration(id: String!): ApplicationRegistration!
   getUsageAnalytics(input: UsageAnalyticsInput): UsageAnalytics!
   getPostgresCredentials: PostgresCredentials
   findManyPublicDomains: [PublicDomain!]!
@@ -3352,6 +3463,7 @@ enum EventLogTable {
   PAGEVIEW
   OBJECT_EVENT
   USAGE_EVENT
+  APPLICATION_LOG
 }
 
 input EventLogFiltersInput {
@@ -3406,6 +3518,7 @@ type Mutation {
   updateNavigationMenuItem(input: UpdateOneNavigationMenuItemInput!): NavigationMenuItem!
   deleteManyNavigationMenuItems(ids: [UUID!]!): [NavigationMenuItem!]!
   deleteNavigationMenuItem(id: UUID!): NavigationMenuItem!
+  uploadEmailAttachmentFile(file: Upload!): FileWithSignedUrl!
   uploadAIChatFile(file: Upload!): FileWithSignedUrl!
   uploadWorkflowFile(file: Upload!): FileWithSignedUrl!
   uploadWorkspaceLogo(file: Upload!): FileWithSignedUrl!
@@ -3470,7 +3583,9 @@ type Mutation {
   updatePageLayout(id: String!, input: UpdatePageLayoutInput!): PageLayout!
   destroyPageLayout(id: String!): Boolean!
   updatePageLayoutWithTabsAndWidgets(id: String!, input: UpdatePageLayoutWithTabsInput!): PageLayout!
+  resetPageLayoutToDefault(id: String!): PageLayout!
   resetPageLayoutWidgetToDefault(id: String!): PageLayoutWidget!
+  resetPageLayoutTabToDefault(id: String!): PageLayoutTab!
   createPageLayoutWidget(input: CreatePageLayoutWidgetInput!): PageLayoutWidget!
   updatePageLayoutWidget(id: String!, input: UpdatePageLayoutWidgetInput!): PageLayoutWidget!
   destroyPageLayoutWidget(id: String!): Boolean!
@@ -3518,7 +3633,7 @@ type Mutation {
   updateWebhook(input: UpdateWebhookInput!): Webhook!
   deleteWebhook(id: UUID!): Webhook!
   createChatThread: AgentChatThread!
-  sendChatMessage(threadId: UUID!, text: String!, messageId: UUID!, browsingContext: JSON, modelId: String): SendChatMessageResult!
+  sendChatMessage(threadId: UUID!, text: String!, messageId: UUID!, browsingContext: JSON, modelId: String, fileIds: [UUID!]): SendChatMessageResult!
   stopAgentChatStream(threadId: UUID!): Boolean!
   deleteQueuedChatMessage(messageId: UUID!): Boolean!
   createSkill(input: CreateSkillInput!): Skill!
@@ -3560,6 +3675,7 @@ type Mutation {
   verifyTwoFactorAuthenticationMethodForAuthenticatedUser(otp: String!): VerifyTwoFactorAuthenticationMethod!
   deleteUser: User!
   deleteUserFromWorkspace(workspaceMemberIdToDelete: String!): UserWorkspace!
+  updateWorkspaceMemberSettings(input: UpdateWorkspaceMemberSettingsInput!): Boolean!
   updateUserEmail(newEmail: String!, verifyEmailRedirectPath: String): Boolean!
   resendEmailVerificationToken(email: String!, origin: String!): ResendEmailVerificationToken!
   activateWorkspace(data: ActivateWorkspaceInput!): Workspace!
@@ -3575,10 +3691,11 @@ type Mutation {
   startChannelSync(connectedAccountId: UUID!): ChannelSyncSuccess!
   saveImapSmtpCaldavAccount(accountOwnerId: UUID!, handle: String!, connectionParameters: EmailAccountConnectionParameters!, id: UUID): ImapSmtpCaldavConnectionSuccess!
   updateLabPublicFeatureFlag(input: UpdateLabPublicFeatureFlagInput!): FeatureFlag!
-  userLookupAdminPanel(userIdentifier: String!): UserLookup!
   updateWorkspaceFeatureFlag(workspaceId: UUID!, featureFlag: String!, value: Boolean!): Boolean!
   setAdminAiModelEnabled(modelId: String!, enabled: Boolean!): Boolean!
+  setAdminAiModelsEnabled(modelIds: [String!]!, enabled: Boolean!): Boolean!
   setAdminAiModelRecommended(modelId: String!, recommended: Boolean!): Boolean!
+  setAdminAiModelsRecommended(modelIds: [String!]!, recommended: Boolean!): Boolean!
   setAdminDefaultAiModel(role: AiModelRole!, modelId: String!): Boolean!
   createDatabaseConfigVariable(key: String!, value: JSON!): Boolean!
   updateDatabaseConfigVariable(key: String!, value: JSON!): Boolean!
@@ -3637,6 +3754,7 @@ input CreateNavigationMenuItemInput {
   icon: String
   color: String
   folderId: UUID
+  pageLayoutId: UUID
   position: Float
 }
 
@@ -3655,6 +3773,7 @@ input UpdateNavigationMenuItemInput {
   link: String
   icon: String
   color: String
+  pageLayoutId: UUID
 }
 
 """The `Upload` scalar type represents a file upload."""
@@ -3975,6 +4094,7 @@ input UpdatePageLayoutWidgetWithIdInput {
   position: JSON
   configuration: JSON
   conditionalDisplay: JSON
+  conditionalAvailabilityExpression: String
 }
 
 input GridPositionInput {
@@ -3995,6 +4115,7 @@ input CreatePageLayoutWidgetInput {
 }
 
 input UpdatePageLayoutWidgetInput {
+  pageLayoutTabId: UUID
   title: String
   type: WidgetType
   objectMetadataId: UUID
@@ -4002,6 +4123,7 @@ input UpdatePageLayoutWidgetInput {
   position: JSON
   configuration: JSON
   conditionalDisplay: JSON
+  conditionalAvailabilityExpression: String
 }
 
 input CreateLogicFunctionFromSourceInput {
@@ -4062,6 +4184,7 @@ input CreateCommandMenuItemInput {
   conditionalAvailabilityExpression: String
   availabilityObjectMetadataId: UUID
   payload: JSON
+  pageLayoutId: UUID
 }
 
 input UpdateCommandMenuItemInput {
@@ -4075,6 +4198,7 @@ input UpdateCommandMenuItemInput {
   availabilityObjectMetadataId: UUID
   engineComponentKey: EngineComponentKey
   hotKeys: [String!]
+  pageLayoutId: UUID
 }
 
 input CreateFrontComponentInput {
@@ -4485,9 +4609,15 @@ input UpdateApplicationRegistrationVariableInput {
 
 input UpdateApplicationRegistrationVariablePayload {
   value: String
+  resetValue: Boolean
   description: String
 }
 
+input UpdateWorkspaceMemberSettingsInput {
+  workspaceMemberId: UUID!
+  update: JSON!
+}
+
 input ActivateWorkspaceInput {
   displayName: String
 }
@@ -4551,6 +4681,12 @@ input SendEmailInput {
   subject: String!
   body: String!
   inReplyTo: String
+  files: [SendEmailAttachmentInput!]
+}
+
+input SendEmailAttachmentInput {
+  id: String!
+  name: String!
 }
 
 input EmailAccountConnectionParameters {
@@ -4617,6 +4753,7 @@ enum FileFolder {
   FilesField
   Dependencies
   Workflow
+  EmailAttachment
   AppTarball
   GeneratedSdkClient
 }

packages/twenty-docker/twenty/Dockerfile

@@ -215,7 +215,8 @@ ENV PG_DATABASE_URL=postgres://twenty:twenty@localhost:5432/default \
     DISABLE_DB_MIGRATIONS=true \
     DISABLE_CRON_JOBS_REGISTRATION=true \
     IS_BILLING_ENABLED=false \
-    SIGN_IN_PREFILLED=true
+    SIGN_IN_PREFILLED=true \
+    APPLICATION_LOG_DRIVER=CONSOLE
 
 EXPOSE 2020
 VOLUME ["/data/postgres", "/app/packages/twenty-server/.local-storage"]

packages/twenty-docs/developers/contribute/capabilities/backend-development/server-commands.mdx

@@ -47,7 +47,7 @@ npx nx run twenty-server:database:reset
 #### For objects in Core/Metadata schemas (TypeORM)
 
 ```bash
-npx nx run twenty-server:typeorm migration:generate src/database/typeorm/core/migrations/nameOfYourMigration -d src/database/typeorm/core/core.datasource.ts
+npx nx run twenty-server:database:migrate:generate
 ```
 
 ## Tech Stack

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

@@ -476,7 +476,7 @@ export default defineLogicFunction({
   httpRouteTriggerSettings: {
     path: '/post-card/create',
     httpMethod: 'GET',
-    isAuthRequired: false,
+    isAuthRequired: true,
   },
   /*databaseEventTriggerSettings: {
     eventName: 'people.created',
@@ -644,49 +644,15 @@ export default defineLogicFunction({
 **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="definePreInstallLogicFunction" description="Define a pre-install logic function (one per app)">
-
-A pre-install function is a logic function that runs automatically before your app is installed on a workspace. This is useful for validation tasks, prerequisite checks, or preparing workspace state before the main installation proceeds.
-
-```ts src/logic-functions/pre-install.ts
-import { definePreInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
-
-const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
-  console.log('Pre install logic function executed successfully!', payload.previousVersion);
-};
-
-export default definePreInstallLogicFunction({
-  universalIdentifier: 'e0604b9e-e946-456b-886d-3f27d9a6b324',
-  name: 'pre-install',
-  description: 'Runs before installation to prepare the application.',
-  timeoutSeconds: 300,
-  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()` — a specialized variant that omits trigger settings (`cronTriggerSettings`, `databaseEventTriggerSettings`, `httpRouteTriggerSettings`, `isTool`).
-- The handler receives an `InstallLogicFunctionPayload` with `{ previousVersion: string }` — the version of the app that was previously installed (or an empty string for fresh installs).
-- Only one pre-install function is allowed per application. The manifest build will error if more than one is detected.
-- The function's `universalIdentifier` is automatically set as `preInstallLogicFunctionUniversalIdentifier` on the application manifest during the build — you do not need to reference it in `defineApplication()`.
-- The default timeout is set to 300 seconds (5 minutes) to allow for longer preparation tasks.
-
 </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 after your app is installed on a workspace. This is useful for one-time setup tasks such as seeding default data, creating initial records, or configuring workspace settings.
+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 InstallLogicFunctionPayload } from 'twenty-sdk';
+import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk';
 
-const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+const handler = async (payload: InstallPayload): Promise<void> => {
   console.log('Post install logic function executed successfully!', payload.previousVersion);
 };
 
@@ -695,6 +661,8 @@ export default definePostInstallLogicFunction({
   name: 'post-install',
   description: 'Runs after installation to set up the application.',
   timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: false,
+  shouldRunSynchronously: false,
   handler,
 });
 ```
@@ -707,10 +675,168 @@ 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 `InstallLogicFunctionPayload` with `{ previousVersion: string }` — the version of the app that was previously installed (or an empty string for fresh installs).
+- 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` is automatically set as `postInstallLogicFunctionUniversalIdentifier` on the application manifest during the build — you do not need to reference it in `defineApplication()`.
+- 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';
+
+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';
+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';
+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>
 <Accordion title="defineFrontComponent" description="Define front components for custom UI" >
@@ -1818,8 +1944,7 @@ 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 pre-install or post-install functions
-yarn twenty exec --preInstall
+# Execute the post-install function
 yarn twenty exec --postInstall
 ```
 

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

@@ -220,6 +220,7 @@ The scaffolder already started a local Twenty server for you. To manage it later
 |---------|-------------|
 | `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, and credentials |
 | `yarn twenty server logs` | Stream server logs |
@@ -228,6 +229,20 @@ The scaffolder already started a local Twenty server for you. To manage it later
 
 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.
 
+### 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, and credentials |
+| `yarn twenty server logs --test` | Stream test instance logs |
+| `yarn twenty server reset --test` | Wipe test data and start fresh |
+
+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>

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

@@ -66,14 +66,71 @@ The share link uses the server's base URL (without any workspace subdomain) so i
 
 ### Version management
 
+When updating an already deployed tarball app, the server requires the `version` in `package.json` to be **strictly higher** (per [semver](https://semver.org) ordering) than the currently deployed version. Re-deploying the same version, or pushing a lower one, is rejected before the tarball is stored — you'll see a `VERSION_ALREADY_EXISTS` error from the CLI.
+
 To release an update:
 
-1. Bump the `version` field in your `package.json`
+1. Bump the `version` field in your `package.json` (e.g. `1.2.3` → `1.2.4`, `1.3.0`, or `2.0.0`)
 2. Run `yarn twenty deploy` (or `yarn twenty deploy --remote production`)
 3. Workspaces that have the app installed will see the upgrade available in their settings
 
+<Note>
+Pre-release tags work as expected: bumping `1.0.0-rc.1` → `1.0.0-rc.2` is allowed, and a final release like `1.0.0` is correctly recognized as higher than `1.0.0-rc.5`. The version in `package.json` must itself be a valid semver string.
+</Note>
+
 {/* TODO: add screenshot of the Upgrade button */}
 
+## 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.
+
+### CI — `ci.yml`
+
+Runs integration tests on every push to `main` and every pull request.
+
+**What it does:**
+
+1. Checks out your app's source.
+2. Spawns an isolated Twenty test instance using the `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main` composite action (the CI equivalent of `yarn twenty server start --test`).
+3. Enables Corepack, sets up Node.js from your `.nvmrc`, and installs dependencies with `yarn install --immutable`.
+4. Runs `yarn test`, passing `TWENTY_API_URL` and `TWENTY_API_KEY` from the spawned instance so your tests can talk to a real server.
+
+**Config knobs:**
+
+- `TWENTY_VERSION` (env, defaults to `latest`) — pin the Twenty server version used in CI by editing this in `ci.yml`.
+- Concurrency is grouped by `github.ref` and cancels in-progress runs on new pushes.
+
+No secrets are required — the test instance is ephemeral and lives only for the duration of the job.
+
+### CD — `cd.yml`
+
+Deploys your app to a configured Twenty server on every push to `main`, and optionally from a pull request when the `deploy` label is applied.
+
+**What it does:**
+
+1. Checks out the PR head (for labeled PRs) or the pushed commit.
+2. Runs `twentyhq/twenty/.github/actions/deploy-twenty-app@main` — the CI equivalent of `yarn twenty deploy`.
+3. Runs `twentyhq/twenty/.github/actions/install-twenty-app@main` so the newly deployed version is installed into the target workspace.
+
+**Required configuration:**
+
+| Setting | Where | Purpose |
+|---------|-------|---------|
+| `TWENTY_DEPLOY_URL` | `env` in `cd.yml` (defaults to `http://localhost:3000`) | The Twenty server to deploy to. Change this to your real server URL before first use. |
+| `TWENTY_DEPLOY_API_KEY` | GitHub repo **Settings → Secrets and variables → Actions** | API key with deploy permission on the target server. |
+
+<Note>
+The default `TWENTY_DEPLOY_URL` of `http://localhost:3000` is a placeholder — it will not reach anything from a GitHub-hosted runner. Update it to your server's public URL (or use a self-hosted runner with network access) before enabling CD.
+</Note>
+
+**Triggering a preview deploy from a PR:**
+
+Add the `deploy` label to a pull request. The `if:` guard in `cd.yml` will run the job for that PR using the PR's head commit, letting you validate a change on the target server before merging.
+
+### Pinning the reusable actions
+
+Both workflows reference reusable actions at `@main`, so action updates in the `twentyhq/twenty` repo are picked up automatically. If you want deterministic builds, replace `@main` with a commit SHA or release tag on each `uses:` line.
+
 ## Publishing to npm
 
 Publishing to npm makes your app discoverable in the Twenty marketplace. Any Twenty workspace can browse, install, and upgrade marketplace apps directly from the UI.
@@ -81,7 +138,7 @@ Publishing to npm makes your app discoverable in the Twenty marketplace. Any Twe
 ### Requirements
 
 - An [npm](https://www.npmjs.com) account
-- The `twenty-app` keyword in your `package.json` `keywords` array (already included when you scaffold with `create-twenty-app`)
+- The `twenty-app` keyword in your `package.json` `keywords` array (add it manually — it is not included by default in the `create-twenty-app` template)
 
 ```json filename="package.json"
 {
@@ -189,3 +246,12 @@ You can also install apps from the command line:
 ```bash filename="Terminal"
 yarn twenty install
 ```
+
+<Note>
+The server enforces semver versioning on install, mirroring the rules on deploy:
+
+- Installing the same version that is already installed in your workspace is rejected with an `APP_ALREADY_INSTALLED` error.
+- Installing a lower version than the one currently installed is rejected with a `CANNOT_DOWNGRADE_APPLICATION` error.
+
+To install a newer version, deploy or publish it first, then re-run `yarn twenty install`.
+</Note>

packages/twenty-docs/l/ar/developers/contribute/capabilities/backend-development/server-commands.mdx

@@ -47,7 +47,7 @@ npx nx run twenty-server:database:reset
 #### للكائنات داخل مخططات Core/Metadata (TypeORM)
 
 ```bash
-npx nx run twenty-server:typeorm migration:generate src/database/typeorm/core/migrations/nameOfYourMigration -d src/database/typeorm/core/core.datasource.ts
+npx nx run twenty-server:database:migrate:generate
 ```
 
 ## "التقنية المستخدمة"

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

@@ -476,7 +476,7 @@ export default defineLogicFunction({
   httpRouteTriggerSettings: {
     path: '/post-card/create',
     httpMethod: 'GET',
-    isAuthRequired: false,
+    isAuthRequired: true,
   },
   /*databaseEventTriggerSettings: {
     eventName: 'people.created',
@@ -643,49 +643,15 @@ export default defineLogicFunction({
 **اكتب `description` جيدًا.** يعتمد وكلاء الذكاء الاصطناعي على حقل `description` الخاص بالدالة لتحديد وقت استخدام الأداة. كن محددًا بشأن ما تفعله الأداة ومتى ينبغي استدعاؤها.
 </Note>
 
-</Accordion>
-<Accordion title="definePreInstallLogicFunction" description="تعريف دالة منطقية لما قبل التثبيت (واحدة لكل تطبيق)">
-
-دالة ما قبل التثبيت هي دالة منطقية تعمل تلقائيًا قبل تثبيت تطبيقك على مساحة عمل. يفيد ذلك في مهام التحقق، وفحص المتطلبات المسبقة، أو تجهيز حالة مساحة العمل قبل متابعة التثبيت الرئيسي.
-
-```ts src/logic-functions/pre-install.ts
-import { definePreInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
-
-const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
-  console.log('Pre install logic function executed successfully!', payload.previousVersion);
-};
-
-export default definePreInstallLogicFunction({
-  universalIdentifier: 'e0604b9e-e946-456b-886d-3f27d9a6b324',
-  name: 'pre-install',
-  description: 'Runs before installation to prepare the application.',
-  timeoutSeconds: 300,
-  handler,
-});
-```
-
-يمكنك أيضًا تنفيذ دالة ما قبل التثبيت يدويًا في أي وقت باستخدام CLI:
-
-```bash filename="Terminal"
-yarn twenty exec --preInstall
-```
-
-النقاط الرئيسية:
-* تستخدم دوال ما قبل التثبيت `definePreInstallLogicFunction()` — وهو إصدار متخصص يستبعد إعدادات المُشغِّل (`cronTriggerSettings` و`databaseEventTriggerSettings` و`httpRouteTriggerSettings` و`isTool`).
-* يتلقى المُعالج `InstallLogicFunctionPayload` يحوي `{ previousVersion: string }` — إصدار التطبيق الذي كان مُثبّتًا سابقًا (أو سلسلة فارغة للتثبيتات الجديدة).
-* يُسمح بدالة ما قبل التثبيت واحدة فقط لكل تطبيق. سيُنتج إنشاء ملف البيان خطأً إذا تم اكتشاف أكثر من واحدة.
-* يتم تعيين `universalIdentifier` للدالة تلقائيًا كـ `preInstallLogicFunctionUniversalIdentifier` في بيان التطبيق أثناء الإنشاء — لست بحاجة إلى الإشارة إليه في `defineApplication()`.
-* تم ضبط المهلة الافتراضية على 300 ثانية (5 دقائق) للسماح بمهام التحضير الأطول.
-
 </Accordion>
 <Accordion title="definePostInstallLogicFunction" description="تعريف دالة منطقية لما بعد التثبيت (واحدة لكل تطبيق)">
 
-دالة ما بعد التثبيت هي دالة منطقية تعمل تلقائيًا بعد تثبيت تطبيقك على مساحة عمل. هذا مفيد لمهام الإعداد لمرة واحدة مثل تهيئة البيانات الافتراضية، وإنشاء السجلات الأولية، أو تكوين إعدادات مساحة العمل.
+دالة ما بعد التثبيت هي دالة منطقية تعمل تلقائيًا بعد تثبيت تطبيقك على مساحة عمل. ينفّذه الخادم **بعد** مزامنة البيانات الوصفية للتطبيق وإنشاء عميل SDK، بحيث تكون مساحة العمل جاهزة تمامًا للاستخدام ويكون المخطط الجديد مطبَّقًا. تشمل حالات الاستخدام النموذجية تهيئة البيانات الافتراضية، وإنشاء السجلات الأولية، وتكوين إعدادات مساحة العمل، أو توفير الموارد على خدمات جهات خارجية.
 
 ```ts src/logic-functions/post-install.ts
-import { definePostInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk';
 
-const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+const handler = async (payload: InstallPayload): Promise<void> => {
   console.log('Post install logic function executed successfully!', payload.previousVersion);
 };
 
@@ -694,6 +660,8 @@ export default definePostInstallLogicFunction({
   name: 'post-install',
   description: 'Runs after installation to set up the application.',
   timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: false,
+  shouldRunSynchronously: false,
   handler,
 });
 ```
@@ -706,10 +674,168 @@ yarn twenty exec --postInstall
 
 النقاط الرئيسية:
 * تستخدم دوال ما بعد التثبيت `definePostInstallLogicFunction()` — وهو إصدار متخصص يستبعد إعدادات المُشغِّل (`cronTriggerSettings` و`databaseEventTriggerSettings` و`httpRouteTriggerSettings` و`isTool`).
-* يتلقى المُعالج `InstallLogicFunctionPayload` يحوي `{ previousVersion: string }` — إصدار التطبيق الذي كان مُثبّتًا سابقًا (أو سلسلة فارغة للتثبيتات الجديدة).
+* يتلقى المعالج `InstallPayload` يحتوي على `{ previousVersion?: string; newVersion: string }` — حيث إن `newVersion` هو الإصدار الجاري تثبيته، و`previousVersion` هو الإصدار الذي كان مُثبّتًا سابقًا (أو `undefined` عند التثبيت الأولي). استخدم هذه القيم للتمييز بين عمليات التثبيت الجديدة والترقيات ولتشغيل منطق الترحيل الخاص بالإصدار.
+* **موعد تشغيل الخطاف**: في عمليات التثبيت الجديدة فقط، افتراضيًا. مرّر `shouldRunOnVersionUpgrade: true` إذا كنت تريد تشغيله أيضًا عند ترقية التطبيق من إصدار سابق. عند إغفاله، تكون القيمة الافتراضية للعلم `false`، وتتجاوز الترقيات هذا الخطاف.
+* **نموذج التنفيذ — غير متزامن افتراضيًا، والتزامني اختياري**: يتحكّم العلم `shouldRunSynchronously` في كيفية تنفيذ ما بعد التثبيت.
+  * `shouldRunSynchronously: false` *(الإعداد الافتراضي)* — يتم **إدراج الخطاف في قائمة الرسائل** مع `retryLimit: 3` ويعمل بشكل غير متزامن داخل عامل عمل. يعود ردّ التثبيت بمجرد وضع المهمة في الطابور، لذا فإن معالجًا بطيئًا أو متعطلًا لا يحجب المستدعي. سيُجرِّب العامل إعادة المحاولة حتى ثلاث مرات. **استخدم هذا للمهام طويلة التشغيل** — بَذر مجموعات بيانات كبيرة، استدعاء واجهات برمجة تطبيقات خارجية بطيئة، تهيئة موارد خارجية، أو أي شيء قد يتجاوز نافذة استجابة HTTP المعقولة.
+  * `shouldRunSynchronously: true` — يُنفّذ الخطاف **ضمن تدفّق التثبيت مباشرةً** (نفس المنفِّذ كما قبل التثبيت). يَحجُب طلب التثبيت حتى ينتهي المعالج، وإذا رمى استثناءً، سيتلقى مستدعي التثبيت `POST_INSTALL_ERROR`. لا توجد محاولات إعادة تلقائية. **استخدم هذا للمهام السريعة التي يجب إكمالها قبل الاستجابة** — مثل إظهار خطأ تحقق للمستخدم، أو إعداد سريع سيعتمد عليه العميل مباشرةً بعد عودة نداء التثبيت. ضع في اعتبارك أن ترحيل البيانات الوصفية يكون قد طُبِّق بالفعل عند تشغيل ما بعد التثبيت، لذلك فإن فشل الوضع المتزامن **لا** يعيد التغييرات على المخطط إلى الوراء — بل يكتفي بإبراز الخطأ.
+* تأكّد من أن معالجك قابل للتنفيذ المتكرر دون آثار جانبية. في الوضع غير المتزامن قد تُعيد قائمة الانتظار المحاولة حتى ثلاث مرات؛ وفي أي من الوضعين قد يعمل الخطاف مجددًا أثناء الترقيات عند ضبط `shouldRunOnVersionUpgrade: true`.
+* متغيرات البيئة `APPLICATION_ID` و`APP_ACCESS_TOKEN` و`API_URL` متاحة داخل المعالج (كما في أي دالة منطق أخرى)، لذا يمكنك استدعاء واجهة Twenty API باستخدام رمز وصول للتطبيق مقيّد بنطاق تطبيقك.
 * يُسمح بدالة ما بعد التثبيت واحدة فقط لكل تطبيق. سيُنتج إنشاء ملف البيان خطأً إذا تم اكتشاف أكثر من واحدة.
-* يتم تعيين `universalIdentifier` للدالة تلقائيًا كـ `postInstallLogicFunctionUniversalIdentifier` في بيان التطبيق أثناء الإنشاء — لست بحاجة إلى الإشارة إليه في `defineApplication()`.
+* تُرفَق خصائص الدالة `universalIdentifier` و`shouldRunOnVersionUpgrade` و`shouldRunSynchronously` تلقائيًا ببيان التطبيق ضمن الحقل `postInstallLogicFunction` أثناء عملية البناء — ولا تحتاج إلى الإشارة إليها في `defineApplication()`.
 * تم تعيين مهلة افتراضية إلى 300 ثانية (5 دقائق) للسماح بمهام الإعداد الأطول مثل تهيئة البيانات.
+* **لا يُنفَّذ في وضع التطوير**: عند تسجيل تطبيق محليًا (عبر `yarn twenty dev`)، يتجاوز الخادم تدفّق التثبيت بالكامل ويُزامن الملفات مباشرةً عبر مراقِب CLI — لذا لن يعمل ما بعد التثبيت في وضع التطوير مطلقًا، بغضّ النظر عن `shouldRunSynchronously`. استخدم `yarn twenty exec --postInstall` لتشغيله يدويًا على مساحة عمل قيد التشغيل.
+
+</Accordion>
+<Accordion title="definePreInstallLogicFunction" description="تعريف دالة منطقية لما قبل التثبيت (واحدة لكل تطبيق)">
+
+دالة ما قبل التثبيت هي دالة منطقية تعمل تلقائيًا أثناء التثبيت، **قبل تطبيق ترحيل البيانات الوصفية لمساحة العمل**. تتشارك نفس بنية الحمولة مع ما بعد التثبيت (`InstallPayload`)، لكنها موضوعة أبكر في تدفّق التثبيت كي تجهّز حالة يعتمد عليها الترحيل القادم — ومن الاستخدامات الشائعة: نسخ البيانات احتياطيًا، التحقق من التوافق مع المخطط الجديد، أو أرشفة السجلات التي ستُعاد هيكلتها أو ستُحذف.
+
+```ts src/logic-functions/pre-install.ts
+import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk';
+
+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,
+});
+```
+
+يمكنك أيضًا تنفيذ دالة ما قبل التثبيت يدويًا في أي وقت باستخدام CLI:
+
+```bash filename="Terminal"
+yarn twenty exec --preInstall
+```
+
+النقاط الرئيسية:
+* تستخدم دوال ما قبل التثبيت `definePreInstallLogicFunction()` — نفس الإعدادات المتخصصة كما في ما بعد التثبيت، لكنها مرتبطة بموضع مختلف ضمن دورة الحياة.
+* يتلقّى كلٌّ من معالجي ما قبل التثبيت وما بعد التثبيت النوع نفسه `InstallPayload`: `{ previousVersion?: string; newVersion: string }`. استورده مرة واحدة وأعد استخدامه لكلا الخطافين.
+* **موعد تشغيل الخطاف**: موضوع مباشرةً قبل ترحيل البيانات الوصفية لمساحة العمل (`synchronizeFromManifest`). قبل التنفيذ، يُشغِّل الخادم مزامنة "pared-down sync" ذات طابع إضافي فقط تقوم بتسجيل دالة ما قبل التثبيت للإصدار **الجديد** في البيانات الوصفية لمساحة العمل — دون لمس أي شيء آخر — ثم يُنفّذها. لأن هذه المزامنة «إضافية فقط»، تبقى كائنات وحقول وبيانات الإصدار السابق سليمة عند تشغيل معالجك: يمكنك قراءة حالة ما قبل الترحيل ونسخها احتياطيًا بأمان.
+* **نموذج التنفيذ**: يُنفَّذ ما قبل التثبيت **بشكل متزامن** و**يحجب عملية التثبيت**. إذا رمى المعالج استثناءً، تُلغى عملية التثبيت قبل تطبيق أي تغييرات على المخطط — وتبقى مساحة العمل على الإصدار السابق بحالة متّسقة. هذا مقصود: ما قبل التثبيت هو فرصتك الأخيرة لرفض ترقية تنطوي على مخاطر.
+* كما هو الحال مع ما بعد التثبيت، يُسمح بدالة ما قبل التثبيت واحدة فقط لكل تطبيق. تُربَط تلقائيًا ببيان التطبيق تحت `preInstallLogicFunction` أثناء عملية البناء.
+* **لا يُنفَّذ في وضع التطوير**: كما في ما بعد التثبيت — يتم تجاوز تدفّق التثبيت بالكامل للتطبيقات المسجّلة محليًا، لذا لن يعمل ما قبل التثبيت مطلقًا عند `yarn twenty dev`. استخدم `yarn twenty exec --preInstall` لتشغيله يدويًا.
+
+</Accordion>
+<Accordion title="ما قبل التثبيت مقابل ما بعد التثبيت: متى تستخدم أيّهما" description="اختيار خطاف التثبيت المناسب">
+
+كلا الخطافين جزء من تدفّق التثبيت نفسه ويتلقّيان نفس `InstallPayload`. الاختلاف يكمن في **موعد** تشغيلهما نسبةً إلى ترحيل البيانات الوصفية لمساحة العمل، وهذا يغيّر البيانات التي يمكنهما التعامل معها بأمان.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ install flow                                                │
+│                                                             │
+│   upload package → [pre-install] → metadata migration →     │
+│   generate SDK → [post-install]                             │
+│                                                             │
+│                  old schema visible    new schema visible   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+ما قبل التثبيت دائمًا **متزامن** (يحجب التثبيت ويمكنه إحباطه). ما بعد التثبيت **غير متزامن افتراضيًا** — يُدرج على عامل مع محاولات إعادة تلقائية — لكن يمكن التبديل إلى تنفيذ متزامن عبر `shouldRunSynchronously: true`. راجع الأكورديون `definePostInstallLogicFunction` أعلاه لمعرفة متى تستخدم كل وضع.
+
+**استخدم `post-install` لأي شيء يتطلّب وجود المخطط الجديد.** وهذا هو السيناريو الشائع:
+
+* بَذر بيانات افتراضية (إنشاء سجلات أولية وعروض افتراضية ومحتوى تجريبي) للكائنات والحقول المضافة حديثًا.
+* تسجيل خطافات الويب مع خدمات أطراف ثالثة بعد أن حصل التطبيق على بيانات الاعتماد الخاصة به.
+* استدعاء واجهة برمجة التطبيقات الخاصة بك لإكمال إعداد يعتمد على البيانات الوصفية المتزامنة.
+* منطق idempotent لتحقيق "تأكّد من وجود هذا" والذي ينبغي مواءمة الحالة في كل ترقية — بالاقتران مع `shouldRunOnVersionUpgrade: true`.
+
+مثال — بَذر سجل `PostCard` افتراضي بعد التثبيت:
+
+```ts src/logic-functions/post-install.ts
+import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk';
+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,
+});
+```
+
+**استخدم `pre-install` عندما قد يُتلف الترحيل أو يدمّر البيانات الحالية.** لأن ما قبل التثبيت يعمل مقابل المخطط *السابق* وفشله يُرجِع الترقية إلى الوراء، فهو المكان المناسب لأي شيء محفوف بالمخاطر:
+
+* **نسخ البيانات احتياطيًا قبل حذفها أو إعادة هيكلتها** — مثل إزالة حقل في v2 وتحتاج إلى نسخ قيمه إلى حقل آخر أو تصديرها إلى التخزين قبل تشغيل الترحيل.
+* **أرشفة السجلات التي سيبطلها قيد جديد** — مثل أن يصبح حقل ما `NOT NULL` وتحتاج أولًا إلى حذف الصفوف ذات القيم الفارغة أو إصلاحها.
+* **التحقق من التوافق ورفض الترقية إذا تعذّر ترحيل البيانات الحالية بسلاسة** — ارمِ من داخل المعالج وسيُلغى التثبيت دون تطبيق أي تغييرات. هذا أكثر أمانًا من اكتشاف عدم التوافق في منتصف الترحيل.
+* **إعادة تسمية البيانات أو إعادة تعيين مفاتيحها** قبل تغيير في المخطط قد يؤدي إلى فقدان الارتباط.
+
+مثال — أرشف السجلات قبل ترحيل هدّام:
+
+```ts src/logic-functions/pre-install.ts
+import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk';
+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,
+});
+```
+
+**قاعدة عامة:**
+
+| ترغب في…                                                                       | استخدام                                                                                          |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| بذر بيانات افتراضية، تهيئة مساحة العمل، تسجيل موارد خارجية                     | `post-install`                                                                                   |
+| تشغيل بذر طويل الأمد أو استدعاءات أطراف ثالثة لا ينبغي أن تحجب استجابة التثبيت | `post-install` (الإعداد الافتراضي — `shouldRunSynchronously: false`، مع محاولات إعادة من العامل) |
+| تشغيل إعداد سريع سيعتمد عليه المستدعي مباشرةً بعد عودة نداء التثبيت            | `post-install` مع `shouldRunSynchronously: true`                                                 |
+| قراءة البيانات أو نسخها احتياطيًا والتي قد يفقدها الترحيل القادم               | `pre-install`                                                                                    |
+| رفض ترقية قد تُفسد البيانات الحالية                                            | `pre-install` (ارمِ من المعالج)                                                                  |
+| تنفيذ مواءمة في كل ترقية                                                       | `post-install` مع `shouldRunOnVersionUpgrade: true`                                              |
+| تنفيذ إعداد لمرة واحدة في التثبيت الأول فقط                                    | `post-install` مع `shouldRunOnVersionUpgrade: false` (الإعداد الافتراضي)                         |
+
+<Note>
+إذا ساورك الشك، فاجعل الافتراضي هو **post-install**. الجأ إلى ما قبل التثبيت فقط عندما يكون الترحيل نفسه هدّامًا وتحتاج إلى التقاط الحالة السابقة قبل أن تزول.
+</Note>
 
 </Accordion>
 <Accordion title="defineFrontComponent" description="عرِّف مكوّنات أمامية لواجهة مستخدم مخصّصة">
@@ -1816,8 +1942,7 @@ 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 pre-install or post-install functions
-yarn twenty exec --preInstall
+# Execute the post-install function
 yarn twenty exec --postInstall
 ```
 

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

@@ -220,6 +220,7 @@ npx create-twenty-app@latest my-twenty-app --example postcard
 | -------------------------------------- | --------------------------------------------- |
 | `yarn twenty server start`             | بدء الخادم المحلي (يسحب الصورة إذا لزم الأمر) |
 | `yarn twenty server start --port 3030` | ابدأ على منفذ مخصّص                           |
+| `yarn twenty server start --test`      | ابدأ مثيل اختبار منفصل على المنفذ 2021        |
 | `yarn twenty server stop`              | إيقاف الخادم (مع الحفاظ على البيانات)         |
 | `yarn twenty server status`            | عرض حالة الخادم، وعنوان URL، وبيانات الاعتماد |
 | `yarn twenty server logs`              | بث سجلات الخادم                               |
@@ -228,6 +229,20 @@ npx create-twenty-app@latest my-twenty-app --example postcard
 
 يتم الاحتفاظ بالبيانات عبر عمليات إعادة التشغيل في وحدتي تخزين Docker (`twenty-app-dev-data` لـ PostgreSQL، و`twenty-app-dev-storage` للملفات). استخدم `reset` لمسح كل شيء والبدء من جديد.
 
+### تشغيل مثيل الاختبار
+
+مرر `--test` إلى أي أمر `server` لإدارة مثيل ثانٍ معزول تمامًا — مفيد لتشغيل اختبارات التكامل أو للتجربة من دون لمس بيانات التطوير الرئيسية لديك.
+
+| أمر                                | الوصف                                                |
+| ---------------------------------- | ---------------------------------------------------- |
+| `yarn twenty server start --test`  | بدء مثيل الاختبار (المنفذ الافتراضي 2021)            |
+| `yarn twenty server stop --test`   | إيقاف مثيل الاختبار                                  |
+| `yarn twenty server status --test` | عرض حالة مثيل الاختبار، وعنوان URL، وبيانات الاعتماد |
+| `yarn twenty server logs --test`   | بث سجلات مثيل الاختبار                               |
+| `yarn twenty server reset --test`  | محو بيانات الاختبار والبدء من جديد                   |
+
+يعمل مثيل الاختبار في حاوية Docker خاصة به (`twenty-app-dev-test`) مع وحدات تخزين مخصصة (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) وتهيئة مستقلة، بحيث يمكنه العمل بالتوازي مع مثيلك الرئيسي من دون تعارضات. اجمع `--test` مع `--port` لتجاوز القيمة الافتراضية 2021.
+
 <Note>
   يتطلّب الخادم أن يكون **Docker** قيد التشغيل. إذا ظهرت لك رسالة خطأ "Docker not running"، فتأكّد من تشغيل Docker Desktop (أو خادوم Docker).
 </Note>

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

@@ -66,14 +66,71 @@ yarn twenty deploy
 
 ### إدارة الإصدارات
 
+عند تحديث تطبيق tarball منشور مسبقًا، يشترط الخادم أن تكون قيمة `version` في `package.json` **أعلى قطعًا** (وفق ترتيب [الإصدار الدلالي](https://semver.org)) من الإصدار المنشور حاليًا. إعادة نشر الإصدار نفسه، أو دفع إصدار أدنى، يُرفَض قبل تخزين ملف tarball — سترى خطأ `VERSION_ALREADY_EXISTS` من CLI.
+
 لطرح تحديث:
 
-1. ارفع قيمة الحقل `version` في ملف `package.json`
+1. قم بزيادة الحقل `version` في ملف `package.json` (مثلًا: `1.2.3` → `1.2.4`، `1.3.0`، أو `2.0.0`)
 2. شغّل `yarn twenty deploy` (أو `yarn twenty deploy --remote production`)
 3. سترى مساحات العمل التي ثبّتت التطبيق الترقية متاحة في إعداداتها
 
+<Note>
+علامات ما قبل الإصدار تعمل كما هو متوقع: زيادة `1.0.0-rc.1` → `1.0.0-rc.2` مسموح بها، ويُعترَف بالإصدار النهائي مثل `1.0.0` على أنه أعلى من `1.0.0-rc.5`. يجب أن يكون الإصدار في `package.json` بنفسه سلسلة semver صالحة.
+</Note>
+
 {/* TODO: add screenshot of the Upgrade button */}
 
+## CI/CD المؤتمتة (مهام سير عمل مُولَّدة بالقوالب)
+
+التطبيقات المُولَّدة باستخدام `create-twenty-app` تأتي افتراضيًا مع مهمَّتي سير عمل من GitHub Actions ضمن `.github/workflows/`. هي جاهزة للتشغيل بمجرد دفع المستودع إلى GitHub — لا حاجة لأي إعداد إضافي لـ CI، وCD يتطلّب سرًّا واحدًا فقط.
+
+### CI — `ci.yml`
+
+يشغّل اختبارات التكامل عند كل دفع إلى `main` وعند كل طلب سحب.
+
+**ماذا يفعل:**
+
+1. يجلب مصدر تطبيقك.
+2. ينشئ مثيلاً اختبارياً معزولاً من Twenty باستخدام الإجراء المركّب `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main` (المكافئ في CI للأمر `yarn twenty server start --test`).
+3. يُفعِّل Corepack، ويُعدّ Node.js من ملف `.nvmrc` لديك، ويثبّت التبعيات بواسطة `yarn install --immutable`.
+4. يشغّل `yarn test`، ويمرّر `TWENTY_API_URL` و`TWENTY_API_KEY` من المثيل الذي تم إنشاؤه بحيث تتمكّن اختباراتك من التواصل مع خادم حقيقي.
+
+**خيارات التكوين:**
+
+* `TWENTY_VERSION` (متغيّر بيئة، القيمة الافتراضية `latest`) — ثبّت نسخة خادم Twenty المستخدمة في CI عبر تعديل هذا في `ci.yml`.
+* يتم تجميع التشغيل المتزامن حسب `github.ref` ويلغي التشغيلات قيد التقدّم عند أي دفع جديد.
+
+لا تتطلّب أي أسرار — مثيل الاختبار مؤقّت ويستمر فقط طوال مدّة المهمّة.
+
+### CD — `cd.yml`
+
+ينشر تطبيقك إلى خادم Twenty مُهيّأ عند كل دفع إلى `main`، وبشكل اختياري من طلب سحب عند تطبيق الوسم `deploy`.
+
+**ماذا يفعل:**
+
+1. يجلب رأس طلب السحب (للطلبات الموسومة) أو الالتزام المدفوع.
+2. يشغّل `twentyhq/twenty/.github/actions/deploy-twenty-app@main` — وهو المكافئ في CI للأمر `yarn twenty deploy`.
+3. يشغّل `twentyhq/twenty/.github/actions/install-twenty-app@main` بحيث تُثبَّت النسخة المُنشَرة حديثًا في مساحة العمل المستهدفة.
+
+**التكوين المطلوب:**
+
+| الإعداد                 | حيث                                                             | الغرض                                                                                    |
+| ----------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `TWENTY_DEPLOY_URL`     | `env` في `cd.yml` (القيمة الافتراضية `http://localhost:3000`)   | خادم Twenty الذي سيتم النشر إليه. غيّر هذا إلى عنوان URL لخادمك الحقيقي قبل أول استخدام. |
+| `TWENTY_DEPLOY_API_KEY` | في مستودع GitHub **Settings → Secrets and variables → Actions** | مفتاح API يمتلك إذن النشر على الخادم المستهدف.                                           |
+
+<Note>
+القيمة الافتراضية لـ `TWENTY_DEPLOY_URL` وهي `http://localhost:3000` مجرد عنصر نائب — لن تصل إلى أي شيء من مُشغِّل مستضاف لدى GitHub. حدّثها إلى عنوان URL العام لخادمك (أو استخدم مُشغِّلًا مستضافًا ذاتيًا مع وصول شبكي) قبل تمكين CD.
+</Note>
+
+**تشغيل نشر معاينة من طلب سحب:**
+
+أضِف الوسم `deploy` إلى طلب سحب. الشرط `if:` في `cd.yml` سيشغّل المهمّة لذلك الطلب مستخدمًا التزام رأس الطلب، مما يتيح لك التحقّق من التغيير على الخادم المستهدف قبل الدمج.
+
+### تثبيت الإجراءات القابلة لإعادة الاستخدام
+
+يشير كلا سيرَي العمل إلى إجراءات قابلة لإعادة الاستخدام عند `@main`، لذا تُلتقط تحديثات الإجراءات في مستودع `twentyhq/twenty` تلقائيًا. إذا كنت تريد بناءات حتمية، فاستبدِل `@main` بقيمة SHA لالتزام أو بوسم إصدار في كل سطر `uses:`.
+
 ## النشر على npm
 
 يُتيح النشر على npm إمكانية العثور على تطبيقك في سوق Twenty. يمكن لأي مساحة عمل في Twenty استعراض تطبيقات السوق وتثبيتها وترقيتها مباشرةً من واجهة المستخدم.
@@ -81,7 +138,7 @@ yarn twenty deploy
 ### المتطلبات
 
 * حساب على [npm](https://www.npmjs.com)
-* الكلمة المفتاحية `twenty-app` في مصفوفة `keywords` في `package.json` (موجودة مسبقًا عند تهيئة المشروع باستخدام `create-twenty-app`)
+* الكلمة المفتاحية `twenty-app` في مصفوفة `keywords` في `package.json` (أضفها يدويًا — فهي غير مضمنة افتراضيًا في قالب `create-twenty-app`)
 
 ```json filename="package.json"
 {
@@ -189,3 +246,12 @@ jobs:
 ```bash filename="Terminal"
 yarn twenty install
 ```
+
+<Note>
+يفرض الخادم اعتماد إصدارات semver عند التثبيت، بما يعكس القواعد المطبّقة عند النشر:
+
+* تثبيت الإصدار نفسه المثبّت بالفعل في مساحة عملك يُرفَض بخطأ `APP_ALREADY_INSTALLED`.
+* تثبيت إصدار أدنى من الإصدار المثبّت حاليًا يُرفَض بخطأ `CANNOT_DOWNGRADE_APPLICATION`.
+
+لتثبيت إصدار أحدث، انشره (deploy) أو انشره إلى السجل (publish) أولًا، ثم أعد تشغيل `yarn twenty install`.
+</Note>

packages/twenty-docs/l/ar/user-guide/data-migration/how-tos/fix-import-errors.mdx

@@ -140,12 +140,12 @@ description: دليل شامل لاستكشاف أخطاء استيراد CSV و
 #### تاريخ
 
 **المشكلة:** تنسيق تاريخ غير معروف
-**الحل:** استخدم تنسيقًا متّسقًا في جميع أنحاء الملف
+**الحل:** استخدم تنسيق `YYYY-MM-DD` بشكل متّسق في جميع أنحاء الملف
 
 ```
-✓ 2024-03-15        (YYYY-MM-DD - recommended)
-✓ 03/15/2024        (MM/DD/YYYY)
-✓ 15/03/2024        (DD/MM/YYYY)
+✓ 2024-03-15        (YYYY-MM-DD)
+❌ 03/15/2024        (MM/DD/YYYY)
+❌ 15/03/2024        (DD/MM/YYYY)
 ```
 
 #### هاتف

packages/twenty-docs/l/ar/user-guide/data-migration/how-tos/prepare-your-csv-files.mdx

@@ -103,8 +103,6 @@ description: دليل كامل خطوة بخطوة لتنسيق بياناتك
 استخدم تنسيقًا موحدًا في كامل ملفك:
 
 * `YYYY-MM-DD` (مُوصى به): `2024-03-15`
-* `MM/DD/YYYY`: `03/15/2024`
-* `DD/MM/YYYY`: `15/03/2024`
 * ISO 8601: `2024-03-15T10:30:00Z`
 
 ### حقول الأرقام

packages/twenty-docs/l/cs/developers/contribute/capabilities/backend-development/server-commands.mdx

@@ -47,7 +47,7 @@ npx nx run twenty-server:database:reset
 #### Pro objekty ve schématech Core/Metadata (TypeORM)
 
 ```bash
-npx nx run twenty-server:typeorm migration:generate src/database/typeorm/core/migrations/nameOfYourMigration -d src/database/typeorm/core/core.datasource.ts
+npx nx run twenty-server:database:migrate:generate
 ```
 
 ## Technologický stack

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

@@ -476,7 +476,7 @@ export default defineLogicFunction({
   httpRouteTriggerSettings: {
     path: '/post-card/create',
     httpMethod: 'GET',
-    isAuthRequired: false,
+    isAuthRequired: true,
   },
   /*databaseEventTriggerSettings: {
     eventName: 'people.created',
@@ -644,49 +644,15 @@ export default defineLogicFunction({
 **Napište kvalitní `description`.** Agenti AI se spoléhají na pole funkce `description` při rozhodování, kdy nástroj použít. Buďte konkrétní ohledně toho, co nástroj dělá a kdy se má volat.
 </Note>
 
-</Accordion>
-<Accordion title="definePreInstallLogicFunction" description="Definujte předinstalační logickou funkci (jedna na aplikaci)">
-
-Předinstalační funkce je logická funkce, která se automaticky spouští před instalací vaší aplikace v pracovním prostoru. To je užitečné pro validační úlohy, kontrolu předpokladů nebo přípravu stavu pracovního prostoru před zahájením hlavní instalace.
-
-```ts src/logic-functions/pre-install.ts
-import { definePreInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
-
-const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
-  console.log('Pre install logic function executed successfully!', payload.previousVersion);
-};
-
-export default definePreInstallLogicFunction({
-  universalIdentifier: 'e0604b9e-e946-456b-886d-3f27d9a6b324',
-  name: 'pre-install',
-  description: 'Runs before installation to prepare the application.',
-  timeoutSeconds: 300,
-  handler,
-});
-```
-
-Předinstalační funkci můžete také kdykoli spustit ručně pomocí CLI:
-
-```bash filename="Terminal"
-yarn twenty exec --preInstall
-```
-
-Hlavní body:
-* Předinstalační funkce používají `definePreInstallLogicFunction()` — specializovanou variantu, která vynechává nastavení spouštěčů (`cronTriggerSettings`, `databaseEventTriggerSettings`, `httpRouteTriggerSettings`, `isTool`).
-* Obslužná funkce (handler) obdrží `InstallLogicFunctionPayload` s `{ previousVersion: string }` — verzi aplikace, která byla dříve nainstalována (nebo prázdný řetězec při čisté instalaci).
-* Na jednu aplikaci je povolena pouze jedna předinstalační funkce. Sestavení manifestu skončí chybou, pokud je zjištěna více než jedna.
-* Identifikátor `universalIdentifier` funkce se během sestavení automaticky nastaví v manifestu aplikace jako `preInstallLogicFunctionUniversalIdentifier` — není potřeba jej uvádět v `defineApplication()`.
-* Výchozí časový limit je nastaven na 300 sekund (5 minut), aby umožnil delší přípravné úlohy.
-
 </Accordion>
 <Accordion title="definePostInstallLogicFunction" description="Definujte postinstalační logickou funkci (jedna na aplikaci)">
 
-Postinstalační funkce je logická funkce, která se automaticky spouští po instalaci vaší aplikace do pracovního prostoru. To je užitečné pro jednorázové úlohy nastavení, jako je naplnění výchozími daty, vytvoření počátečních záznamů nebo konfigurace nastavení pracovního prostoru.
+Postinstalační funkce je logická funkce, která se spustí automaticky, jakmile je instalace vaší aplikace v pracovním prostoru dokončena. Server ji provede **poté**, co byla synchronizována metadata aplikace a vygenerován klient SDK, takže je pracovní prostor plně připraven k použití a nové schéma je zavedeno. Mezi typické případy použití patří naplnění výchozími daty, vytvoření počátečních záznamů, konfigurace nastavení pracovního prostoru nebo zřizování prostředků ve službách třetích stran.
 
 ```ts src/logic-functions/post-install.ts
-import { definePostInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk';
 
-const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+const handler = async (payload: InstallPayload): Promise<void> => {
   console.log('Post install logic function executed successfully!', payload.previousVersion);
 };
 
@@ -695,6 +661,8 @@ export default definePostInstallLogicFunction({
   name: 'post-install',
   description: 'Runs after installation to set up the application.',
   timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: false,
+  shouldRunSynchronously: false,
   handler,
 });
 ```
@@ -707,10 +675,168 @@ yarn twenty exec --postInstall
 
 Hlavní body:
 * Postinstalační funkce používají `definePostInstallLogicFunction()` — specializovanou variantu, která vynechává nastavení spouštěčů (`cronTriggerSettings`, `databaseEventTriggerSettings`, `httpRouteTriggerSettings`, `isTool`).
-* Obslužná funkce (handler) obdrží `InstallLogicFunctionPayload` s `{ previousVersion: string }` — verzi aplikace, která byla dříve nainstalována (nebo prázdný řetězec při čisté instalaci).
+* Obslužná funkce obdrží `InstallPayload` s `{ previousVersion?: string; newVersion: string }` — `newVersion` je verze, která se instaluje, a `previousVersion` je verze, která byla nainstalována dříve (nebo `undefined` při čisté instalaci). Tyto hodnoty použijte k rozlišení čistých instalací od aktualizací a ke spuštění migrační logiky specifické pro verzi.
+* **Kdy se hook spouští**: ve výchozím nastavení pouze při čistých instalacích. Předejte `shouldRunOnVersionUpgrade: true`, pokud chcete, aby se spouštěl i při aktualizaci aplikace z předchozí verze. Pokud je vynechán, příznak má výchozí hodnotu `false` a při aktualizacích se hook přeskočí.
+* **Model provádění — ve výchozím nastavení asynchronní, synchronní volitelně**: příznak `shouldRunSynchronously` určuje *jak* se spouští post-install.
+  * `shouldRunSynchronously: false` *(výchozí)* — hook je **zařazen do fronty zpráv** s `retryLimit: 3` a běží asynchronně ve workeru. Odezva instalace se vrátí hned po zařazení úlohy do fronty, takže pomalá nebo chybující obslužná funkce neblokuje volajícího. Worker se pokusí o opakování až třikrát. **Použijte pro dlouho běžící úlohy** — plnění velkých datových sad, volání pomalých externích API, zřizování externích prostředků, cokoli, co by mohlo přesáhnout rozumné časové okno HTTP odezvy.
+  * `shouldRunSynchronously: true` — hook se provádí **inline během instalačního procesu** (stejný vykonavatel jako pre-install). Instalační požadavek blokuje, dokud obslužná funkce nedokončí, a pokud vyvolá výjimku, volající instalace obdrží `POST_INSTALL_ERROR`. Žádné automatické opakování. **Použijte pro rychlé úlohy, které se musí dokončit před odpovědí** — například vrácení validační chyby uživateli nebo rychlé nastavení, na kterém bude klient záviset ihned po návratu volání instalace. Mějte na paměti, že v době, kdy se spustí post-install, už byla migrace metadat aplikována, takže selhání v synchronním režimu změny schématu **ne**vrací zpět — pouze odhalí chybu.
+* Ujistěte se, že vaše obslužná funkce je idempotentní. V asynchronním režimu se může fronta pokusit až třikrát; v obou režimech se může hook znovu spustit při aktualizacích, pokud je `shouldRunOnVersionUpgrade: true`.
+* Proměnné prostředí `APPLICATION_ID`, `APP_ACCESS_TOKEN` a `API_URL` jsou dostupné uvnitř obslužné funkce (stejně jako u jakékoli jiné logické funkce), takže můžete volat Twenty API s aplikačním přístupovým tokenem omezeným na vaši aplikaci.
 * Na jednu aplikaci je povolena pouze jedna postinstalační funkce. Sestavení manifestu skončí chybou, pokud je zjištěna více než jedna.
-* Identifikátor `universalIdentifier` funkce se během sestavení automaticky nastaví v manifestu aplikace jako `postInstallLogicFunctionUniversalIdentifier` — není potřeba jej uvádět v `defineApplication()`.
+* Atributy funkce `universalIdentifier`, `shouldRunOnVersionUpgrade` a `shouldRunSynchronously` jsou během buildu automaticky připojeny k manifestu aplikace do pole `postInstallLogicFunction` — není potřeba je uvádět v `defineApplication()`.
 * Výchozí časový limit je nastaven na 300 sekund (5 minut), aby umožnil delší úlohy nastavení, jako je naplnění daty.
+* **Nespouští se v režimu dev**: když je aplikace registrována lokálně (pomocí `yarn twenty dev`), server zcela přeskočí instalační tok a synchronizuje soubory přímo prostřednictvím sledovače CLI — takže se post-install v režimu dev nikdy nespustí bez ohledu na `shouldRunSynchronously`. Použijte `yarn twenty exec --postInstall` k ručnímu spuštění nad běžícím pracovním prostorem.
+
+</Accordion>
+<Accordion title="definePreInstallLogicFunction" description="Definujte předinstalační logickou funkci (jedna na aplikaci)">
+
+Funkce pre-install je logická funkce, která se během instalace spouští automaticky, **před aplikováním migrace metadat pracovního prostoru**. Má stejný tvar payloadu jako post-install (`InstallPayload`), ale je zařazena dříve v instalačním toku, aby mohla připravit stav, na němž nadcházející migrace závisí — typické použití zahrnuje zálohování dat, ověření kompatibility s novým schématem nebo archivaci záznamů, které se chystají přeuspořádat nebo odstranit.
+
+```ts src/logic-functions/pre-install.ts
+import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk';
+
+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,
+});
+```
+
+Předinstalační funkci můžete také kdykoli spustit ručně pomocí CLI:
+
+```bash filename="Terminal"
+yarn twenty exec --preInstall
+```
+
+Hlavní body:
+* Funkce pre-install používají `definePreInstallLogicFunction()` — stejné specializované nastavení jako u post-install, pouze připojené k jiné fázi životního cyklu.
+* Obě obslužné funkce pre- i post-install přijímají stejný typ `InstallPayload`: `{ previousVersion?: string; newVersion: string }`. Importujte jej jednou a znovu použijte pro oba hooky.
+* **Kdy se hook spouští**: umístěn těsně před migrací metadat pracovního prostoru (`synchronizeFromManifest`). Před spuštěním server provede čistě aditivní "zjednodušenou synchronizaci", která v metadatech pracovního prostoru zaregistruje pre-install funkci **nové** verze — ničeho dalšího se nedotkne — a poté ji spustí. Protože tato synchronizace je pouze aditivní, objekty, pole a data předchozí verze zůstávají při spuštění vaší obslužné funkce zachována: můžete bezpečně číst a zálohovat stav před migrací.
+* **Model provádění**: pre-install se provádí **synchronně** a **blokuje instalaci**. Pokud obslužná funkce vyvolá výjimku, instalace se přeruší ještě před aplikováním jakýchkoli změn schématu — pracovní prostor zůstane na předchozí verzi v konzistentním stavu. Je to záměrné: pre-install je vaše poslední šance odmítnout rizikovou aktualizaci.
+* Stejně jako u post-install je na jednu aplikaci povolena pouze jedna funkce pre-install. Během buildu je automaticky připojena k manifestu aplikace pod `preInstallLogicFunction`.
+* **Nespouští se v režimu dev**: stejně jako u post-install — u lokálně registrovaných aplikací je instalační tok zcela přeskočen, takže se pre-install pod `yarn twenty dev` nikdy nespustí. Použijte `yarn twenty exec --preInstall` k ručnímu spuštění.
+
+</Accordion>
+<Accordion title="Pre-install vs post-install: kdy použít který" description="Výběr správného instalačního hooku">
+
+Oba hooky jsou součástí téhož instalačního toku a přijímají stejný `InstallPayload`. Rozdíl je v tom, **kdy** se spouštějí vzhledem k migraci metadat pracovního prostoru, a to určuje, jakých dat se mohou bezpečně dotýkat.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ install flow                                                │
+│                                                             │
+│   upload package → [pre-install] → metadata migration →     │
+│   generate SDK → [post-install]                             │
+│                                                             │
+│                  old schema visible    new schema visible   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Pre-install je vždy **synchronní** (blokuje instalaci a může ji přerušit). Post-install je **ve výchozím nastavení asynchronní** — zařazen do workeru s automatickými pokusy o opakování — ale může přejít na synchronní provádění pomocí `shouldRunSynchronously: true`. Viz accordion `definePostInstallLogicFunction` výše, kdy použít jednotlivé režimy.
+
+**Použijte `post-install` pro cokoli, co vyžaduje existenci nového schématu.** To je běžný případ:
+
+* Plnění výchozími daty (vytváření počátečních záznamů, výchozích pohledů, demo obsahu) vůči nově přidaným objektům a polím.
+* Registrace webhooků u služeb třetích stran poté, co má aplikace své přihlašovací údaje.
+* Volání vlastního API k dokončení nastavení, které závisí na synchronizovaných metadatech.
+* Idempotentní logika "zajisti, že to existuje", která má při každé aktualizaci uvést stav do souladu — kombinujte s `shouldRunOnVersionUpgrade: true`.
+
+Příklad — po instalaci naplňte výchozí záznam `PostCard`:
+
+```ts src/logic-functions/post-install.ts
+import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk';
+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,
+});
+```
+
+**Použijte `pre-install`, pokud by migrace jinak zničila nebo poškodila existující data.** Protože pre-install běží proti *předchozímu* schématu a jeho selhání vrací aktualizaci zpět, je to správné místo pro cokoli rizikového:
+
+* **Zálohování dat, která se chystají odstranit nebo přeuspořádat** — např. odstraňujete pole ve verzi v2 a potřebujete jeho hodnoty zkopírovat do jiného pole nebo je před spuštěním migrace exportovat do úložiště.
+* **Archivace záznamů, které by nové omezení zneplatnilo** — např. pole se stává `NOT NULL` a je třeba nejprve smazat nebo opravit řádky s hodnotami null.
+* **Ověření kompatibility a odmítnutí aktualizace, pokud nelze aktuální data čistě migrovat** — vyhoďte výjimku z obslužné funkce a instalace se ukončí bez provedených změn. Je to bezpečnější, než zjistit nekompatibilitu uprostřed migrace.
+* **Přejmenování nebo změna klíčů dat** před změnou schématu, která by ztratila vazby.
+
+Příklad — archivujte záznamy před destruktivní migrací:
+
+```ts src/logic-functions/pre-install.ts
+import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk';
+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,
+});
+```
+
+**Zlaté pravidlo:**
+
+| Chcete…                                                                                           | Použít                                                                                   |
+| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Naplňte výchozí data, nakonfigurujte pracovní prostor, zaregistrujte externí prostředky           | `post-install`                                                                           |
+| Spusťte dlouho běžící plnění nebo volání třetích stran, která by neměla blokovat odezvu instalace | `post-install` (výchozí — `shouldRunSynchronously: false`, s opakovanými pokusy workeru) |
+| Spusťte rychlé nastavení, na které bude volající spoléhat ihned po návratu volání instalace       | `post-install` s `shouldRunSynchronously: true`                                          |
+| Čtěte nebo zálohujte data, která by nadcházející migrace ztratila                                 | `pre-install`                                                                            |
+| Odmítněte aktualizaci, která by poškodila existující data                                         | `pre-install` (vyhoďte výjimku z obslužné funkce)                                        |
+| Spouštějte srovnání stavu při každé aktualizaci                                                   | `post-install` s `shouldRunOnVersionUpgrade: true`                                       |
+| Proveďte jednorázové nastavení pouze při první instalaci                                          | `post-install` s `shouldRunOnVersionUpgrade: false` (výchozí)                            |
+
+<Note>
+Pokud si nejste jisti, výchozí volbou je **post-install**. Po pre-install sáhněte pouze tehdy, když je samotná migrace destruktivní a potřebujete zachytit předchozí stav, než zmizí.
+</Note>
 
 </Accordion>
 <Accordion title="defineFrontComponent" description="Definujte frontendové komponenty pro vlastní uživatelské rozhraní">
@@ -1817,8 +1943,7 @@ 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 pre-install or post-install functions
-yarn twenty exec --preInstall
+# Execute the post-install function
 yarn twenty exec --postInstall
 ```
 

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

@@ -220,6 +220,7 @@ Nástroj pro vytvoření kostry vám již spustil lokální server Twenty. Pro j
 | -------------------------------------- | ------------------------------------------------------ |
 | `yarn twenty server start`             | Spustí lokální server (v případě potřeby stáhne image) |
 | `yarn twenty server start --port 3030` | Spustí na vlastním portu                               |
+| `yarn twenty server start --test`      | Spusťte samostatnou testovací instanci na portu 2021   |
 | `yarn twenty server stop`              | Zastaví server (zachová data)                          |
 | `yarn twenty server status`            | Zobrazí stav serveru, URL a přihlašovací údaje         |
 | `yarn twenty server logs`              | Streamuje protokoly serveru                            |
@@ -228,6 +229,20 @@ Nástroj pro vytvoření kostry vám již spustil lokální server Twenty. Pro j
 
 Data přetrvávají při restartech ve dvou svazcích Dockeru (`twenty-app-dev-data` pro PostgreSQL, `twenty-app-dev-storage` pro soubory). Pomocí `reset` vymažte vše a začněte znovu.
 
+### Spuštění testovací instance
+
+Předejte volbu `--test` libovolnému příkazu `server` pro správu druhé, plně izolované instance — užitečné pro spouštění integračních testů nebo experimentování, aniž byste se dotkli svých hlavních vývojových dat.
+
+| Příkaz                             | Popis                                                     |
+| ---------------------------------- | --------------------------------------------------------- |
+| `yarn twenty server start --test`  | Spustí testovací instanci (výchozí port je 2021)          |
+| `yarn twenty server stop --test`   | Zastaví testovací instanci                                |
+| `yarn twenty server status --test` | Zobrazí stav testovací instance, URL a přihlašovací údaje |
+| `yarn twenty server logs --test`   | Streamuje protokoly testovací instance                    |
+| `yarn twenty server reset --test`  | Vymaže testovací data a začne znovu                       |
+
+Testovací instance běží ve vlastním kontejneru Docker (`twenty-app-dev-test`) s vyhrazenými svazky (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) a konfigurací, takže může běžet paralelně s vaší hlavní instancí bez konfliktů. Zkombinujte `--test` s `--port` pro změnu výchozího portu 2021.
+
 <Note>
   Server vyžaduje, aby **Docker** běžel. Pokud vidíte chybu "Docker not running", ujistěte se, že je spuštěný Docker Desktop (nebo démon Dockeru).
 </Note>

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

@@ -66,14 +66,71 @@ Odkaz ke sdílení používá základní adresu URL serveru (bez jakékoli subdo
 
 ### Správa verzí
 
+Při aktualizaci již nasazené tarballové aplikace server vyžaduje, aby hodnota `version` v `package.json` byla **přísně vyšší** (podle řazení [semver](https://semver.org)) než aktuálně nasazená verze. Opětovné nasazení stejné verze nebo odeslání nižší verze je odmítnuto ještě před uložením tarballu — v CLI uvidíte chybu `VERSION_ALREADY_EXISTS`.
+
 Chcete-li vydat aktualizaci:
 
-1. Zvyšte hodnotu pole `version` v souboru `package.json`
+1. Zvyšte hodnotu pole `version` v souboru `package.json` (např. `1.2.3` → `1.2.4`, `1.3.0` nebo `2.0.0`)
 2. Spusťte `yarn twenty deploy` (nebo `yarn twenty deploy --remote production`)
 3. Pracovní prostory, které mají aplikaci nainstalovanou, uvidí dostupnou aktualizaci ve svém nastavení
 
+<Note>
+Předběžné tagy fungují podle očekávání: zvýšení z `1.0.0-rc.1` → `1.0.0-rc.2` je povoleno a finální vydání jako `1.0.0` je správně rozpoznáno jako vyšší než `1.0.0-rc.5`. Verze v `package.json` musí být platným řetězcem semver.
+</Note>
+
 {/* TODO: add screenshot of the Upgrade button */}
 
+## Automatizované CI/CD (předpřipravené workflowy)
+
+Aplikace vygenerované pomocí `create-twenty-app` jsou hned připravené se dvěma workflowy GitHub Actions ve složce `.github/workflows/`. Jsou připravené ke spuštění hned, jakmile repozitář pushnete na GitHub — pro CI není potřeba žádné další nastavení a CD vyžaduje pouze jeden secret.
+
+### CI — `ci.yml`
+
+Automaticky spouští integrační testy při každém pushi do `main` a u pull requestů.
+
+**K čemu slouží:**
+
+1. Provede checkout zdrojového kódu vaší aplikace.
+2. Spustí izolovanou testovací instanci Twenty pomocí složené akce `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main` (ekvivalent v CI k `yarn twenty server start --test`).
+3. Povolí Corepack, nastaví Node.js podle vašeho `.nvmrc` a nainstaluje závislosti pomocí `yarn install --immutable`.
+4. Spustí `yarn test` a předá `TWENTY_API_URL` a `TWENTY_API_KEY` ze spuštěné instance, aby vaše testy mohly komunikovat se skutečným serverem.
+
+**Konfigurační volby:**
+
+* `TWENTY_VERSION` (env, výchozí hodnota `latest`) — uzamkněte v CI používanou verzi serveru Twenty úpravou této hodnoty v `ci.yml`.
+* Souběžné běhy jsou seskupeny podle `github.ref` a při nových pushích ruší právě probíhající běhy.
+
+Nejsou potřeba žádné secrety — testovací instance je efemérní a existuje pouze po dobu běhu úlohy.
+
+### CD — `cd.yml`
+
+Nasazuje vaši aplikaci na nakonfigurovaný server Twenty při každém pushi do `main` a volitelně také z pull requestu, pokud je přidán štítek `deploy`.
+
+**K čemu slouží:**
+
+1. Provede checkout headu PR (u označených PR) nebo pushnutého commitu.
+2. Spustí `twentyhq/twenty/.github/actions/deploy-twenty-app@main` — ekvivalent v CI k `yarn twenty deploy`.
+3. Spustí `twentyhq/twenty/.github/actions/install-twenty-app@main`, aby se nově nasazená verze nainstalovala do cílového workspace.
+
+**Požadovaná konfigurace:**
+
+| Nastavení               | Kde                                                             | Účel                                                                                                 |
+| ----------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `TWENTY_DEPLOY_URL`     | `env` v `cd.yml` (výchozí `http://localhost:3000`)              | Server Twenty, na který se nasazuje. Před prvním použitím to změňte na skutečnou URL vašeho serveru. |
+| `TWENTY_DEPLOY_API_KEY` | GitHub repozitář **Settings → Secrets and variables → Actions** | API klíč s oprávněním k nasazení na cílovém serveru.                                                 |
+
+<Note>
+Výchozí `TWENTY_DEPLOY_URL` `http://localhost:3000` je pouze zástupná hodnota — z runneru hostovaného GitHubem tato adresa nebude dosažitelná. Před povolením CD ji aktualizujte na veřejnou URL vašeho serveru (nebo použijte self-hosted runner s přístupem do sítě).
+</Note>
+
+**Spuštění náhledového nasazení z PR:**
+
+Přidejte k pull requestu štítek `deploy`. Podmínka `if:` v `cd.yml` spustí úlohu pro dané PR s použitím head commitu PR, což vám umožní ověřit změnu na cílovém serveru před sloučením.
+
+### Připnutí verzí znovupoužitelných akcí
+
+Obě workflowy odkazují na znovupoužitelné akce na `@main`, takže aktualizace akcí v repozitáři `twentyhq/twenty` se přeberou automaticky. Pokud chcete deterministická sestavení, nahraďte `@main` v každém řádku `uses:` za commit SHA nebo tag vydání.
+
 ## Publikování na npm
 
 Publikování na npm zajistí, že bude vaše aplikace dohledatelná v Marketplace Twenty. Jakýkoli pracovní prostor Twenty může procházet, instalovat a aktualizovat aplikace z Marketplace přímo z UI.
@@ -81,7 +138,7 @@ Publikování na npm zajistí, že bude vaše aplikace dohledatelná v Marketpla
 ### Požadavky
 
 * Účet na [npm](https://www.npmjs.com)
-* Klíčové slovo `twenty-app` ve vašem poli `keywords` v souboru `package.json` (již je zahrnuto, když založíte projekt pomocí `create-twenty-app`)
+* Klíčové slovo `twenty-app` ve vašem poli `keywords` v souboru `package.json` (přidejte je ručně — ve výchozím nastavení není zahrnuto v šabloně `create-twenty-app`)
 
 ```json filename="package.json"
 {
@@ -189,3 +246,12 @@ Aplikace můžete nainstalovat také z příkazového řádku:
 ```bash filename="Terminal"
 yarn twenty install
 ```
+
+<Note>
+Server při instalaci vynucuje verzování semver a zrcadlí pravidla pro nasazení:
+
+* Instalace stejné verze, která je již nainstalována ve vašem pracovním prostoru, je odmítnuta s chybou `APP_ALREADY_INSTALLED`.
+* Instalace nižší verze, než je aktuálně nainstalovaná, je odmítnuta s chybou `CANNOT_DOWNGRADE_APPLICATION`.
+
+K instalaci novější verze ji nejprve nasaďte nebo publikujte, poté znovu spusťte `yarn twenty install`.
+</Note>

packages/twenty-docs/l/cs/user-guide/data-migration/how-tos/fix-import-errors.mdx

@@ -140,12 +140,12 @@ Data neodpovídají očekávanému formátu pro tento typ pole.
 #### Datum
 
 **Problém:** Nerozpoznaný formát data
-**Řešení:** Používejte jednotný formát v celém souboru
+**Řešení:** Používejte formát `YYYY-MM-DD` jednotně v celém souboru
 
 ```
-✓ 2024-03-15        (YYYY-MM-DD - recommended)
-✓ 03/15/2024        (MM/DD/YYYY)
-✓ 15/03/2024        (DD/MM/YYYY)
+✓ 2024-03-15        (YYYY-MM-DD)
+❌ 03/15/2024        (MM/DD/YYYY)
+❌ 15/03/2024        (DD/MM/YYYY)
 ```
 
 #### Telefon

packages/twenty-docs/l/cs/user-guide/data-migration/how-tos/prepare-your-csv-files.mdx

@@ -103,8 +103,6 @@ Adresa je **vnořené pole** s více sloupci (některé mohou zůstat prázdné)
 Používejte jednotný formát v celém souboru:
 
 * `YYYY-MM-DD` (doporučeno): `2024-03-15`
-* `MM/DD/YYYY`: `03/15/2024`
-* `DD/MM/YYYY`: `15/03/2024`
 * ISO 8601: `2024-03-15T10:30:00Z`
 
 ### Číselná pole

packages/twenty-docs/l/de/developers/contribute/capabilities/backend-development/server-commands.mdx

@@ -47,7 +47,7 @@ npx nx run twenty-server:database:reset
 #### Für Objekte in Core/Metadata-Schemas (TypeORM)
 
 ```bash
-npx nx run twenty-server:typeorm migration:generate src/database/typeorm/core/migrations/nameOfYourMigration -d src/database/typeorm/core/core.datasource.ts
+npx nx run twenty-server:database:migrate:generate
 ```
 
 ## Technologie-Stack

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

@@ -476,7 +476,7 @@ export default defineLogicFunction({
   httpRouteTriggerSettings: {
     path: '/post-card/create',
     httpMethod: 'GET',
-    isAuthRequired: false,
+    isAuthRequired: true,
   },
   /*databaseEventTriggerSettings: {
     eventName: 'people.created',
@@ -643,49 +643,15 @@ export default defineLogicFunction({
 **Schreiben Sie eine gute `description`.** KI-Agenten verlassen sich auf das `description`-Feld der Funktion, um zu entscheiden, wann das Tool verwendet werden soll. Seien Sie konkret darin, was das Tool tut und wann es aufgerufen werden soll.
 </Note>
 
-</Accordion>
-<Accordion title="definePreInstallLogicFunction" description="Eine Pre-Installations-Logikfunktion definieren (eine pro App)">
-
-Eine Pre-Installationsfunktion ist eine Logikfunktion, die automatisch ausgeführt wird, bevor Ihre App in einem Arbeitsbereich installiert wird. Dies ist nützlich für Validierungsaufgaben, Überprüfungen von Voraussetzungen oder die Vorbereitung des Status des Arbeitsbereichs, bevor die Hauptinstallation fortgesetzt wird.
-
-```ts src/logic-functions/pre-install.ts
-import { definePreInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
-
-const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
-  console.log('Pre install logic function executed successfully!', payload.previousVersion);
-};
-
-export default definePreInstallLogicFunction({
-  universalIdentifier: 'e0604b9e-e946-456b-886d-3f27d9a6b324',
-  name: 'pre-install',
-  description: 'Runs before installation to prepare the application.',
-  timeoutSeconds: 300,
-  handler,
-});
-```
-
-Sie können die Pre-Installationsfunktion auch jederzeit manuell über die CLI ausführen:
-
-```bash filename="Terminal"
-yarn twenty exec --preInstall
-```
-
-Hauptpunkte:
-* Pre-Installationsfunktionen verwenden `definePreInstallLogicFunction()` — eine spezialisierte Variante, die Trigger-Einstellungen (`cronTriggerSettings`, `databaseEventTriggerSettings`, `httpRouteTriggerSettings`, `isTool`) weglässt.
-* Der Handler erhält ein `InstallLogicFunctionPayload` mit `{ previousVersion: string }` — die Version der App, die zuvor installiert war (oder eine leere Zeichenkette bei Neuinstallationen).
-* Pro Anwendung ist nur eine Pre-Installationsfunktion zulässig. Der Manifest-Build schlägt fehl, wenn mehr als eine erkannt wird.
-* Der `universalIdentifier` der Funktion wird während des Builds im Anwendungsmanifest automatisch als `preInstallLogicFunctionUniversalIdentifier` gesetzt — Sie müssen ihn nicht in `defineApplication()` referenzieren.
-* Das standardmäßige Timeout ist auf 300 Sekunden (5 Minuten) festgelegt, um längere Vorbereitungsvorgänge zu ermöglichen.
-
 </Accordion>
 <Accordion title="definePostInstallLogicFunction" description="Eine Post-Installations-Logikfunktion definieren (eine pro App)">
 
-Eine Post-Installationsfunktion ist eine Logikfunktion, die automatisch ausgeführt wird, nachdem Ihre App in einem Arbeitsbereich installiert wurde. Dies ist nützlich für einmalige Einrichtungsvorgänge wie das Befüllen mit Standarddaten, das Erstellen erster Datensätze oder das Konfigurieren von Arbeitsbereichseinstellungen.
+Eine Post-Installationsfunktion ist eine Logikfunktion, die automatisch ausgeführt wird, nachdem Ihre App in einem Arbeitsbereich installiert wurde. 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 InstallLogicFunctionPayload } from 'twenty-sdk';
+import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk';
 
-const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+const handler = async (payload: InstallPayload): Promise<void> => {
   console.log('Post install logic function executed successfully!', payload.previousVersion);
 };
 
@@ -694,6 +660,8 @@ export default definePostInstallLogicFunction({
   name: 'post-install',
   description: 'Runs after installation to set up the application.',
   timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: false,
+  shouldRunSynchronously: false,
   handler,
 });
 ```
@@ -706,10 +674,168 @@ yarn twenty exec --postInstall
 
 Hauptpunkte:
 * Post-Installationsfunktionen verwenden `definePostInstallLogicFunction()` — eine spezialisierte Variante, die Trigger-Einstellungen (`cronTriggerSettings`, `databaseEventTriggerSettings`, `httpRouteTriggerSettings`, `isTool`) weglässt.
-* Der Handler erhält ein `InstallLogicFunctionPayload` mit `{ previousVersion: string }` — die Version der App, die zuvor installiert war (oder eine leere Zeichenkette bei Neuinstallationen).
+* 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.
-* Der `universalIdentifier` der Funktion wird während des Builds im Anwendungsmanifest automatisch als `postInstallLogicFunctionUniversalIdentifier` gesetzt — Sie müssen ihn nicht in `defineApplication()` referenzieren.
+* 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()` 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 Workspace auszulösen.
+
+</Accordion>
+<Accordion title="definePreInstallLogicFunction" description="Eine Pre-Installations-Logikfunktion definieren (eine pro App)">
+
+Eine Pre-Install-Funktion ist eine Logikfunktion, die automatisch während der Installation ausgeführt wird, **bevor die Metadatenmigration des Workspaces 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';
+
+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 Workspaces (`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 Workspace-Metadaten 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 Workspace 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.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ install flow                                                │
+│                                                             │
+│   upload package → [pre-install] → metadata migration →     │
+│   generate SDK → [post-install]                             │
+│                                                             │
+│                  old schema visible    new schema visible   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+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';
+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';
+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 Workspace 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>
 <Accordion title="defineFrontComponent" description="Frontend-Komponenten für benutzerdefinierte UI definieren">
@@ -1816,8 +1942,7 @@ 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 pre-install or post-install functions
-yarn twenty exec --preInstall
+# Execute the post-install function
 yarn twenty exec --postInstall
 ```
 

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

@@ -220,6 +220,7 @@ Der Scaffolder hat bereits einen lokalen Twenty-Server für Sie gestartet. Um ih
 | -------------------------------------- | ----------------------------------------------------------- |
 | `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 und Anmeldedaten anzeigen                 |
 | `yarn twenty server logs`              | Serverprotokolle streamen                                   |
@@ -228,6 +229,20 @@ Der Scaffolder hat bereits einen lokalen Twenty-Server für Sie gestartet. Um ih
 
 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.
 
+### Eine Testinstanz ausführen
+
+Ü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                             | 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 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                |
+
+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>

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

@@ -66,14 +66,71 @@ Der Freigabelink verwendet die Basis-URL des Servers (ohne Workspace-Subdomain),
 
 ### Versionsverwaltung
 
+Beim Aktualisieren einer bereits bereitgestellten Tarball-App verlangt der Server, dass die `version` in `package.json` **strikt höher** (gemäß der [semver](https://semver.org)-Reihenfolge) ist als die derzeit bereitgestellte Version. Das erneute Bereitstellen derselben Version oder das Pushen einer niedrigeren Version wird abgelehnt, bevor das Tarball gespeichert wird — in der CLI wird ein `VERSION_ALREADY_EXISTS`-Fehler angezeigt.
+
 So veröffentlichen Sie ein Update:
 
-1. Erhöhen Sie das Feld `version` in Ihrer `package.json`
+1. Erhöhen Sie das Feld `version` in Ihrer `package.json` (z. B. `1.2.3` → `1.2.4`, `1.3.0` oder `2.0.0`).
 2. Führen Sie `yarn twenty deploy` aus (oder `yarn twenty deploy --remote production`)
 3. Arbeitsbereiche, die die App installiert haben, sehen in ihren Einstellungen, dass ein Upgrade verfügbar ist.
 
+<Note>
+Pre-Release-Tags funktionieren wie erwartet: Das Erhöhen von `1.0.0-rc.1` → `1.0.0-rc.2` ist zulässig, und eine finale Version wie `1.0.0` wird korrekt als höher als `1.0.0-rc.5` erkannt. Die Version in `package.json` muss selbst eine gültige semver-Zeichenfolge sein.
+</Note>
+
 {/* TODO: add screenshot of the Upgrade button */}
 
+## Automatisiertes CI/CD (vorgefertigte Workflows)
+
+Apps, die mit `create-twenty-app` erzeugt wurden, enthalten von Haus aus zwei GitHub-Actions-Workflows unter `.github/workflows/`. Sie sind einsatzbereit, sobald Sie das Repository zu GitHub pushen — für CI ist keine zusätzliche Einrichtung erforderlich, und für CD ist nur ein einziges Secret nötig.
+
+### CI — `ci.yml`
+
+Führt Ihre Integrationstests bei jedem Push auf `main` und bei Pull Requests aus.
+
+**Was sie macht:**
+
+1. Checkt den Quellcode Ihrer App aus.
+2. Startet eine isolierte Twenty-Testinstanz mithilfe der Composite-Action `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main` (das CI-Äquivalent zu `yarn twenty server start --test`).
+3. Aktiviert Corepack, richtet Node.js anhand Ihrer `.nvmrc` ein und installiert Abhängigkeiten mit `yarn install --immutable`.
+4. Führt `yarn test` aus und übergibt `TWENTY_API_URL` und `TWENTY_API_KEY` aus der gestarteten Instanz, damit Ihre Tests mit einem echten Server kommunizieren können.
+
+**Konfigurationsoptionen:**
+
+* `TWENTY_VERSION` (env, standardmäßig `latest`) — fixieren Sie die in CI verwendete Twenty-Server-Version, indem Sie dies in `ci.yml` anpassen.
+* Die Parallelität wird nach `github.ref` gruppiert und bricht laufende Ausführungen bei neuen Pushes ab.
+
+Es sind keine Secrets erforderlich — die Testinstanz ist flüchtig und existiert nur für die Dauer des Jobs.
+
+### CD — `cd.yml`
+
+Stellt Ihre App bei jedem Push auf `main` auf einem konfigurierten Twenty-Server bereit und optional aus einem Pull Request, wenn das Label `deploy` gesetzt ist.
+
+**Was sie macht:**
+
+1. Checkt den PR-Head (bei PRs mit Label) oder den gepushten Commit aus.
+2. Führt `twentyhq/twenty/.github/actions/deploy-twenty-app@main` aus — das CI-Äquivalent zu `yarn twenty deploy`.
+3. Führt `twentyhq/twenty/.github/actions/install-twenty-app@main` aus, damit die neu bereitgestellte Version in den Ziel-Workspace installiert wird.
+
+**Erforderliche Konfiguration:**
+
+| Einstellung             | Wo                                                               | Zweck                                                                                                                      |
+| ----------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `TWENTY_DEPLOY_URL`     | `env` in `cd.yml` (standardmäßig `http://localhost:3000`)        | Der Twenty-Server, auf den bereitgestellt werden soll. Ändern Sie dies vor der ersten Verwendung auf die echte Server-URL. |
+| `TWENTY_DEPLOY_API_KEY` | GitHub-Repository **Settings → Secrets and variables → Actions** | API-Schlüssel mit Berechtigung zum Bereitstellen auf dem Zielserver.                                                       |
+
+<Note>
+Der Standardwert von `TWENTY_DEPLOY_URL` (`http://localhost:3000`) ist ein Platzhalter — von einem GitHub-gehosteten Runner ist er nicht erreichbar. Aktualisieren Sie sie auf die öffentliche URL Ihres Servers (oder verwenden Sie einen selbstgehosteten Runner mit Netzwerkzugriff), bevor Sie CD aktivieren.
+</Note>
+
+**Eine Vorschau-Bereitstellung aus einem PR auslösen:**
+
+Fügen Sie einem Pull Request das Label `deploy` hinzu. Die `if:`-Bedingung in `cd.yml` führt den Job für diesen PR mit dem Head-Commit des PR aus, sodass Sie eine Änderung auf dem Zielserver vor dem Mergen validieren können.
+
+### Fixieren der wiederverwendbaren Actions
+
+Beide Workflows verweisen auf wiederverwendbare Actions mit `@main`, sodass Aktualisierungen der Actions im Repository `twentyhq/twenty` automatisch übernommen werden. Wenn Sie deterministische Builds möchten, ersetzen Sie `@main` in jeder `uses:`-Zeile durch eine Commit-SHA oder einen Release-Tag.
+
 ## Auf npm veröffentlichen
 
 Die Veröffentlichung auf npm macht Ihre App im Twenty-Marktplatz auffindbar. Jeder Twenty-Arbeitsbereich kann Marktplatz-Apps direkt über die Benutzeroberfläche durchsuchen, installieren und aktualisieren.
@@ -81,7 +138,7 @@ Die Veröffentlichung auf npm macht Ihre App im Twenty-Marktplatz auffindbar. Je
 ### Anforderungen
 
 * Ein [npm](https://www.npmjs.com)-Konto
-* Das Schlüsselwort `twenty-app` in Ihrem `package.json`-Array `keywords` (bereits enthalten, wenn Sie mit `create-twenty-app` ein Gerüst erstellen)
+* Das Schlüsselwort `twenty-app` in Ihrem `package.json`-Array `keywords` (manuell hinzufügen — es ist in der `create-twenty-app`-Vorlage standardmäßig nicht enthalten)
 
 ```json filename="package.json"
 {
@@ -189,3 +246,12 @@ Sie können Apps auch über die Befehlszeile installieren:
 ```bash filename="Terminal"
 yarn twenty install
 ```
+
+<Note>
+Der Server erzwingt bei der Installation semver-Versionierung und spiegelt damit die Regeln beim Bereitstellen wider:
+
+* Die Installation derselben Version, die in Ihrem Arbeitsbereich bereits installiert ist, wird mit einem `APP_ALREADY_INSTALLED`-Fehler abgelehnt.
+* Die Installation einer niedrigeren Version als die aktuell installierte wird mit einem `CANNOT_DOWNGRADE_APPLICATION`-Fehler abgelehnt.
+
+Um eine neuere Version zu installieren, stellen Sie sie zuerst bereit oder veröffentlichen Sie sie und führen Sie dann `yarn twenty install` erneut aus.
+</Note>

packages/twenty-docs/l/de/user-guide/data-migration/how-tos/fix-import-errors.mdx

@@ -140,12 +140,12 @@ Die Daten entsprechen nicht dem erwarteten Format für diesen Feldtyp.
 #### Datum
 
 **Problem:** Nicht erkanntes Datumsformat
-**Lösung:** Verwenden Sie in der gesamten Datei ein einheitliches Format
+**Lösung:** Verwenden Sie in der gesamten Datei durchgängig das Format `YYYY-MM-DD`
 
 ```
-✓ 2024-03-15        (YYYY-MM-DD - empfohlen)
-✓ 03/15/2024        (MM/DD/YYYY)
-✓ 15/03/2024        (DD/MM/YYYY)
+✓ 2024-03-15        (YYYY-MM-DD)
+❌ 03/15/2024        (MM/DD/YYYY)
+❌ 15/03/2024        (DD/MM/YYYY)
 ```
 
 #### Telefon

packages/twenty-docs/l/de/user-guide/data-migration/how-tos/prepare-your-csv-files.mdx

@@ -103,8 +103,6 @@ Adresse ist ein **verschachteltes Feld** mit mehreren Spalten (einige können le
 Verwenden Sie in Ihrer Datei ein einheitliches Format:
 
 * `YYYY-MM-DD` (empfohlen): `2024-03-15`
-* `MM/DD/YYYY`: `03/15/2024`
-* `DD/MM/YYYY`: `15/03/2024`
 * ISO 8601: `2024-03-15T10:30:00Z`
 
 ### Zahlenfelder

packages/twenty-docs/l/es/developers/contribute/capabilities/backend-development/server-commands.mdx

@@ -47,7 +47,7 @@ npx nx run twenty-server:database:reset
 #### Para objetos en esquemas Core/Metadata (TypeORM)
 
 ```bash
-npx nx run twenty-server:typeorm migration:generate src/database/typeorm/core/migrations/nameOfYourMigration -d src/database/typeorm/core/core.datasource.ts
+npx nx run twenty-server:database:migrate:generate
 ```
 
 ## Stack Tecnológico

packages/twenty-docs/l/it/developers/contribute/capabilities/backend-development/server-commands.mdx

@@ -47,7 +47,7 @@ npx nx run twenty-server:database:reset
 #### Per oggetti negli schemi Core/Metadata (TypeORM)
 
 ```bash
-npx nx run twenty-server:typeorm migration:generate src/database/typeorm/core/migrations/nameOfYourMigration -d src/database/typeorm/core/core.datasource.ts
+npx nx run twenty-server:database:migrate:generate
 ```
 
 ## Tech Stack

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

@@ -476,7 +476,7 @@ export default defineLogicFunction({
   httpRouteTriggerSettings: {
     path: '/post-card/create',
     httpMethod: 'GET',
-    isAuthRequired: false,
+    isAuthRequired: true,
   },
   /*databaseEventTriggerSettings: {
     eventName: 'people.created',
@@ -643,49 +643,15 @@ export default defineLogicFunction({
 **Scrivi una buona `description`.** Gli agenti IA fanno affidamento sul campo `description` della funzione per decidere quando usare lo strumento. Sii specifico su cosa fa lo strumento e quando dovrebbe essere invocato.
 </Note>
 
-</Accordion>
-<Accordion title="definePreInstallLogicFunction" description="Definisci una funzione logica di pre-installazione (una per app)">
-
-Una funzione di pre-installazione è una funzione logica che viene eseguita automaticamente prima che la tua app venga installata in uno spazio di lavoro. È utile per attività di convalida, controlli dei prerequisiti o per preparare lo stato dello spazio di lavoro prima che proceda l'installazione principale.
-
-```ts src/logic-functions/pre-install.ts
-import { definePreInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
-
-const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
-  console.log('Pre install logic function executed successfully!', payload.previousVersion);
-};
-
-export default definePreInstallLogicFunction({
-  universalIdentifier: 'e0604b9e-e946-456b-886d-3f27d9a6b324',
-  name: 'pre-install',
-  description: 'Runs before installation to prepare the application.',
-  timeoutSeconds: 300,
-  handler,
-});
-```
-
-Puoi anche eseguire manualmente la funzione di pre-installazione in qualsiasi momento utilizzando la CLI:
-
-```bash filename="Terminal"
-yarn twenty exec --preInstall
-```
-
-Punti chiave:
-* Le funzioni di pre-installazione utilizzano `definePreInstallLogicFunction()` — una variante specializzata che omette le impostazioni dei trigger (`cronTriggerSettings`, `databaseEventTriggerSettings`, `httpRouteTriggerSettings`, `isTool`).
-* L'handler riceve un `InstallLogicFunctionPayload` con `{ previousVersion: string }` — la versione dell'app precedentemente installata (oppure una stringa vuota per nuove installazioni).
-* È consentita una sola funzione di pre-installazione per applicazione. La build del manifesto genererà un errore se ne viene rilevata più di una.
-* L'`universalIdentifier` della funzione viene impostato automaticamente come `preInstallLogicFunctionUniversalIdentifier` nel manifesto dell'applicazione durante la build — non è necessario farvi riferimento in `defineApplication()`.
-* Il timeout predefinito è impostato a 300 secondi (5 minuti) per consentire attività di preparazione più lunghe.
-
 </Accordion>
 <Accordion title="definePostInstallLogicFunction" description="Definisci una funzione logica di post-installazione (una per app)">
 
-Una funzione post-installazione è una funzione logica che viene eseguita automaticamente dopo che la tua app è stata installata in uno spazio di lavoro. Questo è utile per attività di configurazione una tantum come il popolamento di dati predefiniti, la creazione di record iniziali o la configurazione delle impostazioni dello spazio di lavoro.
+Una funzione post-installazione è una funzione logica che viene eseguita automaticamente dopo che la tua app è stata installata in uno spazio di lavoro. Il server la esegue **dopo** che i metadati dell'app sono stati sincronizzati e il client SDK è stato generato, così lo spazio di lavoro è completamente pronto per l'uso e il nuovo schema è attivo. I casi d'uso tipici includono il popolamento di dati predefiniti, la creazione di record iniziali, la configurazione delle impostazioni dello spazio di lavoro o il provisioning di risorse su servizi di terze parti.
 
 ```ts src/logic-functions/post-install.ts
-import { definePostInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk';
 
-const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+const handler = async (payload: InstallPayload): Promise<void> => {
   console.log('Post install logic function executed successfully!', payload.previousVersion);
 };
 
@@ -694,6 +660,8 @@ export default definePostInstallLogicFunction({
   name: 'post-install',
   description: 'Runs after installation to set up the application.',
   timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: false,
+  shouldRunSynchronously: false,
   handler,
 });
 ```
@@ -706,10 +674,168 @@ yarn twenty exec --postInstall
 
 Punti chiave:
 * Le funzioni di post-installazione utilizzano `definePostInstallLogicFunction()` — una variante specializzata che omette le impostazioni dei trigger (`cronTriggerSettings`, `databaseEventTriggerSettings`, `httpRouteTriggerSettings`, `isTool`).
-* L'handler riceve un `InstallLogicFunctionPayload` con `{ previousVersion: string }` — la versione dell'app precedentemente installata (oppure una stringa vuota per nuove installazioni).
+* L'handler riceve un `InstallPayload` con `{ previousVersion?: string; newVersion: string }` — `newVersion` è la versione in fase di installazione e `previousVersion` è la versione installata in precedenza (oppure `undefined` in caso di nuova installazione). Usa questi valori per distinguere le nuove installazioni dagli aggiornamenti e per eseguire logiche di migrazione specifiche per versione.
+* **Quando viene eseguito l'hook**: solo sulle nuove installazioni, per impostazione predefinita. Passa `shouldRunOnVersionUpgrade: true` se vuoi che venga eseguito anche quando l'app viene aggiornata da una versione precedente. Se omesso, il flag è `false` per impostazione predefinita e gli aggiornamenti saltano l'hook.
+* **Modello di esecuzione — asincrono per impostazione predefinita, sincrono su richiesta**: il flag `shouldRunSynchronously` controlla *come* viene eseguito il post-install.
+  * `shouldRunSynchronously: false` *(default)* — l'hook viene **messo in coda nella coda dei messaggi** con `retryLimit: 3` ed eseguito in modo asincrono in un worker. La risposta di installazione viene restituita non appena il job è messo in coda, quindi un handler lento o in errore non blocca il chiamante. Il worker riproverà fino a tre volte. **Usalo per job di lunga durata** — popolamento di dataset di grandi dimensioni, chiamate a API di terze parti lente, provisioning di risorse esterne, qualsiasi cosa che possa superare una finestra di risposta HTTP ragionevole.
+  * `shouldRunSynchronously: true` — l'hook viene eseguito **inline durante il flusso di installazione** (stesso executor del pre-install). La richiesta di installazione rimane bloccata finché l'handler non termina e, se genera un'eccezione, il chiamante dell'installazione riceve un `POST_INSTALL_ERROR`. Nessun tentativo automatico. **Usalo per attività rapide che devono completarsi prima della risposta** — ad esempio, emettere un errore di validazione all'utente, oppure un setup rapido di cui il client avrà bisogno immediatamente dopo il ritorno della chiamata di installazione. Tieni presente che la migrazione dei metadati è già stata applicata quando viene eseguito il post-install, quindi un errore in modalità sincrona **non** annulla le modifiche allo schema — si limita a far emergere l'errore.
+* Assicurati che il tuo handler sia idempotente. In modalità asincrona la coda può riprovare fino a tre volte; in entrambe le modalità l'hook può essere eseguito di nuovo durante gli aggiornamenti quando `shouldRunOnVersionUpgrade: true`.
+* Le variabili d'ambiente `APPLICATION_ID`, `APP_ACCESS_TOKEN` e `API_URL` sono disponibili all'interno dell'handler (come in qualsiasi altra funzione logica), quindi puoi chiamare le API di Twenty con un token di accesso applicativo con ambito sulla tua app.
 * È consentita una sola funzione di post-installazione per applicazione. La build del manifesto genererà un errore se ne viene rilevata più di una.
-* L'`universalIdentifier` della funzione viene impostato automaticamente come `postInstallLogicFunctionUniversalIdentifier` nel manifesto dell'applicazione durante la build — non è necessario farvi riferimento in `defineApplication()`.
+* I campi `universalIdentifier`, `shouldRunOnVersionUpgrade` e `shouldRunSynchronously` della funzione vengono associati automaticamente al manifest dell'applicazione nel campo `postInstallLogicFunction` durante la build — non è necessario referenziarli in `defineApplication()`.
 * Il timeout predefinito è impostato a 300 secondi (5 minuti) per consentire attività di configurazione più lunghe, come il popolamento dei dati.
+* **Non eseguito in modalità dev**: quando un'app è registrata in locale (tramite `yarn twenty dev`), il server salta completamente il flusso di installazione e sincronizza i file direttamente tramite il watcher della CLI — quindi il post-install non viene mai eseguito in modalità dev, indipendentemente da `shouldRunSynchronously`. Usa `yarn twenty exec --postInstall` per attivarlo manualmente su un workspace in esecuzione.
+
+</Accordion>
+<Accordion title="definePreInstallLogicFunction" description="Definisci una funzione logica di pre-installazione (una per app)">
+
+Una funzione di pre-install è una funzione logica che viene eseguita automaticamente durante l'installazione, **prima che venga applicata la migrazione dei metadati del workspace**. Condivide la stessa struttura di payload del post-install (`InstallPayload`), ma è posizionata prima nel flusso di installazione così da poter preparare lo stato da cui dipenderà la migrazione imminente — usi tipici includono il backup dei dati, la validazione della compatibilità con il nuovo schema o l'archiviazione di record che stanno per essere ristrutturati o eliminati.
+
+```ts src/logic-functions/pre-install.ts
+import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk';
+
+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,
+});
+```
+
+Puoi anche eseguire manualmente la funzione di pre-installazione in qualsiasi momento utilizzando la CLI:
+
+```bash filename="Terminal"
+yarn twenty exec --preInstall
+```
+
+Punti chiave:
+* Le funzioni di pre-install usano `definePreInstallLogicFunction()` — stessa configurazione specialistica del post-install, solo agganciata a uno slot di ciclo di vita diverso.
+* Sia gli handler di pre- sia quelli di post-install ricevono lo stesso tipo `InstallPayload`: `{ previousVersion?: string; newVersion: string }`. Importalo una volta e riutilizzalo per entrambi gli hook.
+* **Quando viene eseguito l'hook**: posizionato appena prima della migrazione dei metadati del workspace (`synchronizeFromManifest`). Prima dell'esecuzione, il server esegue una "sincronizzazione ridotta" puramente additiva che registra nei metadati del workspace la funzione di pre-install della versione **nuova** — nient'altro viene toccato — e poi la esegue. Poiché questa sincronizzazione è solo additiva, gli oggetti, i campi e i dati della versione precedente restano intatti quando il tuo handler viene eseguito: puoi leggere ed eseguire in sicurezza il backup dello stato pre-migrazione.
+* **Modello di esecuzione**: il pre-install è eseguito **in modo sincrono** e **blocca l'installazione**. Se l'handler genera un'eccezione, l'installazione viene interrotta prima che vengano applicate modifiche allo schema — il workspace rimane sulla versione precedente in uno stato coerente. Questo è intenzionale: il pre-install è la tua ultima possibilità per rifiutare un aggiornamento rischioso.
+* Come per il post-install, è consentita una sola funzione di pre-installazione per applicazione. Viene collegata automaticamente al manifest dell'applicazione nel campo `preInstallLogicFunction` durante la build.
+* **Non eseguito in modalità dev**: come per il post-install — il flusso di installazione viene completamente saltato per le app registrate localmente, quindi il pre-install non viene mai eseguito con `yarn twenty dev`. Usa `yarn twenty exec --preInstall` per attivarlo manualmente.
+
+</Accordion>
+<Accordion title="Pre-install vs post-install: quando usare l'uno o l'altro" description="Scegliere l'hook di installazione giusto">
+
+Entrambi gli hook fanno parte dello stesso flusso di installazione e ricevono lo stesso `InstallPayload`. La differenza è **quando** vengono eseguiti rispetto alla migrazione dei metadati del workspace, e questo modifica quali dati possono gestire in sicurezza.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ install flow                                                │
+│                                                             │
+│   upload package → [pre-install] → metadata migration →     │
+│   generate SDK → [post-install]                             │
+│                                                             │
+│                  old schema visible    new schema visible   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Il pre-install è sempre **sincrono** (blocca l'installazione e può interromperla). Il post-install è **asincrono per impostazione predefinita** — messo in coda su un worker con retry automatici — ma può optare per l'esecuzione sincrona con `shouldRunSynchronously: true`. Vedi l'accordion `definePostInstallLogicFunction` sopra per quando usare ciascuna modalità.
+
+**Usa `post-install` per tutto ciò che richiede l'esistenza del nuovo schema.** Questo è il caso più comune:
+
+* Popolamento di dati predefiniti (creazione di record iniziali, viste predefinite, contenuti demo) su oggetti e campi appena aggiunti.
+* Registrazione di webhook con servizi di terze parti ora che l'app ha le proprie credenziali.
+* Chiamare la tua API per completare il setup che dipende dai metadati sincronizzati.
+* Logica idempotente di "ensure this exists" che dovrebbe riconciliare lo stato a ogni aggiornamento — da combinare con `shouldRunOnVersionUpgrade: true`.
+
+Esempio — eseguire il seeding di un record `PostCard` predefinito dopo l'installazione:
+
+```ts src/logic-functions/post-install.ts
+import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk';
+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,
+});
+```
+
+**Usa `pre-install` quando una migrazione altrimenti distruggerebbe o corromperebbe i dati esistenti.** Poiché il pre-install viene eseguito contro lo schema *precedente* e un suo fallimento annulla l'aggiornamento, è il posto giusto per qualsiasi operazione rischiosa:
+
+* **Eseguire il backup dei dati che stanno per essere eliminati o ristrutturati** — ad esempio, stai rimuovendo un campo nella v2 e devi copiarne i valori in un altro campo o esportarli su uno storage prima che venga eseguita la migrazione.
+* **Archiviare i record che un nuovo vincolo renderebbe non validi** — ad esempio, un campo sta diventando `NOT NULL` e devi prima eliminare o correggere le righe con valori nulli.
+* **Validare la compatibilità e rifiutare l'aggiornamento se i dati attuali non possono essere migrati correttamente** — genera un'eccezione dall'handler e l'installazione si interrompe senza applicare modifiche. Questo è più sicuro che scoprire l'incompatibilità a migrazione in corso.
+* **Rinominare o rigenerare le chiavi dei dati** prima di una modifica dello schema che farebbe perdere l'associazione.
+
+Esempio — archiviare i record prima di una migrazione distruttiva:
+
+```ts src/logic-functions/pre-install.ts
+import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk';
+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,
+});
+```
+
+**Regola generale:**
+
+| Vuoi…                                                                                                                        | Usa                                                                                  |
+| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Popolare dati predefiniti, configurare il workspace, registrare risorse esterne                                              | `post-install`                                                                       |
+| Eseguire seeding di lunga durata o chiamate a terze parti che non dovrebbero bloccare la risposta dell'installazione         | `post-install` (predefinito — `shouldRunSynchronously: false`, con retry del worker) |
+| Eseguire un setup rapido di cui il chiamante farà affidamento immediatamente dopo il ritorno della chiamata di installazione | `post-install` con `shouldRunSynchronously: true`                                    |
+| Leggere o eseguire il backup dei dati che la prossima migrazione perderebbe                                                  | `pre-install`                                                                        |
+| Rifiutare un aggiornamento che corromperebbe i dati esistenti                                                                | `pre-install` (genera un'eccezione dall'handler)                                     |
+| Eseguire la riconciliazione a ogni aggiornamento                                                                             | `post-install` con `shouldRunOnVersionUpgrade: true`                                 |
+| Eseguire un setup una tantum solo alla prima installazione                                                                   | `post-install` con `shouldRunOnVersionUpgrade: false` (predefinito)                  |
+
+<Note>
+In caso di dubbio, usa **post-install**. Ricorri al pre-install solo quando la migrazione stessa è distruttiva e devi intercettare lo stato precedente prima che vada perso.
+</Note>
 
 </Accordion>
 <Accordion title="defineFrontComponent" description="Definisci componenti front-end per un'interfaccia utente personalizzata">
@@ -1816,8 +1942,7 @@ 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 pre-install or post-install functions
-yarn twenty exec --preInstall
+# Execute the post-install function
 yarn twenty exec --postInstall
 ```